@rafinery/cli 0.11.0 → 0.12.0

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`
@@ -529,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-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.