mandrel 2.35.0 → 2.37.0

package/.agents/scripts/lib/baselines/env-overrides.js

@@ -16,7 +16,7 @@ import { Logger } from '../Logger.js';
 // rounding) routinely drifts +/- 0.05 to 0.3 on otherwise-unchanged files —
 // well below the threshold of "actually less maintainable." A 0.5 floor
 // stops the pre-push hook from auto-ratcheting the baseline on noise.
-export const MI_DEFAULT_TOLERANCE = 0.5;
+const MI_DEFAULT_TOLERANCE = 0.5;
 
 /**
  * Pure helper: resolve the effective CRAP config by layering env-var

package/.agents/scripts/lib/bootstrap/branch-protection.js

@@ -43,7 +43,7 @@ const TARGET_APPROVAL_COUNT = 0;
  * return value is a structured diff suitable for `hitlConfirm` so the
  * operator sees exactly what would flip.
  */
-export function diffProtection(current, targetContexts) {
+function diffProtection(current, targetContexts) {
   if (!current) return null; // create-from-scratch path; no diff needed.
 
   const diff = {};

package/.agents/scripts/lib/bootstrap/install-ledger.js

@@ -80,7 +80,7 @@ const TARGET_TO_PHASE = Object.freeze({
  * @param {Record<string, { action?: string }>} [report]
  * @returns {string|undefined}
  */
-export function resolveExecutedAction(entry, report) {
+function resolveExecutedAction(entry, report) {
   if (!report) return undefined;
   const phaseName = TARGET_TO_PHASE[entry.target];
   if (!phaseName) return undefined;

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

@@ -28,7 +28,7 @@ import readline from 'node:readline/promises';
  * Flags the bootstrap CLI accepts. Keep this list in sync with the
  * `--help` text in bootstrap.js.
  */
-export const KNOWN_FLAGS = Object.freeze({
+const KNOWN_FLAGS = Object.freeze({
   string: [
     'owner',
     'repo',

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

@@ -41,7 +41,7 @@ import { deepEqual } from '../json-utils.js';
  * the hook-installer can detect a verbatim framework hook (overwrite-safe)
  * vs a custom hook (preserve and warn).
  */
-export const FRAMEWORK_PRE_COMMIT = `node scripts/check-version-sync.js
+const FRAMEWORK_PRE_COMMIT = `node scripts/check-version-sync.js
 npx lint-staged
 # Story #1395 / Epic #1386: catch MI/CRAP drift at git-commit time so the
 # agent refactors before the diff is closed. quality:preview wraps both gates
@@ -78,7 +78,7 @@ export const PRE_COMMIT_MARKER =
  * when the keys are absent. Mirrors `.agents/docs/agentrc-reference.json` — keep in
  * sync when those numbers move.
  */
-export const QUALITY_CONFIG_DEFAULTS = Object.freeze({
+const QUALITY_CONFIG_DEFAULTS = Object.freeze({
   codingGuardrails: Object.freeze({
     cyclomaticFlag: 8,
     cyclomaticMustFix: 12,

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

@@ -42,7 +42,7 @@ import { validateSignal } from '../observability/signal-validator.js';
  * a health probe, not an exhaustive audit — the most recent window is a
  * representative sample that keeps the read bounded on long streams.
  */
-export const MAX_SAMPLE_LINES = 200;
+const MAX_SAMPLE_LINES = 200;
 
 /**
  * Locate the most-recently-touched `run-<id>` temp tree under

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

@@ -210,7 +210,6 @@ export function parseSprintArgs(
       'recut-of': { type: 'string' },
       resume: { type: 'boolean', default: false },
       restart: { type: 'boolean', default: false },
-      'no-evidence': { type: 'boolean', default: false },
     },
     allowPositionals: true,
     strict: false,
@@ -260,7 +259,6 @@ export function parseSprintArgs(
     // CLI compatibility).
     resume: values.resume ?? false,
     restart: values.restart ?? false,
-    noEvidence: values['no-evidence'] ?? false,
   };
 
   parsed.ticketId =

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

@@ -392,7 +392,7 @@ export const DEFAULT_GATES = buildDefaultGates();
  * state, no overlapping ports/sockets). Safe to run concurrently — see
  * `runCloseValidation` for the Promise.all + AbortController plumbing.
  */
-export const INDEPENDENT_GATE_NAMES = new Set(['lint', 'format', 'typecheck']);
+const INDEPENDENT_GATE_NAMES = new Set(['lint', 'format', 'typecheck']);
 
 /**
  * Partition a gate list into the parallel-safe set and the order-sensitive

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

@@ -113,7 +113,7 @@ const MARKER_PROBE_TAIL_LINES = 32;
  * @param {string} output - Combined stdout/stderr captured from the gate child.
  * @returns {boolean}
  */
-export function isBiomeNoFilesProcessed(output) {
+function isBiomeNoFilesProcessed(output) {
   return (
     typeof output === 'string' && output.includes(BIOME_NO_FILES_PROCESSED)
   );

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

@@ -5,6 +5,13 @@
  * (default `"trust-ci"`) selects the merge posture — `"trust-ci"` merges once
  * required checks pass, `"strict"` additionally requires a clean review gate.
  *
+ * Story #5096 added `blockOnAdvisoryFailure` (default `true`) and
+ * `advisoryAllowlist` (default `[]`). GitHub native auto-merge waits on
+ * REQUIRED contexts only, so a red ADVISORY gate would otherwise be merged
+ * straight past; these knobs own mandrel's side of that decision. Set
+ * `blockOnAdvisoryFailure: false` to restore the pre-#5096 behaviour verbatim,
+ * or list a job name in `advisoryAllowlist` to exempt just that one.
+ *
  * Retired (no production readers on v2 Story-only delivery): `earlyPr`
  * (Epic early-PR warmup) and `requireChecks` (AutomergePredicate escape hatch
  * whose listener was never landed).
@@ -12,6 +19,8 @@
 
 export const CI_DELIVERY_DEFAULTS = Object.freeze({
   autoMerge: 'trust-ci',
+  blockOnAdvisoryFailure: true,
+  advisoryAllowlist: Object.freeze([]),
 });
 
 /**
@@ -31,6 +40,15 @@ export function getCiDelivery(config) {
       ci.autoMerge === 'trust-ci' || ci.autoMerge === 'strict'
         ? ci.autoMerge
         : CI_DELIVERY_DEFAULTS.autoMerge,
+    blockOnAdvisoryFailure:
+      typeof ci.blockOnAdvisoryFailure === 'boolean'
+        ? ci.blockOnAdvisoryFailure
+        : CI_DELIVERY_DEFAULTS.blockOnAdvisoryFailure,
+    advisoryAllowlist: Array.isArray(ci.advisoryAllowlist)
+      ? ci.advisoryAllowlist.filter(
+          (entry) => typeof entry === 'string' && entry,
+        )
+      : [...CI_DELIVERY_DEFAULTS.advisoryAllowlist],
     watch:
       ci.watch && typeof ci.watch === 'object' ? { ...ci.watch } : undefined,
   };

package/.agents/scripts/lib/config/sync-agentrc.js

@@ -173,7 +173,7 @@ export function collectRedundantAdvisories(
  * @param {string} dottedPath
  * @returns {boolean}
  */
-export function isLeafSchemaRemovable(rootSchema, dottedPath) {
+function isLeafSchemaRemovable(rootSchema, dottedPath) {
   if (!rootSchema || typeof rootSchema !== 'object') return true;
   const parts = dottedPath.split('.');
   let cursor = rootSchema;

package/.agents/scripts/lib/config-settings-schema-delivery.js

@@ -389,6 +389,19 @@ const CI_DELIVERY_SCHEMA = {
         "Story #4356 (Epic #4355). Merge posture. 'trust-ci' (default) merges once required checks pass; 'strict' additionally requires a clean review gate.",
       default: CI_DELIVERY_DEFAULTS.autoMerge,
     },
+    blockOnAdvisoryFailure: {
+      type: 'boolean',
+      description:
+        'Story #5096. When true (default), delivery refuses to arm — and disarms — GitHub native auto-merge while a non-required (advisory) check is genuinely red on the PR head and GitHub reports the PR mergeable anyway (mergeStateStatus=UNSTABLE). `--auto` waits on REQUIRED contexts only, so without this a red advisory quality gate merges unattended. Set false to restore the pre-#5096 behaviour verbatim.',
+      default: CI_DELIVERY_DEFAULTS.blockOnAdvisoryFailure,
+    },
+    advisoryAllowlist: {
+      type: 'array',
+      items: { type: 'string' },
+      description:
+        'Story #5096. Check-run names exempt from blockOnAdvisoryFailure — a red run whose name matches exactly never blocks arming. Matching is exact; an unnamed run can never match and always blocks.',
+      default: [...CI_DELIVERY_DEFAULTS.advisoryAllowlist],
+    },
   },
   additionalProperties: false,
 };

package/.agents/scripts/lib/config-settings-schema.js

@@ -1,7 +1,7 @@
 /* node:coverage ignore file -- AJV schema declaration (data-as-code); MI < 70 is inherent to large flat schema literals, no business logic to test */
 
-import Ajv from 'ajv';
-
+import { createRequire } from 'node:module';
+import process from 'node:process';
 import { COMMANDS_DEFAULTS } from './config/commands.js';
 import {
   BRANCH_PROTECTION_DEFAULTS,
@@ -15,6 +15,7 @@ import { SHELL_INJECTION_PATTERN_STRING } from './config-schema-shared.js';
 // to keep this aggregate module above the maintainability floor. The
 // resolved AGENTRC_SCHEMA is unchanged.
 import { DELIVERY_SCHEMA } from './config-settings-schema-delivery.js';
+import compiledAgentrcValidator from './generated/agentrc-validator.js';
 
 /**
  * Annotation contract (Story #5007). These schema literals are the SINGLE
@@ -861,10 +862,49 @@ export const AGENTRC_SCHEMA = {
 };
 
 let _agentrcValidator = null;
+
+/**
+ * Compile `AGENTRC_SCHEMA` with a live AJV instance.
+ *
+ * `ajv` is pulled in through `createRequire` rather than a top-level
+ * `import` so the module never enters the graph on the fast path
+ * (Story #5109). Loading AJV was itself a measurable share of the ~35 ms
+ * this function used to cost in each of the 36 config-touching entry
+ * scripts, and the precompiled validator needs none of it.
+ *
+ * @returns {import('ajv').ValidateFunction}
+ */
+function compileAgentrcValidatorDynamically() {
+  const require = createRequire(import.meta.url);
+  const ajvModule = require('ajv');
+  const Ajv = ajvModule.default ?? ajvModule;
+  const ajv = new Ajv({ allErrors: true });
+  return ajv.compile(AGENTRC_SCHEMA);
+}
+
+/**
+ * The `.agentrc.json` validator.
+ *
+ * Returns the **precompiled** validator committed at
+ * `lib/generated/agentrc-validator.js` — AJV's standalone emit for the exact
+ * `AGENTRC_SCHEMA` literal above, kept in step by
+ * `check-generated-validator.js --check` inside `npm run lint`. The verdicts
+ * are AJV's own, produced by AJV's own generated code with the same
+ * `allErrors: true` option the dynamic path uses, so nothing about what a
+ * config is allowed to contain changes — only when the codegen runs.
+ *
+ * Set `MANDREL_AGENTRC_VALIDATOR=dynamic` to compile at runtime instead. That
+ * escape hatch exists so a consumer who has hand-edited the schema (or hit a
+ * platform where the generated module will not load) is never stuck with a
+ * validator they cannot regenerate; it costs the ~35 ms the artifact removes.
+ *
+ * @returns {import('ajv').ValidateFunction}
+ */
 export function getAgentrcValidator() {
-  if (!_agentrcValidator) {
-    const ajv = new Ajv({ allErrors: true });
-    _agentrcValidator = ajv.compile(AGENTRC_SCHEMA);
-  }
+  if (_agentrcValidator) return _agentrcValidator;
+  _agentrcValidator =
+    process.env.MANDREL_AGENTRC_VALIDATOR === 'dynamic'
+      ? compileAgentrcValidatorDynamically()
+      : compiledAgentrcValidator;
   return _agentrcValidator;
 }

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

@@ -22,7 +22,7 @@ import path from 'node:path';
 import picomatch from 'picomatch';
 import { write, writeFile } from './baselines/writer.js';
 
-export const COVERAGE_FINAL_PATH = 'coverage/coverage-final.json';
+const COVERAGE_FINAL_PATH = 'coverage/coverage-final.json';
 export const COVERAGE_BASELINE_PATH = 'baselines/coverage.json';
 // Absolute floating-point tolerance (percentage points). Values in the
 // baseline are stored to two decimals, so anything below 0.01 is noise.
@@ -32,7 +32,7 @@ export const COVERAGE_TOLERANCE = 0.01;
 // branch flipping covered↔uncovered between runs is the natural noise floor
 // under non-deterministic Windows/Node 22 V8 instrumentation. We absorb up
 // to one event of slack per axis. Anything beyond one event is real signal.
-export const NOISE_EVENT_HEADROOM = 1.0;
+const NOISE_EVENT_HEADROOM = 1.0;
 
 function toForwardSlash(p) {
   return p.replace(/\\/g, '/');

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

@@ -2,7 +2,9 @@
  * lib/cpu-pool.js — Generic worker_threads pool for CPU-bound work.
  *
  * `runOnPool(workerScript, items, opts)` spawns up to
- * `opts.concurrency ?? os.availableParallelism()` persistent workers,
+ * `resolvePoolConcurrency(opts.concurrency)` persistent workers — an
+ * explicit option, else `MANDREL_POOL_CONCURRENCY`, else a clamp of 4 under
+ * `node:test`, else `os.availableParallelism()` —
  * dispatches `items` to whichever worker is idle, and resolves with an
  * array of per-item results in input order. The queue is bounded by
  * worker count — we only have N items in flight at once, where N =
@@ -58,15 +60,93 @@ 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.
+ * callers fall back to in-process serial scoring. 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.
+ *
+ * **Retuned from 8 to 256 in Story #5109.** The original 8 was set against
+ * tmpdir fixtures and never measured against a real batch, so every
+ * pre-commit preview — the most frequent path in the framework — paid for a
+ * pool it could not amortise. Measured on this repository (18 logical cores,
+ * `.agents/scripts` + `bin` + `lib`, MI scoring):
+ *
+ * ```text
+ *   n=16   serial  125 ms   pooled  444 ms
+ *   n=64   serial  175 ms   pooled  535 ms
+ *   n=128  serial  241 ms   pooled  422 ms
+ *   n=256  serial  440 ms   pooled  707 ms   <- still serial-favourable
+ *   n=384  serial  943 ms   pooled  782 ms   <- crossover
+ *   n=619  serial 1054 ms   pooled  710 ms
+ * ```
+ *
+ * The crossover sits between 256 and 384, so 256 is the last power-of-two
+ * step the serial path provably wins. A whole-tree baseline refresh
+ * (n≈619) still takes the pool; a diff-scoped preview (n≈50) no longer
+ * spawns a worker at all. Scoring output is identical on either path — the
+ * worker runs the same scorer — so this is a cost retune, never a verdict
+ * change.
+ */
+export const POOL_SERIAL_THRESHOLD = 256;
+
+/**
+ * Hard ceiling on pool width when the process is a `node:test` child.
+ *
+ * Node's test runner already fans test *files* out across processes, so a
+ * pool inside one of them multiplies against that fan-out and can oversubscribe
+ * the host by an order of magnitude. Four is wide enough to keep the pooled
+ * code path genuinely concurrent (so the scheduling branches under test stay
+ * exercised) without letting a suite of parallel test processes each claim
+ * every core.
+ */
+const NODE_TEST_CONCURRENCY_CLAMP = 4;
+
+/**
+ * True when this process was spawned by Node's own test runner, which sets
+ * `NODE_TEST_CONTEXT` in every test child.
+ *
+ * @param {NodeJS.ProcessEnv} env
+ * @returns {boolean}
+ */
+function inNodeTestContext(env) {
+  return (
+    typeof env.NODE_TEST_CONTEXT === 'string' && env.NODE_TEST_CONTEXT !== ''
+  );
+}
+
+/**
+ * Resolve the requested pool width, in strict precedence order:
+ *
+ *   1. an explicit `opts.concurrency` — the caller knows its own budget;
+ *   2. `MANDREL_POOL_CONCURRENCY` — the operator/CI override, so a
+ *      constrained runner can bound every pool in the process tree at once;
+ *   3. `NODE_TEST_CONCURRENCY_CLAMP` when running under `node:test`;
+ *   4. `os.availableParallelism()`.
+ *
+ * Only *finite, positive* values are honoured at each step; anything else
+ * falls through to the next, so a typo in the env var degrades to the
+ * default rather than collapsing the pool to a single worker.
+ *
+ * Module-private on purpose: `runOnPool` is the only caller, and the
+ * precedence is pinned through its observable worker count rather than by
+ * an export whose sole importer would be a test.
+ *
+ * @param {number|undefined} explicit
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {number}
  */
-export const POOL_SERIAL_THRESHOLD = 8;
+function resolvePoolConcurrency(explicit, env = process.env) {
+  const positive = (value) => {
+    const n = Number(value);
+    return Number.isFinite(n) && n >= 1 ? Math.floor(n) : null;
+  };
+  return (
+    positive(explicit) ??
+    positive(env.MANDREL_POOL_CONCURRENCY) ??
+    (inNodeTestContext(env) ? NODE_TEST_CONCURRENCY_CLAMP : null) ??
+    os.availableParallelism()
+  );
+}
 
 /**
  * @template TItem, TResult
@@ -90,7 +170,7 @@ export async function runOnPool(workerScript, items, opts = {}) {
   const itemsArr = [...items];
   if (itemsArr.length === 0) return [];
 
-  const requested = opts.concurrency ?? os.availableParallelism();
+  const requested = resolvePoolConcurrency(opts.concurrency);
   const concurrency = Math.max(1, Math.min(requested, itemsArr.length));
   const workerData = opts.workerData;
   const throwOnItemError = opts.throwOnItemError === true;

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

@@ -21,7 +21,10 @@ import {
 const CRAP_WORKER_URL = new URL('./workers/crap-worker.js', import.meta.url);
 
 // Pool-vs-serial cutover — single-sourced in cpu-pool.js (see the
-// POOL_SERIAL_THRESHOLD docstring for the tuning rationale).
+// POOL_SERIAL_THRESHOLD docstring for the tuning rationale). Callers may
+// override it per scan via `serialThreshold`, which is how the parity tests
+// drive the pooled path without materialising a batch bigger than the
+// cutover (Story #5109 raised it from 8 to 256).
 const SERIAL_THRESHOLD = POOL_SERIAL_THRESHOLD;
 // 1.1.0 — TypeScript support landed in 5.29.0. Bumped from 1.0.0 because
 // the scanner now emits CRAP rows for TS/TSX paths that the previous
@@ -393,6 +396,7 @@ export async function scanAndScore({
   ignoreGlobs = [],
   preScannedFiles = null,
   incremental = null,
+  serialThreshold = SERIAL_THRESHOLD,
 }) {
   if (!Array.isArray(targetDirs)) {
     throw new TypeError('scanAndScore: targetDirs must be an array');
@@ -430,7 +434,7 @@ export async function scanAndScore({
   // Serial below the pool cutover, and ALWAYS in incremental mode: the
   // per-file baseline lookup Maps the join needs do not cross the worker
   // boundary (Story #4981).
-  const runSerial = queue.length < SERIAL_THRESHOLD || Boolean(incremental);
+  const runSerial = queue.length < serialThreshold || Boolean(incremental);
   const perFile = runSerial
     ? queue.map((item) => ({ item, result: scoreFileSerial(item, coverage) }))
     : await scoreFilesViaPool(queue, coverage);

package/.agents/scripts/lib/cyclomatic-ceiling.js

@@ -30,8 +30,9 @@
  */
 
 import path from 'node:path';
+import { selectFilesToScore } from './cyclomatic-scope.js';
 import { calculateReportForFile } from './maintainability-engine.js';
-import { isIgnoredByGlobs, scanDirectory } from './maintainability-utils.js';
+import { scanDirectory } from './maintainability-utils.js';
 
 /** Default location of the committed breach baseline. */
 export const DEFAULT_CYCLOMATIC_BASELINE = 'baselines/cyclomatic.json';
@@ -96,20 +97,37 @@ function breachRowFor(file, methods, ceiling) {
  * `scoreFile` is a seam so tests can drive the reduction without the kernel;
  * production callers omit it.
  *
+ * **Scoped scoring (Story #5109).** The directory walk is cheap — a few
+ * `readdir` calls — but scoring is an escomplex parse per file, and re-parsing
+ * the whole tree on every CI run cost 0.94 s to re-derive rows that could not
+ * have moved. `scopeFiles`, when supplied, is the set of repo-relative POSIX
+ * paths that are still *scored*; everything else is walked, counted, and
+ * skipped. That is sound precisely because this gate is a ratchet: a verdict
+ * exists only for a file that either changed (so it must be re-scored) or is
+ * already recorded in the baseline (so its recorded count must be re-derived
+ * to detect an improvement or a removal). A file that is neither cannot
+ * produce `added` or `worsened`, and `removed` is computed from baseline files
+ * — all of which are in scope by construction. `scannedFiles` therefore keeps
+ * reporting the **whole walk**, so the reported scan surface does not shrink
+ * just because the scoring did. Callers pass `null` (the default) for the
+ * whole-tree scan, which `--update` and `BASELINE_SCOPE=full` always do.
+ *
  * @param {{
  *   targetDirs: string[],
  *   ignoreGlobs?: string[],
  *   ceiling: number,
  *   cwd?: string,
+ *   scopeFiles?: Set<string> | null,
  *   scoreFile?: (absPath: string) => { methods?: Array<{ cyclomatic?: number }>, parseError?: boolean },
  * }} args
- * @returns {{ rows: Array<object>, scannedFiles: number, parseErrors: number }}
+ * @returns {{ rows: Array<object>, scannedFiles: number, scoredFiles: number, parseErrors: number }}
  */
 export function scanCyclomatic({
   targetDirs,
   ignoreGlobs = [],
   ceiling,
   cwd = process.cwd(),
+  scopeFiles = null,
   scoreFile = calculateReportForFile,
 }) {
   const files = [];
@@ -118,21 +136,25 @@ export function scanCyclomatic({
     scanDirectory(abs, files, { cwd, ignoreGlobs });
   }
   files.sort();
+  const selected = selectFilesToScore(files, { cwd, ignoreGlobs, scopeFiles });
   const rows = [];
   let parseErrors = 0;
-  for (const abs of files) {
-    if (isIgnoredByGlobs(abs, ignoreGlobs, cwd)) continue;
+  for (const { abs, rel } of selected) {
     const report = scoreFile(abs);
     if (!report || report.parseError) {
       parseErrors += 1;
       continue;
     }
-    const rel = path.relative(cwd, abs).split(path.sep).join('/');
     const row = breachRowFor(rel, report.methods, ceiling);
     if (row) rows.push(row);
   }
   rows.sort((a, b) => a.file.localeCompare(b.file));
-  return { rows, scannedFiles: files.length, parseErrors };
+  return {
+    rows,
+    scannedFiles: files.length,
+    scoredFiles: selected.length,
+    parseErrors,
+  };
 }
 
 /**

package/.agents/scripts/lib/cyclomatic-scope.js

@@ -0,0 +1,144 @@
+/**
+ * cyclomatic-scope.js — which files the cyclomatic ratchet still has to score
+ * (Story #5109).
+ *
+ * `check-cyclomatic.js` re-parsed the whole tree on every run — 0.94 s of
+ * escomplex work to re-derive rows that could not have moved. The scan surface
+ * is unchanged; only the *scoring* is narrowed, and it is narrowed to exactly
+ * the two sets a ratchet verdict can come from:
+ *
+ *   - **every file already recorded in the baseline**, because `improved`,
+ *     `worsened` and `removed` are all computed by re-deriving a recorded
+ *     file's current count;
+ *   - **everything this branch changed** against `project.baseBranch`,
+ *     including the staged, unstaged and untracked working tree, because
+ *     `added` is what a change introduces — and a pre-push gate that only
+ *     looked at committed work would wave through the breach an operator is
+ *     about to commit.
+ *
+ * A file in neither set is unchanged and unrecorded: it cannot produce a
+ * verdict in any bucket.
+ *
+ * @module lib/cyclomatic-scope
+ */
+
+import path from 'node:path';
+import { createGitInterface } from './git-utils.js';
+import { isIgnoredByGlobs } from './maintainability-utils.js';
+
+/**
+ * Git probes whose union is "everything this working copy has touched".
+ *
+ * Three, not four: `git diff --name-only HEAD` already reports the staged
+ * *and* unstaged deltas, so a separate `--cached` pass would only re-list
+ * paths this one has, at the cost of another process spawn.
+ *
+ * @type {ReadonlyArray<ReadonlyArray<string>>}
+ */
+const CHANGE_PROBES = Object.freeze([
+  Object.freeze(['diff', '--name-only', '__BASE__...HEAD']),
+  Object.freeze(['diff', '--name-only', 'HEAD']),
+  Object.freeze(['ls-files', '--others', '--exclude-standard']),
+]);
+
+/**
+ * Resolve the set of repo-relative POSIX paths the ratchet still needs to
+ * score, or `null` when it must scan the whole tree.
+ *
+ * **Fails open, never closed.** Any git failure — a shallow clone, a missing
+ * base ref, a fixture directory that is not a repository at all — returns
+ * `null`, and the caller scans everything. Narrowing on an unreadable scope
+ * is how a ratchet silently stops ratcheting; paying for a whole-tree scan is
+ * not.
+ *
+ * @param {{
+ *   cwd: string,
+ *   baseRef: string,
+ *   baselineRows?: Array<{ file?: string }>,
+ *   git?: ReturnType<typeof createGitInterface>,
+ * }} args
+ * Module-private: `resolveScanScope` below is the only caller, and it is the
+ * one the CLI actually asks. Exporting both would ship a seam whose only
+ * importer is a test, which the `--production` dead-export pass discounts.
+ *
+ * @returns {Set<string> | null}
+ */
+function resolveCyclomaticScope({ cwd, baseRef, baselineRows = [], git }) {
+  const gitIface = git ?? createGitInterface({});
+  const scope = new Set();
+  for (const row of baselineRows) {
+    if (typeof row?.file === 'string' && row.file) scope.add(row.file);
+  }
+  for (const probe of CHANGE_PROBES) {
+    const argv = probe.map((arg) =>
+      arg === '__BASE__...HEAD' ? `${baseRef}...HEAD` : arg,
+    );
+    const res = gitIface.gitSpawn(cwd, ...argv);
+    if (res?.status !== 0) return null;
+    for (const line of String(res.stdout ?? '').split('\n')) {
+      const file = line.trim().replace(/\\/g, '/');
+      if (file) scope.add(file);
+    }
+  }
+  return scope;
+}
+
+/**
+ * Decide the scan scope for one `check-cyclomatic` invocation.
+ *
+ * `--update` rewrites the baseline from the current tree, and
+ * `BASELINE_SCOPE=full` is the operator's explicit "re-derive everything" —
+ * both must see the whole tree, so both return `null`.
+ *
+ * @param {{
+ *   cwd: string,
+ *   config?: { project?: { baseBranch?: string } } | null,
+ *   update?: boolean,
+ *   env?: NodeJS.ProcessEnv,
+ *   baselineRows?: Array<{ file?: string }>,
+ *   git?: ReturnType<typeof createGitInterface>,
+ * }} args
+ * @returns {Set<string> | null} `null` means "scan everything".
+ */
+export function resolveScanScope({
+  cwd,
+  config = null,
+  update = false,
+  env = process.env,
+  baselineRows = [],
+  git,
+}) {
+  if (update || env?.BASELINE_SCOPE === 'full') return null;
+  return resolveCyclomaticScope({
+    cwd,
+    baseRef: config?.project?.baseBranch ?? 'main',
+    baselineRows,
+    git,
+  });
+}
+
+/**
+ * Reduce a walked file list to the `{ abs, rel }` pairs that will actually be
+ * scored, applying the gate's `ignoreGlobs` and then the diff scope.
+ *
+ * Kept here rather than inside `scanCyclomatic` so "which files count" lives
+ * in one module: the ignore rule and the scope rule are the same decision
+ * asked twice, and splitting them across two files is how they drift.
+ *
+ * @param {string[]} files Absolute paths, as walked.
+ * @param {{ cwd: string, ignoreGlobs?: string[], scopeFiles?: Set<string> | null }} args
+ * @returns {Array<{ abs: string, rel: string }>}
+ */
+export function selectFilesToScore(
+  files,
+  { cwd, ignoreGlobs = [], scopeFiles = null },
+) {
+  const selected = [];
+  for (const abs of files) {
+    if (isIgnoredByGlobs(abs, ignoreGlobs, cwd)) continue;
+    const rel = path.relative(cwd, abs).split(path.sep).join('/');
+    if (scopeFiles && !scopeFiles.has(rel)) continue;
+    selected.push({ abs, rel });
+  }
+  return selected;
+}