mandrel 1.94.0 → 2.1.0

package/.agents/scripts/lib/orchestration/post-merge-pipeline.js

@@ -1,205 +0,0 @@
-/**
- * post-merge-pipeline.js — sequencer for the post-merge phases of
- * `story-close`.
- *
- * After the Story branch is merged into the Epic branch, several best-effort
- * cleanup + reporting phases must run:
- *
- *   1. worktree-reap       — remove the per-Story worktree.
- *   2. branch-cleanup      — delete the Story branch (local + remote).
- *   3. ticket-closure      — transition the Story to agent::done
- *                            and run cascade completion.
- *   4. notification        — fire the story-complete webhook.
- *   5. dashboard-refresh   — regenerate the dispatch manifest.
- *   6. temp-cleanup        — delete the per-Story manifest pair under
- *                            `temp/epic-<eid>/stories/story-<sid>/manifest.{md,json}`
- *                            (Epic #1030 Story #1040). Falls back to the
- *                            legacy flat `temp/story-manifest-<id>.{md,json}`
- *                            layout when `epicId` is unknown — both paths
- *                            are tried so partial migrations don't leak
- *                            files in either layout.
- *   7. detectors           — fire rework + retry signal detectors against
- *                            this Story's `traces.ndjson` and persist each
- *                            emission to `signals.ndjson` BEFORE the
- *                            analyzer renders the perf-summary comment.
- *   8. perf-summary        — shell out to `analyze-execution.js` so the
- *                            analyzer is the single writer of the
- *                            `<!-- structured:story-perf-summary -->`
- *                            comment on the Story ticket.
- *
- * Each phase is wrapped by `runPhase` so a single failure does not abort
- * the rest of the close-out — the same best-effort contract that the
- * pre-extraction inline code provided. Phase return values are merged into
- * a `state` object whose shape `runStoryClose` consumes to build the final
- * structured result.
- *
- * The phase implementations live under `./post-merge/phases/` (one file
- * per phase) — this module is a pure sequencer that imports each phase,
- * re-exports them for backwards compatibility, and runs them in order
- * via `runPhase`.
- */
-
-import { execFileSync } from 'node:child_process';
-import path from 'node:path';
-import { Logger } from '../Logger.js';
-import { detectorsPhase } from './detectors-phase.js';
-import { runPhase } from './phase-runner.js';
-import { branchCleanupPhase } from './post-merge/phases/branch-cleanup.js';
-import { dashboardRefreshPhase } from './post-merge/phases/dashboard-refresh.js';
-import { notificationPhase } from './post-merge/phases/notification.js';
-import { tempCleanupPhase } from './post-merge/phases/temp-cleanup.js';
-import { ticketClosurePhase } from './post-merge/phases/ticket-closure.js';
-import {
-  createWorktreeReapState,
-  worktreeReapPhase,
-} from './post-merge/phases/worktree-reap.js';
-
-export {
-  branchCleanupPhase,
-  dashboardRefreshPhase,
-  detectorsPhase,
-  notificationPhase,
-  tempCleanupPhase,
-  ticketClosurePhase,
-  worktreeReapPhase,
-};
-
-function reapPhaseLogger(progress) {
-  return progress ?? (() => {});
-}
-
-/**
- * perfSummaryPhase — shells out to `analyze-execution.js --story <sid>
- * --epic <eid> --phase-timings <path>` so the analyzer is the single
- * writer of the `<!-- structured:story-perf-summary -->` comment on the
- * Story ticket (Epic #1030 Story #1046). Replaces the legacy
- * `<!-- structured:phase-timings -->` post that lived inline in
- * `post-merge-close.js`.
- *
- * Best-effort: any failure (missing analyzer, non-zero exit, no path
- * supplied) logs a warning and resolves — the merge has already
- * succeeded and we would rather lose the perf summary than roll back
- * closure.
- *
- * @param {{
- *   storyId: number|string,
- *   epicId: number|string,
- *   phaseTimingsPath: string|null|undefined,
- *   projectRoot?: string,
- *   progress?: Function,
- *   logger?: object,
- *   spawnFn?: typeof execFileSync,
- * }} ctx
- * @returns {Promise<{ status: 'ok'|'skipped'|'failed', reason?: string }>}
- */
-export async function perfSummaryPhase(ctx) {
-  const {
-    storyId,
-    epicId,
-    phaseTimingsPath,
-    projectRoot,
-    progress,
-    logger,
-    spawnFn = execFileSync,
-  } = ctx;
-  const log = reapPhaseLogger(progress);
-  if (!phaseTimingsPath) {
-    log('PERF', '⏭️ Skipping perf-summary (no phase-timings path provided)');
-    return { status: 'skipped', reason: 'no-phase-timings-path' };
-  }
-  const root = projectRoot ?? process.cwd();
-  const analyzerPath = path.join(
-    root,
-    '.agents',
-    'scripts',
-    'analyze-execution.js',
-  );
-  const args = [
-    analyzerPath,
-    '--story',
-    String(storyId),
-    '--epic',
-    String(epicId),
-    '--phase-timings',
-    phaseTimingsPath,
-  ];
-  log(
-    'PERF',
-    `Running analyzer: analyze-execution.js --story ${storyId} --epic ${epicId}`,
-  );
-  try {
-    spawnFn(process.execPath, args, {
-      cwd: root,
-      stdio: ['ignore', 'pipe', 'pipe'],
-    });
-    log('PERF', '✅ story-perf-summary posted');
-    return { status: 'ok' };
-  } catch (err) {
-    const reason = err?.message ?? String(err);
-    logger?.warn?.(
-      `[post-merge-pipeline] ⚠️ analyze-execution failed (non-fatal): ${reason}`,
-    );
-    return { status: 'failed', reason };
-  }
-}
-
-export const DEFAULT_POST_MERGE_PHASES = Object.freeze([
-  {
-    name: 'worktree-reap',
-    fn: worktreeReapPhase,
-    stateKey: 'worktreeReap',
-    fallback: createWorktreeReapState({
-      status: 'failed',
-      reason: 'phase-error',
-    }),
-  },
-  { name: 'branch-cleanup', fn: branchCleanupPhase, stateKey: 'branchCleanup' },
-  { name: 'ticket-closure', fn: ticketClosurePhase, stateKey: 'ticketClosure' },
-  { name: 'notification', fn: notificationPhase },
-  {
-    name: 'dashboard-refresh',
-    fn: dashboardRefreshPhase,
-    stateKey: 'manifestUpdated',
-  },
-  { name: 'temp-cleanup', fn: tempCleanupPhase },
-  // Detectors MUST run before `perf-summary`. The perf phase shells out
-  // to `analyze-execution.js`, which reads the per-Story signals stream
-  // to author the `<!-- structured:story-perf-summary -->` comment;
-  // emitting rework/retry events first ensures the rendered surface
-  // reflects this Story's signals.
-  { name: 'detectors', fn: detectorsPhase, stateKey: 'detectors' },
-  { name: 'perf-summary', fn: perfSummaryPhase, stateKey: 'perfSummary' },
-]);
-
-/**
- * Sequence the post-merge phases of `story-close`. Every phase runs
- * under `runPhase` so a single failure logs `[phase=<name>] <err>` and the
- * pipeline keeps going. Each phase's return value is recorded under its
- * `stateKey` (when defined) on the returned state object.
- *
- * @param {object} ctx          Phase collaborators (provider, notify,
- *                              logger, progress, etc.).
- * @param {Array<{name: string, fn: Function, stateKey?: string, fallback?: any}>} [phases]
- *                              Phase descriptors. Defaults to `DEFAULT_POST_MERGE_PHASES`.
- * @returns {Promise<object>}   Aggregated state from each phase.
- */
-export async function runPostMergePipeline(
-  ctx,
-  phases = DEFAULT_POST_MERGE_PHASES,
-) {
-  const logger = ctx.logger ?? Logger;
-  const state = {
-    worktreeReap: createWorktreeReapState(),
-    branchCleanup: { localDeleted: false, remoteDeleted: false },
-    ticketClosure: { closedTickets: [], cascadedTo: [], cascadeFailed: [] },
-    manifestUpdated: false,
-  };
-  for (const phase of phases) {
-    const value = await runPhase(phase.name, () => phase.fn(ctx, state), {
-      logger,
-      fallback: phase.fallback,
-    });
-    if (phase.stateKey && value !== undefined) state[phase.stateKey] = value;
-  }
-  return state;
-}

package/.agents/scripts/lib/orchestration/preflight-cache.js

@@ -1,187 +0,0 @@
-/**
- * preflight-cache.js — Epic #3019 / Story #3027.
- *
- * Cache adapter for the snapshot/DAG envelope produced by
- * `epic-deliver-preflight.js` so `epic-deliver-prepare.js` can skip the
- * second walk of Epic → Story when the underlying Epic ticket
- * has not drifted between the two operator invocations.
- *
- * Contract:
- *   - Cache file lives at `<cwd>/temp/epic-<epicId>/preflight-snapshot.json`.
- *   - Envelope shape:
- *       {
- *         epicId: number,
- *         baseSha: string,        // deterministic fingerprint of the Epic
- *                                 // snapshot returned by provider.getTicket
- *         capturedAt: string,     // ISO-8601 timestamp
- *         epic: object,           // the snapshot from runSnapshotPhase
- *         stories: object[],      // the open Story tickets from runBuildWaveDagPhase
- *         waves: Array<Array<object>>, // wave DAG (ids + labels preserved)
- *       }
- *   - `computeBaseSha(epic)` derives the cache key from the same provider
- *     call (`getTicket(epicId)`) used to walk the hierarchy. The hash
- *     covers the Epic's id, body, labels (sorted), and (when present)
- *     `updatedAt` — the same fields that drive Story discovery and the
- *     acceptance start gate (the Epic body's ## Acceptance Table).
- *   - Cache miss is signalled by `readCache` returning `null`. Callers
- *     MUST fall back to a fresh snapshot/DAG pass.
- *   - `writeCache` creates the parent directory recursively and writes
- *     atomically (write to `<path>.tmp` then rename).
- *
- * The module is pure JS / node:fs — no provider dependency — so tests
- * can exercise it without spinning up a GitHub mock.
- */
-
-import { createHash } from 'node:crypto';
-import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
-import path from 'node:path';
-
-/**
- * Resolve the on-disk path for an Epic's preflight cache.
- *
- * @param {{ epicId: number, cwd?: string }} args
- * @returns {string}
- */
-export function preflightCachePath({ epicId, cwd }) {
-  if (!Number.isInteger(epicId) || epicId <= 0) {
-    throw new TypeError(
-      'preflightCachePath: epicId must be a positive integer',
-    );
-  }
-  const root = cwd ?? process.cwd();
-  return path.join(root, 'temp', `epic-${epicId}`, 'preflight-snapshot.json');
-}
-
-/**
- * Per-ticket fingerprint fields shared by the Epic and each Story in the
- * cache key: id, body, sorted labels, and updatedAt. Story bodies carry
- * the dependency edges, so hashing them means a Story-dependency edit
- * forces a cache miss (Story #4019 — the previous Epic-only key let
- * dependency edits slip through unnoticed).
- *
- * @param {{ id?: number|string, number?: number|string, body?: string, labels?: string[], updatedAt?: string }} ticket
- * @returns {{ id: number|string|null, body: string, labels: string[], updatedAt: string|null }}
- */
-function ticketFingerprint(ticket) {
-  const t = ticket && typeof ticket === 'object' ? ticket : {};
-  return {
-    id: t.id ?? t.number ?? null,
-    body: typeof t.body === 'string' ? t.body : '',
-    labels: Array.isArray(t.labels) ? [...t.labels].map(String).sort() : [],
-    updatedAt: typeof t.updatedAt === 'string' ? t.updatedAt : null,
-  };
-}
-
-/**
- * Stable string fingerprint of an Epic snapshot **plus its Story
- * dependency state**. The hash is keyed on the exact fields
- * `runSnapshotPhase` reads (`getTicket(epicId)` return value) and on each
- * Story's id/body/labels/updatedAt, so that any drift the snapshot or
- * wave-DAG phases would observe — including a Story-dependency edit —
- * forces a cache miss (Story #4019).
- *
- * Labels are sorted to absorb GitHub's non-deterministic label order
- * across responses; stories are sorted by id so enumeration order never
- * perturbs the key. The hash is sha256; we return the full hex digest so
- * the cache key is collision-resistant for the lifetime of a delivery.
- *
- * @param {{ id?: number|string, number?: number|string, body?: string, labels?: string[], updatedAt?: string }} epic
- * @param {Array<{ id?: number|string, number?: number|string, body?: string, labels?: string[], updatedAt?: string }>} [stories]
- * @returns {string}
- */
-export function computeBaseSha(epic, stories = []) {
-  if (!epic || typeof epic !== 'object') {
-    throw new TypeError('computeBaseSha: epic snapshot must be an object');
-  }
-  const epicPrint = ticketFingerprint(epic);
-  const storyPrints = (Array.isArray(stories) ? stories : [])
-    .map(ticketFingerprint)
-    .sort((a, b) => Number(a.id ?? 0) - Number(b.id ?? 0));
-  const payload = JSON.stringify({ ...epicPrint, stories: storyPrints });
-  return createHash('sha256').update(payload).digest('hex');
-}
-
-/**
- * Read the cached preflight envelope from disk. Returns `null` when the
- * file is missing or unreadable — callers MUST treat that as a cache
- * miss and fall back to a fresh snapshot/DAG pass.
- *
- * The function intentionally swallows `ENOENT` and JSON-parse errors so
- * a stale or partially-written file does not poison `epic-deliver-prepare`.
- *
- * @param {{ epicId: number, cwd?: string }} args
- * @returns {Promise<object | null>}
- */
-export async function readPreflightCache({ epicId, cwd }) {
-  const cachePath = preflightCachePath({ epicId, cwd });
-  let raw;
-  try {
-    raw = await readFile(cachePath, 'utf8');
-  } catch (err) {
-    if (err && err.code === 'ENOENT') return null;
-    throw err;
-  }
-  try {
-    const parsed = JSON.parse(raw);
-    if (!parsed || typeof parsed !== 'object') return null;
-    if (parsed.epicId !== epicId) return null;
-    if (typeof parsed.baseSha !== 'string' || !parsed.baseSha) return null;
-    if (!parsed.epic || typeof parsed.epic !== 'object') return null;
-    if (!Array.isArray(parsed.stories)) return null;
-    if (!Array.isArray(parsed.waves)) return null;
-    return parsed;
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Persist the preflight envelope to disk. Writes atomically via tmp +
- * rename so concurrent readers never observe a partial file.
- *
- * @param {{ epicId: number, baseSha: string, epic: object, stories: object[], waves: Array<Array<object>>, cwd?: string, capturedAt?: string }} args
- * @returns {Promise<{ cachePath: string, baseSha: string }>}
- */
-export async function writePreflightCache({
-  epicId,
-  baseSha,
-  epic,
-  stories,
-  waves,
-  cwd,
-  capturedAt,
-}) {
-  if (!Number.isInteger(epicId) || epicId <= 0) {
-    throw new TypeError(
-      'writePreflightCache: epicId must be a positive integer',
-    );
-  }
-  if (typeof baseSha !== 'string' || !baseSha) {
-    throw new TypeError(
-      'writePreflightCache: baseSha must be a non-empty string',
-    );
-  }
-  if (!epic || typeof epic !== 'object') {
-    throw new TypeError('writePreflightCache: epic must be an object');
-  }
-  if (!Array.isArray(stories)) {
-    throw new TypeError('writePreflightCache: stories must be an array');
-  }
-  if (!Array.isArray(waves)) {
-    throw new TypeError('writePreflightCache: waves must be an array');
-  }
-  const cachePath = preflightCachePath({ epicId, cwd });
-  await mkdir(path.dirname(cachePath), { recursive: true });
-  const envelope = {
-    epicId,
-    baseSha,
-    capturedAt: capturedAt ?? new Date().toISOString(),
-    epic,
-    stories,
-    waves,
-  };
-  const tmp = `${cachePath}.tmp`;
-  await writeFile(tmp, `${JSON.stringify(envelope, null, 2)}\n`, 'utf8');
-  await rename(tmp, cachePath);
-  return { cachePath, baseSha };
-}

package/.agents/scripts/lib/orchestration/recurring-failure-detector.js

@@ -1,152 +0,0 @@
-// .agents/scripts/lib/orchestration/recurring-failure-detector.js
-/**
- * recurring-failure-detector.js — Story #3062 / Epic #3051.
- *
- * Pure helper that scans a per-Epic lifecycle ledger for
- * `close-validate.end` `emitted` records and groups them by `failedGate`.
- * Returns one finding per gate that appears in **two or more distinct
- * Stories** within the same Epic. Findings are the substrate
- * `/deliver` consumes when upserting the cross-Story
- * `recurring-failure-class` structured comment on the Epic ticket.
- *
- * The helper is intentionally pure: no GitHub I/O, no global state. It
- * accepts either a pre-parsed `records[]` array (the hot path used by
- * `wave-tick` once it has already read the ledger for its in-flight
- * reconciliation) or a `ledgerPath` string (the convenience path that
- * reads + parses NDJSON on its own). When both are supplied,
- * `records` wins — the caller already paid the parse cost.
- *
- * Finding shape (sorted lexicographically by `gate` for determinism):
- *
- *   { gate: string, storyIds: number[], firstSeenAt: string, lastSeenAt: string }
- *
- * - `storyIds` is the deduplicated, ascending list of Story IDs that
- *   recorded a `close-validate.end` with `ok: false` and this gate.
- * - `firstSeenAt` / `lastSeenAt` are ISO-8601 strings pulled from the
- *   ledger record's top-level `ts` (set by `LedgerWriter.buildEmitted`),
- *   which is the canonical wall-clock for the event.
- *
- * @module lib/orchestration/recurring-failure-detector
- */
-
-import { existsSync, readFileSync } from 'node:fs';
-
-/**
- * Detect recurring failure classes across Stories within one Epic.
- *
- * @param {number} epicId Positive integer — the Epic the ledger belongs
- *   to. Used only for validation (the helper does not filter records by
- *   epicId; the ledger is already epic-scoped on disk).
- * @param {object} [opts]
- * @param {Array<object>} [opts.records] Pre-parsed NDJSON records. Each
- *   entry is the object emitted by `LedgerWriter.buildEmitted`
- *   (`{ kind, seqId, ts, event, payload }`).
- * @param {string} [opts.ledgerPath] Filesystem path to `lifecycle.ndjson`.
- *   Read + parsed only when `records` is absent. A missing file returns
- *   an empty findings array (no throw).
- * @returns {Array<{gate: string, storyIds: number[], firstSeenAt: string, lastSeenAt: string}>}
- */
-export function detectRecurringFailures(epicId, opts = {}) {
-  if (!Number.isInteger(epicId) || epicId <= 0) {
-    throw new TypeError(
-      'detectRecurringFailures: epicId must be a positive integer',
-    );
-  }
-  const records = resolveRecords(opts);
-  if (records.length === 0) return [];
-
-  /** @type {Map<string, {storyIds: Set<number>, firstSeenAt: string, lastSeenAt: string}>} */
-  const byGate = new Map();
-  for (const record of records) {
-    const finding = extractFailedGateRecord(record);
-    if (!finding) continue;
-    const { gate, storyId, ts } = finding;
-    const bucket = byGate.get(gate);
-    if (!bucket) {
-      byGate.set(gate, {
-        storyIds: new Set([storyId]),
-        firstSeenAt: ts,
-        lastSeenAt: ts,
-      });
-      continue;
-    }
-    bucket.storyIds.add(storyId);
-    if (ts < bucket.firstSeenAt) bucket.firstSeenAt = ts;
-    if (ts > bucket.lastSeenAt) bucket.lastSeenAt = ts;
-  }
-
-  const findings = [];
-  for (const [gate, bucket] of byGate) {
-    if (bucket.storyIds.size < 2) continue;
-    findings.push({
-      gate,
-      storyIds: Array.from(bucket.storyIds).sort((a, b) => a - b),
-      firstSeenAt: bucket.firstSeenAt,
-      lastSeenAt: bucket.lastSeenAt,
-    });
-  }
-  findings.sort((a, b) => (a.gate < b.gate ? -1 : a.gate > b.gate ? 1 : 0));
-  return findings;
-}
-
-/**
- * Resolve the records array from caller opts. Pre-parsed `records` wins
- * over a `ledgerPath` so callers that already loaded the file (e.g.
- * `wave-tick.js` doing its in-flight reconciliation) don't pay the parse
- * cost twice. A missing ledger file is treated as "no records" — the
- * tick must remain stateless and must not throw when nothing has
- * happened yet on this Epic.
- *
- * @param {object} opts
- * @returns {Array<object>}
- */
-function resolveRecords(opts) {
-  if (Array.isArray(opts.records)) return opts.records;
-  if (typeof opts.ledgerPath !== 'string' || opts.ledgerPath.length === 0) {
-    return [];
-  }
-  if (!existsSync(opts.ledgerPath)) return [];
-  let raw;
-  try {
-    raw = readFileSync(opts.ledgerPath, 'utf8');
-  } catch {
-    return [];
-  }
-  if (!raw) return [];
-  const out = [];
-  for (const line of raw.split(/\r?\n/)) {
-    if (!line) continue;
-    try {
-      out.push(JSON.parse(line));
-    } catch {
-      // Malformed line — skip; the ledger is append-only NDJSON and a
-      // partial write at process death is the only realistic source of
-      // un-parseable lines. The next tick will see the completed line.
-    }
-  }
-  return out;
-}
-
-/**
- * Decide whether a ledger record is a `close-validate.end` `emitted`
- * payload carrying a failed gate, and if so extract the
- * `(gate, storyId, ts)` triple the bucketing loop consumes. Returns
- * `null` for any record that doesn't satisfy every guard.
- *
- * @param {object} record
- * @returns {{gate: string, storyId: number, ts: string} | null}
- */
-function extractFailedGateRecord(record) {
-  if (!record || record.kind !== 'emitted') return null;
-  if (record.event !== 'close-validate.end') return null;
-  const payload = record.payload;
-  if (!payload || typeof payload !== 'object') return null;
-  if (payload.ok !== false) return null;
-  const gate = payload.failedGate;
-  if (typeof gate !== 'string' || gate.length === 0) return null;
-  const storyId = payload.storyId;
-  if (!Number.isInteger(storyId) || storyId <= 0) return null;
-  const ts = typeof record.ts === 'string' && record.ts ? record.ts : '';
-  if (!ts) return null;
-  return { gate, storyId, ts };
-}

package/.agents/scripts/lib/orchestration/retro/phases/checks.js

@@ -1,94 +0,0 @@
-/**
- * phases/checks.js — retro Phase 3: self-healing checks integration.
- *
- * Story #1290: invoke the self-healing checks registry with scope:'retro'
- * (read-only by construction — `runChecks` throws on autoFix:true under
- * this scope). Failures degrade gracefully to an empty findings list so
- * the retro never blocks on a probe error.
- *
- * Also owns the pure `appendChecksSection` helper that splices the
- * findings table into the composed retro body just above the
- * `<!-- retro-complete: ... -->` terminator.
- */
-
-import { runChecks as defaultRunChecks } from '../../../checks/index.js';
-import { assembleState as defaultAssembleState } from '../../../checks/state.js';
-
-/**
- * Story #1290: invoke the self-healing checks registry with scope:'retro'
- * (read-only by construction — `runChecks` throws on autoFix:true under
- * this scope). Failures degrade gracefully to an empty findings list so
- * the retro never blocks on a probe error.
- */
-export async function collectRetroFindings({
-  runChecksFn = defaultRunChecks,
-  assembleStateFn = defaultAssembleState,
-  cwd,
-  logger,
-}) {
-  try {
-    const state = await assembleStateFn({ scope: 'retro', cwd });
-    const result = await runChecksFn({
-      scope: 'retro',
-      autoFix: false,
-      state,
-    });
-    return Array.isArray(result?.findings) ? result.findings : [];
-  } catch (err) {
-    logger?.warn?.(
-      `[retro-runner] runChecks(scope:'retro') failed (continuing with empty findings): ${err?.message ?? err}`,
-    );
-    return [];
-  }
-}
-
-/**
- * Pure: append a "Self-Healing Checks" section to the retro body, listing
- * each finding's id, severity, summary, and fixCommand. When `findings` is
- * empty, the body is returned unchanged — this preserves the compact
- * "🟢 Clean sprint" shape under a clean manifest.
- *
- * The section is inserted **before** the `<!-- retro-complete: ... -->`
- * terminating marker so the marker stays at the end of the body (the
- * deliver pipeline searches for it as the EOF sentinel).
- *
- * Output format mirrors `/diagnose`'s renderTable for fixCommand display:
- * the same literal shell command appears verbatim in a fenced code block
- * so operators can copy-paste it.
- *
- * @param {string} body
- * @param {Array<import('../../../checks/index.js').Finding>} findings
- * @returns {string}
- */
-export function appendChecksSection(body, findings) {
-  if (!Array.isArray(findings) || findings.length === 0) return body;
-  const section = renderFindingsSection(findings);
-  const markerRe = /(<!--\s*retro-complete:[^>]*-->\s*)$/;
-  if (markerRe.test(body)) {
-    return body.replace(markerRe, `${section}\n$1`);
-  }
-  return `${body}\n${section}`;
-}
-
-function escapeCell(value) {
-  return String(value ?? '').replace(/\|/g, '\\|');
-}
-
-function renderFindingRow(f) {
-  const id = escapeCell(f?.id);
-  const severity = escapeCell(f?.severity);
-  const summary = escapeCell(f?.summary);
-  const fixCommand = escapeCell(f?.fixCommand);
-  return `| ${id} | ${severity} | ${summary} | \`${fixCommand}\` |`;
-}
-
-function renderFindingsSection(findings) {
-  return [
-    '### Self-Healing Checks',
-    '',
-    '| ID | Severity | Summary | Fix Command |',
-    '| --- | --- | --- | --- |',
-    ...findings.map(renderFindingRow),
-    '',
-  ].join('\n');
-}