@rafinery/cli 0.2.2 → 0.4.0

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

@@ -0,0 +1,482 @@
+# rafa brain contract — v1
+
+The strict protocol every brain file obeys, and the `manifest.json` the platform
+ingests. This is the **single source of truth** shared by the writers (atlas, bloom,
+prism) and the reader (the platform ingest). If a file violates this, the compile
+step **fails loudly** and the authoring agent must correct it — the platform never
+guesses, never assumes a value.
+
+**Canonical home: `.claude/rafa/contract.md` in the CODE repo** (blueprint split,
+0.4.0) — the contract versions with the CLI that implements it (`rafa compile` ships
+inside `@rafinery/cli`, never vendored). A **stamped copy** rides every brain push as
+`contract.md` in the brain repo, so any reader of the brain repo knows which contract
+version that brain conforms to.
+
+Pipeline:
+
+```
+agents write .md (frontmatter per this contract)
+  → rafa compile   (deterministic: parse frontmatter, VALIDATE, fail loudly)
+       ├ FAIL → structured error (file · field · rule) → author agent fixes → retry
+       └ PASS → emit manifest.json
+  → git push → webhook → INGEST = JSON.parse(manifest) + shape-check → Convex
+  → query APIs (per repo+branch) → platform renders
+```
+
+Two enforcement points: **compile-time** (structure — this contract) and **prism**
+(semantics — truth of the content). Structure is validated *before* semantics.
+
+---
+
+## File-type registry — every `.rafa` file has a declared class
+
+No consumer ever guesses. **Every** file type is classified here; a `structured` type has
+a schema (parse it), a `verbatim` type is prose (display it, never parse for data), a
+`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 |
+
+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
+any other contract violation, but they are never emitted into `manifest.json` — the
+platform doesn't ingest agents (yet); the gate exists so the agents themselves are
+never un-schema'd. The SOPs the cards point at are committed skills in the code repo
+(`.claude/skills/rafa-*/SKILL.md`); the gate tools are `@rafinery/cli` commands —
+neither lives under `.rafa/`, which holds purely knowledge + state.
+
+`structured` types are compiled into `manifest.json` (§1) — that JSON is the ONLY thing the
+platform ingests. `verbatim`/`generated` files are shown as-is in the file browser (fetched
+lazily), never parsed. A file under a `structured` path that isn't in this table → compile
+error (no rogue unschema'd data files).
+
+---
+
+## 0. Global rules
+
+- **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).
+- **`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`).
+  Renames are safe because rows are keyed by `id`, not path.
+- **Required fields are required.** Missing/empty required field = compile failure.
+  The validator **never fills a default for a required field** — that would be
+  assuming. Optional fields have documented defaults.
+- **Enums are closed.** A value outside the enum = compile failure (not coerced).
+
+### Frontmatter grammar (strict subset — the only shapes allowed)
+
+Frontmatter is a leading `---` … `---` block. Within it, only these forms are legal;
+anything else is a compile error:
+
+```yaml
+key: scalar                       # string | number | true | false
+key: "quoted string"              # quotes stripped
+key: [a, b, c]                    # flow list of scalars
+key: { a: x, b: y }               # flow map of scalars
+key:                              # block list …
+  - item
+  - item
+key: >-                           # folded scalar: continuation lines joined with one space
+  first part
+  second part
+```
+
+No nested block maps, no anchors, no literal (`|`) blocks. The folded scalar (`>-`/`>`)
+is the ONLY multiline form, added for agent cards (§10) whose descriptions fold.
+Deterministic to parse: indented non-empty lines after `>-` join with a single space.
+
+### cites DSL
+
+Each cite is one string: `` `<path>:<line> :: <token>` ``
+
+- split on the **first** ` :: ` → (`left`, `token`)
+- in `left`, split on the **last** `:` → (`path`, `line`)
+- `line` is digits (`"42"`) or a range (`"14-18"`)
+
+Compile parses each into `{ file, line, token }`. A cite that doesn't match → error.
+
+---
+
+## 1. manifest.json — the ingestion contract
+
+Machine-generated by `rafa compile`, committed to the brain repo, read by ingest as
+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
+    "gates": { "fidelity": "pass", "coverage": "pass" },
+    "counts": { "blockers": 0, "majors": 0, "minors": 2 }
+  },
+
+  "ledger": {                               // from improve/ledger.md — or null
+    "open": 7,
+    "debtScore": 13,
+    "byPriority": { "P0": 0, "P1": 1, "P2": 3, "P3": 3 }
+  },
+
+  "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" }
+    ]
+  },
+
+  "notes": [
+    {
+      "id": "agent-name-contract",
+      "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)
+    }
+  ],
+
+  "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
+      "title": "…",
+      "summary": "…",
+      "fix": "…",
+      "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"
+    }
+  ]
+}
+```
+
+**The manifest carries KNOWLEDGE only.** Plans and the active pointer left it
+(0.4.0 — the plans channel, §7): they are pushed on approval via `push_plan` /
+`set_active_plan` and never ride the brain repo. Legacy manifests carrying
+`plans[]`/`activePlanId` are tolerated and IGNORED by ingest (never written).
+
+Ingest is `JSON.parse` + a shape-check against this schema. Any mismatch (missing
+key, wrong enum, wrong type, unknown `schemaVersion`) → a **surfaced ingest error**
+on the platform, never a guessed value.
+
+---
+
+## 2. Note files — `brain/rules/*.md`, `brain/playbooks/*.md`
+
+`kind` is derived from the directory (`rules/` → `rule`, `playbooks/` → `playbook`).
+
+```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
+  - src/lib/model-selector-provider.tsx:42 :: research_agent
+  - agents/python/main.py:20 :: research_agent
+---
+（prose body — rendered verbatim, never parsed）
+```
+
+---
+
+## 3. Improvement files — `improve/improvements/*.md`
+
+```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
+  - src/components/ModelSelector.tsx:25 :: google_genai
+found: 2026-07-02               # optional · ISO date
+---
+（prose body）
+```
+
+Note: `title`, `summary`, `fix` are now **required frontmatter** — previously scraped
+from prose. That scraping is gone; these are authored values.
+
+---
+
+## 4. Health file — `brain/checklist.md`
+
+```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
+---
+（prism report body）
+```
+
+---
+
+## 5. Ledger file — `improve/ledger.md`
+
+The debt figure is **authored in frontmatter** (bloom's number), not parsed from a
+table. `open`/`by_priority` are cross-checked against the improvement rows at ingest.
+Flat keys only — no nesting (compile maps `debt_score`→`debtScore`, `by_priority`→`byPriority`).
+
+```yaml
+---
+schemaVersion: 1
+open: 7
+debt_score: 13
+by_priority: { P0: 0, P1: 1, P2: 3, P3: 3 }
+---
+（human-readable trend/tables in the body）
+```
+
+---
+
+## 6. Coverage file — `brain/coverage.md`
+
+The scan's breadth report. `domains` is a **flow map** of `domain: status`, one entry per
+domain found (compile emits it as `[{ domain, status }]` in the manifest). Status enum:
+`mapped | thin | stubbed | empty`. The body holds the human per-criterion PASS/FAIL narrative.
+
+```yaml
+---
+schemaVersion: 1
+domains: { design-system: mapped, components: mapped, api: thin, external-integrations: empty }
+---
+（per-criterion PASS/FAIL narrative in the body）
+```
+
+---
+
+## 7. Plan files — `plans/**/*.md` (+ the plans channel)
+
+Each child owns exactly one file (so merges never conflict; parent progress is
+derived by counting).
+
+```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
+baseSha: abc123                  # optional · commit it was cut from
+---
+（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.）
+```
+
+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.
+
+---
+
+## 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.
+- **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
+  file and compile re-runs. Bounded retries; if it can't converge, a **hard failure**
+  blocks the push (better than a silently-wrong brain).
+- The validator **reports, never auto-fills** a required value.
+
+---
+
+## 9. The read side — knowledge MCP (platform-served)
+
+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.
+
+**Envelope — mandatory on every tool response:**
+
+```jsonc
+{
+  "source": "platform",
+  "brainForSha": "<snapshot codeSha>",   // the ingested manifest's codeSha — one source
+  "ingestedAt": "<ISO time of ingest>",
+  "schemaVersion": 1,
+  "synthesized": false                   // raw tools: always false
+}
+```
+
+**Error semantics (no assumed values, outward):** snapshot has an `ingestError` →
+every tool returns that error loudly, never partial data. Repo connected but never
+pushed (no snapshot) → `"no brain ingested — run rafa push"`. Invalid/mismatched key
+→ loud auth error, never a fallback. Empty search → empty result, never a stretched
+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" |
+
+`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,
+i.e. the default branch's instance).
+
+**Search = deterministic lexical retrieval; the server retrieves, the agent decides.**
+Fields searched per type — rule/playbook: `title, summary, domain, type` ·
+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`).
+
+**Auth:** per-repo machine keys, minted on the platform, sent as
+`Authorization: Bearer`. Keys are stored hashed platform-side and live client-side in
+`~/.config/rafinery/credentials.json` — never inside the code repo or this brain repo.
+
+**Client wiring (written by `rafa init`, secret-free where committed):** a key is
+minted at setup generation and delivered consume-once through the setup fetch;
+`.mcp.json` (committed) registers the `rafinery` server with
+`Authorization: Bearer ${RAFA_MCP_KEY}` env expansion; the raw key lands in
+`.claude/settings.local.json` `env` (gitignored) and `~/.config/rafinery/credentials.json`
+(0600). Teammates mint their own key on the platform (repo → Agent access).
+
+### §9 addendum — state-plane tools (three-store model, working-set architecture)
+
+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` | **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 |
+
+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
+snapshot/ingestError gates. `get_plan`/`get_active_plan` share this exemption
+(plans are work objects, not snapshot-derived knowledge). The retired
+bucket-note tools (`stage/list/resolve_bucket_note`, pre-0.4.0) are superseded
+by the working-set tools.
+
+## 10. Agent cards — `../.claude/agents/*.md` (local gate)
+
+The shipped agents are contract-governed artifacts: every card is validated by
+`rafa compile` (a malformed agent fails the gate) but never enters `manifest.json`.
+No assumed values — applied to the agents themselves.
+
+```yaml
+---
+name: prism                 # required · MUST equal filename stem
+version: 0.4.0              # required · semver (MAJOR.MINOR.PATCH)
+model: opus                 # required · non-empty (trailing # comment = the why)
+groundTruth: code-vs-claim  # required · code-at-sha | code-vs-claim | code-trend | sessions-over-time
+description: >-             # required · non-empty (folded scalar allowed, §0)
+  …
+tools: Read, Grep, …        # required · non-empty
+color: orange               # optional
+duties:                     # required · block list, ≥ 1 · each a duty DSL string
+  - <duty> :: <sop-path> :: <bar>
+---
+```
+
+**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
+  duty without a procedure is a claim, not a contract). Legacy `.rafa/`-relative
+  paths (pre-0.4.0 `capabilities/*.md`) still resolve during the migration window.
+- `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
+(cards ship to end users and stay clean of build-log clutter).
+
+---
+
+This contract is the thing to test against.

package/blueprint/.claude/skills/rafa-build/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: rafa-build
+description: "rafa SOP — execute the active plan task by task: atlas implements from recalled knowledge, prism gates done on each Done-check, bloom sweeps the ledger; progress + journals sync at checkpoints. Loaded on /rafa build."
+---
+
+# build — execute the plan, trio-choreographed, compounding  (capability #4)
+
+> Status: **active.** The work-time loop where recall + validation + improvement all
+> fire — the mission payoff. Depends on: plan (#3), brain (#1), ledger (#2).
+> Invoke via `/rafa build`.
+
+Execute the approved plan with all three agents in the loop, knowledge served by the
+platform MCP (one read path — the same surface any third-party agent uses).
+
+## The trio at build time
+
+| Role | Agent | Job per task |
+|---|---|---|
+| **Executor** | atlas | RECALL the task's brain slice via MCP (`search_knowledge` + `get_rule`/`get_playbook`; honor non-exemplars) → implement, convention-adherent |
+| **Validator** | prism | validate the execution against the child's `## Done-check` — strict, unbiased, against code + brain, never against atlas's claims. **`status: done` only on prism PASS**; FAIL → atlas corrects (validate-and-correct at work time). This gate is conductor-flow SOP — deterministic enforcement is the deferred capture-engine's job |
+| **Improver** | bloom | **push**: new improvement opportunities spotted during execution → new ledger files. **close**: improvements fixed in passing → `status: fixed`. **nudge**: top-leverage open item in the task's blast radius — opt-in, never blocking |
+
+## Procedure
+
+1. **Resume** — `get_active_plan` (platform) or local `active.md`; staleness check
+   (envelope `brainForSha` vs local stamp → prompt `rafa push` if behind). MCP
+   recall is automatic throughout — SOP-driven, never dev-invoked; a repo without
+   the `rafinery` MCP connected falls back to local `.rafa/` file reads.
+   **Session consent (asked ONCE, verbs ENUMERATED):** *"keep the platform
+   updated as I work? That means exactly: (1) plan status + Log pushes on
+   cadence, (2) checkpointing this branch's working set (edited/new brain
+   files) — announced per file as it happens, (3) nothing else."* Revocable
+   anytime ("stop pushing"). On "no": journal locally only, push at the end on
+   approval. Dev-level insights are NEVER under this consent — each is its own
+   offer.
+2. **Per task:** atlas recalls → implements → prism validates vs `## Done-check` →
+   bloom sweeps (push new / close fixed / nudge) → update the child file's `status`
+   **and append a dated entry to the child's `## Log`** — what was done, what was
+   decided, what surprised (body prose: displayed verbatim on the platform, never
+   parsed; the plan files at `.rafa/plans/<plan>/` ARE the local cache) → at the
+   task-done CHECKPOINT (under the session consent): `push_plan` /
+   `update_plan_status` (the plans channel — statuses + Log journals) +
+   `rafa checkpoint` (the branch working set), so the platform and every MCP
+   consumer reflect live progress. Checkpoint moments: task done · plan
+   approved · explicit ask · cadence · git push/pull — never session-end. A
+   checkpoint CONFLICT (a teammate's newer copy of the same file) is decided
+   IN THIS SESSION: read the `.theirs.md` copy, merge/adopt/keep, re-checkpoint.
+3. **Brain changes mid-build — WHERE you are decides WHERE it goes.**
+   - **On the default branch (main):** run a full `/rafa scan` (regenerate →
+     prism → compile → push); the brain re-stamps at the new sha, so
+     `brain = f(code@sha)` stays exact.
+   - **On any other branch:** the org brain is NEVER written from a branch —
+     it describes main, and a branch-state scan would poison it for everyone.
+     Invalidated/learned knowledge → the branch **working set**: hydrate the
+     affected note (`rafa hydrate <rule|playbook> <id>`) and edit it, or author
+     a new note file under `.rafa/brain/**` — `rafa checkpoint` syncs it. It
+     enters the org brain at merge-to-main, through distillation. This is the
+     knowledge-propagates-like-code rule, enforced.
+   The working-set files ARE the sanctioned branch authoring surface — what is
+   never allowed is editing main's brain around the scan/compile/push gates.
+4. **Verify** (prism-style) before declaring the plan done; final `push_plan` +
+   `set_active_plan` (clear) + `rafa checkpoint`. A plan that stops being worth
+   finishing closes honestly: `superseded` or `abandoned`, never fake-`done`.
+
+**Lite plans** (single-child, from plan-lite) run the same per-task loop — the
+Done-check gate never relaxes; only the ceremony around it shrinks (no bloom nudge,
+single checkpoint + plan push at the end).
+
+## Deferred / open
+- **The capture engine** — `Stop`/`PostToolUse` hooks making the gates + capture
+  automatic rather than conductor-driven SOP (deterministic-enforcement lesson).
+- **Incremental re-scan** — cite-graph invalidation (diff → invalidate notes citing
+  changed files → re-verify/regenerate only those). Needs: partial-brain cache-key
+  semantics + the seam-neighbor scope rule. Designed (see
+  .fable/sessions/2026-07-07-brain-versioning-and-incremental.md); first post-loop item.
+- Show-thinking + pivot protocol from the atlas character.

package/blueprint/.claude/skills/rafa-distill/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: rafa-distill
+description: "rafa SOP — merge-time reconciliation: validate a merged branch's WORKING SET against merged MAIN (prism), author survivors into the org brain through verify-citations + compile + push (atlas), refute loudly with citations; contested items flagged needs-adjudication, never guessed. Loaded on /rafa distill or the merge offer; CI runs the same SOP headlessly (rafa distill --headless)."
+---
+
+# distill — merge-time reconciliation of a branch working set into the org brain
+
+> Status: **active.** Two runners, ONE SOP: the org's CI (`rafa distill
+> --headless`, installed by `rafa ci-setup`, driven by the ORG'S OWN
+> `ANTHROPIC_API_KEY` — never stored on the platform) and the dev session
+> (offer-driven at bootstrap, or explicit `/rafa distill <branch>`) as the
+> fallback when CI isn't wired or failed. Depends on: brain (#1), the branch
+> working set (synced via `rafa checkpoint`).
+
+The rigor gradient this enforces (ratified 2026-07-10): **dev↔dev = CAS + a
+session prompt · branch↔branch = free mechanical fold (no LLM, no prism) ·
+branch→main = full distillation + gates.** Cost tracks consequence. Working-set
+files are candidate-grade — attributed, loose, never served as org truth. The
+merge to main is the one moment rigor fires: what survives validation against
+merged main enters the org brain through the normal gates; what doesn't is
+refuted loudly back to its author; what can't be decided is flagged
+`needs-adjudication` — NEVER guessed. Knowledge propagates exactly like the
+code it describes.
+
+## Trigger
+
+- **CI (normal path):** the reconcile workflow fires on the PR-merged EVENT
+  (squash/rebase-safe — ancestry is never consulted): merge to the default
+  branch → `rafa distill --headless <branch>` · branch→parent merge →
+  `rafa fold --from <branch> --to <parent>` (mechanical, no LLM).
+- **Offer (session fallback):** at bootstrap the conductor checks
+  `get_working_set` for active files on branches whose code reached main —
+  *"branch <x> merged with N working-set files — distill now?"* Part of the
+  ONE bootstrap digest. Boundary consent; accepted offer = invocation.
+- **Explicit:** `/rafa distill <branch>`.
+
+## Procedure (the trio, distillation roles)
+
+1. **Collect** — `get_working_set(repo, branch, status: active)`. Zero files →
+   nothing to do, say so, stop. Rows already `needs-adjudication` are a HUMAN's
+   to resolve — surface them in the digest, never fold them in silently.
+2. **Validate (prism, context-isolated)** — the target is **merged MAIN as of
+   NOW, never the fork point and never a stale checkout**: `git fetch origin`
+   first; judge every claim against the fetched trunk. Confirm every citation
+   resolves (the cited line contains its token — grep it yourself). A claim
+   that can't be confirmed with a `file:line` is REFUTED (cited reason).
+   Contested/low-confidence → `needs-adjudication`, never a guess. Files about
+   code the merge did NOT touch are judged on their own merits, same bar.
+3. **Author (atlas)** — for each survivor: write/update the org-brain file
+   (contract §2) with real cites into main; `anchor:` on contracts (hydrated
+   files lost it — re-declare); fold into an existing note when one covers the
+   topic (supersede, never duplicate).
+4. **Gate + ship** — `rafa verify-citations` AND `rafa compile` to exit 0 →
+   `rafa push`. Only now has anything entered the org brain. A failed gate
+   aborts EVERYTHING: nothing resolved, nothing pushed, working set intact.
+5. **Resolve** — `resolve_working_file(path, distilled)` for survivors —
+   CAS: only a live row resolves; a failure means ANOTHER runner already
+   distilled this branch — STOP and reconcile against what it shipped.
+   `resolve_working_file(path, refuted, note)` for failures — TELL the author
+   which files died and why (cited); refutation is feedback, not silence.
+   `resolve_working_file(path, needs-adjudication, note)` for the undecidable —
+   the next session's digest offers the decision.
+
+## Branch→branch merges (sub-feature → feature): FOLD, don't distill
+
+Distillation targets ONLY the default branch. When a sub-feature merges into
+its parent branch, the working set is **folded forward mechanically** —
+`rafa fold --from <branch> --to <parent>` (or the CI fold job): absent on the
+parent → re-keyed · identical content → merged silently · true same-file
+divergence → `needs-adjudication` on the parent row (incoming preserved,
+attributed). No LLM, no prism — the knowledge keeps riding with the code until
+the code reaches main.
+
+Sub-feature CONTEXT: a branch's working knowledge = org brain (via MCP) + its
+own working set + unmerged ANCESTOR branches' working sets (the conductor
+derives the ancestor chain from git and calls `get_working_set` per ancestor —
+the platform stores no lineage).
+
+## Rules
+
+- Validation target is main at distillation time, never the fork point.
+- An abandoned branch's working set is never distilled — it dies with the
+  branch (propagation mirrors code).
+- No file skips steps 2–4; there is no fast path into the org brain.
+- CI can detect and flag; only a dev session resolves a human's divergence.
+- Dev-level observations found among the files route to `put_dev_insight`
+  (the author's user brain), never to the org brain.