@rafinery/cli 0.4.1 → 0.6.0

package/CHANGELOG.md

@@ -4,6 +4,150 @@ 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`
+(plans data v1→v2: `parent`→`epic`, `child`→`task`, stored `blocked`→`todo` +
+`blocked_reason`). Brain data unchanged; no re-scan. Re-push plans once so the platform
+rows pick up the tree + glimpse fields.
+
+- **The tree**: one epic → tasks → subtasks (three ranks — matching Linear/Jira/Asana's
+  ceiling so tracker sync stays lossless). Compile validates ranks, single root,
+  `blocked_by` resolution + acyclicity.
+- **Vendor-blended vocabulary** (checked against the real APIs): `title` ·
+  `description` (1:1 with vendor description/notes) · `approach` (rafa's how-line) ·
+  `assignee` · `blocked_by` (a dependency IS a blocker) · `blocked_reason` ·
+  `priority` 0–4 (Linear scale) · `estimate` · `external {provider, key, url}`
+  (read-only tracker identity; provider-closed ≠ done — K6).
+- **`blocked` is DERIVED, never stored** — the status enum is
+  todo|in-progress|done|superseded|abandoned; the platform renders a blocked chip from
+  unresolved `blocked_by`/`blocked_reason`.
+- **Decisions are first-class**: `log_decision` (at · actor · context · options ·
+  decision · rationale — paraphrase + pivotal quotes) with the `## Decisions` body
+  section as the human mirror; rendered as a timeline on the plan detail page.
+- Platform: glimpse cards (what/why/how/who/blocked/deps at a glance), tree detail
+  page, board blocked-chip (the Blocked column is gone — it's a condition, not a state).
+
+## 0.4.2
+
+**Adopt with:** `npx @rafinery/cli@latest update` — file re-sync only (skills + contract
+moved a few lines); no migration, no re-scan.
+
+Owner E2E feedback round (research-canvas):
+
+- **`rafa init` offers CI reconciliation** at provisioning (TTY only): yes runs
+  `ci-setup`, no prints the session-fallback path. Nothing is silently installed —
+  the workflow runs on the org's own secrets.
+- **`rafa distill --headless` is observable**: streams the agent's narration lines and
+  prints per-phase timings (brain mirror · agent turns/cost · gates · total), so a CI
+  log shows liveness and where the time goes. Failure semantics unchanged: any
+  incomplete verdict or failed gate aborts with the working set intact.
+- **Plans link to their brain slice**: optional parent-only `domains:` (contract §7) —
+  the blast radius named at plan time rides `push_plan`; the platform's new plan
+  detail page renders the plan's related knowledge beside its tasks + `## Log`
+  journals. Compile validates the shape (child `domains:` fails loudly).
+- **Live improvement signal** (platform + SOP): bloom's fixed-in-passing during build
+  now also calls `report_improvement_status` — event-only (the ledger row keeps its
+  single writer, the ingest); the Improvements page shows it as *pending
+  reconciliation* until the next brain push confirms.
+
 ## 0.4.1
 
 **Adopt with:** `npx @rafinery/cli@latest <cmd>` — no file re-sync needed (the fix is inside

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.5.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: >-
@@ -10,13 +10,14 @@ description: >-
   when a codebase must be scanned, a brain repaired after validation, a plan
   drafted from recalled knowledge, or a plan's task implemented. Runs
   context-isolated; comprehensive, cited, never cherry-picked.
-tools: Read, Write, Edit, Bash, Grep, Glob, TodoWrite, mcp__rafinery
+tools: Read, Write, Edit, Bash, Grep, Glob, TodoWrite, Skill, mcp__rafinery
 color: blue
 duties:
   - "scan :: .claude/skills/rafa-scan/SKILL.md :: comprehensive breadth-first cited brain · verify-citations exits 0 · coverage honest (thin/gap stated, never hidden)"
   - "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
@@ -84,9 +85,13 @@ Never act cold; never over-load.
   **never open `.env`/`.env.*` or any secret store, and never read or copy a value.** A key's
   *name* is a contract; its *value* is a secret. If a note genuinely needs a value, stop and ask
   the dev — don't harvest it. (Enforced in [the scan skill](../skills/rafa-scan/SKILL.md) step 4.)
-- **Orchestrate, don't bury.** At work-time, ride the host + the dev's existing skills/tools/MCP
-  and recommend the best-fit one; never reinvent a capability that already exists. rafa conducts
-  what's present.
+- **Toolbox-first execution (automatic — never an offer).** Before implementing any
+  task step, CHECK the repo's installed toolbox — committed `.claude/skills/`,
+  `.mcp.json` servers, commands — for a capability that already does it, and INVOKE
+  it (Skill tool / MCP) instead of hand-rolling. The conductor passes the matching
+  inventory slice in your spawn prompt; consult it first. Only what is actually
+  installed — never guess a capability into existence. Record the choice in the
+  item's `approach` ("how: via the <x> skill").
 
 ## Style
 Dense, no filler, no praise. Short plan before acting. Bracketed status

package/blueprint/.claude/agents/compass.md

@@ -1,6 +1,6 @@
 ---
 name: compass
-version: 0.2.1
+version: 0.3.0
 model: opus   # a false note about a PERSON is worse than one about code — best model, never cheap
 groundTruth: sessions-over-time
 description: >-
@@ -16,6 +16,8 @@ duties:
   - "bootstrap :: .claude/skills/rafa-insights/SKILL.md :: native /insights report distilled with judgment (never parsed mechanically) into dev-level candidates — each OFFERED, banked only on yes"
   - "continuous-refinement :: .claude/skills/rafa-insights/SKILL.md :: session observations routed by the boundary (dev-level here, code-level to the branch working set) · update beats duplicate · every insight legible, correctable, deletable on request"
   - "steering :: .claude/skills/rafa-insights/SKILL.md :: propose-dev-disposes at natural boundaries · at most one nudge · dismissal is final for the session · never rank, never compare, never nag"
+  - "leverage-coaching :: .claude/skills/rafa-insights/SKILL.md :: the one boundary nudge may be sourced from toolbox × patterns (repo inventory + the dev's tooling insights) — always HAS a candidate ready, never raises nudge frequency; only capabilities actually installed"
+  - "tooling-capture :: .claude/skills/rafa-insights/SKILL.md :: personal ~/.claude tooling (names + descriptions ONLY) banked as kind:tooling insights under STANDING consent · legible/deletable · never enters org stores"
 ---
 
 # compass — the dev's coach

package/blueprint/.claude/commands/rafa.md

@@ -1,5 +1,5 @@
 ---
-version: 1.3.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
@@ -28,6 +54,20 @@ unless explicitly asked (serve knowledge, not gossip). Misroutes the dev correct
 signal — prefer under-routing (answer plainly) over dragging a question through
 choreography.
 
+**Zero-command principle (owner rule, 2026-07-12):** every rafa command — CLI verbs,
+MCP tools, checkpoints, pushes, decisions logging — is AGENT-INTERNAL machinery. The
+dev speaks intent; YOU run the machinery. Never instruct the dev to run a command you
+can run yourself. The only human acts: init (provision) · `npx rafa pull` (once per
+clone) · ci-setup approval · npm publish. **Toolbox is a recall surface:** at
+bootstrap, load the committed toolbox (`.claude/skills/`, `.mcp.json`, commands)
+alongside brain status; pass the matching slice into every atlas/bloom spawn prompt —
+agents USE the fit capability automatically instead of hand-rolling (only what's
+installed, never guessed; personal `~/.claude/` stays live-recommend-only).
+**Actor envelope:** stamp `actorMeta {model, agent, runner: "session"}` on every
+state-plane write (checkpoints, plan pushes, decisions, reports) and export
+`RAFA_ACTOR_MODEL` before CLI calls — the platform records WHO/WHAT executed;
+"unreported" when unknown, never guessed.
+
 **Scope discipline (owner rule):** deliver exactly what the message asked — fix what
 they're expecting, nothing else. No unsolicited extras beyond bloom's single opt-in
 nudge. Fix-shaped prompts: recall the failure domain's knowledge → fix the asked
@@ -49,6 +89,15 @@ 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
+     `## insights`. Offered ONCE; a "no" is a standing no until the dev asks.
 
 Offer etiquette (hard rules): boundaries only, never mid-flow · once per moment — a
 "no" is remembered for the session and never re-argued · an unanswered offer never
@@ -56,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") ·
@@ -105,6 +188,11 @@ improve + push — a cheap knowledge refresh).
    explicit approval**, push the brain: `npx @rafinery/cli push` — commits `.rafa/` and
    pushes to the brain remote using the dev's own git auth, stamped `brain-for: <code sha>`.
    Never push 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` (compass; every candidate offered, banked only on yes). This is
+   the offer rung of the consent ladder — never auto-run, never re-asked after a no.
 
 atlas scans + fixes; prism judges; bloom improves; you orchestrate + push on approval. You own
 `log.md`; never edit `checklist.md` or the brain yourself — spawn atlas for that.
@@ -146,12 +234,15 @@ atlas drafts, bloom pulls, prism validates the plan itself:
 Per [the rafa-build skill](../skills/rafa-build/SKILL.md). Resume from `active.md`
 (or the platform's `get_active_plan` when connected — "load plan X" materializes it) —
 never re-derive context.
-Per task: **atlas** recalls + implements → **prism** validates against the child's
-`## Done-check` (**`status: done` only on prism PASS**; FAIL → atlas corrects) → **bloom**
-sweeps (new opportunities → ledger files; fixed-in-passing → `status: fixed`; one opt-in
-nudge max) → update the child file's `status` + `## Log` → at CHECKPOINTS (task done ·
-cadence under session consent): `push_plan`/`update_plan_status` (plans channel) +
-`rafa checkpoint` (working set) so the platform reflects live progress. Terminal
+Per item (work the tree in `blocked_by` order — an item with an unmet dependency is
+DERIVED-blocked and waits): **atlas** recalls + implements → **prism** validates against
+the item's `## Done-check` (**`status: done` only on prism PASS**; FAIL → atlas corrects)
+→ **bloom** sweeps (new opportunities → ledger files; fixed-in-passing → `status: fixed`;
+one opt-in nudge max) → update the item file's `status` + `## Log` + `## Decisions` →
+at CHECKPOINTS (task done · cadence under session consent):
+`push_plan`/`update_plan_status`/`log_decision` (plans channel — decisions record what
+the DEV chose and why; paraphrase + pivotal quotes) + `rafa checkpoint` (working set)
+so the platform reflects live progress. Terminal
 statuses when honest: `superseded` (replaced by a newer plan) · `abandoned` (dropped).
 If execution invalidates/creates brain knowledge, route per §capture (working set on a
 branch; full `## scan` on main — never hand-edit main's brain around the gate). When all