@rafinery/cli 0.4.1 → 0.5.0

package/CHANGELOG.md

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

package/blueprint/.claude/agents/atlas.md

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

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

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

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

@@ -1,5 +1,5 @@
 ---
-version: 1.3.0
+version: 1.5.0
 description: rafa — the repo's engineering SOP. Use whenever the dev wants to plan a feature or change, build/execute against the active plan, improve code health, or ground work in the repo's brain — intent counts, the dev does NOT need to type /rafa. Also explicit: /rafa <init|scan|improve|plan|build|push|leverage|migrate|update|help> [--brain-only]. Admin verbs (init/scan/push/migrate/update) run ONLY when explicitly invoked.
 ---
 
@@ -28,6 +28,20 @@ unless explicitly asked (serve knowledge, not gossip). Misroutes the dev correct
 signal — prefer under-routing (answer plainly) over dragging a question through
 choreography.
 
+**Zero-command principle (owner rule, 2026-07-12):** every rafa command — CLI verbs,
+MCP tools, checkpoints, pushes, decisions logging — is AGENT-INTERNAL machinery. The
+dev speaks intent; YOU run the machinery. Never instruct the dev to run a command you
+can run yourself. The only human acts: init (provision) · `npx rafa pull` (once per
+clone) · ci-setup approval · npm publish. **Toolbox is a recall surface:** at
+bootstrap, load the committed toolbox (`.claude/skills/`, `.mcp.json`, commands)
+alongside brain status; pass the matching slice into every atlas/bloom spawn prompt —
+agents USE the fit capability automatically instead of hand-rolling (only what's
+installed, never guessed; personal `~/.claude/` stays live-recommend-only).
+**Actor envelope:** stamp `actorMeta {model, agent, runner: "session"}` on every
+state-plane write (checkpoints, plan pushes, decisions, reports) and export
+`RAFA_ACTOR_MODEL` before CLI calls — the platform records WHO/WHAT executed;
+"unreported" when unknown, never guessed.
+
 **Scope discipline (owner rule):** deliver exactly what the message asked — fix what
 they're expecting, nothing else. No unsolicited extras beyond bloom's single opt-in
 nudge. Fix-shaped prompts: recall the failure domain's knowledge → fix the asked
@@ -49,6 +63,10 @@ Three interaction modes by the weight of the action:
    - session start, local ahead of platform → *"brain is N commits behind — push?"*
    - reconciliation pending → *"branch <x> merged with N working-set files — distill now?"*
    - adjudication pending → *"1 file diverged at the <x>→<y> fold — pick a copy?"*
+   - user brain EMPTY (first session / founding scan just completed) → *"want me to
+     bootstrap your insights from your usage report? (compass distills it; every
+     candidate is offered — nothing banked without your yes)"* — accepted = run
+     `## insights`. Offered ONCE; a "no" is a standing no until the dev asks.
 
 Offer etiquette (hard rules): boundaries only, never mid-flow · once per moment — a
 "no" is remembered for the session and never re-argued · an unanswered offer never
@@ -105,6 +123,11 @@ improve + push — a cheap knowledge refresh).
    explicit approval**, push the brain: `npx @rafinery/cli push` — commits `.rafa/` and
    pushes to the brain remote using the dev's own git auth, stamped `brain-for: <code sha>`.
    Never push without approval.
+8. **The coach offer (founding scan only)** — if this was the repo's FIRST scan and the
+   dev's user brain is empty (`list_dev_insights` → none), offer ONCE: *"the code side
+   is mapped — want me to bootstrap YOUR insights from your usage report?"* Accepted =
+   run `## insights` (compass; every candidate offered, banked only on yes). This is
+   the offer rung of the consent ladder — never auto-run, never re-asked after a no.
 
 atlas scans + fixes; prism judges; bloom improves; you orchestrate + push on approval. You own
 `log.md`; never edit `checklist.md` or the brain yourself — spawn atlas for that.
@@ -146,12 +169,15 @@ atlas drafts, bloom pulls, prism validates the plan itself:
 Per [the rafa-build skill](../skills/rafa-build/SKILL.md). Resume from `active.md`
 (or the platform's `get_active_plan` when connected — "load plan X" materializes it) —
 never re-derive context.
-Per task: **atlas** recalls + implements → **prism** validates against the child's
-`## Done-check` (**`status: done` only on prism PASS**; FAIL → atlas corrects) → **bloom**
-sweeps (new opportunities → ledger files; fixed-in-passing → `status: fixed`; one opt-in
-nudge max) → update the child file's `status` + `## Log` → at CHECKPOINTS (task done ·
-cadence under session consent): `push_plan`/`update_plan_status` (plans channel) +
-`rafa checkpoint` (working set) so the platform reflects live progress. Terminal
+Per item (work the tree in `blocked_by` order — an item with an unmet dependency is
+DERIVED-blocked and waits): **atlas** recalls + implements → **prism** validates against
+the item's `## Done-check` (**`status: done` only on prism PASS**; FAIL → atlas corrects)
+→ **bloom** sweeps (new opportunities → ledger files; fixed-in-passing → `status: fixed`;
+one opt-in nudge max) → update the item file's `status` + `## Log` + `## Decisions` →
+at CHECKPOINTS (task done · cadence under session consent):
+`push_plan`/`update_plan_status`/`log_decision` (plans channel — decisions record what
+the DEV chose and why; paraphrase + pivotal quotes) + `rafa checkpoint` (working set)
+so the platform reflects live progress. Terminal
 statuses when honest: `superseded` (replaced by a newer plan) · `abandoned` (dropped).
 If execution invalidates/creates brain knowledge, route per §capture (working set on a
 branch; full `## scan` on main — never hand-edit main's brain around the gate). When all

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

@@ -288,63 +288,94 @@ domains: { design-system: mapped, components: mapped, api: thin, external-integr
 
 ---
 
-## 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 +466,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/skills/rafa-build/SKILL.md

@@ -18,7 +18,7 @@ platform MCP (one read path — the same surface any third-party agent uses).
 |---|---|---|
 | **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 |
+| **Improver** | bloom | **push**: new improvement opportunities spotted during execution → new ledger files. **close**: improvements fixed in passing → `status: fixed` in the ledger file + `report_improvement_status(id, fixed)` so the platform shows it LIVE as pending-reconciliation (the ledger row itself changes only at the next brain push — K1). **nudge**: top-leverage open item in the task's blast radius — opt-in, never blocking |
 
 ## Procedure
 
@@ -40,6 +40,11 @@ platform MCP (one read path — the same surface any third-party agent uses).
    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) +
+   **`log_decision` for each deliberation since the last checkpoint** — what
+   came up, what was considered, what the DEV chose, why (actor = the dev for
+   steering, the agent for its own proposals; PARAPHRASE + short verbatim
+   quotes only where the wording carries the decision — transcripts never land
+   in shared stores; mirror each into the item's `## Decisions` section) +
    `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

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

@@ -58,9 +58,20 @@ code-level → the branch working set (not yours — rafa.md §capture routes it
 existing insight (`put_dev_insight` with its id) rather than accreting near-
 copies.
 
+### 2b. Personal tooling (ratified 2026-07-12 — the user-plane toolbox)
+Under the dev's STANDING insights consent, inventory the tooling they carry
+across repos — `~/.claude/skills` + user-level MCPs — and bank each as a
+`kind: tooling` insight (NAME + DESCRIPTION only, never file contents). Update
+beats duplicate; tombstones honored. This is what lets rafa orchestrate a
+dev's personal migration skill in a repo that has never seen it. The REPO
+toolbox is atlas's plane (scan's toolbox domain), never yours.
+
 ### 3. Steering (the payoff — propose, the dev disposes)
-At natural boundaries only, at most one nudge: surface the insight that changes
-what the dev does next — "you've corrected X three times: want it banked as a
+At natural boundaries only, at most one nudge — and ALWAYS have a candidate
+ready (leverage-coaching: cross the repo's toolbox inventory with the dev's
+patterns + tooling insights — "you've hand-run this migration three times; the
+repo ships a skill for it"). Availability is always; frequency never rises.
+Surface the insight that changes what the dev does next — "you've corrected X three times: want it banked as a
 rule?" · "this decomposition worked before, reuse it?" · "you never use plan
 mode on big changes; it would have caught this." Dismissal is final for the
 session. Never rank, never compare devs, never nag.

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

@@ -37,9 +37,17 @@ Planning is a choreography, not one agent (spec: knowledge-mcp-build-agent):
 1. **Staleness check** — compare the platform envelope's `brainForSha` against the
    local brain stamp; if the platform is behind, surface "run `rafa push`" (never
    proceed silently on knowledge you know is stale — never block either).
-2. **Recall** (atlas, via MCP) → **decompose** ADR-style: decision + rationale +
-   alternatives + risk surface + non-goals; tasks bound to domains with a
-   `## Done-check` each.
+2. **Recall** (atlas, via MCP) → **decompose** into the WORK-ITEM TREE (contract
+   §7 v2): one epic → tasks → subtasks (three ranks, never deeper). Every item
+   carries the glimpse fields — `title` (what) · `description` (why) ·
+   `approach` (how, one line) · `assignee` when known · `blocked_by` for
+   intra-plan dependencies (a dependency IS a blocker; blocked is DERIVED,
+   never a status) · optional `priority` 0–4 / `estimate`. Every LEAF carries a
+   `## Done-check`. The blast radius goes on the EPIC's `domains:` — it rides
+   `push_plan` and the platform renders the plan's brain slice beside it.
+   ADR material (alternatives, risks, non-goals) lives in the epic body AND
+   the pivotal choices are logged as DECISIONS at approval (`log_decision`:
+   context · options · decision · rationale; actor = the dev for their calls).
 3. **Ledger pull** (bloom) → optional leverage tasks in the blast radius.
 4. **Leverage-match** — recommend existing skills/tools/MCP that fit the tasks;
    never plan to hand-roll what a capability already does.

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

@@ -138,6 +138,15 @@ retrieval index. Bodies read like a senior engineer explaining that one concept
    the internal node/relationship model the next steps reason over. (Not emitted as a
    file; it feeds the notes.)
 
+3b. **Toolbox inventory** [deterministic] — ratified 2026-07-12: the REPO toolbox is a
+   first-class brain domain (`toolbox`). Run `npx @rafinery/cli leverage --json` (the
+   deterministic extractor) and author cited notes for the committed toolbox — skills
+   (`.claude/skills/*/SKILL.md` name+description), commands, `.mcp.json` servers,
+   granted permissions — cites into the config files themselves (contract §2; they are
+   citable file:line). This makes the toolbox recallable through the SAME MCP surface
+   as all knowledge and refreshable like any note. Personal `~/.claude/` is NEVER
+   inventoried here (user-profile plane, compass's job, standing consent).
+
 4. **Convention detection** [deterministic + light LLM] — for **each** domain, the local
    idiom (design tokens, component export pattern + any server/client split such as RSC,
    data-op shape, naming).

package/lib/checkpoint.mjs

@@ -84,6 +84,13 @@ export default async function checkpoint() {
   try {
     payload = await callTool(ROOT, "checkpoint_sync", {
       branch,
+      // WHO/WHAT executed — the CLI knows itself; the MODEL is the session's to
+      // report (RAFA_ACTOR_MODEL env, set by the conductor) — never guessed.
+      actorMeta: {
+        agent: "rafa-cli@" + (process.env.npm_package_version ?? "0.5.0"),
+        runner: process.env.CI ? "ci" : "session",
+        model: process.env.RAFA_ACTOR_MODEL ?? "unreported",
+      },
       files: candidates.map(({ path, content, baseVersion, baseBrainSha }) => ({
         path,
         content,

package/lib/claude-config.mjs

@@ -13,6 +13,42 @@ export const RAFA_PERMISSIONS = [
   "Bash(rafa:*)",
 ];
 
+// Merge the repo's .mcp.json server names into the OWNED agent cards' tools
+// lines (ratified 2026-07-12: subagents must be able to reach the repo's MCPs
+// — a Convex repo's mcp__convex tools were structurally invisible to atlas).
+// Owned-file edit, idempotent, reviewable in git diff; blueprint stays generic.
+export function mergeRepoMcpsIntoCards(targetDir) {
+  const mcp = readClaudeSettingsFile(join(targetDir, ".mcp.json"));
+  const servers = Object.keys(mcp?.mcpServers ?? {}).filter((n) => n !== "rafinery");
+  if (servers.length === 0) return { updated: [] };
+  const updated = [];
+  const dir = join(targetDir, ".claude", "agents");
+  if (!existsSync(dir)) return { updated };
+  for (const card of ["atlas.md", "bloom.md", "prism.md", "compass.md"]) {
+    const file = join(dir, card);
+    if (!existsSync(file)) continue;
+    let text = readFileSync(file, "utf8");
+    const m = text.match(/^tools: (.+)$/m);
+    if (!m) continue;
+    const have = m[1].split(",").map((t) => t.trim());
+    const missing = servers.map((s2) => `mcp__${s2}`).filter((t) => !have.includes(t));
+    if (missing.length === 0) continue;
+    text = text.replace(/^tools: .+$/m, `tools: ${[...have, ...missing].join(", ")}`);
+    writeFileSync(file, text);
+    updated.push(`${card} (+${missing.join(", ")})`);
+  }
+  return { updated };
+}
+
+function readClaudeSettingsFile(file) {
+  if (!existsSync(file)) return null;
+  try {
+    return JSON.parse(readFileSync(file, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
 export function settingsPath(targetDir) {
   return join(targetDir, ".claude", "settings.json");
 }

package/lib/distill.mjs

@@ -76,6 +76,10 @@ export default async function distill(args = []) {
     );
 
   const ROOT = process.cwd();
+  // Telemetry (owner feedback #9): every phase is timed and printed, so a CI
+  // log answers "where is it, and where did the time go" at a glance.
+  const t0 = Date.now();
+  const secs = (t) => ((Date.now() - t) / 1000).toFixed(1);
 
   // 1 · collect the branch working set. Adjudication-flagged rows are LEFT for
   // a human session (CI can flag divergence, never resolve it).
@@ -101,7 +105,9 @@ export default async function distill(args = []) {
 
   // 2 · mirror the org brain locally — the authoring target + the base the
   // survivors fold into. (CI checkout is merged main = the validation target.)
+  const tPull = Date.now();
   await pull(["--full"]);
+  console.log(`  ⏱ brain mirror: ${secs(tPull)}s`);
 
   // 3 · stage the incoming working set for the agent (gitignored inside .rafa).
   const stagingRoot = join(ROOT, ".rafa", "distill-incoming");
@@ -153,6 +159,7 @@ Staged files:
 ${fileList}`;
 
   console.log("• running the distillation agent (org's own ANTHROPIC_API_KEY) …");
+  const tAgent = Date.now();
   const run = sdk.query({
     prompt,
     options: {
@@ -163,14 +170,45 @@ ${fileList}`;
       maxTurns: 150,
     },
   });
+  // Stream the agent's narration lines — a silent multi-minute CI step reads
+  // as hung; a narrated one reads as working (and shows WHERE it hangs).
+  let lastLine = "";
+  let agentModel = "unreported";
   for await (const message of run) {
+    if (message.type === "assistant" && typeof message.message?.model === "string")
+      agentModel = message.message.model;
+    if (message.type === "assistant") {
+      const blocks = message.message?.content ?? [];
+      for (const b of blocks) {
+        if (b.type !== "text" || !b.text?.trim()) continue;
+        const line = b.text.trim().split("\n")[0].slice(0, 110);
+        if (line && line !== lastLine) {
+          console.log(`  · ${line}`);
+          lastLine = line;
+        }
+      }
+    }
     if (message.type === "result") {
       if (message.subtype !== "success")
         die(`distillation agent did not complete (${message.subtype}) — nothing resolved, nothing pushed`);
       console.log(
-        `  agent done (${message.num_turns ?? "?"} turns · ` +
+        `  ⏱ agent: ${secs(tAgent)}s (${message.num_turns ?? "?"} turns · ` +
           `$${(message.total_cost_usd ?? 0).toFixed(4)} on the org's key)`,
       );
+      // Self-report the metered run (backlog #6) — best-effort, never fatal.
+      try {
+        await callTool(ROOT, "log_usage", {
+          provider: "anthropic",
+          model: agentModel,
+          inputTokens: message.usage?.input_tokens ?? 0,
+          outputTokens: message.usage?.output_tokens ?? 0,
+          ...(typeof message.total_cost_usd === "number" ? { costUsd: message.total_cost_usd } : {}),
+          purpose: "distill",
+          runner: "ci",
+        });
+      } catch (e) {
+        console.log(`  ! usage not reported: ${e instanceof Error ? e.message : e}`);
+      }
     }
   }
 
@@ -195,10 +233,12 @@ ${fileList}`;
 
   // 6 · trust-but-verify: OUR gates re-run regardless of what the agent claims.
   console.log("• re-running the gates (trust-but-verify) …");
+  const tGates = Date.now();
   if (runVerifyCitations([]) !== 0)
     die("citation checker failed on the authored brain — nothing resolved, nothing pushed");
   if (runCompile([]) !== 0)
     die("compile gate failed on the authored brain — nothing resolved, nothing pushed");
+  console.log(`  ⏱ gates: ${secs(tGates)}s`);
 
   // 7 · ship: brain repo push (webhook → ingest), staging cleaned first.
   rmSync(stagingRoot, { recursive: true, force: true });
@@ -221,6 +261,7 @@ ${fileList}`;
         branch,
         path: f.path,
         resolution: v.verdict,
+        actorMeta: { agent: "rafa-distill", runner: "ci", model: agentModel },
         ...(v.note ? { note: v.note } : {}),
       });
       console.log(`  ${v.verdict === "distilled" ? "✓" : "!"} ${f.path} → ${v.verdict}${v.note ? ` (${v.note})` : ""}`);
@@ -232,6 +273,6 @@ ${fileList}`;
 
   console.log(
     `✓ distillation: ${distilledCount} into the org brain · ${refuted} refuted (reported, cited) · ` +
-      `${adjudication} flagged needs-adjudication (next session's digest)`,
+      `${adjudication} flagged needs-adjudication (next session's digest) · total ${secs(t0)}s`,
   );
 }

package/lib/gate/compile.mjs

@@ -335,20 +335,13 @@ export function runCompile(argv = []) {
     return { domains };
   }
 
-  // Plans (contract §7): parent+child files under plans/**. Global id uniqueness,
-  // parent/child cross-checks, progress never stored, active.md → activePlanId.
-  // VALIDATED here (files are the authoring surface — determinism holds) but
-  // since 0.4.0 plans do NOT ride the manifest: they travel through the
-  // dedicated push-on-approval plans channel (push_plan). Terminal statuses
-  // (superseded/abandoned) close a plan honestly without pretending `done`.
-  const PLAN_STATUSES = [
-    "todo",
-    "in-progress",
-    "done",
-    "blocked",
-    "superseded",
-    "abandoned",
-  ];
+  // Plans (contract §7 v2 — the work-item tree, plans data version 2): one epic
+  // (root) → tasks → subtasks. Vendor-blended vocabulary; `blocked` is DERIVED
+  // (unresolved blocked_by / blocked_reason), never stored. VALIDATED here
+  // (files are the authoring surface — determinism holds) but plans do NOT ride
+  // the manifest: they travel through the push-on-approval plans channel.
+  const PLAN_STATUSES = ["todo", "in-progress", "done", "superseded", "abandoned"];
+  const PLAN_KINDS = ["epic", "task", "subtask"];
   function compilePlans() {
     const plans = [];
     const seen = new Map(); // id → path (global uniqueness across plans/**)
@@ -365,43 +358,123 @@ export function runCompile(argv = []) {
         fail(path, "id", `duplicate plan id "${id}" (also ${seen.get(id)}) · ids are globally unique across plans/**`);
       seen.set(id, path);
       if ("progress" in data)
-        fail(path, "progress", "never stored · parent progress is derived by counting children");
-      const kind = reqEnum(data, "kind", ["parent", "child"], path);
+        fail(path, "progress", "never stored · progress = done leaves / total leaves, derived");
+      if (data.kind === "parent" || data.kind === "child")
+        fail(path, "kind", `plans v1 shape ("${data.kind}") — run \`rafa migrate\` (v2: epic|task|subtask)`);
+      const kind = reqEnum(data, "kind", PLAN_KINDS, path);
       const plan = reqStr(data, "plan", path);
       const status = data.status;
-      if (kind === "child") {
-        if (!isEnum(status, PLAN_STATUSES))
-          fail(path, "status", `required (child) · ${PLAN_STATUSES.join("|")}`);
-        if (data.parent !== plan)
-          fail(path, "parent", `must equal plan "${plan}" for a child (flat v1)`);
-      } else {
+      if (status === "blocked")
+        fail(path, "status", "removed in v2 — blocked is DERIVED from blocked_by/blocked_reason (run `rafa migrate`)");
+      if (kind === "epic") {
         if (data.parent !== null && data.parent !== "null")
-          fail(path, "parent", "must be null for kind: parent");
-        if (plan !== id) fail(path, "plan", `must equal id "${id}" for kind: parent`);
+          fail(path, "parent", "must be null for kind: epic (the root)");
+        if (plan !== id) fail(path, "plan", `must equal id "${id}" for kind: epic`);
         if (status !== undefined && !isEnum(status, PLAN_STATUSES))
-          fail(path, "status", `optional (parent) · ${PLAN_STATUSES.join("|")}`);
+          fail(path, "status", `optional (epic) · ${PLAN_STATUSES.join("|")}`);
+      } else {
+        if (!isEnum(status, PLAN_STATUSES))
+          fail(path, "status", `required (${kind}) · ${PLAN_STATUSES.join("|")}`);
+        if (typeof data.parent !== "string" || data.parent === "")
+          fail(path, "parent", `required (${kind}) · the parent item id`);
+        if (data.domains !== undefined)
+          fail(path, "domains", "epic only · the blast radius belongs to the plan, not an item");
+      }
+      if (data.domains !== undefined && !Array.isArray(data.domains))
+        fail(path, "domains", "optional · flow list of domain strings");
+      if (data.blocked_by !== undefined && !Array.isArray(data.blocked_by))
+        fail(path, "blocked_by", "optional · flow list of item ids this item waits on");
+      if (
+        data.priority !== undefined &&
+        !(Number.isInteger(data.priority) && data.priority >= 0 && data.priority <= 4)
+      )
+        fail(path, "priority", "optional · int 0–4 (0 none · 1 urgent · 2 high · 3 medium · 4 low)");
+      if (data.estimate !== undefined && !(Number.isInteger(data.estimate) && data.estimate >= 0))
+        fail(path, "estimate", "optional · non-negative int (points)");
+      if (data.external !== undefined) {
+        const ex = data.external;
+        if (typeof ex !== "object" || Array.isArray(ex) || typeof ex.provider !== "string" || typeof ex.key !== "string")
+          fail(path, "external", "optional · { provider, key, url? } flow map — tracker identity (read-only to sessions)");
       }
       plans.push({
         id,
         plan,
-        parent: kind === "parent" ? null : plan,
+        parent: kind === "epic" ? null : String(data.parent ?? ""),
         kind,
         title: reqStr(data, "title", path),
         ...(isEnum(status, PLAN_STATUSES) ? { status } : {}),
+        ...(typeof data.description === "string" && data.description !== ""
+          ? { description: data.description }
+          : {}),
+        ...(typeof data.approach === "string" && data.approach !== ""
+          ? { approach: data.approach }
+          : {}),
+        ...(typeof data.assignee === "string" && data.assignee !== ""
+          ? { assignee: data.assignee }
+          : {}),
+        ...(Array.isArray(data.blocked_by) ? { blockedBy: data.blocked_by.map(String) } : {}),
+        ...(typeof data.blocked_reason === "string" && data.blocked_reason !== ""
+          ? { blockedReason: data.blocked_reason }
+          : {}),
+        ...(Number.isInteger(data.priority) ? { priority: data.priority } : {}),
+        ...(Number.isInteger(data.estimate) ? { estimate: data.estimate } : {}),
         ...(typeof data.branch === "string" && data.branch !== ""
           ? { branch: data.branch }
           : {}),
         ...(typeof data.baseSha === "string" && data.baseSha !== ""
           ? { baseSha: String(data.baseSha) }
           : {}),
+        ...(Array.isArray(data.domains) && kind === "epic"
+          ? { domains: data.domains.map(String) }
+          : {}),
+        ...(typeof data.external === "object" && !Array.isArray(data.external) && data.external !== null
+          ? { external: data.external }
+          : {}),
         path: rel(path),
       });
     }
-    // Cross-check: every child's plan resolves to a kind:parent in this compile.
-    const parents = new Set(plans.filter((p) => p.kind === "parent").map((p) => p.id));
+    // Cross-checks: tree shape + blocked_by resolution, per plan.
+    const byId = new Map(plans.map((p) => [p.id, p]));
+    const roots = new Map(); // plan id → epic item
+    for (const p of plans) if (p.kind === "epic") roots.set(p.id, p);
+    for (const p of plans) {
+      if (!roots.has(p.plan))
+        fail(p.path, "plan", `no kind:epic "${p.plan}" in this compile (dangling item)`);
+      if (p.kind === "task") {
+        const parent = byId.get(p.parent);
+        if (!parent || parent.kind !== "epic" || parent.id !== p.plan)
+          fail(p.path, "parent", `a task's parent must be its epic ("${p.plan}")`);
+      }
+      if (p.kind === "subtask") {
+        const parent = byId.get(p.parent);
+        if (!parent || parent.kind !== "task")
+          fail(p.path, "parent", "a subtask's parent must be a task in the same plan");
+        else if (parent.plan !== p.plan)
+          fail(p.path, "parent", `parent task belongs to plan "${parent.plan}", not "${p.plan}"`);
+      }
+      for (const b of p.blockedBy ?? []) {
+        const target = byId.get(b);
+        if (!target || target.plan !== p.plan)
+          fail(p.path, "blocked_by", `"${b}" does not resolve to an item in plan "${p.plan}"`);
+        if (b === p.id) fail(p.path, "blocked_by", "an item cannot block itself");
+      }
+    }
+    // blocked_by acyclicity (per plan; DFS with colors).
+    const color = new Map();
+    const cyc = (p) => {
+      color.set(p.id, 1);
+      for (const b of p.blockedBy ?? []) {
+        const t = byId.get(b);
+        if (!t) continue;
+        if (color.get(t.id) === 1) return true;
+        if (!color.has(t.id) && cyc(t)) return true;
+      }
+      color.set(p.id, 2);
+      return false;
+    };
     for (const p of plans)
-      if (p.kind === "child" && !parents.has(p.plan))
-        fail(p.path, "plan", `no parent plan "${p.plan}" in this compile (dangling child)`);
+      if (!color.has(p.id) && cyc(p))
+        fail(p.path, "blocked_by", "dependency cycle — blocked_by must be acyclic");
     return plans;
   }
 
@@ -419,8 +492,8 @@ export function runCompile(argv = []) {
     }
     const val = m[1].trim();
     if (/^no active plan$/i.test(val)) return null;
-    if (!plans.some((p) => p.kind === "parent" && p.id === val)) {
-      fail(path, "pointer", `active plan "${val}" is not a kind:parent plan in this compile`);
+    if (!plans.some((p) => p.kind === "epic" && p.id === val)) {
+      fail(path, "pointer", `active plan "${val}" is not a kind:epic plan in this compile`);
       return null;
     }
     return val;

package/lib/init.mjs

@@ -105,6 +105,13 @@ export default async function init(args) {
   );
   // Grant rafa's tools their permissions (merge, never overwrite).
   reportSettings(TARGET);
+  // Wire the repo's own MCP servers into the (owned) agent cards so subagents
+  // can actually reach them (zero-command orchestration, 2026-07-12).
+  {
+    const { mergeRepoMcpsIntoCards } = await import("./claude-config.mjs");
+    const r = mergeRepoMcpsIntoCards(TARGET);
+    for (const u of r.updated) console.log(`  ✓ repo MCPs → ${u}`);
+  }
 
   // Keep the brain out of the code repo's diffs; keep the per-dev MCP key out of git.
   const ensureIgnored = (line, label) => {
@@ -151,6 +158,26 @@ export default async function init(args) {
     );
   }
 
+  // CI reconciliation — OPT-IN at provisioning (owner feedback #5): the workflow
+  // runs on the ORG's own secrets (their LLM key never touches our platform), so
+  // it is offered, never silently installed. Non-TTY (CI/agent shells) skips the
+  // question entirely — explicit `rafa ci-setup` remains the path there.
+  if (isInteractive()) {
+    const a = await ask(
+      "  • Wire CI reconciliation now? (GitHub Actions: mechanical fold on branch merges,\n" +
+        "    distillation on merge-to-main — runs on YOUR CI secrets) [y/N] ",
+    );
+    if (a === "y" || a === "yes") {
+      const { default: ciSetup } = await import("./ci-setup.mjs");
+      await ciSetup([]);
+    } else {
+      console.log(
+        "  • skipped — wire it anytime with `rafa ci-setup`. Until then, the next dev\n" +
+          "    session offers the same reconciliation after each merge (nothing is lost).",
+      );
+    }
+  }
+
   // Stamp the versions this repo was provisioned at — the compat anchor `update`/`migrate`
   // diff against. Carries platform identity too when provisioned via a setup URL.
   stampCurrent(

package/lib/leverage.mjs

@@ -3,12 +3,23 @@
 // only: it reads, ranks, and reports — it changes nothing. Run from your repo root.
 
 import { advise } from "./leverage/engine.mjs";
-import { PLANNED } from "./leverage/adapters/index.mjs";
+import { adapters, PLANNED } from "./leverage/adapters/index.mjs";
 
-export default async function leverage() {
+export default async function leverage(args = []) {
   const cwd = process.cwd();
   const { detected, tips } = advise(cwd);
 
+  // --json: the DETERMINISTIC toolbox inventory (ratified 2026-07-12) — what
+  // the conductor loads at bootstrap and atlas consults during scan's toolbox
+  // pass. Machine truth: only what is actually installed, never inferred.
+  if (args.includes("--json")) {
+    const inventory = {};
+    for (const a of adapters)
+      if (a.detect(cwd)) inventory[a.id] = a.inspect(cwd);
+    console.log(JSON.stringify({ detected, inventory, tips }, null, 2));
+    return;
+  }
+
   if (detected.length === 0) {
     console.log(
       "No supported agent toolchain detected here.\n" +

package/lib/migrations/index.mjs

@@ -28,7 +28,7 @@
 //     run: (cwd) => backfillPlanField(cwd, "owner", ownerOf(cwd)),
 //   };
 
-import { existsSync, rmSync } from "node:fs";
+import { existsSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { cmpSemver } from "../releases.mjs";
 
@@ -66,7 +66,62 @@ const blueprint_split_0_4_0 = {
   },
 };
 
-export const MIGRATIONS = [blueprint_split_0_4_0];
+// plans v2 (contract §7 v2, ratified 2026-07-12): the work-item tree. Mechanical
+// half: kind parent→epic, child→task (rank semantics unchanged for flat v1 plans),
+// stored `status: blocked` → `status: todo` + a blocked_reason note (blocked is
+// DERIVED in v2). Only frontmatter lines are touched; bodies never.
+const plans_v1_to_v2 = {
+  id: "plans-v1-to-v2-work-item-tree",
+  kind: "plans",
+  mode: "mechanical",
+  summary:
+    "plans become a work-item tree (epic|task|subtask); blocked becomes derived " +
+    "(kind parent→epic, child→task; status blocked→todo + blocked_reason)",
+  appliesTo: (from, to) => from.plans < 2 && to.plans >= 2,
+  run: (cwd) => {
+    const changed = [];
+    const notes = [];
+    const dir = join(cwd, ".rafa", "plans");
+    const walk = (d) => {
+      if (!existsSync(d)) return [];
+      return readdirSync(d).flatMap((e) => {
+        const p = join(d, e);
+        return statSync(p).isDirectory() ? walk(p) : e.endsWith(".md") ? [p] : [];
+      });
+    };
+    for (const file of walk(dir)) {
+      const text = readFileSync(file, "utf8");
+      if (!text.startsWith("---")) continue;
+      const end = text.indexOf("\n---", 3);
+      if (end === -1) continue;
+      let fm = text.slice(0, end);
+      const body = text.slice(end);
+      const before = fm;
+      fm = fm.replace(/^kind:\s*parent\s*$/m, "kind: epic");
+      fm = fm.replace(/^kind:\s*child\s*$/m, "kind: task");
+      if (/^status:\s*blocked\s*$/m.test(fm)) {
+        fm = fm.replace(/^status:\s*blocked\s*$/m, "status: todo");
+        if (!/^blocked_reason:/m.test(fm))
+          fm += `\nblocked_reason: "(migrated) was 'blocked' in plans v1 — re-state the real blocker"`;
+        notes.push(`${file.slice(cwd.length + 1)}: blocked → todo + blocked_reason (re-state the real blocker)`);
+      }
+      if (fm !== before) {
+        writeFileSync(file, fm + body);
+        changed.push(file.slice(cwd.length + 1));
+      }
+    }
+    return {
+      changed,
+      notes: changed.length
+        ? notes.length
+          ? notes
+          : ["kinds re-ranked (parent→epic, child→task); review the diff"]
+        : ["no v1 plan files found — nothing to migrate"],
+    };
+  },
+};
+
+export const MIGRATIONS = [blueprint_split_0_4_0, plans_v1_to_v2];
 
 // The migrations that apply to a given move (stamped `from` → shipped `to`), in order.
 export function pendingMigrations(from, to) {

package/lib/releases.mjs

@@ -102,6 +102,37 @@ export const RELEASES = [
       "the working-set scanner returned the directory path instead of each file's path " +
       "(variable shadowing in scanWorkingFiles). No schema change; no re-scan.",
   },
+  {
+    version: "0.4.2",
+    contract: 1,
+    plans: 1,
+    requires: "update",
+    summary:
+      "Owner E2E feedback round. `rafa init` now OFFERS CI reconciliation at provisioning " +
+      "(TTY only; skipping prints the session-fallback path — nothing is silently installed). " +
+      "`rafa distill --headless` streams the agent's narration and prints per-phase timings + " +
+      "cost (mirror · agent · gates · total), so CI logs show liveness and where time goes. " +
+      "Plans gain an optional parent-only `domains:` (contract §7) — the blast radius rides " +
+      "push_plan and the platform renders the plan's brain slice on its new detail page. " +
+      "No schema migration; no re-scan.",
+  },
+  {
+    version: "0.5.0",
+    contract: 1,
+    plans: 2,
+    requires: "migrate",
+    summary:
+      "Plans v2 — the work-item tree (contract §7 v2, first plans data-version bump). " +
+      "epic → task → subtask with vendor-blended vocabulary (checked against Linear/Jira/Asana " +
+      "APIs): title · description · approach · assignee · blocked_by (a dependency IS a " +
+      "blocker) · blocked_reason · priority 0–4 · estimate · external {provider,key,url} " +
+      "(read-only tracker identity). `blocked` is DERIVED, never stored — the status enum is " +
+      "todo|in-progress|done|superseded|abandoned. Decisions become first-class channel " +
+      "records (log_decision: at·actor·context·options·decision·rationale; paraphrase + " +
+      "pivotal quotes), mirrored as `## Decisions` body prose. `rafa migrate` converts v1 " +
+      "files mechanically (parent→epic, child→task, blocked→todo+blocked_reason). Brain data " +
+      "schema unchanged; no re-scan.",
+  },
 ];
 
 // The release this CLI build ships (last entry).

package/lib/update.mjs

@@ -31,6 +31,13 @@ export default async function update(args = []) {
     await copyBlueprint(blueprintSource(), TARGET, { onConflict: makeConflictResolver(args) }),
   );
   reportSettings(TARGET);
+  // Wire the repo's own MCP servers into the (owned) agent cards so subagents
+  // can actually reach them (zero-command orchestration, 2026-07-12).
+  {
+    const { mergeRepoMcpsIntoCards } = await import("./claude-config.mjs");
+    const r = mergeRepoMcpsIntoCards(TARGET);
+    for (const u of r.updated) console.log(`  ✓ repo MCPs → ${u}`);
+  }
 
   // ── Blueprint-side migrations: mechanical/deterministic, run here in the CLI. ──
   // (Anything needing intelligence is left for the brain-side pass — /rafa update.)

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@rafinery/cli",
-  "version": "0.4.1",
-  "description": "rafa \u2014 the AI engineer CLI. Vendors the rafa blueprint into your repo (shadcn-style) and runs the deterministic contract gates.",
+  "version": "0.5.0",
+  "description": "rafa — the AI engineer CLI. Vendors the rafa blueprint into your repo (shadcn-style) and runs the deterministic contract gates.",
   "type": "module",
   "bin": {
     "rafa": "bin/rafa.mjs"