mandrel 2.36.0 → 2.37.0

package/.agents/docs/configuration.md

@@ -683,6 +683,31 @@ Claude Code web environment-variables UI for web sessions.
 | `NOTIFICATION_WEBHOOK_URL` | No        | POST target for in-band Notifier events (Make.com / Slack / Discord). Unset disables the webhook channel; `log` and `epic-comment` channels still fire. |
 | `WEBHOOK_SECRET`           | No        | Shared secret used to sign outbound webhook payloads as `X-Signature-256: sha256=<hmac>`. Unset ships unsigned payloads.                                 |
 | `MANDREL_ALLOW_TEST_WEBHOOKS` | No     | Set to `1` to keep `NOTIFICATION_WEBHOOK_URL` live inside `npm test` / `npm run test:profile`. Default behaviour scrubs the env var from the test child so no URL resolves and the webhook never fires (see below). |
+| `MANDREL_POOL_CONCURRENCY` | No | Upper bound on the width of every `runOnPool` worker pool in the process (the MI and CRAP scan pools). Precedence is: a caller's explicit `concurrency` → this variable → a clamp of 4 under `node:test` → `os.availableParallelism()`. Set it on a constrained or shared runner where one pool per core oversubscribes the host; a non-numeric value is ignored rather than collapsing the pool. |
+| `MANDREL_AGENTRC_VALIDATOR` | No | Set to `dynamic` to compile the `.agentrc.json` AJV validator at runtime instead of loading the committed precompiled one (see below). Costs ~35 ms per process; the escape hatch exists for a hand-edited schema or a host where the generated module will not load. |
+
+### The `.agentrc` validator is precompiled
+
+`getAgentrcValidator()` returns AJV's **standalone emit** for
+`AGENTRC_SCHEMA`, committed at
+[`.agents/scripts/lib/generated/agentrc-validator.js`](../scripts/lib/generated/agentrc-validator.js).
+Compiling that schema costs ~35 ms, and 36 of the framework's entry scripts
+resolve configuration, so the compile was being paid over and over to
+re-derive a function from a literal that is already in the repository.
+
+The artifact is generated — never hand-edited — by
+[`check-generated-validator.js`](../scripts/check-generated-validator.js):
+
+```bash
+npm run validator:gen     # rewrite it after a deliberate schema change
+npm run validator:check   # fail when it is stale (also run by `npm run lint`)
+```
+
+`npm run lint` runs the `--check` mode, so a schema edit that skips
+regeneration is refused rather than shipping a validator that accepts the
+wrong config. Validation behaviour is unchanged in either mode: the generated
+code is AJV's own, emitted with the same `allErrors: true` option the dynamic
+path uses, and returns the same verdict and the same `errors` array.
 
 ### Test-mode webhook isolation
 

package/.agents/rules/testing-standards.md

@@ -79,6 +79,13 @@ of the pyramid.
 - **Location.** `tests/features/**/*.feature` with step definitions in
   `tests/steps/**` (or the project's equivalent). The companion skill is
   [`stack/qa/playwright-bdd`](../skills/stack/qa/playwright-bdd/SKILL.md).
+- **Run tier.** This tier MUST NOT ride inside the default suite. It is slow
+  by construction — real installs, real browsers, real stacks — and the
+  default suite is what a pre-push hook and every local iteration pay for.
+  Give it its own runner tier and its own CI job, so its cost is charged to
+  the surface whose signal it is. In this repository that is `tests/e2e/**`,
+  the `e2e` tier (`npm run test:e2e`), and the per-PR `e2e` job; the coverage
+  run still measures those files, so nothing leaves the measured surface.
 
 ## Assertion Placement Rule {#assertion-placement}
 
@@ -236,3 +243,52 @@ Hypothesis keeps a failure DB, proptest writes `proptest-regressions/` — pin o
 commit whichever the stack provides. Once shrinking surfaces a minimal
 counterexample, **add it as an example-based regression test** alongside the
 property: the property guards the domain, the pinned example guards the bug.
+
+## The suite's child-process budget
+
+`npm test` forks one process per test file, and the spawns those leaves make
+dominate the suite's system time. Two instruments and one rule keep that
+budget visible and honest (Story #5121).
+
+### Measure it with `npm run test:census`
+
+```bash
+npm run test:census            # writes temp/census.json
+```
+
+`tests/fixtures/spawn-census.cjs` is a `--require` preload that counts every
+`child_process` call per binary, aggregates across all ~700 processes, and
+reports `nodeInSuite` (node children spawned *by test files*, excluding the
+runner's own fan-out), `git`, `gh`, `npm`, and any standalone
+`git config user.*` spawns. Read the numbers from the census rather than
+re-deriving them; two audits hand-rolled this measurement and lost it both
+times with the gitignored temp tree.
+
+The script interpolates `$PWD` deliberately. A **relative** `--require` path is
+inherited by children that run with a different `cwd`, where it fails to
+resolve and kills the child before it runs a line — measured as 15 spurious
+failures in one file.
+
+### Build a fixture repo once, then copy it
+
+A multi-commit fixture repo rebuilt in `beforeEach` is the costly shape. Build
+it once in `before()` and hand each test an `fs` copy via
+`copyGitRepo(pristine)` from `tests/fixtures/git-fixture.js`: each test still
+gets a private directory it may freely mutate, for **no subprocess at all**.
+One file went from 92 `git` spawns to 27 this way.
+
+`copyGitRepo` is safe only for a locally-`git init`ed repo, whose
+`.git/config` holds no absolute paths. Do **not** copy a **clone** (its
+`remote.origin.url` is absolute, so the copy would fetch from the original) or a
+linked worktree (its `gitdir:` / `commondir` pointers would dangle).
+
+### Never trade coverage for a spawn count
+
+Most of the suite's remaining `git` spawns are integration tests exercising
+real git against git-manipulating production code — the spawn **is** the
+subject under test, and so is a CLI's exit code in an exit-code contract test.
+Those are not fixture waste and must not be converted to in-process calls or
+mocks to make a number smaller. Hoist shared setup; leave the assertions alone.
+A spawn census also records argv, not what the binary resolved to: a
+`gh pr view 4890` line may well be a fake `gh` the test put on `PATH`, so
+verify resolution before calling a spawn a network call.

package/.agents/scripts/boot-sweep.js

@@ -45,6 +45,7 @@ import { PROJECT_ROOT, resolveConfig } from './lib/config-resolver.js';
 import { Logger } from './lib/Logger.js';
 import { createProvider } from './lib/provider-factory.js';
 import { buildProtectionCtx } from './lib/single-story-sweep/protection-ctx.js';
+import { resolveSweepLockPath } from './lib/single-story-sweep/sweep-lock.js';
 import { sweepMergedBranches } from './lib/single-story-sweep.js';
 import { sweepTempRetention } from './lib/temp-retention.js';
 
@@ -141,8 +142,13 @@ export async function runBootSweep({
       excludeGlobs.push(current);
     }
 
+    // Story #5112 — one critical section, one lock. `single-story-init.js`
+    // reaps the same merged `story-*` branches through the same engine; when
+    // the two surfaces held differently named lockfiles they could run
+    // concurrently, each deleting branches the other had already planned.
+    // Both now resolve the path through `resolveSweepLockPath`.
     const tempRoot = config?.project?.paths?.tempRoot ?? 'temp';
-    const lockPath = path.resolve(root, tempRoot, 'boot-sweep.lock');
+    const lockPath = resolveSweepLockPath({ cwd: root, tempRoot });
     const lockTimeoutMs =
       config.delivery?.worktreeIsolation?.sweepLockMs ?? 60_000;
 

package/.agents/scripts/check-context-budget.js

@@ -481,6 +481,179 @@ export function renderReachable(tierMap, baseline) {
  * @returns {Promise<number>} 0 = clean / within tolerance / shrink-only / no-op;
  *   1 = a gated tier grew beyond tolerance
  */
+/**
+ * Write a fresh budget, preserving the recorded tolerance so `--update` never
+ * silently widens the gate it is refreshing.
+ *
+ * @param {object} params
+ * @returns {0}
+ */
+function writeUpdatedBaseline({ tierMap, resolvedBaselinePath, json, stdout }) {
+  const existing = loadBaseline(resolvedBaselinePath);
+  const tolerance = Number.isFinite(existing?.toleranceBytes)
+    ? existing.toleranceBytes
+    : DEFAULT_TOLERANCE_BYTES;
+  const envelope = buildBaseline(tierMap, tolerance);
+  fs.mkdirSync(path.dirname(resolvedBaselinePath), { recursive: true });
+  fs.writeFileSync(
+    resolvedBaselinePath,
+    `${JSON.stringify(envelope, null, 2)}\n`,
+  );
+  if (!json) {
+    stdout.write(
+      `[context-budget] wrote baseline ${resolvedBaselinePath} (tolerance ${tolerance} bytes)\n`,
+    );
+  } else {
+    stdout.write(
+      `${JSON.stringify({ kind: 'context-budget-update', baselinePath: resolvedBaselinePath, envelope }, null, 2)}\n`,
+    );
+  }
+  return 0;
+}
+
+/**
+ * An absent budget is a no-op, not a failure: a consumer that has never
+ * recorded one has nothing to regress against.
+ *
+ * @param {object} params
+ * @returns {0}
+ */
+function reportMissingBaseline({
+  tierMap,
+  resolvedBaselinePath,
+  json,
+  stdout,
+  stderr,
+}) {
+  if (json) {
+    stdout.write(
+      `${JSON.stringify({ kind: 'context-budget-report', baselinePath: resolvedBaselinePath, tiers: tierMap.tiers, grown: [], shrunk: [], absent: [], skipped: GATED_TIERS, exitCode: 0, noBaseline: true }, null, 2)}\n`,
+    );
+  } else {
+    stderr.write(
+      `[context-budget] ⚠ budget not found at ${resolvedBaselinePath} — skipping (no-op)\n`,
+    );
+  }
+  return 0;
+}
+
+/**
+ * Score the tree against the recorded budget. Pure — every verdict the two
+ * renderers below present is decided here, so they cannot disagree about what
+ * failed or drift apart in which fields they surface.
+ *
+ * @param {{ tierMap: object, baseline: object }} params
+ * @returns {{ diff: object, ceiling: number, bootOverflow: object[], bootDrift: object[], permissiveDrift: object[], exitCode: 0 | 1 }}
+ */
+function evaluateBudget({ tierMap, baseline }) {
+  const diff = diffBudget(tierMap, baseline);
+  const ceiling = Number.isFinite(baseline?.agentBoot?.ceilingBytes)
+    ? baseline.agentBoot.ceilingBytes
+    : AGENT_BOOT_CEILING_BYTES;
+  const bootOverflow = agentBootOverflow(tierMap, ceiling);
+  const bootDrift = agentBootDrift(tierMap, baseline, ceiling);
+  const permissiveDrift = bootDrift.filter((d) => d.direction === 'permissive');
+  const exitCode =
+    budgetFailureCount(diff) > 0 ||
+    bootOverflow.length > 0 ||
+    permissiveDrift.length > 0
+      ? 1
+      : 0;
+  return { diff, ceiling, bootOverflow, bootDrift, permissiveDrift, exitCode };
+}
+
+/**
+ * @param {object} params
+ * @returns {void}
+ */
+function renderJsonReport({
+  tierMap,
+  baseline,
+  resolvedBaselinePath,
+  report,
+  stdout,
+}) {
+  const { diff, ceiling, bootOverflow, bootDrift, exitCode } = report;
+  const envelope = {
+    kind: 'context-budget-report',
+    baselinePath: resolvedBaselinePath,
+    toleranceBytes: Number.isFinite(baseline.toleranceBytes)
+      ? baseline.toleranceBytes
+      : 0,
+    current: Object.fromEntries(
+      GATED_TIERS.map((t) => [t, tierTotalBytes(tierMap.tiers[t] ?? [])]),
+    ),
+    grown: diff.grown,
+    shrunk: diff.shrunk,
+    absent: diff.absent,
+    skipped: diff.skipped,
+    agentBootCeilingBytes: ceiling,
+    agentBootOverflow: bootOverflow,
+    agentBootDrift: bootDrift,
+    workflowReachableBytes: tierMap.workflowClosure?.reachableTotalBytes ?? 0,
+    exitCode,
+  };
+  stdout.write(`${JSON.stringify(envelope, null, 2)}\n`);
+}
+
+/**
+ * Each failing condition gets its own remediation line: they are fixed
+ * differently (trim a role def vs refresh the budget), so a single generic
+ * message would leave the author guessing which applies.
+ *
+ * @param {object} params
+ * @returns {void}
+ */
+function renderFailureDiagnostics({ report, stderr }) {
+  const { diff, ceiling, bootOverflow, permissiveDrift } = report;
+  if (permissiveDrift.length > 0) {
+    stderr.write(
+      `[context-budget] ❌ a recorded agentBoot row understates the file it describes, so it overstates the headroom an author would size an edit against — refresh it with \`node .agents/scripts/check-context-budget.js --update\` (the ceiling is unchanged)\n`,
+    );
+  }
+  if (bootOverflow.length > 0) {
+    stderr.write(
+      `[context-budget] ❌ a role-agent boot context exceeds the ${ceiling}-byte per-agent ceiling — trim the role def (the ceiling is a hard cap, not a starve target)\n`,
+    );
+  }
+  if (diff.grown.length > 0) {
+    stderr.write(
+      `[context-budget] ❌ a documentation tier grew beyond tolerance — refresh the budget consciously with \`node .agents/scripts/check-context-budget.js --update\` once the growth is intentional\n`,
+    );
+  }
+  if (diff.shrunk.length > 0) {
+    stderr.write(
+      `[context-budget] ❌ a documentation tier came in under its recorded total — the ratchet is holding slack the tree no longer spends, so the next growth would be absorbed silently. Lock the gain in with \`node .agents/scripts/check-context-budget.js --update\`\n`,
+    );
+  }
+  if (diff.absent.length > 0) {
+    stderr.write(
+      `[context-budget] ❌ a recorded row names a path the measured tier no longer contains — its bytes inflate the recorded total against nothing. Refresh with \`node .agents/scripts/check-context-budget.js --update\`\n`,
+    );
+  }
+}
+
+/**
+ * @param {object} params
+ * @returns {void}
+ */
+function renderTextReport({ tierMap, baseline, report, stdout, stderr }) {
+  const { diff, bootOverflow, bootDrift, exitCode } = report;
+  stdout.write(`\n--- context-budget preview ---\n`);
+  stdout.write(`${renderDiff(diff)}\n`);
+  const reachable = renderReachable(tierMap, baseline);
+  if (reachable) stdout.write(`${reachable}\n`);
+  for (const o of bootOverflow) {
+    stdout.write(
+      `+ agentBoot: ${o.path} is ${o.bytes} bytes, over the ${o.ceiling}-byte per-agent ceiling\n`,
+    );
+  }
+  for (const line of renderBootDrift(bootDrift)) {
+    stdout.write(`${line}\n`);
+  }
+  if (exitCode === 1) renderFailureDiagnostics({ report, stderr });
+}
+
 export async function runCli({
   argv = process.argv.slice(2),
   cwd = process.cwd(),
@@ -498,120 +671,39 @@ export async function runCli({
   const tierMap = resolveDocTiers(resolvedConfig, { root });
 
   if (update) {
-    const existing = loadBaseline(resolvedBaselinePath);
-    const tolerance = Number.isFinite(existing?.toleranceBytes)
-      ? existing.toleranceBytes
-      : DEFAULT_TOLERANCE_BYTES;
-    const envelope = buildBaseline(tierMap, tolerance);
-    fs.mkdirSync(path.dirname(resolvedBaselinePath), { recursive: true });
-    fs.writeFileSync(
+    return writeUpdatedBaseline({
+      tierMap,
       resolvedBaselinePath,
-      `${JSON.stringify(envelope, null, 2)}\n`,
-    );
-    if (!json) {
-      stdout.write(
-        `[context-budget] wrote baseline ${resolvedBaselinePath} (tolerance ${tolerance} bytes)\n`,
-      );
-    } else {
-      stdout.write(
-        `${JSON.stringify({ kind: 'context-budget-update', baselinePath: resolvedBaselinePath, envelope }, null, 2)}\n`,
-      );
-    }
-    return 0;
+      json,
+      stdout,
+    });
   }
 
   const baseline = loadBaseline(resolvedBaselinePath);
   if (!baseline) {
-    if (json) {
-      stdout.write(
-        `${JSON.stringify({ kind: 'context-budget-report', baselinePath: resolvedBaselinePath, tiers: tierMap.tiers, grown: [], shrunk: [], absent: [], skipped: GATED_TIERS, exitCode: 0, noBaseline: true }, null, 2)}\n`,
-      );
-    } else {
-      stderr.write(
-        `[context-budget] ⚠ budget not found at ${resolvedBaselinePath} — skipping (no-op)\n`,
-      );
-    }
-    return 0;
+    return reportMissingBaseline({
+      tierMap,
+      resolvedBaselinePath,
+      json,
+      stdout,
+      stderr,
+    });
   }
 
-  const diff = diffBudget(tierMap, baseline);
-  const ceiling = Number.isFinite(baseline?.agentBoot?.ceilingBytes)
-    ? baseline.agentBoot.ceilingBytes
-    : AGENT_BOOT_CEILING_BYTES;
-  const bootOverflow = agentBootOverflow(tierMap, ceiling);
-  const bootDrift = agentBootDrift(tierMap, baseline, ceiling);
-  const permissiveDrift = bootDrift.filter((d) => d.direction === 'permissive');
-  const exitCode =
-    budgetFailureCount(diff) > 0 ||
-    bootOverflow.length > 0 ||
-    permissiveDrift.length > 0
-      ? 1
-      : 0;
-
+  const report = evaluateBudget({ tierMap, baseline });
   if (json) {
-    const envelope = {
-      kind: 'context-budget-report',
-      baselinePath: resolvedBaselinePath,
-      toleranceBytes: Number.isFinite(baseline.toleranceBytes)
-        ? baseline.toleranceBytes
-        : 0,
-      current: Object.fromEntries(
-        GATED_TIERS.map((t) => [t, tierTotalBytes(tierMap.tiers[t] ?? [])]),
-      ),
-      grown: diff.grown,
-      shrunk: diff.shrunk,
-      absent: diff.absent,
-      skipped: diff.skipped,
-      agentBootCeilingBytes: ceiling,
-      agentBootOverflow: bootOverflow,
-      agentBootDrift: bootDrift,
-      workflowReachableBytes: tierMap.workflowClosure?.reachableTotalBytes ?? 0,
-      exitCode,
-    };
-    stdout.write(`${JSON.stringify(envelope, null, 2)}\n`);
+    renderJsonReport({
+      tierMap,
+      baseline,
+      resolvedBaselinePath,
+      report,
+      stdout,
+    });
   } else {
-    stdout.write(`\n--- context-budget preview ---\n`);
-    stdout.write(`${renderDiff(diff)}\n`);
-    const reachable = renderReachable(tierMap, baseline);
-    if (reachable) stdout.write(`${reachable}\n`);
-    for (const o of bootOverflow) {
-      stdout.write(
-        `+ agentBoot: ${o.path} is ${o.bytes} bytes, over the ${o.ceiling}-byte per-agent ceiling\n`,
-      );
-    }
-    for (const line of renderBootDrift(bootDrift)) {
-      stdout.write(`${line}\n`);
-    }
-    if (exitCode === 1) {
-      if (permissiveDrift.length > 0) {
-        stderr.write(
-          `[context-budget] ❌ a recorded agentBoot row understates the file it describes, so it overstates the headroom an author would size an edit against — refresh it with \`node .agents/scripts/check-context-budget.js --update\` (the ceiling is unchanged)\n`,
-        );
-      }
-      if (bootOverflow.length > 0) {
-        stderr.write(
-          `[context-budget] ❌ a role-agent boot context exceeds the ${ceiling}-byte per-agent ceiling — trim the role def (the ceiling is a hard cap, not a starve target)\n`,
-        );
-      }
-      if (diff.grown.length > 0) {
-        stderr.write(
-          `[context-budget] ❌ a documentation tier grew beyond tolerance — refresh the budget consciously with \`node .agents/scripts/check-context-budget.js --update\` once the growth is intentional\n`,
-        );
-      }
-      if (diff.shrunk.length > 0) {
-        stderr.write(
-          `[context-budget] ❌ a documentation tier came in under its recorded total — the ratchet is holding slack the tree no longer spends, so the next growth would be absorbed silently. Lock the gain in with \`node .agents/scripts/check-context-budget.js --update\`\n`,
-        );
-      }
-      if (diff.absent.length > 0) {
-        stderr.write(
-          `[context-budget] ❌ a recorded row names a path the measured tier no longer contains — its bytes inflate the recorded total against nothing. Refresh with \`node .agents/scripts/check-context-budget.js --update\`\n`,
-        );
-      }
-    }
+    renderTextReport({ tierMap, baseline, report, stdout, stderr });
   }
 
-  return exitCode;
+  return report.exitCode;
 }
 
 async function main() {

package/.agents/scripts/check-cyclomatic.js

@@ -35,6 +35,7 @@ import {
   resolveCyclomaticPolicy,
   scanCyclomatic,
 } from './lib/cyclomatic-ceiling.js';
+import { resolveScanScope } from './lib/cyclomatic-scope.js';
 
 /**
  * Parse `--baseline <path>`, `--json`, and `--update`.
@@ -82,6 +83,86 @@ function loadCyclomaticBaseline(baselinePath) {
   }
 }
 
+/**
+ * `--update`: rewrite the baseline from the current (whole-tree) scan. The
+ * sanctioned motion after a deliberate refactor lands, and the only way the
+ * recorded breach count is allowed to rise.
+ *
+ * @param {{ scan: object, ceiling: number, baselinePath: string, writeFileImpl: Function, stdout: { write: (s: string) => void } }} args
+ * @returns {number} Always 0 — writing a baseline cannot fail the ratchet.
+ */
+function writeUpdatedBaseline({
+  scan,
+  ceiling,
+  baselinePath,
+  writeFileImpl,
+  stdout,
+}) {
+  const envelope = buildCyclomaticEnvelope({ rows: scan.rows, ceiling });
+  writeFileImpl(baselinePath, `${JSON.stringify(envelope, null, 2)}\n`);
+  stdout.write(
+    `[cyclomatic] wrote ${scan.rows.length} breach row(s) at ceiling c=${ceiling} to ${baselinePath}\n`,
+  );
+  return 0;
+}
+
+/**
+ * `--json`: the machine-readable comparison envelope.
+ *
+ * @param {{ policy: object, baseline: object|null, baselineRows: Array<object>, baselinePath: string, scan: object, diff: object, exitCode: number }} args
+ * @returns {string}
+ */
+function renderJsonReport({
+  policy,
+  baseline,
+  baselineRows,
+  baselinePath,
+  scan,
+  diff,
+  exitCode,
+}) {
+  return `${JSON.stringify(
+    {
+      kind: 'cyclomatic-report',
+      ceiling: policy.mustFix,
+      flag: policy.flag,
+      baselinePath,
+      baselineCeiling: baseline?.ceiling ?? null,
+      scannedFiles: scan.scannedFiles,
+      parseErrors: scan.parseErrors,
+      baselineRows,
+      currentRows: scan.rows,
+      ...diff,
+      exitCode,
+    },
+    null,
+    2,
+  )}\n`;
+}
+
+/**
+ * Announce a baseline the comparison cannot fully trust: absent, or recorded
+ * at a ceiling the config no longer uses. Both are warnings rather than
+ * failures — the diff still runs, and staying silent is what would let an
+ * operator read a meaningless verdict as a clean one.
+ *
+ * @param {{ baseline: object|null, mustFix: number, baselinePath: string, stderr: { write: (s: string) => void } }} args
+ * @returns {void}
+ */
+function warnAboutBaseline({ baseline, mustFix, baselinePath, stderr }) {
+  if (!baseline) {
+    stderr.write(
+      `[cyclomatic] ⚠ baseline not found at ${baselinePath} — treating as empty\n`,
+    );
+    return;
+  }
+  if (typeof baseline.ceiling === 'number' && baseline.ceiling !== mustFix) {
+    stderr.write(
+      `[cyclomatic] ⚠ baseline was recorded at ceiling c=${baseline.ceiling} but the configured cyclomaticMustFix is c=${mustFix} — re-run with --update\n`,
+    );
+  }
+}
+
 /**
  * Top-level CLI entry. Exported so tests can drive the whole pipeline through
  * the injected seams below without spawning a process.
@@ -109,75 +190,64 @@ export async function runCli({
   writeFileImpl = (p, data) => fs.writeFileSync(p, data),
 } = {}) {
   const { baselinePath, json, update } = parseArgv(argv);
-  const quality = getQuality(resolveConfigImpl({ cwd }));
+  const config = resolveConfigImpl({ cwd });
+  const quality = getQuality(config);
   const policy = resolveCyclomaticPolicy(quality);
   const resolvedBaselinePath = path.resolve(
     cwd,
     baselinePath ?? DEFAULT_CYCLOMATIC_BASELINE,
   );
 
+  // Read the baseline before scanning: its rows are half the diff scope
+  // (Story #5109). `--update` rewrites the baseline from the whole tree, and
+  // `BASELINE_SCOPE=full` is the operator's explicit "re-derive everything",
+  // so both opt out of scoping entirely.
+  const baseline = loadBaselineImpl(resolvedBaselinePath);
+  const baselineRows = Array.isArray(baseline?.rows) ? baseline.rows : [];
+  const scopeFiles = resolveScanScope({ cwd, config, update, baselineRows });
+
   const scan = scanImpl({
     targetDirs: policy.targetDirs,
     ignoreGlobs: policy.ignoreGlobs,
     ceiling: policy.mustFix,
     cwd,
+    scopeFiles,
   });
 
   if (update) {
-    const envelope = buildCyclomaticEnvelope({
-      rows: scan.rows,
+    return writeUpdatedBaseline({
+      scan,
       ceiling: policy.mustFix,
+      baselinePath: resolvedBaselinePath,
+      writeFileImpl,
+      stdout,
     });
-    writeFileImpl(
-      resolvedBaselinePath,
-      `${JSON.stringify(envelope, null, 2)}\n`,
-    );
-    stdout.write(
-      `[cyclomatic] wrote ${scan.rows.length} breach row(s) at ceiling c=${policy.mustFix} to ${resolvedBaselinePath}\n`,
-    );
-    return 0;
   }
 
-  const baseline = loadBaselineImpl(resolvedBaselinePath);
-  const baselineRows = Array.isArray(baseline?.rows) ? baseline.rows : [];
   const diff = diffCyclomaticRows(baselineRows, scan.rows);
   const exitCode = diff.added.length + diff.worsened.length > 0 ? 1 : 0;
 
   if (json) {
     stdout.write(
-      `${JSON.stringify(
-        {
-          kind: 'cyclomatic-report',
-          ceiling: policy.mustFix,
-          flag: policy.flag,
-          baselinePath: resolvedBaselinePath,
-          baselineCeiling: baseline?.ceiling ?? null,
-          scannedFiles: scan.scannedFiles,
-          parseErrors: scan.parseErrors,
-          baselineRows,
-          currentRows: scan.rows,
-          ...diff,
-          exitCode,
-        },
-        null,
-        2,
-      )}\n`,
+      renderJsonReport({
+        policy,
+        baseline,
+        baselineRows,
+        baselinePath: resolvedBaselinePath,
+        scan,
+        diff,
+        exitCode,
+      }),
     );
     return exitCode;
   }
 
-  if (!baseline) {
-    stderr.write(
-      `[cyclomatic] ⚠ baseline not found at ${resolvedBaselinePath} — treating as empty\n`,
-    );
-  } else if (
-    typeof baseline.ceiling === 'number' &&
-    baseline.ceiling !== policy.mustFix
-  ) {
-    stderr.write(
-      `[cyclomatic] ⚠ baseline was recorded at ceiling c=${baseline.ceiling} but the configured cyclomaticMustFix is c=${policy.mustFix} — re-run with --update\n`,
-    );
-  }
+  warnAboutBaseline({
+    baseline,
+    mustFix: policy.mustFix,
+    baselinePath: resolvedBaselinePath,
+    stderr,
+  });
   stdout.write('\n--- cyclomatic preview ---\n');
   stdout.write(`${renderCyclomaticDiff(diff, policy.mustFix)}\n`);
   return exitCode;