@adia-ai/adia-ui-forge 0.8.31 → 0.8.33

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

@@ -147,6 +147,52 @@ function parseArgs(argv) {
   // there: on the v0.8.10 cut the missing flag surfaced only after tags and
   // npm publish were already irreversible (Step 10 is the LAST step). An arg
   // error must never cost half a shipped release.
+  // From-scratch needs FULL roster CHANGELOG coverage at Step 4 — every
+  // package gets its [VERSION] section from either promote-unreleased
+  // (--substantive-packages) or insert-stub (--stub-packages). Validate at
+  // PARSE time, not there: on the v0.8.29 cut the missing --stub-packages
+  // surfaced only at Step 4e's generate-release-notes ("no [X.Y.Z] CHANGELOG
+  // section in: <8 ride-alongs>") — AFTER the ~15-min pre-flight, promote,
+  // and bump had all run, and each abort left a half-cut tree (gh#765).
+  // Mirrors the handoff --gh-notes-file guard below. Mode cut is exempt: a
+  // peer may have pre-staged the [VERSION] sections by hand.
+  // EITHER package flag arms the guard (CodeRabbit, PR #772): keying on
+  // --substantive-packages alone let a stub-only invocation bypass both the
+  // coverage check and the --substantive/--xref pairing check below — and a
+  // stub list without that pairing makes Step 4 silently skip insert-stub,
+  // the exact Step-4e death this guard exists to prevent. (A ZERO-flag
+  // from-scratch can't be judged here — it may be a half-cut resume whose
+  // sections already exist; main() rules on it after detectHalfCut.)
+  if (args.mode === 'from-scratch' && (args.substantivePackages || args.stubPackages)) {
+    // Flags accept both name form (a2ui-corpus) and path form (a2ui/corpus);
+    // normalize to name form for the roster set-difference.
+    const toName = (p) => (PACKAGE_NAMES.includes(p) ? p : p.replaceAll('/', '-'));
+    const covered = new Set([
+      ...(args.substantivePackages ?? []).map(toName),
+      ...(args.stubPackages ?? []).map(toName),
+    ]);
+    const missing = PACKAGE_NAMES.filter((p) => !covered.has(p));
+    if (missing.length > 0) {
+      console.error(`error: --mode from-scratch covers only ${covered.size} of the ${PACKAGE_NAMES.length} lockstep`);
+      console.error('       packages — Step 4e (generate-release-notes) would die on a missing');
+      console.error(`       [${args.version}] CHANGELOG section in the ${missing.length} ride-along(s):`);
+      console.error(`         ${missing.join(', ')}`);
+      console.error('       Add them to --stub-packages (pure ride-alongs get the lockstep stub;');
+      console.error('       insert-stub also needs --substantive and --xref) or to');
+      console.error('       --substantive-packages if they carry real [Unreleased] content.');
+      console.error('       Failing now, BEFORE the ~15-min pre-flight (v0.8.29 burned three');
+      console.error('       full re-runs discovering this at Step 4e — gh#765).');
+      process.exit(2);
+    }
+    // insert-stub silently no-ops without --substantive/--xref (Step 4's
+    // guard condition) — same Step 4e death, so same parse-time fail.
+    if (args.stubPackages && (!args.substantive || !args.xref)) {
+      console.error('error: --stub-packages requires --substantive and --xref (insert-stub.mjs');
+      console.error('       needs both for the stub block; without them Step 4 silently skips');
+      console.error('       stub insertion and Step 4e dies on the missing CHANGELOG sections).');
+      process.exit(2);
+    }
+  }
   if (args.mode === 'handoff') {
     if (!args.ghNotesFile) {
       console.error('error: --mode handoff requires --gh-notes-file (Step 10 creates the 11 GH');
@@ -210,12 +256,39 @@ async function checkpoint(label, evidence, autoConfirmed) {
   }
 }
 
+// A failed inner command must surface WHAT it said, not a bare execSync
+// stack: the v0.8.29 cut died at Step 4e with only `Error: Command failed`
+// — the generator's real message ("no [X.Y.Z] CHANGELOG section in: …") was
+// invisible until the command was re-run by hand (gh#765). Print the failing
+// command + exit status + any CAPTURED stdout/stderr (piped calls; inherit
+// calls already streamed it live), then rethrow a marked, stack-free error
+// so main()'s catch doesn't re-dump a useless execSync trace over it.
+function shFailure(cmd, e) {
+  const status = e.status ?? (e.signal ? `signal ${e.signal}` : '?');
+  console.error(`\n✗ command failed (exit ${status}): ${cmd}`);
+  const captured = [e.stdout, e.stderr]
+    .map((s) => (s || '').toString().trim())
+    .filter(Boolean);
+  if (captured.length > 0) {
+    console.error('  ── the command\'s own output ──');
+    console.error(captured.join('\n').split('\n').map((l) => `  ${l}`).join('\n'));
+    console.error('  ──');
+  }
+  const err = new Error(`command failed (exit ${status}): ${cmd}`);
+  err.reported = true; // main()'s catch prints e.message only, no stack
+  return err;
+}
+
 function sh(cmd, args, opts = {}) {
   if (args.dry) {
     console.log(`  [dry] ${cmd}`);
     return '';
   }
-  return execSync(cmd, { cwd: REPO, encoding: 'utf8', stdio: opts.stdio || 'inherit' });
+  try {
+    return execSync(cmd, { cwd: REPO, encoding: 'utf8', stdio: opts.stdio || 'inherit' });
+  } catch (e) {
+    throw shFailure(cmd, e);
+  }
 }
 
 function shQuiet(cmd, args) {
@@ -223,7 +296,11 @@ function shQuiet(cmd, args) {
     console.log(`  [dry] ${cmd}`);
     return '';
   }
-  return execSync(cmd, { cwd: REPO, encoding: 'utf8' });
+  try {
+    return execSync(cmd, { cwd: REPO, encoding: 'utf8' });
+  } catch (e) {
+    throw shFailure(cmd, e);
+  }
 }
 
 /** Run a command for its EXIT STATUS only — true on 0, false on anything
@@ -266,6 +343,56 @@ function shCapture(cmd, args) {
   }
 }
 
+// ── Half-cut detection (gh#765) ──────────────────────────────────
+// An aborted Step-4 run (the v0.8.29 cut aborted three times at Step 4e)
+// leaves a half-cut tree: package versions bumped to the cut version +
+// CHANGELOGs promoted. A plain re-run then FALSE-FAILS the pre-flight —
+// gate 24 (cut-hygiene) validates version currency at args.previous, which
+// the half-done bump has already moved past.
+//
+// DETECT-AND-RESUME, not rollback — the smaller and safer of the two:
+// resume is pure detection at the next invocation's start, so it works no
+// matter HOW the previous run died (crash, SIGINT, kill -9 — a rollback
+// handler never runs for those), and it never touches the working tree,
+// so it cannot discard operator hand-edits the way a `git checkout --`
+// rollback could. The already-correct Step-4 work is kept, not redone.
+//
+// Marker: the lockstep bump is the last tree-wide mutation before the
+// abort point, so ALL roster package.json versions at args.version ⇒ the
+// promote+bump half completed — resume. A MIX of cut/previous versions is
+// a mid-bump abort this orchestrator cannot reason about: hard-stop with
+// the manual recovery pointer. CHANGELOG promotion is then re-proved by
+// Step 4's existing unpromoted-[Unreleased] guard, and the remaining Step-4
+// substeps (lockfile, catalog, 4e notes, 4f fix, 4g hygiene) are idempotent
+// regenerations that simply run again.
+function detectHalfCut(args) {
+  if (args.mode === 'handoff' || args.dry) return false;
+  const versions = PACKAGE_ROSTER.map(({ name, dir }) => {
+    const p = path.join(REPO, dir, 'package.json');
+    return { name, version: JSON.parse(fs.readFileSync(p, 'utf8')).version };
+  });
+  const bumped = versions.filter((v) => v.version === args.version);
+  if (bumped.length === 0) return false; // fresh cut — nothing bumped yet
+  if (bumped.length < versions.length) {
+    console.error(`ERROR: mixed lockstep versions — ${bumped.length}/${versions.length} packages are already`);
+    console.error(`       at ${args.version}, the rest are not (a mid-bump abort?):`);
+    for (const v of versions.filter((x) => x.version !== args.version)) {
+      console.error(`         ✗ ${v.name}: ${v.version}`);
+    }
+    console.error('       This orchestrator can neither resume nor safely roll back a partial');
+    console.error('       bump. Restore the tree first (git status / git checkout -- <files>,');
+    console.error('       or re-run bump.mjs by hand), then re-run.');
+    process.exit(1);
+  }
+  console.log(`
+[resume] half-cut tree detected: all ${versions.length} lockstep packages already at ${args.version}
+         (an earlier run's Step 4 promote+bump completed before it aborted — gh#765).
+         Resuming: pre-flight hygiene validates at ${args.version} instead of
+         ${args.previous}, and Step 4 skips promote/stub/bump, re-running only its
+         idempotent substeps (lockfile, catalog, notes, coverage, hygiene).`);
+  return true;
+}
+
 // ── Step 1 — Re-baseline ──────────────────────────────────────────
 function step1ReBaseline(args) {
   console.log('\n=== Step 1 — Re-baseline ===');
@@ -310,8 +437,21 @@ function step3PreFlight(args) {
     // 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;
+    // version and validating at previous fails by construction. A RESUMED
+    // half-cut run (gh#765) is post-bump too: the earlier aborted run already
+    // moved every reference to the cut version, so validating at previous
+    // false-fails gate 24 exactly like handoff would.
+    const hygieneVersion = (args.mode === 'handoff' || args.resume) ? args.version : args.previous;
+    // A RESUMED run's versionArg gates (cut-hygiene) demand artifacts Step 4
+    // has not recreated yet — docs/releases/vX.Y.Z.md exists only after 4e,
+    // which runs AFTER this pre-flight. Step 4g re-runs these same gates at
+    // the cut version once the notes exist, so skipping them here loses no
+    // coverage — running them here false-fails by construction (the v0.8.32
+    // cut hit exactly this: 23/24 green, gate 24 dead on the missing notes).
+    if (g.versionArg && args.resume) {
+      console.log(`\n  ${g.n}/${GATE_ROSTER.length}. ${g.cmd}   # ${g.what} — [resume] deferred to Step 4g (notes not regenerated yet)`);
+      continue;
+    }
     const cmd = g.versionArg ? `${g.cmd} --version ${hygieneVersion}` : g.cmd;
     console.log(`\n  ${g.n}/${GATE_ROSTER.length}. ${cmd}   # ${g.what}`);
     try {
@@ -371,16 +511,48 @@ function step4PromoteAndBump(args) {
   // optional per window, so `root` joins the promote list exactly when its
   // [Unreleased] carries real content. A repo-level-only window (0.8.7 was
   // one) promotes root with zero substantive packages.
-  const promoteTargets = [...(args.substantivePackages ?? [])];
-  if (unpromotedUnreleased(REPO, 'root')) promoteTargets.push('root');
-  if (promoteTargets.length > 0) {
-    const cmd = `node ${SCRIPT_DIR}/promote-unreleased.mjs --version ${args.version} --date ${args.date} --packages ${promoteTargets.join(',')}`;
-    sh(cmd, args);
-  }
+  // A resumed half-cut run (gh#765, detected in main) already promoted,
+  // stubbed, and bumped — re-running promote/insert-stub would double-insert
+  // sections and bump.mjs --from would no longer match. Skip those three;
+  // the unpromoted-[Unreleased] guard below still re-proves the promotion
+  // actually completed, and every later substep is an idempotent regenerate.
+  if (!args.resume) {
+    const promoteTargets = [...(args.substantivePackages ?? [])];
+    if (unpromotedUnreleased(REPO, 'root')) promoteTargets.push('root');
+    if (promoteTargets.length > 0) {
+      const cmd = `node ${SCRIPT_DIR}/promote-unreleased.mjs --version ${args.version} --date ${args.date} --packages ${promoteTargets.join(',')}`;
+      sh(cmd, args);
+    }
 
-  if (args.stubPackages && args.substantive && args.xref) {
-    const cmd = `node ${SCRIPT_DIR}/insert-stub.mjs --version ${args.version} --date ${args.date} --previous-version ${args.previous} --substantive "${args.substantive}" --xref "${args.xref}" --packages ${args.stubPackages.join(',')}`;
-    sh(cmd, args);
+    if (args.stubPackages && args.substantive && args.xref) {
+      const cmd = `node ${SCRIPT_DIR}/insert-stub.mjs --version ${args.version} --date ${args.date} --previous-version ${args.previous} --substantive "${args.substantive}" --xref "${args.xref}" --packages ${args.stubPackages.join(',')}`;
+      sh(cmd, args);
+    }
+  } else {
+    // The bump-complete marker proves promote+bump ran — it CANNOT see
+    // whether insert-stub ran: a stub package's [Unreleased] is empty, so
+    // the unpromoted guard below passes with the [X.Y.Z] section entirely
+    // absent, and the death arrives later at 4e's generate-release-notes
+    // ("no [X.Y.Z] CHANGELOG section in: …"). The v0.8.32 cut hit exactly
+    // this (the aborted run predated stub insertion). Complete the missing
+    // stubs here instead of skipping blindly — insert-stub hard-errors on
+    // existing sections, so filter to the genuinely missing ones.
+    if (args.stubPackages && args.substantive && args.xref) {
+      const missingStubs = args.stubPackages.filter((pkg) => {
+        const p = resolvePackageChangelog(REPO, pkg);
+        return fs.existsSync(p) && !fs.readFileSync(p, 'utf8').includes(`## [${args.version}]`);
+      });
+      if (missingStubs.length > 0) {
+        console.log(`  [resume] ${missingStubs.length} stub section(s) missing from the aborted run — completing: ${missingStubs.join(', ')}`);
+        sh(`node ${SCRIPT_DIR}/insert-stub.mjs --version ${args.version} --date ${args.date} --previous-version ${args.previous} --substantive "${args.substantive}" --xref "${args.xref}" --packages ${missingStubs.join(',')}`, args);
+      } else {
+        console.log('  [resume] promote/stub already applied by the aborted run — skipping');
+      }
+    } else {
+      console.log('  [resume] promote/stub already applied by the aborted run — skipping');
+      console.log('           (no --stub-packages/--substantive/--xref given; if 4e fails on');
+      console.log('           missing [X.Y.Z] sections, re-run with the stub flags to complete them)');
+    }
   }
 
   // Loud guard: after promotion, NO package in the lockstep set (including
@@ -404,7 +576,11 @@ function step4PromoteAndBump(args) {
     console.log(`  ✓ no unpromoted [Unreleased] content across all ${PACKAGES.length} packages + root`);
   }
 
-  sh(`node ${SCRIPT_DIR}/bump.mjs --from ${args.previous} --to ${args.version}`, args);
+  if (!args.resume) {
+    sh(`node ${SCRIPT_DIR}/bump.mjs --from ${args.previous} --to ${args.version}`, args);
+  } else {
+    console.log(`  [resume] versions already at ${args.version} — skipping bump`);
+  }
   sh('npm install --package-lock-only --no-audit --no-fund', args);
   sh('npm run check:lockstep', args);
 
@@ -493,8 +669,15 @@ function step5Commit(args) {
     `docs/releases/v${args.version}.md`,
     // gh#617: Step 4d.5 regenerates these post-bump (catalogId embeds the
     // lockstep version); unstaged, check:genui-catalog fails in CI (v0.8.26).
+    // catalog-data.js is the same derivation's third output (the browser-safe
+    // ES-module projection of base.json/adia-pack.json) — check-genui-catalog.mjs
+    // verifies its freshness too, but this list never carried it (found live
+    // during the v0.8.33 cut: base.json/adia-pack.json staged and committed
+    // fine, catalog-data.js sat modified-uncommitted, CI caught the drift a
+    // fresh checkout exposes that a local working tree doesn't).
     'packages/genui/adia-catalog/base.json',
     'packages/genui/adia-catalog/adia-pack.json',
+    'packages/genui/adia-catalog/catalog-data.js',
     ...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
@@ -751,11 +934,58 @@ async function step10GhAndSite(args) {
     `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');
+  // gh#762 + PR #775 review: dispatch and settle-wait are ONE shell block so
+  // the tracked run id survives between steps. Three fixes over the old
+  // "poll the newest run for status=completed" shape:
+  //   1. It could settle on the PREVIOUS completed run before the dispatch
+  //      registered — so capture the newest id BEFORE dispatching and wait
+  //      for a NEW id to appear.
+  //   2. It accepted failure/cancelled as settled — so poll the tracked run
+  //      by id and require conclusion=success, else fail the handoff.
+  //   3. It waited in silence while a forgotten run at the production-site
+  //      gate held the deploy-site concurrency group for 56h — so each poll
+  //      names the gate-waiting blocker (id, since, URL).
+  // reap-stale-deploy-gate.yml auto-cancels gate-waiters older than 24h, but
+  // a live handoff should not wait hours to find out.
+  console.log('  Dispatching and waiting for the deploy workflow to settle...');
+  sh(String.raw`
+    prev_id=$(gh run list --workflow=deploy-site.yml --repo adiahealth/gen-ui-kit --limit 1 --json databaseId -q '.[0].databaseId')
+    gh workflow run "Deploy site (${args.host})" --repo adiahealth/gen-ui-kit --ref main
+    run_id=""
+    tries=0
+    while [ "$tries" -lt 60 ]; do
+      sleep 5
+      run_id=$(gh run list --workflow=deploy-site.yml --repo adiahealth/gen-ui-kit --limit 1 --json databaseId -q '.[0].databaseId')
+      if [ -n "$run_id" ] && [ "$run_id" != "$prev_id" ]; then break; fi
+      run_id=""
+      tries=$((tries + 1))
+    done
+    if [ -z "$run_id" ]; then
+      echo "ERROR: the dispatched deploy-site run never appeared within 5 min (newest is still $prev_id) — inspect the Actions tab before retrying" >&2
+      exit 1
+    fi
+    echo "  Tracking dispatched run $run_id..."
+    while :; do
+      status=$(gh run view "$run_id" --repo adiahealth/gen-ui-kit --json status -q .status)
+      [ "$status" = "completed" ] && break
+      blocker=$(gh run list --workflow=deploy-site.yml --repo adiahealth/gen-ui-kit --limit 10 \
+        --json databaseId,status,createdAt,url \
+        -q '[.[] | select(.status == "waiting")] | last | if . == null then "" else "run \(.databaseId) — waiting at the production-site gate since \(.createdAt): \(.url)" end')
+      if [ "$status" = "waiting" ]; then
+        echo "  … run $run_id is at the production-site approval gate: ${'$'}{blocker:-approve it in the Actions UI}"
+      elif [ -n "$blocker" ]; then
+        echo "  … run $run_id is '$status' — BLOCKED BEHIND $blocker (gh#762: approve or cancel that run to release the deploy-site concurrency group)"
+      else
+        echo "  … run $run_id: $status"
+      fi
+      sleep 15
+    done
+    conclusion=$(gh run view "$run_id" --repo adiahealth/gen-ui-kit --json conclusion -q .conclusion)
+    if [ "$conclusion" != "success" ]; then
+      echo "ERROR: deploy-site run $run_id completed with conclusion '$conclusion' — the site deploy did NOT land; investigate the run before re-dispatching" >&2
+      exit 1
+    fi
+    echo "  ✓ deploy-site.yml run $run_id settled: success"`, args);
   // 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);
@@ -767,6 +997,41 @@ async function main() {
   // Fail-fast guard: refuse to git/npm/gh/curl against a non-monorepo directory.
   assertMonorepoRoot(REPO);
   console.log(`adia-release release-pack — v${args.version} (${args.mode})${args.dry ? ' [DRY]' : ''}`);
+  // Stale-plugin-cache self-check (v0.8.32 cut, first failure): the INSTALLED
+  // plugin cache only refreshes on a version bump, so running this script from
+  // the cache mid-cycle can execute a version that predates its own guards
+  // (SKILL.md §Plugin cache). If the repo carries its own copy and the bytes
+  // differ, warn loudly — the repo copy is almost always the newer one.
+  const repoCopy = path.join(REPO, 'packages/plugins/adia-ui-forge/skills/adia-release/scripts/release-pack.mjs');
+  const selfPath = new URL(import.meta.url).pathname;
+  if (fs.existsSync(repoCopy) && path.resolve(selfPath) !== path.resolve(repoCopy)) {
+    const self = fs.readFileSync(selfPath, 'utf8');
+    const repo = fs.readFileSync(repoCopy, 'utf8');
+    if (self !== repo) {
+      console.error('\n⚠  STALE-COPY WARNING: this release-pack.mjs differs from the repo\'s own copy at');
+      console.error(`   ${repoCopy}`);
+      console.error('   The installed plugin cache lags the repo between cuts (SKILL.md §Plugin cache);');
+      console.error('   the repo copy is almost certainly newer — prefer running it:');
+      console.error(`     node ${repoCopy} <same args>\n`);
+    }
+  }
+  // gh#765: an aborted Step-4 run leaves bumped versions + promoted
+  // CHANGELOGs; detect BEFORE pre-flight so gate 24 validates at the right
+  // version and Step 4 skips the already-done promote/stub/bump.
+  args.resume = detectHalfCut(args);
+  // The zero-flag from-scratch shape parseArgs deferred (CodeRabbit, PR #772):
+  // with NEITHER package flag, no CHANGELOG gets a [VERSION] section and
+  // Step 4e is a guaranteed death — unless this is a half-cut RESUME, where
+  // the aborted run already wrote the sections. Only detectHalfCut can tell
+  // the two apart, so the ruling lives here — still BEFORE the pre-flight.
+  if (args.mode === 'from-scratch' && !args.resume && !args.substantivePackages && !args.stubPackages) {
+    console.error('error: --mode from-scratch needs --substantive-packages and/or --stub-packages');
+    console.error(`       covering all ${PACKAGE_NAMES.length} lockstep packages — with neither, no CHANGELOG gets`);
+    console.error(`       a [${args.version}] section and Step 4e (generate-release-notes) dies after`);
+    console.error('       the ~15-min pre-flight (gh#765). A resumed half-cut tree is exempt,');
+    console.error('       but this tree is not half-cut (versions are not at the cut version).');
+    process.exit(2);
+  }
   step1ReBaseline(args);
   step3PreFlight(args);
   step4PromoteAndBump(args);
@@ -859,6 +1124,83 @@ function selftest() {
       process.exit(1);
     }
 
+    // gh#765 — from-scratch with substantive-but-no-stub packages must die at
+    // PARSE time, naming the ride-alongs, BEFORE any pre-flight gate runs
+    // (v0.8.29 burned three ~15-min pre-flight re-runs discovering it at
+    // Step 4e). Mirror of the handoff --gh-notes-file guard below.
+    let guardFailed = false;
+    let guardOut = '';
+    try {
+      execSync(
+        `node "${scriptPath}" --mode from-scratch --version 9.9.9 --date 2026-01-01 --previous-version 9.9.8 ` +
+        `--commit-message-file "${commitFile}" --substantive-packages web-components --dry`,
+        { cwd: REPO, encoding: 'utf8' },
+      );
+    } catch (e) {
+      guardFailed = true;
+      guardOut = (e.stdout || '') + (e.stderr || '');
+    }
+    if (!guardFailed || !guardOut.includes('ride-along') || !guardOut.includes('a2ui-validator')) {
+      console.error('selftest FAIL: from-scratch without --stub-packages must hard-reject at parse time, naming the ride-alongs');
+      process.exit(1);
+    }
+    if (guardOut.includes('Step 3') || guardOut.includes('gate roster')) {
+      console.error('selftest FAIL: the ride-along guard must fire BEFORE the pre-flight, not after');
+      process.exit(1);
+    }
+
+    // CodeRabbit (PR #772): the guard must arm on EITHER flag — a stub-only
+    // invocation used to bypass it entirely. Three shapes: stub-only partial
+    // coverage rejects naming ride-alongs; stub-only full coverage without
+    // the --substantive/--xref pairing rejects (insert-stub would silently
+    // no-op); zero-flag from-scratch on a NON-half-cut tree rejects in main
+    // after detectHalfCut, still before the pre-flight.
+    const rejectShapes = [
+      { flags: '--substantive x --xref y --stub-packages llm', marker: 'ride-along' },
+      { flags: `--stub-packages ${PACKAGE_NAMES.join(',')}`, marker: '--substantive and --xref' },
+      { flags: '', marker: 'needs --substantive-packages and/or --stub-packages' },
+    ];
+    for (const { flags, marker } of rejectShapes) {
+      let failed = false;
+      let out = '';
+      try {
+        execSync(
+          `node "${scriptPath}" --mode from-scratch --version 9.9.9 --date 2026-01-01 --previous-version 9.9.8 ` +
+          `--commit-message-file "${commitFile}" ${flags} --dry`,
+          { cwd: REPO, encoding: 'utf8' },
+        );
+      } catch (e) {
+        failed = true;
+        out = (e.stdout || '') + (e.stderr || '');
+      }
+      if (!failed || !out.includes(marker) || out.includes('gate roster')) {
+        console.error(`selftest FAIL: from-scratch shape "${flags || '(no package flags)'}" must reject pre-flight with "${marker}"`);
+        process.exit(1);
+      }
+    }
+
+    // …and a fully covered from-scratch roster (substantive ∪ stub = all
+    // packages) must pass the guard and assemble its dry plan normally.
+    const stubs = PACKAGE_NAMES.filter((p) => p !== 'web-components').join(',');
+    let coveredOut;
+    try {
+      coveredOut = execSync(
+        `node "${scriptPath}" --mode from-scratch --version 9.9.9 --date 2026-01-01 --previous-version 9.9.8 ` +
+        `--commit-message-file "${commitFile}" --gh-notes-file "${notesFile}" ` +
+        `--substantive "selftest" --xref "CHANGELOG.md#999" ` +
+        `--substantive-packages web-components --stub-packages ${stubs} --dry --yes`,
+        { cwd: REPO, encoding: 'utf8' },
+      );
+    } catch (e) {
+      console.error('selftest FAIL: fully covered from-scratch --dry must pass the ride-along guard');
+      console.error((e.stdout || '') + (e.stderr || ''));
+      process.exit(1);
+    }
+    if (!coveredOut.includes('STOPPING per invariant 3')) {
+      console.error('selftest FAIL: covered from-scratch dry plan missing the invariant-3 stop');
+      process.exit(1);
+    }
+
     // Handoff without --gh-notes-file must die at PARSE time (v0.8.10: the old
     // Step-10-only check fired after tags+publish were irreversible).
     let handoffFailed = false;
@@ -892,7 +1234,10 @@ if (topArgv[0] === 'selftest') {
   selftest();
 } else {
   main().catch((e) => {
-    console.error(e);
+    // sh()/shQuiet() failures already printed the failing command + its
+    // captured output (gh#765) — a full stack re-dump would bury it again.
+    if (e && e.reported) console.error(e.message);
+    else console.error(e);
     rl.close();
     process.exit(1);
   });