mandrel 1.94.0 → 2.1.0

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

@@ -1,297 +0,0 @@
-/**
- * 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/projections/maintainability.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/projections/maintainability.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,
-};
-
-/**
- * Composite gates fan out to per-kind projectors. The baseline pipeline was
- * unified behind a single `check-baselines` gate (per-kind pipeline: schema →
- * floor → tolerance), but the attribution layer still keys on the original
- * per-kind gate names. Without this map a `check-baselines` failure projects
- * zero regressions, the gate-failure handler sees an empty list, and the
- * auto-refresh path silently no-ops — so a legitimate MI/CRAP regression
- * hard-fails the close instead of self-healing (framework-gap #4377).
- */
-export const COMPOSITE_SUBGATES = {
-  'check-baselines': ['check-maintainability', 'check-crap'],
-};
-
-/** `check-maintainability` → `maintainability`. */
-function gateKind(gateName) {
-  return gateName.replace(/^check-/, '');
-}
-
-export function projectRegressionsForGate({
-  gateName,
-  cwd,
-  epicBranch,
-  storyBranch,
-  config,
-  projectMaintainability = defaultProjectMaintainabilityRegressions,
-  getBaselines = defaultGetBaselines,
-}) {
-  const ctx = {
-    cwd,
-    epicBranch,
-    storyBranch,
-    config,
-    projectMaintainability,
-    getBaselines,
-  };
-  const subGates = COMPOSITE_SUBGATES[gateName];
-  if (subGates) {
-    // Union the per-kind regressions, tagging each row with its baseline
-    // kind so the gate-failure handler can refresh the right baseline (one
-    // kind per attribution cycle; the retry loop converges the rest).
-    return subGates.flatMap((sub) => {
-      const project = PROJECTORS[sub];
-      if (!project) return [];
-      const kind = gateKind(sub);
-      return project(ctx).map((row) => ({ _gateKind: kind, ...row }));
-    });
-  }
-  const project = PROJECTORS[gateName];
-  if (!project) return [];
-  return project(ctx);
-}

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

@@ -1,48 +0,0 @@
-/**
- * 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

@@ -1,67 +0,0 @@
-/**
- * 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

@@ -1,161 +0,0 @@
-/**
- * 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

@@ -1,117 +0,0 @@
-/**
- * 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 \`/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');
-}