@rafinery/cli 0.8.13 → 0.8.14

package/bin/rafa.mjs

@@ -54,6 +54,7 @@ const COMMANDS = [
   "leverage",
   "benchmark",
   "manifest",
+  "review",
   "migrate",
 ];
 const [cmd, ...rest] = process.argv.slice(2);
@@ -133,6 +134,11 @@ Commands:
                        count harness tokens, emit a MEASURED benchmark.json. --dry-run
                        exercises the scaffold from fixture counts; --help documents the
                        agent-driven run procedure. Measured — never the estimated baseline.
+  review               Brain-grounded review pre-pass (deterministic, zero LLM): the
+                       diff's changed lines ∩ the brain's cite graph → the exact rules/
+                       improvements the change touches (.rafa/review.json + summary).
+                       The rafa-review SOP's judge then rules on precisely that list —
+                       generic "review this PR" never happens. Advisory; never blocks.
   migrate              Bring this repo's structured files (plans, config) up to the schema
                        the installed CLI ships. Idempotent; review the diff after.
 

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

@@ -142,6 +142,33 @@ try {
       `\n`,
   );
 
+  // Local-state exclusion (owner 2026-07-24): the hydration sidecar + sensor
+  // queues are MACHINE state, never knowledge — ensure the ignore entries and
+  // UNTRACK anything an earlier CLI's window let git track (a .gitignore entry
+  // alone never untracks; `git add -A` would keep committing it forever).
+  // Best-effort: exclusion must never block a code commit.
+  try {
+    const LOCAL_STATE = [
+      "hydration.json",
+      "dirty.jsonl",
+      "reflex.jsonl",
+      "sensor-errors.jsonl",
+      "distill-verdicts.json",
+      "benchmark.demo.json",
+    ];
+    const gi = join(rafa, ".gitignore");
+    const cur = existsSync(gi) ? readFileSync(gi, "utf8") : "";
+    const have = new Set(cur.split("\n").map((l) => l.trim()).filter(Boolean));
+    const missing = [...LOCAL_STATE, "*.theirs.md", "distill-incoming/"].filter((l) => !have.has(l));
+    if (missing.length)
+      writeFileSync(gi, cur + (cur === "" || cur.endsWith("\n") ? "" : "\n") + missing.join("\n") + "\n");
+    for (const p of LOCAL_STATE) shR(`git rm -q --cached --ignore-unmatch "${p}"`);
+    shR('git rm -q -r --cached --ignore-unmatch distill-incoming');
+    shR('git rm -q --cached --ignore-unmatch "*.theirs.md"');
+  } catch {
+    /* exclusion is best-effort */
+  }
+
   shR("git add -A");
   disposeHydrations(branch);
   shR(

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

@@ -19,6 +19,7 @@ platform MCP (one read path — the same surface any third-party agent uses).
 | **Executor** | atlas | RECALL the task's brain slice via MCP (`search_knowledge` + `get_rule`/`get_playbook`; honor non-exemplars) → implement, convention-adherent |
 | **Validator** | prism | validate the execution against the child's `## Done-check` — strict, unbiased, against code + brain, never against atlas's claims. **`status: done` only on prism PASS**; FAIL → atlas corrects (validate-and-correct at work time). Plan-done adds one line to the verdict: **working set reviewed — captured, or clean-with-reason** (a build that learned nothing SAYS so; a build that learned something SHOWS the files) |
 | **Improver** | bloom | **push**: new improvement opportunities spotted during execution → new ledger files. **close**: improvements fixed in passing → `status: fixed` in the ledger file + `report_improvement_status(id, fixed)` so the platform shows it LIVE as pending-reconciliation (the ledger row itself changes only at the next brain push — K1). **nudge**: top-leverage open item in the task's blast radius — opt-in, never blocking |
+| **Coach** | compass | **sitback** (harness-arc): after each task's verdict + sweep, one beat of reflection — did THIS task reveal something about how this DEV works (a preference, a recurring friction, a steering pattern)? Repo knowledge goes to the working set, never here. A genuine dev-level observation becomes its OWN opt-in offer (consent doctrine: insights are NEVER under session consent) → `put_dev_insight` on yes. No observation = no offer — silence is the honest default |
 
 ## Procedure
 
@@ -26,6 +27,11 @@ platform MCP (one read path — the same surface any third-party agent uses).
    (envelope `brainForSha` vs local stamp → prompt `rafa push` if behind). MCP
    recall is automatic throughout — SOP-driven, never dev-invoked; a repo without
    the `rafinery` MCP connected falls back to local `.rafa/` file reads.
+   **On a feature branch, pass `branch: <current git branch>` to
+   search_knowledge/get_rule/get_playbook/get_improvement** — recall then
+   overlays the branch's live working set on canon, every non-canonical result
+   tier-labeled (the alert rule: a `source: {tier: "candidate"}` or
+   `branchOverlay` is branch state, not org truth — say so when you rely on it).
    **Session consent (asked ONCE, verbs ENUMERATED):** *"keep the platform
    updated as I work? That means exactly: (1) plan status + Log pushes on
    cadence, (2) checkpointing this branch's working set (edited/new brain
@@ -82,7 +88,10 @@ platform MCP (one read path — the same surface any third-party agent uses).
    **Gap close-out:** authored knowledge that answers an in-scope knowledge
    gap (adopted at plan time via `get_knowledge_gaps`) closes the loop —
    `set_gap_status(q, "closed")` at the same beat the note is authored.
-4. **Verify** (prism-style) before declaring the plan done; final `push_plan` +
+4. **Verify** (prism-style) before declaring the plan done — including the
+   [rafa-review](../rafa-review/SKILL.md) gate: `rafa review` scopes the exact
+   rules/improvements the branch's diff touches; the judge rules on that list
+   + each Done-check, emits `review-verdict`; final `push_plan` +
    `set_active_plan` (clear) + `rafa checkpoint`. **Dual status (single/double
    tick):** `status: done` is the dev ✓ — prism-earned, session-set, for
    leaves AND the epic (the epic's ✓ = every leaf verified done). DELIVERY is

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

@@ -46,7 +46,14 @@ Planning is a choreography, not one agent (spec: knowledge-mcp-build-agent):
 1. **Staleness check** — compare the platform envelope's `brainForSha` against the
    local brain stamp; if the platform is behind, surface "run `rafa push`" (never
    proceed silently on knowledge you know is stale — never block either).
-2. **Recall** (atlas, via MCP) → **decompose** into the WORK-ITEM TREE (contract
+2. **Recall** (atlas, via MCP) — `get_coverage` now carries **`recentDeltas`**
+   (the last trunk merges' knowledge changes + which plan delivered each):
+   open the plan draft with a TWO-LINE BRIEFING of what changed in the blast
+   radius since it was last touched — planning starts from the deltas, never a
+   stale mental model. `search_knowledge` may return a **`decisions`** block
+   (prior recorded calls matching the query): read it BEFORE re-litigating a
+   settled decision — reopening one is the owner's move, not the plan's.
+   Then **decompose** into the WORK-ITEM TREE (contract
    §7 v2): one epic → tasks → subtasks (three ranks, never deeper). Every item
    carries the glimpse fields — `title` (what) · `description` (why) ·
    `approach` (how, one line) · `assignee` when known · `blocked_by` for

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

@@ -0,0 +1,63 @@
+---
+name: rafa-review
+description: "rafa SOP — the brain-grounded review gate: `rafa review` computes the exact rules/improvements a diff touches (cite-intersection, zero LLM); a prism-style judge rules ONLY on that list + the active task's Done-check; findings feed atlas; the verdict emits a review-verdict loop event. Loaded before push/merge or on request."
+---
+
+# review — the brain-grounded gate  (harness-arc wave 2)
+
+> Status: **active.** The at-the-gate moment: defects caught BEFORE merge, by
+> the repo's own rules — not generic review taste. Depends on: brain (#1),
+> plans (#3, for the Done-check). Runs at the pre-push beat (offer, never
+> block) and on demand.
+
+Generic "review this PR" is banned here. The gate is two passes with a hard
+split:
+
+## Pass 1 — mechanical (the CLI, zero LLM)
+
+`rafa review [--json]` — diff vs merge-base(origin default) → changed line
+ranges ∩ the brain's cite graph (`get_code_context` per file):
+
+- **◆ direct** — a changed line falls inside a rule's cited anchor range: the
+  code the rule stands on MOVED. Highest priority; also a staleness signal
+  (the note may need a scoped refresh — the dirty queue already tracks it).
+- **· file** — the file changed elsewhere but the rule governs it.
+- **! open improvements** citing a touched file — is this change making the
+  debt better, worse, or is it the fix itself (then bloom's close flow)?
+
+Output: `.rafa/review.json` + summary. A bounded pass SAYS what it dropped
+(never a silent cap); a mid-pass transport failure marks the list PARTIAL.
+
+## Pass 2 — the judge (prism-style, scoped)
+
+For the work list ONLY — never the whole diff, never taste:
+
+1. Per **rule hit**: fetch the rule (`get_rule`, with `branch:` for the
+   working-set overlay) → does the diff still honor it? Judge against code +
+   rule, never against the author's claims. A `failure: silent` rule gets
+   extra scrutiny — that class never announces itself.
+2. Per **open improvement**: touched for better or worse? Fixed-in-passing →
+   bloom's close flow (hydrate first, `status: fixed`, report).
+3. **The active task's Done-check** (from `get_active_plan`): does the diff
+   satisfy what the plan said done means?
+4. Verdict: **PASS** or **ITERATE** with per-finding citations (rule id +
+   file:line). Findings feed atlas (validate-and-correct — atlas fixes, the
+   judge re-checks; the reviewer never edits).
+5. Emit **`report_loop_event(category: "review-verdict", outcome:
+   PASS|ITERATE, subject: <task id or branch>)`** at the ruling — sage's
+   evidence, monotonic, never a session-end sweep.
+
+## When it runs
+
+- **The pre-push beat** — before `git push`, offer the gate ("review the
+  branch against the brain? <n> rules touched"). Opt-in, advisory, never
+  blocks a push (a declined offer is honored, not re-asked this session).
+- **Plan-done verify** — rafa-build's final verify runs it as part of
+  declaring the build complete.
+- **On demand** — `/rafa review` any time.
+
+## Anti-patterns
+- Judging files the pre-pass didn't flag (scope creep = generic review).
+- Trusting the diff author's summary — judge code against rules.
+- Blocking on the gate — it is advisory; the merge reconciler is the hard gate.
+- Findings without citations (rule id + file:line) — uncited = unactionable.

package/lib/blueprint.mjs

@@ -39,6 +39,7 @@ export const BLUEPRINT = {
     ".claude/skills/rafa-plan",
     ".claude/skills/rafa-build",
     ".claude/skills/rafa-commit",
+    ".claude/skills/rafa-review",
     ".claude/skills/rafa-improve",
     ".claude/skills/rafa-distill",
     ".claude/skills/rafa-insights",

package/lib/brain-repo.mjs

@@ -77,7 +77,7 @@ export function ensureBrainRepo(cwd, { requireRemote = true } = {}) {
   // (not knowledge). MERGED line-by-line so clones ignored under an older CLI
   // still gain new exclusions.
   const ignore = join(rafaDir, ".gitignore");
-  const IGNORES = ["hydration.json", "*.theirs.md", "distill-incoming/", "distill-verdicts.json", "dirty.jsonl", "reflex.jsonl"];
+  const IGNORES = ["hydration.json", "*.theirs.md", "distill-incoming/", "distill-verdicts.json", "dirty.jsonl", "reflex.jsonl", "sensor-errors.jsonl", "benchmark.demo.json"];
   const cur = existsSync(ignore) ? readFileSync(ignore, "utf8") : "";
   const have = new Set(cur.split("\n").map((l) => l.trim()).filter(Boolean));
   const missing = IGNORES.filter((l) => !have.has(l));

package/lib/releases.mjs

@@ -264,6 +264,20 @@ export const RELEASES = [
       "first branch checkout (bounded; a failure never breaks the checkout). " +
       "`rafa update` re-vendors the post-checkout hook.",
   },
+  {
+    version: "0.8.14",
+    contract: 1,
+    plans: 2,
+    requires: "update",
+    summary:
+      "LOCAL-STATE EXCLUSION (zero-leak mirrors): the hydration sidecar + sensor " +
+      "queues (hydration.json · dirty/reflex/sensor-errors.jsonl · benchmark.demo.json " +
+      "· distill staging · *.theirs.md) are machine state, never knowledge — the " +
+      "post-commit brain hook now ENSURES the .rafa/.gitignore entries AND untracks " +
+      "anything an earlier window let git track (gitignore alone never untracks), so " +
+      "the next mirror commit cleans the branch. ensureBrainRepo's ignore list gains " +
+      "sensor-errors.jsonl + benchmark.demo.json. `rafa update` re-vendors the hook.",
+  },
   {
     version: "0.8.13",
     contract: 1,

package/lib/review.mjs

@@ -0,0 +1,160 @@
+// rafa review — the brain-grounded review gate's DETERMINISTIC pre-pass
+// (harness-arc wave 2). Zero LLM here: the diff's changed line ranges are
+// intersected with the brain's cite graph (get_code_context — file → the
+// rules/playbooks/improvements that know about it), producing the exact,
+// scoped work list the rafa-review SOP's judge then rules on. Generic
+// "review this PR" never happens — the judge only ever sees THESE rules
+// against THESE lines.
+//
+//   rafa review [--base <ref>] [--json]
+//
+// Base defaults to merge-base(HEAD, origin/<default>) — the review covers
+// everything this branch changed (committed + working tree). Advisory always:
+// exit 0, never blocks. Output: .rafa/review.json + a human summary.
+//
+//   hit: "direct"  — a changed line falls INSIDE a cite's line range (the rule's
+//                    anchor itself moved — highest review priority)
+//   hit: "file"    — the file changed elsewhere; the rule still governs it
+//
+// Open improvements citing a touched file + stale-risk flags ride along. The
+// SOP (rafa-review) judges the work list, feeds findings to atlas, and emits
+// report_loop_event(review-verdict, PASS|ITERATE).
+
+import { execSync } from "node:child_process";
+import { existsSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { callTool } from "./mcp-client.mjs";
+
+const MAX_FILES = 50; // bounded fan-out — anything dropped is SAID, never silent
+
+const flag = (args, name) => {
+  const i = args.indexOf(name);
+  return i !== -1 && args[i + 1] && !args[i + 1].startsWith("--") ? args[i + 1] : null;
+};
+
+const sh = (cmd, cwd) => {
+  try {
+    return execSync(cmd, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+  } catch {
+    return "";
+  }
+};
+
+// Parse `git diff -U0` → path → changed NEW-side line ranges [{start, end}].
+export function changedRanges(diffText) {
+  const byFile = new Map();
+  let current = null;
+  for (const line of diffText.split("\n")) {
+    const f = line.match(/^\+\+\+ b\/(.+)$/);
+    if (f) {
+      current = f[1];
+      if (!byFile.has(current)) byFile.set(current, []);
+      continue;
+    }
+    const h = current && line.match(/^@@ -\d+(?:,\d+)? \+(\d+)(?:,(\d+))? @@/);
+    if (h) {
+      const start = Number(h[1]);
+      const count = h[2] !== undefined ? Number(h[2]) : 1;
+      if (count > 0) byFile.get(current).push({ start, end: start + count - 1 });
+      else byFile.get(current).push({ start, end: start }); // pure deletion → the seam line
+    }
+  }
+  return byFile;
+}
+
+// A cite line ("12" | "10-14") vs the changed ranges → direct hit?
+export function citeHits(citeLine, ranges) {
+  const m = String(citeLine ?? "").match(/^(\d+)(?:-(\d+))?$/);
+  if (!m) return false;
+  const a = Number(m[1]);
+  const b = m[2] !== undefined ? Number(m[2]) : a;
+  return ranges.some((r) => a <= r.end && b >= r.start);
+}
+
+export default async function review(args = []) {
+  const ROOT = process.cwd();
+  if (!existsSync(join(ROOT, "rafa.json"))) {
+    console.error("✗ not a rafa repo (no rafa.json)");
+    process.exit(1);
+  }
+  const defaultBranch =
+    sh("git symbolic-ref --short refs/remotes/origin/HEAD", ROOT).replace(/^origin\//, "") || "main";
+  const base =
+    flag(args, "--base") ?? sh(`git merge-base HEAD "origin/${defaultBranch}"`, ROOT) ?? "";
+  if (!base) {
+    console.error(`✗ cannot resolve a review base (no origin/${defaultBranch}?) — pass --base <ref>`);
+    process.exit(1);
+  }
+
+  const diff = sh(`git diff -U0 ${base}`, ROOT);
+  const ranges = changedRanges(diff);
+  // Code files only — the brain plane reviews itself at reconcile, not here.
+  const files = [...ranges.keys()].filter(
+    (p) => !p.startsWith(".rafa/") && !p.startsWith(".claude/") && p !== "rafa.json",
+  );
+  const reviewed = files.slice(0, MAX_FILES);
+  const dropped = files.length - reviewed.length;
+
+  const out = [];
+  let unreachable = null;
+  for (const path of reviewed) {
+    let ctx;
+    try {
+      ctx = await callTool(ROOT, "get_code_context", { path });
+    } catch (e) {
+      unreachable = e instanceof Error ? e.message : String(e);
+      break; // one transport failure fails them all — say so, don't half-report
+    }
+    const fileRanges = ranges.get(path) ?? [];
+    const rules = (ctx.notes ?? []).map((n) => ({
+      id: n.id,
+      kind: n.kind,
+      title: n.title,
+      domain: n.domain,
+      line: n.line,
+      ...(n.failure ? { failure: n.failure } : {}),
+      hit: citeHits(n.line, fileRanges) ? "direct" : "file",
+    }));
+    const improvements = (ctx.improvements ?? []).filter((i) => i.status === "open");
+    if (rules.length > 0 || improvements.length > 0)
+      out.push({ path, ranges: fileRanges, rules, improvements, relatedPlans: ctx.relatedPlans ?? [] });
+  }
+
+  const report = {
+    schemaVersion: 1,
+    base,
+    filesChanged: files.length,
+    filesReviewed: reviewed.length,
+    ...(dropped > 0 ? { dropped } : {}),
+    ...(unreachable ? { unreachable } : {}),
+    files: out,
+  };
+  writeFileSync(join(ROOT, ".rafa", "review.json"), JSON.stringify(report, null, 2) + "\n");
+
+  if (args.includes("--json")) {
+    console.log(JSON.stringify(report, null, 2));
+    return;
+  }
+  const direct = out.flatMap((f) => f.rules.filter((r) => r.hit === "direct"));
+  const fileHits = out.flatMap((f) => f.rules.filter((r) => r.hit === "file"));
+  const imps = out.flatMap((f) => f.improvements);
+  console.log(
+    `✓ review pre-pass vs ${base.slice(0, 7)}: ${files.length} changed file(s)` +
+      (dropped > 0 ? ` (${dropped} beyond the ${MAX_FILES}-file bound NOT reviewed)` : ""),
+  );
+  if (unreachable) console.log(`  ! platform unreachable mid-pass — the work list is PARTIAL: ${unreachable}`);
+  if (out.length === 0) {
+    console.log("  no governed lines touched — nothing for the judge (the brain has no rules citing these files)");
+    return;
+  }
+  for (const f of out) {
+    console.log(`  ${f.path}`);
+    for (const r of f.rules)
+      console.log(`    ${r.hit === "direct" ? "◆" : "·"} ${r.id} [${r.domain}] ${r.title}${r.failure ? ` (failure: ${r.failure})` : ""}`);
+    for (const i of f.improvements) console.log(`    ! open ${i.priority}: ${i.id} ${i.title}`);
+  }
+  console.log(
+    `→ ${direct.length} direct anchor hit(s) · ${fileHits.length} same-file rule(s) · ${imps.length} open improvement(s)` +
+      `\n  The judge rules on exactly these (rafa-review SOP): does the diff still honor each rule; does it satisfy the active task's Done-check.`,
+  );
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rafinery/cli",
-  "version": "0.8.13",
+  "version": "0.8.14",
   "description": "rafa — the AI engineer CLI. Vendors the rafa blueprint into your repo (shadcn-style) and runs the deterministic contract gates.",
   "type": "module",
   "bin": {