@rafinery/cli 0.5.0 → 0.7.0

package/CHANGELOG.md

@@ -4,6 +4,103 @@ The machine-readable version of this lives in [`lib/releases.mjs`](lib/releases.
 CLI reads it to tell a client, on `rafa update`, exactly what an upgrade requires (nothing,
 a re-scan, or a `rafa migrate`).
 
+## 0.6.0 — core solidity: checker v2 + the M5 capture engine
+
+**Adopt with:** `npx @rafinery/cli@latest update` — re-vendors the new lockstep hook
+scripts (`.claude/rafa/hooks/`), merges the sensor hooks into `.claude/settings.json`
+(never clobbers yours), and installs the per-clone git pre-push boundary. Brain data
+unchanged; no re-scan. Teammates get the git hook at their next `rafa pull`.
+
+**The ratchet (checker v2)** — the two catches prism recommended in the 2026-06-08 live
+run are now deterministic gates in `rafa verify-citations`:
+
+- **Absence (B3)**: a note that claims something does NOT exist declares
+  `absent: <token>` (repeatable, anchor-style). Every declared absence is re-grepped
+  every run (docs/`.md` excluded) — the moment code grows the thing, the gate fails with
+  the exact site. Mechanizes the 2026-06-08 blocker class (a "stubbed" note the code had
+  outgrown).
+- **Inventory**: `coverage.md` declares `inventory:` entries
+  (`- <name> :: <glob> :: <count>`); each is recomputed via `git ls-files ':(glob)…'` —
+  coverage claiming a surface inventory the repo has outgrown fails with the path diff.
+- **WARN heuristic (non-failing)**: an absence-shaped `title`/`summary` with no `absent:`
+  declared is listed for prism's 3b audit — a heuristic never fails the gate (that would
+  be an assumed value).
+- **Recorded gate level**: the checker writes `citation-check.json`
+  (`{checkerVersion, at, pass, gates, warns}`) and `rafa compile` folds it into
+  `manifest.citations` — the platform knows which checker version a brain actually
+  passed. No recorded run → `citations: null`, honestly.
+- Selftest extended: absence + inventory logic proven on throwaway git fixtures
+  (prism's mutation probe covers the new gates).
+
+**The M5 capture engine** — checkpoint/staleness moments become deterministic code, not
+SOP adherence (the E2E-proven weak link: a full build once produced zero captures,
+silently):
+
+- **SessionStart digest** (`.claude/rafa/hooks/session-start.mjs`): the session starts
+  knowing — dirty code files → the brain notes citing them (local manifest, or
+  `get_code_context` fail-soft ≤2s), pending `*.theirs.md` checkpoint conflicts, the
+  active plan. Prints nothing when there is nothing (silence is the honest digest).
+- **PostToolUse dirty-marker** (`.claude/rafa/hooks/post-tool.mjs`): every Edit/Write is
+  appended to `.rafa/dirty.jsonl` the moment it happens — monotonic, no session-end
+  dependency (there is no session end), never blocks, transport-excluded from brain
+  pushes via `.rafa/.gitignore`.
+- **git pre-push boundary**: `git push` of the code branch runs `rafa checkpoint`
+  (non-blocking — a checkpoint problem never stops a code push; conflicts land as
+  `.theirs.md` for YOUR decision). Installed at init/pull/update; a foreign pre-push
+  hook is respected, never clobbered (the chain line is printed instead).
+- **`rafa dirty [--json|--consume]`**: the cite-graph invalidator's query surface —
+  dirty files → citing notes; at boundaries the conductor OFFERS a scoped refresh
+  (atlas re-derives only the citing notes → gates → checkpoint), `--consume` clears the
+  queue after the refresh ships. Past the drift threshold (15 files / 10 notes) the
+  digest recommends `/rafa scan --brain-only` — the fire-alarm rung.
+- **Recursion guard (U7)**: headless runs (CI fold/distill, the Agent SDK worker) set
+  `RAFA_HOOKS_DISABLED=1`; every hook exits 0 immediately. Hooks also no-op outside a
+  rafa-provisioned repo (no `rafa.json` → silent).
+- **The correction reflex** (`.claude/rafa/hooks/user-prompt-submit.mjs` +
+  `rafa reflex`): a correction-shaped prompt ("no —", "never use X", "use Y instead")
+  is queued to `.rafa/reflex.jsonl` AND answered with a steering injection at that
+  exact moment — the session validates and banks it through the normal gates
+  same-session (branch: cited note + checkpoint · main: full gates), confirms in one
+  line, and consumes the queue entry with a verdict. Ungroundable claims are never
+  banked; unprocessed corrections from abandoned sessions surface at the next
+  session start (monotonic). Corrections are the highest-value knowledge signal —
+  they no longer evaporate.
+- **`rafa push` re-runs the checker itself** (before compile; improvements ledger too
+  when present) — a stale or hand-stamped `citation-check.json` can never ride a push;
+  the record that ships is the record of THAT push. Mechanized same-day from the
+  2026-07-13 prism live-run recommendation (the disposition protocol working).
+- Checker hardening: grep hits under `.rafa/**` are excluded categorically — the brain
+  never counts as "code", so an accidentally-tracked `.rafa/` can't self-collide the
+  completeness/absence gates.
+
+**The frictionless loop** — devs won't run commands in order, so the loop guides
+itself (owner directive; anti-nag etiquette unwaived — guidance is ambient,
+front-loaded, or earned, never interleaved):
+
+- **Loop-state statusline**: `.claude/rafa/hooks/statusline.mjs` renders
+  `rafa ▸ plan <id> 2/5 → <task> · 3 stale · 1 correction` at the bottom of every
+  session (silent outside rafa repos; a dev's existing statusline is NEVER replaced).
+  `rafa status [--line|--json]` is the harness-neutral core it mirrors.
+- **Suggested next**: the SessionStart digest gains one deterministic
+  `[rafa · next]` line — ranked conflicts → corrections → resume plan → staleness —
+  so every session opens knowing the single best next step.
+- **Direct-do path** (conductor 1.8.0): small work (≤ 1 domain, no contract surface,
+  one sitting) gets NO plan files and no approval — act first; the sensors carry the
+  loop; escalates to plan-lite with one announce line only when the work grows.
+- **Brainstorm mode**: during exploration the conductor is a grounded, cited
+  participant with zero workflow talk; at crystallization, exactly one offer (a plan
+  if it's work, a working-set note if it's a conclusion).
+
+**Portability (owner directive, 2026-07-13):** built for Claude Code now, ships for
+Cursor/Codex later — loop logic lives in the harness-neutral core (CLI verbs + the
+`.rafa/*.jsonl` queues + gates + MCP); everything under `.claude/rafa/hooks/` is a
+thin per-harness adapter. The event protocol (detect → queue → steer →
+bank-through-gates) is the portable contract.
+
+The honest boundary, by design: hooks make **sync, staleness, and boundaries**
+deterministic; **authoring stays model work** — steered by the injected digest, visible
+on the platform ("working set clean" is a real answer, not a gap).
+
 ## 0.5.0 — plans v2: the work-item tree
 
 **Adopt with:** `npx @rafinery/cli@latest update` → it runs the mechanical `rafa migrate`

package/bin/rafa.mjs

@@ -1,18 +1,26 @@
 #!/usr/bin/env node
 // rafa — the rafinery CLI. Thin dispatcher; each command lives in ../lib.
 //
-//   rafa init [<setup-url>]   provision this repo (vendor blueprint + wire the platform)
+//   rafa init [<setup-url>]   provision this repo (vendor blueprint + wire the platform + sensors)
 //   rafa update               re-sync the blueprint into this repo (shadcn-style)
 //   rafa compile              run the contract gate → .rafa/manifest.json
-//   rafa verify-citations     deterministic citation checker (B1/B2/policy gates)
+//   rafa verify-citations     deterministic citation checker (B1/B2/policy/absence/inventory)
 //   rafa push                 compile + push .rafa/ to the brain remote (main-branch act)
 //   rafa pull [--full]        make this clone brain-ready (lazy skeleton; --full mirrors)
+//   rafa checkpoint           sync this branch's working set (CAS; conflicts → .theirs.md)
+//   rafa hydrate              fault knowledge into the lazy .rafa/
+//   rafa dirty [--json]       staleness queue → citing notes; --consume after a refresh
+//   rafa fold                 branch→parent mechanical fold of the working set (no LLM)
+//   rafa distill --headless   CI merge-to-main distillation (org's own LLM key)
+//   rafa ci-setup             write the reconcile workflow (fold + distill on PR merge)
 //   rafa leverage             inspect your agent toolbox → proactive tips
+//   rafa benchmark            reproduce the brain-vs-cold token proof on THIS repo (measured)
 //   rafa migrate              bring structured files (plans/config) up to the current schema
 //
 // The gate tools live INSIDE this package (blueprint split, 0.4.0) — nothing is
 // vendored into .rafa/bin anymore. The LLM work (scan / improve / plan) runs
-// inside Claude Code via /rafa.
+// inside Claude Code via /rafa. The M5 sensor hooks (.claude/rafa/hooks/) are
+// vendored LOCKSTEP; commands are agent-internal machinery (zero-command rule).
 
 import { readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
@@ -30,10 +38,14 @@ const COMMANDS = [
   "pull",
   "checkpoint",
   "hydrate",
+  "dirty",
+  "reflex",
+  "status",
   "fold",
   "distill",
   "ci-setup",
   "leverage",
+  "benchmark",
   "migrate",
 ];
 const [cmd, ...rest] = process.argv.slice(2);
@@ -53,8 +65,10 @@ Commands:
                         --keep       keep all changed owned files without asking
                         (default: ask per file; in a non-TTY it keeps them)
   compile              Validate the brain against the contract → .rafa/manifest.json.
-  verify-citations     Deterministic citation checker: every cite resolves (B1), every
-                       contract anchor's code occurrences are cited (B2), policy holds.
+  verify-citations     Deterministic citation checker (v2): every cite resolves (B1),
+                       every contract anchor's code occurrences are cited (B2), policy
+                       holds, declared absences re-grepped (B3), coverage inventories
+                       re-counted. Records the run (citation-check.json → manifest).
   push                 Compile, then push .rafa/ to your brain remote (from main — the
                        org brain describes the default branch). Stamps the contract copy.
   pull                 Make this clone brain-ready — bootstraps the lazy .rafa/ skeleton
@@ -67,6 +81,19 @@ Commands:
   hydrate              Fault knowledge into the lazy .rafa/:  hydrate rule <id> ·
                        hydrate playbook <id> (org brain, stamped disposable-cache) ·
                        hydrate --working-set (this branch's synced files).
+  dirty                The staleness queue (M5): code files edited since the last brain
+                       reconcile → the brain notes citing them. --json for agents;
+                       --consume clears it AFTER a scoped refresh shipped. The queue is
+                       written by the PostToolUse sensor hook the moment an edit happens.
+  reflex               The correction queue (M5): corrections the UserPromptSubmit sensor
+                       detected. List/--json; --consume <id> [verdict] AFTER banking it
+                       through the gates (or judging it session-only). Corrections are
+                       the highest-value knowledge signal — they must never evaporate.
+  status               Where the loop stands, from local state only: active plan +
+                       task progress · stale count · corrections · conflicts.
+                       --line = the one-line ambient form (statuslines/prompts) ·
+                       --json = machine shape. Harness-neutral core: the Claude Code
+                       statusline adapter mirrors exactly this.
   fold                 Branch→parent MECHANICAL fold of the working set (no LLM):
                        rafa fold --from <branch> --to <parent>. Divergence → flagged
                        needs-adjudication for the next dev session, never guessed.
@@ -78,6 +105,11 @@ Commands:
                        PR merge) and name the CI secrets to configure.
   leverage             Inspect your agent toolbox (permissions, skills, MCP) and print
                        prioritized tips for getting more out of it. Advisory — changes nothing.
+  benchmark            Reproduce the brain-vs-cold token-efficiency proof on THIS repo: cut
+                       two isolated worktrees (A=cold, B=brain), run the same task fixture,
+                       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.
   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/agents/atlas.md

@@ -1,6 +1,6 @@
 ---
 name: atlas
-version: 3.6.0
+version: 3.7.0
 model: opus   # authoring is correctness-critical — a hallucinated note poisons the brain; best model, never cheap
 groundTruth: code-at-sha
 description: >-
@@ -17,6 +17,7 @@ duties:
   - "repair :: .claude/skills/rafa-scan/SKILL.md :: every blocker + major in checklist.md fixed against the code · checker re-run to exit 0 · never weaken a check to pass it"
   - "plan-drafting :: .claude/skills/rafa-plan/SKILL.md :: recall-grounded decomposition (coverage → search → notes) · blast radius named · contract §7 files · every child carries a Done-check"
   - "build-execution :: .claude/skills/rafa-build/SKILL.md :: implement per recalled knowledge · never hand-edit brain files around the gate · return what changed, cited"
+  - "scoped-refresh :: .claude/skills/rafa-scan/SKILL.md :: re-derive ONLY the dirty-cited notes against current code (input: rafa dirty --json) · same gates as scan (verify-citations exit 0) · on main: compile+push; on a branch: working-set edit + checkpoint · queue consumed only after the refresh ships"
 ---
 
 # atlas — senior design engineer

package/blueprint/.claude/agents/sage.md

@@ -0,0 +1,66 @@
+---
+name: sage
+version: 0.1.0
+model: opus   # a wrong learning re-shapes an agent for every repo — best model, never cheap
+groundTruth: sessions-over-time
+description: >-
+  The silent L5 observer — studies OUR agents (atlas · prism · bloom · compass),
+  never the devs. Reads loop outcomes (prism verdicts, gate results, reflex
+  outcomes, distill refutations) by SHAPE via get_loop_events, finds PATTERNS of
+  agent structure that under-cover classes of misses, and authors an evidence-cited
+  learnings ledger of proposed card/SOP diffs for human/MR review. Silent (never
+  intervenes mid-session), evidence-cited (event shapes/categories only), person-free
+  (person-shaped → compass), asset-free (NO customer code content ever), and
+  proposals never self-apply.
+tools: Read, Grep, Glob, Skill, Write, mcp__rafinery
+color: cyan
+duties:
+  - "observe-pass :: .claude/skills/rafa-sage/SKILL.md :: cited to loop-event SHAPES via get_loop_events · patterns of agent structure only · learnings ledger of proposed card/SOP diffs · silent (no mid-session output) · advisory, never nagging"
+  - "scrub :: .claude/skills/rafa-sage/SKILL.md :: every entry passes the SCRUB STEP before write — anything asset-shaped (code content, snippets, repo-specific facts, repo-identifying detail) abstracted to the pattern or DROPPED; the ledger entry schema has NO code-content-capable field"
+  - "route-person-shaped :: .claude/skills/rafa-sage/SKILL.md :: a person-shaped observation is NEVER a learning — it routes to compass's consent path (rafa-insights, user brain), never sage's ledger"
+  - "propose-only :: .claude/skills/rafa-sage/SKILL.md :: output is PROPOSED diffs to agent cards/SOPs — applying a change is a separate human/MR-reviewed act; sage never self-applies and never edits an agent card or SOP"
+---
+
+# sage — the silent L5 observer
+
+You are **sage**, rafa's fifth agent and its **self-improvement loop (L5: system → itself)**.
+Where **atlas** knows the code, **prism** doubts the claims, **bloom** raises the code floor,
+and **compass** coaches the dev — **you raise the floor of the agents themselves.** Your subject
+is never a codebase and never a person: it is the SHAPE of how our agents perform over time, read
+from the loop-events store.
+
+**You are silent.** You never intervene mid-session, never interleave output into a dev's flow.
+You run only when explicitly invoked (`/rafa sage`) or offered at a boundary. Your product is a
+ledger, reviewed later — not a live nudge.
+
+**You are asset-free — the tenancy twin of compass's person floor.** Nothing customer-scoped ever
+enters your ledger: no code content, no snippets, no repo-specific facts, no repo-identifying
+detail. What you capture is how to shape OUR agents (cards / SOPs / prompts) to cover *classes* of
+misses that generalize across repos. Evidence cites loop-event SHAPES and categories (verdict
+types, gap classes, miss taxonomies) — never a customer artifact. Anything asset-shaped is
+abstracted to the pattern or dropped. This is binding (owner, 2026-07-13): *nothing person-scoped
+leaves the user brain · nothing customer-scoped leaves the customer's stores.*
+
+**You are person-free.** You study agents, never devs. A person-shaped observation is never a
+sage learning — it routes to **compass**'s consent path (the user brain), never your ledger.
+
+**Your proposals never self-apply.** You output an evidence-cited learnings ledger proposing diffs
+to agent cards / SOPs. Applying any change is a separate, versioned, human/MR-reviewed act — like
+bloom's advisory ledger, kept out of every auto-apply path. You never edit an agent card or SOP.
+
+## SOP
+Load and follow [the sage skill](../skills/rafa-sage/SKILL.md) exactly — the creed
+(silent · evidence-cited · person-free · asset-free · proposals-never-self-apply), the SCRUB STEP,
+the learnings-ledger entry schema, and the procedure. Spawned by the **conductor** (`/rafa sage`,
+or a boundary offer), context-isolated.
+
+## Output
+The **learnings ledger** — a committed, human-reviewed governance artifact at
+`.claude/rafa/learnings/` (per the SOP): `learnings/<id>.md` (one proposed card/SOP diff each) +
+`ledger.md` (the index). **Never** a Convex table; **never** inside any customer `.rafa/brain/`
+(learnings are about OUR agents — they never mix with customer knowledge). Every entry cites loop-
+event shapes only and passes the scrub step, or it doesn't ship.
+
+## Style
+Terse, pattern-first, no nagging. Lead with the highest-leverage learning — the one card/SOP change
+that would cover the widest class of misses. The full ledger holds the rest.