@adia-ai/adia-ui-forge 0.8.36 → 0.8.38

package/skills/{adia-release → package-release}/evals/routing-corpus.json

@@ -1,115 +1,115 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "name": "adia-release routing accuracy corpus",
+  "name": "package-release routing accuracy corpus",
   "version": "2.1.0",
-  "purpose": "Routing-eval corpus for adia-release. Each phrase declares the skill (expected), a forbidden skill (expected_not, for phrases the source data only ever asserted as \"not this skill\"), or neither. Scored by scripts/skills/run-skill-evals.mjs (TF-IDF token overlap over per-skill description+triggers).",
+  "purpose": "Routing-eval corpus for package-release. Each phrase declares the skill (expected), a forbidden skill (expected_not, for phrases the source data only ever asserted as \"not this skill\"), or neither. Scored by scripts/skills/run-skill-evals.mjs (TF-IDF token overlap over per-skill description+triggers).",
   "scoring_notes": "Heuristic signal, not ground truth. Treat misroutes as a prompt to tighten the skill description, never as a reason to keyword-stuff it. Real harness routing is LLM-driven.",
-  "scope": "adia-release routing \u2014 does this phrase activate adia-release?",
+  "scope": "package-release routing \u2014 does this phrase activate package-release?",
   "phrases": [
     {
-      "id": "adia-release-pos-01",
+      "id": "package-release-pos-01",
       "phrase": "Cut and ship v0.8.5 of the AdiaUI packages",
-      "expected": "adia-release"
+      "expected": "package-release"
     },
     {
-      "id": "adia-release-pos-02",
+      "id": "package-release-pos-02",
       "phrase": "The [Unreleased] CHANGELOG entries are piling up, let's cut a release",
-      "expected": "adia-release"
+      "expected": "package-release"
     },
     {
-      "id": "adia-release-pos-03",
+      "id": "package-release-pos-03",
       "phrase": "Tag the lockstep packages and push them to origin",
-      "expected": "adia-release"
+      "expected": "package-release"
     },
     {
-      "id": "adia-release-pos-04",
+      "id": "package-release-pos-04",
       "phrase": "check:lockstep is failing \u2014 one package didn't bump",
-      "expected": "adia-release"
+      "expected": "package-release"
     },
     {
-      "id": "adia-release-pos-05",
+      "id": "package-release-pos-05",
       "phrase": "Dispatch the publish workflows for v0.8.5 and verify npm",
-      "expected": "adia-release"
+      "expected": "package-release"
     },
     {
-      "id": "adia-release-pos-06",
+      "id": "package-release-pos-06",
       "phrase": "We have three unpushed release commits piled up, batch-push them",
-      "expected": "adia-release"
+      "expected": "package-release"
     },
     {
-      "id": "adia-release-pos-07",
+      "id": "package-release-pos-07",
       "phrase": "F-N1 is warning about a CHANGELOG entry not covering a touched directory",
-      "expected": "adia-release"
+      "expected": "package-release"
     },
     {
-      "id": "adia-release-pos-08",
+      "id": "package-release-pos-08",
       "phrase": "The release cut landed on the wrong branch, help me recover",
-      "expected": "adia-release"
+      "expected": "package-release"
     },
     {
-      "id": "adia-release-pos-09",
+      "id": "package-release-pos-09",
       "phrase": "Author the release notes and Slack post for the last two versions",
-      "expected": "adia-release"
+      "expected": "package-release"
     },
     {
-      "id": "adia-release-pos-10",
+      "id": "package-release-pos-10",
       "phrase": "This cut removes the variant prop from button-ui, write the MIGRATION GUIDE section",
-      "expected": "adia-release"
+      "expected": "package-release"
     },
     {
-      "id": "adia-release-pos-11",
+      "id": "package-release-pos-11",
       "phrase": "Publish the adia-ui-forge plugin independently of the lockstep set",
-      "expected": "adia-release"
+      "expected": "package-release"
     },
     {
-      "id": "adia-release-pos-12",
+      "id": "package-release-pos-12",
       "phrase": "Just verify the release gates are green without cutting anything",
-      "expected": "adia-release"
+      "expected": "package-release"
     },
     {
-      "id": "adia-release-pos-13",
+      "id": "package-release-pos-13",
       "phrase": "Tags are pushed but zero publish workflows fired, what happened",
-      "expected": "adia-release"
+      "expected": "package-release"
     },
     {
-      "id": "adia-release-neg-01",
+      "id": "package-release-neg-01",
       "phrase": "Restart the exe.dev VM, it's returning 502s",
-      "expected_not": "adia-release"
+      "expected_not": "package-release"
     },
     {
-      "id": "adia-release-neg-02",
+      "id": "package-release-neg-02",
       "phrase": "Rsync the built dist folder to ui-kit.exe.xyz",
-      "expected_not": "adia-release"
+      "expected_not": "package-release"
     },
     {
-      "id": "adia-release-neg-03",
+      "id": "package-release-neg-03",
       "phrase": "Sweep our consumer app for the renamed variant prop after the last breaking release",
-      "expected_not": "adia-release"
+      "expected_not": "package-release"
     },
     {
-      "id": "adia-release-neg-04",
+      "id": "package-release-neg-04",
       "phrase": "Add a new size variant to the button-ui primitive",
-      "expected_not": "adia-release"
+      "expected_not": "package-release"
     },
     {
-      "id": "adia-release-neg-05",
+      "id": "package-release-neg-05",
       "phrase": "Compose a settings screen for our app from the AdiaUI catalog",
-      "expected_not": "adia-release"
+      "expected_not": "package-release"
     },
     {
-      "id": "adia-release-neg-06",
+      "id": "package-release-neg-06",
       "phrase": "zettel coverage dropped on the nightly eval, find out why",
-      "expected_not": "adia-release"
+      "expected_not": "package-release"
     },
     {
-      "id": "adia-release-neg-07",
+      "id": "package-release-neg-07",
       "phrase": "sweep the component demos for native-primitive leaks before we cut",
-      "expected_not": "adia-release"
+      "expected_not": "package-release"
     },
     {
-      "id": "adia-release-neg-08",
+      "id": "package-release-neg-08",
       "phrase": "the gemini adapter is dropping usage tokens on streamed responses",
-      "expected": "adia-llm-internals"
+      "expected": "llm-client-maintenance"
     }
   ],
   "_measured_historical": {

package/skills/{adia-release → package-release}/references/changelog-discipline.md

@@ -18,7 +18,7 @@
 The heading swap is all that happens; content under it stays:
 
 ```bash
-node "${CLAUDE_PLUGIN_ROOT}/skills/adia-release/scripts/promote-unreleased.mjs" \
+node "${CLAUDE_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,12 +70,12 @@ Why this recurs: cross-package sweeps leave 1–3 incidental touches (a docstrin
 ## §Stubs — ride-along lockstep
 
 ```bash
-node "${CLAUDE_PLUGIN_ROOT}/skills/adia-release/scripts/insert-stub.mjs" \
+node "${CLAUDE_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" \
   --previous-version 0.X.Y-1 \
-  --packages llm,a2ui/compose,a2ui/mcp,a2ui/retrieval,a2ui/runtime,a2ui/validator
+  --packages llm,a2ui-compose,a2ui-mcp,a2ui-retrieval,a2ui-runtime,a2ui-validator
 ```
 
 The inserted block:
@@ -111,7 +111,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/adia-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 "${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.
 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/{adia-release → package-release}/references/cut-procedure.md

@@ -5,7 +5,7 @@
 > failure routing), [`changelog-discipline.md`](changelog-discipline.md) (promotion
 > + F-N1 enrichment), [`recovery-paths.md`](recovery-paths.md) (when it goes wrong).
 > The concrete gate names, the roster's package paths (`scripts/package-paths.mjs`,
-> 13 lockstep as of gh#607), and `ui-kit.exe.xyz` deploy are the @adia-ai
+> 16 lockstep as of gh#1240's MCP-distribution fold), and `ui-kit.exe.xyz` deploy are the @adia-ai
 > monorepo's worked example of the portable discipline. `$REPO` = repo root.
 
 Two entry variants, converging at Step 5:
@@ -13,7 +13,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/adia-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.
+`` `${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.
 
 | Step | Action | Mutates? |
 | --- | --- | --- |
@@ -71,7 +71,7 @@ node scripts/build/site-a2ui.mjs --stale      # /site/components/* converted row
 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)
-node scripts/release/check-token-semantics-sync.mjs --fix   # adia-tokens role-roster + alias-layer
+node scripts/release/check-token-semantics-sync.mjs --fix   # token-selection role-roster + alias-layer
 npm run build -w @adia-ai/llm                 # tsc artifact build:bundle-js resolves
 npm run build:bundles                         # dist CSS+JS bundles
 ```
@@ -110,25 +110,30 @@ npm run dogfood:status                         # 17 P0/P1 dogfood floor
 npm run check:examples-md-fresh                # 18 .examples.md vs .examples.html
 npm run verify:site-a2ui                       # 19 site-a2ui rows vs source fragments
 npm run verify:contrast                        # 20 WCAG AA — canvas-text AND text-on-fill
-npm run check:token-semantics-sync             # 21 adia-tokens generated refs vs token sources
+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
 npm run check:brand-assets                     # 23 brand mark token-driven, not baked raster
 node scripts/release/check-cut-hygiene.mjs --version <mode-dependent>  # 24 README CDN-pin + version currency — CUT modes pre-flight at the PREVIOUS version (the README claim is exact-match and only moves at the Step-4 bump; Step 4g re-proves at the cut version), HANDOFF pre-flights at the CUT version (post-merge, the claim already moved)
 python3 packages/plugins/adia-ui-factory/scripts/adia-scaffold selftest  # 25 scaffold specifiers resolve in packed @adia-ai/web-components + @adia-ai/web-modules tarballs (gh#1132)
-node scripts/release/check-dx-sweep-freshness.mjs  # 26 DX sweep fresh + not regression-RED (gh#1137 REQ-05 — FLAGGED, needs adia-release confirmation; see the script's own header)
+node scripts/release/check-dx-sweep-freshness.mjs  # 26 DX sweep fresh + not regression-RED (gh#1137 REQ-05 — FLAGGED, needs package-release confirmation; see the script's own header)
 npm run eval:diff -- --engine free-form                    # 27 fresh free-form eval run (evals/health input, gh#1135)
 node scripts/release/write-eval-health.mjs --version <cut>  # 28 evals/health/<version>.json committed, AC-01/AC-02 run for real (gh#1135, WS-4 SPEC REQ-06)
+node scripts/release/check-estate-split-latch.mjs           # 29 no lockstep cut mid estate-split (ADR-0048 / gh#1192) — see the note below
 ```
 
+**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.
+
+It asserts three tree properties over the lockstep roster — no roster dir is `private: true`, and no roster package depends on a workspace package that is either private or absent from the roster — which is why it self-cleared rather than needing a removal. Never bypass it by flipping `private` or hand-editing the roster; that is the exact failure it exists to prevent. Self-check: `node scripts/release/check-estate-split-latch.mjs selftest`. It stays in the roster permanently: it now costs nothing and catches any FUTURE unpublishable dependency edge.
+
 Any red → route via [`gates-catalog.md`](gates-catalog.md); fix at the source, re-run the narrowest gate, then re-run the full sequence. The canonical miss: a cut that ran 7 of the gates shipped a stale-embeddings defect that surfaced a day later and cost a tag-move recovery.
 
 ## §Step 4 — (Variant B, or ANY variant with uncommitted `[Unreleased]` content) Promote, bump, lockfile
 
 **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/adia-release/scripts/promote-unreleased.mjs` ``); author fresh blocks for changed-but-unlogged packages; stub the pure ride-alongs (`` `${CLAUDE_PLUGIN_ROOT}/skills/adia-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 (`` `${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).
 
-**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/adia-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 "${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)).
 
 **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.
 
@@ -190,10 +195,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/adia-release/scripts/insert-stub.mjs" \
+node "${CLAUDE_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/adia-release/scripts/bump.mjs" --from X.Y.Z-1 --to X.Y.Z   # 4b (skip if versions already moved)
+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)
 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)
@@ -218,7 +223,7 @@ allowlist (never `git add -A`; if peers may have pre-staged files,
 git -C "$REPO" checkout -b "release/vX.Y.Z"
 git -C "$REPO" reset HEAD >/dev/null 2>&1
 git -C "$REPO" add package-lock.json packages/*/package.json packages/*/CHANGELOG.md \
-  packages/a2ui/*/package.json packages/a2ui/*/CHANGELOG.md \
+  packages/gen-ui/a2ui/*/package.json packages/gen-ui/a2ui/*/CHANGELOG.md \
   packages/genui/adia-catalog/base.json packages/genui/adia-catalog/adia-pack.json \
   docs/releases/vX.Y.Z.md   # + in-scope source + Step-3.0 regen outputs
 git -C "$REPO" diff --cached --stat | tail -3   # count must match the allowlist
@@ -245,7 +250,7 @@ unresolved AND no review requests changes; any other state stops with the
 evidence, never force-merges):
 
 ```bash
-node "${CLAUDE_PLUGIN_ROOT}/skills/adia-release/scripts/pr-bridge.mjs" \
+node "${CLAUDE_PLUGIN_ROOT}/skills/package-release/scripts/pr-bridge.mjs" \
   --branch "release/vX.Y.Z" --title "release: vX.Y.Z lockstep" --body-file <path>
 ```
 
@@ -271,7 +276,7 @@ The operator's initiating instruction covers the whole cycle — no per-step re-
 
 | Evidence logged before | Content | Why it's still printed |
 | --- | --- | --- |
-| Tagging (Step 6) | The planned tag list (umbrella + 13 per-package) | The log line a recovery diagnoses from |
+| Tagging (Step 6) | The planned tag list (umbrella + 10 per-package) | The log line a recovery diagnoses from |
 | Pushing (Step 8) | The Step 7 F-N1 output + tag list + `origin/main..HEAD` count | F-N1's first real evidence — and its ERROR path still hard-stops unconditionally |
 | Publishing (Step 9) | The current registry snapshot (versions + `dist-tags.latest`) | Ordering is verified against what's LIVE, mechanically |
 | Deploying (Step 10) | The `deploy-site.yml` dispatch (never a raw rsync) | The workflow carries its own GitHub-environment human gate |
@@ -293,8 +298,8 @@ 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/adia-release/scripts/tag-lockstep.mjs" \
-  --version X.Y.Z                        # umbrella vX.Y.Z + 13 <pkg>-vX.Y.Z (11 npm + 2 plugins, 2026-07-15 policy)
+node "${CLAUDE_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)
 ```
 
 ## §Step 7 — F-N1 release trip-wire
@@ -313,14 +318,20 @@ only the tags push here. Log the Step 7 F-N1 results + the tag list
 is 0 (a non-zero count means local commits bypassed the PR flow — stop
 and route them through a PR first); then:
 
+The package list comes from the roster, never a hand list. This block used to
+enumerate the names inline and silently went stale — it pushed 11 tags against
+a 14-package roster (`agent`, `persona` and `a2ui-protocol-mcp` missing), which
+is three packages that would simply never publish.
+
 ```bash
-for t in web-components-vX.Y.Z web-modules-vX.Y.Z llm-vX.Y.Z a2ui-runtime-vX.Y.Z \
-         a2ui-compose-vX.Y.Z a2ui-corpus-vX.Y.Z a2ui-mcp-vX.Y.Z \
-         a2ui-retrieval-vX.Y.Z a2ui-validator-vX.Y.Z \
-         adia-ui-factory-vX.Y.Z adia-ui-forge-vX.Y.Z; do
-  git -C "$REPO" push origin "$t"        # ONE tag per push — batched multi-tag
-done                                     # pushes drop the create event (Scenario 7)
-git -C "$REPO" push origin vX.Y.Z        # umbrella last; triggers nothing
+PKGS=$(node -e "import('${CLAUDE_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
+
+for p in $PKGS; do
+  git -C "$REPO" push origin "${p}-vX.Y.Z"   # ONE tag per push — batched multi-tag
+done                                         # pushes drop the create event (Scenario 7)
+git -C "$REPO" push origin vX.Y.Z            # umbrella last; triggers nothing
 ```
 
 ## §Step 9 — Publish
@@ -328,16 +339,22 @@ 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/adia-release/scripts/dispatch-publish.mjs" \
+node "${CLAUDE_PLUGIN_ROOT}/skills/package-release/scripts/dispatch-publish.mjs" \
   --version X.Y.Z --verify-triggered     # re-dispatches missing/dead runs; registry-gated (gh#763)
 ```
 
 Wait for the workflows to settle, then verify against the **registry**, never the workflow's green check:
 
 ```bash
-for pkg in web-components web-modules llm agent persona a2ui-runtime a2ui-compose \
-           a2ui-corpus a2ui-mcp a2ui-retrieval a2ui-validator adia-ui-factory \
-           adia-ui-forge; do
+# The name list comes from PACKAGE_ROSTER, never a hand-typed loop — this loop
+# WAS hand-typed and went stale the moment ADR-0048 changed the roster (it still
+# named the six pre-split a2ui packages and omitted a2ui-protocol-mcp, so a
+# "verified" cut would have skipped checking the package most likely to be
+# missing: the new one).
+for pkg in $(node -e '
+  import("./packages/plugins/adia-ui-forge/skills/package-release/scripts/package-paths.mjs")
+    .then(m => console.log(m.PACKAGE_ROSTER.filter(p => p.lockstep !== false).map(p => p.name).join(" ")))
+'); do
   echo -n "$pkg: "; npm view "@adia-ai/$pkg" version
 done
 npm view @adia-ai/web-components dist-tags.latest   # must equal X.Y.Z
@@ -348,9 +365,10 @@ Zero workflows fired after a tag push → [`recovery-paths.md`](recovery-paths.m
 ## §Step 10 — GH releases + site deploy dispatch
 
 ```bash
-for pkg in web-components web-modules llm agent persona a2ui-runtime a2ui-compose \
-           a2ui-corpus a2ui-mcp a2ui-retrieval a2ui-validator adia-ui-factory \
-           adia-ui-forge; do
+for pkg in $(node -e '
+  import("./packages/plugins/adia-ui-forge/skills/package-release/scripts/package-paths.mjs")
+    .then(m => console.log(m.PACKAGE_ROSTER.filter(p => p.lockstep !== false).map(p => p.name).join(" ")))
+'); do
   gh release create "$pkg-vX.Y.Z" --title "@adia-ai/$pkg vX.Y.Z" --notes-file <body>.md
 done
 # Site deploy goes through the pipeline, never a raw rsync. The dispatch is
@@ -359,7 +377,7 @@ done
 gh workflow run "Deploy site (ui-kit.exe.xyz)" --repo adiahealth/gen-ui-kit --ref main
 ```
 
-Deploy discipline (the release tenant of the demo-site host; VM/service ops belong to the deploy skill, `adia-deploy`):
+Deploy discipline (the release tenant of the demo-site host; VM/service ops belong to the deploy skill, `site-deployment`):
 
 - `deploy-site.yml` owns build → pre-flight verify → snapshot → rsync → post-deploy verify → auto-rollback; it builds from `main`, so the release commit must already be merged (§Step 5.7 guarantees this). A raw local rsync bypasses every one of those gates — `release-pack.mjs` dispatches the workflow (never rsyncs directly) behind its own confirm (H1, forge-campaign gh#268 audit: the script had drifted from this already-documented procedure).
 - **Verify deployed FILES, never SPA routes.** The docs site returns HTTP 200 + the same ~5 KB shell for *every* path; an unmatched route renders blank with no error. Curl a content file and grep for real bytes:
@@ -377,7 +395,43 @@ Any Step-2 stashes: `git stash pop`; flag conflicts to the operator.
 
 Always author notes at end-of-cycle without being asked — context is freshest now. Single version → [`notes-authoring.md`](notes-authoring.md); ≥2 versions since the last broadcast → its §Rollup section. Surface the draft inline for copy-paste; the operator owns posting. Skip only on an explicit "no notes".
 
----
+## §The 0.8.38 cut (the clean-world cut — delete this section after it lands)
+
+The first cut AFTER the estate-split bridge. Pre-conditions, all verifiable
+before Step 1:
+
+1. **The shim-deletion follow-up PR has MERGED** (the §0.8.37 follow-up — that
+   section deleted itself with the same PR, as designed:
+   `packages/shims/` gone, roster shim rows gone, the six `publish-a2ui-*.yml`
+   workflows gone, `check:shims`/`check-shim-bridges` retired). The roster file
+   is the member count — never transcribe it.
+2. **Deprecation pointers have been live for the full inter-cut window** —
+   `npm info <old-name> deprecated` returns the pointer text for all six names.
+   This is the stated policy for the one-cycle bridge: caret-floating consumers
+   landed on the shims at 0.8.37, were pointed at the successors the entire
+   window, and hard-stop only now. If the window was shorter than ~a week of
+   real consumer exposure, surface to the operator before cutting rather than
+   deleting the bridge out from under them.
+3. **`fix-old-names` has swept the known consumer repos** against the shim
+   names (the closeout half of the rename wave + split).
+4. Whatever landed between cuts rides along normally — as of authoring, the
+   queued candidates are the directory wave (gh#1244, npm-invisible), the
+   catalog tiers (gh#1243, new `@adia-ai/a2ui` subpath `./catalog`), and the
+   factory MCP server (gh#1241, a third `adia-mcp` subcommand — NOT a new
+   package). None changes the roster; if one does by then, the roster file
+   already reflects it and the gates enforce it.
+
+**In the release commit:** nothing estate-split-specific remains — this is a
+normal cut. If gh#1241 landed, the factory `.mcp.json` MAY additionally
+register `adia-factory` (`["-y", "@adia-ai/mcp@0.8.38", "factory"]`) — an
+addition, not a flip.
+
+**After publish:** the standard registry verify, plus one split-closure check:
+`npm view @adia-ai/a2ui-compose versions` should END at 0.8.37 (the shim's one
+and only publish) — a 0.8.38 appearing under any retired name means a workflow
+survived the follow-up PR; kill the tag and investigate before anything else.
+
+Delete this section in the same PR that closes the split's tracking record.
 
 ## §Variant A shortcut
 

package/skills/{adia-release → package-release}/references/gates-catalog.md

@@ -14,9 +14,9 @@ Row layout per gate: **What** · **Typical failure** · **Recovery**.
 
 ### `npm run check:lockstep`
 
-- **What:** all 13 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).
+- **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/adia-release/scripts/bump.mjs` ``; range drift → `npm run check:lockstep:fix` auto-aligns, then re-run.
+- **Recovery:** version drift → `` `${CLAUDE_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)
@@ -96,8 +96,8 @@ Also: `check:no-self-import-css` (no transitively self-importing barrel) · `che
 
 ### `npm run check:browser-safe`
 
-- **What:** no top-level `import 'node:*'` in browser-reachable modules (`packages/a2ui/{compose,retrieval,validator}`, `web-components/`, `web-modules/`, `apps/*/app/*.contents.js`).
-- **Recovery:** dual-mode pattern (`IS_NODE` + dynamic `await import(/* @vite-ignore */ 'node:*')` + `import.meta.glob` browser branch); canonical impl: `packages/a2ui/retrieval/component-catalog.js`.
+- **What:** no top-level `import 'node:*'` in browser-reachable modules (`packages/gen-ui/a2ui/{compose,retrieval,validator}`, `web-components/`, `web-modules/`, `apps/*/app/*.contents.js`).
+- **Recovery:** dual-mode pattern (`IS_NODE` + dynamic `await import(/* @vite-ignore */ 'node:*')` + `import.meta.glob` browser branch); canonical impl: `packages/gen-ui/a2ui/retrieval/component-catalog.js`.
 
 Siblings: `check:absolute-imports` (no leading-`/` imports — rewrite relative) · `check:template-interp` (template `${expr}` contract) · `check:yaml-events` (yaml `events:` match runtime `dispatchEvent` calls) · `check:yaml-impl-coverage` (every yaml prop implemented in the JS class).
 
@@ -121,7 +121,7 @@ The two `audit:*` probes are soft-fail pre-cut (exit-1 only on criticals); findi
 
 ### `npm run verify:corpus`
 
-- **What:** every chunk in `packages/a2ui/corpus/chunks/*.json` is reachable and well-formed.
+- **What:** every chunk in `packages/gen-ui/a2ui/corpus/chunks/*.json` is reachable and well-formed.
 - **Recovery:** corpus remediation routes to the A2UI-pipeline skill, not this one.
 
 ### `npm run check:chunks-fresh`
@@ -133,6 +133,7 @@ The two `audit:*` probes are soft-fail pre-cut (exit-1 only on criticals); findi
 
 - **What:** `chunk-embeddings.json` at-or-newer-than `chunks/_index.json`.
 - **Recovery:** `npm run build:embeddings:chunks` (needs `OPENAI_API_KEY`; ~6s). Stage `chunk-embeddings.json` + note the regen in the a2ui-corpus CHANGELOG `[vX.Y.Z]`.
+- **2026-08-12 — isolated agent worktrees can't run this recovery step.** An agent dispatched with `isolation: worktree` (e.g. `build-lead` resolving a merge conflict) structurally can't read the dotenv secrets file — a permission guard blocks copying it into the worktree, correctly, since that's a content-revealing operation on a secret file. Hit twice in one sweep: two separate PRs (#1113, #1117) each needed this recovery step mid-conflict-resolution and both had to hand off to a human running the command directly in their own terminal / via `!`. This step is a standing human-in-the-loop point, not something to keep dispatching an agent for.
 
 ### `npm run check:css-bundles-fresh` / `npm run check:js-bundles-fresh`
 
@@ -204,7 +205,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 28-gate roster in [`cut-procedure.md`](cut-procedure.md) §Step 3, sourced from `` `${CLAUDE_PLUGIN_ROOT}/skills/adia-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 29-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.
 
 **Omnibus** — `npm run check` invokes everything. Heavy; use when re-baselining a stale checkout.
 

package/skills/{adia-release → package-release}/references/independent-package-release.md

@@ -19,7 +19,7 @@
 | | Class A — lockstep cut | Class B — independent package |
 | --- | --- | --- |
 | Versioning | whole set bumps together | own version line per package |
-| Lockstep gate | enforced (`check:lockstep` 13/13) | **excluded** — a class-B package is not listed in `check-lockstep.mjs`'s `PACKAGES` (`adia-plugins`, the current member, is filtered out via `lockstep: false` — `scripts/package-paths.mjs`) |
+| Lockstep gate | enforced (`check:lockstep` 10/10) | **excluded** — a class-B package is not listed in `check-lockstep.mjs`'s `PACKAGES` (`adia-plugins`, the current member, is filtered out via `lockstep: false` — `scripts/package-paths.mjs`) |
 | Umbrella tag | `vX.Y.Z` + per-package | **none** — per-package tags only (versions differ) |
 | `dist-tag` ordering | cross-package publish order matters | N/A |
 | Demo-site deploy | yes | **none** |
@@ -47,7 +47,7 @@ Substrate fixes (release scripts / lockfile / CHANGELOG), landed once as a norma
 
 ## §Verify target
 
-The published package(s) on the **npm registry** at their independent versions, plus the npm-published `@adia-ai/adia-plugins` manifest referencing the new versions (ADR-0045). NOT "all 13 lockstep packages + the demo site" — that's class A.
+The published package(s) on the **npm registry** at their independent versions, plus the npm-published `@adia-ai/adia-plugins` manifest referencing the new versions (ADR-0045). NOT "all 10 lockstep packages + the demo site" — that's class A.
 
 ## §Gotchas (from the first independent cut, factory v0.2.2 + forge v0.1.2)
 

package/skills/{adia-release → package-release}/references/migration-guide-authoring.md

@@ -5,11 +5,11 @@
 > the release ships the breaking change, so the release authors the guide section
 > consumers follow. The shared producer/consumer format contract is
 > [`../../../references/contracts/migration-guide-format.md`](../../../references/contracts/migration-guide-format.md)
-> — the factory's `adia-migrate` skill consumes exactly that shape.
+> — the factory's `app-migration` skill consumes exactly that shape.
 >
 > Scope split: **producer (this skill)** authors the guide section + migrates the
 > framework's own in-repo surfaces. **Consumer** (a downstream app sweep) is the
-> factory plugin's `adia-migrate` — decline and redirect. Designing the breaking
+> factory plugin's `app-migration` — decline and redirect. Designing the breaking
 > change itself is a contract decision upstream of both.
 
 The guide lives at **`.claude/docs/MIGRATION GUIDE.md`** (the space in the filename is intentional; it's a first-class consumer artifact). One section per breaking release, newest at top; a consumer jumping versions reads the merged span. Every cut — breaking or not — gets a version-scope bullet in the top index (see the format contract).
@@ -37,7 +37,9 @@ Author (or extend) a section when the cut removes or renames a **public API symb
 git grep -nE '<pattern that surfaces call sites>'
 
 **Sweep:**
-git grep -nlE '<pattern>' | xargs perl -i -pe 's/<old>/<new>/g'
+git grep -lz '<pattern>' | while IFS= read -r -d '' f; do
+  perl -i -pe 's/<old>/<new>/g' "$f"
+done
 ```
 
 Shape rules:
@@ -46,6 +48,13 @@ Shape rules:
 - **Mechanical vs manual, explicitly labeled.** A pure rename ships a `perl -i -pe`; a semantic flip ships a "manual review — here's why" note (sed can't tell author intent).
 - **One component per sweep regex** — alternation captures (`<(toast|alert)-ui`) don't preserve the matched alternative cleanly.
 - **HTML-attribute regexes only match HTML/JSX** — author a separate JS-side regex when the symbol has a programmatic form (`el.variant = 'danger'`).
+- **`git grep -lz | while read -d '' f; do perl -i … "$f"; done`, never `| xargs perl -i`.**
+  The `xargs` form hangs on zero matches (GNU xargs still runs perl once with no file argument,
+  and `perl -i -pe` then blocks reading stdin instead of no-op'ing) and, if `<old>`/`<new>` are
+  passed as shell variables rather than literals, an `@`-bearing replacement (`@adia-ai/...`)
+  parses as perl array interpolation when inlined into `-pe` and silently substitutes empty
+  (gh#1233) — pass such strings through the environment instead of the perl source, per
+  `.claude/docs/MIGRATION GUIDE.md`'s `§0.8.37` `sweep()` helper.
 
 **3. Migrate the in-repo surfaces FIRST.** Before the cut ships, run the audit + sweep against `apps/`, `playgrounds/`, `catalog/`, `packages/web-components/components/*/*.html` — the release must not ship broken examples of the thing it changed, and dogfooding the recipe here is what proves it works for consumers.
 

package/skills/{adia-release → package-release}/references/recovery-paths.md

@@ -17,7 +17,7 @@
 
 1. Verify the skip: `npm view <pkg> versions --json | tail` (no X+1 on npm) + `git tag --list 'vX.Y.*'` (no tags). Run pre-flight at the peer's commit to confirm it's shippable.
 2. Correct the version via a **new commit on top** (not amend — the peer's commit stays for history).
-3. Sweep every occurrence of the wrong version: 13 × package.json, 13 × CHANGELOG (headers + body refs — the lockstep roster, `scripts/package-paths.mjs`), any doc/CSS-comment refs, then regenerate the lockfile. Preserve filename references that intentionally encode the original label.
+3. Sweep every occurrence of the wrong version: 10 × package.json, 10 × CHANGELOG (headers + body refs — the lockstep roster, `scripts/package-paths.mjs`), any doc/CSS-comment refs, then regenerate the lockfile. Preserve filename references that intentionally encode the original label.
 4. Commit as `fix(release): correct vX.Y.Z+1 version-skip → vX.Y.Z` documenting the discovery, then resume [`cut-procedure.md`](cut-procedure.md) at Step 5.
 
 ## §Scenario 2 — Batch push
@@ -38,7 +38,7 @@
 
 **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/adia-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; `` `${CLAUDE_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)
 
@@ -63,18 +63,18 @@
 
 ## §Scenario 7 — Tags pushed, ZERO publish workflows fired
 
-**Shape:** all 14 tags exist on origin (umbrella + one per lockstep-roster package — `scripts/package-paths.mjs`), but no `publish-<pkg>.yml` run exists for them; npm latest unchanged; nothing errored.
+**Shape:** all 11 tags exist on origin (umbrella + one per lockstep-roster package — `scripts/package-paths.mjs`), but no `publish-<pkg>.yml` run exists for them; npm latest unchanged; nothing errored.
 
 **Root cause:** pushing many tags in **one** `git push` fires a single batched create event that GitHub Actions routinely drops. Re-pushing is a no-op (the tags already exist remotely).
 
 **Resolution:**
 
 ```bash
-node "${CLAUDE_PLUGIN_ROOT}/skills/adia-release/scripts/dispatch-publish.mjs" \
+node "${CLAUDE_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/adia-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); `` `${CLAUDE_PLUGIN_ROOT}/skills/package-release/scripts/release-pack.mjs` `` does this automatically and follows with `--verify-triggered`.
 
 ## §Scenario 8 — Cut on the wrong branch