mandrel 2.40.0 → 2.42.0

package/.agents/scripts/lib/baselines/crap-preview-incremental.js

@@ -14,8 +14,13 @@ import { getChangedFiles } from '../changed-files.js';
  * not be resolved — a resolution failure falls back to full-scope rather
  * than silently relaxing the gate.
  *
+ * Gated by `incrementalCoverage.baselineJoin` alone (Story #5173). It MUST
+ * NOT consult `skipWhenUnchanged`: the join loosens what the gate demands,
+ * while the skip only decides whether a capture runs, so a consumer that took
+ * the saving has not thereby asked for the loosening.
+ *
  * @param {{
- *   crap: { incrementalCoverage?: { enabled?: boolean, baseRef?: string } },
+ *   crap: { incrementalCoverage?: { baselineJoin?: boolean, baseRef?: string } },
  *   diffRef: string | null,
  *   cwd: string,
  *   baselineRows: Array<object>,
@@ -30,7 +35,7 @@ export function resolveCrapPreviewIncremental({
   baselineRows,
   getChangedFilesImpl = getChangedFiles,
 }) {
-  if (crap.incrementalCoverage?.enabled !== true) return null;
+  if (crap.incrementalCoverage?.baselineJoin !== true) return null;
   const baseRef = crap.incrementalCoverage.baseRef || diffRef || 'main';
   try {
     const touchedFiles = new Set(getChangedFilesImpl({ ref: baseRef, cwd }));

package/.agents/scripts/lib/baselines/git-base.js

@@ -145,6 +145,32 @@ function cleanGitEnv() {
   );
 }
 
+/** Both reads reject the same way on a missing or non-string argument. */
+function isNonEmptyString(value) {
+  return typeof value === 'string' && value.length > 0;
+}
+
+/** Both reads coerce a missing stdout to the empty string rather than throwing. */
+function stdoutOf(result) {
+  return typeof result?.stdout === 'string' ? result.stdout : '';
+}
+
+/**
+ * Run a git subprocess through the shared child surface. Both reads below need
+ * the identical shape — injected runner, resolved cwd, `GIT_*`-scrubbed env,
+ * argv tokens rather than a shell string — so it lives here once.
+ *
+ * @param {string[]} args
+ * @param {{ cwd?: string }} opts
+ */
+function runGit(args, opts) {
+  return spawnChild('git', args, {
+    run: _spawnRunner,
+    cwd: opts.cwd ?? process.cwd(),
+    env: cleanGitEnv(),
+  });
+}
+
 /**
  * Read `<file>` at the given git ref. Returns the file contents as a
  * UTF-8 string when the path exists, or `null` when git reports the
@@ -161,10 +187,10 @@ function cleanGitEnv() {
  * @returns {string | null}
  */
 export function readBaseFromGit(ref, file, opts = {}) {
-  if (typeof ref !== 'string' || ref.length === 0) {
+  if (!isNonEmptyString(ref)) {
     throw new TypeError('readBaseFromGit: ref must be a non-empty string');
   }
-  if (typeof file !== 'string' || file.length === 0) {
+  if (!isNonEmptyString(file)) {
     throw new TypeError('readBaseFromGit: file must be a non-empty string');
   }
 
@@ -176,19 +202,14 @@ export function readBaseFromGit(ref, file, opts = {}) {
     return cached;
   }
 
-  const cwd = opts.cwd ?? process.cwd();
   const spec = `${ref}:${file}`;
-  const result = spawnChild('git', ['show', spec], {
-    run: _spawnRunner,
-    cwd,
-    env: cleanGitEnv(),
-  });
+  const result = runGit(['show', spec], opts);
 
   // `child_process.spawnSync` returns `status: null` when the child died
   // by signal. Treat that as a hard failure rather than "no file".
   const status = result.status;
   if (status === 0) {
-    const out = typeof result.stdout === 'string' ? result.stdout : '';
+    const out = stdoutOf(result);
     touch(key, out);
     return out;
   }
@@ -212,53 +233,68 @@ export function readBaseFromGit(ref, file, opts = {}) {
 }
 
 /**
- * Read the commit subjects, within the range `<baseRef>..HEAD`, of commits
- * that touched `<file>` (Story #4731). Powers the maintainability
+ * Read the commits, within the range `<baseRef>..HEAD`, that touched `<file>`
+ * (Story #4731; widened to carry SHAs by Story #5179). Powers the baseline
  * refresh-acknowledgment trigger: a `baseline-refresh:`-tagged commit in the
- * compared range that touches the maintainability baseline demotes that run's
+ * compared range that touches a kind's baseline acknowledges that run's
  * head-vs-base regressions.
  *
- * Restricting the log to `-- <file>` means the returned subjects already
- * satisfy the "commit whose diff touches the baseline file" half of the
- * predicate; the caller only has to match the tag substring against each
- * subject. Runs through the same shared `spawnChild` surface and injected
- * runner as `readBaseFromGit`, so it inherits the identical env scrubbing
- * (drop inherited `GIT_*`), the same stdout ceiling, and the spawn-not-exec
- * security posture (argv tokens, `shell: false`).
+ * Story #5179 — this returned SUBJECTS ONLY, and that omission was load-bearing
+ * in the wrong direction. With no commit handle, the acknowledgment could not
+ * ask what the tagged commit actually rewrote, so it could only be a whole-run
+ * blanket: every regression in the range demoted, including rows that commit
+ * never touched and drift that landed after it. Carrying `sha` alongside
+ * `subject` is what lets the caller read the baseline blob AT the refresh
+ * commit and scope the acknowledgment to it.
+ *
+ * Restricting the log to `-- <file>` means the returned commits already satisfy
+ * the "commit whose diff touches the baseline file" half of the predicate; the
+ * caller only has to match the tag substring against each subject. Runs through
+ * the same shared `spawnChild` surface and injected runner as
+ * `readBaseFromGit`, so it inherits the identical env scrubbing (drop inherited
+ * `GIT_*`), the same stdout ceiling, and the spawn-not-exec security posture
+ * (argv tokens, `shell: false`).
+ *
+ * A NUL separator between the two fields is what makes this parse safely: a
+ * commit subject may contain anything except a newline, so any printable
+ * delimiter could appear inside one, but neither field may contain NUL.
  *
- * Returns an empty array whenever the range cannot be walked (missing base
- * ref, git failure, empty range) — the acknowledgment path treats "no
- * matching commit" and "could not determine" identically: the ratchet stays
- * at full strength. Not cached: the range result depends on live HEAD, which
- * the `(ref, file)` LRU key does not capture.
+ * Returns an empty array whenever the range cannot be walked (missing base ref,
+ * git failure, empty range) — the acknowledgment path treats "no matching
+ * commit" and "could not determine" identically: the ratchet stays at full
+ * strength. Not cached: the range result depends on live HEAD, which the
+ * `(ref, file)` LRU key does not capture.
  *
  * @param {string} baseRef - Range base (e.g. `main`, `origin/main`, a SHA).
  * @param {string} file    - Repo-relative path to the baseline file.
  * @param {{ cwd?: string }} [opts]
- * @returns {string[]} commit subjects, newest first; `[]` on any failure.
+ * @returns {{ sha: string, subject: string }[]} newest first; `[]` on any failure.
  */
-export function readRangeSubjectsTouchingFile(baseRef, file, opts = {}) {
-  if (typeof baseRef !== 'string' || baseRef.length === 0) return [];
-  if (typeof file !== 'string' || file.length === 0) return [];
+export function readRangeCommitsTouchingFile(baseRef, file, opts = {}) {
+  if (!isNonEmptyString(baseRef) || !isNonEmptyString(file)) return [];
 
-  const cwd = opts.cwd ?? process.cwd();
   let result;
   try {
-    result = spawnChild(
-      'git',
-      ['log', `${baseRef}..HEAD`, '--format=%s', '--', file],
-      { run: _spawnRunner, cwd, env: cleanGitEnv() },
+    result = runGit(
+      ['log', `${baseRef}..HEAD`, '--format=%H%x00%s', '--', file],
+      opts,
     );
   } catch {
     return [];
   }
 
-  if (!result || result.status !== 0) return [];
-  const out = typeof result.stdout === 'string' ? result.stdout : '';
-  return out
+  if (result?.status !== 0) return [];
+  return stdoutOf(result)
     .split('\n')
-    .map((line) => line.trim())
-    .filter((line) => line.length > 0);
+    .map((line) => {
+      const sep = line.indexOf('\u0000');
+      if (sep === -1) return null;
+      return {
+        sha: line.slice(0, sep).trim(),
+        subject: line.slice(sep + 1).trim(),
+      };
+    })
+    .filter((commit) => commit !== null && commit.sha.length > 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