mandrel 2.16.0 → 2.18.0

package/.agents/scripts/lib/crap-utils.js

@@ -2,15 +2,15 @@ import fs from 'node:fs';
 import path from 'node:path';
 import escomplex from 'typhonjs-escomplex';
 import { canonicalise as canonicalisePath } from './baselines/path-canon.js';
-import {
-  coverageForMethodInEntry,
-  findCoverageEntry,
-} from './coverage-utils.js';
+import { findCoverageEntry } from './coverage-utils.js';
 import { POOL_SERIAL_THRESHOLD, runOnPool } from './cpu-pool.js';
-import { crapFormula } from './crap-engine.js';
+import { finalizeMethodRows, methodRowsFromReport } from './crap-engine.js';
 import { Logger } from './Logger.js';
 import { scanDirectory } from './maintainability-utils.js';
-import { resolveTsTranspilerVersion, transpileIfNeeded } from './transpile.js';
+import {
+  prepareSourceForScoring,
+  resolveTsTranspilerVersion,
+} from './transpile.js';
 
 const CRAP_WORKER_URL = new URL('./workers/crap-worker.js', import.meta.url);
 const COMBINED_MI_CRAP_WORKER_URL = new URL(
@@ -201,6 +201,103 @@ export function buildBaselineEnvelope({
   };
 }
 
+/**
+ * How many files to name when reporting the worst unresolved offenders. Long
+ * enough to point at a pattern, short enough to stay a readable CLI message.
+ */
+const WORST_OFFENDER_LIMIT = 5;
+
+/**
+ * Method-resolution telemetry (Story #4775, fix part 4).
+ *
+ * The updater used to persist a 100-row baseline built from 5023 dropped
+ * methods and log it as success — the rot that let a broken coverage join
+ * sit undetected for five weeks across three repos. These three helpers
+ * carry the counters that make a thin result *visible* and therefore
+ * refusable.
+ *
+ * The rate is deliberately measured over files that **do** have a coverage
+ * entry: a file the test run never touched has no join to fail, so counting
+ * it would dilute the signal the floor is meant to catch.
+ */
+function newResolutionAccumulator() {
+  return { resolved: 0, total: 0, byFile: [] };
+}
+
+function accumulateResolution(acc, relPath, result) {
+  if (result?.hasCoverageEntry !== true) return;
+  const total = result.totalMethods ?? 0;
+  if (total === 0) return;
+  const resolved = result.resolvedMethods ?? 0;
+  acc.resolved += resolved;
+  acc.total += total;
+  if (resolved < total) {
+    acc.byFile.push({ file: relPath, unresolved: total - resolved, total });
+  }
+}
+
+function summarizeResolution(acc) {
+  const worstFiles = [...acc.byFile]
+    .sort((a, b) => b.unresolved - a.unresolved || a.file.localeCompare(b.file))
+    .slice(0, WORST_OFFENDER_LIMIT);
+  return {
+    resolvedMethods: acc.resolved,
+    joinableMethods: acc.total,
+    rate: acc.total === 0 ? 1 : acc.resolved / acc.total,
+    worstFiles,
+  };
+}
+
+/**
+ * Minimum number of joinable methods before the resolution-rate floor is
+ * enforced. A diff-scoped run can legitimately touch a handful of methods,
+ * where one unresolved method is a 50% rate and says nothing about the health
+ * of the join. Below this sample the rate is reported, never enforced.
+ */
+const MIN_RESOLUTION_SAMPLE = 25;
+
+/**
+ * Fail-closed guard on the per-method coverage join (Story #4775, fix part 4).
+ *
+ * The updater used to persist a 100-row baseline distilled from 5023 dropped
+ * methods and log it as a success — which is exactly how a broken join stayed
+ * invisible for five weeks across three repositories. A thin result is now a
+ * refusal: the caller throws before anything is written, and the message names
+ * the rate, the counts, and the files carrying the most unresolved methods so
+ * the operator can tell "my tests do not cover that" apart from "the join is
+ * broken".
+ *
+ * Returns `null` when the run may proceed, or the operator-facing message when
+ * it must not.
+ *
+ * @param {{resolvedMethods: number, joinableMethods: number, rate: number,
+ *   worstFiles: Array<{file: string, unresolved: number, total: number}>}
+ *   | undefined} resolution
+ * @param {number} floor
+ * @returns {string|null}
+ */
+export function checkResolutionFloor(resolution, floor) {
+  if (!resolution) return null;
+  const { joinableMethods = 0, resolvedMethods = 0, rate = 1 } = resolution;
+  if (joinableMethods < MIN_RESOLUTION_SAMPLE) return null;
+  if (rate >= floor) return null;
+  const worst = (resolution.worstFiles ?? [])
+    .map((w) => `         - ${w.file} (${w.unresolved}/${w.total} unresolved)`)
+    .join('\n');
+  return (
+    `[CRAP] Refusing to persist: only ${resolvedMethods}/${joinableMethods} ` +
+    `method(s) (${(rate * 100).toFixed(1)}%) resolved a coverage entry in files ` +
+    `that HAVE coverage — below the ${(floor * 100).toFixed(1)}% floor ` +
+    '(delivery.quality.gates.crap.minMethodResolutionRate).\n' +
+    '       A baseline built from a broken join is not sparse, it is wrong: ' +
+    'unresolved methods are absent and coincidental line collisions are ' +
+    'mis-attributed.\n' +
+    (worst ? `       Worst unresolved files:\n${worst}\n` : '') +
+    "       Regenerate coverage ('npm run test:coverage') and re-run; if the " +
+    'rate stays low the coverage artifact and the scanned tree disagree.'
+  );
+}
+
 /**
  * Parse `source` exactly once with escomplex and derive both the
  * maintainability score and the raw CRAP method rows from that single report.
@@ -216,6 +313,10 @@ export function buildBaselineEnvelope({
  *
  * @param {string} source Prepared (possibly transpiled) JavaScript source text.
  * @param {object|null} coverageForFile Istanbul coverage entry for this file.
+ * @param {((line: number) => number|null)|null} [mapLine] Transpiled →
+ *   original-source line resolver from `transpileIfNeeded(…, {withLineMap:
+ *   true})`; `null` for JavaScript, whose coordinates already match the
+ *   coverage entry's.
  * @returns {{
  *   report: object,
  *   miScore: number,
@@ -229,7 +330,7 @@ export function buildBaselineEnvelope({
  *   parseError: boolean,
  * }}
  */
-export function analyzeOnce(source, coverageForFile) {
+export function analyzeOnce(source, coverageForFile, mapLine = null) {
   let report;
   try {
     report = escomplex.analyzeModule(source);
@@ -238,18 +339,7 @@ export function analyzeOnce(source, coverageForFile) {
   }
   const miScore =
     typeof report.maintainability === 'number' ? report.maintainability : 0;
-  const methods = report?.methods ?? [];
-  const crapRows = [];
-  for (const m of methods) {
-    const startLine = m?.lineStart;
-    if (typeof startLine !== 'number') continue;
-    const cyclomatic = m?.cyclomatic ?? 0;
-    const coverage = coverageForFile
-      ? coverageForMethodInEntry(coverageForFile, startLine)
-      : null;
-    const crap = coverage === null ? null : crapFormula(cyclomatic, coverage);
-    crapRows.push({ method: m.name, startLine, cyclomatic, coverage, crap });
-  }
+  const crapRows = methodRowsFromReport(report, coverageForFile, mapLine);
   return { report, miScore, crapRows, parseError: false };
 }
 
@@ -348,6 +438,7 @@ export async function scanAndScore({
   const rows = [];
   let skippedFilesNoCoverage = 0;
   let skippedMethodsNoCoverage = 0;
+  const resolution = newResolutionAccumulator();
   for (const { item, result } of perFile) {
     if (!result) continue; // unrecoverable per-file failure: drop silently to match pre-pool semantics
     if (result.skippedFileNoCoverage) {
@@ -366,6 +457,7 @@ export async function scanAndScore({
       continue;
     }
     skippedMethodsNoCoverage += result.skippedMethodsNoCoverage ?? 0;
+    accumulateResolution(resolution, item.relPath, result);
     for (const mr of result.rows) {
       rows.push({
         file: item.relPath,
@@ -390,6 +482,7 @@ export async function scanAndScore({
     scannedFiles,
     skippedFilesNoCoverage,
     skippedMethodsNoCoverage,
+    resolution: summarizeResolution(resolution),
   };
 }
 
@@ -408,50 +501,33 @@ function scoreFileSerial({ abs, relPath, requireCoverage }, coverage) {
       skippedFileNoCoverage: true,
       rows: [],
       skippedMethodsNoCoverage: 0,
+      hasCoverageEntry: false,
+      resolvedMethods: 0,
+      totalMethods: 0,
     };
   }
-  let source;
-  try {
-    source = fs.readFileSync(abs, 'utf-8');
-  } catch {
-    return {
-      skippedFileNoCoverage: false,
-      rows: null,
-      skippedMethodsNoCoverage: 0,
-    };
-  }
-  const prepared = transpileIfNeeded(abs, source);
-  if (prepared === null) {
-    return {
-      skippedFileNoCoverage: false,
-      rows: null,
-      skippedMethodsNoCoverage: 0,
-    };
-  }
-  const { crapRows, parseError } = analyzeOnce(prepared, entry);
-  if (parseError) {
-    return {
-      skippedFileNoCoverage: false,
-      rows: null,
-      skippedMethodsNoCoverage: 0,
-    };
-  }
-  const rows = [];
-  let skippedMethodsNoCoverage = 0;
-  for (const mr of crapRows) {
-    if (mr.crap === null || mr.coverage === null) {
-      skippedMethodsNoCoverage += 1;
-      continue;
-    }
-    rows.push({
-      method: mr.method,
-      startLine: mr.startLine,
-      cyclomatic: mr.cyclomatic,
-      coverage: mr.coverage,
-      crap: mr.crap,
-    });
-  }
-  return { skippedFileNoCoverage: false, rows, skippedMethodsNoCoverage };
+  const dropped = {
+    skippedFileNoCoverage: false,
+    rows: null,
+    skippedMethodsNoCoverage: 0,
+    hasCoverageEntry: entry !== null,
+    resolvedMethods: 0,
+    totalMethods: 0,
+  };
+  const prepared = prepareSourceForScoring(abs);
+  if (prepared.error) return dropped;
+  const { crapRows, parseError } = analyzeOnce(
+    prepared.code,
+    entry,
+    prepared.mapLine,
+  );
+  if (parseError) return dropped;
+  const finalized = finalizeMethodRows(crapRows, { requireCoverage });
+  return {
+    skippedFileNoCoverage: false,
+    hasCoverageEntry: entry !== null,
+    ...finalized,
+  };
 }
 
 async function scoreFilesViaPool(queue, coverage) {
@@ -494,33 +570,24 @@ async function scoreFilesViaPool(queue, coverage) {
  */
 function scoreFileCombinedSerial({ abs, relPath, requireCoverage }, coverage) {
   const entry = findCoverageEntry(coverage, relPath);
-  let source;
-  try {
-    source = fs.readFileSync(abs, 'utf-8');
-  } catch {
-    return {
-      relPath,
-      miScore: null,
-      skippedFileNoCoverage: false,
-      crapRows: null,
-      skippedMethodsNoCoverage: 0,
-    };
-  }
-  const prepared = transpileIfNeeded(abs, source);
-  if (prepared === null) {
+  const prepared = prepareSourceForScoring(abs);
+  if (prepared.error) {
     return {
       relPath,
-      miScore: 0,
+      miScore: prepared.error === 'read' ? null : 0,
       skippedFileNoCoverage: false,
       crapRows: null,
       skippedMethodsNoCoverage: 0,
+      hasCoverageEntry: entry !== null,
+      resolvedMethods: 0,
+      totalMethods: 0,
     };
   }
   const {
     miScore,
     crapRows: rawCrapRows,
     parseError,
-  } = analyzeOnce(prepared, entry);
+  } = analyzeOnce(prepared.code, entry, prepared.mapLine);
   if (parseError) {
     return {
       relPath,
@@ -528,6 +595,9 @@ function scoreFileCombinedSerial({ abs, relPath, requireCoverage }, coverage) {
       skippedFileNoCoverage: false,
       crapRows: null,
       skippedMethodsNoCoverage: 0,
+      hasCoverageEntry: entry !== null,
+      resolvedMethods: 0,
+      totalMethods: 0,
     };
   }
   if (requireCoverage && entry === null) {
@@ -537,29 +607,22 @@ function scoreFileCombinedSerial({ abs, relPath, requireCoverage }, coverage) {
       skippedFileNoCoverage: true,
       crapRows: [],
       skippedMethodsNoCoverage: 0,
+      hasCoverageEntry: false,
+      resolvedMethods: 0,
+      totalMethods: 0,
     };
   }
-  const crapRows = [];
-  let skippedMethodsNoCoverage = 0;
-  for (const mr of rawCrapRows) {
-    if (mr.crap === null || mr.coverage === null) {
-      skippedMethodsNoCoverage += 1;
-      continue;
-    }
-    crapRows.push({
-      method: mr.method,
-      startLine: mr.startLine,
-      cyclomatic: mr.cyclomatic,
-      coverage: mr.coverage,
-      crap: mr.crap,
-    });
-  }
+  const { rows, skippedMethodsNoCoverage, resolvedMethods, totalMethods } =
+    finalizeMethodRows(rawCrapRows, { requireCoverage });
   return {
     relPath,
     miScore,
     skippedFileNoCoverage: false,
-    crapRows,
+    crapRows: rows,
     skippedMethodsNoCoverage,
+    hasCoverageEntry: entry !== null,
+    resolvedMethods,
+    totalMethods,
   };
 }
 
@@ -693,6 +756,7 @@ export async function scanAndScoreCombined({
   const crapRows = [];
   let skippedFilesNoCoverage = 0;
   let skippedMethodsNoCoverage = 0;
+  const resolution = newResolutionAccumulator();
 
   for (const { item, result } of perFile) {
     if (!result) continue; // unrecoverable per-file failure: drop silently
@@ -716,6 +780,7 @@ export async function scanAndScoreCombined({
       continue;
     }
     skippedMethodsNoCoverage += result.skippedMethodsNoCoverage ?? 0;
+    accumulateResolution(resolution, item.relPath, result);
     for (const mr of result.crapRows) {
       crapRows.push({
         file: item.relPath,
@@ -750,6 +815,7 @@ export async function scanAndScoreCombined({
       scannedFiles,
       skippedFilesNoCoverage,
       skippedMethodsNoCoverage,
+      resolution: summarizeResolution(resolution),
     },
   };
 }

package/.agents/scripts/lib/dynamic-workflow/audit-orchestrator.js

@@ -26,6 +26,18 @@
  * single write in the run is the report artifact, performed by the synthesis
  * agent, which is granted the read-only allowlist plus `Write`.
  *
+ * ## Partial-failure posture
+ *
+ * The per-dimension fan-out is settled, not all-or-nothing (Story #4783). One
+ * rejected dimension used to discard every sibling's completed work; the
+ * engine now partitions the settled results, flows the fulfilled dimensions on
+ * to the next phase, and records the rejected ones as an explicit
+ * degraded-coverage note in the report's Executive Summary. This mirrors the
+ * posture `close-validation/runner.js` already takes with per-gate errors:
+ * capture the failure into the result rather than rejecting the whole run.
+ * Only a *total* loss — every dimension rejected — throws, because there is
+ * then nothing to synthesise.
+ *
  * ## Report-contract self-check
  *
  * After synthesis the engine calls the caller-supplied `assertReportContract`
@@ -43,6 +55,14 @@
  * @module dynamic-workflow/audit-orchestrator
  */
 
+import { withDegradedCoverageNote } from './degraded-coverage.js';
+
+/**
+ * A dimension that did not complete, as recorded by the settled fan-out.
+ *
+ * @typedef {import('./degraded-coverage.js').DimensionFailure} DimensionFailure
+ */
+
 /**
  * The live dynamic-workflow runtime context the host passes to a saved
  * `.claude/workflows/*.workflow.js` entry point. Re-exported as a typedef so
@@ -82,8 +102,11 @@
  *   Compose the analysis prompt for one dimension (lens-specific).
  * @property {(dimension: string, findings: string) => string} buildCrossCheckPrompt
  *   Compose the adversarial cross-check prompt for one dimension's findings.
- * @property {(crossCheckedBlocks: string[]) => string} buildSynthesisPrompt
- *   Compose the synthesis prompt that assembles the report and writes it.
+ * @property {(crossCheckedBlocks: string[], degraded: DimensionFailure[]) => string} buildSynthesisPrompt
+ *   Compose the synthesis prompt that assembles the report and writes it. The
+ *   second argument lists the dimensions that did not complete (empty on a
+ *   full-coverage run); lenses may ignore it — the engine annotates the report
+ *   with the degraded-coverage note either way.
  * @property {(report: string) => { conformant: boolean, missingSections: string[], hasTitle: boolean }} assertReportContract
  *   Self-check the synthesised report against the lens's report contract.
  * @property {(check: { conformant: boolean, missingSections: string[], hasTitle: boolean }) => string} [formatContractError]
@@ -122,6 +145,45 @@ export function defaultContractError(check) {
   return `report failed contract check: missing ${titlePart}sections=[${sections}]`;
 }
 
+/**
+ * Reduce a rejection reason to a single-line message.
+ *
+ * @param {unknown} reason
+ * @returns {string}
+ */
+function describeRejection(reason) {
+  if (reason instanceof Error) return reason.message;
+  return String(reason ?? 'unknown error');
+}
+
+/**
+ * Partition settled fan-out results into the values that completed and the
+ * dimensions that did not. `dimensions[i]` names the dimension behind
+ * `settled[i]`, so a rejection is always attributable.
+ *
+ * @template T
+ * @param {readonly string[]} dimensions
+ * @param {readonly PromiseSettledResult<T>[]} settled
+ * @param {string} phaseName Phase recorded on each failure.
+ * @returns {{ fulfilled: T[], failures: DimensionFailure[] }}
+ */
+function partitionSettled(dimensions, settled, phaseName) {
+  const fulfilled = [];
+  const failures = [];
+  settled.forEach((result, index) => {
+    if (result.status === 'fulfilled') {
+      fulfilled.push(result.value);
+      return;
+    }
+    failures.push({
+      dimension: dimensions[index],
+      phase: phaseName,
+      reason: describeRejection(result.reason),
+    });
+  });
+  return { fulfilled, failures };
+}
+
 /**
  * Run the shared three-phase audit-lens orchestration: parallel per-dimension
  * analysis → adversarial cross-check → synthesis + report-contract self-check.
@@ -149,9 +211,10 @@ export async function runAuditOrchestration(spec) {
 
   const { agent, phase } = ctx;
 
-  // Phase 1 — parallel per-dimension analysis (read-only agents).
-  const rawFindings = await phase(ORCHESTRATION_PHASES.ANALYZE, async () =>
-    Promise.all(
+  // Phase 1 — parallel per-dimension analysis (read-only agents). Settled, not
+  // all-or-nothing: one dimension's rejection must not discard its siblings.
+  const analyzed = await phase(ORCHESTRATION_PHASES.ANALYZE, async () =>
+    Promise.allSettled(
       dimensions.map(async (dimension) => {
         const { output } = await agent({
           prompt: buildDimensionPrompt(dimension),
@@ -161,11 +224,15 @@ export async function runAuditOrchestration(spec) {
       }),
     ),
   );
+  const { fulfilled: rawFindings, failures: analyzeFailures } =
+    partitionSettled(dimensions, analyzed, 'analyze');
 
   // Phase 2 — adversarial cross-check: an independent agent re-verifies each
-  // dimension's findings and filters false positives before inclusion.
-  const crossChecked = await phase(ORCHESTRATION_PHASES.CROSS_CHECK, async () =>
-    Promise.all(
+  // surviving dimension's findings and filters false positives before
+  // inclusion. Settled for the same reason as phase 1.
+  const checkedDimensions = rawFindings.map((entry) => entry.dimension);
+  const checked = await phase(ORCHESTRATION_PHASES.CROSS_CHECK, async () =>
+    Promise.allSettled(
       rawFindings.map(async ({ dimension, findings }) => {
         const { output } = await agent({
           prompt: buildCrossCheckPrompt(dimension, findings),
@@ -175,18 +242,38 @@ export async function runAuditOrchestration(spec) {
       }),
     ),
   );
+  const { fulfilled: crossChecked, failures: crossCheckFailures } =
+    partitionSettled(checkedDimensions, checked, 'cross-check');
+
+  const degraded = [...analyzeFailures, ...crossCheckFailures];
+  if (dimensions.length > 0 && crossChecked.length === 0) {
+    // Nothing survived — there is no partial report to salvage.
+    throw new Error(
+      `every audit dimension failed: ${degraded
+        .map((f) => `${f.dimension} (${f.phase}: ${f.reason})`)
+        .join('; ')}`,
+    );
+  }
 
   // Phase 3 — synthesis: assemble the report contract and write the artifact.
-  const { output: report } = await phase(
+  const { output: synthesised } = await phase(
     ORCHESTRATION_PHASES.SYNTHESIZE,
     async () =>
       agent({
-        prompt: buildSynthesisPrompt(crossChecked),
+        prompt: buildSynthesisPrompt(crossChecked, degraded),
         // Synthesis is the one stage permitted to write the report artifact.
         allowedTools: [...readOnlyTools, SYNTHESIS_WRITE_TOOL],
       }),
   );
 
+  // The coverage gap is annotated by the engine, never left to the synthesis
+  // agent's discretion.
+  const report = withDegradedCoverageNote(
+    synthesised,
+    degraded,
+    dimensions.length,
+  );
+
   // Self-verify report-contract conformance before returning.
   const check = assertReportContract(report);
   if (!check.conformant) {

package/.agents/scripts/lib/dynamic-workflow/degraded-coverage.js

@@ -0,0 +1,81 @@
+// .agents/scripts/lib/dynamic-workflow/degraded-coverage.js
+/**
+ * Degraded-coverage annotation for audit-lens reports (Story #4783).
+ *
+ * An audit lens fans out one sub-agent per analysis dimension. When one of
+ * those dimensions rejects — a sub-agent that ran out of context, a
+ * measurement command that failed, a transient runtime error — the run used to
+ * discard every sibling dimension's completed work along with it.
+ *
+ * The engine now partitions instead: the fulfilled dimensions flow on to
+ * synthesis, and the rejected ones are recorded here as an explicit note in
+ * the report's Executive Summary. A lens that covers four of five dimensions
+ * *and says which one is missing* is strictly more useful than one that yields
+ * nothing — but only if the gap is visible. An unannotated partial report is
+ * worse than no report, because it reads as complete coverage.
+ *
+ * The annotation is applied by the engine, not requested of the synthesis
+ * agent: a coverage disclaimer that depends on an LLM remembering to write it
+ * is not a disclaimer.
+ *
+ * @module dynamic-workflow/degraded-coverage
+ */
+
+/**
+ * A dimension that did not complete.
+ *
+ * @typedef {object} DimensionFailure
+ * @property {string} dimension The analysis dimension that failed.
+ * @property {string} phase     The phase it failed in (`analyze` / `cross-check`).
+ * @property {string} reason    The rejection's message.
+ */
+
+/** Matches the Executive Summary heading at any heading level. */
+const EXECUTIVE_SUMMARY_HEADING = /^#{1,6}\s+Executive Summary\b/i;
+
+/**
+ * Render the degraded-coverage note. Names every failed dimension, the phase
+ * it failed in, and the reason, so a reader can tell coverage loss apart from
+ * an absence of findings.
+ *
+ * @param {readonly DimensionFailure[]} failures
+ * @param {number} totalDimensions Dimensions the run set out to cover.
+ * @returns {string} A markdown blockquote.
+ */
+function formatDegradedCoverageNote(failures, totalDimensions) {
+  const detail = failures
+    .map((f) => `**${f.dimension}** (${f.phase}: ${f.reason})`)
+    .join('; ');
+  const noun = failures.length === 1 ? 'dimension' : 'dimensions';
+  return [
+    `> ⚠️ **Degraded coverage** — ${failures.length} of ${totalDimensions} analysis ${noun} did not complete`,
+    `> and ${failures.length === 1 ? 'is' : 'are'} unrepresented in this report: ${detail}.`,
+    '> Findings for the remaining dimensions are complete; the gap above is not evidence of their absence.',
+  ].join('\n');
+}
+
+/**
+ * Annotate a synthesised report with the degraded-coverage note, inserted
+ * directly beneath the `## Executive Summary` heading (every lens report
+ * contract requires that section). A report without the heading is prefixed
+ * instead, so the note can never be silently dropped.
+ *
+ * Returns the report unchanged when nothing failed — a full-coverage run must
+ * not carry a coverage caveat.
+ *
+ * @param {string} report
+ * @param {readonly DimensionFailure[]} failures
+ * @param {number} totalDimensions
+ * @returns {string}
+ */
+export function withDegradedCoverageNote(report, failures, totalDimensions) {
+  if (!Array.isArray(failures) || failures.length === 0) return report;
+  const note = formatDegradedCoverageNote(failures, totalDimensions);
+  const lines = String(report).split('\n');
+  const headingIndex = lines.findIndex((line) =>
+    EXECUTIVE_SUMMARY_HEADING.test(line.trim()),
+  );
+  if (headingIndex === -1) return `${note}\n\n${report}`;
+  lines.splice(headingIndex + 1, 0, '', note);
+  return lines.join('\n');
+}

package/.agents/scripts/lib/git-branch-lifecycle.js

@@ -134,16 +134,22 @@ export function classifyBranchSeed({ localHas, remoteHas }) {
  *
  * Caller-specific log lines and error text are passed in as the `messages`
  * data bag so behaviour stays byte-identical to the pre-extraction switches.
- * The git seams (`spawn`, `existsLocally`, `existsRemotely`) are injected so
- * each caller can bind its own cwd (and tests can mock them).
+ * The git seams (`spawn`, `existsLocally`, `existsRemotely`) are injectable so
+ * each caller can bind its own cwd (and tests can substitute stubs through the
+ * parameter rather than by module mocking). Per
+ * `.agents/rules/test-seams.md` rule 1 each seam **defaults to the real
+ * implementation** bound to `cwd`, so a caller that only knows its checkout
+ * passes `cwd` and nothing else; `single-story-init.js` keeps passing its own
+ * pre-bound seams and is unaffected.
  *
  * @param {object} opts
  * @param {string} opts.storyBranch
  * @param {string} opts.baseRef            Ref to branch from on `create`.
+ * @param {string} [opts.cwd]              Checkout the default seams bind to.
  * @param {boolean} [opts.swallowCreateRace=false]
- * @param {(args: string[]) => { status: number, stdout?: string, stderr?: string }} opts.spawn
- * @param {(branch: string) => boolean} opts.existsLocally
- * @param {(branch: string) => boolean} opts.existsRemotely
+ * @param {(args: string[]) => { status: number, stdout?: string, stderr?: string }} [opts.spawn]
+ * @param {(branch: string) => boolean} [opts.existsLocally]
+ * @param {(branch: string) => boolean} [opts.existsRemotely]
  * @param {(level: string, message: string) => void} [opts.progress]
  * @param {object} opts.messages
  * @param {(b: string) => string} opts.messages.reuse
@@ -158,10 +164,11 @@ export function classifyBranchSeed({ localHas, remoteHas }) {
 export function seedStoryBranchRef({
   storyBranch,
   baseRef,
+  cwd,
   swallowCreateRace = false,
-  spawn,
-  existsLocally,
-  existsRemotely,
+  spawn = (args) => gitSpawn(cwd, ...args),
+  existsLocally = (branch) => branchExistsLocally(branch, cwd),
+  existsRemotely = (branch) => branchExistsViaTrackingRef(branch, cwd),
   progress = () => {},
   messages,
 }) {