mandrel 1.57.0

package/.agents/scripts/lib/findings/route-finding.js

@@ -0,0 +1,283 @@
+/**
+ * lib/findings/route-finding.js — Shared dedup/route helper for findings.
+ *
+ * This module is the single dedup/route implementation that both
+ * `audit-to-stories` and `qa-explore` consume. It does three things:
+ *
+ *   1. `fingerprintFinding(finding)` — a stable sha1 over the finding's
+ *      identity fields (`title`, `area`, `primaryFile`, `severity`,
+ *      `labels`). Two runs over the same finding MUST produce the same
+ *      sha, and unrelated prose drift MUST NOT change it.
+ *   2. `fingerprintFooter(sha)` / `parseFingerprintFooter(body)` — round-trip
+ *      the machine-readable `<!-- audit-fingerprints: sha,sha,... -->` marker
+ *      stamped into Issue bodies.
+ *   3. `routeFinding(finding, { searchIssues, searchCandidates })` — classify a
+ *      finding against existing Issues into one of `new | update-existing |
+ *      duplicate | regression-of-closed`. Routing is a two-stage pass: a
+ *      meaning-first **semantic candidate** pass runs FIRST (when a
+ *      `searchCandidates` port is injected, e.g. wired to
+ *      `semantic-issue-search.js`), then the exact **fingerprint
+ *      confirmation** pass runs SECOND over that candidate pool. When no
+ *      semantic port is injected the helper falls back to a fingerprint-only
+ *      lookup via the `searchIssues` port. Either way the ports query BOTH
+ *      open and closed issues; a closed fingerprint match yields
+ *      `regression-of-closed`.
+ *
+ * Pure orchestration: no network I/O lives here. The `searchIssues` /
+ * `searchCandidates` ports are injected by the caller (production wires them
+ * to the GitHub provider; tests pass an in-memory stub).
+ */
+
+import crypto from 'node:crypto';
+
+const SEP = '␟'; // unit separator — keeps fingerprint fields unambiguous
+const MARKER = 'audit-fingerprints:';
+const SHA1_RE = /^[0-9a-f]{40}$/;
+
+/**
+ * Normalise a single scalar identity field to a stable string.
+ * @param {unknown} value
+ * @returns {string}
+ */
+function normaliseField(value) {
+  if (value === null || value === undefined) return '';
+  return String(value).toLowerCase().trim();
+}
+
+/**
+ * Normalise the `labels` array into a stable, order-independent string.
+ * @param {unknown} labels
+ * @returns {string}
+ */
+function normaliseLabels(labels) {
+  if (!Array.isArray(labels)) return '';
+  return labels
+    .map((l) => normaliseField(l))
+    .filter((l) => l.length > 0)
+    .sort()
+    .join(',');
+}
+
+/**
+ * Compute the stable identity payload for a finding.
+ * @param {object} finding
+ * @returns {{ title: string, area: string, primaryFile: string, severity: string, labels: string }}
+ */
+function fingerprintComponents(finding) {
+  return {
+    title: normaliseField(finding?.title),
+    area: normaliseField(finding?.area),
+    primaryFile: normaliseField(finding?.primaryFile),
+    severity: normaliseField(finding?.severity),
+    labels: normaliseLabels(finding?.labels),
+  };
+}
+
+/**
+ * Stable per-finding fingerprint over {title, area, primaryFile, severity, labels}.
+ *
+ * @param {object} finding
+ * @returns {{ short: string, full: string, components: object }}
+ */
+export function fingerprintFinding(finding) {
+  const components = fingerprintComponents(finding);
+  const payload = [
+    components.title,
+    components.area,
+    components.primaryFile,
+    components.severity,
+    components.labels,
+  ].join(SEP);
+  const full = crypto.createHash('sha1').update(payload).digest('hex');
+  return { short: full.slice(0, 12), full, components };
+}
+
+/**
+ * Render the machine-readable fingerprint footer for one or more shas.
+ *
+ * Accepts either a single 40-char sha1 or an array of them, so a footer
+ * can carry every finding sha that a grouped Issue tracks
+ * (`<!-- audit-fingerprints: sha,sha,... -->`). The comma-joined form
+ * round-trips through {@link parseFingerprintFooter}. This is the single
+ * footer renderer shared by `audit-to-stories` and `qa-explore`; neither
+ * consumer defines its own marker.
+ *
+ * @param {string | string[]} shas — full 40-char sha1, or an array of them.
+ * @returns {string}
+ */
+export function fingerprintFooter(shas) {
+  const list = Array.isArray(shas) ? shas : [shas];
+  for (const sha of list) {
+    if (typeof sha !== 'string' || !SHA1_RE.test(sha)) {
+      throw new Error(
+        'fingerprintFooter: every sha must be a 40-char sha1 hex string',
+      );
+    }
+  }
+  return `<!-- ${MARKER} ${list.join(',')} -->`;
+}
+
+/**
+ * Extract fingerprint sha1s from an Issue body carrying the footer marker.
+ *
+ * @param {string} body
+ * @returns {string[]}
+ */
+export function parseFingerprintFooter(body) {
+  if (typeof body !== 'string') return [];
+  const match = body.match(/<!--\s*audit-fingerprints:\s*([^>]+?)\s*-->/);
+  if (!match) return [];
+  return match[1]
+    .split(',')
+    .map((s) => s.trim())
+    .filter((s) => SHA1_RE.test(s));
+}
+
+/**
+ * Confirm an issue body's footer actually carries the target sha. Guards
+ * against a false-positive search hit (e.g. a body that mentions the sha in
+ * prose rather than in the fingerprint footer).
+ *
+ * @param {{ body?: string }} issue
+ * @param {string} sha
+ * @returns {boolean}
+ */
+function issueCarriesFingerprint(issue, sha) {
+  if (typeof issue?.body !== 'string') return true;
+  return parseFingerprintFooter(issue.body).includes(sha);
+}
+
+/**
+ * Decide the route decision from a confirmed matched issue's state.
+ * @param {{ state?: string }} issue
+ * @returns {'update-existing'|'regression-of-closed'}
+ */
+function decisionForIssue(issue) {
+  const state = normaliseField(issue?.state);
+  return state === 'closed' ? 'regression-of-closed' : 'update-existing';
+}
+
+/**
+ * Decide the final route from a confirmed-match pool (issues that both
+ * surfaced in the candidate/search pass AND carry the finding's fingerprint
+ * in their footer). Shared by both the semantic-first and fingerprint-only
+ * code paths so the decision enum is identical regardless of how candidates
+ * were gathered.
+ *
+ * @param {Array<{ number: number, state: string }>} confirmed
+ * @param {string} sha
+ * @returns {{ decision: 'new'|'update-existing'|'duplicate'|'regression-of-closed', matchedIssue: object|null, fingerprint: string }}
+ */
+function decideFromConfirmed(confirmed, sha) {
+  if (confirmed.length === 0) {
+    return { decision: 'new', matchedIssue: null, fingerprint: sha };
+  }
+
+  const open = confirmed.filter((h) => normaliseField(h.state) === 'open');
+  if (open.length > 1) {
+    return { decision: 'duplicate', matchedIssue: open[0], fingerprint: sha };
+  }
+  if (open.length === 1) {
+    return {
+      decision: 'update-existing',
+      matchedIssue: open[0],
+      fingerprint: sha,
+    };
+  }
+
+  const closed = confirmed[0];
+  return {
+    decision: decisionForIssue(closed),
+    matchedIssue: closed,
+    fingerprint: sha,
+  };
+}
+
+/**
+ * Keep only the issue records that have the right wire shape AND carry the
+ * target fingerprint in their footer. A semantic candidate that merely *looks*
+ * similar but does not carry the sha is dropped here — semantic similarity
+ * widens the net; the fingerprint footer is what confirms identity.
+ *
+ * @param {Array<unknown>} hits
+ * @param {string} sha
+ * @returns {Array<{ number: number, state: string }>}
+ */
+function confirmFingerprint(hits, sha) {
+  if (!Array.isArray(hits)) return [];
+  return hits.filter(
+    (h) =>
+      h &&
+      typeof h.number === 'number' &&
+      typeof h.state === 'string' &&
+      issueCarriesFingerprint(h, sha),
+  );
+}
+
+/**
+ * Route a finding against existing Issues with a two-stage pass.
+ *
+ * **Stage 1 — semantic candidate search (first).** When a `searchCandidates`
+ * port is injected, it runs first to surface issues that *describe the same
+ * problem by meaning* across BOTH open and closed issues (and, when the
+ * caller wires it, an Epic's sub-issues). This widens the net beyond an exact
+ * fingerprint so a reworded title or a moved file does not hide a real
+ * duplicate. When no `searchCandidates` port is supplied the helper skips
+ * straight to Stage 2 over the `searchIssues` lookup — the legacy
+ * fingerprint-only behaviour, preserved verbatim.
+ *
+ * **Stage 2 — fingerprint confirmation (second).** Whatever candidates Stage 1
+ * produced are filtered down to those that actually carry the finding's
+ * fingerprint footer, then resolved:
+ *   - An open match → `update-existing` (or `duplicate` when more than one
+ *     open issue carries the fingerprint).
+ *   - A closed match (no open match) → `regression-of-closed`.
+ *   - No confirmed match → `new`.
+ *
+ * The decision enum is identical on both paths.
+ *
+ * @param {object} finding
+ * @param {object} ports
+ * @param {(sha: string) => Promise<Array<{ number: number, state: string, body?: string }>>} [ports.searchIssues]
+ *   Fingerprint-keyed lookup over open+closed issues. Required when
+ *   `searchCandidates` is not supplied.
+ * @param {(finding: object) => Promise<Array<{ number: number, state: string, title?: string, body?: string }>>} [ports.searchCandidates]
+ *   Meaning-first candidate search over open+closed issues (and Epic
+ *   sub-issues). When supplied, runs FIRST; its candidates are then
+ *   fingerprint-confirmed.
+ * @returns {Promise<{ decision: 'new'|'update-existing'|'duplicate'|'regression-of-closed', matchedIssue: object|null, fingerprint: string }>}
+ */
+export async function routeFinding(
+  finding,
+  { searchIssues, searchCandidates } = {},
+) {
+  if (
+    typeof searchCandidates !== 'function' &&
+    typeof searchIssues !== 'function'
+  ) {
+    throw new Error(
+      'routeFinding: a searchCandidates or searchIssues port is required',
+    );
+  }
+
+  const { full: sha } = fingerprintFinding(finding);
+
+  // Stage 1: semantic candidate pass first (when wired); else fingerprint
+  // lookup. Both yield a candidate pool drawn from open AND closed issues.
+  const hits =
+    typeof searchCandidates === 'function'
+      ? await searchCandidates(finding)
+      : await searchIssues(sha);
+
+  // Stage 2: confirm identity by fingerprint footer over the candidate pool.
+  const confirmed = confirmFingerprint(hits, sha);
+
+  return decideFromConfirmed(confirmed, sha);
+}
+
+export const __testing = {
+  MARKER,
+  SEP,
+  confirmFingerprint,
+  decideFromConfirmed,
+};

package/.agents/scripts/lib/findings/semantic-issue-search.js

@@ -0,0 +1,179 @@
+/**
+ * lib/findings/semantic-issue-search.js — Semantic candidate search for findings.
+ *
+ * Dedup has two stages. This module owns the **first** stage: a meaning-first
+ * candidate search that surfaces issues likely to describe the same problem as
+ * a finding, *before* the exact fingerprint confirmation in
+ * `route-finding.js` runs. The fingerprint is precise but brittle — a reworded
+ * title or a moved file produces a fresh sha even when the underlying problem
+ * is the same. The semantic pass casts a wider net so the confirmation stage
+ * has the right candidates to inspect.
+ *
+ * The search scans BOTH open and closed issues, and explicitly includes the
+ * sub-issues of any in-scope Epic (a regression that was closed under a prior
+ * Epic, or a still-open sibling Story, must be reachable). Epic sub-issues are
+ * fetched through the same injected port so a closed-then-reopened problem is
+ * never missed.
+ *
+ * Pure orchestration: no network I/O lives here. The `search` port — and the
+ * optional `listEpicSubIssues` port — are injected by the caller (production
+ * wires them to the GitHub provider; tests pass in-memory stubs). The unit
+ * test for this module performs no network calls.
+ */
+
+const DEFAULT_LIMIT = 25;
+
+/**
+ * Normalise a free-text string for token comparison: lowercased, trimmed,
+ * punctuation collapsed to spaces.
+ * @param {unknown} value
+ * @returns {string}
+ */
+function normaliseText(value) {
+  if (value === null || value === undefined) return '';
+  return String(value)
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, ' ')
+    .trim();
+}
+
+/**
+ * Tokenise normalised text into a Set of words, dropping very short noise
+ * tokens that carry no discriminating signal.
+ * @param {string} text
+ * @returns {Set<string>}
+ */
+function tokenize(text) {
+  return new Set(
+    normaliseText(text)
+      .split(' ')
+      .filter((t) => t.length >= 2),
+  );
+}
+
+/**
+ * Jaccard similarity between two token sets. Returns 0 when either set is
+ * empty so an empty query never spuriously matches.
+ * @param {Set<string>} a
+ * @param {Set<string>} b
+ * @returns {number} similarity in [0, 1]
+ */
+function jaccard(a, b) {
+  if (a.size === 0 || b.size === 0) return 0;
+  let intersection = 0;
+  for (const token of a) {
+    if (b.has(token)) intersection += 1;
+  }
+  const union = a.size + b.size - intersection;
+  return union === 0 ? 0 : intersection / union;
+}
+
+/**
+ * Build the search query text for a finding. The title carries the strongest
+ * signal; area and primaryFile sharpen it. This is the text both the
+ * (production) full-text search port and the local relevance scorer key on.
+ * @param {object} finding
+ * @returns {string}
+ */
+export function buildQuery(finding) {
+  return [finding?.title, finding?.area, finding?.primaryFile]
+    .map((v) => normaliseText(v))
+    .filter((v) => v.length > 0)
+    .join(' ');
+}
+
+/**
+ * Score a candidate issue against the finding's query tokens. Title overlap
+ * dominates; body overlap is a weaker secondary signal so a verbose body
+ * cannot drown out a precise title match.
+ * @param {Set<string>} queryTokens
+ * @param {{ title?: string, body?: string }} issue
+ * @returns {number} relevance score in [0, 1]
+ */
+function scoreIssue(queryTokens, issue) {
+  const titleScore = jaccard(queryTokens, tokenize(issue?.title));
+  const bodyScore = jaccard(queryTokens, tokenize(issue?.body));
+  return titleScore * 0.75 + bodyScore * 0.25;
+}
+
+/**
+ * De-duplicate issue records by `number`, keeping the first occurrence.
+ * @param {Array<{ number?: number }>} issues
+ * @returns {Array<object>}
+ */
+function dedupeByNumber(issues) {
+  const seen = new Set();
+  const out = [];
+  for (const issue of issues) {
+    const number = issue?.number;
+    if (typeof number !== 'number' || seen.has(number)) continue;
+    seen.add(number);
+    out.push(issue);
+  }
+  return out;
+}
+
+/**
+ * Find semantically-similar candidate issues for a finding.
+ *
+ * The `search` port runs the host's issue search (production: GitHub
+ * full-text search across open AND closed issues). When an `epicId` is in
+ * scope and a `listEpicSubIssues` port is supplied, that Epic's sub-issues
+ * are folded into the candidate pool so a regression closed under a prior
+ * Epic — or an open sibling Story — is never missed. The pooled candidates
+ * are scored locally by token overlap and returned best-first.
+ *
+ * @param {object} finding — canonical finding ({ title, area, primaryFile, ... }).
+ * @param {object} ports
+ * @param {(query: string) => Promise<Array<{ number: number, state: string, title?: string, body?: string }>>} ports.search
+ *   Required. Queries both open and closed issues for the finding's query text.
+ * @param {(epicId: number) => Promise<Array<{ number: number, state: string, title?: string, body?: string }>>} [ports.listEpicSubIssues]
+ *   Optional. Lists the sub-issues of the in-scope Epic.
+ * @param {object} [options]
+ * @param {number|null} [options.epicId] — Epic whose sub-issues to include.
+ * @param {number} [options.limit] — max candidates to return (default 25).
+ * @param {number} [options.minScore] — drop candidates scoring below this
+ *   (default 0; every scanned issue is a candidate).
+ * @returns {Promise<Array<{ number: number, state: string, title?: string, body?: string, score: number }>>}
+ *   candidates sorted by descending relevance score.
+ */
+export async function searchSemanticCandidates(
+  finding,
+  ports = {},
+  options = {},
+) {
+  const { search, listEpicSubIssues } = ports;
+  if (typeof search !== 'function') {
+    throw new Error('searchSemanticCandidates: search port is required');
+  }
+
+  const { epicId = null, limit = DEFAULT_LIMIT, minScore = 0 } = options;
+
+  const query = buildQuery(finding);
+  const queryTokens = tokenize(query);
+
+  const pool = [];
+
+  const searchHits = await search(query);
+  if (Array.isArray(searchHits)) pool.push(...searchHits);
+
+  if (epicId != null && typeof listEpicSubIssues === 'function') {
+    const subIssues = await listEpicSubIssues(epicId);
+    if (Array.isArray(subIssues)) pool.push(...subIssues);
+  }
+
+  const candidates = dedupeByNumber(pool).filter(
+    (issue) =>
+      issue &&
+      typeof issue.number === 'number' &&
+      typeof issue.state === 'string',
+  );
+
+  return candidates
+    .map((issue) => ({ ...issue, score: scoreIssue(queryTokens, issue) }))
+    .filter((issue) => issue.score >= minScore)
+    .sort((a, b) => b.score - a.score)
+    .slice(0, limit);
+}
+
+export const __testing = { tokenize, jaccard, scoreIssue, dedupeByNumber };

package/.agents/scripts/lib/findings/severity.js

@@ -0,0 +1,102 @@
+/**
+ * lib/findings/severity.js — Canonical severity vocabulary for the findings core.
+ *
+ * Single source of truth for finding severity (Story #3816). Three modules in
+ * the shared findings core previously each declared their own severity list —
+ * `classify-finding.js` (`[unknown, low, medium, high, critical]`),
+ * `promote-finding.js` (`SEVERITY_RANK` over `[critical … info]`), and the
+ * `qa-finding` / `qa-ledger` JSON schemas (`[critical, high, medium, low,
+ * info]`). Because `severity` is a `fingerprintFinding` identity field
+ * (`route-finding.js`), the same finding could hash to different SHAs depending
+ * on which path normalised its severity, silently weakening dedup. This module
+ * collapses all three onto one enum + one normaliser so the fingerprint is
+ * stable regardless of the code path that produced the severity.
+ *
+ * The canonical order is `critical | high | medium | low | info`, highest →
+ * lowest, and it MUST match the `severity` enum in
+ * `.agents/schemas/qa-ledger.schema.json` (and the mirrored `qa-finding`
+ * schema). Pure module: no I/O, no module-level state beyond the frozen
+ * constants.
+ */
+
+/**
+ * The closed, canonical set of severity values, ordered highest → lowest.
+ * This is the ONLY definition of the severity vocabulary in the findings core;
+ * `classify-finding.js` and `promote-finding.js` re-export / import it rather
+ * than re-declaring their own list. Mirrors the `severity` enum in
+ * `qa-ledger.schema.json` / `qa-finding.schema.json`.
+ */
+export const SEVERITIES = Object.freeze([
+  'critical',
+  'high',
+  'medium',
+  'low',
+  'info',
+]);
+
+/**
+ * The severity applied when a finding carries no recognisable severity. `info`
+ * is the canonical floor (lowest level). The ledger/finding schemas REQUIRE a
+ * severity drawn from {@link SEVERITIES}, so this fallback only fires on
+ * malformed input — and because both the classify and promote paths share it,
+ * malformed input still fingerprints identically across the two paths.
+ */
+export const DEFAULT_SEVERITY = 'info';
+
+const SEVERITY_SET = new Set(SEVERITIES);
+
+/**
+ * Numeric rank for "highest severity wins" comparisons, derived from the
+ * canonical order so the ranking has exactly one source. `critical` is the
+ * highest rank (`SEVERITIES.length - 1`); `info` is `0`.
+ *
+ * @type {Readonly<Record<string, number>>}
+ */
+export const SEVERITY_RANK = Object.freeze(
+  Object.fromEntries(
+    SEVERITIES.map((severity, index) => [
+      severity,
+      SEVERITIES.length - 1 - index,
+    ]),
+  ),
+);
+
+/**
+ * Normalise an arbitrary severity input to one of {@link SEVERITIES}. Case- and
+ * whitespace-insensitive. A non-string, empty, or unrecognised value resolves
+ * to `fallback` (default {@link DEFAULT_SEVERITY}) rather than throwing — the
+ * findings pipeline treats severity as advisory signal, never a hard gate.
+ *
+ * @param {unknown} value — the raw severity field off a finding/ledger item.
+ * @param {string} [fallback=DEFAULT_SEVERITY] — canonical value to return when
+ *   `value` is absent or unrecognised.
+ * @returns {string} one of {@link SEVERITIES}.
+ */
+export function normalizeSeverity(value, fallback = DEFAULT_SEVERITY) {
+  if (typeof value !== 'string') return fallback;
+  const normalized = value.trim().toLowerCase();
+  return SEVERITY_SET.has(normalized) ? normalized : fallback;
+}
+
+/**
+ * The highest-ranked severity across a list of raw severity values. Returns
+ * {@link DEFAULT_SEVERITY} for an empty list. Each value is normalised through
+ * {@link normalizeSeverity}, so the result is always one of {@link SEVERITIES}.
+ *
+ * @param {Iterable<unknown>} values — raw severity strings (or anything
+ *   `normalizeSeverity` accepts).
+ * @returns {string} one of {@link SEVERITIES}.
+ */
+export function highestSeverity(values) {
+  let best = DEFAULT_SEVERITY;
+  let bestRank = -1;
+  for (const value of values) {
+    const severity = normalizeSeverity(value);
+    const rank = SEVERITY_RANK[severity];
+    if (rank > bestRank) {
+      bestRank = rank;
+      best = severity;
+    }
+  }
+  return best;
+}

package/.agents/scripts/lib/gates/baseline-store.js

@@ -0,0 +1,106 @@
+/**
+ * Pure-I/O baseline-JSON store: encapsulates the Story #1120 `--epic-ref`
+ * fallback chain (try `readAtRef` → fall back to fs with a warning) and
+ * an atomic tmp-rename write. Shape validation stays in each gate.
+ * Missing files throw `BaselineNotFoundError`; write failures throw
+ * `BaselineWriteError` — no swallowing.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { readBaselineAtRef as defaultReadAtRef } from '../baseline-loader.js';
+import { Logger } from '../Logger.js';
+
+export class BaselineNotFoundError extends Error {
+  constructor(message, details = {}) {
+    super(message);
+    this.name = 'BaselineNotFoundError';
+    Object.assign(this, details);
+  }
+}
+
+export class BaselineWriteError extends Error {
+  constructor(message, details = {}) {
+    super(message);
+    this.name = 'BaselineWriteError';
+    Object.assign(this, details);
+  }
+}
+
+function absPath(baselinePath, projectRoot) {
+  if (typeof baselinePath !== 'string' || baselinePath.length === 0) {
+    throw new TypeError('[baseline-store] baselinePath is required');
+  }
+  return path.isAbsolute(baselinePath)
+    ? baselinePath
+    : path.resolve(projectRoot ?? process.cwd(), baselinePath);
+}
+
+// Default working-tree reader. Throws `BaselineNotFoundError` when absent.
+function defaultReadFromTree({ baselinePath, projectRoot } = {}) {
+  const abs = absPath(baselinePath, projectRoot);
+  if (!fs.existsSync(abs)) {
+    throw new BaselineNotFoundError(`baseline not found at ${baselinePath}`, {
+      path: abs,
+      baselinePath,
+    });
+  }
+  return JSON.parse(fs.readFileSync(abs, 'utf8'));
+}
+
+/**
+ * Load a baseline JSON file with the Story #1120 `--epic-ref` fallback
+ * chain. Gates may supply a `readFromTree` to preserve a "missing →
+ * empty" bootstrap (e.g. MI returns `{}`); otherwise the default throws
+ * `BaselineNotFoundError`.
+ */
+export function loadBaseline({
+  baselinePath,
+  epicRef = null,
+  projectRoot,
+  readAtRef = defaultReadAtRef,
+  readFromTree = defaultReadFromTree,
+  logger = Logger,
+  label = 'baseline-store',
+} = {}) {
+  if (epicRef) {
+    try {
+      const parsed = readAtRef(epicRef, baselinePath);
+      if (parsed !== null && parsed !== undefined) return parsed;
+    } catch (err) {
+      logger.warn(
+        `[${label}] ⚠ failed to read baseline at ref "${epicRef}": ${err?.message ?? err}. Falling back to working-tree read.`,
+      );
+    }
+  }
+  return readFromTree({ baselinePath, projectRoot });
+}
+
+/**
+ * Atomic write via temp-file + rename. 2-space indent + trailing newline.
+ */
+export function writeBaseline({
+  baselinePath,
+  data,
+  projectRoot,
+  indent = 2,
+} = {}) {
+  const abs = absPath(baselinePath, projectRoot);
+  const tmp = `${abs}.tmp`;
+  try {
+    const serialised = `${JSON.stringify(data, null, indent)}\n`;
+    fs.mkdirSync(path.dirname(abs), { recursive: true });
+    fs.writeFileSync(tmp, serialised, 'utf8');
+    fs.renameSync(tmp, abs);
+  } catch (err) {
+    try {
+      fs.rmSync(tmp, { force: true });
+    } catch {
+      /* best-effort cleanup */
+    }
+    throw new BaselineWriteError(
+      `[baseline-store] failed to write baseline at ${baselinePath}: ${err?.message ?? err}`,
+      { path: abs, cause: err },
+    );
+  }
+}