@adia-ai/adia-ui-forge 0.8.4 → 0.8.6

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

@@ -4,8 +4,11 @@
 // Chains the 5 CLI helpers (bump · promote-unreleased · insert-stub ·
 // tag-lockstep · dispatch-publish) plus the non-helper steps (lockfile ·
 // pre-flight gates · git commit · F-N1 · push · GH releases · site
-// deploy) into one walked sequence with 3 operator checkpoints (before
-// tag, before push, before publish) per SKILL.md operator checkpoints.
+// deploy) into one walked sequence with 4 confirmation boundaries (before
+// tag, before push, before publish, before deploy dispatch). Under the
+// single-authorization model (SKILL.md §Authorization, operator ruling
+// 2026-07-17) `--go` auto-confirms all of them — the evidence blocks still
+// print as a log; the granular flags below remain for cautious manual runs.
 //
 // MODES (two-phase since 2026-07-16 — invariant 3: release commits land via
 // PR, so the cut modes stop after the release commit; handoff runs the
@@ -13,7 +16,13 @@
 //   --mode cut          (Mode 1 — peer pre-staged [Unreleased] or pure stub; STOPS at the release commit)
 //   --mode from-scratch (Mode 2 — promote [Unreleased] → [VERSION]; STOPS at the release commit)
 //   --mode handoff      (Mode 3 — the second phase: tag at post-merge main → publish → deploy)
-//   --mode batch        (Mode 4 — multiple merged cuts; pass --version-list)
+//
+// `--mode batch` is NOT implemented here — a batch push tags each version at
+// its OWN release-merge SHA and enforces oldest-first publish ordering, which
+// this single-version orchestrator has no model for. Passing it hard-errors
+// with a pointer to the manual procedure: references/recovery-paths.md
+// §Scenario 2 (Batch push). Silently falling through to the single-version
+// path was the H2 audit finding this replaced.
 //
 // REQUIRED:
 //   --version 0.6.22
@@ -25,26 +34,42 @@
 //   --gh-notes-file <path>            : GH release notes body (one per cycle)
 //   --substantive "<one-line>"        : for the stub block xref
 //   --xref "<changelog-anchor>"       : for the stub block
-//   --substantive-packages a,b,c      : packages with [Unreleased] to promote
+//   --substantive-packages a,b,c      : packages with [Unreleased] to promote (cut AND from-scratch)
 //   --stub-packages a,b,c             : packages getting the lockstep stub
 //
 // FLAGS:
+//   --go                 : single-authorization — the operator's cut-start go
+//                          covers the whole cycle; equals --yes --push --publish.
+//                          THE standard invocation for an operator-initiated
+//                          release. An F-N1 warn still refuses auto-confirm at
+//                          the push boundary (a gate failure, not ceremony).
 //   --dry                : preview all commands, no mutation, no prompts
-//   --yes                : skip the 3 operator checkpoints (CI / scripted)
+//   --yes                : auto-confirm the tag boundary ONLY. Tag creation is
+//                          the least destructive of the mutating boundaries
+//                          (moving/deleting a local-only tag is free); push and
+//                          publish each need their own flag — --yes does not
+//                          cover them (H5/defect-2: a single --yes used to
+//                          flatten every boundary).
+//   --push               : auto-confirm the push-tags boundary
+//   --publish            : auto-confirm the publish + deploy-dispatch boundaries
 //   --skip-gates         : (DEBUG ONLY) skip pre-flight (don't ship anything!)
 //   --skip-site          : skip the EXE deploy step (rare; for offline cycles)
 //
 // Part of the adia-release skill. Mechanizes the cut procedure from
-// references/cut-procedure.md while preserving operator judgment at
-// the 3 mutating-checkpoint boundaries.
+// references/cut-procedure.md. Every confirmation boundary prints its evidence
+// block BEFORE the prompt (H5) — never a bare y/N — whether it waits for input
+// (manual flags) or auto-confirms (--go).
 
 import { execSync } from 'node:child_process';
 import { createInterface } from 'node:readline/promises';
 import { stdin, stdout } from 'node:process';
 import fs from 'node:fs';
+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 { GATE_ROSTER } from './gate-roster.mjs';
 
 const SCRIPT_DIR = path.dirname(new URL(import.meta.url).pathname);
 const REPO = process.cwd();
@@ -70,7 +95,7 @@ function parseArgs(argv) {
     versionList: null,
     host: process.env.ADIA_DEPLOY_HOST || DEFAULT_DEPLOY_HOST,
     scope: process.env.ADIA_NPM_SCOPE || DEFAULT_NPM_SCOPE,
-    dry: false, yes: false, skipGates: false, skipSite: false,
+    dry: false, yes: false, push: false, publish: false, skipGates: false, skipSite: false,
   };
   for (let i = 0; i < argv.length; i++) {
     const k = argv[i];
@@ -89,6 +114,16 @@ function parseArgs(argv) {
     else if (k === '--scope') args.scope = argv[++i];
     else if (k === '--dry') args.dry = true;
     else if (k === '--yes') args.yes = true;
+    else if (k === '--push') args.push = true;
+    else if (k === '--publish') args.publish = true;
+    // --go: the single-authorization model (operator ruling 2026-07-17,
+    // replacing the 4-checkpoint ceremony after the v0.8.5 cut spent ~40
+    // minutes on approval relays that produced zero safety). The operator's
+    // cut-start instruction covers the WHOLE cycle; the run stops only on
+    // gate failures. Equivalent to --yes --push --publish; the F-N1
+    // error hard-stop and the warn-blocks-auto-confirm rule still apply —
+    // those are gates, not approvals, and no flag skips them.
+    else if (k === '--go') { args.yes = true; args.push = true; args.publish = true; }
     else if (k === '--skip-gates') args.skipGates = true;
     else if (k === '--skip-site') args.skipSite = true;
     else if (k === '-h' || k === '--help') { help(); process.exit(0); }
@@ -98,8 +133,17 @@ function parseArgs(argv) {
     console.error('       see --help');
     process.exit(2);
   }
-  if (!['cut', 'from-scratch', 'handoff', 'batch'].includes(args.mode)) {
-    console.error(`error: --mode must be cut|from-scratch|handoff|batch (got: ${args.mode})`);
+  if (args.mode === 'batch') {
+    console.error('error: --mode batch is not implemented — a batch push tags each version at');
+    console.error('       its OWN release-merge SHA and enforces oldest-first publish ordering,');
+    console.error('       which this single-version orchestrator has no model for. Silently');
+    console.error('       falling through to the single-version path was the H2 defect this');
+    console.error('       replaced. Follow the manual procedure instead:');
+    console.error('         references/recovery-paths.md §Scenario 2 — Batch push');
+    process.exit(2);
+  }
+  if (!['cut', 'from-scratch', 'handoff'].includes(args.mode)) {
+    console.error(`error: --mode must be cut|from-scratch|handoff (got: ${args.mode})`);
     process.exit(2);
   }
   return args;
@@ -116,15 +160,31 @@ function help() {
     --substantive-packages web-components,web-modules,a2ui/corpus \\
     --stub-packages llm,a2ui/compose,a2ui/mcp,a2ui/retrieval,a2ui/runtime,a2ui/validator
 
-Flags: --dry  (preview all)  --yes  (skip prompts)  --skip-site  (skip EXE deploy)
+Flags: --go   (single-authorization: the operator's cut-start go covers the
+               whole cycle — auto-confirms ALL checkpoints; stops only on
+               gate failures. THE DEFAULT for an operator-initiated release.)
+       --dry  (preview all)  --yes  (auto-confirm checkpoint 1 ONLY — tag)
+       --push  (auto-confirm checkpoint 2 — push tags)
+       --publish  (auto-confirm checkpoint 3 — dispatch publishes)
+       --skip-site  (skip EXE deploy)
 Instance: --host <deploy-host>  (default ${DEFAULT_DEPLOY_HOST}; or $ADIA_DEPLOY_HOST)
           --scope <@org>        (npm scope; default ${DEFAULT_NPM_SCOPE}; or $ADIA_NPM_SCOPE)`);
 }
 
 const rl = createInterface({ input: stdin, output: stdout });
-async function checkpoint(label, args) {
-  if (args.yes) {
-    console.log(`\n[checkpoint] ${label} — auto-confirmed (--yes)`);
+// Every checkpoint prints its evidence block BEFORE the y/N prompt (H5) —
+// `evidence` is a pre-formatted string (tag list, F-N1 results, registry
+// snapshot); `autoConfirmed` is the SPECIFIC flag that covers THIS checkpoint
+// (--yes for checkpoint 1 only; --push / --publish for 2 and 3 — H5/defect-2:
+// a single --yes used to flatten all three).
+async function checkpoint(label, evidence, autoConfirmed) {
+  if (evidence) {
+    console.log(`\n--- evidence for: ${label} ---`);
+    console.log(evidence);
+    console.log('---');
+  }
+  if (autoConfirmed) {
+    console.log(`\n[checkpoint] ${label} — auto-confirmed`);
     return;
   }
   const answer = await rl.question(`\n[CHECKPOINT] ${label} — proceed? [y/N]: `);
@@ -151,6 +211,24 @@ function shQuiet(cmd, args) {
   return execSync(cmd, { cwd: REPO, encoding: 'utf8' });
 }
 
+// Runs a command and CAPTURES its combined output instead of streaming it —
+// used where the output itself becomes evidence in a later checkpoint's
+// evidence block (H5), rather than just scrolling past in the terminal.
+// Never throws: F-N1 legitimately exits non-zero on cosmetic warns; the
+// caller decides what a non-zero code means.
+function shCapture(cmd, args) {
+  if (args.dry) {
+    console.log(`  [dry] ${cmd}`);
+    return { code: 0, output: '[dry] (not run)' };
+  }
+  try {
+    const output = execSync(cmd, { cwd: REPO, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+    return { code: 0, output };
+  } catch (e) {
+    return { code: e.status ?? 1, output: (e.stdout || '') + (e.stderr || '') };
+  }
+}
+
 // ── Step 1 — Re-baseline ──────────────────────────────────────────
 function step1ReBaseline(args) {
   console.log('\n=== Step 1 — Re-baseline ===');
@@ -173,32 +251,40 @@ function step3PreFlight(args) {
     console.log('\n=== Step 3 — Pre-flight (SKIPPED via --skip-gates; danger!) ===');
     return;
   }
-  console.log('\n=== Step 3 — Pre-flight gates ===');
-  const gates = [
-    'node scripts/build/components.mjs --verify',
-    'npm run verify:traits',
-    'npm run check:lockstep',
-    'npm run test:unit',
-    'npm run typecheck',
-    'npm run check:demo-shells',
-    'npm run check:lightningcss-build',
-    'npm run smoke:engines',
-    'npm run smoke:register-engine',
-    'npm run check:links',
-    'npm run check:embeddings-fresh',
-    'npm run verify:corpus',
-  ];
-  for (const g of gates) {
-    console.log(`\n  ${g}`);
+  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}`);
     try {
-      sh(g, args, { stdio: 'inherit' });
+      sh(g.cmd, args, { stdio: 'inherit' });
     } catch (e) {
-      console.error(`\n  ✗ FAILED: ${g}`);
+      console.error(`\n  ✗ FAILED (${g.n}/${GATE_ROSTER.length}): ${g.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);
     }
   }
+  console.log(`\n  ✓ all ${GATE_ROSTER.length}/${GATE_ROSTER.length} gates passed`);
+}
+
+// Read a package's CHANGELOG at repo HEAD (working tree) and report whether a
+// `## [Unreleased]` heading still carries non-empty content — i.e. it rode
+// through un-promoted. Defect 1 (H1-adjacent, audit seed): `--mode cut` never
+// called promote-unreleased.mjs at all, so a peer's hand-authored
+// `## [Unreleased]` section shipped in the tarball unpromoted (bit the
+// v0.8.4 cut — the plugin packages needed hand-promotion because nothing
+// caught it). Returns null when clean, or a short description when dirty.
+function unpromotedUnreleased(repo, pkg) {
+  const p = resolvePackageChangelog(repo, pkg);
+  if (!fs.existsSync(p)) return null;
+  const txt = fs.readFileSync(p, 'utf8');
+  const m = txt.match(/^## \[Unreleased\][^\n]*\n([\s\S]*?)(?=^## \[|$(?![\s\S]))/m);
+  if (!m) return null;
+  // Strip subsection headers (### Added, ### Fixed, …) and blank lines — what's
+  // left is real content, not just empty scaffolding.
+  const body = m[1].replace(/^###.*$/gm, '').trim();
+  if (body.length === 0) return null;
+  const firstLine = body.split('\n')[0].slice(0, 100);
+  return `${pkg}: "${firstLine}${firstLine.length === 100 ? '…' : ''}"`;
 }
 
 // ── Step 4 — Promote + bump + lockfile ───────────────────────────
@@ -209,7 +295,12 @@ function step4PromoteAndBump(args) {
   }
   console.log('\n=== Step 4 — Promote + Bump + Lockfile ===');
 
-  if (args.mode === 'from-scratch' && args.substantivePackages) {
+  // Promotion runs for BOTH cut and from-scratch now — a peer's pre-staged
+  // [Unreleased] content needs promoting in either mode; only the CALLER
+  // (whether a peer already promoted vs. this cycle authoring fresh) differs,
+  // not whether promotion is needed. `--substantive-packages` is the same flag
+  // in both modes.
+  if (args.substantivePackages) {
     const cmd = `node ${SCRIPT_DIR}/promote-unreleased.mjs --version ${args.version} --date ${args.date} --packages ${args.substantivePackages.join(',')}`;
     sh(cmd, args);
   }
@@ -219,9 +310,35 @@ function step4PromoteAndBump(args) {
     sh(cmd, args);
   }
 
+  // Loud guard: after promotion, NO package in the lockstep set (including
+  // the 2 plugin packages, which required hand-promotion at v0.8.4) may still
+  // carry a non-empty [Unreleased] — that content would ride through the
+  // bump unpromoted, undocumented in the tarball's own CHANGELOG.
+  if (!args.dry) {
+    const dirty = PACKAGES.map((p) => unpromotedUnreleased(REPO, p)).filter(Boolean);
+    if (dirty.length > 0) {
+      console.error(`\nERROR: ${dirty.length} package(s) still have non-empty [Unreleased] content after promotion:`);
+      for (const d of dirty) console.error(`  ✗ ${d}`);
+      console.error('\n  Add the missing package(s) to --substantive-packages (or --stub-packages if');
+      console.error('  they are pure ride-alongs) and re-run. See changelog-discipline.md §Detecting');
+      console.error('  source-changing packages.');
+      process.exit(1);
+    }
+    console.log(`  ✓ no unpromoted [Unreleased] content across all ${PACKAGES.length} packages`);
+  }
+
   sh(`node ${SCRIPT_DIR}/bump.mjs --from ${args.previous} --to ${args.version}`, args);
   sh('npm install --package-lock-only --no-audit --no-fund', args);
   sh('npm run check:lockstep', args);
+
+  // Step 4f — pre-tag F-N1 coverage with auto-fix, run with the AUTHORITATIVE
+  // matcher (check-release.mjs itself, not the drifted 9-package
+  // check-changelog-coverage.mjs). Appends verified Maintenance bullets for
+  // any changed-but-unmentioned directory so the post-tag F-N1 (Step 7) is a
+  // formality. The v0.8.5 cut lacked this and paid 3 enrichment PRs + 3
+  // 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 5 — Commit ──────────────────────────────────────────────
@@ -262,23 +379,45 @@ function step5Commit(args) {
   sh(`git commit -F ${args.commitMessageFile}`, args);
 }
 
-// ── Step 6 — Tag ─────────────────────────────────────────────────
+// ── Step 6 — Tag ← operator checkpoint 1 (before tagging) ────────
 async function step6Tag(args) {
   console.log('\n=== Step 6 — Tag at HEAD ===');
-  await checkpoint('Ready to create 12 tags (umbrella + 11 per-package)', args);
+  const tagList = [`v${args.version}`, ...PACKAGES.map((p) => `${p}-v${args.version}`)];
+  const evidence = `Planned tags (${tagList.length} — umbrella + ${PACKAGES.length} per-package):\n` +
+    tagList.map((t) => `  ${t}`).join('\n');
+  // --yes covers ONLY this checkpoint (defect-2/H5) — moving/deleting a
+  // local-only tag is free, so this is the least destructive of the three.
+  await checkpoint('Create tags at HEAD — before tagging', evidence, args.yes);
   sh(`node ${SCRIPT_DIR}/tag-lockstep.mjs --version ${args.version}`, args);
+  console.log(`  ✓ created ${tagList.length} tags`);
 }
 
-// ── Step 7 — F-N1 ────────────────────────────────────────────────
+// ── Step 7 — F-N1 ─────────────────────────────────────────────────
+// Captures output (rather than streaming it) so checkpoint 2 can show the
+// per-package F-N1 results as evidence BEFORE the push prompt (H5) — the F-N1
+// output used to scroll past in Step 7 with no connection to Step 8's prompt.
 function step7Fn1(args) {
   console.log('\n=== Step 7 — F-N1 release trip-wire ===');
-  try {
-    sh('node scripts/release/check-release.mjs --all-pending', args);
-  } catch (e) {
-    // F-N1 sometimes exits non-zero on cosmetic warns; show the output and let the operator decide
-    console.warn('\n  F-N1 returned non-zero — review the warns above.');
-    console.warn('  See references/changelog-discipline.md § F-N1 diff-coverage enrichment.');
+  const { code, output } = shCapture('node scripts/release/check-release.mjs --all-pending', args);
+  console.log(output);
+  // CodeRabbit (PR #289): a non-zero exit here (without --strict, which this
+  // call doesn't pass) is ALWAYS a real `error` finding — check-release.mjs
+  // only sets a non-zero code for `error` severity; cosmetic `warn`s leave it
+  // 0. Treating non-zero as "just review the warns" let --push auto-confirm
+  // straight past a known trip-wire failure. Fail closed: hard-stop HERE,
+  // before Step 8 exists at all — no flag can skip this.
+  if (code !== 0 && !args.dry) {
+    console.error('\n  ✗ F-N1 reported an ERROR (not a cosmetic warn) — release-pack stops here.');
+    console.error('  Fix the finding above, land it as a new commit through the PR flow (the');
+    console.error('  release commit is already merged — see changelog-discipline.md §F-N1');
+    console.error('  diff-coverage enrichment), delete + re-create the tags, re-run.');
+    process.exit(1);
   }
+  // Cosmetic warns (exit 0, but the output carries `[warn]` lines) are real
+  // signal an operator should read before pushing — never let --push silently
+  // wave them through; only the interactive prompt may proceed past a warn.
+  const hasWarn = /\[warn\]/.test(output);
+  return { output, hasWarn };
 }
 
 // ── Step 8 — Push ────────────────────────────────────────────────
@@ -296,7 +435,7 @@ function step7Fn1(args) {
 // orchestrated cut does NOT rely on push-on-tag firing. The one-at-a-time push
 // is defensive (a cut aborted after Step 8 still has its publishes triggered)
 // AND keeps the standalone tag-lockstep.mjs hint honest.
-async function step8Push(args) {
+async function step8Push(args, fn1) {
   console.log('\n=== Step 8 — Push tags (per-tag, NOT batched) ===');
   // Invariant 3: main reached this state via a merged release PR — never a
   // direct push from here. Assert we're tagging the pushed history.
@@ -305,14 +444,22 @@ async function step8Push(args) {
     console.error(`ERROR: HEAD is ${ahead} commit(s) ahead of origin/main — release commits land via PR (invariant 3); merge first, then tag at post-merge main.`);
     process.exit(1);
   }
-  await checkpoint('Ready to push 12 tags (one-at-a-time)', args);
   const perPkgTags = PACKAGES.map((p) => `${p}-v${args.version}`);
+  const evidence = `F-N1 results (Step 7):\n${fn1?.output || '(none captured)'}\n` +
+    `Tags to push (${perPkgTags.length + 1} — one push per tag, umbrella last):\n` +
+    [...perPkgTags, `v${args.version}`].map((t) => `  ${t}`).join('\n');
+  // --push is its OWN flag — NOT covered by --yes (defect-2/H5). CodeRabbit
+  // (PR #289): a cosmetic F-N1 warn must still force the interactive prompt —
+  // --push may NOT auto-confirm past ANY F-N1 finding, only a fully clean
+  // run. (A real F-N1 error never reaches here — step7Fn1 hard-exits first.)
+  const autoConfirm = args.push && !fn1?.hasWarn;
+  await checkpoint('Push tags — before pushing', evidence, autoConfirm);
   for (const t of perPkgTags) {
     sh(`git push origin ${t}`, args);
   }
   // Umbrella tag last — triggers no workflow (convention only).
   sh(`git push origin v${args.version}`, args);
-  console.log(`\n  ${perPkgTags.length} per-package tags + 1 umbrella pushed individually.`);
+  console.log(`\n  ✓ pushed ${perPkgTags.length} per-package tags + 1 umbrella tag`);
   console.log('  NOTE: a single `git push origin <all tags>` can skip ALL publish-on-tag');
   console.log('  triggers (the GitHub batch-push skip). Step 9 dispatches via');
   console.log('  workflow_dispatch + verifies each triggered — see recovery-paths.md §Scenario 7.');
@@ -324,9 +471,30 @@ async function step8Push(args) {
 // exist for the <pkg>-vX.Y.Z tags and re-dispatches ONLY the misses — closing the
 // batch-tag-push skip without double-publishing the ones that already fired.
 // Idempotent: if all 11 triggered (or none did), it does the right thing.
+// Snapshot the CURRENT registry state — the "ordering evidence" for
+// checkpoint 3 (H5): what's live right now, before anything is dispatched,
+// so the operator can confirm publish order/target against reality rather
+// than a bare y/N.
+function registrySnapshot(args) {
+  if (args.dry) return '[dry] (registry snapshot skipped)';
+  const lines = [];
+  for (const pkg of PACKAGES) {
+    let v;
+    try { v = execSync(`npm view "${args.scope}/${pkg}" version`, { encoding: 'utf8' }).trim(); }
+    catch { v = 'MISSING/E404'; }
+    lines.push(`  ${pkg}: ${v}${v === args.version ? '  (already at target — idempotent re-dispatch)' : ''}`);
+  }
+  let latest = 'unknown';
+  try { latest = execSync(`npm view ${args.scope}/web-components dist-tags.latest`, { encoding: 'utf8' }).trim(); } catch { /* offline */ }
+  lines.push(`  dist-tags.latest: ${latest}`);
+  return `Registry state BEFORE publish (target = ${args.version}):\n${lines.join('\n')}`;
+}
+
 async function step9Publish(args) {
   console.log('\n=== Step 9 — Verify-triggered + re-dispatch misses ===');
-  await checkpoint('Ready to verify the 11 publish triggers + re-dispatch any misses', args);
+  const evidence = registrySnapshot(args);
+  // --publish is its OWN flag — NOT covered by --yes (defect-2/H5).
+  await checkpoint('Dispatch publishes — before publishing', evidence, args.publish);
   // Give GH a moment to index the runs created by the per-tag push in Step 8.
   if (!args.dry) sh('sleep 6', args);
   sh(`node ${SCRIPT_DIR}/dispatch-publish.mjs --version ${args.version} --scope ${args.scope} --verify-triggered`, args);
@@ -335,7 +503,7 @@ async function step9Publish(args) {
   console.log('  ✓ publishes settled');
   // Fail-closed: the registry is the verify target (SKILL.md) — a missing or
   // stale package aborts the cut here, before GH releases + site deploy.
-  console.log(`\n  Verify all ${PACKAGES.length} at ${args.version} + npm latest (fail-closed):`);
+  console.log(`\n  Post-publish registry verification, all ${PACKAGES.length} at ${args.version} + npm latest (fail-closed):`);
   sh(
     `fail=0; ` +
     `for pkg in ${PACKAGES.join(' ')}; do ` +
@@ -369,8 +537,24 @@ async function step10GhAndSite(args) {
     console.log('  --skip-site set; skipping EXE deploy');
     return;
   }
-  sh('npm run build:site', args);
-  sh(`rsync -az --delete dist/ ${args.host}:/srv/adia-ui/dist/`, args);
+  // H1 (forge-campaign gh#268 audit): this used to `npm run build:site` +
+  // raw `rsync -az --delete` straight to the host — bypassing deploy-site.yml
+  // entirely (its build → pre-flight verify → snapshot → rsync → post-deploy
+  // verify → auto-rollback pipeline), even though cut-procedure.md §Step 10
+  // already documented the workflow-dispatch path as the correct one. A raw
+  // local rsync has no snapshot to roll back to on a bad deploy. Dispatch the
+  // real pipeline instead — gated behind its own confirm (deploy is
+  // outward-facing exactly like publish; --publish covers it, or an
+  // interactive confirm if not given).
+  const evidence = `Dispatching "Deploy site (${args.host})" (.github/workflows/deploy-site.yml) —\n` +
+    `builds from main, runs pre-flight verify → snapshot → hardened rsync →\n` +
+    `post-deploy verify → auto-rollback. NOT a raw rsync (the bypass this replaced).`;
+  await checkpoint('Deploy site — before dispatching deploy-site.yml', evidence, args.publish);
+  sh(`gh workflow run "Deploy site (${args.host})" --repo adiahealth/gen-ui-kit --ref main`, args);
+  console.log('  Waiting for the deploy workflow to settle...');
+  if (!args.dry) sh('sleep 10', args);
+  sh(`until [ "$(gh run list --workflow=deploy-site.yml --limit 1 --json status -q '.[0].status')" = "completed" ]; do sleep 5; done`, args);
+  console.log('  ✓ deploy-site.yml settled');
   // Verify a deployed CONTENT FILE, never an SPA route — the docs site
   // returns HTTP 200 + a blank shell for ANY unmatched route (v0.7.4 trap).
   sh(`curl -s -o /dev/null -w "EXE host.css: HTTP %{http_code}\\n" https://${args.host}/packages/web-components/styles/host.css`, args);
@@ -405,16 +589,91 @@ async function main() {
     return;
   }
   await step6Tag(args);
-  step7Fn1(args);
-  await step8Push(args);
+  const fn1 = step7Fn1(args);
+  await step8Push(args, fn1);
   await step9Publish(args);
   await step10GhAndSite(args);
   rl.close();
   console.log('\n✓ release-pack complete. Verify against the npm registry + GH releases, then author the release notes.');
 }
 
-main().catch((e) => {
-  console.error(e);
+// Plan-assembly selftest — spawns THIS script as a real subprocess with
+// --mode cut --dry (fully mutation-free per every step's own dry-guard) and
+// asserts the assembled plan carries the expected markers: the full
+// 17-gate roster (H3 — a subset run must be impossible without editing
+// gate-roster.mjs), and the invariant-3 stop-before-PR message (cut mode
+// must never proceed to tag/push/publish on its own). A fixture temp dir
+// supplies the operator-authored content files (--commit-message-file /
+// --gh-notes-file) so nothing here depends on real repo state.
+function selftest() {
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'release-pack-selftest-'));
+  try {
+    const commitFile = path.join(tmp, 'commit.txt');
+    const notesFile = path.join(tmp, 'notes.md');
+    fs.writeFileSync(commitFile, 'selftest fixture commit message\n');
+    fs.writeFileSync(notesFile, 'selftest fixture notes\n');
+
+    const scriptPath = fileURLToPathCompat(import.meta.url);
+    let out;
+    try {
+      out = execSync(
+        `node "${scriptPath}" --mode cut --version 9.9.9 --date 2026-01-01 --previous-version 9.9.8 ` +
+        `--commit-message-file "${commitFile}" --gh-notes-file "${notesFile}" ` +
+        `--substantive-packages web-components --stub-packages llm --dry --yes`,
+        { cwd: REPO, encoding: 'utf8' },
+      );
+    } catch (e) {
+      console.error('selftest FAIL: --mode cut --dry plan assembly exited non-zero');
+      console.error(e.stdout || e.message);
+      process.exit(1);
+    }
+
+    const need = [
+      `${GATE_ROSTER.length}-gate roster`,
+      `✓ all ${GATE_ROSTER.length}/${GATE_ROSTER.length} gates passed`,
+      'STOPPING per invariant 3',
+    ];
+    for (const marker of need) {
+      if (!out.includes(marker)) {
+        console.error(`selftest FAIL: expected marker not found in plan output: "${marker}"`);
+        process.exit(1);
+      }
+    }
+
+    // The batch-mode hard-reject (H2) must fire BEFORE any of the above runs.
+    let batchOut = '';
+    let batchFailed = false;
+    try {
+      execSync(`node "${scriptPath}" --mode batch --version 9.9.9 --date 2026-01-01 --previous-version 9.9.8`, { cwd: REPO, encoding: 'utf8' });
+    } catch (e) {
+      batchFailed = true;
+      batchOut = (e.stdout || '') + (e.stderr || '');
+    }
+    if (!batchFailed || !batchOut.includes('Scenario 2')) {
+      console.error('selftest FAIL: --mode batch must hard-reject with a pointer to recovery-paths.md §Scenario 2');
+      process.exit(1);
+    }
+
+    console.log('selftest OK');
+  } finally {
+    fs.rmSync(tmp, { recursive: true, force: true });
+  }
+}
+
+// import.meta.url → filesystem path (works the same on the platforms this
+// skill runs on; avoids pulling in node:url's fileURLToPath just for this).
+function fileURLToPathCompat(url) {
+  return new URL(url).pathname;
+}
+
+const topArgv = process.argv.slice(2);
+if (topArgv[0] === 'selftest') {
   rl.close();
-  process.exit(1);
-});
+  selftest();
+} else {
+  main().catch((e) => {
+    console.error(e);
+    rl.close();
+    process.exit(1);
+  });
+}

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

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
-// tag-lockstep.mjs — create 10 lockstep tags (umbrella vX.Y.Z + 9
-// per-package <pkg>-vX.Y.Z) at HEAD or at a specified SHA.
+// tag-lockstep.mjs — create 12 lockstep tags (umbrella vX.Y.Z + 11
+// per-package <pkg>-vX.Y.Z, including the 2 plugin packages that joined
+// the lockstep 2026-07-15) at HEAD or at a specified SHA.
 //
 // Usage:
 //   node tag-lockstep.mjs --version 0.6.22
@@ -114,9 +115,30 @@ function main() {
   }
 }
 
-try {
-  main();
-} catch (e) {
-  console.error(`error: ${e.message}`);
-  process.exit(1);
+function selftest() {
+  const tags = buildTagList('1.2.3');
+  if (tags.length !== 12) {
+    console.error(`selftest FAIL: expected 12 tags (umbrella + 11 per-package), got ${tags.length}`); process.exit(1);
+  }
+  if (tags[0] !== 'v1.2.3') {
+    console.error('selftest FAIL: umbrella tag must be first'); process.exit(1);
+  }
+  for (const expected of ['web-components-v1.2.3', 'adia-ui-factory-v1.2.3', 'adia-ui-forge-v1.2.3']) {
+    if (!tags.includes(expected)) {
+      console.error(`selftest FAIL: expected tag '${expected}' missing from buildTagList output`); process.exit(1);
+    }
+  }
+  console.log('selftest OK');
+}
+
+const topArgv = process.argv.slice(2);
+if (topArgv[0] === 'selftest') {
+  selftest();
+} else {
+  try {
+    main();
+  } catch (e) {
+    console.error(`error: ${e.message}`);
+    process.exit(1);
+  }
 }

package/skills/adia-site-docs/SKILL.md

@@ -35,7 +35,7 @@ skill routes to it and enforces it, it does not restate it.
 | Task shape | Do |
 | --- | --- |
 | New page in an owned category | Read the convention doc's template section; copy the shared skeleton from a sibling page in the same category (narrative archetype vs. reference/gallery archetype). |
-| Callout / "meta content" block | `<alert-ui variant="warning\|info\|...">` with `<div slot="content">` (never `<span>` — the transpiler only treats `p`/`div`/`ul`/`ol` as prose; a `<span>` silently reorders mixed inline content on regen) for rich text — never a bare `data-*` attribute. A whole multi-heading section aimed at a different reader (not a short callout) is NOT `alert-ui`'s job either (wrong shape) — currently there's no working distinguishing treatment for this case beyond the heading text itself; see the convention doc's rule 2 for what's been tried and why it doesn't render. |
+| Callout / "meta content" block | `<alert-ui variant="warning\|info\|...">` with `<div slot="content">` (never `<span>` — the transpiler only treats `p`/`div`/`ul`/`ol` as prose; a `<span>` silently reorders mixed inline content on regen) for rich text — never a bare `data-*` attribute. A whole multi-heading section aimed at a different reader (not a short callout) is NOT `alert-ui`'s job either — wrong shape — the convention doc's rule 2 carries the working treatment (eyebrow `<tag-ui>` title-row, TKT-0011). |
 | Tamed admin-shell demo | Add `class="demo-frame"` to the shell instance + a page-local `<style>` block setting only `--demo-frame-height` (and any genuinely page-specific extra). That's `site/site.css`'s `.demo-frame` utility already covering `position`/`border`/`overflow`/`.demo-body` padding. |
 | A surface needs to read as "its own distinct object" against the page background (a chip, a pill) | Reuse `--a-canvas-well-strong` (`packages/web-components/styles/colors/semantics/core.css`) — verified ≥3:1 (WCAG 2.2 SC 1.4.11) in both schemes. `--a-canvas-well` alone is for a subtly-sunken panel; a new candidate token always runs through `color:color-verify` first. |
 | "Is this page consistent?" / review request | Check the page against the convention doc's rules 1–4 by name; a finding names the specific rule violated, not just "this looks off." |
@@ -63,6 +63,11 @@ A check that cannot run (missing script, no network for a build step) is a
 named blocker in the report — flag it and stop; never mark the page done on
 an assumed pass.
 
+The fresh-context critic for an authored page is the `framework-reviewer`
+agent (its dogfood visual probe covers rendered site surfaces) — the author
+never certifies their own page's rendered result; the mechanical checks
+above plus that read-only pass together are the review.
+
 Done when the touched page(s) pass the checks above and, for a reviewed
 page, every finding cites the specific rule in `site-pages-authoring.md` it
 violates.