Front door: verifiable spec registry + routing + drift automation

[hyperpolymath]

What this does

Turns the ~7,000-file standards monorepo into something an agent or human can read as one coherent thing or jump straight to exactly what they need — and wires it into live drift-detection automation so documentation rot becomes a detected, routed finding instead of something noticed 60 days later.

Built on a fresh inventory (103 top-level entries, 7,026 tracked files, 28 spec homes verified to exist).

⚠️ OWNER REVIEW REQUIRED — read first

Commit f805bdc is isolated and contains the only licence-touching changes: it corrects human-facing doc badges/prose that asserted PMPL-1.0-or-later to MPL-2.0, matching the actual LICENSE file (set owner-directed in #354). This is a documentation-accuracy fix, not a relicensing.

• No LICENSE file and no SPDX header is edited — those stay owner-only / Manual-Only per .claude/CLAUDE.md.
• Drop this one commit if you disagree; the rest stands alone.
• Files: README.adoc (badge + Licensing bullet + structure line + == License; also dropped the "Philosophy: Palimpsest" badge since this is not a Palimpsest carve-out repo), ROADMAP.adoc, QUICKSTART-MAINTAINER.adoc, PALIMPSEST.adoc (added a NOTE that the doc describes PMPL generally and that this repo is MPL-2.0).

The other commits only remove now-false PMPL-1.0 claims (replaced with neutral "see LICENSE" / Manual-Only wording) — they assert no identifier.

The two front doors

Audience	Canonical entry
Human	README.adoc — now opens with a "Start Here" + "if you want X, go here" routing table
Agent	0-AI-MANIFEST.a2ml — rewritten from a generic template into the real machine entry, with routing + registry pointer + real invariants

Every other "what is this repo" doc is now a thin pointer back to these two.

The verifiable registry (Task 3)

• .machine_readable/REGISTRY.a2ml — generated index of 28 specs across 6 streams; each [[spec]] has home, canonical_doc, and a content-addressed source_hash (sha256 over git ls-files -s <home>).
• scripts/build-registry.sh — the generator (honest by construction: only emits homes that exist; deterministic; idempotent). just registry / just registry-check.
• REGISTRY.adoc — prose on the registry, how source_hash catches drift, and the router.

Drift becomes a detected, routed finding (Task 3)

file tree + STATE.a2ml ─► build-registry.sh ─► REGISTRY.a2ml ─► TOPOLOGY.md
                                ▲                     │
                                │                     ▼
              registry-verify.yml (CI)        HYP-S006 registry-staleness
              (fails build on drift)          emits doc.drift → hybrid router

• .github/workflows/registry-verify.yml — in-repo half: fails the build on registry/topology drift.
• hypatia-rules/registry-staleness.a2ml (HYP-S006) — estate half: recomputes hashes, emits doc.drift. Its @router defaults to auto_execute (regenerate) but hard-caps any licence/SPDX-overlapping drift to :review, honouring the Manual-Only guardrail and license_finding_strategy/0.

Confirmed drift fixed (Task 4)

• EXPLAINME.adoc → thin stub: drops the ReScript-as-Primary line (banned 2026-04-30) and the dead groove-protocol/ + palimpsest-license/ local links (both confirmed absent); defers the spec inventory to the registry.
• llm-warmup-{dev,user}.md were byte-identical → now role-specific stubs.
• QUICKSTART-{DEV,USER,MAINTAINER}.adoc — all {{PLACEHOLDER}} markers filled (USER re-framed for a specs repo, not an app install).
• Doc badges → owner-review commit above.

TOPOLOGY now derived (Task 5)

TOPOLOGY.md was hand-frozen at 2026-04-04 (80% overall while integration read 0%). It is now generated from the registry + STATE.a2ml — it can't freeze. Its existing AGPL-3.0-or-later SPDX header is preserved (not touched).

REORGANIZATION-PLAN.md superseded (Task 6)

Marked SUPERSEDED with a banner: its premise (move content out to separate repos) predates the 2026-02-08 monorepo consolidation; discoverability/drift are now handled by the registry + automation.

Notes for the reviewer

• New-file SPDX: new/generated files use AGPL-3.0-or-later to match the repo's current per-file SPDX convention (Phase 1/2 sweeps chore(license): flip 700 PMPL→AGPL-3.0-or-later SPDX stamps (Phase 1) #344/chore(license): replace 7 subdir LICENSEs + flip 2717 SPDX → AGPL-3.0-or-later (Phase 2) #345) and to preserve TOPOLOGY.md's existing header. Note the LICENSE file is MPL-2.0 — the LICENSE-vs-per-file-SPDX classification is an owner-only question I did not resolve.
• just registry-check is green; output is deterministic (commit 83e83a6 removed a volatile timestamp that would have spuriously tripped CI).

Out of scope (untouched)

A2ML/K9 spec internals (Stream 1); AffineScript spec text (Stream 2); any LICENSE/SPDX edits (owner-only — flagged, not fixed).

https://claude.ai/code/session_011xv3VLrqeXkpjXxUojKz82

---

Generated by Claude Code

[github-actions]

🔍 Hypatia Security Scan

Findings: 223 issues detected

Severity	Count
🔴 Critical	64
🟠 High	62
🟡 Medium	97

⚠️ Action Required: Critical security issues found!

View findings

[
  {
    "reason": "Action for the check script)\n        uses: actions/checkout@de0f needs attention",
    "type": "unpinned_action",
    "file": "governance-reusable.yml",
    "action": "pin_sha",
    "rule_module": "workflow_audit",
    "severity": "medium"
  },
  {
    "reason": "Action for the check script)\n        uses: actions/checkout@de0f needs attention",
    "type": "unpinned_action",
    "file": "governance-reusable.yml",
    "action": "pin_sha",
    "rule_module": "workflow_audit",
    "severity": "medium"
  },
  {
    "reason": "Issue in affinescript-verify.yml",
    "type": "missing_timeout_minutes",
    "file": "affinescript-verify.yml",
    "action": "flag",
    "rule_module": "workflow_audit",
    "severity": "medium"
  },
  {
    "reason": "Issue in boj-build.yml",
    "type": "missing_timeout_minutes",
    "file": "boj-build.yml",
    "action": "flag",
    "rule_module": "workflow_audit",
    "severity": "medium"
  },
  {
    "reason": "Issue in casket-pages.yml",
    "type": "missing_timeout_minutes",
    "file": "casket-pages.yml",
    "action": "flag",
    "rule_module": "workflow_audit",
    "severity": "medium"
  },
  {
    "reason": "Issue in casket-pages.yml",
    "type": "missing_timeout_minutes",
    "file": "casket-pages.yml",
    "action": "flag",
    "rule_module": "workflow_audit",
    "severity": "medium"
  },
  {
    "reason": "Issue in changelog-reusable.yml",
    "type": "missing_timeout_minutes",
    "file": "changelog-reusable.yml",
    "action": "flag",
    "rule_module": "workflow_audit",
    "severity": "medium"
  },
  {
    "reason": "Issue in codeql-reusable.yml",
    "type": "missing_timeout_minutes",
    "file": "codeql-reusable.yml",
    "action": "flag",
    "rule_module": "workflow_audit",
    "severity": "medium"
  },
  {
    "reason": "Issue in codeql.yml",
    "type": "missing_timeout_minutes",
    "file": "codeql.yml",
    "action": "flag",
    "rule_module": "workflow_audit",
    "severity": "medium"
  },
  {
    "reason": "Issue in deno-ci-reusable.yml",
    "type": "missing_timeout_minutes",
    "file": "deno-ci-reusable.yml",
    "action": "flag",
    "rule_module": "workflow_audit",
    "severity": "medium"
  }
]

Powered by Hypatia Neurosymbolic CI/CD Intelligence

[github-actions]

🔍 Hypatia Security Scan

Findings: 222 issues detected

Severity	Count
🔴 Critical	64
🟠 High	62
🟡 Medium	96

⚠️ Action Required: Critical security issues found!

View findings

[
  {
    "reason": "Action for the check script)\n        uses: actions/checkout@de0f needs attention",
    "type": "unpinned_action",
    "file": "governance-reusable.yml",
    "action": "pin_sha",
    "rule_module": "workflow_audit",
    "severity": "medium"
  },
  {
    "reason": "Action for the check script)\n        uses: actions/checkout@de0f needs attention",
    "type": "unpinned_action",
    "file": "governance-reusable.yml",
    "action": "pin_sha",
    "rule_module": "workflow_audit",
    "severity": "medium"
  },
  {
    "reason": "Issue in affinescript-verify.yml",
    "type": "missing_timeout_minutes",
    "file": "affinescript-verify.yml",
    "action": "flag",
    "rule_module": "workflow_audit",
    "severity": "medium"
  },
  {
    "reason": "Issue in boj-build.yml",
    "type": "missing_timeout_minutes",
    "file": "boj-build.yml",
    "action": "flag",
    "rule_module": "workflow_audit",
    "severity": "medium"
  },
  {
    "reason": "Issue in casket-pages.yml",
    "type": "missing_timeout_minutes",
    "file": "casket-pages.yml",
    "action": "flag",
    "rule_module": "workflow_audit",
    "severity": "medium"
  },
  {
    "reason": "Issue in casket-pages.yml",
    "type": "missing_timeout_minutes",
    "file": "casket-pages.yml",
    "action": "flag",
    "rule_module": "workflow_audit",
    "severity": "medium"
  },
  {
    "reason": "Issue in changelog-reusable.yml",
    "type": "missing_timeout_minutes",
    "file": "changelog-reusable.yml",
    "action": "flag",
    "rule_module": "workflow_audit",
    "severity": "medium"
  },
  {
    "reason": "Issue in codeql-reusable.yml",
    "type": "missing_timeout_minutes",
    "file": "codeql-reusable.yml",
    "action": "flag",
    "rule_module": "workflow_audit",
    "severity": "medium"
  },
  {
    "reason": "Issue in codeql.yml",
    "type": "missing_timeout_minutes",
    "file": "codeql.yml",
    "action": "flag",
    "rule_module": "workflow_audit",
    "severity": "medium"
  },
  {
    "reason": "Issue in deno-ci-reusable.yml",
    "type": "missing_timeout_minutes",
    "file": "deno-ci-reusable.yml",
    "action": "flag",
    "rule_module": "workflow_audit",
    "severity": "medium"
  }
]

Powered by Hypatia Neurosymbolic CI/CD Intelligence