@adia-ai/adia-ui-forge 0.8.62 → 0.8.64

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

@@ -1,4 +1,4 @@
-# `cut-procedure.md` — the standard lockstep cut
+# `cut-procedure.md`, the standard lockstep cut
 
 `<plugin-root>` below is `$CLAUDE_PLUGIN_ROOT` in Claude Code; the plugin's installed directory
 in Codex.
@@ -13,10 +13,10 @@ in Codex.
 
 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.
+- **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.
 
-`` `<plugin-root>/skills/package-release/scripts/release-pack.mjs` `` (bundled) mechanizes the sequence in two phases per invariant 3 — the cut modes stop at the release commit (PR → CI → merge happens between), `--mode handoff` runs tag→publish→deploy from post-merge main. **Run with `--go` for an operator-initiated release** (single authorization, §below); the steps below are the manual/diagnostic form and run straight through on the same one-go model.
+`` `<plugin-root>/skills/package-release/scripts/release-pack.mjs` `` (bundled) mechanizes the sequence in two phases per invariant 3, the cut modes stop at the release commit (PR → CI → merge happens between), `--mode handoff` runs tag→publish→deploy from post-merge main. **Run with `--go` for an operator-initiated release** (single authorization, §below); the steps below are the manual/diagnostic form and run straight through on the same one-go model.
 
 | Step | Action | Mutates? |
 | --- | --- | --- |
@@ -25,12 +25,12 @@ Two entry variants, converging at Step 5:
 | 3 | Pre-flight gates (+ harvest preamble if source content changed) | No |
 | 4a-pre | Assemble `changes/<pr>.md` fragments into the right `[Unreleased]` (REQ-W11-06) | Yes |
 | 4 | (Variant B) Promote `[Unreleased]`; bump; lockfile | Yes |
-| 4f | Pre-tag coverage `--fix` — authoritative F-N1 matcher, pre-PR | CHANGELOGs |
+| 4f | Pre-tag coverage `--fix`, authoritative F-N1 matcher, pre-PR | CHANGELOGs |
 | 5 | Stage the release allowlist; commit on `release/vX.Y.Z` | Yes |
 | 5.5 | Pre-commit freshness trip-wire | No |
 | 5.7 | Release PR: push branch → CI → merge → re-baseline on `main` | PR + merge |
 | 6 | Tag umbrella + per-package at post-merge HEAD | Yes |
-| 7 | F-N1 release trip-wire (expected clean — 4f already ran) | No |
+| 7 | F-N1 release trip-wire (expected clean, 4f already ran) | No |
 | 8 | Push tags (one per push; `main` already merged) | Push |
 | 9 | Dispatch publish workflows; wait; verify registry | Publish |
 | 10 | GH releases + site deploy dispatch | Deploy |
@@ -39,7 +39,7 @@ Two entry variants, converging at Step 5:
 
 ---
 
-## §Step 1 — Re-baseline
+## §Step 1, Re-baseline
 
 Context is stale at the start of every turn; run unconditionally:
 
@@ -49,35 +49,35 @@ git -C "$REPO" status --short
 git -C "$REPO" log --oneline -8
 git -C "$REPO" fetch && git -C "$REPO" log HEAD..origin/main --oneline   # must be empty
 git -C "$REPO" tag --list 'vX.Y.Z' '*-vX.Y.Z'   # must NOT exist yet
-[ -d "$REPO/node_modules/.pnpm" ] && echo "STOP: pnpm-shaped node_modules — run npm ci first"   # gate 9 precondition, see §3.1 layout note
+[ -d "$REPO/node_modules/.pnpm" ] && echo "STOP: pnpm-shaped node_modules, run npm ci first"   # gate 9 precondition, see §3.1 layout note
 ```
 
 **Check the `node_modules` layout here, not at gate 9.** The §3.1 layout note (gh#1359)
 already says gate 9 (`check:js-bundles-fresh`) needs the npm-ci layout, but it sits AFTER
-the gate roster and is easy to read past — the v0.8.55 cut (2026-08-28) ran the full
+the gate roster and is easy to read past, the v0.8.55 cut (2026-08-28) ran the full
 33-gate pre-flight under a pnpm-shaped tree, lost ~12 minutes to gates 1-8 and 10-33
 passing, then failed gate 9 with phantom bundle drift (1.24 MB on disk vs 1.52 MB fresh
-on every JS entry — the Phosphor icon glob resolving differently, not a real source
+on every JS entry, the Phosphor icon glob resolving differently, not a real source
 change). The one-line check above fails in under a second instead. `npm ci` to recover;
 `npm install` alone does NOT reshape an existing pnpm tree.
 
 `branch --show-current` ≠ `main` → stop; cutting on a feature branch pushes a stale `main` ref while the tags point at the feature tip. Recovery: [`recovery-paths.md`](recovery-paths.md) §Scenario 8. If multiple unpushed `release(*):` commits exist → this is a batch push, [`recovery-paths.md`](recovery-paths.md) §Scenario 2.
 
-## §Step 2 — Classify uncommitted files; stash strays
+## §Step 2, Classify uncommitted files; stash strays
 
-Modified/untracked files you didn't author are classification decisions — diff each one. A **stray** = uncommitted + undocumented (no CHANGELOG entry or commit explains it) + behavior-visible + contradicting a release artifact. Stash strays; never revert (revert destroys the work):
+Modified/untracked files you didn't author are classification decisions, diff each one. A **stray** = uncommitted + undocumented (no CHANGELOG entry or commit explains it) + behavior-visible + contradicting a release artifact. Stash strays; never revert (revert destroys the work):
 
 ```bash
-git -C "$REPO" stash push <file1> <file2> -m "vX.Y.Z-cycle: <reason> — parked"
+git -C "$REPO" stash push <file1> <file2> -m "vX.Y.Z-cycle: <reason>, parked"
 ```
 
-Keep the stash held through the site deploy (Step 10) — the tarball builds from the **tag** but the site builds from the **working tree**; an uncommitted stray leaks into the deployed site and not the packages, silently. Pop after the cycle; if pop reports "kept the stash", see [`recovery-paths.md`](recovery-paths.md) §Scenario 6. Record any exclusion in the release-commit message (`Excluded — in-flight: <file> (<reason>)`).
+Keep the stash held through the site deploy (Step 10), the tarball builds from the **tag** but the site builds from the **working tree**; an uncommitted stray leaks into the deployed site and not the packages, silently. Pop after the cycle; if pop reports "kept the stash", see [`recovery-paths.md`](recovery-paths.md) §Scenario 6. Record any exclusion in the release-commit message (`Excluded, in-flight: <file> (<reason>)`).
 
-## §Step 3 — Pre-flight gates
+## §Step 3, Pre-flight gates
 
 ### 3.0 Harvest preamble (only when source content changed in the window)
 
-If `git diff <prev-tag>..HEAD --name-only` touches component yaml / `.a2ui.json` sources, **`*.examples.html`**, `*.contents.html`, **any file under `site/`, `apps/`, `playgrounds/`, or `catalog/`** — annotated with `data-chunk-*` or not — or any `styles/colors/*` token source, regenerate downstream artifacts proactively (otherwise the freshness gates force a tag-move recovery later):
+If `git diff <prev-tag>..HEAD --name-only` touches component yaml / `.a2ui.json` sources, **`*.examples.html`**, `*.contents.html`, **any file under `site/`, `apps/`, `playgrounds/`, or `catalog/`**, annotated with `data-chunk-*` or not, or any `styles/colors/*` token source, regenerate downstream artifacts proactively (otherwise the freshness gates force a tag-move recovery later):
 
 ```bash
 node scripts/build/components.mjs             # catalog + per-component sidecars
@@ -92,20 +92,20 @@ npm run build:bundles                         # dist CSS+JS bundles
 
 **The `data-chunk-*` qualifier was the trap** (gh#421). Two separate cuts lost a CI round-trip to it:
 
-- **v0.8.14** edited two components' `*.examples.html` — not yaml, not `.contents.html`, no annotation — so it read as out of scope. It isn't: `.examples.html` feeds **two** generators (`.examples.md` and the chunk harvest's source hashes; a third, the retired site-a2ui converted rows, applied historically). Every freshness gate this doc named came back clean, and CI still failed on `🔴 stale /site/components/{menu,popover}` plus `2 source file(s) changed since harvest`.
-- **The 0.8.16 cycle** then added a brand-new `site/pages/guides/theming.html` with *no* annotations, ran `check:links`, `verify:llms`, and `verify:patterns-index` — all clean — and CI failed anyway: `1 source file(s) NEW since harvest`.
+- **v0.8.14** edited two components' `*.examples.html`, not yaml, not `.contents.html`, no annotation, so it read as out of scope. It isn't: `.examples.html` feeds **two** generators (`.examples.md` and the chunk harvest's source hashes; a third, the retired site-a2ui converted rows, applied historically). Every freshness gate this doc named came back clean, and CI still failed on `🔴 stale /site/components/{menu,popover}` plus `2 source file(s) changed since harvest`.
+- **The 0.8.16 cycle** then added a brand-new `site/pages/guides/theming.html` with *no* annotations, ran `check:links`, `verify:llms`, and `verify:patterns-index`, all clean, and CI failed anyway: `1 source file(s) NEW since harvest`.
 
 Root cause of both: `check-chunks-fresh` hashes **every** source file under the harvest globs and compares the set against the corpus record, so a new or changed file trips it whether or not the harvester extracts a chunk from it. The annotation governs what gets *harvested*, never what gets *hashed*. Hence the trigger list above names the directories, not the annotation.
 
-When only source *hashes* move and chunk content does not, `check:embeddings-fresh` stays green on its content hash — no embedding rebuild, no `OPENAI_API_KEY` needed. Both incidents above were that case, which is why the block above runs that check *before* `build:embeddings:chunks` and skips the rebuild when it passes: an unconditional rebuild makes an ordinary `.examples.html` or new-page edit fail pre-flight on any machine without the key, for no reason. Only a change that alters chunk **content** needs the rebuild.
+When only source *hashes* move and chunk content does not, `check:embeddings-fresh` stays green on its content hash, no embedding rebuild, no `OPENAI_API_KEY` needed. Both incidents above were that case, which is why the block above runs that check *before* `build:embeddings:chunks` and skips the rebuild when it passes: an unconditional rebuild makes an ordinary `.examples.html` or new-page edit fail pre-flight on any machine without the key, for no reason. Only a change that alters chunk **content** needs the rebuild.
 
-**Regen output supersedes working-tree state.** These outputs land in the release commit unconditionally, even when the same paths are also dirty from a peer — the fresh regen is authoritative; divergent uncommitted work rebases on top afterwards.
+**Regen output supersedes working-tree state.** These outputs land in the release commit unconditionally, even when the same paths are also dirty from a peer: the fresh regen is authoritative; divergent uncommitted work rebases on top afterwards.
 
-**Staging a read-only report without cutting** (gh#3063): `node scripts/release/preflight-dry-run.mjs --version X.Y.Z` runs this same roster (`gate-roster.mjs` SoT) inside a throwaway `npm ci` clone and prints per-gate PASS/FAIL plus a tail-of-log on failure — no bump, no tag, no CHANGELOG promotion, nothing lands on the real repo. This mechanizes the ad-hoc procedure the 0.8.59 staging pre-flight hand-drove (gh#2870 comments 5526330460 + addendum); use it whenever a "how healthy is main right now" report is wanted ahead of an actual cut. `--dry-run` lists the roster with no clone/npm ci; `--keep` preserves the throwaway clone for inspection.
+**Staging a read-only report without cutting** (gh#3063): `node scripts/release/preflight-dry-run.mjs --version X.Y.Z` runs this same roster (`gate-roster.mjs` SoT) inside a throwaway `npm ci` clone and prints per-gate PASS/FAIL plus a tail-of-log on failure, no bump, no tag, no CHANGELOG promotion, nothing lands on the real repo. This mechanizes the ad-hoc procedure the 0.8.59 staging pre-flight hand-drove (gh#2870 comments 5526330460 + addendum); use it whenever a "how healthy is main right now" report is wanted ahead of an actual cut. `--dry-run` lists the roster with no clone/npm ci; `--keep` preserves the throwaway clone for inspection.
 
-### 3.1 The full roster — every gate runs; a subset = pre-flight failure
+### 3.1 The full roster, every gate runs; a subset = pre-flight failure
 
-**Precondition — tsc build for llm, agent, persona (gh#3342).** Gate 4
+**Precondition, tsc build for llm, agent, persona (gh#3342).** Gate 4
 (`test:unit:serial`) runs each package's root `*.test.js` files against its
 BUILT output, not its `src/*.ts`: `persona.test.js` imports `./index.js`
 directly, `agent.test.js`'s own docstring says "run against the BUILT
@@ -113,23 +113,23 @@ output ... `npm run build -w @adia-ai/agent` first", and `llm/core` carries
 a dedicated `dist-check.test.js` that asserts the emitted artifacts exist
 and explicitly does not build them itself. All three packages' emitted
 `.js`/`.d.ts` are gitignored, so a fresh cut clone has none of them until
-something builds them — unlike §3.0's regen outputs, this is a plain build
+something builds them, unlike §3.0's regen outputs, this is a plain build
 artifact, not a content-conditional regen, so `release-pack.mjs`'s
 `step3PreFlight()` now runs `npm run build -w @adia-ai/llm -w @adia-ai/agent
 -w @adia-ai/persona` unconditionally, every cut, immediately before gate 4
-(mechanized fix — a manual cut should run the same command first). The
+(mechanized fix, a manual cut should run the same command first). The
 v0.8.59 cut hit this: §3.0's `npm run build -w @adia-ai/llm` line only
 fires when its source-content trigger list matches, and never named
 agent/persona at all, so a cut with no matching trigger reached gate 4 with
 stale or absent dist and failed on it.
 
-**Execution model (gh#2006): three phases, not one serial walk.** `step3PreFlight()` runs gate 4 solo first (see its own note below), then gates 16 → 27 → 28 strictly in order (the eval-health write-then-read dependency — gate 28 reads whichever `evals/mcp/runs/` directory sorts lexically LAST, so nothing else may write there between 27 and 28), concurrently with a bounded pool running every other gate at once (`PREFLIGHT_CONCURRENCY`, default 4 — override for a dedicated/idle host). Every gate still resolves the same command, still fails the whole pre-flight on a red result, and still reports its own number — only the WALL-CLOCK schedule changed, never the roster below or its numbering. `--dry` previews stay the original flat serial walk unchanged.
+**Execution model (gh#2006): three phases, not one serial walk.** `step3PreFlight()` runs gate 4 solo first (see its own note below), then gates 16 → 27 → 28 strictly in order (the eval-health write-then-read dependency, gate 28 reads whichever `evals/mcp/runs/` directory sorts lexically LAST, so nothing else may write there between 27 and 28), concurrently with a bounded pool running every other gate at once (`PREFLIGHT_CONCURRENCY`, default 4, override for a dedicated/idle host). Every gate still resolves the same command, still fails the whole pre-flight on a red result, and still reports its own number, only the WALL-CLOCK schedule changed, never the roster below or its numbering. `--dry` previews stay the original flat serial walk unchanged.
 
 ```bash
 node scripts/build/components.mjs --verify    #  1 yaml ↔ sidecar ↔ .d.ts
 npm run verify:traits                          #  2 trait coverage
 npm run check:lockstep                         #  3 version coherence (+ factory .mcp.json @adia-ai/mcp pin, invariant 8)
-npm run test:unit:serial                       #  4 vitest, serial — the source of truth (§Cat 8; parallel flakes under load)
+npm run test:unit:serial                       #  4 vitest, serial, the source of truth (§Cat 8; parallel flakes under load)
 npm run typecheck                              #  5 tsc --noEmit
 npm run check:demo-shells                      #  6 demo imports cover composes:
 npm run check:lightningcss-build               #  7 CSS minifies
@@ -144,48 +144,47 @@ npm run check:links                            # 15 intra-repo links
 npm run eval:diff -- --engine zettel           # 16 eval floors
 npm run dogfood:status                         # 17 P0/P1 dogfood floor (static-only under npm-ci; run once more under bootstrap layout for full coverage, gh#1359)
 npm run check:examples-md-fresh                # 18 .examples.md vs .examples.html
-# gate 19 (verify:site-a2ui) retired with the site-a2ui mechanism — ADR-0072 Decision 2 / gh#2410
-npm run verify:contrast                        # 20 WCAG AA — canvas-text AND text-on-fill
+# gate 19 (verify:site-a2ui) retired with the site-a2ui mechanism, ADR-0072 Decision 2 / gh#2410
+npm run verify:contrast                        # 20 WCAG AA, canvas-text AND text-on-fill
 npm run check:token-semantics-sync             # 21 token-selection generated refs vs token sources
 npm run check:demo-routes                      # 22 demo surfaces routed + patterns indexed
 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)
+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 package-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
-npm run check:catalog-tiers                    # 30 tier-index.json vs committed catalog (gh#1494 — ADR-0069 moved its PR-blocking half to derived-resync; the pre-cut roster re-asserts Class-R freshness before a tag. Gate 13 can't catch this: the harvester hashes tier-index.json as a SOURCE)
+node scripts/release/check-estate-split-latch.mjs           # 29 no lockstep cut mid estate-split (ADR-0048 / gh#1192), see the note below
+npm run check:catalog-tiers                    # 30 tier-index.json vs committed catalog (gh#1494, ADR-0069 moved its PR-blocking half to derived-resync; the pre-cut roster re-asserts Class-R freshness before a tag. Gate 13 can't catch this: the harvester hashes tier-index.json as a SOURCE)
 npm run check:codex-manifests-fresh            # 31 Codex plugin.json + openai.yaml vs .claude-plugin/plugin.json SoT (gh#1888)
 npm run check:harness-manifests-fresh          # 32 Hermes/Pi plugin.yaml + __init__.py + prompts vs .claude-plugin/plugin.json + commands SoT (gh#1954)
 npm run verify:patterns-index                  # 33 pattern-index.md (mcp + adia-ui-factory) vs corpus source
-node scripts/release/check-yaml-events-vs-runtime.mjs --strict --strict-details  # 34 yaml events: blocks vs runtime dispatch — no phantom/missing events (gh#2829)
+node scripts/release/check-yaml-events-vs-runtime.mjs --strict --strict-details  # 34 yaml events: blocks vs runtime dispatch, no phantom/missing events (gh#2829)
 node scripts/release/check-yaml-impl-coverage.mjs --strict                       # 35 yaml schema fields vs implementation coverage (gh#2829)
-npm run check:treeshake                        # 36 single-import build matrix (esbuild+rollup) — byte budgets + marker-leak + CSS purity + whole-lib delta + docs grep-gate (gh#2912)
-npm run check:lint-efficacy                    # 37 lint rule bank: seeded catch rate 100% + golden-set 0 error FPs + mutation hardening (gh#2911 — not in `npm run check`, ~100s over the <60s bar)
+npm run check:treeshake                        # 36 single-import build matrix (esbuild+rollup), byte budgets + marker-leak + CSS purity + whole-lib delta + docs grep-gate (gh#2912)
+npm run check:lint-efficacy                    # 37 lint rule bank: seeded catch rate 100% + golden-set 0 error FPs + mutation hardening (gh#2911, not in `npm run check`, ~100s over the <60s bar)
 ```
 
-**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.
+**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.
+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.
 
 **Layout note (gh#1359): the roster does not run under one uniform `node_modules` shape.** Every gate above is layout-agnostic except two, which pull in opposite directions:
 
-- **Gate 9** (`check:js-bundles-fresh`) needs the **npm-ci layout** — the committed `dist/` bundles are npm-shaped (an entry-relative Phosphor icon glob resolves differently under pnpm's non-hoisted layout, producing a materially larger fresh build that fails the diff). Run pre-flight under `npm ci`.
-- **Gate 17** (`npm run dogfood:status`) needs the **pnpm/bootstrapped layout** for its two live-probe legs (`empty-instantiation`, `padded-route-gutter`) to render icons correctly (gh#340) — but auto-degrades to a static-only run (every other audit it aggregates has no dev-server dependency) rather than hard-failing when it detects an npm-shaped layout, so it no longer blocks a straight npm-ci roster pass. **A static-only pass is not full coverage.** Run `node scripts/dev/bootstrap-worktree.mjs && npm run dogfood:status` once under that layout — before or after the main npm-ci roster pass — to actually exercise the two live-probe legs before tagging.
+- **Gate 9** (`check:js-bundles-fresh`) needs the **npm-ci layout**: the committed `dist/` bundles are npm-shaped (an entry-relative Phosphor icon glob resolves differently under pnpm's non-hoisted layout, producing a materially larger fresh build that fails the diff). Run pre-flight under `npm ci`.
+- **Gate 17** (`npm run dogfood:status`) needs the **pnpm/bootstrapped layout** for its two live-probe legs (`empty-instantiation`, `padded-route-gutter`) to render icons correctly (gh#340), but auto-degrades to a static-only run (every other audit it aggregates has no dev-server dependency) rather than hard-failing when it detects an npm-shaped layout, so it no longer blocks a straight npm-ci roster pass. **A static-only pass is not full coverage.** Run `node scripts/dev/bootstrap-worktree.mjs && npm run dogfood:status` once under that layout, before or after the main npm-ci roster pass, to actually exercise the two live-probe legs before tagging.
 
 No other gate in the roster cares which layout produced `node_modules`.
 
 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
+## §Step 4, (Variant B, or ANY variant with uncommitted `[Unreleased]` content) Promote, bump, lockfile
 
 **4a-pre. Assemble `changes/<pr>.md` fragments (REQ-W11-06, gh#2931), BEFORE promotion.** This
-repo's PRs land a `changes/<pr>.md` fragment instead of hand-editing a CHANGELOG directly —
-`check-changelog-pr-gate.mjs`'s own PR-time gate now REQUIRES a fragment for a roster-package
+repo's PRs land a `changes/<pr>.md` fragment instead of hand-editing a CHANGELOG directly, `check-changelog-pr-gate.mjs`'s own PR-time gate now REQUIRES a fragment for a roster-package
 change and refuses the direct edit outright (gh#3123; the root `CHANGELOG.md` was already
 fragment-only in practice before that ticket). Those fragments accumulate
-unreleased until something folds them into the right CHANGELOG's `[Unreleased]` section — that's
+unreleased until something folds them into the right CHANGELOG's `[Unreleased]` section, that's
 this step, and it must run before 4a promotes `[Unreleased]` to a versioned heading, or a
 fragment folded in afterward would land under the WRONG (already-promoted) heading.
 
@@ -203,44 +202,43 @@ Routing rule (`scripts/release/assemble-changelog-fragments.mjs`'s own header, f
 there): a fragment's first line is `- <kind>: <sentence>` (kind in fix|feature|chore|docs,
 unchanged from `changelog_fragments.py`'s schema) or, this repo's own addition, `- <kind>
 (<package>): <sentence>` naming a `PACKAGE_ROSTER` (`package-paths.mjs`) entry. The
-parenthetical-package form routes to that package's own `packages/<dir>/CHANGELOG.md` — the
+parenthetical-package form routes to that package's own `packages/<dir>/CHANGELOG.md`, the
 norm for package-scoped fragments as of gh#3123, not a hypothetical; the plain form routes to
 the repo-root `CHANGELOG.md`, whose own header scopes
 it to exactly that shape of change ("tooling, CI, build scripts, cross-package work, docs").
 `kind` maps to a Keep-a-Changelog subsection: `feature`→Added, `fix`→Fixed, `chore`→Changed,
-`docs`→Docs — created under `## [Unreleased]` in that canonical order if the subsection doesn't
+`docs`→Docs, created under `## [Unreleased]` in that canonical order if the subsection doesn't
 already exist, otherwise appended to the existing one.
 
 **Deliberately NOT a pre-flight roster gate (§3.1).** Pending fragments are a NORMAL state
-between PRs, not a defect — a `--verify`-shaped freshness gate added to the pre-cut roster (which
+between PRs, not a defect, a `--verify`-shaped freshness gate added to the pre-cut roster (which
 runs before this step, in Step 3) would fail on every cut that has any recent chore/fix/feature
 PR queued, which is the common case. The `--verify` invocation above is a post-assembly
 self-check (proves the assemble actually consumed everything it found), not a standing gate;
 `gate-roster.mjs`'s count is unchanged by this ticket.
 
-**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.
+**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 (`` `<plugin-root>/skills/package-release/scripts/promote-unreleased.mjs` ``); author fresh blocks for changed-but-unlogged packages; stub the pure ride-alongs (`` `<plugin-root>/skills/package-release/scripts/insert-stub.mjs` ``). Classification recipe + shapes: [`changelog-discipline.md`](changelog-discipline.md).
+**4a. Promote** `## [Unreleased]` → `## [vX.Y.Z], YYYY-MM-DD` per package (`` `<plugin-root>/skills/package-release/scripts/promote-unreleased.mjs` ``); author fresh blocks for changed-but-unlogged packages; stub the pure ride-alongs (`` `<plugin-root>/skills/package-release/scripts/insert-stub.mjs` ``). Classification recipe + shapes: [`changelog-discipline.md`](changelog-discipline.md).
 
-`release-pack.mjs` (both `--mode cut` and `--mode from-scratch`) now rejects any `--substantive-packages`/`--stub-packages` name whose entry in `scripts/package-paths.mjs`'s `PACKAGE_ROSTER` is unknown or `lockstep: false`, at parse time, before Step 1 runs (gh#2894) — the 0.8.58 cut passed `adia-plugins` (lockstep:false) in `--substantive-packages` and let `promote-unreleased.mjs` rewrite its `[Unreleased]` header to a version that package never ships, caught only at Step 5.6 after the full pre-flight had already run.
+`release-pack.mjs` (both `--mode cut` and `--mode from-scratch`) now rejects any `--substantive-packages`/`--stub-packages` name whose entry in `scripts/package-paths.mjs`'s `PACKAGE_ROSTER` is unknown or `lockstep: false`, at parse time, before Step 1 runs (gh#2894), the 0.8.58 cut passed `adia-plugins` (lockstep:false) in `--substantive-packages` and let `promote-unreleased.mjs` rewrite its `[Unreleased]` header to a version that package never ships, caught only at Step 5.6 after the full pre-flight had already run.
 
-**4b. Bump.** PATCH vs MINOR: **MINOR is reserved for API-surface breaks only** (removed/renamed prop, attribute, slot, event, token, or tag). Visible behavior changes, re-scalings, and opt-in features stay PATCH; a CHANGELOG bullet saying "(MINOR behavior change)" is prose, not a semver directive. Unqualified "bump version" = PATCH; don't round-trip to ask. `node "<plugin-root>/skills/package-release/scripts/bump.mjs" --from X.Y.Z-1 --to X.Y.Z`. On a MINOR cut, also bump the internal `@adia-ai/*` `^ranges` separately (bump.mjs touches `"version"` fields only) — and a MINOR cut owes a MIGRATION GUIDE section ([`migration-guide-authoring.md`](migration-guide-authoring.md)).
+**4b. Bump.** PATCH vs MINOR: **MINOR is reserved for API-surface breaks only** (removed/renamed prop, attribute, slot, event, token, or tag). Visible behavior changes, re-scalings, and opt-in features stay PATCH; a CHANGELOG bullet saying "(MINOR behavior change)" is prose, not a semver directive. Unqualified "bump version" = PATCH; don't round-trip to ask. `node "<plugin-root>/skills/package-release/scripts/bump.mjs" --from X.Y.Z-1 --to X.Y.Z`. On a MINOR cut, also bump the internal `@adia-ai/*` `^ranges` separately (bump.mjs touches `"version"` fields only), and a MINOR cut owes a MIGRATION GUIDE section ([`migration-guide-authoring.md`](migration-guide-authoring.md)).
 
-**4c. Lockfile.** `npm install --package-lock-only --no-audit --no-fund` — must land in the release commit. The publish workflows open with `npm ci`, which hard-fails on a version/lockfile mismatch: a bump without the regenerated lockfile passes locally and breaks **every** publish at clean-install.
+**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.
 
-**4d.** `npm run check:lockstep` → `OK — all packages at X.Y.Z, all internal ranges at ^X.Y.0`.
+**4d.** `npm run check:lockstep` → `OK, all packages at X.Y.Z, all internal ranges at ^X.Y.0`.
 
-**4d.5. Regenerate the derived genui catalog** (gh#617): `node scripts/build/derive-genui-catalog.mjs`. Its `catalogId` embeds the lockstep version (`adia.base@X.Y.Z`), so the 4b bump just invalidated `packages/genui/adia-catalog/{base,adia-pack}.json` — regenerated pre-bump (§3.0) or not. The v0.8.26 cut skipped this and `check:genui-catalog` failed in CI one push later. Both files ride the release commit (Step 5 stages them).
+**4d.5. Regenerate the derived genui catalog** (gh#617): `node scripts/build/derive-genui-catalog.mjs`. Its `catalogId` embeds the lockstep version (`adia.base@X.Y.Z`), so the 4b bump just invalidated `packages/genui/adia-catalog/{base,adia-pack}.json`, regenerated pre-bump (§3.0) or not. The v0.8.26 cut skipped this and `check:genui-catalog` failed in CI one push later. Both files ride the release commit (Step 5 stages them).
 
-**4d.5b. Regenerate catalog tiers + re-harvest the chunk corpus if it goes stale** (gh#1361, automated — this was a recurring manual rider before): `npm run build:catalog-tiers`, then `npm run check:chunks-fresh`; if that probe goes stale, `npm run harvest:chunks`. `tier-index.json` derives from the same post-bump catalog 4d.5 just refreshed, and the chunk harvester hashes `tier-index.json` as a harvest SOURCE — regenerating tiers without re-harvesting left `check:chunks-fresh` red on the next run, needing a manual rider commit both cuts it happened live: v0.8.39 (`72417beff`) and v0.8.40/CUT-0840-B (`d9ca8b323`, "Ran `npm run build:catalog-tiers` ... That regen staled `check:chunks-fresh` ... so re-harvested"). The re-harvest is CONDITIONAL on the freshness probe, not unconditional — a tier regen that produces a byte-identical index owes no re-harvest. `tier-index.json`, `packages/gen-ui/engine/corpus/manifest.json`, and `packages/gen-ui/engine/corpus/chunks/` all ride the release commit (Step 5 stages them).
+**4d.5b. Regenerate catalog tiers + re-harvest the chunk corpus if it goes stale** (gh#1361, automated: this was a recurring manual rider before): `npm run build:catalog-tiers`, then `npm run check:chunks-fresh`; if that probe goes stale, `npm run harvest:chunks`. `tier-index.json` derives from the same post-bump catalog 4d.5 just refreshed, and the chunk harvester hashes `tier-index.json` as a harvest SOURCE, regenerating tiers without re-harvesting left `check:chunks-fresh` red on the next run, needing a manual rider commit both cuts it happened live: v0.8.39 (`72417beff`) and v0.8.40/CUT-0840-B (`d9ca8b323`, "Ran `npm run build:catalog-tiers` ... That regen staled `check:chunks-fresh` ... so re-harvested"). The re-harvest is CONDITIONAL on the freshness probe, not unconditional, a tier regen that produces a byte-identical index owes no re-harvest. `tier-index.json`, `packages/gen-ui/engine/corpus/manifest.json`, and `packages/gen-ui/engine/corpus/chunks/` all ride the release commit (Step 5 stages them).
 
-**4d.6. Regenerate the Codex plugin manifests** (gh#1888, gh#1899): `node scripts/build/codex-manifests.mjs`, then `npm run check:codex-manifests-fresh` to confirm. Both plugins' `.codex-plugin/plugin.json` embed `version` from `.claude-plugin/plugin.json`, which the 4b bump just moved — same "derived artifact carries the lockstep version" class as 4d.5's genui catalog. Gate 31 runs pre-bump in Step 3 and only proves freshness against the PREVIOUS version; nothing re-ran the generator post-bump before this line existed — the v0.8.48 release PR (#1897) shipped stale manifests as a result, caught by `check:codex-manifests-fresh` in CI and fixed by hand on the release branch. `packages/plugins/*/.codex-plugin/plugin.json` and `packages/plugins/*/skills/*/agents/openai.yaml` ride the release commit (Step 5 stages them).
+**4d.6. Regenerate the Codex plugin manifests** (gh#1888, gh#1899): `node scripts/build/codex-manifests.mjs`, then `npm run check:codex-manifests-fresh` to confirm. Both plugins' `.codex-plugin/plugin.json` embed `version` from `.claude-plugin/plugin.json`, which the 4b bump just moved, same "derived artifact carries the lockstep version" class as 4d.5's genui catalog. Gate 31 runs pre-bump in Step 3 and only proves freshness against the PREVIOUS version; nothing re-ran the generator post-bump before this line existed, the v0.8.48 release PR (#1897) shipped stale manifests as a result, caught by `check:codex-manifests-fresh` in CI and fixed by hand on the release branch. `packages/plugins/*/.codex-plugin/plugin.json` and `packages/plugins/*/skills/*/agents/openai.yaml` ride the release commit (Step 5 stages them).
 
-**4d.7. Regenerate the Hermes/Pi plugin manifests** (gh#1954): `node scripts/build/harness-manifests.mjs`, then `npm run check:harness-manifests-fresh` to confirm. Same hazard as 4d.6, same fix — both plugins' `plugin.yaml` embed `version` from `.claude-plugin/plugin.json`. Gate 32 runs pre-bump in Step 3 and only proves freshness against the PREVIOUS version; run this post-bump every cut, not just when a skill/command changed. `packages/plugins/*/plugin.yaml`, `packages/plugins/*/__init__.py`, `packages/plugins/*/hermes-mcp.yaml` (factory only), and `packages/plugins/*/prompts/*.md` ride the release commit (Step 5 stages them).
+**4d.7. Regenerate the Hermes/Pi plugin manifests** (gh#1954): `node scripts/build/harness-manifests.mjs`, then `npm run check:harness-manifests-fresh` to confirm. Same hazard as 4d.6, same fix, both plugins' `plugin.yaml` embed `version` from `.claude-plugin/plugin.json`. Gate 32 runs pre-bump in Step 3 and only proves freshness against the PREVIOUS version; run this post-bump every cut, not just when a skill/command changed. `packages/plugins/*/plugin.yaml`, `packages/plugins/*/__init__.py`, `packages/plugins/*/hermes-mcp.yaml` (factory only), and `packages/plugins/*/prompts/*.md` ride the release commit (Step 5 stages them).
 
 **4e. Release docs + team notes** (gated, not optional): review the entry
-files the release touches (root README/CHANGELOG, per-package READMEs —
-content currency is YOUR judgment; the gate only proves presence), then
+files the release touches (root README/CHANGELOG, per-package READMEs, content currency is YOUR judgment; the gate only proves presence), then
 generate the team notes and land them IN the release commit:
 
 ```bash
@@ -248,7 +246,7 @@ node scripts/release/generate-release-notes.mjs --version X.Y.Z --write   # →
 node scripts/release/check-release-docs.mjs --version X.Y.Z               # must print OK
 ```
 
-`check-release-docs` is enforced twice downstream — the
+`check-release-docs` is enforced twice downstream, the
 `release-pretag-docs-gate` Claude Code hook (adia-forge plugin) denies
 tag-creation/tag-push/publish-dispatch commands until it passes, and
 `.githooks/pre-push` blocks release-tag pushes the same way (v0.8.4
@@ -256,27 +254,27 @@ shipped tarballs with unpromoted `[Unreleased]` CHANGELOG headers because
 this class of check ran only after tagging).
 
 **4-resume. Resuming a cut that died mid-Step-4** (v0.8.10 and v0.8.29 hit
-this live). Two shapes, told apart by the lockstep versions — `release-pack.mjs`
+this live). Two shapes, told apart by the lockstep versions, `release-pack.mjs`
 checks them itself at startup (gh#765):
 
 - **Complete bump (all 13 `package.json` versions at the cut version):**
   just RE-RUN the same `release-pack.mjs` command. It detects the half-cut
   tree before the pre-flight, prints a `[resume]` banner, validates the
   hygiene gates at the CUT version (no more gate-24 false-fail at the
-  previous version), and skips promote/stub/bump in Step 4 — re-running only
+  previous version), and skips promote/stub/bump in Step 4, re-running only
   the idempotent substeps (lockfile, catalog, 4e notes, 4f coverage, 4g
   hygiene) and continuing to Step 5. The `promote-unreleased.mjs`
   "already has ## [X.Y.Z]" hard-error can no longer be reached on this path.
-  Do NOT hand-edit CHANGELOGs back to `[Unreleased]` first — the resumed run
+  Do NOT hand-edit CHANGELOGs back to `[Unreleased]` first, the resumed run
   expects the promoted state and re-proves it with the
   unpromoted-`[Unreleased]` guard.
-- **Mixed versions (some packages bumped, some not — a mid-bump abort):**
+- **Mixed versions (some packages bumped, some not, a mid-bump abort):**
   the orchestrator hard-stops listing the stragglers and will neither resume
   nor roll back. Recover by hand: restore the tree (`git status` /
   `git checkout -- <files>`, or finish the bump with `bump.mjs` directly),
   then re-run. To verify the promotion state along the way, the
   authoritative gate is `node scripts/release/check-release-docs.mjs
-  --version X.Y.Z` — it covers every lockstep package (including the nested
+  --version X.Y.Z`, it covers every lockstep package (including the nested
   `a2ui/*` and `plugins/*` paths a shallow `packages/*` glob misses) and
   fails on any leftover `[Unreleased]` content or missing `[X.Y.Z]` heading;
   it will still flag the not-yet-generated `docs/ops/releases/vX.Y.Z.md`, which
@@ -285,36 +283,35 @@ checks them itself at startup (gh#765):
 The fully manual fallback (both shapes, if the orchestrator itself is
 suspect) remains the standalone pieces the Mechanization section names, in
 this order. **Stubs complete BEFORE 4f** (the v0.8.32 resume proved the
-ordering): the bump-complete marker cannot see whether insert-stub ran — a
+ordering): the bump-complete marker cannot see whether insert-stub ran, a
 stub package's `[Unreleased]` is empty, so every guard passes with its
 `[X.Y.Z]` section entirely absent; running the coverage `--fix` before the
 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 scripts/release/assemble-changelog-fragments.mjs                                         # 4a-pre (idempotent — safe to re-run; no-op if already assembled)
+node scripts/release/assemble-changelog-fragments.mjs                                         # 4a-pre (idempotent, safe to re-run; no-op if already assembled)
 node "<plugin-root>/skills/package-release/scripts/insert-stub.mjs" \
   --version X.Y.Z --date YYYY-MM-DD --previous-version X.Y.Z-1 \
-  --substantive "<one-line>" --xref "<anchor>" --packages <missing-stubs>   # 4a-stub — FIRST, only the missing ones (hard-errors on existing sections)
+  --substantive "<one-line>" --xref "<anchor>" --packages <missing-stubs>   # 4a-stub, FIRST, only the missing ones (hard-errors on existing sections)
 node "<plugin-root>/skills/package-release/scripts/bump.mjs" --from X.Y.Z-1 --to X.Y.Z   # 4b (skip if versions already moved)
 npm install --package-lock-only --no-audit --no-fund                                          # 4c
 npm run check:lockstep                                                                        # 4d
-node scripts/build/derive-genui-catalog.mjs                                                   # 4d.5 — catalogId carries the bumped version (gh#617)
-node scripts/build/codex-manifests.mjs                                                        # 4d.6 — Codex manifest version carries the bumped version (gh#1899)
-node scripts/build/harness-manifests.mjs                                                      # 4d.7 — Hermes/Pi manifest version carries the bumped version (gh#1954)
-node scripts/release/check-release.mjs --pending-version X.Y.Z --fix                          # 4f — AFTER the stubs exist
+node scripts/build/derive-genui-catalog.mjs                                                   # 4d.5, catalogId carries the bumped version (gh#617)
+node scripts/build/codex-manifests.mjs                                                        # 4d.6, Codex manifest version carries the bumped version (gh#1899)
+node scripts/build/harness-manifests.mjs                                                      # 4d.7, Hermes/Pi manifest version carries the bumped version (gh#1954)
+node scripts/release/check-release.mjs --pending-version X.Y.Z --fix                          # 4f, AFTER the stubs exist
 node scripts/release/generate-release-notes.mjs --version X.Y.Z --write                       # 4e
 node scripts/release/check-release-docs.mjs --version X.Y.Z                                   # 4e gate
-node scripts/release/check-cut-hygiene.mjs --version X.Y.Z                                    # 4g — post-bump proof
-# then Step 5 by hand (branch, stage, commit) — Step 5.5's freshness
-# trip-wire runs on the staged set exactly as on a normal cut, don't skip it —
-# and Step 5.7 via pr-bridge.mjs
+node scripts/release/check-cut-hygiene.mjs --version X.Y.Z                                    # 4g, post-bump proof
+# then Step 5 by hand (branch, stage, commit), Step 5.5's freshness
+# trip-wire runs on the staged set exactly as on a normal cut, don't skip it, # and Step 5.7 via pr-bridge.mjs
 ```
 
-## §Step 5 — Stage and commit (on a release branch)
+## §Step 5, Stage and commit (on a release branch)
 
 The release commit lands via PR, never a direct push to `main` (repo
-policy, operator ruling 2026-07-12 — everything ships PR-first). Branch
+policy, operator ruling 2026-07-12, everything ships PR-first). Branch
 FIRST, then stage. Defensively clear the index, then stage by explicit
 allowlist (never `git add -A`; if peers may have pre-staged files,
 `git commit -o <paths>` also bypasses a polluted index):
@@ -331,9 +328,9 @@ git -C "$REPO" add package-lock.json packages/*/package.json packages/*/CHANGELO
 git -C "$REPO" diff --cached --stat | tail -3   # count must match the allowlist
 ```
 
-Commit shape: `chore(release): vX.Y.Z lockstep — <summary>` with substantive scope per package, ride-along stub list, any `Excluded — in-flight:` lines, and the pasted gate summary.
+Commit shape: `chore(release): vX.Y.Z lockstep, <summary>` with substantive scope per package, ride-along stub list, any `Excluded, in-flight:` lines, and the pasted gate summary.
 
-## §Step 5.5 — Pre-commit freshness trip-wire
+## §Step 5.5, Pre-commit freshness trip-wire
 
 After `git add`, before `git commit`, re-run the three freshness gates against staged state:
 
@@ -341,23 +338,22 @@ After `git add`, before `git commit`, re-run the three freshness gates against s
 node scripts/build/components.mjs --verify && npm run check:chunks-fresh && npm run check:embeddings-fresh
 ```
 
-Drift here means a regen output was left out of the allowlist — stage it and re-run. <2s now vs ~5min of tag-move recovery after CI catches it. Do not proceed to tag with drift.
+Drift here means a regen output was left out of the allowlist, stage it and re-run. <2s now vs ~5min of tag-move recovery after CI catches it. Do not proceed to tag with drift.
 
-## §Step 5.6 — Unstaged-tracked-files guard (`release-pack.mjs`, gh#2473)
+## §Step 5.6, Unstaged-tracked-files guard (`release-pack.mjs`, gh#2473)
 
 `release-pack.mjs`'s Step 5 mechanizes this: right after its own `git add`
 (the allowlist above, as automated), it runs `git status --porcelain` and
-fails the cut if any tracked file is still modified-in-the-worktree —
-proof the allowlist covered everything bump.mjs / cut-hygiene touched this
+fails the cut if any tracked file is still modified-in-the-worktree, proof the allowlist covered everything bump.mjs / cut-hygiene touched this
 cut, not just what §Step 5.5's three named freshness gates happen to check.
 The allowlist itself went stale five times (gh#1198, gh#1899, gh#1954,
-gh#2473, gh#3342 — most recently `icons-cdn.js`'s PACKAGE_VERSION pin), so
-this guard is generic rather than another named file — it stays the
+gh#2473, gh#3342, most recently `icons-cdn.js`'s PACKAGE_VERSION pin), so
+this guard is generic rather than another named file, it stays the
 fallback for anything below. **The PINNED_REFS-covered subset of the
 allowlist can no longer drift this way at all** (gh#3361): `release-pack.mjs`
 now derives those specific entries straight from `bump.mjs`'s own
 `PINNED_REFS`/`REPO_PINNED_REFS` tables (`pinnedRefFiles()`) instead of
-hand-listing the same paths a second time — a new pinned file in `bump.mjs`
+hand-listing the same paths a second time, a new pinned file in `bump.mjs`
 is automatically a new allowlist entry, no second edit needed. Everything
 NOT PINNED_REFS-covered (roster `package.json`/`CHANGELOG.md`, and the Step
 4d.5-4d.8 derived catalog/manifest/dist outputs) is still hand-listed and
@@ -365,10 +361,10 @@ still relies on this guard as the safety net. A manual cut should run the
 equivalent check by hand: `git status --porcelain` after staging must be
 empty of `M`/`D` lines.
 
-## §Step 5.7 — Release PR: push the branch, merge, re-baseline
+## §Step 5.7, Release PR: push the branch, merge, re-baseline
 
 The release commit reaches `main` through the standard PR flow. Mechanized
-form (preferred — `pr-bridge.mjs` pushes, opens the PR, polls, merges ONLY
+form (preferred, `pr-bridge.mjs` pushes, opens the PR, polls, merges ONLY
 when every non-fail-soft check is green AND zero review threads are
 unresolved AND no review requests changes; any other state stops with the
 evidence, never force-merges):
@@ -389,78 +385,77 @@ git -C "$REPO" checkout main && git -C "$REPO" pull
 ```
 
 Post-merge fixes land as follow-up commits to the SAME release PR (or a
-second PR merged before tagging) — the tag point below is always `main`'s
+second PR merged before tagging): the tag point below is always `main`'s
 post-merge HEAD, so anything merged before tagging ships in the tarball.
 If unrelated PRs merged between yours and the tag step, that is fine: tag
 at HEAD is the invariant, and the window closes at the tag.
 
 ## §Single authorization + evidence log (operator ruling 2026-07-17)
 
-The operator's initiating instruction covers the whole cycle — no per-step re-confirmation (this replaced the 4-checkpoint sign-off model after the v0.8.5 cut spent ~40 minutes on approval relays while every real protection fired deterministically). The evidence blocks the checkpoints used to gate on still PRINT, as a running log — the audit trail is unchanged; only the waiting is gone:
+The operator's initiating instruction covers the whole cycle, no per-step re-confirmation (this replaced the 4-checkpoint sign-off model after the v0.8.5 cut spent ~40 minutes on approval relays while every real protection fired deterministically). The evidence blocks the checkpoints used to gate on still PRINT, as a running log: the audit trail is unchanged; only the waiting is gone:
 
 | Evidence logged before | Content | Why it's still printed |
 | --- | --- | --- |
 | 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 |
+| 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 |
 
-`release-pack.mjs --go` auto-confirms all of these; the granular `--yes` / `--push` / `--publish` flags remain for cautious manual runs and prompt interactively when absent. **Two rules no flag or instruction wording skips:** an F-N1 *error* hard-stops before the push step exists at all, and a cosmetic F-N1 *warn* refuses auto-confirmation at the push boundary (with Step 4f mechanized, a warn appearing at Step 7 means something novel — investigate, don't loop enrichment PRs).
+`release-pack.mjs --go` auto-confirms all of these; the granular `--yes` / `--push` / `--publish` flags remain for cautious manual runs and prompt interactively when absent. **Two rules no flag or instruction wording skips:** an F-N1 *error* hard-stops before the push step exists at all, and a cosmetic F-N1 *warn* refuses auto-confirmation at the push boundary (with Step 4f mechanized, a warn appearing at Step 7 means something novel, investigate, don't loop enrichment PRs).
 
-## §Step 4f — Pre-tag coverage `--fix` (the retag-loop killer)
+## §Step 4f, Pre-tag coverage `--fix` (the retag-loop killer)
 
-After the bump + lockfile, run the AUTHORITATIVE F-N1 matcher against the working tree — same code, same `changelogMentions` patterns, every roster package — and let it append verified Maintenance bullets for any changed-but-unmentioned directory:
+After the bump + lockfile, run the AUTHORITATIVE F-N1 matcher against the working tree, same code, same `changelogMentions` patterns, every roster package, and let it append verified Maintenance bullets for any changed-but-unmentioned directory:
 
 ```bash
 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. (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.)
+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
+## §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):
+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 "<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
+## §Step 7, F-N1 release trip-wire
 
 ```bash
 node scripts/release/check-release.mjs --all-pending
 ```
 
-Per-package tags must be `✓ clean`; the umbrella-tag error is expected noise. **Expected outcome: clean — Step 4f already ran the same matcher pre-PR.** A warn here means something changed between 4f and the tag (an interleaved merge, a 4f skip) — investigate the cause, then recover via [`changelog-discipline.md`](changelog-discipline.md) §F-N1: fix the entry, land it as a follow-up commit through the PR flow (`--amend` is not possible — the release commit is already merged), delete + re-create the tags at the new post-merge SHA, re-run.
+Per-package tags must be `✓ clean`; the umbrella-tag error is expected noise. **Expected outcome: clean, Step 4f already ran the same matcher pre-PR.** A warn here means something changed between 4f and the tag (an interleaved merge, a 4f skip), investigate the cause, then recover via [`changelog-discipline.md`](changelog-discipline.md) §F-N1: fix the entry, land it as a follow-up commit through the PR flow (`--amend` is not possible: the release commit is already merged), delete + re-create the tags at the new post-merge SHA, re-run.
 
-## §Step 8 — Push tags
+## §Step 8, Push tags
 
-`main` is already on the remote (the release PR merged in Step 5.7) —
-only the tags push here. Log the Step 7 F-N1 results + the tag list
+`main` is already on the remote (the release PR merged in Step 5.7), only the tags push here. Log the Step 7 F-N1 results + the tag list
 (evidence table above) + confirm `git rev-list --count origin/main..HEAD`
-is 0 (a non-zero count means local commits bypassed the PR flow — stop
+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
+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
 PKGS=$(node -e "import('<plugin-root>/skills/package-release/scripts/package-paths.mjs')
   .then(m => console.log(m.PACKAGE_ROSTER.filter(p => p.lockstep !== false).map(p => p.name).join(' ')))")
-echo "$PKGS"                             # log it — this IS the tag list evidence
+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
+  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
+## §Step 9, Publish
 
-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:
+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 "<plugin-root>/skills/package-release/scripts/dispatch-publish.mjs" \
@@ -470,7 +465,7 @@ node "<plugin-root>/skills/package-release/scripts/dispatch-publish.mjs" \
 Wait for the workflows to settle, then verify against the **registry**, never the workflow's green check:
 
 ```bash
-# The name list comes from PACKAGE_ROSTER, never a hand-typed loop — this loop
+# 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
@@ -487,18 +482,17 @@ npm view @adia-ai/web-components dist-tags.latest   # must equal X.Y.Z
 Zero workflows fired after a tag push → [`recovery-paths.md`](recovery-paths.md) §Scenario 7.
 
 **npm's async staged-publish path (gh#3342):** a large tarball can take up to
-~25 minutes to become visible on `npm view` after npm accepts it —
-`release-pack.mjs`'s own Step 9 poll accounts for this (`REGISTRY_POLL_MINUTES`,
+~25 minutes to become visible on `npm view` after npm accepts it, `release-pack.mjs`'s own Step 9 poll accounts for this (`REGISTRY_POLL_MINUTES`,
 default 30, up from the 10-minute window the v0.8.59 cut exceeded with every
 publish run green). A re-dispatch attempted while a package is in that state
 fails its `npm publish` step with `npm error code E409` ("Cannot publish over
-previously staged version") — that is the staged-not-lost signal, never a real
+previously staged version"): that is the staged-not-lost signal, never a real
 failure; release-pack's Step 9 detects it (the failing run's own log) and polls
 longer instead of hard-failing. See [`recovery-paths.md`](recovery-paths.md)
 §Scenario 9 for manual recovery, including resuming at Step 10 only
 (`--from-step10`) without re-running the pre-flight or re-tagging.
 
-## §Step 10 — GH releases + site deploy dispatch
+## §Step 10, GH releases + site deploy dispatch
 
 ```bash
 for pkg in $(node -e '
@@ -515,7 +509,7 @@ gh workflow run "Deploy site (ui-kit.exe.xyz)" --repo adiahealth/gen-ui-kit --re
 
 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).
+- `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:
 
   ```bash
@@ -523,7 +517,7 @@ Deploy discipline (the release tenant of the demo-site host; VM/service ops belo
   curl -s https://ui-kit.exe.xyz/<this-cycle's-content-file> | grep -q "<unique string>" && echo OK
   ```
 
-- Any docs **route** cited to the operator or in notes must exist in `site/sitemap.json` (`grep '"path":'`) — a plausible-looking route that isn't in the sitemap renders blank.
+- Any docs **route** cited to the operator or in notes must exist in `site/sitemap.json` (`grep '"path":'`), a plausible-looking route that isn't in the sitemap renders blank.
 
 **Milestone close (ADR-0103, gh#2729, dated addendum 2026-09-01).** Every
 lockstep cut has an open GitHub Milestone named `vX.Y.Z` (one per cut,
@@ -537,7 +531,7 @@ gh api -X PATCH "repos/adiahealth/gen-ui-kit/milestones/$number" -f state=closed
 ```
 
 Any issue still open in that milestone at close time either ships anyway
-(re-tag it into the milestone that actually shipped it — never leave an
+(re-tag it into the milestone that actually shipped it, never leave an
 already-shipped issue's milestone wrong) or slips to the next milestone
 (re-tag now, don't leave the closed milestone showing open issues). Create
 the NEXT cut's milestone here too, so scheduling work for it doesn't wait on
@@ -549,11 +543,11 @@ gh api repos/adiahealth/gen-ui-kit/milestones -f title="vNEXT.Y.Z" -f state=open
 
 Any Step-2 stashes: `git stash pop`; flag conflicts to the operator.
 
-## §Step 11 — Author release notes (default)
+## §Step 11, Author release notes (default)
 
-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".
+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".
 
-## §Step 12 — Restore the dev layout
+## §Step 12, Restore the dev layout
 
 The cut runs under `npm ci` (Step 1's layout check, gate 9), and that leaves
 `node_modules` npm-shaped. The dev server refuses to start on that tree:
@@ -572,18 +566,17 @@ gitignored). Live cost of skipping this: the v0.8.55 cut (2026-08-28) left the
 operator's primary checkout unable to run `npm run dev` until the layout was
 restored by hand.
 
-## §The 0.8.38 cut (the clean-world cut — delete this section after it lands)
+## §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
+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.
+   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
@@ -591,37 +584,37 @@ before Step 1:
    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
+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
+   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
+**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
+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
+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.
+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.
 
-## §Plugin cache — content between cuts is invisible until the next bump
+## §Plugin cache, content between cuts is invisible until the next bump
 
-The installed Claude Code plugin cache is keyed by the version string in `.claude-plugin/plugin.json` — `/reload-plugins` only refreshes when that string CHANGES. Lockstep forbids a solo plugin bump, so any skill/agent/doc content merged to `main` between cuts does NOT reach the installed plugin until the next lockstep cut (or a deliberate manual `rsync` of the plugin dir over `~/.claude/plugins/cache/<marketplace>/<plugin>/<version>/`). Consequences:
+The installed Claude Code plugin cache is keyed by the version string in `.claude-plugin/plugin.json`, `/reload-plugins` only refreshes when that string CHANGES. Lockstep forbids a solo plugin bump, so any skill/agent/doc content merged to `main` between cuts does NOT reach the installed plugin until the next lockstep cut (or a deliberate manual `rsync` of the plugin dir over `~/.claude/plugins/cache/<marketplace>/<plugin>/<version>/`). Consequences:
 
-- Shipping plugin-content changes mid-cycle is fine — just know they're repo-only until the next cut; don't report them as "live in the harness".
+- Shipping plugin-content changes mid-cycle is fine, just know they're repo-only until the next cut; don't report them as "live in the harness".
 - The v0.8.5 case (PR #304): a full release-process rewrite merged with no bump, and the installed plugin silently kept executing the RETIRED procedure until a manual cache sync. If the merged content changes operational behavior an active session depends on, do the manual sync immediately and say so.
-- At cut time nothing extra is needed — the lockstep bump itself is what invalidates the cache.
+- At cut time nothing extra is needed: the lockstep bump itself is what invalidates the cache.
 
 ## §When to abort
 
-Stop and surface to the operator when: a gate fails outside the documented recoveries; F-N1 reports >1 warn per package tag or any non-umbrella error; the release-commit candidate fails `check:demo-shells` / `check:lockstep` / `check:embeddings-fresh` (→ [`recovery-paths.md`](recovery-paths.md) §Scenario 4); uncommitted files stay unclassifiable after diffing; or a publish workflow fails E404/E401 (npm-token rotation — operator-owned).
+Stop and surface to the operator when: a gate fails outside the documented recoveries; F-N1 reports >1 warn per package tag or any non-umbrella error; the release-commit candidate fails `check:demo-shells` / `check:lockstep` / `check:embeddings-fresh` (→ [`recovery-paths.md`](recovery-paths.md) §Scenario 4); uncommitted files stay unclassifiable after diffing; or a publish workflow fails E404/E401 (npm-token rotation, operator-owned).