@kiwidata/grimoire 0.1.4 → 0.1.5

package/skills/grimoire-plan/SKILL.md

@@ -38,7 +38,7 @@ Derive implementation tasks from approved Gherkin features and MADR decisions. T
 - "See if there's an existing utility for Z"
 - "TODO: check if this conflicts with…"
 
-Resolve each one yourself before writing the task. Tools: codebase-memory-mcp (`search_graph`, `trace_path`, `get_code_snippet`), `.grimoire/docs/<area>.md` reusable-code tables, `Grep`, neighbor files. The task should state the *answer* ("Reuse `parse_invoice` in `src/billing/parsing.py:42`" or "No existing utility — write new"), never the *question*.
+Resolve each one yourself before writing the task. Tools: codebase-memory-mcp (`search_graph`, `trace_path`, `get_code_snippet`) for symbols and reusable code, `.grimoire/docs/<area>.md` for conventions/boundaries, `Grep`, neighbor files. The task should state the *answer* ("Reuse `parse_invoice` in `src/billing/parsing.py:42`" or "No existing utility — write new"), never the *question*.
 
 **2. Clarify or propose, never assume.** When the spec is ambiguous or silent on something you need to plan:
 
@@ -48,6 +48,14 @@ Resolve each one yourself before writing the task. Tools: codebase-memory-mcp (`
 
 The plan implements what's approved. It does not expand scope to hit a checklist.
 
+**3. Plan to the principles.** Every task is gated by the four principles in `../references/principles.md` — **one right way, DRY, don't reinvent the wheel, keep it simple.** Concretely, before writing each task:
+- **One right way:** name the single sanctioned approach. If the spec leaves two ways open, pick one (record why in the task) — never plan both.
+- **DRY:** reuse before write (search the graph); don't plan a task that stores a fact already derivable from code/mcp or already homed elsewhere.
+- **Don't reinvent:** prefer an existing tool/library/proven pattern over a bespoke mechanism. git for change process, standard libs for crypto/auth/parsing.
+- **Keep it simple:** choose the least-code option inside the non-goals. Flag any task that adds an abstraction, a dependency, or a second mechanism — it needs an explicit reason.
+
+These are gates, not aspirations — a task that adds a duplicate home or a reinvented wheel is rejected, not refined.
+
 ### 1. Select Change
 - List active changes in `.grimoire/changes/`
 - If multiple, ask user which one to plan
@@ -59,9 +67,10 @@ The plan implements what's approved. It does not expand scope to hit a checklist
 
 **Always read:**
 - `manifest.md` for the change summary, **including complexity level, Assumptions, Pre-Mortem, and Prior Art sections**
-- All proposed `.feature` files
-- All proposed decision records, **including Cost of Ownership sections**
-- The current baseline (`features/`, `.grimoire/decisions/`) for context on what's changing
+- All `.feature` files for this change (edited live in `features/` on the branch)
+- All decision records for this change (edited live in `.grimoire/decisions/`), **including Cost of Ownership sections**
+- `.grimoire/docs/constraints.md` — any constraints (security/NFR/observability) this change adds or touches. These produce `unit-invariant` tasks, not scenarios.
+- The current baseline (`features/`, `.grimoire/decisions/`) via `git diff main` to see exactly what this change adds vs. what already existed
 
 **Validate the build-vs-buy decision:**
 - Check that `manifest.md` has a **Prior Art** section documenting what existing solutions were researched. If it's missing or empty, **stop and tell the user** — planning without a build-vs-buy analysis produces plans that ignore cheaper alternatives.
@@ -70,21 +79,21 @@ The plan implements what's approved. It does not expand scope to hit a checklist
 - If the decision was **hybrid** (adopt for part, build for part), ensure the boundary between adopted and custom code is clear in the tasks.
 
 **Read from grimoire docs (these replace codebase exploration):**
-- **`.grimoire/docs/<area>.md`** for each area the change touches — these contain: key files with responsibilities, reusable utilities (exact function names, file paths, line numbers), naming conventions, structural patterns, and "Where New Code Goes" guidance. This is the information that lets you write tasks with exact file paths without reading every source file.
+- **`.grimoire/docs/<area>.md`** for each area the change touches — these contain Purpose, Boundaries, Conventions (naming/structure), and "Where New Code Goes" guidance. For key files, exact symbols, reusable utilities (function names, file paths, line numbers), and call graphs, **query the graph** — `search_graph` / `get_code_snippet` / `get_architecture`. Area docs give you intent and placement; the graph gives you the live structure to write exact file paths and reuse existing code.
 - **`.grimoire/docs/data/schema.yml`** — the full data model: every table/collection, field types, relationships, indexes, and external API contracts with `source:` pointers to ORM code. Read this instead of reading individual model files.
 - **`.grimoire/docs/context.yml`** — the project's deployment environment, related services, infrastructure dependencies, CI/CD pipelines, and observability setup. Read this to understand deployment constraints (e.g., Lambda means no long-running processes, Kubernetes means you may need health check endpoints), cross-service boundaries (e.g., auth is handled by a sibling service, not this project), and infrastructure available at runtime (e.g., Redis is available for caching, RabbitMQ for async tasks).
-- **`.grimoire/docs/.snapshot.json`** `duplicates` section if present — existing clones in areas you're touching, so tasks consolidate rather than add more.
+- Existing duplication in areas you're touching — query codebase-memory-mcp (`search_graph` for similar functions) or run `grimoire health` (its config-driven `duplicates` metric) so tasks consolidate rather than add more clones.
 
 **Read proposed data changes:**
 - **`data.yml`** if present — proposed schema changes need migration and model tasks
 
 **Staleness gate:** For each area doc loaded, check its `last_updated` date against `git log -1 --format=%ci <directory>`. If any doc is older than the most recent commit to its directory, it's stale — the file paths, utility names, and patterns it describes may no longer be accurate.
 
-- **Level 1-2:** Warn ("Area doc for `<area>` is behind recent commits — reusable utilities and file paths may be wrong") and proceed. Note inferred paths with `<!-- inferred: area doc may be stale -->`.
+- **Level 1-2:** Warn ("Area doc for `<area>` is behind recent commits — its boundaries/conventions may be wrong; rely on the graph for structure") and proceed. Note inferred paths with `<!-- inferred: area doc may be stale -->`.
 - **Level 3-4:** Treat as a blocker. Do not generate tasks until the user refreshes stale docs via `grimoire-discover` targeted refresh. Planning with stale docs at this complexity produces wrong file paths and misses recent utilities — the cost of re-planning outweighs the cost of refreshing first.
 
 **Read specific source files only when:**
-- Area docs don't exist yet (tell the user to run `grimoire map` + `/grimoire:discover` first — planning without area docs produces worse tasks)
+- Area docs don't exist yet (tell the user to run `/grimoire:discover` first — planning without area docs produces worse tasks)
 - Area docs exist but you need to verify a specific implementation detail (e.g., exact function signature, exact import path)
 - You need to read existing step definitions to understand the test setup
 
@@ -133,11 +142,22 @@ Level 1-2 changes with minor gaps may proceed; level 3-4 with multiple gaps shou
 **If no real gaps**, proceed directly to task generation.
 
 ### 4. Generate Tasks
-Create `.grimoire/changes/<change-id>/tasks.md`. **Every scenario must produce both production code AND tests.** Tasks are structured as pairs: step definitions first, then production code.
+Create `.grimoire/changes/<change-id>/tasks.md`. **Every task produces both production code AND a test — but the test level matches the artifact the task derives from.** Tasks are structured as pairs: the failing test first, then the production code.
+
+**Tag every implementation task with a `verify:` level** — this tells `grimoire-apply` which test vehicle to use. Match the artifact:
+
+| Task derives from | `verify:` | Test vehicle |
+|-------------------|-----------|--------------|
+| a `.feature` scenario (actor-observable behavior) | `scenario` | step definitions + Gherkin |
+| a constraint in `constraints.md` (security/NFR/observability) | `unit-invariant` | unit/integration test asserting the invariant |
+| an ADR consequence, refactor, or internal change with no spec | `characterization` | unit / characterization test |
+
+**Do not plan a `.feature` scenario task for a constraint or an internal change.** Constraints get `unit-invariant` unit tests; internal changes get `characterization` tests. Forcing Gherkin onto a non-behavioral concern is the antipattern that fills feature files with slop (one right way: behavior → scenario, everything else → unit test).
 
 **THE PLAN'S SCOPE IS WHAT WAS APPROVED.** Tasks may only derive from:
-- Approved `.feature` scenarios in this change
-- Approved ADRs in this change (and their Confirmation sections)
+- `.feature` scenarios in this change → `verify: scenario`
+- Constraints added/touched in `.grimoire/docs/constraints.md` → `verify: unit-invariant`
+- ADRs in this change (and their Confirmation sections) → `verify: unit-invariant` or `characterization`
 - `data.yml` entries in this change
 - The manifest's Assumptions, Pre-Mortem mitigations, and Prior Art borrowings
 - Verification tasks (run feature suite, run project suite, validate ADR confirmation)
@@ -259,8 +279,8 @@ Follow the rules in `../references/testing-contracts.md`. Key points: mock at HT
 - If a library was rejected for a specific reason (e.g., doesn't support X), add a comment to the relevant task noting this so future developers don't re-evaluate the same option
 
 **Existing code to reuse:**
-- If `.grimoire/docs/` has area docs, check the Reusable Code tables for utilities that apply to this change
-- If the snapshot has duplicate data, check whether the area you're touching already has clones — tasks should consolidate rather than add more
+- Query the graph (`search_graph` by concept/name) for existing utilities that apply to this change; area docs give conventions, the graph gives the reusable symbols
+- If `grimoire health`/mcp shows existing clones in the area you're touching, tasks should consolidate rather than add more
 - Add a "Reuse" section at the top of tasks.md listing specific functions/classes to import instead of rewriting
 
 **Verification (always last):**
@@ -282,12 +302,12 @@ The tasks file starts with a context block so any LLM can orient without re-read
 
 ## 1. <Capability/Area>
 <!-- context:
-  - .grimoire/changes/<change-id>/features/<capability>/<name>.feature
+  - features/<name>.feature
   - .grimoire/docs/<area>.md
   - src/<area>/<file-to-edit>.ts
   - tests/<area>/<test-file>.ts
 -->
-- [ ] 1.1 Write step defs in `<exact path>` for scenario: "<scenario name>" in `<file>`
+- [ ] 1.1 (verify: scenario) Write step defs in `<exact path>` for scenario: "<scenario name>" in `features/<file>`
       - Given: <what the step does, what it calls>
       - When: <what the step does, what it calls>
       - Then: <what to assert — specific expected values/states>
@@ -295,32 +315,40 @@ The tasks file starts with a context block so any LLM can orient without re-read
       - <specific function/class/view to create or modify>
       - <specific behavior to implement>
       - <edge cases to handle>
-- [ ] 1.3 Write step defs in `<exact path>` for scenario: "<next scenario>"
-      ...
-- [ ] 1.4 Implement in `<exact path>`:
-      ...
 
-## 2. Shared Steps
+## 2. Constraints
+<!-- context:
+  - .grimoire/docs/constraints.md
+  - src/<area>/<file-to-edit>.ts
+  - tests/<area>/<unit-test-file>.ts
+-->
+- [ ] 2.1 (verify: unit-invariant) Write unit test in `<exact path>` asserting constraint: "<assertion from constraints.md>"
+      - Arrange: <setup>
+      - Assert: <the invariant — exact expected behavior, no Gherkin>
+- [ ] 2.2 Implement in `<exact path>`:
+      - <specific change that satisfies the invariant>
+
+## 3. Shared Steps
 <!-- context:
   - tests/step_defs/common.py
-  - .grimoire/changes/<change-id>/features/<all relevant .feature files>
+  - features/<all relevant .feature files>
 -->
-- [ ] 2.1 Add to `<exact path>`:
+- [ ] 3.1 Add to `<exact path>`:
       - Given "<step text>": <what it does>
       - Given "<step text>": <what it does>
 
-## 3. Architecture
+## 4. Architecture
 <!-- context:
-  - .grimoire/changes/<change-id>/decisions/<nnnn-title>.md
+  - .grimoire/decisions/<nnnn-title>.md
   - src/<files affected by decision>
 -->
-- [ ] 3.1 In `<exact path>`: <specific change from ADR>
-- [ ] 3.2 Add test in `<exact path>`: <ADR confirmation check — what to assert>
+- [ ] 4.1 (verify: characterization) In `<exact path>`: <specific change from ADR>
+- [ ] 4.2 Add test in `<exact path>`: <ADR confirmation check — what to assert>
 
-## 4. Verification
-- [ ] 4.1 Run `<exact test command>` — all new scenarios green
-- [ ] 4.2 Run `<exact test command>` — no regressions
-- [ ] 4.3 Run `<exact test command>` — full project suite
+## 5. Verification
+- [ ] 5.1 Run `<exact test command>` — all new scenarios green
+- [ ] 5.2 Run `<exact test command>` — no regressions
+- [ ] 5.3 Run `<exact test command>` — full project suite
 ```
 
 **Context blocks are mandatory.** Every task section (except Verification) must have a `<!-- context: ... -->` listing the files needed. This serves two purposes:
@@ -330,11 +358,13 @@ The tasks file starts with a context block so any LLM can orient without re-read
 ### 6. Quality Check
 Before presenting to the user, verify the plan:
 - [ ] Every task references a specific file path (no "implement the feature")
-- [ ] Every step definition task describes what to assert (no "write a test")
+- [ ] Every implementation task carries a `verify:` tag matching its source artifact — `scenario` only for `.feature` behavior; `unit-invariant` for constraints; `characterization` for internal/refactor. No `.feature` scenario task for a constraint or internal change.
+- [ ] Every test task describes what to assert (no "write a test")
 - [ ] Every implementation task describes what to create/modify (no "add the code")
 - [ ] The verification section has the exact commands to run
-- [ ] Tasks are ordered: shared steps → step defs → production code → verification
+- [ ] Tasks are ordered: shared steps → test → production code → verification
 - [ ] No task requires the LLM to make architectural decisions — those should already be in the ADR
+- [ ] **Principles gate** (`../references/principles.md`): no task introduces a duplicate home for an existing fact (DRY), a second way to do an existing thing (one right way), a reinvented wheel where a tool/library/proven pattern exists (don't reinvent), or an abstraction/dependency justified only by a hypothetical (KISS). Any that does has a stated reason.
 
 If any task is too vague, make it more specific before presenting. Read more codebase if needed.
 

package/skills/grimoire-pr/SKILL.md

@@ -17,14 +17,14 @@ Generate a pull request description from grimoire change artifacts and optionall
 - Loose match: "PR", "pull request", "ready to merge", "create PR"
 
 ## Routing
-- Tasks incomplete or finalize not done → `grimoire-apply` first. Do not create a PR before the change is finalized — PR must reflect the archived state (decisions promoted, manifest archived, change directory removed).
+- Tasks incomplete or finalize not done → `grimoire-apply` first. Do not create a PR before the change is finalized — the PR reflects the finished branch state (decisions accepted, change folder removed).
 - Haven't committed yet → `grimoire-commit` first
 - Want a pre-merge design review → this skill includes optional post-implementation review
 
 ## Prerequisites
-- Change has been finalized: `.grimoire/changes/<change-id>/` is removed, manifest is in `.grimoire/archive/`
-- All decisions promoted to `.grimoire/decisions/`
-- The change is on a feature branch (created during apply)
+- Change has been finalized: `.grimoire/changes/<change-id>/` is removed (manifest/tasks were ephemeral scaffolding)
+- Decision records are live in `.grimoire/decisions/` with status `accepted`
+- The change is on a feature branch (created during draft/apply); its diff vs. `main` is the change
 
 ## Workflow
 
@@ -117,9 +117,8 @@ Check that the branch is pushed to the remote before creating. If not, offer to
 
 ### 6. Link Back
 After PR creation:
-- Update manifest's status to `complete` if not already
-- Add the PR URL to the manifest as a comment or field
-- Suggest running `grimoire archive <change-id>` to complete the lifecycle
+- The `Change: <change-id>` trailer on the commits links them to the change; the PR body + git log are the durable record (the change folder was already removed at finalize).
+- Suggest merging the PR to complete the change. There is no archive step — git history is the history.
 
 ## Important
 - The PR description must trace back to grimoire artifacts — this is what makes the audit trail work.
@@ -129,4 +128,4 @@ After PR creation:
 - If tasks are incomplete, warn the user but don't block PR creation — they may want a draft PR.
 
 ## Done
-When the PR is created (or description is presented for manual creation), the workflow is complete. Suggest `grimoire archive <change-id>` to complete the lifecycle.
+When the PR is created (or description is presented for manual creation), the workflow is complete. Suggest merging the PR to complete the change — git history + the `Change:` trailer are the record; there is no separate archive step.

package/skills/grimoire-pr-review/SKILL.md

@@ -64,7 +64,7 @@ git log <base>..<head> --format="%B" | grep -E "^Change:"
 
 If present:
 - Change ID = trailer value
-- Load artifacts: first check `.grimoire/changes/<change-id>/` (in-progress), then `.grimoire/archive/*<change-id>*/` (archived). Try the PR's head branch checked out locally if needed.
+- Load artifacts: check `.grimoire/changes/<change-id>/` for an active change. If the change is already finalized/merged the change folder is gone — read the artifacts from the PR's head branch (`git diff main` shows the live `features/`, `.grimoire/decisions/`, `.grimoire/docs/constraints.md`) and use the `Change:` trailer to correlate commits.
 - Read `manifest.md`, all `.feature` files in the change, decision records, `tasks.md`, `data.yml`
 - Also grep for `Scenarios:` and `Decisions:` trailers to scope review to the named items
 

package/skills/grimoire-refactor/SKILL.md

@@ -26,7 +26,7 @@ Systematically find, prioritize, and plan tech debt reduction. Combines automate
 ## Prerequisites
 - A grimoire-initialized project (`.grimoire/` exists)
 - Git history available (hotspot analysis needs `git log`)
-- Ideally: `grimoire map` + `/grimoire:discover` already run (area docs help contextualize findings)
+- Ideally: codebase-memory-mcp indexed (live structure/duplication intelligence) + `/grimoire:discover` run (area intent docs help contextualize findings)
 
 ## Debt Item Format
 
@@ -113,7 +113,7 @@ Run applicable scans from the categories in `../references/refactor-scan-categor
 - **Circular dependencies** — tight coupling between modules
 - **Dependency staleness** — uses `config.tools.dep_audit` or package manager outdated commands
 - **Broken promises** — aged TODO/FIXME/HACK comments via `grep` + `git blame`
-- **Duplication** — textual clones via `.snapshot.json` or `config.tools.duplicates`; plus semantic duplicate detection via `search_graph(semantic_query=[...])` to find re-implementations under different names (requires `codebase-memory-mcp`)
+- **Duplication** — textual clones via `config.tools.duplicates` or `grimoire health` (config-driven duplicates metric); plus semantic duplicate detection via `search_graph(semantic_query=[...])` to find re-implementations under different names (requires `codebase-memory-mcp`)
 - **Dead code** — uses `config.tools.dead_code` or `codebase-memory-mcp` graph queries
 - **Test debt** — high complexity + low coverage
 - **Pattern divergence** — code that contradicts established codebase patterns; uses `codebase-memory-mcp` peer group analysis + hallucinated reference detection (skip if graph not indexed)

package/skills/grimoire-review/SKILL.md

@@ -95,6 +95,12 @@ Persona scope for design review:
 - 4.6 Code Style Reviewer — **skip** (no code yet; runs only on diff reviews)
 - 4.7 Adversarial User — engage per matrix; criteria in `../references/adversarial-personas.md`
 - 4.8 Contrarian — runs last when any persona produced a blocker; calibrates other personas' findings post-hoc
+- 4.9 Principles Auditor — **runs on every review (complexity ≥ 2), always.** Audits the design against the four principles in `../references/principles.md` and raises a finding for each violation lacking a stated reason:
+  - **One right way** — does any artifact introduce a second way to do something the codebase already does? Does a spec leave two approaches open ("X or Y")? → blocker until one is chosen.
+  - **DRY** — is any fact given a second home (a capability in feature + MADR + constraint; a constant/rule duplicated)? Does any task store something derivable from code/mcp? → blocker.
+  - **Don't reinvent the wheel** — does any task build a mechanism that an existing tool/library/proven pattern already provides (custom crypto/auth, a bespoke change-tracking/diff/staging process where git suffices)? → blocker.
+  - **Keep it simple** — any abstraction, indirection, new dependency, or new file justified only by a hypothetical, or scope reaching past a non-goal? → suggestion (blocker if it adds a maintained surface).
+  - Also enforce the **artifact-jurisdiction** rule: any `.feature` scenario that is really a constraint (security/NFR/observability), an internal technical detail, or a non-functional concern is a blocker — it belongs in `constraints.md` or a MADR, not Gherkin.
 
 ### 5.5 Visual Fidelity (cheap tier)
 
@@ -144,6 +150,12 @@ Compile into the standard report layout (§5 of the personas reference):
 - **[suggestion]** [axe-color-contrast] `designs/preview.html` — Element has insufficient color contrast 3.8. Impact: serious.
 (or: "axe-core: no violations." / "axe-core not installed — install `@axe-core/cli` for accessibility checks.")
 
+## Principles Auditor
+- **[blocker]** [DRY] PII-scrubbing behavior is specified in both `features/pii-log-scrubbing.feature` and ADR-0008 — one authoritative home. Move to `constraints.md`, link the MADR.
+- **[blocker]** [jurisdiction] `features/logging-observability.feature` describes internal log structure (no external actor) — belongs in `constraints.md`, not a `.feature`.
+- **[suggestion]** [KISS] Task 3.2 adds a `BaseExtractor` for a single caller — inline until a second extractor exists.
+(or: "No principle violations found.")
+
 ## Contrarian                      <!-- omit when zero findings from all personas -->
 - **[blocker upheld]** ...
 - **[blocker → suggestion]** ...

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
@@ -236,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
 
@@ -251,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.