@rafinery/cli 0.3.0 → 0.4.0

package/lib/push.mjs

@@ -1,24 +1,103 @@
-// rafa push — compile (contract gate) then push .rafa/ to the brain remote. Thin
-// wrapper over the vendored .rafa/bin/rafa-push.mjs (which runs compile itself).
+// rafa push — compile (contract gate), stamp the contract copy, commit `.rafa/`
+// and push it to the brain remote.
+//
+// Blueprint split (0.4.0): the gate runs in-process (no vendored bin), `.rafa/`
+// bootstraps lazily from the committed rafa.json, and a STAMPED copy of the
+// canonical contract (.claude/rafa/contract.md, code repo) rides every push so
+// the brain repo always carries the contract version it conforms to.
+// Uses YOUR git auth — no credential passes through rafa. Run from the code
+// repo root. Pushing is a MAIN-branch act: the org brain describes the default
+// branch; branch work syncs through checkpoints, not brain pushes.
 
-import { existsSync } from "node:fs";
 import { execSync } from "node:child_process";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
+import { runCompile } from "./gate/compile.mjs";
+import { ensureBrainRepo, remoteDefaultBranch, inDir, die } from "./brain-repo.mjs";
+import { CLI_VERSION } from "./releases.mjs";
 
-export default async function push(args) {
-  const script = join(process.cwd(), ".rafa", "bin", "rafa-push.mjs");
-  if (!existsSync(script)) {
-    console.error(
-      "✗ .rafa/bin/rafa-push.mjs not found — run `rafa init` (or `rafa update`) first.",
+export default async function push(args = []) {
+  const ROOT = process.cwd();
+  const { rafaDir } = ensureBrainRepo(ROOT);
+  const inRafa = inDir(rafaDir);
+
+  // Anchor the brain to the current code HEAD.
+  let codeSha = "unknown";
+  try {
+    codeSha = execSync("git rev-parse --short HEAD", { cwd: ROOT, encoding: "utf8" }).trim();
+  } catch {
+    /* code repo may have no commits yet — fine */
+  }
+
+  // The CODE repo's full_name — stamped into the manifest as its identity.
+  let repoFull = "";
+  try {
+    const origin = execSync("git remote get-url origin", { cwd: ROOT, encoding: "utf8" }).trim();
+    const m = origin.match(/[/:]([^/:]+)\/([^/]+?)(?:\.git)?\/?$/);
+    if (m) repoFull = `${m[1]}/${m[2]}`;
+  } catch {
+    /* no origin — manifest.repo stays "" */
+  }
+
+  // ── contract gate (in-process) ──
+  // Compile + validate the brain. A schema-invalid brain NEVER leaves the machine —
+  // the platform ingests JSON, so what we push must already conform to the contract.
+  console.log("• rafa compile — validating against the contract …");
+  if (runCompile([`--repo=${repoFull}`]) !== 0)
+    die(
+      "brain failed the contract (see errors above). Fix the files, or have the " +
+        "authoring agent (atlas/bloom/prism) correct them, then re-push.",
+    );
+
+  // ── stamped contract copy rides the push ──
+  // The canonical contract lives in the CODE repo (.claude/rafa/contract.md);
+  // the brain repo carries a stamped copy so any reader of the brain repo knows
+  // exactly which contract version this brain conforms to.
+  const canonical = join(ROOT, ".claude", "rafa", "contract.md");
+  if (existsSync(canonical)) {
+    const stampHeader =
+      `<!-- STAMPED COPY — canonical: .claude/rafa/contract.md in the code repo.\n` +
+      `     cli: ${CLI_VERSION} · brain-for: ${codeSha} · stamped: ${new Date().toISOString()} -->\n\n`;
+    writeFileSync(join(rafaDir, "contract.md"), stampHeader + readFileSync(canonical, "utf8"));
+  } else {
+    console.log(
+      "  ! no .claude/rafa/contract.md in this repo — pushing without the stamped contract copy " +
+        "(run `rafa update` to vendor it)",
     );
-    process.exit(1);
   }
+
+  inRafa("git add -A");
+  try {
+    inRafa(`git commit -m "brain: scan" -m "brain-for: ${codeSha}"`);
+  } catch {
+    console.log("• nothing new to commit — pushing current state");
+  }
+  const branch = remoteDefaultBranch(rafaDir);
+  inRafa(`git branch -M ${branch}`);
   try {
-    execSync(`node ${JSON.stringify(script)} ${args.join(" ")}`.trim(), {
-      stdio: "inherit",
-      cwd: process.cwd(),
-    });
+    inRafa(`git push -u origin ${branch}`);
   } catch {
-    process.exit(1);
+    // Someone pushed since our last pull. TRANSPORT replay (not knowledge
+    // merging): rebase our local commits onto the remote tip — child-owned plan
+    // files and improve rows are disjoint by design, so this is clean in the
+    // normal case. A real conflict aborts loudly with local work INTACT.
+    console.log("• remote is ahead — replaying local commits on top (pull --rebase) …");
+    try {
+      inRafa(`git pull --rebase origin ${branch}`);
+      inRafa(`git push -u origin ${branch}`);
+    } catch {
+      try {
+        inRafa("git rebase --abort");
+      } catch {
+        /* no rebase in progress */
+      }
+      die(
+        "push conflicts with the remote on the SAME file — local work kept intact. " +
+          "Conflicting knowledge is never hand-merged: run `rafa pull --full --force` to adopt the " +
+          "remote (your local .rafa is a cache) and re-derive, or resolve the plan-file " +
+          "conflict manually inside .rafa and re-push.",
+      );
+    }
   }
+  console.log(`✓ Pushed .rafa/ → brain remote (${branch} · brain-for: ${codeSha})`);
 }

package/lib/releases.mjs

@@ -69,6 +69,29 @@ export const RELEASES = [
       "wired: compile now emits `plans[]` + `activePlanId` with global-id/parent/progress rules. " +
       "Re-run `/rafa scan` (or push) to surface plans in your manifest; no re-scan required to adopt.",
   },
+  {
+    version: "0.4.0",
+    contract: 1,
+    plans: 1,
+    requires: "migrate",
+    summary:
+      "The working-set blueprint. BLUEPRINT SPLIT: gate tools live INSIDE the CLI (compile/" +
+      "verify-citations/push/pull — nothing vendored under .rafa/bin); capabilities are committed " +
+      "skills (.claude/skills/rafa-*); the contract is canonical in the code repo " +
+      "(.claude/rafa/contract.md; stamped copy rides brain pushes); .rafa/ is lazy + gitignored " +
+      "and bootstraps from the committed rafa.json (clone → npx rafa pull just works). " +
+      "WORKING SET: branch capture is files under .rafa/brain/** — rafa hydrate faults notes in, " +
+      "rafa checkpoint syncs under base-version CAS at checkpoint moments (never session-end); " +
+      "conflicts are YOUR decision, never auto-resolved. PLANS CHANNEL: push-on-approval " +
+      "(push_plan, bodies stored), list = names only, load materializes; terminal statuses " +
+      "superseded/abandoned; plans never ride the manifest. CI RECONCILIATION: rafa ci-setup " +
+      "installs the reconcile workflow — mechanical fold on branch→parent merges (rafa fold), " +
+      "headless distillation on merge-to-main (rafa distill --headless, on the ORG'S OWN " +
+      "ANTHROPIC_API_KEY — never stored on the platform). Also: contract-governed agent cards " +
+      "(§10, compile-gated), intent dispatch, plan-lite, compass (4th agent), /rafa insights. " +
+      "Brain data schema UNCHANGED (no re-scan); the mechanical blueprint-split migration " +
+      "cleans the old vendored files; re-push plans once through the new channel.",
+  },
 ];
 
 // The release this CLI build ships (last entry).

package/lib/verify-citations.mjs

@@ -0,0 +1,9 @@
+// rafa verify-citations — the deterministic citation checker (B1 resolution ·
+// B2 completeness · contract-anchor policy). Lives inside the CLI (blueprint
+// split, 0.4.0). Agents run it until it exits 0; prism re-runs it blind.
+
+import { runVerifyCitations } from "./gate/verify-citations.mjs";
+
+export default async function verifyCitations(args = []) {
+  process.exit(runVerifyCitations(args));
+}

package/lib/working-set.mjs

@@ -0,0 +1,113 @@
+// Shared working-set bookkeeping (working-set architecture, ratified 2026-07-10).
+//
+// `.rafa/hydration.json` is the DETERMINISTIC sidecar that makes "unedited
+// hydrated file = disposable cache, edited/new file = working set" a hash
+// comparison, not a judgment call:
+//
+//   files[path]              { baseBrainSha, hash }   set at hydration
+//   sync[branch][path]       { version, hash }        set on accepted checkpoint
+//   sync[branch][path].conflictSeen                    server version surfaced as a
+//                                                      conflict; the NEXT checkpoint
+//                                                      (after the human decided)
+//                                                      pushes against it
+//
+// The sidecar is state about cache-ness, never knowledge — gitignored with the
+// rest of `.rafa/`, regenerable by re-hydrating.
+
+import { createHash } from "node:crypto";
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import { dirname, join } from "node:path";
+
+// The working-set scan roots inside .rafa/ — brain-shaped authoring surfaces.
+export const WORKING_DIRS = ["brain/rules", "brain/playbooks"];
+
+export const hashOf = (text) => createHash("sha256").update(text).digest("hex");
+
+export function sidecarPath(cwd) {
+  return join(cwd, ".rafa", "hydration.json");
+}
+
+export function readSidecar(cwd) {
+  const p = sidecarPath(cwd);
+  if (!existsSync(p)) return { files: {}, sync: {} };
+  try {
+    const d = JSON.parse(readFileSync(p, "utf8"));
+    return { files: d.files ?? {}, sync: d.sync ?? {} };
+  } catch {
+    // A corrupt sidecar means cache-ness is unknowable — treat everything as
+    // working set (over-sync is safe; silent loss is not). Start fresh.
+    return { files: {}, sync: {} };
+  }
+}
+
+export function writeSidecar(cwd, data) {
+  const p = sidecarPath(cwd);
+  mkdirSync(dirname(p), { recursive: true });
+  writeFileSync(p, JSON.stringify(data, null, 2) + "\n");
+}
+
+// Every candidate working-set file under .rafa/ (brain-relative paths).
+// `.theirs.md` conflict copies and `_*` scratch are never part of the set.
+export function scanWorkingFiles(cwd) {
+  const out = [];
+  for (const dir of WORKING_DIRS) {
+    const abs = join(cwd, ".rafa", dir);
+    if (!existsSync(abs)) continue;
+    for (const e of readdirSync(abs)) {
+      const p = join(abs, e);
+      if (statSync(p).isDirectory()) continue;
+      if (!e.endsWith(".md") || e.startsWith("_") || e.endsWith(".theirs.md")) continue;
+      out.push({ path: `${dir}/${e}`, abs });
+    }
+  }
+  return out;
+}
+
+// Write a hydrated org-brain note to disk + record its cache identity.
+// Returns the brain-relative path.
+export function materializeNote(cwd, kind, data, brainForSha) {
+  const dir = kind === "rule" ? "brain/rules" : "brain/playbooks";
+  const rel = `${dir}/${data.id}.md`;
+  const abs = join(cwd, ".rafa", rel);
+  const content = renderNote(data);
+  mkdirSync(dirname(abs), { recursive: true });
+  writeFileSync(abs, content);
+  const sidecar = readSidecar(cwd);
+  sidecar.files[rel] = {
+    ...(brainForSha ? { baseBrainSha: brainForSha } : {}),
+    hash: hashOf(content),
+  };
+  writeSidecar(cwd, sidecar);
+  return rel;
+}
+
+// Deterministic contract-§2 frontmatter writer for hydrated notes. The MCP
+// serves fields, not raw files, so hydration reconstructs the file; `anchor:`
+// is not served — a contract note edited after hydration must re-declare it
+// before distillation (the policy gate catches the omission loudly).
+const q = (s) => `"${String(s).replace(/"/g, '\\"')}"`;
+export function renderNote(d) {
+  const lines = [
+    "---",
+    "schemaVersion: 1",
+    `id: ${d.id}`,
+    `type: ${d.type}`,
+    `domain: ${d.domain}`,
+    `title: ${q(d.title)}`,
+    ...(d.summary ? [`summary: ${q(d.summary)}`] : []),
+    `links: [${(d.links ?? []).join(", ")}]`,
+    ...(d.failure ? [`failure: ${d.failure}`] : []),
+    "cites:",
+    ...(d.cites ?? []).map((c) => `  - ${c.file}:${c.line} :: ${c.token}`),
+    "---",
+    "",
+  ];
+  return lines.join("\n") + (d.body ?? "") + "\n";
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@rafinery/cli",
-  "version": "0.3.0",
-  "description": "rafa — the AI engineer CLI. Vendors the rafa blueprint into your repo (shadcn-style) and runs the deterministic contract gates.",
+  "version": "0.4.0",
+  "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"