mandrel 1.57.0

package/.agents/scripts/lib/close-validation.js

@@ -0,0 +1,897 @@
+/**
+ * close-validation.js — Shift-left validation gates for story-close.
+ *
+ * Runs typecheck, lint, test, format check, and maintainability/coverage/
+ * CRAP regression checks before the story merge so drift is caught in the
+ * worktree rather than at pre-push time on the Epic branch. Format command
+ * is configurable via `project.commands.formatCheck`; default is
+ * `npx biome format .`. All gates inherit stdio so the operator sees the
+ * raw output; the returned summary surfaces actionable hints on failure.
+ *
+ * Pre-merge MI projection (Story #781) is re-exported from
+ * `close-validation/projections/maintainability.js` — the engine that
+ * surfaces, by name, the files that would breach their per-file MI
+ * baseline post-merge so the operator can ship a `baseline-refresh:`
+ * commit atomically with the Story PR.
+ */
+
+import { execFileSync, spawn } from 'node:child_process';
+import { writeFile as defaultWriteFile } from 'node:fs/promises';
+import { diffNameOnly } from './changed-files.js';
+import { defaultGetHeadSha } from './close-validation/projections/head-sha.js';
+import { getCommands } from './config/commands.js';
+import { storyArtifactPath } from './config/temp-paths.js';
+import { getSpawnCount as defaultGetSpawnCount } from './gh-exec.js';
+import {
+  recordPass as defaultRecordPass,
+  shouldSkip as defaultShouldSkip,
+  hashCommandConfig,
+} from './validation-evidence.js';
+
+/**
+ * @typedef {Object} Gate
+ * @property {string}   name  - Short label used in progress logs.
+ * @property {string}   cmd   - Executable to run.
+ * @property {string[]} args  - Arguments passed to `cmd`.
+ * @property {string}   [hint] - Remediation hint shown on failure.
+ * @property {{ baseRef: string }} [changedFileScope] - Optional Story-diff scope.
+ * @property {Record<string, string>} [env] - Optional per-gate environment
+ *   overlay. Merged over `process.env` for this gate's spawned child only.
+ *   Used to thread the epic baseRef into the `check-baselines` gate via
+ *   `BASELINE_REF` (Story #3890) so baseline regressions compare against the
+ *   epic integration branch rather than `origin/main`.
+ * @property {(cmd: string, args: string[], opts: { cwd: string, gateName?: string, log?: (m: string) => void, signal?: AbortSignal, env?: Record<string, string> }) => Promise<{ status: number }> | { status: number }} [run]
+ *   - Optional in-process runner. Story #1973: when present, the gate
+ *     executes via this callable instead of spawning `cmd`/`args` through
+ *     the default runner — used for per-kind baseline gates that import
+ *     `compare(head, base)` directly.
+ */
+
+/**
+ * Fallback typecheck command — the gate is mandatory by design (Epic-branch
+ * type regressions surface in the next Story's pre-push otherwise).
+ */
+const TYPECHECK_FALLBACK = 'npm run typecheck';
+
+const TYPECHECK_HINT =
+  'TypeScript regression — fix type errors on the Story branch before retrying close. If the failure is a stale generated type (e.g. wrangler types), regenerate locally and commit before the close.';
+
+/** Default formatter command when `project.commands.formatCheck` is unset. */
+const FORMAT_CHECK_FALLBACK = 'npx biome format .';
+
+/** Default formatter command in write mode. */
+const FORMAT_WRITE_FALLBACK = 'npx biome format --write .';
+
+/**
+ * Build the format-gate hint dynamically from the resolved write command so
+ * a Prettier-only repo gets `prettier --write` in its hint, not biome.
+ */
+function buildFormatHint(writeCmd) {
+  const cmd =
+    writeCmd && writeCmd.trim().length > 0 ? writeCmd : FORMAT_WRITE_FALLBACK;
+  return `Run \`${cmd}\` to auto-fix formatting drift.`;
+}
+
+/**
+ * Resolve a string `project.commands.<key>` with a fallback when the
+ * value is missing, empty, or the resolver throws on malformed config.
+ * Shared engine behind the three resolveX command helpers.
+ *
+ * @param {{ project?: { commands?: object } } | null | undefined} config
+ *   Canonical resolved config (or a bare `{ project: { commands } }` bag).
+ * @param {string} key
+ * @param {string} fallback
+ * @returns {string}
+ */
+function resolveCommandWithFallback(config, key, fallback) {
+  try {
+    // `getCommands` reads `config.project.commands` from the canonical
+    // resolved config.
+    const cmds = getCommands(config);
+    const value = cmds[key];
+    if (typeof value === 'string' && value.trim().length > 0) {
+      return value.trim();
+    }
+  } catch {
+    // Malformed config — fall through to the framework default.
+  }
+  return fallback;
+}
+
+/**
+ * Resolve the typecheck command. Reads `project.commands.typecheck`;
+ * falls back to `npm run typecheck`. The framework-wide
+ * `COMMANDS_DEFAULTS.typecheck` is `null` but this gate is mandatory, so
+ * we apply the fallback here. Exported for testing.
+ *
+ * @param {{ project?: { commands?: object } } | null | undefined} config
+ * @returns {string}
+ */
+export function resolveTypecheckCommand(config) {
+  return resolveCommandWithFallback(config, 'typecheck', TYPECHECK_FALLBACK);
+}
+
+/**
+ * Resolve the format-check command. Reads `project.commands.formatCheck`;
+ * falls back to `npx biome format .` so existing repos keep working byte-
+ * for-byte. Exported for testing.
+ *
+ * @param {{ project?: { commands?: object } } | null | undefined} config
+ * @returns {string}
+ */
+export function resolveFormatCheckCommand(config) {
+  return resolveCommandWithFallback(
+    config,
+    'formatCheck',
+    FORMAT_CHECK_FALLBACK,
+  );
+}
+
+/**
+ * Resolve the format-write command used by story-close format-autofix (and
+ * surfaced in the format-gate hint). Reads `project.commands.formatWrite`;
+ * falls back to `npx biome format --write .`. Exported for testing.
+ *
+ * @param {{ project?: { commands?: object } } | null | undefined} config
+ * @returns {string}
+ */
+export function resolveFormatWriteCommand(config) {
+  return resolveCommandWithFallback(
+    config,
+    'formatWrite',
+    FORMAT_WRITE_FALLBACK,
+  );
+}
+
+/**
+ * Compute the Story-diff file scope for formatter gates. The default Biome
+ * formatter used to run against `.` from inside `.worktrees/story-*`, which
+ * lets consumer ignore globs that exclude `.worktrees` self-exclude the whole
+ * run. Scoping to changed paths keeps verification real without depending on
+ * how consumers spell root ignore patterns.
+ *
+ * @param {{ cwd: string, baseRef: string }} opts
+ * @returns {string[]}
+ */
+export function listChangedFilesForFormatGate({ cwd, baseRef }) {
+  if (!cwd) throw new Error('listChangedFilesForFormatGate: cwd is required');
+  if (!baseRef)
+    throw new Error('listChangedFilesForFormatGate: baseRef is required');
+  // Bridge execFileSync into the gitSpawn(cwd, ...args) contract so
+  // diffNameOnly owns the stdout → path-list conversion.
+  const gitSpawn = (_cwd, ...args) => {
+    try {
+      const stdout = execFileSync('git', args, {
+        cwd: _cwd,
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'pipe'],
+      });
+      return { status: 0, stdout, stderr: '' };
+    } catch (err) {
+      return {
+        status: err.status ?? 1,
+        stdout: err.stdout ?? '',
+        stderr: err.stderr ?? err.message,
+      };
+    }
+  };
+  return diffNameOnly({ baseRef, cwd, gitSpawn });
+}
+
+function buildChangedFileScope(baseRef) {
+  if (!baseRef) return null;
+  return { baseRef };
+}
+
+/**
+ * Derive the per-gate `env` overlay that pins the `check-baselines`
+ * regression-compare base to the close run's integration branch
+ * (Story #3890).
+ *
+ * The baselines gate resolves its compare ref through `resolveScope`,
+ * whose environment layer reads `BASELINE_REF`. Threading
+ * `origin/<epicBranch>` here makes the gate diff head against the epic
+ * integration branch instead of the framework-default `origin/main`, so
+ * drift that already landed on `main` but is outside the Story's own diff
+ * does not surface as a phantom regression. The same convention
+ * (`origin/<epicBranch>`) is used by the baseline-attribution and
+ * auto-refresh paths, keeping read/compare bases aligned.
+ *
+ * Returns `null` when no integration branch is supplied (the gate then
+ * keeps its existing default-ref / consumer-config behaviour untouched).
+ *
+ * @param {string|undefined|null} epicBranch
+ * @returns {{ BASELINE_REF: string } | null}
+ */
+function buildBaselinesGateEnv(epicBranch) {
+  if (typeof epicBranch !== 'string' || epicBranch.length === 0) return null;
+  return { BASELINE_REF: `origin/${epicBranch}` };
+}
+
+/**
+ * File extensions Biome's formatter can process. Used to filter the
+ * changed-file scope down to the formatter-eligible subset (Story #3410):
+ * passing only ineligible paths (e.g. a docs-only Story whose diff is all
+ * markdown) makes `biome format <files>` report "No files were processed"
+ * and exit 1, failing the gate for a Story that has nothing to format.
+ *
+ * The set mirrors Biome's handled languages (JS/TS family + JSON + CSS).
+ * Markdown, YAML, and other unhandled types are intentionally absent — the
+ * default formatter is biome, so the scope is keyed to what biome formats.
+ * Consumers who swap the formatter via `project.commands.formatCheck`
+ * do not get `changedFileScope` at all (see `buildDefaultGates`), so this
+ * filter only ever runs against the default biome command.
+ */
+const FORMATTER_ELIGIBLE_EXTENSIONS = new Set([
+  'ts',
+  'tsx',
+  'js',
+  'jsx',
+  'mjs',
+  'cjs',
+  'json',
+  'jsonc',
+  'css',
+]);
+
+/**
+ * Whether a changed path is eligible for the default (biome) formatter,
+ * decided purely by file extension. Pure function — no I/O. Exported for
+ * unit coverage (Story #3410).
+ *
+ * @param {string} filePath - A repo-relative path (forward-slash normalized).
+ * @returns {boolean}
+ */
+export function isFormatterEligible(filePath) {
+  if (typeof filePath !== 'string') return false;
+  const lastSlash = Math.max(
+    filePath.lastIndexOf('/'),
+    filePath.lastIndexOf('\\'),
+  );
+  const base = filePath.slice(lastSlash + 1);
+  const dot = base.lastIndexOf('.');
+  // No extension (dotfile-only or extensionless) → not formatter-eligible.
+  if (dot <= 0) return false;
+  const ext = base.slice(dot + 1).toLowerCase();
+  return FORMATTER_ELIGIBLE_EXTENSIONS.has(ext);
+}
+
+function applyChangedFileScope({ gate, spawnCwd, log }) {
+  if (!gate.changedFileScope) {
+    return { gate, cmd: gate.cmd, args: gate.args, skip: false };
+  }
+  const changedFiles = listChangedFilesForFormatGate({
+    cwd: spawnCwd,
+    baseRef: gate.changedFileScope.baseRef,
+  });
+  // Filter to the formatter-eligible subset before deciding to skip. A
+  // non-empty diff that contains zero formatter-eligible files (e.g. a
+  // docs-only Story) must take the skip path, not invoke biome with only
+  // ineligible paths — biome reports "No files were processed" and exits 1
+  // in that case (Story #3410).
+  const eligibleFiles = changedFiles.filter(isFormatterEligible);
+  if (eligibleFiles.length === 0) {
+    log(
+      `[close-validation] ⏭ ${gate.name} skipped (no formatter-eligible changed files)`,
+    );
+    return { gate, cmd: gate.cmd, args: gate.args, skip: true };
+  }
+  const args =
+    gate.args[gate.args.length - 1] === '.'
+      ? gate.args.slice(0, -1)
+      : gate.args;
+  log(
+    `[close-validation] ↳ ${gate.name} scoped to ${eligibleFiles.length} formatter-eligible changed file(s) from ${gate.changedFileScope.baseRef}...HEAD`,
+  );
+  return {
+    gate,
+    cmd: gate.cmd,
+    args: [...args, ...eligibleFiles],
+    skip: false,
+  };
+}
+
+/**
+ * Resolve whether the CRAP gate is enabled. When enabled, the close-
+ * validation graph drops the standalone `test` gate because coverage-
+ * capture already runs the suite under c8 instrumentation (Story #1798).
+ *
+ * Reads the single canonical shape `delivery.quality.gates.crap.enabled`
+ * from the resolved config. Defaults to `true` so an omitted setting
+ * matches `CRAP_GATE_DEFAULTS.enabled`. We deliberately do NOT round-trip
+ * through `getQuality()` here because that resolver expects the unresolved
+ * `gates.crap.*` shape.
+ *
+ * @param {object|undefined|null} config - Canonical resolved config.
+ * @returns {boolean}
+ */
+function isCrapGateEnabled(config) {
+  if (!config || typeof config !== 'object') return true;
+  const enabled = config?.delivery?.quality?.gates?.crap?.enabled;
+  return typeof enabled === 'boolean' ? enabled : true;
+}
+
+/**
+ * Conditionally produce the standalone `test` gate entry. Returns an empty
+ * array when the CRAP gate is enabled (Story #1798: coverage-capture is the
+ * canonical test runner in that mode); returns the legacy single-entry
+ * gate otherwise. Splitting this out keeps `buildDefaultGates` flat for
+ * the CRAP-cyclomatic gate.
+ *
+ * @param {object|undefined|null} config - Canonical resolved config.
+ * @returns {Gate[]}
+ */
+function buildTestGateEntry(config) {
+  if (isCrapGateEnabled(config)) return [];
+  return [{ name: 'test', cmd: 'npm', args: ['test'] }];
+}
+
+/**
+ * Build the canonical close-validation gate list.
+ *
+ * Ordering (cheapest fast-fail first): typecheck → lint → [test] →
+ * format → coverage-capture → check-baselines. The standalone `test`
+ * gate is dropped when `crap.enabled === true` (Story #1798) because
+ * coverage-capture carries test-failure signalling under c8 in that
+ * mode.
+ *
+ * `typecheck` is mandatory; consumers may customise the command via
+ * `project.commands.typecheck` (default `npm run typecheck`).
+ *
+ * Story #2210 retired the legacy per-kind in-process regression gates
+ * (`check-maintainability`, `check-crap`, `check-mutation`) and their
+ * shared `buildInProcessBaselineGate` runner. The unified
+ * `check-baselines` gate is now the single source of truth for per-kind
+ * regression enforcement (attribution-wired floor + tolerance + schema).
+ * The `epicBranch` parameter threads the close run's integration branch
+ * into two gates: the `format` gate's `changedFileScope` (existing) and —
+ * since Story #3890 — the `check-baselines` gate's `BASELINE_REF` env, so
+ * the baselines regression compare diffs head against the epic integration
+ * branch (`origin/<epicBranch>`) rather than the framework-default
+ * `origin/main`. Without this, every child Story on an `epic/<id>` branch
+ * re-discovered inherited main-vs-epic drift in untouched files as phantom
+ * regressions and worked around it by hand-setting `BASELINE_REF`.
+ *
+ * @param {{ config?: object, epicBranch?: string }} [opts] - `config` is the
+ *   canonical resolved config (`{ project, delivery, ... }`); gate commands
+ *   resolve from `project.commands` and the CRAP toggle from
+ *   `delivery.quality.gates.crap.enabled`. `epicBranch` is the close run's
+ *   integration branch (`epic/<id>` for Epic-attached Stories, the base
+ *   branch for standalone Stories).
+ * @returns {Gate[]}
+ */
+export function buildDefaultGates({ config, epicBranch } = {}) {
+  const typecheckCmdString = resolveTypecheckCommand(config);
+  const [typecheckCmd, ...typecheckArgs] = typecheckCmdString
+    .split(/\s+/)
+    .filter(Boolean);
+  const formatCheckString = resolveFormatCheckCommand(config);
+  const [formatCmd, ...formatArgs] = formatCheckString
+    .split(/\s+/)
+    .filter(Boolean);
+  const formatWriteString = resolveFormatWriteCommand(config);
+  const formatChangedFileScope =
+    formatCheckString === FORMAT_CHECK_FALLBACK
+      ? buildChangedFileScope(epicBranch)
+      : null;
+  const baselinesGateEnv = buildBaselinesGateEnv(epicBranch);
+  return [
+    {
+      name: 'typecheck',
+      cmd: typecheckCmd,
+      args: typecheckArgs,
+      hint: TYPECHECK_HINT,
+    },
+    { name: 'lint', cmd: 'npm', args: ['run', 'lint'] },
+    ...buildTestGateEntry(config),
+    {
+      // Gate name kept generic ("format") so the close-orchestrator log line
+      // and the per-gate phase-timer key don't shift when a repo swaps biome
+      // for Prettier / dprint via `project.commands.formatCheck`. The
+      // actual command and the remediation hint resolve from config.
+      name: 'format',
+      cmd: formatCmd,
+      args: formatArgs,
+      hint: buildFormatHint(formatWriteString),
+      ...(formatChangedFileScope
+        ? { changedFileScope: formatChangedFileScope }
+        : {}),
+    },
+    {
+      name: 'coverage-capture',
+      cmd: 'node',
+      args: ['.agents/scripts/coverage-capture.js'],
+      hint: 'Coverage capture failed — `npm run test:coverage` exited non-zero. Fix failing tests or coverage-threshold breaches, then re-run close.',
+    },
+    {
+      // Story #2210 — unified `check-baselines` gate is the only path for
+      // per-kind regression enforcement. The legacy per-kind in-process
+      // gates (`check-maintainability`, `check-crap`, `check-mutation`)
+      // were retired with `buildInProcessBaselineGate` because their
+      // regression-compare semantics are fully subsumed by this gate's
+      // attribution-wired floor + tolerance + schema enforcement, and
+      // running both paths in series was redundant and conflict-prone.
+      //
+      // `check-baselines.js` self-skips per-kind gates whose
+      // `enabled === false` is configured, so registering it
+      // unconditionally is safe.
+      name: 'check-baselines',
+      cmd: 'node',
+      args: ['.agents/scripts/check-baselines.js', '--format', 'text'],
+      hint: 'Unified baselines gate breached. Inspect the JSON report (`node .agents/scripts/check-baselines.js`) to see which kind/component/axis fell below floor; remediate the underlying file(s) or — when the regression is intentional — refresh the relevant baseline through its per-kind update script and commit with a `baseline-refresh:` tagged subject.',
+      ...(baselinesGateEnv ? { env: baselinesGateEnv } : {}),
+    },
+  ];
+}
+
+/**
+ * Default gate list resolved with no consumer config — uses the
+ * `npm run typecheck` fallback for the typecheck gate. Call sites that have a
+ * resolved config object in scope (e.g. `story-close.js`) should
+ * prefer `buildDefaultGates({ config })` so a configured
+ * `project.commands.typecheck` is honoured.
+ *
+ * @type {Gate[]}
+ */
+export const DEFAULT_GATES = buildDefaultGates();
+
+/**
+ * Gates whose I/O is read-only against the working tree (no shared mutable
+ * state, no overlapping ports/sockets). Safe to run concurrently — see
+ * `runCloseValidation` for the Promise.all + AbortController plumbing.
+ */
+export const INDEPENDENT_GATE_NAMES = new Set(['lint', 'format', 'typecheck']);
+
+/**
+ * Partition a gate list into the parallel-safe set and the order-sensitive
+ * remainder. Order is preserved within each bucket so the serial walk stays
+ * cheapest-fast-fail-first (test → coverage-capture → check-baselines).
+ *
+ * @param {Gate[]} gates
+ * @returns {{ independent: Gate[], serial: Gate[] }}
+ */
+export function partitionGates(gates) {
+  const independent = [];
+  const serial = [];
+  for (const gate of gates) {
+    if (INDEPENDENT_GATE_NAMES.has(gate.name)) independent.push(gate);
+    else serial.push(gate);
+  }
+  return { independent, serial };
+}
+
+/**
+ * Pipe a child stream's output line-by-line through `emit`, prepending
+ * `prefix` to each line. Tail bytes without a trailing newline flush on
+ * `end` so the operator never loses the last line of a gate's output.
+ */
+function pipePrefixed(stream, prefix, emit) {
+  let buf = '';
+  stream.setEncoding('utf8');
+  stream.on('data', (chunk) => {
+    buf += chunk;
+    while (true) {
+      const nl = buf.indexOf('\n');
+      if (nl === -1) break;
+      emit(prefix + buf.slice(0, nl));
+      buf = buf.slice(nl + 1);
+    }
+  });
+  stream.on('end', () => {
+    if (buf.length > 0) emit(prefix + buf);
+  });
+}
+
+/**
+ * Default async gate runner — used by `runCloseValidation` when no `runner`
+ * is injected. Spawns the gate via `child_process.spawn`, prefixes every
+ * stdout/stderr line with `[gate-name] ` (so concurrent gates don't bleed
+ * into each other in the operator's terminal), and resolves only when the
+ * child exits.
+ *
+ * Honours `opts.signal`: a TERM is delivered to the child the moment the
+ * signal fires, so a sibling gate's failure aborts the rest of the wave
+ * promptly. The promise still resolves (rather than rejecting) on abort —
+ * `runCloseValidation` sees a non-zero status and folds it into the
+ * already-recorded first-failure.
+ *
+ * @param {string} cmd
+ * @param {string[]} args
+ * @param {{ cwd: string, signal?: AbortSignal, gateName?: string, log?: (m: string) => void, env?: Record<string, string> }} opts
+ * @returns {Promise<{ status: number }>}
+ */
+/** Wire the AbortSignal so an abort kills the child. Returns the cleanup fn. */
+export function attachGateAbortHandler(child, signal) {
+  if (!signal) return () => {};
+  const killChild = () => {
+    try {
+      child.kill('SIGTERM');
+    } catch {
+      /* race: already exited */
+    }
+  };
+  if (signal.aborted) {
+    killChild();
+    return () => {};
+  }
+  signal.addEventListener('abort', killChild, { once: true });
+  return () => signal.removeEventListener('abort', killChild);
+}
+
+/** SIGTERM (no exit code) on abort → non-zero so the gate counts as failed. */
+export function gateExitCode(code, sig) {
+  if (typeof code === 'number') return code;
+  return sig ? 143 : 1;
+}
+
+function defaultGateRunner(cmd, args, opts = {}) {
+  const { cwd, signal, gateName, log, env } = opts;
+  const child = spawn(cmd, args, {
+    cwd,
+    shell: process.platform === 'win32',
+    stdio: ['ignore', 'pipe', 'pipe'],
+    // Per-gate env overlay (Story #3890): merged over the inherited
+    // environment so a gate-scoped `BASELINE_REF` reaches the spawned
+    // `check-baselines` child without mutating the parent process env.
+    ...(env ? { env: { ...process.env, ...env } } : {}),
+  });
+  const prefix = gateName ? `[${gateName}] ` : '';
+  const emit =
+    typeof log === 'function' ? log : (m) => process.stdout.write(`${m}\n`);
+  pipePrefixed(child.stdout, prefix, emit);
+  pipePrefixed(child.stderr, prefix, emit);
+  const detach = attachGateAbortHandler(child, signal);
+  return new Promise((resolve) => {
+    child.on('exit', (code, sig) => {
+      detach();
+      resolve({ status: gateExitCode(code, sig) });
+    });
+    child.on('error', () => {
+      detach();
+      resolve({ status: 1 });
+    });
+  });
+}
+
+/**
+ * Run every gate sequentially. Stops collecting after the first failure but
+ * still returns a summary so the caller decides how to surface the result.
+ *
+ * Worktree locality (Story #1120): when `worktreePath` is supplied, every
+ * gate runner is spawned with `cwd: worktreePath` so the gate sees the
+ * Story branch's post-rebase tree. Evidence reads/writes still key against
+ * `cwd` (the main checkout) because the per-Epic temp tree lives under
+ * the main `.git/`. Failure messages name the worktree path.
+ *
+ * Evidence-aware: when both `storyId` and `epicId` are provided and
+ * `useEvidence !== false`, each gate consults `validation-evidence
+ * .shouldSkip()` against current HEAD + the gate's command-config hash. A
+ * matching record skips the gate; a successful run is recorded so the
+ * next caller in the local hot path can skip in turn.
+ *
+ * `onGateStart` is invoked immediately before each gate's runner spawn.
+ * story-close uses it to drive `phaseTimer.mark(...)` for per-gate
+ * wall-clock telemetry. Errors thrown from the hook propagate.
+ *
+ * @param {{
+ *   cwd: string,
+ *   worktreePath?: string,
+ *   gates?: Gate[],
+ *   runner?: (cmd: string, args: string[], opts: { cwd: string, signal?: AbortSignal, gateName?: string, log?: (m: string) => void }) => Promise<{ status: number }> | { status: number },
+ *   log?: (m: string) => void,
+ *   onGateStart?: (gate: Gate) => void,
+ *   storyId?: number|null,
+ *   epicId?: number|null,
+ *   useEvidence?: boolean,
+ *   evidenceClock?: () => number,
+ *   getHeadSha?: (cwd: string) => string|null,
+ *   recordPass?: typeof defaultRecordPass,
+ *   shouldSkip?: typeof defaultShouldSkip,
+ * }} opts
+ * @returns {{ ok: boolean, failed: Array<{ gate: Gate, status: number, cwd: string }>, skipped: Array<{ gate: Gate, reason: string }> }}
+ */
+export async function runCloseValidation({
+  cwd,
+  worktreePath,
+  gates = DEFAULT_GATES,
+  runner = defaultGateRunner,
+  log = () => {},
+  onGateStart,
+  storyId = null,
+  epicId = null,
+  useEvidence = true,
+  evidenceClock = () => Date.now(),
+  getHeadSha = (resolvedCwd) => defaultGetHeadSha(resolvedCwd),
+  recordPass = defaultRecordPass,
+  shouldSkip = defaultShouldSkip,
+} = {}) {
+  const failed = [];
+  const skipped = [];
+  const evidenceActive = useEvidence && storyId != null && epicId != null;
+  // Evidence keys against the main checkout's HEAD because the per-Epic
+  // evidence file lives under the main `.git/`. Gate spawn, in contrast,
+  // runs in the worktree when one is supplied — that's the whole point of
+  // Story #1120.
+  const spawnCwd = worktreePath ?? cwd;
+  const headSha = evidenceActive ? getHeadSha(spawnCwd) : null;
+
+  // Helper closures so the parallel and serial passes share evidence
+  // bookkeeping bit-for-bit.
+
+  /** Returns a `{ skip: true }` verdict when evidence makes the gate redundant. */
+  const evidenceVerdict = (gate, configHash) => {
+    if (!(evidenceActive && headSha)) return { skip: false };
+    const verdict = shouldSkip(
+      {
+        storyId,
+        gateName: gate.name,
+        currentSha: headSha,
+        configHash,
+        inputFingerprint: gate.inputFingerprint ?? null,
+      },
+      { cwd, epicId },
+    );
+    if (verdict.skip) {
+      const tsHint = verdict.record?.timestamp
+        ? ` recorded ${verdict.record.timestamp}`
+        : '';
+      log(
+        `[close-validation] ⏭ ${gate.name} skipped (${verdict.reason}: SHA=${headSha.slice(0, 7)}${tsHint})`,
+      );
+    }
+    return verdict;
+  };
+
+  const recordIfActive = (gate, configHash, durationMs) => {
+    if (!(evidenceActive && headSha)) return;
+    try {
+      recordPass(
+        {
+          storyId,
+          gateName: gate.name,
+          sha: headSha,
+          configHash,
+          exitCode: 0,
+          durationMs,
+          inputFingerprint: gate.inputFingerprint ?? null,
+        },
+        { cwd, epicId },
+      );
+    } catch (err) {
+      log(
+        `[close-validation]   ⚠ failed to record evidence for ${gate.name}: ${err?.message ?? err}`,
+      );
+    }
+  };
+
+  /**
+   * Run a single gate. When `gate.run` is a function the gate executes
+   * **in process** (Story #1973 / Task #1984 — per-kind baseline gates
+   * removed their `child_process.spawn(node check-<kind>.js)` arm and
+   * call `compare(head, base)` directly). The `run` callable receives
+   * the same `(cmd, args, opts)` argv shape as `runner` so it slots into
+   * the existing contract without churn at the runner boundary.
+   * Otherwise the supplied `runner` is used (default: spawn).
+   *
+   * @returns {Promise<{ status: number }>}
+   */
+  const dispatchGate = async (gate, signal) => {
+    log(
+      `[close-validation] ▶ ${gate.name}${worktreePath ? ` (cwd=${worktreePath})` : ''}`,
+    );
+    if (typeof onGateStart === 'function') onGateStart(gate);
+    const dispatcher = typeof gate.run === 'function' ? gate.run : runner;
+    const result = await dispatcher(gate.cmd, gate.args, {
+      cwd: spawnCwd,
+      gateName: gate.name,
+      log,
+      signal,
+      ...(gate.env ? { env: gate.env } : {}),
+    });
+    return { status: result?.status ?? 1 };
+  };
+
+  const { independent, serial } = partitionGates(gates);
+
+  // ── Phase 1: independent gates in parallel ──────────────────────────
+  // First non-zero exit pins `firstFailure` and aborts every in-flight
+  // sibling via SIGTERM. Other gates' results are still awaited (so we
+  // never leak children) but their non-zero status is intentionally
+  // dropped: only one error surfaces.
+  const ac = new AbortController();
+  let firstIndepFailure = null;
+
+  const indepTasks = independent.map(async (gate) => {
+    let execution;
+    try {
+      execution = applyChangedFileScope({ gate, spawnCwd, log });
+    } catch (err) {
+      if (!firstIndepFailure) {
+        firstIndepFailure = { gate, status: 1, cwd: spawnCwd };
+        log(
+          `[close-validation] ✖ ${gate.name} failed to resolve changed-file scope: ${err?.message ?? err}`,
+        );
+        ac.abort();
+      }
+      return;
+    }
+    if (execution.skip) {
+      skipped.push({ gate, reason: 'no-changed-files' });
+      return;
+    }
+    const configHash = hashCommandConfig({
+      cmd: execution.cmd,
+      args: execution.args,
+      cwd: spawnCwd,
+    });
+    const verdict = evidenceVerdict(gate, configHash);
+    if (verdict.skip) {
+      skipped.push({ gate, reason: verdict.reason });
+      return;
+    }
+    const startedAt = evidenceActive ? evidenceClock() : 0;
+    let result;
+    try {
+      result = await dispatchGate(
+        { ...gate, cmd: execution.cmd, args: execution.args },
+        ac.signal,
+      );
+    } catch (err) {
+      result = { status: 1, error: err };
+    }
+    if (result.status !== 0) {
+      if (!firstIndepFailure) {
+        firstIndepFailure = { gate, status: result.status, cwd: spawnCwd };
+        ac.abort();
+      }
+      return;
+    }
+    log(`[close-validation] ✓ ${gate.name}`);
+    recordIfActive(
+      gate,
+      configHash,
+      evidenceActive ? evidenceClock() - startedAt : 0,
+    );
+  });
+
+  await Promise.all(indepTasks);
+
+  if (firstIndepFailure) {
+    failed.push(firstIndepFailure);
+    log(
+      `[close-validation] ✖ ${firstIndepFailure.gate.name} failed (exit ${firstIndepFailure.status}) in ${spawnCwd}`,
+    );
+    if (firstIndepFailure.gate.hint) {
+      log(`[close-validation]   hint: ${firstIndepFailure.gate.hint}`);
+    }
+    return { ok: false, failed, skipped };
+  }
+
+  // ── Phase 2: serial gates in declared order ─────────────────────────
+  for (const gate of serial) {
+    let execution;
+    try {
+      execution = applyChangedFileScope({ gate, spawnCwd, log });
+    } catch (err) {
+      failed.push({ gate, status: 1, cwd: spawnCwd });
+      log(
+        `[close-validation] ✖ ${gate.name} failed to resolve changed-file scope: ${err?.message ?? err}`,
+      );
+      if (gate.hint) log(`[close-validation]   hint: ${gate.hint}`);
+      break;
+    }
+    if (execution.skip) {
+      skipped.push({ gate, reason: 'no-changed-files' });
+      continue;
+    }
+    const configHash = hashCommandConfig({
+      cmd: execution.cmd,
+      args: execution.args,
+      cwd: spawnCwd,
+    });
+    const verdict = evidenceVerdict(gate, configHash);
+    if (verdict.skip) {
+      skipped.push({ gate, reason: verdict.reason });
+      continue;
+    }
+    const startedAt = evidenceActive ? evidenceClock() : 0;
+    const result = await dispatchGate({
+      ...gate,
+      cmd: execution.cmd,
+      args: execution.args,
+    });
+    if (result.status !== 0) {
+      failed.push({ gate, status: result.status, cwd: spawnCwd });
+      log(
+        `[close-validation] ✖ ${gate.name} failed (exit ${result.status}) in ${spawnCwd}`,
+      );
+      if (gate.hint) log(`[close-validation]   hint: ${gate.hint}`);
+      break;
+    }
+    log(`[close-validation] ✓ ${gate.name}`);
+    recordIfActive(
+      gate,
+      configHash,
+      evidenceActive ? evidenceClock() - startedAt : 0,
+    );
+  }
+
+  return { ok: failed.length === 0, failed, skipped };
+}
+
+/**
+ * Pre-merge MI ceiling projection helpers — `projectMaintainabilityRegressions`
+ * and `formatMaintainabilityProjection` were extracted to
+ * `close-validation/projections/maintainability.js` (Story #1850) so the
+ * parent module stays below the 700-LOC ceiling and the inline guard
+ * cascade collapses into the shared `validateProjectionInputs` predicate.
+ * The re-export below preserves the public contract — every existing call
+ * site continues to import from `./close-validation.js`.
+ */
+export {
+  formatMaintainabilityProjection,
+  projectMaintainabilityRegressions,
+} from './close-validation/projections/maintainability.js';
+
+/**
+ * Throw-away ghSpawnCount emitter (Story #1795 / Epic #1788).
+ *
+ * Writes the current `gh-exec` spawn counter to
+ * `temp/epic-<eid>/stories/story-<sid>/gh-spawn-count.json` so the
+ * `analyze-execution.js` child process can read it and emit a
+ * `ghSpawnCount` field on the `story-perf-summary` payload. The Story-
+ * close orchestrator calls this inside `runPostMergeClose` right before
+ * the perf-summary phase, capturing every `gh` invocation from preflight
+ * through the merge in one counter snapshot.
+ *
+ * @param {object} opts
+ * @param {number|string} opts.epicId
+ * @param {number|string} opts.storyId
+ * @param {object} [opts.config] - Resolved config bag so `tempRoot`
+ *   resolution honours the consumer's configured path.
+ * @param {() => number} [opts.getSpawnCountFn=defaultGetSpawnCount] - Test seam.
+ * @param {typeof defaultWriteFile} [opts.writeFileFn=defaultWriteFile] - Test seam.
+ * @param {{ warn?: (s: string) => void }} [opts.logger] - Best-effort
+ *   failure-path logger; never throws.
+ * @returns {Promise<{ status: 'ok'|'failed', path?: string, ghSpawnCount?: number, reason?: string }>}
+ */
+export async function emitGhSpawnCount({
+  epicId,
+  storyId,
+  config,
+  getSpawnCountFn = defaultGetSpawnCount,
+  writeFileFn = defaultWriteFile,
+  logger,
+} = {}) {
+  const eid = Number(epicId);
+  const sid = Number(storyId);
+  if (!Number.isInteger(eid) || eid < 1 || !Number.isInteger(sid) || sid < 1) {
+    return { status: 'failed', reason: 'invalid-ids' };
+  }
+  let ghSpawnCount;
+  try {
+    ghSpawnCount = getSpawnCountFn();
+  } catch (err) {
+    logger?.warn?.(
+      `[close-validation] gh-spawn-count read failed: ${err?.message ?? err}`,
+    );
+    return { status: 'failed', reason: 'counter-read-failed' };
+  }
+  const targetPath = storyArtifactPath(eid, sid, 'gh-spawn-count.json', config);
+  const payload = {
+    kind: 'gh-spawn-count',
+    epicId: eid,
+    storyId: sid,
+    ghSpawnCount,
+    capturedAt: new Date().toISOString(),
+  };
+  try {
+    await writeFileFn(targetPath, JSON.stringify(payload, null, 2));
+    return { status: 'ok', path: targetPath, ghSpawnCount };
+  } catch (err) {
+    logger?.warn?.(
+      `[close-validation] gh-spawn-count emit failed: ${err?.message ?? err}`,
+    );
+    return { status: 'failed', reason: 'write-failed' };
+  }
+}