@rafinery/cli 0.5.0 → 0.6.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,25 @@
 #!/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 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,6 +37,9 @@ const COMMANDS = [
   "pull",
   "checkpoint",
   "hydrate",
+  "dirty",
+  "reflex",
+  "status",
   "fold",
   "distill",
   "ci-setup",
@@ -53,8 +63,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 +79,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.

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/commands/rafa.md

@@ -1,5 +1,5 @@
 ---
-version: 1.5.0
+version: 1.8.0
 description: rafa — the repo's engineering SOP. Use whenever the dev wants to plan a feature or change, build/execute against the active plan, improve code health, or ground work in the repo's brain — intent counts, the dev does NOT need to type /rafa. Also explicit: /rafa <init|scan|improve|plan|build|push|leverage|migrate|update|help> [--brain-only]. Admin verbs (init/scan/push/migrate/update) run ONLY when explicitly invoked.
 ---
 
@@ -13,14 +13,40 @@ Admin verbs are expensive or side-effectful and run **only when explicitly typed
 
 | Prompt shape | Route |
 |---|---|
-| "let's add / build / implement / refactor X" (no active plan) | `## plan` — weight by blast radius: lite vs full (see plan.md § plan-lite) |
+| small work — radius ≤ 1 domain, no contract surface, fits one sitting | **DIRECT-DO**: recall → implement → verify → done. NO plan files, NO approval, NOTHING to remember — the sensors carry the loop (dirty-mark, reflex, checkpoint-at-push). Escalate only if it GROWS (below). |
+| "let's add / build / implement / refactor X" — real blast radius (≥ 2 domains, a contract surface, or multi-session) (no active plan) | `## plan` — weight by blast radius: lite vs full (see plan.md § plan-lite) |
 | same, with an active plan covering it | `## build` |
 | "why / how / where does X …" (a question) | recall-and-answer: MCP `search_knowledge` → cited answer. No choreography. |
+| exploration — "what if / should we / compare / thinking about X" | **BRAINSTORM mode** (§ below): grounded participant, zero workflow talk, one offer at crystallization. |
 | "list plans / what plans are there" | `list_plans` — NAMES ONLY (id · title · status · progress); never dump bodies |
 | "load / open / work on plan X" | `get_plan(X)` → materialize parent + children (bodies) into `.rafa/plans/<X>/` + set `active.md` → resume per `## build` |
 | "improve / clean up / what's rotting" | `## improve` |
 | explicit `/rafa <admin verb>` — init · scan · push · migrate · update | that verb, and ONLY then |
 
+**Direct-do — the light path must be lighter than bypassing rafa.** For small work
+the default INVERTS: act first, record only if it earns recording. No announcement
+ceremony either — just do it (recall still automatic; verify still real: types/lint/
+tests as the repo warrants). **The escalation rule:** the moment the work grows — a
+second domain, a contract surface, or it clearly won't finish this sitting — say ONE
+line (*"this grew — recording it as a plan so it's resumable"*), create the plan-lite
+files THEN, and continue; never ask permission to keep the loop honest, and never
+escalate a task that stayed small. What keeps direct-do safe with zero ceremony: the
+sensors (every edit dirty-marked, corrections reflexed, `git push` checkpoints) plus
+§capture for anything learned — the loop closes without the dev or you filing
+paperwork.
+
+**Brainstorm mode — grounded participant, not a process.** During exploration:
+recall automatically and cite (the brain is WHY the brainstorm is good), think WITH
+the dev, and say NOTHING about plans, captures, checkpoints, or process — zero
+workflow talk mid-exploration. At CRYSTALLIZATION (the dev stops exploring and
+starts concluding — "ok let's do X", "so the decision is Y", or asks to proceed):
+exactly ONE offer, shaped by what the conversation produced — work → *"want me to
+turn this into a plan?"* · a durable conclusion with no work attached → *"bank the
+conclusion as a note?"* (a plan-less decision lands as a working-set note under
+§capture, so brainstorm output survives even when no work item ever exists). A "no"
+stands for the session. If nothing crystallized, offer nothing — an open exploration
+is a fine place to end.
+
 **Announce-and-proceed, never ask-permission:** state the route in one line — *"this
 looks plan-shaped — following the plan SOP (say 'skip' to bypass)"* — then go. "skip"
 always wins, immediately and without argument. Never narrate other devs' activity
@@ -63,6 +89,11 @@ Three interaction modes by the weight of the action:
    - session start, local ahead of platform → *"brain is N commits behind — push?"*
    - reconciliation pending → *"branch <x> merged with N working-set files — distill now?"*
    - adjudication pending → *"1 file diverged at the <x>→<y> fold — pick a copy?"*
+   - staleness (the M5 dirty queue, injected by the SessionStart digest or read via
+     `rafa dirty --json` at boundaries) → *"N notes cite files you've touched — refresh
+     just those?"* — accepted = atlas scoped-refresh (only the citing notes, gates as
+     usual, checkpoint/push per branch rules), then `rafa dirty --consume`. Past the
+     drift threshold the offer escalates to */rafa scan --brain-only* (the fire-alarm).
    - user brain EMPTY (first session / founding scan just completed) → *"want me to
      bootstrap your insights from your usage report? (compass distills it; every
      candidate is offered — nothing banked without your yes)"* — accepted = run
@@ -74,13 +105,47 @@ blocks; keep working, the offer stands · admin verbs stay explicit — an ACCEP
 offer is the explicit invocation.
 
 **Bootstrap digest — one question, however much is pending.** Session start may
-accumulate many offers (staleness push, N distills, needs-adjudication flags, a
-nudge). NEVER ask them serially — batch into ONE itemized digest: *"3 things
-pending: brain push · 2 merged branches to distill · 1 file needs adjudication —
-want any now, or later?"*
+accumulate many offers (staleness push, N distills, needs-adjudication flags, dirty
+notes to refresh, a nudge). NEVER ask them serially — batch into ONE itemized digest:
+*"4 things pending: brain push · 2 merged branches to distill · 1 file needs
+adjudication · 3 notes cite code you changed — want any now, or later?"*
 Dismissible as a unit; offer fatigue trains reflexive yes, which corrodes every
 consent rung above it.
 
+**The M5 sensors feed you — you never poll.** Four deterministic instruments run
+outside the model (blueprint hooks + the git boundary): the SessionStart digest
+injects staleness/conflicts/corrections/active-plan as context at session start ·
+every Edit/Write is dirty-marked into `.rafa/dirty.jsonl` the moment it happens ·
+`git push` runs `rafa checkpoint` mechanically (non-blocking) · a correction-shaped
+prompt is queued to `.rafa/reflex.jsonl` AND arrives with a `[rafa · reflex <id>]`
+steering injection. Your part is the JUDGMENT half: consume `rafa dirty --json` at
+natural boundaries, offer the scoped refresh (above), and run `rafa dirty --consume`
+ONLY after a refresh actually shipped through the gates. Sensors make the moments
+deterministic; authoring stays yours.
+
+**Guidance is ambient · front-loaded · earned — never interleaved.** The dev sees
+the loop three ways and ONLY three: the **statusline** (always-on one-liner —
+plan progress · stale · corrections · conflicts; `rafa status --line` is the same
+truth for any surface) · the digest's **`[rafa · next] suggested next:`** line
+(deterministic, ranked: conflicts → corrections → resume plan → staleness) — honor
+it by putting that item FIRST in the bootstrap digest · the **boundary offers**.
+Never emit mid-flow "next step" reminders; the statusline already says it silently.
+
+**The correction reflex (bank it THIS session, not next scan).** When the
+`[rafa · reflex <id>]` injection arrives: first address the dev's correction; then
+judge it — is this DURABLE repo knowledge (a convention/contract/fact a future
+session needs), or a one-off steer? Durable → bank NOW through the gates: on a
+branch, author/edit the note under `.rafa/brain/**` (≥1 resolving cite) +
+`rafa checkpoint`; on main, full gates (verify-citations · compile · push). Confirm
+to the dev in ONE line — note id + where it landed — then
+`rafa reflex --consume <id>`. Not durable (preference, out-of-code claim,
+one-off) → say it stays session-only and consume with verdict `session-only`. An
+ungroundable claim is NEVER banked (no cite = no note — tell the dev honestly).
+Unprocessed corrections from abandoned sessions surface in the bootstrap digest —
+work them like any pending item. Dev-level preferences route to compass's offer
+path (user brain), never the org stores. Raw transcripts never enter any shared
+store; only the distilled, cited note ships.
+
 **The frame is CONSENT (owner, 2026-07-10).** Four rungs, each action needs exactly
 one: (1) **implied** — the message itself consents to what it asks, and only that ·
 (2) **session** — asked once, remembered, revocable mid-session ("stop pushing") ·

package/blueprint/.claude/rafa/contract.md

@@ -46,8 +46,11 @@ doesn't validate, compile fails.
 | plan | `plans/**/*.md` | **structured** | §7 | plan/build |
 | log | `brain/log.md` | **verbatim** | — (prose trail) | conductor |
 | citation-check | `**/citation-check.md` | **generated** | — (by `rafa verify-citations`) | tool |
+| citation-check record | `**/citation-check.json` | **generated** | `{ checkerVersion, at, pass, gates, warns }` (by `rafa verify-citations`; compile folds it into `manifest.citations`) | tool |
 | active pointer | `active.md` | **generated** | — (`# <plan-id>` or "No active plan"; compile emits it as `activePlanId`, §7) | conductor |
 | contract copy | `contract.md` | **generated** | — (stamped copy of `.claude/rafa/contract.md`, written by `rafa push`) | tool |
+| dirty queue | `dirty.jsonl` | **generated** (local state — transport-excluded, NEVER pushed/ingested) | one `{f, t}` JSON line per code edit (by the PostToolUse sensor hook; read by `rafa dirty` + the SessionStart digest) | tool |
+| reflex queue | `reflex.jsonl` | **generated** (local state — transport-excluded, NEVER pushed/ingested; transcript pointers are LOCAL, raw transcripts never ship) | `{id, p, t, tp}` per detected correction + append-only `{id, done, verdict, at}` markers (by the UserPromptSubmit sensor; read by `rafa reflex` + the digest) | tool |
 | agent | `.claude/agents/*.md` (code repo) | **structured** (local gate — NOT in manifest) | §10 | rafa |
 
 The `agent` type is the one structured type outside `.rafa/`: the shipped agent cards
@@ -146,6 +149,12 @@ JSON. This is the exact shape the platform binds to.
     ]
   },
 
+  "citations": {                            // from brain/citation-check.json — or null
+    "checkerVersion": 2,                    // the gate level this brain passed
+    "pass": true,                           // that run's verdict (recorded, never assumed)
+    "at": "2026-07-12T10:00:00Z"            // when the checker last ran
+  },                                        // null = no recorded checker run rode this push
+
   "notes": [
     {
       "id": "agent-name-contract",
@@ -204,6 +213,14 @@ title: The agent name is a cross-process contract   # required
 summary: Only "research_agent" is fully wired end to end   # required
 links: [copilotkit-runtime-route-convention]   # optional · default []
 failure: silent                  # optional · silent | loud
+anchor: research_agent           # optional · checker gate B2: EVERY code hit of this
+                                 #   token must be a cited site (`anchor: none` = explicit
+                                 #   exemption for composition/ordering contracts)
+absent: legacy_agent_name        # optional · checker gate B3: this token must appear
+                                 #   NOWHERE in code (docs/.md excluded) — declare one for
+                                 #   every claim that depends on something NOT existing;
+                                 #   the checker re-greps it every run, so the claim can
+                                 #   never silently go stale. Repeatable (one per line).
 cites:                           # required · ≥ 1
   - src/lib/model-selector-provider.tsx:42 :: research_agent
   - agents/python/main.py:20 :: research_agent
@@ -211,6 +228,12 @@ cites:                           # required · ≥ 1
 （prose body — rendered verbatim, never parsed）
 ```
 
+`anchor:`/`absent:` are **checker declarations** (consumed by `rafa verify-citations`
+gates B2/B3, not emitted into the manifest). A note whose title/summary reads as an
+absence claim without declaring `absent:` is listed as a checker WARN — prism's
+worklist, never a gate failure (a heuristic that fails the gate would be an assumed
+value).
+
 ---
 
 ## 3. Improvement files — `improve/improvements/*.md`
@@ -282,10 +305,19 @@ domain found (compile emits it as `[{ domain, status }]` in the manifest). Statu
 ---
 schemaVersion: 1
 domains: { design-system: mapped, components: mapped, api: thin, external-integrations: empty }
+inventory:                       # optional · declared surface inventories, re-counted by
+  - route-pages :: apps/web/app/**/page.tsx :: 23      # the checker every run
+  - api-routes :: apps/web/app/api/**/route.ts :: 2
 ---
 （per-criterion PASS/FAIL narrative in the body）
 ```
 
+`inventory:` entries are `<name> :: <glob> :: <count>` — the checker recomputes each
+count via `git ls-files ':(glob)<glob>'` and FAILS on drift (coverage claiming a
+surface inventory the repo has outgrown). atlas declares one per framework surface it
+maps (route pages, API routes, workflows — whatever the repo's shape makes load-bearing);
+compile validates the grammar, the checker owns the truth.
+
 ---
 
 ## 7. Plan files — `plans/**/*.md` (+ the plans channel) — **v2: the work-item tree**

package/blueprint/.claude/rafa/hooks/post-tool.mjs

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+// rafa hook · PostToolUse (Edit|Write|MultiEdit|NotebookEdit) — the dirty-marker.
+//
+// M5 capture engine, sensor #1: every code edit is recorded the moment it happens
+// (monotonic, event-driven — never at session end, because there is no session end).
+// Appends {f, t} to .rafa/dirty.jsonl; the SessionStart digest and `rafa dirty`
+// resolve entries to the brain notes that cite those files (the codeRefs plane).
+//
+// Hard rules: NEVER block the session (exit 0 on every path, all errors swallowed),
+// no network, no LLM, O(append). Honors RAFA_HOOKS_DISABLED=1 (headless workers /
+// CI distillation set it — the recursion guard).
+
+import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join, relative, isAbsolute, sep } from "node:path";
+
+try {
+  if (process.env.RAFA_HOOKS_DISABLED === "1") process.exit(0);
+
+  let input = "";
+  try {
+    input = readFileSync(0, "utf8"); // stdin: the hook event JSON
+  } catch {
+    process.exit(0);
+  }
+  let evt = null;
+  try {
+    evt = JSON.parse(input);
+  } catch {
+    process.exit(0);
+  }
+
+  const root = process.env.CLAUDE_PROJECT_DIR || evt?.cwd || process.cwd();
+  if (!existsSync(join(root, "rafa.json"))) process.exit(0); // not a rafa-provisioned repo
+
+  const fp = evt?.tool_input?.file_path || evt?.tool_input?.notebook_path;
+  if (!fp || typeof fp !== "string") process.exit(0);
+
+  const rel = isAbsolute(fp) ? relative(root, fp) : fp;
+  // Outside the repo, or not code-plane: knowledge/state/tooling edits don't dirty the brain.
+  if (rel.startsWith("..") || isAbsolute(rel)) process.exit(0);
+  const top = rel.split(sep)[0];
+  if ([".rafa", ".claude", ".git", "node_modules"].includes(top) || rel === "rafa.json") process.exit(0);
+
+  const rafaDir = join(root, ".rafa");
+  mkdirSync(rafaDir, { recursive: true });
+
+  // Transport exclusion, belt-and-braces: the queue is session-local state and must
+  // never ride a brain push (`rafa push` commits .rafa/ wholesale). ensureBrainRepo
+  // writes this too — this covers the window before any pull/push ran here.
+  const gi = join(rafaDir, ".gitignore");
+  const body = existsSync(gi) ? readFileSync(gi, "utf8") : "";
+  if (!/^dirty\.jsonl$/m.test(body))
+    writeFileSync(gi, body + (body === "" || body.endsWith("\n") ? "" : "\n") + "dirty.jsonl\n");
+
+  appendFileSync(
+    join(rafaDir, "dirty.jsonl"),
+    JSON.stringify({ f: rel.split(sep).join("/"), t: new Date().toISOString() }) + "\n",
+  );
+} catch {
+  /* a sensor must never take down the session */
+}
+process.exit(0);

package/blueprint/.claude/rafa/hooks/pre-push

@@ -0,0 +1,24 @@
+#!/bin/sh
+# rafa pre-push hook v1 (installed by @rafinery/cli init/pull/update — safe to
+# delete; it will be offered again, never forced over a foreign hook).
+#
+# M5 capture engine, sensor #3: `git push` of the CODE branch is a ratified
+# natural checkpoint boundary — so the branch WORKING SET (edited/new brain
+# files) syncs to the platform deterministically here, not only when a session
+# remembers its SOP. Non-blocking by design: a checkpoint problem must never
+# stop a code push (exit 0 on every path; conflicts land as .theirs.md copies
+# for the next session to decide — printed, never auto-resolved).
+
+[ "$RAFA_HOOKS_DISABLED" = "1" ] && exit 0
+[ -f "rafa.json" ] || exit 0
+
+echo "rafa · checkpoint (pre-push boundary) …"
+npx -y @rafinery/cli checkpoint || {
+  code=$?
+  if [ "$code" = "2" ]; then
+    echo "rafa · checkpoint CONFLICT — a teammate's newer copy landed as *.theirs.md; decide in your next session (merge/adopt/keep, re-run rafa checkpoint). Push continues."
+  else
+    echo "rafa · checkpoint skipped (exit $code) — push continues; run 'rafa checkpoint' manually when convenient."
+  fi
+}
+exit 0