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

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,16 +51,18 @@ 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),

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
@@ -154,9 +156,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 +226,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 +298,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 +346,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 +372,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 +387,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)
 ```
 

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
 

package/skills/package-release/scripts/gate-roster.mjs

@@ -56,14 +56,17 @@ export const GATE_ROSTER = [
   // worktree.mjs && npm run dogfood:status` once under the pnpm layout too
   // before cutting (cut-procedure.md §3.1 states the per-gate layout need).
   { n: 17, cmd: 'npm run dogfood:status',                      what: 'P0/P1 dogfood floor (static-only under npm-ci; run once more under bootstrap layout for full coverage, gh#1359)' },
-  // gh#421: these four live in the `npm run check` aggregate but were never
-  // in the pre-cut roster, so a gate added to CI silently never reached a
-  // cut. examples-md + site-a2ui are the two generators an `.examples.html`
-  // edit invalidates (the v0.8.14 cut lost a CI round-trip to exactly that);
-  // contrast is the AA gate that gh#427 widened from 42 to 90 pairs;
-  // token-semantics-sync keeps the token-selection pack's generated half honest.
+  // gh#421: these live in the `npm run check` aggregate but were never in
+  // the pre-cut roster, so a gate added to CI silently never reached a cut.
+  // examples-md is the generator an `.examples.html` edit invalidates (the
+  // v0.8.14 cut lost a CI round-trip to exactly that); contrast is the AA
+  // gate that gh#427 widened from 42 to 90 pairs; token-semantics-sync keeps
+  // the token-selection pack's generated half honest.
+  // (Gate 19 was `verify:site-a2ui` — retired with the site-a2ui mechanism
+  // itself, ADR-0072 Decision 2 / gh#2410. Number left unassigned rather
+  // than renumbering 20+ — gate numbers are cited as identities in shipped
+  // release notes, same discipline gate 29's note states.)
   { n: 18, cmd: 'npm run check:examples-md-fresh',             what: '.examples.md vs .examples.html' },
-  { n: 19, cmd: 'npm run verify:site-a2ui',                    what: 'site-a2ui converted rows vs source fragments' },
   { n: 20, cmd: 'npm run verify:contrast',                     what: 'WCAG AA — canvas-text + text-on-fill pairs' },
   { n: 21, cmd: 'npm run check:token-semantics-sync',          what: 'token-selection generated references vs token sources' },
   // Operator directive 2026-07-27: demo surfaces must be discoverable —

package/skills/primitive-authoring/references/common-gotchas.md

@@ -16,7 +16,7 @@ Composite authors: read §§1–5 BEFORE Phase 3 sketch. Anyone adding an async
 4. [minmax(min, 1fr) inside repeat() fighting container queries](#4-minmaxmin-1fr-inside-repeat-fighting-container-queries)
 5. [Nested `<!-- ... -->` inside design-plan canonical-sketch fenced blocks](#5-nested----inside-design-plan-canonical-sketch-fenced-blocks)
 6. [Async load/render function completing out of order](#6-async-loadrender-function-completing-out-of-order--a-guard-at-the-checkpoint-isnt-enough)
-7. [Minting a wrapper-shaped component before its registry.js entry lands](#7-minting-a-wrapper-shaped-component-before-its-registryjs-entry-lands--site-a2ui-silently-deletes-the-node-not-just-mis-types-it)
+7. [Minting a wrapper-shaped component before its registry.js entry lands](#7-minting-a-wrapper-shaped-component-before-its-registryjs-entry-lands--the-transpiler-silently-deletes-the-node-not-just-mis-types-it)
 
 ---
 
@@ -123,15 +123,15 @@ async #loadContent(route) {
 
 ---
 
-## 7. Minting a wrapper-shaped component before its registry.js entry lands — site-a2ui silently deletes the node, not just mis-types it
+## 7. Minting a wrapper-shaped component before its registry.js entry lands — the transpiler silently deletes the node, not just mis-types it
 
-**Pattern**: a tag is gated first and only, for `*-ui` tags, by `packages/gen-ui/a2ui/registry.js`'s hand-maintained `registry` map — inverted into `reverseRegistry` at `transpiler-maps.js`'s module init, consulted first thing in `compose/transpiler/transpiler.js:149-150`. `registry.js` is hand-edited, not generated by `node scripts/build/components.mjs` (that script writes sidecars/prop-catalog data, consumed only for prop-extraction fidelity on tags the transpiler ALREADY resolved — `transpiler-maps.js:22-26`); a runtime `registerType()` call doesn't rescue a stale row either — `reverseRegistry` is a one-time init snapshot, not live. Regenerate a site-a2ui row for a demo using a component minted in the SAME change, before its `registry.js` line lands, and the tag falls through to `transpiler.js`'s "Unknown → Column" branch (line 180-183) — same mechanism as gh#535's toolbar-group breakage, which at least rendered visibly-wrong. A NEW component is usually wrapper-shaped (one child, author-defined attributes like `anchor="bottom"` the transpiler doesn't map to any real A2UI prop). That shape trips a SECOND, separate rule right after — "single-child container chains flatten" (`transpiler.js:282-285`): a retyped Column with exactly one child and zero recognized props is discarded outright, and its child is spliced directly into the PARENT's children in its place. The wrapper's own id and node are never pushed to the tree at all — not visible-but-wrong, just gone. The row is then internally self-consistent (content hash matches source) so `check:chunks-fresh`/`verify:site-a2ui` both report clean.
+**Pattern**: a tag is gated first and only, for `*-ui` tags, by `packages/gen-ui/a2ui/registry.js`'s hand-maintained `registry` map — inverted into `reverseRegistry` at `transpiler-maps.js`'s module init, consulted first thing in `compose/transpiler/transpiler.js:149-150`. `registry.js` is hand-edited, not generated by `node scripts/build/components.mjs` (that script writes sidecars/prop-catalog data, consumed only for prop-extraction fidelity on tags the transpiler ALREADY resolved — `transpiler-maps.js:22-26`); a runtime `registerType()` call doesn't rescue a stale row either — `reverseRegistry` is a one-time init snapshot, not live. Transpile a demo using a component minted in the SAME change, before its `registry.js` line lands (e.g. the chunk harvester, `node scripts/build/harvest-chunks.mjs`, or any other engine-transpiler consumer), and the tag falls through to `transpiler.js`'s "Unknown → Column" branch (line 180-183) — same mechanism as gh#535's toolbar-group breakage, which at least rendered visibly-wrong. A NEW component is usually wrapper-shaped (one child, author-defined attributes like `anchor="bottom"` the transpiler doesn't map to any real A2UI prop). That shape trips a SECOND, separate rule right after — "single-child container chains flatten" (`transpiler.js:282-285`): a retyped Column with exactly one child and zero recognized props is discarded outright, and its child is spliced directly into the PARENT's children in its place. The wrapper's own id and node are never pushed to the tree at all — not visible-but-wrong, just gone. The row is then internally self-consistent (content hash matches source) so `check:chunks-fresh` reports clean.
 
-**Example**: minting `anchor-bar-ui` (gh#495, PR #569) and regenerating the `bulk-action-toolbar` pattern's site-a2ui row before the worktree's `registry.js` entry for it existed. Git-verified on the pre-fix commit (`ebf71832d`): `site-a2ui/pages/site__patterns__bulk-action-toolbar.a2ui.json` contains zero occurrences of `pat-bulk-float-bar` (the anchor-bar-ui's own authored id) anywhere — not retyped-and-visible, genuinely absent — while its single child (the toolbar content) survived, reparented one level up. `verify:site-a2ui` reported 321/321 clean.
+**Example (historical — the illustrating consumer has since retired):** minting `anchor-bar-ui` (gh#495, PR #569) and regenerating the `bulk-action-toolbar` pattern's site-a2ui row (site-a2ui itself retired 2026-08-31, ADR-0072 Decision 2 / gh#2410 — the underlying registry-gating hazard below is unchanged, only that particular consumer is gone) before the worktree's `registry.js` entry for it existed. Git-verified on the pre-fix commit (`ebf71832d`): the converted artifact contained zero occurrences of `pat-bulk-float-bar` (the anchor-bar-ui's own authored id) anywhere — not retyped-and-visible, genuinely absent — while its single child (the toolbar content) survived, reparented one level up. The site-a2ui freshness gate of the day reported clean regardless, for the exact reason the Detector below still explains.
 
-**Detector**: none generic — `verify:site-a2ui`'s freshness check can't catch this (the row IS fresh relative to its source, it transpiled correctly against a registry that was itself incomplete). The only catch is rendering the actual route in a browser and confirming the new tag's node count is nonzero, or re-running `node scripts/build/site-a2ui.mjs --page <route>` (or `--stale`) after `registry.js` is updated and diffing the row for the new component name. A non-wrapper-shaped new component (multiple children, or attributes that happen to map to real props) is lower-risk here — it survives as a visible-but-wrong Column, the gh#535 class, which at least has a visual tell.
+**Detector**: none generic — a same-source freshness check can't catch this (the artifact IS fresh relative to its source, it transpiled correctly against a registry that was itself incomplete). The only catch is rendering the actual consuming surface and confirming the new tag's node count is nonzero, or re-running the transpile after `registry.js` is updated and diffing the output for the new component name. A non-wrapper-shaped new component (multiple children, or attributes that happen to map to real props) is lower-risk here — it survives as a visible-but-wrong Column, the gh#535 class, which at least has a visual tell.
 
-**Fix**: the `registry.js` entry is what gates resolution — land it (not just run `components.mjs`, which is necessary for prop fidelity but not sufficient to avoid the retype) before regenerating any site-a2ui row that uses the new tag. When gating a dispatched agent's PR that did this out of order, re-run `node scripts/build/site-a2ui.mjs --page <route>` on the merged tree and browser-probe the tag actually appears — never trust `verify:site-a2ui`'s green alone for a route touching a component minted in the same change.
+**Fix**: the `registry.js` entry is what gates resolution — land it (not just run `components.mjs`, which is necessary for prop fidelity but not sufficient to avoid the retype) before transpiling anything that uses the new tag. When gating a dispatched agent's PR that did this out of order, re-run the transpile on the merged tree and confirm the tag actually appears in the output — never trust a freshness gate's green alone for a surface touching a component minted in the same change.
 
 **Generalizes to**: any hand-maintained resolution map (not build-generated) that a later regeneration step reads through — regenerating before the map is updated produces an internally-consistent-but-wrong artifact that passes a same-source freshness check; if the misresolved shape also happens to trip a downstream simplification/collapse rule, the failure escalates from "renders wrong" to "renders nothing," with no visual tell at all.