@rafinery/cli 0.5.0 → 0.7.0

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

@@ -24,7 +24,7 @@ agents write .md (frontmatter per this contract)
 ```
 
 Two enforcement points: **compile-time** (structure — this contract) and **prism**
-(semantics — truth of the content). Structure is validated *before* semantics.
+(semantics — truth of the content). Structure is validated _before_ semantics.
 
 ---
 
@@ -35,20 +35,23 @@ a schema (parse it), a `verbatim` type is prose (display it, never parse for dat
 `generated` type is machine-written by a named tool. If a file matching a `structured` path
 doesn't validate, compile fails.
 
-| Type | Path glob | Class | Schema | Author |
-|---|---|---|---|---|
-| rule | `brain/rules/*.md` | **structured** | §2 | atlas |
-| playbook | `brain/playbooks/*.md` | **structured** | §2 | atlas |
-| health | `brain/checklist.md` | **structured** | §4 | prism |
-| coverage | `brain/coverage.md` | **structured** | §6 | atlas |
-| improvement | `improve/improvements/*.md` | **structured** | §3 | bloom |
-| ledger | `improve/ledger.md` | **structured** | §5 | bloom |
-| 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 |
-| 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 |
-| agent | `.claude/agents/*.md` (code repo) | **structured** (local gate — NOT in manifest) | §10 | rafa |
+| Type                  | Path glob                         | Class                                                                                                                              | Schema                                                                                                                                                        | Author     |
+| --------------------- | --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| rule                  | `brain/rules/*.md`                | **structured**                                                                                                                     | §2                                                                                                                                                            | atlas      |
+| playbook              | `brain/playbooks/*.md`            | **structured**                                                                                                                     | §2                                                                                                                                                            | atlas      |
+| health                | `brain/checklist.md`              | **structured**                                                                                                                     | §4                                                                                                                                                            | prism      |
+| coverage              | `brain/coverage.md`               | **structured**                                                                                                                     | §6                                                                                                                                                            | atlas      |
+| improvement           | `improve/improvements/*.md`       | **structured**                                                                                                                     | §3                                                                                                                                                            | bloom      |
+| ledger                | `improve/ledger.md`               | **structured**                                                                                                                     | §5                                                                                                                                                            | bloom      |
+| 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
 in the code repo. Compile validates them (§10) so a malformed card fails the gate like
@@ -69,7 +72,7 @@ error (no rogue unschema'd data files).
 
 - **Frontmatter is the only machine-read surface.** The markdown **body is prose**
   and is NEVER parsed for data. Every value the platform shows comes from frontmatter
-  (via the compiled manifest), or from the body rendered *verbatim* (never scraped).
+  (via the compiled manifest), or from the body rendered _verbatim_ (never scraped).
 - **`schemaVersion` is required** on every file and in the manifest. Unknown version
   → ingest reports an error, does not guess.
 - **`id` is required and stable.** It MUST equal the filename stem (`foo.md` → `foo`).
@@ -105,7 +108,7 @@ Deterministic to parse: indented non-empty lines after `>-` join with a single s
 
 Each cite is one string: `` `<path>:<line> :: <token>` ``
 
-- split on the **first** ` :: ` → (`left`, `token`)
+- split on the **first** `::` → (`left`, `token`)
 - in `left`, split on the **last** `:` → (`path`, `line`)
 - `line` is digits (`"42"`) or a range (`"14-18"`)
 
@@ -121,61 +124,82 @@ JSON. This is the exact shape the platform binds to.
 ```jsonc
 {
   "schemaVersion": 1,
-  "generatedAt": "2026-07-03T10:00:00Z",   // ISO-8601, stamped by compile
-  "repo": "owner/repo",                     // CODE repo full_name (identity)
-  "branch": "main",                         // code branch this brain reflects
-  "codeSha": "abc123…",                     // code commit the brain was built for
-
-  "health": {                               // from brain/checklist.md — or null
-    "verdict": "PASS",                      // "PASS" | "ITERATE"
-    "score": 95,                            // 0–100
+  "generatedAt": "2026-07-03T10:00:00Z", // ISO-8601, stamped by compile
+  "repo": "owner/repo", // CODE repo full_name (identity)
+  "branch": "main", // code branch this brain reflects
+  "codeSha": "abc123…", // code commit the brain was built for
+
+  "health": {
+    // from brain/checklist.md — or null
+    "verdict": "PASS", // "PASS" | "ITERATE"
+    "score": 95, // 0–100
     "gates": { "fidelity": "pass", "coverage": "pass" },
-    "counts": { "blockers": 0, "majors": 0, "minors": 2 }
+    "counts": { "blockers": 0, "majors": 0, "minors": 2 },
   },
 
-  "ledger": {                               // from improve/ledger.md — or null
+  "ledger": {
+    // from improve/ledger.md — or null
     "open": 7,
     "debtScore": 13,
-    "byPriority": { "P0": 0, "P1": 1, "P2": 3, "P3": 3 }
+    "byPriority": { "P0": 0, "P1": 1, "P2": 3, "P3": 3 },
   },
 
-  "coverage": {                             // from brain/coverage.md — or null
-    "domains": [                            // one row per domain, its scan status
+  "coverage": {
+    // from brain/coverage.md — or null
+    "domains": [
+      // one row per domain, its scan status
       { "domain": "design-system", "status": "mapped" },
-      { "domain": "external-integrations", "status": "thin" }
-    ]
+      { "domain": "external-integrations", "status": "thin" },
+    ],
   },
 
+  "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",
-      "kind": "rule",                       // "rule" | "playbook" (from directory)
-      "type": "contract",                   // contract | convention | flow | how-to
+      "kind": "rule", // "rule" | "playbook" (from directory)
+      "type": "contract", // contract | convention | flow | how-to
       "domain": "web-agent-bridge",
       "title": "…",
       "summary": "…",
-      "links": ["other-note-id"],           // [] if none
-      "failure": "silent",                  // "silent" | "loud" | omitted
-      "cites": [{ "file": "src/x.tsx", "line": "42", "token": "research_agent" }],
-      "path": "brain/rules/agent-name-contract.md"  // prose body (lazy fetch)
-    }
+      "links": ["other-note-id"], // [] if none
+      "failure": "silent", // "silent" | "loud" | omitted
+      "bodyTokens": 180, // OPTIONAL · ceil(bodyChars/4) size estimate of the
+      //   prose body — deterministic (no LLM), for recall-savings
+      "cites": [
+        {
+          "file": "src/x.tsx",
+          "line": "42",
+          "token": "research_agent",
+          "targetTokens": 940,
+        },
+      ], // targetTokens OPTIONAL · ceil(fileChars/4) of the CITED
+      //   file — OMITTED when unreadable at compile (never 0)
+      "path": "brain/rules/agent-name-contract.md", // prose body (lazy fetch)
+    },
   ],
 
   "improvements": [
     {
       "id": "dead-model-options-google-crewai",
-      "priority": "P1",                     // P0 | P1 | P2 | P3
-      "lens": "product",                    // security|correctness|performance|architecture|product|ops
-      "status": "open",                     // open | backlog | fixed | wontfix
+      "priority": "P1", // P0 | P1 | P2 | P3
+      "lens": "product", // security|correctness|performance|architecture|product|ops
+      "status": "open", // open | backlog | fixed | wontfix
       "title": "…",
       "summary": "…",
       "fix": "…",
-      "leverage": { "impact": "high", "effort": "low" },   // impact/effort ∈ low|medium|high
-      "blastRadius": ["web-agent-bridge"],  // [] if none
+      "leverage": { "impact": "high", "effort": "low" }, // impact/effort ∈ low|medium|high
+      "blastRadius": ["web-agent-bridge"], // [] if none
       "cites": [{ "file": "…", "line": "25", "token": "…" }],
-      "path": "improve/improvements/dead-model-options-google-crewai.md"
-    }
-  ]
+      "path": "improve/improvements/dead-model-options-google-crewai.md",
+    },
+  ],
 }
 ```
 
@@ -188,6 +212,16 @@ Ingest is `JSON.parse` + a shape-check against this schema. Any mismatch (missin
 key, wrong enum, wrong type, unknown `schemaVersion`) → a **surfaced ingest error**
 on the platform, never a guessed value.
 
+**Size stamps (`bodyTokens`, `cites[].targetTokens`) are ADDITIVE OPTIONAL.** compile
+stamps each note's body-token estimate and, per cite, the cited file's token estimate —
+both `ceil(chars/4)`, computed deterministically at compile time (no LLM, no network) to
+feed the platform's recall-savings estimator. `targetTokens` is **omitted** for any cite
+whose target is unreadable at compile (honest absence — never a guessed `0`). Because
+these fields are purely additive and optional, `schemaVersion` **stays 1**: ingest never
+refuses a manifest for lacking them, so a legacy manifest produced without them (or with
+some cites carrying no `targetTokens`) remains valid. The shape-check treats them as
+optional and tolerates their absence.
+
 ---
 
 ## 2. Note files — `brain/rules/*.md`, `brain/playbooks/*.md`
@@ -197,20 +231,36 @@ on the platform, never a guessed value.
 ```yaml
 ---
 schemaVersion: 1
-id: agent-name-contract          # required · == filename stem
-type: contract                   # required · contract | convention | flow | how-to
-domain: web-agent-bridge         # required · non-empty
-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
-cites:                           # required · ≥ 1
+id: agent-name-contract # required · == filename stem
+type: contract # required · contract | convention | flow | how-to
+domain: web-agent-bridge # required · non-empty
+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
 ---
 （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`
@@ -218,18 +268,18 @@ cites:                           # required · ≥ 1
 ```yaml
 ---
 schemaVersion: 1
-id: dead-model-options-google-crewai   # required · == filename stem
-priority: P1                     # required · P0 | P1 | P2 | P3
-lens: product                    # required · security|correctness|performance|architecture|product|ops
-status: open                     # required · open | backlog | fixed | wontfix
-title: Two of the four model options are dead and fail silently   # required
-summary: google_genai and crewai route to unwired agents   # required
-fix: Wire both agents in main.py, or remove them from the picker   # required
-leverage: { impact: high, effort: low }   # required · impact/effort ∈ low|medium|high
-blast_radius: [web-agent-bridge, external-integrations]   # optional · default []
-cites:                           # required · ≥ 1
+id: dead-model-options-google-crewai # required · == filename stem
+priority: P1 # required · P0 | P1 | P2 | P3
+lens: product # required · security|correctness|performance|architecture|product|ops
+status: open # required · open | backlog | fixed | wontfix
+title: Two of the four model options are dead and fail silently # required
+summary: google_genai and crewai route to unwired agents # required
+fix: Wire both agents in main.py, or remove them from the picker # required
+leverage: { impact: high, effort: low } # required · impact/effort ∈ low|medium|high
+blast_radius: [web-agent-bridge, external-integrations] # optional · default []
+cites: # required · ≥ 1
   - src/components/ModelSelector.tsx:25 :: google_genai
-found: 2026-07-02               # optional · ISO date
+found: 2026-07-02 # optional · ISO date
 ---
 （prose body）
 ```
@@ -244,10 +294,10 @@ from prose. That scraping is gone; these are authored values.
 ```yaml
 ---
 schemaVersion: 1
-verdict: PASS                    # required · PASS | ITERATE
-score: 95                        # required · 0–100
-gates: { fidelity: pass, coverage: pass }   # required · each pass | fail
-counts: { blockers: 0, majors: 0, minors: 2 }   # required · non-negative ints
+verdict: PASS # required · PASS | ITERATE
+score: 95 # required · 0–100
+gates: { fidelity: pass, coverage: pass } # required · each pass | fail
+counts: { blockers: 0, majors: 0, minors: 2 } # required · non-negative ints
 ---
 （prism report body）
 ```
@@ -282,10 +332,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**
@@ -300,24 +359,25 @@ Each item owns exactly one file (merges never conflict; progress is derived).
 ```yaml
 ---
 schemaVersion: 1
-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
+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
+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 — a LEAF item (a task with no subtasks, or a subtask) MUST carry a
 `## Done-check`; `## Log` is the execution journal; `## Decisions` mirrors the
@@ -352,7 +412,7 @@ Rules (all compile-enforced unless noted):
 **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
+`{ 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
@@ -382,7 +442,10 @@ imported comments are never scraped into decisions.
 ## 8. Versioning & the validate-and-correct loop
 
 - **`schemaVersion`** bumps when this contract changes incompatibly. Ingest refuses
-  an unknown version (surfaced error) rather than mis-reading it.
+  an unknown version (surfaced error) rather than mis-reading it. **Additive OPTIONAL
+  fields do NOT bump it** — e.g. the note size stamps (`bodyTokens`,
+  `cites[].targetTokens`, §1): ingest tolerates their absence, so a legacy manifest
+  without them stays valid at the same `schemaVersion`.
 - **Validate-and-correct:** `rafa compile` validates every file. On failure it emits
   a structured error — `path · field · rule` — to the **authoring agent** (atlas for
   notes, bloom for improvements/ledger, prism for checklist). The agent edits the
@@ -396,18 +459,18 @@ imported comments are never scraped into decisions.
 
 The platform serves the **ingested** brain to any MCP client (the build agent, a
 teammate's session, Slack/incident.io agents) — the read-side twin of this contract.
-One backend: the platform. Local files are the *authoring* surface; the platform is
-the *serving* surface, and it serves only what passed compile + ingest.
+One backend: the platform. Local files are the _authoring_ surface; the platform is
+the _serving_ surface, and it serves only what passed compile + ingest.
 
 **Envelope — mandatory on every tool response:**
 
 ```jsonc
 {
   "source": "platform",
-  "brainForSha": "<snapshot codeSha>",   // the ingested manifest's codeSha — one source
+  "brainForSha": "<snapshot codeSha>", // the ingested manifest's codeSha — one source
   "ingestedAt": "<ISO time of ingest>",
   "schemaVersion": 1,
-  "synthesized": false                   // raw tools: always false
+  "synthesized": false, // raw tools: always false
 }
 ```
 
@@ -419,15 +482,16 @@ match.
 
 **Tools (read-only — ALL writes flow files → compile → push → ingest):**
 
-| Tool | Args | Returns |
-|---|---|---|
-| `get_brain_status` | `repo` | envelope + per-type counts, health, coverage summary, `activePlanId`, `ingestError?` |
-| `get_coverage` | `repo` | coverage rows (the domain map — how an agent navigates) |
-| `search_knowledge` | `q`, `types?`, `domain?`, `limit?` | ranked candidates (fields per type below) |
-| `get_rule` / `get_playbook` / `get_improvement` | `repo`, `id` | full frontmatter + lazy-fetched body + cites as objects |
-| `list_improvements` | `repo`, `status?`, `priority?`, `domain?` | ledger rows |
-| `get_plan` | `repo`, `id` (parent or child) | parent + all children **with stored bodies** + **derived** progress; a child id resolves the whole plan with `requestedChild` set — this is what "load plan X" materializes into `.rafa/plans/` |
-| `get_active_plan` | `repo` | resolves the channel pointer (`set_active_plan`) → `get_plan`, or "no active plan" |
+| Tool                                            | Args                                      | Returns                                                                                                                                                                                         |
+| ----------------------------------------------- | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `get_brain_status`                              | `repo`                                    | envelope + per-type counts, health, coverage summary, `activePlanId`, `ingestError?`                                                                                                            |
+| `get_coverage`                                  | `repo`                                    | coverage rows (the domain map — how an agent navigates)                                                                                                                                         |
+| `search_knowledge`                              | `q`, `types?`, `domain?`, `limit?`        | ranked candidates (fields per type below)                                                                                                                                                       |
+| `ask_knowledge`                                 | `repo`, `q`                               | the guarded synthesis read (below) — `{answer, synthesized, citations[], retrieval, usage?}`                                                                                                    |
+| `get_rule` / `get_playbook` / `get_improvement` | `repo`, `id`                              | full frontmatter + lazy-fetched body + cites as objects                                                                                                                                         |
+| `list_improvements`                             | `repo`, `status?`, `priority?`, `domain?` | ledger rows                                                                                                                                                                                     |
+| `get_plan`                                      | `repo`, `id` (parent or child)            | parent + all children **with stored bodies** + **derived** progress; a child id resolves the whole plan with `requestedChild` set — this is what "load plan X" materializes into `.rafa/plans/` |
+| `get_active_plan`                               | `repo`                                    | resolves the channel pointer (`set_active_plan`) → `get_plan`, or "no active plan"                                                                                                              |
 
 `repo` must match the key's scope exactly; `branch` is reserved (branch-keyed
 instances land in Slice 2 — third-party clients default to the production brain,
@@ -439,8 +503,32 @@ improvement: `title, summary, lens, blast_radius` · plan: `title, plan, parent`
 Score = Σ over matched case-folded query tokens of field weight (`title` 3 ·
 `domain`/`lens`/`blast_radius`/`type`/`plan`/`parent` 2 · `summary` 1); tie-break
 score desc then id asc; fields a type lacks are omitted, never defaulted. Candidates
-carry `matchKind: "lexical"` (`"semantic"` reserved). `ask_knowledge` is a reserved
-tool id for the synthesis layer (responses will carry `synthesized: true`).
+carry `matchKind: "lexical"` (`"semantic"` reserved).
+
+**`ask_knowledge` — the guarded synthesis read (the reserved id, filled 2026-07-13
+per the served-brain spec).** For THIN clients (Slack bots, dashboards); full agents
+should prefer `search_knowledge` + `get_*` and compose with their own model. The
+guarantees, in order: 0. **Enumerable intents route deterministically BEFORE retrieval** — command-shaped
+asks ("list improvements [open|P0]", "list plans", "status/health", "coverage")
+return the actual rows (`retrieval.matchKind: "intent"`, `items[]`), no LLM
+involved. Interrogatives (how/why/where/when) always retrieve instead — a missed
+intent degrades to search; a wrong intent would answer the wrong thing.
+
+1. **Retrieval first, deterministic** — the same lexical scorer, top-K candidates.
+2. **Empty = honest empty**: `{answer: null, synthesized: false, found: 0}` with a
+   "no knowledge found" message — never composed from general knowledge; the empty
+   ask is logged into the same knowledge-gaps feed as an empty search
+   (`payload.via: "ask"`).
+3. **Composition uses retrieved cited notes ONLY**; answers are marked
+   `synthesized: true` and carry `citations[]` ({id, title, kind, domain?, path}).
+4. **Raw mode**: with no org synthesis key configured, returns `rawMode: true` +
+   the top cited candidates (no LLM call) — the surface degrades to search, never
+   to silence or invention.
+5. **Custody**: synthesis runs on the ORG'S OWN LLM key (a platform tokens row,
+   provider `anthropic`, encrypted at rest, decrypted per call server-side, never
+   logged). Usage is metered to `usageEvents` (purpose `ask`, runner `platform`).
+6. **Caps are loud**: a per-repo daily cap returns an explicit error, never a
+   silent throttle.
 
 **Auth:** per-repo machine keys, minted on the platform, sent as
 `Authorization: Bearer`. Keys are stored hashed platform-side and live client-side in
@@ -459,15 +547,15 @@ The knowledge plane stays strictly read-only (org-brain writes go ONLY through
 files → compile → push → ingest). Seven additional tools write **collaboration
 state**, marked by `envelope.plane: "state"`:
 
-| Tool | Store | Notes |
-|---|---|---|
-| `list_dev_insights` / `put_dev_insight` / `remove_dev_insight` | **user brain** — account-scoped, cross-repo, PRIVATE | consent-gated by the conductor; never logged to repo activity; nothing person-scoped is ever served to another user |
-| `checkpoint_sync` | **branch working set** — (repo, branch, file path) rows | pushes edited/new brain files from the lazy `.rafa/` instance at CHECKPOINTS (task done · plan approved · explicit ask · cadence · git push/pull — never session-end) under **base-version CAS**: each file carries the row `version` last seen (null = create); a stale base returns the newer copy as a per-file conflict for the HUMAN in that session to resolve |
-| `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` / `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 |
+| Tool                                                                                   | Store                                                   | Notes                                                                                                                                                                                                                                                                                                                                                                |
+| -------------------------------------------------------------------------------------- | ------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `list_dev_insights` / `put_dev_insight` / `remove_dev_insight`                         | **user brain** — account-scoped, cross-repo, PRIVATE    | consent-gated by the conductor; never logged to repo activity; nothing person-scoped is ever served to another user                                                                                                                                                                                                                                                  |
+| `checkpoint_sync`                                                                      | **branch working set** — (repo, branch, file path) rows | pushes edited/new brain files from the lazy `.rafa/` instance at CHECKPOINTS (task done · plan approved · explicit ask · cadence · git push/pull — never session-end) under **base-version CAS**: each file carries the row `version` last seen (null = create); a stale base returns the newer copy as a per-file conflict for the HUMAN in that session to resolve |
+| `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` / `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
@@ -497,7 +585,8 @@ duties:                     # required · block list, ≥ 1 · each a duty DSL s
 ---
 ```
 
-**Duty DSL** (one string per duty, split on ` :: `, exactly three parts):
+**Duty DSL** (one string per duty, split on `::`, exactly three parts):
+
 - `duty` — kebab-case name of the responsibility.
 - `sop-path` — path relative to the CODE repo root (e.g.
   `.claude/skills/rafa-validate/SKILL.md`); the file MUST exist at compile time (a
@@ -506,7 +595,7 @@ duties:                     # required · block list, ≥ 1 · each a duty DSL s
 - `bar` — the explicit pass/fail sentence for this duty. Never empty: a duty whose
   bar can't be stated can't be validated, so it doesn't ship.
 
-Versioning: bump `version:` with any card change; record the *why* outside the card
+Versioning: bump `version:` with any card change; record the _why_ outside the card
 (cards ship to end users and stay clean of build-log clutter).
 
 ---

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