mandrel 2.31.0 → 2.33.0

package/.agents/scripts/lib/bootstrap/manifest.js

@@ -1,14 +1,13 @@
 /**
- * bootstrap/manifest — single mutation-manifest source for the
- * consent-first phased install (Story #3521, Feature #3515, Epic #3438).
+ * bootstrap/manifest — single mutation-manifest source for the install
+ * ledger (Story #3521, Feature #3515, Epic #3438).
  *
  * `buildMutationManifest(ctx)` enumerates every mutation the bootstrap
- * pipeline can perform as a flat, declarative array. Each entry carries the
- * five fields the consent-first install screen needs to preview a change
- * before any write lands:
+ * pipeline can perform as a flat, declarative array. Each entry carries five
+ * fields:
  *
- *   - `phaseGroup` — one of the four independently-approvable groups
- *     (`ide-wiring`, `repo-config`, `github-admin`, `quality-gates`).
+ *   - `phaseGroup` — one of the four groups (`ide-wiring`, `repo-config`,
+ *     `github-admin`, `quality-gates`).
  *   - `target`     — the file path or remote resource the mutation touches.
  *   - `action`     — the verb describing the mutation (`create`, `merge`,
  *     `update`, `run`, `configure`).
@@ -17,16 +16,18 @@
  *     (e.g. delete a created file) vs. a remote-admin mutation that is not
  *     a simple local revert.
  *
- * The manifest is the SINGLE source of truth: `applyProjectBootstrap`'s
- * no-write preview is derived from `buildMutationManifest` so the preview
- * the operator approves and the execution that follows enumerate the exact
- * same set of mutations. There is no second, drift-prone list.
+ * Story #3690 replaced the consent-first phased-approval install screen with
+ * a plain summary+confirm loop, and Story #5007 removed the vestigial
+ * machinery it left behind (the no-write `previewMutationManifest` renderer
+ * and the `approvedGroups` set-threading). What survives is load-bearing:
+ * `recordLedger` filters these entries into the install ledger, and
+ * `mandrel uninstall` walks them — the `phaseGroup` string is the ledger's
+ * grouping key, not an approval gate.
  *
  * The manifest describes *intended* mutations deterministically from the
  * project root; it does not read or mutate any file. Whether a given
  * mutation is a no-op on a particular clone (the file already carries the
- * wiring) is decided at execution time by the idempotent `ensure*` steps —
- * the manifest always lists the full surface so the preview is complete.
+ * wiring) is decided at execution time by the idempotent `ensure*` steps.
  *
  * @module bootstrap/manifest
  */
@@ -34,9 +35,9 @@
 import path from 'node:path';
 
 /**
- * The four independently-approvable phase groups. The consent-first install
- * flow gates each group behind its own opt-in, so every manifest entry MUST
- * carry exactly one of these values.
+ * The four phase groups. Ledger/uninstall metadata only (Story #5007): every
+ * manifest entry MUST carry exactly one of these values so the install ledger
+ * can group and the uninstaller can select what a run actually landed.
  *
  * @type {Readonly<{ IDE_WIRING: 'ide-wiring', REPO_CONFIG: 'repo-config',
  *   GITHUB_ADMIN: 'github-admin', QUALITY_GATES: 'quality-gates' }>}
@@ -271,27 +272,3 @@ export function buildMutationManifest(ctx = {}) {
 
   return entries;
 }
-
-/**
- * Render the manifest as a no-write preview report grouped by phase group.
- * Pure helper — derives entirely from {@link buildMutationManifest}, so the
- * preview and the executing pipeline enumerate one identical source.
- *
- * The returned shape is `{ preview: true, groups: { <phaseGroup>: entry[] },
- * entries: entry[] }`: callers that want the flat list read `entries`, and
- * the consent-first screen reads `groups` to render one approvable section
- * per phase group (only groups with at least one entry appear).
- *
- * @param {object} [ctx] — same context as {@link buildMutationManifest}.
- * @returns {{ preview: true, groups: Record<string, MutationManifestEntry[]>,
- *   entries: MutationManifestEntry[] }}
- */
-export function previewMutationManifest(ctx = {}) {
-  const entries = buildMutationManifest(ctx);
-  const groups = {};
-  for (const entry of entries) {
-    if (!groups[entry.phaseGroup]) groups[entry.phaseGroup] = [];
-    groups[entry.phaseGroup].push(entry);
-  }
-  return { preview: true, groups, entries };
-}

package/.agents/scripts/lib/bootstrap/project-bootstrap.js

@@ -20,7 +20,7 @@ import { isCommandExcluded } from '../command-header.js';
 import { detectPackageManager as detectPm } from '../detect-package-manager.js';
 import { LEDGER_RELATIVE_PATH } from './install-ledger.js';
 import { ensureIssueForms } from './issue-forms-template.js';
-import { PHASE_GROUPS, previewMutationManifest } from './manifest.js';
+import { PHASE_GROUPS } from './manifest.js';
 import { applyQualityBootstrap } from './quality-bootstrap.js';
 
 export const SYNC_COMMAND = 'node .agents/scripts/sync-claude-commands.js';
@@ -436,8 +436,7 @@ export function ensureGitignore(ctx) {
  * project (Story #4227). Derived from the Story-body SSOT so a human-filed
  * ticket round-trips through `story-body.parse()`. Idempotent and additive,
  * mirroring `ensureGitignore`: byte-identical forms are `unchanged`,
- * operator-edited forms are preserved (`custom-skip`). Honours `ctx.preview`
- * (no writes) like the other phases.
+ * operator-edited forms are preserved (`custom-skip`).
  *
  * Returns the per-form action envelope keyed by ticket type.
  *
@@ -446,13 +445,9 @@ export function ensureGitignore(ctx) {
  *
  * @param {object} ctx
  * @param {string} ctx.projectRoot
- * @param {boolean} [ctx.preview]
  */
 function ensureIssueFormsPhase(ctx) {
-  const { forms } = ensureIssueForms({
-    projectRoot: ctx.projectRoot,
-    write: !ctx.preview,
-  });
+  const { forms } = ensureIssueForms({ projectRoot: ctx.projectRoot });
   const outcomes = {};
   for (const form of forms) {
     outcomes[form.type] = { action: form.action, path: form.path };
@@ -691,12 +686,11 @@ const fatalParity = (result) =>
  * bootstrap.
  *
  * Each project-side mutation phase carries a `phaseGroup` matching one of
- * the consent-first {@link PHASE_GROUPS}. When a phased-approval gate is
- * supplied via `ctx.approvedGroups`, a phase whose `phaseGroup` is not in
- * the approved set is skipped (recorded as a `phase-group-declined` no-op)
- * — declining one group never short-circuits the others (Story #3524).
- * Phases with no `phaseGroup` (the Node-version precondition and the
- * dependency install) are always-run infrastructure, never gated.
+ * the {@link PHASE_GROUPS}. Since Story #5007 that string is pure
+ * ledger/uninstall metadata — every phase runs on every install, and the
+ * ledger decides after the fact which groups actually landed. Phases with no
+ * `phaseGroup` (the Node-version precondition and the dependency install)
+ * are always-run infrastructure.
  */
 export const BOOTSTRAP_PHASES = Object.freeze([
   {
@@ -770,24 +764,6 @@ export const BOOTSTRAP_PHASES = Object.freeze([
   },
 ]);
 
-/**
- * Decide whether a phase should run given the approved-phase-group gate.
- * An always-run infrastructure phase (no `phaseGroup`) runs unconditionally.
- * A grouped phase runs only when no gate is supplied (`approvedGroups`
- * absent — the un-gated legacy path) or when its group is in the gate.
- *
- * Exported for unit testing.
- *
- * @param {BootstrapPhase} phase
- * @param {Set<string>|undefined} approvedGroups
- * @returns {boolean}
- */
-export function isPhaseApproved(phase, approvedGroups) {
-  if (!phase.phaseGroup) return true;
-  if (!approvedGroups) return true;
-  return approvedGroups.has(phase.phaseGroup);
-}
-
 /**
  * Throw with the formatted message when the phase is marked fatal and
  * the result indicates an abort. Pure helper so the driver stays a
@@ -809,12 +785,6 @@ export function throwIfFatal(phase, result) {
  * the result on `report[phase.name]`, then route fatal phases through
  * `throwIfFatal`. Returns the accumulated report.
  *
- * When `ctx.approvedGroups` is a `Set`, a grouped phase whose `phaseGroup`
- * is not approved is skipped and recorded as
- * `{ skipped: true, reason: 'phase-group-declined', phaseGroup }` — it never
- * runs, never throws (so a declined `ide-wiring` group also skips its
- * fatal `parity` check), and never short-circuits the remaining phases.
- *
  * Exported for tests so phase ordering and fatal behaviour can be
  * asserted without spawning a full bootstrap.
  *
@@ -825,14 +795,6 @@ export function throwIfFatal(phase, result) {
 export async function runPhases(phases, ctx) {
   const report = {};
   for (const phase of phases) {
-    if (!isPhaseApproved(phase, ctx.approvedGroups)) {
-      report[phase.name] = {
-        skipped: true,
-        reason: 'phase-group-declined',
-        phaseGroup: phase.phaseGroup,
-      };
-      continue;
-    }
     const result = await phase.run(ctx, report);
     report[phase.name] = result;
     throwIfFatal(phase, result);
@@ -844,24 +806,16 @@ export async function runPhases(phases, ctx) {
  * Compose every step in order. Each returned key is the outcome of one
  * step so the CLI can render a structured summary.
  *
- * When `ctx.preview` is truthy, the function performs **no writes and no
- * network I/O**. Instead it derives the operator-facing change list from
- * the single mutation-manifest source ({@link previewMutationManifest}) and
- * returns `{ preview: true, groups, entries }` — the exact same source the
- * consent-first install screen renders. Deriving the preview from
- * `buildMutationManifest` (rather than from a parallel hand-maintained list)
- * guarantees the preview the operator approves and the execution that
- * follows enumerate one identical set of mutations (Story #3521).
+ * Story #5007 removed the no-write `ctx.preview` branch: it had zero
+ * production callers (bootstrap's own `--dry-run` renders a hand-rolled text
+ * plan instead) and it survived only to serve the consent-first install
+ * screen Story #3690 replaced with a plain summary+confirm loop.
  *
  * @param {object} ctx
  * @param {string} ctx.projectRoot
  * @param {string} [ctx.agentRoot]
  * @param {{ owner: string, repo: string, baseBranch: string,
  *           operatorHandle: string|null }} ctx.answers
- * @param {boolean} [ctx.preview]   — no-write preview from the manifest.
- * @param {Set<string>} [ctx.approvedGroups] — when present, only phases
- *   whose `phaseGroup` is in this set execute (the consent-first gate from
- *   Story #3524); always-run infrastructure phases ignore it.
  * @param {boolean} [ctx.withQuality]
  * @param {boolean} [ctx.skipGithub]
  * @param {boolean} [ctx.skipInstall]
@@ -871,6 +825,5 @@ export async function runPhases(phases, ctx) {
  * @returns {Promise<object>}
  */
 export async function applyProjectBootstrap(ctx) {
-  if (ctx.preview) return previewMutationManifest(ctx);
   return runPhases(BOOTSTRAP_PHASES, ctx);
 }

package/.agents/scripts/lib/bootstrap/quality-bootstrap.js

@@ -2,7 +2,7 @@
  * bootstrap/quality-bootstrap — Story #1401 (Epic #1386)
  *
  * Idempotent installer for the stabilized-quality-gates surface area on a
- * project clone. Performs four additive actions, each safe to re-run:
+ * project clone. Performs five additive actions, each safe to re-run:
  *
  *   1. Copies the `code-quality-guardrails.md` helper into the project's
  *      `.agents/workflows/helpers/` (no-op when the helper is already present).
@@ -15,6 +15,11 @@
  *   4. Seeds `delivery.quality.codingGuardrails` and
  *      `delivery.quality.autoRefresh` defaults in `.agentrc.json` when
  *      the keys are absent. Existing values are preserved.
+ *   5. Prunes a committed pre-v2 `baselines/epic/` tree (Story #5007). The
+ *      v2 model is Story-only — nothing writes, reads, or reaps per-Epic
+ *      ratchet snapshots — so an upgrading consumer is left carrying a
+ *      committed directory no gate consults. Absent on every repo that never
+ *      ran a pre-v2 install, which is the overwhelmingly common case.
  *
  * Returns a structured summary so the bootstrap and update workflows can
  * surface exactly which actions ran and which were no-ops.
@@ -25,6 +30,7 @@
  * @module bootstrap/quality-bootstrap
  */
 
+import { spawnSync as defaultSpawnSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
 import { getAgentrcDefaults, lookupPath } from '../config/defaults.js';
@@ -349,7 +355,59 @@ export function ensureQualityConfigDefaults(ctx) {
 }
 
 /**
- * Run all four steps in order. Composable wrapper used by the bootstrap
+ * Repo-root-relative path of the retired committed per-Epic snapshot tree.
+ * Module-private: exporting it would add a production-dead row to the
+ * dead-exports ratchet for a two-word constant.
+ */
+const LEGACY_EPIC_BASELINES_RELPATH = 'baselines/epic';
+
+/**
+ * Step 5 — Prune a committed pre-v2 `baselines/epic/` tree (Story #5007).
+ *
+ * Story #1396 committed per-Epic ratchet snapshots under
+ * `baselines/epic/<id>/`. The v2 Story-only model retired epics along with
+ * every reader of those snapshots, and `check-baselines.js` resolves
+ * baselines by fixed filename rather than by directory glob — so the tree is
+ * inert, and the only remaining value in the retired layout migration was
+ * getting it out of version control.
+ *
+ * `git rm -r --ignore-unmatch` stages the removal when the path is tracked
+ * and is a safe no-op when it is not (fresh clone / untracked leftovers);
+ * the on-disk residue is then removed so a re-run reports `absent`. The
+ * caller commits the resulting working-tree delta.
+ *
+ * @param {object} ctx
+ * @param {string} ctx.projectRoot
+ * @param {typeof defaultSpawnSync} [ctx.spawnImpl] — injectable spawn seam.
+ * @returns {{ action: 'absent'|'pruned', path: string, gitStatus?: number|null }}
+ */
+export function pruneLegacyEpicBaselines(ctx) {
+  const target = path.join(ctx.projectRoot, 'baselines', 'epic');
+  if (!fs.existsSync(target)) return { action: 'absent', path: target };
+  const spawn = ctx.spawnImpl ?? defaultSpawnSync;
+  const rm = spawn(
+    'git',
+    [
+      'rm',
+      '-r',
+      '--quiet',
+      '--ignore-unmatch',
+      '--',
+      LEGACY_EPIC_BASELINES_RELPATH,
+    ],
+    {
+      cwd: ctx.projectRoot,
+      encoding: 'utf-8',
+      stdio: 'pipe',
+      shell: false,
+    },
+  );
+  fs.rmSync(target, { recursive: true, force: true });
+  return { action: 'pruned', path: target, gitStatus: rm.status ?? null };
+}
+
+/**
+ * Run all five steps in order. Composable wrapper used by the bootstrap
  * and update workflows. Each step's outcome is returned under its own key
  * so callers can render a per-action summary.
  *
@@ -357,6 +415,7 @@ export function ensureQualityConfigDefaults(ctx) {
  * @param {string} ctx.projectRoot
  * @param {string} [ctx.frameworkRoot]
  * @param {'framework'|'downstream'} [ctx.variant]
+ * @param {typeof defaultSpawnSync} [ctx.spawnImpl]
  */
 export function applyQualityBootstrap(ctx) {
   return {
@@ -364,5 +423,6 @@ export function applyQualityBootstrap(ctx) {
     hook: ensurePreCommitHook(ctx),
     scripts: ensureQualityNpmScripts(ctx),
     config: ensureQualityConfigDefaults(ctx),
+    legacyBaselines: pruneLegacyEpicBaselines(ctx),
   };
 }

package/.agents/scripts/lib/checks/loop-health.js

@@ -5,7 +5,7 @@
  * The original feedback-loop drift shipped silently because an empty
  * feedback report is indistinguishable from a healthy one. This standing
  * self-check closes that gap: at retro time it samples the on-disk signal
- * substrate the sibling Stories established and surfaces the three ways the
+ * substrate the sibling Stories established and surfaces the two ways the
  * repaired loop can regress without anyone noticing:
  *
  *   1. **Schema-invalid signal lines.** It tails the most recent
@@ -13,11 +13,7 @@
  *      the run temp tree and validates each against the canonical
  *      `signal-event.schema.json` (via `validateSignal`, the same validator
  *      the writer uses — no hand-rolled drift).
- *   2. **Persisted write-time rejects.** It reads the per-run reject tally
- *      (`temp/run-<id>/signal-rejects.json`, written by Story #4413's
- *      signals-writer) so records that were dropped at write time — and thus
- *      never appear in the stream — are still counted.
- *   3. **Un-actioned retro proposals.** It reads the retro mirror
+ *   2. **Un-actioned retro proposals.** It reads the retro mirror
  *      (`temp/run-<id>/retro.md`, Story #4418) and flags any actionable
  *      "Proposed issues" item that carries neither a filed-issue reference
  *      (`Filed: [#N](url)`) nor lives under the explicit "One-off /
@@ -26,7 +22,7 @@
  * Contract:
  *   - Scope `retro`, `autoCorrect: 'refuse-and-print'` — read-only by
  *     construction; the runner refuses `autoFix` under the retro scope.
- *   - A clean substrate (valid lines, zero rejects, every proposal filed or
+ *   - A clean substrate (valid lines, every proposal filed or
  *     discarded) yields **zero findings**, preserving the compact retro
  *     shape. Only when a concern is non-zero does `detect` return a single
  *     combined finding naming every non-clean dimension.
@@ -168,25 +164,6 @@ export function sampleStreamInvalidCount(
   return { sampled: tail.length, invalid };
 }
 
-/**
- * Read the per-run persisted reject count from `signal-rejects.json`.
- * Returns 0 when the tally is absent or unreadable.
- *
- * @param {string} epicDir
- * @param {{ readImpl?: typeof readFileSync }} [opts]
- * @returns {number}
- */
-export function readRejectTally(epicDir, { readImpl = readFileSync } = {}) {
-  try {
-    const parsed = JSON.parse(
-      readImpl(path.join(epicDir, 'signal-rejects.json'), 'utf8'),
-    );
-    return parsed && Number.isFinite(parsed.count) ? parsed.count : 0;
-  } catch {
-    return 0;
-  }
-}
-
 /**
  * Scan a retro mirror body for actionable proposals that were neither filed
  * nor discarded. An actionable proposal is a `- **Title**` item under a
@@ -207,7 +184,7 @@ export function scanRetroMirror(retroText) {
   let inSection = false;
   let current = null;
   const flush = () => {
-    if (current && current.actionable && !current.filed) {
+    if (current?.actionable && !current.filed) {
       unfiled.push(current.title);
     }
     current = null;
@@ -235,8 +212,8 @@ export function scanRetroMirror(retroText) {
 
 /**
  * Core detection: locate the Epic temp tree under `baseDir`, sample its
- * signal streams, read its reject tally, and scan its retro mirror. Returns
- * a single combined finding when any dimension is non-clean, else `null`.
+ * signal streams, and scan its retro mirror. Returns a single combined
+ * finding when either dimension is non-clean, else `null`.
  *
  * @param {string} baseDir
  * @param {{
@@ -277,8 +254,6 @@ export function detectLoopHealth(
     sampled += r.sampled;
   }
 
-  const rejectCount = readRejectTally(epicDir, { readImpl });
-
   let retroText = '';
   try {
     retroText = readImpl(path.join(epicDir, 'retro.md'), 'utf8');
@@ -287,20 +262,17 @@ export function detectLoopHealth(
   }
   const unfiledProposals = scanRetroMirror(retroText);
 
-  const signalConcern = invalidCount > 0 || rejectCount > 0;
+  const signalConcern = invalidCount > 0;
   const proposalConcern = unfiledProposals.length > 0;
   if (!signalConcern && !proposalConcern) return null;
 
   const summaryParts = [];
   const detailLines = [];
   if (signalConcern) {
-    summaryParts.push(
-      `${invalidCount} schema-invalid signal sample(s), ${rejectCount} persisted reject(s)`,
-    );
+    summaryParts.push(`${invalidCount} schema-invalid signal sample(s)`);
     detailLines.push(
       `Sampled ${sampled} line(s) across ${streams.length} signals.ndjson stream(s) (last ${maxLines} per stream):`,
       `  schema-invalid samples: ${invalidCount}`,
-      `  persisted reject tally (signal-rejects.json): ${rejectCount}`,
     );
   }
   if (proposalConcern) {
@@ -320,7 +292,7 @@ export function detectLoopHealth(
     summary: `Loop-health (run-${epicId}): ${summaryParts.join('; ')}.`,
     detail: detailLines.join('\n'),
     fixCommand:
-      'Inspect temp/run-<id>/{signals.ndjson,signal-rejects.json,retro.md}; fix the signal producer or file/discard the surfaced proposals.',
+      'Inspect temp/run-<id>/{signals.ndjson,retro.md}; fix the signal producer or file/discard the surfaced proposals.',
     autoCorrectable: false,
   };
 }

package/.agents/scripts/lib/child-exec.js

@@ -0,0 +1,193 @@
+/**
+ * child-exec.js — the one child-process execution surface (Story #5009).
+ *
+ * Every synchronous and asynchronous child this framework spawns runs through
+ * this module. It owns exactly three policies, and nothing else:
+ *
+ *   1. **The stdout ceiling.** `MAX_BUFFER_BYTES` is defined here and nowhere
+ *      else. Node's child-process runners default `maxBuffer` to 1 MB and
+ *      *kill* the child on overflow — `status: null`, `signal: 'SIGTERM'`,
+ *      `error.code: 'ENOBUFS'` — so the call fails for a reason that has
+ *      nothing to do with the command. That failure class has shipped
+ *      operator-visible breakage more than once (Story #4914's committed
+ *      baseline read at 1,178,910 bytes; Story #4948's `git push` relaying a
+ *      2,166,643-byte `pre-push` envelope, which reddened `phase: push` on
+ *      every Story close while the gates themselves were green). Both were
+ *      fixed one call site at a time. This module is why there is no third.
+ *   2. **Shell-free argv.** `shell: false` on every invocation, so no argument
+ *      is ever shell-interpolated (`rules/security-baseline.md` § Output &
+ *      Rendering). Callers pass argv tokens; they cannot pass a command line.
+ *   3. **Result and error normalisation.** {@link spawnCapture} collapses the
+ *      `spawnSync` return into `{ status, stdout, stderr }` with a non-null
+ *      status and trimmed streams; {@link formatChildFailure} renders the one
+ *      failure-message shape so a thrown child error reads the same wherever
+ *      it came from.
+ *
+ * Every wrapper takes an optional `run` — the injected child-process runner —
+ * so a module keeps its own test seam (`git-base.js`'s `__setSpawnRunner`,
+ * `git-utils.js`'s `__setGitRunners`, the `run` / `spawn` parameters threaded
+ * through the audit-baselines engine) while still delegating buffer, shell and
+ * error policy here. Omit it and the real Node runner is used.
+ *
+ * **Do not re-import `node:child_process` in new modules.**
+ * `tests/enforcement/child-process-imports.test.js` captures the current set
+ * of direct importers and fails on any addition outside that allowlist.
+ *
+ * @module lib/child-exec
+ */
+
+import { execFile, execFileSync, spawnSync } from 'node:child_process';
+import { promisify } from 'node:util';
+
+/** One mebibyte, so the ceilings below read as the units they are quoted in. */
+const MIB = 1024 * 1024;
+
+/**
+ * The stdout ceiling every child in this framework runs under — the single
+ * definition of the constant.
+ *
+ * Deliberately **not** exported. Every wrapper below applies it as its
+ * default, so a call site gets the ceiling by importing the wrapper rather
+ * than by importing (and possibly forgetting) a number. The only bound a
+ * caller ever names explicitly is one that is deliberately *different* —
+ * today that is {@link INTERCEPTOR_MAX_BUFFER_BYTES} and nothing else.
+ *
+ * 64 MiB is not a fresh guess: it is the bound Stories #4914 and #4948 already
+ * settled on independently for the git read and git push paths, and the value
+ * `run-test-profile.js`, `audit-baselines/trend.js` and
+ * `audit-baselines/weights.js` had hand-copied. `maxBuffer` caps a buffer, it
+ * does not reserve one, so a generous ceiling costs nothing on the calls that
+ * print two lines.
+ *
+ * @type {number}
+ */
+const MAX_BUFFER_BYTES = 64 * MIB;
+
+/**
+ * The deliberately *lower* ceiling the friction interceptor spawns arbitrary
+ * operator commands under (`diagnose-friction.js`).
+ *
+ * This one is a reported policy bound, not an overflow guard: when it fires,
+ * the interceptor records `executionMaxBuffer` on the friction row and tells
+ * the operator to quieten the command rather than split it (Story #4915).
+ * Raising it to {@link MAX_BUFFER_BYTES} would change that emitted row, so it
+ * stays where it was — but it is defined here, alongside the ceiling it is
+ * deliberately different from, rather than hand-copied into the interceptor.
+ *
+ * @type {number}
+ */
+export const INTERCEPTOR_MAX_BUFFER_BYTES = 10 * MIB;
+
+/**
+ * Merge caller options over this module's fixed policy.
+ *
+ * `maxBuffer` is applied **last** so a caller's spread cannot silently drop it
+ * back to Node's 1 MB default — the only way to change the ceiling is to pass
+ * `maxBuffer` explicitly, which the two named constants above exist for.
+ *
+ * @param {{ encoding: string }} defaults - Runner-specific defaults.
+ * @param {object} rest      - Caller options (`cwd`, `env`, `stdio`, …).
+ * @param {number} maxBuffer - Resolved stdout ceiling.
+ * @returns {object}
+ */
+function childOptions(defaults, rest, maxBuffer) {
+  return { ...defaults, shell: false, ...rest, maxBuffer };
+}
+
+/**
+ * Run a child synchronously via `execFileSync`, returning whatever the runner
+ * returns (a UTF-8 string under the default encoding). **Throws** on a
+ * non-zero exit, exactly like `execFileSync` — callers that treat failure as a
+ * recoverable state want {@link spawnCapture} instead.
+ *
+ * @param {string}   file   - Executable name (never a shell command line).
+ * @param {string[]} args   - Argv tokens.
+ * @param {object}   [opts] - `cwd` / `env` / `stdio` / `encoding`, plus:
+ * @param {Function} [opts.run]       - Injected runner; defaults to `execFileSync`.
+ * @param {number}   [opts.maxBuffer] - Override the ceiling; defaults to {@link MAX_BUFFER_BYTES}.
+ * @returns {string}
+ */
+export function execFileCapture(file, args, opts = {}) {
+  const { run = execFileSync, maxBuffer = MAX_BUFFER_BYTES, ...rest } = opts;
+  return run(file, args, childOptions({ encoding: 'utf8' }, rest, maxBuffer));
+}
+
+/** Promisified `execFile` — the default runner for {@link execFileCaptureAsync}. */
+const execFileAsync = promisify(execFile);
+
+/**
+ * The asynchronous sibling of {@link execFileCapture}. Resolves to
+ * `{ stdout, stderr }` and rejects on a non-zero exit.
+ *
+ * @param {string}   file   - Executable name.
+ * @param {string[]} args   - Argv tokens.
+ * @param {object}   [opts] - As {@link execFileCapture}; `run` defaults to a
+ *   promisified `execFile`.
+ * @returns {Promise<{ stdout: string, stderr: string }>}
+ */
+export function execFileCaptureAsync(file, args, opts = {}) {
+  const { run = execFileAsync, maxBuffer = MAX_BUFFER_BYTES, ...rest } = opts;
+  return run(file, args, childOptions({ encoding: 'utf8' }, rest, maxBuffer));
+}
+
+/**
+ * Run a child synchronously via `spawnSync`, returning the runner's **raw**
+ * result. Never throws on a non-zero exit.
+ *
+ * Use this when the caller needs the untouched result — untrimmed `stdout`
+ * (file contents, TAP output), a `status` of `null` that must stay `null`
+ * (`git show`'s 128-vs-killed split), or `result.error`. Callers that only
+ * want a normalised `{ status, stdout, stderr }` should use
+ * {@link spawnCapture}.
+ *
+ * @param {string}   file   - Executable name.
+ * @param {string[]} args   - Argv tokens.
+ * @param {object}   [opts] - As {@link execFileCapture}; `run` defaults to `spawnSync`.
+ * @returns {import('node:child_process').SpawnSyncReturns<string>}
+ */
+export function spawnChild(file, args, opts = {}) {
+  const { run = spawnSync, maxBuffer = MAX_BUFFER_BYTES, ...rest } = opts;
+  return run(
+    file,
+    args,
+    childOptions({ encoding: 'utf-8', stdio: 'pipe' }, rest, maxBuffer),
+  );
+}
+
+/**
+ * {@link spawnChild} with the result normalised: `status` is coerced to `1`
+ * when the child did not exit normally (so no caller can read a `null` status
+ * as success — `process.exit(null)` exits 0), and both streams are coerced to
+ * trimmed strings.
+ *
+ * @param {string}   file   - Executable name.
+ * @param {string[]} args   - Argv tokens.
+ * @param {object}   [opts] - As {@link spawnChild}.
+ * @returns {{ status: number, stdout: string, stderr: string }}
+ */
+export function spawnCapture(file, args, opts = {}) {
+  const result = spawnChild(file, args, opts);
+  return {
+    status: result?.status ?? 1,
+    stdout: (result?.stdout ?? '').toString().trim(),
+    stderr: (result?.stderr ?? '').toString().trim(),
+  };
+}
+
+/**
+ * The one failure-message shape for a child that exited non-zero.
+ *
+ * `status` is rendered verbatim — a `null` prints as `status=null`, which is
+ * the diagnostic: it means the child was killed (buffer overflow, timeout,
+ * signal) rather than having reported an exit code of its own.
+ *
+ * @param {object} failure
+ * @param {string} failure.label    - What was being attempted, e.g. `readBaseFromGit: git show main:x`.
+ * @param {number|null} failure.status - Raw child exit status.
+ * @param {unknown} [failure.stderr]   - Raw stderr; coerced and trimmed.
+ * @returns {string}
+ */
+export function formatChildFailure({ label, status, stderr }) {
+  const detail = (stderr ?? '').toString().trim();
+  return `${label} failed (status=${status}): ${detail}`;
+}

package/.agents/scripts/lib/cli/standard-args.js

@@ -4,7 +4,7 @@
  *
  * Replaces the per-CLI hand-rolled flag dispatch with a single
  * declarative entrypoint that the refactored scripts (story-close,
- * epic-deliver, check-baselines, audit-suite/cli) all call. The helper
+ * epic-deliver, check-baselines) all call. The helper
  * covers the flags every dispatcher CLI shares (`--epic`, `--story`,
  * `--changed-since`, `--json`, `--full-scope`, `--dry-run`)
  * and — via the `extras` schema entry — caller-defined extras (e.g.