@rafinery/cli 0.8.3 → 0.8.5

package/blueprint/.claude/rafa/hooks/brain-commit.mjs

@@ -7,7 +7,8 @@
 // non-blocking always — a brain problem must never block a code commit.
 
 import { execSync } from "node:child_process";
-import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 
 const ROOT = process.cwd();
@@ -21,6 +22,31 @@ try {
   const rafa = join(ROOT, ".rafa");
   const shR = (cmd) => sh(cmd, rafa);
 
+  // DISPOSAL (MIRRORS working-set.isDisposableHydration — the ONE rule, both planes):
+  // an UNEDITED hydration must never enter a brain commit, or we re-push org content as a
+  // branch delta → stale-override at reconcile. After staging, unstage every unedited
+  // hydration (it stays in the working tree as disposable cache) so only real deltas commit.
+  const disposeHydrations = (br) => {
+    try {
+      const sc = JSON.parse(readFileSync(join(rafa, "hydration.json"), "utf8"));
+      const synced = (sc.sync ?? {})[br] ?? {};
+      for (const [p, rec] of Object.entries(sc.files ?? {})) {
+        const abs = join(rafa, p);
+        if (!existsSync(abs) || !/^[A-Za-z0-9._/-]+$/.test(p)) continue;
+        const hash = createHash("sha256").update(readFileSync(abs, "utf8")).digest("hex");
+        if (!synced[p] && rec?.hash === hash) {
+          try {
+            shR(`git reset -q -- "${p}"`);
+          } catch {
+            /* not staged (never tracked) — already excluded */
+          }
+        }
+      }
+    } catch {
+      /* no/corrupt sidecar → nothing hydrated to dispose */
+    }
+  };
+
   const branch = sh("git rev-parse --abbrev-ref HEAD");
   // Trunk commits never mirror — the brain default branch has one writer, the
   // distiller. Conservative charset guard: a refname git allows but a shell
@@ -34,6 +60,7 @@ try {
   if (cur !== branch) {
     try {
       shR("git add -A");
+      disposeHydrations(cur);
       shR(`git commit -q -m "brain(switch-carryover)" -m "switch-carryover-from: ${cur}"`);
     } catch {
       /* nothing dirty */
@@ -46,6 +73,38 @@ try {
     }
   }
 
+  // Merge-union (spec r2 §2.2): a LOCAL merge of branch X into this branch Y ⇒ union
+  // brain/X into brain/Y, the merged branch winning per path (fold doctrine on the git
+  // plane, `-X theirs`). TRUNK is excluded — merging main into a branch is a resync, not
+  // a knowledge transport (unioning main's brain would re-pull org content = stale-
+  // override). Best-effort: an unrecoverable branch name just leaves the 1-1 commit, and
+  // the reconciler's ancestry sweep still catches the merged commits.
+  try {
+    const parents = sh("git rev-list --parents -n 1 HEAD").split(/\s+/).slice(1);
+    if (parents.length >= 2) {
+      const m = sh("git log -1 --pretty=%B").match(
+        /Merge branch '([^']+)'|Merge branch "([^"]+)"|Merge remote-tracking branch '[^/]+\/([^']+)'/,
+      );
+      const merged = m ? m[1] || m[2] || m[3] : null;
+      if (
+        merged &&
+        merged !== branch &&
+        merged !== "main" &&
+        merged !== "master" &&
+        /^[A-Za-z0-9._/-]+$/.test(merged)
+      ) {
+        try {
+          shR(`git rev-parse --verify -q "refs/heads/${merged}"`);
+          shR(`git merge -q -m "brain(merge): ${merged} -> ${branch}" -X theirs "${merged}"`);
+        } catch {
+          /* no brain branch for the merged code branch, or already up to date */
+        }
+      }
+    }
+  } catch {
+    /* not a merge / rev-list unavailable — normal 1-1 path */
+  }
+
   // The intent record — the commit's end-to-end intent, mechanically joined.
   // Minimal here (sha · subject · files); the P3 capture worker enriches.
   const fullSha = sh("git rev-parse HEAD");
@@ -71,6 +130,7 @@ try {
   );
 
   shR("git add -A");
+  disposeHydrations(branch);
   shR(
     `git commit --allow-empty -q -m "brain(${branch}): ${subject}" ` +
       `-m "code-commit: ${fullSha}" -m "code-branch: ${branch}"`,

package/blueprint/.claude/skills/rafa-scan/SKILL.md

@@ -253,9 +253,16 @@ pipeline; **`--brain-only`** stops after the brain is validated (step 5 PASS)
 6. **Improve** *(skip if `--brain-only`)* — run the improve pass ([rafa-improve](../rafa-improve/SKILL.md)):
    spawn `bloom` → `.rafa/improve/`. It reads the *validated* brain as its index, so it only
    runs after PASS.
-7. **Push** — present the full summary (brain verdict/score + top improvements). **On the
-   dev's explicit approval**, `npx @rafinery/cli push --verb=scan` — commits `.rafa/` and pushes to the
-   brain remote using the dev's own git auth, stamped `brain-for: <code sha>`. Never without approval.
+7. **Land it** — present the full summary (brain verdict/score + top improvements). **On the
+   dev's explicit approval**, land the brain the way EVERY brain change lands — through the
+   commit hooks, **never a direct trunk push** (the reconciler is the org brain's only writer).
+   The dev MUST be on a feature branch (the post-commit hook no-ops on `main`). Then:
+   `git add -A && git commit` → **post-commit** mirrors the validated `.rafa/` brain 1-1 onto
+   the matching brain branch (stamped `code-commit: <sha>`); `git push` → **pre-push**
+   checkpoints the working set to the platform; then land it on main (open a PR **or** a plain
+   `git merge` + push — both work) → detection enqueues and the **reconciler** authors the org
+   brain at the merge sha, minting the node (brain ↔ code). Do **not** run `rafa push` (retired:
+   it wrote the trunk directly, bypassing the reconciler). Never land without approval.
 8. **The coach offer (founding scan only)** — if this was the repo's FIRST scan and the dev's
    user brain is empty (`list_dev_insights` → none), offer ONCE: *"the code side is mapped —
    want me to bootstrap YOUR insights from your usage report?"* Accepted = run `## insights`

package/lib/checkpoint.mjs

@@ -20,7 +20,7 @@ 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";
+import { hashOf, isDisposableHydration, readSidecar, scanWorkingFiles, writeSidecar } from "./working-set.mjs";
 
 const die = (m) => {
   console.error(`✗ ${m}`);
@@ -85,7 +85,7 @@ export default async function checkpoint() {
     const synced = syncBranch[path];
 
     if (synced?.hash === hash && synced.conflictSeen === undefined) continue; // already checkpointed
-    if (!synced && hydrated?.hash === hash) continue; // unedited hydration = disposable cache
+    if (isDisposableHydration({ synced, hydrated, hash })) continue; // unedited hydration = disposable cache
 
     candidates.push({
       path,

package/lib/distiller/doctrine.mjs

@@ -131,6 +131,38 @@ export async function arbitrateCandidate(candidate, cwd, { judge }) {
   return { outcome: "banked", noteId, cites: grounded, regroundings, detail: `banked as ${noteId}` };
 }
 
+// ── mechanical grounding for the brain-grounded agent path (agent.mjs) ──────────
+// The agent owns claim-level JUDGMENT (does this hold? redundant? contradicted?);
+// grounding stays MECHANICAL here — it is grep, not judgment, so an LLM must never
+// decide it. groundCandidate is the PRE-PASS: it resolves a candidate's cites against
+// merged main exactly as arbitrateCandidate's mechanical half does, but WITHOUT the
+// judge, and returns the raw grounding so the agent path can (a) prune a candidate
+// citing deleted code without spending a token and (b) hand the agent only grounded /
+// re-grounded claims to judge. `deleted` non-empty ⇒ a mechanical prune (deletion is
+// ground truth). Same one implementation of "does the token still live" as the gate.
+export function groundCandidate(candidate, cwd = process.cwd()) {
+  const cites = citesOf(candidate.content);
+  const noteId = idOf(candidate.content, candidate.path);
+  const perCite = cites.map((c) => arbitrateCite(c, cwd));
+  const deleted = perCite.filter((d) => d.status === "deleted");
+  const regroundings = perCite.filter((d) => d.status === "regrounded");
+  const grounded = perCite.map((d) => (d.status === "regrounded" ? d.to : d.cite));
+  return { cites, noteId, deleted, regroundings, grounded };
+}
+
+// citesGround is the POST-VERIFY GUARDRAIL: whatever content the agent proposes to
+// author, EVERY cite in it must resolve AS AUTHORED against merged main (the agent is
+// responsible for having re-grounded any moved cite itself in the content it returns).
+// An unresolved cite means the agent hallucinated or mis-grounded — the loop downgrades
+// that ONE disposition to needs-adjudication rather than banking ungrounded knowledge.
+// This sits in FRONT of the verify-citations gate: it fails a single note to
+// adjudication instead of letting the whole run's gate reject. Returns { ok, unresolved }.
+export function citesGround(content, cwd = process.cwd()) {
+  const cites = citesOf(content);
+  const unresolved = cites.filter((c) => arbitrateCite(c, cwd).status !== "resolved");
+  return { ok: unresolved.length === 0, unresolved };
+}
+
 // Rewrite a survivor's frontmatter `cites:` DSL so a re-grounded citation points
 // at where the token NOW lives on main — otherwise banking it as authored would
 // fail the checker (the stale line no longer resolves). Mechanical string

package/lib/distiller.mjs

@@ -394,7 +394,28 @@ export default async function distiller(_args = []) {
   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"]);
+  // Prep failures MUST self-report (live-caught 2026-07-18: a safe.directory
+  // throw here died before the state plane ever started — running row, no
+  // lastError, no logs, invisible until someone ssh'd the sandbox). Best-effort
+  // report, then rethrow: the row shows the reason and the sweep retries.
+  try {
+    await pull(["--full"]);
+  } catch (e) {
+    const message = `brain mirror (pull --full) failed: ${e instanceof Error ? e.message.split("\n")[0] : e}`;
+    try {
+      await reportFailure({
+        call,
+        reconciliationId: env.RAFA_LEAD_RECONCILIATION_ID,
+        attempt: Number(env.RAFA_ATTEMPT),
+        actor: { model: env.RAFA_MODEL || "claude-opus-4-8", agent: "distiller", runner: "sandbox" },
+        errorClass: "transient",
+        message,
+      });
+    } catch {
+      /* the report is best-effort — the lease/sweep loop still recovers */
+    }
+    throw e;
+  }
   if (!existsSync(brainRoot)) mkdirSync(brainRoot, { recursive: true });
 
   const result = await runDistiller({

package/lib/gather.mjs

@@ -0,0 +1,64 @@
+// git-native gather (capture-engine spec r2 §2.4) — the ONE mechanism that reads candidate
+// brain deltas from a brain branch's history, unioned latest-wins per path. Two consumers:
+//
+//   • session hydration — pull the branch's accumulated NON-main knowledge (an epic's task
+//     branches, inherited through git), so a dev has it while building the feature.
+//   • the distiller — gather a merged branch's deltas since it diverged, to reconcile into
+//     the org brain at main.
+//
+// Union-latest-wins is FREE: a branch tip already holds the latest version of every note in
+// its ancestry (git inheritance from parent branches), so the net `base..tip` diff IS the
+// union. The base picks the lens:
+//   • distill  → base = branchPoint(branch, main): the branch's OWN deltas since it forked.
+//   • pull     → base = main's brain tip: everything NOT yet distilled into the org brain.
+
+import { execSync } from "node:child_process";
+
+// The candidate authoring surfaces (mirrors working-set WORKING_DIRS; intent/ is provenance,
+// never a candidate, so it is excluded here).
+const CANDIDATE_DIRS = ["brain/rules", "brain/playbooks", "improve/improvements"];
+
+const git = (dir, cmd) =>
+  execSync(cmd, { cwd: dir, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+
+// The branch point: where `branch` diverged from `from` (both brain refs). The distiller's
+// base — the branch's own accumulated deltas are everything since here. "" if no common
+// ancestor (an orphan/first branch → gather the whole branch).
+export function branchPoint(brainDir, branch, from = "main") {
+  try {
+    return git(brainDir, `git merge-base ${JSON.stringify(from)} ${JSON.stringify(branch)}`);
+  } catch {
+    return "";
+  }
+}
+
+// Gather candidate deltas from `branch` since `base` (both brain refs) in the brain repo at
+// `brainDir`. base "" ⇒ the whole branch. Returns:
+//   { tip, candidates: [{ path, content }], deleted: [path] }
+// candidates = notes present at the tip that changed since base (latest-wins content).
+// deleted    = notes that existed at base and are GONE at the tip → prune signals.
+export function gather({ brainDir, branch, base = "" }) {
+  const tip = git(brainDir, `git rev-parse ${JSON.stringify(branch)}`);
+  const dirspec = CANDIDATE_DIRS.map((d) => JSON.stringify(d)).join(" ");
+  const names = base
+    ? git(brainDir, `git diff --name-only ${base} ${tip} -- ${dirspec}`)
+    : git(brainDir, `git ls-tree -r --name-only ${tip} -- ${dirspec}`);
+
+  const candidates = [];
+  const deleted = [];
+  for (const path of names.split("\n").filter(Boolean)) {
+    const leaf = path.split("/").pop() ?? "";
+    if (path.endsWith(".theirs.md") || leaf.startsWith("_")) continue; // conflict/scratch
+    try {
+      const content = execSync(`git show ${tip}:${JSON.stringify(path)}`, {
+        cwd: brainDir,
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "ignore"],
+      });
+      candidates.push({ path, content });
+    } catch {
+      deleted.push(path); // in the diff but not at the tip ⇒ deleted since base
+    }
+  }
+  return { tip, candidates, deleted };
+}

package/lib/push.mjs

@@ -19,6 +19,23 @@ import { ensureBrainRepo, remoteDefaultBranch, inDir, die } from "./brain-repo.m
 import { CLI_VERSION } from "./releases.mjs";
 
 export default async function push(args = []) {
+  // Doctrine A (2026-07-20): `rafa push` wrote the brain TRUNK directly, bypassing the
+  // reconciler — which is now the org brain's ONLY writer. A scan no longer publishes the
+  // trunk; its validated `.rafa/` brain lands through the commit hooks (post-commit mirrors
+  // it 1-1 onto the matching brain branch → pre-push checkpoints → merge → the reconciler
+  // authors the trunk at the merge sha). Reconciler runs (`--verb=distill`) still pass, and
+  // `--force-trunk` stays as an explicit emergency override.
+  if (!args.includes("--verb=distill") && !args.includes("--force-trunk")) {
+    console.log(
+      "✗ `rafa push` (direct brain-trunk write) is retired — the reconciler is the org brain's\n" +
+        "  only writer. Land a scan the normal way, ON A FEATURE BRANCH:\n" +
+        "    • git add -A && git commit   → post-commit mirrors the validated .rafa/ brain 1-1\n" +
+        "    • git push                   → pre-push checkpoints the working set to the platform\n" +
+        "    • merge to main (PR or plain git merge) → the reconciler authors the org brain\n" +
+        "  (Emergency direct trunk write, discouraged: rerun with --force-trunk.)",
+    );
+    return;
+  }
   const ROOT = process.cwd();
   const { rafaDir } = ensureBrainRepo(ROOT);
   const inRafa = inDir(rafaDir);

package/lib/releases.mjs

@@ -229,6 +229,20 @@ export const RELEASES = [
       "value is needed it is rafa.json → repoId, never a folder-name guess. `rafa " +
       "update` re-vendors the cards.",
   },
+  {
+    version: "0.8.5",
+    contract: 1,
+    plans: 2,
+    requires: "update",
+    summary:
+      "Doctrine: the reconciler is the org brain's ONLY trunk writer. `rafa push` " +
+      "(direct brain-trunk write) is RETIRED — a scan now LANDS through the commit hooks: " +
+      "commit your code on a feature branch (post-commit mirrors the validated .rafa/ " +
+      "brain 1-1 onto the matching brain branch) → git push (pre-push checkpoints the " +
+      "working set) → merge to main → the reconciler authors the org brain at the merge " +
+      "sha and mints the node (brain ↔ code). Merges need NOT be PR-driven: a plain " +
+      "`git merge` + push to main reconciles too. `rafa update` re-vendors the scan SOP.",
+  },
 ];
 
 // The release this CLI build ships (last entry).

package/lib/working-set.mjs

@@ -48,6 +48,16 @@ export function kindOfPath(path) {
 
 export const hashOf = (text) => createHash("sha256").update(text).digest("hex");
 
+// The ONE disposal rule of the working-set architecture: a file is a DISPOSABLE
+// unedited hydration — never a candidate on EITHER plane — iff it is not a synced
+// working-set file and its content still hashes to its hydration base. Extracted so the
+// checkpoint (platform plane) and the brain-commit hook (git plane) apply the IDENTICAL
+// test. The hook is standalone by design (node built-ins only), so it mirrors this
+// one-liner inline — keep the two in sync (there is only one rule).
+export function isDisposableHydration({ synced, hydrated, hash }) {
+  return !synced && hydrated?.hash === hash;
+}
+
 export function sidecarPath(cwd) {
   return join(cwd, ".rafa", "hydration.json");
 }

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@rafinery/cli",
-  "version": "0.8.3",
+  "version": "0.8.5",
   "description": "rafa \u2014 the AI engineer CLI. Vendors the rafa blueprint into your repo (shadcn-style) and runs the deterministic contract gates.",
   "type": "module",
   "bin": {
     "rafa": "bin/rafa.mjs",
+    "cli": "bin/rafa.mjs",
     "rafa-distiller": "bin/rafa-distiller.mjs"
   },
   "files": [