@rafinery/cli 0.4.1 → 0.6.0

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,69 +305,109 @@ 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)
+## 7. Plan files — `plans/**/*.md` (+ the plans channel) — **v2: the work-item tree**
 
-Each child owns exactly one file (so merges never conflict; parent progress is
-derived by counting).
+Plans are a TREE of work items (plans data version 2, ratified 2026-07-12): one
+**epic** (the root) → **tasks** → **subtasks**. Three ranks, deliberately matching
+the ceiling of Linear (Project→Issue→sub-issue), Jira (Epic→Task→Sub-task), and
+Asana (Project→Task→Subtask) so tracker sync is lossless. Vocabulary is
+vendor-blended: field names below are the majority vendor names wherever one exists.
+Each item owns exactly one file (merges never conflict; progress is derived).
 
 ```yaml
 ---
 schemaVersion: 1
-id: multitenant-c1-schema        # required · == filename stem · GLOBALLY unique across plans/**
-plan: multitenant                # required · the parent plan id
-parent: multitenant              # required · parent plan id (child), or null (root)
-kind: parent | child             # required
-title: …                         # required
-status: todo | in-progress | done | blocked | superseded | abandoned   # required (child); parent may omit
-branch: feat/mt-c1               # optional · the branch this executes on
+id: payments-c3-webhooks         # required · == filename stem · GLOBALLY unique across plans/**
+plan: payments                   # required · the ROOT (epic) id
+parent: payments-c3              # required · the parent ITEM id (any rank above), or null (epic)
+kind: epic | task | subtask      # required · epic = root only · task's parent = the epic · subtask's parent = a task
+title: Handle provider webhooks  # required · WHAT (Linear title · Jira summary · Asana name)
+description: >-                  # optional · WHY + context — syncs 1:1 with vendor description/notes
+  reconciliation must be automatic; manual matching doesn't scale
+approach: verify HMAC → enqueue → idempotent apply   # optional · HOW, one line — rafa value-add
+status: todo | in-progress | done | superseded | abandoned   # required (task/subtask); epic may omit
+assignee: rohik                  # optional · WHO (free string pre-orgs; unanimous vendor word)
+blocked_by: [payments-c2]        # optional · item ids this waits on — a dependency IS a blocker
+blocked_reason: "vendor sandbox access"   # optional · external blocks (no dependency id to point at)
+priority: 2                      # optional · 0 none · 1 urgent · 2 high · 3 medium · 4 low (Linear scale)
+estimate: 3                      # optional · points (Linear estimate / Jira story points)
+branch: feat/webhooks            # optional · ↔ Linear branchName
 baseSha: abc123                  # optional · commit it was cut from
+domains: [payments]              # optional · EPIC only · the blast radius — the brain link
+external: { provider: jira, key: PAY-142 }   # optional · tracker identity — READ-ONLY to sessions
 ---
-（prose body — for a child it MUST contain a `## Done-check` section: the expected
-outcome prism validates execution against. Compile never parses bodies; a missing
-Done-check is rejected by prism's PLAN validation, not by compile.）
+（prose body — a LEAF item (a task with no subtasks, or a subtask) MUST carry a
+`## Done-check`; `## Log` is the execution journal; `## Decisions` mirrors the
+structured decision records (below). Compile never parses bodies.）
 ```
 
 Rules (all compile-enforced unless noted):
 
-- **Global id uniqueness.** `plans/**` is nested, so stems could collide; a duplicate
-  plan id anywhere under `plans/` is a compile error. Convention: prefix children
-  with the plan id (`<plan>-c1-….md`).
-- **`kind: parent`** → `parent` MUST be `null` and `plan` MUST equal `id`.
-- **`kind: child`** → `plan` MUST resolve to a `kind: parent` file in the same
-  compile, and `parent` MUST equal `plan` (flat parent→children in v1). A dangling
-  child is a loud error; a parent with zero children is valid (a plan just created).
-- **Progress is never stored.** A `progress` key in plan frontmatter is a compile
-  error. Parent progress is `count(children where status == done) / count(children)`
-  — derived at read time, everywhere (compile, platform, MCP).
-- **Statuses.** `done` exists only on prism PASS (the execution gate). The two
-  TERMINAL statuses close work honestly without pretending `done`:
-  `superseded` (a newer plan replaces it) · `abandoned` (deliberately dropped).
-  `blocked` is waiting, not terminal. Statuses are set in sessions; the platform
-  board renders them read-only.
-- **`active.md` → `activePlanId`.** Compile reads the generated pointer: a first line
-  `# <plan-id>` must resolve to a `kind: parent` plan (else compile error);
-  `# No active plan` or a missing `active.md` → `activePlanId: null` (documented
-  default — the pointer is generated, absence means "none", never a guess of one).
-  The PLATFORM pointer is set separately through `set_active_plan` (below).
-
-**Transport — the plans channel (0.4.0; plans never ride the brain manifest):**
-
-- **Authoring**: plans are drafted as the files above (compile-validated —
-  determinism holds; `.rafa/plans/` is the working copy).
-- **Push on approval**: the dev's approval IS the trigger — `push_plan` sends the
-  whole plan (parent + children + bodies) to the platform; `set_active_plan`
-  points the repo's active pointer at it. Build cadence re-pushes statuses +
-  `## Log` journals (`push_plan` upsert / `update_plan_status`).
-- **Pull-based work**: `list_plans` returns NAMES ONLY (id · title · status ·
-  progress); **"load plan X"** = `get_plan` (bodies included) materialized back
-  into `.rafa/plans/` by the session. Nothing plan-shaped is hydrated until
-  explicitly loaded.
+- **Global id uniqueness** across `plans/**` (duplicate = error). Convention: prefix
+  descendants with the epic id.
+- **Tree shape.** Exactly ONE `kind: epic` per plan; `epic` → `parent: null`, `plan == id`.
+  A task's `parent` is the epic; a subtask's `parent` is a task. Every item's `plan`
+  is the root epic id. Dangling parents and rank violations are loud errors.
+- **`blocked` is DERIVED, never stored.** An item is blocked when it has an
+  unresolved `blocked_by` (a listed item not yet `done`) or a `blocked_reason`.
+  `status: blocked` is a compile ERROR (removed in v2 — `rafa migrate` converts).
+  No vendor stores blocked as a state either (Linear: relations · Jira: links +
+  Flagged · Asana: dependencies) — deriving it keeps sync lossless.
+- **`blocked_by` ids resolve within the plan and are acyclic.**
+- **Progress is never stored.** A `progress` key is a compile error. Progress =
+  `count(done LEAVES) / count(leaves)` per subtree — derived everywhere.
+- **Statuses.** `done` exists only on prism PASS (the execution gate). Terminal:
+  `superseded` (replaced by a newer plan) · `abandoned` (deliberately dropped) —
+  mapping losslessly to Linear `canceled` / Jira resolution "Duplicate"/"Won't do".
+  Statuses are set in sessions; the platform board renders them read-only.
+- **`external` is read-only to sessions** — the sync layer owns it. When a provider
+  closes a ticket, the item shows DUAL status (provider's + ours); `done` is never
+  imported (K6: done is earned, not synced).
+- **`active.md` → `activePlanId`.** First line `# <plan-id>` must resolve to a
+  `kind: epic`; `# No active plan` / missing file → null.
+
+**Decisions — first-class deliberation records (channel-borne, never frontmatter):**
+the frontmatter grammar is flat and bodies are never parsed, so structured decisions
+live on the PLATFORM, pushed via `log_decision` at checkpoint moments:
+`{ item, at, actor, context, options[], decision, rationale }` — *actor* is who
+decided (the dev for steering; the agent for proposals it made under standing
+consent). Text fidelity: **paraphrase + short verbatim quotes only where the exact
+wording carries the decision** (transcripts never land in shared stores). Sessions
+mirror each record into the item body's `## Decisions` for human reading. On tracker
+sync, decisions flow OUT as prefixed comments (Jira/Linear comments, Asana stories);
+imported comments are never scraped into decisions.
+
+**Transport — the plans channel (plans never ride the brain manifest):**
+
+- **Authoring**: files above, compile-validated; `.rafa/plans/` is the working copy.
+- **Push on approval**: approval IS the trigger — `push_plan` sends the whole tree
+  (`items[]`, bodies included); `set_active_plan` points the pointer. Build cadence
+  re-pushes statuses + `## Log` (`push_plan` / `update_plan_status`) and logs
+  decisions (`log_decision`).
+- **Pull-based work**: `list_plans` = NAMES ONLY; **"load plan X"** = `get_plan`
+  (bodies + decisions) materialized back into `.rafa/plans/` by the session.
+- **The brain link**: the epic's `domains:` rides the channel; the plan detail page
+  renders the related knowledge beside the tree.
+- **Tracker sync (phased)**: `external` identity now → import (a ticket is
+  purpose/what, NOT an executable plan — it still flows through plan drafting +
+  prism before build) → two-way sync under a field-ownership matrix (provider owns
+  ticket-native fields; rafa owns execution fields; conflicts surface, never
+  auto-resolve).
 
 ---
 
@@ -435,7 +498,8 @@ state**, marked by `envelope.plane: "state"`:
 | `get_working_set` | branch working set | hydration (a session starts with its branch's working set), the branch view, distillation collect; `needs-adjudication` rows carry the incoming copy in `pending` |
 | `resolve_working_file` | branch working set | `distilled` / `refuted` (+ cited note) at merge-to-main distillation; `keep-current` for adjudication decisions; CAS on status — a racing distill fails loudly |
 | `fold_working_set` | branch working set | branch→parent-branch MECHANICAL fold (no LLM, no prism — rigor only at main): absent → re-keyed · identical → merged · divergent → `needs-adjudication` on the parent row |
-| `push_plan` / `list_plans` / `update_plan_status` / `set_active_plan` | **plans** — (repo) work objects | the dedicated push-on-approval channel (§7): approval pushes the whole plan (bodies stored); `list_plans` = names only; statuses push back from sessions; the active pointer is explicit, never inferred |
+| `push_plan` / `list_plans` / `update_plan_status` / `set_active_plan` / `log_decision` | **plans** — (repo) work objects | the push-on-approval channel (§7 v2): approval pushes the whole work-item TREE (items[], bodies stored); `list_plans` = names only; statuses push back (5-value enum — blocked is derived); `log_decision` records the deliberation trail (paraphrase + pivotal quotes); the active pointer is explicit, never inferred |
+| `report_improvement_status` | **events only** — no store | a LIVE session signal (bloom's fixed-in-passing during build). The improvement ledger row is untouched — it has ONE writer, the ingest (K1); the platform overlays the report as pending-reconciliation until the next brain push confirms it |
 
 State tools work with or without an ingested brain (a working set can exist —
 and a plan can be pushed — before the first scan) and are exempt from the

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

package/blueprint/.claude/rafa/hooks/session-start.mjs

@@ -0,0 +1,229 @@
+#!/usr/bin/env node
+// rafa hook · SessionStart (startup|resume|clear) — the state digest.
+//
+// M5 capture engine, sensor #2: the session starts KNOWING instead of assuming —
+// staleness (dirty code files → the brain notes citing them, via the local manifest
+// or the platform's get_code_context), pending checkpoint conflicts (*.theirs.md),
+// and the active plan. State, never activity (no-gossip principle: nothing here
+// narrates what other devs did — only what THIS working copy's brain plane looks like).
+//
+// Everything printed to stdout lands in Claude's context. Silence = nothing to
+// report (the honest digest). Budget: local reads + ONE optional platform call
+// (get_code_context batch, ≤ 2s, fail-soft to local counts). Never blocks a
+// session: every path exits 0. Honors RAFA_HOOKS_DISABLED=1.
+
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+const DIRTY_FILES_ALARM = 15; // ≥ → recommend /rafa scan --brain-only (the fire-alarm rung)
+const CITED_NOTES_ALARM = 10;
+const MCP_BUDGET_MS = 2000;
+const MCP_MAX_FILES = 6;
+
+function readJson(file) {
+  try {
+    return JSON.parse(readFileSync(file, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function dirtyEntries(rafaDir) {
+  const f = join(rafaDir, "dirty.jsonl");
+  if (!existsSync(f)) return [];
+  const files = new Map(); // path → latest touch
+  for (const line of readFileSync(f, "utf8").split("\n")) {
+    if (!line.trim()) continue;
+    try {
+      const e = JSON.parse(line);
+      if (e && typeof e.f === "string") files.set(e.f, e.t ?? "");
+    } catch {
+      /* a torn line never breaks the digest */
+    }
+  }
+  return [...files.keys()];
+}
+
+// file → citing note ids, from the LOCAL manifest (a full pull / prior compile).
+function citersFromManifest(rafaDir, files) {
+  const m = readJson(join(rafaDir, "manifest.json"));
+  if (!m || !Array.isArray(m.notes)) return null;
+  const want = new Set(files);
+  const byNote = new Map();
+  for (const group of [m.notes, Array.isArray(m.improvements) ? m.improvements : []]) {
+    for (const n of group) {
+      const hits = (n.cites ?? []).filter((c) => want.has(c.file)).map((c) => c.file);
+      if (hits.length) byNote.set(n.id, [...new Set(hits)]);
+    }
+  }
+  return byNote;
+}
+
+// Fallback: the platform's inverted cite graph (get_code_context), fail-soft.
+async function citersFromPlatform(root, files) {
+  const stamp = readJson(join(root, "rafa.json"));
+  const repoId = stamp?.repoId;
+  if (!repoId) return null;
+  let key = process.env.RAFA_MCP_KEY || null;
+  let url = null;
+  const local = readJson(join(root, ".claude", "settings.local.json"));
+  if (!key && local?.env?.RAFA_MCP_KEY) key = local.env.RAFA_MCP_KEY;
+  const creds = readJson(join(homedir(), ".config", "rafinery", "credentials.json"));
+  const entry = creds?.repos?.[repoId];
+  if (!key && entry?.key) key = entry.key;
+  if (entry?.mcpUrl) url = entry.mcpUrl;
+  if (!key || !url || typeof fetch !== "function") return null;
+
+  const byNote = new Map();
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), MCP_BUDGET_MS);
+  try {
+    await Promise.all(
+      files.slice(0, MCP_MAX_FILES).map(async (path, i) => {
+        const res = await fetch(url, {
+          method: "POST",
+          signal: ctrl.signal,
+          headers: { "content-type": "application/json", authorization: `Bearer ${key}` },
+          body: JSON.stringify({
+            jsonrpc: "2.0",
+            id: i + 1,
+            method: "tools/call",
+            params: { name: "get_code_context", arguments: { path } },
+          }),
+        });
+        if (!res.ok) return;
+        const rpc = await res.json();
+        const text = rpc?.result?.content?.[0]?.text;
+        const env = typeof text === "string" ? JSON.parse(text) : text;
+        for (const ref of [...(env?.notes ?? []), ...(env?.improvements ?? [])]) {
+          const id = ref?.id;
+          if (!id) continue;
+          if (!byNote.has(id)) byNote.set(id, []);
+          byNote.get(id).push(path);
+        }
+      }),
+    );
+  } catch {
+    return null; // offline / slow / shape drift → local counts still serve
+  } finally {
+    clearTimeout(timer);
+  }
+  return byNote.size ? byNote : null;
+}
+
+// Unprocessed corrections (the reflex queue) — monotonic; an abandoned session
+// loses nothing because the next session starts by seeing these.
+function pendingCorrections(rafaDir) {
+  const f = join(rafaDir, "reflex.jsonl");
+  if (!existsSync(f)) return [];
+  const out = [];
+  for (const line of readFileSync(f, "utf8").split("\n")) {
+    if (!line.trim()) continue;
+    try {
+      const e = JSON.parse(line);
+      if (e && e.id && !e.done) out.push(e);
+    } catch {
+      /* torn line never breaks the digest */
+    }
+  }
+  return out;
+}
+
+function conflictCopies(rafaDir) {
+  const out = [];
+  const walk = (dir, depth) => {
+    if (depth > 4 || !existsSync(dir)) return;
+    for (const e of readdirSync(dir)) {
+      if (e === ".git") continue;
+      const p = join(dir, e);
+      try {
+        if (statSync(p).isDirectory()) walk(p, depth + 1);
+        else if (e.endsWith(".theirs.md")) out.push(p.slice(rafaDir.length + 1));
+      } catch {
+        /* races are fine */
+      }
+    }
+  };
+  walk(rafaDir, 0);
+  return out;
+}
+
+try {
+  if (process.env.RAFA_HOOKS_DISABLED === "1") process.exit(0);
+  const root = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+  if (!existsSync(join(root, "rafa.json"))) process.exit(0);
+  const rafaDir = join(root, ".rafa");
+
+  const lines = [];
+
+  const dirty = dirtyEntries(rafaDir);
+  if (dirty.length) {
+    let byNote = citersFromManifest(rafaDir, dirty);
+    if (byNote === null || byNote.size === 0) byNote = (await citersFromPlatform(root, dirty)) ?? byNote;
+    const noteIds = byNote ? [...byNote.keys()] : [];
+    const shown = noteIds.slice(0, 8).join(", ") + (noteIds.length > 8 ? ` (+${noteIds.length - 8} more)` : "");
+    lines.push(
+      `[rafa · staleness] ${dirty.length} code file(s) edited since the last brain reconcile` +
+        (noteIds.length
+          ? ` → ${noteIds.length} brain note(s) cite them: ${shown}.`
+          : byNote === null
+            ? " (citing notes unresolved here — run `rafa dirty` for the mapping)."
+            : " — no brain note cites them (nothing to refresh)."),
+    );
+    if (noteIds.length || byNote === null)
+      lines.push(
+        dirty.length >= DIRTY_FILES_ALARM || noteIds.length >= CITED_NOTES_ALARM
+          ? `[rafa · staleness] drift is past the threshold (${dirty.length} files / ${noteIds.length} notes) — recommend a brain refresh from main (\`/rafa scan --brain-only\`) at the next natural boundary.`
+          : `[rafa · staleness] at the next natural boundary, OFFER a scoped refresh of just the citing notes (atlas re-derives them, gates run as usual, then checkpoint). After the refresh: \`rafa dirty --consume\`.`,
+      );
+  }
+
+  const corrections = pendingCorrections(rafaDir);
+  if (corrections.length)
+    lines.push(
+      `[rafa · reflex] ${corrections.length} unprocessed correction(s) from earlier sessions: ` +
+        corrections
+          .slice(0, 3)
+          .map((c) => `${c.id} ("${c.p.slice(0, 60)}${c.p.length > 60 ? "…" : ""}")`)
+          .join(" · ") +
+        (corrections.length > 3 ? " …" : "") +
+        ` — fold into the bootstrap digest: bank the durable ones through the gates (see \`rafa reflex\`), consume each with its verdict.`,
+    );
+
+  const conflicts = conflictCopies(rafaDir);
+  if (conflicts.length)
+    lines.push(
+      `[rafa · conflicts] ${conflicts.length} checkpoint conflict cop${conflicts.length === 1 ? "y" : "ies"} await a decision (never auto-resolved): ${conflicts.slice(0, 5).join(", ")}${conflicts.length > 5 ? " …" : ""} — read each .theirs.md, merge/adopt/keep, re-run \`rafa checkpoint\`.`,
+    );
+
+  let activePlanId = null;
+  const activePath = join(rafaDir, "active.md");
+  if (existsSync(activePath)) {
+    const first = readFileSync(activePath, "utf8").split("\n")[0].trim();
+    if (first.startsWith("#") && first !== "# No active plan") {
+      activePlanId = first.replace(/^#\s*/, "");
+      lines.push(`[rafa · plan] active: ${activePlanId} (materialized under .rafa/plans/).`);
+    }
+  }
+
+  // Suggested next — ONE deterministic recommendation, ranked by consequence:
+  // a teammate blocked by a conflict > an unbanked correction > resuming the
+  // active plan > staleness repair. Guidance is front-loaded here (and ambient
+  // in the statusline) — never interleaved mid-flow (offer etiquette).
+  {
+    let next = null;
+    if (conflicts.length)
+      next = `resolve the checkpoint conflict${conflicts.length > 1 ? "s" : ""} (${conflicts.length} .theirs.md) — a teammate's copy is waiting on your decision`;
+    else if (corrections.length)
+      next = `work the ${corrections.length} unprocessed correction${corrections.length > 1 ? "s" : ""} (bank the durable ones — \`rafa reflex\`)`;
+    else if (activePlanId) next = `resume plan ${activePlanId}`;
+    else if (dirty.length) next = `refresh the notes your edits staled (offer the scoped refresh)`;
+    if (next) lines.push(`[rafa · next] suggested next: ${next}. Fold into the bootstrap digest — one question, never serial.`);
+  }
+
+  if (lines.length) process.stdout.write(lines.join("\n") + "\n");
+} catch {
+  /* the digest is a courtesy — never a crash */
+}
+process.exit(0);