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

package/skills/package-release/references/gates-catalog.md

@@ -1,40 +1,39 @@
-# `gates-catalog.md` — pre-flight gate roster + failure → recovery map
+# `gates-catalog.md`, pre-flight gate roster + failure → recovery map
 
 `<plugin-root>` below is `$CLAUDE_PLUGIN_ROOT` in Claude Code; the plugin's installed directory
 in Codex.
 
 > Load for a verify-only run or on any gate failure during a cut. Maps every
 > release-flow gate × what it checks × typical failure × recovery. Gates are
-> grouped by **failure category** — how the operator routes when one goes red —
-> not by alphabetical namespace. Cited scripts live in the target monorepo's
+> grouped by **failure category**, how the operator routes when one goes red, > not by alphabetical namespace. Cited scripts live in the target monorepo's
 > `package.json` (`check:*` / `verify:*` / `smoke:*` / `test:*`).
 
 Row layout per gate: **What** · **Typical failure** · **Recovery**.
 
 ---
 
-## §Category 1 — Release identity (hard-fail any cut)
+## §Category 1, Release identity (hard-fail any cut)
 
 ### `npm run check:lockstep`
 
-- **What:** all 10 lockstep `@adia-ai/*` packages declare the same `version` (the class-B `adia-plugins` package is excluded — `lockstep: false`, `scripts/package-paths.mjs`); internal `@adia-ai/*` dep ranges match policy (`^X.Y.0` during PATCH cycles, bumped at MINOR).
+- **What:** all 10 lockstep `@adia-ai/*` packages declare the same `version` (the class-B `adia-plugins` package is excluded, `lockstep: false`, `scripts/package-paths.mjs`); internal `@adia-ai/*` dep ranges match policy (`^X.Y.0` during PATCH cycles, bumped at MINOR).
 - **Typical failure:** one package forgot to bump; a peer edited an internal range mid-PATCH; a `^0.0.x` range slipped in.
 - **Recovery:** version drift → `` `<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.
+- **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)
 
 - **What:** for every unpushed tag, verifies CHANGELOG coverage of the diff between this tag and the package's previous tag.
-- **Cosmetic failure:** "diff `packages/<pkg>/components/` touched but CHANGELOG `[X.Y.Z]` doesn't mention 'components'" — the entry names the component (`table-ui`) but not the literal path keyword. Regex miss, change IS documented.
-- **Real failure:** a touched directory has NO matching CHANGELOG entry at all — the cycle missed documenting a change.
-- **Recovery:** cosmetic → add the path keyword to a relevant entry (`table.yaml` → `components/table/table.yaml`); real → author the missing entry. Either way: land it as a new commit through the PR flow (the release commit is already merged — `--amend` is not possible post-invariant-3), delete + re-create the tags at the new post-merge SHA, re-run. Full discipline: [`changelog-discipline.md`](changelog-discipline.md) §F-N1 enrichment.
-- The umbrella tag `vX.Y.Z` classifies **`info`** (since 2026-07-19 — it used to score `error`, which false-stopped release-pack's Step 7 on every cut); only per-package findings need action.
+- **Cosmetic failure:** "diff `packages/<pkg>/components/` touched but CHANGELOG `[X.Y.Z]` doesn't mention 'components'": the entry names the component (`table-ui`) but not the literal path keyword. Regex miss, change IS documented.
+- **Real failure:** a touched directory has NO matching CHANGELOG entry at all, the cycle missed documenting a change.
+- **Recovery:** cosmetic → add the path keyword to a relevant entry (`table.yaml` → `components/table/table.yaml`); real → author the missing entry. Either way: land it as a new commit through the PR flow (the release commit is already merged, `--amend` is not possible post-invariant-3), delete + re-create the tags at the new post-merge SHA, re-run. Full discipline: [`changelog-discipline.md`](changelog-discipline.md) §F-N1 enrichment.
+- The umbrella tag `vX.Y.Z` classifies **`info`** (since 2026-07-19, it used to score `error`, which false-stopped release-pack's Step 7 on every cut); only per-package findings need action.
 
-(The former `check:changelog-coverage` gate was deleted 2026-07-19 — its drifted 9-package matcher could report "clean" where the authoritative gate fails. Pre-tag coverage is `check-release.mjs --pending-version X.Y.Z [--fix]`, Step 4f.)
+(The former `check:changelog-coverage` gate was deleted 2026-07-19, its drifted 9-package matcher could report "clean" where the authoritative gate fails. Pre-tag coverage is `check-release.mjs --pending-version X.Y.Z [--fix]`, Step 4f.)
 
 ---
 
-## §Category 2 — Generated-file coherence (hard-fail any cut)
+## §Category 2, Generated-file coherence (hard-fail any cut)
 
 ### `node scripts/build/components.mjs --verify`
 
@@ -58,15 +57,15 @@ Row layout per gate: **What** · **Typical failure** · **Recovery**.
 
 ---
 
-## §Category 3 — Component / primitive structural drift
+## §Category 3, Component / primitive structural drift
 
 ### `npm run check:demo-shells`
 
 - **What:** every component demo `.html` imports all primitives named in its yaml `composes:` list.
 - **Typical failure:** a yaml gained a `composes:` entry but the demo shell didn't get the matching `<script>` import.
-- **Recovery:** add `<script type="module" src="../<tag>/<tag>.js">` to the demo shell. **Release-blocking: HIGH** — a commit failing this gate ships broken demo pages in its tarball. If the fix already landed later but entangled with `[Unreleased]` work → [`recovery-paths.md`](recovery-paths.md) §Scenario 4.
+- **Recovery:** add `<script type="module" src="../<tag>/<tag>.js">` to the demo shell. **Release-blocking: HIGH**, a commit failing this gate ships broken demo pages in its tarball. If the fix already landed later but entangled with `[Unreleased]` work → [`recovery-paths.md`](recovery-paths.md) §Scenario 4.
 
-Smaller siblings in this category (same recovery shape — fix the declaration or regenerate the registry):
+Smaller siblings in this category (same recovery shape, fix the declaration or regenerate the registry):
 
 | Gate | What |
 | --- | --- |
@@ -79,7 +78,7 @@ Smaller siblings in this category (same recovery shape — fix the declaration o
 
 ---
 
-## §Category 4 — CSS spec compatibility
+## §Category 4, CSS spec compatibility
 
 ### `npm run check:lightningcss-build`
 
@@ -95,18 +94,18 @@ Also: `check:no-self-import-css` (no transitively self-importing barrel) · `che
 
 ---
 
-## §Category 5 — Browser safety / module hygiene
+## §Category 5, Browser safety / module hygiene
 
 ### `npm run check:browser-safe`
 
 - **What:** no top-level `import 'node:*'` in browser-reachable modules (`packages/gen-ui/a2ui/{compose,retrieval,validator}`, `web-components/`, `web-modules/`, `apps/*/app/*.contents.js`).
 - **Recovery:** dual-mode pattern (`IS_NODE` + dynamic `await import(/* @vite-ignore */ 'node:*')` + `import.meta.glob` browser branch); canonical impl: `packages/gen-ui/a2ui/retrieval/component-catalog.js`.
 
-Siblings: `check:absolute-imports` (no leading-`/` imports — rewrite relative) · `check:template-interp` (template `${expr}` contract) · `check:yaml-events` (yaml `events:` match runtime `dispatchEvent` calls) · `check:yaml-impl-coverage` (every yaml prop implemented in the JS class).
+Siblings: `check:absolute-imports` (no leading-`/` imports, rewrite relative) · `check:template-interp` (template `${expr}` contract) · `check:yaml-events` (yaml `events:` match runtime `dispatchEvent` calls) · `check:yaml-impl-coverage` (every yaml prop implemented in the JS class).
 
 ---
 
-## §Category 6 — Visual / structural integrity
+## §Category 6, Visual / structural integrity
 
 | Gate | What |
 | --- | --- |
@@ -116,11 +115,11 @@ Siblings: `check:absolute-imports` (no leading-`/` imports — rewrite relative)
 | `audit:native-primitive-leak` | native `<button>`/`<input>`/… where a `*-ui` equivalent exists; criticals must be replaced or annotated `data-native-ok="<reason>"` |
 | `audit:shell-composition` | admin-shell compositions missing canonical parts (statusbar, `[data-spacer]`/`[data-actions]`, …); escape hatch `data-shell-opt-out="<reason>"` |
 
-The two `audit:*` probes are soft-fail pre-cut (exit-1 only on criticals); findings get folded into release notes if non-zero. Recovery for both is manual — slot/attr semantics need a human eyeball, never auto-fix.
+The two `audit:*` probes are soft-fail pre-cut (exit-1 only on criticals); findings get folded into release notes if non-zero. Recovery for both is manual, slot/attr semantics need a human eyeball, never auto-fix.
 
 ---
 
-## §Category 7 — Corpus / bundle freshness
+## §Category 7, Corpus / bundle freshness
 
 ### `npm run verify:corpus`
 
@@ -129,8 +128,8 @@ The two `audit:*` probes are soft-fail pre-cut (exit-1 only on criticals); findi
 
 ### `npm run check:catalog-tiers`
 
-- **What:** `packages/gen-ui/a2ui/catalog/tier-index.json` derives cleanly from the committed catalog + the hand-authored `tiers/l*-*.json` sources (L0–L4 membership, composability law). It ships inside `@adia-ai/a2ui`, so a stale index is a publish defect. ADR-0069's gate split moved its PR-blocking freshness onto the `derived-resync` (push:main) job; the pre-cut roster re-asserts it because gate `check:chunks-fresh` cannot — the harvester hashes `tier-index.json` as a harvest *source*, so a stale-but-harvested index keeps that gate green (gh#1494).
-- **Recovery:** `npm run build:catalog-tiers`; if that regen stales `check:chunks-fresh`, `npm run harvest:chunks` (the conditional pair Step 4d.5b runs post-bump — a byte-identical tier regen owes no re-harvest). Stage `tier-index.json` + any corpus outputs.
+- **What:** `packages/gen-ui/a2ui/catalog/tier-index.json` derives cleanly from the committed catalog + the hand-authored `tiers/l*-*.json` sources (L0–L4 membership, composability law). It ships inside `@adia-ai/a2ui`, so a stale index is a publish defect. ADR-0069's gate split moved its PR-blocking freshness onto the `derived-resync` (push:main) job; the pre-cut roster re-asserts it because gate `check:chunks-fresh` cannot, the harvester hashes `tier-index.json` as a harvest *source*, so a stale-but-harvested index keeps that gate green (gh#1494).
+- **Recovery:** `npm run build:catalog-tiers`; if that regen stales `check:chunks-fresh`, `npm run harvest:chunks` (the conditional pair Step 4d.5b runs post-bump, a byte-identical tier regen owes no re-harvest). Stage `tier-index.json` + any corpus outputs.
 
 ### `npm run check:chunks-fresh`
 
@@ -141,13 +140,13 @@ 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.
+- **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`
 
 - **What:** the `dist/` CDN bundles (`web-components.min.{css,js}`, `everything.min.js`, per-shell `*.min.js`, `icons-manifest.js`) match source. Stale bundles mean jsdelivr/unpkg serve yesterday's build. **Blocking in CI** (2026-06-08).
-- **Recovery:** `npm run build -w @adia-ai/llm` **FIRST** (its `index.js` is a gitignored tsc artifact `build:bundle-js` resolves — a fresh worktree can't bundle without it), then `npm run build:bundles` (or `build:bundle-css` / `build:bundle-js` individually). Stage both `dist/` trees.
-- **Semantic content checks — mechanized 2026-07-19** (formerly manual spot-checks; the v0.6.29–31 cycles shipped a shells-only `everything.min.js` that hard-crashed CDN consumers): `bundle-js.mjs` now enforces, on every build AND `--verify` run, that (1) `everything.js` still imports `@adia-ai/web-components`, (2) `everything.min.js` carries ≥100 distinct `-ui` tags, and (3) `icons-manifest.js` exists populated in BOTH dist trees. A fresh-but-semantically-wrong bundle fails the gate itself — no separate manual step remains.
+- **Recovery:** `npm run build -w @adia-ai/llm` **FIRST** (its `index.js` is a gitignored tsc artifact `build:bundle-js` resolves, a fresh worktree can't bundle without it), then `npm run build:bundles` (or `build:bundle-css` / `build:bundle-js` individually). Stage both `dist/` trees.
+- **Semantic content checks, mechanized 2026-07-19** (formerly manual spot-checks; the v0.6.29–31 cycles shipped a shells-only `everything.min.js` that hard-crashed CDN consumers): `bundle-js.mjs` now enforces, on every build AND `--verify` run, that (1) `everything.js` still imports `@adia-ai/web-components`, (2) `everything.min.js` carries ≥100 distinct `-ui` tags, and (3) `icons-manifest.js` exists populated in BOTH dist trees. A fresh-but-semantically-wrong bundle fails the gate itself, no separate manual step remains.
 
 ### `npm run audit:chunk-reconcile`
 
@@ -155,16 +154,16 @@ The two `audit:*` probes are soft-fail pre-cut (exit-1 only on criticals); findi
 
 ---
 
-## §Category 8 — Tests + types + evals
+## §Category 8, Tests + types + evals
 
 ### `npm run test:unit`
 
 - **What:** the vitest suite (~1000+ tests).
-- **Stale-test failure:** the test asserts a behavior a peer deliberately changed (CHANGELOG-documented) without updating the assertion. Tell it apart by reading assertion vs CHANGELOG vs source: if the code matches the CHANGELOG's described behavior, the test is stale — update the assertion (see [`recovery-paths.md`](recovery-paths.md) §Scenario 5). Real regression → fix the regression.
-- **Parallel-contention flake:** heavy web-modules composite suites can fail under full parallelism on a loaded machine (`signals: drain loop exceeded 100 iterations`). Load-dependent, not a code defect. Sequential is the source of truth, and **the roster gate now runs it directly** (`npm run test:unit:serial` = `vitest run --no-file-parallelism`, gate 4 since 2026-07-19) — a parallel `test:unit` flake outside the roster still isn't a blocker, and don't raise the drain guard.
-- **Same-host contention timeout (gh#2195):** gate 4 running solo (Phase 1, see the execution-model note above) isolates it from every OTHER pre-flight gate, but not from unrelated concurrent load on the same shared, multi-tenant host — another agent's build, a peer's own `npm run check`. gh#2195's diagnosis found this surfaces as a genuine 45s per-test timeout on a DIFFERENT single file each run, with no repeat culprit (the contention signature, not an order-dependent leak) — and found no separate "release pre-flight runner" with its own core count exists to recalibrate `worker-cap.mjs` against; it's the same operator/agent host either way. `release-pack.mjs`'s `runSoloGateWithRetry()` now retries gate 4 exactly once, scoped to only the file(s) it named as failed, when the failure output has a parseable `FAIL <file>` list — a file that fails once and passes clean on that immediate re-run was contention, not a regression; a file that fails twice is treated as a real one and the pre-flight still aborts. No other gate, and no OTHER invocation of `test:unit:serial` (CI, local dev, `npm run check`), gets this retry.
-- **Exit 143 (SIGTERM):** the vitest process was KILLED (resource pressure / a stray terminator), not a test failure — re-run the gate directly (`npx vitest run --no-file-parallelism`) before diagnosing anything; a clean re-run means transient, proceed (v0.8.34 handoff hit this).
-- **First-time-at-cut failures are REAL (v0.8.34):** this serial suite runs tests PR CI never does — `exit-gate.corpus` (dialect-catalog conformance over real harvested chunks) surfaces yaml-schema drift (e.g. an array prop missing `items.type`, the command/combobox `DynamicStringList` mis-map) only HERE, potentially weeks after the yaml edit merged green. Treat such a failure as a genuine latent defect to root-cause at the yaml SoT, never as release-blocking noise. (Structural fix — promoting the corpus batch into PR CI — tracked as a follow-up.)
+- **Stale-test failure:** the test asserts a behavior a peer deliberately changed (CHANGELOG-documented) without updating the assertion. Tell it apart by reading assertion vs CHANGELOG vs source: if the code matches the CHANGELOG's described behavior, the test is stale, update the assertion (see [`recovery-paths.md`](recovery-paths.md) §Scenario 5). Real regression → fix the regression.
+- **Parallel-contention flake:** heavy web-modules composite suites can fail under full parallelism on a loaded machine (`signals: drain loop exceeded 100 iterations`). Load-dependent, not a code defect. Sequential is the source of truth, and **the roster gate now runs it directly** (`npm run test:unit:serial` = `vitest run --no-file-parallelism`, gate 4 since 2026-07-19), a parallel `test:unit` flake outside the roster still isn't a blocker, and don't raise the drain guard.
+- **Same-host contention timeout (gh#2195):** gate 4 running solo (Phase 1, see the execution-model note above) isolates it from every OTHER pre-flight gate, but not from unrelated concurrent load on the same shared, multi-tenant host, another agent's build, a peer's own `npm run check`. gh#2195's diagnosis found this surfaces as a genuine 45s per-test timeout on a DIFFERENT single file each run, with no repeat culprit (the contention signature, not an order-dependent leak), and found no separate "release pre-flight runner" with its own core count exists to recalibrate `worker-cap.mjs` against; it's the same operator/agent host either way. `release-pack.mjs`'s `runSoloGateWithRetry()` now retries gate 4 exactly once, scoped to only the file(s) it named as failed, when the failure output has a parseable `FAIL <file>` list, a file that fails once and passes clean on that immediate re-run was contention, not a regression; a file that fails twice is treated as a real one and the pre-flight still aborts. No other gate, and no OTHER invocation of `test:unit:serial` (CI, local dev, `npm run check`), gets this retry.
+- **Exit 143 (SIGTERM):** the vitest process was KILLED (resource pressure / a stray terminator), not a test failure, re-run the gate directly (`npx vitest run --no-file-parallelism`) before diagnosing anything; a clean re-run means transient, proceed (v0.8.34 handoff hit this).
+- **First-time-at-cut failures are REAL (v0.8.34):** this serial suite runs tests PR CI never does, `exit-gate.corpus` (dialect-catalog conformance over real harvested chunks) surfaces yaml-schema drift (e.g. an array prop missing `items.type`, the command/combobox `DynamicStringList` mis-map) only HERE, potentially weeks after the yaml edit merged green. Treat such a failure as a genuine latent defect to root-cause at the yaml SoT, never as release-blocking noise. (Structural fix, promoting the corpus batch into PR CI, tracked as a follow-up.)
 
 ### `npm run eval:diff -- --engine zettel`
 
@@ -173,36 +172,36 @@ The two `audit:*` probes are soft-fail pre-cut (exit-1 only on criticals); findi
   - **Free-form**: cov ≥ 90%, avg ≥ 83, F1 ≥ 55
   - **Monolithic**: cov = 100%, avg ≥ 95
   - **Dogfood**: 20/20, avg ≥ 95
-- **Recovery:** retrieval/corpus regression — routes to the A2UI-pipeline skill.
+- **Recovery:** retrieval/corpus regression, routes to the A2UI-pipeline skill.
 
 Siblings: `typecheck` (`tsc --noEmit`) · `smoke:engines` (gen-UI engines + retrieval probes) · `smoke:register-engine` (11/11) · `test:a2ui` (22/22, +1 skipped OK).
 
 ---
 
-## §Category 9 — Misc release safety
+## §Category 9, Misc release safety
 
 ### `node scripts/release/check-cut-hygiene.mjs --version X.Y.Z`
 
-- **What:** roster gate 18 (wired 2026-07-19; release-pack fills `--version` — the roster's one `versionArg` entry). The objective half of the v0.7.13-retro hygiene checker: published README CDN pins / "Current version" claims must not sit below the cut's minor (`doc-currency`, error-level); merged release branches + extra worktrees print as `limbo` warns (advisory without `--strict`). The judgment half of §4e — content *currency* of what the READMEs say — stays yours.
+- **What:** roster gate 18 (wired 2026-07-19; release-pack fills `--version`, the roster's one `versionArg` entry). The objective half of the v0.7.13-retro hygiene checker: published README CDN pins / "Current version" claims must not sit below the cut's minor (`doc-currency`, error-level); merged release branches + extra worktrees print as `limbo` warns (advisory without `--strict`). The judgment half of §4e, content *currency* of what the READMEs say, stays yours.
 - **Recovery:** update the stale README pin/claim, stage it into the release commit. A `limbo` warn routes to branch/worktree cleanup, never blocks the cut.
 
 ### `npm run dogfood:status`
 
 - **What:** aggregator over the component dogfood audits; classifies findings P0–P3 and regenerates the tracker at `qa/findings/dogfood-tracker.md`. Exit-1 when P0+P1 > 0; P2/P3 are advisory.
 - **Pre-cut policy: must pass before tag.** Any P0/P1 means a paid-down bug class was re-introduced; open the tracker, apply the canonical fix template at the cited file:line, re-run. ~5s.
-- **Layout-aware since gh#1359.** Two of the aggregated audits (`empty-instantiation`, `padded-route-gutter`) render against a throwaway vite dev server and need the pnpm/bootstrapped layout to trust rendered icons (gh#340). Under an npm-shaped `node_modules` (or the explicit `--static-only` flag) the run auto-degrades — skips those two legs, prints a loud non-fatal notice, and still runs every other (static, layout-agnostic) audit. A green static-only result is **not** full coverage: run `node scripts/dev/bootstrap-worktree.mjs && npm run dogfood:status` once under the pnpm layout too before a cut ships. Only a missing `node_modules` entirely still hard-exits.
+- **Layout-aware since gh#1359.** Two of the aggregated audits (`empty-instantiation`, `padded-route-gutter`) render against a throwaway vite dev server and need the pnpm/bootstrapped layout to trust rendered icons (gh#340). Under an npm-shaped `node_modules` (or the explicit `--static-only` flag) the run auto-degrades, skips those two legs, prints a loud non-fatal notice, and still runs every other (static, layout-agnostic) audit. A green static-only result is **not** full coverage: run `node scripts/dev/bootstrap-worktree.mjs && npm run dogfood:status` once under the pnpm layout too before a cut ships. Only a missing `node_modules` entirely still hard-exits.
 
 ### `npm run verify:pack`
 
-- **What:** `npm pack --dry-run` succeeds per package — catches malformed `files`/`exports`. Note: the npm `files:` array supports negation (`!components/**/*.html`); verify tarball contents with `--dry-run` after touching it.
+- **What:** `npm pack --dry-run` succeeds per package, catches malformed `files`/`exports`. Note: the npm `files:` array supports negation (`!components/**/*.html`); verify tarball contents with `--dry-run` after touching it.
 
-Siblings: `check:links` (intra-repo markdown links resolve) · `check:cdn-pins` (docs' CDN `@0.X` pins match the current minor — catches a stale `@0.6` after a `0.7` cut) · `verify:contrast` / `verify:palette` (WCAG pairs / OKLCH ramps).
+Siblings: `check:links` (intra-repo markdown links resolve) · `check:cdn-pins` (docs' CDN `@0.X` pins match the current minor, catches a stale `@0.6` after a `0.7` cut) · `verify:contrast` / `verify:palette` (WCAG pairs / OKLCH ramps).
 
 ---
 
 ## §Standard subsets
 
-**Minimum 6 (verify-only default)** — fastest set that catches release-blockers:
+**Minimum 6 (verify-only default)**, fastest set that catches release-blockers:
 
 ```bash
 node scripts/build/components.mjs --verify
@@ -215,9 +214,9 @@ npm run check:demo-shells
 
 Add `verify:corpus` + `check:embeddings-fresh` if chunks were touched; `check:lightningcss-build` if CSS was touched; F-N1 if unpushed release tags exist.
 
-**Full pre-cut sweep** — the 30-gate roster in [`cut-procedure.md`](cut-procedure.md) §Step 3, sourced from `` `<plugin-root>/skills/package-release/scripts/gate-roster.mjs` `` (the ONE list; `release-pack.mjs` imports and runs it in full — a subset run is impossible without editing that file). ~90s wall time.
+**Full pre-cut sweep**, the 30-gate roster in [`cut-procedure.md`](cut-procedure.md) §Step 3, sourced from `` `<plugin-root>/skills/package-release/scripts/gate-roster.mjs` `` (the ONE list; `release-pack.mjs` imports and runs it in full, a subset run is impossible without editing that file). ~90s wall time.
 
-**Omnibus** — `npm run check` invokes everything. Heavy; use when re-baselining a stale checkout.
+**Omnibus**, `npm run check` invokes everything. Heavy; use when re-baselining a stale checkout.
 
 **Suffix variants:** most gates have `:strict` (warns fail), `:fix` (auto-apply, e.g. `check:lockstep:fix`), `:json` / `:quiet` (output form) variants.
 
@@ -226,5 +225,5 @@ Add `verify:corpus` + `check:embeddings-fresh` if chunks were touched; `check:li
 ## §Gate stewardship
 
 - **This catalog must stay in sync with `package.json` `scripts`.** When a cycle meets a release-flow gate not listed here, add its row in the same change.
-- **New CI gates ship advisory first** (`continue-on-error: true`), promoted to blocking after 5+ green runs. Two freshness-gate traps: mtime checks are permanently red on fresh `actions/checkout` (clone-time mtimes — need `fetch-depth: 0` + git-restore-mtime); a dir-watching gate needs its own workflow whose `pull_request: paths:` covers the watched dirs.
-- **New/extended `scripts/release/check-*.mjs` slots run against `main` immediately**; close every finding same-cycle. Before adding a slot, grep the existing ones — the gap is often a regex limit in a current slot, not a missing slot.
+- **New CI gates ship advisory first** (`continue-on-error: true`), promoted to blocking after 5+ green runs. Two freshness-gate traps: mtime checks are permanently red on fresh `actions/checkout` (clone-time mtimes, need `fetch-depth: 0` + git-restore-mtime); a dir-watching gate needs its own workflow whose `pull_request: paths:` covers the watched dirs.
+- **New/extended `scripts/release/check-*.mjs` slots run against `main` immediately**; close every finding same-cycle. Before adding a slot, grep the existing ones: the gap is often a regex limit in a current slot, not a missing slot.

package/skills/package-release/references/independent-package-release.md

@@ -1,9 +1,8 @@
-# `independent-package-release.md` — class-B cut (independently-versioned package)
+# `independent-package-release.md`, class-B cut (independently-versioned package)
 
-> Load when releasing a package versioned **independently** of the lockstep set —
-> excluded from the lockstep gate, no umbrella tag, no demo-site deploy.
+> Load when releasing a package versioned **independently** of the lockstep set, > excluded from the lockstep gate, no umbrella tag, no demo-site deploy.
 > **Class B's current member is `@adia-ai/adia-plugins`** (gh#1133/gh#1160,
-> ADR-0045) — the npm-sourced marketplace manifest package, marked
+> ADR-0045), the npm-sourced marketplace manifest package, marked
 > `lockstep: false` on the roster (`scripts/package-paths.mjs`). It's the
 > first member since the 2026-07-15 policy change (operator ruling) that
 > emptied the class: the Claude Code plugins under `packages/plugins/*`
@@ -16,18 +15,18 @@
 
 ## §Two release classes in one monorepo
 
-| | Class A — lockstep cut | Class B — independent package |
+| | Class A, lockstep cut | Class B, independent package |
 | --- | --- | --- |
 | Versioning | whole set bumps together | own version line per package |
-| Lockstep gate | enforced (`check:lockstep` 10/10) | **excluded** — a class-B package is not listed in `check-lockstep.mjs`'s `PACKAGES` (`adia-plugins`, the current member, is filtered out via `lockstep: false` — `scripts/package-paths.mjs`) |
-| Umbrella tag | `vX.Y.Z` + per-package | **none** — per-package tags only (versions differ) |
+| Lockstep gate | enforced (`check:lockstep` 10/10) | **excluded**, a class-B package is not listed in `check-lockstep.mjs`'s `PACKAGES` (`adia-plugins`, the current member, is filtered out via `lockstep: false`, `scripts/package-paths.mjs`) |
+| Umbrella tag | `vX.Y.Z` + per-package | **none**, per-package tags only (versions differ) |
 | `dist-tag` ordering | cross-package publish order matters | N/A |
 | Demo-site deploy | yes | **none** |
 | Publish trigger | tag-triggered per-package workflow | same mechanism (`.github/workflows/publish-adia-ui-{factory,forge}.yml`) |
 
 Class B keeps the single-authorization model and the verify-against-the-registry discipline; it drops every lockstep-specific invariant.
 
-## §New-package onboarding — the three trip-wires a FIRST cut hits
+## §New-package onboarding, the three trip-wires a FIRST cut hits
 
 Substrate fixes (release scripts / lockfile / CHANGELOG), landed once as a normal PR on `main` *before* tagging:
 
@@ -37,20 +36,20 @@ Substrate fixes (release scripts / lockfile / CHANGELOG), landed once as a norma
 
 ## §Procedure
 
-1. **Re-baseline** — `git fetch`; confirm the checkout isn't on a peer's branch.
+1. **Re-baseline**, `git fetch`; confirm the checkout isn't on a peer's branch.
 2. **Land the package(s) on `main`** via PR; resolve every review thread before an admin-merge (this repo's merge gate).
-3. **Pre-publish gate.** `npm run verify:plugins` (package.json ↔ plugin-manifest versions synced). Plugin-specific structural gates: `npm run audit:plugin-coupling` + `npm run check:factory-bare-repo` (ADR-0040 — the plugin must work in a bare consumer repo, no monorepo coupling). The lockstep gate still passes for the lockstep set. First publish of a name: `npm view @adia-ai/<pkg> version` → `E404` means the name is free.
-4. **Tag at the published commit** — `git tag <pkg>-vX.Y.Z` per package; versions differ; no umbrella. Dry-run the trip-wire over the tags (`node scripts/release/check-release.mjs <tags>`) before pushing. If the shared working tree is on a peer's branch, push tags from a throwaway worktree on `origin/main`.
+3. **Pre-publish gate.** `npm run verify:plugins` (package.json ↔ plugin-manifest versions synced). Plugin-specific structural gates: `npm run audit:plugin-coupling` + `npm run check:factory-bare-repo` (ADR-0040, the plugin must work in a bare consumer repo, no monorepo coupling). The lockstep gate still passes for the lockstep set. First publish of a name: `npm view @adia-ai/<pkg> version` → `E404` means the name is free.
+4. **Tag at the published commit**, `git tag <pkg>-vX.Y.Z` per package; versions differ; no umbrella. Dry-run the trip-wire over the tags (`node scripts/release/check-release.mjs <tags>`) before pushing. If the shared working tree is on a peer's branch, push tags from a throwaway worktree on `origin/main`.
 5. **Push the tags** → the per-package workflows run `npm ci → verify:plugins → npm publish --access public`.
 6. **Verify against npm, not the workflow:** `npm view @adia-ai/<pkg> version` returns the new independent version for each package. Watch runs (`gh run watch <id> --exit-status`), but the registry is the source of truth.
-7. **Marketplace cut-over** — per ADR-0045 the distribution channel is the npm-sourced manifest package `@adia-ai/adia-plugins` (no public git marketplace repo — that shape was considered and rejected). Bump/publish the manifest package so its `marketplace.json` entries reference the new plugin versions; consumers add the marketplace from npm, never from a git repo.
+7. **Marketplace cut-over**, per ADR-0045 the distribution channel is the npm-sourced manifest package `@adia-ai/adia-plugins` (no public git marketplace repo: that shape was considered and rejected). Bump/publish the manifest package so its `marketplace.json` entries reference the new plugin versions; consumers add the marketplace from npm, never from a git repo.
 
 ## §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 10 lockstep packages + the demo site" — that's class A.
+The published package(s) on the **npm registry** at their independent versions, plus the npm-published `@adia-ai/adia-plugins` manifest referencing the new versions (ADR-0045). NOT "all 10 lockstep packages + the demo site", that's class A.
 
 ## §Gotchas (from the first independent cut, factory v0.2.2 + forge v0.1.2)
 
 - Never add the package to the lockstep gate or tag it with the umbrella.
-- Publish-workflow YAMLs are token-bearing — keep `persist-credentials: false` on the checkout step, matching the established workflows' action-pinning.
-- A marketplace repo's org + visibility is an **operator call** — a public `gh repo create` is outward-facing; confirm first, and run a secret-scan of full history before pushing any repo public.
+- Publish-workflow YAMLs are token-bearing, keep `persist-credentials: false` on the checkout step, matching the established workflows' action-pinning.
+- A marketplace repo's org + visibility is an **operator call**, a public `gh repo create` is outward-facing; confirm first, and run a secret-scan of full history before pushing any repo public.

package/skills/package-release/references/invariants-detail.md

@@ -1,4 +1,4 @@
-# Invariants — detail and history
+# Invariants, detail and history
 
 SKILL.md's own "Invariants" section states each rule; this expands the
 history and mechanics behind the denser ones.
@@ -6,39 +6,39 @@ history and mechanics behind the denser ones.
 ## 1. Lockstep coherence
 
 Every roster package bumps together (`check:lockstep`). **The roster is
-`scripts/package-paths.mjs`'s `PACKAGE_ROSTER` — read it, never a copy.**
+`scripts/package-paths.mjs`'s `PACKAGE_ROSTER`, read it, never a copy.**
 This line used to enumerate the names inline and went stale the first time
 the roster moved (ADR-0048 P4 added a package while the list still read the
 pre-split six); a name list has no gate behind it, so it can only decay.
 Each plugin's `.claude-plugin/plugin.json` version moves with its
-package.json — `bump.mjs` handles both; `verify:plugins` gates the sync.
+package.json, `bump.mjs` handles both; `verify:plugins` gates the sync.
 
 ## 2. PATCH-cut asymmetry
 
 Internal `@adia-ai/*` ranges hold at `^X.Y.0` during PATCH cuts; only MINOR
-bumps the floor. `^0.0.x` is forbidden (pre-1.0 caret locks exact — shipped
+bumps the floor. `^0.0.x` is forbidden (pre-1.0 caret locks exact, shipped
 a real stale-sibling bug).
 
 ## 3. Release commits land via PR, never a direct push to `main`
 
 (Repo policy, operator ruling 2026-07-12.) Commit on `release/vX.Y.Z` → PR →
-CI → merge — THEN tag at `main`'s post-merge HEAD, not at the bump commit;
+CI → merge, THEN tag at `main`'s post-merge HEAD, not at the bump commit;
 post-bump fixes merge before tagging and belong in the tarball. Exception:
 batch push tags each version at its own release-merge SHA.
 
 ## 4. One umbrella + one per-package tag per cut
 
 One per lockstep-roster package (`scripts/package-paths.mjs`); publish
-workflows key off the per-package tags. Push tags **one per `git push`** — a
+workflows key off the per-package tags. Push tags **one per `git push`**, a
 batched multi-tag push drops the trigger event.
 
 ## 5. F-N1 per-package clean
 
-`check:release --all-pending` — the umbrella-tag mismatch error is expected
+`check:release --all-pending`: the umbrella-tag mismatch error is expected
 noise. Coverage is mechanized at cut time: Step 4f
 (`check-release.mjs --pending-version X.Y.Z --fix`) runs the SAME matcher
 pre-PR and auto-appends verified Maintenance bullets, so a post-tag warn
-means something novel — stop and investigate, don't loop enrichment PRs.
+means something novel, stop and investigate, don't loop enrichment PRs.
 
 ## 6. `npm dist-tag latest` is set by publish order
 
@@ -54,7 +54,7 @@ including visible behavior changes, stays PATCH.
 Bump the pin in `packages/plugins/adia-ui-factory/.mcp.json` in the same cut
 (the consumer never floats; with the plugins in-lockstep this lands in the
 release commit itself, not a follow-up). The pinned NAME is `@adia-ai/mcp`
-with the `gen-ui` subcommand (`npx -y @adia-ai/mcp@<exact> gen-ui`) — the
+with the `gen-ui` subcommand (`npx -y @adia-ai/mcp@<exact> gen-ui`), the
 single live name since the ADR-0048 P7 cut (v0.8.37) per the gh#1240
 one-package amendment; `@adia-ai/a2ui-mcp` is retired and the P2-planned
 `@adia-ai/gen-ui-mcp` never published. `check:lockstep`'s mcp-pin guard and

package/skills/package-release/references/mechanization.md

@@ -1,40 +1,39 @@
-# Mechanization — bundled `scripts/`, stdlib Node, all support `--dry`
+# Mechanization, bundled `scripts/`, stdlib Node, all support `--dry`
 
-`release-pack.mjs` walks the cycle in two phases per invariant 3 — `--mode
-cut` / `--mode from-scratch` promote `[Unreleased]` (BOTH modes now — a
+`release-pack.mjs` walks the cycle in two phases per invariant 3, `--mode
+cut` / `--mode from-scratch` promote `[Unreleased]` (BOTH modes now, a
 peer's hand-authored section must be promoted whichever mode cut it, and a
 loud guard blocks the bump if any roster package still carries non-empty
 `[Unreleased]` content after promotion), run Step 4f (pre-tag coverage
 `--fix` with the authoritative F-N1 matcher), and stop at the release commit
 (PR → merge); `--mode handoff` tags/publishes/deploys from post-merge main.
-**`--go` is the standard invocation for an operator-initiated release** — the
+**`--go` is the standard invocation for an operator-initiated release**, the
 single authorization covers the cycle; evidence blocks print as a log;
 granular `--yes`/`--push`/`--publish` remain for cautious manual runs
 (`--push` still refuses to auto-fire past any F-N1 finding). `--mode batch`
-is not implemented — it hard-rejects with a pointer to
+is not implemented, it hard-rejects with a pointer to
 [recovery-paths.md](recovery-paths.md) §Scenario 2 rather than silently
 misbehaving; a real batch tags each version at its own release-merge SHA,
 which this single-version orchestrator has no model for. Pre-flight (Step 3)
 runs the full 30-gate roster from the single shared list in
-`scripts/gate-roster.mjs` — the same list [cut-procedure.md](cut-procedure.md)
+`scripts/gate-roster.mjs`, the same list [cut-procedure.md](cut-procedure.md)
 §3.1 transcribes, so a subset run requires editing that one file, not two.
 
 The pieces are callable alone: `bump.mjs` (version fields + the factory
 `.mcp.json` `@adia-ai/mcp` pin, invariant 8), `promote-unreleased.mjs` /
 `insert-stub.mjs` (CHANGELOG blocks), `tag-lockstep.mjs` (umbrella + one tag
-per lockstep roster package — the set is derived from `PACKAGE_ROSTER`,
+per lockstep roster package: the set is derived from `PACKAGE_ROSTER`,
 never a number written here: it went stale at 14 while the roster said 17,
 17 went stale in turn when gh#1240 folded two planned MCP rows into one
 (now 16), and 16 goes stale again the day the ADR-0048 shims retire; run
 `--dry` to see the live list, `--delete` to move), `dispatch-publish.mjs`
-(publish workflows; `--verify-triggered` re-dispatches missing AND dead —
-cancelled/failed/timed-out — runs, each gated behind an npm-registry check
+(publish workflows; `--verify-triggered` re-dispatches missing AND dead, cancelled/failed/timed-out, runs, each gated behind an npm-registry check
 so an already-published version is never re-dispatched (gh#763); `--after`
-enforces batch ordering — dispatch output states what WAS done, never a
+enforces batch ordering, dispatch output states what WAS done, never a
 to-do phrased as if it hadn't fired), and `pr-bridge.mjs` (the two-phase
 bridge: pushes the release branch, opens the PR, waits out CI, and merges
 ONLY on all-non-fail-soft-checks-green + zero unresolved threads + no
-changes-requested; any other state stops with evidence — §5.7 mechanized,
+changes-requested; any other state stops with evidence, §5.7 mechanized,
 `--dry` to preview the decision). All fail fast outside a monorepo root
 (`assert-monorepo-root.mjs`); fork-configurable via `--host` / `--scope`.
 All 6 CLI scripts (plus `scripts/release/check-release.mjs`) have a
@@ -46,7 +45,7 @@ exercised through the CLIs' selftests, not their own.
 
 Site deploy (Step 10 of the handoff) dispatches `deploy-site.yml` (its own
 pre-flight verify → snapshot → hardened rsync → post-deploy verify →
-auto-rollback), never a raw local `rsync` — H1 (forge-campaign gh#268
+auto-rollback), never a raw local `rsync`, H1 (forge-campaign gh#268
 audit): the script had drifted into bypassing that pipeline even though this
 doc already taught the workflow-dispatch path. The dispatch rides the
 cycle's single authorization (`--go`, or `--publish` on a manual run); the

package/skills/package-release/references/migration-guide-authoring.md

@@ -1,35 +1,35 @@
-# `migration-guide-authoring.md` — authoring the MIGRATION GUIDE on a breaking cut
+# `migration-guide-authoring.md`, authoring the MIGRATION GUIDE on a breaking cut
 
 > Load whenever the cut is **MINOR** (an API-surface break) or on an explicit
 > "author the migration guide" ask. This is the **producer** side of migrations:
 > 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 `app-migration` 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 `app-migration` — 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).
+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).
 
 ## §When a section is owed
 
-Author (or extend) a section when the cut removes or renames a **public API symbol**: a prop/attribute (`variant="danger"` → `color="danger"`), a slot or slot-semantics flip, an event name, a token (`--n-*` → `--a-*`), a tag, a Boolean → enum migration, or a default-value change wide enough that consumers must act. Same line as the PATCH-vs-MINOR rule: cutting MINOR almost certainly owes a section. Additive cuts need none — note "additive; no consumer sweep" in the version-coverage table and move on.
+Author (or extend) a section when the cut removes or renames a **public API symbol**: a prop/attribute (`variant="danger"` → `color="danger"`), a slot or slot-semantics flip, an event name, a token (`--n-*` → `--a-*`), a tag, a Boolean → enum migration, or a default-value change wide enough that consumers must act. Same line as the PATCH-vs-MINOR rule: cutting MINOR almost certainly owes a section. Additive cuts need none, note "additive; no consumer sweep" in the version-coverage table and move on.
 
 ## §The authoring workflow
 
 **1. Enumerate the breaking surface** from the cut's diff + CHANGELOG `### Removed`/`### Changed` entries. Per item capture: the symbol · before → after · the kind (pure rename / semantic flip / Boolean→enum / removal) · the audit grep · the sweep (or "manual review").
 
-**2. Write the section** — one `###` subsection per item:
+**2. Write the section**, one `###` subsection per item:
 
 ```markdown
 ## Migrating to @adia-ai/web-components@X.Y.Z (YYYY-MM-DD)
 
 <one-line scope: N breaking items, the headline.>
 
-### <item — bold headline> (`old` → `new`)
+### <item, bold headline> (`old` → `new`)
 
 <one sentence: what changed and why.>
 
@@ -44,21 +44,21 @@ done
 
 Shape rules:
 
-- **Audit grep first, sweep second** — the consumer always lists call sites before sweeping; author both.
-- **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'`).
+- **Audit grep first, sweep second**, the consumer always lists call sites before sweeping; author both.
+- **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
+  (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.
+**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.
 
-**4. Verify.** Run the cut's normal gate roster; the structural/demo gates catch missed in-repo surfaces. Then the **sweep-verification grep** across ALL extensions — the trap is a vocabulary migration that touched markup but not the CSS selectors or JS comments referencing it:
+**4. Verify.** Run the cut's normal gate roster; the structural/demo gates catch missed in-repo surfaces. Then the **sweep-verification grep** across ALL extensions: the trap is a vocabulary migration that touched markup but not the CSS selectors or JS comments referencing it:
 
 ```bash
 LEGACY_PATTERNS=( '<old-tag' 'old-attr=' '--old-token' )
@@ -69,15 +69,15 @@ for pat in "${LEGACY_PATTERNS[@]}"; do
 done   # 0 hits = sweep verified clean
 ```
 
-**5. Cross-reference.** The breaking package's CHANGELOG entry names the symbol AND points at the guide section; the release notes carry a `⚠️` heads-up linking it. Anchors are stable — never retitle an existing section (release notes and consumer tooling link them).
+**5. Cross-reference.** The breaking package's CHANGELOG entry names the symbol AND points at the guide section; the release notes carry a `⚠️` heads-up linking it. Anchors are stable, never retitle an existing section (release notes and consumer tooling link them).
 
 ## §Manual-review classes (never auto-sweep)
 
-- **Semantic flips** — a rename that inverts default behavior (`[open]` default-hidden → `[collapsed]` default-visible): the right migration depends on author intent. List occurrences, ask.
-- **Opt-out Booleans defaulting true** — the migration only matters where a consumer explicitly disabled the affordance; sed can't tell.
-- **Ownership moves** — a prop moving from wrapper to slotted child; the target child may not exist yet.
-- **kebab-string property keys** — attribute name unchanged, only the JS programmatic form changed; audit programmatic access only.
-- **Wide namespace renames (50+ symbols)** — tag/token/class rename waves: list by table, require human approval per cluster; blind sweeps hit false positives on shared prefixes.
+- **Semantic flips**, a rename that inverts default behavior (`[open]` default-hidden → `[collapsed]` default-visible): the right migration depends on author intent. List occurrences, ask.
+- **Opt-out Booleans defaulting true**, the migration only matters where a consumer explicitly disabled the affordance; sed can't tell.
+- **Ownership moves**, a prop moving from wrapper to slotted child; the target child may not exist yet.
+- **kebab-string property keys**, attribute name unchanged, only the JS programmatic form changed; audit programmatic access only.
+- **Wide namespace renames (50+ symbols)**, tag/token/class rename waves: list by table, require human approval per cluster; blind sweeps hit false positives on shared prefixes.
 
 ## §The version-coverage table