@rafinery/cli 0.10.0 → 0.12.0

package/CHANGELOG.md

@@ -4,6 +4,55 @@ 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.11.0 — schema-aware reconciliation (the 4-case ladder)
+
+Distillation is where knowledge from two lineages meets — so it is now also
+where brain SCHEMA VERSIONS meet. Before any claim-level judging, the
+reconciler resolves target (the org brain) vs source (the branch's candidates)
+vs the runner's own latest schema:
+
+1. **target < source** → full target-brain rewrite onto the newer schema,
+   riding the same run's gates + push (one migration+reconcile commit).
+2. **target > source** → incoming old-schema candidates lift into the
+   target's schema before judging.
+3. **target == source, both < latest** → the merged target rewrites onto the
+   runner's latest.
+4. **target == source == latest** → plain diff reconcile — the happy flow,
+   exactly as before.
+
+Either side NEWER than the runner aborts loudly — update the runner;
+knowledge is never downgraded. Transforms are registered per step AND per
+OKF type (`lib/distiller/schema-ladder.mjs` — each step declares rule ·
+playbook · improvement explicitly: a function, or the EXPLICIT "unchanged",
+which still re-stamps the version line; derived/generated files regenerate
+at the new schema, they never migrate); a missing step or class fails
+loudly — the ladder never guesses a schema. v1 is the only schema in existence, so today
+every reconcile is case 4; this ships the SEAM (fully tested) that turns a
+future v2 into a one-entry registry change instead of a migration crisis.
+
+**Descriptive commits (owner 2026-07-26).** Reconciliation commits now SAY
+what the run did: the headless distiller composes
+`reconcile(<branch>): N banked · M refuted · K adjudication — <ids…>` and
+passes it via the new `rafa push --message=` override (the brain-for trailer
+is untouched — provenance consumers keep their key); the session SOP carries
+the same rule. And the commit contract (rafa-commit) now REQUIRES an
+agent-readable body on dev commits: what concretely changed, the why the diff
+can't show, brain-note join keys, no session deixis — the next reader of a
+commit is usually an agent.
+
+**The configurable prod branch reaches the CLI.** `trunkBranchOf` resolves
+the stamped `rafa.json → prodBranch` → git's origin/HEAD → "main"; the
+checkpoint trunk guard and the CI distill target use it (with prodBranch set,
+"main" can be a plain feature-carrying branch). The platform side shipped the
+`repos.prodBranch` setting + repo-page card in the same arc.
+
+Also in this release (landed after 0.10.0's publish): distill-refutation loop
+events carry the required actor envelope + a dedupeKey (a retried distill
+counts each resolution once); `cliActorMeta` honors `RAFA_ACTOR_RUNNER` for
+sandbox/CI attribution; and dependsOn invalidation is documented as NOT
+transitive, with breadth-of-declaration taught as the conservative pattern at
+`rafa facts add`, the CLI help, and prism's citation rule (pinned by test).
+
 ## 0.10.0 — wave 6: the capability arc (skill dependencies + agent upgrades)
 
 rafa's agents get materially better at engineering — and the mechanism is the

package/bin/rafa.mjs

@@ -18,6 +18,8 @@
 //   rafa distill --headless   CI merge-to-main distillation (org's own LLM key)
 //   rafa ci-setup             write the reconcile workflow (fold + distill on PR merge)
 //   rafa leverage             inspect your agent toolbox → proactive tips
+//   rafa audit [--json]       self-contained security engine: dep CVEs (OSV) ·
+//                             secrets (built-in ruleset) · SAST (semgrep if present)
 //   rafa benchmark            reproduce the brain-vs-cold token proof on THIS repo (measured)
 //   rafa migrate              bring structured files (plans/config) up to the current schema
 //
@@ -53,6 +55,7 @@ const COMMANDS = [
   "distill",
   "ci-setup",
   "leverage",
+  "audit",
   "benchmark",
   "manifest",
   "review",
@@ -140,6 +143,13 @@ Commands:
                        PR merge) and name the CI secrets to configure.
   leverage             Inspect your agent toolbox (permissions, skills, MCP) and print
                        prioritized tips for getting more out of it. Advisory — changes nothing.
+  audit                Self-contained security engine (rafa.audit/v1): dependency CVEs via
+                       the built-in lockfile parser + OSV.dev (pnpm audit merged in),
+                       secrets via the built-in ruleset (tracked files only, .env* never
+                       opened, fingerprints never bytes), SAST via semgrep IF present —
+                       tiers that can't run say so honestly. --json emits the envelope;
+                       writes .rafa/improve/security-audit.{json,md} when .rafa exists.
+                       Exit: 0 clean · 1 findings · 2 engine error. Installs nothing.
   benchmark            Reproduce the brain-vs-cold token-efficiency proof on THIS repo: cut
                        two isolated worktrees (A=cold, B=brain), run the same task fixture,
                        count harness tokens, emit a MEASURED benchmark.json. --dry-run

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

@@ -1,6 +1,6 @@
 ---
 name: atlas
-version: 4.0.0
+version: 4.1.0
 model: opus   # authoring is correctness-critical — a hallucinated note poisons the brain; best model, never cheap
 groundTruth: code-at-sha
 description: >-
@@ -15,7 +15,7 @@ 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)"
   - "repair :: .claude/skills/rafa-scan/SKILL.md :: every blocker + major in checklist.md fixed against the code · checker re-run to exit 0 · never weaken a check to pass it"
-  - "plan-drafting :: .claude/skills/rafa-plan/SKILL.md :: recall-grounded decomposition (coverage → search → notes) · blast radius named · contract §7 files · every child carries a Done-check"
+  - "plan-drafting :: .claude/skills/rafa-plan/SKILL.md :: recall-grounded decomposition (coverage → search → notes) · blast radius named · contract §7 files · every child carries a Done-check · the security audit runs BEFORE approval and its picture is presented to the dev verbatim (§3b — totals + blast-radius criticals; clean said out loud, never silence)"
   - "build-execution :: .claude/skills/rafa-build/SKILL.md :: implement per recalled knowledge · TDD-DEFAULT when the tdd skill + a harness are present (the Done-check is a failing test FIRST at the plan-named seam; red→green evidence in the return) · UI tasks run the installed design skills per SOP (brain conventions win) · read session-facts FIRST and bank new expensive verifications (rafa facts add) · never hand-edit brain files around the gate · return what changed, cited"
   - "scoped-refresh :: .claude/skills/rafa-scan/SKILL.md :: re-derive ONLY the dirty-cited notes against current code (input: rafa dirty --json) · same gates as scan (verify-citations exit 0) · on main: compile+push; on a branch: working-set edit + checkpoint · queue consumed only after the refresh ships"
   - "okf-surface :: .claude/skills/rafa-okf/SKILL.md :: authored files pass rafa okf check as written — body links are markdown (never wikilinks); emit-owned sections untouched"

package/blueprint/.claude/agents/bloom.md

@@ -1,6 +1,6 @@
 ---
 name: bloom
-version: 0.9.0
+version: 0.10.0
 model: opus   # a false flag mutes the whole ledger — best model, never cheap
 groundTruth: code-trend
 description: >-
@@ -15,7 +15,8 @@ color: green
 duties:
   - "improve-pass :: .claude/skills/rafa-improve/SKILL.md :: cited · prioritized P0–P3 · the architecture lens applies the deletion-test/depth method with its vocabulary (Confidence-lined candidates, first-slice-or-backlog, never big-bang) · leverage-ranked · cite-checked (unresolved dropped) · ledger + debt trend regenerated"
   - "plan-pull :: .claude/skills/rafa-plan/SKILL.md :: top-leverage OPEN improvements in the blast radius surfaced as optional child tasks — dismissible, never blocking"
-  - "build-sweep :: .claude/skills/rafa-build/SKILL.md :: newly spotted → ledger files · fixed-in-passing → status fixed · at most ONE opt-in nudge per task"
+  - "build-sweep :: .claude/skills/rafa-build/SKILL.md :: newly spotted → ledger files · fixed-in-passing → status fixed · at most ONE opt-in nudge per task · the cheap dependency tier of `rafa audit` re-runs so a mid-build lockfile change is caught"
+  - "security-profile :: .claude/skills/rafa-security/SKILL.md :: `rafa audit --json` is the engine (never LLM-pretended) · findings → category:security rows with the MECHANICAL priority map (critical→P0…dev-only→P3, annotate reachability, never downgrade) · P0 security rows are the ONE class that may surface outside the blast radius (dismissible, never blocking)"
   - "staleness-watch :: .claude/skills/rafa-improve/SKILL.md :: median open-item age stays minimal — every sweep re-validates or closes aged items; no improvement ages silently"
   - "okf-surface :: .claude/skills/rafa-okf/SKILL.md :: improvements/ledger pass rafa okf check as written · found: authored so timestamps are authored truth"
 ---

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

@@ -232,7 +232,7 @@ explicitly typed; an ACCEPTED boundary offer counts as the explicit invocation.
 |---|---|---|
 | `plan <intent>` | trio decomposition — atlas drafts brain-grounded contract §7 files (Done-checks), bloom pulls blast-radius improvements, prism validates the plan; approval → compile → `push_plan` + `set_active_plan` | [rafa-plan](../skills/rafa-plan/SKILL.md) |
 | `build` | execute the active plan per item (in `blocked_by` order): atlas recalls+implements → prism gates `status: done` on the `## Done-check` → bloom sweeps the ledger → update file + journals → checkpoint (push_plan/log_decision/`rafa checkpoint`); final verify + clear `active.md` when all children done | [rafa-build](../skills/rafa-build/SKILL.md) |
-| `improve` | spawn bloom → cited, prioritized P0–P3 ledger in `.rafa/improve/`; surface only the top few high-leverage items, never nag | [rafa-improve](../skills/rafa-improve/SKILL.md) |
+| `improve` | spawn bloom → cited, prioritized P0–P3 ledger in `.rafa/improve/`; surface only the top few high-leverage items, never nag. Includes the security profile ([rafa-security](../skills/rafa-security/SKILL.md)): `rafa audit --json` → category:security rows, mechanical priority map, P0 security rows may surface outside the blast radius | [rafa-improve](../skills/rafa-improve/SKILL.md) |
 | `scan [--brain-only]` | the full pass know → verify → improve → push — atlas maps → gate-1 checker → prism validates → iterate (max 3) → improve → push on approval → founding-scan coach offer. `--brain-only` stops after validation. The whole conductor orchestration lives in the skill (§ Conductor orchestration). | [rafa-scan](../skills/rafa-scan/SKILL.md) |
 | `init` | first run: ensure `.rafa/active.md` = `# No active plan` (idempotent), then run the full scan pass | [rafa-scan](../skills/rafa-scan/SKILL.md) |
 | `distill [<branch>]` | reconcile a merged branch's working set into the org brain — prism validates each file vs merged MAIN, atlas authors survivors through verify-citations · compile · push, refutes with cites, flags `needs-adjudication`. Offer-driven at bootstrap; CI runs it headlessly. | [rafa-distill](../skills/rafa-distill/SKILL.md) |

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

@@ -197,7 +197,8 @@ JSON. This is the exact shape the platform binds to.
     {
       "id": "dead-model-options-google-crewai",
       "priority": "P1", // P0 | P1 | P2 | P3
-      "lens": "product", // security|correctness|performance|architecture|product|ops
+      "category": "product", // security|correctness|performance|architecture|product|ops
+      "lens": "product", // transitional mirror of category (pre-2026-07-26 name) — dropped with the backfill arc
       "status": "open", // open | backlog | fixed | wontfix
       "title": "…",
       "summary": "…",
@@ -278,7 +279,7 @@ value).
 schemaVersion: 1
 id: dead-model-options-google-crewai # required · == filename stem
 priority: P1 # required · P0 | P1 | P2 | P3
-lens: product # required · security|correctness|performance|architecture|product|ops
+category: product # required · security|correctness|performance|architecture|product|ops
 status: open # required · open | backlog | fixed | wontfix
 title: Two of the four model options are dead and fail silently # required
 summary: google_genai and crewai route to unwired agents # required
@@ -295,6 +296,11 @@ found: 2026-07-02 # optional · ISO date
 Note: `title`, `summary`, `fix` are now **required frontmatter** — previously scraped
 from prose. That scraping is gone; these are authored values.
 
+`category` is the canonical field name (2026-07-26). The pre-rename name `lens`
+is accepted as a **deprecated alias** by the compile gate (`category ?? lens`,
+same enum); the manifest carries both keys during the transition. New files
+author `category:` only.
+
 ---
 
 ## 4. Health file — `brain/checklist.md`
@@ -455,6 +461,23 @@ imported comments are never scraped into decisions.
   fields do NOT bump it** — e.g. the note size stamps (`bodyTokens`,
   `cites[].targetTokens`, §1): ingest tolerates their absence, so a legacy manifest
   without them stays valid at the same `schemaVersion`.
+- **The reconciliation schema ladder (0.11.0 — owner's 4-case doctrine).** When a
+  version bump DOES ship, distillation is the upgrade moment — the reconciler
+  resolves target-vs-source-vs-runner before judging: target below source → full
+  target rewrite onto the newer schema; source below target → incoming candidates
+  lift before judging; both equal-but-old → the merged target rewrites onto the
+  runner's latest; both current → plain diff (today). Either side newer than the
+  runner → **abort loudly** (update the runner; knowledge is never downgraded).
+  Transforms are registered per step AND per OKF type in the CLI
+  (`lib/distiller/schema-ladder.mjs`): each step declares rule · playbook · improvement
+  explicitly — a function, or the EXPLICIT `"unchanged"` (still re-stamps the note's
+  `schemaVersion:`); an unregistered step or class fails loudly — the ladder never
+  guesses a schema. Class resolves by CHAIN: the governed directory first (inside the
+  transport the path IS identity — the CAS row key), then the portable filename suffix
+  (`.rule.md` · `.playbook.md` · `.improvement.md`) for files travelling outside the
+  canonical tree; a contradiction between the two is a loud error. Only durable
+  knowledge migrates; derived/generated files
+  (coverage · checklist · ledger · reports · the manifest) regenerate at the new schema.
 - **Validate-and-correct:** `rafa compile` validates every file. On failure it emits
   a structured error — `path · field · rule` — to the **authoring agent** (atlas for
   notes, bloom for improvements/ledger, prism for checklist). The agent edits the
@@ -512,9 +535,9 @@ i.e. the default branch's instance).
 
 **Search = deterministic lexical retrieval; the server retrieves, the agent decides.**
 Fields searched per type — rule/playbook: `title, summary, domain, type` ·
-improvement: `title, summary, lens, blast_radius` · plan: `title, plan, parent`.
+improvement: `title, summary, category, blast_radius` · plan: `title, plan, parent`.
 Score = Σ over matched case-folded query tokens of field weight (`title` 3 ·
-`domain`/`lens`/`blast_radius`/`type`/`plan`/`parent` 2 · `summary` 1); tie-break
+`domain`/`category`/`blast_radius`/`type`/`plan`/`parent` 2 · `summary` 1); tie-break
 score desc then id asc; fields a type lacks are omitted, never defaulted. Candidates
 carry `matchKind: "lexical"` (`"semantic"` reserved).
 

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

@@ -43,7 +43,11 @@ platform MCP (one read path — the same surface any third-party agent uses).
    [rafa-commit](../rafa-commit/SKILL.md) format — `[<task-id>] <type>:
    <subject>` (the id join-key; intent records + the branch manifest lift it
    into per-note provenance)** → prism validates vs `## Done-check` →
-   bloom sweeps (push new / close fixed / nudge) → update the child file's `status`
+   bloom sweeps (push new / close fixed / nudge; **when THIS task changed a
+   lockfile/manifest, re-run the cheap dependency tier — `rafa audit --json` —
+   and report the delta to the dev in one transparent line: new/cleared
+   findings, never silence**; a new critical → a `category: security` P0 row
+   surfaced now) → update the child file's `status`
    **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

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

@@ -36,6 +36,28 @@ description: "rafa SOP — generate the commit message with the id join-key: the
    outcome one-line ("Done-check: prism PASS") — the receipt travels with the
    code.
 
+## The body is REQUIRED and written for an AGENT reader (owner 2026-07-26)
+
+A subject-only commit is a broken contract here. The next reader of this
+message is most often an AGENT — ours (atlas recalling why a line exists, the
+distiller judging a claim against this change, sage reading shapes) or a
+foreign one — so the body must be SELF-CONTAINED and joinable:
+
+- **What, concretely** — the surfaces/behaviors that changed, named (not
+  "various fixes"); a reader must know the blast radius without the diff.
+- **Why — the intent** — the one thing the diff cannot show. State the
+  problem/decision that made this change necessary; paraphrase the pivotal
+  choice if one was made (it should also be a `log_decision`).
+- **Join keys** — mention the brain notes this change follows or invalidates
+  (`per rule <id>` / `staleness: touches <id>`), so the cite-graph and the
+  dirty queue read straight out of the log.
+- **No session deixis** — never "as discussed", "per the above", "the same
+  fix as before": the message must stand alone in `git log` a year later,
+  with zero conversation context.
+
+TDD-default red commits keep their fixed form (`[<task-id>] test: red —
+<seam>`) — the seam IS the body's content there.
+
 ## Why this exists (don't skip the bracket)
 
 The brain-commit hook captures every subject into `intent/<sha>.md`;

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

@@ -39,6 +39,28 @@ code it describes.
 1. **Collect** — `get_working_set(repo, branch, status: active)`. Zero files →
    nothing to do, say so, stop. Rows already `needs-adjudication` are a HUMAN's
    to resolve — surface them in the digest, never fold them in silently.
+1b. **Schema ladder (0.11.0 — the owner's 4-case doctrine).** Before ANY
+   claim-level judging, resolve the version lattice: **target** = the org
+   brain's `manifest.json → schemaVersion` (else max over its notes; a
+   pre-manifest brain is the founding v1) · **source** = max over the
+   collected candidates' own `schemaVersion` · **latest** = the running CLI's
+   `SCHEMA_VERSION`. Then: **target < source → REWRITE-TARGET** (every org-
+   brain note lifts to the newer schema and rides THIS run's gates + push —
+   one migration+reconcile commit) · **target > source → UPGRADE-SOURCE**
+   (incoming candidates lift into the target's schema before judging) ·
+   **equal but < latest → REWRITE-MERGED** (both lift; the merged target is a
+   full rewrite onto latest) · **equal and == latest → DIFF** (the happy flow,
+   steps 2–6 exactly as written). **Either side > latest → ABORT LOUDLY** — a
+   newer CLI authored it; update the runner, knowledge is never downgraded.
+   Transforms are REGISTERED per step AND per OKF type
+   (`lib/distiller/schema-ladder.mjs` — each step declares rule · playbook ·
+   improvement explicitly: a function, or the EXPLICIT "unchanged", which
+   still re-stamps the note's schemaVersion line); a missing step OR class is
+   a loud error, never a guess. Only durable knowledge ladders — derived/
+   generated files (coverage · checklist · ledger · reports · manifest)
+   REGENERATE at the new schema; intent records pass through untouched. The
+   headless CLI runs this mechanically; the session path applies the same
+   lattice by hand.
 2. **Validate (prism, context-isolated)** — the target is **merged MAIN as of
    NOW, never the fork point and never a stale checkout**: `git fetch origin`
    first; judge every claim against the fetched trunk. Confirm every citation
@@ -51,7 +73,13 @@ code it describes.
    files lost it — re-declare); fold into an existing note when one covers the
    topic (supersede, never duplicate).
 4. **Gate + ship** — `rafa verify-citations` AND `rafa compile` to exit 0 →
-   `rafa push`. Only now has anything entered the org brain. A failed gate
+   `rafa push --verb=distill --message="reconcile(<branch>): <N> banked ·
+   <M> refuted · <K> adjudication — <banked ids…>"`. The reconciliation
+   commit is DESCRIPTIVE (owner 2026-07-26): its subject states what THIS run
+   did — branch, per-verdict counts, the banked note ids — so any agent
+   walking the brain log understands the commit without opening it (the
+   headless CLI composes this automatically; the session path passes it
+   explicitly). Only now has anything entered the org brain. A failed gate
    aborts EVERYTHING: nothing resolved, nothing pushed, working set intact.
 5. **Resolve** — `resolve_working_file(path, distilled)` for survivors — authored
    per the OKF surface ([rafa-okf](../rafa-okf/SKILL.md); push emits the rest) —
@@ -61,9 +89,14 @@ code it describes.
    which files died and why (cited); refutation is feedback, not silence. At
    that same resolve beat emit **`report_loop_event(category:
    "distill-refutation", outcome: refuted|distilled, subject: <path or note
-   id>)`** — sage's evidence that a claim met the gates or was refuted (shapes
-   only: the outcome + a file/note reference, never the refuted content, never
-   the cited code). Checkpoint-adjacent, monotonic, never a session-end sweep.
+   id>, actorMeta: {model: <the judging model>, agent: "distiller@<ver>" (or
+   "prism@<ver>" on the session path), runner: session|ci|sandbox — the tier
+   this distill runs in}, dedupeKey: "<branch>·<path>·<outcome>")`** — sage's
+   evidence that a claim met the gates or was refuted (shapes only: the
+   outcome + a file/note reference, never the refuted content, never the
+   cited code). Wave 5 is STRICT: an emit without the actor envelope is
+   rejected loudly; the dedupeKey makes a re-run of the same distillation
+   count ONCE. Checkpoint-adjacent, monotonic, never a session-end sweep.
    `resolve_working_file(path, needs-adjudication, note)` for the undecidable —
    the next session's digest offers the decision.
 

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

@@ -50,7 +50,7 @@ Invoke via `/rafa improve`. The brain (#1) must exist — bloom *uses* it as the
 ## Output (to `.rafa/improve/`)
 
 - `improvements/<id>.md` — one file per improvement (cited, prioritized, status-tracked).
-- `ledger.md` — generated index: counts by priority/lens/status + the **health/debt trend**.
+- `ledger.md` — generated index: counts by priority/category/status + the **health/debt trend**.
   Its **frontmatter carries the machine-read `open` · `debt_score` · `by_priority`** (per
   [`.claude/rafa/contract.md`](../../rafa/contract.md) §5) — the platform reads *that*, never the body tables,
   and `rafa compile` cross-checks `open`/`by_priority` against the actual improvement rows.
@@ -65,7 +65,7 @@ platform shows them; nothing is scraped from prose). Example *illustrative — f
 schemaVersion: 1
 id: rsc-route-level-use-client              # required · kebab = filename stem
 priority: P1                                # required · P0|P1|P2|P3
-lens: architecture                          # required · security|correctness|performance|architecture|product|ops
+category: architecture                      # required · security|correctness|performance|architecture|product|ops (pre-2026-07-26 name `lens` is a deprecated alias)
 status: open                                # required · open|backlog|fixed|wontfix
 title: Route-level "use client" silently disables RSC   # required
 summary: A route-level directive kills RSC down the whole subtree; no gate catches it   # required
@@ -109,9 +109,15 @@ convention — see [RSC client boundary](/brain/rules/rsc-client-boundary.md)).
      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.
+3. **The security profile.** Run `npx @rafinery/cli audit --json` — the SELF-CONTAINED
+   engine (dep CVEs via the built-in OSV client + pnpm audit; secrets via the built-in
+   ruleset; SAST via semgrep only if present — a tier that didn't run says `ran:false`).
+   Then follow [rafa-security](../rafa-security/SKILL.md): findings → `category: security`
+   rows with the MECHANICAL priority map (critical→P0 · high→P1 · moderate→P2 ·
+   low/dev-only→P3), reachability annotated from the brain's domain map but never
+   downgraded, same-fix CVEs grouped into one row. The LLM pass (authz per route,
+   webhook verification, input validation) is observational only — never present it
+   as an authoritative audit.
 4. **Write improvements.** One file per improvement, cited (`file:line :: token`), prioritized,
    leverage-ranked. **Reconcile** against the existing ledger: dedup; **auto-close** improvements
    whose code is now clean (`status: fixed`); **preserve** the dev's prior triage
@@ -119,7 +125,7 @@ convention — see [RSC client boundary](/brain/rules/rsc-client-boundary.md)).
 5. **Cite-check (the fidelity gate).** Run
    `npx @rafinery/cli verify-citations --root=.rafa/improve --dirs=improvements`. Every cite
    must resolve; **drop or fix any that don't** — a hallucinated improvement is the cardinal sin.
-6. **Ledger + trend.** Regenerate `ledger.md`: counts by priority/lens/status + a **debt
+6. **Ledger + trend.** Regenerate `ledger.md`: counts by priority/category/status + a **debt
    score** (weighted open improvements) and its trend vs the last run — the compounding made
    visible. Write the machine-read **frontmatter** `open` · `debt_score` · `by_priority`
    ([contract §5](../../rafa/contract.md)) — the platform reads that.
@@ -167,6 +173,11 @@ in that area and nudge once — *"2 P1s here, one's a 10-min fix — take it whi
 ranked by leverage, **dismissible, never blocking.** Not built here; this capability produces
 the ledger the nudge will read.
 
+**The one exception to blast-radius scoping: `category: security` P0s.** A critical
+CVE lives in no file the dev is touching, so a P0 security row may surface at
+plan/build boundaries regardless of region — one line, dismissible, never blocking,
+never re-nagged in the same session.
+
 ---
 
 ## Anti-patterns (each is a way bloom gets muted)

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

@@ -50,7 +50,7 @@ Conformance is our distribution wedge; verification stays the moat.
 | Agent | Files | What OKF-native means for you |
 |---|---|---|
 | **atlas** | `brain/rules/` · `brain/playbooks/` · `brain/coverage.md` | author `type` (§2 enum) + `title` + `summary` as ever; body cross-links as markdown links; optionally author `description`/`tags` — emit derives them from `summary`/`domain` if you don't |
-| **bloom** | `improve/improvements/` · `improve/ledger.md` | same; your files gain `type: Improvement` + `tags: [lens, priority]` at emit — author `found:` so timestamps are yours, not git's |
+| **bloom** | `improve/improvements/` · `improve/ledger.md` | same; your files gain `type: Improvement` + `tags: [category, priority]` at emit — author `found:` so timestamps are yours, not git's |
 | **prism** | `brain/checklist.md` | verdict frontmatter as ever (emit stamps `type: Health Report` + a derived description); at validation, treat the checker's LINKS warns as a worklist — dangling links are claims of future knowledge |
 | **sage** | `.claude/rafa/learnings/` | learnings are OKF concepts too: frontmatter + `type: Learning` + markdown links; outside the bundle but under the same protocol |
 | **conductor / plan·build** | `plans/**` · `brain/log.md` | plan items gain `type` from `kind` at emit (per-epic `plans/index.md`); journals + bodies use markdown links; `log.md` stays the reserved trail |

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

@@ -23,7 +23,9 @@ Planning is a choreography, not one agent (spec: knowledge-mcp-build-agent):
   the tools; the dev never asks for it. Repo not platform-connected (no `rafinery`
   MCP in the session)? Fall back to reading `.rafa/brain/` files directly — same
   knowledge, just unserved.*
-- **bloom pulls** — `list_improvements` in the blast radius; surface the
+- **bloom pulls** — `list_improvements` in the blast radius (PLUS any open
+  `category: security` P0 regardless of region — the one class that travels;
+  one line, dismissible, never blocking); surface the
   top-leverage open items as optional *"while-you're-here"* child tasks
   (leverage-ranked, dismissible, never blocking). **Any improvement the plan
   ADOPTS (as a task or the plan's very subject) is hydrated NOW** —
@@ -100,6 +102,17 @@ Planning is a choreography, not one agent (spec: knowledge-mcp-build-agent):
    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.
+3b. **Security transparency** (2026-07-26 r2 — "security is not an aftermath").
+   Run `npx @rafinery/cli audit --json` (seconds; reuse a same-session
+   `security-audit.json` if fresh) and present the picture TO THE DEV, verbatim
+   and unburied, before the plan is approved: one line of severity totals +
+   which tiers ran, then any critical/high finding whose package or file sits
+   in THIS plan's blast radius (per [rafa-security](../rafa-security/SKILL.md)'s
+   reachability method). A blast-radius critical/high → propose it as a plan
+   child task (the fix rides the work); open `category: security` P0s surface
+   regardless of region. Transparent means: the dev sees the counts even when
+   everything is clean — "dependency tier clean at <sha>" is one honest line,
+   never silence.
 4. **Leverage-match** — recommend existing skills/tools/MCP that fit the tasks;
    never plan to hand-roll what a capability already does.
 5. **prism plan-validation** → REJECT/fix loop until clean.

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

@@ -201,6 +201,13 @@ retrieval index. Bodies read like a senior engineer explaining that one concept
 6. **Flow tracing** [LLM, cited] — from each entry point, hop-by-hop to termination
    (render / DB write / response) → `flow` playbooks. Add `how-to` playbooks for the
    recurring "add X" procedures these flows imply.
+   **One `security-posture` playbook is required** (2026-07-26): the repo's trust
+   boundaries (what's server-exposed vs build-time), auth chokepoints (where
+   authz is enforced — cited), and the secret-handling convention (where env
+   names are read; names only, per the step-4 guardrail). This is durable
+   KNOWLEDGE, not findings — it grounds bloom's security profile
+   ([rafa-security](../rafa-security/SKILL.md)): reachability annotations on
+   CVE rows come FROM this note's map.
 
 7. **Verification & synthesis** — apply the 100× filter (a note earns a file only if it
    answers a work-time question AND eliminates a recurring tax), then write the notes. Run
@@ -255,7 +262,8 @@ pipeline; **`--brain-only`** stops after the brain is validated (step 5 PASS)
    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.
+   runs after PASS. The security profile rides this step ([rafa-security](../rafa-security/SKILL.md):
+   `rafa audit --json` → category:security rows) — every scan carries it; no separate command.
 7. **Prove it — the measured benchmark** *(skip if `--brain-only`; skip if
    `.rafa/benchmark.json` already carries `measured: true` for this repo)* —
    the proof engine is WORKFLOW-WOVEN, never a dev-typed command (owner

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

@@ -0,0 +1,96 @@
+---
+name: rafa-security
+description: "rafa SOP — the security profile: run the self-contained `rafa audit` engine (dep CVEs via OSV · secrets · SAST if present), brain-ground reachability, author category:security improvements with the mechanical priority map, emit the profile. Loaded by bloom/the conductor at profiling moments (scan's improve pass, build-time sweep) — NEVER a dev-typed verb."
+---
+
+# security — the profile  (woven, never a command)
+
+rafa's security posture is **woven into the loop, not a chore**: the dev never
+types a security command. Owner doctrine (2026-07-26 r2): *"security is not an
+aftermath — it is an integral part of the development cycle."* The engine
+fires at every moment of that cycle:
+
+- **plan** — the audit runs before approval and its picture is presented to
+  the dev verbatim (rafa-plan §3b): totals + blast-radius criticals; clean is
+  said out loud, never implied by silence.
+- **build** — a task that touches the lockfile re-runs the cheap dep tier and
+  reports the delta in one line (rafa-build §2).
+- **improve / scan** — the full three-tier profile (this SOP's procedure below).
+- **every merge** — branch→branch merges get a platform-side dep audit at fold
+  time; canonical merges get the reconcile graph's security lane. Both mint
+  Security-tab rows — freshness at every level, not just prod.
+
+Findings land as ordinary contract §3 improvements with `category: security`;
+the platform's Security tab reads the merge-level rows.
+
+## The engine — deterministic first, always
+
+Run **`npx @rafinery/cli audit --json`** and parse the `rafa.audit/v1`
+envelope. The engine is SELF-CONTAINED — it needs no installs, ever:
+
+- **dependency** — built-in pnpm-lock parser + the OSV.dev advisory API,
+  merged with `pnpm audit`; per finding: package · GHSA/CVE + aliases ·
+  severity + CVSS · direct-vs-transitive chain · fixed-in · dev-only flag.
+- **secrets** — built-in curated ruleset over tracked files (`.env*` never
+  opened; fingerprints, never secret bytes). gitleaks enhances if present.
+- **sast** — semgrep if installed (pinned `p/security-audit`), otherwise the
+  envelope says `ran:false` with the reason. semgrep/gitleaks are OPTIONAL
+  enhancers; mention their value once when relevant (`rafa doctor` shows
+  install hints) — installing is always the dev's own consented choice.
+  **Never LLM-pretend a tier that did not run** — `tiers.<t>.ran` is the truth.
+
+## Findings → improvements (the mechanical part)
+
+One §3 improvement file per finding worth a row (group same-package CVEs into
+one row when they share the fix — one lockfile bump = one improvement).
+Required frontmatter as ever (`title` · `summary` · `fix` · `leverage` ·
+`cites`), plus:
+
+- `category: security` — always.
+- **Priority maps mechanically, never by vibe**: critical → P0 · high → P1 ·
+  moderate → P2 · low or dev-only (`dev:true`) → P3. The LLM may ANNOTATE
+  (see below) but **never downgrades** a mapped priority.
+- `fix:` carries the concrete path: the upgrade target (`fixedIn`), whether the
+  dep is direct (bump it) or transitive (dedupe/overrides/parent-bump), the
+  secret's rotation step. Comprehensive detail (chain, refs, CVSS) rides the
+  body — machine-sourced from the envelope, never re-guessed.
+- Dependency-tier rows cite the lockfile/manifest line that pins the package;
+  secret/sast rows cite the `file:line` from the finding.
+
+**Reconcile like any improvement**: dedupe against existing rows by the stable
+finding id (in the body); auto-close rows whose finding vanished from a fresh
+audit (`status: fixed` — the lockfile bump landed); preserve the dev's triage
+(backlog/wontfix stay).
+
+## Brain-ground the reachability (the judgment part)
+
+The brain's domain map is what raw scanners lack. For each dependency finding,
+answer from the brain — *is this package on a server-exposed path?* (API
+routes, webhook handlers, auth boundary) — and write the answer into the body
+as an annotation: `Reachability: server-exposed via <domain> — see
+[<note>](/brain/...)` or `Reachability: build-time only`. Cited, observational,
+and **priority-neutral** — it informs the dev's triage, it never overrides the
+mechanical map.
+
+The wider observational pass (authz per route, webhook verification, input
+validation against the brain's contracts) belongs to the improve SOP's
+security lens — cited `file:line`, labeled observational, never presented as
+SAST output.
+
+## The P0 exception — the one row that travels
+
+Improvement nudges are blast-radius-scoped — EXCEPT `category: security` P0s:
+a critical CVE lives in no file the dev is touching, so a P0 security row may
+surface at plan/build boundaries regardless of region. Still one line, still
+dismissible, never blocking, never re-nagged in the same session.
+
+## Anti-patterns
+
+- Running the engine and PARAPHRASING its output into rows without the
+  envelope's fields — the detail is machine-sourced or it doesn't ship.
+- Downgrading a mapped priority because it "seems fine" — annotate, never
+  downgrade.
+- A wall of per-CVE rows for one package — group by shared fix.
+- Presenting the observational pass as scanner output.
+- Asking the dev to install semgrep/gitleaks more than once — the doctor
+  carries the hint; a decline stands.