@rafinery/cli 0.8.1 → 0.8.3

package/lib/distiller.mjs

@@ -0,0 +1,410 @@
+// The distiller loop — the metered core boot.sh hands off to (reconciliation
+// orchestrator, spec §2.6; refinery-arc-p1-distiller). boot.sh has already won the
+// claim (claim-on-start) and exported RAFA_ATTEMPT (the fence token); this is the
+// run that owns the repo. Sequence:
+//
+//   heartbeat on → collect the folded working sets → arbitrate against merged main
+//   (the mechanical DOCTRINE, doctrine.mjs) → author survivors + the per-run
+//   reconciliation-report concept → okf emit → verify-citations → compile → push
+//   (NEVER force) → reconcile_report (node delta + per-branch outcomes + meter).
+//
+// The ONE non-mechanical step is claim-level truth — judged by the org's own LLM
+// behind the `judge` seam. Every other decision (fold, re-ground, prune, sweep,
+// latest-merge-wins, provenance, failure class) is deterministic doctrine, so the
+// whole loop is drivable in tests with a fake judge + fake platform + a manual clock.
+//
+// Refutations are a GREEN run (reconcile_report success with refuted outcomes), not
+// a failure. A gate rejection is DETERMINISTIC (needs-attention now, no retry spend);
+// a boot/clone/network fault is TRANSIENT (backoff retry while a later branch proceeds).
+
+import { existsSync, mkdirSync, writeFileSync, rmSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { createRequire } from "node:module";
+import { pathToFileURL } from "node:url";
+import { runOkfEmit } from "./gate/okf-emit.mjs";
+import { runVerifyCitations } from "./gate/verify-citations.mjs";
+import { runCompile } from "./gate/compile.mjs";
+import push from "./push.mjs";
+import pull from "./pull.mjs";
+import { callTool } from "./mcp-client.mjs";
+import {
+  startHeartbeat,
+  makeLogBatcher,
+  reportSuccess,
+  reportFailure,
+} from "./distiller/state-plane.mjs";
+import {
+  foldCandidates,
+  arbitrateCandidate,
+  resolveCollision,
+  rewriteCites,
+  changedFilesSince,
+  mergeRangeSweep,
+  outcomeRow,
+  perBranchOutcomes,
+  buildDelta,
+  renderReconReport,
+  classifyError,
+  deterministicFailure,
+  transientFailure,
+} from "./distiller/doctrine.mjs";
+
+// Load the already-mirrored org brain notes for the merge-range sweep: every
+// `.rafa/brain/{rules,playbooks}/**/*.md` (the `await pull(["--full"])` in the
+// entry puts them on disk before the loop runs). Skips generated `index.md`,
+// scratch `_*.md`, and conflict `*.theirs.md`; reconciliations/ is excluded by
+// only walking rules + playbooks. Returns [{ path, content }] with bundle-relative
+// paths ("brain/rules/x.md") mirroring foldCandidates' candidate shape.
+export function loadBrainNotes(cwd = process.cwd()) {
+  const brain = join(cwd, ".rafa", "brain");
+  const walkMd = (dir) => {
+    if (!existsSync(dir)) return [];
+    return readdirSync(dir).flatMap((e) => {
+      const p = join(dir, e);
+      if (statSync(p).isDirectory()) return walkMd(p);
+      return e.endsWith(".md") && e !== "index.md" && !e.startsWith("_") && !e.endsWith(".theirs.md")
+        ? [p]
+        : [];
+    });
+  };
+  const notes = [];
+  for (const sub of ["rules", "playbooks"]) {
+    for (const p of walkMd(join(brain, sub)))
+      notes.push({ path: "brain/" + p.slice(brain.length + 1), content: readFileSync(p, "utf8") });
+  }
+  return notes;
+}
+
+// A brain-relative path that would escape .rafa/ is refused loudly (mirrors
+// distill.mjs safeRel — never write, never guess).
+const safeRel = (p) => {
+  if (p.startsWith("/") || p.split("/").includes(".."))
+    throw deterministicFailure(`unsafe working-set path: ${p}`);
+  return p;
+};
+
+// The Agent SDK is not a hard dependency of the CLI (heavy; only the metered judge
+// needs it). Same isolated-install resolution order as distill.mjs.
+async function loadAgentSdk(cwd) {
+  const roots = [process.env.RAFA_AGENT_SDK_DIR, null, cwd];
+  for (const root of roots) {
+    try {
+      if (root === null) return await import("@anthropic-ai/claude-agent-sdk");
+      if (!root) continue;
+      const req = createRequire(join(root, "package.json"));
+      return await import(pathToFileURL(req.resolve("@anthropic-ai/claude-agent-sdk")).href);
+    } catch {
+      /* try the next root */
+    }
+  }
+  throw deterministicFailure(
+    "@anthropic-ai/claude-agent-sdk is not installed — the distiller image bakes it in " +
+      "(RAFA_AGENT_SDK_DIR points at the isolated install).",
+  );
+}
+
+// ── the injectable orchestration ────────────────────────────────────────────────
+// Every external effect is a seam with a real default: `call` (platform MCP),
+// `judge` (org LLM), `collectSets` (working sets), `orgNotes` (brain notes for the
+// sweep), gate/push runners, timers, clock. Tests pass deterministic fakes; the
+// sandbox path builds the real ones in the default export below.
+export async function runDistiller({
+  env = process.env,
+  cwd = process.cwd(),
+  call,
+  judge,
+  collectSets,
+  orgNotes = async () => [],
+  cursorSha = env.RAFA_CURSOR_SHA || "",
+  parents = (env.RAFA_PARENT_SHAS || "").split(",").filter(Boolean),
+  authorSurvivor,
+  removeNote,
+  authorReport,
+  runGates,
+  doPush,
+  now = () => Date.now(),
+  setTimer = setInterval,
+  clearTimer = clearInterval,
+  log = console.log,
+} = {}) {
+  const reconciliationId = env.RAFA_LEAD_RECONCILIATION_ID;
+  const attempt = Number(env.RAFA_ATTEMPT);
+  const mergeSha = env.RAFA_MERGE_SHA;
+  const tier = env.RAFA_TIER === "provisional" ? "provisional" : "canonical";
+  const model = env.RAFA_MODEL || "claude-opus-4-8";
+  const actor = { model, agent: "distiller", runner: "sandbox" };
+  if (!reconciliationId) throw deterministicFailure("RAFA_LEAD_RECONCILIATION_ID is not set");
+  if (!Number.isFinite(attempt)) throw deterministicFailure("RAFA_ATTEMPT (the fence token) is not set");
+  if (!mergeSha) throw deterministicFailure("RAFA_MERGE_SHA is not set");
+
+  const t0 = now();
+  const meter = { machineSeconds: 0, tokens: 0 };
+  let fenced = false;
+
+  // Token accounting rides the judge seam's return (`{ hold, reason, tokens }`) —
+  // the ONLY metered step is claim-level truth. This wrapper accumulates it so
+  // reconcile_report's meter reflects real LLM spend, never a hardcoded 0.
+  let judgedTokens = 0;
+  const meteredJudge = async (cand, ctx) => {
+    const v = await judge(cand, ctx);
+    judgedTokens += v && Number.isFinite(v.tokens) ? v.tokens : 0;
+    return v;
+  };
+
+  const hb = startHeartbeat({
+    call, reconciliationId, attempt, actor, phase: "reconciling",
+    setTimer, clearTimer,
+    onFenced: () => { fenced = true; log("! heartbeat fenced (a newer attempt owns this run) — aborting"); },
+  });
+  const logs = makeLogBatcher({ call, reconciliationId, attempt, actor, setTimer, clearTimer, warn: log });
+
+  try {
+    logs.append("distiller: collecting folded working sets");
+    const branchSets = await collectSets();
+    hb.setPhase("arbitrating");
+
+    // Fold N branches into ONE run; a path carried by >1 branch is a collision.
+    const { candidates, collisions } = foldCandidates(branchSets);
+    const dispositions = [];
+
+    // Non-colliding candidates: arbitrate each against merged main.
+    for (const cand of candidates) {
+      const d = await arbitrateCandidate(cand, cwd, { judge: meteredJudge });
+      dispositions.push({ ...d, candidate: cand });
+    }
+    // Collisions: judge every version, latest-merge-wins tiebreak (case 5).
+    for (const { versions } of collisions) {
+      for (const d of await resolveCollision(versions, cwd, { judge: meteredJudge })) dispositions.push(d);
+    }
+
+    // Merge-range sweep (case 4, second half): existing org notes citing files the
+    // merge changed get their citations re-resolved — re-ground or prune, same rule.
+    // changedFilesSince returns null on an UNREACHABLE range (a cursor sha not yet
+    // in the clone) — honor that contract: a transient skip (backoff retry once the
+    // sha lands), a loud log line, NEVER a silent coerce-to-[] that would let stale
+    // org notes through undetected.
+    const changed = changedFilesSince(cursorSha, mergeSha, cwd);
+    if (changed === null) {
+      logs.append(`distiller: merge-range ${cursorSha}..${mergeSha} unreachable — transient skip, retrying`);
+      throw transientFailure(`merge-range sweep: ${cursorSha}..${mergeSha} unreachable (cursor sha not in the clone yet?)`);
+    }
+    const orgNoteList = await orgNotes();
+    const sweep = mergeRangeSweep({ changedFiles: changed, orgNotes: orgNoteList, cwd });
+    // Observability: the sweep's reach is REPORTED (a true 0 is fine; an
+    // indistinguishable stub is not). Counts only — never note content.
+    logs.append(
+      `distiller: merge-range sweep — ${orgNoteList.length} org note(s) loaded · ` +
+        `${changed.length} changed file(s) in range · ${sweep.length} citation(s) re-checked`,
+    );
+    for (const s of sweep) {
+      if (s.disposition.status === "deleted") {
+        dispositions.push({
+          outcome: "pruned", noteId: s.noteId, cites: [s.cite],
+          detail: `sweep: ${s.disposition.record}`,
+          candidate: { path: s.notePath, branch: "(org-brain)", capturedAtSha: mergeSha },
+          sweepPath: s.notePath,
+        });
+      } else if (s.disposition.status === "regrounded") {
+        dispositions.push({
+          outcome: "rewritten", noteId: s.noteId, cites: [s.disposition.to],
+          detail: `sweep: re-grounded ${s.cite.loc} → ${s.disposition.to.loc}`,
+          candidate: { path: s.notePath, branch: "(org-brain)", capturedAtSha: mergeSha },
+        });
+      }
+    }
+
+    // Author survivors into the brain; prune deletions; refuted/folded author nothing.
+    hb.setPhase("authoring");
+    for (const d of dispositions) {
+      if (d.outcome === "banked") {
+        authorSurvivor({ path: safeRel(d.candidate.path), content: d.candidate.content });
+      } else if (d.outcome === "rewritten" && d.candidate.content) {
+        authorSurvivor({
+          path: safeRel(d.candidate.path),
+          content: rewriteCites(d.candidate.content, d.regroundings),
+        });
+      } else if (d.outcome === "pruned" && d.sweepPath) {
+        removeNote(safeRel(d.sweepPath));
+      }
+    }
+
+    // The per-run reconciliation-report concept (provenance record).
+    const outcomeRows = dispositions.map((d) =>
+      outcomeRow({
+        candidate: d.candidate, outcome: d.outcome, detail: d.detail,
+        reconciliationId, supersededBy: d.supersededBy,
+      }),
+    );
+    meter.machineSeconds = Math.round((now() - t0) / 1000);
+    meter.tokens = judgedTokens; // real LLM spend from the judge seam, not a hardcoded 0
+    const report = renderReconReport({
+      mergeSha, outcome: "succeeded", tier, reconciliationId, outcomeRows, meter,
+    });
+    authorReport(report);
+    logs.append(`distiller: ${outcomeRows.length} outcome(s) — running gates`);
+
+    // Gates + push. A gate rejection is DETERMINISTIC (retrying only burns spend).
+    hb.setPhase("gating");
+    if (fenced) throw deterministicFailure("run fenced before gating — a newer attempt owns it");
+    const gate = runGates();
+    if (!gate.ok) throw deterministicFailure(gate.message || "authored brain failed the gates");
+    hb.setPhase("pushing");
+    doPush(); // never force — push.mjs rebase-replays, aborts loudly on real conflict
+
+    // Terminal success (refutations included in the delta — a refute-everything run
+    // is GREEN here, not a failure).
+    const delta = buildDelta(dispositions);
+    const outcomes = perBranchOutcomes(branchSets, outcomeRows);
+    const res = await reportSuccess({ call, reconciliationId, attempt, actor, parents, delta, outcomes, meter });
+    log(
+      `✓ reconciliation ${reconciliationId}: ${delta.banked.length} banked · ${delta.rewritten.length} rewritten · ` +
+        `${delta.pruned.length} pruned · ${delta.refuted.length} refuted · ${collisions.length} collision(s)`,
+    );
+    return { ok: true, delta, outcomes, meter, report, reportResult: res };
+  } catch (e) {
+    const errorClass = classifyError(e);
+    const message = e instanceof Error ? e.message : String(e);
+    // A fenced run must not stamp a terminal state (the newer attempt owns it).
+    if (fenced) {
+      log(`! run fenced — leaving the terminal write to the owning attempt (${message})`);
+      return { ok: false, fenced: true, errorClass, message };
+    }
+    log(`✗ reconciliation ${reconciliationId} failed (${errorClass}): ${message}`);
+    const res = await reportFailure({ call, reconciliationId, attempt, actor, errorClass, message });
+    return { ok: false, errorClass, message, reportResult: res };
+  } finally {
+    hb.stop();
+    await logs.stop();
+  }
+}
+
+// ── the CLI entry (bin/rafa-distiller.mjs · boot.sh's DISTILLER_ENTRY seam) ───────
+// Builds the REAL seams from the sandbox environment and runs the loop. This is the
+// path that only exercises end-to-end inside the pinned image (E2B/Docker) — the
+// exit-gate sandbox-run clause. The doctrine + state-plane it composes are proven
+// at module level without a sandbox.
+export default async function distiller(_args = []) {
+  process.env.RAFA_HOOKS_DISABLED = "1"; // never re-fire session sensors from the worker
+  const cwd = process.cwd();
+  const env = process.env;
+  const repo = env.RAFA_REPO;
+
+  // Real platform call — mirrors boot.sh exactly (JSON-RPC 2.0 to RAFA_MCP_URL, key
+  // in the Authorization header never logged, `repo` = RAFA_REPO). The route spreads
+  // the tool payload to the TOP LEVEL of structuredContent, so { ok, attempt, … } is
+  // read there. Reuses mcp-client's transport error shaping.
+  const call = async (tool, args = {}) => {
+    // callTool derives repo/key/url from rafa.json + env; in the image RAFA_MCP_URL,
+    // RAFA_MCP_KEY, and the committed rafa.json are all present, and the reconcile
+    // tools scope by the agent key. Pass repo explicitly for parity with boot.sh.
+    return callTool(cwd, tool, { repo, ...args });
+  };
+
+  // Real judge seam — the org's own LLM (Agent SDK, ANTHROPIC_API_KEY from the image
+  // secrets). Claim-level truth ONLY; the doctrine decides everything else. Kept
+  // behind loadAgentSdk so tests never touch it.
+  const judge = async (candidate) => {
+    const sdk = await loadAgentSdk(cwd);
+    const run = sdk.query({
+      prompt:
+        "You are the distiller's claim judge. The checked-out repo IS merged main.\n" +
+        "Judge ONLY whether this note's normative claim still holds against the code as it now\n" +
+        "stands. Its citations already ground (the doctrine verified that). Reply with a single\n" +
+        `JSON line {"hold": true|false, "reason": "<cited reason if false>"}.\n\n` +
+        `Note (${candidate.path}):\n${candidate.content}`,
+      options: { cwd, permissionMode: "bypassPermissions", allowedTools: ["Read", "Grep", "Glob", "Bash"], settingSources: [], maxTurns: 30 },
+    });
+    let verdict = { hold: true };
+    let tokens = 0;
+    for await (const m of run) {
+      if (m.type === "assistant")
+        for (const b of m.message?.content ?? []) {
+          if (b.type !== "text") continue;
+          const mm = b.text.match(/\{[^{}]*"hold"[^{}]*\}/);
+          if (mm) { try { verdict = JSON.parse(mm[0]); } catch { /* keep last */ } }
+        }
+      if (m.type === "result") {
+        if (m.subtype !== "success") throw deterministicFailure(`judge did not complete (${m.subtype})`);
+        // Usage from the SDK result message (same field distill.mjs meters on) →
+        // the metering wrapper accumulates it into reconcile_report's meter.tokens.
+        tokens += (m.usage?.input_tokens ?? 0) + (m.usage?.output_tokens ?? 0);
+      }
+    }
+    return { ...verdict, tokens };
+  };
+
+  // Real working-set collector — the folded branches the run reconciles. The
+  // reconcile fold groups them; here we enumerate live branches and gather each.
+  const collectSets = async () => {
+    const { branches } = await call("list_working_sets", {});
+    const sets = [];
+    for (const b of branches ?? []) {
+      const branch = typeof b === "string" ? b : b.branch;
+      const allFiles = (await call("get_working_set", { branch, status: "active" })).files ?? [];
+      // Intent records are provenance, never arbitrated claims (P2) — the
+      // note-shaped doctrine must not judge them.
+      const files = allFiles.filter((f) => !f.path.startsWith("intent/"));
+      if (files.length)
+        sets.push({
+          branch,
+          // Set-level grounding: the newest per-row capture sha when the rows
+          // carry one (branch listings never did — b.capturedAtSha was always
+          // undefined), else the triggering merge sha as before.
+          capturedAtSha:
+            files
+              .filter((f) => typeof f.capturedAtSha === "string" && f.capturedAtSha)
+              .sort((a, b2) => (b2.updatedAt ?? 0) - (a.updatedAt ?? 0))[0]
+              ?.capturedAtSha || mergeShaOf(env),
+          mergedAt: (typeof b === "object" && b.mergedAt) || 0,
+          files: files.map((f) => ({
+            path: f.path,
+            content: f.content,
+            ...(f.capturedAtSha ? { capturedAtSha: f.capturedAtSha } : {}),
+          })),
+        });
+    }
+    return sets;
+  };
+
+  const brainRoot = join(cwd, ".rafa", "brain");
+  const authorSurvivor = ({ path, content }) => {
+    const abs = join(cwd, ".rafa", path);
+    mkdirSync(dirname(abs), { recursive: true });
+    writeFileSync(abs, content);
+  };
+  const removeNote = (path) => rmSync(join(cwd, ".rafa", path), { force: true });
+  const authorReport = ({ path, content }) => {
+    const abs = join(cwd, ".rafa", path);
+    mkdirSync(dirname(abs), { recursive: true });
+    writeFileSync(abs, content);
+  };
+
+  // Gates re-run OURS, trust-but-verify — the authoring push order (contract §11):
+  // okf emit → verify-citations → compile. A non-zero anywhere is a deterministic
+  // gate rejection.
+  const runGates = () => {
+    if (runOkfEmit([`--repo=${repo || ""}`]) !== 0)
+      return { ok: false, message: "okf emit failed on the authored brain" };
+    if (runVerifyCitations([]) !== 0)
+      return { ok: false, message: "citation checker failed on the authored brain" };
+    if (runCompile([`--repo=${repo || ""}`]) !== 0)
+      return { ok: false, message: "compile gate failed on the authored brain" };
+    return { ok: true };
+  };
+  const doPush = () => push(["--verb=distill"]); // push.mjs re-runs the same gates + pushes; NEVER --force
+
+  // Mirror the org brain first (the authoring target the survivors fold into).
+  await pull(["--full"]);
+  if (!existsSync(brainRoot)) mkdirSync(brainRoot, { recursive: true });
+
+  const result = await runDistiller({
+    env, cwd, call, judge, collectSets, authorSurvivor, removeNote, authorReport, runGates, doPush,
+    orgNotes: async () => loadBrainNotes(cwd), // the mirrored brain is the sweep source
+  });
+  if (!result.ok && !result.fenced) process.exitCode = 1;
+  return result;
+}
+
+function mergeShaOf(env) {
+  return env.RAFA_MERGE_SHA || "";
+}

package/lib/doctor.mjs

@@ -0,0 +1,110 @@
+// rafa doctor — prove the capture machinery end to end (capture-engine P0).
+// Sensors fail silent BY DESIGN inside sessions (never block the dev); doctor
+// is the loud, on-demand proof: provisioning → hook wiring → script sanity →
+// the platform round-trip (the heartbeat actually LANDS). Run it after init /
+// ci-setup, or whenever capture looks quiet. Exit 1 on any failure, with the
+// named fix — an unfalsifiable "hooks are probably fine" is exactly what this
+// command exists to kill.
+
+import { execSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { callTool, resolveMcp } from "./mcp-client.mjs";
+import { collectSensorHealth } from "./sensor-health.mjs";
+
+// Callable form — init runs this as its final proof step (advisory there:
+// init already succeeded; doctor names any remaining fix). Returns the
+// failure count; the CLI command wraps it with the exit code.
+export async function runDoctor(ROOT = process.cwd()) {
+  let failures = 0;
+  const ok = (m) => console.log(`  ✓ ${m}`);
+  const bad = (m, fix) => {
+    failures++;
+    console.log(`  ✗ ${m}`);
+    if (fix) console.log(`      fix: ${fix}`);
+  };
+
+  console.log("rafa doctor — proving the capture machinery\n");
+
+  // 1 · provisioning — the same resolution the real tools use, so a doctor
+  // pass here means checkpoint/distill auth will resolve identically.
+  console.log("• provisioning");
+  let provisioned = false;
+  try {
+    const { repoId, mcpUrl, keySource, urlSource } = resolveMcp(ROOT);
+    provisioned = true;
+    ok(`repo "${repoId}" → ${mcpUrl}  (key: ${keySource} · url: ${urlSource})`);
+  } catch (e) {
+    bad(
+      e instanceof Error ? e.message.split("\n")[0] : String(e),
+      "run `rafa init <setup-url>` (platform → repo → generate setup command)",
+    );
+  }
+
+  // 2 · sensors — wiring truth (settings ∧ script) + per-clone git hook.
+  console.log("• sensors");
+  const health = collectSensorHealth(ROOT);
+  for (const h of health.hooks) {
+    const life =
+      typeof h.entries === "number"
+        ? ` · ${h.entries} queue entrie(s)${h.lastFireAt ? `, last ${new Date(h.lastFireAt).toISOString()}` : ""}`
+        : "";
+    if (h.wired) ok(`${h.name} wired${life}`);
+    else
+      bad(
+        `${h.name} NOT wired`,
+        h.name === "pre-push"
+          ? "run `rafa init`/`rafa pull` in this clone — the git hook is per-clone"
+          : "run `rafa update` — re-merges the hooks into .claude/settings.json",
+      );
+    if (h.lastError)
+      bad(
+        `${h.name} last run failed: ${h.lastError}${h.lastErrorAt ? ` (${new Date(h.lastErrorAt).toISOString()})` : ""}`,
+        "run `rafa checkpoint` manually and read its output",
+      );
+  }
+  // Script sanity: a wired-but-unparseable hook would still fail silently.
+  for (const script of [
+    "session-start.mjs",
+    "post-tool.mjs",
+    "user-prompt-submit.mjs",
+  ]) {
+    const abs = join(ROOT, ".claude", "rafa", "hooks", script);
+    if (!existsSync(abs)) continue; // wiring check above already reported it
+    try {
+      execSync(`node --check "${abs}"`, { stdio: "ignore" });
+      ok(`${script} parses`);
+    } catch {
+      bad(`${script} has a syntax error`, "run `rafa update` to re-vendor it");
+    }
+  }
+
+  // 3 · the round-trip — the heartbeat must LAND, not just send. A recorded
+  // response proves key + url + repo scoping + the platform handler, end to end.
+  console.log("• platform round-trip");
+  if (provisioned) {
+    try {
+      const res = await callTool(ROOT, "report_sensor_health", health);
+      if (res?.recorded) ok("heartbeat landed (report_sensor_health → recorded)");
+      else bad("heartbeat sent but the platform did not confirm it", "deploy the latest platform (report_sensor_health ships with capture-engine P0)");
+    } catch (e) {
+      bad(
+        e instanceof Error ? e.message.split("\n")[0] : String(e),
+        "the message above names the failing piece (key/url/deploy)",
+      );
+    }
+  } else {
+    console.log("  · skipped (not provisioned)");
+  }
+
+  console.log(
+    failures
+      ? `\n✗ doctor: ${failures} problem(s) — capture is NOT fully live; fixes named above`
+      : "\n✓ doctor: all clear — sensors wired, scripts parse, heartbeat lands",
+  );
+  return failures;
+}
+
+export default async function doctor() {
+  if ((await runDoctor()) > 0) process.exit(1);
+}

package/lib/gate/compile.mjs

@@ -418,6 +418,35 @@ export function runCompile(argv = []) {
     return { domains };
   }
 
+  // Reconciliation reports (contract §11 file-type registry — a per-run
+  // outcome/provenance record the distiller authors into the bundle at merge-to-main;
+  // reconciliation orchestrator, spec 2026-07-14). A `structured` class: required
+  // fields FAIL LOUDLY here. Deletion/refutation records ride INSIDE the body
+  // (sections), so there is ONE class, not three. Validated like plans but does NOT
+  // ride the manifest — it travels on the brain-repo transport. The stamped
+  // `type: Reconciliation Report` (OKF §11) is validated by checkOkfFields.
+  const RECON_OUTCOMES = ["succeeded", "needs-attention", "superseded"];
+  const RECON_TIERS = ["canonical", "provisional"];
+  function compileReconciliations() {
+    let count = 0;
+    for (const path of walk(join(ROOT, "brain", "reconciliations"))) {
+      const name = path.split("/").pop();
+      const { data, error } = parseFrontmatter(read(path));
+      if (error) {
+        fail(path, "frontmatter", error);
+        continue;
+      }
+      count++;
+      checkVersion(data, path);
+      checkId(data, path, name);
+      checkOkfFields(data, path, { typed: true }); // stamped `type: Reconciliation Report`
+      reqStr(data, "run", path); // the merge commit sha this run reconciled (provenance)
+      reqEnum(data, "outcome", RECON_OUTCOMES, path);
+      reqEnum(data, "tier", RECON_TIERS, path);
+    }
+    return count;
+  }
+
   // citation-check.json — the checker's machine record of its last run (generated
   // by `rafa verify-citations`). Folded into manifest.citations so the platform
   // knows which gate level this brain passed. Absent file → null (an honest
@@ -849,6 +878,7 @@ export function runCompile(argv = []) {
   const ledger = compileLedger();
   const coverage = compileCoverage();
   const citations = compileCitations();
+  const reconciliations = compileReconciliations();
   const plans = compilePlans();
   const activePlanId = compileActivePlanId(plans);
   const agentCards = compileAgentCards();
@@ -908,6 +938,7 @@ export function runCompile(argv = []) {
   console.log(
     `✓ rafa compile: ${notes.length} notes · ${improvements.length} improvements · ` +
       `${plans.length} plans validated${activePlanId ? ` (active: ${activePlanId})` : ""} (plans travel via the plans channel, not the manifest) · ` +
+      `${reconciliations} reconciliation reports validated (brain-repo transport, not the manifest) · ` +
       `health ${health ? "ok" : "—"} · ledger ${ledger ? "ok" : "—"} · ` +
       `coverage ${coverage ? `${coverage.domains.length} domains` : "—"} · ` +
       `${agentCards} agent cards + ${shippedSops} SOPs${learnings ? ` + ${learnings} learnings` : ""} (local gate) → ${ROOT}/manifest.json`,

package/lib/gate/verify-citations.mjs

@@ -88,7 +88,11 @@ function walkBundleMd(dir, base = dir) {
   });
 }
 
-function gitGrep(token, cwd = process.cwd()) {
+// EXPORTED (refinery-arc-p1-distiller): the distiller's arbitration doctrine
+// reuses this SAME resolution machinery — a cite is re-grounded against main
+// by re-grepping its token, and pruned when the grep comes back empty. One
+// implementation of "does this token still live in the code," gate + doctrine.
+export function gitGrep(token, cwd = process.cwd()) {
   try {
     const out = execSync(`git grep -nF -e ${JSON.stringify(token)}`, { encoding: "utf8", cwd });
     return out.split("\n").filter(Boolean).map((l) => {
@@ -115,7 +119,10 @@ function gitLsGlob(glob, cwd = process.cwd()) {
   }
 }
 
-function citeResolves(file, start, end, token) {
+// EXPORTED (refinery-arc-p1-distiller): the doctrine validates a candidate's
+// citations against merged main through the exact same predicate the gate uses,
+// so "resolves for the checker" and "resolves for arbitration" can never drift.
+export function citeResolves(file, start, end, token) {
   if (!existsSync(file)) return { ok: false, reason: "file missing" };
   const src = readFileSync(file, "utf8").split("\n");
   if (start < 1 || end > src.length) return { ok: false, reason: `lines ${start}-${end} out of range (${src.length})` };