mandrel 2.31.0 → 2.33.0

package/.agents/scripts/prune-baseline-orphans.js

@@ -0,0 +1,181 @@
+#!/usr/bin/env node
+
+// .agents/scripts/prune-baseline-orphans.js — Story #5012.
+//
+// Delete the baseline rows that are provably inert, and nothing else.
+//
+// This is the cheap remedy that makes `check-baseline-scope.js` fair. A gate
+// that hard-fails on a stale row is only defensible while clearing one costs a
+// command rather than a full re-score: the honest alternative — re-derive the
+// whole baseline — spends a coverage run or a full-tree MI pass to express a
+// deletion, which is why stale rows accumulate instead.
+//
+// Two row classes qualify, both decidable without measuring anything:
+//
+//   - `absent`       — the row's file is gone from disk.
+//   - `out-of-scope` — the file is still there, but the gate's own
+//                      `targetDirs` / `ignoreGlobs` no longer match it.
+//
+// The pruner never adds a row, never restamps `generatedAt` (a fresh stamp
+// over unmeasured rows is the exact failure an age check exists to catch), and
+// recomputes `rollup` through the kind's own arithmetic so the pruned envelope
+// still validates against its schema. An unreadable scope config degrades to
+// orphan-only pruning rather than treating unknown scope as empty scope.
+//
+// Exit codes:
+//   0  nothing to prune (or, without `--check`, the prune was written)
+//   1  `--check` found rows that would be pruned
+//   2  the pruner could not run
+
+// Fail-fast if the framework's runtime deps are not installed — must be the
+// first import so the check runs before any third-party-importing sibling
+// module is evaluated (Story #3432).
+import './lib/runtime-deps/ensure-installed.js';
+import { PRUNABLE_KINDS, runPrune } from './lib/baselines/orphan-pruner.js';
+import { runAsCli } from './lib/cli-utils.js';
+import { getQuality } from './lib/config/quality.js';
+import { resolveConfig } from './lib/config-resolver.js';
+
+const EXIT_CLEAN = 0;
+const EXIT_WOULD_PRUNE = 1;
+const EXIT_CANNOT_RUN = 2;
+
+const HELP = {
+  invocation:
+    'node .agents/scripts/prune-baseline-orphans.js [--check] [--kind <kind>] [--json]',
+  summary:
+    "Remove baseline rows whose file is gone from disk or has left the gate's scope. Never adds a row, never restamps generatedAt, never re-scores.",
+  flags: [
+    ['--check', 'Report what would be pruned, write nothing, exit 1 if any.'],
+    ['--kind <kind>', 'Prune one kind only (repeatable). Default: all.'],
+    ['--json', 'Emit the report as JSON instead of text.'],
+    ['--cwd <dir>', 'Repository root to prune. Default: process.cwd().'],
+  ],
+  notes: [
+    'Exit codes:\n  0  clean, or pruned\n  1  --check found prunable rows\n  2  the pruner could not run',
+  ],
+};
+
+/**
+ * Parse argv into an options bag. An unknown flag is an error, never a silent
+ * no-op — a typo'd `--dry-run` must not read as "write the files".
+ *
+ * @param {string[]} argv
+ * @returns {{ kinds: string[], check: boolean, json: boolean, cwd: string }}
+ */
+export function parseArgs(argv = []) {
+  const out = { kinds: [], check: false, json: false, cwd: null };
+  let i = 0;
+  while (i < argv.length) {
+    const arg = argv[i];
+    const value = argv[i + 1];
+    i += 1;
+    if (arg === '--check') out.check = true;
+    else if (arg === '--json') out.json = true;
+    else if (arg === '--kind') {
+      out.kinds.push(value);
+      i += 1;
+    } else if (arg === '--cwd') {
+      out.cwd = value;
+      i += 1;
+    } else throw new Error(`unknown flag "${arg}" (try --help)`);
+  }
+  const unknown = out.kinds.filter((k) => !PRUNABLE_KINDS.includes(k));
+  if (unknown.length > 0) {
+    throw new Error(
+      `unknown --kind ${unknown.join(', ')}; expected one of ${PRUNABLE_KINDS.join(', ')}`,
+    );
+  }
+  if (out.kinds.length === 0) out.kinds = [...PRUNABLE_KINDS];
+  out.cwd = out.cwd ?? process.cwd();
+  return out;
+}
+
+/**
+ * Render one kind's outcome as indented text lines.
+ *
+ * @param {object} entry
+ * @param {boolean} check
+ * @returns {string[]}
+ */
+function renderKind(entry, check) {
+  if (!entry.present) return [];
+  if (entry.skipped)
+    return [`  - ${entry.kind}: skipped (${entry.skipReason})`];
+  const suffix = entry.degraded
+    ? ` [orphan-only: ${entry.degradedReason}]`
+    : '';
+  if (entry.removed.length === 0) {
+    return [`  - ${entry.kind}: clean${suffix}`];
+  }
+  const verb = check ? 'would prune' : 'pruned';
+  return [
+    `  - ${entry.kind}: ${verb} ${entry.removed.length} row(s)${suffix}`,
+    ...entry.removed.map((row) => `      · ${row.reason}: ${row.path}`),
+  ];
+}
+
+/**
+ * Render the whole report as text.
+ *
+ * @param {object} report
+ * @returns {string}
+ */
+export function formatReport(report) {
+  const verb = report.check ? 'would prune' : 'pruned';
+  const lines = [
+    `[prune-baseline-orphans] ${verb} ${report.removedCount} row(s) across ` +
+      `${report.writtenCount} file(s)`,
+    ...report.kinds.flatMap((entry) => renderKind(entry, report.check)),
+  ];
+  if (report.check && report.removedCount > 0) {
+    lines.push(
+      '',
+      'Run without --check to write the prune:',
+      '  node .agents/scripts/prune-baseline-orphans.js',
+    );
+  }
+  return lines.join('\n');
+}
+
+/**
+ * CLI entry point. Returns its exit code rather than calling `process.exit()`,
+ * so `runAsCli`'s `propagateExitCode` path settles it through `flushStdio` and
+ * an unbounded report is not truncated at a pipe boundary (Story #4783).
+ *
+ * @returns {Promise<number>}
+ */
+async function main() {
+  let opts;
+  let report;
+  try {
+    opts = parseArgs(process.argv.slice(2));
+    const config = resolveConfig({ cwd: opts.cwd });
+    report = runPrune({
+      cwd: opts.cwd,
+      kinds: opts.kinds,
+      check: opts.check,
+      quality: getQuality(config) ?? { gates: {} },
+    });
+  } catch (err) {
+    const message = err?.message ?? String(err);
+    process.stdout.write(
+      `${JSON.stringify({ schemaVersion: '1', error: message }, null, 2)}\n`,
+    );
+    return EXIT_CANNOT_RUN;
+  }
+  process.stdout.write(
+    opts.json
+      ? `${JSON.stringify(report, null, 2)}\n`
+      : `${formatReport(report)}\n`,
+  );
+  return report.check && report.removedCount > 0
+    ? EXIT_WOULD_PRUNE
+    : EXIT_CLEAN;
+}
+
+runAsCli(import.meta.url, main, {
+  source: 'prune-baseline-orphans',
+  usage: HELP,
+  propagateExitCode: true,
+});

package/.agents/scripts/resolve-stories.js

@@ -11,8 +11,11 @@
  * What it resolves, per Story:
  *   - the issue itself, fetched with **state=all** so an already-landed
  *     sibling is present rather than silently dropped;
- *   - its dependency edges: the union of body-parsed `blocked by #N` /
- *     `depends on #N` and native GitHub `blocked_by` edges;
+ *   - its dependency edges: the union of the body's `---` footer
+ *     (`blocked by #N`, footer-scoped and strict — prose mentioning a blocker
+ *     elsewhere in the body declares nothing) and native GitHub `blocked_by`
+ *     edges, read to exhaustion and failing loud rather than degrading to
+ *     "no edges";
  *   - its declared file footprint, as plain path strings, so the scheduler's
  *     co-dispatch overlap guard has something to work with.
  *
@@ -45,7 +48,7 @@ import {
 } from './lib/orchestration/resolve-stories.js';
 import { createProvider } from './lib/provider-factory.js';
 import { concurrentMap } from './lib/util/concurrent-map.js';
-import { parseApiJson } from './providers/github/request-helpers.js';
+import { paginateRest } from './providers/github/request-helpers.js';
 
 export { buildStoriesEnvelope, parseIds, readNativeBlockedBy, toStoryRecord };
 
@@ -111,9 +114,21 @@ export async function fetchStories(provider, ids) {
 /**
  * Read native blocked_by edges for every Story in the set.
  *
+ * `paginate` is injected rather than imported inside the lib layer so
+ * `readNativeBlockedBy` stays provider-agnostic and unit-testable; production
+ * passes `paginateRest`, which walks every page (the read used to stop at the
+ * first, silently truncating a Story's gates — Story #5046).
+ *
  * @returns {Promise<Map<number, number[]>>}
  */
-export async function readNativeEdges({ provider, stories, owner, repo }) {
+export async function readNativeEdges({
+  provider,
+  stories,
+  owner,
+  repo,
+  paginate = paginateRest,
+  warn = (m) => Logger.warn(m),
+}) {
   const entries = await concurrentMap(
     stories,
     async (story) => [
@@ -123,7 +138,8 @@ export async function readNativeEdges({ provider, stories, owner, repo }) {
         owner,
         repo,
         issueNumber: story.id,
-        parseJson: parseApiJson,
+        paginate,
+        warn,
       }),
     ],
     { concurrency: FETCH_CONCURRENCY },
@@ -197,7 +213,6 @@ export async function runResolveStories(
     stories,
     nativeEdges,
     warn: (m) => Logger.warn(m),
-    config,
   });
   const foreignDone = await resolveForeignDone({
     provider,
@@ -209,7 +224,6 @@ export async function runResolveStories(
     nativeEdges,
     foreignDone,
     warn: () => {},
-    config,
   });
 
   stdout.write(

package/.agents/scripts/run-lint.js

@@ -21,6 +21,32 @@ import process from 'node:process';
 // can spawn directly.
 const useShell = process.platform === 'win32';
 
+/**
+ * A Node gate spelled `node .agents/scripts/<script>` — the shape six of the
+ * eight tasks share. Spelling it once keeps this list readable as what it
+ * actually is (a fan-out roster) instead of a wall of spawn tuples, and keeps
+ * adding a gate from costing the module a maintainability regression for the
+ * boilerplate rather than the behaviour. Mirrors `run-verify.js`'s `gate()`.
+ *
+ * Use bare `node` (PATH-resolved) rather than `process.execPath`:
+ * `process.execPath` on Windows often expands to `C:\Program
+ * Files\nodejs\node.exe`, and spawn(..., { shell: true }) does not quote the
+ * executable, so the space breaks invocation.
+ *
+ * The path is passed WHOLE rather than assembled from a basename. Composing
+ * it (`` `.agents/scripts/${script}` ``) reads better and is wrong:
+ * `check-knip-entries.js` derives which CLIs something actually invokes by
+ * scanning this file's source text for literal script paths, and four of the
+ * gates below are invoked from nowhere else. Interpolating the path made them
+ * invisible to that derivation, so knip called them dead and the ratchet
+ * offered to record live gates as expected-dead — the Story #5012 trap.
+ *
+ * @param {string} name reported in this driver's own error prefix
+ * @param {string} script repo-relative path, spelled as one literal
+ * @returns {{ name: string, cmd: string, args: string[] }}
+ */
+const nodeGate = (name, script) => ({ name, cmd: 'node', args: [script] });
+
 const tasks = [
   {
     name: 'biome',
@@ -47,67 +73,41 @@ const tasks = [
       '!.worktrees/**',
     ],
   },
-  {
-    // Custom Node-based lint for the lifecycle bus surface (Story #2227).
-    // Enforces:
-    //   1. No `Promise.all` over listener arrays under
-    //      `.agents/scripts/lib/orchestration/lifecycle/**`.
-    //   2. Wildcard-observer firewall: no state-mutating imports in
-    //      listener modules that register on `'*'`.
-    // Both rules are mandated by Tech Spec #2189 and have no biome
-    // equivalent.
-    //
-    // Use bare `node` (PATH-resolved) rather than `process.execPath`:
-    // `process.execPath` on Windows often expands to `C:\Program
-    // Files\nodejs\node.exe`, and spawn(..., { shell: true }) does not
-    // quote the executable, so the space breaks invocation.
-    name: 'lifecycle-lint',
-    cmd: 'node',
-    args: ['.agents/scripts/check-lifecycle-lint.js'],
-  },
-  {
-    // Custom Node-based lint for the workflow prose surface (Epic #4474
-    // PR5). Enforces: no workflow may instruct calling an exported
-    // library function that has no CLI entrypoint — the measured
-    // shim-writing failure mode the /plan collapse killed. See
-    // check-workflow-cli-lint.js for the paragraph-level heuristic.
-    name: 'workflow-cli-lint',
-    cmd: 'node',
-    args: ['.agents/scripts/check-workflow-cli-lint.js'],
-  },
-  {
-    // Custom Node-based lint for label-vocabulary citations in
-    // `.agents/docs/SDLC.md` and `.agents/workflows/**/*.md` (Story #2892,
-    // Tech Spec F9 under Epic #2880). Greps inline backtick code
-    // spans for axis-shaped tokens (`type/epic`, etc.) and asserts
-    // only the canonical `<axis>::<value>` separator from
-    // `lib/label-constants.js` appears. Closes the drift gap that
-    // let the original `type/epic` typo land in a since-retired
-    // planning workflow helper.
-    name: 'label-vocabulary',
-    cmd: 'node',
-    args: ['.agents/scripts/lint-label-vocabulary.js'],
-  },
-  {
-    // GitHub Actions job-timeout gate (Story #4936). Enumerates every
-    // `jobs.<id>` key across `.github/workflows/*.yml` and fails when one
-    // sets no `timeout-minutes` (inheriting GitHub's 360-minute default) or
-    // sets one above the ceiling. A deadlocked Windows job burned 44 minutes
-    // of a runner and withheld the failing required check's logs for the
-    // whole time; nothing but this check would have caught the gap.
-    name: 'workflow-timeouts',
-    cmd: 'node',
-    args: ['.agents/scripts/check-workflow-timeouts.js'],
-  },
-  {
-    // Architecture cycle ratchet (Story #3991). Detects directed import
-    // cycles under `.agents/scripts/` and fails on any cycle not in the
-    // committed allowlist (`baselines/arch-cycles.json`). Mirrors the
-    // ratchet-down semantics of `check-dead-exports.js`.
-    name: 'arch-cycles',
-    cmd: 'node',
-    args: ['.agents/scripts/check-arch-cycles.js'],
-  },
+  // Lifecycle surface (Story #2227). Enforces (1) no `Promise.all` under
+  // `.agents/scripts/lib/orchestration/lifecycle/**` — the ledger is
+  // append-only and a parallel write interleaves records; and (2) the
+  // auto-merge lockout: the `gh pr merge` literal appears only in
+  // `single-story-close/phases/auto-merge.js`. Neither has a biome
+  // equivalent. Story #5024 dropped the third rule (the wildcard-observer
+  // firewall) with the bus and the `listeners/` directory its predicate
+  // required.
+  nodeGate('lifecycle-lint', '.agents/scripts/check-lifecycle-lint.js'),
+  // Workflow prose surface (Epic #4474 PR5). No workflow may instruct calling
+  // an exported library function that has no CLI entrypoint — the measured
+  // shim-writing failure mode the /plan collapse killed. See
+  // check-workflow-cli-lint.js for the paragraph-level heuristic.
+  nodeGate('workflow-cli-lint', '.agents/scripts/check-workflow-cli-lint.js'),
+  // Label-vocabulary citations in `.agents/docs/SDLC.md` and
+  // `.agents/workflows/**/*.md` (Story #2892). Greps inline backtick code
+  // spans for axis-shaped tokens (`type/epic`, etc.) and asserts only the
+  // canonical `<axis>::<value>` separator from `lib/label-constants.js`
+  // appears. Closes the drift gap that let the original `type/epic` typo land.
+  nodeGate('label-vocabulary', '.agents/scripts/lint-label-vocabulary.js'),
+  // GitHub Actions job-timeout gate (Story #4936). Fails a `jobs.<id>` that
+  // sets no `timeout-minutes` (inheriting GitHub's 360-minute default) or sets
+  // one above the ceiling. A deadlocked Windows job burned 44 minutes of a
+  // runner and withheld the failing required check's logs for the whole time.
+  nodeGate('workflow-timeouts', '.agents/scripts/check-workflow-timeouts.js'),
+  // Architecture cycle ratchet (Story #3991). Detects directed import cycles
+  // under `.agents/scripts/` and fails on any cycle not in the committed
+  // allowlist (`baselines/arch-cycles.json`).
+  nodeGate('arch-cycles', '.agents/scripts/check-arch-cycles.js'),
+  // Static Gherkin corpus gate (Story #5013): must-compile with the real
+  // parser, then must-bind scoped per step root. Opt-in behind
+  // `qa.gherkinLint`, so it exits 0 as "not configured" in this repo. Here
+  // rather than in run-verify.js so it reaches CI through the same `lint`
+  // required check as arch-cycles; listing it in both would double-pay it.
+  nodeGate('gherkin-corpus', '.agents/scripts/check-gherkin-corpus.js'),
 ];
 
 function runTask({ name, cmd, args }) {

package/.agents/scripts/run-test-profile.js

@@ -8,10 +8,10 @@
  * runner only — set SKIP_PREFLIGHT=0 to include preflight if desired.
  */
 
-import { spawnSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { spawnChild } from './lib/child-exec.js';
 import { runAsCli } from './lib/cli-utils.js';
 import { buildWebhookSafeTestEnv } from './lib/test-env.js';
 import { parseTapOutput } from './lib/test-profile/parse-tap.js';
@@ -56,13 +56,14 @@ export function parseProfileArgv(argv) {
  * @param {object} [opts]
  * @param {string[]} [opts.argv]
  * @param {string} [opts.cwd]
- * @param {typeof spawnSync} [opts.spawn]
+ * @param {Function} [opts.spawn] - Injected child runner; defaults to the
+ *   shared surface's real `spawnSync`.
  * @param {typeof fs} [opts.fs]
  */
 export function runTestProfile({
   argv = process.argv.slice(2),
   cwd = ROOT,
-  spawn = spawnSync,
+  spawn,
   fs: fsLike = fs,
 } = {}) {
   const { outDir, topN, testArgv } = parseProfileArgv(argv);
@@ -75,7 +76,8 @@ export function runTestProfile({
   ];
 
   const started = Date.now();
-  const result = spawn(process.execPath, nodeArgs, {
+  const result = spawnChild(process.execPath, nodeArgs, {
+    run: spawn,
     cwd,
     encoding: 'utf8',
     env: {
@@ -84,8 +86,6 @@ export function runTestProfile({
       FORCE_COLOR: '0',
       NO_COLOR: '1',
     },
-    maxBuffer: 64 * 1024 * 1024,
-    shell: false,
   });
   const wallDurationMs = Date.now() - started;
 

package/.agents/scripts/run-verify.js

@@ -6,8 +6,8 @@
  * locally, without epic-scoped MI projection or push semantics.
  *
  * Order: audit (SCA) → lint (includes docs:check + the arch-cycles ratchet) →
- * full test suite → unified baselines → the dead-exports and context-budget
- * ratchets.
+ * full test suite → unified baselines → the standalone ratchets
+ * (dead-exports ×2, context-budget, cyclomatic, schema-references).
  *
  * The `audit` step runs `npm audit --audit-level=high`, matching CI's
  * "Dependency Vulnerability Audit (SCA)" gate so a local green no longer hides
@@ -27,42 +27,60 @@
  * full-tree scan in check-dead-exports.js) to a command that already carries
  * the full test suite.
  *
- * A handful of CI gates cannot be reproduced by this command (action pinning,
- * TruffleHog secret scan, the BASELINE_SCOPE=full push-scoped maintainability
- * run) — those are catalogued in docs/ci-contract.md.
+ * Story #5004 closed the last two mirror gaps that were pure omission.
+ * `check-cyclomatic.js` (#4923) and `check-schema-references.js` (#4938) were
+ * each added to the `baselines` job's standalone-ratchet slot without ever
+ * being added here, so a green `verify` still hid both. Like their neighbours
+ * they are pure-Node and cost milliseconds.
+ *
+ * Still NOT mirrored: `check-workflow-citations.js` and
+ * `check-baseline-scope.js` run in CI's `baselines` job only —
+ * `.agents/rules/known-tooling-behavior.md` entry 2 carries the current
+ * coverage table. (`prune-baseline-orphans.js --check` used to sit in that
+ * list; it no longer runs in CI at all — the un-attributed duplicate of the
+ * scope gate's `extra` direction reds every open PR on inherited rows.) Nor are the CI gates this command structurally cannot
+ * reproduce (action pinning, TruffleHog secret scan) — those are catalogued
+ * in docs/ci-contract.md. The nightly full-scope re-score
+ * (.github/workflows/baseline-drift.yml) is deliberately outside this
+ * mirror too: it re-scores the whole tree, which is the cost `verify` exists
+ * to avoid paying on every run.
  */
 
 import { spawnSync } from 'node:child_process';
 import { runAsCli } from './lib/cli-utils.js';
 
+/**
+ * A gate step: `node .agents/scripts/<script>` plus any extra args. Seven of
+ * the ten steps share exactly that shape, so spelling it once leaves the list
+ * below readable as what it actually is — a gate *order* — instead of a wall
+ * of spawn tuples.
+ *
+ * @param {string} label reported as `failedStep` when the gate exits non-zero
+ * @param {string} script basename under `.agents/scripts/`
+ * @param {...string} args extra CLI args
+ * @returns {{ label: string, cmd: string, args: string[] }}
+ */
+const gate = (label, script, ...args) => ({
+  label,
+  cmd: 'node',
+  args: [`.agents/scripts/${script}`, ...args],
+});
+
 const STEPS = [
-  {
-    label: 'audit',
-    cmd: 'npm',
-    args: ['audit', '--audit-level=high'],
-  },
+  { label: 'audit', cmd: 'npm', args: ['audit', '--audit-level=high'] },
   { label: 'lint', cmd: 'npm', args: ['run', 'lint'] },
   { label: 'test', cmd: 'npm', args: ['test'] },
-  {
-    label: 'baselines',
-    cmd: 'node',
-    args: ['.agents/scripts/check-baselines.js'],
-  },
-  {
-    label: 'dead-exports',
-    cmd: 'node',
-    args: ['.agents/scripts/check-dead-exports.js'],
-  },
-  {
-    label: 'dead-exports-production',
-    cmd: 'node',
-    args: ['.agents/scripts/check-dead-exports.js', '--production'],
-  },
-  {
-    label: 'context-budget',
-    cmd: 'node',
-    args: ['.agents/scripts/check-context-budget.js'],
-  },
+  gate('baselines', 'check-baselines.js'),
+  // Ordered ahead of the dead-exports pair deliberately. When a new CLI is
+  // missing from knip.json's entry list, both gates fail — but only this one
+  // names the cause. Seeing the ratchet's whole-file diff first is what made
+  // "accept the diff" look like the fix during Story #5012.
+  gate('knip-entries', 'check-knip-entries.js'),
+  gate('dead-exports', 'check-dead-exports.js'),
+  gate('dead-exports-production', 'check-dead-exports.js', '--production'),
+  gate('context-budget', 'check-context-budget.js'),
+  gate('cyclomatic', 'check-cyclomatic.js'),
+  gate('schema-references', 'check-schema-references.js'),
 ];
 
 export function runVerifySteps({

package/.agents/scripts/single-story-close.js

@@ -44,6 +44,18 @@
  *                              [--no-auto-merge]
  *                              [--wait-merge | --no-wait-merge]
  *                              [--merge-watch-mode <sync|async>]
+ *                              [--override-review-block <reason>]
+ *
+ * `--override-review-block <reason>` is the one sanctioned way
+ * past a code-review CRITICAL blocker. A critical finding halts this script
+ * before auto-merge, and until this flag existed there was no override at all —
+ * so an operator who had read a finding and judged it wrong could only land by
+ * running `gh pr merge` themselves, bypassing the gate with nothing written
+ * down. The flag does not weaken the gate; it moves that escape hatch into a
+ * mandatory-reason audit trail (Story comment + PR comment + a
+ * `review-block-overridden` friction signal) and reports
+ * `gates.codeReview: "overridden"` on the terminal envelope. A bare or
+ * too-short reason fails during option parsing, before any phase runs.
  *
  * `--merge-watch-mode` (Story #4949) overrides `delivery.mergeWatch.mode` for
  * one invocation, on the same explicit-wins-over-config precedence
@@ -217,6 +229,14 @@ runAsCli(import.meta.url, main, {
         '--merge-watch-mode <sync|async>',
         'Override delivery.mergeWatch.mode for this invocation only. `async` caps the merge wait to a short probe window and returns the resumable `pending` terminal instead of holding the foreground slot — pass it on every close of a multi-Story run. An invalid value exits non-zero before any phase runs.',
       ],
+      [
+        '--override-review-block <reason>',
+        // Deliberately does not spell the merge CLI invocation: the
+        // merge-lockout rule in `check-lifecycle-lint.js` forbids that literal
+        // in any string outside `phases/auto-merge.js`, and it is right to —
+        // the point of this flag is that arming stays on the one code path.
+        'Land despite a Story-scope code-review CRITICAL blocker you have reviewed and judged wrong. The reason is mandatory (≥12 chars) and is recorded on the Story, on the PR, and as a `review-block-overridden` friction signal; the terminal envelope reports `gates.codeReview: "overridden"`. Use this instead of merging the PR by hand with the GitHub CLI — a hand-merge bypasses the gate with no record at all.',
+      ],
       ['--no-evidence', 'Do not reuse or write gate evidence stamps.'],
       ['--dry-run', 'Report the plan; mutate nothing.'],
     ],