@adia-ai/adia-ui-forge 0.8.3 → 0.8.5

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

@@ -9,10 +9,10 @@
 
 Two entry variants, converging at Step 5:
 
-- **Variant A — deploy handoff:** a peer pre-cut the release commit + CHANGELOG + bump + lockfile. Re-baseline, verify, then resume at Step 6 (tag).
+- **Variant A — deploy handoff:** a peer pre-cut the release commit + CHANGELOG + bump + lockfile. Re-baseline, verify, run **Step 4e** (release docs + team notes — the peer's cut may not have generated them, and the pretag gate blocks Step 6 without them), then resume at Step 6 (tag).
 - **Variant B — author from scratch:** source landed under `## [Unreleased]` with no bump. Do Step 4 (promotion + bump + lockfile), then the full tail.
 
-`scripts/release-pack.mjs` (bundled) mechanizes the sequence in two phases per invariant 3 — the cut modes stop at the release commit (PR → CI → merge happens between), `--mode handoff` runs tag→publish→deploy from post-merge main — with the three operator checkpoints preserved; the steps below are the manual/diagnostic form.
+`` `${CLAUDE_PLUGIN_ROOT}/skills/adia-release/scripts/release-pack.mjs` `` (bundled) mechanizes the sequence in two phases per invariant 3 — the cut modes stop at the release commit (PR → CI → merge happens between), `--mode handoff` runs tag→publish→deploy from post-merge main — with the three operator checkpoints preserved; the steps below are the manual/diagnostic form.
 
 | Step | Action | Mutates? |
 | --- | --- | --- |
@@ -27,7 +27,7 @@ Two entry variants, converging at Step 5:
 | 7 | F-N1 release trip-wire; enrich CHANGELOGs on warns | If warns |
 | 8 | Push tags (one per push; `main` already merged) — **checkpoint 2 first** | Push |
 | 9 | Dispatch publish workflows; wait; verify registry — **checkpoint 3 first** | Publish |
-| 10 | GH releases + site deploy | Deploy |
+| 10 | GH releases + site deploy — **checkpoint 4 first** | Deploy |
 | 11 | Author release notes (default, not optional) | No |
 
 ---
@@ -96,9 +96,11 @@ npm run dogfood:status                         # 17 P0/P1 dogfood floor
 
 Any red → route via [`gates-catalog.md`](gates-catalog.md); fix at the source, re-run the narrowest gate, then re-run the full sequence. The canonical miss: a cut that ran 7 of the gates shipped a stale-embeddings defect that surfaced a day later and cost a tag-move recovery.
 
-## §Step 4 — (Variant B) Promote, bump, lockfile
+## §Step 4 — (Variant B, or ANY variant with uncommitted `[Unreleased]` content) Promote, bump, lockfile
 
-**4a. Promote** `## [Unreleased]` → `## [vX.Y.Z] — YYYY-MM-DD` per package (`scripts/promote-unreleased.mjs`); author fresh blocks for changed-but-unlogged packages; stub the pure ride-alongs (`scripts/insert-stub.mjs`). Classification recipe + shapes: [`changelog-discipline.md`](changelog-discipline.md).
+**Run 4a whenever a hand-authored `## [Unreleased]` section is still sitting uncommitted, not only on a strict Variant B.** `release-pack.mjs --mode cut` (a peer's pre-staged content, not yet promoted) needs it exactly as much as `--mode from-scratch` does — the v0.8.4 near-miss was `--mode cut` skipping this step entirely because the doc (and the script) only associated promotion with "from scratch". Both modes now run it and both hard-fail before the bump if any of the 11 packages still carries non-empty `[Unreleased]` content afterward.
+
+**4a. Promote** `## [Unreleased]` → `## [vX.Y.Z] — YYYY-MM-DD` per package (`` `${CLAUDE_PLUGIN_ROOT}/skills/adia-release/scripts/promote-unreleased.mjs` ``); author fresh blocks for changed-but-unlogged packages; stub the pure ride-alongs (`` `${CLAUDE_PLUGIN_ROOT}/skills/adia-release/scripts/insert-stub.mjs` ``). Classification recipe + shapes: [`changelog-discipline.md`](changelog-discipline.md).
 
 **4b. Bump.** PATCH vs MINOR: **MINOR is reserved for API-surface breaks only** (removed/renamed prop, attribute, slot, event, token, or tag). Visible behavior changes, re-scalings, and opt-in features stay PATCH; a CHANGELOG bullet saying "(MINOR behavior change)" is prose, not a semver directive. Unqualified "bump version" = PATCH; don't round-trip to ask. `node "${CLAUDE_PLUGIN_ROOT}/skills/adia-release/scripts/bump.mjs" --from X.Y.Z-1 --to X.Y.Z`. On a MINOR cut, also bump the internal `@adia-ai/*` `^ranges` separately (bump.mjs touches `"version"` fields only) — and a MINOR cut owes a MIGRATION GUIDE section ([`migration-guide-authoring.md`](migration-guide-authoring.md)).
 
@@ -106,6 +108,23 @@ Any red → route via [`gates-catalog.md`](gates-catalog.md); fix at the source,
 
 **4d.** `npm run check:lockstep` → `OK — all packages at X.Y.Z, all internal ranges at ^X.Y.0`.
 
+**4e. Release docs + team notes** (gated, not optional): review the entry
+files the release touches (root README/CHANGELOG, per-package READMEs —
+content currency is YOUR judgment; the gate only proves presence), then
+generate the team notes and land them IN the release commit:
+
+```bash
+node scripts/release/generate-release-notes.mjs --version X.Y.Z --write   # → docs/releases/vX.Y.Z.md
+node scripts/release/check-release-docs.mjs --version X.Y.Z               # must print OK
+```
+
+`check-release-docs` is enforced twice downstream — the
+`release-pretag-docs-gate` Claude Code hook (adia-forge plugin) denies
+tag-creation/tag-push/publish-dispatch commands until it passes, and
+`.githooks/pre-push` blocks release-tag pushes the same way (v0.8.4
+shipped tarballs with unpromoted `[Unreleased]` CHANGELOG headers because
+this class of check ran only after tagging).
+
 ## §Step 5 — Stage and commit (on a release branch)
 
 The release commit lands via PR, never a direct push to `main` (repo
@@ -118,7 +137,8 @@ allowlist (never `git add -A`; if peers may have pre-staged files,
 git -C "$REPO" checkout -b "release/vX.Y.Z"
 git -C "$REPO" reset HEAD >/dev/null 2>&1
 git -C "$REPO" add package-lock.json packages/*/package.json packages/*/CHANGELOG.md \
-  packages/a2ui/*/package.json packages/a2ui/*/CHANGELOG.md   # + in-scope source + Step-3.0 regen outputs
+  packages/a2ui/*/package.json packages/a2ui/*/CHANGELOG.md \
+  docs/releases/vX.Y.Z.md   # + in-scope source + Step-3.0 regen outputs
 git -C "$REPO" diff --cached --stat | tail -3   # count must match the allowlist
 ```
 
@@ -152,9 +172,22 @@ post-merge HEAD, so anything merged before tagging ships in the tarball.
 If unrelated PRs merged between yours and the tag step, that is fine: tag
 at HEAD is the invariant, and the window closes at the tag.
 
+## §Operator checkpoints — evidence-first, not a bare y/N
+
+Four checkpoints total (corrected on PR #289 review — this section previously said "three", missing the Step-10 deploy-dispatch confirm that already existed in the script). Each prints its evidence block BEFORE the prompt, never a bare confirm (H5, forge-campaign gh#268 audit — the prior shape asked "proceed? [y/N]" with nothing to judge it against). The prompt itself is a plain two-way gate, honestly: **yes proceeds** (the mutating step for that checkpoint runs); **anything else aborts** — the script exits cleanly having done nothing past that point. There is no in-script "enrich" path (a CodeRabbit finding on PR #289 caught this doc previously over-promising a three-way go/enrich/abort choice the code never implemented) — to enrich, abort, fix the thing the evidence surfaced (a CHANGELOG entry, a version mismatch), then re-run from that checkpoint; the evidence re-prints fresh against the fixed state.
+
+| Checkpoint | Evidence shown BEFORE the prompt | Why this evidence (not F-N1 at cp1) |
+| --- | --- | --- |
+| 1 — before tagging | The planned tag list (umbrella + 11 per-package) | F-N1 inspects tag commits — it has nothing to check until Step 6 creates them |
+| 2 — before pushing | The Step 7 F-N1 output (now real, against the just-created tags) + the tag list again | This is the FIRST point F-N1 evidence exists — showing it here, not at cp1, is why the step order (tag → F-N1 → cp2) is fixed |
+| 3 — before publishing | The current registry snapshot (per-package versions + `dist-tags.latest`) | Publish ordering is judged against what's LIVE right now, not an assumption |
+| 4 — before deploying the site | The `deploy-site.yml` dispatch itself as evidence (never a raw rsync) | Deploy is its own irreversible, outward-facing action distinct from publish |
+
+`release-pack.mjs` implements this: `checkpoint(label, evidence, autoConfirmed)` always prints `evidence` first, then `[CHECKPOINT] <label> — proceed? [y/N]`; `--yes` auto-confirms checkpoint 1 ONLY, `--push` gates checkpoint 2, `--publish` gates checkpoints 3 AND 4 (a single `--yes` used to flatten all of them — the defect this replaced). **F-N1 errors (not warns) hard-stop before checkpoint 2 even appears — no flag, including `--push`, skips this.** A cosmetic F-N1 warn does not hard-stop, but it also blocks `--push` from auto-confirming checkpoint 2 — only the interactive prompt may proceed past a warn (never past an error, which already exited).
+
 ## §Step 6 — Tag ← operator checkpoint 1 (before tagging)
 
-Show the operator the planned tag list + the F-N1 preview; proceed only on their go. Then tag **at `main`'s post-merge HEAD** (post-bump fixes belong in the tarball; the window's last merge is the tag point — exception: batch push tags each version at its own release-merge SHA):
+Show the operator the planned tag list; proceed only on their go (F-N1 can't run yet — see the table above). Then tag **at `main`'s post-merge HEAD** (post-bump fixes belong in the tarball; the window's last merge is the tag point — exception: batch push tags each version at its own release-merge SHA):
 
 ```bash
 node "${CLAUDE_PLUGIN_ROOT}/skills/adia-release/scripts/tag-lockstep.mjs" \
@@ -172,7 +205,8 @@ Per-package tags must be `✓ clean`; the umbrella-tag error is expected noise.
 ## §Step 8 — Push tags ← operator checkpoint 2 (before pushing tags)
 
 `main` is already on the remote (the release PR merged in Step 5.7) —
-only the tags push here. Show the tag list + confirm
+only the tags push here. Show the Step 7 F-N1 results + the tag list (the
+evidence block for this checkpoint — see the table above) + confirm
 `git rev-list --count origin/main..HEAD` is 0 (a non-zero count means
 local commits bypassed the PR flow — stop and route them through a PR
 first); on go:
@@ -189,7 +223,7 @@ git -C "$REPO" push origin vX.Y.Z        # umbrella last; triggers nothing
 
 ## §Step 9 — Publish ← operator checkpoint 3 (before publishing)
 
-For batch pushes, confirm ordering with the operator: **oldest version publishes and settles first** — `npm dist-tag latest` is set by publish order. Then:
+Show the current registry snapshot (per-package versions + `dist-tags.latest`) as this checkpoint's evidence. For batch pushes, confirm ordering with the operator against that snapshot: **oldest version publishes and settles first** — `npm dist-tag latest` is set by publish order. Then:
 
 ```bash
 node "${CLAUDE_PLUGIN_ROOT}/skills/adia-release/scripts/dispatch-publish.mjs" \
@@ -208,7 +242,7 @@ npm view @adia-ai/web-components dist-tags.latest   # must equal X.Y.Z
 
 Zero workflows fired after a tag push → [`recovery-paths.md`](recovery-paths.md) §Scenario 7.
 
-## §Step 10 — GH releases + site deploy
+## §Step 10 — GH releases + site deploy ← operator checkpoint 4 (before deploying)
 
 ```bash
 for pkg in <the 9>; do
@@ -220,7 +254,7 @@ gh workflow run "Deploy site (ui-kit.exe.xyz)" --repo adiahealth/gen-ui-kit --re
 
 Deploy discipline (the release tenant of the demo-site host; VM/service ops belong to the deploy skill, `adia-deploy`):
 
-- `deploy-site.yml` owns build → pre-flight verify → snapshot → rsync → post-deploy verify → auto-rollback; it builds from `main`, so the release commit must already be merged (§Step 5.7 guarantees this). A raw local rsync bypasses every one of those gates.
+- `deploy-site.yml` owns build → pre-flight verify → snapshot → rsync → post-deploy verify → auto-rollback; it builds from `main`, so the release commit must already be merged (§Step 5.7 guarantees this). A raw local rsync bypasses every one of those gates — `release-pack.mjs` dispatches the workflow (never rsyncs directly) behind its own confirm (H1, forge-campaign gh#268 audit: the script had drifted from this already-documented procedure).
 - **Verify deployed FILES, never SPA routes.** The docs site returns HTTP 200 + the same ~5 KB shell for *every* path; an unmatched route renders blank with no error. Curl a content file and grep for real bytes:
 
   ```bash

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

@@ -16,7 +16,7 @@ Row layout per gate: **What** · **Typical failure** · **Recovery**.
 
 - **What:** all 11 `@adia-ai/*` packages declare the same `version`; internal `@adia-ai/*` dep ranges match policy (`^X.Y.0` during PATCH cycles, bumped at MINOR).
 - **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 → `scripts/bump.mjs` (bundled with this skill); range drift → `npm run check:lockstep:fix` auto-aligns, then re-run.
+- **Recovery:** version drift → `` `${CLAUDE_PLUGIN_ROOT}/skills/adia-release/scripts/bump.mjs` ``; range drift → `npm run check:lockstep:fix` auto-aligns, then re-run.
 - **Why `^0.0.x` is forbidden:** npm pre-1.0 semver only widens the caret when major+minor aren't both zero — `^0.0.6` resolves to `>=0.0.6 <0.0.7`, locked to exactly 0.0.6. An internal dep pinned that way silently installs a *stale* sibling on every fresh `npm i` (this shipped a real ~4-day-latent bug before the lockstep policy). The `^X.Y.0` floor (Y≥1) widens correctly across patches; trust the gate, don't reason about caret semantics by hand. Moot at 1.0.0.
 
 ### `node scripts/release/check-release.mjs --all-pending` (F-N1, the release trip-wire)
@@ -24,7 +24,7 @@ Row layout per gate: **What** · **Typical failure** · **Recovery**.
 - **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: amend the release commit, delete + re-create the tags at the new SHA, re-run. Full discipline: [`changelog-discipline.md`](changelog-discipline.md) §F-N1 enrichment.
+- **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.
 
 ### `npm run check:changelog-coverage`
@@ -207,7 +207,7 @@ npm run check:demo-shells
 
 Add `verify:corpus` + `check:embeddings-fresh` if chunks were touched; `check:lightningcss-build` if CSS was touched; F-N1 if unpushed release tags exist.
 
-**Full pre-cut sweep** — the 17-gate roster in [`cut-procedure.md`](cut-procedure.md) §Step 3. ~90s wall time.
+**Full pre-cut sweep** — the 17-gate roster in [`cut-procedure.md`](cut-procedure.md) §Step 3, sourced from `` `${CLAUDE_PLUGIN_ROOT}/skills/adia-release/scripts/gate-roster.mjs` `` (the ONE list; `release-pack.mjs` imports and runs it in full — a subset run is impossible without editing that file). ~90s wall time.
 
 **Omnibus** — `npm run check` invokes everything. Heavy; use when re-baselining a stale checkout.
 

package/skills/adia-release/references/recovery-paths.md

@@ -24,6 +24,8 @@
 
 **Shape:** multiple unpushed `release(*): vX.Y.Z` commits since the last published tag; operator asks to "publish what's accumulated."
 
+`release-pack.mjs --mode batch` hard-rejects and points here rather than attempting this — each version tags at its OWN release-commit SHA (not `main`'s single post-merge HEAD) and publish order must be enforced across versions, which the single-version orchestrator has no model for. This IS the manual procedure; there is no mechanized alternative.
+
 **Resolution:**
 
 1. Order the release commits oldest → newest.
@@ -36,7 +38,7 @@
 
 **Shape:** source + CHANGELOG entries landed under `## [Unreleased]`, no bump, no release commit.
 
-**Resolution:** [`cut-procedure.md`](cut-procedure.md) Variant B; `scripts/promote-unreleased.mjs` mechanizes the heading swap; fresh blocks per [`changelog-discipline.md`](changelog-discipline.md) §Authoring.
+**Resolution:** [`cut-procedure.md`](cut-procedure.md) Variant B; `` `${CLAUDE_PLUGIN_ROOT}/skills/adia-release/scripts/promote-unreleased.mjs` `` mechanizes the heading swap; fresh blocks per [`changelog-discipline.md`](changelog-discipline.md) §Authoring.
 
 ## §Scenario 4 — `[Unreleased]` extension (early cut + entangled fix)
 
@@ -72,7 +74,7 @@ node "${CLAUDE_PLUGIN_ROOT}/skills/adia-release/scripts/dispatch-publish.mjs" \
   --version X.Y.Z --verify-triggered   # re-dispatches ONLY packages with no run; idempotent
 ```
 
-For a batch, preserve npm-latest ordering (`--after <prev>`). Verify against the registry, not the workflows. **Prevention:** push tags one-at-a-time ([`cut-procedure.md`](cut-procedure.md) §Step 8); `release-pack.mjs` does this automatically and follows with `--verify-triggered`.
+For a batch, preserve npm-latest ordering (`--after <prev>`). Verify against the registry, not the workflows. **Prevention:** push tags one-at-a-time ([`cut-procedure.md`](cut-procedure.md) §Step 8); `` `${CLAUDE_PLUGIN_ROOT}/skills/adia-release/scripts/release-pack.mjs` `` does this automatically and follows with `--verify-triggered`.
 
 ## §Scenario 8 — Cut on the wrong branch
 

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

@@ -140,4 +140,35 @@ function main() {
   }
 }
 
-main();
+// Fixture-locked proof of the core transform, entirely in-memory (no real
+// package.json files touched) — the `dry: true` path below asserts the
+// script never calls fs.writeFileSync by pointing at a path whose directory
+// doesn't exist; a latent write bug would throw ENOENT instead of passing.
+function selftest() {
+  const fake = [{
+    pkg: 'packages/web-components',
+    path: '/nonexistent-fixture-dir/package.json',
+    txt: '{\n  "name": "@adia-ai/web-components",\n  "version": "0.8.4"\n}\n',
+    version: '0.8.4',
+  }];
+  if (!validateAllAtFrom(fake, '0.8.4')) {
+    console.error('selftest FAIL: validateAllAtFrom rejected a matching version'); process.exit(1);
+  }
+  if (validateAllAtFrom(fake, '0.8.3')) {
+    console.error('selftest FAIL: validateAllAtFrom accepted a mismatched version'); process.exit(1);
+  }
+  const bumped = bumpAll(fake, '0.8.4', '0.8.5', true /* dry */);
+  if (bumped !== fake.length) {
+    console.error('selftest FAIL: bumpAll(dry) did not report all packages bumped'); process.exit(1);
+  }
+  // Corrupted package.json (regex has nothing to match) must be caught, not silently skipped.
+  const corrupted = [{ pkg: 'packages/x', path: '/nonexistent-fixture-dir/x/package.json', txt: '{}', version: '0.8.4' }];
+  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);
+  }
+  console.log('selftest OK');
+}
+
+const topArgv = process.argv.slice(2);
+if (topArgv[0] === 'selftest') selftest();
+else main();

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

@@ -199,19 +199,57 @@ async function main() {
   }
   console.log(`\n[dispatch] ${succeeded}/${PACKAGES.length} dispatched ${args.dry ? '(dry)' : ''}`);
 
-  if (!args.dry) {
-    console.log(`\n[next] wait for workflows to settle:`);
-    console.log(`  until [ "$(gh run list --workflow=publish-a2ui-validator.yml --limit 1 --json status -q '.[0].status')" = "completed" ]; do sleep 5; done`);
-    console.log(`\n[next] verify all 11 succeeded:`);
-    console.log(`  for pkg in ${PACKAGES.join(' ')}; do`);
-    console.log(`    gh run list --workflow=publish-$pkg.yml --limit 1 --json conclusion -q '.[0].conclusion'`);
-    console.log(`  done`);
+  // defect-2 (forge-campaign gh#268 audit): this used to print a "[next] wait
+  // for / verify" block phrased as a to-do EVEN THOUGH the dispatch above
+  // already fired — an operator's agent read it as "publish hasn't happened
+  // yet" and went back to refine CHANGELOGs post-publish. State what WAS
+  // done; offer monitoring as optional, not required.
+  if (!args.dry && succeeded > 0) {
+    // CodeRabbit (PR #289): "RUNNING" overclaimed — `gh workflow run` only
+    // confirms the dispatch was SUBMITTED; the run may still queue, or fail
+    // to materialize (bad ref, disabled workflow). "dispatched" is what we
+    // actually know happened; no further action is still true either way —
+    // the point stands, the verb doesn't overreach.
+    console.log(`\n✓ ${succeeded} publish workflow(s) dispatched above — no further action required.`);
+    console.log('  Optional — monitor until they settle:');
+    console.log(`    until [ "$(gh run list --workflow=publish-a2ui-validator.yml --limit 1 --json status -q '.[0].status')" = "completed" ]; do sleep 5; done`);
+    console.log('  Optional — check each conclusion once settled:');
+    console.log(`    for pkg in ${PACKAGES.join(' ')}; do`);
+    console.log(`      gh run list --workflow=publish-$pkg.yml --limit 1 --json conclusion -q '.[0].conclusion'`);
+    console.log(`    done`);
   }
 
   if (succeeded !== PACKAGES.length) process.exit(1);
 }
 
-main().catch((e) => {
-  console.error(`error: ${e.message}`);
-  process.exit(1);
-});
+// dry mode never shells out (run()/dispatch() short-circuit before
+// execSync), so this exercises the real functions without touching gh/npm.
+function selftest() {
+  let allOk = true;
+  for (const pkg of PACKAGES) {
+    if (!dispatch(pkg, '9.9.9', true /* dry */)) allOk = false;
+  }
+  if (!allOk) { console.error('selftest FAIL: dry dispatch() reported a failure for at least one package'); process.exit(1); }
+
+  // triggeredForTag() in dry mode must conservatively report "not yet
+  // triggered" — verifyTriggeredAndRedispatch's whole point is to re-dispatch
+  // misses; silently assuming "triggered" would let a real miss through.
+  if (triggeredForTag('web-components', '9.9.9', true) !== false) {
+    console.error('selftest FAIL: dry triggeredForTag() must report false (conservative default)'); process.exit(1);
+  }
+
+  const rc = verifyTriggeredAndRedispatch('9.9.9', true);
+  if (rc !== 0) { console.error(`selftest FAIL: dry verifyTriggeredAndRedispatch() should report rc=0, got ${rc}`); process.exit(1); }
+
+  console.log('selftest OK');
+}
+
+const topArgv = process.argv.slice(2);
+if (topArgv[0] === 'selftest') {
+  selftest();
+} else {
+  main().catch((e) => {
+    console.error(`error: ${e.message}`);
+    process.exit(1);
+  });
+}

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

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+// gate-roster.mjs — the ONE ordered list of the pre-cut gate roster.
+//
+// H3 (forge-campaign gh#268 audit): release-pack.mjs's Step 3 pre-flight ran
+// only 12 of the 17 gates cut-procedure.md §3.1 declares as "every gate runs;
+// a subset = pre-flight failure" — the roster had drifted into two places
+// (the script's own hardcoded array + the doc's table) and only one of them
+// got the memo when gates were added. This module is the single source: the
+// doc's §3.1 table transcribes it, release-pack.mjs's step3PreFlight()
+// imports and runs it in full, and nothing else declares its own subset — a
+// gate can only be dropped by editing this file, which is the change the
+// doc and the script both need anyway.
+//
+// Usage:
+//   import { GATE_ROSTER } from './gate-roster.mjs';
+//   node gate-roster.mjs --list     # human-readable numbered roster (docs/CI use)
+//   node gate-roster.mjs --count    # just the count (drift check)
+
+import { fileURLToPath } from 'node:url';
+import { realpathSync } from 'node:fs';
+
+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' },
+  { 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' },
+  { n: 8,  cmd: 'npm run check:css-bundles-fresh',             what: 'dist CSS matches source' },
+  { n: 9,  cmd: 'npm run check:js-bundles-fresh',              what: 'dist JS matches source' },
+  { n: 10, cmd: 'npm run smoke:engines',                       what: 'gen-UI engines' },
+  { n: 11, cmd: 'npm run smoke:register-engine',               what: 'register-engine 11/11' },
+  { n: 12, cmd: 'npm run verify:corpus',                       what: 'corpus 0 errors' },
+  { n: 13, cmd: 'npm run check:chunks-fresh',                  what: 'chunk index vs sources' },
+  { n: 14, cmd: 'npm run check:embeddings-fresh',              what: 'embeddings vs chunk index' },
+  { 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' },
+];
+
+// -- CLI ------------------------------------------------------------------
+// Only runs when invoked directly (not when imported by release-pack.mjs).
+// realpathSync BOTH sides (CodeRabbit, PR #289): a naive string/URL compare
+// breaks under a symlinked invocation — this skill is normally reached
+// through `.claude/skills/adia-release` -> `packages/plugins/adia-ui-forge/
+// skills/adia-release`, and Node resolves `import.meta.url` through that
+// symlink to the real file while `process.argv[1]` keeps the as-invoked
+// path, so an unresolved compare never matches even when this IS the entry
+// point. Verified directly (see embeddings-chunks.mjs's identical guard).
+const isMain = (() => {
+  if (!process.argv[1]) return false;
+  try {
+    return realpathSync(fileURLToPath(import.meta.url)) === realpathSync(process.argv[1]);
+  } catch {
+    return false;
+  }
+})();
+if (isMain) {
+  const args = new Set(process.argv.slice(2));
+  if (args.has('--count')) {
+    console.log(GATE_ROSTER.length);
+  } else if (args.has('--list') || args.size === 0) {
+    console.log(`${GATE_ROSTER.length}-gate pre-cut roster (source of truth — cut-procedure.md §3.1 transcribes this):\n`);
+    for (const g of GATE_ROSTER) {
+      console.log(`  ${String(g.n).padStart(2)}. ${g.cmd.padEnd(46)} # ${g.what}`);
+    }
+  } else {
+    console.log('Usage: node gate-roster.mjs [--list|--count]');
+  }
+}

package/skills/adia-release/scripts/insert-stub.mjs

@@ -16,6 +16,8 @@
 // cycles.
 
 import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
 import process from 'node:process';
 import { resolvePackageChangelog } from './package-paths.mjs';
 
@@ -126,4 +128,36 @@ function main() {
   }
 }
 
-main();
+// Fixture-locked proof against a real (throwaway) temp directory.
+function selftest() {
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'insert-stub-selftest-'));
+  try {
+    const dir = path.join(tmp, 'packages', 'llm');
+    fs.mkdirSync(dir, { recursive: true });
+    const clPath = path.join(dir, 'CHANGELOG.md');
+    const anchor = '## [0.1.0] — 2026-01-01';
+    fs.writeFileSync(clPath, `# C\n\n${anchor}\n\n- prior\n`);
+
+    const stub = buildStub('0.2.0', '2026-02-02', '@adia-ai/web-components', 'packages/web-components/CHANGELOG.md#020--2026-02-02');
+    const r1 = insertStub(tmp, 'llm', anchor, stub, '0.2.0', false);
+    if (r1 !== 'inserted') { console.error(`selftest FAIL: expected 'inserted', got '${r1}'`); process.exit(1); }
+    const out = fs.readFileSync(clPath, 'utf8');
+    if (!out.includes('## [0.2.0]')) { console.error('selftest FAIL: stub heading not written'); process.exit(1); }
+    if (out.indexOf('## [0.2.0]') > out.indexOf(anchor)) {
+      console.error('selftest FAIL: stub must land ABOVE the previous-version anchor, not below'); process.exit(1);
+    }
+
+    // Idempotency: re-inserting against an already-stubbed target must fail
+    // loudly, not create a duplicate [0.2.0] block.
+    const r2 = insertStub(tmp, 'llm', anchor, stub, '0.2.0', false);
+    if (r2 !== 'already-present') { console.error(`selftest FAIL: expected 'already-present' on re-run, got '${r2}'`); process.exit(1); }
+
+    console.log('selftest OK');
+  } finally {
+    fs.rmSync(tmp, { recursive: true, force: true });
+  }
+}
+
+const topArgv = process.argv.slice(2);
+if (topArgv[0] === 'selftest') selftest();
+else main();

package/skills/adia-release/scripts/promote-unreleased.mjs

@@ -20,6 +20,8 @@
 //   2  — bad args / file I/O error
 
 import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
 import process from 'node:process';
 import { resolvePackageChangelog } from './package-paths.mjs';
 
@@ -86,4 +88,36 @@ function main() {
   }
 }
 
-main();
+// Fixture-locked proof against a real (throwaway) temp directory — promote()
+// does real fs.readFileSync/writeFileSync via resolvePackageChangelog, so a
+// pure in-memory test can't exercise it; a temp dir keeps this <1s and
+// touches nothing in the real repo.
+function selftest() {
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'promote-unreleased-selftest-'));
+  try {
+    const dir = path.join(tmp, 'packages', 'web-components');
+    fs.mkdirSync(dir, { recursive: true });
+    const clPath = path.join(dir, 'CHANGELOG.md');
+    fs.writeFileSync(clPath, '# C\n\n## [Unreleased]\n\n### Fixed\n- x\n\n## [0.1.0] — 2026-01-01\n\n- y\n');
+
+    const r1 = promote(tmp, 'web-components', '0.2.0', '2026-02-02', false);
+    if (r1 !== 'promoted') { console.error(`selftest FAIL: expected 'promoted', got '${r1}'`); process.exit(1); }
+    const out = fs.readFileSync(clPath, 'utf8');
+    if (!out.includes('## [0.2.0] — 2026-02-02')) { console.error('selftest FAIL: new heading not written'); process.exit(1); }
+    if (out.includes('## [Unreleased]')) { console.error('selftest FAIL: [Unreleased] heading should have been renamed, not left behind'); process.exit(1); }
+    if (!out.includes('### Fixed\n- x')) { console.error('selftest FAIL: content under the heading must survive the rename'); process.exit(1); }
+
+    // Idempotency: re-running against an already-promoted target must fail
+    // loudly (a silent no-op or a duplicate block would both be wrong).
+    const r2 = promote(tmp, 'web-components', '0.2.0', '2026-02-02', false);
+    if (r2 !== 'already-promoted') { console.error(`selftest FAIL: expected 'already-promoted' on re-run, got '${r2}'`); process.exit(1); }
+
+    console.log('selftest OK');
+  } finally {
+    fs.rmSync(tmp, { recursive: true, force: true });
+  }
+}
+
+const topArgv = process.argv.slice(2);
+if (topArgv[0] === 'selftest') selftest();
+else main();