@adia-ai/adia-ui-forge 0.8.35 → 0.8.37

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

@@ -4,15 +4,16 @@
 > handoff). Companions: [`gates-catalog.md`](gates-catalog.md) (gate roster +
 > 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, 9 package paths, and `ui-kit.exe.xyz` deploy are the
-> @adia-ai monorepo's worked example of the portable discipline. `$REPO` = repo root.
+> The concrete gate names, the roster's package paths (`scripts/package-paths.mjs`,
+> 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:
 
 - **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? |
 | --- | --- | --- |
@@ -70,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
 ```
@@ -109,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.
 
@@ -189,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)
@@ -244,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>
 ```
 
@@ -270,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 + 11 per-package) | The log line a recovery diagnoses from |
+| Tagging (Step 6) | The planned tag list (umbrella + 16 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 |
@@ -285,15 +291,15 @@ After the bump + lockfile, run the AUTHORITATIVE F-N1 matcher against the workin
 node scripts/release/check-release.mjs --pending-version X.Y.Z --fix
 ```
 
-Stage its CHANGELOG edits into the release commit (the Step-5 allowlist already covers `CHANGELOG.md`). It re-verifies its own output with the same matcher before writing — a `--fix` that doesn't satisfy the checker is a hard error, not a silent pass. Do NOT use `check-changelog-coverage.mjs` as the pre-tag gate: it carries a different matcher and a 9-package roster missing the 2 plugins — the drift that cost the v0.8.5 cut 3 enrichment PRs and 3 tag rewrites after "coverage clean" at cut time.
+Stage its CHANGELOG edits into the release commit (the Step-5 allowlist already covers `CHANGELOG.md`). It re-verifies its own output with the same matcher before writing — a `--fix` that doesn't satisfy the checker is a hard error, not a silent pass. (The former `check:changelog-coverage` gate — a different matcher and a 9-package roster missing the 2 plugins — cost the v0.8.5 cut 3 enrichment PRs and 3 tag rewrites after "coverage clean" at cut time; it was deleted 2026-07-19, so `check-release.mjs --pending-version` is now the only pre-tag coverage check.)
 
 ## §Step 6 — Tag
 
 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 + 11 <pkg>-vX.Y.Z (incl. the 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 + 16 <pkg>-vX.Y.Z (14 npm + 2 plugins)
 ```
 
 ## §Step 7 — F-N1 release trip-wire
@@ -312,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
@@ -327,15 +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 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
@@ -346,7 +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 <the 9>; 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
@@ -355,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:
@@ -373,8 +395,129 @@ 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.37 estate-split cut (ADR-0048 P7 — ONE cut, then delete this section)
+
+Extra steps for the single cut that ships the a2ui/gen-ui split. They ride the
+normal procedure above; nothing here replaces a step.
+
+**It is a PATCH cut, by operator ruling (2026-08-13, gh#1192)** — `0.8.37`, not
+the `0.9.0` MINOR the ADR originally proposed. Two consequences to hold in mind
+before Step 4:
+
+- **Invariant 2 (PATCH asymmetry) applies UNCHANGED — no exception.** Internal
+  `@adia-ai/*` dep ranges stay `^0.8.0` on a patch cut, and that is exactly
+  right here: `targetCaret("0.8.37")` is `^0.8.0`, the three new names
+  (`a2ui`, `gen-ui`, `mcp` — retargeted gh#1240, 2026-08-14: this row named
+  `gen-ui-mcp` before the MCP-distribution fold; that name never published,
+  `mcp` is its real successor) publish `0.8.37` as their FIRST version, and
+  `^0.8.0` resolves to it. The shims' deps on their successors are already
+  `^0.8.0` and need no edit; web-modules' EXACT peer pin moves to `0.8.37` by
+  the normal peer rule (gh#489), which `bump.mjs` does. So nothing in the split
+  needs a hand-written range — if `check:lockstep` asks for one, something else
+  is wrong; do not hand-pin.
+- **A patch-shaped number does NOT relax the MIGRATION GUIDE obligation**
+  (invariant 7). Six published names are being replaced; the guide is owed
+  regardless of what the version looks like. This is the one failure mode the
+  small number invites.
+
+**In the release commit (Step 4/5), not before and not after:**
+
+1. **Flip the factory `.mcp.json` pin NAME** — `@adia-ai/a2ui-mcp` →
+   `@adia-ai/mcp` (retargeted gh#1240, 2026-08-14: this step named
+   `@adia-ai/gen-ui-mcp` before the MCP-distribution fold folded that planned
+   name — and `@adia-ai/a2ui-protocol-mcp` — into `@adia-ai/mcp` before either
+   ever published; the flip target moved, the flip's own timing did not), in
+   `packages/plugins/adia-ui-factory/.mcp.json` AND its README prose echo
+   (invariant 8 covers both files; `bump.mjs` moves the VERSION on either
+   name, so only the name is hand-edited). The pinned args also grow a
+   subcommand: `["-y", "@adia-ai/mcp@0.8.37", "gen-ui"]` — the fold's bin
+   dispatches `adia-mcp gen-ui`/`adia-mcp protocol`, not a bare invocation.
+   **Why here and not at P5:** invariant 8 forces the pin to the CURRENT
+   lockstep version. Before this cut that is `0.8.36`, and `@adia-ai/mcp`
+   has no `0.8.36` on npm — flipping early pins every local-marketplace install
+   to `npx -y @adia-ai/mcp@0.8.36`, i.e. a registry 404. In this commit
+   the version becomes `0.8.37`, which this cut publishes. (The reasoning is
+   unchanged by the 0.9.0 → 0.8.37 ruling, and unchanged again by the
+   gen-ui-mcp → mcp retarget; only the numbers and the name moved.)
+   `check:lockstep` accepts any name this pin has carried (`MCP_PIN_RE`), so
+   the flip is gate-clean regardless of which name is live when this runs.
+
+   **Config-KEY standardization rides the same flip (operator ruling
+   2026-08-14):** the `mcpServers` key names move with the pin so a tool
+   call's prefix always names which server answered. Factory `.mcp.json`:
+   key `a2ui` → `adia-gen-ui`. Repo root `.mcp.json`: key `adia-ui` →
+   `adia-gen-ui`. New entries added later use `adia-protocol` /
+   `adia-factory` for the other subcommands. Key renames change consumers'
+   tool prefixes (`mcp__a2ui__*` → `mcp__adia-gen-ui__*`) — that is the
+   point, and it ships in the same breaking-named cut as everything else.
+
+**After Step 9 (publish), once `npm view <old-name> version` shows the shim on
+the registry — never before:**
+
+2. **Deprecate the six retired names.** The list is projected from the shim
+   generator's SPEC, so it cannot drift from what actually shipped:
+
+   ```bash
+   node scripts/build/generate-shims.mjs --deprecate-commands
+   ```
+
+   It prints the `npm deprecate` lines plus an `npm info <pkg> deprecated`
+   verify line per package. Print-only by design — read them, then run them.
+   **Verify by reading the field back**; a zero exit code is not proof.
+   Deprecating before the shim publishes leaves consumers at a dead end (the
+   pointer text names a package version that isn't there yet).
+
+3. **Verify a shim tarball's CONTENTS, not just the publish exit code** — e.g.
+   `npm pack @adia-ai/a2ui-runtime@0.8.37 && tar -tzf *.tgz`, then import one
+   subpath from a scratch dir and confirm it resolves through to
+   `@adia-ai/a2ui`.
+
+**Follow-up PR (not this cut):** delete `packages/shims/`, the roster rows
+marked `shim: true`, their six `publish-a2ui-*.yml` workflows,
+`resolvePackageDir`'s `shims/` fallback, `scripts/build/generate-shims.mjs`,
+`scripts/verify/check-shim-bridges.mjs`, the `check:shims` gate, and this
+section. Then narrow `MCP_PIN_RE` + `bump.mjs`'s pin pattern back to the single
+new name.
+
 ---
 
+## §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 above:
+   `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
 
 Peer pre-cut the release commit: Step 1 (confirm HEAD is the `release(*): vX.Y.Z` commit) → Step 2 → Step 3 → skip 4–5 → resume at Step 6. The peer's release commit must already be MERGED to `main` via its PR before tagging (invariant 3 — tag at post-merge HEAD, never at an unpushed local commit); an unmerged pre-cut commit goes through Step 5.7 first, it doesn't shortcut past it.

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 11 `@adia-ai/*` packages declare the same `version`; internal `@adia-ai/*` dep ranges match policy (`^X.Y.0` during PATCH cycles, bumped at MINOR).
+- **What:** all 16 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)
@@ -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

@@ -2,12 +2,16 @@
 
 > Load when releasing a package versioned **independently** of the lockstep set —
 > excluded from the lockstep gate, no umbrella tag, no demo-site deploy.
-> **Class B currently has NO members** (2026-07-15 policy change, operator
-> ruling): the Claude Code plugins under `packages/plugins/*` joined the
-> lockstep after class-B independence let npm drift a full harness-reset
-> behind the repo (npm served forge 0.1.3/factory 0.2.4 pre-reset content
-> while the rewritten estate sat unpublished at a regressed 0.1.0). This
-> procedure is retained for future genuinely-independent packages. The
+> **Class B's current member is `@adia-ai/adia-plugins`** (gh#1133/gh#1160,
+> ADR-0045) — the npm-sourced marketplace manifest package, marked
+> `lockstep: false` on the roster (`scripts/package-paths.mjs`). It's the
+> first member since the 2026-07-15 policy change (operator ruling) that
+> emptied the class: the Claude Code plugins under `packages/plugins/*`
+> joined the lockstep after class-B independence let npm drift a full
+> harness-reset behind the repo (npm served forge 0.1.3/factory 0.2.4
+> pre-reset content while the rewritten estate sat unpublished at a
+> regressed 0.1.0). This procedure covers both onboarding a NEW class-B
+> package and a routine cut of an existing one (adia-plugins). The
 > lockstep cut is [`cut-procedure.md`](cut-procedure.md).
 
 ## §Two release classes in one monorepo
@@ -15,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` 11/11) | **excluded** — a class-B package is not listed in `check-lockstep.mjs`'s `PACKAGES` (none currently exist; `packages/plugins/*` joined class A 2026-07-15) |
+| Lockstep gate | enforced (`check:lockstep` 16/16) | **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** |
@@ -43,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 11 + 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 16 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: 9 × package.json, 9 × CHANGELOG (headers + body refs), 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: 16 × package.json, 16 × 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 12 tags exist on origin, but no `publish-<pkg>.yml` run exists for them; npm latest unchanged; nothing errored.
+**Shape:** all 17 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