@kiwidata/grimoire 0.1.4 → 0.1.6

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
@@ -55,13 +63,11 @@ The plan implements what's approved. It does not expand scope to hit a checklist
 
 ### 2. Read All Artifacts
 
-**Grimoire docs first, codebase second.** The `.grimoire/docs/` directory is a pre-computed map of the codebase — it tells you where code lives, what utilities exist, what patterns to follow, and what the data layer looks like. Read these *instead of* exploring the raw codebase. Only read specific source files when the docs don't have what you need.
+Read the change's artifacts following `../references/artifact-map.md` — it defines what each file is, the grimoire-docs-first / graph-for-structure discipline, and the staleness gate. Plan-specific reading on top of that:
 
-**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
+- `.grimoire/docs/constraints.md` — any constraints (security/NFR/observability) this change touches. These produce `unit-invariant` tasks, not scenarios.
+- The current baseline (`features/`, `.grimoire/decisions/`) via `git diff main` — exactly what this change adds vs. what already existed.
+- Existing duplication in areas you're touching — `search_graph` for similar functions, or `grimoire health` (its `duplicates` metric) — so tasks consolidate rather than clone.
 
 **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.
@@ -69,27 +75,6 @@ The plan implements what's approved. It does not expand scope to hit a checklist
 - If the decision was to **build custom**, verify the manifest documents (1) what existing tools were considered, (2) the specific requirements they don't meet, and (3) what design patterns are being borrowed from prior art.
 - 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/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.
-
-**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 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 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
-
-**Do NOT read the entire codebase** for "context." The plan skill's job is to produce tasks with specific file paths and specific assertions. Area docs + data schema give you this. Reading dozens of source files wastes context window and doesn't produce better plans.
-
 ### 3. Check Specification Completeness
 
 Before generating tasks, evaluate whether the specifications are detailed enough to plan against. Underspecified requirements produce vague tasks, which produce wrong code.
@@ -133,11 +118,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 +255,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 +278,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 +291,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 +334,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,13 +64,14 @@ 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
 
 If no `Change:` trailer exists, that's itself a finding for a grimoire-managed repo: flag as **suggestion** ("commits missing audit trailer — `grimoire trace` won't find this PR") unless the project clearly doesn't use grimoire.
 
 ### 4. Gather Project Context
+See `../references/artifact-map.md` for what each artifact is and the grimoire-docs-first / staleness discipline.
 - `.grimoire/config.yaml` — language, tools, `commit_style`, `comment_style`, `project.compliance`, `dep_audit`
 - `.grimoire/docs/context.yml` — deployment environment, related services
 - `.grimoire/docs/data/schema.yml` — current data baseline

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)
@@ -209,7 +209,7 @@ For each item the user approves to fix:
 4. Hand off to `/grimoire:plan` for task generation, then `/grimoire:apply` for implementation
 
 **Refactoring-specific guidance for the plan/apply stages:**
-- **All existing tests must keep passing.** A refactoring that breaks tests is not a refactoring.
+- **Capture a baseline first, then keep it.** Apply records which tests were already failing at change start (`baseline.md`, see `../references/test-baseline.md`). For a refactor this is the whole safety net: "passing" means *no new failures vs the baseline*, not "zero failures." A test red before you started is pre-existing and accepted; a test you turn red is the refactor breaking behavior — and that means it's not a refactoring. Diff against the baseline after each incremental move.
 - **Prefer incremental moves over big-bang rewrites.** Move one function at a time, run tests after each move.
 - **Add tests before refactoring if test debt is part of the item.** You need a safety net before restructuring.
 - **Update imports incrementally.** When moving code to a new module, re-export from the old location first, then update consumers, then remove the re-export.

package/skills/grimoire-review/SKILL.md

@@ -42,7 +42,7 @@ This step is optional. The user can skip it by saying "skip review" or "go strai
 - If only one, confirm it
 
 ### 2. Gather Context
-Read all artifacts for the change:
+Read all artifacts for the change — see `../references/artifact-map.md` for what each is and the grimoire-docs-first / staleness discipline:
 - `manifest.md` — change summary, scope, **and Prior Art section** (build-vs-buy rationale)
 - All `.feature` files — behavioral specifications
 - All decision records — architectural choices
@@ -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
@@ -41,6 +41,7 @@ Two modes:
 ### 2. Load Artifacts
 For change verification:
 - Read `manifest.md`, proposed `.feature` files, decision records, `tasks.md`
+- Read `baseline.md` if present (the test state captured at change start) — it's how you tell a regression from a failure that was already red
 
 For baseline verification:
 - Read all `features/**/*.feature` and `.grimoire/decisions/*.md`
@@ -76,6 +77,17 @@ Flag issues:
 - Decision's Confirmation criteria not verifiable → WARNING
 - Decision consequences not addressed → WARNING
 
+### 3.C2 Regression vs Baseline
+
+Run the configured suites (`config.tools.unit_test`, `config.tools.bdd_test`) and classify each failure against `baseline.md`:
+
+- Failing now **and** in the baseline → **pre-existing**, already accepted by the user at change start. Not a regression. Do not blame the change.
+- Failing now, **not** in the baseline → **regression** introduced by this change → CRITICAL. Must be fixed before the change finalizes.
+- Passing now, failing in the baseline → incidentally fixed; note it, don't require it.
+- **No `baseline.md` / baseline skipped** → you cannot classify. List all failures and say plainly they're untriaged. Do NOT assert "existing tests pass" or call anything "pre-existing" without a baseline to back it.
+
+The rule: a failure is "pre-existing" only if it's in `baseline.md`. Otherwise it's the change's. Full protocol: `../references/test-baseline.md`.
+
 ### 3.D Test Quality Intelligence
 
 Go beyond "does a step definition exist?" to "would this test catch a real bug?"
@@ -236,8 +248,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 +263,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.