mandrel 2.33.0 → 2.35.0

package/.agents/docs/configuration.md

@@ -210,8 +210,8 @@ Everything `/deliver` and `single-story-close` consume: execution timeouts, work
 | `quality.gates.crap.refreshTag` | No | `string` | `"baseline-refresh:"` | Commit-subject substring that acknowledges a deliberate CRAP baseline refresh in the compared range. A range commit carrying it that also touches the baseline file demotes head-vs-base regressions; floors stay enforced. |
 | `quality.gates.crap.refreshTimeoutMs` | No | `integer` | `60000` | 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` | — | Master switch for incremental capture + join scoping. |
+| `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`, 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). |
+| `quality.gates.crap.incrementalCoverage.enabled` | No | `boolean` | — | Master switch for the capture skip and the baseline-resolved CRAP join. |
 | `quality.gates.crap.incrementalCoverage.baseRef` | No | `string` | — | Git ref the changed-file set is computed against. Omitted falls back to the gate’s own `--ref` (`main`). |
 | `quality.gates.maintainability` | No | `object` | — | Maintainability-index ratchet. Scores per file as the average over its methods, so deleting a small high-MI method can legitimately lower a file’s score. |
 | `quality.gates.maintainability.enabled` | No | `boolean` | `true` | When false, the checker exits 0 with a skip line and the gate is reported as `skipped`, never omitted. |

package/.agents/docs/quality-gates.md

@@ -424,6 +424,36 @@ refresh-guardrail accepts it on the next PR.
 If your test runner doesn't produce per-method coverage, see "Disabling the
 gate" below.
 
+### Coverage freshness — what triggers a capture
+
+The CRAP scorer treats "no coverage" as "skip the method", so a missing or
+stale `coverage/coverage-final.json` silently weakens the gate.
+`coverage-capture.js` closes that hole by capturing coverage in-band, and
+decides whether it needs to by two rules (Story #5076):
+
+- **The source set is derived, not configured.** Freshness is measured over
+  exactly the extensions the CRAP scanner walks — `.js`, `.mjs`, `.cjs`,
+  `.ts`, `.tsx`, `.mts`, `.cts` — defined once in
+  `.agents/scripts/lib/source-extensions.js`. There is deliberately no
+  `.agentrc.json` key for this: a consumer-settable list would be a second
+  way to mis-scope the same gate. Formats the engines cannot parse
+  (`.astro`, `.vue`, `.svelte`) are not part of it — a project written in
+  those still has its `.ts`/`.tsx` measured.
+- **Both freshness paths fail closed on an empty source set.** Finding no
+  scorable source under `crap.targetDirs` means the check learned nothing,
+  so it captures rather than assuming coverage is current, and warns naming
+  the configured dirs. If you see that warning, `targetDirs` almost
+  certainly does not point at your sources — fix it rather than living with
+  a full capture on every run.
+
+**Upgrading from a version before this fix:** a TypeScript project's sources
+matched neither path, so the capture was skipped on every run and
+`crap:check` compared the committed baseline against itself. The first run
+after upgrading captures for real and measures your committed floors for the
+first time, which may surface breaches that were always there. That is a
+one-off re-baseline (`npm run crap:update`, committed with a
+`baseline-refresh:` subject), not a regression.
+
 ### Disabling the gate (single-flag opt-out)
 
 If your repo doesn't run coverage, set `enabled: false` in your

package/.agents/docs/workflows.md

@@ -32,11 +32,12 @@ by `node .agents/scripts/generate-workflows-doc.js`; `npm run docs:check`
 fails when it drifts from the on-disk workflow set. To change a command’s
 description, edit the workflow file’s front-matter and regenerate.
 
-## Commands (27)
+## Commands (28)
 
 | Command | Description |
 | --- | --- |
 | `/audit-accessibility` | Audit WCAG accessibility conformance (static-first) with an optional runtime verification pass, and produce a structured findings report |
+| `/audit-adrs` | Audit the decisions log as a live contract — Accepted ADRs whose claims the tree has outgrown, broken supersede chains, structural gaps, and directional changes that landed with no decision recorded. A deliberately-global lens over whichever decisions-log layout the consumer ships. |
 | `/audit-architecture` | Audit architectural boundaries, module coupling, layering violations, and shipped-but-uncalled seams; emit a structured findings report keyed to the canonical severity scale. |
 | `/audit-baselines` | Audit the committed baseline surface — dead instruments, stale baselines, cross-gate hotspot clusters, trend drift, and floor-tightening headroom — and emit findings whose remediation burns the measured debt down and tightens the ratchet behind it. |
 | `/audit-clean-code` | Audit code smells, dead code, complexity hotspots, and maintainability-index outliers; emit a structured findings report. |

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

@@ -978,11 +978,11 @@
                     },
                     "incrementalCoverage": {
                       "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`, `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.",
+                      "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).",
                       "properties": {
                         "enabled": {
                           "type": "boolean",
-                          "description": "Master switch for incremental capture + join scoping."
+                          "description": "Master switch for the capture skip and the baseline-resolved CRAP join."
                         },
                         "baseRef": {
                           "type": "string",

package/.agents/schemas/audit-rules.json

@@ -312,6 +312,23 @@
       "target": "web",
       "scope": "global",
       "substitutionKeys": []
+    },
+    "audit-adrs": {
+      "triggers": {
+        "gates": ["gate1", "gate3"],
+        "keywords": [
+          "adr",
+          "adrs",
+          "decision record",
+          "architecture decision",
+          "decisions log",
+          "supersede",
+          "superseded"
+        ],
+        "filePatterns": ["**/decisions.md", "**/decisions/**"]
+      },
+      "scope": "global",
+      "substitutionKeys": []
     }
   },
   "sensitivePaths": {
@@ -363,6 +380,33 @@
         "**/openapi/**",
         "**/graphql/**"
       ]
+    },
+    "deploy-runtime": {
+      "description": "Deployment and runtime topology: the CI/CD pipeline, infrastructure-as-code, container images, and the server/serverless entrypoint with its platform and build config. A change here alters how the product is built, bound, and run in production without necessarily touching application logic. Build configs are enumerated by name rather than matched with a blanket `**/*.config.*` glob, which would swallow the test and lint configs and flip nearly every change set to high.",
+      "filePatterns": [
+        ".github/workflows/**",
+        ".github/actions/**",
+        "**/Dockerfile",
+        "**/docker-compose*.yml",
+        "**/docker-compose*.yaml",
+        "infra/**",
+        "**/*.tf",
+        "**/*.tfvars",
+        "**/wrangler.json",
+        "**/wrangler.jsonc",
+        "**/wrangler.toml",
+        "**/worker-entry.ts",
+        "**/worker-entry.js",
+        "**/astro.config.*",
+        "**/next.config.*",
+        "**/nuxt.config.*",
+        "**/svelte.config.*",
+        "**/fly.toml",
+        "**/vercel.json",
+        "**/netlify.toml",
+        "**/serverless.yml",
+        "**/serverless.yaml"
+      ]
     }
   }
 }

package/.agents/schemas/audit-rules.schema.json

@@ -22,7 +22,7 @@
     },
     "sensitivePaths": {
       "type": "object",
-      "description": "Map of sensitive-path class name to the globs that identify it. A change set touching any registered pattern derives a `high` change level, which resolves review depth to `deep` and the acceptance critic to `fresh` regardless of how narrow the diff is (deriveChangeLevel in lib/orchestration/review-depth.js). This is configuration, not code: an operator extends the classes or their globs here without editing a module, and the globs run through the same picomatch machinery as the audit-lens `filePatterns` triggers above. An absent or empty block means no path is sensitive and depth falls back to diff width alone.",
+      "description": "Map of sensitive-path class name to the globs that identify it. A change set touching any registered pattern derives a `high` change level, which resolves review depth to `deep` and the acceptance critic to `fresh` regardless of how narrow the diff is (deriveChangeLevel in lib/orchestration/review-depth.js). This is configuration, not code: an operator extends the classes or their globs here without editing a module, and the globs run through the same picomatch machinery as the audit-lens `filePatterns` triggers above. Those lens triggers are a SEPARATE block with a separate job — they select which lens runs, never the change level — so a path registered there is not sensitive here unless it is also registered in this block. An absent or empty block means no path is sensitive and depth falls back to diff width alone.",
       "patternProperties": {
         "^[a-z][a-z0-9-]*$": { "$ref": "#/definitions/sensitivePathClass" }
       },

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

@@ -33,6 +33,7 @@ import {
 } from './lib/coverage-capture.js';
 import { runFullScopeCapture } from './lib/coverage-capture-fullscope.js';
 import { tryIncrementalCapture } from './lib/coverage-capture-incremental.js';
+import { handleCoverageCaptureHelp } from './lib/coverage-capture-usage.js';
 
 import { Logger } from './lib/Logger.js';
 import { hasNpmScript, readPackageScripts } from './lib/npm-scripts.js';
@@ -160,7 +161,12 @@ export function runCoverageCapture(argv = process.argv, deps = {}) {
 // invoked as a CLI the behaviour — exit code and log lines — is unchanged.
 if (isDirectInvocation(import.meta.url)) {
   try {
-    process.exit(runCoverageCapture());
+    // `--help` is answered before the decision core runs: it used to fall
+    // through to the capture path, so asking this script to describe itself
+    // spawned the whole coverage suite.
+    process.exit(
+      handleCoverageCaptureHelp(process.argv) ? 0 : runCoverageCapture(),
+    );
   } catch (err) {
     Logger.error('[coverage-capture] unexpected error:', err);
     process.exit(1);

package/.agents/scripts/lib/baselines/kernel.js

@@ -107,6 +107,7 @@ import {
 } from './kinds/maintainability.js';
 import {
   applyEpsilon as mutationApplyEpsilon,
+  assertBaselineCompatible as mutationAssertBaselineCompatible,
   compare as mutationCompare,
   kernelVersion as mutationKernelVersion,
   keyField as mutationKeyField,
@@ -211,6 +212,7 @@ const KIND_MODULES = Object.freeze({
     compare: mutationCompare,
     applyEpsilon: mutationApplyEpsilon,
     mergeRows: mutationMergeRows,
+    assertBaselineCompatible: mutationAssertBaselineCompatible,
   }),
   lighthouse: bindKindModule({
     name: lighthouseName,
@@ -280,6 +282,22 @@ export function currentKernelVersion(kind) {
   return getKindModule(kind).kernelVersion();
 }
 
+/**
+ * Resolve a kind module, or null when the kind is not registered. Lets the
+ * optional-hook callers below stay expression-shaped instead of threading a
+ * mutable binding through a try/catch.
+ *
+ * @param {string} kind
+ * @returns {object|null}
+ */
+function tryGetKindModule(kind) {
+  try {
+    return getKindModule(kind);
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Ask a kind whether a loaded baseline is compatible with the running
  * scorer's SEMANTICS — a dimension `kernelVersion` cannot express, because a
@@ -291,13 +309,8 @@ export function currentKernelVersion(kind) {
  * @returns {string|null} Operator-facing message, or null when compatible.
  */
 export function checkBaselineSemantics(kind, baseline) {
-  let mod;
-  try {
-    mod = getKindModule(kind);
-  } catch {
-    return null;
-  }
-  if (typeof mod.assertBaselineCompatible !== 'function') return null;
+  const mod = tryGetKindModule(kind);
+  if (typeof mod?.assertBaselineCompatible !== 'function') return null;
   return mod.assertBaselineCompatible(baseline);
 }
 

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

@@ -673,8 +673,13 @@ export function assessComparisonBasis(compareResult, opts = {}) {
  *
  * Story #791 retired the transitional `bootstrap` exit-0 path: a missing
  * baseline still fails closed. Story #829 (5.29.0) softened `kernelVersion`
- * and `tsTranspilerVersion` drift to **warn**, not fail; `escomplexVersion`
- * mismatch continues to fail closed.
+ * drift to **warn**, not fail, and did the same for `tsTranspilerVersion` —
+ * but that second half was re-escalated to **fatal** once Story #4866 made a
+ * TS row's `startLine` an original-source coordinate resolved through the
+ * transpiler's sourcemap. `startLine` is half the row identity key, so a
+ * transpiler change makes the rows incomparable rather than merely stale; see
+ * the `ts-transpiler-drift` axis below for the two exemptions that bound it.
+ * `escomplexVersion` mismatch has always failed closed.
  */
 /**
  * The one re-seed recipe every coordinate-invalidating axis ends on. Three

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

@@ -2,13 +2,43 @@
  * kinds/mutation.js — per-kind module for the mutation-testing baseline
  * (Story #1891). Row shape: `{ path, score, killed, survived }`. Rollup
  * carries score/killed/survived/noCoverage. Stryker is the upstream
- * kernel; we pin a static `1.0.0` until a Mandrel-side retrofit story
+ * kernel; we pin a static version until a Mandrel-side retrofit story
  * wires the running Stryker version through (#1908).
  *
  * Higher score = better. New paths land in the `additions` bucket
  * (Story #2012 — any real-world score under 100 must never flip to a
  * regression); removed paths count as improvements when their score was
  * non-perfect. Scaffold is generated by `makeBaselineKind` (Story #3983).
+ *
+ * ## Rollup weighting (Story #5058)
+ *
+ * The rollup score is a **mutant-weighted** mean —
+ * `sum(score_i * mutants_i) / sum(mutants_i)`, where
+ * `mutants_i = killed_i + survived_i`. It used to be `scoreSum / rows.length`,
+ * an unweighted mean over files, under which a 3-mutant file carried the same
+ * weight as a 300-mutant one: adding a handful of thinly-mutated new files
+ * dragged the whole-repo number down far enough to breach the floor arm while
+ * the compare arm reported no regression at all (a newly-scanned file has no
+ * baseline row, so it can only move the aggregate `applyFloors` scores).
+ *
+ * Both weights are already summed in the same loop and are already required
+ * by the row schema, which is `additionalProperties: false` — so the weighted
+ * score is computable from the existing row shape with no producer change and
+ * no schema change.
+ *
+ * **Limit of the approximation.** Rows carry no timeout or no-coverage counts
+ * (`noCoverage` in the rollup is hardcoded `0`), so `killed + survived` is not
+ * Stryker's full mutant population wherever timed-out or uncovered mutants
+ * exist. The weighted score therefore *approximates* Stryker's published
+ * overall score — it does not reproduce it. Closing that gap needs a producer
+ * change and its own Story.
+ *
+ * Because this changes what the stored number MEANS, it is a semantics
+ * migration: a baseline measured at 88.51 unweighted is 85.18 weighted over
+ * the same rows, so every floor calibrated on the old mean breaches on
+ * upgrade. `assertBaselineCompatible` below fails such a baseline closed —
+ * a bare `kernelVersion` bump would not, because `kernelMatch` feeds only the
+ * reporting-side drift count and reaches no exit code.
  */
 
 import { canonicalise } from '../path-canon.js';
@@ -17,6 +47,24 @@ import { makeBaselineKind } from './kind-factory.js';
 export const name = 'mutation';
 export const keyField = 'path';
 
+/**
+ * Kernel version of the mutation scorer. Bumped off the original `1.0.0` by
+ * Story #5058: the rollup score changed from an unweighted file mean to a
+ * mutant-weighted mean, so rows stamped below this version were aggregated
+ * under superseded semantics.
+ */
+const KERNEL_VERSION = '2.0.0';
+
+/** Major of {@link KERNEL_VERSION} — the weighted-rollup boundary. */
+const WEIGHTED_ROLLUP_MAJOR = 2;
+
+const RESEED_REMEDY =
+  'Re-seed the baseline: re-run this project mutation run (Mandrel ships no ' +
+  "runner — Stryker is the upstream producer, e.g. 'npx stryker run') so " +
+  "'baselines/mutation.json' is rewritten under the weighted rollup, then " +
+  "commit it with a 'baseline-refresh:' subject and recalibrate the gate's " +
+  'floors against the new number.';
+
 export function projectRow(row) {
   return {
     path: canonicalise(row.path),
@@ -26,20 +74,102 @@ export function projectRow(row) {
   };
 }
 
+/**
+ * Parse the major component of a semver-ish stamp.
+ *
+ * @param {unknown} version
+ * @returns {number|null} The major, or null when unparseable/absent.
+ */
+function majorOf(version) {
+  const match = /^(\d+)\./.exec(String(version ?? ''));
+  return match ? Number(match[1]) : null;
+}
+
+/**
+ * Kind-module hook (Story #4775) — refuse a loaded baseline whose rollup was
+ * aggregated by the superseded unweighted mean. `checkBaselineSemantics`
+ * dispatches here and `check-baselines`' evaluate phase turns a non-null
+ * return into a fail-closed `semantics` schema error, so a pre-weighting
+ * baseline can never be silently scored against floors calibrated on a
+ * different definition of the number. Follows the `kinds/crap.js` precedent.
+ *
+ * An absent or unparseable stamp is rejected too: `kernelVersion` is required
+ * by the shared envelope schema, so its absence is not evidence of a newer
+ * writer.
+ *
+ * @param {object|null} baseline A loaded v2 baseline envelope.
+ * @returns {string|null} Operator-facing message, or null when compatible.
+ */
+export function assertBaselineCompatible(baseline) {
+  if (!baseline) return null;
+  const stamped = baseline.kernelVersion ?? null;
+  const major = majorOf(stamped);
+  if (major !== null && major >= WEIGHTED_ROLLUP_MAJOR) return null;
+  return (
+    `[mutation] rollup scoring semantics changed: baseline=${stamped ?? '<unstamped>'} ` +
+    `running=${KERNEL_VERSION}. The rollup score is now a mutant-weighted mean ` +
+    '(sum(score * mutants) / sum(mutants)) rather than an unweighted mean over ' +
+    'files, so the stored aggregate is a different number for the same rows and ' +
+    `the floors calibrated against it no longer mean what they did. ${RESEED_REMEDY}`
+  );
+}
+
+/**
+ * A row's mutant count — the weight it carries in the rollup score.
+ *
+ * @param {object} row
+ * @returns {number}
+ */
+function mutantsOf(row) {
+  return (row.killed ?? 0) + (row.survived ?? 0);
+}
+
+/**
+ * Sum one numeric row field across a row set.
+ *
+ * @param {object[]} rows
+ * @param {string} field
+ * @returns {number}
+ */
+function sumOf(rows, field) {
+  let total = 0;
+  for (const r of rows) total += r[field] ?? 0;
+  return total;
+}
+
+/**
+ * The mutant-weighted mean score: `sum(score * mutants) / sum(mutants)`.
+ *
+ * Zero-mutant guard: an empty row set, or one whose rows carry only zeroes,
+ * has no weight to divide by. Returning 0 rather than dividing keeps `NaN` and
+ * `Infinity` out of the envelope, where they would fail the schema's numeric
+ * bounds downstream.
+ *
+ * @param {object[]} rows
+ * @param {number} mutants Total mutant count across `rows`.
+ * @returns {number}
+ */
+function weightedScore(rows, mutants) {
+  if (mutants <= 0) return 0;
+  let weighted = 0;
+  for (const r of rows) weighted += (r.score ?? 0) * mutantsOf(r);
+  return Number((weighted / mutants).toFixed(2));
+}
+
+/**
+ * Aggregate rows into the rollup shape. `killed` and `survived` stay plain
+ * sums and `noCoverage` stays hardcoded 0 — the weighting changes `score`
+ * alone.
+ *
+ * @param {object[]} rows
+ * @returns {{score: number, killed: number, survived: number, noCoverage: number}}
+ */
 function aggregate(rows) {
-  if (!rows || rows.length === 0) {
-    return { score: 0, killed: 0, survived: 0, noCoverage: 0 };
-  }
-  let scoreSum = 0;
-  let killed = 0;
-  let survived = 0;
-  for (const r of rows) {
-    scoreSum += r.score ?? 0;
-    killed += r.killed ?? 0;
-    survived += r.survived ?? 0;
-  }
+  const scored = rows ?? [];
+  const killed = sumOf(scored, 'killed');
+  const survived = sumOf(scored, 'survived');
   return {
-    score: Number((scoreSum / rows.length).toFixed(2)),
+    score: weightedScore(scored, killed + survived),
     killed,
     survived,
     noCoverage: 0,
@@ -55,7 +185,7 @@ export const {
   mergeRows,
 } = makeBaselineKind({
   keyField,
-  kernelVersion: '1.0.0',
+  kernelVersion: KERNEL_VERSION,
   axes: ['score'],
   betterWhen: 'higher',
   aggregate,

package/.agents/scripts/lib/close-validation/projections/crap.js

@@ -36,6 +36,7 @@ import { loadCoverage } from '../../coverage-utils.js';
 import { scanAndScore } from '../../crap-utils.js';
 import { cachedGitFetchSync } from '../../git/cached-fetch.js';
 import { gitSpawn as defaultGitSpawn } from '../../git-utils.js';
+import { SCORABLE_SOURCE_EXT_RE } from '../../source-extensions.js';
 import { MISSING_ARG_REASONS, validateProjectionInputs } from './inputs.js';
 
 /**
@@ -48,9 +49,6 @@ export const DEFAULT_CRAP_TOLERANCE = 0.001;
 /** Framework default for the new-method ceiling (`gates.crap.newMethodCeiling`). */
 export const DEFAULT_NEW_METHOD_CEILING = 30;
 
-/** Extensions the CRAP scanner can score. */
-const SCORABLE = /\.(?:js|mjs|cjs|ts|tsx)$/;
-
 /**
  * Map the shared predicate's fine-grained `missing-*` reason onto the
  * `missing-args` skipped-reason the sibling MI projection reports, so both
@@ -155,8 +153,9 @@ function refreshBaseRef(cwd, baseBranch, git) {
 }
 
 /**
- * Enumerate the Story branch's changed files, narrowed to the extensions
- * the CRAP scanner can score.
+ * Enumerate the Story branch's changed files, narrowed by the shared
+ * scorable-source extension set (`source-extensions.js`) so the projection
+ * selects exactly the files the CRAP scanner walks.
  *
  * @param {{ cwd: string, baseBranch: string, storyBranch: string, git: { gitSpawn: typeof defaultGitSpawn } }} opts
  * @returns {{ ok: true, files: string[] } | { ok: false, detail: string }}
@@ -168,7 +167,10 @@ function diffScorableFiles({ cwd, baseBranch, storyBranch, git }) {
       cwd,
       gitSpawn: git.gitSpawn,
     });
-    return { ok: true, files: files.filter((f) => SCORABLE.test(f)) };
+    return {
+      ok: true,
+      files: files.filter((f) => SCORABLE_SOURCE_EXT_RE.test(f)),
+    };
   } catch (err) {
     return { ok: false, detail: err.message };
   }

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

@@ -10,20 +10,23 @@
  * 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.
+ * 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).
  */
 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`, `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.',
+    '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).',
   properties: {
     enabled: {
       type: 'boolean',
-      description: 'Master switch for incremental capture + join scoping.',
+      description:
+        'Master switch for the capture skip and the baseline-resolved CRAP join.',
     },
     baseRef: {
       type: 'string',

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

@@ -78,6 +78,13 @@ const DEFAULT_MI_FLOORS = Object.freeze({
  * `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 #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`.
  */
 const DEFAULT_INCREMENTAL_COVERAGE = Object.freeze({
   enabled: false,

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

@@ -8,7 +8,10 @@
  * logic; behaviour is byte-for-byte the pre-#4981 body.
  */
 import path from 'node:path';
-import { anyChangedUnderTargets } from './coverage-capture.js';
+import {
+  anyChangedUnderTargets,
+  describeFreshness,
+} from './coverage-capture.js';
 
 /**
  * Run the `--skip-when-no-crap-files` check (when requested), the
@@ -72,7 +75,7 @@ export function runFullScopeCapture({
   }
 
   logger.info(
-    `[coverage-capture] Coverage at ${crap.coveragePath} is ${freshness.reason}; running npm run test:coverage…`,
+    `[coverage-capture] Coverage at ${crap.coveragePath} is ${describeFreshness(freshness, crap.targetDirs)}; running npm run test:coverage…`,
   );
   const code = runCaptureImpl({
     cwd: args.cwd,

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

@@ -14,6 +14,14 @@ import path from 'node:path';
  * Run the incremental capture path when
  * `delivery.quality.gates.crap.incrementalCoverage.enabled` is true.
  *
+ * **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.
+ *
  * Returns the process exit code when incremental mode handled the run
  * (skip, capture, or a capture failure), or `null` when the caller should
  * fall through to the full-scope path — either incremental mode is
@@ -81,13 +89,12 @@ export function tryIncrementalCapture({
   }
 
   logger.info(
-    `[coverage-capture] Incremental mode: capturing coverage scoped to ${scopedFiles.length} changed file(s) under [${crap.targetDirs.join(', ')}]…`,
+    `[coverage-capture] Incremental mode: ${scopedFiles.length} changed file(s) under [${crap.targetDirs.join(', ')}] — capturing…`,
   );
   const code = runCaptureImpl({
     cwd: args.cwd,
     timeoutMs: coverage?.timeoutMs,
     log: (m) => logger.info(m),
-    files: scopedFiles,
   });
   if (code !== 0) {
     logger.error(

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

@@ -0,0 +1,55 @@
+/**
+ * coverage-capture-usage.js — the `--help` spec for `coverage-capture.js`
+ * (Story #5063).
+ *
+ * The delivery workflow invokes `coverage-capture.js` by name
+ * (`helpers/deliver-story-reference.md` § Step 1), which brings it under the
+ * workflow-invoked self-description contract enforced by
+ * `tests/enforcement/workflow-script-help.test.js`. It failed that contract:
+ * `--help` fell through to the capture path and spawned the whole coverage
+ * suite instead of describing the script.
+ *
+ * The spec lives here rather than inline for the same reason
+ * `coverage-capture-incremental.js` does — a same-file expansion of the CLI
+ * shell costs maintainability index on a file already near its floor, and a
+ * usage table is data, not decision logic.
+ */
+
+import { respondToHelp } from './cli-usage.js';
+
+/**
+ * Usage spec consumed by `cli-usage.js#respondToHelp`. `coverage-capture.js`
+ * does not route through `runAsCli` (its synchronous main returns an exit
+ * code that `process.exit` forwards), so the help short-circuit is wired by
+ * hand rather than declared on a `runAsCli` call.
+ *
+ * @type {{ invocation: string, summary: string, flags: Array<[string, string]> }}
+ */
+const COVERAGE_CAPTURE_USAGE = {
+  invocation:
+    'node .agents/scripts/coverage-capture.js [--skip-when-no-crap-files] [--ref <git-ref>] [--cwd <path>]',
+  summary:
+    'Ensure coverage/coverage-final.json is present and fresh before the CRAP gate fires, spawning `npm run test:coverage` only when it is stale. Writes a content-digest capture stamp that close-validation reads to skip a redundant re-run.',
+  flags: [
+    [
+      '--skip-when-no-crap-files',
+      'Exit 0 without capturing when no changed file under the CRAP target dirs differs from --ref.',
+    ],
+    ['--ref <git-ref>', 'Git ref the changed-file set is computed against.'],
+    ['--cwd <path>', 'Repository root the capture runs in.'],
+  ],
+};
+
+/**
+ * Answer `--help` / `-h` on stdout, returning whether the caller should stop.
+ * Takes the full `process.argv`-shaped array so the CLI shell hands over its
+ * own argv unchanged and the index arithmetic lives here rather than at the
+ * call site.
+ *
+ * @param {string[]} argv Full `process.argv`-shaped array.
+ * @param {{ write: (s: string) => void }} [out] Defaults to `process.stdout`.
+ * @returns {boolean} `true` when help was printed and the run must not proceed.
+ */
+export function handleCoverageCaptureHelp(argv = [], out = process.stdout) {
+  return respondToHelp(argv.slice(2), COVERAGE_CAPTURE_USAGE, out);
+}