backpass 0.1.0

package/src/fold.js

@@ -0,0 +1,214 @@
+import { similarity } from "./memory.js";
+import { GAP_SIMILARITY_THRESHOLD, gapSource } from "./gap-ledger.js";
+
+/**
+ * Stage 2 of the pipeline (design section 3): fold per-transcript evidence into one
+ * compact summary. Entirely deterministic - no model involved.
+ *
+ * Three things happen here that the synthesis pass depends on:
+ *
+ *  1. Evidence is grouped by instruction id, giving per-instruction positive/negative
+ *     counts and, crucially, `relevance` = sessions where the instruction drew any
+ *     evidence / sessions analyzed. That ratio is what decides memory-file vs skill
+ *     placement in section 7.
+ *  2. Near-duplicate gaps from different sessions are clustered, so "three sessions
+ *     re-derived the db schema" arrives as one item with three quotes.
+ *  3. Gap clusters below `minGapEvidence` are dropped. Batch size > 1: one bad session
+ *     never rewrites the weights. Sessions are counted across runs, not per run: when the
+ *     caller passes `gapObservations` (the pruned gap ledger, `src/gap-ledger.js`) the
+ *     clusters are built from those instead of this run's records, so a gap seen once now
+ *     and once on a later run graduates. Without a ledger the records alone are used.
+ */
+
+/**
+ * @param {object[]} evidenceRecords
+ * @param {{ minGapEvidence?: number, memoryFile?: object|null, gapObservations?: object[]|null }} [options]
+ */
+export function foldEvidence(evidenceRecords, { minGapEvidence = 2, memoryFile = null, gapObservations = null } = {}) {
+  const usable = evidenceRecords.filter((e) => e && e.status === "ok");
+  const analyzedSessions = usable.length;
+
+  const instructions = new Map();
+  let positiveCount = 0;
+  let negativeCount = 0;
+  let usedRawCount = 0;
+
+  const touch = (id) => {
+    if (!instructions.has(id)) {
+      instructions.set(id, {
+        instruction: id,
+        positive: 0,
+        negative: 0,
+        sessions: new Set(),
+        quotes: [],
+      });
+    }
+    return instructions.get(id);
+  };
+
+  const recordObservations = [];
+  for (const record of usable) {
+    if (record.usedRawTranscript) usedRawCount += 1;
+    const source = gapSource(record.transcript);
+
+    for (const polarity of ["positive", "negative"]) {
+      for (const item of record[polarity] || []) {
+        const entry = touch(item.instruction);
+        entry[polarity] += 1;
+        entry.sessions.add(record.transcript.id);
+        entry.quotes.push({ polarity, text: item.quote, effect: item.effect, moment: item.moment, source });
+        if (polarity === "positive") positiveCount += 1;
+        else negativeCount += 1;
+      }
+    }
+
+    for (const gap of record.gaps || []) {
+      recordObservations.push({
+        proposedInstruction: gap.proposedInstruction,
+        mistake: gap.mistake,
+        quote: gap.quote,
+        recurrenceRisk: gap.recurrenceRisk,
+        source,
+        sessionId: record.transcript.id,
+      });
+    }
+  }
+
+  const gapClusters = clusterGapObservations(gapObservations ?? recordObservations);
+
+  // Instructions that exist in the file but drew no evidence at all are the strongest
+  // removal / extraction candidates, so they must appear in the summary too.
+  if (memoryFile) {
+    for (const unit of memoryFile.units) touch(unit.id);
+  }
+
+  const instructionRows = [...instructions.values()]
+    .map((entry) => {
+      const unit = memoryFile?.units.find((u) => u.id === entry.instruction) || null;
+      return {
+        instruction: entry.instruction,
+        positive: entry.positive,
+        negative: entry.negative,
+        sessions: entry.sessions.size,
+        relevance: analyzedSessions ? entry.sessions.size / analyzedSessions : 0,
+        tokens: unit?.tokens ?? null,
+        section: unit?.section ?? null,
+        known: Boolean(unit),
+        quotes: entry.quotes.slice(0, 6),
+      };
+    })
+    .sort((a, b) => b.negative - a.negative || b.sessions - a.sessions || a.instruction.localeCompare(b.instruction));
+
+  const gaps = gapClusters
+    .map((cluster) => ({
+      proposedInstruction: cluster.proposedInstruction,
+      sessions: cluster.sessions.size,
+      recurrenceRisk: highestRisk(cluster.items),
+      quotes: cluster.items.slice(0, 6).map((i) => ({ text: i.quote, effect: i.mistake, source: i.source })),
+    }))
+    .filter((cluster) => cluster.sessions >= minGapEvidence)
+    .sort((a, b) => b.sessions - a.sessions);
+
+  const droppedGapSingletons = gapClusters.length - gaps.length;
+
+  return {
+    version: 1,
+    generatedAt: new Date().toISOString(),
+    analyzedSessions,
+    totals: {
+      positive: positiveCount,
+      negative: negativeCount,
+      gapClusters: gaps.length,
+      droppedGapSingletons,
+      usedRawTranscript: usedRawCount,
+    },
+    instructions: instructionRows,
+    gaps,
+  };
+}
+
+/**
+ * Greedy similarity clustering over gap observations. A cluster counts each session once
+ * no matter how many observations it contributed (re-analysis, duplicate reports).
+ */
+export function clusterGapObservations(observations) {
+  const clusters = [];
+  for (const obs of observations) {
+    if (!obs || !obs.proposedInstruction) continue;
+    const cluster = clusters.find(
+      (c) => similarity(c.proposedInstruction, obs.proposedInstruction) >= GAP_SIMILARITY_THRESHOLD,
+    );
+    const item = {
+      mistake: obs.mistake,
+      quote: obs.quote,
+      recurrenceRisk: obs.recurrenceRisk,
+      source: obs.source,
+      sessionId: obs.sessionId,
+    };
+    if (cluster) {
+      if (!cluster.sessions.has(obs.sessionId)) cluster.items.push(item);
+      cluster.sessions.add(obs.sessionId);
+      // Keep the shortest phrasing: it generalizes best.
+      if (obs.proposedInstruction.length < cluster.proposedInstruction.length) {
+        cluster.proposedInstruction = obs.proposedInstruction;
+      }
+    } else {
+      clusters.push({
+        proposedInstruction: obs.proposedInstruction,
+        sessions: new Set([obs.sessionId]),
+        items: [item],
+      });
+    }
+  }
+  return clusters;
+}
+
+function highestRisk(items) {
+  const order = { high: 3, medium: 2, low: 1 };
+  return items.reduce((best, i) => (order[i.recurrenceRisk] > order[best] ? i.recurrenceRisk : best), "low");
+}
+
+/** Compact rendering of the folded evidence for the synthesis prompt. */
+export function renderEvidenceForPrompt(summary) {
+  const lines = [];
+
+  lines.push(`Sessions analyzed: ${summary.analyzedSessions}`);
+  lines.push(
+    `Totals: ${summary.totals.positive} positive, ${summary.totals.negative} negative, ` +
+      `${summary.totals.gapClusters} gap clusters (${summary.totals.droppedGapSingletons} singletons dropped below threshold)`,
+  );
+  lines.push("");
+  lines.push("### Per-instruction evidence");
+  for (const row of summary.instructions) {
+    const relevance = `${(row.relevance * 100).toFixed(1)}%`;
+    const cost = row.tokens === null ? "" : ` cost=${row.tokens}tok`;
+    lines.push(
+      `- [${row.instruction}] +${row.positive} -${row.negative} sessions=${row.sessions} relevance=${relevance}${cost}` +
+        (row.known ? "" : " (id not found in current file - stale reference)"),
+    );
+    for (const quote of row.quotes.slice(0, 3)) {
+      lines.push(`    ${quote.polarity === "negative" ? "-" : "+"} "${oneLine(quote.text)}" (${quote.source})`);
+    }
+  }
+
+  lines.push("");
+  lines.push("### Gap clusters (mistakes no current instruction covers)");
+  if (!summary.gaps.length) {
+    lines.push("- none above the evidence threshold");
+  }
+  for (const gap of summary.gaps) {
+    lines.push(`- sessions=${gap.sessions} risk=${gap.recurrenceRisk} :: ${gap.proposedInstruction}`);
+    for (const quote of gap.quotes.slice(0, 3)) {
+      lines.push(`    "${oneLine(quote.text)}" (${quote.source})`);
+    }
+  }
+
+  return lines.join("\n");
+}
+
+function oneLine(text) {
+  const flat = String(text || "")
+    .replace(/\s+/g, " ")
+    .trim();
+  return flat.length > 240 ? `${flat.slice(0, 240)}...` : flat;
+}

package/src/gap-ledger.js

@@ -0,0 +1,174 @@
+import { similarity } from "./memory.js";
+import { parseSince } from "./config.js";
+import { sha256 } from "./state.js";
+
+/**
+ * Durable gap corroboration across runs (`.backpass/gap-ledger.json`).
+ *
+ * The fold stage only promotes a gap once `minGapEvidence` distinct sessions report it.
+ * Counting those sessions from the evidence that happens to be on disk is lossy: a
+ * transcript's evidence file is rewritten every time it is re-analyzed against a changed
+ * memory file (every apply changes the hash), and the analysis model rephrases gaps
+ * between runs, so two observations of one gap rarely line up in a single fold. This
+ * ledger keeps every gap observation, keyed by gap identity and session, so a gap seen in
+ * one session now and in another session on a later run still reaches the bar.
+ *
+ * Identity and freshness rules:
+ *
+ *  - A gap's identity is its proposed instruction, matched by the same bigram similarity
+ *    the in-run clustering uses (`GAP_SIMILARITY_THRESHOLD`), against the ledger's
+ *    canonical phrasing (the shortest seen). The entry id is a hash of the first phrasing
+ *    and never changes, so rephrasing does not split an entry.
+ *  - Sessions are keyed by transcript id (harness + native session id), so re-analyzing
+ *    or re-sampling the same session overwrites its observation and never adds a count.
+ *  - A gap is a fact about its session: re-analysis that no longer mentions it is model
+ *    noise, not the session changing, so observations are only ever replaced, not removed
+ *    by absence. They retire in exactly two ways: the memory file gains an instruction
+ *    that covers the gap (`GAP_COVERED_THRESHOLD`, the `reanchor` bar), or the sighting
+ *    has waited longer than `gapLedgerMaxAge` for a partner, counted from when backpass
+ *    first saw it (re-analysis never refreshes that clock; session age itself is already
+ *    bounded by discovery's `since` at entry). Keying to the memory hash instead would
+ *    reset the count on every unrelated edit, which is the failure this ledger fixes.
+ *  - The file is fail-soft: a missing or corrupt ledger is rebuilt from this run's
+ *    evidence, which is exactly what the pre-ledger fold saw.
+ */
+
+/** Two gap phrasings at or above this Sorensen-Dice bigram score are one gap. */
+export const GAP_SIMILARITY_THRESHOLD = 0.45;
+/** A memory-file instruction this similar to a gap's proposal covers it. */
+export const GAP_COVERED_THRESHOLD = 0.6;
+
+export function emptyGapLedger() {
+  return { version: 1, entries: {} };
+}
+
+export function gapSource(transcript = {}) {
+  const date = transcript.startedAt ? new Date(transcript.startedAt).toISOString().slice(0, 10) : "unknown date";
+  return `${transcript.harness} · ${String(transcript.id || "")
+    .replace(/^[a-z-]+-/, "")
+    .slice(0, 8)} · ${date}`;
+}
+
+function normalize(text) {
+  return String(text || "")
+    .toLowerCase()
+    .replace(/[^a-z0-9\s]/g, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+export function gapEntryId(memoryPath, proposedInstruction) {
+  return sha256(`${memoryPath}\n${normalize(proposedInstruction)}`).slice(0, 16);
+}
+
+/** The ledger entry a proposed instruction belongs to, or null. */
+export function findGapEntry(ledger, memoryPath, proposedInstruction) {
+  let best = null;
+  let bestScore = 0;
+  for (const entry of Object.values(ledger.entries)) {
+    if (entry.memoryPath !== memoryPath) continue;
+    const score = similarity(entry.proposedInstruction, proposedInstruction);
+    if (score >= GAP_SIMILARITY_THRESHOLD && score > bestScore) {
+      best = entry;
+      bestScore = score;
+    }
+  }
+  return best;
+}
+
+/**
+ * Fold this run's evidence into the ledger. One observation per (gap, session); a
+ * session seen again replaces its own observation and keeps its first-seen timestamp.
+ */
+export function recordGapObservations(ledger, evidenceRecords, { now = new Date() } = {}) {
+  const observedAt = new Date(now).toISOString();
+  let recorded = 0;
+  for (const record of evidenceRecords) {
+    if (!record || record.status !== "ok" || !record.memoryPath) continue;
+    const transcript = record.transcript || {};
+    if (!transcript.id) continue;
+    for (const gap of record.gaps || []) {
+      if (!gap || !gap.proposedInstruction) continue;
+      let entry = findGapEntry(ledger, record.memoryPath, gap.proposedInstruction);
+      if (!entry) {
+        const id = gapEntryId(record.memoryPath, gap.proposedInstruction);
+        entry = ledger.entries[id] = {
+          id,
+          memoryPath: record.memoryPath,
+          proposedInstruction: gap.proposedInstruction,
+          sessions: {},
+        };
+      } else if (gap.proposedInstruction.length < entry.proposedInstruction.length) {
+        // Keep the shortest phrasing: it generalizes best (same rule as the in-run fold).
+        entry.proposedInstruction = gap.proposedInstruction;
+      }
+      const prior = entry.sessions[transcript.id];
+      entry.sessions[transcript.id] = {
+        firstObservedAt: prior?.firstObservedAt || observedAt,
+        observedAt,
+        sessionStartedAt: transcript.startedAt ?? prior?.sessionStartedAt ?? null,
+        memoryHash: record.memoryHash || null,
+        source: gapSource(transcript),
+        mistake: gap.mistake,
+        quote: gap.quote,
+        recurrenceRisk: gap.recurrenceRisk,
+      };
+      recorded += 1;
+    }
+  }
+  return recorded;
+}
+
+/**
+ * Retire observations that no longer count: sightings first seen more than `maxAge` ago
+ * (a duration like `90d`, `all` to disable) and gaps the current memory file now covers.
+ */
+export function pruneGapLedger(
+  ledger,
+  { memoryFile = null, memoryPath = null, maxAge = "90d", now = new Date() } = {},
+) {
+  const maxAgeMs = parseSince(maxAge);
+  const cutoff = maxAgeMs === null ? -Infinity : new Date(now).getTime() - maxAgeMs;
+  const stats = { expired: 0, covered: 0 };
+
+  for (const [id, entry] of Object.entries(ledger.entries)) {
+    const applies = memoryPath === null || entry.memoryPath === memoryPath;
+    if (applies && memoryFile && isCovered(memoryFile, entry.proposedInstruction)) {
+      stats.covered += Object.keys(entry.sessions).length;
+      delete ledger.entries[id];
+      continue;
+    }
+    for (const [sessionId, obs] of Object.entries(entry.sessions)) {
+      const when = Date.parse(obs.firstObservedAt || obs.observedAt);
+      if (!Number.isFinite(when) || when < cutoff) {
+        stats.expired += 1;
+        delete entry.sessions[sessionId];
+      }
+    }
+    if (!Object.keys(entry.sessions).length) delete ledger.entries[id];
+  }
+  return stats;
+}
+
+function isCovered(memoryFile, proposedInstruction) {
+  return (memoryFile.units || []).some((unit) => similarity(unit.text, proposedInstruction) >= GAP_COVERED_THRESHOLD);
+}
+
+/** Flatten the ledger into the observation list `foldEvidence` clusters over. */
+export function ledgerGapObservations(ledger, memoryPath) {
+  const observations = [];
+  for (const entry of Object.values(ledger.entries)) {
+    if (entry.memoryPath !== memoryPath) continue;
+    for (const [sessionId, obs] of Object.entries(entry.sessions)) {
+      observations.push({
+        proposedInstruction: entry.proposedInstruction,
+        sessionId,
+        source: obs.source,
+        mistake: obs.mistake,
+        quote: obs.quote,
+        recurrenceRisk: obs.recurrenceRisk,
+      });
+    }
+  }
+  return observations;
+}

package/src/logger.js

@@ -0,0 +1,74 @@
+const NO_COLOR = process.env.NO_COLOR !== undefined || !process.stderr.isTTY;
+const CSI = "\u001b[";
+
+const wrap = (code) => (s) => (NO_COLOR ? String(s) : `${CSI}${code}m${s}${CSI}0m`);
+
+export const color = {
+  dim: wrap("2"),
+  bold: wrap("1"),
+  red: wrap("31"),
+  green: wrap("32"),
+  yellow: wrap("33"),
+  blue: wrap("34"),
+  cyan: wrap("36"),
+};
+
+let quiet = false;
+let sink = null;
+
+export function setQuiet(value) {
+  quiet = Boolean(value);
+}
+
+/**
+ * While the live progress view owns stderr, progress lines are diverted here,
+ * buffered, and replayed verbatim on teardown - so scrollback after a TUI run
+ * is byte-identical to a run without one. Pass null to restore direct output.
+ */
+export function setLoggerSink(fn) {
+  sink = fn;
+}
+
+/** Human-facing progress and diagnostics go to stderr so stdout stays pipeable. */
+export function info(...args) {
+  if (quiet) return;
+  if (sink) {
+    sink(args.join(" "));
+    return;
+  }
+  console.error(...args);
+}
+
+export function step(label, detail = "") {
+  info(`${color.cyan("·")} ${label}${detail ? ` ${color.dim(detail)}` : ""}`);
+}
+
+export function warn(message) {
+  const line = `${color.yellow("warn")} ${message}`;
+  if (sink) {
+    sink(line);
+    return;
+  }
+  console.error(line);
+}
+
+export function fail(message) {
+  console.error(`${color.red("error")} ${message}`);
+}
+
+/** Structured results go to stdout. */
+export function out(text) {
+  console.log(text);
+}
+
+export function json(value) {
+  console.log(JSON.stringify(value, null, 2));
+}
+
+export class UserError extends Error {
+  constructor(message, hint) {
+    super(message);
+    this.name = "UserError";
+    this.hint = hint;
+  }
+}

package/src/memory.js

@@ -0,0 +1,244 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import { sha256 } from "./state.js";
+import { estimateTokens } from "./tokens.js";
+
+/**
+ * Memory files are the weights. To talk about them precisely, backpass parses each
+ * file into addressable instruction units (design section 3.1):
+ *
+ *   - sections come from markdown headings
+ *   - units come from list items and paragraphs inside those sections
+ *   - each unit gets a content hash (survives cosmetic edits elsewhere in the file)
+ *     and a readable alias AG-001, AG-002, ... used in prompts and evidence
+ *
+ * Evidence anchors to the alias; the hash is what lets us re-anchor across runs.
+ */
+
+const FENCE = /^\s*(```|~~~)/;
+
+function normalizeForHash(text) {
+  return text
+    .toLowerCase()
+    .replace(/[`*_~]/g, "")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+export function unitHash(text) {
+  return sha256(normalizeForHash(text)).slice(0, 12);
+}
+
+function alias(index) {
+  return `AG-${String(index + 1).padStart(3, "0")}`;
+}
+
+/**
+ * Split memory-file text into instruction units. Fenced code blocks stay attached to
+ * the paragraph they belong to rather than being split into nonsense lines.
+ */
+export function parseMemoryUnits(text) {
+  const lines = text.split("\n");
+  const units = [];
+  const headings = [];
+
+  let buffer = [];
+  let bufferStart = 0;
+  let inFence = false;
+  let fenceMarker = null;
+
+  const flush = (endLine) => {
+    const raw = buffer.join("\n");
+    if (raw.trim()) {
+      units.push({
+        text: raw.replace(/\s+$/, ""),
+        section: headings.join(" > "),
+        startLine: bufferStart + 1,
+        endLine,
+      });
+    }
+    buffer = [];
+  };
+
+  for (let i = 0; i < lines.length; i += 1) {
+    const line = lines[i];
+
+    if (FENCE.test(line)) {
+      const marker = line.trim().slice(0, 3);
+      if (!inFence) {
+        inFence = true;
+        fenceMarker = marker;
+      } else if (marker === fenceMarker) {
+        inFence = false;
+      }
+      if (!buffer.length) bufferStart = i;
+      buffer.push(line);
+      continue;
+    }
+
+    if (inFence) {
+      buffer.push(line);
+      continue;
+    }
+
+    const heading = line.match(/^(#{1,6})\s+(.*)$/);
+    if (heading) {
+      flush(i);
+      const depth = heading[1].length;
+      headings.length = Math.min(headings.length, depth - 1);
+      headings[depth - 1] = heading[2].trim();
+      for (let d = 0; d < depth - 1; d += 1) headings[d] = headings[d] ?? "";
+      continue;
+    }
+
+    const isListItem = /^\s*([-*+]|\d+[.)])\s+/.test(line);
+    const isBlank = line.trim() === "";
+
+    if (isBlank) {
+      flush(i);
+      continue;
+    }
+    // A new list item starts a new unit; continuation lines stay with it.
+    if (isListItem && buffer.length && /^\s*([-*+]|\d+[.)])\s+/.test(buffer[0])) {
+      flush(i);
+    }
+    if (!buffer.length) bufferStart = i;
+    buffer.push(line);
+  }
+  flush(lines.length);
+
+  return units.map((unit, index) => ({
+    id: alias(index),
+    hash: unitHash(unit.text),
+    tokens: estimateTokens(unit.text),
+    ...unit,
+  }));
+}
+
+export function readMemoryFile(repoRoot, relativePath) {
+  const absolute = path.join(repoRoot, relativePath);
+  if (!fs.existsSync(absolute)) return null;
+  const text = fs.readFileSync(absolute, "utf8");
+  return {
+    path: relativePath,
+    absolute,
+    text,
+    hash: `sha256:${sha256(text).slice(0, 16)}`,
+    tokens: estimateTokens(text),
+    units: parseMemoryUnits(text),
+  };
+}
+
+/** Load every configured memory file that actually exists in the repo. */
+export function loadMemoryFiles(repoRoot, memoryFiles) {
+  return memoryFiles.map((f) => readMemoryFile(repoRoot, f)).filter(Boolean);
+}
+
+/** Combined hash across all memory files - the "weights version" evidence is keyed to. */
+export function memorySetHash(files) {
+  return `sha256:${sha256(files.map((f) => `${f.path}:${f.hash}`).join("|")).slice(0, 16)}`;
+}
+
+/**
+ * Render the instruction index that both prompt tiers see. It is a lookup table keyed
+ * by alias, never a stand-in for the file: units are listed with the lines they occupy
+ * so the synthesis agent can find them in the raw file it edits.
+ */
+export function renderInstructionIndex(file) {
+  return file.units
+    .map((u) => {
+      const lines = u.startLine === u.endLine ? `L${u.startLine}` : `L${u.startLine}-${u.endLine}`;
+      return `[${u.id}] (${u.tokens} tok, ${lines})${u.section ? ` <${u.section}>` : ""}\n${u.text}`;
+    })
+    .join("\n\n");
+}
+
+function bigrams(text) {
+  const words = normalizeForHash(text).split(" ").filter(Boolean);
+  if (words.length < 2) return new Set(words);
+  const out = new Set();
+  for (let i = 0; i < words.length - 1; i += 1) out.add(`${words[i]} ${words[i + 1]}`);
+  return out;
+}
+
+/** Sorensen-Dice similarity over word bigrams, used for re-anchoring. */
+export function similarity(a, b) {
+  const A = bigrams(a);
+  const B = bigrams(b);
+  if (!A.size || !B.size) return A.size === B.size ? 1 : 0;
+  let shared = 0;
+  for (const g of A) if (B.has(g)) shared += 1;
+  return (2 * shared) / (A.size + B.size);
+}
+
+/**
+ * Re-anchor an instruction reference from a previous run onto the current file.
+ * Exact hash match wins; otherwise the best fuzzy match above threshold; otherwise stale.
+ */
+export function reanchor(reference, file, threshold = 0.6) {
+  if (reference.hash) {
+    const exact = file.units.find((u) => u.hash === reference.hash);
+    if (exact) return { unit: exact, match: "hash", score: 1 };
+  }
+  if (reference.id) {
+    const byId = file.units.find((u) => u.id === reference.id);
+    if (byId && (!reference.text || similarity(byId.text, reference.text) >= threshold)) {
+      return { unit: byId, match: "id", score: 1 };
+    }
+  }
+  if (!reference.text) return { unit: null, match: "stale", score: 0 };
+
+  let best = null;
+  let bestScore = 0;
+  for (const unit of file.units) {
+    const score = similarity(unit.text, reference.text);
+    if (score > bestScore) {
+      best = unit;
+      bestScore = score;
+    }
+  }
+  if (best && bestScore >= threshold) return { unit: best, match: "fuzzy", score: bestScore };
+  return { unit: null, match: "stale", score: bestScore };
+}
+
+/**
+ * Pointer detection. The convention for covering both harness families without
+ * duplicating content is a canonical AGENTS.md plus a CLAUDE.md that only contains the
+ * `@AGENTS.md` import (Claude Code inlines it at load time). Such a file carries no
+ * instructions of its own, so optimizing the target is fully correct and the pointer
+ * stays valid afterwards.
+ *
+ * A file is a pointer to `target` when, ignoring blank lines and HTML comments, its
+ * only content is the import line (`@AGENTS.md` or `@./AGENTS.md`).
+ */
+export function isPointerTo(text, target) {
+  const lines = text
+    .replace(/<!--[\s\S]*?-->/g, "")
+    .split("\n")
+    .map((l) => l.trim())
+    .filter(Boolean);
+  if (lines.length !== 1) return false;
+  const ref = lines[0].replace(/^@\.\//, "@");
+  return ref === `@${target}`;
+}
+
+/**
+ * Resolve the memory file a run optimizes from the configured order.
+ *
+ *   primary   the first configured file that exists (null when none does)
+ *   pointers  other configured files that are pointers to the primary - silently fine
+ *   separate  other configured files with their own content - NOT updated by a run;
+ *             the caller warns so divergence is never silent
+ *
+ * The weights hash still covers every existing file, as before, so cached evidence
+ * survives this resolution unchanged.
+ */
+export function resolveMemoryFiles(repoRoot, memoryFiles) {
+  const files = loadMemoryFiles(repoRoot, memoryFiles);
+  if (!files.length) return { primary: null, all: files, pointers: [], separate: [], hash: null };
+  const [primary, ...others] = files;
+  const pointers = others.filter((f) => isPointerTo(f.text, primary.path));
+  const separate = others.filter((f) => !pointers.includes(f));
+  return { primary, all: files, pointers, separate, hash: memorySetHash(files) };
+}