mandrel 2.30.0 → 2.32.0

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.

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

@@ -109,6 +109,59 @@ function tolerantMergeWatchMode(value) {
   }
 }
 
+/**
+ * Shortest override reason that can plausibly name a rejected finding. Below
+ * this, the flag is being used to silence the gate rather than to record a
+ * judgement, which is the failure mode the reason requirement exists to stop.
+ */
+const MIN_OVERRIDE_REASON_LENGTH = 12;
+
+/**
+ * Parse `--override-review-block <reason>` — the sanctioned,
+ * logged override of a Story-scope code-review critical blocker.
+ *
+ * The reason is **mandatory and validated**, because the alternative it
+ * replaces is not "no override" but `gh pr merge` run by hand: before this
+ * flag, a review blocker the operator had reviewed and rejected left bypassing
+ * the gate entirely as the only way to land, and that bypass wrote nothing
+ * down anywhere. An override that records why is strictly more auditable than
+ * the hand-merge it displaces; an override that records nothing is not, so a
+ * bare or blank `--override-review-block` fails closed here — before any phase
+ * runs, at no mutation cost — rather than arming a silent one.
+ *
+ * @param {unknown} value
+ * @returns {string|undefined} the trimmed reason, or `undefined` when absent.
+ */
+export function parseOverrideReviewBlock(value) {
+  if (value == null) return undefined;
+  // `parseArgs` with `strict: false` yields `true` for a bare string flag.
+  const reason = typeof value === 'string' ? value.trim() : '';
+  if (reason.length >= MIN_OVERRIDE_REASON_LENGTH) return reason;
+  throw new Error(
+    '--override-review-block requires a reason of at least ' +
+      `${MIN_OVERRIDE_REASON_LENGTH} characters naming the finding you reviewed ` +
+      `and rejected (got ${JSON.stringify(value)}). The reason is posted to the ` +
+      'PR and the Story and recorded as friction telemetry.',
+  );
+}
+
+/**
+ * {@link parseOverrideReviewBlock} degraded to absent instead of throwing, for
+ * the tolerant reporting parse. Same contract as
+ * {@link tolerantMergeWatchMode}: safe only because a tolerant parse runs no
+ * phase.
+ *
+ * @param {unknown} value
+ * @returns {string|undefined}
+ */
+function tolerantOverrideReviewBlock(value) {
+  try {
+    return parseOverrideReviewBlock(value);
+  } catch {
+    return undefined;
+  }
+}
+
 /**
  * Standardized CLI argument parser for sprint scripts.
  * Supports options like --epic, --story, --dry-run, --skip-dashboard.
@@ -147,6 +200,11 @@ export function parseSprintArgs(
       // Absent means "use the config"; see `parseMergeWatchMode` for why an
       // unrecognized value fails closed instead of degrading to absent.
       'merge-watch-mode': { type: 'string' },
+      // Sanctioned override of a code-review critical blocker.
+      // Absent means "the blocker blocks"; see `parseOverrideReviewBlock` for
+      // why a bare or too-short reason fails closed instead of arming a silent
+      // override.
+      'override-review-block': { type: 'string' },
       executor: { type: 'string' },
       cwd: { type: 'string' },
       'recut-of': { type: 'string' },
@@ -183,6 +241,12 @@ export function parseSprintArgs(
     mergeWatchMode: tolerant
       ? tolerantMergeWatchMode(values['merge-watch-mode'])
       : parseMergeWatchMode(values['merge-watch-mode']),
+    // The operator's recorded reason for overriding a review
+    // blocker. `undefined` when the flag is absent, which is what keeps the
+    // blocker blocking by default.
+    overrideReviewBlock: tolerant
+      ? tolerantOverrideReviewBlock(values['override-review-block'])
+      : parseOverrideReviewBlock(values['override-review-block']),
     executor: values.executor ?? null,
     // Resolve worktree cwd from flag or env. Empty string/whitespace → null.
     cwd:

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

@@ -327,8 +327,8 @@ export function buildDefaultGates({
     ...buildTestGateEntry(coverageCaptureActive),
     {
       // 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
+      // doesn'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,

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

@@ -87,9 +87,9 @@ function applyChangedFileScope({ gate, spawnCwd, log }) {
  * `<tempRoot>/standalone/stories/story-<id>/validation-evidence.json`
  * keyspace. v2.0.0 removed the Epic tier and its Epic-keyed keyspace.
  *
- * `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.
+ * `onGateStart` is invoked immediately before each gate's runner spawn, so a
+ * caller can record per-gate wall-clock telemetry. Errors thrown from the
+ * hook propagate.
  *
  * Projection advisories (Story #4776): when `baseBranch` and `storyBranch`
  * are both supplied and every gate passed, the maintainability and CRAP

package/.agents/scripts/lib/config/acceptance-eval.js

@@ -38,7 +38,6 @@
  */
 export const ACCEPTANCE_EVAL_DEFAULTS = Object.freeze({
   maxRounds: 2,
-  clusterCeiling: 4,
 });
 
 /**
@@ -51,22 +50,6 @@ export const ACCEPTANCE_EVAL_DEFAULTS = Object.freeze({
  */
 export const ACCEPTANCE_EVAL_MAX_ROUNDS_CEILING = 5;
 
-/**
- * Hard, undisableable ceiling on `clusterCeiling` — the max ACs one
- * single-delivery acceptance critic scores in a single fresh-context pass
- * (Epic #4475, M4-B, design §S2a). It is the **acceptance-dilution guard**:
- * single delivery collapses the whole Epic into one session, so the only
- * acceptance coverage left is the per-AC-cluster critic fan-out
- * (`ceil(totalACs / clusterCeiling)` independent maker-blind passes). A
- * pathologically large `clusterCeiling` would collapse that fan-out to a
- * single critic scoring every AC at once — exactly the dilution the design
- * forecloses — so a configured value above this ceiling is clamped down to
- * it. Kept small on purpose.
- *
- * @type {number}
- */
-export const ACCEPTANCE_EVAL_CLUSTER_CEILING_MAX = 8;
-
 /**
  * Clamp a candidate round count into the inviolable `[1, ceiling]` range.
  * Non-integer / non-finite inputs fall back to the documented default.
@@ -85,43 +68,19 @@ function clampRounds(value, fallback) {
   return candidate;
 }
 
-/**
- * Clamp a candidate cluster ceiling into the inviolable
- * `[1, ACCEPTANCE_EVAL_CLUSTER_CEILING_MAX]` range. Non-integer / non-finite
- * inputs fall back to the documented default. Mirrors `clampRounds` — the
- * anti-dilution guard cannot be disabled (`clusterCeiling: 0` or a negative
- * clamps up to 1; an over-max value clamps down to the hard cap).
- *
- * @param {unknown} value
- * @param {number} fallback
- * @returns {number}
- */
-function clampClusterCeiling(value, fallback) {
-  const candidate =
-    typeof value === 'number' && Number.isInteger(value) ? value : fallback;
-  if (candidate < 1) return 1;
-  if (candidate > ACCEPTANCE_EVAL_CLUSTER_CEILING_MAX) {
-    return ACCEPTANCE_EVAL_CLUSTER_CEILING_MAX;
-  }
-  return candidate;
-}
-
 /**
  * Read the merged acceptance-eval block. Returns the canonical shape:
  *
  *   {
- *     maxRounds: number,        // clamped into [1, roundsCeiling]
- *     ceiling: number,          // the undisableable hard cap on rounds
- *     clusterCeiling: number,   // clamped into [1, clusterCeilingMax]
- *     clusterCeilingMax: number // the undisableable hard cap on cluster size
+ *     maxRounds: number,  // clamped into [1, ceiling]
+ *     ceiling: number     // the undisableable hard cap on rounds
  *   }
  *
- * `maxRounds` is always a positive integer no greater than `ceiling`;
- * `clusterCeiling` is always a positive integer no greater than
- * `clusterCeilingMax`, regardless of what the resolved config carried.
+ * `maxRounds` is always a positive integer no greater than `ceiling`,
+ * regardless of what the resolved config carried.
  *
  * @param {object | null | undefined} config
- * @returns {{ maxRounds: number, ceiling: number, clusterCeiling: number, clusterCeilingMax: number }}
+ * @returns {{ maxRounds: number, ceiling: number }}
  */
 export function getAcceptanceEval(config) {
   const user = config?.delivery?.acceptanceEval ?? {};
@@ -129,14 +88,8 @@ export function getAcceptanceEval(config) {
     user.maxRounds,
     ACCEPTANCE_EVAL_DEFAULTS.maxRounds,
   );
-  const clusterCeiling = clampClusterCeiling(
-    user.clusterCeiling,
-    ACCEPTANCE_EVAL_DEFAULTS.clusterCeiling,
-  );
   return {
     maxRounds,
     ceiling: ACCEPTANCE_EVAL_MAX_ROUNDS_CEILING,
-    clusterCeiling,
-    clusterCeilingMax: ACCEPTANCE_EVAL_CLUSTER_CEILING_MAX,
   };
 }

package/.agents/scripts/lib/config/commands.js

@@ -1,12 +1,11 @@
 /**
  * `project.commands` accessor (Epic #1720 Story #1739 — top-level reshape).
  *
- * The surviving five command keys are `lintBaseline`, `test`,
- * `typecheck`, `formatCheck`, `formatWrite`.
+ * The surviving four command keys are `test`, `typecheck`,
+ * `formatCheck`, `formatWrite`.
  */
 
 export const COMMANDS_DEFAULTS = Object.freeze({
-  lintBaseline: 'npx eslint . --format json',
   test: 'npm test',
   typecheck: null,
   formatCheck: 'npx biome format .',
@@ -19,12 +18,11 @@ export const COMMANDS_DEFAULTS = Object.freeze({
  * a bare `{ project }` bag.
  *
  * @param {object | null | undefined} config
- * @returns {{ lintBaseline: string, test: string, typecheck: string|null, formatCheck: string, formatWrite: string }}
+ * @returns {{ test: string, typecheck: string|null, formatCheck: string, formatWrite: string }}
  */
 export function getCommands(config) {
   const commands = config?.project?.commands ?? {};
   return {
-    lintBaseline: commands.lintBaseline ?? COMMANDS_DEFAULTS.lintBaseline,
     test: commands.test ?? COMMANDS_DEFAULTS.test,
     typecheck:
       commands.typecheck === undefined