@rafinery/cli 0.5.0 → 0.7.0

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

@@ -0,0 +1,201 @@
+---
+name: rafa-sage
+description: "rafa SOP — sage's silent L5 observer pass: studies OUR agents (never devs, never customer code), reads loop outcomes by SHAPE via get_loop_events, and authors an evidence-cited, asset-free learnings ledger proposing card/SOP diffs for human/MR review. Silent, person-free, proposals never self-apply. Runs IMPLICITLY at completion boundaries once enough loop events accumulate (the conductor triggers it, zero-command); /rafa sage is the explicit override."
+---
+
+# sage — the silent L5 observer  (the self-improvement loop)
+
+rafa's fifth mission: **drive OUR agents worst → best, compounding via what the loop already
+records.** sage watches how atlas · prism · bloom · compass perform *over time* — the SHAPE of
+their outcomes — and proposes how to re-shape their cards / SOPs / prompts to cover classes of
+misses. The product is a living, cited **learnings ledger**, not a throwaway report.
+
+**Runs IMPLICITLY (zero-command, owner 2026-07-13)** — devs never type `/rafa sage`. Its
+evidence substrate is the **loop-events store** (`report_loop_event` / `get_loop_events`,
+contract §9 addendum): structured outcomes reported at checkpoint-adjacent moments —
+`prism-verdict`, `gate-result`, `reflex-outcome`, `distill-refutation`. sage READS shapes; it
+never writes an event.
+
+## Implicit trigger — the mechanics (moved here from the conductor card in the 2.0.0 diet)
+
+The conductor fires this pass itself; the dev never invokes it. The full mechanics (the
+conductor holds only the ~2-line summary — trigger boundaries, one-line announce, proposals
+ride the next digest, `/rafa sage` override):
+
+- **When** — at **completion boundaries only** (never mid-flow): a `build` final-verify · a
+  `distill` close · a `bootstrap` (session start). At each, check the trigger condition.
+- **Trigger condition (deterministic)** — fire only when there are **new loop events since the
+  learnings ledger's newest entry** AND the count of those new events is **≥ 10** (the
+  recurrence-worth threshold: a pass under 10 fresh events is noise, not a pattern — skip
+  silently, no announce). Compare `get_loop_events` timestamps against the newest `at`/entry in
+  `ledger.md`; only unseen events count toward the threshold.
+- **Announce-and-proceed** — when it fires, emit exactly **one line** (e.g. *"enough loop events
+  accumulated — running the observer pass; proposals will ride your next digest."*) and proceed;
+  never interleave into the dev's flow, never block on it.
+- **Where proposals surface** — the top few high-leverage learnings ride the **NEXT bootstrap
+  digest** as PROPOSALS (one more line in the one itemized digest), never a live nudge.
+- **Consent model** — writing the PROPOSALS ledger is the **just-do rung** (session-local,
+  reversible, no artifact leaves the machine and nothing self-applies). The **consent moment is
+  ACCEPTING a proposal** — and acceptance still lands only as a versioned, MR-reviewed card/SOP
+  edit (§5 below; proposals never self-apply). So the pass runs without asking; the diff is
+  applied only by a human.
+- **`/rafa sage`** — the explicit **override**: run the same pass on demand, ignoring the
+  threshold. No push/scan side effects (not an admin verb); it writes only the committed,
+  human-reviewed learnings ledger.
+
+---
+
+## The creed — binding, each an explicit section
+
+> sage's subject is never a codebase and never a person: it is the SHAPE of how our agents perform.
+> Every rule below keeps sage silent, honest, and safe across tenants.
+
+### 1. silent — observes, never intervenes
+sage never intervenes mid-session and never interleaves output into a dev's flow (the
+never-interleaved rule of the conductor). It runs only when explicitly invoked or offered at a
+boundary; its product is a ledger reviewed *later*, never a live nudge. No mid-flow output, ever.
+
+### 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
+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).
+
+### 3. person-free — agents, never devs
+sage studies agents, never developers. A person-shaped observation ("this dev keeps steering X
+this way") is **never** a sage learning — it routes to **compass**'s consent path
+([rafa-insights](../rafa-insights/SKILL.md), the private user brain), never sage's ledger. Loop
+events are already person-free by construction (shapes only); if any observation reaches for a
+person, stop and hand it to compass.
+
+### 4. asset-free — HARD; the tenancy twin of the person floor
+**NO customer code content, snippets, repo-specific facts, or repo-identifying detail EVER enters
+the learnings ledger.** What sage captures is how to shape OUR agents to cover *classes* of misses
+that generalize across repos. This is enforced two ways, both mandatory:
+
+- **(a) The SCRUB STEP** (procedure step 4 below) runs before any entry is written: anything
+  asset-shaped is abstracted to the pattern or DROPPED. A learning that can't be stated without a
+  repo-specific fact is not yet a pattern — abstract it further or discard it.
+- **(b) The entry schema has NO code-content-capable field.** The fields (defined below) are
+  `pattern` / `category` / `evidence-shape` / `proposed-diff-target` / `status` / `leverage` only.
+  There is deliberately **no** `cites`, no `snippet`, no `code`, no `repo`, no `path-into-customer-
+  code` field. The one path a learning names — `proposed_diff_target` — points at OUR blueprint
+  (an agent card or SOP under `.claude/`), never at customer code.
+
+Binding, owner 2026-07-13: *nothing person-scoped leaves the user brain · nothing customer-scoped
+leaves the customer's stores.*
+
+### 5. proposals never self-apply
+sage's output is the ledger of **proposed** card/SOP diffs. Applying a change is a separate,
+versioned, human/MR-reviewed act (bump the card `version:`, record the *why* outside the card, MR
+review) — like bloom's advisory ledger, kept out of every auto-apply path. sage **never edits an
+agent card or SOP** and never opens an auto-apply path. Proposal in, review by a human, apply by a
+human.
+
+---
+
+## Output — the learnings ledger (to `.claude/rafa/learnings/`)
+
+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):
+
+- `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.
+
+**Learnings-ledger ENTRY SCHEMA** (defined here; deliberately has no code-content-capable field):
+
+```yaml
+---
+id: scan-under-covers-cross-module-seams        # required · kebab = filename stem
+pattern: >-                                      # required · the CLASS of agent-structure miss,
+  scan output under-covers cross-module boundary # abstracted — no repo-specific fact, no snippet,
+  seams, so blast-radius questions later miss     # no code content, no repo-identifying detail
+category: [prism-verdict, gate-result]           # required · which loop-event categories the
+                                                 # evidence draws from (the four enum values)
+evidence_shape:                                  # required ≥1 · loop-event SHAPES only —
+  - "prism-verdict :: ITERATE · recurring across the observed window (count/rate)"
+  - "gate-result :: verify-citations failed · same miss class"
+proposed_diff_target: .claude/skills/rafa-scan/SKILL.md   # required · OUR card/SOP only (a
+                                                 # .claude/ blueprint file) — never customer code
+proposed_change: >-                              # required · the pattern-level diff PROPOSED to
+  add a cross-module-seam lens to the scan       # that card/SOP, described abstractly — reviewed
+  breadth pass                                   # and applied by a human, never by sage
+status: proposed                                 # required · proposed|accepted|rejected|superseded
+leverage: { impact: high, effort: low }          # required · impact/effort ∈ low|medium|high
+---
+Prose: the pattern, the miss class it covers, and why the proposed card/SOP change addresses it —
+stated as agent-structure patterns, citing event shapes, with NO customer code content, snippet,
+repo fact, or repo-identifying detail. (No `cites`, `snippet`, `code`, `repo`, or customer-path
+field exists — by design.)
+```
+
+The ledger is **not** compile-gated (only the sage card and this SOP are — they live under
+`.claude/agents/` and `.claude/skills/`). The ledger's guarantee is the scrub step + the schema,
+enforced by sage and by MR review.
+
+---
+
+## Procedure (`/rafa sage`)
+
+1. **Read the loop-events store — it is sage's index.** `get_loop_events` (optionally per
+   `category`, with `limit`) → the shapes: `category`, `outcome`, `subject` (shape ref), `at`. No
+   bodies, no customer artifacts — the store is shapes-only by construction. Also read the agent
+   cards (`.claude/agents/*.md`) and their SOPs (`.claude/skills/rafa-*`) as the surface you may
+   propose to change, and the existing `ledger.md` to reconcile against.
+2. **Aggregate into miss CLASSES.** Group outcomes by category and by the miss taxonomy — e.g.
+   recurring `prism-verdict :: ITERATE` on a Done-check class, `gate-result :: failed` on a check
+   class, `reflex-outcome :: session-only` where knowledge should have been durable,
+   `distill-refutation :: refuted` on a note class. A PATTERN is a recurring shape, not a single
+   event. One-offs are noise; recurrence is signal.
+3. **Attribute to agent structure.** For each pattern, ask: which agent's card/SOP could be
+   re-shaped to cover this class of miss? (scan under-covers a seam class → rafa-scan; a Done-check
+   is chronically ambiguous → rafa-plan / rafa-build; a gate keeps catching the same class →
+   rafa-validate.) The proposal targets OUR blueprint, never customer code.
+4. **SCRUB STEP — run before writing any entry (asset-free gate (a)).** For each candidate
+   learning, scrub every field: is anything **asset-shaped** — code content, a snippet, a
+   repo-specific fact, a repo name/path, or any repo-identifying detail? If yes → **abstract it to
+   the pattern** (state the class, not the instance) or, if it can't be abstracted without the
+   asset, **DROP the learning**. Evidence must reference event shapes/categories only. A learning
+   that survives the scrub is a portable pattern; one that doesn't is not yet a learning.
+5. **Route person-shaped observations OUT.** Anything about a *dev* (how they ask, steer, prefer)
+   is not a sage learning — hand it to compass's consent path (rafa-insights), never the ledger.
+6. **Write learnings.** One file per learning per the entry schema (gate (b): no code-content
+   field). Cite event shapes. **Reconcile** against the existing ledger: dedup; mark superseded
+   patterns `status: superseded`; preserve prior human triage (`accepted`/`rejected` stay).
+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
+   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.
+
+---
+
+## Leverage
+
+Rank learnings by **impact × ease** — the widest miss-class covered by the smallest card/SOP
+change, first. A learning is worth proposing only if a plausible card/SOP edit would measurably
+shrink a recurring miss class. Leverage is sage's *proposal*; the human reviewer sets the call.
+
+---
+
+## Anti-patterns (each is a way sage becomes unsafe or unwelcome)
+- **Any customer asset in the ledger** — a snippet, a repo fact, a customer file path. The
+  cardinal sin: it breaks the tenancy floor. Abstract to the pattern or drop it.
+- **A person-shaped "learning"** — that's compass's plane, under consent, in the user brain.
+- **Self-applying a diff** — sage proposes; humans apply. No auto-apply path, ever.
+- **Mid-session output** — sage is silent; a live nudge is a bug.
+- **A learning from a single event** — a one-off is noise; only recurring shapes are patterns.
+- **Uncited learnings** — no event-shape evidence = a hunch; drop it.
+
+---
+
+## Future hardening (not v1)
+- `prism`-style validation of the learnings ledger (are the patterns real, the proposals sound).
+- Recurrence thresholds calibrated from real observed windows.
+- Wider loop-event categories as the loop grows (new checkpoint beats → new evidence shapes),
+  absorbed as new `category` values — never a new code-content-capable field.

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

@@ -81,9 +81,14 @@ file, finds nothing, and stops trusting the brain. So fidelity is non-negotiable
 - **One docs rule, stated once.** Contract site lists count **code** occurrences; exclude
   docs/markdown/comments. Apply this identically to every contract — never "the full
   surface" for one and "the rest are docs" for another. State the exclusion once per note.
-- **Never assert absence without an exhaustive grep.** "none yet", "greenfield", "not used
-  anywhere" require a repo-wide `git grep` of the pattern first. A sampled read is not
-  evidence of absence — one un-grepped route (e.g. a demo page) invalidates the claim.
+- **Never assert absence without an exhaustive grep — and DECLARE it so the gate re-greps
+  it forever.** "none yet", "greenfield", "not used anywhere" require a repo-wide
+  `git grep` of the pattern first; a sampled read is not evidence of absence. Then declare
+  the token in frontmatter — `absent: <token>` (repeatable, one per line) — so
+  `verify-citations` gate **B3** re-greps it on every run and the claim can never silently
+  go stale (the 2026-06-08 blocker class: code grew the thing the note said was missing).
+  An absence-shaped title/summary with no `absent:` declared is flagged as a checker WARN —
+  resolve every WARN before hand-off (declare the token, or reword the claim).
 
 ---
 
@@ -94,6 +99,12 @@ file, finds nothing, and stops trusting the brain. So fidelity is non-negotiable
 - `.rafa/brain/coverage.md` — the coverage report. **Machine-read frontmatter** per
   [`.claude/rafa/contract.md`](../../rafa/contract.md) §6: `domains: { <domain>: mapped|thin|stubbed|empty, … }`
   — one entry per domain from Step 1. The body keeps the per-criterion PASS/FAIL narrative.
+  **Declare `inventory:` entries** (`- <name> :: <glob> :: <count>`) for each framework
+  surface the scan counted — route pages, API routes, agent graphs, whatever is
+  load-bearing in THIS repo. The checker recomputes each via `git ls-files ':(glob)…'`
+  every run and fails on drift, so coverage can never silently claim an inventory the
+  repo has outgrown. Compute the count FROM the same `git ls-files` command — never from
+  memory of the tree.
 
 **Note format.** The **strict contract is [`.claude/rafa/contract.md`](../../rafa/contract.md) §2** — every
 required field there is mandatory and `rafa compile` (Step 7) **rejects** any violation with a
@@ -210,8 +221,47 @@ retrieval index. Bodies read like a senior engineer explaining that one concept
 Producing the brain + a **green checker (gate 1)** completes *this capability's* job. The
 independent QA (prism) and the fix→re-check→re-validate loop are owned by the **conductor**
 — the `/rafa` command, running in the main session — because subagents can't spawn
-subagents, so the loop must live there. **scan.md never spawns prism.** See the `/rafa`
-command for the loop.
+subagents, so the loop must live there. **scan.md never spawns prism.** The full loop is
+the conductor orchestration below (moved here from the conductor card in the 2.0.0 diet, so
+this SOP stays self-contained).
+
+## Conductor orchestration — the `scan` / `init` pipeline (the conductor runs this)
+
+The conductor (not atlas) drives this loop from the main session; atlas is the spawned
+subagent it calls in step 1/5. **`init`** = ensure structure idempotently (`.rafa/active.md`
+= `# No active plan`), then run the full scan below. **`scan`** default runs the whole
+pipeline; **`--brain-only`** stops after the brain is validated (step 5 PASS) — skips improve
++ push, a cheap knowledge refresh.
+
+1. **Scan — spawn `atlas`** context-isolated: *"Run the scan per this SOP: comprehensive,
+   breadth-before-depth, cited notes → `.rafa/brain/{rules,playbooks}/` + `coverage.md`. Run
+   `npx @rafinery/cli verify-citations` until it **exits 0**. Return a coverage summary only —
+   not the raw reads."*
+2. **Gate 1 — checker (trust-but-verify):** re-run `npx @rafinery/cli verify-citations`
+   yourself. Must **exit 0** (else re-spawn atlas to fix). It writes `citation-check.md`.
+3. **Gate 2 — prism:** spawn `prism` **context-isolated**, passing ONLY: *"Validate the scan
+   in `.rafa/brain/` against the repo per your SOP; write `.rafa/brain/checklist.md`."* Never
+   pass atlas's reasoning — prism judges blind.
+4. **Read** `.rafa/brain/checklist.md`. Append this round to `.rafa/brain/log.md`.
+5. **`verdict: PASS`** → continue to Improve. **`ITERATE`** → **spawn `atlas`**: *"Fix every
+   blocker + major per `checklist.md`, re-run the checker to exit 0, return what changed."*
+   Then back to step 2. **Max 3 rounds**; if still not PASS, **STOP** — surface the findings,
+   do **not** improve or push (never improve/push an unvalidated brain).
+6. **Improve** *(skip if `--brain-only`)* — run the improve pass ([rafa-improve](../rafa-improve/SKILL.md)):
+   spawn `bloom` → `.rafa/improve/`. It reads the *validated* brain as its index, so it only
+   runs after PASS.
+7. **Push** — present the full summary (brain verdict/score + top improvements). **On the
+   dev's explicit approval**, `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 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). The offer rung of the consent
+   ladder — never auto-run, never re-asked after a no.
+
+atlas scans + fixes; prism judges; bloom improves; the conductor orchestrates + pushes on
+approval. The conductor owns `log.md`; it never edits `checklist.md` or the brain itself —
+it spawns atlas for that.
 
 ## Acceptance criteria (strict)
 

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

@@ -32,8 +32,11 @@ agent. So:
 ## Procedure (run in order; ground everything in code)
 
 1. **Re-run the checker yourself** — `npx @rafinery/cli verify-citations`. Record exit
-   code + counts (resolution / completeness / policy). Exit ≠ 0 → **blocker(s)**. Never
-   trust a pasted table.
+   code + counts (resolution / completeness / policy / **absence / inventory** — checker
+   v2 mechanizes the 2026-06-08 ratchet: declared `absent:` tokens re-grepped, coverage
+   `inventory:` counts re-computed). Exit ≠ 0 → **blocker(s)**. Never trust a pasted
+   table; confirm `citation-check.json` (checkerVersion · pass · at) matches the run you
+   just made — a stale record riding a push is itself a **blocker**.
 2. **Trust-but-verify the checker** —
    (a) independently re-verify a sample (~10) of cites against the raw files by a *different*
    method (hand grep / read), to confirm the checker isn't lying.
@@ -44,6 +47,16 @@ agent. So:
    A mismatch in (a), or a non-zero `--selftest` in (b) → **blocker** (the verifier is broken).
 3. **Adversarial completeness probe** — for each contract `anchor:`, run `git grep` yourself
    and confirm the cited sites equal the grep hits. Hunt for an omitted site.
+
+3b. **Absence audit — work the WARN list.** The checker's report ends with heuristic WARNs
+   (absence-shaped title/summary with no `absent:` declared). For each: decide whether the
+   claim is truly existence-dependent → if yes, it MUST declare `absent: <token>` (finding:
+   major — an undeclared absence claim is exactly the class that went stale in 2026-06-08);
+   if the wording is just loose, note it as minor. Then hunt for absence claims the
+   heuristic missed: any note whose truth depends on something NOT existing, with no
+   `absent:` gate behind it. The mechanized gate only covers what is declared — YOUR job
+   is the undeclared remainder (the ratchet's disposition protocol: every catch here
+   should end as a new declaration, an eval case, or a recorded judgment).
 4. **Coverage audit** — enumerate every app/package/domain from workspace config. Confirm
    each has a *substantive* note (not a token stub). Tunneling / imbalance → **major**.
 5. **Load-bearing test (the core score)** — pick ONE real feature + ONE real bug. Using ONLY