mandrel 1.57.0 → 1.59.0

package/lib/cli/init.js

@@ -0,0 +1,336 @@
+// lib/cli/init.js
+/**
+ * `mandrel init` subcommand — one-command cold start (Story #3975).
+ *
+ * Folds the former `create-mandrel` launcher logic into a subcommand of the
+ * single published `mandrel` package. `npx mandrel init` (≡ `npm exec --
+ * mandrel init`, or `mandrel init` once installed) takes a project from a
+ * blank folder to a configured Mandrel environment in one command:
+ *
+ *   1. **Install-if-absent.** When `./.agents/` is missing in the cwd, install
+ *      the framework deterministically — `npm install mandrel --ignore-scripts`
+ *      followed by an explicit sync run against the freshly installed bin
+ *      (`node ./node_modules/mandrel/bin/mandrel.js sync`, NOT a bare `mandrel`
+ *      on `PATH` — see `SYNC_BIN` below). The `--ignore-scripts` install
+ *      skips the package's best-effort `postinstall` sync so the explicit
+ *      `sync` is the single, deterministic materialization (review rec D.3 —
+ *      no postinstall-then-init double-sync, and no arbitrary install
+ *      lifecycle scripts during cold start). When `./.agents/` already exists
+ *      (the operator ran `npm install mandrel` first), step 1 is skipped and
+ *      `init` goes straight to the prompt — the one subcommand is idempotent
+ *      across both the cold-start and post-install entry points.
+ *
+ *   2. **Two-option prompt.** Ask whether to configure now (option 1 → run
+ *      `node .agents/scripts/bootstrap.js`, forwarding every passthrough flag
+ *      unchanged) or stop at "just the files" (option 2 → print a re-run hint
+ *      and exit 0). `--assume-yes` skips the prompt and configures (the flag is
+ *      also forwarded to bootstrap for its own non-interactive run). A non-TTY
+ *      stdin without `--assume-yes` defaults to option 2 (files-only) so the
+ *      side-effecting GitHub provisioning never runs unattended.
+ *
+ * ## Cold-start provenance
+ *
+ * The installed package name is the **hardcoded build-time constant**
+ * `PACKAGE_NAME` below — it is NEVER read from argv or the environment. A
+ * cold start fetches `mandrel` from npx's temp cache and runs this bin; the
+ * package it then installs into the project must be the same `mandrel`, not an
+ * attacker-influenced name supplied on the command line. The forwarded
+ * passthrough flags reach `bootstrap.js` (the sole bootstrap orchestrator),
+ * which owns its own summary + confirm loop and validates its own inputs.
+ *
+ * ## Injectable seams (used by tests/cli/init.test.js)
+ *
+ * The plan/decision logic is a pure function (`planInit`) over injected
+ * boundaries so the suite is hermetic — no real TTY, npm, or network:
+ *
+ *   - `argv`     — subcommand args (after `mandrel init`)
+ *   - `exists`   — `(path) => boolean`; defaults to an `fs.existsSync` probe
+ *                  for `./.agents/` in the cwd
+ *   - `runStep`  — `(cmd, args) => { status }`; runs one install/sync/bootstrap
+ *                  step. Defaults to a `spawnSync` runner with `stdio: inherit`.
+ *   - `confirm`  — `() => '1' | '2'`; reads the operator's numbered choice.
+ *                  Defaults to a synchronous stdin readline prompt.
+ *   - `stdout`   — `(s) => void`; defaults to `process.stdout.write`.
+ *   - `isTTY`    — boolean; defaults to `process.stdin.isTTY`.
+ *   - `exit`     — `(code) => void`; defaults to `process.exit`.
+ *
+ * Security (security-baseline § 5/6): logs only flag/step descriptions and
+ * never reads or echoes tokens, credentials, or env values. The package name
+ * is a hardcoded constant rather than interpolated input, and the step runner
+ * passes argv as an array (no shell-string concatenation of user input).
+ */
+
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+
+/**
+ * Hardcoded build-time package name. NEVER read from argv or env — cold-start
+ * provenance requires the install target to be the same package this bin
+ * shipped from. See the module header.
+ */
+const PACKAGE_NAME = 'mandrel';
+
+// The `mandrel sync` and `node .agents/scripts/bootstrap.js` invocations both
+// resolve relative to the consumer's cwd at run time (the materialized
+// `.agents/` lives there), so they are expressed as cwd-relative steps rather
+// than against PROJECT_ROOT (which, under npx, is npx's throwaway cache).
+const BOOTSTRAP_SCRIPT = path.join('.agents', 'scripts', 'bootstrap.js');
+
+// The `sync` step is dispatched against the **locally installed** Mandrel bin
+// rather than a bare `mandrel` on `PATH`. A bare `spawnSync('mandrel', …)` only
+// resolves while npx keeps its throwaway `.bin` on `PATH`; reached any other
+// way (a documented `npm install mandrel` then `mandrel init`, or a plain
+// `node bin/mandrel.js init`), the freshly installed binary lives at
+// `./node_modules/mandrel/bin/mandrel.js` — off `PATH` — and a bare spawn dies
+// with ENOENT, leaving `.agents/` un-materialized. Spawning `process.execPath`
+// against the package entrypoint resolves identically under npx, under a
+// post-install invocation, and in tests — and, by going through `node`, also
+// sidesteps the win32 `.cmd`-shim concern entirely (no `shell: true` needed for
+// this step). The path is cwd-relative because the package is installed into
+// the consumer's cwd (the same reason BOOTSTRAP_SCRIPT is cwd-relative).
+const SYNC_BIN = path.join('node_modules', PACKAGE_NAME, 'bin', 'mandrel.js');
+
+const PROMPT_TEXT =
+  'Mandrel is installed. What next?\n' +
+  '  1) Configure my environment now (creates the GitHub repo + Projects board)\n' +
+  "  2) Just the files — I'll configure later\n" +
+  'Choice [1/2]: ';
+
+const FILES_ONLY_HINT = 'Configure any time with: mandrel init\n';
+
+// On win32, `npm` resolves to a `.cmd` shim that Node refuses to spawn without
+// a shell after the CVE-2024-27980 hardening; mirror update.js and set
+// `shell: true` only there. Off win32, never shell out — array argv stays
+// injection-proof. (The `sync` step no longer hits a `.cmd` shim at all: it is
+// dispatched as `process.execPath` + `SYNC_BIN`, a plain `node` spawn — but the
+// `npm install` step still needs the shim handling, so `NEEDS_SHELL` stays.)
+const NEEDS_SHELL = process.platform === 'win32';
+
+/**
+ * Strip the `--assume-yes` flag from a passthrough argv, returning the
+ * remaining flags. `--assume-yes` is consumed by `init` to skip the prompt but
+ * is ALSO forwarded to bootstrap (see `buildBootstrapArgs`), so this helper
+ * exists only to detect its presence, not to drop it from the forward set.
+ *
+ * @param {string[]} argv
+ * @returns {boolean} whether `--assume-yes` is present
+ */
+function hasAssumeYes(argv) {
+  return argv.includes('--assume-yes');
+}
+
+/**
+ * Build the forwarded argv for the bootstrap step. Every passthrough flag is
+ * forwarded unchanged; `--assume-yes` is appended when chosen but absent so
+ * bootstrap runs non-interactively without the operator having typed it.
+ *
+ * @param {string[]} argv
+ * @param {boolean} assumeYes
+ * @returns {string[]}
+ */
+function buildBootstrapArgs(argv, assumeYes) {
+  if (assumeYes && !argv.includes('--assume-yes')) {
+    return [...argv, '--assume-yes'];
+  }
+  return [...argv];
+}
+
+/**
+ * Decide and execute the cold-start plan over injected boundaries.
+ *
+ * This is the testable core: it consults `exists` to decide whether to run the
+ * install + sync steps, resolves the prompt outcome from `isTTY` / `--assume-yes`
+ * / `confirm`, and either runs the bootstrap step or prints the files-only hint.
+ * Every effectful boundary is injected so the suite never touches a real TTY,
+ * npm, or the network.
+ *
+ * @param {{
+ *   argv?: string[],
+ *   exists?: (relPath: string) => boolean,
+ *   runStep?: (cmd: string, args: string[]) => { status: number | null },
+ *   confirm?: () => '1' | '2',
+ *   stdout?: (s: string) => void,
+ *   isTTY?: boolean,
+ * }} [opts]
+ * @returns {{
+ *   installed: boolean,
+ *   ranBootstrap: boolean,
+ *   steps: Array<{ cmd: string, args: string[] }>,
+ *   exitCode: number,
+ * }}
+ */
+export function planInit({
+  argv = [],
+  exists,
+  runStep,
+  confirm,
+  stdout = (s) => process.stdout.write(s),
+  isTTY,
+} = {}) {
+  const steps = [];
+
+  /**
+   * Run one step through the injected runner and record it. A non-zero status
+   * short-circuits the plan with that exit code (the runner inherits stdio, so
+   * the failing tool's own output already reached the terminal).
+   *
+   * @param {string} cmd
+   * @param {string[]} args
+   * @returns {number} the step's exit code (0 on success)
+   */
+  const step = (cmd, args) => {
+    steps.push({ cmd, args });
+    const result = runStep(cmd, args);
+    return result?.status ?? 1;
+  };
+
+  // --- Step 1: install-if-absent ------------------------------------------
+  // When `./.agents/` is missing, materialize the framework deterministically:
+  // `npm install <pkg> --ignore-scripts` then explicit `mandrel sync`. When it
+  // is present, skip straight to the prompt (idempotent post-install path).
+  const agentsPresent = exists('.agents');
+  if (!agentsPresent) {
+    const installStatus = step('npm', [
+      'install',
+      PACKAGE_NAME,
+      '--ignore-scripts',
+    ]);
+    if (installStatus !== 0) {
+      return {
+        installed: false,
+        ranBootstrap: false,
+        steps,
+        exitCode: installStatus,
+      };
+    }
+
+    const syncStatus = step(process.execPath, [SYNC_BIN, 'sync']);
+    if (syncStatus !== 0) {
+      return {
+        installed: true,
+        ranBootstrap: false,
+        steps,
+        exitCode: syncStatus,
+      };
+    }
+  }
+
+  const installed = !agentsPresent;
+
+  // --- Step 2: configure-or-files prompt ----------------------------------
+  const assumeYes = hasAssumeYes(argv);
+
+  // Decide the outcome: configure (run bootstrap) vs. files-only.
+  // - `--assume-yes` → configure, prompt skipped entirely.
+  // - non-TTY without `--assume-yes` → files-only (never provision unattended).
+  // - TTY → consult the confirm seam for the numbered choice.
+  let choice;
+  if (assumeYes) {
+    choice = '1';
+  } else if (!isTTY) {
+    choice = '2';
+  } else {
+    stdout(PROMPT_TEXT);
+    choice = confirm();
+  }
+
+  if (choice === '1') {
+    const bootstrapArgs = buildBootstrapArgs(argv, assumeYes);
+    const bootstrapStatus = step(process.execPath, [
+      BOOTSTRAP_SCRIPT,
+      ...bootstrapArgs,
+    ]);
+    return {
+      installed,
+      ranBootstrap: true,
+      steps,
+      exitCode: bootstrapStatus,
+    };
+  }
+
+  // Option 2 (files-only): print the re-run hint and exit cleanly.
+  stdout(FILES_ONLY_HINT);
+  return { installed, ranBootstrap: false, steps, exitCode: 0 };
+}
+
+/**
+ * Default `exists` seam — probe for `./.agents/` in the consumer's cwd.
+ *
+ * @param {string} relPath
+ * @returns {boolean}
+ */
+function defaultExists(relPath) {
+  return fs.existsSync(path.resolve(process.cwd(), relPath));
+}
+
+/**
+ * Default step runner — spawn the tool synchronously, inheriting stdio so its
+ * output streams to the terminal. Sets `shell: true` only on win32 so the
+ * `npm.cmd` shim resolves under CVE-2024-27980 hardening. The `sync` and
+ * bootstrap steps spawn `process.execPath` (a plain `node`), which needs no
+ * shell on any platform.
+ *
+ * @param {string} cmd
+ * @param {string[]} args
+ * @returns {{ status: number | null }}
+ */
+function defaultRunStep(cmd, args) {
+  return spawnSync(cmd, args, {
+    stdio: 'inherit',
+    env: process.env,
+    shell: NEEDS_SHELL,
+  });
+}
+
+/**
+ * Default `confirm` seam — synchronous numbered-choice prompt. Reads one line
+ * from stdin and normalizes it to `'1'` or `'2'`; any input other than `'2'`
+ * (including bare Enter) defaults to `'1'` (configure), matching the
+ * `Choice [1/2]:` convention where the first option is the default.
+ *
+ * @returns {'1' | '2'}
+ */
+function defaultConfirm() {
+  let answer = '';
+  try {
+    const buf = fs.readFileSync(0, 'utf8');
+    answer = buf.split('\n', 1)[0].trim();
+  } catch {
+    // No readable line (e.g. stdin closed) → fall through to the default.
+    answer = '';
+  }
+  return answer === '2' ? '2' : '1';
+}
+
+/**
+ * Default export consumed by `bin/mandrel.js`.
+ *
+ * @param {string[]} [argv] - Subcommand arguments (after `mandrel init`).
+ * @returns {void}
+ */
+export default function run(argv = []) {
+  if (argv.includes('--help') || argv.includes('-h')) {
+    process.stdout.write(
+      'Usage: mandrel init [bootstrap flags]\n\n' +
+        '  One-command cold start: install Mandrel (if absent), then prompt to\n' +
+        '  configure now or stop at the files.\n\n' +
+        '  --assume-yes   Skip the prompt and configure non-interactively\n' +
+        '                 (forwarded to bootstrap.js). All other flags are\n' +
+        '                 forwarded to bootstrap.js unchanged.\n',
+    );
+    return;
+  }
+
+  const result = planInit({
+    argv,
+    exists: defaultExists,
+    runStep: defaultRunStep,
+    confirm: defaultConfirm,
+    isTTY: Boolean(process.stdin.isTTY),
+  });
+
+  if (result.exitCode !== 0) {
+    process.exit(result.exitCode);
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mandrel",
-  "version": "1.57.0",
+  "version": "1.59.0",
   "description": "Claude Code-first opinionated workflow framework: instructions, personas, skills, and SDLC workflows that govern AI coding assistants.",
   "main": "index.js",
   "files": [
@@ -36,6 +36,7 @@
     "format:check": "biome ci .",
     "maintainability:check": "node .agents/scripts/check-baselines.js --gate maintainability",
     "maintainability:update": "node .agents/scripts/update-maintainability-baseline.js",
+    "check:arch": "node .agents/scripts/check-arch-cycles.js",
     "crap:check": "node .agents/scripts/check-baselines.js --gate crap",
     "crap:update": "node .agents/scripts/update-crap-baseline.js",
     "duplication:check": "node .agents/scripts/check-baselines.js --gate duplication",

package/.agents/scripts/lib/auto-refresh-baselines.js

@@ -1,308 +0,0 @@
-/**
- * auto-refresh-baselines.js — pure delta-cap evaluator for the bounded
- * baseline auto-refresh at story-close (Story #1398, Epic #1386).
- *
- * Story #1891 (Epic #1786) note: this evaluator is purely functional and
- * has never written a baseline JSON file directly — every regenerated row
- * funnels through the per-kind refresh entry points
- * (`update-crap-baseline.js`, `update-maintainability-baseline.js`,
- * `lib/coverage-baseline.js`'s `writeBaseline`), which now write through
- * the shared `lib/baselines/writer.js`. The migration leaves this
- * evaluator unchanged structurally; it remains the single seam for the
- * delta-cap decision.
- *
- * After the close-validation chain has passed (`runPreMergeGatesWithAttribution`
- * already auto-refreshed any attributable drift), `story-close` regenerates
- * the baseline rows scoped to the Story diff and asks this evaluator whether
- * the regenerated rows are within bounded delta caps. If yes, `story-close`
- * amends the regenerated rows into the close commit (no separate
- * `baseline-refresh:` commit). If no, `story-close` refuses to amend, leaves
- * the close commit untouched, and appends a `baseline-refresh-regression`
- * friction signal naming the offending file(s)/method(s).
- *
- * The evaluator is a pure function — no I/O, no spawn, no provider calls.
- * Inputs are fixtures the caller has already loaded; outputs are plain
- * objects ready for the friction-signal renderer.
- *
- * Contract:
- *
- *   evaluateAutoRefresh({ scoredRows, baseline, caps }) →
- *     {
- *       canAutoRefresh: boolean,
- *       miOverCap:   Array<{ path, baseline, scored, delta }>,
- *       crapOverCap: Array<{ file, method, startLine, baseline, scored, delta }>,
- *       refusalReasons: string[],
- *     }
- *
- *   - `scoredRows` carries the *just-regenerated* rows, partitioned by kind:
- *       { mi: Array<{ path, mi }>, crap: Array<{ file, method, startLine, crap }> }
- *     Either kind may be absent or empty — the evaluator treats a missing
- *     kind as "no rows of that kind to evaluate".
- *
- *   - `baseline` carries the *previously committed* rows, in the same shape:
- *       { mi: Array<{ path, mi }>, crap: Array<{ file, method, startLine, crap }> }
- *     A scored row whose path/method has no matching baseline row is treated
- *     as "new" and evaluated against the cap with `baseline = null` — its
- *     delta is the scored value vs an absent prior, which by convention
- *     never breaches a cap (the row didn't exist before, there is no drop /
- *     jump to bound). New rows therefore never block auto-refresh.
- *
- *   - `caps = { miDropCap: number, crapJumpCap: number }` carries the
- *     bounded delta thresholds. The defaults (`miDropCap: 1.5`,
- *     `crapJumpCap: 5`) live in `.agents/docs/agentrc-reference.json` under
- *     `delivery.quality.autoRefresh` (Story #1413). Callers always
- *     pass an explicit caps object; the evaluator does not default-fill.
- *
- * Cap semantics:
- *
- *   - MI is "higher is better". A *drop* (baseline.mi − scored.mi) greater
- *     than `miDropCap` breaches the cap. Improvements (scored.mi ≥ baseline.mi
- *     or any negative drop) never breach.
- *
- *   - CRAP is "lower is better". A *jump* (scored.crap − baseline.crap)
- *     greater than `crapJumpCap` breaches the cap. Improvements (scored.crap
- *     ≤ baseline.crap or any negative jump) never breach.
- *
- *   - Equality at the cap (delta === cap) is *under* the cap — the cap is
- *     the maximum allowed delta, not the strict maximum. This matches the
- *     Tech Spec's "at or below" wording and the AC1 phrasing ("every scored
- *     row delta is at or below the configured caps").
- *
- *   - Missing baseline rows (path/method new in the scored set) are recorded
- *     with `baseline: null` and a `delta` of 0 — they never push
- *     `canAutoRefresh` to `false`. The evaluator does not surface them in
- *     `miOverCap` / `crapOverCap`. The friction renderer therefore never
- *     names a file that was newly introduced by the Story.
- *
- * The renderer is pure so callers can unit-test the cap math against fixed
- * inputs without spawning git or reading the filesystem. Story-close wires
- * it into the post-validation amend path; tests for the wiring live in
- * `tests/story-close-auto-refresh.test.js` (Story #1415).
- */
-
-/**
- * Numeric guard — accepts finite numbers only. Strings, NaN, Infinity, null,
- * undefined all fail. The evaluator runs against scored rows produced by the
- * MI / CRAP scanners (which always emit numeric scores) and baseline rows
- * loaded from the on-disk JSON (which JSON-parses numeric fields), so a
- * non-finite value here signals upstream corruption — we exclude the row
- * conservatively rather than coercing.
- */
-function isFiniteNumber(value) {
-  return typeof value === 'number' && Number.isFinite(value);
-}
-
-/**
- * Index `baseline.mi` rows by `path` for O(1) lookup. Bad rows (missing
- * `path`, non-string `path`, non-finite `mi`) are skipped — their absence
- * causes the matching scored row to be treated as "new", which never blocks
- * auto-refresh.
- */
-function indexMiBaseline(rows) {
-  const byPath = new Map();
-  if (!Array.isArray(rows)) return byPath;
-  for (const row of rows) {
-    if (!row || typeof row.path !== 'string' || row.path.length === 0) continue;
-    if (!isFiniteNumber(row.mi)) continue;
-    byPath.set(row.path, row);
-  }
-  return byPath;
-}
-
-/**
- * Index `baseline.crap` rows by `${file}::${method}` for O(1) lookup.
- * `startLine` is *not* part of the key — the scored row may have shifted
- * lines vs the baseline (legitimate refactor), and we want the closest match
- * by method name. When the same method appears multiple times in the same
- * file (e.g. nested helpers), we pick the closest startLine at lookup time.
- *
- * Bad rows (missing `file`/`method`, non-finite `crap`) are skipped — their
- * absence causes the matching scored row to be treated as "new".
- */
-function indexCrapBaseline(rows) {
-  const byMethod = new Map();
-  if (!Array.isArray(rows)) return byMethod;
-  for (const row of rows) {
-    if (!row || typeof row.file !== 'string' || row.file.length === 0) {
-      continue;
-    }
-    if (typeof row.method !== 'string' || row.method.length === 0) continue;
-    if (!isFiniteNumber(row.crap)) continue;
-    const key = `${row.file}::${row.method}`;
-    if (!byMethod.has(key)) byMethod.set(key, []);
-    byMethod.get(key).push(row);
-  }
-  return byMethod;
-}
-
-/**
- * Pick the closest baseline candidate by `startLine` distance. When the
- * scored row's `startLine` is missing or all candidates have missing line
- * info, returns the first candidate — matches `baseline-attribution-wiring`'s
- * `diffCrapBaselines` resolution policy.
- */
-function pickClosestBaseline(candidates, scoredStartLine) {
-  if (!Array.isArray(candidates) || candidates.length === 0) return null;
-  if (candidates.length === 1) return candidates[0];
-  const target = isFiniteNumber(scoredStartLine) ? scoredStartLine : 0;
-  let best = candidates[0];
-  let bestDist = Math.abs((best.startLine ?? 0) - target);
-  for (let i = 1; i < candidates.length; i += 1) {
-    const c = candidates[i];
-    const dist = Math.abs((c?.startLine ?? 0) - target);
-    if (dist < bestDist) {
-      bestDist = dist;
-      best = c;
-    }
-  }
-  return best;
-}
-
-/**
- * Evaluate every MI scored row against the MI cap. Returns the over-cap
- * subset; rows under the cap (or new) are simply omitted from the result.
- *
- * MI is higher-is-better, so drift = baseline.mi − scored.mi. A positive
- * drift is a regression; a drift greater than `miDropCap` breaches the cap.
- */
-function evaluateMiRows({ scoredRows, baselineIndex, miDropCap }) {
-  const overCap = [];
-  if (!Array.isArray(scoredRows)) return overCap;
-  for (const row of scoredRows) {
-    if (!row || typeof row.path !== 'string' || row.path.length === 0) {
-      continue;
-    }
-    if (!isFiniteNumber(row.mi)) continue;
-    const baselineRow = baselineIndex.get(row.path);
-    if (!baselineRow) continue; // new path — never breaches
-    const drop = baselineRow.mi - row.mi;
-    if (drop > miDropCap) {
-      overCap.push({
-        path: row.path,
-        baseline: baselineRow.mi,
-        scored: row.mi,
-        delta: drop,
-      });
-    }
-  }
-  return overCap;
-}
-
-/**
- * Evaluate every CRAP scored row against the CRAP cap. Returns the over-cap
- * subset; rows under the cap (or new) are simply omitted from the result.
- *
- * CRAP is lower-is-better, so jump = scored.crap − baseline.crap. A positive
- * jump is a regression; a jump greater than `crapJumpCap` breaches the cap.
- */
-function evaluateCrapRows({ scoredRows, baselineIndex, crapJumpCap }) {
-  const overCap = [];
-  if (!Array.isArray(scoredRows)) return overCap;
-  for (const row of scoredRows) {
-    if (!row || typeof row.file !== 'string' || row.file.length === 0) {
-      continue;
-    }
-    if (typeof row.method !== 'string' || row.method.length === 0) continue;
-    if (!isFiniteNumber(row.crap)) continue;
-    const candidates = baselineIndex.get(`${row.file}::${row.method}`);
-    const baselineRow = pickClosestBaseline(candidates, row.startLine);
-    if (!baselineRow) continue; // new method — never breaches
-    const jump = row.crap - baselineRow.crap;
-    if (jump > crapJumpCap) {
-      overCap.push({
-        file: row.file,
-        method: row.method,
-        startLine: row.startLine,
-        baseline: baselineRow.crap,
-        scored: row.crap,
-        delta: jump,
-      });
-    }
-  }
-  return overCap;
-}
-
-/**
- * Build the human-readable refusal reasons array. Stable formatting so the
- * friction-signal renderer (and unit tests) can pin the strings exactly.
- *
- * Each reason names the kind, the file/path/method, and the absolute delta
- * vs the cap. Numbers are formatted to 3 decimal places to match the
- * baseline JSON's float precision without trailing-zero noise.
- */
-function buildRefusalReasons({ miOverCap, crapOverCap, caps }) {
-  const reasons = [];
-  for (const r of miOverCap) {
-    reasons.push(
-      `MI drop ${r.delta.toFixed(3)} > cap ${caps.miDropCap} on ${r.path} (baseline ${r.baseline.toFixed(3)} → scored ${r.scored.toFixed(3)})`,
-    );
-  }
-  for (const r of crapOverCap) {
-    reasons.push(
-      `CRAP jump ${r.delta.toFixed(3)} > cap ${caps.crapJumpCap} on ${r.file}::${r.method} (baseline ${r.baseline.toFixed(3)} → scored ${r.scored.toFixed(3)})`,
-    );
-  }
-  return reasons;
-}
-
-/**
- * Pure delta-cap evaluator. Decides whether the regenerated rows can be
- * silently amended into the close commit (under-cap) or whether the close
- * must refuse the amend and surface a `baseline-refresh-regression` friction
- * signal (over-cap).
- *
- * @param {object} input
- * @param {{
- *   mi?: Array<{ path: string, mi: number }>,
- *   crap?: Array<{ file: string, method: string, startLine?: number, crap: number }>,
- * }} input.scoredRows  Just-regenerated rows for the Story diff.
- * @param {{
- *   mi?: Array<{ path: string, mi: number }>,
- *   crap?: Array<{ file: string, method: string, startLine?: number, crap: number }>,
- * }} input.baseline    Previously committed rows.
- * @param {{ miDropCap: number, crapJumpCap: number }} input.caps
- *   Bounded delta caps (defaults: miDropCap=1.5, crapJumpCap=5 — see
- *   `.agents/docs/agentrc-reference.json` under `delivery.quality.autoRefresh`).
- * @returns {{
- *   canAutoRefresh: boolean,
- *   miOverCap:   Array<{ path: string, baseline: number, scored: number, delta: number }>,
- *   crapOverCap: Array<{ file: string, method: string, startLine?: number, baseline: number, scored: number, delta: number }>,
- *   refusalReasons: string[],
- * }}
- */
-export function evaluateAutoRefresh({
-  scoredRows = {},
-  baseline = {},
-  caps,
-} = {}) {
-  if (
-    !caps ||
-    !isFiniteNumber(caps.miDropCap) ||
-    !isFiniteNumber(caps.crapJumpCap)
-  ) {
-    throw new TypeError(
-      'evaluateAutoRefresh: caps.{miDropCap,crapJumpCap} must be finite numbers',
-    );
-  }
-
-  const miBaselineIdx = indexMiBaseline(baseline?.mi);
-  const crapBaselineIdx = indexCrapBaseline(baseline?.crap);
-
-  const miOverCap = evaluateMiRows({
-    scoredRows: scoredRows?.mi,
-    baselineIndex: miBaselineIdx,
-    miDropCap: caps.miDropCap,
-  });
-  const crapOverCap = evaluateCrapRows({
-    scoredRows: scoredRows?.crap,
-    baselineIndex: crapBaselineIdx,
-    crapJumpCap: caps.crapJumpCap,
-  });
-
-  const canAutoRefresh = miOverCap.length === 0 && crapOverCap.length === 0;
-  const refusalReasons = canAutoRefresh
-    ? []
-    : buildRefusalReasons({ miOverCap, crapOverCap, caps });
-
-  return { canAutoRefresh, miOverCap, crapOverCap, refusalReasons };
-}