mandrel 2.41.0 → 2.42.0

package/.agents/agents/story-worker.md

@@ -90,14 +90,25 @@ Do **not** re-read every file in `project.docsContextFiles`. Read the
 at the line numbers it names. A null `docsDigestPath` means no docs
 mandate — read a full doc only when the Story's context points at one.
 
-## Close gates — do not pre-run
+## Close gates — one credited run, no ad-hoc stamping
 
 `single-story-close.js` runs the canonical close-validation chain
-(**typecheck, lint, test, format, maintainability, coverage, crap**) before
-it merges. Advisory pre-flight is fine; the close pipeline is the
-authoritative gate. The acceptance self-eval loop may share `lint` /
-`typecheck` evidence with close via `evidence-gate.js`; never stamp
-coverage / CRAP fresh that way.
+(**typecheck, lint, test, format, maintainability, coverage, crap**) and is
+the authoritative gate — do not pre-run the chain. The **one** exception is
+the full suite: run it exactly once, after the self-eval loop's last fix
+commit and immediately before the push, in the shape close credits. A bare
+`npm test` / `pnpm run test` deposits **no** credit:
+
+```bash
+# CRAP gate on (default) + a `test:coverage` script:
+node <main-repo>/.agents/scripts/coverage-capture.js --cwd <workCwd>
+# otherwise — <workCwd> ABSOLUTE, runner exactly `npm test`:
+node <main-repo>/.agents/scripts/evidence-gate.js --standalone \
+  --scope-id <storyId> --gate test --worktree <workCwd> -- npm test
+```
+
+Sharing `lint` / `typecheck` evidence with close via `evidence-gate.js` is
+fine; never stamp coverage / CRAP fresh any other way.
 
 Before trusting a gate's output — or diagnosing a red one — read
 [`known-tooling-behavior.md`](../rules/known-tooling-behavior.md): measured
@@ -138,14 +149,13 @@ You do **not** run close. Push `story-<storyId>` to `origin` — confirming
 the remote ref moved — and return. The dispatching orchestrator runs
 `single-story-close.js` in its own session, serialized against your
 siblings. Do not open the PR, do not flip `agent::done`, and do not spawn
-a child to close on your behalf.
+a child to close on your behalf. If the push itself fails, take the blocked
+path above rather than returning a hand-off you cannot back.
 
 ## Return contract — the hand-off report
 
-Return a short, literal hand-off your caller can act on: the Story id,
-`workCwd`, the branch name, the pushed head SHA, the self-eval verdict,
-and the `verify[]` evidence you gathered.
-Say plainly that the branch is pushed and unclosed. Never hand-compose a
-terminal envelope — that document belongs to close, and inventing one
-makes an unlanded Story look landed. If the push itself fails, take the
-blocked path above rather than returning a hand-off you cannot back.
+A short, literal hand-off your caller can act on: Story id, `workCwd`,
+branch, pushed head SHA, self-eval verdict, `verify[]` evidence. Say plainly
+that the branch is pushed and unclosed. Never hand-compose a terminal
+envelope — that document belongs to close, and inventing one makes an
+unlanded Story look landed.

package/.agents/docs/agentrc-reference.json

@@ -89,7 +89,8 @@
   },
   "delivery": {
     "execution": {
-      "timeoutMs": 600000
+      "timeoutMs": 600000,
+      "fullSuiteLock": true
     },
     "docsFreshness": {
       "paths": ["README.md"]
@@ -188,7 +189,11 @@
           },
           "refreshTag": "baseline-refresh:",
           "refreshTimeoutMs": 60000,
-          "ignoreGlobs": []
+          "ignoreGlobs": [],
+          "incrementalCoverage": {
+            "skipWhenUnchanged": true,
+            "baselineJoin": false
+          }
         },
         "maintainability": {
           "enabled": true,

package/.agents/docs/configuration.md

@@ -144,6 +144,7 @@ Everything `/mandrel-deliver` and `single-story-close` consume: execution timeou
 | --- | --- | --- | --- | --- |
 | `execution` | No | `object` | — | Wall-clock bounds on the subprocesses delivery spawns. |
 | `execution.timeoutMs` | No | `integer` | `600000` | Per-command timeout (ms) for the long-running spawns delivery drives — the close-validation chain and the gate CLIs. |
+| `execution.fullSuiteLock` | No | `boolean` | `true` | Serialize full-suite spawns (`npm test` / `npm run test:coverage`) behind a host-level advisory lock, so two concurrent deliveries on one checkout do not run two suites against the same cores. Best-effort: a wait that expires spawns anyway, so the lock can never fail a delivery. Set false — or export `MANDREL_FULL_SUITE_LOCK=0` for one invocation — to disable. |
 | `docsFreshness` | No | `object` | — | Documentation-freshness scope: the files a change of consequence is expected to touch. Read by the audit-documentation lens to seed its target set; no delivery gate enforces it. |
 | `docsFreshness.paths` | No | `array<string>` | `["README.md"]` | Repo-relative documentation paths the audit-documentation lens adds to its target set. |
 | `tempRetention` | No | `object` | — | Story #4794. Auto-purge of spent temp artifacts once their Story lands. Classification is an allowlist: only the declared classes below are ever deleted, so operator scratch files under tempRoot are reported with their size and left alone. signals.ndjson is never purged by any path. |
@@ -210,8 +211,10 @@ Everything `/mandrel-deliver` and `single-story-close` consume: execution timeou
 | `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`, 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` | No | `object` | — | The two independent full-suite economies (Story #4981, split by Story #5173). `skipWhenUnchanged` (default true) decides WHETHER to capture — no changed file under `crap.targetDirs` versus `baseRef` means no capture at all — and is a pure saving. `baselineJoin` (default false) loosens gate semantics: the CRAP join resolves a method in an untouched file from its committed baseline row instead of requiring fresh coverage for it. Neither narrows the capture run itself: a capture that does happen is the ordinary full `npm run test:coverage` (Story #5065). |
+| `quality.gates.crap.incrementalCoverage.skipWhenUnchanged` | No | `boolean` | `true` | Skip the capture entirely when no changed file under `crap.targetDirs` versus `baseRef` was touched. The only measured saving, and gate-semantics-neutral. Defaults to true. |
+| `quality.gates.crap.incrementalCoverage.baselineJoin` | No | `boolean` | `false` | Let the CRAP join resolve a method in a file the diff did not touch from its committed baseline row instead of requiring fresh coverage for it. A gate loosening, not a saving — defaults to false. |
+| `quality.gates.crap.incrementalCoverage.enabled` | No | `boolean` | — | DEPRECATED alias for setting both `skipWhenUnchanged` and `baselineJoin`. Prefer the two switches: they are not equally safe, and bundling them is why the earlier default flip was reverted. Either explicit switch overrides this alias. |
 | `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

@@ -451,6 +451,11 @@
               "minimum": 1,
               "description": "Per-command timeout (ms) for the long-running spawns delivery drives — the close-validation chain and the gate CLIs.",
               "default": 600000
+            },
+            "fullSuiteLock": {
+              "type": "boolean",
+              "description": "Serialize full-suite spawns (`npm test` / `npm run test:coverage`) behind a host-level advisory lock, so two concurrent deliveries on one checkout do not run two suites against the same cores. Best-effort: a wait that expires spawns anyway, so the lock can never fail a delivery. Set false — or export `MANDREL_FULL_SUITE_LOCK=0` for one invocation — to disable.",
+              "default": true
             }
           },
           "additionalProperties": false
@@ -978,11 +983,21 @@
                     },
                     "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`, 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).",
+                      "description": "The two independent full-suite economies (Story #4981, split by Story #5173). `skipWhenUnchanged` (default true) decides WHETHER to capture — no changed file under `crap.targetDirs` versus `baseRef` means no capture at all — and is a pure saving. `baselineJoin` (default false) loosens gate semantics: the CRAP join resolves a method in an untouched file from its committed baseline row instead of requiring fresh coverage for it. Neither narrows the capture run itself: a capture that does happen is the ordinary full `npm run test:coverage` (Story #5065).",
                       "properties": {
+                        "skipWhenUnchanged": {
+                          "type": "boolean",
+                          "description": "Skip the capture entirely when no changed file under `crap.targetDirs` versus `baseRef` was touched. The only measured saving, and gate-semantics-neutral. Defaults to true.",
+                          "default": true
+                        },
+                        "baselineJoin": {
+                          "type": "boolean",
+                          "description": "Let the CRAP join resolve a method in a file the diff did not touch from its committed baseline row instead of requiring fresh coverage for it. A gate loosening, not a saving — defaults to false.",
+                          "default": false
+                        },
                         "enabled": {
                           "type": "boolean",
-                          "description": "Master switch for the capture skip and the baseline-resolved CRAP join."
+                          "description": "DEPRECATED alias for setting both `skipWhenUnchanged` and `baselineJoin`. Prefer the two switches: they are not equally safe, and bundling them is why the earlier default flip was reverted. Either explicit switch overrides this alias."
                         },
                         "baseRef": {
                           "type": "string",

package/.agents/schemas/validation-evidence.schema.json

@@ -38,10 +38,12 @@
               "format",
               "coverage-capture",
               "check-baselines",
+              "check-baselines-independent",
+              "check-baselines-coverage",
               "check-maintainability",
               "check-crap"
             ],
-            "description": "Stable gate identifier. Closed enum — additions require a schema bump. Must be a superset of every gate name buildDefaultGates() can emit (lib/close-validation/gates.js); tests/close-validation-gates-enum.test.js pins that gate-list ⊆ enum invariant. `coverage-capture` and `check-baselines` are the real close-validation gates (Story #4697); `check-maintainability` / `check-crap` are the retired per-kind gates (Story #2210) kept so historical evidence records still validate."
+            "description": "Stable gate identifier. Closed enum — additions require a schema bump. Must be a superset of every gate name buildDefaultGates() can emit (lib/close-validation/gates.js); tests/close-validation-gates-enum.test.js pins that gate-list ⊆ enum invariant. `coverage-capture` and `check-baselines` are the real close-validation gates (Story #4697); `check-baselines-independent` / `check-baselines-coverage` are the split pair the gate registers as when its enabled-kind set resolves (Story #5172), with `check-baselines` kept as both the unsplit fail-closed fallback and the historical name; `check-maintainability` / `check-crap` are the retired per-kind gates (Story #2210) kept so historical evidence records still validate."
           },
           "commitSha": {
             "type": "string",

package/.agents/scripts/acceptance-eval.js

@@ -57,8 +57,9 @@
  *   --no-signal               Suppress the signal emit (tests).
  *
  * Stdout: a single JSON envelope
- *   { storyId, epicId, decision, round, cap, capReached, totalCriteria,
- *     metCount, unmetCriteria[], signalEmitted, replay, verdictFingerprint }
+ *   { storyId, epicId, fullSuiteVerifyCommands[], decision, round, cap,
+ *     capReached, totalCriteria, metCount, unmetCriteria[], signalEmitted,
+ *     replay, verdictFingerprint }
  *   (`epicId` is retained as a always-null field for envelope stability.)
  *
  * Reading is free (Story #4874): re-invoking the gate over a verdict the
@@ -88,6 +89,10 @@ import {
   decideAcceptanceEval,
   resolveAcceptanceEvalRound,
 } from './lib/orchestration/acceptance-eval-decision.js';
+import {
+  FULL_SUITE_SHAPE_WARNING,
+  isFullSuiteCommand,
+} from './lib/orchestration/verify-credit.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
@@ -225,6 +230,58 @@ export function assertCriteriaCoverage(verdict, expectedCriteria) {
   );
 }
 
+/**
+ * Collect the distinct `verify[]` commands a verdict recorded that are
+ * themselves full-suite runs (Story #5174).
+ *
+ * The intended `verify[]` shape is scoped entries **plus** the one credited
+ * full-suite run the worker makes before the hand-off push. A full-suite
+ * command sitting in `verify[]` is the misshapen case: it either re-pays for
+ * the credited run or, worse, gets skipped as "already covered" without
+ * anyone saying so. The gate is where every round's evidence passes through,
+ * so it is where the shape is called out.
+ *
+ * Exported for tests.
+ *
+ * @param {object} verdict — schema-validated verdict.
+ * @returns {string[]} distinct offending commands, in first-seen order.
+ */
+export function collectFullSuiteVerifyCommands(verdict) {
+  const seen = new Set();
+  for (const criterion of verdict?.criteria ?? []) {
+    for (const evidence of criterion?.verifyEvidence ?? []) {
+      const command = evidence?.command;
+      if (typeof command === 'string' && isFullSuiteCommand(command)) {
+        seen.add(command.trim());
+      }
+    }
+  }
+  return [...seen];
+}
+
+/**
+ * Surface the misshapen-`verify[]` warning, if there is one.
+ *
+ * Extracted from `runAcceptanceEvalCli` rather than inlined: the CLI shell is
+ * already the file's worst-CRAP method, and a branch added there costs more
+ * than the same branch in a small, fully-covered helper. Module-private: it is
+ * reached through the CLI shell, which is where the tests drive it.
+ *
+ * @param {object} verdict — schema-validated verdict.
+ * @param {{ warn?: Function }} logger
+ * @returns {string[]} the offending commands (empty when the shape is fine).
+ */
+function warnOnFullSuiteVerify(verdict, logger) {
+  const commands = collectFullSuiteVerifyCommands(verdict);
+  if (commands.length > 0) {
+    logger?.warn?.(
+      `acceptance-eval: verify[] carries full-suite command(s) ${commands.join(', ')}. ` +
+        FULL_SUITE_SHAPE_WARNING,
+    );
+  }
+  return commands;
+}
+
 /**
  * Compose the operator-facing envelope and emit the per-criterion signal.
  *
@@ -304,9 +361,12 @@ export async function runAcceptanceEval(
     }
   }
 
+  const fullSuiteVerifyCommands = collectFullSuiteVerifyCommands(verdict);
+
   const envelope = {
     storyId: storyId ?? null,
     epicId: null,
+    fullSuiteVerifyCommands,
     decision: outcome.decision,
     round: outcome.round,
     cap: outcome.cap,
@@ -349,7 +409,7 @@ export async function runAcceptanceEval(
  *   resolveConfigImpl?: typeof resolveConfig,
  *   validateVerdictImpl?: typeof validateVerdict,
  *   runAcceptanceEvalImpl?: typeof runAcceptanceEval,
- *   logger?: { info: Function },
+ *   logger?: { info: Function, warn?: Function },
  * }} [deps]
  * @returns {Promise<object>} the emitted envelope.
  */
@@ -414,6 +474,11 @@ export async function runAcceptanceEvalCli(
     );
   }
 
+  // Story #5174 — the shape warning is derived from the VALIDATED verdict, not
+  // from the envelope, so it fires for the real decision path and for every
+  // caller that injects its own scorer.
+  warnOnFullSuiteVerify(verdict, logger);
+
   const config = resolveConfigImpl();
   const { envelope, exitCode } = await runAcceptanceEvalImpl({
     storyId,

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

@@ -12,8 +12,15 @@
  *   3. Test freshness: content digest of `crap.targetDirs` vs. the persisted
  *      capture stamp (`coverage/.capture-stamp.json`), falling back to the
  *      artifact-mtime heuristic when no stamp exists. Exit 0 when fresh.
- *   4. Otherwise spawn `npm run test:coverage`, write a fresh capture stamp
- *      on success, and propagate the exit code.
+ *   4. Otherwise spawn `npm run test:coverage` — serialized behind the
+ *      host-level full-suite lock (Story #5173) so two concurrent runs on one
+ *      checkout do not race — write a fresh capture stamp on success, and
+ *      propagate the exit code.
+ *
+ * Step 3 is preceded by the changed-file skip when
+ * `delivery.quality.gates.crap.incrementalCoverage.skipWhenUnchanged` is on
+ * (the default): no changed file under `crap.targetDirs` versus `baseRef`
+ * means no capture at all.
  *
  * Exit codes:
  *   0 — coverage is fresh (or capture skipped/succeeded).
@@ -34,6 +41,7 @@ import {
 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 { lockedCapture } from './lib/full-suite-lock.js';
 
 import { Logger } from './lib/Logger.js';
 import { hasNpmScript, readPackageScripts } from './lib/npm-scripts.js';
@@ -124,10 +132,19 @@ export function runCoverageCapture(argv = process.argv, deps = {}) {
     return 1;
   }
 
-  // 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.
+  // Story #5173 — the host-level full-suite lock. Resolved once here, where
+  // the config is already in scope, and composed over the capture runner so
+  // whichever path reaches the spawn is serialized without either of them
+  // knowing about it. `delivery.execution.fullSuiteLock: false` and
+  // `MANDREL_FULL_SUITE_LOCK=0` each disable it; both hatches live in
+  // `isFullSuiteLockEnabled`.
+  const capture = lockedCapture(runCaptureImpl, config);
+
+  // Story #4981/#5173 — the capture skip, gated by
+  // `delivery.quality.gates.crap.incrementalCoverage.skipWhenUnchanged` (on
+  // by default). `null` means "not applicable" (switched off, or a
+  // ref-resolution error) — fall through to the full-scope path below rather
+  // than silently skipping capture.
   const incrementalResult = tryIncrementalCapture({
     crap,
     coverage,
@@ -135,7 +152,7 @@ export function runCoverageCapture(argv = process.argv, deps = {}) {
     getChangedFilesImpl,
     filterFilesUnderTargetsImpl,
     isCoverageFreshImpl,
-    runCaptureImpl,
+    runCaptureImpl: capture,
     computeContentDigestImpl,
     writeCaptureStampImpl,
     logger,
@@ -148,7 +165,7 @@ export function runCoverageCapture(argv = process.argv, deps = {}) {
     args,
     getChangedFilesImpl,
     isCoverageFreshImpl,
-    runCaptureImpl,
+    runCaptureImpl: capture,
     computeContentDigestImpl,
     writeCaptureStampImpl,
     logger,

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

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

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

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