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

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)
@@ -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 + 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 |
@@ -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 + 16 <pkg>-vX.Y.Z (14 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,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 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 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

@@ -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` 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** |
@@ -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 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: 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: 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 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 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
 

package/skills/{adia-release → package-release}/scripts/bump.mjs

@@ -1,5 +1,7 @@
 #!/usr/bin/env node
-// bump.mjs — bump the 11 lockstep @adia-ai/* package.json from --from to --to.
+// bump.mjs — bump every lockstep @adia-ai/* package.json from --from to --to.
+// The set is PACKAGE_ROSTER (package-paths.mjs) filtered to `lockstep !== false`,
+// never a count written here — that number went stale twice.
 //
 // Idempotent. Stops on the first mismatch (a package not at --from) so
 // you can investigate before any mutation lands.
@@ -8,11 +10,11 @@
 //   node bump.mjs --from 0.6.20 --to 0.6.21
 //   node bump.mjs --from 0.6.20 --to 0.6.21 --dry
 //
-// Part of the adia-release skill. Replaces the /tmp/vXXX-prep.mjs
+// Part of the package-release skill. Replaces the /tmp/vXXX-prep.mjs
 // improvisation pattern from the v0.6.13 → v0.6.21 cycles.
 //
 // Exits:
-//   0  — all 11 bumped successfully (or --dry succeeded)
+//   0  — every lockstep package bumped successfully (or --dry succeeded)
 //   1  — at least one package not at --from (no mutation)
 //   2  — bad args / file I/O error
 //   3  — partial mutation (shouldn't happen if --from validation passes)
@@ -43,26 +45,51 @@ const SIBLING_MANIFESTS = Object.fromEntries(
 // version (SKILL invariant 8 — the consumer never floats). bump.mjs left this
 // untouched through the 0.8.6 + 0.8.7 cuts, forcing a manual edit + amend each
 // time; check-lockstep's mcp-pin guard now catches a drift, this moves it.
+//
+// Each package maps to an ARRAY of pin configs — the factory README's own
+// prose echo of the same pin (`server pinned: @adia-ai/a2ui-mcp@X`) is a
+// SECOND file invariant 8 covers, and check:plugin-count-claims' "factory
+// README a2ui-mcp pin" EQUALITY check enforces the two agree. Left out of
+// this array through the 0.8.35 + 0.8.36 cuts, it needed the same manual
+// hand-commit .mcp.json used to (gh#1198) — same file set, invariant 8's own
+// scope, so it moves alongside .mcp.json rather than getting its own key.
+//
+// ANY NAME THIS PIN HAS CARRIED (ADR-0048 P5, retargeted gh#1240 2026-08-14):
+// the generation MCP is `@adia-ai/mcp` (its `gen-ui` surface) since the
+// MCP-distribution fold — P2 had planned `@adia-ai/gen-ui-mcp`, which never
+// published — but the pin keeps naming the old package until the P7 cut
+// flips it in the release commit itself (see lockstep-checks.mjs MCP_PIN_RE
+// for why an early flip pins consumers to a 404). Matching every name means
+// the version bump works before AND after either flip, with no cut-day edit
+// to this file.
+const A2UI_MCP_PIN = {
+  label: 'generation-MCP pin (@adia-ai/{a2ui-mcp,gen-ui-mcp,mcp})',
+  // `@adia-ai/{a2ui-mcp,gen-ui-mcp,mcp}@<from>` (not a prefix of a longer version) → `@<to>`
+  // Escape EVERY regex metacharacter in `from`, not just dots: a prerelease or
+  // build-metadata version (`0.9.0-rc+1`) would otherwise inject `+` as a
+  // quantifier and silently match the wrong text. Same class as the truncating
+  // MCP_PIN_RE suffix CodeRabbit found on PR #1229.
+  pattern: (from) =>
+    new RegExp(`(@adia-ai/(?:(?:a2ui|gen-ui)-mcp|mcp)@)${from.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}(?![\\d.])`),
+  replace: (to) => `$1${to}`,
+};
 const PINNED_REFS = {
-  'packages/plugins/adia-ui-factory': {
-    file: '.mcp.json',
-    label: '@adia-ai/a2ui-mcp pin',
-    // `@adia-ai/a2ui-mcp@<from>` (not a prefix of a longer version) → `@<to>`
-    pattern: (from) => new RegExp(`(@adia-ai/a2ui-mcp@)${from.replace(/\./g, '\\.')}(?![\\d.])`),
-    replace: (to) => `$1${to}`,
-  },
+  'packages/plugins/adia-ui-factory': [
+    { ...A2UI_MCP_PIN, file: '.mcp.json' },
+    { ...A2UI_MCP_PIN, file: 'README.md', label: 'generation-MCP pin (README prose)' },
+  ],
   // web-modules' internal peers pin the EXACT lockstep version (gh#489 —
   // a caret peer never moves on a lockstep bump; adia-v2 sat on llm 0.8.19
   // under web-modules 0.8.22). Same file bumpAll already rewrote for
   // "version", so this pass re-reads it from disk before matching. The
   // check:lockstep peer-exact-mismatch guard catches a pin left behind.
-  'packages/web-modules': {
+  'packages/web-modules': [{
     file: 'package.json',
     label: '@adia-ai/* exact peer pins',
     pattern: (from) =>
       new RegExp(`("@adia-ai/[a-z0-9-]+":\\s*")${from.replace(/\./g, '\\.')}(?![\\d.])`, 'g'),
     replace: (to) => `$1${to}`,
-  },
+  }],
 };
 
 // Repo-level version references (path relative to REPO ROOT, not a package) —
@@ -131,13 +158,15 @@ function loadPackageJsons(repo) {
 // half-bumped tree whose re-run then failed validateAllAtFrom.)
 function loadPinnedRefs(repo) {
   const out = [];
-  for (const [pkg, cfg] of Object.entries(PINNED_REFS)) {
-    const p = path.join(repo, pkg, cfg.file);
-    if (!fs.existsSync(p)) {
-      console.error(`error: missing ${p}`);
-      process.exit(2);
+  for (const [pkg, cfgs] of Object.entries(PINNED_REFS)) {
+    for (const cfg of cfgs) {
+      const p = path.join(repo, pkg, cfg.file);
+      if (!fs.existsSync(p)) {
+        console.error(`error: missing ${p}`);
+        process.exit(2);
+      }
+      out.push({ pkg, cfg, path: p, txt: fs.readFileSync(p, 'utf8') });
     }
-    out.push({ pkg, cfg, path: p, txt: fs.readFileSync(p, 'utf8') });
   }
   for (const cfg of REPO_PINNED_REFS) {
     const p = path.join(repo, cfg.file);
@@ -206,17 +235,19 @@ function bumpAll(packages, from, to, dry) {
       if (!dry) fs.writeFileSync(sibPath, sibOut);
       console.log(`  ${dry ? '[dry] ' : ''}bumped ${p.pkg}/${sibling}: ${from} → ${to}`);
     }
-    const pin = PINNED_REFS[p.pkg];
-    if (pin) {
-      const pinPath = path.join(path.dirname(p.path), pin.file);
-      const pinTxt = fs.readFileSync(pinPath, 'utf8');
-      const pinOut = bumpPinnedRef(pinTxt, pin, from, to);
-      if (pinOut === pinTxt) {
-        console.error(`error: ${p.pkg}/${pin.file} — ${pin.label} '@${from}' not found (invariant 8 drift? set the pin to @${from} and re-run, or use \`npm run check:lockstep:fix\`)`);
-        return -1;
+    const pins = PINNED_REFS[p.pkg];
+    if (pins) {
+      for (const pin of pins) {
+        const pinPath = path.join(path.dirname(p.path), pin.file);
+        const pinTxt = fs.readFileSync(pinPath, 'utf8');
+        const pinOut = bumpPinnedRef(pinTxt, pin, from, to);
+        if (pinOut === pinTxt) {
+          console.error(`error: ${p.pkg}/${pin.file} — ${pin.label} '@${from}' not found (invariant 8 drift? set the pin to @${from} and re-run, or use \`npm run check:lockstep:fix\`)`);
+          return -1;
+        }
+        if (!dry) fs.writeFileSync(pinPath, pinOut);
+        console.log(`  ${dry ? '[dry] ' : ''}bumped ${p.pkg}/${pin.file} ${pin.label}: @${from} → @${to}`);
       }
-      if (!dry) fs.writeFileSync(pinPath, pinOut);
-      console.log(`  ${dry ? '[dry] ' : ''}bumped ${p.pkg}/${pin.file} ${pin.label}: @${from} → @${to}`);
     }
   }
   return bumped;
@@ -268,7 +299,7 @@ function selftest() {
   }
 
   // PINNED_REFS — the .mcp.json a2ui-mcp pin (invariant 8) moves in lockstep.
-  const pinCfg = PINNED_REFS['packages/plugins/adia-ui-factory'];
+  const [pinCfg, readmePinCfg] = PINNED_REFS['packages/plugins/adia-ui-factory'];
   const pinBefore = '{"args":["-y","@adia-ai/a2ui-mcp@0.8.6"]}';
   const pinAfter = bumpPinnedRef(pinBefore, pinCfg, '0.8.6', '0.8.7');
   if (!pinAfter.includes('@adia-ai/a2ui-mcp@0.8.7') || pinAfter.includes('@0.8.6')) {
@@ -279,9 +310,25 @@ function selftest() {
     console.error('selftest FAIL: PINNED_REFS pattern prefix-matched a longer version'); process.exit(1);
   }
 
+  // gh#1198 — the factory README's OWN prose echo of the same pin
+  // (`server pinned: @adia-ai/a2ui-mcp@X`) must move alongside .mcp.json;
+  // check:plugin-count-claims' "factory README a2ui-mcp pin" EQUALITY check
+  // is what caught this drift on the v0.8.35 + v0.8.36 cuts.
+  if (readmePinCfg.file !== 'README.md') {
+    console.error('selftest FAIL: expected the second factory pin config to target README.md'); process.exit(1);
+  }
+  const readmeBefore = '`a2ui` server pinned: `@adia-ai/a2ui-mcp@0.8.6` (tool SoT: `packages/mcp/TOOLS.md`)';
+  const readmeAfter = bumpPinnedRef(readmeBefore, readmePinCfg, '0.8.6', '0.8.7');
+  if (!readmeAfter.includes('@adia-ai/a2ui-mcp@0.8.7') || readmeAfter.includes('@0.8.6')) {
+    console.error('selftest FAIL: PINNED_REFS did not bump the README a2ui-mcp prose pin'); process.exit(1);
+  }
+  if (bumpPinnedRef('@adia-ai/a2ui-mcp@0.8.60', readmePinCfg, '0.8.6', '0.8.7') !== '@adia-ai/a2ui-mcp@0.8.60') {
+    console.error('selftest FAIL: README pin pattern prefix-matched a longer version'); process.exit(1);
+  }
+
   // web-modules exact peer pins (gh#489) — all three move in one pass; a
   // longer version must not prefix-match.
-  const peerCfg = PINNED_REFS['packages/web-modules'];
+  const [peerCfg] = PINNED_REFS['packages/web-modules'];
   const peersBefore = '{"peerDependencies":{"@adia-ai/web-components": "0.8.22","@adia-ai/a2ui-runtime": "0.8.22","@adia-ai/llm": "0.8.22"}}';
   const peersAfter = bumpPinnedRef(peersBefore, peerCfg, '0.8.22', '0.8.23');
   if ((peersAfter.match(/0\.8\.23/g) || []).length !== 3 || peersAfter.includes('0.8.22')) {