@rafinery/cli 0.3.0 → 0.4.0

package/lib/checkpoint.mjs

@@ -0,0 +1,138 @@
+// rafa checkpoint — sync this branch's WORKING SET to the platform (working-set
+// architecture, ratified 2026-07-10).
+//
+// Deterministic by construction: the hydration sidecar makes "unedited hydrated
+// file = disposable cache" a hash comparison. What syncs is exactly the edited
+// or new brain files under .rafa/brain/**, keyed by the CURRENT code branch,
+// under base-version CAS:
+//
+//   accepted  → sidecar records the new row version
+//   conflict  → the newer copy lands beside the file as `<file>.theirs.md`
+//               (attributed) and this command exits 2 — the HUMAN in this
+//               session decides (merge/adopt/overwrite the local file), then
+//               re-runs `rafa checkpoint`, which pushes against the seen
+//               version. CI can flag staleness; it never resolves it.
+//
+// Checkpoint moments (the conductor invokes this): task done · plan approved ·
+// explicit ask · cadence under session consent · git push/pull. Never session-end.
+
+import { execSync } from "node:child_process";
+import { existsSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { callTool } from "./mcp-client.mjs";
+import { hashOf, readSidecar, scanWorkingFiles, writeSidecar } from "./working-set.mjs";
+
+const die = (m) => {
+  console.error(`✗ ${m}`);
+  process.exit(1);
+};
+
+export default async function checkpoint() {
+  const ROOT = process.cwd();
+
+  let branch = "";
+  try {
+    branch = execSync("git rev-parse --abbrev-ref HEAD", {
+      cwd: ROOT,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+  } catch {
+    die("not a git repo — run from your code repo root");
+  }
+  // The working set is BRANCH state. On the trunk, knowledge changes go
+  // through scan → compile → rafa push (the org brain's one writer surface).
+  if (branch === "main" || branch === "master") {
+    console.log(
+      `• on ${branch} — the working set is branch-scoped; org-brain changes on the trunk go through /rafa scan + rafa push. Nothing to checkpoint.`,
+    );
+    return;
+  }
+
+  const sidecar = readSidecar(ROOT);
+  const syncBranch = (sidecar.sync[branch] = sidecar.sync[branch] ?? {});
+
+  const candidates = [];
+  for (const { path, abs } of scanWorkingFiles(ROOT)) {
+    const content = readFileSync(abs, "utf8");
+    const hash = hashOf(content);
+    const hydrated = sidecar.files[path];
+    const synced = syncBranch[path];
+
+    if (synced?.hash === hash && synced.conflictSeen === undefined) continue; // already checkpointed
+    if (!synced && hydrated?.hash === hash) continue; // unedited hydration = disposable cache
+
+    candidates.push({
+      path,
+      content,
+      hash,
+      // CAS base: the version this client last saw. After a surfaced conflict,
+      // conflictSeen IS the seen version — pushing against it is the human's
+      // decision made in this session.
+      baseVersion: synced?.conflictSeen ?? synced?.version ?? null,
+      ...(hydrated?.baseBrainSha ? { baseBrainSha: hydrated.baseBrainSha } : {}),
+    });
+  }
+
+  if (candidates.length === 0) {
+    console.log(`✓ working set clean on ${branch} — nothing to checkpoint`);
+    return;
+  }
+
+  console.log(`• checkpointing ${candidates.length} file(s) on ${branch} …`);
+  let payload;
+  try {
+    payload = await callTool(ROOT, "checkpoint_sync", {
+      branch,
+      files: candidates.map(({ path, content, baseVersion, baseBrainSha }) => ({
+        path,
+        content,
+        baseVersion,
+        ...(baseBrainSha ? { baseBrainSha } : {}),
+      })),
+    });
+  } catch (e) {
+    die(e instanceof Error ? e.message : String(e));
+  }
+
+  const results = payload.results ?? [];
+  let conflicts = 0;
+  for (const r of results) {
+    const cand = candidates.find((c) => c.path === r.path);
+    if (r.ok) {
+      syncBranch[r.path] = { version: r.version, hash: cand?.hash ?? "" };
+      const theirs = join(ROOT, ".rafa", `${r.path}.theirs.md`);
+      if (existsSync(theirs)) rmSync(theirs);
+      console.log(`  ✓ ${r.path}  (v${r.version})`);
+    } else if (r.conflict) {
+      conflicts++;
+      const theirs = join(ROOT, ".rafa", `${r.path}.theirs.md`);
+      writeFileSync(
+        theirs,
+        `<!-- CONFLICT copy from the platform — v${r.conflict.version} by ${r.conflict.author ?? r.conflict.lastAuthor} at ${new Date(r.conflict.updatedAt).toISOString()}.\n` +
+          `     Your checkpoint was based on an older version. Decide: merge/adopt/keep, edit the\n` +
+          `     real file accordingly, then re-run \`rafa checkpoint\` (it will push YOUR file as\n` +
+          `     the decision). Delete this copy when done. -->\n\n` +
+          r.conflict.content,
+      );
+      syncBranch[r.path] = {
+        ...(syncBranch[r.path] ?? { version: 0, hash: "" }),
+        conflictSeen: r.conflict.version,
+      };
+      console.log(
+        `  ✗ ${r.path} — CONFLICT: v${r.conflict.version} by ${r.conflict.lastAuthor} is newer.\n` +
+          `      their copy: .rafa/${r.path}.theirs.md — decide, edit your file, re-run rafa checkpoint`,
+      );
+    } else {
+      console.log(`  ✗ ${r.path} — ${r.error ?? "rejected"}`);
+    }
+  }
+  writeSidecar(ROOT, sidecar);
+
+  const accepted = results.filter((r) => r.ok).length;
+  console.log(
+    `${conflicts ? "!" : "✓"} checkpoint: ${accepted}/${results.length} synced on ${branch}` +
+      (conflicts ? ` · ${conflicts} conflict(s) need YOUR decision (see above)` : ""),
+  );
+  if (conflicts) process.exit(2);
+}

package/lib/ci-setup.mjs

@@ -0,0 +1,109 @@
+// rafa ci-setup — install the reconciliation workflow (working-set
+// architecture, ratified 2026-07-10, rules 6–7): the org's own CI folds
+// branch→branch merges mechanically and DISTILLS merge-to-main with the org's
+// own LLM key. Writes .github/workflows/rafa-reconcile.yml and names the
+// secrets to configure — it configures nothing itself (secrets are the org's;
+// nothing sensitive ever transits rafinery).
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+const WORKFLOW_PATH = ".github/workflows/rafa-reconcile.yml";
+
+const WORKFLOW = `# rafa reconcile — knowledge propagates exactly like the code it describes.
+#
+#   branch → parent branch merge   = MECHANICAL FOLD (no LLM, no prism)
+#   branch → default branch merge  = DISTILLATION (prism-validated vs merged main,
+#                                    compile-gated, pushed to the brain repo)
+#
+# Secrets (Settings → Secrets and variables → Actions):
+#   RAFA_MCP_KEY        an agent key for this repo (platform → repo → Agent access)
+#   ANTHROPIC_API_KEY   the ORG'S OWN LLM key — used only inside this CI for
+#                       distillation; never stored on the rafinery platform
+#   RAFA_BRAIN_TOKEN    a token with push access to the BRAIN repo (distill only)
+#
+# Fires on the merge EVENT itself (PR closed+merged), so squash/rebase merges are
+# detected correctly — git ancestry is never consulted. If distillation cannot run
+# (missing secret, failed gate) it fails LOUD and the branch's working set stays
+# intact — the next dev session gets the standard distill offer (fallback chain).
+
+name: rafa reconcile
+
+on:
+  pull_request:
+    types: [closed]
+
+jobs:
+  fold:
+    name: fold working set (branch → parent)
+    if: github.event.pull_request.merged == true && github.event.pull_request.base.ref != github.event.repository.default_branch
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - name: Mechanical fold (no LLM — rigor lives at main)
+        env:
+          RAFA_MCP_KEY: \${{ secrets.RAFA_MCP_KEY }}
+        run: npx -y @rafinery/cli fold --from "\${{ github.event.pull_request.head.ref }}" --to "\${{ github.event.pull_request.base.ref }}"
+
+  distill:
+    name: distill working set (merge to main)
+    if: github.event.pull_request.merged == true && github.event.pull_request.base.ref == github.event.repository.default_branch
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: \${{ github.event.repository.default_branch }} # merged main = the validation target
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - name: Install the Agent SDK (runs on the org's own key)
+        run: npm i --no-save @anthropic-ai/claude-agent-sdk
+      - name: Distill into the org brain (prism-validated, compile-gated)
+        env:
+          ANTHROPIC_API_KEY: \${{ secrets.ANTHROPIC_API_KEY }}
+          RAFA_MCP_KEY: \${{ secrets.RAFA_MCP_KEY }}
+          RAFA_BRAIN_TOKEN: \${{ secrets.RAFA_BRAIN_TOKEN }}
+        run: npx -y @rafinery/cli distill --headless "\${{ github.event.pull_request.head.ref }}"
+`;
+
+export default async function ciSetup(args = []) {
+  const ROOT = process.cwd();
+  const target = join(ROOT, WORKFLOW_PATH);
+
+  if (existsSync(target)) {
+    const current = readFileSync(target, "utf8");
+    if (current === WORKFLOW) {
+      console.log(`✓ ${WORKFLOW_PATH} is already current`);
+    } else if (args.includes("--overwrite")) {
+      writeFileSync(target, WORKFLOW);
+      console.log(`✓ ${WORKFLOW_PATH} updated (--overwrite)`);
+    } else {
+      console.log(
+        `! ${WORKFLOW_PATH} exists and differs — left untouched (yours may be tuned).\n` +
+          "  Re-run with --overwrite to replace it.",
+      );
+    }
+  } else {
+    mkdirSync(dirname(target), { recursive: true });
+    writeFileSync(target, WORKFLOW);
+    console.log(`✓ wrote ${WORKFLOW_PATH}`);
+  }
+
+  console.log(`
+Next steps (repo Settings → Secrets and variables → Actions):
+  1. RAFA_MCP_KEY       — mint on the platform (repo → Agent access); scope: this repo.
+  2. ANTHROPIC_API_KEY  — the ORG'S OWN LLM key. Used only inside YOUR CI for
+                          merge-to-main distillation; never stored on the rafinery
+                          platform (hard rule).
+  3. RAFA_BRAIN_TOKEN   — a token with push access to the BRAIN repo (the distill
+                          job pushes validated knowledge there).
+  4. Commit the workflow via your normal MR flow.
+
+The rigor gradient this wires: dev↔dev = CAS + session prompt · branch↔branch =
+free mechanical fold · branch→main = full distillation + gates. Cost tracks
+consequence. Without CI, nothing is lost — the next dev session's bootstrap
+digest offers the same reconciliation (/rafa distill).`);
+}

package/lib/claude-config.mjs

@@ -4,13 +4,13 @@
 import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
 import { dirname, join } from "node:path";
 
-// The permissions rafa's installed tooling needs to run without a prompt each time.
-// Kept minimal + specific to what `rafa init` actually vendors into `.rafa/bin`.
+// The permissions rafa's tooling needs to run without a prompt each time.
+// Blueprint split (0.4.0): the gate tools live inside @rafinery/cli, so the
+// grant is the CLI itself (deterministic commands), not vendored scripts.
 export const RAFA_PERMISSIONS = [
   "Read(.rafa/**)",
-  "Bash(node .rafa/bin/rafa-compile.mjs:*)",
-  "Bash(node .rafa/bin/rafa-push.mjs:*)",
-  "Bash(node .rafa/bin/verify-citations.mjs:*)",
+  "Bash(npx @rafinery/cli:*)",
+  "Bash(rafa:*)",
 ];
 
 export function settingsPath(targetDir) {

package/lib/compile.mjs

@@ -1,24 +1,9 @@
-// rafa compile — run the vendored contract gate on this repo's brain. Thin wrapper
-// over .rafa/bin/rafa-compile.mjs (the client's own copy = its contract version).
+// rafa compile — run the contract gate on this repo's brain. The gate lives
+// INSIDE the CLI (blueprint split, 0.4.0) — it moves with the CLI version,
+// never vendored, so a repo is gate-current the moment the CLI is.
 
-import { existsSync } from "node:fs";
-import { execSync } from "node:child_process";
-import { join } from "node:path";
+import { runCompile } from "./gate/compile.mjs";
 
-export default async function compile(args) {
-  const script = join(process.cwd(), ".rafa", "bin", "rafa-compile.mjs");
-  if (!existsSync(script)) {
-    console.error(
-      "✗ .rafa/bin/rafa-compile.mjs not found — run `rafa init` (or `rafa update`) first.",
-    );
-    process.exit(1);
-  }
-  try {
-    execSync(`node ${JSON.stringify(script)} ${args.join(" ")}`.trim(), {
-      stdio: "inherit",
-      cwd: process.cwd(),
-    });
-  } catch {
-    process.exit(1); // compile already printed its path·field·rule errors
-  }
+export default async function compile(args = []) {
+  process.exit(runCompile(args));
 }

package/lib/distill.mjs

@@ -0,0 +1,237 @@
+// rafa distill --headless <branch> — merge-to-main DISTILLATION in the org's
+// own CI (working-set architecture, ratified 2026-07-10, rule 7).
+//
+// The rigor moment of the gradient: every working-set file the branch captured
+// is validated against the CHECKED-OUT MERGED MAIN (prism-shaped skepticism),
+// survivors are authored into the org brain (atlas-shaped), and only what
+// passes verify-citations + compile is pushed to the brain repo. Contested or
+// low-confidence items are NEVER guessed — flagged needs-adjudication for the
+// next dev session's digest offer.
+//
+// The judgment runs on the Agent SDK, driven by the ORG'S OWN LLM key
+// (ANTHROPIC_API_KEY from CI secrets — never stored on the rafinery platform).
+// The gates stay deterministic and OURS: this CLI collects, stages, re-runs
+// the checkers itself (trust-but-verify), pushes, and resolves. The agent
+// judges; it never ships.
+//
+// Fallback chain when this can't run (no key, no CI): the dev-session flow —
+// /rafa distill <branch> in Claude Code (the bootstrap digest offers it).
+
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { callTool } from "./mcp-client.mjs";
+import { runCompile } from "./gate/compile.mjs";
+import { runVerifyCitations } from "./gate/verify-citations.mjs";
+import pull from "./pull.mjs";
+import push from "./push.mjs";
+
+const die = (m) => {
+  console.error(`✗ ${m}`);
+  process.exit(1);
+};
+
+// A brain-relative path from the platform must stay inside .rafa/ — a row that
+// would escape is refused loudly (never written, never guessed).
+const safeRel = (p) => {
+  if (p.startsWith("/") || p.split("/").includes("..")) die(`unsafe working-set path: ${p}`);
+  return p;
+};
+
+// The Agent SDK is deliberately NOT a dependency of this CLI (it is heavy and
+// only CI distillation needs it). Resolution order: normal import → the host
+// repo's node_modules (the workflow installs it with `npm i --no-save`).
+async function loadAgentSdk(cwd) {
+  try {
+    return await import("@anthropic-ai/claude-agent-sdk");
+  } catch {
+    try {
+      const req = createRequire(join(cwd, "package.json"));
+      return await import(pathToFileURL(req.resolve("@anthropic-ai/claude-agent-sdk")).href);
+    } catch {
+      die(
+        "@anthropic-ai/claude-agent-sdk is not installed — the reconcile workflow runs\n" +
+          "  `npm i --no-save @anthropic-ai/claude-agent-sdk` before this command (see rafa ci-setup).",
+      );
+    }
+  }
+}
+
+const VERDICTS = ["distilled", "refuted", "needs-adjudication"];
+
+export default async function distill(args = []) {
+  const branch = args.filter((a) => !a.startsWith("-"))[0];
+  if (!args.includes("--headless"))
+    die(
+      "session distillation runs in Claude Code (/rafa distill <branch> — offer-driven at bootstrap).\n" +
+        "  This CLI runs the CI path:  rafa distill --headless <branch>",
+    );
+  if (!branch) die("usage: rafa distill --headless <branch>");
+  if (!process.env.ANTHROPIC_API_KEY)
+    die(
+      "ANTHROPIC_API_KEY is not set — CI distillation runs on the ORG'S OWN LLM key from CI\n" +
+        "  secrets (never stored on the rafinery platform). Add the secret (rafa ci-setup names\n" +
+        "  it), or fall back to the dev session: /rafa distill " + branch,
+    );
+
+  const ROOT = process.cwd();
+
+  // 1 · collect the branch working set. Adjudication-flagged rows are LEFT for
+  // a human session (CI can flag divergence, never resolve it).
+  console.log(`• collecting working set for ${branch} …`);
+  let active, flagged;
+  try {
+    active = (await callTool(ROOT, "get_working_set", { branch, status: "active" })).files ?? [];
+    flagged =
+      (await callTool(ROOT, "get_working_set", { branch, status: "needs-adjudication" }))
+        .files ?? [];
+  } catch (e) {
+    die(e instanceof Error ? e.message : String(e));
+  }
+  if (flagged.length)
+    console.log(
+      `  ! ${flagged.length} file(s) already need adjudication — left for the next dev session's digest`,
+    );
+  if (active.length === 0) {
+    console.log(`✓ nothing to distill on ${branch}`);
+    return;
+  }
+  console.log(`  ${active.length} file(s) to distill`);
+
+  // 2 · mirror the org brain locally — the authoring target + the base the
+  // survivors fold into. (CI checkout is merged main = the validation target.)
+  await pull(["--full"]);
+
+  // 3 · stage the incoming working set for the agent (gitignored inside .rafa).
+  const stagingRoot = join(ROOT, ".rafa", "distill-incoming");
+  rmSync(stagingRoot, { recursive: true, force: true });
+  for (const f of active) {
+    const abs = join(stagingRoot, safeRel(f.path));
+    mkdirSync(dirname(abs), { recursive: true });
+    writeFileSync(
+      abs,
+      `<!-- incoming working-set file · branch: ${branch} · author: ${f.lastAuthor} · v${f.version}` +
+        `${f.baseBrainSha ? ` · base: ${f.baseBrainSha}` : ""} -->\n` +
+        f.content,
+    );
+  }
+  const verdictsPath = join(ROOT, ".rafa", "distill-verdicts.json");
+  rmSync(verdictsPath, { force: true });
+
+  // 4 · the judgment pass (org's own key; gates stay deterministic below).
+  const sdk = await loadAgentSdk(ROOT);
+  const fileList = active.map((f) => `- ${f.path} (author: ${f.lastAuthor})`).join("\n");
+  const prompt = `You are running rafa's CI DISTILLATION — merge-time reconciliation of branch "${branch}"'s
+working set into the org brain. The checked-out repo IS merged main (the ground truth).
+The current org brain is mirrored at .rafa/brain/. The incoming candidate-grade files are
+staged under .rafa/distill-incoming/ (brain-relative paths mirrored; a provenance comment
+tops each file).
+
+Read .claude/skills/rafa-distill/SKILL.md (the SOP) and .claude/rafa/contract.md §2 (the
+note schema) first.
+
+For EACH staged file:
+1. VALIDATE like prism — skeptical, code-grounded: does every claim hold against the code
+   as it now stands on main? Confirm each citation resolves (the cited line contains the
+   token; run \`git grep\` yourself). A claim you cannot confirm with a file:line is
+   REFUTED (note the cited reason). Contested or genuinely uncertain → verdict
+   "needs-adjudication" (NEVER guess; a wrong note is worse than none).
+2. For survivors, AUTHOR like atlas — write/update the org-brain file under .rafa/brain/
+   per the contract: valid frontmatter, real cites into main, \`anchor:\` on contracts;
+   fold into an existing note when one already covers the topic (supersede, never
+   duplicate). Never copy the provenance comment into the brain file.
+3. When all survivors are authored, run \`npx @rafinery/cli verify-citations\` and
+   \`npx @rafinery/cli compile\` and fix your authored files until BOTH exit 0.
+
+Finally write .rafa/distill-verdicts.json:
+  {"verdicts":[{"path":"<staged brain-relative path>","verdict":"distilled|refuted|needs-adjudication","note":"<cited reason — required for refuted and needs-adjudication>"}]}
+with EXACTLY one entry per staged file listed below. Do not modify anything outside
+.rafa/ except nothing — the code repo is read-only ground truth.
+
+Staged files:
+${fileList}`;
+
+  console.log("• running the distillation agent (org's own ANTHROPIC_API_KEY) …");
+  const run = sdk.query({
+    prompt,
+    options: {
+      cwd: ROOT,
+      permissionMode: "bypassPermissions",
+      allowedTools: ["Read", "Grep", "Glob", "Bash", "Write", "Edit"],
+      settingSources: [],
+      maxTurns: 150,
+    },
+  });
+  for await (const message of run) {
+    if (message.type === "result") {
+      if (message.subtype !== "success")
+        die(`distillation agent did not complete (${message.subtype}) — nothing resolved, nothing pushed`);
+      console.log(
+        `  agent done (${message.num_turns ?? "?"} turns · ` +
+          `$${(message.total_cost_usd ?? 0).toFixed(4)} on the org's key)`,
+      );
+    }
+  }
+
+  // 5 · verdicts must be complete — a missing entry is a hard stop, never a guess.
+  if (!existsSync(verdictsPath))
+    die("agent produced no .rafa/distill-verdicts.json — nothing resolved, nothing pushed; working set left intact");
+  let verdicts;
+  try {
+    verdicts = JSON.parse(readFileSync(verdictsPath, "utf8")).verdicts;
+  } catch {
+    die("distill-verdicts.json is not valid JSON — nothing resolved, nothing pushed");
+  }
+  if (!Array.isArray(verdicts)) die("distill-verdicts.json has no verdicts[] — aborting");
+  const byPath = new Map(verdicts.map((v) => [v.path, v]));
+  for (const f of active) {
+    const v = byPath.get(f.path);
+    if (!v || !VERDICTS.includes(v.verdict))
+      die(`no valid verdict for ${f.path} — nothing resolved, nothing pushed; working set left intact`);
+    if (v.verdict !== "distilled" && (typeof v.note !== "string" || v.note.trim() === ""))
+      die(`${f.path}: verdict "${v.verdict}" requires a cited note — aborting`);
+  }
+
+  // 6 · trust-but-verify: OUR gates re-run regardless of what the agent claims.
+  console.log("• re-running the gates (trust-but-verify) …");
+  if (runVerifyCitations([]) !== 0)
+    die("citation checker failed on the authored brain — nothing resolved, nothing pushed");
+  if (runCompile([]) !== 0)
+    die("compile gate failed on the authored brain — nothing resolved, nothing pushed");
+
+  // 7 · ship: brain repo push (webhook → ingest), staging cleaned first.
+  rmSync(stagingRoot, { recursive: true, force: true });
+  const distilledCount = active.filter((f) => byPath.get(f.path).verdict === "distilled").length;
+  if (distilledCount > 0) {
+    await push([]);
+  } else {
+    console.log("• no survivors — nothing to push to the brain repo");
+  }
+
+  // 8 · resolve the rows (CAS — a racing session's resolve loses loudly).
+  let refuted = 0,
+    adjudication = 0;
+  for (const f of active) {
+    const v = byPath.get(f.path);
+    if (v.verdict === "refuted") refuted++;
+    if (v.verdict === "needs-adjudication") adjudication++;
+    try {
+      await callTool(ROOT, "resolve_working_file", {
+        branch,
+        path: f.path,
+        resolution: v.verdict,
+        ...(v.note ? { note: v.note } : {}),
+      });
+      console.log(`  ${v.verdict === "distilled" ? "✓" : "!"} ${f.path} → ${v.verdict}${v.note ? ` (${v.note})` : ""}`);
+    } catch (e) {
+      console.log(`  ✗ ${f.path} — resolve failed: ${e instanceof Error ? e.message : e}`);
+    }
+  }
+  rmSync(verdictsPath, { force: true });
+
+  console.log(
+    `✓ distillation: ${distilledCount} into the org brain · ${refuted} refuted (reported, cited) · ` +
+      `${adjudication} flagged needs-adjudication (next session's digest)`,
+  );
+}

package/lib/fold.mjs

@@ -0,0 +1,53 @@
+// rafa fold — branch→parent-branch MECHANICAL fold of the working set
+// (working-set architecture, ratified 2026-07-10, rule 6). No LLM, no prism —
+// rigor lives only at main. The platform re-keys rows onto the parent:
+//
+//   absent on parent      → re-keyed silently (knowledge rides with the code)
+//   identical content     → merged silently
+//   true divergence       → needs-adjudication flag on the parent row
+//                           (incoming preserved + attributed) — the next dev
+//                           session's digest offers the decision; CI never
+//                           resolves a human's divergence.
+//
+// Run by the reconciliation workflow on branch→branch merges (rafa ci-setup),
+// or by hand:  rafa fold --from <branch> --to <parent>
+
+import { callTool } from "./mcp-client.mjs";
+
+const die = (m) => {
+  console.error(`✗ ${m}`);
+  process.exit(1);
+};
+
+const flag = (args, name) => {
+  const i = args.indexOf(name);
+  return i !== -1 && args[i + 1] && !args[i + 1].startsWith("--") ? args[i + 1] : null;
+};
+
+export default async function fold(args = []) {
+  const from = flag(args, "--from");
+  const to = flag(args, "--to");
+  if (!from || !to) die("usage: rafa fold --from <branch> --to <parent-branch>");
+  if (from === to) die("--from and --to are the same branch");
+
+  let res;
+  try {
+    res = await callTool(process.cwd(), "fold_working_set", {
+      fromBranch: from,
+      toBranch: to,
+    });
+  } catch (e) {
+    die(e instanceof Error ? e.message : String(e));
+  }
+
+  console.log(
+    `✓ fold ${from} → ${to}: ${res.folded} file(s) · ` +
+      `${res.rekeyed} re-keyed · ${res.merged} identical (merged) · ` +
+      `${res.needsAdjudication} divergent → needs-adjudication`,
+  );
+  if (res.needsAdjudication > 0)
+    console.log(
+      "  ! divergent copies were preserved + flagged — the next dev session's bootstrap digest\n" +
+        "    offers the decision (CI detects divergence, never resolves it).",
+    );
+}