@rafinery/cli 0.8.15 → 0.10.0

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

@@ -17,7 +17,7 @@ platform MCP (one read path — the same surface any third-party agent uses).
 | 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). Plan-done adds one line to the verdict: **working set reviewed — captured, or clean-with-reason** (a build that learned nothing SAYS so; a build that learned something SHOWS the files) |
+| **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). **TDD tasks (wave 6): green re-run LIVE; red per tier (standard = attested `method:"static"` · full = re-run at the red commit in a throwaway worktree). Findings carry `Critical (Must Fix) · Important (Should Fix) · Minor (Nice to Have)` — ITERATE iff any Critical/Important; Minor NEVER flips the verdict.** Plan-done adds one line to the verdict: **working set reviewed — captured, or clean-with-reason** (a build that learned nothing SAYS so; a build that learned something SHOWS the files) |
 | **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 |
 | **Coach** | compass | **sitback** (harness-arc): after each task's verdict + sweep, one beat of reflection — did THIS task reveal something about how this DEV works (a preference, a recurring friction, a steering pattern)? Repo knowledge goes to the working set, never here. A genuine dev-level observation becomes its OWN opt-in offer (consent doctrine: insights are NEVER under session consent) → `put_dev_insight` on yes. No observation = no offer — silence is the honest default |
 
@@ -47,22 +47,33 @@ platform MCP (one read path — the same surface any third-party agent uses).
    **and append a dated entry to the child's `## Log`** (body links: markdown,
    per [rafa-okf](../rafa-okf/SKILL.md)) — 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) +
-   **`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) +
-   **`report_loop_event(category: "prism-verdict", outcome: PASS|ITERATE,
-   subject: <task id>)`** at the moment prism rules on the Done-check (sage's
-   evidence — shapes only: the verdict + the task id, never code) +
-   `rafa checkpoint` (the branch working set), so the platform and every MCP
-   consumer reflect live progress. Checkpoint moments: task done · plan
+   parsed; the plan files at `.rafa/plans/<plan>/` ARE the local cache) → the
+   task-done CHECKPOINT is **ONE beat (wave 5), two calls total**, under the
+   session consent:
+   **(a) `checkpoint_task`** — the atomic boundary write (all-or-nothing,
+   idempotent on retry) carrying together: `patch: {status, body}` (the item's
+   new status + its full body with the fresh `## Log` entry — never a
+   whole-tree `push_plan` for one task); `loopEvent: {category:
+   "prism-verdict", outcome: PASS|ITERATE, subject: <task id>, tier: <the
+   task's validation_tier>, verification: <prism's evidence entry — method
+   static|live + tool + exit code, straight from its structured return>,
+   actorMeta: {model: <ruling model>, agent: "prism@<card ver>", runner:
+   "session"}, dedupeKey: "<task-id>·v<attempt>"}` (the emit rides the ruling's
+   OWN moment, never a session-end sweep; the dedupeKey makes a retried beat
+   count ONCE — the non-idempotent-emit learning, closed); and `decisions:
+   [...]` — each deliberation since the last beat with a CLIENT-STABLE id
+   (`<task-id>·d1`, `·d2` …): 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).
+   **(b) `rafa checkpoint`** — the branch working set + sensor heartbeat +
+   brain mirror (the CLI beat; it also refreshes the loop-event cache the
+   sage-due digest reads).
+   `push_plan` remains for CREATION and structure changes only;
+   `update_plan_status`/`log_decision` stay valid but the one-beat call
+   replaces them at task boundaries. Checkpoint moments: task done · plan
    approved · explicit ask · cadence · git push/pull — never session-end. The
-   loop-event emits ride the SAME checkpoint beats — one per outcome as it
-   occurs, monotonic, NEVER a session-end sweep. The
    git-push boundary is MECHANICAL (M5): the pre-push hook runs `rafa checkpoint`
    itself, non-blocking — the session still owns the task-done/plan-approved
    moments. A checkpoint CONFLICT (a teammate's newer copy of the same file) is
@@ -71,10 +82,11 @@ platform MCP (one read path — the same surface any third-party agent uses).
 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. When the gate runs, emit
-     **`report_loop_event(category: "gate-result", outcome: exit0|failed,
-     subject: <compile|verify-citations>)`** at that checkpoint beat — the gate's
-     own moment, never deferred to session-end.
+     `brain = f(code@sha)` stays exact. gate-result loop events are
+     **MECHANICAL** (wave 5): the push gates emit them CLI-stamped — actor
+     envelope, `method: "live"` verification with the real exit code, and a
+     `(gate·sha·outcome)` dedupeKey. The session never hand-emits gate-result;
+     the double-emit class died with the non-idempotent-emit learning.
    - **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
@@ -106,6 +118,85 @@ platform MCP (one read path — the same surface any third-party agent uses).
    scoped-refresh offer NOW (on main: refresh → gates → push; on a branch:
    working-set edit → checkpoint), and `rafa dirty --consume` only after it ships.
 
+## TDD-default (wave 6 — code tasks build red → green)
+
+**Eligibility gate (deterministic, decided once per session):** the `tdd` skill
+is installed (`.agents/skills/tdd/` — the toolbox slice says so) AND the repo
+has a test harness — checklist, first hit wins: `package.json` `test` script ·
+`vitest.config.*`/`jest.config.*` · `pytest.ini`/`pyproject [tool.pytest]` ·
+`go.mod` with `*_test.go` · `Cargo.toml`. Bank the answer as a session fact
+(`rafa facts add --claim="test harness: <runner>" --command="<detect>" --exit=0
+--depends=package.json`) so no later spawn re-derives it. Not eligible → the
+pre-wave path below, unchanged, plus a `factsDiscovered: ["tdd unavailable:
+<reason>"]` note in atlas's return — bloom may later surface a tooling-fit
+improvement; NEVER a mid-build nag.
+
+**The loop (per the installed tdd skill — atlas INVOKES it; its anti-patterns
+are prism's criteria):**
+1. **Red** — atlas authors the failing test FIRST, at the seam the plan's
+   Done-check names (the seam was dev-confirmed at approval — never invented
+   here). Run it; it must FAIL for the right reason. Commit
+   `[<task-id>] test: red — <seam>` (full tier prefers the split commit; at
+   standard tier the evidence object below is the durable proof and red+green
+   may land as one commit).
+2. **Green** — implement the minimal slice to exit 0. One seam, one test, one
+   vertical slice per cycle — never all-tests-then-all-code.
+3. **Refactor is NOT part of the loop** — it belongs to the review stage
+   (tdd SKILL.md's own rule + the [rafa-review](../rafa-review/SKILL.md) gate;
+   bloom's no-big-bang directive is the same law).
+Evidence rides atlas's structured return —
+`evidence: [{claim: "red", tool: "<runner>", exitCode: 1}, {claim: "green",
+tool: "<runner>", exitCode: 0}]` + `skillsUsed: ["tdd"]` — and
+`how: via the tdd skill` lands in the item's `approach`.
+
+**prism's verification, tier-scaled:** green is ALWAYS re-run live (tool
+authenticity: binary + real exit code). Red at **standard** = attested from
+atlas's evidence, labeled `method: "static"`; at **full** = re-run at the red
+commit in a throwaway worktree (`git worktree add`), labeled `method: "live"`.
+Mock discipline is a finding class: mocks only at system boundaries, never the
+repo's own collaborators (the tdd skill's mocking reference is the criteria).
+
+## UI tasks — the design method (wave 6)
+
+**Trigger:** the task's epic `domains:` include a UI domain, or its target
+files land in the app's component/route surfaces — the BRAIN's domain map
+decides, never a hardcoded path list.
+
+**Method (when the skills are installed — the toolbox slice says):** atlas
+**INVOKES** `frontend-design` (Skill tool) for the two-pass plan — token
+system (Color 4–6 named values · Type roles · Layout · the ONE signature
+element), then self-critique against the brief before any code — and CONSULTS
+`vercel-composition-patterns` for component structure (no boolean-prop
+sprawl · compound components · state/actions/meta context · children over
+render props), gating the `react19-*` rules on the repo's actual React version
+(a React ≤18 repo skips them, stated in the return).
+
+**Adherence vs distinctive — the brain decides:** when the brain documents a
+design system (theme tokens, component conventions), those notes ARE the
+brief and the skill's own "the brief's own words always win" rule applies —
+adherence mode, distinctiveness spent within the system. No design-system
+notes (greenfield/marketing surface) → distinctive mode, full method. Record
+`how: via the frontend-design skill` (+ vercel-composition-patterns when
+consulted). Skills declined → the pre-wave path + a `factsDiscovered` note.
+
+## Spawn-prompt discipline (wave 5 — pay once, cite after)
+
+- **Session facts first.** Every atlas/prism spawn prompt begins by pointing at
+  `.rafa/session-facts.json` (read first; cite `SF-n unchanged` where it holds;
+  bank new expensive verifications via `rafa facts add`). Six agents
+  re-deriving one environment fact was the QA session's headline waste.
+- **Never restate card doctrine.** The card already binds the agent's creed
+  (prism's skepticism, atlas's toolbox-first) — a spawn prompt carries ONLY the
+  task-specific grounding: the task file, the exact target files/patterns, the
+  `validation_tier`, the facts pointer. Re-explaining the card in every prompt
+  is conductor inefficiency, not rigor.
+- **Compact agent-to-agent register.** A subagent's primary reader is the
+  CONDUCTOR: terse-with-citations by default, ending in the structured return
+  (prism: `{verdict, evidence[], residualRisk}` · atlas: `{filesChanged,
+  commitSha, notes, factsDiscovered}`) — Logs and loop events assemble from
+  FIELDS, never re-paraphrased prose. Expand to full prose only on ITERATE or
+  when the human will read it directly.
+
 **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).

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

@@ -91,6 +91,24 @@ convention — see [RSC client boundary](/brain/rules/rsc-client-boundary.md)).
    performance · architecture · product · ops**. Weight the **silent** issues (directive 2):
    convention violations the brain documents, framework boundary breaches (e.g. RSC), missing
    authz, drifting contracts. The brain's conventions are your oracle for "what's a violation here."
+
+   **The architecture lens has a METHOD (wave 6)** — criteria adapted from the installed
+   `improve-codebase-architecture` skill (READ as criteria, never invoked — it is
+   `disable-model-invocation`; the method below stands whether or not the skill is installed):
+   - **Scope by heat, not by sweep** (YAGNI): unless the dev named a direction, walk
+     `git log --oneline` for the hot spots — churn is where depth pays; cold code waits.
+   - **Deep vs shallow judgment**: a module earns its interface when the interface is smaller
+     than what it hides. Bouncing between many small modules to follow one behavior, pure
+     functions extracted only for testability, and leaky seams are the friction signals.
+   - **The deletion test**: would deleting this module CONCENTRATE complexity somewhere honest,
+     or just smear it around? "Concentrates" marks a candidate.
+   - **Candidates are normal §3 improvement files** (zero schema change): before/after as body
+     prose + a `Confidence: Strong | Worth exploring | Speculative` body line; inside these
+     notes use the depth vocabulary — module · interface · implementation · seam · adapter ·
+     depth · leverage · locality — and keep it INSIDE the architecture lens (the rest of the
+     ledger speaks the repo's own language).
+   - **The big-bang guard is sovereign** (directive 1): a `Strong` candidate lands as its first
+     10-minute slice or a P2 backlog item — never a grand refactor plan.
 3. **Delegate security.** Run `pnpm audit` (dep CVEs). Recommend/run the **`security-review`**
    skill and semgrep/CodeQL if available. Record *tool* results as improvements; the LLM pass is
    observational only — never present it as an authoritative audit.
@@ -166,3 +184,7 @@ the ledger the nudge will read.
   beyond the deterministic cite-check.
 - Debt-score weighting calibrated from real runs.
 - Per-lens diverse validators (a security lens checked by a security-minded validator).
+- A visual before/after artifact for architecture candidates (the
+  improve-codebase-architecture skill's HTML report) — deliberately SKIPPED for now: its
+  CDN-loaded Tailwind/Mermaid + temp-file-and-open mechanics violate the deterministic,
+  no-network posture; the ledger IS the report.

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

@@ -44,7 +44,12 @@ at the fix. This is platform DNA: **leverage what's present; never reinvent it.*
 
 The engine ([`lib/leverage/engine.mjs`](../../../packages/cli/lib/leverage/engine.mjs)) gathers
 light, tool-agnostic repo signals (`repoContext`: stack deps, `.env` files + whether they're
-ignored, declared MCP servers), then runs every **detected** adapter and ranks the tips.
+ignored, declared MCP servers, **and the harness-neutral `.agents/skills/` inventory +
+skill-dependency status (wave 6)** — `.agents/` is ONE convention Claude Code · Codex ·
+Cursor all read, so it lives in the engine, never inside a per-toolchain adapter), then runs
+every **detected** adapter and ranks the tips. The engine emits its own rafa-level tip —
+`skill-deps-missing` (`P2`, fix = `rafa update --skills`) — because rafa's declared skill
+dependencies are harness-neutral by definition.
 
 Each adapter implements one contract ([`lib/leverage/adapters/index.mjs`](../../../packages/cli/lib/leverage/adapters/index.mjs)):
 

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

@@ -41,6 +41,34 @@ Planning is a choreography, not one agent (spec: knowledge-mcp-build-agent):
   A plan whose children lack Done-checks is REJECTED here — compile never parses
   bodies (invariant #3); this gate is prism's.
 
+  **The grill pass (wave 6 — tier-bounded adversarial interview).** On top of
+  the two invariants, prism GRILLS the draft — the same procedure the installed
+  `grilling` skill carries (`.agents/skills/grilling/SKILL.md`; prism READS it
+  as criteria when installed, and this SOP carries the method regardless —
+  never invoked mid-validation, per its card). Per task, up the probe ladder:
+  **grounding** (which claims rest on assumption? name it, demand its
+  evidence — a session-fact id counts, vibes don't) · **unstated dependencies**
+  (what must exist for this task that no `blocked_by` declares?) · **vacuous
+  Done-check** (can it pass while the feature is broken? a check that
+  recomputes its expectation the way the code will, or that a no-op satisfies,
+  is TAUTOLOGICAL — criteria per the tdd skill's anti-patterns when installed)
+  · **YAGNI** (does the INTENT need this task, or did thoroughness invent it?).
+  Budget scales with the task's `validation_tier`: **light** = the two
+  invariants only (exactly today) · **standard** = ≤2 probes per task, ≤10 per
+  plan · **full** = the complete grilling procedure (one probe at a time,
+  survives-three-consecutive ends it). Every probe finding cites the plan line
+  it hits — an uncited probe is dropped, and findings feed the existing
+  REJECT-with-cited-reasons loop. Plan-lite drafts grill at light.
+
+  **The seam ritual (wave 6 — TDD's consent moment, no new prompt).** For code
+  tasks in TDD-eligible repos (the tdd skill installed + a test harness
+  detected — the build SOP's gate), every LEAF's `## Done-check` NAMES the seam
+  under test: *"`<runner>` on `<test-file>` at seam `<the public interface>`
+  exits 0"*. Seams come from recall (the brain's contracts/flows) — never
+  invented at build time. The plan-approval summary lists the seams as their
+  own line, so **the dev approving the plan IS the tdd skill's "confirm seams
+  with the user" step** — consent rides the existing approval gate.
+
 ## Procedure
 
 1. **Staleness check** — compare the platform envelope's `brainForSha` against the
@@ -58,7 +86,14 @@ Planning is a choreography, not one agent (spec: knowledge-mcp-build-agent):
    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
+   never a status) · optional `priority` 0–4 / `estimate` ·
+   **`validation_tier` (wave 5 — rigor scales with blast radius, not with
+   process): assign per LEAF from what the task touches — contract/state-shape/
+   graph surface → `full` · pure types/docs/leaf-UI → `light` · everything else
+   → `standard` (the default when omitted). The tier bounds prism's
+   RE-DERIVATION DEPTH only; the Done-check gate itself never relaxes, and the
+   tier rides the task's loop events so sage can audit the tiering against
+   escaped-bug reality instead of anyone guessing.** 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

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

@@ -104,8 +104,16 @@ its OWN question:
 7. **The active task's Done-check** (from `get_active_plan`): does the diff
    satisfy what the plan said done means?
 8. Verdict: **PASS** or **ITERATE** with per-finding citations (note id +
-   file:line). Findings feed atlas (validate-and-correct — atlas fixes, the
-   judge re-checks; the reviewer never edits).
+   file:line). **Severity rides every finding (wave 6 — the
+   requesting-code-review taxonomy): `Critical (Must Fix)` · `Important
+   (Should Fix)` · `Minor (Nice to Have)`. ITERATE iff ≥1 Critical or
+   Important; Minor NEVER flips the verdict** (advisory noise must not
+   masquerade as a gate — and "not everything is Critical" is the taxonomy's
+   own first rule). Findings feed atlas (validate-and-correct — atlas fixes,
+   the judge re-checks; the reviewer never edits). The fresh-context reviewer
+   discipline the installed requesting-code-review skill prescribes
+   (precisely-crafted context, never the session's history) IS rafa's spawn
+   model already — confirmation, not new machinery.
 9. Emit **`report_loop_event(category: "review-verdict", outcome:
    PASS|ITERATE, subject: <task id or branch>)`** at the ruling — sage's
    evidence, monotonic, never a session-end sweep.
@@ -124,3 +132,9 @@ its OWN question:
 - Trusting the diff author's summary — judge code against rules.
 - Blocking on the gate — it is advisory; the merge reconciler is the hard gate.
 - Findings without citations (rule id + file:line) — uncited = unactionable.
+- **Mutating anything while judging** (wave 6, from the code-reviewer's
+  read-only rule): the review never touches the working tree, the index, HEAD,
+  or branch state — inspect another revision via `git show`/a throwaway
+  worktree, never a checkout on this one.
+- **Severity inflation** — a verdict where everything is Critical has stopped
+  discriminating; that is itself a review failure.

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

@@ -58,8 +58,14 @@ boundary; its product is a ledger reviewed *later*, never a live nudge. No mid-f
 ### 2. evidence-cited — SHAPES only, via `get_loop_events`
 Every learning cites its evidence, and evidence is **loop-event shapes and categories only**:
 verdict TYPES, gap CLASSES, miss TAXONOMIES, and the aggregate counts/rates over them — read via
-`get_loop_events` (category ∈ `prism-verdict | gate-result | reflex-outcome | distill-refutation`;
-outcome enum per category; `subject` is a shape reference, never content). A learning with no
+`get_loop_events` (category ∈ `prism-verdict | gate-result | reflex-outcome | distill-refutation |
+review-verdict`; outcome enum per category; `subject` is a shape reference, never content). Wave 5
+enriched every event with THREE new analysis dimensions — split every rate by them: **verification
+method** (`static` vs `live` — a PASS-rate that holds only on static rulings is a coverage gap, not
+health), **actor envelope** (model · agent@version · runner — attribute a miss class to the agent
+structure that produced it), and **tier** (`light|standard|full` — audit the tiering itself: a
+light-tier task class that later produced escaped bugs is evidence the planner's tier rule needs a
+diff; a full-tier class whose findings-density is ~zero is evidence of ceremony). A learning with no
 event-shape evidence is a hunch — drop it. sage never cites a customer artifact (no `file:line`
 into customer code; that field does not exist in the schema below).
 
@@ -101,7 +107,9 @@ human.
 The ledger is a **committed, human-reviewed governance artifact** — diffs for MR review. It is
 **NOT** a Convex table and **NOT** inside any customer `.rafa/brain/` (asset-free: learnings are
 about OUR agents; they never mix with customer knowledge). It lives beside the contract at
-`.claude/rafa/learnings/` (governance, versioned with the blueprint, MR-reviewed):
+`.claude/rafa/learnings/` (governance, versioned with the blueprint, MR-reviewed). The platform's
+"agent learnings" card renders a **projection** of it (summary rows via `report_learning`, wave
+4.1, owner-ratified 2026-07-24) — a display overlay, never a second truth and never the store:
 
 - `learnings/<id>.md` — one file per learning (one proposed card/SOP diff, cited to event shapes).
 - `ledger.md` — generated index: counts by category / target / status, and the top-leverage few.
@@ -169,7 +177,16 @@ enforced by sage and by MR review.
 7. **Ledger + leverage.** Regenerate `ledger.md`: counts by category / target / status, and the
    **top-leverage few** (impact × ease) — the single card/SOP change that would cover the widest
    class of misses, first.
-8. **Present, don't nag, don't apply.** Surface the top few high-leverage learnings succinctly as
+8. **Mirror the summary rows (wave 4.1 — the platform "agent learnings" card).** For each entry
+   written or status-changed in step 6, call `report_learning` with the entry's SUMMARY fields
+   (`id · pattern · categories · evidence_shape · proposed_diff_target · proposed_change ·
+   status · leverage`) — AFTER the scrub step and the file write, never before. This is a
+   **projection, not a second truth** (owner 2026-07-24): the committed `.md` stays the single
+   truth; the rows only render the Activity card. Upsert by id — re-runs refresh `status`,
+   never duplicate. The server re-screens every field (enum checks, `.claude/`-only target,
+   length caps, code-fence/secret rejection) — a rejection means the entry failed the asset-free
+   gate: fix the ENTRY, don't re-word past the screen.
+9. **Present, don't nag, don't apply.** Surface the top few high-leverage learnings succinctly as
    PROPOSALS. sage never applies a diff; a human reviews the ledger, and any accepted change lands
    as a versioned, MR-reviewed card/SOP edit (bump `version:`, record the why). Silent otherwise.
 

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

@@ -155,7 +155,10 @@ retrieval index. Bodies read like a senior engineer explaining that one concept
 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,
+   (`.claude/skills/*/SKILL.md` name+description), **the harness-neutral
+   `.agents/skills/*/SKILL.md` (wave 6 — the `agentSkills` block in the JSON: one
+   convention Claude Code · Codex · Cursor all read; consent-installed by
+   `rafa update`)**, 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

package/lib/brain-repo.mjs

@@ -77,7 +77,7 @@ export function ensureBrainRepo(cwd, { requireRemote = true } = {}) {
   // (not knowledge). MERGED line-by-line so clones ignored under an older CLI
   // still gain new exclusions.
   const ignore = join(rafaDir, ".gitignore");
-  const IGNORES = ["hydration.json", "*.theirs.md", "distill-incoming/", "distill-verdicts.json", "dirty.jsonl", "reflex.jsonl", "sensor-errors.jsonl", "benchmark.demo.json"];
+  const IGNORES = ["hydration.json", "*.theirs.md", "distill-incoming/", "distill-verdicts.json", "dirty.jsonl", "reflex.jsonl", "sensor-errors.jsonl", "benchmark.demo.json", "session-facts.json", "loop-events-tail.json"];
   const cur = existsSync(ignore) ? readFileSync(ignore, "utf8") : "";
   const have = new Set(cur.split("\n").map((l) => l.trim()).filter(Boolean));
   const missing = IGNORES.filter((l) => !have.has(l));

package/lib/checkpoint.mjs

@@ -27,6 +27,62 @@ const die = (m) => {
   process.exit(1);
 };
 
+// The GIT-PLANE tail beat (0.8.16, live-catch 2026-07-24): brain deltas written
+// AFTER the last code commit (verify flips · late-authored notes · regenerated
+// manifest) have no post-commit mirror to ride, and the pre-push ceremony may
+// already have run — they strand uncommitted until the next code commit. The
+// checkpoint beat is the boundary that CREATES that tail, so it fires the SAME
+// vendored worker the git hooks run (single implementation, tail-aware since
+// 0.8.16) whenever the brain tree is dirty. One beat, both planes: "clean"
+// from this command means capture AND mirror. Best-effort — a mirror problem
+// never fails a checkpoint.
+function mirrorTail(ROOT, branch) {
+  const rafa = join(ROOT, ".rafa");
+  const worker = join(ROOT, ".claude", "rafa", "hooks", "brain-commit.mjs");
+  if (!existsSync(join(rafa, ".git")) || !existsSync(worker)) return;
+  const shR = (cmd) =>
+    execSync(cmd, { cwd: rafa, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+  let dirty = "";
+  try {
+    dirty = shR("git status --porcelain");
+  } catch {
+    return; // unreadable brain repo — the hooks' own paths will surface it
+  }
+  if (dirty === "") return; // git plane already clean — nothing stranded
+  let before = "";
+  try {
+    before = shR("git rev-parse HEAD");
+  } catch {
+    /* unborn HEAD — the worker handles it */
+  }
+  try {
+    execSync(`node "${worker}"`, { cwd: ROOT, stdio: ["ignore", "ignore", "ignore"], timeout: 60000 });
+  } catch {
+    /* worker is silent + non-blocking by design; fall through to the report */
+  }
+  try {
+    const after = shR("git rev-parse HEAD");
+    if (after !== before) {
+      let pushed = false;
+      try {
+        pushed = shR(`git rev-parse "origin/${branch}"`) === after;
+      } catch {
+        /* no remote tracking yet */
+      }
+      console.log(
+        `✓ brain mirror: session tail committed (${after.slice(0, 12)})` +
+          (pushed ? " + pushed" : " — push rides the next pre-push ceremony"),
+      );
+    } else {
+      console.log(
+        "• brain tree dirt is disposable hydration cache — nothing real to mirror",
+      );
+    }
+  } catch {
+    /* report is best-effort */
+  }
+}
+
 export default async function checkpoint() {
   const ROOT = process.cwd();
 
@@ -101,6 +157,9 @@ export default async function checkpoint() {
 
   if (candidates.length === 0) {
     console.log(`✓ working set clean on ${branch} — nothing to checkpoint`);
+    // A clean CAPTURE plane can still hide a dirty GIT plane (the live catch:
+    // "checkpoint said clean" while the session tail sat uncommitted).
+    mirrorTail(ROOT, branch);
     // Knowledge-absence nudge (live-catch 2026-07-17: a session can do real
     // work and bank ZERO knowledge, silently — no sensor fires on absence).
     // Deterministic signal only: code edits recorded, no brain delta on this
@@ -184,22 +243,29 @@ export default async function checkpoint() {
       (conflicts ? ` · ${conflicts} conflict(s) need YOUR decision (see above)` : ""),
   );
 
-  // prism-verdict backstop (harness-arc wave 0): gate-result/reflex-outcome are
-  // emitted mechanically by the CLI, but prism verdicts are LLM judgments only
-  // the session can report. The checkpoint beat — the SOP's own emit moment —
-  // checks the store and reminds while it's still empty. Best-effort, one line.
+  // Both planes, one beat: the capture sync above, the brain mirror here.
+  // (Runs before the conflict exit — a contested working set is still worth a
+  // durable mirror of the dev's current copies; .theirs.md files are ignored.)
+  mirrorTail(ROOT, branch);
+
+  // prism-verdict backstop (harness-arc wave 0) + the sage-due cache (wave
+  // 5.5): the SAME single best-effort call, enriched. It now fetches recent
+  // events (no category filter) and caches their SHAPES locally
+  // (.rafa/loop-events-tail.json — category/at only, subjects excluded) so the
+  // SessionStart digest computes "sage due" with ZERO added platform calls.
+  // The old prism-verdict reminder derives from the same response.
   try {
-    const evts = await callTool(ROOT, "get_loop_events", {
-      category: "prism-verdict",
-      limit: 1,
-    });
-    if ((evts.events ?? []).length === 0)
+    const { writeLoopCache } = await import("./loop-cache.mjs");
+    const evts = await callTool(ROOT, "get_loop_events", { limit: 200 });
+    const events = evts.events ?? [];
+    writeLoopCache(ROOT, { fetchedAt: new Date().toISOString(), events });
+    if (events.filter((e) => e.category === "prism-verdict").length === 0)
       console.log(
         "  ℹ no prism-verdict loop events recorded yet — the build SOP emits " +
           "report_loop_event(prism-verdict, PASS|ITERATE, <task id>) at each Done-check ruling.",
       );
   } catch {
-    /* unprovisioned/unreachable — the reminder is best-effort */
+    /* unprovisioned/unreachable — the reminder + cache are best-effort */
   }
   if (conflicts) process.exit(2);
 }

package/lib/distiller/doctrine.mjs

@@ -164,22 +164,11 @@ export function citesGround(content, cwd = process.cwd()) {
 }
 
 // Rewrite a survivor's frontmatter `cites:` DSL so a re-grounded citation points
-// at where the token NOW lives on main — otherwise banking it as authored would
-// fail the checker (the stale line no longer resolves). Mechanical string
-// substitution on the exact `file:line :: token` locator; untouched lines pass
-// through. Returns the rewritten content.
-export function rewriteCites(content, regroundings) {
-  let out = content;
-  for (const r of regroundings ?? []) {
-    const fromLoc = r.cite.loc; // file:line[-end]
-    const toLoc = r.to.loc; // file:line
-    // Match the DSL line `  - <fromLoc> :: <token>` and swap the locator only.
-    const esc = fromLoc.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-    const re = new RegExp(`(-\\s+)${esc}(\\s*::\\s*)`, "g");
-    out = out.replace(re, `$1${toLoc}$2`);
-  }
-  return out;
-}
+// at where the token NOW lives on main. MOVED to the gate (wave 5.3) so
+// `verify-citations --fix` can use it without an import cycle (this module
+// imports the gate's primitives, never the reverse); re-exported here so the
+// doctrine's callers keep their import path.
+export { rewriteCites } from "../gate/verify-citations.mjs";
 
 // ── folding N branch working sets into ONE run (case 1 · case 5) ────────────────
 // Input: [{ branch, capturedAtSha, mergedAt, files: [{ path, content }] }].

package/lib/doctor.mjs

@@ -79,7 +79,25 @@ export async function runDoctor(ROOT = process.cwd()) {
     }
   }
 
-  // 3 · the round-trip — the heartbeat must LAND, not just send. A recorded
+  // 3 · capabilities — every STAMPED-installed skill dependency re-verified
+  // against disk (wave 6): dir present, frontmatter parses, hashes match the
+  // bundle, license file where required. Declined/never-offered = silent.
+  {
+    const { verifyInstalled, neededSkills } = await import("./skill-deps.mjs");
+    const results = verifyInstalled(ROOT);
+    const pending = neededSkills(ROOT).length;
+    if (results.length || pending) {
+      console.log("• capabilities (skill dependencies)");
+      for (const r of results) {
+        if (r.ok) ok(`${r.name} installed + verified`);
+        else bad(`${r.name} ${r.reason}`, "re-install: `rafa update --skills`");
+      }
+      if (pending)
+        console.log(`  · ${pending} declared dep(s) not installed — offer: \`rafa update --skills\``);
+    }
+  }
+
+  // 4 · the round-trip — the heartbeat must LAND, not just send. A recorded
   // response proves key + url + repo scoping + the platform handler, end to end.
   console.log("• platform round-trip");
   if (provisioned) {