mandrel 2.16.0 → 2.18.0

package/.agents/scripts/lib/checks/story-init-not-backgrounded.js

@@ -26,7 +26,7 @@
  * fan-out target, or `&` shell backgrounding) within a small line window.
  */
 
-import { readdirSync, readFileSync } from 'node:fs';
+import nodeFs from 'node:fs';
 import path from 'node:path';
 
 const SCAN_ROOT_DEFAULT = '.agents';
@@ -54,14 +54,20 @@ const BACKGROUND_TOKENS = [
  * and `.md` sources. Skips `node_modules`, `.worktrees`, and directories
  * starting with `.git`.
  *
+ * The optional final `fsImpl` parameter defaults to the real `node:fs`
+ * (`.agents/rules/test-seams.md` rule 1) and is forwarded to the recursive
+ * call rather than re-acquired there (rule 4), so a test drives the whole walk
+ * through a plain stub object instead of module mocking (rule 5).
+ *
  * @param {string} dir
+ * @param {typeof nodeFs} [fsImpl]
  * @returns {string[]}
  */
-function walkSources(dir) {
+export function walkSources(dir, fsImpl = nodeFs) {
   const out = [];
   let entries;
   try {
-    entries = readdirSync(dir, { withFileTypes: true });
+    entries = fsImpl.readdirSync(dir, { withFileTypes: true });
   } catch {
     return out;
   }
@@ -75,7 +81,7 @@ function walkSources(dir) {
       ) {
         continue;
       }
-      out.push(...walkSources(full));
+      out.push(...walkSources(full, fsImpl));
       continue;
     }
     if (!entry.isFile()) continue;
@@ -94,11 +100,14 @@ function walkSources(dir) {
  * any dedicated check module (this file): the source-of-truth
  * implementation legitimately mentions itself.
  *
+ * Pure: it is handed the already-read source, so it needs no filesystem seam
+ * of its own.
+ *
  * @param {string} file
  * @param {string} src
  * @returns {Array<{ line: number, kind: string }>}
  */
-function scanFile(file, src) {
+export function scanFile(file, src) {
   const offences = [];
   // Don't flag the actual story-init script, self-references, or the
   // parallel-tooling helper — the helper documents both Rule 2
@@ -149,15 +158,21 @@ export default {
   scope: ['story-close', 'retro'],
   autoCorrect: 'refuse-and-print',
 
-  detect(state) {
+  /**
+   * @param {{ cwd?: string, scanRoot?: string, scope?: string }} [state]
+   * @param {typeof nodeFs} [fsImpl] Optional final filesystem seam; defaults
+   *   to the real `node:fs` (`.agents/rules/test-seams.md` rule 1) and is
+   *   forwarded to {@link walkSources} rather than re-acquired (rule 4).
+   */
+  detect(state, fsImpl = nodeFs) {
     const cwd = state?.cwd ?? process.cwd();
     const root = state?.scanRoot ?? path.join(cwd, SCAN_ROOT_DEFAULT);
-    const files = walkSources(root);
+    const files = walkSources(root, fsImpl);
     const offences = [];
     for (const file of files) {
       let src;
       try {
-        src = readFileSync(file, 'utf8');
+        src = fsImpl.readFileSync(file, 'utf8');
       } catch {
         continue;
       }

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

@@ -18,6 +18,7 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { respondToHelp } from './cli-usage.js';
 import { formatCliError } from './error-redactor.js';
+import { flushStdio } from './stdio-flush.js';
 
 /**
  * Is the current module being executed directly as a CLI (as opposed to
@@ -32,11 +33,48 @@ export function isDirectInvocation(importMetaUrl) {
   return fileURLToPath(importMetaUrl) === path.resolve(entry);
 }
 
+/**
+ * Settle one CLI run: await `main`, translate its outcome into an exit code,
+ * then flush stdio.
+ *
+ * **The exit is never eager** (Story #4783). This helper assigns
+ * `process.exitCode` and returns, letting Node terminate once the event loop
+ * is empty — which is *after* the pending stdout writes drain. The previous
+ * `process.exit()` call terminated first, discarding anything still queued
+ * behind a full pipe buffer, so any CLI emitting more than 64 KiB into a pipe
+ * truncated silently while still reporting success. The resulting exit code is
+ * identical for every caller: `code ?? 0` on the `propagateExitCode` path,
+ * `options.exitCode` (default 1) on the fatal-error path, and an untouched 0
+ * everywhere else.
+ *
+ * @param {() => Promise<unknown>} main
+ * @param {{ source: string, exitCode: number, onError?: (err: Error) => void,
+ *   propagateExitCode: boolean, errorPrefix?: string }} settings
+ * @returns {Promise<void>}
+ */
+async function settleCli(main, settings) {
+  const { source, exitCode, onError, propagateExitCode, errorPrefix } =
+    settings;
+  try {
+    const code = await main();
+    if (propagateExitCode) process.exitCode = code ?? 0;
+  } catch (err) {
+    if (typeof onError === 'function') {
+      onError(err);
+    } else {
+      const prefix = errorPrefix ?? `[${source}] Fatal error`;
+      console.error(`${prefix}: ${formatCliError(err)}`);
+      process.exitCode = exitCode;
+    }
+  }
+  await flushStdio();
+}
+
 /**
  * Run `main` as the CLI entry point for the caller's module. No-op when the
  * module is imported rather than invoked directly. Promise rejection from
  * `main` is funnelled through either the caller-supplied `onError` callback
- * or the default handler (prefixed stderr line + `process.exit(exitCode)`).
+ * or the default handler (prefixed stderr line + `process.exitCode`).
  *
  * A `usage` option makes the script self-describing: when the argv carries
  * `--help` / `-h`, the rendered usage block goes to stdout and `main` is
@@ -51,6 +89,9 @@ export function isDirectInvocation(importMetaUrl) {
  * @param {string} [options.source='CLI']           Prefix used in the default error message.
  * @param {number} [options.exitCode=1]             Exit code used by the default error handler.
  * @param {(err: Error) => void} [options.onError]  Full override of the error handler.
+ * @param {boolean} [options.propagateExitCode=false] Adopt `main`'s resolved
+ *   value as the process exit code.
+ * @param {string} [options.errorPrefix]            Overrides the `[source] Fatal error` prefix.
  * @param {object|string} [options.usage]           Usage spec (or pre-rendered
  *   text) printed for `--help`; see `lib/cli-usage.js`.
  */
@@ -65,17 +106,11 @@ export function runAsCli(importMetaUrl, main, options = {}) {
     usage,
   } = options;
   if (usage && respondToHelp(process.argv.slice(2), usage)) return;
-  const promise = main();
-  if (propagateExitCode) {
-    promise.then((code) => process.exit(code ?? 0));
-  }
-  promise.catch((err) => {
-    if (typeof onError === 'function') {
-      onError(err);
-      return;
-    }
-    const prefix = errorPrefix ?? `[${source}] Fatal error`;
-    console.error(`${prefix}: ${formatCliError(err)}`);
-    process.exit(exitCode);
+  void settleCli(main, {
+    source,
+    exitCode,
+    onError,
+    propagateExitCode,
+    errorPrefix,
   });
 }

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

@@ -0,0 +1,184 @@
+// .agents/scripts/lib/close-validation/projections/advisories.js
+/**
+ * advisories.js — the projection layer's single call site (Story #4776).
+ *
+ * `projections/maintainability.js` shipped fully written, fully unit-tested
+ * and imported by nothing: the v2 Epic-tier collapse removed its caller and
+ * left the module behind. The practical consequence was that the advisory
+ * telling an operator to run `npm run maintainability:update` and commit a
+ * `baseline-refresh:` subject had never fired in v2 — consumers refreshed
+ * their baselines by hand or not at all.
+ *
+ * This module is that caller, for both projections. It is deliberately the
+ * only door: `close-validation/runner.js` invokes `runProjectionAdvisories`
+ * once, after the gate chain has passed, and every per-kind concern (gate
+ * enablement, baseline path resolution, scorer construction, formatting)
+ * lives here rather than being re-derived at the runner boundary.
+ *
+ * **Advisory, always.** Nothing in here can fail a close. `check-baselines`
+ * already fails closed on a real regression; the projections add the refresh
+ * half of the loop, not a second gate. Every projection is wrapped so a
+ * throw becomes a logged skip.
+ */
+
+import path from 'node:path';
+import { getQuality } from '../../config/quality.js';
+import {
+  createCrapScorer,
+  formatCrapProjection,
+  projectCrapBreaches,
+} from './crap.js';
+import {
+  formatMaintainabilityProjection,
+  projectMaintainabilityRegressions,
+} from './maintainability.js';
+
+/** Default on-disk baseline locations, mirroring the per-gate defaults. */
+const DEFAULT_BASELINE_PATHS = Object.freeze({
+  maintainability: 'baselines/maintainability.json',
+  crap: 'baselines/crap.json',
+});
+
+/**
+ * Resolve a gate's baseline file to an absolute path.
+ *
+ * @param {string} kind
+ * @param {object} gate resolved `delivery.quality.gates.<kind>` block
+ * @param {string} cwd
+ * @returns {string}
+ */
+function resolveBaselinePath(kind, gate, cwd) {
+  const rel =
+    typeof gate?.baselinePath === 'string' && gate.baselinePath.length > 0
+      ? gate.baselinePath
+      : DEFAULT_BASELINE_PATHS[kind];
+  return path.isAbsolute(rel) ? rel : path.resolve(cwd, rel);
+}
+
+/**
+ * A gate is projected unless it is explicitly disabled. An absent gate
+ * block means "framework defaults", which enable it — the same reading
+ * `buildDefaultGates` applies.
+ *
+ * @param {object|undefined} gate
+ * @returns {boolean}
+ */
+function isEnabled(gate) {
+  return gate?.enabled !== false;
+}
+
+/**
+ * Run one projection with its formatter, swallowing every failure into a
+ * logged skip. Returns the projection result (or `null` when it threw) so
+ * callers and tests can inspect what happened without parsing log lines.
+ *
+ * @param {{ kind: string, log: (m: string) => void, run: () => Promise<object>|object, format: (r: object) => string|null }} opts
+ * @returns {Promise<object|null>}
+ */
+async function runOne({ kind, log, run, format }) {
+  let result;
+  try {
+    result = await run();
+  } catch (err) {
+    log(
+      `[close-validation]   ⚠ ${kind} projection skipped (errored): ${err?.message ?? err}`,
+    );
+    return null;
+  }
+  if (result?.skipped) {
+    log(
+      `[close-validation] ⏭ ${kind} projection skipped (${result.skipped}${
+        result.detail ? `: ${result.detail}` : ''
+      })`,
+    );
+    return result;
+  }
+  const advisory = format(result);
+  if (advisory) log(advisory);
+  return result;
+}
+
+/**
+ * Run the maintainability and CRAP pre-merge projections and log their
+ * advisories. Never throws; never affects the close verdict.
+ *
+ * @param {{
+ *   cwd: string,
+ *   baseBranch: string,
+ *   storyBranch: string,
+ *   config?: object,
+ *   quality?: object,
+ *   log?: (m: string) => void,
+ *   projectMaintainability?: typeof projectMaintainabilityRegressions,
+ *   formatMaintainability?: typeof formatMaintainabilityProjection,
+ *   projectCrap?: typeof projectCrapBreaches,
+ *   formatCrap?: typeof formatCrapProjection,
+ * }} opts
+ * @returns {Promise<{ maintainability: object|null, crap: object|null }>}
+ */
+export async function runProjectionAdvisories({
+  cwd,
+  baseBranch,
+  storyBranch,
+  config,
+  quality,
+  log = () => {},
+  projectMaintainability = projectMaintainabilityRegressions,
+  formatMaintainability = formatMaintainabilityProjection,
+  projectCrap = projectCrapBreaches,
+  formatCrap = formatCrapProjection,
+} = {}) {
+  const out = { maintainability: null, crap: null };
+  let gates;
+  try {
+    gates = quality ?? getQuality(config) ?? {};
+  } catch {
+    gates = {};
+  }
+
+  const miGate = gates.maintainability;
+  if (isEnabled(miGate)) {
+    out.maintainability = await runOne({
+      kind: 'maintainability',
+      log,
+      format: formatMaintainability,
+      run: () =>
+        projectMaintainability({
+          cwd,
+          baseBranch,
+          storyBranch,
+          baselinePath: resolveBaselinePath('maintainability', miGate, cwd),
+        }),
+    });
+  } else {
+    log('[close-validation] ⏭ maintainability projection skipped (disabled)');
+  }
+
+  const crapGate = gates.crap;
+  if (isEnabled(crapGate)) {
+    out.crap = await runOne({
+      kind: 'crap',
+      log,
+      format: formatCrap,
+      run: () =>
+        projectCrap({
+          cwd,
+          baseBranch,
+          storyBranch,
+          baselinePath: resolveBaselinePath('crap', crapGate, cwd),
+          newMethodCeiling: crapGate?.newMethodCeiling,
+          scoreFiles: createCrapScorer({
+            cwd,
+            targetDirs: crapGate?.targetDirs,
+            ignoreGlobs: crapGate?.ignoreGlobs,
+            requireCoverage: crapGate?.requireCoverage,
+            coveragePath: crapGate?.coveragePath,
+          }),
+        }),
+    });
+  } else {
+    log('[close-validation] ⏭ crap projection skipped (disabled)');
+  }
+
+  return out;
+}

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

@@ -0,0 +1,303 @@
+// .agents/scripts/lib/close-validation/projections/crap.js
+/**
+ * crap.js — pre-merge CRAP ceiling projection helper (Story #4776).
+ *
+ * The CRAP analogue of `projections/maintainability.js`. Both answer the
+ * same operator question before the merge runs: *given what this branch
+ * changed, which committed baseline rows would the post-merge tree breach,
+ * and what is the exact remedy?*
+ *
+ * Advisory only. `check-baselines` already fails close-validation closed on
+ * a real regression; duplicating that here would double-gate the same
+ * defect. What this projection adds is the **refresh** half of the loop —
+ * naming the breaching methods and the `npm run crap:update` +
+ * `baseline-refresh:` remedy while the operator still has the branch in
+ * hand, so a corrected baseline does not rot back into staleness.
+ *
+ * The helper never throws and never mutates anything. Every failure path
+ * resolves to `{ ok: true, breaches: [], skipped: '<reason>' }` so the
+ * caller can treat the advisory as best-effort.
+ *
+ * Post-merge approximation: CRAP needs a coverage join, so — unlike the MI
+ * projection, which scores a `git show` blob — the scorer reads the working
+ * tree. Close-validation runs inside the Story worktree at the branch tip,
+ * which is exactly the content a squash-merge lands, so the approximation is
+ * exact whenever the merge applies cleanly.
+ */
+
+import path from 'node:path';
+import {
+  compareCrap,
+  filterRowsByFileScope,
+} from '../../baselines/kinds/crap.js';
+import { loadFile as loadBaselineFile } from '../../baselines/reader.js';
+import { diffNameOnly } from '../../changed-files.js';
+import { loadCoverage } from '../../coverage-utils.js';
+import { scanAndScore } from '../../crap-utils.js';
+import { cachedGitFetchSync } from '../../git/cached-fetch.js';
+import { gitSpawn as defaultGitSpawn } from '../../git-utils.js';
+import { MISSING_ARG_REASONS, validateProjectionInputs } from './inputs.js';
+
+/**
+ * Default absolute tolerance on a projected CRAP score, shared with
+ * `check-crap`'s regression arm: floating-point noise must not register as
+ * a breach.
+ */
+export const DEFAULT_CRAP_TOLERANCE = 0.001;
+
+/** Framework default for the new-method ceiling (`gates.crap.newMethodCeiling`). */
+export const DEFAULT_NEW_METHOD_CEILING = 30;
+
+/** Extensions the CRAP scanner can score. */
+const SCORABLE = /\.(?:js|mjs|cjs|ts|tsx)$/;
+
+/**
+ * Map the shared predicate's fine-grained `missing-*` reason onto the
+ * `missing-args` skipped-reason the sibling MI projection reports, so both
+ * projections speak one vocabulary at the advisory boundary.
+ *
+ * @param {string} reason
+ * @returns {string}
+ */
+function normaliseSkipReason(reason) {
+  return MISSING_ARG_REASONS.has(reason) ? 'missing-args' : reason;
+}
+
+/**
+ * Read the committed CRAP baseline and re-key its rows onto the `file`
+ * field `compareCrap` matches on (the on-disk v2 envelope keys on `path`).
+ * Returns `[]` when the baseline is absent or unreadable — the caller maps
+ * that to the `no-baseline` skip.
+ *
+ * Deliberately module-local: `projectCrapBreaches`'s `loadBaseline` default
+ * is the single production door to it, and tests inject their own loader.
+ * Exporting it would add a second entry point nothing in production reaches
+ * — which is precisely the orphaning this Story exists to stop.
+ *
+ * @param {string} baselinePath absolute path to `baselines/crap.json`
+ * @returns {Array<{file: string, method: string, startLine: number, crap: number}>}
+ */
+function loadCrapBaselineRows(baselinePath) {
+  let envelope;
+  try {
+    envelope = loadBaselineFile(baselinePath, { kind: 'crap' });
+  } catch {
+    return [];
+  }
+  const rows = Array.isArray(envelope?.rows) ? envelope.rows : [];
+  return rows.map((row) => ({
+    file: row.path,
+    method: row.method,
+    startLine: row.startLine,
+    crap: row.crap,
+  }));
+}
+
+/**
+ * Build the default working-tree CRAP scorer. Returns an async callable
+ * `(files) => rows | null`; `null` signals "coverage artifact missing under
+ * `requireCoverage`", which the projection reports as the `no-coverage`
+ * skip rather than as a clean run.
+ *
+ * @param {{
+ *   cwd: string,
+ *   targetDirs?: string[],
+ *   ignoreGlobs?: string[],
+ *   requireCoverage?: boolean,
+ *   coveragePath?: string,
+ * }} opts
+ * @returns {(files: string[]) => Promise<Array<object>|null>}
+ */
+export function createCrapScorer({
+  cwd,
+  targetDirs = [],
+  ignoreGlobs = [],
+  requireCoverage = true,
+  coveragePath = 'coverage/coverage-final.json',
+} = {}) {
+  return async (files) => {
+    const abs = path.isAbsolute(coveragePath)
+      ? coveragePath
+      : path.resolve(cwd, coveragePath);
+    const coverage = loadCoverage(abs);
+    if (!coverage && requireCoverage) return null;
+    const { rows } = await scanAndScore({
+      targetDirs,
+      coverage,
+      requireCoverage,
+      cwd,
+      ignoreGlobs,
+      scopeFiles: files,
+    });
+    return rows ?? [];
+  };
+}
+
+/**
+ * Refresh `origin/<baseBranch>` so the diff range resolves even when close
+ * has not reached its own base-sync step. Routed through the shared fetch
+ * cache so a story-init fetch in the same run satisfies it for free.
+ *
+ * @param {string} cwd
+ * @param {string} baseBranch
+ * @param {{ gitSpawn: typeof defaultGitSpawn }} git
+ * @returns {{ ok: true } | { ok: false, detail: string }}
+ */
+function refreshBaseRef(cwd, baseBranch, git) {
+  const res = cachedGitFetchSync(cwd, baseBranch, { gitSpawn: git.gitSpawn });
+  if (res.status !== 0) {
+    return {
+      ok: false,
+      detail: res.stderr || res.stdout || `exit ${res.status}`,
+    };
+  }
+  return { ok: true };
+}
+
+/**
+ * Enumerate the Story branch's changed files, narrowed to the extensions
+ * the CRAP scanner can score.
+ *
+ * @param {{ cwd: string, baseBranch: string, storyBranch: string, git: { gitSpawn: typeof defaultGitSpawn } }} opts
+ * @returns {{ ok: true, files: string[] } | { ok: false, detail: string }}
+ */
+function diffScorableFiles({ cwd, baseBranch, storyBranch, git }) {
+  try {
+    const files = diffNameOnly({
+      range: `origin/${baseBranch}...${storyBranch}`,
+      cwd,
+      gitSpawn: git.gitSpawn,
+    });
+    return { ok: true, files: files.filter((f) => SCORABLE.test(f)) };
+  } catch (err) {
+    return { ok: false, detail: err.message };
+  }
+}
+
+/**
+ * Project the post-merge CRAP scores for every file changed on the Story
+ * branch and return the subset of methods that would breach either their
+ * committed baseline row or, for methods with no baseline row, the
+ * configured `newMethodCeiling`.
+ *
+ * Baseline rows are narrowed to the changed-file set before the compare so
+ * every untouched file's rows are not spuriously reported as removed.
+ *
+ * @param {{
+ *   cwd: string,
+ *   baseBranch: string,
+ *   storyBranch: string,
+ *   baselinePath: string,
+ *   newMethodCeiling?: number,
+ *   tolerance?: number,
+ *   git?: { gitSpawn: typeof defaultGitSpawn },
+ *   loadBaseline?: (path: string) => Array<object>,
+ *   scoreFiles?: (files: string[]) => Promise<Array<object>|null>|Array<object>|null,
+ * }} opts
+ * @returns {Promise<{
+ *   ok: boolean,
+ *   breaches: Array<object>,
+ *   skipped?: string,
+ *   detail?: string,
+ * }>}
+ */
+export async function projectCrapBreaches({
+  cwd,
+  baseBranch,
+  storyBranch,
+  baselinePath,
+  newMethodCeiling = DEFAULT_NEW_METHOD_CEILING,
+  tolerance = DEFAULT_CRAP_TOLERANCE,
+  git = { gitSpawn: defaultGitSpawn },
+  loadBaseline = loadCrapBaselineRows,
+  scoreFiles,
+} = {}) {
+  const skip = (reason, detail) => ({
+    ok: true,
+    breaches: [],
+    skipped: reason,
+    ...(detail === undefined ? {} : { detail }),
+  });
+
+  const validation = validateProjectionInputs({
+    cwd,
+    baseBranch,
+    storyBranch,
+    baselinePath,
+  });
+  if (!validation.ok) return skip(normaliseSkipReason(validation.reason));
+
+  const baselineRows = loadBaseline(baselinePath);
+  if (!Array.isArray(baselineRows) || baselineRows.length === 0) {
+    return skip('no-baseline');
+  }
+
+  const fetched = refreshBaseRef(cwd, baseBranch, git);
+  if (!fetched.ok) return skip('fetch-failed', fetched.detail);
+
+  const diffed = diffScorableFiles({ cwd, baseBranch, storyBranch, git });
+  if (!diffed.ok) return skip('diff-failed', diffed.detail);
+  if (diffed.files.length === 0) return skip('no-scorable-files');
+
+  const scorer =
+    typeof scoreFiles === 'function' ? scoreFiles : createCrapScorer({ cwd });
+  let currentRows;
+  try {
+    currentRows = await scorer(diffed.files);
+  } catch (err) {
+    return skip('score-failed', err?.message ?? String(err));
+  }
+  if (currentRows === null || currentRows === undefined) {
+    return skip('no-coverage');
+  }
+  if (currentRows.length === 0) return skip('no-scored-methods');
+
+  const scopeSet = new Set(diffed.files);
+  const result = compareCrap({
+    currentRows,
+    baselineRows: filterRowsByFileScope(baselineRows, scopeSet),
+    newMethodCeiling,
+    tolerance,
+  });
+  const breaches = result.violations ?? [];
+  return { ok: breaches.length === 0, breaches };
+}
+
+/**
+ * Render one breach as an advisory bullet. New-method breaches name the
+ * ceiling they cleared; regressions name the baseline row they exceeded.
+ *
+ * @param {object} b
+ * @returns {string}
+ */
+function formatBreach(b) {
+  const where = `${b.file}::${b.method} (line ${b.startLine})`;
+  const projected = Number(b.crap ?? 0).toFixed(2);
+  if (b.kind === 'new') {
+    return `  • ${where}  projected=${projected}  ceiling=${b.ceiling}  [new method]`;
+  }
+  const baseline = Number(b.baseline ?? 0).toFixed(2);
+  return `  • ${where}  projected=${projected}  baseline=${baseline}  [${b.kind}]`;
+}
+
+/**
+ * Render the pre-merge CRAP advisory as a human-readable multi-line log
+ * block, naming every breaching method and the exact refresh remedy.
+ * Returns `null` when there is nothing to surface so callers can `if` past
+ * the log call without a string-empty check.
+ *
+ * @param {Awaited<ReturnType<typeof projectCrapBreaches>>} result
+ * @returns {string | null}
+ */
+export function formatCrapProjection(result) {
+  if (!result || !Array.isArray(result.breaches)) return null;
+  if (result.breaches.length === 0) return null;
+  const lines = [
+    `[close-validation] ⚠ Pre-merge CRAP projection: ${result.breaches.length} method(s) would breach post-merge:`,
+  ];
+  for (const b of result.breaches) lines.push(formatBreach(b));
+  lines.push(
+    '[close-validation]   To land cleanly, run `npm run crap:update` and commit the refreshed baseline with a `baseline-refresh:` tagged subject (non-empty body) on the story branch before re-running close.',
+  );
+  return lines.join('\n');
+}