Front door: verifiable spec registry + routing + drift automation (#357)

## 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
#344/#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](https://claude.ai/code/session_011xv3VLrqeXkpjXxUojKz82)_

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: hyperpolymath

.github/workflows/registry-verify.yml

@@ -0,0 +1,34 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# registry-verify — fail the build if the spec registry or the DERIVED
+# topology map has drifted from the file tree. This is the in-repo half of
+# the drift-detection loop (the estate half is Hypatia rule HYP-S006).
+name: Registry Verify
+
+on:
+  push:
+    branches: [ main, master ]
+  pull_request:
+    branches: [ main, master ]
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  verify:
+    name: Registry + topology in sync
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          fetch-depth: 0  # full history so `git ls-files -s` hashes are stable
+
+      - name: Verify registry + derived topology are current
+        run: |
+          bash scripts/build-registry.sh --check

.machine_readable/REGISTRY.a2ml

@@ -0,0 +1,281 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
+#
+# REGISTRY.a2ml — the verifiable index of every spec/standard in this monorepo.
+#
+# GENERATED FILE — DO NOT EDIT BY HAND.
+# Regenerate with:  bash scripts/build-registry.sh   (or: just registry)
+# Source of truth:  the SPECS table in scripts/build-registry.sh + the file tree.
+#
+# Each entry's `source_hash` is a sha256 over `git ls-files -s <home>`, so it
+# changes whenever any tracked file under the spec's home changes. Hypatia rule
+# HYP-S006 (hypatia-rules/registry-staleness.a2ml) recomputes these and emits a
+# `doc.drift` finding (strategy :review) when a recorded hash goes stale.
+
+[registry]
+version = "1.0.0"
+generator = "scripts/build-registry.sh"
+hash_algorithm = "sha256(git ls-files -s <home>)"
+entry_count = 28
+
+[registry.streams]
+foundation  = "A2ML format family + K9 + contractiles (Stream 1)"
+language    = "AffineScript and language-policy specs (Stream 2)"
+protocol    = "Inter-service / agent protocols"
+governance  = "RSR, readiness grading, pre-flight gates, session standards"
+readiness   = "ARG / FRG / CRG / TRG maturity-grading frameworks"
+integration = "Registry, hypatia rules, templates — the wiring (Stream 3)"
+
+[[spec]]
+id = "a2ml"
+name = "A2ML — Attested Markup Language"
+stream = "foundation"
+home = "a2ml/"
+canonical_doc = "a2ml/README.adoc"
+source_hash = "sha256:b34ffe4d51c1715c4f2e51183d7a510865dc03e962fbeae121e3868fd88a718a"
+route = "the typed/verified machine-readable document format"
+
+[[spec]]
+id = "k9-svc"
+name = "K9 Self-Validating Components"
+stream = "foundation"
+home = "k9-svc/"
+canonical_doc = "k9-svc/README.adoc"
+source_hash = "sha256:eae3b6a0f4e2da1afcfddfecf7a5c173d6c0ac090923c63fe9c14806b5a3b11b"
+route = "self-validating components with embedded contracts + deploy logic"
+
+[[spec]]
+id = "contractiles"
+name = "Contractiles (Must/Trust/Dust/Intend)"
+stream = "foundation"
+home = "contractiles/"
+canonical_doc = "contractiles/README.adoc"
+source_hash = "sha256:628efcbff607cc7382280b52bf662c2c79801ae8f01b902f3aebe84b08dd79ad"
+route = "policy-enforcement primitives the K9 layer is built from"
+
+[[spec]]
+id = "meta-a2ml"
+name = "META.a2ml spec"
+stream = "foundation"
+home = "meta-a2ml/"
+canonical_doc = "meta-a2ml/README.adoc"
+source_hash = "sha256:2904f47d20a79723a830674fd9dc14105bf14911b5f700586480fe3a7a424542"
+route = "architecture decisions / governance metadata format"
+
+[[spec]]
+id = "state-a2ml"
+name = "STATE.a2ml spec"
+stream = "foundation"
+home = "state-a2ml/"
+canonical_doc = "state-a2ml/README.adoc"
+source_hash = "sha256:21d88102987bae7853cf8d642aeeba13efdeb1a105bbd4d89e7064ef15ce8b9d"
+route = "project-state metadata format (drives this registry's topology)"
+
+[[spec]]
+id = "ecosystem-a2ml"
+name = "ECOSYSTEM.a2ml spec"
+stream = "foundation"
+home = "ecosystem-a2ml/"
+canonical_doc = "ecosystem-a2ml/README.adoc"
+source_hash = "sha256:46b529c177ddc2166bc2cdfdccc55fef8650e03f8d6b3a1ee25d70a494fb1626"
+route = "ecosystem-positioning metadata format"
+
+[[spec]]
+id = "agentic-a2ml"
+name = "AGENTIC.a2ml spec"
+stream = "foundation"
+home = "agentic-a2ml/"
+canonical_doc = "agentic-a2ml/README.adoc"
+source_hash = "sha256:31832029e8e989e200b4022075ed0c8807bb95f55baa0cda11ce079d1bd5b900"
+route = "AI-agent operational gating / entropy budgets"
+
+[[spec]]
+id = "neurosym-a2ml"
+name = "NEUROSYM.a2ml spec"
+stream = "foundation"
+home = "neurosym-a2ml/"
+canonical_doc = "neurosym-a2ml/README.adoc"
+source_hash = "sha256:62bbea52b4b57bb582cc79b320b97d2fced2bef41a77c33590211cbf4ddbd224"
+route = "symbolic semantics / proof obligations"
+
+[[spec]]
+id = "playbook-a2ml"
+name = "PLAYBOOK.a2ml spec"
+stream = "foundation"
+home = "playbook-a2ml/"
+canonical_doc = "playbook-a2ml/README.adoc"
+source_hash = "sha256:b00cd658fe367314735c9f2689579820263b26d1853252dc72a0fee3d784db63"
+route = "executable operational runbooks"
+
+[[spec]]
+id = "anchor-a2ml"
+name = "ANCHOR.a2ml spec"
+stream = "foundation"
+home = "anchor-a2ml/"
+canonical_doc = "anchor-a2ml/README.adoc"
+source_hash = "sha256:2a88233f201c3d2c05dd4d2530cc0fe33423ce9540a0fc2aa21556233074f4fb"
+route = "project-recalibration intervention format"
+
+[[spec]]
+id = "0-ai-gatekeeper-protocol"
+name = "0-AI Gatekeeper Protocol"
+stream = "protocol"
+home = "0-ai-gatekeeper-protocol/"
+canonical_doc = "0-ai-gatekeeper-protocol/README.adoc"
+source_hash = "sha256:e1893253df97b1b989b1ba8e6926548a9a06a6582ab8b9448438da0b4b3e4428"
+route = "the AI-agent entry/gating protocol behind 0-AI-MANIFEST"
+
+[[spec]]
+id = "k9-coordination-protocol"
+name = "K9 Coordination Protocol"
+stream = "protocol"
+home = "k9-coordination-protocol/"
+canonical_doc = "k9-coordination-protocol/README.adoc"
+source_hash = "sha256:9c856a0ed99f92ab3f8f6049df918fe023422dc6688cbc6110190c122ab28f97"
+route = "multi-agent coordination on top of K9"
+
+[[spec]]
+id = "avow-protocol"
+name = "AVOW Protocol"
+stream = "protocol"
+home = "avow-protocol/"
+canonical_doc = "avow-protocol/README.adoc"
+source_hash = "sha256:fc6011d8531fbe3d8fbc5ba0b819cea892d8e0dee7ccb31ef0a22b7d264a8263"
+route = "consent-attested messaging / origin attribution"
+
+[[spec]]
+id = "axel-protocol"
+name = "AXEL Protocol"
+stream = "protocol"
+home = "axel-protocol/"
+canonical_doc = "axel-protocol/README.adoc"
+source_hash = "sha256:6884bcc4f845e05cb0ff0d6d77171707e74f6069512bcf233161a5d8de8fb704"
+route = "age-gating + explicit-content enforcement"
+
+[[spec]]
+id = "overlay-protocol"
+name = "Overlay Protocol"
+stream = "protocol"
+home = "overlay-protocol/"
+canonical_doc = "overlay-protocol/.machine_readable/6a2/ECOSYSTEM.a2ml"
+source_hash = "sha256:4e490e20401ef888930d7b72fe151bc89e4d084606252a1d6344df2c1dc904e1"
+route = "layered overlay composition spec"
+
+[[spec]]
+id = "consent-aware-http"
+name = "Consent-Aware HTTP"
+stream = "protocol"
+home = "consent-aware-http/"
+canonical_doc = "consent-aware-http/README.adoc"
+source_hash = "sha256:e4165fa238b12e8515b985a21e7c7a9d7337627a484e74abe17fa000113a22e0"
+route = "consent headers / AI-usage boundaries for HTTP"
+
+[[spec]]
+id = "adoption-readiness-grades"
+name = "ARG — Adoption Readiness Grades"
+stream = "readiness"
+home = "adoption-readiness-grades/"
+canonical_doc = "adoption-readiness-grades/README.adoc"
+source_hash = "sha256:036055fcb1c66320015e5dfca56438d8c87fa078c527c4c6226ec9e16803b4e0"
+route = "per-language adoption-maturity profile templates"
+
+[[spec]]
+id = "foundations-readiness-grades"
+name = "FRG — Foundations Readiness Grades"
+stream = "readiness"
+home = "foundations-readiness-grades/"
+canonical_doc = "foundations-readiness-grades/README.adoc"
+source_hash = "sha256:a0e205de918a34d731e65d76e0a87d879dfd07b4e7cefc9b9c59cf8e81a051cb"
+route = "per-language foundational-maturity profile templates"
+
+[[spec]]
+id = "component-readiness-grades"
+name = "CRG — Component Readiness Grades"
+stream = "readiness"
+home = "component-readiness-grades/"
+canonical_doc = "component-readiness-grades/README.adoc"
+source_hash = "sha256:47e5a756220c6f2e1c7274f6814fdbd8fe5a235b808eb638f83f80994d0843e8"
+route = "the X..A grading system for components"
+
+[[spec]]
+id = "toolchain-readiness-grades"
+name = "TRG — Toolchain Readiness Grades"
+stream = "readiness"
+home = "toolchain-readiness-grades/"
+canonical_doc = "toolchain-readiness-grades/README.adoc"
+source_hash = "sha256:26a5399a7b83ccd95e9eee574b90c92ed238fb671f9eb0e284bd7a0b0e109f36"
+route = "per-toolchain readiness profile templates"
+
+[[spec]]
+id = "rhodium-standard-repositories"
+name = "RSR — Rhodium Standard Repositories"
+stream = "governance"
+home = "rhodium-standard-repositories/"
+canonical_doc = "rhodium-standard-repositories/README.adoc"
+source_hash = "sha256:9e10e92598a307d3e32f8af3dc8b5cdfdbbcfd6d78069498d6797dc1f0001e62"
+route = "the repository-compliance standard every repo is graded against"
+
+[[spec]]
+id = "session-management-standards"
+name = "Session Management Standards"
+stream = "governance"
+home = "session-management-standards/"
+canonical_doc = "session-management-standards/README.adoc"
+source_hash = "sha256:86a7739ac5cfd12aa34b1be1505c169e41b53e01bd1b3e3b7be308cd3b06d6b3"
+route = "continuity / verify / handover protocols"
+
+[[spec]]
+id = "ensaid-config"
+name = "ENSAID Config"
+stream = "governance"
+home = "ensaid-config/"
+canonical_doc = "ensaid-config/README.adoc"
+source_hash = "sha256:f6cc431368df4cea795ca24eafb26ae42e6ff6bb17a02d8c4c3d75218709d0b1"
+route = "the ensaid configuration standard"
+
+[[spec]]
+id = "accessibility"
+name = "Accessibility Standard"
+stream = "governance"
+home = "accessibility/"
+canonical_doc = "accessibility/STANDARD.a2ml"
+source_hash = "sha256:2286b68bb6ededf8534e90ad52f3ae5f7d25e4193f890ce5c740686171a4db2b"
+route = "estate accessibility requirements"
+
+[[spec]]
+id = "publication-pre-flight"
+name = "Publication Pre-Flight"
+stream = "governance"
+home = "publication-pre-flight/"
+canonical_doc = "publication-pre-flight/ESTATE-AUDIT-BASELINE-2026-03-30.adoc"
+source_hash = "sha256:5bcf21e86a10248b20bf37fa8480a16d3ab3604a784f3cdb23e2ec351329975b"
+route = "submission gate (HOL + Zenodo checklists)"
+
+[[spec]]
+id = "release-pre-flight"
+name = "Release Pre-Flight (V1 Gate)"
+stream = "governance"
+home = "release-pre-flight/"
+canonical_doc = "release-pre-flight/V1-GATE.adoc"
+source_hash = "sha256:790505e07de1cc1f3a22eed1e9ee0be0c75e28f9adbdec0aa9833253d9030a4a"
+route = "hard v1.0.0 audit requirements"
+
+[[spec]]
+id = "hypatia-rules"
+name = "Standards Hypatia Rules"
+stream = "integration"
+home = "hypatia-rules/"
+canonical_doc = "hypatia-rules/README.adoc"
+source_hash = "sha256:707852684795e8474bc764473c36bc4d56fa139014ab3abbc0f550319637138c"
+route = "the dogfooding rules that scan THIS repo (incl. drift detection)"
+
+[[spec]]
+id = "a2ml-templates"
+name = "A2ML Templates"
+stream = "integration"
+home = "a2ml-templates/"
+canonical_doc = "a2ml-templates/STATE.a2ml.v2.spec.adoc"
+source_hash = "sha256:5105bc72621b6214f1adecdf33a1dadf62d1d2b0afd0c2c6a48bbc5e24e9a454"
+route = "copy-in templates for the 7 A2ML files"
+
+### End of REGISTRY.a2ml