@adia-ai/adia-ui-forge 0.8.7 → 0.8.8

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "adia-forge",
-  "version": "0.8.7",
+  "version": "0.8.8",
   "description": "Maintain the adia-ui (@adia-ai) framework itself \u2014 author primitives and shells, run the A2UI generation pipeline and its corpus, review gen-UI quality, sweep QA, cut releases, deploy. The maintainer counterpart to adia-factory (the consumer/app-author plugin).",
   "author": {
     "name": "Kim",

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog — adia-forge
 
+## [0.8.8] — 2026-07-19
+
+### Added
+- **`pr-bridge.mjs`** (adia-release `skills/adia-release/scripts/`): the cut's two-phase PR bridge, mechanized — pushes the release branch, opens/reuses the PR, polls CI, and admin-merges ONLY on all-non-fail-soft-checks-green + zero unresolved review threads + no changes-requested + MERGEABLE; anything else waits or stops with full evidence (`--dry` previews the decision). Independently reviewed and hardened pre-ship: never merges on an empty gating-check set ("nothing failed" ≠ "something passed"); operator-supplied args go through `execFileSync` arg arrays (no shell); the merge-landing proof never skips silently. 14-case selftest; registered in CI's Plugin bin selftests; battle-tested on 8 real merges before first release use. cut-procedure §5.7 documents both the mechanized and manual forms.
+
+### Changed
+- **`package-paths.mjs` is now the single source of the 11-package roster** (`PACKAGE_ROSTER` + `PACKAGE_NAMES`/`PACKAGE_DIRS`): the lockstep list was re-declared in 8 scripts (bump, tag-lockstep, dispatch-publish, release-pack, and the repo-side check-release/check-lockstep/check-release-docs/generate-release-notes), each with its own projection — the same list-drift class the gate-roster incident proved out. Skill-side home is deliberate: cache-executed skill scripts can't import repo modules; repo scripts import the skill module by its stable in-repo path.
+- **`gate-roster.mjs` grew gate 18** (`check-cut-hygiene --version X.Y.Z`, via the new `versionArg` field release-pack substitutes) and **gate 4 now runs `test:unit:serial`** (`vitest --no-file-parallelism` — gates-catalog §Cat 8's documented source of truth IS now the gate). References updated same-change: cut-procedure §3.1 (18-gate table), gates-catalog Cat 1/7/8/9.
+
+### Fixed
+- **`bump.mjs` moves every cross-file version reference in the same pass**: the factory `.mcp.json` `@adia-ai/a2ui-mcp@X.Y.Z` pin (invariant 8 — hand-fixed on BOTH the 0.8.6 and 0.8.7 cuts; `check:lockstep` now guards it too) and the root README "Current version" claim (`REPO_PINNED_REFS` — gate 18 exact-matches it, so a hand-set value fails the next cut by construction). All pins pre-flight-validated alongside `validateAllAtFrom`, so a doomed bump writes NOTHING (reviewer finding: the mid-loop check fired only after two files were already written).
+- **adia-release docs**: SKILL.md Mechanization + cut-procedure §5.7/§3.1 + gates-catalog reflect pr-bridge, the 18-gate roster, the umbrella tag's `info` classification (the repo-side `check-release.mjs` fix that killed the Step-7 false-stop which forced manual handoffs on 0.8.6/0.8.7), and the deleted superseded `check-changelog-coverage` gate.
+
+### Maintenance
+- **`.claude-plugin/plugin.json` version bump** — moves in lockstep with package.json (the `/plugin update` cache key).
+
 ## [0.8.7] — 2026-07-19
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adia-ai/adia-ui-forge",
-  "version": "0.8.7",
+  "version": "0.8.8",
   "description": "Maintain the adia-ui (@adia-ai) framework itself \u2014 author primitives and shells, run the A2UI generation pipeline and its corpus, review gen-UI quality, sweep QA, cut releases, deploy. The maintainer counterpart to adia-factory (the consumer/app-author plugin).",
   "keywords": [
     "adia-ui",

package/skills/adia-release/SKILL.md

@@ -95,7 +95,7 @@ assumed pass, or "published" without the actual `npm view` output.
 
 `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 of the 11 packages 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 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 [`recovery-paths.md`](references/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 17-gate roster from the single shared list in `scripts/gate-roster.mjs` — the same list [`cut-procedure.md`](references/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), `promote-unreleased.mjs` / `insert-stub.mjs` (CHANGELOG blocks), `tag-lockstep.mjs` (12 tags, `--delete` to move), `dispatch-publish.mjs` (publish workflows; `--verify-triggered` re-dispatches only missing runs; `--after` enforces batch ordering — dispatch output states what WAS done, never a to-do phrased as if it hadn't fired). 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 `selftest` mode wired into CI's Plugin bin selftests step; the 3 helper modules (`assert-monorepo-root`, `gate-roster`, `package-paths`) are exercised through the CLIs' selftests, not their own.
+The pieces are callable alone: `bump.mjs` (version fields + the factory `.mcp.json` a2ui-mcp pin, invariant 8), `promote-unreleased.mjs` / `insert-stub.mjs` (CHANGELOG blocks), `tag-lockstep.mjs` (12 tags, `--delete` to move), `dispatch-publish.mjs` (publish workflows; `--verify-triggered` re-dispatches only missing runs; `--after` 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, `--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 `selftest` mode wired into CI's Plugin bin selftests step; the 3 helper modules (`assert-monorepo-root`, `gate-roster`, `package-paths`) are 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 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 workflow's own GitHub environment gate is the human stop for the deploy itself.
 

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

@@ -78,13 +78,13 @@ npm run build:bundles                  # dist CSS+JS bundles
 ```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
-npm run test:unit                              #  4 vitest
+npm run check:lockstep                         #  3 version coherence (+ factory .mcp.json a2ui-mcp pin, invariant 8)
+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
 npm run check:css-bundles-fresh                #  8 dist CSS matches source
-npm run check:js-bundles-fresh                 #  9 dist JS matches source
+npm run check:js-bundles-fresh                 #  9 dist JS matches source + semantic content (everything-import, ≥100 -ui tags, icons-manifest ×2)
 npm run smoke:engines                          # 10 gen-UI engines
 npm run smoke:register-engine                  # 11 register-engine 11/11
 npm run verify:corpus                          # 12 corpus 0 errors
@@ -93,6 +93,7 @@ npm run check:embeddings-fresh                 # 14 embeddings vs chunk index
 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
+node scripts/release/check-cut-hygiene.mjs --version <mode-dependent>  # 18 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)
 ```
 
 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.
@@ -157,7 +158,18 @@ Drift here means a regen output was left out of the allowlist — stage it and r
 
 ## §Step 5.7 — Release PR: push the branch, merge, re-baseline
 
-The release commit reaches `main` through the standard PR flow:
+The release commit reaches `main` through the standard PR flow. Mechanized
+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):
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/skills/adia-release/scripts/pr-bridge.mjs" \
+  --branch "release/vX.Y.Z" --title "release: vX.Y.Z lockstep" --body-file <path>
+```
+
+Manual form (the same flow the bridge mechanizes):
 
 ```bash
 git -C "$REPO" push -u origin "release/vX.Y.Z"

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

@@ -25,12 +25,9 @@ Row layout per gate: **What** · **Typical failure** · **Recovery**.
 - **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's "doesn't match `<pkg>-v<version>`" **error is expected — ignore it**; only per-package warns need action.
+- 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.
 
-### `npm run check:changelog-coverage`
-
-- **What:** every published package has a `[vX.Y.Z]` CHANGELOG block for the current `package.json` version.
-- **Recovery:** add the block (stub if genuinely no source change — but classify by the diff first, see [`changelog-discipline.md`](changelog-discipline.md) §Detecting source-changing packages).
+(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.)
 
 ---
 
@@ -141,14 +138,7 @@ The two `audit:*` probes are soft-fail pre-cut (exit-1 only on criticals); findi
 
 - **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.
-- **Manual spot-checks** (complement the gate; the v0.6.29–31 cycles shipped a shells-only `everything.min.js` that hard-crashed CDN consumers):
-
-  ```bash
-  grep "import '@adia-ai/web-components'" packages/web-modules/everything.js   # must be present
-  grep -oE '"[a-z][a-z-]*-ui"' packages/web-modules/dist/everything.min.js | sort -u | wc -l   # ≥100
-  node -e "const m=require('./packages/web-components/dist/icons-manifest.js'); \
-    console.log('regular:', m.default.regular.length, '| cdn:', m.default.cdn)"   # non-empty + cdn key
-  ```
+- **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`
 
@@ -162,7 +152,7 @@ The two `audit:*` probes are soft-fail pre-cut (exit-1 only on criticals); findi
 
 - **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. **Gate on `npx vitest run --no-file-parallelism`** (sequential is the source of truth); don't treat a one-off parallel flake as a blocker, and don't raise the drain guard.
+- **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.
 
 ### `npm run eval:diff -- --engine zettel`
 
@@ -179,6 +169,11 @@ Siblings: `typecheck` (`tsc --noEmit`) · `smoke:engines` (gen-UI engines + retr
 
 ## §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.
+- **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.

package/skills/adia-release/scripts/bump.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// bump.mjs — bump 9 @adia-ai/* package.json from --from to --to.
+// bump.mjs — bump the 11 lockstep @adia-ai/* package.json from --from to --to.
 //
 // Idempotent. Stops on the first mismatch (a package not at --from) so
 // you can investigate before any mutation lands.
@@ -20,32 +20,55 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import process from 'node:process';
+import { PACKAGE_DIRS, PACKAGE_ROSTER } from './package-paths.mjs';
 
-const PACKAGES = [
-  'packages/web-components',
-  'packages/web-modules',
-  'packages/llm',
-  'packages/a2ui/compose',
-  'packages/a2ui/corpus',
-  'packages/a2ui/mcp',
-  'packages/a2ui/retrieval',
-  'packages/a2ui/runtime',
-  'packages/a2ui/validator',
-  // Plugins joined the lockstep 2026-07-15 (see check-lockstep.mjs's POLICY
-  // note). Each also carries a .claude-plugin/plugin.json whose version MUST
-  // move with package.json — plugin.json is the /plugin-update cache key
-  // (verify:plugins gates the sync).
-  'packages/plugins/adia-ui-factory',
-  'packages/plugins/adia-ui-forge',
-];
+// Single-sourced roster (H3, package-paths.mjs). Each plugin also carries a
+// .claude-plugin/plugin.json whose version MUST move with package.json —
+// plugin.json is the /plugin-update cache key (verify:plugins gates the sync).
+const PACKAGES = PACKAGE_DIRS;
 
 // Sibling manifests bumped in the same pass as package.json (path relative to
-// the package dir). Today: the Claude Code plugin manifests.
-const SIBLING_MANIFESTS = {
-  'packages/plugins/adia-ui-factory': '.claude-plugin/plugin.json',
-  'packages/plugins/adia-ui-forge': '.claude-plugin/plugin.json',
+// the package dir) — derived from the roster's plugin flag.
+const SIBLING_MANIFESTS = Object.fromEntries(
+  PACKAGE_ROSTER.filter((p) => p.plugin).map((p) => [p.dir, '.claude-plugin/plugin.json']),
+);
+
+// Cross-package EXACT pins bumped in the same pass — a different shape from a
+// package.json "version" field, so SIBLING_MANIFESTS' regex can't reach them.
+// The factory plugin's .mcp.json pins @adia-ai/a2ui-mcp to the exact lockstep
+// version (SKILL invariant 8 — the consumer never floats). bump.mjs left this
+// untouched through the 0.8.6 + 0.8.7 cuts, forcing a manual edit + amend each
+// time; check-lockstep's mcp-pin guard now catches a drift, this moves it.
+const PINNED_REFS = {
+  'packages/plugins/adia-ui-factory': {
+    file: '.mcp.json',
+    label: '@adia-ai/a2ui-mcp pin',
+    // `@adia-ai/a2ui-mcp@<from>` (not a prefix of a longer version) → `@<to>`
+    pattern: (from) => new RegExp(`(@adia-ai/a2ui-mcp@)${from.replace(/\./g, '\\.')}(?![\\d.])`),
+    replace: (to) => `$1${to}`,
+  },
 };
 
+// Repo-level version references (path relative to REPO ROOT, not a package) —
+// same mechanism, different anchor. The root README's "Current version" claim
+// is gate 18's EXACT-match check (check-cut-hygiene doc-currency): hand-set it
+// once and the next cut fails the gate — so the bump moves it, like the
+// .mcp.json pin (H2 follow-through, 2026-07-19: found 0.7.13 claimed while
+// 0.8.7 was live — a full minor of README drift shipped to npm).
+const REPO_PINNED_REFS = [
+  {
+    file: 'README.md',
+    label: '"Current version" claim',
+    pattern: (from) => new RegExp(`([Cc]urrent version[^\\d]*v?)${from.replace(/\./g, '\\.')}(?![\\d.])`),
+    replace: (to) => `$1${to}`,
+  },
+];
+
+// Pure so the selftest can lock the transform without touching a real file.
+function bumpPinnedRef(text, cfg, from, to) {
+  return text.replace(cfg.pattern(from), cfg.replace(to));
+}
+
 function parseArgs(argv) {
   const args = { from: null, to: null, dry: false, repo: process.cwd() };
   for (let i = 0; i < argv.length; i++) {
@@ -84,6 +107,52 @@ function loadPackageJsons(repo) {
   return result;
 }
 
+// Pre-flight the cross-package pins the same way validateAllAtFrom pre-flights
+// versions: a pin not at --from means invariant-8 drift, and catching it HERE —
+// before bumpAll writes anything — keeps the failure mutation-free. (Reviewer
+// finding on the first PINNED_REFS cut: the mid-loop pin check fired only after
+// factory's package.json + plugin.json were already written, leaving a
+// half-bumped tree whose re-run then failed validateAllAtFrom.)
+function loadPinnedRefs(repo) {
+  const out = [];
+  for (const [pkg, cfg] of Object.entries(PINNED_REFS)) {
+    const p = path.join(repo, pkg, cfg.file);
+    if (!fs.existsSync(p)) {
+      console.error(`error: missing ${p}`);
+      process.exit(2);
+    }
+    out.push({ pkg, cfg, path: p, txt: fs.readFileSync(p, 'utf8') });
+  }
+  for (const cfg of REPO_PINNED_REFS) {
+    const p = path.join(repo, cfg.file);
+    if (!fs.existsSync(p)) {
+      console.error(`error: missing ${p}`);
+      process.exit(2);
+    }
+    out.push({ pkg: '(repo)', cfg, path: p, txt: fs.readFileSync(p, 'utf8') });
+  }
+  return out;
+}
+
+// Repo-level pins aren't tied to a package iteration in bumpAll — apply them
+// after it, from the same pre-validated set (validatePinsAtFrom guarantees the
+// pattern matches, so this cannot fail mid-write).
+function applyRepoPins(pins, from, to, dry) {
+  for (const x of pins.filter((x) => x.pkg === '(repo)')) {
+    const out = bumpPinnedRef(x.txt, x.cfg, from, to);
+    if (!dry) fs.writeFileSync(x.path, out);
+    console.log(`  ${dry ? '[dry] ' : ''}bumped ${x.cfg.file} ${x.cfg.label}: ${from} → ${to}`);
+  }
+}
+
+function validatePinsAtFrom(pins, from) {
+  const bad = pins.filter((x) => !x.cfg.pattern(from).test(x.txt));
+  for (const x of bad) {
+    console.error(`error: ${x.pkg}/${x.cfg.file} — ${x.cfg.label} '@${from}' not found (invariant-8 drift? fix the pin first: \`npm run check:lockstep:fix\`). Nothing written.`);
+  }
+  return bad.length === 0;
+}
+
 function validateAllAtFrom(packages, from) {
   const wrong = packages.filter((p) => p.version !== from);
   if (wrong.length > 0) {
@@ -121,6 +190,18 @@ function bumpAll(packages, from, to, dry) {
       if (!dry) fs.writeFileSync(sibPath, sibOut);
       console.log(`  ${dry ? '[dry] ' : ''}bumped ${p.pkg}/${sibling}: ${from} → ${to}`);
     }
+    const pin = PINNED_REFS[p.pkg];
+    if (pin) {
+      const pinPath = path.join(path.dirname(p.path), pin.file);
+      const pinTxt = fs.readFileSync(pinPath, 'utf8');
+      const pinOut = bumpPinnedRef(pinTxt, pin, from, to);
+      if (pinOut === pinTxt) {
+        console.error(`error: ${p.pkg}/${pin.file} — ${pin.label} '@${from}' not found (invariant 8 drift? set the pin to @${from} and re-run, or use \`npm run check:lockstep:fix\`)`);
+        return -1;
+      }
+      if (!dry) fs.writeFileSync(pinPath, pinOut);
+      console.log(`  ${dry ? '[dry] ' : ''}bumped ${p.pkg}/${pin.file} ${pin.label}: @${from} → @${to}`);
+    }
   }
   return bumped;
 }
@@ -128,8 +209,11 @@ function bumpAll(packages, from, to, dry) {
 function main() {
   const args = parseArgs(process.argv.slice(2));
   const packages = loadPackageJsons(args.repo);
+  const pins = loadPinnedRefs(args.repo);
   if (!validateAllAtFrom(packages, args.from)) process.exit(1);
+  if (!validatePinsAtFrom(pins, args.from)) process.exit(1);
   const bumped = bumpAll(packages, args.from, args.to, args.dry);
+  if (bumped >= 0) applyRepoPins(pins, args.from, args.to, args.dry);
   if (bumped < 0) process.exit(3);
   console.log(`\n[bump] ${bumped}/${PACKAGES.length} ${args.dry ? '(dry — no files written)' : 'bumped'}`);
   if (!args.dry) {
@@ -166,6 +250,43 @@ function selftest() {
   if (bumpAll(corrupted, '0.8.4', '0.8.5', true) !== -1) {
     console.error('selftest FAIL: corrupted package.json (no version match) not caught'); process.exit(1);
   }
+
+  // PINNED_REFS — the .mcp.json a2ui-mcp pin (invariant 8) moves in lockstep.
+  const pinCfg = PINNED_REFS['packages/plugins/adia-ui-factory'];
+  const pinBefore = '{"args":["-y","@adia-ai/a2ui-mcp@0.8.6"]}';
+  const pinAfter = bumpPinnedRef(pinBefore, pinCfg, '0.8.6', '0.8.7');
+  if (!pinAfter.includes('@adia-ai/a2ui-mcp@0.8.7') || pinAfter.includes('@0.8.6')) {
+    console.error('selftest FAIL: PINNED_REFS did not bump the .mcp.json a2ui-mcp pin'); process.exit(1);
+  }
+  // Must NOT prefix-match a longer version (0.8.6 inside 0.8.60).
+  if (bumpPinnedRef('@adia-ai/a2ui-mcp@0.8.60', pinCfg, '0.8.6', '0.8.7') !== '@adia-ai/a2ui-mcp@0.8.60') {
+    console.error('selftest FAIL: PINNED_REFS pattern prefix-matched a longer version'); process.exit(1);
+  }
+
+  // validatePinsAtFrom — the mutation-free pre-flight (reviewer finding: the
+  // mid-loop pin check fired only after two files were already written).
+  const goodPin = [{ pkg: 'packages/plugins/adia-ui-factory', cfg: pinCfg, path: '/nonexistent/.mcp.json', txt: pinBefore }];
+  if (!validatePinsAtFrom(goodPin, '0.8.6')) {
+    console.error('selftest FAIL: validatePinsAtFrom rejected a pin at --from'); process.exit(1);
+  }
+  if (validatePinsAtFrom(goodPin, '0.8.5')) {
+    console.error('selftest FAIL: validatePinsAtFrom accepted a drifted pin (should pre-flight-fail before any write)'); process.exit(1);
+  }
+
+  // REPO_PINNED_REFS — the root README "Current version" claim moves per-cut
+  // (gate 18's doc-currency check is EXACT-match, so a static value fails the
+  // next cut by construction).
+  const readmeCfg = REPO_PINNED_REFS[0];
+  const claimBefore = 'lockstep. Current version: **`v0.8.7`** — see CHANGELOG';
+  const claimAfter = bumpPinnedRef(claimBefore, readmeCfg, '0.8.7', '0.8.8');
+  if (!claimAfter.includes('v0.8.8') || claimAfter.includes('0.8.7')) {
+    console.error('selftest FAIL: REPO_PINNED_REFS did not move the Current-version claim'); process.exit(1);
+  }
+  // Must not touch an already-moved or unrelated version string.
+  if (bumpPinnedRef('Current version: v0.8.70', readmeCfg, '0.8.7', '0.8.8') !== 'Current version: v0.8.70') {
+    console.error('selftest FAIL: Current-version pattern prefix-matched a longer version'); process.exit(1);
+  }
+
   console.log('selftest OK');
 }
 

package/skills/adia-release/scripts/dispatch-publish.mjs

@@ -20,25 +20,14 @@
 import { execSync } from 'node:child_process';
 import process from 'node:process';
 import { assertMonorepoRoot } from './assert-monorepo-root.mjs';
+import { PACKAGE_NAMES } from './package-paths.mjs';
 
 // Instance data — fork-configurable. The npm scope the 11 packages publish under.
 // Default preserves @adia-ai behavior; override via --scope or $ADIA_NPM_SCOPE.
 const DEFAULT_SCOPE = '@adia-ai';
 
-const PACKAGES = [
-  'web-components',
-  'web-modules',
-  'llm',
-  'a2ui-runtime',
-  'a2ui-compose',
-  'a2ui-corpus',
-  'a2ui-mcp',
-  'a2ui-retrieval',
-  'a2ui-validator',
-  // Plugins joined the lockstep 2026-07-15 (check-lockstep.mjs POLICY note).
-  'adia-ui-factory',
-  'adia-ui-forge',
-];
+// Single-sourced roster (H3, package-paths.mjs); order = dispatch order.
+const PACKAGES = PACKAGE_NAMES;
 
 function parseArgs(argv) {
   const args = {

package/skills/adia-release/scripts/gate-roster.mjs

@@ -23,7 +23,10 @@ export const GATE_ROSTER = [
   { n: 1,  cmd: 'node scripts/build/components.mjs --verify', what: 'yaml ↔ sidecar ↔ .d.ts' },
   { n: 2,  cmd: 'npm run verify:traits',                      what: 'trait coverage' },
   { n: 3,  cmd: 'npm run check:lockstep',                     what: 'version coherence' },
-  { n: 4,  cmd: 'npm run test:unit',                          what: 'vitest' },
+  // Serial on purpose: heavy web-modules suites flake under full parallelism
+  // ("drain loop exceeded 100 iterations") — gates-catalog §Cat 8 names the
+  // sequential run as the source of truth; the gate now IS that run (H5).
+  { n: 4,  cmd: 'npm run test:unit:serial',                   what: 'vitest (serial — the source of truth)' },
   { n: 5,  cmd: 'npm run typecheck',                          what: 'tsc --noEmit' },
   { n: 6,  cmd: 'npm run check:demo-shells',                  what: 'demo imports cover composes:' },
   { n: 7,  cmd: 'npm run check:lightningcss-build',           what: 'CSS minifies' },
@@ -37,6 +40,11 @@ export const GATE_ROSTER = [
   { n: 15, cmd: 'npm run check:links',                         what: 'intra-repo links' },
   { n: 16, cmd: 'npm run eval:diff -- --engine zettel',        what: 'eval floors' },
   { n: 17, cmd: 'npm run dogfood:status',                      what: 'P0/P1 dogfood floor' },
+  // versionArg: the runner appends ` --version X.Y.Z` (release-pack knows the
+  // cut version; the roster stays a static list). Objective half of the
+  // v0.7.13-retro hygiene checker — README CDN pins / "Current version"
+  // claims vs the cut version; branch/worktree limbo prints as warns (H2).
+  { n: 18, cmd: 'node scripts/release/check-cut-hygiene.mjs',  what: 'README CDN-pin + version currency', versionArg: true },
 ];
 
 // -- CLI ------------------------------------------------------------------

package/skills/adia-release/scripts/package-paths.mjs

@@ -23,6 +23,44 @@
 import fs from 'node:fs';
 import path from 'node:path';
 
+// ─── THE package roster — single source of truth (H3, 2026-07-19) ─────────
+//
+// The 11-package lockstep list was re-declared in ~8 files (bump, tag-lockstep,
+// dispatch-publish, release-pack, check-release, check-lockstep,
+// check-release-docs, generate-release-notes), each carrying its own
+// name/path projection — adding the 12th package meant 8 hand-edits, and the
+// gate-roster.mjs incident (release-pack silently running 12 of 17 gates)
+// proved what list-drift does. Same fix, same pattern: ONE list here, every
+// consumer projects from it.
+//
+// This module lives in the SKILL scripts dir deliberately: skill scripts must
+// work from the installed plugin cache (CLAUDE_PLUGIN_ROOT), where repo
+// modules aren't importable — but repo scripts (scripts/release/*) always run
+// in-repo and CAN import this by its stable in-repo path. The asymmetry
+// decides the home.
+//
+// Order is the canonical publish/tag order (release-pack's historical order);
+// consumers needing a different ordering (check-lockstep sorts by path for
+// stable output) re-sort locally.
+export const PACKAGE_ROSTER = [
+  { name: 'web-components',  dir: 'packages/web-components' },
+  { name: 'web-modules',     dir: 'packages/web-modules' },
+  { name: 'llm',             dir: 'packages/llm' },
+  { name: 'a2ui-runtime',    dir: 'packages/a2ui/runtime' },
+  { name: 'a2ui-compose',    dir: 'packages/a2ui/compose' },
+  { name: 'a2ui-corpus',     dir: 'packages/a2ui/corpus' },
+  { name: 'a2ui-mcp',        dir: 'packages/a2ui/mcp' },
+  { name: 'a2ui-retrieval',  dir: 'packages/a2ui/retrieval' },
+  { name: 'a2ui-validator',  dir: 'packages/a2ui/validator' },
+  // Plugins joined the lockstep 2026-07-15 (check-lockstep.mjs POLICY note);
+  // each carries a .claude-plugin/plugin.json that bumps with package.json.
+  { name: 'adia-ui-factory', dir: 'packages/plugins/adia-ui-factory', plugin: true },
+  { name: 'adia-ui-forge',   dir: 'packages/plugins/adia-ui-forge',   plugin: true },
+];
+
+export const PACKAGE_NAMES = PACKAGE_ROSTER.map((p) => p.name);
+export const PACKAGE_DIRS = PACKAGE_ROSTER.map((p) => p.dir);
+
 // Resolve a package arg to its on-disk directory under packages/, accepting
 // BOTH the name form (`a2ui-corpus`) and the path form (`a2ui/corpus`).
 // Returns the resolved relative directory (e.g. `a2ui/corpus`); does not

package/skills/adia-release/scripts/pr-bridge.mjs

@@ -0,0 +1,316 @@
+#!/usr/bin/env node
+// pr-bridge.mjs — babysit a release PR from push to merged main (the cut's
+// two-phase bridge, mechanized).
+//
+// The cut modes of release-pack.mjs stop at the release commit (invariant 3:
+// release commits land via PR, never a direct push to main). The bridge from
+// there to `--mode handoff` — push the branch, open the PR, wait out CI,
+// merge, re-baseline main — was the release cycle's last hand-carried leg
+// (the operator babysat it on every cut). This script mechanizes EXACTLY the
+// documented house flow (cut-procedure.md §5.7), no policy expansion:
+//
+//   MERGES only when ALL of:
+//     - every non-fail-soft check has landed SUCCESS (jobs whose name carries
+//       the repo's "(fail-soft)" marker are advisory — reported, never gating,
+//       matching §5.7's "required checks (fail-soft jobs excluded)")
+//     - zero unresolved review threads (admin merge bypasses required review
+//       but NOT unresolved threads — repo-verified behavior)
+//     - no CHANGES_REQUESTED review decision
+//     - GitHub reports the PR MERGEABLE
+//   WAITS while anything is still pending/queued/UNKNOWN (up to --timeout).
+//   STOPS (exit 1, full evidence, no mutation) on anything else: a failed
+//   check, an unresolved thread, changes requested, a merge conflict, or
+//   timeout. It never force-merges past a red or contested state — a stop
+//   here is a human's turn, by design.
+//
+// Usage:
+//   node pr-bridge.mjs --branch release/v0.8.8 \
+//     --title "release: v0.8.8 lockstep" --body-file /tmp/pr-body.md
+//   node pr-bridge.mjs --branch <existing-pr-branch>   # reuses the open PR
+//   node pr-bridge.mjs selftest
+//
+// Flags:
+//   --poll-interval <s>   seconds between polls (default 30)
+//   --timeout <s>         max seconds to wait for pending checks (default 2400)
+//   --dry                 report the current decision for the PR and exit;
+//                         no push, no create, no merge
+//
+// Exit: 0 merged + main re-baselined · 1 stopped (evidence printed) · 2 bad args.
+//
+// Part of the adia-release skill. Registered in CI's "Plugin bin selftests".
+
+import { execSync, execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import process from 'node:process';
+import { assertMonorepoRoot } from './assert-monorepo-root.mjs';
+
+const REPO = process.cwd();
+
+function parseArgs(argv) {
+  const args = {
+    branch: null, title: null, bodyFile: null,
+    pollInterval: 30, timeout: 2400, dry: false,
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const k = argv[i];
+    if (k === '--branch') args.branch = argv[++i];
+    else if (k === '--title') args.title = argv[++i];
+    else if (k === '--body-file') args.bodyFile = argv[++i];
+    else if (k === '--poll-interval') args.pollInterval = Number(argv[++i]);
+    else if (k === '--timeout') args.timeout = Number(argv[++i]);
+    else if (k === '--dry') args.dry = true;
+    else if (k === '-h' || k === '--help') { help(); process.exit(0); }
+  }
+  if (!args.branch) {
+    console.error('error: --branch is required (see --help)');
+    process.exit(2);
+  }
+  if (!Number.isFinite(args.pollInterval) || args.pollInterval < 5 ||
+      !Number.isFinite(args.timeout) || args.timeout < args.pollInterval) {
+    console.error('error: --poll-interval must be ≥5s and --timeout ≥ --poll-interval');
+    process.exit(2);
+  }
+  return args;
+}
+
+function help() {
+  console.log(`Usage:
+  node pr-bridge.mjs --branch release/vX.Y.Z --title "release: vX.Y.Z lockstep" --body-file <path>
+  node pr-bridge.mjs --branch <branch-with-open-pr>          # reuse the PR
+  node pr-bridge.mjs --branch <branch> --dry                 # decision only
+Flags: --poll-interval <s=30> --timeout <s=2400> --dry`);
+}
+
+function sh(cmd) {
+  return execSync(cmd, { cwd: REPO, encoding: 'utf8' }).trim();
+}
+
+// No-shell variant for every call that carries an operator-supplied value
+// (branch, title, body path) — reviewer finding #2: string interpolation left
+// `$(…)`/backticks live inside double quotes and broke on metachar branch
+// names. execFileSync + arg array = no shell, no expansion, no quoting bugs.
+function shFile(cmd, argv) {
+  return execFileSync(cmd, argv, { cwd: REPO, encoding: 'utf8' }).trim();
+}
+
+// ── The decision predicate — pure, selftest-locked ────────────────
+// state: {
+//   checks: [{ name, status, conclusion }]   normalized check runs + contexts
+//   unresolvedThreads: number
+//   reviewDecision: 'APPROVED' | 'CHANGES_REQUESTED' | 'REVIEW_REQUIRED' | null
+//   mergeable: 'MERGEABLE' | 'CONFLICTING' | 'UNKNOWN'
+// }
+// → { action: 'merge' | 'wait' | 'stop', reasons: [string] }
+//
+// Gating checks = every check whose name does NOT carry the "(fail-soft)"
+// marker (the repo's own advisory-job convention). NEUTRAL and SKIPPED count
+// as pass; anything not landed counts as pending; every other conclusion is
+// a failure. CHANGES_REQUESTED, unresolved threads, and CONFLICTING always
+// stop — no flag overrides them.
+export const FAIL_SOFT_RE = /fail-soft/i;
+const PASS = new Set(['SUCCESS', 'NEUTRAL', 'SKIPPED']);
+const PENDING = new Set(['PENDING', 'QUEUED', 'IN_PROGRESS', 'WAITING', 'REQUESTED', 'EXPECTED', '']);
+
+export function bridgeDecision(state) {
+  const reasons = [];
+  let pending = false;
+  let gatingLanded = 0;
+
+  for (const c of state.checks) {
+    if (FAIL_SOFT_RE.test(c.name)) continue; // advisory by convention
+    const landed = (c.status || '').toUpperCase() === 'COMPLETED' || c.conclusion;
+    const concl = (c.conclusion || c.status || '').toUpperCase();
+    if (!landed || PENDING.has(concl)) { pending = true; continue; }
+    if (!PASS.has(concl)) reasons.push(`check '${c.name}' landed ${concl}`);
+    else gatingLanded++;
+  }
+  if (state.reviewDecision === 'CHANGES_REQUESTED') reasons.push('a review requests changes');
+  if (state.unresolvedThreads > 0) reasons.push(`${state.unresolvedThreads} unresolved review thread(s) — admin merge cannot bypass these`);
+  if (state.mergeable === 'CONFLICTING') reasons.push('PR is CONFLICTING with the base branch');
+
+  if (reasons.length > 0) return { action: 'stop', reasons };
+  if (pending || state.mergeable === 'UNKNOWN') return { action: 'wait', reasons: ['checks or mergeability still pending'] };
+  // Never merge on an empty gating set (reviewer finding #1): "nothing failed"
+  // must not pass for "something passed" — a fresh PR's rollup can be briefly
+  // empty (or carry only advisory fail-soft jobs) while CI spins up, and this
+  // window would otherwise admin-merge with ZERO verified checks. WAIT (not
+  // stop): the checks appear within moments, or the timeout reports it.
+  if (gatingLanded === 0) {
+    return { action: 'wait', reasons: ['no gating check has landed SUCCESS yet — refusing to merge on an empty check set'] };
+  }
+  return { action: 'merge', reasons: [] };
+}
+
+// ── GitHub reads ──────────────────────────────────────────────────
+function readPrState(prNumber) {
+  const view = JSON.parse(sh(
+    `gh pr view ${prNumber} --json state,mergeable,reviewDecision,statusCheckRollup,headRefName,baseRefName`,
+  ));
+  const checks = (view.statusCheckRollup || []).map((c) => ({
+    name: c.name || c.context || '?',
+    status: c.status || c.state || '',
+    conclusion: c.conclusion || (c.state === 'SUCCESS' ? 'SUCCESS' : c.state === 'FAILURE' || c.state === 'ERROR' ? 'FAILURE' : ''),
+  }));
+  const threads = JSON.parse(sh(
+    `gh api graphql -f query='query($n:Int!){repository(owner:"${OWNER}",name:"${NAME}"){pullRequest(number:$n){reviewThreads(first:100){nodes{isResolved path line}}}}}' -F n=${prNumber}`,
+  )).data.repository.pullRequest.reviewThreads.nodes;
+  return {
+    state: view.state,
+    headRefName: view.headRefName,
+    baseRefName: view.baseRefName,
+    checks,
+    unresolvedThreads: threads.filter((t) => !t.isResolved).length,
+    unresolvedList: threads.filter((t) => !t.isResolved).map((t) => `${t.path}:${t.line}`),
+    reviewDecision: view.reviewDecision || null,
+    mergeable: view.mergeable || 'UNKNOWN',
+  };
+}
+
+function printEvidence(st) {
+  console.log(`  checks (${st.checks.length}):`);
+  for (const c of st.checks) {
+    const soft = FAIL_SOFT_RE.test(c.name) ? ' [advisory]' : '';
+    console.log(`    ${c.name}: ${c.status} ${c.conclusion}${soft}`);
+  }
+  console.log(`  unresolved threads: ${st.unresolvedThreads}${st.unresolvedThreads ? ' — ' + st.unresolvedList.join(', ') : ''}`);
+  console.log(`  reviewDecision: ${st.reviewDecision || '(none)'} · mergeable: ${st.mergeable}`);
+}
+
+let OWNER = 'adiahealth';
+let NAME = 'gen-ui-kit';
+
+// ── Main flow ─────────────────────────────────────────────────────
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  assertMonorepoRoot(REPO);
+  const slug = JSON.parse(sh('gh repo view --json nameWithOwner')).nameWithOwner;
+  [OWNER, NAME] = slug.split('/');
+
+  // Locate or create the PR for the branch.
+  const existing = JSON.parse(
+    shFile('gh', ['pr', 'list', '--head', args.branch, '--state', 'open', '--json', 'number,title']));
+  let prNumber;
+  if (existing.length > 0) {
+    prNumber = existing[0].number;
+    console.log(`[pr-bridge] reusing open PR #${prNumber} for ${args.branch} ("${existing[0].title}")`);
+  } else if (args.dry) {
+    console.error(`[pr-bridge] --dry: no open PR for ${args.branch}; nothing to report`);
+    process.exit(1);
+  } else {
+    if (!args.title || !args.bodyFile) {
+      console.error('error: no open PR for this branch — --title and --body-file are required to create one');
+      process.exit(2);
+    }
+    if (!fs.existsSync(args.bodyFile)) {
+      console.error(`error: body file not found: ${args.bodyFile}`);
+      process.exit(2);
+    }
+    // Push the branch (idempotent if already pushed), then create.
+    shFile('git', ['push', '-u', 'origin', args.branch]);
+    const url = shFile('gh', ['pr', 'create', '--base', 'main', '--head', args.branch, '--title', args.title, '--body-file', args.bodyFile]);
+    prNumber = Number(url.split('/').pop());
+    console.log(`[pr-bridge] opened PR #${prNumber}: ${url}`);
+  }
+
+  // Poll until the predicate resolves.
+  const deadline = Date.now() + args.timeout * 1000;
+  for (;;) {
+    const st = readPrState(prNumber);
+    if (st.state === 'MERGED') {
+      console.log(`[pr-bridge] PR #${prNumber} is already merged`);
+      break;
+    }
+    if (st.state !== 'OPEN') {
+      console.error(`[pr-bridge] STOP — PR #${prNumber} is ${st.state}`);
+      process.exit(1);
+    }
+    const d = bridgeDecision(st);
+    console.log(`\n[pr-bridge] ${new Date().toISOString()} — decision: ${d.action.toUpperCase()}`);
+    printEvidence(st);
+
+    if (args.dry) {
+      console.log(`[pr-bridge] --dry: would ${d.action}${d.reasons.length ? ` (${d.reasons.join('; ')})` : ''}`);
+      process.exit(d.action === 'stop' ? 1 : 0);
+    }
+    if (d.action === 'stop') {
+      console.error(`\n[pr-bridge] STOP — not merging PR #${prNumber}:`);
+      for (const r of d.reasons) console.error(`  ✗ ${r}`);
+      console.error('  This state needs a human (or a fix pushed to the branch); pr-bridge never merges past it.');
+      process.exit(1);
+    }
+    if (d.action === 'merge') {
+      console.log(`\n[pr-bridge] all gates green — merging PR #${prNumber} (admin merge per house flow §5.7)`);
+      sh(`gh pr merge ${prNumber} --admin --merge --delete-branch`);
+      break;
+    }
+    if (Date.now() > deadline) {
+      console.error(`\n[pr-bridge] STOP — timeout after ${args.timeout}s with checks still pending. Re-run to resume waiting.`);
+      process.exit(1);
+    }
+    await new Promise((r) => setTimeout(r, args.pollInterval * 1000));
+  }
+
+  // Re-baseline main and prove the merge landed.
+  sh('git checkout main');
+  sh('git pull origin main');
+  const mergedSha = JSON.parse(sh(`gh pr view ${prNumber} --json mergeCommit`)).mergeCommit?.oid;
+  if (mergedSha) {
+    sh(`git merge-base --is-ancestor ${mergedSha} HEAD`); // throws if not
+    console.log(`[pr-bridge] main re-baselined at ${sh('git rev-parse --short HEAD')} (merge ${mergedSha.slice(0, 9)} confirmed in history)`);
+  } else {
+    // Reviewer finding #4: never skip the landing proof SILENTLY.
+    console.log(`[pr-bridge] note: GitHub has not populated mergeCommit yet — landing proof skipped (main was pulled; verify with \`git log\` if it matters)`);
+  }
+  // Local branch cleanup (remote side handled by --delete-branch).
+  try { shFile('git', ['branch', '-D', args.branch]); } catch { /* already gone */ }
+  console.log(`[pr-bridge] done — PR #${prNumber} merged, main current. Resume with --mode handoff.`);
+}
+
+// ── Selftest — the predicate is the load-bearing part ─────────────
+function selftest() {
+  const ck = (name, status, conclusion) => ({ name, status, conclusion });
+  const base = { unresolvedThreads: 0, reviewDecision: 'REVIEW_REQUIRED', mergeable: 'MERGEABLE' };
+  const cases = [
+    ['all green → merge',
+      { ...base, checks: [ck('Static checks + MCP smoke', 'COMPLETED', 'SUCCESS'), ck('CodeRabbit', '', 'SUCCESS')] }, 'merge'],
+    ['fail-soft failure is advisory → merge',
+      { ...base, checks: [ck('Static checks + MCP smoke', 'COMPLETED', 'SUCCESS'), ck('Audit health (fail-soft)', 'COMPLETED', 'FAILURE')] }, 'merge'],
+    ['EMPTY check set → wait, never blind-merge (reviewer finding #1)',
+      { ...base, checks: [] }, 'wait'],
+    ['fail-soft-only set → wait, zero gating checks verified (reviewer finding #1)',
+      { ...base, checks: [ck('Audit health (fail-soft)', 'COMPLETED', 'SUCCESS')] }, 'wait'],
+    ['gating check failed → stop',
+      { ...base, checks: [ck('Static checks + MCP smoke', 'COMPLETED', 'FAILURE')] }, 'stop'],
+    ['gating check pending → wait',
+      { ...base, checks: [ck('Static checks + MCP smoke', 'IN_PROGRESS', '')] }, 'wait'],
+    ['status-context pending → wait',
+      { ...base, checks: [ck('CodeRabbit', 'PENDING', '')] }, 'wait'],
+    ['unresolved thread → stop even when green',
+      { ...base, unresolvedThreads: 2, checks: [ck('Static checks + MCP smoke', 'COMPLETED', 'SUCCESS')] }, 'stop'],
+    ['changes requested → stop even when green',
+      { ...base, reviewDecision: 'CHANGES_REQUESTED', checks: [ck('Static checks + MCP smoke', 'COMPLETED', 'SUCCESS')] }, 'stop'],
+    ['conflicting → stop',
+      { ...base, mergeable: 'CONFLICTING', checks: [ck('Static checks + MCP smoke', 'COMPLETED', 'SUCCESS')] }, 'stop'],
+    ['mergeable UNKNOWN with green checks → wait (never merge blind)',
+      { ...base, mergeable: 'UNKNOWN', checks: [ck('Static checks + MCP smoke', 'COMPLETED', 'SUCCESS')] }, 'wait'],
+    ['SKIPPED + NEUTRAL count as pass → merge',
+      { ...base, checks: [ck('a', 'COMPLETED', 'SKIPPED'), ck('b', 'COMPLETED', 'NEUTRAL')] }, 'merge'],
+    ['CANCELLED is a failure → stop',
+      { ...base, checks: [ck('Static checks + MCP smoke', 'COMPLETED', 'CANCELLED')] }, 'stop'],
+    ['failure + pending → stop wins (report now, not after the wait)',
+      { ...base, checks: [ck('a', 'COMPLETED', 'FAILURE'), ck('b', 'IN_PROGRESS', '')] }, 'stop'],
+  ];
+  let failed = 0;
+  for (const [label, state, want] of cases) {
+    const got = bridgeDecision(state).action;
+    const ok = got === want;
+    if (!ok) failed++;
+    console.log(`${ok ? 'PASS' : 'FAIL'}  ${label}: expected ${want}, got ${got}`);
+  }
+  console.log(failed === 0 ? '\nselftest OK' : `\nselftest: ${failed} failure(s)`);
+  process.exit(failed === 0 ? 0 : 1);
+}
+
+const argv = process.argv.slice(2);
+if (argv[0] === 'selftest') selftest();
+else main().catch((e) => { console.error(e.message || e); process.exit(1); });

package/skills/adia-release/scripts/release-pack.mjs

@@ -68,7 +68,7 @@ import os from 'node:os';
 import path from 'node:path';
 import process from 'node:process';
 import { assertMonorepoRoot } from './assert-monorepo-root.mjs';
-import { resolvePackageChangelog } from './package-paths.mjs';
+import { resolvePackageChangelog, PACKAGE_NAMES, PACKAGE_ROSTER } from './package-paths.mjs';
 import { GATE_ROSTER } from './gate-roster.mjs';
 
 const SCRIPT_DIR = path.dirname(new URL(import.meta.url).pathname);
@@ -80,11 +80,8 @@ const REPO = process.cwd();
 const DEFAULT_DEPLOY_HOST = 'ui-kit.exe.xyz';
 const DEFAULT_NPM_SCOPE = '@adia-ai';
 
-const PACKAGES = ['web-components', 'web-modules', 'llm', 'a2ui-runtime',
-                  'a2ui-compose', 'a2ui-corpus', 'a2ui-mcp', 'a2ui-retrieval',
-                  'a2ui-validator',
-                  // Plugins joined the lockstep 2026-07-15 (check-lockstep.mjs POLICY note).
-                  'adia-ui-factory', 'adia-ui-forge'];
+// Single-sourced roster (H3, package-paths.mjs); order = publish order.
+const PACKAGES = PACKAGE_NAMES;
 
 function parseArgs(argv) {
   const args = {
@@ -253,11 +250,19 @@ function step3PreFlight(args) {
   }
   console.log(`\n=== Step 3 — Pre-flight gates (${GATE_ROSTER.length}-gate roster — gate-roster.mjs) ===`);
   for (const g of GATE_ROSTER) {
-    console.log(`\n  ${g.n}/${GATE_ROSTER.length}. ${g.cmd}   # ${g.what}`);
+    // versionArg gates take a MODE-DEPENDENT version (both directions bit
+    // the first 0.8.8 run): cut modes run pre-flight PRE-BUMP, where the
+    // README "Current version" claim still equals the PREVIOUS version (the
+    // bump moves it in Step 4; Step 4g then re-proves at the cut version) —
+    // while handoff runs POST-MERGE, where the claim already equals the CUT
+    // version and validating at previous fails by construction.
+    const hygieneVersion = args.mode === 'handoff' ? args.version : args.previous;
+    const cmd = g.versionArg ? `${g.cmd} --version ${hygieneVersion}` : g.cmd;
+    console.log(`\n  ${g.n}/${GATE_ROSTER.length}. ${cmd}   # ${g.what}`);
     try {
-      sh(g.cmd, args, { stdio: 'inherit' });
+      sh(cmd, args, { stdio: 'inherit' });
     } catch (e) {
-      console.error(`\n  ✗ FAILED (${g.n}/${GATE_ROSTER.length}): ${g.cmd}`);
+      console.error(`\n  ✗ FAILED (${g.n}/${GATE_ROSTER.length}): ${cmd}`);
       console.error('  Pre-flight aborted. Fix the gate failure before proceeding.');
       console.error('  See references/gates-catalog.md for failure-mode → recovery.');
       process.exit(1);
@@ -339,6 +344,15 @@ function step4PromoteAndBump(args) {
   // delete/retag rounds discovering the same gaps only after tagging.
   console.log('\n  Step 4f — pre-tag coverage (+auto-fix) with the authoritative F-N1 matcher:');
   sh(`node scripts/release/check-release.mjs --pending-version ${args.version} --fix`, args);
+
+  // Step 4g — re-run the versionArg gates at the CUT version, post-bump: the
+  // pre-flight ran them against the previous version (the README claim can't
+  // equal the cut version before bump.mjs moves it); this run proves the bump
+  // moved every cross-file reference to the new version.
+  console.log('\n  Step 4g — cut-hygiene at the cut version (post-bump proof):');
+  for (const g of GATE_ROSTER.filter((g) => g.versionArg)) {
+    sh(`${g.cmd} --version ${args.version}`, args);
+  }
 }
 
 // ── Step 5 — Commit ──────────────────────────────────────────────
@@ -351,18 +365,18 @@ function step5Commit(args) {
   sh('git reset HEAD >/dev/null 2>&1 || true', args);
   const releaseFiles = [
     'package-lock.json',
-    ...PACKAGES.flatMap((p) => {
-      // Path map covers all three package families — the plugins joined the
-      // lockstep 2026-07-15 and live under packages/plugins/ with a sibling
-      // .claude-plugin/plugin.json that bump.mjs also moves (the
-      // /plugin-update cache key); factory additionally pins a2ui-mcp in
-      // .mcp.json (SKILL invariant 8).
-      const dir = p.startsWith('a2ui-') ? `packages/a2ui/${p.replace('a2ui-', '')}`
-        : p.startsWith('adia-ui-') ? `packages/plugins/${p}`
-        : `packages/${p}`;
+    // Root README's "Current version" claim — bump.mjs moves it per-cut
+    // (REPO_PINNED_REFS); gate 18 (check-cut-hygiene doc-currency) exact-matches
+    // it against the cut version, so it must ride the release commit.
+    'README.md',
+    ...PACKAGE_ROSTER.flatMap(({ name, dir, plugin }) => {
+      // Roster-driven (H3): each package stages its manifest + CHANGELOG;
+      // plugins also stage .claude-plugin/plugin.json (the /plugin-update
+      // cache key, moved by bump.mjs); factory additionally pins a2ui-mcp in
+      // .mcp.json (SKILL invariant 8 — bump.mjs moves the pin too).
       const files = [`${dir}/package.json`, `${dir}/CHANGELOG.md`];
-      if (p.startsWith('adia-ui-')) files.push(`${dir}/.claude-plugin/plugin.json`);
-      if (p === 'adia-ui-factory') files.push(`${dir}/.mcp.json`);
+      if (plugin) files.push(`${dir}/.claude-plugin/plugin.json`);
+      if (name === 'adia-ui-factory') files.push(`${dir}/.mcp.json`);
       return files;
     }),
   ];
@@ -579,9 +593,11 @@ async function main() {
     console.log(`
 ✓ release commit ready — STOPPING per invariant 3 (release commits land via PR).
 
-  Next (manual, or your CI-babysitting flow):
-    git push -u origin <release/v${args.version} branch>
-    gh pr create …            # release PR → CI → merge
+  Next — mechanized bridge (pushes, opens the PR, waits out CI, merges only
+  green + zero unresolved threads, re-baselines main; stops on anything else):
+    node ${SCRIPT_DIR}/pr-bridge.mjs --branch release/v${args.version} \\
+      --title "release: v${args.version} lockstep" --body-file <path>
+  (or the manual flow: git push -u origin release/v${args.version} && gh pr create … && merge)
   Then resume from post-merge main:
     git checkout main && git pull origin main
     node release-pack.mjs --mode handoff --version ${args.version} --date ${args.date} \\

package/skills/adia-release/scripts/tag-lockstep.mjs

@@ -15,22 +15,11 @@
 import { execSync } from 'node:child_process';
 import process from 'node:process';
 import { assertMonorepoRoot } from './assert-monorepo-root.mjs';
+import { PACKAGE_NAMES } from './package-paths.mjs';
 
-const PER_PACKAGE_NAMES = [
-  'web-components',
-  'web-modules',
-  'llm',
-  'a2ui-runtime',
-  'a2ui-compose',
-  'a2ui-corpus',
-  'a2ui-mcp',
-  'a2ui-retrieval',
-  'a2ui-validator',
-  // Plugins joined the lockstep 2026-07-15 (check-lockstep.mjs POLICY note);
-  // their `adia-ui-*-v*` tags trigger publish-adia-ui-{factory,forge}.yml.
-  'adia-ui-factory',
-  'adia-ui-forge',
-];
+// The roster is single-sourced in package-paths.mjs (H3) — the `adia-ui-*-v*`
+// tags trigger publish-adia-ui-{factory,forge}.yml like every other package.
+const PER_PACKAGE_NAMES = PACKAGE_NAMES;
 
 function parseArgs(argv) {
   const args = { version: null, at: null, deleteMode: false, dry: false, repo: process.cwd() };