mandrel 1.57.0

package/.agents/scripts/lib/orchestration/story-close/baseline-attribution/phases/regression-projection.js

@@ -0,0 +1,266 @@
+/**
+ * regression-projection.js — phase 2 of baseline-attribution.
+ *
+ * For each baseline-style gate (`check-maintainability`, `check-crap`),
+ * re-derive the per-file/per-method regression rows that `runPreMergeGates`
+ * would have surfaced on failure. These rows feed the attribution
+ * classifier downstream so attributable rows can trigger a refresh and
+ * non-attributable rows can route to a friction comment.
+ *
+ * Two projectors live here:
+ *
+ *   - `projectMaintainabilityForGate` — reuses the MI projection from
+ *     `close-validation.js` (Story #874).
+ *   - `projectCrapForGate` / `projectCrapRegressions` — diff CRAP envelopes
+ *     at `origin/<epicBranch>` vs `storyBranch`, optionally scoped to the
+ *     Story's touched files (Story #1124).
+ */
+
+import { readBaselineAtRef as defaultReadBaselineAtRef } from '../../../../baseline-loader.js';
+import { projectMaintainabilityRegressions as defaultProjectMaintainabilityRegressions } from '../../../../close-validation.js';
+import { getBaselines as defaultGetBaselines } from '../../../../config-resolver.js';
+import {
+  computeStoryDiffPaths,
+  validateProjectionContext,
+} from './scope-discovery.js';
+
+/**
+ * Default CRAP regression tolerance — mirrors `check-crap.js`. Score noise
+ * floor is ~0.01 from coverage rounding shifts across Node/V8 builds; a
+ * 0.05 tolerance clears that without admitting real regressions (those
+ * cross whole-integer thresholds and clear 0.05 trivially).
+ */
+const DEFAULT_CRAP_TOLERANCE = 0.05;
+
+function coerceScopeSet(touchedFiles) {
+  if (touchedFiles == null) return null;
+  if (touchedFiles instanceof Set) return touchedFiles;
+  return new Set(touchedFiles);
+}
+
+// Story #1895: rows from the canonical envelope key by `path`; legacy
+// rows key by `file`. Accept either so this attribution layer keeps
+// working while the Epic migrates consumers off the legacy shape.
+function rowFileKey(row) {
+  if (!row) return null;
+  if (typeof row.file === 'string') return row.file;
+  if (typeof row.path === 'string') return row.path;
+  return null;
+}
+
+function indexCrapBaselineByMethod(baselineRows) {
+  const byMethod = new Map();
+  for (const b of baselineRows) {
+    const f = rowFileKey(b);
+    if (!f || typeof b.method !== 'string') continue;
+    const key = `${f}::${b.method}`;
+    if (!byMethod.has(key)) byMethod.set(key, []);
+    byMethod.get(key).push(b);
+  }
+  return byMethod;
+}
+
+function pickClosestUnseen(candidates, headStartLine, seen) {
+  let pick = null;
+  let bestDist = Number.POSITIVE_INFINITY;
+  for (const c of candidates) {
+    const f = rowFileKey(c);
+    const k = `${f}::${c.method}@${c.startLine}`;
+    if (seen.has(k)) continue;
+    const d = Math.abs((c.startLine ?? 0) - (headStartLine ?? 0));
+    if (d < bestDist) {
+      bestDist = d;
+      pick = c;
+    }
+  }
+  return pick;
+}
+
+function isValidHeadRow(row) {
+  return Boolean(row && rowFileKey(row) && typeof row.method === 'string');
+}
+
+function buildCrapRegression(row, pick) {
+  const headCrap = typeof row.crap === 'number' ? row.crap : 0;
+  const baseCrap = typeof pick.crap === 'number' ? pick.crap : 0;
+  const f = rowFileKey(row);
+  return {
+    file: f,
+    path: f,
+    method: row.method,
+    startLine: row.startLine,
+    crap: headCrap,
+    projected: headCrap,
+    baseline: baseCrap,
+    drop: headCrap - baseCrap,
+    headCrap,
+    baseCrap,
+  };
+}
+
+/**
+ * Pure helper — given two CRAP baseline envelopes (`{ rows: [...] }`), produce
+ * the regression rows for methods whose `crap` score increased beyond
+ * `tolerance` between `baselineRows` and `headRows`. When `touchedFiles` is
+ * supplied (as a Set or array of repo-relative POSIX paths), rows are filtered
+ * to functions inside files the Story changed — sibling drift outside the
+ * Story's diff is excluded by construction, matching the maintainability
+ * projector's "touched-only" contract.
+ *
+ * Row shape mirrors the maintainability projector — `{ file, method,
+ * startLine, crap, baseline, drop, projected }` — so downstream attribution
+ * + refresh-commit logic (`classifyBaselineDrift`,
+ * `renderBaselineFrictionBody`) can read either projector's output with the
+ * same field accessors. `projected` is an alias for `crap` retained for
+ * shape compatibility with maintainability rows.
+ *
+ * Exported so unit tests can pin the diff math against a fixture pair of
+ * baseline envelopes without spawning `git`.
+ */
+export function diffCrapBaselines({
+  baselineRows,
+  headRows,
+  touchedFiles = null,
+  tolerance = DEFAULT_CRAP_TOLERANCE,
+} = {}) {
+  if (!Array.isArray(baselineRows) || !Array.isArray(headRows)) return [];
+  const scope = coerceScopeSet(touchedFiles);
+  const byMethod = indexCrapBaselineByMethod(baselineRows);
+  const seen = new Set();
+  const regressions = [];
+
+  for (const row of headRows) {
+    if (!isValidHeadRow(row)) continue;
+    const rowFile = rowFileKey(row);
+    if (scope && !scope.has(rowFile)) continue;
+    const candidates = byMethod.get(`${rowFile}::${row.method}`);
+    if (!Array.isArray(candidates) || candidates.length === 0) continue;
+    const pick = pickClosestUnseen(candidates, row.startLine, seen);
+    if (!pick) continue;
+    seen.add(`${rowFileKey(pick)}::${pick.method}@${pick.startLine}`);
+    const entry = buildCrapRegression(row, pick);
+    if (entry.headCrap <= entry.baseCrap + tolerance) continue;
+    const { headCrap: _h, baseCrap: _b, ...publicEntry } = entry;
+    regressions.push(publicEntry);
+  }
+  return regressions;
+}
+
+export function projectCrapRegressions({
+  touchedFiles,
+  baselineRef,
+  headRef,
+  cwd,
+  baselinePath,
+  tolerance = DEFAULT_CRAP_TOLERANCE,
+  readBaselineAtRef = defaultReadBaselineAtRef,
+  getBaselines = defaultGetBaselines,
+  config,
+} = {}) {
+  if (!baselineRef || !headRef) return [];
+  const resolvedPath = baselinePath ?? getBaselines(config)?.crap?.path;
+  if (!resolvedPath) return [];
+
+  let baselineEnv;
+  let headEnv;
+  try {
+    baselineEnv = readBaselineAtRef(baselineRef, resolvedPath, { cwd });
+  } catch {
+    return [];
+  }
+  try {
+    headEnv = readBaselineAtRef(headRef, resolvedPath, { cwd });
+  } catch {
+    return [];
+  }
+  const baselineRows = Array.isArray(baselineEnv?.rows) ? baselineEnv.rows : [];
+  const headRows = Array.isArray(headEnv?.rows) ? headEnv.rows : [];
+  return diffCrapBaselines({
+    baselineRows,
+    headRows,
+    touchedFiles,
+    tolerance,
+  });
+}
+
+/**
+ * Maintainability projector — extracts the same regression rows
+ * `runPreMergeGates` would have surfaced for `check-maintainability` by
+ * re-running the per-file MI ceiling projection against `origin/<epicBranch>`.
+ *
+ * Behaviour is preserved byte-for-byte from the pre-refactor early-return
+ * branch of `projectRegressionsForGate`: missing baseline path → `[]`, and
+ * the underlying `projectMaintainabilityRegressions` decides what counts as
+ * a regression row.
+ *
+ * @returns {Array<{ path?: string, file?: string }>}
+ */
+function projectMaintainabilityForGate({
+  cwd,
+  epicBranch,
+  storyBranch,
+  config,
+  projectMaintainability = defaultProjectMaintainabilityRegressions,
+  getBaselines = defaultGetBaselines,
+}) {
+  const baselinePath = getBaselines(config)?.maintainability?.path;
+  if (!baselinePath) return [];
+  const projection = projectMaintainability({
+    cwd,
+    epicBranch,
+    storyBranch,
+    baselinePath,
+  });
+  return projection?.regressions ?? [];
+}
+
+function projectCrapForGate({
+  cwd,
+  epicBranch,
+  storyBranch,
+  config,
+  getBaselines = defaultGetBaselines,
+  readBaselineAtRef = defaultReadBaselineAtRef,
+  computeTouched = computeStoryDiffPaths,
+  projectCrap = projectCrapRegressions,
+} = {}) {
+  if (!validateProjectionContext({ cwd, epicBranch, storyBranch })) return [];
+  const touchedFiles = new Set(
+    computeTouched({ cwd, epicBranch, storyBranch }),
+  );
+  return projectCrap({
+    touchedFiles,
+    baselineRef: `origin/${epicBranch}`,
+    headRef: storyBranch,
+    cwd,
+    config,
+    readBaselineAtRef,
+    getBaselines,
+  });
+}
+
+export const PROJECTORS = {
+  'check-maintainability': projectMaintainabilityForGate,
+  'check-crap': projectCrapForGate,
+};
+
+export function projectRegressionsForGate({
+  gateName,
+  cwd,
+  epicBranch,
+  storyBranch,
+  config,
+  projectMaintainability = defaultProjectMaintainabilityRegressions,
+  getBaselines = defaultGetBaselines,
+}) {
+  const project = PROJECTORS[gateName];
+  if (!project) return [];
+  return project({
+    cwd,
+    epicBranch,
+    storyBranch,
+    config,
+    projectMaintainability,
+    getBaselines,
+  });
+}

package/.agents/scripts/lib/orchestration/story-close/baseline-attribution/phases/scope-discovery.js

@@ -0,0 +1,48 @@
+/**
+ * scope-discovery.js — phase 1 of baseline-attribution.
+ *
+ * Resolve the Story branch's diff scope vs `origin/<epicBranch>` so the
+ * downstream projection + attribution layers can split "this Story's
+ * regressions" from "sibling drift inherited from the Epic branch".
+ *
+ * Pure helpers — every git invocation goes through the injected
+ * `gitRunner` so tests can pin the diff math without spawning git.
+ */
+
+import { diffNameOnly } from '../../../../changed-files.js';
+import { gitSpawn as defaultGitSpawn } from '../../../../git-utils.js';
+
+/**
+ * Compute repo-relative paths the Story branch changed vs `origin/<epicBranch>`.
+ * Best-effort: a non-zero diff exit returns an empty array so the caller
+ * conservatively treats every regression as non-attributable (the safer
+ * default — the close blocks rather than absorbs sibling drift).
+ */
+export function computeStoryDiffPaths({
+  cwd,
+  epicBranch,
+  storyBranch,
+  gitRunner = { gitSpawn: defaultGitSpawn },
+}) {
+  if (!cwd || !epicBranch || !storyBranch) return [];
+  try {
+    return diffNameOnly({
+      range: `origin/${epicBranch}...${storyBranch}`,
+      cwd,
+      gitSpawn: gitRunner.gitSpawn,
+    });
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Guard for the projection phase — the projectors require a worktree + the
+ * pair of branch refs to compute a meaningful diff.
+ */
+export function validateProjectionContext({ cwd, epicBranch, storyBranch }) {
+  if (!cwd) return false;
+  if (!epicBranch) return false;
+  if (!storyBranch) return false;
+  return true;
+}

package/.agents/scripts/lib/orchestration/story-close/baseline-attribution-wiring.js

@@ -0,0 +1,67 @@
+/**
+ * baseline-attribution-wiring.js — glue between the close-validation gate
+ * chain and the diff-based attribution classifier (Story #1124).
+ *
+ * `runPreMergeGates` throws on the first failed gate but does not surface
+ * regression rows. For baseline gates (`check-maintainability`, `check-crap`)
+ * the post-#1120 contract is to:
+ *
+ *   1. Compute the regressions list ourselves (the pre-merge MI projection
+ *      already knows how — Story #874).
+ *   2. Compute the Story's diff vs `epic/<id>` so the classifier can split
+ *      attributable from non-attributable rows.
+ *   3. If every regression is attributable, refresh the kind's baseline via
+ *      `refreshBaseline()` (Story #2197), stage the changed baseline file,
+ *      and commit on the Story branch with a `chore(baselines): refresh
+ *      <kind> for story-<id>` subject. The caller then re-runs the gate
+ *      chain — drift is now committed, gate passes.
+ *   4. If any regression is non-attributable, render the friction body
+ *      (`renderBaselineFrictionBody`) and upsert it via
+ *      `upsertStructuredComment`. Return a status that signals story-close
+ *      to short-circuit with `{ status: 'blocked', phase: 'closing' }`.
+ *
+ * Story #2205 — refresh path now flows through `refreshBaseline()` from
+ * `.agents/scripts/lib/baselines/refresh-service.js`. The `--amend` / `--allow-empty`
+ * shortcuts and the legacy `npm run <kind>:update` shell-outs are gone.
+ * Post-refresh hygiene is: stage the baseline file, run `git diff --cached
+ * --exit-code`, and either skip (empty diff → log "no baseline drift to
+ * fold in") or emit one canonical `chore(baselines): refresh <kind> for
+ * story-<id>` commit. The retry loop is gated by an idempotency token
+ * (`cycleState.refreshedKinds`) so a fail-then-pass sequence still emits
+ * at most one baseline-refresh commit per close cycle (AC-9, #2176-fixture).
+ *
+ * Story #3002 — the module body was decomposed into
+ * `./baseline-attribution/phases/` (one file per functional phase)
+ * following the established pattern at `./phases/`, `../post-merge/phases/`,
+ * and `../retro/phases/`. This file is now a thin re-export sequencer; the
+ * phase implementations live under:
+ *
+ *   - phases/scope-discovery.js       — Story-diff scope + projection guard.
+ *   - phases/regression-projection.js — per-gate regression projectors.
+ *   - phases/refresh-commit.js        — in-process refresh + commit.
+ *   - phases/gate-failure.js          — per-failure classifier
+ *                                       (handleBaselineGateFailure).
+ *   - phases/pre-merge-attribution.js — bounded retry driver
+ *                                       (runPreMergeGatesWithAttribution).
+ */
+
+export {
+  DEFAULT_GATE_REGISTRY,
+  handleBaselineGateFailure,
+} from './baseline-attribution/phases/gate-failure.js';
+export { runPreMergeGatesWithAttribution } from './baseline-attribution/phases/pre-merge-attribution.js';
+export {
+  buildKindScorer,
+  runRefreshCommit,
+  stageAndCheckBaselineDrift,
+} from './baseline-attribution/phases/refresh-commit.js';
+export {
+  diffCrapBaselines,
+  PROJECTORS,
+  projectCrapRegressions,
+  projectRegressionsForGate,
+} from './baseline-attribution/phases/regression-projection.js';
+export {
+  computeStoryDiffPaths,
+  validateProjectionContext,
+} from './baseline-attribution/phases/scope-discovery.js';

package/.agents/scripts/lib/orchestration/story-close/baseline-attribution.js

@@ -0,0 +1,161 @@
+/**
+ * baseline-attribution.js — diff-based attribution of baseline regressions.
+ *
+ * Story #1124 (Tech Spec #902, "s-baseline-refresh-discipline") closes a
+ * subtle race in the post-#1120 worktree-local close path: when a Story's
+ * close run trips a baseline gate (maintainability, crap, etc.) the failing
+ * regression rows may include paths the Story never touched — drift carried
+ * in from a sibling Story that already merged into `epic/<id>` between this
+ * Story's branch cut and its close attempt. Auto-refreshing those baselines
+ * here would silently absorb the sibling's debt onto this Story's PR and
+ * destroy the audit trail. Doing nothing locks the close behind drift the
+ * operator did not cause.
+ *
+ * The split this module computes is:
+ *
+ *   - `attributable`    — regressions on paths intersecting the Story's diff
+ *                         vs `epic/<id>`. Safe to auto-refresh on the Story
+ *                         branch as `baseline-refresh: ...`.
+ *   - `nonAttributable` — regressions on paths the Story never touched. Each
+ *                         row is annotated with the most recent commit on
+ *                         `epic/<id>` that touched the path (`suspectSha`)
+ *                         and the `(resolves #N)` token parsed out of that
+ *                         commit subject (`suspectStoryNumber`, may be null).
+ *                         The caller surfaces these as friction so the
+ *                         operator can route the refresh back to the sibling
+ *                         that caused the drift.
+ *
+ * The classifier itself does no IO when every regression is attributable —
+ * the `git log` lookup runs only on non-attributable rows so the hot path
+ * (the common case where the operator's Story is the sole writer) costs
+ * one `Set` membership check per row.
+ */
+
+import { gitSpawn as defaultGitSpawn } from '../../git-utils.js';
+import { parseResolvesStoryId } from '../resolves-token.js';
+
+/**
+ * Normalize a path for set-based intersection. `git diff --name-only`
+ * returns POSIX paths on every OS, but a caller passing
+ * `storyDiffPaths` from a Windows tooling boundary may have `\` in the
+ * path. Round both sides through `/` so the intersection is honest.
+ */
+function normalize(p) {
+  return typeof p === 'string' ? p.replace(/\\/g, '/') : p;
+}
+
+/**
+ * Look up the most recent commit on `epicRef` that touched `path` and
+ * extract the `(resolves #N)` trailer if present. Returns
+ * `{ suspectSha, suspectStoryNumber }`; either field may be `null` when
+ * the lookup yields no commit (e.g. file added on this branch but
+ * still flagged as a regression by the gate against a stale baseline)
+ * or the most recent commit subject does not carry the trailer.
+ *
+ * Failure of the spawn is treated as "no information" — the caller
+ * still surfaces the row as non-attributable, just without a suspect.
+ */
+function lookupSuspect({ gitRunner, cwd, epicRef, path }) {
+  const res = gitRunner.gitSpawn(
+    cwd,
+    'log',
+    '--oneline',
+    '-n',
+    '1',
+    epicRef,
+    '--',
+    path,
+  );
+  if (res.status !== 0) {
+    return { suspectSha: null, suspectStoryNumber: null };
+  }
+  const line = (res.stdout || '').split('\n')[0]?.trim() ?? '';
+  if (!line) return { suspectSha: null, suspectStoryNumber: null };
+
+  // `--oneline` format is `<short-sha> <subject…>`; split on the first
+  // run of whitespace so multi-space subjects survive.
+  const sepIdx = line.search(/\s/);
+  const suspectSha = sepIdx === -1 ? line : line.slice(0, sepIdx);
+  const subject = sepIdx === -1 ? '' : line.slice(sepIdx + 1);
+  const suspectStoryNumber = parseResolvesStoryId(subject);
+  return { suspectSha: suspectSha || null, suspectStoryNumber };
+}
+
+/**
+ * Classify the supplied baseline regressions into rows the running Story
+ * should auto-refresh vs rows it should surface as friction.
+ *
+ * @param {object} opts
+ * @param {Array<{ path?: string, file?: string }>} opts.regressions
+ *   Regression rows from a baseline gate. Either `path` or `file` is read
+ *   for the file key — different gate emitters use different names and
+ *   normalizing them here keeps the wiring at the call site trivial.
+ * @param {Iterable<string>} opts.storyDiffPaths
+ *   Repo-relative paths the Story branch changed vs `epic/<id>` (typically
+ *   the output of `git diff --name-only origin/<epicBranch>...storyBranch`).
+ * @param {string} opts.epicRef Git ref the suspect lookup walks (e.g.
+ *   `origin/epic/1114` or `epic/1114`).
+ * @param {string} [opts.cwd] CWD for `git log`. Defaults to `process.cwd()`.
+ * @param {{ gitSpawn: typeof defaultGitSpawn }} [opts.gitRunner]
+ *   Injected git seam. Tests pass a fake recorder.
+ * @returns {{
+ *   attributable: Array<{ path: string }>,
+ *   nonAttributable: Array<{
+ *     path: string,
+ *     suspectSha: string|null,
+ *     suspectStoryNumber: number|null,
+ *   }>,
+ * }}
+ */
+export function classifyBaselineDrift({
+  regressions,
+  storyDiffPaths,
+  epicRef,
+  cwd,
+  gitRunner,
+} = {}) {
+  const rows = Array.isArray(regressions) ? regressions : [];
+  const touched = new Set(
+    Array.from(storyDiffPaths ?? [], normalize).filter(Boolean),
+  );
+
+  const attributable = [];
+  const nonAttributable = [];
+
+  // Defer git seam construction until at least one non-attributable row
+  // appears — the all-attributable hot path costs zero spawns.
+  let runner = null;
+  const ensureRunner = () => {
+    if (runner) return runner;
+    runner = gitRunner ?? { gitSpawn: defaultGitSpawn };
+    return runner;
+  };
+  const lookupCwd =
+    cwd ?? (typeof process !== 'undefined' ? process.cwd() : '.');
+
+  for (const row of rows) {
+    const rawPath = row?.path ?? row?.file;
+    if (typeof rawPath !== 'string' || rawPath.length === 0) continue;
+    const p = normalize(rawPath);
+    if (touched.has(p)) {
+      attributable.push({ ...row, path: p });
+      continue;
+    }
+    const suspect = epicRef
+      ? lookupSuspect({
+          gitRunner: ensureRunner(),
+          cwd: lookupCwd,
+          epicRef,
+          path: p,
+        })
+      : { suspectSha: null, suspectStoryNumber: null };
+    nonAttributable.push({
+      ...row,
+      path: p,
+      suspectSha: suspect.suspectSha,
+      suspectStoryNumber: suspect.suspectStoryNumber,
+    });
+  }
+
+  return { attributable, nonAttributable };
+}

package/.agents/scripts/lib/orchestration/story-close/baseline-friction-body.js

@@ -0,0 +1,117 @@
+/**
+ * baseline-friction-body.js — render the friction-comment body for
+ * non-attributable baseline drift surfaced by the close-validation chain.
+ *
+ * Story #1124 (Tech Spec #902, "s-baseline-refresh-discipline"). When
+ * `classifyBaselineDrift` reports rows on paths the running Story never
+ * touched, story-close upserts a `friction`-typed structured comment on
+ * the Story so the operator can route the refresh back to the sibling
+ * Story whose merge introduced the drift. The body shape is stable so
+ * the `diagnose-friction` analyzer can pattern-match the section.
+ *
+ * Output contract (markdown):
+ *
+ *     ### Baseline drift not attributable to this Story
+ *
+ *     The close-validation chain flagged the following file(s) as breaching
+ *     a committed baseline, but none of the paths intersect this Story's
+ *     diff vs `epic/<epicId>`. Refreshing them here would silently absorb a
+ *     sibling Story's debt onto this Story's PR, so the close is blocked
+ *     until an operator routes the refresh to the suspect Story below.
+ *
+ *     | Path | Suspect Story | Suspect Commit |
+ *     | --- | --- | --- |
+ *     | lib/foo.js | #777 | `deadbee1` |
+ *     | lib/orphan.js | _unknown_ | `beef0001` |
+ *
+ *     <triage instructions>
+ *
+ * The renderer is pure — no IO, no provider calls — so unit tests can pin
+ * the exact body string against fixed inputs.
+ */
+
+/**
+ * Format a single suspect cell: `#<num>` when present, italic `_unknown_`
+ * otherwise. Italic so a Markdown-aware reader can scan the column for
+ * holes without parsing the table semantics.
+ */
+function formatSuspectStory(num) {
+  return typeof num === 'number' && Number.isFinite(num) && num > 0
+    ? `#${num}`
+    : '_unknown_';
+}
+
+/**
+ * Format the suspect-commit cell as an inline-code SHA, or em-dash when
+ * the lookup yielded nothing (the row was non-attributable but git log
+ * returned no commit on `epicRef` for the path — typically a renamed
+ * file or a stale baseline against an empty path).
+ */
+function formatSuspectSha(sha) {
+  return typeof sha === 'string' && sha.length > 0 ? `\`${sha}\`` : '—';
+}
+
+/**
+ * Render the friction-comment body. The caller passes the result to
+ * `upsertStructuredComment(provider, ticketId, 'friction', body)` which
+ * applies the canonical structured-comment marker.
+ *
+ * @param {object} input
+ * @param {Array<{
+ *   path: string,
+ *   suspectStoryNumber: number|null,
+ *   suspectSha: string|null,
+ * }>} input.rows
+ *   The `nonAttributable` slice from `classifyBaselineDrift`. Empty input
+ *   yields a defensive "no rows" body so a misuse never produces a
+ *   blank comment — that comment shape is asserted by the unit test.
+ * @param {number|string} input.epicId
+ * @param {number|string} input.storyId
+ * @returns {string} markdown body (no trailing newline)
+ */
+export function renderBaselineFrictionBody({ rows, epicId, storyId } = {}) {
+  const tableRows = Array.isArray(rows) ? rows : [];
+  const heading = `### Baseline drift not attributable to Story #${storyId}`;
+  const intro =
+    `The close-validation chain flagged the file(s) below as breaching a ` +
+    `committed baseline, but none of the paths intersect this Story's diff vs ` +
+    `\`epic/${epicId}\`. Auto-refreshing them on Story #${storyId} would silently ` +
+    `absorb a sibling Story's debt onto this Story's PR, so the close is ` +
+    `blocked until an operator routes the refresh to the suspect Story below.`;
+
+  if (tableRows.length === 0) {
+    return [
+      heading,
+      '',
+      intro,
+      '',
+      '_No non-attributable rows were supplied — this comment was emitted defensively._',
+    ].join('\n');
+  }
+
+  const tableHeader = [
+    '| Path | Suspect Story | Suspect Commit |',
+    '| --- | --- | --- |',
+  ];
+  const tableBody = tableRows.map(
+    (r) =>
+      `| \`${r.path}\` | ${formatSuspectStory(r.suspectStoryNumber)} | ${formatSuspectSha(r.suspectSha)} |`,
+  );
+  const triage = [
+    '**Triage:**',
+    `1. Open each suspect Story above and run \`npm run maintainability:update\` (or \`npm run crap:update\`) on **its** branch, then commit with a \`baseline-refresh:\` subject and re-close it.`,
+    `2. Re-run \`/story-deliver ${storyId}\` once the suspect Story's refresh has merged into \`epic/${epicId}\`.`,
+    `3. If the suspect column reads \`_unknown_\`, the path has no commit on \`epic/${epicId}\` — investigate the baseline file directly before refreshing.`,
+  ];
+
+  return [
+    heading,
+    '',
+    intro,
+    '',
+    ...tableHeader,
+    ...tableBody,
+    '',
+    ...triage,
+  ].join('\n');
+}