mandrel 2.41.0 → 2.43.0

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

@@ -117,28 +117,74 @@ function isCrapGateEnabled(config) {
  */
 function buildTestGateEntry(coverageCaptureActive) {
   if (coverageCaptureActive) return [];
-  return [{ name: 'test', cmd: 'npm', args: ['test'] }];
+  // Story #5173 — `fullSuiteLock` marks the one gate here that spawns a whole
+  // suite, so `defaultGateRunner` serializes it behind the host lock. It is
+  // set on this entry alone precisely because the two full-suite gates are
+  // mutually exclusive: when `coverage-capture` is registered instead, the
+  // lock is taken one level down, inside `runCapture`.
+  return [{ name: 'test', cmd: 'npm', args: ['test'], fullSuiteLock: true }];
 }
 
 const CHECK_BASELINES_HINT =
   'Unified baselines gate breached. Inspect the JSON report (`node .agents/scripts/check-baselines.js`) to see which kind/component/axis fell below floor; remediate the underlying file(s) or — when the regression is intentional — refresh the relevant baseline through its per-kind update script and commit with a `baseline-refresh:` tagged subject.';
 
+/**
+ * The names the unified baselines gate can register under (Story #5172).
+ *
+ * `single` is the unsplit entry — the historical name, and the fail-closed
+ * fallback used whenever the enabled-kind set cannot be resolved into two
+ * buckets. `independent` and `coverage` are the split pair: the first reads no
+ * coverage artifact and therefore fails alongside `lint` / `format` /
+ * `typecheck` in the parallel partition, the second consumes the artifact
+ * `coverage-capture` writes and therefore stays serial behind it.
+ *
+ * Every name here MUST also be a member of the `gateName` enum in
+ * `.agents/schemas/validation-evidence.schema.json` — the close pipeline keys
+ * per-gate evidence on it. `tests/close-validation-gates-enum.test.js` pins
+ * that ⊆ invariant.
+ */
+export const BASELINES_GATE_NAMES = Object.freeze({
+  single: 'check-baselines',
+  independent: 'check-baselines-independent',
+  coverage: 'check-baselines-coverage',
+});
+
+/**
+ * The baseline kinds whose evaluation reads the coverage artifact written by
+ * the `coverage-capture` gate (`coverage` scores it directly; `crap` divides
+ * complexity by it). They are the only kinds that have to wait for the
+ * capture — every other kind scores the source tree and can run as early as
+ * the cheapest gates do.
+ */
+const COVERAGE_CONSUMING_KINDS = new Set(['coverage', 'crap']);
+
 /**
  * Baseline kinds the resolved config enables for the unified
  * `check-baselines` gate. Mirrors `selectEnabledGates` in the check-baselines
  * pipeline (a kind runs when its `gates.<kind>` block is present and not
  * explicitly disabled) so the registration probe's view of "what will run"
- * matches the gate's own view exactly.
+ * matches the gate's own view exactly — and so the Story #5172 partition is
+ * derived from the pipeline's own view of what runs rather than a hardcoded
+ * kind list that a consumer's config could silently contradict.
+ *
+ * Returns `null` when that view cannot be resolved at all (a config object
+ * whose `delivery.quality` access throws). Callers MUST read `null` as
+ * "unknown" and fall back to the single unsplit gate: a partition that cannot
+ * be computed must never silently drop enforcement.
  *
  * @param {object|undefined|null} config canonical resolved config
- * @returns {string[]}
+ * @returns {string[]|null}
  */
 function enabledBaselineKinds(config) {
-  const gates = getQuality(config)?.gates ?? {};
-  return KNOWN_KINDS.filter((kind) => {
-    const block = gates[kind];
-    return block && typeof block === 'object' && block.enabled !== false;
-  });
+  try {
+    const gates = getQuality(config)?.gates ?? {};
+    return KNOWN_KINDS.filter((kind) => {
+      const block = gates[kind];
+      return block && typeof block === 'object' && block.enabled !== false;
+    });
+  } catch {
+    return null;
+  }
 }
 
 /**
@@ -182,13 +228,22 @@ function toKindSet(presentBaselines) {
  *     (`requireBaselines: true`) but absent; keep the gate registered so it
  *     fails, with a preflight hint naming the fix.
  *
- * @param {{ config?: object, cwd?: string, presentBaselines?: string[]|Set<string> }} opts
- *   `presentBaselines` injects the set of kinds whose baseline artifact
- *   exists (tests), short-circuiting the on-disk probe.
+ * @param {{ config?: object, cwd?: string, enabledKinds?: string[]|null, presentBaselines?: string[]|Set<string> }} opts
+ *   `enabledKinds` is `enabledBaselineKinds(config)` computed once by the
+ *   caller (so the probe and the partition below read the same view).
+ *   A `null` — the unresolvable set — reads as "no enabled kinds", which is
+ *   the fail-closed path: the gate stays registered under its single
+ *   historical name. `presentBaselines` injects the set of kinds whose
+ *   baseline artifact exists (tests), short-circuiting the on-disk probe.
  * @returns {{ register: boolean, reason?: string, hint?: string }}
  */
-function probeBaselinesGate({ config, cwd, presentBaselines } = {}) {
-  const enabled = enabledBaselineKinds(config);
+function probeBaselinesGate({
+  config,
+  cwd,
+  enabledKinds,
+  presentBaselines,
+} = {}) {
+  const enabled = enabledKinds ?? [];
   if (enabled.length === 0) {
     // No enabled baseline kinds → `check-baselines.js` self-skips every kind
     // and exits clean (an empty PASS). There is no deterministic-failure risk
@@ -220,6 +275,66 @@ function probeBaselinesGate({ config, cwd, presentBaselines } = {}) {
   };
 }
 
+/**
+ * Build the `check-baselines` gate entries for this run (Story #5172).
+ *
+ * One registration decision, one `BASELINE_REF` overlay, one remediation
+ * hint — fanned out across however many entries the enabled-kind set splits
+ * into. Keeping the fan-out here is what makes the #3890 (`BASELINE_REF`)
+ * and #4495 (`probeBaselinesGate`) invariants structurally impossible to
+ * apply to one entry and forget on the other.
+ *
+ * Three shapes:
+ *   - decision says skip → no entries at all (#4495's greenfield skip).
+ *   - `kinds` is null (unresolvable) or empty → ONE entry under the single
+ *     historical name with no `--gate` filter, in its historical serial
+ *     position. Fail closed: a partition that cannot be computed must never
+ *     silently drop enforcement, and an empty set means the gate self-skips
+ *     every kind and exits a clean empty PASS exactly as it did pre-split.
+ *   - otherwise → the split pair, each pinned to its own `--gate` list.
+ *     Neither bucket is ever registered with an empty kind set, so a consumer
+ *     running only coverage-consuming kinds gets no parallel entry and one
+ *     running none of them gets no serial entry.
+ *
+ * The independent entry is emitted first so a reader of the gate list sees
+ * the order the runner actually walks; `partitionGates` is what routes it
+ * into the parallel phase, and the coverage entry keeps its declared
+ * position after `coverage-capture`.
+ *
+ * @param {{ decision: { register: boolean, hint?: string }, kinds: string[]|null, env: { BASELINE_REF: string }|null }} args
+ * @returns {Gate[]}
+ */
+function buildBaselinesGateEntries({ decision, kinds, env }) {
+  if (!decision.register) return [];
+  const entry = (name, gateKinds) => ({
+    name,
+    cmd: 'node',
+    args: [
+      '.agents/scripts/check-baselines.js',
+      ...(gateKinds ? ['--gate', gateKinds.join(',')] : []),
+      '--format',
+      'text',
+    ],
+    hint: decision.hint ?? CHECK_BASELINES_HINT,
+    ...(env ? { env } : {}),
+  });
+  if (!Array.isArray(kinds) || kinds.length === 0) {
+    return [entry(BASELINES_GATE_NAMES.single, null)];
+  }
+  const independentKinds = kinds.filter(
+    (k) => !COVERAGE_CONSUMING_KINDS.has(k),
+  );
+  const coverageKinds = kinds.filter((k) => COVERAGE_CONSUMING_KINDS.has(k));
+  return [
+    ...(independentKinds.length > 0
+      ? [entry(BASELINES_GATE_NAMES.independent, independentKinds)]
+      : []),
+    ...(coverageKinds.length > 0
+      ? [entry(BASELINES_GATE_NAMES.coverage, coverageKinds)]
+      : []),
+  ];
+}
+
 /**
  * Build the canonical close-validation gate list.
  *
@@ -308,9 +423,11 @@ export function buildDefaultGates({
       ? buildChangedFileScope(baseBranch)
       : null;
   const baselinesGateEnv = buildBaselinesGateEnv(baseBranch);
+  const baselineKinds = enabledBaselineKinds(config);
   const baselinesDecision = probeBaselinesGate({
     config,
     cwd,
+    enabledKinds: baselineKinds,
     presentBaselines,
   });
   if (!baselinesDecision.register && baselinesDecision.reason) {
@@ -362,17 +479,19 @@ export function buildDefaultGates({
     // gate fails deterministically on first try reading a non-existent
     // `baselines/<kind>.json` (`probeBaselinesGate`). When required-by-config
     // but absent, it stays registered with a preflight hint naming the fix.
-    ...(baselinesDecision.register
-      ? [
-          {
-            name: 'check-baselines',
-            cmd: 'node',
-            args: ['.agents/scripts/check-baselines.js', '--format', 'text'],
-            hint: baselinesDecision.hint ?? CHECK_BASELINES_HINT,
-            ...(baselinesGateEnv ? { env: baselinesGateEnv } : {}),
-          },
-        ]
-      : []),
+    //
+    // Story #5172: the gate registers as up to TWO entries. The kinds that
+    // read no coverage artifact run in the parallel independent partition so
+    // a baseline breach fails beside `lint` / `format` / `typecheck` instead
+    // of minutes later behind `coverage-capture`; the coverage-consuming
+    // kinds keep the serial slot after it. `buildBaselinesGateEntries` owns
+    // that fan-out so both entries inherit ONE registration decision, ONE
+    // `BASELINE_REF` overlay and ONE hint.
+    ...buildBaselinesGateEntries({
+      decision: baselinesDecision,
+      kinds: baselineKinds,
+      env: baselinesGateEnv,
+    }),
   ];
 }
 
@@ -392,7 +511,16 @@ export const DEFAULT_GATES = buildDefaultGates();
  * state, no overlapping ports/sockets). Safe to run concurrently — see
  * `runCloseValidation` for the Promise.all + AbortController plumbing.
  */
-const INDEPENDENT_GATE_NAMES = new Set(['lint', 'format', 'typecheck']);
+const INDEPENDENT_GATE_NAMES = new Set([
+  'lint',
+  'format',
+  'typecheck',
+  // Story #5172 — the coverage-independent half of the baselines gate. It
+  // reads the committed `baselines/<kind>.json` files and scores the source
+  // tree in-process; it writes nothing and shares no port, so it satisfies
+  // the same read-only contract as the three gates above.
+  BASELINES_GATE_NAMES.independent,
+]);
 
 /**
  * Partition a gate list into the parallel-safe set and the order-sensitive

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

@@ -7,6 +7,8 @@
 
 import { spawn } from 'node:child_process';
 
+import { withFullSuiteLockAsync } from '../full-suite-lock.js';
+
 /**
  * Pipe a child stream's output line-by-line through `emit`, prepending
  * `prefix` to each line. Tail bytes without a trailing newline flush on
@@ -141,12 +143,39 @@ function isBiomeNoFilesProcessed(output) {
  * because that exit means every config-included path was already excluded,
  * not that formatting drifted.
  *
+ * When `opts.fullSuiteLock` is set — the standalone `test` gate, the one gate
+ * here that runs a whole suite (Story #5173) — the spawn is serialized behind
+ * the host-level advisory lock so two concurrent closes on one checkout do not
+ * run two suites against the same cores. Best-effort: a wait that expires
+ * spawns anyway. The async wrapper is used rather than the synchronous one
+ * precisely because this runner drives sibling gates on the same event loop,
+ * which a blocking wait would stall.
+ *
  * @param {string} cmd
  * @param {string[]} args
- * @param {{ cwd: string, signal?: AbortSignal, gateName?: string, log?: (m: string) => void, env?: Record<string, string>, tolerateNoFilesProcessed?: boolean }} opts
+ * @param {{ cwd: string, signal?: AbortSignal, gateName?: string, log?: (m: string) => void, env?: Record<string, string>, tolerateNoFilesProcessed?: boolean, fullSuiteLock?: boolean }} opts
  * @returns {Promise<{ status: number }>}
  */
 export function defaultGateRunner(cmd, args, opts = {}) {
+  if (!opts.fullSuiteLock) return spawnGate(cmd, args, opts);
+  // `log` is passed through as-is: `withFullSuiteLockAsync` supplies its own
+  // no-op default, so a second fallback here would be an untestable branch.
+  return withFullSuiteLockAsync({ cwd: opts.cwd, log: opts.log }, () =>
+    spawnGate(cmd, args, opts),
+  );
+}
+
+/**
+ * The bare gate spawn — child process, prefixed drain, abort wiring, exit-code
+ * normalisation. Split from {@link defaultGateRunner} so the full-suite lock
+ * composes over one named unit.
+ *
+ * @param {string} cmd
+ * @param {string[]} args
+ * @param {Parameters<typeof defaultGateRunner>[2]} opts
+ * @returns {Promise<{ status: number }>}
+ */
+function spawnGate(cmd, args, opts) {
   const { cwd, signal, gateName, log, env, tolerateNoFilesProcessed } = opts;
   const child = spawn(cmd, args, {
     cwd,

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

@@ -226,6 +226,11 @@ export async function runCloseValidation({
       log,
       signal,
       ...(gate.env ? { env: gate.env } : {}),
+      // Story #5173 — forwarded unconditionally (never a conditional spread
+      // like the two below): `defaultGateRunner` already treats a falsy value
+      // as "no lock", so a branch here would only add a decision point to the
+      // hottest function in this file.
+      fullSuiteLock: gate.fullSuiteLock,
       ...(gate.tolerateNoFilesProcessed
         ? { tolerateNoFilesProcessed: true }
         : {}),

package/.agents/scripts/lib/config/gates/crap-incremental-coverage.schema.js

@@ -1,32 +1,53 @@
 /* node:coverage ignore file -- AJV schema declaration (data-as-code) */
 
 /**
- * `delivery.quality.gates.crap.incrementalCoverage` — opt-in incremental
- * coverage-capture + CRAP-join scoping (Story #4981).
+ * `delivery.quality.gates.crap.incrementalCoverage` — the two independent
+ * full-suite economies (Story #4981, split by Story #5173).
  *
  * Split into its own module (rather than an inline property literal on
  * `CRAP_GATE`) so the schema addition lands as a new file, not a same-file
  * expansion of `crap.schema.js` — the file this module's sole export is
  * spread into.
  *
- * Default (key absent) preserves today's full-repo behaviour byte-for-byte.
- * When `enabled: true`, the changed-file set against `baseRef` (default: the
- * gate's own `--ref` / `main`) decides **whether** to capture — no changed
- * file under `crap.targetDirs` means no capture at all — and the CRAP join
- * treats a method in a file the diff did not touch as resolved by its
- * committed baseline row instead of requiring fresh coverage for it. It does
- * not narrow the capture run itself: a capture that does happen is the
- * ordinary full `npm run test:coverage` (Story #5065).
+ * The two switches are deliberately independent because they are not equally
+ * safe:
+ *
+ *   - **`skipWhenUnchanged`** (default `true`) decides *whether* to capture:
+ *     no changed file under `crap.targetDirs` versus `baseRef` means no
+ *     capture at all. It is a pure saving — the gates score exactly what they
+ *     scored before, because nothing they score moved.
+ *   - **`baselineJoin`** (default `false`) loosens gate semantics: the CRAP
+ *     join resolves a method in an untouched file from its committed baseline
+ *     row instead of requiring fresh coverage for it.
+ *
+ * Bundling them under one `enabled` switch is what forced the earlier default
+ * flip to be reverted. `enabled` survives as a deprecated alias that sets
+ * both.
+ *
+ * Neither switch narrows the capture run itself: a capture that does happen is
+ * the ordinary full `npm run test:coverage` (Story #5065).
  */
 export const INCREMENTAL_COVERAGE_SCHEMA = {
   type: 'object',
   description:
-    'Story #4981 — opt-in incremental coverage-capture + CRAP-join scoping. Default (key absent) preserves today’s full-repo behaviour byte-for-byte. When `enabled: true`, the changed-file set against `baseRef` (default: the gate’s own `--ref` / `main`) decides WHETHER to capture — no changed file under `crap.targetDirs` means no capture at all — and the CRAP join treats a method in a file the diff did not touch as resolved by its committed baseline row instead of requiring fresh coverage for it. It does NOT narrow the capture run itself: a capture that does happen is the ordinary full `npm run test:coverage` (Story #5065).',
+    'The two independent full-suite economies (Story #4981, split by Story #5173). `skipWhenUnchanged` (default true) decides WHETHER to capture — no changed file under `crap.targetDirs` versus `baseRef` means no capture at all — and is a pure saving. `baselineJoin` (default false) loosens gate semantics: the CRAP join resolves a method in an untouched file from its committed baseline row instead of requiring fresh coverage for it. Neither narrows the capture run itself: a capture that does happen is the ordinary full `npm run test:coverage` (Story #5065).',
   properties: {
+    skipWhenUnchanged: {
+      type: 'boolean',
+      description:
+        'Skip the capture entirely when no changed file under `crap.targetDirs` versus `baseRef` was touched. The only measured saving, and gate-semantics-neutral. Defaults to true.',
+      default: true,
+    },
+    baselineJoin: {
+      type: 'boolean',
+      description:
+        'Let the CRAP join resolve a method in a file the diff did not touch from its committed baseline row instead of requiring fresh coverage for it. A gate loosening, not a saving — defaults to false.',
+      default: false,
+    },
     enabled: {
       type: 'boolean',
       description:
-        'Master switch for the capture skip and the baseline-resolved CRAP join.',
+        'DEPRECATED alias for setting both `skipWhenUnchanged` and `baselineJoin`. Prefer the two switches: they are not equally safe, and bundling them is why the earlier default flip was reverted. Either explicit switch overrides this alias.',
     },
     baseRef: {
       type: 'string',

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

@@ -72,22 +72,27 @@ const DEFAULT_MI_FLOORS = Object.freeze({
 });
 
 /**
- * Story #4981 — opt-in incremental coverage-capture + CRAP-join scoping.
- * Disabled by default: `coverage-capture.js` and the CRAP join keep their
- * pre-#4981 full-repo behaviour byte-for-byte until a consumer sets
- * `enabled: true`. `baseRef: null` means "use the caller's own ref
- * resolution" (the gate's `--ref` flag / `main`) rather than a second,
- * possibly-conflicting default.
+ * Story #4981 / #5065 / #5173 — the two independent full-suite economies.
  *
- * Story #5065 — what `enabled: true` actually buys, measured: the capture is
- * **skipped entirely** when no changed file lives under `crap.targetDirs`,
- * and the CRAP join resolves methods in untouched files from the committed
- * baseline row instead of requiring fresh coverage. It does **not** shorten
- * the capture run — when a capture does happen it is the ordinary full
- * `npm run test:coverage`.
+ * `skipWhenUnchanged` decides *whether* to capture: no changed file under
+ * `crap.targetDirs` versus `baseRef` means no capture at all. It is on by
+ * default because it is gate-semantics-neutral — the gates score exactly what
+ * they scored before, since nothing they score moved.
+ *
+ * `baselineJoin` lets the CRAP join resolve a method in an untouched file
+ * from its committed baseline row instead of requiring fresh coverage for it.
+ * That *loosens* the gate, so it stays off by default. Bundling the two under
+ * one `enabled` switch is precisely what forced the earlier default flip to
+ * be reverted (Story #5173).
+ *
+ * Neither switch shortens the capture run — a capture that does happen is the
+ * ordinary full `npm run test:coverage` (Story #5065). `baseRef: null` means
+ * "use the caller's own ref resolution" (the gate's `--ref` flag / `main`)
+ * rather than a second, possibly-conflicting default.
  */
 const DEFAULT_INCREMENTAL_COVERAGE = Object.freeze({
-  enabled: false,
+  skipWhenUnchanged: true,
+  baselineJoin: false,
   baseRef: null,
 });
 
@@ -263,19 +268,29 @@ function resolveResolutionRate(value, fallback) {
 }
 
 /**
- * Resolve `gates.crap.incrementalCoverage` (Story #4981). A malformed or
- * absent user block resolves to the framework default (disabled), so a
- * consumer that never sets the key gets the exact pre-#4981 shape back.
+ * Resolve `gates.crap.incrementalCoverage` (Story #4981, split by #5173).
+ *
+ * Precedence, lowest to highest: the framework defaults
+ * (`skipWhenUnchanged: true`, `baselineJoin: false`), then the deprecated
+ * `enabled` alias which sets **both** switches to its value, then either
+ * explicit switch. A malformed or absent user block resolves to the defaults,
+ * so a consumer that never sets the key inherits the saving without the
+ * loosening.
  *
- * @param {{ enabled?: boolean, baseRef?: string } | undefined} user
- * @param {{ enabled: boolean, baseRef: string | null }} defaults
- * @returns {{ enabled: boolean, baseRef: string | null }}
+ * @param {{ skipWhenUnchanged?: boolean, baselineJoin?: boolean, enabled?: boolean, baseRef?: string } | undefined} user
+ * @param {{ skipWhenUnchanged: boolean, baselineJoin: boolean, baseRef: string | null }} defaults
+ * @returns {{ skipWhenUnchanged: boolean, baselineJoin: boolean, baseRef: string | null }}
  */
 function resolveIncrementalCoverage(user, defaults) {
   if (user == null || typeof user !== 'object') return { ...defaults };
+  const alias = typeof user.enabled === 'boolean' ? user.enabled : null;
+  const pick = (explicit, fallback) => {
+    if (typeof explicit === 'boolean') return explicit;
+    return alias === null ? fallback : alias;
+  };
   return {
-    enabled:
-      typeof user.enabled === 'boolean' ? user.enabled : defaults.enabled,
+    skipWhenUnchanged: pick(user.skipWhenUnchanged, defaults.skipWhenUnchanged),
+    baselineJoin: pick(user.baselineJoin, defaults.baselineJoin),
     baseRef:
       typeof user.baseRef === 'string' && user.baseRef.length > 0
         ? user.baseRef

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

@@ -39,6 +39,12 @@ const EXECUTION_SCHEMA = {
         'Per-command timeout (ms) for the long-running spawns delivery drives — the close-validation chain and the gate CLIs.',
       default: LIMITS_DEFAULTS.executionTimeoutMs,
     },
+    fullSuiteLock: {
+      type: 'boolean',
+      description:
+        'Serialize full-suite spawns (`npm test` / `npm run test:coverage`) behind a host-level advisory lock, so two concurrent deliveries on one checkout do not run two suites against the same cores. Best-effort: a wait that expires spawns anyway, so the lock can never fail a delivery. Set false — or export `MANDREL_FULL_SUITE_LOCK=0` for one invocation — to disable.',
+      default: true,
+    },
   },
   additionalProperties: false,
 };

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

@@ -456,7 +456,7 @@ const GITHUB_SCHEMA = {
 const PLANNING_SCHEMA = {
   type: 'object',
   description:
-    'Inputs to `/mandrel-plan`: risk escalation heuristics, ceremony-lite routing, and the cross-Story conflict-finding severity gates.',
+    'Inputs to `/mandrel-plan`: risk escalation heuristics, ceremony-lite routing, the memory-hygiene advisory thresholds, and the cross-Story conflict-finding severity gates.',
   properties: {
     riskHeuristics: {
       ...LIST_OR_EXTENDER_OF_STRINGS,
@@ -498,6 +498,34 @@ const PLANNING_SCHEMA = {
       },
       additionalProperties: false,
     },
+    // Story #5182 — the `/mandrel-plan` Phase 0 memory-hygiene advisory's two
+    // arms. The count arm this replaced was an absolute ceiling, which no
+    // consolidation pass could ever bring a pool back under; `growthDelta`
+    // measures entries written since the last pass instead, which a pass
+    // does reset. Both are advisory thresholds — nothing here gates a plan.
+    memoryPool: {
+      type: 'object',
+      description:
+        'Thresholds for the memory-hygiene advisory `/mandrel-plan` surfaces at Gate #1. Advisory only: it recommends `/memory-consolidate` and never gates, reroutes, or mutates the memory pool.',
+      properties: {
+        staleAfterDays: {
+          type: 'integer',
+          minimum: 1,
+          description:
+            "Recommend a consolidation pass once the pool's stamp is older than this many days. Default 30.",
+          default: 30,
+        },
+        growthDelta: {
+          type: 'integer',
+          minimum: 1,
+          description:
+            'Recommend a consolidation pass once this many entries have been written since the last one. Measured against the entry count the last pass stamped, so a stamp predating that field leaves growth unmeasured and only the age threshold applies. Default 25.',
+          default: 25,
+        },
+      },
+      additionalProperties: false,
+    },
+
     // Cross-Story conflict-finding severity gates. Off by default so
     // existing repos keep advisory-only behaviour; flipping either to
     // `true` upgrades the matching finding class to `'hard'`, which routes

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

@@ -11,16 +11,22 @@
 import path from 'node:path';
 
 /**
- * Run the incremental capture path when
- * `delivery.quality.gates.crap.incrementalCoverage.enabled` is true.
+ * Run the skip-aware capture path when
+ * `delivery.quality.gates.crap.incrementalCoverage.skipWhenUnchanged` is true
+ * (the default since Story #5173).
  *
  * **This does not shorten the capture run.** The changed-file set decides
  * *whether* to capture, never *what* the capture executes: when nothing under
  * `crap.targetDirs` changed there is no capture at all, and otherwise the
  * ordinary full `npm run test:coverage` runs. The saving that makes the mode
- * worth having is the skip; the other half is the CRAP join, which resolves
- * methods in untouched files from the committed baseline row
- * (`crap-baseline-join.js`) instead of demanding fresh coverage for them.
+ * worth having is the skip.
+ *
+ * Gated by `skipWhenUnchanged` alone (Story #5173). It MUST NOT consult
+ * `baselineJoin`: that switch governs the CRAP join
+ * (`crap-baseline-join.js`), which resolves methods in untouched files from
+ * the committed baseline row instead of demanding fresh coverage for them —
+ * a gate loosening, where the skip is a pure saving. The two are defaulted
+ * differently for exactly that reason, so neither may read the other.
  *
  * Returns the process exit code when incremental mode handled the run
  * (skip, capture, or a capture failure), or `null` when the caller should
@@ -54,7 +60,7 @@ export function tryIncrementalCapture({
   writeCaptureStampImpl,
   logger,
 }) {
-  if (crap.incrementalCoverage?.enabled !== true) return null;
+  if (crap.incrementalCoverage?.skipWhenUnchanged !== true) return null;
 
   const ref = crap.incrementalCoverage.baseRef || args.ref;
   let changed = null;

package/.agents/scripts/lib/crap-baseline-join.js

@@ -176,14 +176,18 @@ export function resolveRawRow(mr, { requireCoverage, coverageAvailable }) {
 }
 
 /**
- * Incremental-mode join (Story #4981): resolve a file's raw method rows
- * against its committed CRAP-baseline rows instead of requiring fresh
- * coverage, for a file the diff did NOT touch.
+ * Baseline-join mode (Story #4981; gated by
+ * `incrementalCoverage.baselineJoin` since Story #5173): resolve a file's raw
+ * method rows against its committed CRAP-baseline rows instead of requiring
+ * fresh coverage, for a file the diff did NOT touch.
  *
- * Rationale: `coverage-capture`'s incremental mode only runs the consumer's
- * test suite scoped to the diff, so an untouched file's coverage entry may
- * legitimately be absent even though nothing about that file's methods
- * changed. Requiring a fresh join for it would either (a) skip-and-count
+ * Rationale: when the capture was skipped because nothing under
+ * `crap.targetDirs` changed, the coverage artifact on disk is whatever the
+ * last run left — so an untouched file's coverage entry may legitimately be
+ * absent even though nothing about that file's methods changed. (The capture
+ * run itself is never narrowed: a capture that *does* happen is the ordinary
+ * full suite — Story #5065.) Requiring a fresh join for it would either
+ * (a) skip-and-count
  * every one of its methods under `requireCoverage: true`, weakening the
  * gate's signal for the vast majority of the tree on every run, or (b) score
  * them at an invented 0% under `requireCoverage: false`, manufacturing a