mandrel 2.30.0 → 2.32.0

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.'],
     ],

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

@@ -54,7 +54,6 @@ import {
 import { getStoryBranch, gitSpawn, gitSync } from './lib/git-utils.js';
 import { Logger } from './lib/Logger.js';
 import { TYPE_LABELS } from './lib/label-constants.js';
-import { setActiveStoryEnv } from './lib/observability/active-story-env.js';
 import { emitTerseResult } from './lib/observability/terse-result.js';
 import {
   executeFastForward,
@@ -492,10 +491,9 @@ export function seedStoryBranch({ cwd, storyBranch, baseBranch, progress }) {
 }
 
 /**
- * Provision a worktree (or check out the branch in single-tree mode), then
- * record the active-story environment markers. Returns the resolved
- * `workCwd`, `worktreeCreated`, and `installStatus`. Exported for testing
- * (owns the worktree/single-tree routing + setActiveStoryEnv call).
+ * Provision a worktree (or check out the branch in single-tree mode).
+ * Returns the resolved `workCwd`, `worktreeCreated`, and `installStatus`.
+ * Exported for testing (owns the worktree/single-tree routing).
  *
  * @param {object} opts
  * @param {object} opts.runtime
@@ -541,23 +539,6 @@ export async function provisionWorktree({
     gitSync(cwd, 'checkout', storyBranch);
   }
 
-  try {
-    // v2 Stories are standalone — no parent Epic. The helper omits
-    // CC_EPIC_ID from env + file; the trace hook keys its standalone-trace
-    // branch on CC_EPIC_ID being absent.
-    setActiveStoryEnv({
-      storyId,
-      workCwd,
-      logger: {
-        warn: (m) => progress('ENV', `⚠️ ${m}`),
-      },
-    });
-  } catch (err) {
-    Logger.error(
-      `[single-story-init] ⚠️ Failed to set active-Story env: ${err?.message ?? err}`,
-    );
-  }
-
   return { workCwd, worktreeCreated, installStatus };
 }
 
@@ -572,13 +553,11 @@ export async function runSingleStoryInit({
   injectedConfig,
   injectedSweep,
   // Story #3483: lets tests drive the lease preflight deterministically.
-  // `injectedAcquireLease` swaps the guard; `leaseNow` injects the clock the
-  // fail-closed liveness check evaluates against (audit #3513). `steal`
-  // forcibly transfers a foreign claim — the standalone path has no Epic
-  // heartbeat ledger, so a foreign assignee blocks unless stolen.
+  // `injectedAcquireLease` swaps the guard. `steal` forcibly transfers a
+  // foreign claim — the lease fails closed (audit #3513), so a foreign
+  // assignee blocks unless stolen.
   injectedAcquireLease,
   steal = false,
-  leaseNow,
   injectedVerifyRemote,
   // Story #4620: swap the git-touching provisioning steps so the
   // early-flip-then-rollback ordering is unit-testable without a real worktree.
@@ -652,13 +631,12 @@ export async function runSingleStoryInit({
     `Standalone Story: "${story.title}" → branch ${storyBranch} from ${baseBranch}.`,
   );
 
-  // Story #3483 — lease preflight. Take an exclusive, time-bounded claim on
-  // the Story ticket before any git mutation so two concurrent standalone
-  // runs cannot both drive the same Story. The standalone path has no Epic
-  // heartbeat ledger, so the guard fails closed (audit #3513): a foreign
-  // assignee is treated as a live claim and aborts init (naming the current
-  // owner) unless --steal forcibly transfers it. Unclaimed / self-held claims
-  // proceed. Skipped under --dry-run (no assignee mutation).
+  // Story #3483 — lease preflight. Take an exclusive claim on the Story
+  // ticket before any git mutation so two concurrent standalone runs cannot
+  // both drive the same Story. The guard fails closed (audit #3513): a
+  // foreign assignee aborts init (naming the current owner) unless --steal
+  // forcibly transfers it. Unclaimed / self-held claims proceed. Skipped
+  // under --dry-run (no assignee mutation).
   let workCwd = cwd;
   let worktreeCreated = false;
   let installStatus = { status: 'skipped', reason: 'dry-run' };
@@ -670,7 +648,6 @@ export async function runSingleStoryInit({
       storyId,
       config,
       steal: stealRequested,
-      now: leaseNow,
     });
     progress(
       'LEASE',