mandrel 2.28.0 → 2.29.0

package/.agents/docs/configuration.md

@@ -183,6 +183,9 @@ top-level keys are validation errors.
 | `quality.gates.crap.refreshTag` | No | `string` | — | — |
 | `quality.gates.crap.refreshTimeoutMs` | No | `integer` | — | Bounded timeout (ms) for `npm run crap:update` spawned by the baseline-attribution refresh path. Mirrors `coverage.timeoutMs`: a SIGKILL fired at the budget boundary maps to exit 124 so the close orchestrator can flip the Story to `agent::blocked`. Default 60000 (Story #2165). |
 | `quality.gates.crap.ignoreGlobs` | No | `array<string>` | — | Minimatch glob patterns matched against the canonicalised repo-relative path of each discovered file. Files matching any pattern are excluded from CRAP discovery before scoring. Orthogonal to `components` (grouping) — a file excluded here never appears in any component bucket. Absent or empty preserves the existing IGNORED_DIRS-only behaviour (Story #3217). |
+| `quality.gates.crap.incrementalCoverage` | No | `object` | — | 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`, `coverage-capture.js` scopes `npm run test:coverage` to the files changed against `baseRef` (default: the gate's own `--ref` / `main`), 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. |
+| `quality.gates.crap.incrementalCoverage.enabled` | No | `boolean` | — | — |
+| `quality.gates.crap.incrementalCoverage.baseRef` | No | `string` | — | — |
 | `quality.gates.maintainability` | No | `object` | — | Nested configuration block. |
 | `quality.gates.maintainability.enabled` | No | `boolean` | — | — |
 | `quality.gates.maintainability.baselinePath` | No | `string` | — | — |

package/.agents/schemas/agentrc.schema.json

@@ -820,6 +820,20 @@
             "minLength": 1
           },
           "description": "Minimatch glob patterns matched against the canonicalised repo-relative path of each discovered file. Files matching any pattern are excluded from CRAP discovery before scoring. Orthogonal to `components` (grouping) — a file excluded here never appears in any component bucket. Absent or empty preserves the existing IGNORED_DIRS-only behaviour (Story #3217)."
+        },
+        "incrementalCoverage": {
+          "type": "object",
+          "properties": {
+            "enabled": {
+              "type": "boolean"
+            },
+            "baseRef": {
+              "type": "string",
+              "minLength": 1
+            }
+          },
+          "additionalProperties": false,
+          "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`, `coverage-capture.js` scopes `npm run test:coverage` to the files changed against `baseRef` (default: the gate's own `--ref` / `main`), 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."
         }
       },
       "additionalProperties": false

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

@@ -21,17 +21,18 @@
  *       caller MUST surface this — silently passing here would defeat the
  *       CRAP gate's `requireCoverage: true` policy.
  */
-import path from 'node:path';
 import { getChangedFiles } from './lib/changed-files.js';
 import { isDirectInvocation } from './lib/cli-utils.js';
 import { getQuality, resolveConfig } from './lib/config-resolver.js';
 import {
-  anyChangedUnderTargets,
   computeContentDigest,
+  filterFilesUnderTargets,
   isCoverageFresh,
   runCapture,
   writeCaptureStamp,
 } from './lib/coverage-capture.js';
+import { runFullScopeCapture } from './lib/coverage-capture-fullscope.js';
+import { tryIncrementalCapture } from './lib/coverage-capture-incremental.js';
 
 import { Logger } from './lib/Logger.js';
 import { hasNpmScript, readPackageScripts } from './lib/npm-scripts.js';
@@ -78,6 +79,7 @@ export function parseArgs(argv) {
  *   runCaptureImpl?: typeof runCapture,
  *   computeContentDigestImpl?: typeof computeContentDigest,
  *   writeCaptureStampImpl?: typeof writeCaptureStamp,
+ *   filterFilesUnderTargetsImpl?: typeof filterFilesUnderTargets,
  *   logger?: { info: Function, warn: Function, error: Function },
  * }} [deps]
  * @returns {number} process exit code
@@ -93,6 +95,7 @@ export function runCoverageCapture(argv = process.argv, deps = {}) {
     runCaptureImpl = runCapture,
     computeContentDigestImpl = computeContentDigest,
     writeCaptureStampImpl = writeCaptureStamp,
+    filterFilesUnderTargetsImpl = filterFilesUnderTargets,
     logger = Logger,
   } = deps;
   const args = parseArgs(argv);
@@ -120,69 +123,35 @@ export function runCoverageCapture(argv = process.argv, deps = {}) {
     return 1;
   }
 
-  if (args.skipWhenNoCrapFiles) {
-    let changed;
-    try {
-      changed = getChangedFilesImpl({ ref: args.ref, cwd: args.cwd });
-    } catch (err) {
-      // A bad ref must not silently relax the gate. Fall through to the
-      // freshness check so coverage still gets captured if needed.
-      logger.warn(
-        `[coverage-capture] ⚠ ${err?.message ?? err} — falling back to freshness check.`,
-      );
-      changed = null;
-    }
-    if (changed && !anyChangedUnderTargets(changed, crap.targetDirs)) {
-      logger.info(
-        `[coverage-capture] No changed files under [${crap.targetDirs.join(', ')}] — skipping capture.`,
-      );
-      return 0;
-    }
-  }
-
-  const freshness = isCoverageFreshImpl({
-    coveragePath: crap.coveragePath,
-    targetDirs: crap.targetDirs,
-    cwd: args.cwd,
+  // Story #4981 — incremental mode, opt-in via
+  // `delivery.quality.gates.crap.incrementalCoverage.enabled`. `null` means
+  // "not applicable" (disabled, or a ref-resolution error) — fall through to
+  // the full-scope path below rather than silently skipping capture.
+  const incrementalResult = tryIncrementalCapture({
+    crap,
+    coverage,
+    args,
+    getChangedFilesImpl,
+    filterFilesUnderTargetsImpl,
+    isCoverageFreshImpl,
+    runCaptureImpl,
+    computeContentDigestImpl,
+    writeCaptureStampImpl,
+    logger,
   });
-  if (freshness.fresh) {
-    logger.info(
-      `[coverage-capture] Coverage at ${path.resolve(args.cwd, crap.coveragePath)} is ${freshness.reason} — skipping capture.`,
-    );
-    return 0;
-  }
+  if (incrementalResult !== null) return incrementalResult;
 
-  logger.info(
-    `[coverage-capture] Coverage at ${crap.coveragePath} is ${freshness.reason}; running npm run test:coverage…`,
-  );
-  const code = runCaptureImpl({
-    cwd: args.cwd,
-    timeoutMs: coverage?.timeoutMs,
-    log: (m) => logger.info(m),
+  return runFullScopeCapture({
+    crap,
+    coverage,
+    args,
+    getChangedFilesImpl,
+    isCoverageFreshImpl,
+    runCaptureImpl,
+    computeContentDigestImpl,
+    writeCaptureStampImpl,
+    logger,
   });
-  if (code !== 0) {
-    logger.error(
-      `[coverage-capture] ✖ npm run test:coverage exited ${code}. Fix failing tests or coverage-threshold breaches before re-running the CRAP gate.`,
-    );
-    return code;
-  }
-
-  // Persist the content digest next to the fresh artifact so subsequent
-  // freshness checks are content-aware (mtime churn from branch switches no
-  // longer invalidates). Best-effort — a missing stamp just means the next
-  // check falls back to the mtime heuristic.
-  const digest = computeContentDigestImpl(args.cwd, crap.targetDirs);
-  if (
-    digest &&
-    writeCaptureStampImpl({
-      cwd: args.cwd,
-      coveragePath: crap.coveragePath,
-      digest,
-    })
-  ) {
-    logger.info('[coverage-capture] Wrote content-digest capture stamp.');
-  }
-  return code;
 }
 
 // cli-opt-out: synchronous main returns an exit code that is forwarded via process.exit(code); runAsCli's async-main signature does not preserve the result code.

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

@@ -0,0 +1,41 @@
+/**
+ * crap-preview-incremental.js — resolve `runCrapPreview`'s incremental-join
+ * `scanAndScore` input (Story #4981).
+ *
+ * Split into its own file (rather than added inline to `preview-gates.js`)
+ * so the Story's opt-in wiring lands as new code, not a same-file expansion
+ * of the pre-existing preview runner.
+ */
+import { getChangedFiles } from '../changed-files.js';
+
+/**
+ * Resolve the `incremental` option `scanAndScore` (`crap-utils.js`) expects,
+ * or `null` when incremental mode is disabled or the changed-files ref could
+ * not be resolved — a resolution failure falls back to full-scope rather
+ * than silently relaxing the gate.
+ *
+ * @param {{
+ *   crap: { incrementalCoverage?: { enabled?: boolean, baseRef?: string } },
+ *   diffRef: string | null,
+ *   cwd: string,
+ *   baselineRows: Array<object>,
+ *   getChangedFilesImpl?: typeof getChangedFiles,
+ * }} opts
+ * @returns {{ touchedFiles: Set<string>, baselineRows: Array<object> } | null}
+ */
+export function resolveCrapPreviewIncremental({
+  crap,
+  diffRef,
+  cwd,
+  baselineRows,
+  getChangedFilesImpl = getChangedFiles,
+}) {
+  if (crap.incrementalCoverage?.enabled !== true) return null;
+  const baseRef = crap.incrementalCoverage.baseRef || diffRef || 'main';
+  try {
+    const touchedFiles = new Set(getChangedFilesImpl({ ref: baseRef, cwd }));
+    return { touchedFiles, baselineRows };
+  } catch {
+    return null;
+  }
+}

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

@@ -0,0 +1,135 @@
+/**
+ * crap-preview-scan.js — the scan → compare → report tail of
+ * `preview-gates.js#runCrapPreview`, once its baseline is loaded and judged
+ * compatible.
+ *
+ * Hoisted out of `runCrapPreview` verbatim (Story #4981) so that function's
+ * cyclomatic complexity does not grow with the incremental-mode wiring
+ * alongside it — this is a relocation of pre-existing logic, not new
+ * behaviour; the incremental resolution itself is the only Story #4981
+ * addition (see `resolveCrapPreviewIncremental`).
+ */
+import path from 'node:path';
+import { loadCoverage } from '../coverage-utils.js';
+import {
+  KERNEL_VERSION,
+  resolveEscomplexVersion,
+  scanAndScore,
+} from '../crap-utils.js';
+import { resolveCrapPreviewIncremental } from './crap-preview-incremental.js';
+import { resolveCrapEnvOverrides } from './env-overrides.js';
+import {
+  assessComparisonBasis,
+  buildCrapReport,
+  compareCrap,
+  filterRowsByFileScope,
+  suppressVerdicts,
+} from './kinds/crap.js';
+
+/**
+ * Narrow a CRAP baseline to the rows whose file path is in `scopeSet`,
+ * or return all rows when no diff-scope filter is active.
+ *
+ * @param {{ rows: object[] }} baseline
+ * @param {Set<string>|null|undefined} scopeSet
+ * @returns {object[]}
+ */
+function resolveBaselineRows(baseline, scopeSet) {
+  return scopeSet
+    ? filterRowsByFileScope(baseline.rows, scopeSet)
+    : baseline.rows;
+}
+
+/**
+ * Return true when the CRAP compare result contains regressions or new
+ * violations — i.e. when the preview gate should exit non-zero.
+ *
+ * @param {{ regressions: number, newViolations: number }} result
+ * @returns {boolean}
+ */
+function hasCrapRegressions(result) {
+  return result.regressions > 0 || result.newViolations > 0;
+}
+
+/**
+ * Scan `crap.targetDirs`, compare against the (already compatibility-judged)
+ * baseline, and build the `--json` envelope — the exact pre-#4981 tail of
+ * `runCrapPreview`, now including the Story #4981 incremental-join opt-in.
+ *
+ * @param {{
+ *   crap: object,
+ *   cwd: string,
+ *   scopeSet: Set<string>|null,
+ *   scope: string,
+ *   diffRef: string|null,
+ *   baseline: { rows: object[] },
+ * }} opts
+ * @returns {Promise<{ exitCode: number, envelope: object }>}
+ */
+export async function computeCrapPreviewScan({
+  crap,
+  cwd,
+  scopeSet,
+  scope,
+  diffRef,
+  baseline,
+}) {
+  const targetDirs = Array.isArray(crap.targetDirs) ? crap.targetDirs : [];
+  const crapIgnoreGlobs = Array.isArray(crap.ignoreGlobs)
+    ? crap.ignoreGlobs
+    : [];
+  const requireCoverage = crap.requireCoverage !== false;
+  const coveragePath = crap.coveragePath ?? 'coverage/coverage-final.json';
+  const coverage = loadCoverage(path.resolve(cwd, coveragePath));
+  // Story #4731 (AC-3) — feed the CRAP regression compare the *configured*
+  // crap tolerance (env override → `gates.crap.tolerance` → framework default)
+  // so `compareCrap` demotes positive deltas at or under tolerance rather than
+  // failing on any positive delta; over-tolerance deltas still fail. This keeps
+  // the pre-commit/pre-push preview aligned with the authoritative gate.
+  const { newMethodCeiling, tolerance } = resolveCrapEnvOverrides(
+    crap,
+    process.env,
+  );
+  const incremental = resolveCrapPreviewIncremental({
+    crap,
+    diffRef,
+    cwd,
+    baselineRows: baseline.rows,
+  });
+  const scan = await scanAndScore({
+    targetDirs,
+    coverage,
+    requireCoverage,
+    cwd,
+    scopeFiles: scopeSet,
+    ignoreGlobs: crapIgnoreGlobs,
+    incremental,
+  });
+  const baselineRows = resolveBaselineRows(baseline, scopeSet);
+  const result = compareCrap({
+    currentRows: scan.rows,
+    baselineRows,
+    newMethodCeiling,
+    tolerance,
+  });
+  const envelope = buildCrapReport({
+    compareResult: result,
+    scanSummary: scan,
+    kernelVersion: KERNEL_VERSION,
+    escomplexVersion: resolveEscomplexVersion(),
+    newMethodCeiling,
+    scopeInfo: { scope, diffRef },
+  });
+  // Story #4866 (AC-5): above the drifted-row ratio the basis is self-
+  // evidently unsound and every per-method verdict below it is an artefact of
+  // a mis-keyed join. Say so once, by name, and fail open.
+  const basis = assessComparisonBasis(result);
+  if (!basis.sound) {
+    return {
+      exitCode: 0,
+      envelope: suppressVerdicts(envelope, basis.diagnostic),
+    };
+  }
+  const exitCode = hasCrapRegressions(result) ? 1 : 0;
+  return { exitCode, envelope };
+}

package/.agents/scripts/lib/baselines/kinds/crap.js

@@ -245,6 +245,19 @@ function crapRowKey(row) {
   return `${row.path}::${row.method}@${row.startLine}`;
 }
 
+// `methodIdentityKey` / `indexBaselineRowsByFile` (Story #4981) live in
+// crap-baseline-index.js, not here — `crap-utils.js#scanAndScore` needs them
+// to build the incremental join's per-file baseline lookup, and crap-utils.js
+// already imports `getCrapBaseline` FROM this module. Defining them here and
+// importing them into crap-utils.js would close that edge into a cycle
+// (kinds/crap.js → crap-utils.js → kinds/crap.js). Re-exported here so
+// existing importers of this module keep a single door to the identity key
+// `crapRowKey` composes with the file path.
+export {
+  indexBaselineRowsByFile,
+  methodIdentityKey,
+} from '../../crap-baseline-index.js';
+
 /**
  * Pure stabilizer for s-stability-epsilon (Story #1964). CRAP rows match
  * by the composite `path::method@startLine` identity. Sub-epsilon CRAP

package/.agents/scripts/lib/baselines/preview-gates.js

@@ -21,20 +21,11 @@ import path from 'node:path';
 
 import { resolvePreviewScope } from '../changed-files.js';
 import { getBaselines, getQuality, resolveConfig } from '../config-resolver.js';
-import { loadCoverage } from '../coverage-utils.js';
-import {
-  KERNEL_VERSION,
-  resolveEscomplexVersion,
-  scanAndScore,
-} from '../crap-utils.js';
+import { KERNEL_VERSION, resolveEscomplexVersion } from '../crap-utils.js';
 import { calculateAll, scanDirectory } from '../maintainability-utils.js';
-import { resolveCrapEnvOverrides } from './env-overrides.js';
+import { computeCrapPreviewScan } from './crap-preview-scan.js';
 import {
   assertBaselineCompatible,
-  assessComparisonBasis,
-  buildCrapReport,
-  compareCrap,
-  filterRowsByFileScope,
   INCOMPATIBLE_BASELINE_DIAGNOSTIC,
   loadCrapBaseline,
   suppressVerdicts,
@@ -110,31 +101,6 @@ function compareScores(scores, baseline, tolerance) {
   return { regressions, newFiles, improvements, regressedFiles };
 }
 
-/**
- * Narrow a CRAP baseline to the rows whose file path is in `scopeSet`,
- * or return all rows when no diff-scope filter is active.
- *
- * @param {{ rows: object[] }} baseline
- * @param {Set<string>|null|undefined} scopeSet
- * @returns {object[]}
- */
-function resolveBaselineRows(baseline, scopeSet) {
-  return scopeSet
-    ? filterRowsByFileScope(baseline.rows, scopeSet)
-    : baseline.rows;
-}
-
-/**
- * Return true when the CRAP compare result contains regressions or new
- * violations — i.e. when the preview gate should exit non-zero.
- *
- * @param {{ regressions: number, newViolations: number }} result
- * @returns {boolean}
- */
-function hasCrapRegressions(result) {
-  return result.regressions > 0 || result.newViolations > 0;
-}
-
 /**
  * Build the zero-row CRAP envelope the preview returns when it has nothing to
  * compare against — no baseline, or the gate disabled.
@@ -289,58 +255,12 @@ export async function runCrapPreview({
     };
   }
 
-  const targetDirs = Array.isArray(crap.targetDirs) ? crap.targetDirs : [];
-  const crapIgnoreGlobs = Array.isArray(crap.ignoreGlobs)
-    ? crap.ignoreGlobs
-    : [];
-  const requireCoverage = crap.requireCoverage !== false;
-  const coveragePath = crap.coveragePath ?? 'coverage/coverage-final.json';
-  const coverage = loadCoverage(path.resolve(cwd, coveragePath));
-  // Story #4731 (AC-3) — feed the CRAP regression compare the *configured*
-  // crap tolerance (env override → `gates.crap.tolerance` → framework default)
-  // so `compareCrap` demotes positive deltas at or under tolerance rather than
-  // failing on any positive delta; over-tolerance deltas still fail. This keeps
-  // the pre-commit/pre-push preview aligned with the authoritative gate.
-  const { newMethodCeiling, tolerance } = resolveCrapEnvOverrides(
+  return computeCrapPreviewScan({
     crap,
-    process.env,
-  );
-  const scan = await scanAndScore({
-    targetDirs,
-    coverage,
-    requireCoverage,
     cwd,
-    scopeFiles: scopeSet,
-    ignoreGlobs: crapIgnoreGlobs,
-  });
-  const baselineRows = resolveBaselineRows(baseline, scopeSet);
-  const result = compareCrap({
-    currentRows: scan.rows,
-    baselineRows,
-    newMethodCeiling,
-    tolerance,
-  });
-  const envelope = buildCrapReport({
-    compareResult: result,
-    scanSummary: scan,
-    kernelVersion: KERNEL_VERSION,
-    escomplexVersion: resolveEscomplexVersion(),
-    newMethodCeiling,
-    scopeInfo: {
-      scope,
-      diffRef,
-    },
+    scopeSet,
+    scope,
+    diffRef,
+    baseline,
   });
-  // Story #4866 (AC-5): above the drifted-row ratio the basis is self-
-  // evidently unsound and every per-method verdict below it is an artefact of
-  // a mis-keyed join. Say so once, by name, and fail open.
-  const basis = assessComparisonBasis(result);
-  if (!basis.sound) {
-    return {
-      exitCode: 0,
-      envelope: suppressVerdicts(envelope, basis.diagnostic),
-    };
-  }
-  const exitCode = hasCrapRegressions(result) ? 1 : 0;
-  return { exitCode, envelope };
 }

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

@@ -0,0 +1,26 @@
+/* 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).
+ *
+ * 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`, `coverage-capture.js` scopes `npm run test:coverage`
+ * to the files changed against `baseRef` (default: the gate's own `--ref` /
+ * `main`), 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.
+ */
+export const INCREMENTAL_COVERAGE_SCHEMA = {
+  type: 'object',
+  properties: {
+    enabled: { type: 'boolean' },
+    baseRef: { type: 'string', minLength: 1 },
+  },
+  additionalProperties: false,
+};

package/.agents/scripts/lib/config/gates/crap.schema.js

@@ -1,5 +1,6 @@
 /* node:coverage ignore file -- AJV schema declaration (data-as-code) */
 
+import { INCREMENTAL_COVERAGE_SCHEMA } from './crap-incremental-coverage.schema.js';
 import {
   GATE_BASE,
   LIST_OR_EXTENDER_OF_STRINGS,
@@ -35,6 +36,7 @@ export const CRAP_GATE = {
     // paths to exclude files from CRAP discovery before scoring. Orthogonal
     // to `components` (grouping). Absent/empty preserves existing behaviour.
     ignoreGlobs: { type: 'array', items: { type: 'string', minLength: 1 } },
+    incrementalCoverage: INCREMENTAL_COVERAGE_SCHEMA,
   },
   additionalProperties: false,
 };

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

@@ -71,6 +71,19 @@ const DEFAULT_MI_FLOORS = Object.freeze({
   '*': Object.freeze({ min: 70 }),
 });
 
+/**
+ * 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.
+ */
+const DEFAULT_INCREMENTAL_COVERAGE = Object.freeze({
+  enabled: false,
+  baseRef: null,
+});
+
 /** Framework defaults for the CRAP gate (post-1737 uniform shape). */
 export const CRAP_GATE_DEFAULTS = Object.freeze({
   enabled: true,
@@ -97,6 +110,7 @@ export const CRAP_GATE_DEFAULTS = Object.freeze({
   // run (a repo with fresh coverage resolves ~98%) and far below the 4–6%
   // signature of a coordinate-system mismatch.
   minMethodResolutionRate: 0.75,
+  incrementalCoverage: DEFAULT_INCREMENTAL_COVERAGE,
 });
 
 /** Framework defaults for the coverage gate. */
@@ -163,6 +177,7 @@ const CRAP_GATE_KEYS = new Set([
   'refreshTimeoutMs',
   'ignoreGlobs',
   'minMethodResolutionRate',
+  'incrementalCoverage',
 ]);
 
 const COVERAGE_GATE_KEYS = new Set([
@@ -240,6 +255,27 @@ function resolveResolutionRate(value, fallback) {
   return value;
 }
 
+/**
+ * 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.
+ *
+ * @param {{ enabled?: boolean, baseRef?: string } | undefined} user
+ * @param {{ enabled: boolean, baseRef: string | null }} defaults
+ * @returns {{ enabled: boolean, baseRef: string | null }}
+ */
+function resolveIncrementalCoverage(user, defaults) {
+  if (user == null || typeof user !== 'object') return { ...defaults };
+  return {
+    enabled:
+      typeof user.enabled === 'boolean' ? user.enabled : defaults.enabled,
+    baseRef:
+      typeof user.baseRef === 'string' && user.baseRef.length > 0
+        ? user.baseRef
+        : defaults.baseRef,
+  };
+}
+
 export function resolveMaintainabilityCrap(
   userCrap,
   gateScoping,
@@ -267,6 +303,7 @@ export function resolveMaintainabilityCrap(
       refreshTag: defaults.refreshTag,
       refreshTimeoutMs: defaults.refreshTimeoutMs,
       ignoreGlobs: [...defaults.ignoreGlobs],
+      incrementalCoverage: { ...defaults.incrementalCoverage },
       defaultScope: scoping.defaultScope,
       diffRef: scoping.diffRef,
     };
@@ -297,6 +334,10 @@ export function resolveMaintainabilityCrap(
     ignoreGlobs: Array.isArray(userCrap.ignoreGlobs)
       ? userCrap.ignoreGlobs.slice()
       : [...defaults.ignoreGlobs],
+    incrementalCoverage: resolveIncrementalCoverage(
+      userCrap.incrementalCoverage,
+      defaults.incrementalCoverage,
+    ),
     defaultScope: scoping.defaultScope,
     diffRef: scoping.diffRef,
   };

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

@@ -443,6 +443,12 @@ export const DELIVERY_SCHEMA = {
     deliverRunner: DELIVER_RUNNER_SCHEMA,
     worktreeIsolation: WORKTREE_ISOLATION_SCHEMA,
     signals: SIGNALS_SCHEMA,
+    // `quality.gates.crap.incrementalCoverage` (Story #4981) is declared in
+    // `config/gates/crap.schema.js` and reaches AJV validation through this
+    // property — QUALITY_SCHEMA → GATES_SCHEMA → CRAP_GATE. No separate
+    // declaration lives here; this is the composition point that makes the
+    // gate-level schema authoritative for the top-level `.agentrc.json`
+    // surface this module validates.
     quality: QUALITY_SCHEMA,
     mergeWatch: MERGE_WATCH_SCHEMA,
     codeReview: CODE_REVIEW_SCHEMA,