mandrel 2.27.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/docs/execution-reference.md

@@ -96,18 +96,28 @@ over-ceiling envelope or an over-budget Story count.
 - **`PLAN_CONTEXT_ENVELOPE_BYTE_CEILING`** (`lib/orchestration/plan-context.js`):
   256 KB (≈64K tokens at the ≈4-chars/token estimate) on the serialized
   envelope `buildPlanContext` assembles, checked at the single choke point
-  every mode returns through. A measured seed-mode envelope on this repo is
-  ~120 KB — `docsContext` (~63 KB) and `systemPrompts` (~54 KB) are the whole
-  of it, every other field under 1 KB — so the ceiling carries roughly 2×
-  headroom. Story #4811 retired the codebase snapshot that used to sit
-  alongside them, leaving the operator-supplied seed the only unbounded
-  contributor.
-- **On refusal**, the error names the envelope's largest fields. Trim the seed,
-  or plan fewer `--tickets` source issues in one run. The seed is carried
-  **verbatim** by design — it
-  is the operator's request, and summarizing it silently would degrade planning
-  quality precisely when the input is richest — so there is no elision path to
-  fall back on. Raising the ceiling needs a measured justification.
+  every mode returns through. A measured seed-mode envelope on this repo's
+  thin `.feature` corpus is ~120 KB — `docsContext` (~63 KB) and
+  `systemPrompts` (~54 KB) are the bulk of the fixed floor, every other field
+  under 1 KB. That is **not** representative of every consumer: Story #4977
+  measured `bddScenarios` at 118 KB on a consumer with a mature Gherkin
+  corpus — larger than `docsContext` and `systemPrompts` combined, leaving
+  ~5.5% headroom instead of ~2×. `bddScenarios` is now truncated to
+  `BDD_SCENARIOS_BYTE_BUDGET` (`lib/bdd-scenario-budget.js`, ≤24 KB,
+  reported via `truncated` / `totalScenarios` / `includedScenarios` rather
+  than silently dropped) before it reaches the envelope, deliberately a fixed
+  framework constant rather than an `.agentrc.json` knob — the same reasoning
+  Story #4811 applied when it retired the codebase snapshot. The
+  operator-supplied seed remains the one field with no cap and no elision
+  path.
+- **On refusal**, the error names the envelope's largest fields and the
+  remedy that follows the single largest one (`OVERSIZE_FIELD_REMEDIES` in
+  `plan-context.js`) — trim the seed, plan fewer `--tickets` source issues in
+  one run, or trim `docsContextFiles`, depending on which field actually blew
+  the budget. The seed itself is carried **verbatim** by design — it is the
+  operator's request, and summarizing it silently would degrade planning
+  quality precisely when the input is richest — so it alone has no elision
+  path to fall back on. Raising the ceiling needs a measured justification.
 
 ### Session-mass capacity (plan-time sizing)
 

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/bdd-scenario-budget.js

@@ -0,0 +1,68 @@
+/**
+ * bdd-scenario-budget.js — envelope byte budget for the `bddScenarios`
+ * `/plan` context-envelope field (Story #4977).
+ *
+ * `bdd-scenario-scanner.js`'s `scanBddScenarios` stays a faithful, uncapped
+ * index of the project's `.feature` corpus — that scan is also used
+ * directly by `lib/qa/resolve-selection.js`, which needs the full set. The
+ * cap belongs at the envelope boundary instead, in its own module: on a
+ * consumer with a mature Gherkin corpus, `bddScenarios` grew to 118 KB —
+ * larger than `docsContext` and `systemPrompts` combined — consuming
+ * nearly the entire `PLAN_CONTEXT_ENVELOPE_BYTE_CEILING` headroom on its
+ * own and blocking `/audit-to-stories`' single-plan path entirely.
+ *
+ * Deliberately a fixed framework constant rather than an `.agentrc.json`
+ * knob: Story #4541 retired the one operator-tunable planner-context budget
+ * (`planning.context.maxBytes`) because a cap the operator can raise past
+ * what the model can read fails silently again, and the same reasoning
+ * applies here.
+ */
+
+/**
+ * Byte budget for the capped `bddScenarios` envelope field. Sized well
+ * under `PLAN_CONTEXT_ENVELOPE_BYTE_CEILING` (256 KB) — this is one of
+ * several envelope fields, not the whole budget. At the measured ~337
+ * bytes/scenario average (Story #4977 evidence, a mature Gherkin corpus),
+ * 24 KB holds roughly 70 scenarios before truncating.
+ *
+ * Deliberately module-private: the only production consumer is
+ * {@link capBddScenarios} below via the `opts.byteBudget` default. Tests
+ * assert the resulting behavior (truncation, order, fit) rather than
+ * importing this value directly, so it carries no public export the
+ * `--production` dead-exports ratchet would otherwise flag as test-only.
+ */
+const BDD_SCENARIOS_BYTE_BUDGET = 24_000;
+
+/**
+ * Truncate a scenario index to a byte budget, deterministically (scan
+ * order — file walk order, then in-file order — never re-sorted), and
+ * report what was dropped rather than truncating silently.
+ *
+ * @param {Array<object>} scenarios Full scan output (order preserved).
+ * @param {{ byteBudget?: number }} [opts]
+ * @returns {{
+ *   scenarios: Array<object>,
+ *   totalScenarios: number,
+ *   includedScenarios: number,
+ *   truncated: boolean,
+ * }}
+ */
+export function capBddScenarios(scenarios, opts = {}) {
+  const byteBudget = opts.byteBudget ?? BDD_SCENARIOS_BYTE_BUDGET;
+  const list = Array.isArray(scenarios) ? scenarios : [];
+  let bytes = 0;
+  let cut = list.length;
+  for (let i = 0; i < list.length; i += 1) {
+    bytes += Buffer.byteLength(JSON.stringify(list[i]), 'utf-8');
+    if (bytes > byteBudget) {
+      cut = i;
+      break;
+    }
+  }
+  return {
+    scenarios: list.slice(0, cut),
+    totalScenarios: list.length,
+    includedScenarios: cut,
+    truncated: cut < list.length,
+  };
+}

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,
 };