mandrel 2.33.0 → 2.34.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/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/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/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/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-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);
+}

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

@@ -363,20 +363,21 @@ export const COVERAGE_TIMEOUT_EXIT_CODE = 124;
  * `timeout(1)` convention exit code 124 so callers can pattern-match a
  * runaway runner without inspecting signal names.
  *
- * `files` (Story #4981) scopes the spawn to a file list — `npm run
- * test:coverage -- <files...>`, the standard npm convention for forwarding
- * argv to the underlying script (which most test runners, including Node's
- * own, treat as positional file filters). Omitted or empty means the
- * default full-scope invocation, byte-identical to the pre-#4981 argv
- * (AC-5); a non-empty list makes the scope observable on the emitted
- * command line (AC-1).
+ * The spawn takes **no positional file arguments**. Story #4981 forwarded the
+ * changed-file list as `npm run test:coverage -- <files...>` on the premise
+ * that a test runner treats trailing positionals as filters over the suite.
+ * Node's runner does not: it treats each path as a test file to execute, so a
+ * forwarded *source* file runs as a trivially-passing test and the real suite
+ * never runs. `run-coverage.js` discarded the list, which is the only reason
+ * that never bit; Story #5063 measured it and Story #5065 removed the
+ * plumbing rather than leave a parameter whose obvious "fix" empties the
+ * coverage artifact.
  *
  * @param {{
  *   cwd: string,
  *   timeoutMs?: number,
  *   runner?: typeof spawnSync,
  *   log?: (m: string) => void,
- *   files?: string[] | null,
  * }} opts
  * @returns {number}
  */
@@ -385,14 +386,8 @@ export function runCapture({
   timeoutMs,
   runner = spawnSync,
   log = () => {},
-  files = null,
 } = {}) {
-  const scopedFiles = Array.isArray(files) && files.length > 0 ? files : null;
-  const args = [
-    'run',
-    'test:coverage',
-    ...(scopedFiles ? ['--', ...scopedFiles] : []),
-  ];
+  const args = ['run', 'test:coverage'];
   log(`[coverage-capture] ▶ npm ${args.join(' ')}`);
   const spawnOpts = {
     cwd,

package/.agents/scripts/lib/orchestration/plan-persist/story-ops.js

@@ -672,13 +672,30 @@ function renderStoryBodyForCreate(story, idBySlug) {
   const dependencyRefs = story.depends_on.map(
     (slug) => `#${idBySlug.get(slug)}`,
   );
-  const base =
-    dependencyRefs.length === 0
-      ? story.body
-      : serializeStoryBody(
-          { ...story.bodyObject, depends_on: dependencyRefs },
-          { includeFooter: true },
-        );
+  let base = story.body;
+  if (dependencyRefs.length > 0) {
+    // Re-serializing from `bodyObject` is what resolves the sibling slugs to
+    // real issue ids — but `bodyObject` never held the provenance footers
+    // (`assembleOnePlanStory` appends those to the body *string*), so this
+    // branch drops them unless the carry is re-applied. That is the exact
+    // loss site Story #4935 diagnosed, #4939 fixed, and #4956 reverted
+    // wholesale hours later; Story #5056 restored it with a persist-side
+    // regression test that reads the POSTed body.
+    //
+    // `from: story.body` — not the seed — is load-bearing: it re-carries the
+    // identities *this* Story was stamped with under Story #5045 attribution
+    // rather than reintroducing the whole seed's union. `carryProvenanceFooters`
+    // is additive, union-preserving and idempotent, so re-applying is safe by
+    // construction.
+    const reserialized = serializeStoryBody(
+      { ...story.bodyObject, depends_on: dependencyRefs },
+      { includeFooter: true },
+    );
+    base = carryProvenanceFooters({
+      from: story.body,
+      into: reserialized,
+    }).body;
+  }
   return `${base}\n\n${planFingerprintMarker(story.fingerprint)}`;
 }
 

package/.agents/workflows/helpers/deliver-light.md

@@ -131,8 +131,11 @@ answer).
    invoked, not reimplemented.
 
 3. **Implement + self-eval.** `cd` into `workCwd`, implement the change, run
-   `npm test` once in the worktree, then run the bounded acceptance self-eval
-   loop ([`deliver-story.md`](deliver-story.md) Step 1a). Commit
+   the full suite once in the worktree **so close can credit it** — the
+   crediting invocation and the freshness contract are
+   [`deliver-story.md`](deliver-story.md) Step 1.3, unchanged here — then run
+   the bounded acceptance self-eval loop
+   ([`deliver-story.md`](deliver-story.md) Step 1a). Commit
    on `story-<id>` with `(refs #<storyId>)`.
 
 4. **Diff backstop.** Before close, re-check the ACTUAL diff:

package/.agents/workflows/helpers/deliver-story-reference.md

@@ -233,12 +233,34 @@ runs maker-blind at Story-scope review inside the close subprocess. The
 dispatch step produces `checklistPath` from the Story's predicted footprint
 before it spawns the worker — see [`/deliver`](../deliver.md).
 
-**Pre-eval full-suite discipline (spine step 5).** Repo-invariant guards —
+**Pre-eval full-suite discipline (spine step 1.3).** Repo-invariant guards —
 drift-guard and schema tests living outside the Story's scoped greps — are
 the failure class that actually bounces deliveries: close-validation
 discovers them only after the whole close pipeline has run, at several times
 the cost of one pre-eval full-suite run.
 
+**Run it so close can credit it.** Close skips a gate that already passed at
+the current HEAD, but a bare `npm test` deposits no such record — the suite
+then runs twice per delivery, once here and once in the close gate chain.
+Pick the invocation by the same predicate `close-validation/gates.js` uses to
+choose its test gate:
+
+```bash
+# CRAP gate enabled (default) + a `test:coverage` script — writes the stamp
+# the close `coverage-capture` gate reads:
+node <main-repo>/.agents/scripts/coverage-capture.js --cwd <workCwd>
+# otherwise — the evidence record the close `test` gate reads. <workCwd> must
+# be ABSOLUTE and the runner exactly `npm test`: both sides hash
+# {cmd, args, cwd}, so a relative path or a wrapper misses the credit.
+node <main-repo>/.agents/scripts/evidence-gate.js --standalone \
+  --scope-id <storyId> --gate test --worktree <workCwd> -- npm test
+```
+
+The credit expires the moment it stops describing the tree: evidence is keyed
+on HEAD, the capture stamp on a content digest of `crap.targetDirs`. A
+self-eval fix — or any commit — invalidates it and close re-runs the suite for
+real, so this never trades away the gate.
+
 **Conflict with `main` mid-implementation** → resolve as you would any branch
 rebase. There is no `epic/<id>` intermediate, so the rebase base is `main`
 directly.

package/.agents/workflows/helpers/deliver-story.md

@@ -75,9 +75,11 @@ One branch, one PR to `main`, commits against the inline `acceptance[]` /
    `## Slicing` rows as **intra-session checkpoints** (reference § Step 1).
 2. Implement and commit on the Story branch, iterating with quick advisory
    gates (`typecheck`, `lint`, scoped tests) — the full chain runs in Step 3.
-3. Run `npm test` once in the worktree **before Step 1a**: repo-invariant
+3. Run the full suite once in the worktree **before Step 1a**: repo-invariant
    guards outside the Story's scoped greps are the failure class that bounces
-   deliveries. Fix and commit first, then run the self-eval loop.
+   deliveries. Fix and commit first, then run the self-eval loop. Run it **so
+   Step 3 credits it** — a bare `npm test` records nothing, so close re-runs
+   the identical suite (reference § Step 1, "Pre-eval full-suite discipline").
 
 ### Step 1a — Bounded acceptance self-eval loop (**required**)
 

package/docs/CHANGELOG.md

@@ -15,6 +15,16 @@ All notable changes to this project will be documented in this file.
 -->
 <!-- markdownlint-disable-file MD004 MD012 MD037 -->
 
+## [2.34.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.33.0...mandrel-v2.34.0) (2026-08-27)
+
+
+### Fixed
+
+* **baselines:** weight the mutation rollup by mutant count and gate the migration (refs [#5058](https://github.com/dsj1984/mandrel/issues/5058)) ([#5062](https://github.com/dsj1984/mandrel/issues/5062)) ([a645d30](https://github.com/dsj1984/mandrel/commit/a645d3085450b4dae39ae5d0a9b9844014535f84))
+* **coverage:** describe incrementalCoverage honestly, drop inert forwarding (refs [#5065](https://github.com/dsj1984/mandrel/issues/5065)) ([#5066](https://github.com/dsj1984/mandrel/issues/5066)) ([04ff450](https://github.com/dsj1984/mandrel/commit/04ff450cb1774a1faa0b4f901f1e09261b0ae00a))
+* delivery lifecycle: credit the Step 1 full-suite run to close and enable incremental coverage by default ([#5063](https://github.com/dsj1984/mandrel/issues/5063)) ([#5064](https://github.com/dsj1984/mandrel/issues/5064)) ([39b1ea4](https://github.com/dsj1984/mandrel/commit/39b1ea421c9a8a43f35ad4c8cbc082e1f2ead8c4))
+* **plan-persist:** re-carry audit provenance onto dependent Stories (refs [#5056](https://github.com/dsj1984/mandrel/issues/5056)) ([#5060](https://github.com/dsj1984/mandrel/issues/5060)) ([548cc8a](https://github.com/dsj1984/mandrel/commit/548cc8a46afc5b643452060cc3a03bf71a874b89))
+
 ## [2.33.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.32.0...mandrel-v2.33.0) (2026-08-07)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mandrel",
-  "version": "2.33.0",
+  "version": "2.34.0",
   "description": "Claude Code-first opinionated workflow framework: instructions, skills, rules, and SDLC workflows that govern AI coding assistants.",
   "files": [
     ".agents/",