@kiwidata/grimoire 0.1.4 → 0.1.5

package/skills/references/code-quality.md

@@ -14,7 +14,7 @@ For each production file you wrote or edited, walk the seven checks below. Any f
 
 ### 1. Reuse before write
 
-Before adding a function, helper, type, or constant: grep for it. Check the area doc's reusable-code table if one exists. Check neighbors in the same directory.
+Before adding a function, helper, type, or constant: query the graph (`search_graph` by concept and by name) for an existing one. Then grep, and check neighbors in the same directory.
 
 - If a function with the same job already exists → call it. Don't re-implement.
 - If something *almost* fits → use it directly first, refactor it once a second caller actually needs the change. Don't generalize on speculation.
@@ -83,21 +83,53 @@ Keep:
 
 Fail: a new `BaseFoo` / `FooStrategy` / `FooFactory` introduced for a single caller.
 
-### 7. Comments earn their place
+### 7. Comments earn their place — terse, self-contained, no essays
 
-Default: no comments. Add a comment **only** when the *why* is non-obvious — a hidden constraint, a workaround for a specific bug, an invariant that would surprise a future reader.
+Write comments like a senior engineer with no time: dense, professional, zero filler.
+
+**Voice: terse.** "Resolve model by id; raises on unknown provider." — not "This function is responsible for resolving the model by its id, and it will raise an exception if the provider is not known." Drop "this function", "we", hedging, and restated types. Fragments are fine; full prose grammar is not required.
+
+**Self-contained.** A comment describes the function/class on its own terms only. It must NOT name an external artifact that changes independently — feature flags / `.feature` files / scenario names, unit or integration test names, MADR/ADR numbers, change-ids, issue/PR numbers, tag codes (`LOG-OBS-003`). Those orphan the moment the artifact moves, and rot silently. Describe the *behavior*, not where it's specced.
+- OK: `# skip third-party sinks (e.g. behave capture)` — generic, about the code.
+- Not OK: `# implements scenario LOG-OBS-003 from logging.feature` — points at an artifact that will move.
+
+**No paragraphs.** Summary is one line, two at most. No prose block explaining the whole design before the params. If the rationale needs a paragraph, it belongs in a decision record — not the code.
+
+**Params per `comment_style` are fine.** If the project's style (sphinx/google/jsdoc/…) calls for `:param`/`Args:`/`@param`, keep them — but describe a param only when its name + type don't already say it, and don't precede them with prose.
 
 Drop:
 - Comments that restate the code (`# loop over users`).
-- Comments referencing the current task / PR / ticket (`# added for issue #123`, `# used by the new flow`). These rot.
-- Multi-line docstrings on private functions whose name and signature already say everything.
+- Any reference to a task / PR / ticket / feature / scenario / ADR / specific test (`# added for issue #123`, `# covers scenario X`, `# see test_foo`). Self-contained or gone.
+- Multi-line prose docstrings on private functions whose name + signature already say everything.
 - Commented-out code. Delete it; git remembers.
 
 Keep:
-- One-line "why": the constraint, the gotcha, the link to the spec / ADR.
-- Docstrings the project's `comment_style` requires (check `.grimoire/config.yaml`).
+- One terse line of *why* when non-obvious — a hidden constraint, a workaround, a surprising invariant — stated in terms of the code itself.
+- The structured `comment_style` param/return section, terse.
+
+Fail: any comment that (a) wouldn't confuse a future reader if removed, (b) names an external artifact, or (c) runs to a prose paragraph.
+
+**Before / after** (the offender this rule targets):
+```python
+# BEFORE — orphan-prone essay
+def build_chat(model_id):
+    """
+    Build and return a chat model for the given model id. This is the primary
+    entry point used by every agent and team in the system, as specified by
+    scenario LOG-OBS-003 in logging.feature and decided in ADR-0001. See
+    test_build_chat for the expected behavior. Added as part of add-2fa-login.
+
+    :param model_id: the id of the model to build
+    :return: the chat model
+    """
+
+# AFTER — terse, self-contained
+def build_chat(model_id):
+    """Resolve a chat model by id. Raises on an unknown provider.
 
-Fail: any comment whose removal would not confuse a future reader.
+    :param model_id: provider-prefixed model id (e.g. "gpt-4.1-mini")
+    """
+```
 
 ---
 
@@ -110,7 +142,7 @@ Before marking a task `[x]`:
 - [ ] No guards / try-except / type-checks inside the trust boundary (§4)
 - [ ] No locals named `data`, `result`, `temp`, `info`, `obj` — names reveal intent (§5)
 - [ ] No new abstractions, interfaces, or wrappers with a single caller (§6)
-- [ ] No comments describing *what* the code does — only *why*, and only when non-obvious (§7)
+- [ ] Comments are terse, self-contained, ≤2 lines of prose — no *what*, no external-artifact refs (feature/scenario/ADR/test/ticket) (§7)
 - [ ] Diff stays inside the task's scope — no "while I'm here" refactors
 
 If any box can't be ticked, fix the code (not the checklist) and re-run tests.

package/skills/references/container-scan-triage.md

@@ -0,0 +1,102 @@
+# Container & OS-Package Scan Triage Reference
+
+The deep-dive for `os-package` / `container` / `iac` findings from image scanners (Trivy, Grype). Loaded by `grimoire-vuln-triage` when a scan carries container/OS-package results. The general rubric — normalize, reconcile, KEV/EPSS, VEX, urgency, Contrarian — lives in `./dependency-vuln-triage.md`; this file is the discipline for the part that goes wrong most: deciding what to *do* about a base-OS CVE.
+
+Written after a review recommended removing `Mesa`, `ncurses`, and `krb5` from a headless Django API with the rationale "no business in a headless API." Two of the three could not be removed without breaking the image. This guide exists so that mistake is not repeated.
+
+## Separate the two axes — they are not the same question
+
+- **Reachability** — *is the vulnerable code path actually called by untrusted input in this service?* Decides **urgency** (hotfix / next-release / accept). A library present but never invoked is low risk even at CVSS CRITICAL.
+- **Removability** — *can we delete the package, and what breaks if we do?* Decides **remediation** (Dockerfile edit / base bump / accept+document).
+
+Conflating them produces the classic error: "this lib is unreachable, so remove it." Unreachable ≠ removable. A headless API genuinely cannot reach Mesa's OpenGL code — **and also cannot remove Mesa** if it arrived transitively behind a package it needs. Judge both, separately.
+
+## Core rule: trace before you recommend
+
+A CVE scanner reports *what is present*, not *why* or *whether it is removable*. Never recommend removing a package until you have answered all three:
+
+1. **How does it get in?** Directly installed, transitive, base image, or builder-stage-only?
+2. **What depends on it?** Application code, a required runtime lib, or the base OS?
+3. **What breaks if it's gone?** Build, runtime, or nothing — and what's the test that proves it?
+
+"This doesn't belong in a headless API" is an assumption, not an analysis.
+
+## Step A — How is it installed?
+
+Search the Dockerfile for an explicit install line first.
+
+- **Explicitly installed** (named in `apt-get install` / `pip install`): a real removal candidate — continue to Step B.
+- **Not named anywhere**: it's transitive — pulled by another package or shipped in the base image. You cannot `apt-get remove` it without breaking its parent. Identify the parent before saying anything.
+
+Common transitive sources — map these before flagging:
+
+| Flagged lib | Usually pulled in by | Notes |
+|---|---|---|
+| krb5 / libgssapi-krb5 | `libpq5`, `postgresql-client`, `curl` | Postgres GSSAPI/Kerberos auth |
+| ncurses / libtinfo | base image | bash, apt, dpkg, python readline link it |
+| Mesa / libgl1 / libgbm | `libgl1`, `libglib2.0-0` | OpenCV / docling / easyocr deps |
+| OpenSSL / libssl | base image + most TLS clients | almost never removable |
+| libexpat1 | base image + python (`pyexpat`) | stdlib XML |
+
+## Step B — What actually depends on it?
+
+Do not assume. Check the repo:
+
+- **App imports** — grep for the consuming module (`import cv2`, `import magic`, `import pyodbc`, `gssapi`, `lxml`).
+- **System tools used at runtime** — grep code, scripts, and the entrypoint for the binary (`psql`, `pg_dump`, `pg_isready`).
+- **Driver bundling** — many Python wheels bundle their native lib, making the system package redundant. `psycopg-binary` bundles libpq → system `libpq5` not needed for the driver; `pylibmagic` bundles libmagic → system `libmagic1` may be redundant. When a binary wheel is present, the matching system runtime package is often dead weight — **verify, then say so**.
+- **Cross-service config trap** — env vars or paths in this repo may configure a *different* container. `EASYOCR_MODULE_PATH` / `DOCLING_ARTIFACTS_PATH` in bake are passed by `job_runner.py` to the **ricky** pipeline container — they do **not** mean bake runs easyocr/docling. Never justify or condemn a package using a string that belongs to another service.
+
+## Step C — Know what is not removable
+
+Some findings are not actionable by editing an install line:
+
+- **Base-image packages** (ncurses, OpenSSL, glibc, zlib, expat): part of the OS. Removing breaks bash/apt/dpkg or the Python runtime. The only real mitigations are: **switch to a smaller/distroless base**, **bump the base image** for patched versions, or **accept and document** the risk. State which — do not tell the user to "remove" it.
+- **Transitive deps of required libs** (e.g. krb5 behind `libpq5`): removable only by also removing the parent, and only if the parent is itself unneeded.
+
+## Step D — Multi-stage builds: target the right stage
+
+In a multi-stage Dockerfile only the final stage ships. Packages in a `builder` stage (compilers, `-dev` headers) do **not** appear in the runtime image if only the artifact (`/opt/venv` or equivalent) is copied forward. They are not runtime attack surface. Don't flag builder-stage packages as runtime risk; if you mention them, label them **build-only**.
+
+## Step E — Assess real risk, not just presence (reachability)
+
+Maps to `./dependency-vuln-triage.md` § Reachability. A CVE in a library never reached by untrusted input is lower priority than its score. For each finding note:
+
+- Is the vulnerable code path reachable in *this* service? (use the consumer map below — grep the **consumer**, not the C package name; the app never `import`s `libexpat1`)
+- Network/user-input exposed, or internal-only?
+- Headless API context: no display, no user shell, no interactive TTY → GUI/terminal libs (Mesa, ncurses) are usually unreachable even when present.
+
+| OS package | Reached only if the app… | Grep for |
+|---|---|---|
+| libexpat1 | parses XML via stdlib | `xml.etree`, `xml.sax`, `pyexpat`, `minidom` |
+| libxml2 / libxslt | parses XML/XSLT via lxml | `import lxml`, `etree`, `XSLT` |
+| krb5 / libgssapi | does Kerberos/GSSAPI auth | `gssapi`, `kerberos`, `requests_kerberos` |
+| mesa / libGL / libgbm | does GPU/OpenGL rendering | `OpenGL`, `moderngl`, `cv2` (headless API: none) |
+| ncurses / libtinfo | drives an interactive terminal | `curses`, `pty`, `readline` (web process: none) |
+| libssl / openssl | does TLS | usually reachable — judge on impact |
+| imagemagick / libvips | processes user-uploaded images | the upload/convert path |
+
+**Grep can lie — verify the binding.** `Price.fromstring()` (price-parser) is not `etree.fromstring()` (XML). Confirm the match is the real vulnerable call site before asserting `not_affected` or `affected`; if you can't, mark `under_investigation` and name what a human must check. Prefer reachability-based prioritization over raw CVSS.
+
+## Honor the scanner's fix-state
+
+Trivy `Status` (and Grype `fix.state`): `fixed` → a patched package exists; upgrade/rebuild is the lever. `affected` / `will_not_fix` / `end_of_life` → **no fix available**; the lever is *accept with expiry* or *rebuild on a newer/slimmer base when one ships* — **not** an "upgrade X" ticket. `under_investigation` → distro hasn't ruled; mirror it. Never file an upgrade task for a no-fixed-version finding.
+
+## Output per flagged package
+
+1. **Package + CVE(s)** — what the scanner said (and the dedup count if one CVE spans many packages).
+2. **How it's installed** — explicit line N / transitive via `<parent>` / base image / builder-only.
+3. **What depends on it** — app module / runtime tool / OS, with grep evidence.
+4. **Reachable?** — vulnerable path called by untrusted input? (provenance: graph / grep / image-layer / unknown)
+5. **Removable?** — Yes (safe) / Yes (after removing `<parent>`, test X) / No (base OS) / No (required by Y).
+6. **Recommendation** — exact Dockerfile edit, or "patch/bump base image", or "accept + document", **plus the post-change test** (build, import, DB connect). Route image-structure changes to infra / `grimoire-draft`, not app remediation.
+
+## Anti-patterns — do not do these
+
+- ❌ "X has no business in a headless API" with no trace of how X got installed.
+- ❌ Recommending `apt-get remove` of a base-image or transitive package.
+- ❌ Treating scanner presence as equal to exploitable risk.
+- ❌ Justifying or condemning a package using config that targets another service.
+- ❌ Flagging builder-stage packages as runtime attack surface.
+- ❌ Recommending removal without naming the post-change test.
+- ❌ Filing an "upgrade" ticket for a `will_not_fix` / no-fixed-version finding.

package/skills/references/dependency-vuln-triage.md

@@ -0,0 +1,236 @@
+# Vulnerability Triage Reference
+
+Loaded by `grimoire-vuln-triage` (and later `grimoire-vuln-remediate`). Turns **any** vulnerability scan — `npm audit`, `pip-audit`, `osv-scanner`, Trivy, Grype, Snyk, Dependabot, a SARIF file, or a CSV/markdown report a teammate forwards — into per-advisory verdicts whose single most important output is one decision:
+
+> **Drop everything and hotfix now, or let it ride the normal testing / release cycle?**
+
+Everything below exists to answer that, honestly, for *our* deployment — not in the abstract. The skill is **scanner-agnostic**: it normalizes whatever it's handed into one canonical model, then triages that. Covers application dependencies (npm/PyPI/Go/Cargo/…), OS packages (Debian/Alpine/RPM from container scans), and container/IaC findings alike.
+
+## Why raw scanner severity is not the answer
+
+Scanners rank by **CVSS base score**, which describes the vulnerability in a vacuum. It knows nothing about whether our code reaches the vulnerable function, whether the package even runs in production, whether the service is internet-facing, what controls sit in front of it, or **whether we already upgraded past it**. CVSS alone over-escalates: most "high"/"critical" findings are not actionable in a given deployment. Commercial reachability tooling suppresses 70–90% of findings for exactly this reason. We get most of that signal for free from reconciliation + KEV + EPSS + reachability + our own context.
+
+The triage rubric is **Threat × Exposure × Impact**:
+- **Threat** — is it actually being exploited / likely to be? (KEV, EPSS)
+- **Exposure** — can an attacker reach the vulnerable code in our deployment? (reachability + network exposure)
+- **Impact** — what is the blast radius if they do? (data sensitivity, privilege)
+
+## Step 1 — Normalize the scan into the canonical advisory model
+
+**Do this before anything else, regardless of source.** Different scanners emit wildly different shapes; triage logic must never be coupled to one format. Map each finding to:
+
+| Field | Meaning |
+|---|---|
+| `id` | Primary advisory id (CVE, GHSA, OSV, vendor id) |
+| `aliases` | All other ids (so KEV/EPSS lookups can find the CVE) |
+| `cve` | The CVE alias if any (KEV/EPSS key); may be absent |
+| `component` | Package / module / OS-package / image name |
+| `component_type` | `library` \| `os-package` \| `container` \| `iac` \| `runtime` — drives how reachability is judged |
+| `installed_version` | What the scan saw |
+| `fixed_version` | First fixed version, or `none` |
+| `severity` / `cvss` | Scanner-reported, treated as a prior only |
+| `target` | Where it was found (lockfile, image layer, Dockerfile, repo) |
+| `scanner` | Which tool produced it |
+| `advisory_url` / `description` | For reading what the bug actually is |
+
+### Format adapters
+
+Read the right fields per scanner — **do not** assume one tool's field names apply to another:
+
+- **npm audit** (`--json`): `vulnerabilities{}` keyed by package → `severity`, `via[]` (string or advisory object with `title`/`url`), `isDirect`, `fixAvailable`, `nodes[]`. Dev deps appear via `effects`/dependency graph (no single `dev` flag on every entry).
+- **pip-audit** (`-f json`): `dependencies[]` → `{name, version, vulns[]}`; each vuln has `id`, `aliases[]` (find the `CVE-` one), `fix_versions[]`, `description`. **No dev flag in the data** — infer dev/runtime from lockfile groups (`[tool.uv] dev-dependencies`, poetry `group.dev`, `requirements-dev.txt`).
+- **osv-scanner** (`--format json`): `results[].packages[].vulnerabilities[]` with OSV ids + `aliases`; `results[].source.path` is the manifest.
+- **Trivy** (`--format json`): `Results[]` each with a `Class` (`os-pkgs` \| `lang-pkgs` \| `config`) and `Type` (debian, alpine, gobinary, python-pkg, …); `Results[].Vulnerabilities[]` → `VulnerabilityID`, `PkgName`, `InstalledVersion`, `FixedVersion`, `Severity`, `CVSS{}`. **`Class: os-pkgs` → `component_type: os-package`** (base-image OS cruft — judged differently from app deps). `Results[].Class: config` → `component_type: iac` (Dockerfile/k8s misconfig, not a CVE — triage on exposure, no KEV/EPSS).
+- **Grype** (`-o json`): `matches[].vulnerability` (`id`, `severity`, `fix.versions[]`) + `matches[].artifact` (`name`, `version`, `type`).
+- **Snyk / Dependabot / SARIF**: pull `ruleId`/`cve`, the package coordinate, and fixed version from `results[]` / alerts / `runs[].results[]`. SARIF `level` maps to severity.
+- **Unknown / freeform (CSV, markdown, pasted text):** extract the minimum — `id` (CVE/GHSA), `component`, `installed_version`, `fixed_version` if stated. Anything you can't fill is `unknown`, not a guess. Triage proceeds on what you have; record `scanner: <described>` and note reduced confidence.
+
+If you genuinely can't parse a format, say so and ask for `--json`/SARIF rather than guessing at a table.
+
+### Deduplicate before triaging
+
+Scanners — Trivy especially — emit the **same CVE once per affected package** (e.g. `CVE-2026-40393` listed against `libgbm1`, `libgl1-mesa-dri`, `libglx-mesa0`, `mesa-libgallium` = 4 findings, 1 vulnerability). Collapse to **unique `(id, component_type)`**, keeping the list of affected packages on the single entry. Triage and count the deduplicated set — a "200 CVE" image scan is often 30 real advisories. Report both numbers (raw findings → unique advisories) so the noise reduction is visible.
+
+### Container scans also carry non-CVE results — don't drop them
+
+Trivy/Grype image scans include result classes that are **not** package CVEs and need routing, not triage:
+- **secret** (`Class: secret`) — a credential/key found in an image layer (e.g. an `.env` file baked in). Even zero-hit secret *targets* are a smell (why is an env file in the image?). Route to infra/`grimoire-draft`, treat any real hit as a confidential security issue.
+- **config / misconfig** (`Class: config`, `component_type: iac`) — Dockerfile/k8s findings (root user, no resource limits, exposed port, `:latest` base). Triage on exposure; route persistent ones to infra/`grimoire-draft`. Not an app hotfix.
+
+## Step 2 — Reconcile against the current tree FIRST  *(mandatory, highest-leverage)*
+
+**Scan artifacts go stale.** A report from last week was taken against versions you may have already upgraded. Before spending any effort on enrichment or reachability, compare each advisory's `installed_version` against what the repo resolves **right now**:
+
+- Read the live lockfile / manifest: `package-lock.json` / `pnpm-lock.yaml` / `yarn.lock`, `uv.lock` / `poetry.lock` / `requirements.txt`, `go.mod`/`go.sum`, `Cargo.lock`, `Gemfile.lock`. For container/OS findings, the equivalent is "is this image still deployed?" — check the current image tag / Dockerfile base.
+- If the **currently resolved version ≥ `fixed_version`**, the advisory is **`fixed`** → drop it from the queue before enrichment. Record it in the "Already fixed" section as the audit trail.
+- If a manifest comment or prior triage already dismisses the CVE (e.g. `urllib3>=2.7.0  # CVE-2026-44431`), treat as `fixed`/known and don't re-litigate.
+
+This single pass routinely clears the majority of a stale scan and saves the expensive work for findings that are actually still present. **Never file remediation for an advisory without confirming it still exists in the current tree.**
+
+## The enrichment signals (for advisories that survive reconciliation)
+
+Gather what you can. Degrade gracefully — a missing signal is "unknown", not "safe". OS-package and library findings both get KEV/EPSS (they're CVEs); IaC/config findings skip threat-intel and triage on exposure.
+
+### KEV — CISA Known Exploited Vulnerabilities  *(Threat, binary)*
+
+Fetch once per run and match every advisory's `cve`/`aliases`:
+`https://www.cisa.gov/sites/default/files/feeds/known_exploited_vulnerabilities.json`
+
+KEV membership is binary, evidence-grounded, auditor-defensible. **A reachable KEV vulnerability is a hotfix candidate regardless of CVSS.**
+
+### EPSS — Exploit Prediction Scoring System  *(Threat, probability)*
+
+Fetch per CVE (batchable, comma-separated):
+`https://api.first.org/data/v1/epss?cve=CVE-2024-XXXX,CVE-2024-YYYY`
+
+Daily-refreshed probability (0–1) of exploitation in the next 30 days. Ranks the long tail KEV is silent on. Rough bands: `≥0.5` high, `0.1–0.5` elevated, `<0.1` low. A prior, not a verdict.
+
+### Reachability — is the vulnerable code in our execute path?  *(Exposure)* — judge by `component_type`
+
+The strongest noise filter. **How you judge reachability depends on what kind of component it is:**
+
+- **`library` (app dependency):**
+  - *Dev/test only?* Not shipped or run in prod → **not_affected** in prod (`vulnerable_code_not_in_execute_path`). Infer dev/runtime from lockfile groups — there is usually no single flag.
+  - *Imported at all?* `search_graph(name_pattern=<pkg>)` / `search_code(<pkg>)`. Unused transitive → low exposure.
+  - *Vulnerable function reached?* When the advisory names the affected API, `trace_path` / `search_code` to confirm our code calls *that* surface. Not present / not on a reachable path → **not_affected**.
+- **`os-package` (Debian/Alpine/RPM from a container scan):** judge **two separate axes** — *reachability* (is the vulnerable code path called by untrusted input?) drives urgency; *removability* (can we delete it, and what breaks?) drives remediation. **They are not the same — unreachable ≠ removable.** A headless API can't reach Mesa's OpenGL code *and* can't remove Mesa if it arrived transitively behind a package it needs. A C library is only reachable if something in the running app binds to it, so grep the **consumer**, not the C package name (the app never `import`s `libexpat1`). Honor the scanner's fix-state: `will_not_fix`/`end_of_life`/no-`FixedVersion` means **no fix exists** → the lever is accept-with-expiry or a base-image bump/rebuild, **never** an "upgrade X" ticket. **Before recommending any removal or "slim the base image," trace how the package is installed (explicit / transitive / base-image / builder-only) and name the post-change test** — see `./container-scan-triage.md` for the full discipline, the transitive-source and consumer maps, and the anti-patterns. Route image-structure changes to infra/`grimoire-draft`, not app remediation.
+- **`runtime` (the interpreter/build tool itself — e.g. `pip`, `node`, `setuptools`):** is it invoked **at runtime** or only at **build time**? A build-time tool not present/called in the running container → **not_affected** at runtime (`vulnerable_code_not_in_execute_path`); note it as build-image hygiene at most. Check the container entrypoint/CMD.
+- **`container` / `iac` (Dockerfile, k8s, compose misconfig):** not a CVE — no KEV/EPSS. Triage on exposure + control: does the misconfig (root user, no resource limits, exposed port, `:latest` base) actually create reachable risk in our deployment? Route persistent ones to `grimoire-draft`/infra, not an app hotfix.
+
+**Grep can lie — verify the binding.** A bare symbol/name match is not proof: `Price.fromstring()` (the `price-parser` library) is not XML `etree.fromstring()`; a package named in a comment isn't a call. Confirm the match is the actual vulnerable binding (right import, right call site) before asserting `not_affected` **or** `affected`.
+
+**Resolve unknowns now — `under_investigation` is a last resort, not a default.** When grep doesn't settle reachability, work the question before deferring it:
+1. **Trace deeper** — `codebase-memory-mcp` `trace_path` from the entry points (routes/handlers) to the vulnerable binding; read the actual call site, not just its name.
+2. **Ask the decisive question.** Most reachability unknowns collapse to one yes/no the human can answer instantly — ask it inline rather than filing a task. The pattern: *"Does <surface> ever receive attacker-controlled <input>?"* e.g. "Does any endpoint parse user-supplied XML (SAML/SSO metadata, uploads, external responses)?" → "no" makes expat/libxml2 `not_affected` on the spot; "yes" makes them `affected`. One question can clear several findings **and** spare a register entry and a follow-up task.
+3. Only when the answer genuinely needs work nobody in the session can do — a runtime check, a teammate's knowledge, an external dependency — mark **`under_investigation`**, time-box it, and name exactly what must be checked. Don't force a verdict to look decisive; but don't punt one you could resolve with a trace or a question, either.
+
+Record reachability provenance: `graph-verified` (codebase-memory-mcp), `grep-asserted` (fallback), `image-layer` (container scan), or `unknown`.
+
+### Exposure & Controls — our deployment, our mitigations  *(Exposure + Impact damping)*
+
+Read these — do **not** invent a controls config file; the truth already lives here:
+
+- **`.grimoire/docs/context.yml`** — `deployment` (internet-facing vs internal vs lambda/batch), `infrastructure`, `services`. An internal-only service behind an auth gateway has far less exposure than a public endpoint.
+- **MADR decisions** (`.grimoire/decisions/*.md`) — `Security (CIA)` quality-attribute rows and security-relevant decisions (WAF, network isolation, input validation, auth model, tenancy). A documented control that breaks the attack path is a legitimate VEX `inline_mitigations_already_exist` / severity damper.
+- **App config that satisfies (or fails) an advisory's precondition** — many CVEs are conditional ("only when `SESSION_SAVE_EVERY_REQUEST=True`", "only on ASGI", "only if middleware X enabled"). Read the actual setting. A precondition that is **met** raises urgency; one that is **absent** is a clean `not_affected` (`vulnerable_code_cannot_be_controlled_by_adversary` / not in execute path).
+
+If a control that *would* change the verdict is assumed but **not recorded anywhere**, do not credit it silently. Flag the gap and recommend recording it as a MADR via `grimoire-draft` — an undocumented control is not defensible in an audit.
+
+## VEX verdict — the per-advisory status
+
+Assign each surviving advisory a [VEX](https://www.cisa.gov/sites/default/files/2023-04/minimum-requirements-for-vex-508c.pdf) status. This is the noise-suppression layer: only `affected` items become dev work.
+
+| Status | Meaning | Justification codes (for `not_affected`) |
+|---|---|---|
+| `fixed` | Already remediated — current tree resolves ≥ the fixed version (from Step 2). | — |
+| `not_affected` | We are not exploitable. **No dev work.** | `component_not_present`, `vulnerable_code_not_present`, `vulnerable_code_not_in_execute_path`, `vulnerable_code_cannot_be_controlled_by_adversary`, `inline_mitigations_already_exist` |
+| `affected` | Exploitable in our deployment. **Needs a remediation action.** | — (carries an urgency, see below) |
+| `under_investigation` | Can't determine yet (no graph, ambiguous advisory). Time-box it. | — |
+
+Every verdict records *why*. A `not_affected` with a justification code is the auditor-defensible way to dismiss noise; a bare "looks fine" is not.
+
+## Urgency — the decision that matters (for `affected` items only)
+
+| Urgency | Trigger | Action |
+|---|---|---|
+| **hotfix-now** | In **KEV** AND reachable AND exposed; **or** EPSS high + reachable + internet-exposed + no mitigating control; **or** active exploitation against a high-impact surface (auth, PII, RCE on a public endpoint). | Drop everything. Expedited fix branch, out-of-band release. Notify security owner. |
+| **next-release** | Reachable but exposure is damped (internal-only / behind a control), **or** no KEV and low/elevated EPSS, **or** fix requires a non-trivial upgrade / image rebuild with no active-exploitation pressure. | File remediation for the normal testing / release cycle. |
+| **accept (risk-accepted)** | `affected` but low real risk and **no fix available** (no patched version / no newer base image yet). | Record justification + an **expiry / revisit date**. Re-triage on expiry or when a fix ships. Don't let it become permanent. |
+
+Decision tree, in order:
+
+1. Already `fixed` (Step 2)? → done, drop. No enrichment needed.
+2. `not_affected` (reachability / precondition absent)? → done, it's noise. No urgency.
+3. Reachable + (KEV **or** high EPSS) + internet-exposed + no breaking control? → **hotfix-now**.
+4. `affected` but damped (not exposed / control breaks the path / low EPSS / dev-or-build-time only) → **next-release**.
+5. `affected`, no fix exists, low risk → **accept** with expiry.
+
+Default bias: unknown reachability + internet-facing + KEV → **hotfix-now** (fail safe). Unknown reachability + no KEV + low EPSS → **under_investigation** + next-release — don't manufacture an emergency.
+
+## The Contrarian pass — calibrate before you escalate
+
+Before finalizing **any** `hotfix-now` or `affected` verdict, run the **Contrarian calibration pass** (`./review-personas.md` §4.8) over the escalated findings. The Contrarian adds no findings; it challenges the ones we're about to act on. For each escalation ask:
+
+1. **Steel-man "we are not affected."** Strongest case this doesn't matter here — dev/build-only, function never called, base-OS cruft, behind auth + network isolation, precondition absent, input never attacker-controlled. If it holds, drop the urgency (often to `not_affected`).
+2. **Name the assumption.** "Assumes the parser is fed untrusted input." "Assumes this endpoint is public." If it contradicts `context.yml`/a MADR/the actual config, the finding is mis-calibrated.
+3. **Inversion.** If we hotfixed this, what *new* risk ships — a rushed major bump, an untested base-image swap, a breaking transitive change? Is the cure riskier than the disease before the next release window?
+4. **Is doing-nothing-until-release right?** Symptom vs root cause; will it actually trigger; cost of "fix now" vs "fix when it hurts".
+5. **Is severity calibrated?** A `hotfix-now` must clear all of: reachable, exploitable-as-deployed, real blast radius.
+
+Emit per escalation: `[hotfix upheld]` / `[hotfix → next-release]` / `[finding dropped]` with one line of evidence. Summary counts are **post-Contrarian**. Calibration, not veto — a surviving harm path tied to `context.yml`/KEV stands.
+
+## Triage record format
+
+Write `.grimoire/security/vulns/<run-date>/triage.md`:
+
+```markdown
+---
+scanners: [<npm-audit|pip-audit|osv-scanner|trivy|grype|snyk|sarif|other>]
+scan_dates: [<YYYY-MM-DD per source>]
+triaged_date: <YYYY-MM-DD>
+reconciled_against: <lockfile/manifest/image checked>
+kev-feed: <date fetched, or "offline">
+epss-fetched: <true|false>
+reachability: <graph-verified|grep-asserted|image-layer|unknown>
+totals: { raw_findings: N, unique_advisories: N, fixed: N, not_affected: N, affected: N, hotfix_now: N, accepted: N, under_investigation: N }
+---
+
+# Vulnerability Triage — <run-date>
+
+## Hotfix now (drop everything)
+<!-- omit section if empty -->
+### <id> — <component> <version> (<component_type>)
+- **VEX**: affected · **Urgency**: hotfix-now
+- **KEV**: yes/no · **EPSS**: 0.NN · **CVSS**: N.N (<severity>) · **Scanner**: <tool>
+- **Reachable**: <yes — calls X / image-layer / no / unknown> (<provenance>)
+- **Exposure**: <internet-facing endpoint / internal-only / dev/build-only / base-OS>
+- **Controls**: <none that break the path / WAF per ADR-00NN / behind auth gateway>
+- **Precondition**: <CVE condition — met / absent, with the setting checked>
+- **Blast radius**: <RCE / PII read / DoS / info disclosure>
+- **Contrarian**: [hotfix upheld] <one line>
+- **Fix**: upgrade <component> <from> → <to> / rebuild on <base> (or: no fix — mitigation: <...>)
+
+## Next release cycle
+### <id> — <component> (<component_type>)
+- (same fields) · **Contrarian**: [hotfix → next-release] <why damped>
+
+## Risk-accepted (revisit by <date>)
+### <id> — <component>
+- **VEX**: affected · no fix available · **Expiry**: <YYYY-MM-DD> · **Justification**: <...>
+
+## Already fixed (reconciled out — scan was stale)
+<!-- audit trail: dropped before enrichment because current tree is past the fix -->
+- <id> — <component>: current tree resolves <ver> ≥ fixed <ver>
+- <id> — <component>: dismissed in manifest (<comment/prior triage>)
+
+## Not affected (suppressed noise)
+- <id> — <component>: not_affected (`vulnerable_code_not_in_execute_path` — dev-only / build-time / base-OS not invoked)
+- <id> — <component>: not_affected (`vulnerable_code_cannot_be_controlled_by_adversary` — precondition absent: <setting>)
+
+## Under investigation (time-boxed to <date>)
+- <id> — <component>: <what's blocking the call>
+
+## Control gaps surfaced
+- <control> assumed for <id> but not in any decision record → suggest `grimoire-draft`.
+
+## Infra follow-ups (root-cause, not per-CVE)
+<!-- container/IaC hygiene — route to infra/grimoire-draft, not app remediation. Each must state how-installed + post-change test, per container-scan-triage.md. -->
+- <package> (CVE <id>): installed via <explicit line N / transitive via PARENT / base image / builder-only>; depends: <evidence>; removable: <yes-safe / yes-after-removing-PARENT / no-base-OS / no-required-by-Y>; recommendation: <Dockerfile edit / bump-base / accept+document> — test: <build / import / DB connect>.
+- Secret/config result: <e.g. `.env` baked into image layer> → remove from image, route to infra.
+```
+
+## Supply-chain note (separate from CVE triage)
+
+A *known CVE* in a component is what this reference triages. A **dependency add/upgrade** (new package, version bump, floating range, missing lockfile/integrity hashes) is a different risk class — covered by `security-compliance.md` § Supply Chain Defense, a review-time blocker, not a CVE-triage output. Keep them distinct: triage answers "is this known CVE a hotfix?"; supply-chain defense answers "should this change merge at all?".
+
+## Principles
+
+- **Reconcile first.** A stale scan is mostly already-fixed findings. Confirm each advisory still exists in the current tree before any other work — it's the cheapest, highest-leverage pass.
+- **Scanner-agnostic by construction.** Normalize any tool's output into the canonical model, then triage that. Never couple the verdict logic to npm's or pip's field names.
+- **CVSS ranks the world; we triage our deployment.** The whole job is that gap. 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.** Library imports, OS-package usage, runtime-vs-build, and IaC misconfig are judged differently. A flagged base-image OS lib the app never calls is not a prod emergency.
+- **`not_affected` needs a justification code, not a vibe.** That line is the audit trail.
+- **Controls must be recorded to count.** Undocumented WAF/auth/isolation can't damp a verdict — flag the gap.
+- **Fail safe on unknowns, but don't manufacture emergencies.**
+- **The Contrarian calibrates escalations; it does not suppress real signal.**
+- **`accept` is not `ignore`.** It carries an expiry and gets re-triaged.

package/skills/references/principles.md

@@ -0,0 +1,82 @@
+# Grimoire Design Principles
+
+Four principles govern every grimoire artifact and every change. `grimoire-draft`,
+`grimoire-plan`, and `grimoire-review` each enforce them at their own stage. They
+are not style preferences — they are gates. A draft, plan, or design that violates
+one without a stated reason is rejected, not merged.
+
+This file is the single home for the principles (it practices what it preaches —
+the skills cite it rather than restating it).
+
+---
+
+## 1. One right way to do a thing
+
+There is exactly **one** sanctioned way to do each thing in the codebase, and one
+authoritative home for each fact. Two ways to do the same thing is a defect, even
+if both work.
+
+- One capability → one feature spec. One decision → one MADR. One constraint → one
+  register entry. One fact → one home. No capability described in three places.
+- When a second mechanism appears for an existing job, the right move is to delete
+  one and converge — never to keep both "for flexibility."
+- **Tell:** "we could do it this way *or* that way" in a spec/plan. Pick one. Record
+  why in a MADR if the choice is non-obvious; don't leave both paths in the code.
+
+## 2. DRY — don't repeat yourself
+
+Every piece of knowledge has a single, unambiguous representation.
+
+- Don't store what's derivable. Code structure comes from codebase-memory-mcp on
+  demand — never freeze it into a doc that drifts. Generated overviews regenerate;
+  they are not hand-edited.
+- Reuse before write: search the graph for an existing function/utility before
+  writing a new one. Three near-identical copies is the trigger to converge — but
+  do not abstract before the third (see KISS).
+- Duplication of *content* (the same rule in three skill files, the same constant in
+  three modules, the same scenario in feature + MADR) is the target. Eliminate it.
+
+## 3. Don't reinvent the wheel — use existing tools
+
+If an established tool already does a job well, use it. Do not build a parallel
+grimoire mechanism that duplicates it.
+
+- **git** is the wheel for change processes: branches = isolation, `git diff` =
+  staging, `git log` + PR + commit trailers = history and change identity. Do not
+  build change-folder copies, promote/sync steps, or bespoke archive/changelog trees.
+- For auth, crypto, parsing, HTTP, queues, etc. — adopt the battle-tested library.
+  Never roll custom crypto, custom session management, custom auth tokens.
+- Before building any tracking/versioning/state/diff mechanism, ask: does a standard
+  tool already in the stack do this? If yes, wire to it.
+- **Exception that proves the rule:** when no single standard tool exists (e.g. issue
+  tracking is a fractured landscape), don't force-adopt one *and* don't build a
+  general-purpose clone. Keep any local mechanism narrow and purpose-scoped.
+
+## 4. Keep it simple (KISS)
+
+The simplest thing that fully solves the *stated* problem wins.
+
+- Least code, fewest new files, smallest surface area. A few lines in an existing
+  file beats a new module. A standard-library call beats a new dependency. Inline
+  beats a one-line wrapper.
+- No premature abstraction. No `BaseX`/factory/strategy/config-object for a single
+  caller. No speculative generality "for a future second caller" that doesn't exist.
+- Solve the problem in front of you, not the imagined one. Non-goals are real scope
+  boundaries — do not plan or build past them.
+- **Tell:** an abstraction, indirection, or dependency whose only justification is a
+  hypothetical. Cut it.
+
+---
+
+## How the stages apply these
+
+- **draft** — admission-test every artifact: does this fact already have a home
+  (one-right-way/DRY)? Is it behavior (→ feature) or a constraint/decision/structure
+  (→ its own home, not a feature)? Is there an existing tool/library for it
+  (don't-reinvent)? Is the scope the stated problem only (KISS)?
+- **plan** — every task names the single approach (one-right-way), reuses before
+  writing (DRY), follows a proven pattern / existing tool rather than a bespoke one
+  (don't-reinvent), and chooses the least-code option within non-goals (KISS). Flag
+  any task that adds an abstraction, dependency, or second mechanism.
+- **review** — a dedicated principles pass: hunt for duplicate homes, derivable-but-
+  stored facts, reinvented wheels, and speculative complexity. Each is a finding.

package/skills/references/refactor-scan-categories.md

@@ -91,8 +91,8 @@ TODO/FIXME/HACK/XXX comments that have aged.
 ## 2g. Duplication
 
 **How to scan:**
-- Read `.grimoire/docs/.snapshot.json` `duplicates` section if present
-- Or run `config.tools.duplicates` if configured (e.g., jscpd)
+- Run `config.tools.duplicates` if configured (e.g., jscpd), or `grimoire health` (config-driven `duplicates` metric)
+- Plus semantic clones via `search_graph(semantic_query=[...])` (requires codebase-memory-mcp) to catch re-implementations under different names
 - Group by area — within-area dupes are easy to consolidate
 
 **Severity:** high = >30 lines or >3 copies, medium = 10-30 lines or 2 copies, low = <10 lines

package/skills/references/review-personas.md

@@ -26,13 +26,13 @@ Build once, inject as preface to every persona. Findings that don't threaten any
 - `.grimoire/brand/tokens.json` and `.grimoire/brand/voice.md` — brand axis (if exist; see `./brand-tokens-format.md`)
 - `.grimoire/changes/<id>/consult.md` — pre-design consult assumptions + givens (if exists)
 - `.grimoire/changes/<id>/designs/problem.md` — design problem statement (if exists)
-- Tag histogram across `.grimoire/changes/**/*.feature` + `.grimoire/archive/**/*.feature`
+- Tag histogram across `features/**/*.feature` (the live baseline; features are edited in place, so this covers both the change and prior work)
 - All `.grimoire/decisions/*.md` with `status: accepted` — extract ID, title, top Decision Driver
 - Linked manifest's `Why` and `Non-goals` (if a Change trailer / active manifest exists); else PR body or commit messages
 
 ### Feature inventory
 
-- Glob `.grimoire/changes/**/*.feature` + `.grimoire/archive/**/*.feature`
+- Glob `features/**/*.feature` (the live baseline, including this change's edits)
 - Parse: `Feature:` line, first description line, `@tags`
 - Bucket by path prefix (area)
 - If total >80, emit area-level summary only (count + capability one-liner)
@@ -274,7 +274,8 @@ If none of the above pin a rule, **don't invent one**. Style preferences without
 - **Imports**: Order, grouping, and form match the project (relative vs absolute, `.js` extension policy, type-only imports)?
 - **Formatting**: Diff respects `.editorconfig` and formatter rules (indentation, line endings, trailing newline, max line length)? Any formatter-noisy hunks unrelated to the change?
 - **Comments — presence**: Is there a comment whose WHAT is already obvious from the code? Per most projects' comment policies (and grimoire's `AGENTS.md`), explanatory-of-what comments are noise — **suggestion** to remove.
-- **Comments — content**: Do comments reference current task / fix / PR / caller ("added for X", "used by Y", "fix for issue #123")? These rot — **suggestion** to remove or rewrite as durable rationale.
+- **Comments — self-contained**: Does a comment name an external artifact that moves independently — a feature/scenario/`.feature`, MADR/ADR number, change-id, ticket/PR, specific test, or tag code (`LOG-OBS-003`)? These orphan — **suggestion** to rewrite in terms of the code itself (`code-quality.md` §7). Generic descriptive words (test, feature) are fine; identifiers pointing elsewhere are not.
+- **Comments — no essays**: Does a docstring lead with a prose paragraph before its params, or restate types in prose? Keep the summary to 1–2 terse lines — **suggestion** to compress; design rationale belongs in a decision record.
 - **Comments — style**: Match the project's comment form (`//` vs `/* */` vs `#`, JSDoc/TSDoc/docstring conventions)?
 - **Docstrings**: New public functions/classes — does the project require docstrings? If yes (per `comment_style` or visible convention), missing docstring = **suggestion**. If no, added boilerplate docstrings = **suggestion** to remove.
 - **Dead comments**: Commented-out code in the diff = **suggestion** to delete.

package/skills/references/testing-contracts.md

@@ -41,7 +41,7 @@ For contract regression tests: if the client starts reading a new field or stops
 Before importing a module, calling a function, or adding a dependency — confirm it exists.
 
 **Imports and functions:**
-- Check area docs' Reusable Code table first (exact paths and line numbers)
+- Query the graph first (`search_graph` / `get_code_snippet`) for the exact symbol, path, and signature
 - If importing from a file you haven't read, read it first
 - If an import fails, don't guess — read the actual module for the real export name
 

package/templates/accepted-risks.yml

@@ -0,0 +1,47 @@
+# Grimoire Risk-Accepted Vulnerabilities
+# Vulnerabilities triaged as `affected` but consciously accepted — because no fix
+# exists yet, the residual risk is low, or the fix isn't worth it right now.
+#
+# Written by: grimoire-vuln-remediate (from a grimoire-vuln-triage `accept` verdict)
+# Read by:    grimoire-vuln-triage — an UNEXPIRED entry auto-suppresses that CVE as
+#             known-accepted so it doesn't re-flood the queue. An EXPIRED entry is
+#             re-surfaced for re-triage.
+#
+# Each entry requires: a CVE, the component, the VEX justification, a reason, an
+# owner, an accepted date, and an expiry (when to re-evaluate).
+#
+# An accepted risk is NOT closed — it is scheduled for review. Don't accept the same
+# CVE twice; update the existing entry.
+#
+# Created by: grimoire init
+# Last updated: YYYY-MM-DD
+
+accepted: []
+
+# --- Examples ---
+#
+# No upstream fix available — low residual risk, reachable but damped:
+#
+#   - cve: CVE-2026-44405
+#     component: paramiko
+#     component_type: library
+#     vex_justification: inline_mitigations_already_exist
+#     reason: "SHA-1 accepted in rsakey; outbound SFTP only, to tenant-configured
+#              trusted hosts. No upstream fix. EPSS ~0, not in KEV. Blast radius:
+#              low (integration, not the public API)."
+#     owner: fred
+#     accepted: 2026-06-04
+#     expires: 2026-09-04
+#
+# Base-image OS package with no patched version yet (not removable — transitive):
+#
+#   - cve: CVE-2026-40356
+#     component: krb5 (libgssapi-krb5-2, libk5crypto3, libkrb5-3, libkrb5support0)
+#     component_type: os-package
+#     vex_justification: vulnerable_code_not_in_execute_path
+#     reason: "Kerberos DoS. No gssapi/kerberos usage in app; pulled transitively
+#              via libpq5 (Postgres). Not removable without breaking libpq.
+#              status=affected, no FixedVersion. Re-check on base-image bump."
+#     owner: fred
+#     accepted: 2026-06-04
+#     expires: 2026-09-04