mandrel 1.58.0 → 1.59.0

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

@@ -0,0 +1,325 @@
+/**
+ * close-validation/runner.js — The `runCloseValidation` orchestrator.
+ *
+ * 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. All gates
+ * inherit stdio so the operator sees the raw output; the returned summary
+ * surfaces actionable hints on failure.
+ */
+
+import {
+  recordPass as defaultRecordPass,
+  shouldSkip as defaultShouldSkip,
+  hashCommandConfig,
+} from '../validation-evidence.js';
+import {
+  isFormatterEligible,
+  listChangedFilesForFormatGate,
+} from './commands.js';
+import { DEFAULT_GATES, partitionGates } from './gates.js';
+import { defaultGateRunner } from './process.js';
+import { defaultGetHeadSha } from './projections/head-sha.js';
+
+/** @typedef {import('./gates.js').Gate} Gate */
+
+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,
+  };
+}
+
+/**
+ * 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 };
+}

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

@@ -0,0 +1,70 @@
+/**
+ * close-validation/telemetry.js — gh-spawn telemetry emitter.
+ */
+
+import { writeFile as defaultWriteFile } from 'node:fs/promises';
+import { storyArtifactPath } from '../config/temp-paths.js';
+import { getSpawnCount as defaultGetSpawnCount } from '../gh-exec.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' };
+  }
+}

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

@@ -121,7 +121,7 @@ export const MAINTAINABILITY_GATE_DEFAULTS = Object.freeze({
  * --write` autofix spawn. The SIGKILL → exit 124 mapping mirrors
  * `gates.coverage.timeoutMs` (Story #2142).
  */
-export const FORMAT_AUTOFIX_DEFAULTS = Object.freeze({
+const FORMAT_AUTOFIX_DEFAULTS = Object.freeze({
   timeoutMs: 60_000,
 });
 
@@ -259,7 +259,7 @@ export function resolveMaintainabilityCrap(
  * `targetDirs` + a scalar `tolerance` (when set) + scoping inherited
  * from `gateScoping`.
  */
-export function resolveMaintainabilityQuality(userBlock, gateScoping) {
+function resolveMaintainabilityQuality(userBlock, gateScoping) {
   const defaults = MAINTAINABILITY_GATE_DEFAULTS;
   const scoping = {
     defaultScope: gateScoping?.scope ?? DEFAULT_GATE_SCOPING.scope,
@@ -321,7 +321,7 @@ function resolvePositiveIntegerMs(value, defaultMs) {
  */
 const FORMAT_AUTOFIX_KEYS = new Set(['timeoutMs']);
 
-export function resolveFormatAutofix(userBlock) {
+function resolveFormatAutofix(userBlock) {
   const defaults = FORMAT_AUTOFIX_DEFAULTS;
   if (userBlock == null || typeof userBlock !== 'object') {
     return { timeoutMs: defaults.timeoutMs };
@@ -336,7 +336,7 @@ export function resolveFormatAutofix(userBlock) {
 }
 
 /** Resolve the coverage gate. Owns `coveragePath` and `timeoutMs`. */
-export function resolveCoverageGate(userBlock) {
+function resolveCoverageGate(userBlock) {
   const defaults = COVERAGE_GATE_DEFAULTS;
   if (userBlock == null || typeof userBlock !== 'object') {
     return {
@@ -402,7 +402,7 @@ export function resolveCodingGuardrails(userBlock) {
   };
 }
 
-export const AUTO_REFRESH_DEFAULTS = Object.freeze({
+const AUTO_REFRESH_DEFAULTS = Object.freeze({
   enabled: true,
   miDropCap: 1.5,
   crapJumpCap: 5,
@@ -411,7 +411,7 @@ export const AUTO_REFRESH_DEFAULTS = Object.freeze({
 
 const AUTO_REFRESH_KEYS = new Set(Object.keys(AUTO_REFRESH_DEFAULTS));
 
-export function resolveAutoRefresh(userBlock) {
+function resolveAutoRefresh(userBlock) {
   const defaults = AUTO_REFRESH_DEFAULTS;
   if (userBlock == null || typeof userBlock !== 'object') {
     return {

package/.agents/scripts/lib/config-resolver.js

@@ -24,7 +24,6 @@
 
 import fs from 'node:fs';
 import path from 'node:path';
-import { fileURLToPath } from 'node:url';
 import { getCiDelivery } from './config/ci.js';
 import { getCommands } from './config/commands.js';
 import { getGitHub } from './config/github.js';
@@ -34,6 +33,7 @@ import { validateOrchestrationConfig } from './config/validate-orchestration.js'
 import { getWorktreeIsolation } from './config/worktree-isolation.js';
 import { getAgentrcValidator } from './config-schema.js';
 import { loadEnv } from './env-loader.js';
+import { PROJECT_ROOT } from './project-root.js';
 
 export { getAcceptanceEval } from './config/acceptance-eval.js';
 export { BASELINES_DEFAULTS, getBaselines } from './config/baselines.js';
@@ -64,10 +64,7 @@ export {
 export { resolveListValue } from './config/shared.js';
 export { validateOrchestrationConfig } from './config/validate-orchestration.js';
 export { WORKTREE_ISOLATION_DEFAULTS } from './config/worktree-isolation.js';
-
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-// scripts/lib/ → scripts/ → .agents/ → project root
-export const PROJECT_ROOT = path.resolve(__dirname, '../../..');
+export { PROJECT_ROOT } from './project-root.js';
 
 // Cache keyed by absolute root path so callers passing different cwds
 // (e.g. per-worktree) each get their own resolved config.

package/.agents/scripts/lib/coverage-capture.js

@@ -11,6 +11,7 @@
  * `isCoverageFresh` and decide whether to delegate to `runCapture`.
  */
 import { spawnSync } from 'node:child_process';
+import crypto from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
 
@@ -65,10 +66,130 @@ export function newestSourceMtime(cwd, targetDirs, io = {}) {
 }
 
 /**
- * Decide whether the existing coverage artifact is "fresh" — present and at
- * least as new as the newest source file under `targetDirs`. Missing files,
- * missing target dirs, or any IO error resolve to `false` so the caller
- * captures rather than trusting stale data.
+ * Resolve the capture-stamp path that sits next to the coverage artifact.
+ * The stamp persists the content digest of the CRAP-target sources at the
+ * moment coverage was last captured, so freshness can be decided by content
+ * rather than mtime (mtime churns on branch switches / checkouts even when
+ * content is unchanged).
+ *
+ * @param {string} cwd Absolute repo root.
+ * @param {string} coveragePath Repo-relative coverage artifact path.
+ * @returns {string} Absolute stamp path (`<coverage-dir>/.capture-stamp.json`).
+ */
+export function captureStampPath(cwd, coveragePath) {
+  return path.join(
+    path.dirname(path.resolve(cwd, coveragePath)),
+    '.capture-stamp.json',
+  );
+}
+
+const SOURCE_EXT_RE = /\.(?:js|mjs)$/;
+
+/**
+ * Compute a stable content digest of the `.js`/`.mjs` sources under
+ * `targetDirs`: the `git ls-files -s` listing (mode + blob SHA + path) of
+ * tracked content, plus the on-disk bytes of any dirty working-tree files.
+ * Checkout/branch churn leaves blob SHAs untouched, so the digest only moves
+ * when content actually changes.
+ *
+ * Returns `null` when the digest cannot be computed (git unavailable, not a
+ * repo, empty target list) so callers can fall back to the mtime heuristic.
+ *
+ * @param {string} cwd Absolute repo root.
+ * @param {string[]} targetDirs Repo-relative directories to digest.
+ * @param {{ spawnSync?: typeof spawnSync, readFileSync?: typeof fs.readFileSync }} [io]
+ * @returns {string | null} Hex SHA-256 digest, or null when unavailable.
+ */
+export function computeContentDigest(cwd, targetDirs, io = {}) {
+  const spawn = io.spawnSync ?? spawnSync;
+  const readFileSync = io.readFileSync ?? fs.readFileSync;
+  const dirs = (targetDirs ?? []).filter(
+    (d) => typeof d === 'string' && d.length > 0,
+  );
+  if (dirs.length === 0) return null;
+
+  const git = (...args) => {
+    const res = spawn('git', args, { cwd, encoding: 'utf8' });
+    if (res?.error || res?.status !== 0) {
+      throw res?.error ?? new Error(res?.stderr || `git ${args[0]} failed`);
+    }
+    return res.stdout ?? '';
+  };
+
+  try {
+    const hash = crypto.createHash('sha256');
+    const tracked = git('ls-files', '-s', '--', ...dirs)
+      .split('\n')
+      .filter((line) => SOURCE_EXT_RE.test(line.trimEnd()));
+    hash.update(tracked.join('\n'));
+
+    // Dirty working-tree files are not represented by their index blob SHA,
+    // so fold in their on-disk bytes (or absence) explicitly.
+    const dirty = git('status', '--porcelain', '--', ...dirs)
+      .split('\n')
+      .filter((line) => line.length > 3);
+    for (const line of dirty) {
+      let file = line.slice(3).trim();
+      if (file.includes(' -> ')) file = file.split(' -> ').pop();
+      file = file.replace(/^"|"$/g, '');
+      if (!SOURCE_EXT_RE.test(file)) continue;
+      hash.update(`\0${file}\0`);
+      try {
+        hash.update(readFileSync(path.resolve(cwd, file)));
+      } catch {
+        hash.update('<absent>');
+      }
+    }
+    return hash.digest('hex');
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Persist the capture stamp next to the coverage artifact. Best-effort: a
+ * write failure returns `false` rather than throwing — the worst case is a
+ * fall back to the mtime heuristic on the next freshness check.
+ *
+ * @param {{
+ *   cwd: string,
+ *   coveragePath: string,
+ *   digest: string,
+ *   writeFileSync?: typeof fs.writeFileSync,
+ * }} opts
+ * @returns {boolean} True when the stamp was written.
+ */
+export function writeCaptureStamp({
+  cwd,
+  coveragePath,
+  digest,
+  writeFileSync = fs.writeFileSync,
+}) {
+  if (typeof digest !== 'string' || digest.length === 0) return false;
+  try {
+    writeFileSync(
+      captureStampPath(cwd, coveragePath),
+      `${JSON.stringify({ digest, capturedAt: new Date().toISOString() }, null, 2)}\n`,
+    );
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Decide whether the existing coverage artifact is "fresh".
+ *
+ * Primary test (content-aware, Story #3982): when a capture stamp exists
+ * next to the artifact, compare its persisted digest against the current
+ * content digest of `targetDirs`. Equal digests → fresh; different → stale.
+ * Branch switches and checkouts that bump mtimes without changing content
+ * no longer invalidate coverage.
+ *
+ * Fallback (stamp absent / unreadable / digest unavailable): the original
+ * mtime heuristic — artifact at least as new as the newest source file
+ * under `targetDirs`. Missing files, missing target dirs, or any IO error
+ * resolve to `false` so the caller captures rather than trusting stale data.
  *
  * @param {{
  *   coveragePath: string,
@@ -77,6 +198,8 @@ export function newestSourceMtime(cwd, targetDirs, io = {}) {
  *   statSync?: typeof fs.statSync,
  *   readdirSync?: typeof fs.readdirSync,
  *   existsSync?: typeof fs.existsSync,
+ *   readFileSync?: typeof fs.readFileSync,
+ *   computeDigest?: typeof computeContentDigest,
  * }} opts
  * @returns {{ fresh: boolean, reason: 'missing' | 'stale' | 'fresh' | 'no-sources' }}
  */
@@ -87,10 +210,30 @@ export function isCoverageFresh({
   statSync = fs.statSync,
   readdirSync = fs.readdirSync,
   existsSync = fs.existsSync,
+  readFileSync = fs.readFileSync,
+  computeDigest = computeContentDigest,
 }) {
   const absCoverage = path.resolve(cwd, coveragePath);
   if (!existsSync(absCoverage)) return { fresh: false, reason: 'missing' };
 
+  const stampPath = captureStampPath(cwd, coveragePath);
+  if (existsSync(stampPath)) {
+    let stamp = null;
+    try {
+      stamp = JSON.parse(readFileSync(stampPath, 'utf8'));
+    } catch {
+      // Corrupt/unreadable stamp → fall through to the mtime heuristic.
+    }
+    if (typeof stamp?.digest === 'string' && stamp.digest.length > 0) {
+      const current = computeDigest(cwd, targetDirs);
+      if (typeof current === 'string' && current.length > 0) {
+        return current === stamp.digest
+          ? { fresh: true, reason: 'fresh' }
+          : { fresh: false, reason: 'stale' };
+      }
+    }
+  }
+
   let coverageMtime;
   try {
     coverageMtime = statSync(absCoverage).mtimeMs;

package/.agents/scripts/lib/cpu-pool.js

@@ -54,6 +54,20 @@ import { Worker } from 'node:worker_threads';
 /** Default factory: spawn a real `worker_threads.Worker`. */
 const defaultWorkerFactory = (script, options) => new Worker(script, options);
 
+/**
+ * Pool-vs-serial cutover for `runOnPool` callers.
+ *
+ * Below this batch size the pool's worker spawn overhead dominates, so
+ * callers fall back to in-process serial scoring. Tuned against the test
+ * suite's tmpdir fixtures (n=2 stays serial; the full repo n≈200–470
+ * takes the pool path). Single-sourced here so the maintainability
+ * baseline scan (`maintainability-utils.js`), the CRAP scanner
+ * (`crap-utils.js`), and the native review provider
+ * (`review-providers/native.js`) cannot silently desynchronize on a
+ * retune.
+ */
+export const POOL_SERIAL_THRESHOLD = 8;
+
 /**
  * @template TItem, TResult
  * @param {string|URL} workerScript - File URL or path to the worker entry.