@adia-ai/adia-ui-forge 0.8.56 → 0.8.58

package/scripts/site-postwrite-derivation-gate

@@ -1,88 +1,40 @@
 #!/usr/bin/env python3
 """site-postwrite-derivation-gate — PostToolUse check: site source edits name their stale derivatives.
 
-The docs site renders converted routes from GENERATED artifacts: site/site.js
-probes site-a2ui/pages/<slug>.a2ui.json per route and renders it via
-<a2ui-root>.doc — the HTML fragment under site/pages/** is only the 404
-fallback. An editor who changes the fragment and stops there has changed
-NOTHING users see (shipped exactly that way 2026-07, caught only by manual
-review). site/sitemap.json likewise feeds site/llms.txt and the patterns
-index. This hook feeds the regeneration obligation back at write-time; the
-hard gate is the repo-wide site-a2ui verify wired in CI.
-
-Quiet on: fragments with no sitemap route, routes the ledger has not
-converted (the fragment IS what renders), anything under site-a2ui/ and the
-generated pages sidecar-prewrite-guard owns, and any internal error
-(fail-open — this hook must never block editing with a crash).
+site/sitemap.json feeds GENERATED surfaces (site/llms.txt, the patterns/
+templates index) that go stale the moment a route or content path changes
+without a regen. This hook feeds that regeneration obligation back at
+write-time.
+
+(Before ADR-0072 Decision 2 / gh#2410, this hook also flagged
+site/pages/**/*.html fragment edits whose route the site-a2ui ledger
+marked "converted" — the docs site rendered such routes from a GENERATED
+site-a2ui/pages/<slug>.a2ui.json artifact, so a fragment-only edit changed
+nothing users saw. That render path retired; every route now renders
+straight from its fragment, so a fragment edit is never stale on its own
+and needs no nudge.)
 
 Usage:
   site-postwrite-derivation-gate --hook       # PostToolUse mode: event JSON on stdin
-  site-postwrite-derivation-gate selftest     # prove matcher + resolution on fixtures
+  site-postwrite-derivation-gate selftest     # prove matcher on fixtures
 """
 import json
 import sys
 
 SITEMAP_MARKER = "site/sitemap.json"
-FRAGMENT_MARKER = "site/pages/"
-
-# Generated files under site/pages/ are sidecar-prewrite-guard territory.
-GENERATED_EXCLUDE = ("site/pages/patterns/index.html",)
 
 
 def classify(path):
-    """→ ("sitemap"|"fragment", repo-root prefix, "/"-rooted repo path) or (None, None, None)."""
-    if not path or "site-a2ui/" in path:
-        return None, None, None
-    if path.endswith(SITEMAP_MARKER):
-        return "sitemap", path[: -len(SITEMAP_MARKER)], "/" + SITEMAP_MARKER
-    idx = path.find(FRAGMENT_MARKER)
-    if idx == -1 or not path.endswith(".html") or path[idx:] in GENERATED_EXCLUDE:
-        return None, None, None
-    return "fragment", path[:idx], "/" + path[idx:]
-
-
-def find_route(sitemap, rel):
-    """Walk sections/items for the entry whose `content` equals rel; → route path or None."""
-    stack = [sitemap.get("sections") or []]
-    while stack:
-        node = stack.pop()
-        if isinstance(node, list):
-            stack.extend(node)
-        elif isinstance(node, dict):
-            if node.get("content") == rel and node.get("path"):
-                return node["path"]
-            stack.extend(v for k, v in node.items() if k in ("sections", "items", "children"))
+    """→ "sitemap" if `path` is site/sitemap.json, else None."""
+    if path and path.endswith(SITEMAP_MARKER):
+        return "sitemap"
     return None
 
 
-def resolve_fragment(root, rel):
-    """→ feedback reason for a stale-artifact edit, or None to stay quiet.
-
-    Raises on I/O / parse trouble — the caller fail-opens.
-    """
-    with open(root + "site/sitemap.json", encoding="utf-8") as f:
-        route = find_route(json.load(f), rel)
-    if not route:
-        return None  # not a routed page
-    with open(root + "site-a2ui/ledger.json", encoding="utf-8") as f:
-        rows = json.load(f).get("pages") or []
-    row = next((r for r in rows if r.get("route") == route), None)
-    if not row or row.get("status") != "converted":
-        return None  # legacy-rendered: the fragment IS what users see
-    slug = row.get("slug") or route.lstrip("/").replace("/", "__")
-    return (
-        f"site-postwrite-derivation-gate · {rel} is the SOURCE for {route}, which renders "
-        f"from GENERATED site-a2ui/pages/{slug}.a2ui.json — the artifact is now stale and "
-        f"users still see the OLD content. Regenerate: `node scripts/build/site-a2ui.mjs "
-        f"--page {route}` (repo-wide check: `npm run verify:site-a2ui`)."
-    )
-
-
 SITEMAP_REASON = (
     "site-postwrite-derivation-gate · site/sitemap.json feeds GENERATED surfaces that are "
     "now stale: site/llms.txt (`npm run build:llms`) and the patterns/templates index "
-    "(`npm run build:patterns-index`). If you changed routes or content paths, also verify "
-    "site-a2ui route coverage: `node scripts/build/site-a2ui.mjs --verify`."
+    "(`npm run build:patterns-index`)."
 )
 
 
@@ -92,80 +44,24 @@ def hook_mode():
     except Exception:
         return 0
     tool_input = event.get("tool_input") or {}
-    kind, root, rel = classify(tool_input.get("file_path") or "")
-    if not kind:
-        return 0
-    if kind == "sitemap":
+    if classify(tool_input.get("file_path") or "") == "sitemap":
         print(json.dumps({"decision": "block", "reason": SITEMAP_REASON}))
-        return 0
-    try:
-        reason = resolve_fragment(root, rel)
-    except Exception:
-        return 0  # fail-open: never block editing on our own error
-    if reason:
-        print(json.dumps({"decision": "block", "reason": reason}))
     return 0
 
 
 def selftest():
-    import os
-    import tempfile
-
     scope_cases = [
-        ("/repo/site/pages/architecture/ontology.html", "fragment"),
-        ("site/pages/guides/testing.html", "fragment"),
         ("/repo/site/sitemap.json", "sitemap"),
-        ("/repo/site/pages/patterns/index.html", None),  # generated: prewrite guard owns it
-        ("/repo/site-a2ui/pages/site__x__y.a2ui.json", None),
-        ("/repo/site-a2ui/ledger.json", None),
+        ("/repo/site/pages/architecture/ontology.html", None),
+        ("site/pages/guides/testing.html", None),
+        ("/repo/site/pages/patterns/index.html", None),
         ("/repo/site/site.js", None),
         ("/repo/site/pages/architecture/notes.txt", None),
         ("/repo/apps/tasks/app/index.html", None),
     ]
     for path, expected in scope_cases:
-        if classify(path)[0] != expected:
-            print(f"selftest: FAIL scope {path} → {classify(path)[0]} expected {expected}")
-            return 1
-    with tempfile.TemporaryDirectory() as tmp:
-        root = tmp + os.sep
-        os.makedirs(root + "site")
-        os.makedirs(root + "site-a2ui")
-        with open(root + "site/sitemap.json", "w", encoding="utf-8") as f:
-            json.dump(
-                {
-                    "sections": [
-                        {
-                            "items": [
-                                {"path": "/site/a/one", "content": "/site/pages/a/one.html"},
-                                {"path": "/site/a/two", "content": "/site/pages/a/two.html"},
-                            ]
-                        }
-                    ]
-                },
-                f,
-            )
-        with open(root + "site-a2ui/ledger.json", "w", encoding="utf-8") as f:
-            json.dump(
-                {
-                    "pages": [
-                        {"route": "/site/a/one", "slug": "site__a__one", "status": "converted"},
-                        {"route": "/site/a/two", "slug": "site__a__two", "status": "failed"},
-                    ]
-                },
-                f,
-            )
-        resolve_cases = [
-            ("/site/pages/a/one.html", True),  # converted → nudge
-            ("/site/pages/a/two.html", False),  # ledger row not converted → quiet
-            ("/site/pages/a/three.html", False),  # no sitemap entry → quiet
-        ]
-        for rel, should_fire in resolve_cases:
-            fired = resolve_fragment(root, rel) is not None
-            if fired != should_fire:
-                print(f"selftest: FAIL resolve {rel} fired={fired} expected={should_fire}")
-                return 1
-        if "site__a__one.a2ui.json" not in resolve_fragment(root, "/site/pages/a/one.html"):
-            print("selftest: FAIL reason does not name the stale artifact")
+        if classify(path) != expected:
+            print(f"selftest: FAIL scope {path} → {classify(path)} expected {expected}")
             return 1
     print("selftest: PASS")
     return 0

package/skills/a2ui-maintenance/references/pipeline-overview.md

@@ -51,19 +51,21 @@ ruling was load-bearing on `wireFormat` defaulting to `'dialect'`, with a
 **Named expiry**: the flag-flip ADR that makes `'v1'` the shipping default
 had to re-rule site-a2ui's fitness (re-point vs retirement-by-attrition).
 
-**[resolved, ADR-0072]** That trigger has fired and been ruled:
-retirement-by-attrition, not re-point (Decision 2) — promotion program
-closed, site-a2ui moves to breakage-only maintenance, an attrition-exit
-ticket tracks the wind-down (gh#2410), and the mechanism is removed once the
-promoted set reaches zero. The flip itself has since executed (PR #2412,
-merged 2026-08-30: `exit-gate.js` now defaults to `'v1'`) — site-a2ui is in
-its attrition window now, not a still-open future trigger. Burn-down of
-existing `visual-drift`/`blocked-format-gap` rows is no longer "ordinary
-maintenance toward parity promotion" (ADR-0068 Decision 5) — it is wind-down
-toward the mechanism's removal per gh#2410.
+**[resolved, ADR-0072 — retired 2026-08-31]** That trigger fired and was
+ruled: retirement, not re-point (Decision 2). Passive attrition never
+netted the promoted set down (355 pages and growing at last measurement —
+regen work kept adding rows faster than breakage retired them), so the
+operator converted it to an active drain (gh#2410): the mechanism —
+builder, ledger, artifact tree, gates, hook — is gone. The docs site now
+renders every route through the legacy template path only; site-a2ui is
+no longer part of this pipeline. The dialect side's regression-corpus
+coverage site-a2ui once provided (real-content-scale exercise of the
+dialect renderer, the ADR-0061 lifecycle path, and the engine transpiler)
+has no standing replacement — see ADR-0072 Decision 2 / gh#2410 for the
+closure record.
 
 All paths repo-relative. Specs worth reading before structural changes:
-`.claude/docs/specs/a2ui-v0.9-catalog-guide.md` (protocol + catalog format),
+`.claude/docs/specs/a2ui-v1.0-catalog-guide.md` (protocol + catalog format),
 `.claude/docs/specs/genui-multiturn-architecture.md` (state cache, refiner,
 op format), `.claude/docs/specs/genui-chunk-marker.md` (chunk attributes),
 `.claude/docs/conventions/gen-ui-pipeline.md` (harvester wiring + embedding

package/skills/demo-audit/references/admin-shell-anatomy.md

@@ -30,7 +30,15 @@ the live admin-dashboard example.
    (there is no `<theme-picker-ui>`)
 9. `<admin-scroll>` wrapping optional `<aside data-subnav hidden>` +
    `<router-ui>` (or `<admin-page>` directly for non-routed)
+   **[deprecated 2026-09-01, ADR-0098]** `admin-scroll` is a wholesale
+   rename to `page-scroll` (both modes carried over); `admin-scroll` stays
+   as a working compat alias for the deprecation window only.
 10. `<admin-page>` with `<admin-page-header>` + `<admin-page-body>`
+    **[deprecated 2026-09-01, ADR-0098]** The `admin-page` family is
+    retired deprecate-then-delete in favor of `page-ui[band]` — `page-ui`
+    is now the one canonical page-chrome primitive; this anatomy still
+    describes the pre-migration shape for auditing legacy surfaces during
+    the deprecation window.
 11. `<admin-statusbar>` at content footer (version strip) — ★ commonly missing
 12. Second `<admin-sidebar slot="trailing">` (inspector rail, hidden by
     default) — strongly recommended
@@ -56,7 +64,7 @@ the live admin-dashboard example.
 | content topbar missing `[data-spacer]` / `[data-actions]` | warning — part 7 |
 | content missing trailing `<admin-statusbar>` | warning — part 11 |
 | sidebar topbar contains only plain text | warning — part 3 context switcher |
-| `<admin-scroll>` missing around `<admin-page>` | critical — part 9 (the enforcing script `audit-shell-composition.mjs` tiers this critical: without the scroll+page wrapper the content renders flush with the topbar, no margins) |
+| `<admin-scroll>` missing around `<admin-page>` | critical — part 9 (the enforcing script `audit-shell-composition.mjs` tiers this critical: without the scroll+page wrapper the content renders flush with the topbar, no margins) — **[deprecated 2026-09-01, ADR-0098]** `admin-scroll`/`admin-page` describe the pre-migration shape; the successor is `page-scroll` wrapping `page-ui[band]` |
 
 ## Opt-out contract
 

package/skills/demo-audit/references/app-shell-pitfalls.md

@@ -20,7 +20,7 @@ may stall — wait 30s, re-run.
 | 4 | Top-level `await` without async setup wrap | `[setup-failed]` console error | `export default async function setup(host) { … }` |
 | 5 | Vite import-analysis 500 on dynamic import | `[network-4xx] 500` for `./<name>.contents.js` | add `/* @vite-ignore */` to the dynamic import |
 | 6 | icon-ui not imported despite `<icon-ui>` / `[icon=…]` / icon-rendering composites | `[icon-ui-missing]` | `import "/packages/web-components/components/icon/icon.js"` |
-| 7 | `<admin-page-body>` emitted without its `<admin-page>` ancestor (gh#981) | *(no audit-app-shells.mjs tag — apps/-only script, doesn't sweep this surface)* | wrap in `<admin-page>` — `admin-page > admin-page-body { flex:1; … }` (`admin-shell.bespoke.css:144`) is a direct-child selector; without that literal parent, `admin-page-body` falls back to UA `display:inline` |
+| 7 | `<admin-page-body>` emitted without its `<admin-page>` ancestor (gh#981) | *(no audit-app-shells.mjs tag — apps/-only script, doesn't sweep this surface)* | wrap in `<admin-page>` — `admin-page > admin-page-body { flex:1; … }` (`admin-shell.bespoke.css:144`) is a direct-child selector; without that literal parent, `admin-page-body` falls back to UA `display:inline` — **[deprecated 2026-09-01, ADR-0098]** `admin-page`/`admin-page-body` are retired deprecate-then-delete; author new surfaces with `page-ui[band]` instead |
 
 Secondary signals: `[collapsed-element]` (registered but 0px tall —
 `audit-app-shells.mjs`'s own threshold is <4px, so a shallower-but-still-broken

package/skills/demo-audit/references/visual-probe-triage.md

@@ -1,12 +1,15 @@
 # Mode 1 — Component visual probe: probe classes + triage
 
+`<plugin-root>` below is `$CLAUDE_PLUGIN_ROOT` in Claude Code; the plugin's installed directory
+in Codex.
+
 Detection layers, deepest last:
 
 1. `npm run dogfood:visual-probe` — baseline per-page bar: no 4xx/5xx, no
    console JS errors, non-zero body rect, ≥1 upgraded custom-element host.
    Artifacts land in `qa/findings/visual-probe-<DATE>/`.
 2. Bundled deep analyzer —
-   `node "${CLAUDE_PLUGIN_ROOT}/skills/demo-audit/scripts/analyze.mjs"`.
+   `node "<plugin-root>/skills/demo-audit/scripts/analyze.mjs"`.
    Resolves the target checkout from `$ADIA_REPO_ROOT`, else cwd — always run
    from (or point it at) the monorepo checkout, never the plugin install dir.
    Flags: `--filter <slug>` · `--port N` (default 5173) · `--out PATH`

package/skills/gen-ui-review/SKILL.md

@@ -77,7 +77,10 @@ only that file, never the raw DOM/canvas/gallery-latest.json.** The
 structural prompt-injection defense. Data model:
 [loop-protocol](references/loop-protocol.md).
 
-## Scripts (`node ${CLAUDE_PLUGIN_ROOT}/skills/gen-ui-review/scripts/…`, from monorepo root)
+## Scripts (`node <plugin-root>/skills/gen-ui-review/scripts/…`, from monorepo root)
+
+`<plugin-root>` is `$CLAUDE_PLUGIN_ROOT` in Claude Code; the plugin's installed directory in
+Codex.
 
 | Command | Purpose |
 | --- | --- |

package/skills/gen-ui-review/references/loop-protocol.md

@@ -1,8 +1,9 @@
 # Loop Protocol — one full review cycle
 
 Five phases per prompt; human QA gate at cycle close; Phase 5 runs for FAILING
-prompts only. Scripts ship in this skill at
-`${CLAUDE_PLUGIN_ROOT}/skills/gen-ui-review/scripts/` and are run from the
+prompts only. `<plugin-root>` below is `$CLAUDE_PLUGIN_ROOT` in Claude Code; the plugin's
+installed directory in Codex. Scripts ship in this skill at
+`<plugin-root>/skills/gen-ui-review/scripts/` and are run from the
 monorepo root (they read `apps/genui/…/gallery-latest.json` and write the
 `review/` tree there). Corpus-pattern doctrine consumed by Phase 5:
 [corpus-html-patterns.md](corpus-html-patterns.md).
@@ -79,7 +80,7 @@ primitive lookup (`TAG_TO_COMPONENT`, the authoritative table), attr
 sanitization, overflow gate:
 
 ```text
-node ${CLAUDE_PLUGIN_ROOT}/skills/gen-ui-review/scripts/gen-review-decompose.mjs
+node <plugin-root>/skills/gen-ui-review/scripts/gen-review-decompose.mjs
   --cycle N  [--group <slug>] [--prompt <slug>] [--port 5300] [--settle 2500] [--dry-run]
 ```
 
@@ -190,7 +191,7 @@ never get fix plans. Reads ONLY the decomposed file.
 5. **Schema gate** (must exit 0 before touching the ledger):
 
    ```bash
-   node ${CLAUDE_PLUGIN_ROOT}/skills/gen-ui-review/scripts/validate-cycle-scores.mjs --cycle N --strict
+   node <plugin-root>/skills/gen-ui-review/scripts/validate-cycle-scores.mjs --cycle N --strict
    ```
 
 6. **Update ledger** (`review/cycle-ledger.json`): `cycleNumber`,
@@ -203,7 +204,7 @@ never get fix plans. Reads ONLY the decomposed file.
 7. **Exit condition**:
 
    ```bash
-   node ${CLAUDE_PLUGIN_ROOT}/skills/gen-ui-review/scripts/gen-review-status.mjs --check-exit
+   node <plugin-root>/skills/gen-ui-review/scripts/gen-review-status.mjs --check-exit
    ```
 
    Exit 0 → `status: COMPLETE`; exit 1 → `status: OPEN` (the script lists the

package/skills/package-release/references/changelog-discipline.md

@@ -1,5 +1,8 @@
 # `changelog-discipline.md` — Keep-a-Changelog mechanics + F-N1 enrichment
 
+`<plugin-root>` below is `$CLAUDE_PLUGIN_ROOT` in Claude Code; the plugin's installed directory
+in Codex.
+
 > Load whenever a cut touches CHANGELOGs (always for author-from-scratch; for a
 > handoff only if F-N1 warns). The monorepo uses Keep-a-Changelog per package;
 > the cut **promotes** `## [Unreleased]` into `## [vX.Y.Z] — YYYY-MM-DD`.
@@ -18,7 +21,7 @@
 The heading swap is all that happens; content under it stays:
 
 ```bash
-node "${CLAUDE_PLUGIN_ROOT}/skills/package-release/scripts/promote-unreleased.mjs" \
+node "<plugin-root>/skills/package-release/scripts/promote-unreleased.mjs" \
   --version 0.X.Y --date YYYY-MM-DD --packages web-components,web-modules,a2ui/corpus
 ```
 
@@ -70,7 +73,7 @@ Why this recurs: cross-package sweeps leave 1–3 incidental touches (a docstrin
 ## §Stubs — ride-along lockstep
 
 ```bash
-node "${CLAUDE_PLUGIN_ROOT}/skills/package-release/scripts/insert-stub.mjs" \
+node "<plugin-root>/skills/package-release/scripts/insert-stub.mjs" \
   --version 0.X.Y --date YYYY-MM-DD \
   --substantive "<one-line> in @adia-ai/<pkg>" \
   --xref "packages/web-modules/CHANGELOG.md#0XY--YYYY-MM-DD" \
@@ -111,7 +114,7 @@ This is cut-procedure §Step 4f: the SAME matcher F-N1 uses at tag time (every r
 **Recovery — a warn AFTER tagging** (Step 4f skipped, or an interleaved merge added uncovered changes): the release commit is already merged via PR, so `--amend` is not possible —
 
 1. Run `--pending-version X.Y.Z --fix`; `git add` the CHANGELOGs; `git commit -m "fix(release): F-N1 enrichment — vX.Y.Z"`; push the branch → PR → CI → merge.
-2. The SHA moved: `node "${CLAUDE_PLUGIN_ROOT}/skills/package-release/scripts/tag-lockstep.mjs" --version X.Y.Z --delete`, then re-tag at `main`'s new post-merge HEAD.
+2. The SHA moved: `node "<plugin-root>/skills/package-release/scripts/tag-lockstep.mjs" --version X.Y.Z --delete`, then re-tag at `main`'s new post-merge HEAD.
 3. Re-run F-N1; expect per-package clean (umbrella error stays, ignored). ONE recovery round — if a second warn appears, the cause is upstream (find what keeps merging into the window), not another enrichment.
 
 ## §Dating and anchors

package/skills/package-release/references/cut-procedure.md

@@ -1,5 +1,8 @@
 # `cut-procedure.md` — the standard lockstep cut
 
+`<plugin-root>` below is `$CLAUDE_PLUGIN_ROOT` in Claude Code; the plugin's installed directory
+in Codex.
+
 > Load for any class-A lockstep cut (cut & ship · author from scratch · deploy
 > handoff). Companions: [`gates-catalog.md`](gates-catalog.md) (gate roster +
 > failure routing), [`changelog-discipline.md`](changelog-discipline.md) (promotion
@@ -13,7 +16,7 @@ Two entry variants, converging at Step 5:
 - **Variant A — deploy handoff:** a peer pre-cut the release commit + CHANGELOG + bump + lockfile. Re-baseline, verify, run **Step 4e** (release docs + team notes — the peer's cut may not have generated them, and the pretag gate blocks Step 6 without them), then resume at Step 6 (tag).
 - **Variant B — author from scratch:** source landed under `## [Unreleased]` with no bump. Do Step 4 (promotion + bump + lockfile), then the full tail.
 
-`` `${CLAUDE_PLUGIN_ROOT}/skills/package-release/scripts/release-pack.mjs` `` (bundled) mechanizes the sequence in two phases per invariant 3 — the cut modes stop at the release commit (PR → CI → merge happens between), `--mode handoff` runs tag→publish→deploy from post-merge main. **Run with `--go` for an operator-initiated release** (single authorization, §below); the steps below are the manual/diagnostic form and run straight through on the same one-go model.
+`` `<plugin-root>/skills/package-release/scripts/release-pack.mjs` `` (bundled) mechanizes the sequence in two phases per invariant 3 — the cut modes stop at the release commit (PR → CI → merge happens between), `--mode handoff` runs tag→publish→deploy from post-merge main. **Run with `--go` for an operator-initiated release** (single authorization, §below); the steps below are the manual/diagnostic form and run straight through on the same one-go model.
 
 | Step | Action | Mutates? |
 | --- | --- | --- |
@@ -78,7 +81,6 @@ If `git diff <prev-tag>..HEAD --name-only` touches component yaml / `.a2ui.json`
 ```bash
 node scripts/build/components.mjs             # catalog + per-component sidecars
 node scripts/build/generate-examples-md.mjs   # .examples.md from .examples.html
-node scripts/build/site-a2ui.mjs --stale      # /site/components/* converted rows
 npm run harvest:chunks                        # chunk corpus from site/apps/playgrounds/catalog
 npm run check:embeddings-fresh                # ← run this FIRST; if it passes, SKIP the rebuild below
 npm run build:embeddings:chunks               # ONLY if the line above failed (needs OPENAI_API_KEY)
@@ -89,8 +91,8 @@ npm run build:bundles                         # dist CSS+JS bundles
 
 **The `data-chunk-*` qualifier was the trap** (gh#421). Two separate cuts lost a CI round-trip to it:
 
-- **v0.8.14** edited two components' `*.examples.html` — not yaml, not `.contents.html`, no annotation — so it read as out of scope. It isn't: `.examples.html` feeds **three** generators (`.examples.md`, the `site-a2ui` converted rows, and the chunk harvest's source hashes). Every freshness gate this doc named came back clean, and CI still failed on `🔴 stale /site/components/{menu,popover}` plus `2 source file(s) changed since harvest`.
-- **The 0.8.16 cycle** then added a brand-new `site/pages/guides/theming.html` with *no* annotations, ran `site-a2ui`, `check:links`, `verify:llms`, and `verify:patterns-index` — all clean — and CI failed anyway: `1 source file(s) NEW since harvest`.
+- **v0.8.14** edited two components' `*.examples.html` — not yaml, not `.contents.html`, no annotation — so it read as out of scope. It isn't: `.examples.html` feeds **two** generators (`.examples.md` and the chunk harvest's source hashes; a third, the retired site-a2ui converted rows, applied historically). Every freshness gate this doc named came back clean, and CI still failed on `🔴 stale /site/components/{menu,popover}` plus `2 source file(s) changed since harvest`.
+- **The 0.8.16 cycle** then added a brand-new `site/pages/guides/theming.html` with *no* annotations, ran `check:links`, `verify:llms`, and `verify:patterns-index` — all clean — and CI failed anyway: `1 source file(s) NEW since harvest`.
 
 Root cause of both: `check-chunks-fresh` hashes **every** source file under the harvest globs and compares the set against the corpus record, so a new or changed file trips it whether or not the harvester extracts a chunk from it. The annotation governs what gets *harvested*, never what gets *hashed*. Hence the trigger list above names the directories, not the annotation.
 
@@ -121,7 +123,7 @@ npm run check:links                            # 15 intra-repo links
 npm run eval:diff -- --engine zettel           # 16 eval floors
 npm run dogfood:status                         # 17 P0/P1 dogfood floor (static-only under npm-ci; run once more under bootstrap layout for full coverage, gh#1359)
 npm run check:examples-md-fresh                # 18 .examples.md vs .examples.html
-npm run verify:site-a2ui                       # 19 site-a2ui rows vs source fragments
+# gate 19 (verify:site-a2ui) retired with the site-a2ui mechanism — ADR-0072 Decision 2 / gh#2410
 npm run verify:contrast                        # 20 WCAG AA — canvas-text AND text-on-fill
 npm run check:token-semantics-sync             # 21 token-selection generated refs vs token sources
 npm run check:demo-routes                      # 22 demo surfaces routed + patterns indexed
@@ -135,6 +137,9 @@ node scripts/release/check-estate-split-latch.mjs           # 29 no lockstep cut
 npm run check:catalog-tiers                    # 30 tier-index.json vs committed catalog (gh#1494 — ADR-0069 moved its PR-blocking half to derived-resync; the pre-cut roster re-asserts Class-R freshness before a tag. Gate 13 can't catch this: the harvester hashes tier-index.json as a SOURCE)
 npm run check:codex-manifests-fresh            # 31 Codex plugin.json + openai.yaml vs .claude-plugin/plugin.json SoT (gh#1888)
 npm run check:harness-manifests-fresh          # 32 Hermes/Pi plugin.yaml + __init__.py + prompts vs .claude-plugin/plugin.json + commands SoT (gh#1954)
+npm run verify:patterns-index                  # 33 pattern-index.md (mcp + adia-ui-factory) vs corpus source
+node scripts/release/check-yaml-events-vs-runtime.mjs --strict --strict-details  # 34 yaml events: blocks vs runtime dispatch — no phantom/missing events (gh#2829)
+node scripts/release/check-yaml-impl-coverage.mjs --strict                       # 35 yaml schema fields vs implementation coverage (gh#2829)
 ```
 
 **Gate 29 was the ADR-0048 latch; since P5 it is a permanent invariant.** Between P1 and P5 the repo was correct in-repo but deliberately **not publishable** (old-name stubs marked `private: true` that the roster still mapped, plus dependency edges onto workspace packages no cut published), and a cut in that window would have shipped broken packages that npm cannot unpublish. **P5 cleared it by landing the real thing** — the six stubs became publishable shims and `PACKAGE_ROSTER` gained the three remaining new names, at which point all 9 offending edges resolved and the gate went green on its own. No gate logic was changed.
@@ -154,9 +159,9 @@ Any red → route via [`gates-catalog.md`](gates-catalog.md); fix at the source,
 
 **Run 4a whenever a hand-authored `## [Unreleased]` section is still sitting uncommitted, not only on a strict Variant B.** `release-pack.mjs --mode cut` (a peer's pre-staged content, not yet promoted) needs it exactly as much as `--mode from-scratch` does — the v0.8.4 near-miss was `--mode cut` skipping this step entirely because the doc (and the script) only associated promotion with "from scratch". Both modes now run it and both hard-fail before the bump if any roster package still carries non-empty `[Unreleased]` content afterward.
 
-**4a. Promote** `## [Unreleased]` → `## [vX.Y.Z] — YYYY-MM-DD` per package (`` `${CLAUDE_PLUGIN_ROOT}/skills/package-release/scripts/promote-unreleased.mjs` ``); author fresh blocks for changed-but-unlogged packages; stub the pure ride-alongs (`` `${CLAUDE_PLUGIN_ROOT}/skills/package-release/scripts/insert-stub.mjs` ``). Classification recipe + shapes: [`changelog-discipline.md`](changelog-discipline.md).
+**4a. Promote** `## [Unreleased]` → `## [vX.Y.Z] — YYYY-MM-DD` per package (`` `<plugin-root>/skills/package-release/scripts/promote-unreleased.mjs` ``); author fresh blocks for changed-but-unlogged packages; stub the pure ride-alongs (`` `<plugin-root>/skills/package-release/scripts/insert-stub.mjs` ``). Classification recipe + shapes: [`changelog-discipline.md`](changelog-discipline.md).
 
-**4b. Bump.** PATCH vs MINOR: **MINOR is reserved for API-surface breaks only** (removed/renamed prop, attribute, slot, event, token, or tag). Visible behavior changes, re-scalings, and opt-in features stay PATCH; a CHANGELOG bullet saying "(MINOR behavior change)" is prose, not a semver directive. Unqualified "bump version" = PATCH; don't round-trip to ask. `node "${CLAUDE_PLUGIN_ROOT}/skills/package-release/scripts/bump.mjs" --from X.Y.Z-1 --to X.Y.Z`. On a MINOR cut, also bump the internal `@adia-ai/*` `^ranges` separately (bump.mjs touches `"version"` fields only) — and a MINOR cut owes a MIGRATION GUIDE section ([`migration-guide-authoring.md`](migration-guide-authoring.md)).
+**4b. Bump.** PATCH vs MINOR: **MINOR is reserved for API-surface breaks only** (removed/renamed prop, attribute, slot, event, token, or tag). Visible behavior changes, re-scalings, and opt-in features stay PATCH; a CHANGELOG bullet saying "(MINOR behavior change)" is prose, not a semver directive. Unqualified "bump version" = PATCH; don't round-trip to ask. `node "<plugin-root>/skills/package-release/scripts/bump.mjs" --from X.Y.Z-1 --to X.Y.Z`. On a MINOR cut, also bump the internal `@adia-ai/*` `^ranges` separately (bump.mjs touches `"version"` fields only) — and a MINOR cut owes a MIGRATION GUIDE section ([`migration-guide-authoring.md`](migration-guide-authoring.md)).
 
 **4c. Lockfile.** `npm install --package-lock-only --no-audit --no-fund` — must land in the release commit. The publish workflows open with `npm ci`, which hard-fails on a version/lockfile mismatch: a bump without the regenerated lockfile passes locally and breaks **every** publish at clean-install.
 
@@ -224,10 +229,10 @@ stub sections exist leaves it nothing to append to, and the gap resurfaces
 as F-N1 warns at the push boundary, costing a tag move:
 
 ```bash
-node "${CLAUDE_PLUGIN_ROOT}/skills/package-release/scripts/insert-stub.mjs" \
+node "<plugin-root>/skills/package-release/scripts/insert-stub.mjs" \
   --version X.Y.Z --date YYYY-MM-DD --previous-version X.Y.Z-1 \
   --substantive "<one-line>" --xref "<anchor>" --packages <missing-stubs>   # 4a-stub — FIRST, only the missing ones (hard-errors on existing sections)
-node "${CLAUDE_PLUGIN_ROOT}/skills/package-release/scripts/bump.mjs" --from X.Y.Z-1 --to X.Y.Z   # 4b (skip if versions already moved)
+node "<plugin-root>/skills/package-release/scripts/bump.mjs" --from X.Y.Z-1 --to X.Y.Z   # 4b (skip if versions already moved)
 npm install --package-lock-only --no-audit --no-fund                                          # 4c
 npm run check:lockstep                                                                        # 4d
 node scripts/build/derive-genui-catalog.mjs                                                   # 4d.5 — catalogId carries the bumped version (gh#617)
@@ -296,7 +301,7 @@ unresolved AND no review requests changes; any other state stops with the
 evidence, never force-merges):
 
 ```bash
-node "${CLAUDE_PLUGIN_ROOT}/skills/package-release/scripts/pr-bridge.mjs" \
+node "<plugin-root>/skills/package-release/scripts/pr-bridge.mjs" \
   --branch "release/vX.Y.Z" --title "release: vX.Y.Z lockstep" --body-file <path>
 ```
 
@@ -344,7 +349,7 @@ Stage its CHANGELOG edits into the release commit (the Step-5 allowlist already
 Log the planned tag list (evidence table above), then tag **at `main`'s post-merge HEAD** (post-bump fixes belong in the tarball; the window's last merge is the tag point — exception: batch push tags each version at its own release-merge SHA):
 
 ```bash
-node "${CLAUDE_PLUGIN_ROOT}/skills/package-release/scripts/tag-lockstep.mjs" \
+node "<plugin-root>/skills/package-release/scripts/tag-lockstep.mjs" \
   --version X.Y.Z                        # umbrella vX.Y.Z + 10 <pkg>-vX.Y.Z (8 npm + 2 plugins)
 ```
 
@@ -370,7 +375,7 @@ a 14-package roster (`agent`, `persona` and `a2ui-protocol-mcp` missing), which
 is three packages that would simply never publish.
 
 ```bash
-PKGS=$(node -e "import('${CLAUDE_PLUGIN_ROOT}/skills/package-release/scripts/package-paths.mjs')
+PKGS=$(node -e "import('<plugin-root>/skills/package-release/scripts/package-paths.mjs')
   .then(m => console.log(m.PACKAGE_ROSTER.filter(p => p.lockstep !== false).map(p => p.name).join(' ')))")
 echo "$PKGS"                             # log it — this IS the tag list evidence
 
@@ -385,7 +390,7 @@ git -C "$REPO" push origin vX.Y.Z            # umbrella last; triggers nothing
 Log the current registry snapshot (per-package versions + `dist-tags.latest`) before dispatching. For batch pushes, verify ordering against that snapshot: **oldest version publishes and settles first** — `npm dist-tag latest` is set by publish order. Then:
 
 ```bash
-node "${CLAUDE_PLUGIN_ROOT}/skills/package-release/scripts/dispatch-publish.mjs" \
+node "<plugin-root>/skills/package-release/scripts/dispatch-publish.mjs" \
   --version X.Y.Z --verify-triggered     # re-dispatches missing/dead runs; registry-gated (gh#763)
 ```
 
@@ -435,6 +440,28 @@ Deploy discipline (the release tenant of the demo-site host; VM/service ops belo
 
 - Any docs **route** cited to the operator or in notes must exist in `site/sitemap.json` (`grep '"path":'`) — a plausible-looking route that isn't in the sitemap renders blank.
 
+**Milestone close (ADR-0103, gh#2729, dated addendum 2026-09-01).** Every
+lockstep cut has an open GitHub Milestone named `vX.Y.Z` (one per cut,
+created ahead of time or by the first PR scheduled into it). Close it here,
+after the GH releases above and before release notes:
+
+```bash
+number=$(gh api repos/adiahealth/gen-ui-kit/milestones --jq \
+  '.[] | select(.title == "vX.Y.Z") | .number')
+gh api -X PATCH "repos/adiahealth/gen-ui-kit/milestones/$number" -f state=closed
+```
+
+Any issue still open in that milestone at close time either ships anyway
+(re-tag it into the milestone that actually shipped it — never leave an
+already-shipped issue's milestone wrong) or slips to the next milestone
+(re-tag now, don't leave the closed milestone showing open issues). Create
+the NEXT cut's milestone here too, so scheduling work for it doesn't wait on
+this cut's tag:
+
+```bash
+gh api repos/adiahealth/gen-ui-kit/milestones -f title="vNEXT.Y.Z" -f state=open
+```
+
 Any Step-2 stashes: `git stash pop`; flag conflicts to the operator.
 
 ## §Step 11 — Author release notes (default)

package/skills/package-release/references/gates-catalog.md

@@ -1,5 +1,8 @@
 # `gates-catalog.md` — pre-flight gate roster + failure → recovery map
 
+`<plugin-root>` below is `$CLAUDE_PLUGIN_ROOT` in Claude Code; the plugin's installed directory
+in Codex.
+
 > Load for a verify-only run or on any gate failure during a cut. Maps every
 > release-flow gate × what it checks × typical failure × recovery. Gates are
 > grouped by **failure category** — how the operator routes when one goes red —
@@ -16,7 +19,7 @@ Row layout per gate: **What** · **Typical failure** · **Recovery**.
 
 - **What:** all 10 lockstep `@adia-ai/*` packages declare the same `version` (the class-B `adia-plugins` package is excluded — `lockstep: false`, `scripts/package-paths.mjs`); internal `@adia-ai/*` dep ranges match policy (`^X.Y.0` during PATCH cycles, bumped at MINOR).
 - **Typical failure:** one package forgot to bump; a peer edited an internal range mid-PATCH; a `^0.0.x` range slipped in.
-- **Recovery:** version drift → `` `${CLAUDE_PLUGIN_ROOT}/skills/package-release/scripts/bump.mjs` ``; range drift → `npm run check:lockstep:fix` auto-aligns, then re-run.
+- **Recovery:** version drift → `` `<plugin-root>/skills/package-release/scripts/bump.mjs` ``; range drift → `npm run check:lockstep:fix` auto-aligns, then re-run.
 - **Why `^0.0.x` is forbidden:** npm pre-1.0 semver only widens the caret when major+minor aren't both zero — `^0.0.6` resolves to `>=0.0.6 <0.0.7`, locked to exactly 0.0.6. An internal dep pinned that way silently installs a *stale* sibling on every fresh `npm i` (this shipped a real ~4-day-latent bug before the lockstep policy). The `^X.Y.0` floor (Y≥1) widens correctly across patches; trust the gate, don't reason about caret semantics by hand. Moot at 1.0.0.
 
 ### `node scripts/release/check-release.mjs --all-pending` (F-N1, the release trip-wire)
@@ -212,7 +215,7 @@ npm run check:demo-shells
 
 Add `verify:corpus` + `check:embeddings-fresh` if chunks were touched; `check:lightningcss-build` if CSS was touched; F-N1 if unpushed release tags exist.
 
-**Full pre-cut sweep** — the 30-gate roster in [`cut-procedure.md`](cut-procedure.md) §Step 3, sourced from `` `${CLAUDE_PLUGIN_ROOT}/skills/package-release/scripts/gate-roster.mjs` `` (the ONE list; `release-pack.mjs` imports and runs it in full — a subset run is impossible without editing that file). ~90s wall time.
+**Full pre-cut sweep** — the 30-gate roster in [`cut-procedure.md`](cut-procedure.md) §Step 3, sourced from `` `<plugin-root>/skills/package-release/scripts/gate-roster.mjs` `` (the ONE list; `release-pack.mjs` imports and runs it in full — a subset run is impossible without editing that file). ~90s wall time.
 
 **Omnibus** — `npm run check` invokes everything. Heavy; use when re-baselining a stale checkout.
 

package/skills/package-release/references/recovery-paths.md

@@ -1,5 +1,8 @@
 # `recovery-paths.md` — the 8 recovery scenarios
 
+`<plugin-root>` below is `$CLAUDE_PLUGIN_ROOT` in Claude Code; the plugin's installed directory
+in Codex.
+
 > Load on any F-N1 / pre-flight failure, for a batch push, or for post-release
 > recovery. Each scenario: the **shape** (what the repo state looks like), the
 > **resolution** (commands + judgment calls), and what to record. Every scenario
@@ -48,7 +51,7 @@ Ambiguous → surface it, don't guess.
 
 **Shape:** source + CHANGELOG entries landed under `## [Unreleased]`, no bump, no release commit.
 
-**Resolution:** [`cut-procedure.md`](cut-procedure.md) Variant B; `` `${CLAUDE_PLUGIN_ROOT}/skills/package-release/scripts/promote-unreleased.mjs` `` mechanizes the heading swap; fresh blocks per [`changelog-discipline.md`](changelog-discipline.md) §Authoring.
+**Resolution:** [`cut-procedure.md`](cut-procedure.md) Variant B; `` `<plugin-root>/skills/package-release/scripts/promote-unreleased.mjs` `` mechanizes the heading swap; fresh blocks per [`changelog-discipline.md`](changelog-discipline.md) §Authoring.
 
 ## §Scenario 4 — `[Unreleased]` extension (early cut + entangled fix)
 
@@ -80,11 +83,11 @@ Ambiguous → surface it, don't guess.
 **Resolution:**
 
 ```bash
-node "${CLAUDE_PLUGIN_ROOT}/skills/package-release/scripts/dispatch-publish.mjs" \
+node "<plugin-root>/skills/package-release/scripts/dispatch-publish.mjs" \
   --version X.Y.Z --verify-triggered   # re-dispatches packages with no run OR a dead (cancelled/failed/timed-out) run; registry-gated; idempotent
 ```
 
-For a batch, preserve npm-latest ordering (`--after <prev>`). Verify against the registry, not the workflows. **Prevention:** push tags one-at-a-time ([`cut-procedure.md`](cut-procedure.md) §Step 8); `` `${CLAUDE_PLUGIN_ROOT}/skills/package-release/scripts/release-pack.mjs` `` does this automatically and follows with `--verify-triggered`.
+For a batch, preserve npm-latest ordering (`--after <prev>`). Verify against the registry, not the workflows. **Prevention:** push tags one-at-a-time ([`cut-procedure.md`](cut-procedure.md) §Step 8); `` `<plugin-root>/skills/package-release/scripts/release-pack.mjs` `` does this automatically and follows with `--verify-triggered`.
 
 ## §Scenario 8 — Cut on the wrong branch