@kiwidata/grimoire 0.1.3 → 0.1.5

package/skills/grimoire-verify/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: grimoire-verify
-description: Verify that implementation matches feature specs and decision records. Use after apply is complete, before archiving the change.
+description: Verify that implementation matches feature specs and decision records. Use after apply is complete, before committing and opening a PR.
 compatibility: Designed for Claude Code (or similar products)
 metadata:
   author: kiwi-data
@@ -9,11 +9,11 @@ metadata:
 
 # grimoire-verify
 
-Verify that implementation matches the feature specs and decision records. Run after apply, before archive.
+Verify that implementation matches the feature specs and decision records. Run after apply, before commit and PR.
 
 ## Triggers
 - User wants to verify a grimoire change is correctly implemented
-- User asks to check, verify, or review a change before archiving
+- User asks to check, verify, or review a change before committing
 - Loose match: "verify", "check", "review" with a change reference
 
 ## Routing
@@ -170,6 +170,36 @@ Check for features that exist in specs but may no longer be implemented:
 - Step definitions with `pass` or `NotImplementedError` bodies
 - Features tagged `@skip` or `@wip` that have been in that state for a long time
 
+### 6b. Code Quality Audit
+
+For every production file changed in this implementation, run an independent quality check — not a re-read of what the implementing agent self-reported.
+
+**A. Walk the seven-point checklist from `../references/code-quality.md` on each changed file:**
+
+1. **Reuse before write** — any new helper/function that duplicates existing code? Flag the duplicate and the existing function.
+2. **Branching budget** — any function with more than ~7 branches (`if`/`else`/`case`/ternary/`&&`/`||`)? Name it and count.
+3. **Function size** — any function body over ~30 lines? Flag it. "One job per function" — if the name needs "and", it's two functions.
+4. **Defensive code inside trust boundary** — `if x is None` guards on non-nullable types, `isinstance` checks on values the codebase just built, `try/except` with no real recovery? Flag each.
+5. **Names** — any local named `data`, `result`, `temp`, `info`, `obj`, `item`, or `value` when a specific name would fit?
+6. **Premature abstraction** — any new `BaseX`, factory, strategy, config object, or registry pattern with a single caller? Any wrapper function that only renames arguments?
+7. **Comments** — any comment that restates the code (`# loop over users`), references the current task/PR/ticket, is a multi-line docstring on a private function, or whose removal would not confuse a future reader?
+
+**B. Classify findings:**
+- **[critical]** — premature abstraction (new base class / factory / strategy for one caller), or dead code (function/class written but never called)
+- **[warning]** — function too large, too many branches, defensive guards inside trust boundary, generic names
+- **[suggestion]** — comment noise, minor naming issue
+
+**C. Report format:**
+```
+## Code Quality
+- [ ] **[critical]** `src/auth.ts:12` — `BaseTokenValidator` has one subclass; inline it
+- [ ] **[critical]** `src/auth.ts:88` — `_validate_helper` never called outside `validate()`; inline it
+- [ ] **[warning]** `src/auth.ts:45` — `process_request` is 62 lines with 9 branches; split by responsibility
+- [ ] **[suggestion]** `src/auth.ts:31` — comment "# check if token is expired" restates the code; remove
+```
+
+If no issues: `## Code Quality — clean`.
+
 ### 7. Generate Report
 Produce a structured report:
 
@@ -190,6 +220,9 @@ Produce a structured report:
 - [ ] **[critical]** [OWASP/CWE tag] <violation> — `file:line`
 - [ ] **[warning]** [OWASP/CWE tag] <concern> — `file:line`
 
+## Code Quality
+- [ ] **[critical/warning/suggestion]** <issue> — `file:line`
+
 ## Warnings
 - [ ] <issue description> — `file:line`
 
@@ -203,8 +236,8 @@ Produce a structured report:
 
 ### 8. Recommend Next Steps
 Based on the report:
-- **All clear** → recommend archiving the change
-- **Critical issues** → must fix before archiving
+- **All clear** → recommend committing and opening a PR (git diff is the staging area, the PR is the changelog)
+- **Critical issues** → must fix before committing
 - **Warnings only** → user decides whether to fix or accept
 - **Dead features found** → suggest a removal change or updating the features
 
@@ -218,6 +251,6 @@ Based on the report:
 
 ## Done
 When the verification report is presented, the workflow is complete. Suggest next steps based on findings:
-- **All clear** → `grimoire archive <change-id>` or `grimoire-pr`
-- **Critical issues** → must fix before archiving
+- **All clear** → `grimoire-commit` then `grimoire-pr`
+- **Critical issues** → must fix before committing
 - **Warnings only** → user decides whether to fix or accept

package/skills/grimoire-vuln-remediate/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: grimoire-vuln-remediate
+description: File the dev work from a vulnerability triage — turn affected findings into tickets in the configured bug tracker, record risk-accepted items with expiry, and stub grimoire changes for non-trivial fixes. Consumes a grimoire-vuln-triage record. Use after triage, when you're ready to action the findings that actually matter.
+compatibility: Designed for Claude Code (or similar products)
+metadata:
+  author: kiwi-data
+  version: "0.1"
+---
+
+# grimoire-vuln-remediate
+
+`grimoire-vuln-triage` decides *what matters*. This skill **files the work** for the findings that survived: it turns `affected` advisories into tickets in the team's configured bug reporting system, records `accept` items in a risk-acceptance register with an expiry, and stubs a grimoire change for fixes too big to be a one-line bump. It never invents urgency — it acts on the triage's verdicts.
+
+The split is deliberate: triage classifies (read-only, repeatable), remediate commits to action (writes tickets, branches, registers). Run triage first.
+
+## Triggers
+- After triage: "file these", "create the tickets", "remediate the CVEs", "action the vuln triage"
+- "open tickets for the affected vulnerabilities", "track the risk-accepted ones"
+- User points at a triage record and asks to take it forward
+- Loose match: "vuln remediate", "file vulnerabilities", "security tickets", "remediation plan"
+
+## Routing
+- No triage record yet → `grimoire-vuln-triage` first. Do not file tickets off a raw scanner dump — file only what triage marked `affected`.
+- A fix that's a real code change (new abstraction, behavior change, schema) → stub a change and hand to `grimoire-draft` / `grimoire-plan` / `grimoire-apply`.
+- A confirmed-exploitable code defect a developer will fix immediately → `grimoire-bug` (reproduction-first).
+- Infra follow-ups (base-image bump, secrets-in-image, IaC misconfig from the triage's "Infra follow-ups") → infra board / `grimoire-draft`, not app remediation.
+
+## Prerequisites
+- A triage record at `.grimoire/security/vulns/<run-date>/triage.md` (from `grimoire-vuln-triage`). If the user points at a different path, use it.
+- `.grimoire/config.yaml` — read `bug_trackers` (MCP) for where to file. If `none`, fall back to a local remediation doc.
+
+## Workflow
+
+### 1. Read the triage record
+
+Load the triage. Pull the actionable buckets — **ignore `fixed` and `not_affected`** (triage already dismissed them; they are the audit trail, not work):
+- **hotfix-now** — expedited, confidential handling.
+- **next-release** — normal release-cycle work.
+- **accept** — no fix available / low risk → goes to the risk-acceptance register, not a fix ticket.
+- **under_investigation** — file a time-boxed investigation task, not a fix. **Does not enter the risk register** — it isn't a decision yet. When the investigation resolves, re-run remediate so it routes to close / ticket / register.
+- **Infra follow-ups** — route separately (Step 5).
+
+Cross-check the record's totals against what you're about to file so nothing is dropped or invented.
+
+### 2. Decide the fix type per affected item
+
+For each `affected` advisory, classify the remediation so it routes correctly:
+- **Trivial bump** — a patch/minor version with a fix exists (`upgrade X 1.2.3 → 1.2.4`), no API break. Can be a direct PR or a simple ticket.
+- **Non-trivial fix** — major-version bump, code changes, base-image rebuild, or a transitive dep that needs a constraint/override. Needs design → stub a grimoire change (Step 4).
+- **No fix available** — `will_not_fix` / no fixed version. Not a fix ticket → risk-acceptance register with an expiry (Step 3). Never file an "upgrade X" ticket when no fixed version exists.
+
+### 3. File the work into the configured bug reporting system
+
+Read `bug_trackers` in `.grimoire/config.yaml`.
+
+**If a tracker MCP is configured (Jira / Linear / GitHub):**
+- **Idempotency first** — search the tracker for the CVE/GHSA id before creating anything. If a ticket exists, update it (link the triage, refresh urgency); don't duplicate. Mirror both directions like `grimoire-bug-triage`.
+- **One ticket per advisory** (or per package-upgrade when several CVEs share one bump — group by the fix, not the CVE). Include: id(s), component + version, fixed version / action, urgency, reachability + exposure summary, and a link back to `.grimoire/security/vulns/<run-date>/triage.md`. Set priority from urgency (hotfix-now → highest).
+- **hotfix-now is confidential** — mirror `grimoire-bug-triage` §7. Do **not** post exploit details, reachability specifics, or a step-by-step in a public tracker. If the tracker is public, the ticket states impact + "fix in progress, details held privately"; the detail stays in the local triage record. Notify the security owner out of band. Recommend an expedited branch (non-descriptive name) + out-of-band release.
+- **under_investigation** → a time-boxed task ("confirm reachability of <CVE> in <path> by <date>"), assigned, with the open question from triage.
+
+**If `bug_trackers: none`:**
+- Write `.grimoire/security/vulns/<run-date>/remediation.md` — a checklist: one entry per actionable item with `[ ]` checkbox, id(s), action (exact upgrade or change-stub link or accept-ref), urgency, suggested owner, and the triage link. This is the deliverable the team works from until a tracker exists. Tell the user where it is.
+
+### 4. Stub a grimoire change for non-trivial fixes
+
+For each non-trivial fix, create `.grimoire/changes/<change-id>/manifest.md` so the normal build workflow takes over:
+- Frontmatter `status: proposed`, plus `source: vuln-triage`, the CVE id(s), and the triage path.
+- **Why**: the vulnerability + why a one-line bump isn't enough (major break, code path affected, transitive constraint).
+- **Scope**: the upgrade/change needed and the blast radius from triage (which code paths touch the vulnerable surface).
+- Point the user at `grimoire-draft` / `grimoire-plan` to continue. Reference the change-id from the ticket so the trail is intact.
+
+### 5. Record risk-accepted items (with expiry)
+
+**Register invariant: only a settled `accept` verdict enters the register.** The register means "we triaged this, decided, and consciously accepted the residual risk." Two states must stay out of it:
+- **`under_investigation`** — not decided yet. It gets an investigation task (Step 3), nothing in the register. The register's `vex_justification` must be a real VEX code, not "pending"; a finding you can't yet justify hasn't been accepted. When the investigation resolves, *then* it routes — to `not_affected` (close), `affected` (ticket/change), or `accept` (register).
+- **`not_affected`** — already dismissed by triage, deterministically, every scan. It needs no register entry; adding one would bloat the register with the unreachable os-package noise the reachability verdict already suppresses.
+
+For every settled `accept` item, append to `.grimoire/security/accepted-risks.yml` (create from the template if absent). Each entry: `cve`, `component`, `vex_justification` (a real code), `reason` (why it's acceptable — reachability/exposure/no-fix), `owner`, `accepted` date, and an **`expires`** date (when to re-triage — sooner for higher residual risk, default ~90 days). An accepted risk is not closed — it's scheduled for re-evaluation.
+
+**This register is read back by `grimoire-vuln-triage` during reconciliation** — an unexpired entry auto-suppresses that CVE as a known-accepted, so the same finding doesn't re-flood the queue next scan. An **expired** entry is re-surfaced for re-triage. Don't accept the same CVE twice; update the existing entry.
+
+A no-fix os-package finding that is genuinely **`affected` and accepted** (reachable, no patched base yet) belongs here — with `component_type: os-package` and the trace summary from `container-scan-triage.md`. One that is **`not_affected`** (unreachable, like a headless API's GPU/terminal libs) does **not**.
+
+### 6. Optionally execute trivial bumps (skippable)
+
+Offer — don't assume — to apply trivial bumps directly: edit the manifest pin, run the lockfile update (`uv lock` / `npm install` / etc.), and run the configured `dep_audit` to confirm the advisory clears. Keep it on a branch. This step is **opt-in**; if the user just wants tickets, file and stop. If you do apply, the supply-chain rules in `security-compliance.md` still hold (committed lockfile + integrity hashes).
+
+### 7. Report and update the record
+
+Update the triage record (or a sibling `remediation.md`) with what was filed: ticket refs, change-ids, register entries. Report the headline:
+- N tickets filed (M hotfix-now expedited), K risk-accepted (next review dates), J change stubs, I investigations.
+- Any hotfix-now: restate it's flagged for the security owner and expedited.
+- Where the artifacts are (tracker links / local docs / register).
+
+## Important
+- **Act only on triage verdicts.** This skill files what triage marked `affected` / `accept` / `under_investigation`. It does not re-triage, re-rank, or escalate on its own. If a verdict looks wrong, send it back to `grimoire-vuln-triage`, don't override it here.
+- **No fixed version → no upgrade ticket.** A `will_not_fix` / no-fix finding goes to the risk register with an expiry, or to infra for a base bump. Filing "upgrade X" when X has no fix wastes a developer's time.
+- **Group by the fix, not the CVE.** One upgrade often clears several advisories — one ticket, listing all the CVEs it resolves.
+- **hotfix-now is confidential.** No exploit detail in public trackers; impact-only, details local, security owner notified out of band, expedited branch.
+- **Idempotent.** Search before filing; update existing tickets and register entries instead of duplicating. Sync local ↔ tracker both ways.
+- **`accept` carries an expiry and feeds back into triage.** The register is the loop that stops accepted noise from re-flooding every scan — and re-surfaces it when the expiry passes.
+- **The register holds only settled `accept` verdicts.** `under_investigation` gets an investigation task, never a register entry (it isn't decided); `not_affected` is already suppressed by triage's reachability verdict each run. Keep the invariant clean: register = decided + accepted, with a real VEX justification.
+- **Steps are skippable.** Filing, change-stubbing, and direct bumps are independent — do what the user asked for and stop.
+
+## Done
+When every actionable triage finding has a home — a ticket (or remediation.md entry), a change stub, or a risk-register entry with an expiry — and the triage record reflects what was filed, remediation is complete. Hotfix-now items are flagged and confidential; accepted items are scheduled for re-triage.

package/skills/grimoire-vuln-triage/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: grimoire-vuln-triage
+description: Triage vulnerability scans from any source — npm audit, pip-audit, osv-scanner, Trivy, Grype, Snyk, Dependabot, SARIF, or a report a teammate forwards — against our actual deployment model and recorded mitigating controls. Reconciles stale scans against the current tree, then decides the one thing that matters per finding — drop-everything hotfix vs next release cycle — and suppresses non-actionable noise with VEX verdicts. Use when a scanner produces a flood of CVEs and you need to know which actually matter here.
+compatibility: Designed for Claude Code (or similar products)
+metadata:
+  author: kiwi-data
+  version: "0.2"
+---
+
+# grimoire-vuln-triage
+
+Vulnerability scanners flag every CVE that *exists* in your tree or image, ranked by CVSS base score — which knows nothing about your deployment, and nothing about whether you already upgraded past it. Most findings are not exploitable as you actually run the code. This skill is **scanner-agnostic**: it normalizes whatever it's handed (npm audit, pip-audit, osv-scanner, Trivy, Grype, Snyk, Dependabot, SARIF, or a freeform CSV/markdown report) into one canonical model, reconciles it against the current tree, and triages each surviving advisory against **our** deployment and controls to answer the only question that drives action:
+
+> **Drop everything and hotfix now, or let it ride the normal testing / release cycle?**
+
+It produces VEX verdicts (`fixed` / `not_affected` / `affected` / `under_investigation`) so non-actionable findings are dismissed with an auditor-defensible justification, and an urgency (`hotfix-now` / `next-release` / `accept`) for the ones that survive. Covers application dependencies, OS packages from container scans, and runtime/build tooling alike.
+
+This skill **classifies**. Filing the dev work (tickets in the configured bug reporting system) is the job of `grimoire-vuln-remediate`, which consumes this triage.
+
+## Triggers
+- A scanner produces a wall of findings: "npm audit found 40 vulnerabilities", "pip-audit is screaming", "trivy flagged 200 CVEs in the image", "triage these CVEs"
+- "Is this CVE actually a problem for us?", "do we need to hotfix this or can it wait?"
+- "which of these vulnerabilities actually matter", "filter out the noise from the scan"
+- A teammate forwards a scan report (any tool, any format) and asks what's real
+- Loose match: "vuln triage", "CVE triage", "security scan", "trivy/grype/snyk results", "audit results", "image scan"
+
+## Routing
+- A *reported* security bug (not a scanner finding) → `grimoire-bug-triage` (it has a security classification path)
+- A dependency *add/upgrade* review (lockfile, floating ranges, supply chain) → review-time; see `../references/security-compliance.md` § Supply Chain Defense, enforced by `grimoire-review` / `grimoire-precommit-review`
+- After this triage, to file dev work → `grimoire-vuln-remediate`
+- Persistent IaC/container misconfig (root user, no limits, `:latest` base) → `grimoire-draft`/infra, not an app hotfix
+- A control gap surfaced here (a mitigation assumed but never recorded) → `grimoire-draft` to write the MADR
+
+## Prerequisites
+- A scan to triage: output of `config.tools.dep_audit` / `config.tools.security`, a saved scan file (e.g. `reports/security/...`), or pasted text. Prefer machine-readable (`--json` / SARIF) over a human table.
+- The repo's current lockfile/manifest (or deployed image tag) available for reconciliation.
+- Network access for KEV + EPSS enrichment (degrades gracefully to CVSS-only if offline).
+- Best results with `codebase-memory-mcp` for reachability; falls back to grep.
+
+## Workflow
+
+Read `../references/dependency-vuln-triage.md` now — it has the canonical model, the format adapters, the reconciliation rule, the enrichment feeds, the type-aware reachability rules, the VEX statuses, the urgency tree, and the record format. Follow it. The steps below are the spine.
+
+### 1. Normalize the scan into the canonical model (any scanner)
+
+Identify the source and map each finding to the canonical advisory (reference § Step 1): `id`, `aliases`, `cve`, `component`, `component_type` (`library`/`os-package`/`container`/`iac`/`runtime`), `installed_version`, `fixed_version`, `severity`/`cvss`, `target`, `scanner`. Use the format adapter for the tool you were handed — **never assume one tool's field names apply to another** (npm's `isDirect`/`via` ≠ pip-audit's `aliases`/`fix_versions` ≠ Trivy's `Results[].Vulnerabilities[]` with `Class`/`Type`/`Status`). For an unknown/freeform report, extract the minimum (`id`, `component`, version, fixed version) and mark the rest `unknown`. If you can't parse it, ask for `--json`/SARIF rather than guessing.
+
+**Dedup + non-CVE results.** Collapse the same CVE listed across multiple packages (Trivy does this constantly) to unique `(id, component_type)`, keeping the package list — report `raw_findings → unique_advisories` so the noise reduction is visible. Don't discard `Class: secret` / `Class: config` results — they aren't package CVEs; route them (secrets-in-image, Dockerfile/k8s misconfig) to infra/`grimoire-draft`, not triage.
+
+### 2. Reconcile against the current tree FIRST (mandatory)
+
+Before any enrichment, compare each advisory's `installed_version` against what the repo resolves **right now** (reference § Step 2): read the live lockfile/manifest (`uv.lock`/`poetry.lock`/`package-lock.json`/`go.sum`/`Cargo.lock`/`Gemfile.lock`), or for container/OS findings check the currently deployed image tag / Dockerfile base. If the current version ≥ `fixed_version`, mark **`fixed`** and drop it before enrichment — record it under "Already fixed" as the audit trail. Honor manifest comments / prior triage that already dismiss a CVE. **Never file remediation for an advisory you haven't confirmed still exists.** On a stale scan this pass clears most of the queue.
+
+**Honor the risk-acceptance register.** Read `.grimoire/security/accepted-risks.yml` (written by `grimoire-vuln-remediate`). An **unexpired** entry for a CVE means it was already triaged and consciously accepted → carry it as known-accepted, don't re-escalate (cite the register entry). An **expired** entry → re-triage it fresh (the acceptance lapsed). This is what stops accepted findings from re-flooding the queue every scan.
+
+### 3. Enrich the survivors — KEV then EPSS
+
+Per the reference: fetch the **CISA KEV** catalog once and match every `cve`/`aliases` (known-exploited = strongest hotfix signal); fetch **EPSS** for all CVE ids (batch, comma-separated) for exploit probability. Cache both in the run dir. If offline, record `kev-feed: offline` / `epss-fetched: false` and proceed on CVSS + reachability + exposure — say so. IaC/config findings skip threat-intel (no CVE).
+
+### 4. Reachability — type-aware, the cheapest big filter
+
+Judge reachability by `component_type` (reference § Reachability):
+- **library** — dev/test-only (infer from lockfile groups, not a flag) → `not_affected` in prod; imported at all? (`search_graph`/`search_code`); vulnerable function actually called? (`trace_path`).
+- **os-package** (container scan) — judge **two separate axes**: *reachability* (is the vulnerable code called by untrusted input? grep the consumer, not the C package name) and *removability* (how installed — explicit/transitive/base-image/builder-only — and what breaks). **Unreachable ≠ removable.** Never recommend removing a package (or "slim the base image") without tracing the install path and naming the post-change test; many base-OS/transitive libs aren't removable. No-fix / `will_not_fix` → accept or base bump, never an "upgrade X" ticket. Full discipline + maps + anti-patterns in `../references/container-scan-triage.md`.
+- **runtime** (interpreter/build tool, e.g. pip) — invoked at runtime or only at build time? Build-only, not in the running container → `not_affected` at runtime (check entrypoint/CMD).
+- **container/iac** — not a CVE; triage on whether the misconfig is reachable in our deployment; route persistent ones to infra.
+
+Also check **advisory preconditions** against real config — many CVEs are conditional (a setting, ASGI-vs-WSGI, a middleware). Precondition met → raises urgency; absent → clean `not_affected`. Record reachability provenance (`graph-verified`/`grep-asserted`/`image-layer`/`unknown`).
+
+**Resolve unknowns in the moment — don't default to `under_investigation`.** When reachability isn't settled by grep: trace deeper (`trace_path` from routes to the vulnerable binding), then **ask the human the one decisive question** (e.g. "does any endpoint parse user-supplied XML?") — a single yes/no usually collapses several findings to `not_affected` or `affected` on the spot, sparing both a register entry and a follow-up task. Reserve `under_investigation` for questions nobody in the session can answer (needs a runtime check / a teammate / an external dependency); time-box those and name what must be checked.
+
+### 5. Exposure & controls — read, don't invent
+
+Per reference § Exposure & Controls: `.grimoire/docs/context.yml` (internet-facing vs internal vs lambda/batch, infra, services) and MADR decisions (`Security (CIA)` rows, WAF/network-isolation/auth/tenancy decisions). A documented control that breaks the attack path is a legitimate damper / VEX `inline_mitigations_already_exist`. **Do not create a controls config file** — controls live in MADR + context.yml. A verdict-changing control that's recorded nowhere → log under "Control gaps", don't credit it silently.
+
+### 6. Assign VEX verdict + urgency
+
+Apply the decision tree (reference § VEX + § Urgency): `fixed` (Step 2) → `not_affected` (reachability/precondition) → `affected` with **hotfix-now** / **next-release** / **accept** (with expiry) → `under_investigation` (time-boxed). Fail safe on unknowns (KEV + public + unknown reachability → hotfix-now); don't manufacture emergencies (no KEV + low EPSS + unknown → under_investigation + next-release).
+
+### 7. Contrarian pass — calibrate before you escalate
+
+Run the **Contrarian calibration pass** (`../references/review-personas.md` §4.8) over every `hotfix-now` and `affected` verdict: steel-man "we are not affected", name the assumption, run the inversion test (does a rushed hotfix / base-image swap ship *new* risk?), check severity clears all three bars (reachable + exploitable-as-deployed + real blast radius). Emit `[hotfix upheld]` / `[hotfix → next-release]` / `[finding dropped]` per escalation with one line of evidence. Summary counts are **post-Contrarian**. Calibration, not veto.
+
+### 8. Write the triage record
+
+Write `.grimoire/security/vulns/<run-date>/triage.md` in the reference format: frontmatter totals, then sections — Hotfix now / Next release / Risk-accepted / **Already fixed** (the stale-scan audit trail) / Not affected / Under investigation / Control gaps. Cache the KEV snapshot and EPSS responses alongside for reproducibility.
+
+### 9. Report and hand off
+
+Headline: how many findings, how many already **fixed** (stale scan), how many **not_affected** (noise) with the dominant reason, how many real (`affected`), how many **hotfix-now** — and *why* the hotfixes are hotfixes (one line each).
+- **Any hotfix-now** → flag immediately, notify the security owner, recommend expedited fix.
+- **affected (any urgency)** → "Run `grimoire-vuln-remediate` to file these into the bug tracker."
+- **Control gaps** → "Assumed but unrecorded — `grimoire-draft` to capture them."
+
+## Important
+- **Reconcile before you triage.** A scan is a snapshot; the tree moves. Confirm each finding still exists in the current lockfile/image before spending any effort on it — it's the single highest-leverage step and stops you filing dead tickets.
+- **Scanner-agnostic by design.** Normalize any tool into the canonical model, then triage that. The verdict logic must never depend on npm's or pip's or Trivy's field names. New tool? Add an adapter, not a new triage path.
+- **CVSS ranks the world; we triage our deployment.** A "critical" in a dev-only, unreachable, or base-OS-cruft component is noise; a "medium" KEV hit on a public endpoint is a hotfix.
+- **Reachability is type-aware.** App import ≠ OS package ≠ build-time tool ≠ IaC misconfig. Judge each on its own terms; a flagged base-image lib the app never calls is not a prod emergency.
+- **Check the precondition.** Conditional CVEs are common — read the actual setting. Met → escalate; absent → `not_affected`.
+- **`not_affected` requires a justification code.** The code is what makes the dismissal defensible to an auditor.
+- **Controls must be recorded to count.** Flag undocumented ones, don't assume them.
+- **Fail safe, don't fearmonger.** Escalate on KEV + public + unknown reachability; don't turn a low-EPSS, non-KEV, internal-only finding into a fire drill.
+- **The Contrarian is the noise filter, not a silencer.**
+- **`accept` carries an expiry.** Re-triaged when the fix ships; never silently permanent.
+- **This skill does not fix or file.** It classifies. Code changes, ticket filing, image rebuilds are downstream (`grimoire-vuln-remediate`, `grimoire-bug`/`grimoire-draft` for non-trivial fixes).
+
+## Done
+When `.grimoire/security/vulns/<run-date>/triage.md` exists with every finding normalized, reconciled, and assigned a VEX verdict (and for `affected`, an urgency), the Contrarian pass applied to escalations, and the headline reported, triage is complete. Hand off to `grimoire-vuln-remediate` to file the dev work.

package/skills/references/adversarial-personas.md

@@ -0,0 +1,225 @@
+# Adversarial Personas Reference
+
+Loaded by `grimoire-review`, `grimoire-pr-review`, and `grimoire-precommit-review` when the change touches a user-facing surface. Defines the surface-conditional adversarial personas that complement the engineering / product / security personas in `./review-personas.md`.
+
+Each persona inhabits a user the design might fail. Their job is to find the failure paths a happy-path-focused reviewer would miss: the keyboard-only user who can't tab to the submit button, the screen-reader user lost in an unlabelled icon grid, the user on a 3G connection waiting for a 4 MB hero image.
+
+The set engaged on a given review is filtered by `project.surface` (see §Activation Matrix). All personas inherit the project briefing (§1 of `./review-personas.md`), the materiality gate (§2), and the steel-man requirement (§2a).
+
+---
+
+## Persona Catalog
+
+Each persona below names: **identity** (whose constraints they hold), **evaluation criteria** (what they look at), **what triggers a finding** (the concrete observation that becomes feedback).
+
+### Keyboard-Only User
+
+- **Identity**: Power user navigating exclusively via keyboard (Tab, Shift-Tab, arrow keys, Enter, Esc). Mouse unavailable due to RSI, motor impairment, terminal-only environment, or preference for speed.
+- **Evaluation criteria**:
+  - Every interactive element reachable via Tab in a sensible order
+  - Focus indicator visible on every focusable element
+  - No keyboard traps (except modal dialogs, which must escape on Esc)
+  - Shortcuts documented and consistent (don't shadow OS / browser defaults)
+  - Custom controls (combobox, datepicker, drag-drop) implement full keyboard interaction patterns per WAI-ARIA Authoring Practices
+- **Triggers a finding**:
+  - Click-only handler without keyboard equivalent
+  - Focus indicator suppressed (`outline: none` without replacement)
+  - Tab order jumps visually unrelated regions
+  - Modal dialog cannot be dismissed with Esc
+  - Custom dropdown reachable but not operable from keyboard
+
+### Screen-Reader User
+
+- **Identity**: User of VoiceOver (macOS/iOS), NVDA (Windows), JAWS (Windows), or TalkBack (Android). Navigates by reading aloud announcements; relies on semantic markup and ARIA.
+- **Evaluation criteria**:
+  - Semantic HTML used in preference to ARIA (`<button>` not `<div role="button">`)
+  - Every form input has a programmatically-associated label
+  - Icons that convey meaning have accessible names (`aria-label` or visually-hidden text)
+  - Dynamic content changes are announced (live regions or focus shifts)
+  - Heading hierarchy is meaningful (H1 once, H2 sections, no skipped levels)
+  - Image alt text describes meaning, not appearance (decorative images: `alt=""`)
+- **Triggers a finding**:
+  - Icon-only button without accessible name
+  - Form field with placeholder used as the only label
+  - Live error announcement missing (form submit → silent failure)
+  - Decorative SVG read aloud as a long filename
+  - `<div onclick>` instead of `<button>`
+
+### Low-Vision / Color-Blind User
+
+- **Identity**: User with low vision (uses browser zoom 200%+, OS magnifier), or color vision deficiency (deuteranopia, protanopia, tritanopia, monochromacy — affects ~8% of men, ~0.5% of women).
+- **Evaluation criteria**:
+  - Body text contrast ≥ 4.5:1 (WCAG AA)
+  - UI component contrast ≥ 3:1 vs adjacent
+  - Information not conveyed by color alone (status badges have icons or text; error fields have text labels not just red borders)
+  - Page reflows cleanly at 200% zoom (no horizontal scroll, no overlapping content)
+  - Text scales when user adjusts browser font size (no fixed `px` font sizes on body text where `rem` would work)
+- **Triggers a finding**:
+  - Gray text on white below 4.5:1 (the perennial offender)
+  - Red/green status indicator with no icon or text differentiator
+  - Layout breaks at 200% zoom (content cut off, controls overlap)
+  - Required-field marker conveyed only by red asterisk color (no actual asterisk character)
+
+### Touch-Target User
+
+- **Identity**: Mobile user, often one-handed, often with imprecise thumb input (in motion, accessibility-impaired motor control, or just normal use on a small screen).
+- **Evaluation criteria**:
+  - Interactive targets ≥ 24×24 CSS pixels (WCAG 2.2 AA minimum); ≥ 44×44 preferred (iOS HIG)
+  - 8px+ spacing between adjacent targets
+  - Primary actions reachable in the thumb zone (bottom half of phone screen)
+  - No hover-only affordances (hover doesn't exist on touch)
+  - Long-press, swipe, pinch interactions have a tap-only equivalent
+- **Triggers a finding**:
+  - Buttons sized below 24×24 in the actual rendered design
+  - Adjacent links in a list with no spacing (mis-tap risk)
+  - Primary CTA in the top-right corner (unreachable for one-handed use on large phones)
+  - Tooltip is the only source of help text on a touch surface
+
+### Responsive-Breakpoint User
+
+- **Identity**: User on a viewport the designer didn't focus-test — 320px-wide phones, foldables in their open state, 5K desktops, browser windows the user resized.
+- **Evaluation criteria**:
+  - Layout works from 320px viewport width upward (smallest common phone)
+  - No horizontal scroll except for content where scrolling is intentional (tables, code blocks)
+  - Breakpoints handle landscape phone orientation (short, wide viewports)
+  - Text remains readable line length (45-75 characters) across breakpoints — does not stretch to full ultra-wide width
+  - Touch targets remain ≥ 24×24 at the smallest breakpoint
+- **Triggers a finding**:
+  - Card layout breaks below 360px (content overflows or overlaps)
+  - Sidebar that collapses to a hamburger but the hamburger button is itself 12×12
+  - Line length unconstrained on ultra-wide displays (text spans 2000px)
+  - Modal dialog wider than the viewport, requiring horizontal scroll inside the modal
+
+### RTL / i18n User
+
+- **Identity**: User of a right-to-left script (Arabic, Hebrew, Persian, Urdu) or a language with different text expansion (German, Finnish — typically 30% longer; Chinese, Japanese, Korean — often shorter but with line-break rules).
+- **Evaluation criteria**:
+  - Layout mirrors correctly under `dir="rtl"` (logical properties used: `margin-inline-start` not `margin-left`)
+  - Icons that imply direction (arrows, chevrons) flip; icons that don't (clock, magnifying glass) don't
+  - Strings interpolated with placeholders use named/positional substitution, not concatenation
+  - Hardcoded strings flagged; user-visible text comes from a translation catalog
+  - Date, number, currency formats use the user's locale
+- **Triggers a finding**:
+  - User-visible string hardcoded in the markup (not extracted for translation)
+  - Layout breaks visually under `dir="rtl"` (margins on the wrong side, icons not mirrored)
+  - Date displayed as `MM/DD/YYYY` without locale awareness (ambiguous globally)
+  - String concatenation that won't translate cleanly: `"You have " + count + " items"` → use a translation function with placeholders
+
+### Low-Bandwidth / Offline User
+
+- **Identity**: User on slow or intermittent network (3G, congested wifi, satellite, train tunnel). Frequent in markets the project may not actively target but where users still exist.
+- **Evaluation criteria**:
+  - Total payload weight for first meaningful render reasonable for the surface (web < 200 KB JS gzipped is a starting bar; mobile native should function offline-first for read paths)
+  - Images sized to actual display dimensions; modern formats (AVIF, WebP) with fallbacks
+  - Network failures fail gracefully (cached state, queued writes, retry with backoff)
+  - Loading states address slow connections, not just fast ones (skeleton at 100ms, escalated message at 5s)
+- **Triggers a finding**:
+  - Hero image > 1 MB without responsive `srcset`
+  - Form submit hangs indefinitely when network is dropped (no timeout, no queue)
+  - Critical content loaded via blocking JS bundle > 500 KB
+  - No offline state — app crashes or shows blank screen when network is lost
+
+### Hostile Actor
+
+- **Identity**: User actively trying to misuse the design — abuse a flow, exfiltrate data, deceive other users via the system, or weaponize the UI as part of a social-engineering attack. Adversarial UX, not just adversarial security.
+- **Evaluation criteria**:
+  - User-generated content is escaped and rendered safely (no XSS, no markdown that smuggles HTML)
+  - Rate limits visible to legitimate users (so they understand why an action was blocked) but unbypassable
+  - Sharing / impersonation features have abuse mitigation (report button, mute, block)
+  - Display-name fields don't accept Unicode lookalikes that impersonate other users (homograph attack)
+  - Email / SMS templates can't be hijacked for phishing-by-proxy (user-supplied URL appearing in an authority-branded message)
+  - Sensitive actions require recent re-authentication, not just an open session
+- **Triggers a finding**:
+  - Comment field renders user-supplied HTML
+  - Search field reflects input back into the page without escaping
+  - Profile URL accepts `javascript:` scheme
+  - "Invite via email" feature sends arbitrary user-supplied text from the project's domain
+
+### API Conventions Reviewer
+
+- **Identity**: API consumer (internal team, partner, third-party developer). Evaluates the *design* of public APIs the same way users evaluate UI — for consistency, predictability, and minimum surprise.
+- **Evaluation criteria**:
+  - REST: resource-oriented URLs, correct HTTP verbs and status codes, consistent error envelope, predictable pagination
+  - GraphQL: schema follows naming conventions (camelCase fields, PascalCase types), no over-fetching defaults, deprecation flow uses `@deprecated` not removal
+  - Idempotency: PUT and DELETE are idempotent; POST that should be idempotent uses an `Idempotency-Key` header
+  - Versioning: breaking change has a versioning plan (URL path, header, or media type — but consistent across the API)
+  - Discoverability: spec is published (OpenAPI, GraphQL introspection); errors point to docs
+- **Triggers a finding**:
+  - New `POST /deleteUser` endpoint (verb in URL — should be `DELETE /users/:id`)
+  - Inconsistent error envelopes across endpoints (some `{ error: "..." }`, some `{ message: "..." }`)
+  - Breaking change to a documented field with no version bump or deprecation notice
+  - 200 OK returned for an operation that failed (status code masks the error)
+
+---
+
+## Activation Matrix
+
+Engagement of each persona is determined by `project.surface`. The matrix below comes from ADR-0019.
+
+| Persona | TUI | Web | Mobile | API | Mixed |
+|---|---|---|---|---|---|
+| Keyboard-only | required | required | n/a | n/a | required |
+| Screen-reader | n/a | required | required | n/a | required |
+| Low-vision / color-blind | n/a | required | required | n/a | required |
+| Touch-target | n/a | n/a | required | n/a | required |
+| Responsive-breakpoint | n/a | required | n/a | n/a | required |
+| RTL / i18n | conditional | conditional | conditional | n/a | conditional |
+| Low-bandwidth / offline | n/a | required | required | conditional | required |
+| Hostile actor | required | required | required | required | required |
+| API conventions | n/a | n/a | n/a | required | required |
+
+**Legend**:
+- **required** — persona engages by default on this surface
+- **conditional** — persona engages only when a project briefing axis flags it (e.g., `i18n` tag has count > 0 in the feature inventory; project compliance includes a region requiring RTL)
+- **n/a** — persona does not engage by default; user can still invoke via `--personas=...`
+
+**User override always available** via `--personas=keyboard,low-vision` or "skip <persona>". Surface is the default; the user is the override.
+
+**Mixed surface** runs the union of all surface-specific personas. Projects that genuinely span TUI + web + mobile should set `surface: mixed`; that is the cost of breadth.
+
+**Unknown surface** (config field absent) falls back to `mixed`. Better to over-engage than to silently skip critical personas.
+
+---
+
+## Materiality Gate Cross-Reference
+
+Every adversarial finding must cite an axis from the Project Briefing (§1 of `./review-personas.md`). The adversarial set extends the briefing axes the original engine considered:
+
+- **Surface axis** (this engine adds it) — TUI vs web vs mobile vs API determines which personas engage at all
+- **Brand axis** — if `.grimoire/brand/tokens.json` defines a contrast ratio target, the low-vision persona uses it; otherwise WCAG AA default
+- **Compliance axis** — `project.compliance` mentions WCAG, ADA, EAA (European Accessibility Act), Section 508 → screen-reader and low-vision findings escalate from suggestion to blocker by default
+- **Threat-surface tags** (existing) — `i18n=N` count > 0 promotes RTL persona from conditional to required; `mobile=N` count > 0 promotes touch-target persona
+
+A finding from any persona below that lacks a briefing anchor is dropped. The full materiality rules from `./review-personas.md` §2 apply unchanged.
+
+---
+
+## Steel-Man Requirement
+
+Per `./review-personas.md` §2a, every adversarial finding must include a steel-man before submission:
+
+- **Steel-man**: "The designer likely chose this because <strongest plausible reason — convention, performance, scope, stage>."
+- **Why it still fails**: "Despite that, <concrete harm path tied to a briefing axis — named user impacted, named state, named consequence>."
+
+If either line cannot be completed with substance, the finding is dropped. "An accessibility issue" is not a finding; "screen-reader user submitting the login form receives no audible feedback on validation error — they cannot recover without sighted assistance" is a finding.
+
+Vague harm paths fail this gate. The adversarial personas exist precisely to name specific harms; generic ones are noise.
+
+---
+
+## Severity Calibration
+
+The default for an adversarial finding is **suggestion**. A finding is a **blocker** when *all three* hold (mirroring `./review-personas.md` §2b):
+
+1. **Concrete harm path** — named user (the persona), named trigger, named consequence
+2. **Briefing-anchored** — the consequence threatens a briefing axis (surface, compliance, brand contrast target, threat-surface tag)
+3. **Not already mitigated** — neighbor code, design-system component, or sibling feature does not already handle it
+
+Adversarial-specific severity rules:
+
+- WCAG AA violations on a project that lists WCAG / ADA / EAA in `project.compliance` → blocker by default (regulator anchor)
+- Deceptive patterns (see `./design-heuristics.md` §3) → blocker by default on customer-facing stage; suggestion on internal-tools stage
+- Hostile-actor findings with a working harm path → blocker, regardless of stage (security overlap)
+- Touch-target findings on a mobile surface where the project ships → blocker if a user couldn't complete a primary task; suggestion if it's a secondary control
+
+Zero findings is a valid outcome. A persona that returns "no material findings under the briefing" is doing its job. The Contrarian pass (§4.8 of `./review-personas.md`) calibrates inflated findings post-hoc.