@kiwidata/grimoire 0.1.5 → 0.2.0

package/skills/grimoire-verify/SKILL.md

@@ -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?"

package/skills/references/artifact-map.md

@@ -0,0 +1,45 @@
+# Artifact Map & Reading Discipline
+
+Loaded by skills that read a change's specs before acting (`grimoire-plan`, `grimoire-draft`, `grimoire-design`, `grimoire-review`, `grimoire-pr-review`). This is the single home for **what each grimoire artifact is** and **how to read them**. Skills link here instead of restating it; they keep only the reading focus specific to their job.
+
+---
+
+## The artifacts
+
+Per-change (under `.grimoire/changes/<change-id>/`):
+
+- **`draft.md`** — the living design doc the change was designed on (diagram/sketch, decision ledger, pseudo-code, Decided/Open ledger). The single source the other artifacts were **projected** from at the end of `grimoire-draft`. Ephemeral: retained read-only as the agreed-design reference through the pipeline, deleted when `grimoire-apply` clears the change folder. Read it for the *intent and rationale* behind the projected artifacts; the features/constraints/decisions remain the authoritative homes.
+- **`manifest.md`** — change summary, complexity level, and the Why. Level 3-4 also carry Assumptions, Pre-Mortem, and **Prior Art** (the build-vs-buy rationale). Generated from `draft.md` at projection.
+- **`features/*.feature`** — behavioral specifications. Edited live in `features/` on the branch.
+- **decision records** — architectural choices for this change, edited live in `.grimoire/decisions/`, including Cost of Ownership sections.
+- **`tasks.md`** — the implementation plan (present once planned).
+- **`data.yml`** — proposed schema changes (present only when the change touches the data model).
+
+Project-wide (under `.grimoire/`):
+
+- **`config.yaml`** — language, tools, conventions, `comment_style`, `commit_style`, `compliance`, `dep_audit`.
+- **`docs/<area>.md`** — per-area Purpose, Boundaries, Conventions, and "Where New Code Goes". Intent and placement, not live structure.
+- **`docs/data/schema.yml`** — the full data model: tables/collections, field types, relationships, indexes, external API contracts with `source:` pointers. Read this instead of individual model files.
+- **`docs/context.yml`** — deployment environment, related services, infrastructure dependencies, CI/CD, observability. Tells you runtime constraints (Lambda → no long-running processes), cross-service boundaries (auth lives in a sibling service), and what's available (Redis, RabbitMQ).
+- **`brand/tokens.json`**, **`brand/voice.md`** — design grounding (see `brand-tokens-format.md`).
+
+---
+
+## Reading discipline
+
+**Grimoire docs first, codebase second.** `.grimoire/docs/` is a pre-computed map — where code lives, what utilities exist, what patterns to follow, what the data layer looks like. Read it *instead of* exploring raw source. Read specific source files only when the docs don't have what you need.
+
+**Graph for live structure.** Area docs give intent and placement; they do not carry exact symbols. For function names, file paths, line numbers, reusable utilities, and call graphs, query the graph — `search_graph` / `get_code_snippet` / `get_architecture`. Combine the two: area doc says *where new code goes*, the graph says *what's already there to reuse*.
+
+**Do NOT read the entire codebase for "context."** Area docs + data schema + the graph already give you specific paths and assertions. Reading dozens of source files wastes context and does not produce better output. Read specific source only to verify a detail the docs can't answer (exact signature, exact import path, existing step-definition setup).
+
+---
+
+## Staleness gate
+
+For each area doc you load, compare its `last_updated` against `git log -1 --format=%ci <directory>`. If the doc is older than the most recent commit to its directory, it's stale — its paths, utility names, and patterns may be wrong.
+
+- **Level 1-2:** warn (`Area doc for <area> is behind recent commits — rely on the graph for structure`) and proceed. Mark inferred paths with `<!-- inferred: area doc may be stale -->`.
+- **Level 3-4:** blocker. Do not proceed until the user refreshes via `grimoire-discover` targeted refresh. Acting on stale docs at this complexity produces wrong paths and misses recent utilities — re-doing the work costs more than refreshing first.
+
+If area docs don't exist at all, tell the user to run `/grimoire:discover` first.

package/skills/references/review-personas.md

@@ -227,12 +227,18 @@ Every security finding gets OWASP 2021 + CWE tags. See CWE quick-reference in `.
 
 Skip if change is purely internal.
 
+**Coverage-gap routing (apply before recommending any new artifact).** A coverage gap does NOT default to "write a `.feature`." Route each gap to its one home using the feature-file admission test in `../grimoire-draft/SKILL.md` (§ jurisdiction table + the four admission gates):
+- A `.feature` scenario is warranted **only** for an actor-observable behavior that passes all four gates (external actor, observable outcome, domain language, survives reimplementation).
+- An invariant — observability/logging guarantee, perf budget, security control, compliance rule — is a **constraint**. Recommend it be recorded/verified in `.grimoire/docs/constraints.md`, never as a new `.feature`.
+- When a behavior gap belongs in features, the default is **extend an existing feature file** in the same domain — recommend a new file only if no existing file fits, and say which were considered. Don't propose a `.feature` per finding.
+- Test gaps for already-specified behavior are a *missing test*, not a missing feature — recommend the test, not a new spec.
+
 Evaluate:
-- **Test presence**: Every new user-facing behavior has a test? Every scenario from linked feature file has step definitions?
+- **Test presence**: Every new user-facing behavior has a test? Every scenario from a linked feature file has step definitions? Missing test = recommend the test; only recommend a new/extended `.feature` if the behavior itself is unspecified *and* passes the admission test.
 - **Test quality**: Tests asserting outputs, or just that code "ran"? Over-mocked tests = red flag.
 - **Negative paths**: For each happy path, is there a failure-path test?
-- **Edge cases**: Empty states, concurrent users, interruptions, boundary values?
-- **Observability**: New feature — how will it be debugged in prod? Structured logs / metrics / error surfaces?
+- **Edge cases**: Empty states, concurrent users, interruptions, boundary values? A missing edge case is a missing test/scenario in the relevant existing feature — not grounds for a new feature file.
+- **Observability**: New feature — how will it be debugged in prod? Structured logs / metrics / error surfaces? Observability is a **constraint**: verify it's asserted in `constraints.md`; do not recommend a `.feature` for it.
 - **Regression risk** *(PR/pre-commit)*: Which existing tests cover the touched code? Were any tests removed or weakened?
 - **Accessibility**: New UI — keyboard nav, aria labels, contrast?
 

package/skills/references/test-baseline.md

@@ -0,0 +1,55 @@
+# Test Baseline Reference
+
+Loaded by skills that mutate code (`grimoire-apply`, `grimoire-bug`, `grimoire-refactor`) and the skill that checks for regressions (`grimoire-verify`).
+
+## Why
+
+"That's a pre-existing failure" is unfalsifiable if you never recorded what was failing *before* you started. Without a baseline, verify diffs against nothing — a regression you introduced and a failure that was already red look identical, and the user finds out at the end instead of signing off at the start.
+
+The fix is cheap: you already run the suite when you pick up a change. **Capture which tests were already failing, save it, and let the user accept it before any code is touched.** Verify then flags only *new* failures as regressions.
+
+This is not a new gate. It's saving the result of a run you already do.
+
+## Capture (at the start of a code change)
+
+Do this once, before writing the first test or touching production code — as part of the suite run you'd do anyway to understand the starting state.
+
+1. Run the configured suites: `config.tools.unit_test` and `config.tools.bdd_test`. Use what's configured; don't invent commands.
+2. Record the result to `.grimoire/changes/<change-id>/baseline.md` (ephemeral scaffolding, discarded with the change folder like `tasks.md`). For a bug fix with no change folder, record inline in the commit/test note and present to the user instead.
+3. Present the pre-existing failures to the user and get explicit acceptance before proceeding.
+
+### baseline.md format
+
+```markdown
+# Test Baseline — <change-id>
+
+captured: <date>          # the day you ran it; if unavailable, omit
+unit:  <pass>/<total> passing   command: <config.tools.unit_test>
+bdd:   <pass>/<total> passing   command: <config.tools.bdd_test>
+
+## Pre-existing failures (accepted by user before change)
+- <test id / name> — <one-line reason if known, else "pre-existing, cause unknown">
+- ...
+
+## Notes
+- <e.g. "unit suite not configured — baseline skipped for unit">
+```
+
+If nothing was failing, say so explicitly: `## Pre-existing failures: none — clean baseline`.
+
+## Skip rules
+
+- **No test command configured** for a suite → skip that suite, write `baseline skipped — no <suite> command configured` under Notes. Don't fabricate a command.
+- **User opts out** → write `baseline skipped — user opted out`. Verify must then NOT claim a clean diff; it reports failures as unclassified (could be pre-existing or new).
+- A skipped baseline is recorded, not silent. Verify needs to know it can't trust a diff.
+
+## Diff (at verify)
+
+`grimoire-verify` reads `baseline.md` and classifies the current suite result against it:
+
+- Test failing now **and** in baseline → **pre-existing** (already accepted; not a regression, don't blame the change).
+- Test failing now, **not** in baseline → **regression** introduced by this change → CRITICAL, must fix before finalize.
+- Test passing now, failing in baseline → incidentally fixed; note it, don't require it.
+- **No baseline / baseline skipped** → state plainly that failures cannot be classified, and list them all for the user to triage. Do not assert "existing tests pass" or "pre-existing failure" without a baseline to back it.
+
+The rule that replaces the old unfalsifiable claim: **a failure is "pre-existing" only if it's in `baseline.md`.** Otherwise it's yours.

package/templates/draft.md

@@ -0,0 +1,108 @@
+---
+status: draft
+change-id: <kebab-case-verb-led>
+kind: greenfield | refactor
+# NO complexity here. Complexity is an OUTPUT of design — scored at projection
+# (after agreement) and written to manifest.md, never to this file.
+---
+
+<!--
+  draft.md — the ONE living surface you design a change on.
+
+  This is where the whole change lives as a single coherent picture: diagram/sketch,
+  rationale, a decision ledger, pseudo-code, and an open-question ledger. You and the
+  user iterate HERE (this is the interview). Nothing is written to features/,
+  constraints.md, or decisions/ until the design is agreed — then it is PROJECTED into
+  those homes. This file is ephemeral: retained read-only as reference through the
+  pipeline, deleted when the change folder is cleared at grimoire-apply finalize. Git
+  history preserves it.
+
+  Required sections: At a glance · Why · Decisions · Decided / Open.
+  As-needed: Current state (REQUIRED for kind=refactor) · Sketches · Constraints · Cut.
+  Delete the guidance comments and any section that carries no weight for this change.
+-->
+
+# <change> — draft
+
+**Date:** <YYYY-MM-DD> · **Provenance:** <prior passes / branches / source docs, if any>
+
+## At a glance
+
+<!--
+  Make the whole change graspable in one screen. Pick the medium that fits:
+    - greenfield → an ASCII flow / box diagram of the system or pipeline
+    - refactor   → a pseudo-code sketch of the target shape (annotate with decision IDs)
+  If grimoire-design (Figma) output exists for this change, its visual + component/state
+  material anchors this section.
+-->
+
+## Why
+
+<!--
+  greenfield: the objective (what problem, how you'll know it's solved) + non-goals.
+  refactor:   the pain points justifying the change — each a NAMED, LOCATED smell with a
+              file:line breadcrumb, not an abstract complaint.
+-->
+
+## Current state            <!-- REQUIRED for kind=refactor; omit for greenfield -->
+
+<!--
+  How the touched system works TODAY, with breadcrumbs to live code. Mandate the codebase
+  graph: index_repository first if needed, then search_graph / trace_path / get_code_snippet
+  for qualified names, callers, and call chains. Follow with a severity-ranked Gaps/drift
+  list — the audit findings that motivate the redesign.
+-->
+
+## Decisions
+
+<!--
+  ONE inline ledger. Each row: a stable ID, the decision, and its WHY. Use sub-IDs (D1a)
+  and cross-references (D7 cites D3) freely — this is how coupled decisions stay legible
+  in one place. At projection, each NOVEL decision becomes a MADR (novelty gate applies —
+  obvious tooling picks fold into the baseline ADR, they don't mint a record).
+-->
+
+| #  | Decision | Why |
+|----|----------|-----|
+| D1 |          |     |
+
+## Sketches                 <!-- as-needed; expected for refactor -->
+
+<!--
+  Pseudo-code / key considerations for the target shape. Mark it "not final" — it is shape,
+  not contract. Annotate lines with the decision IDs they realize (# D8).
+-->
+
+## Constraints              <!-- as-needed -->
+
+<!--
+  Invariants this change must hold (security / NFR / observability / compliance). One line
+  each: assertion · rationale · how-verified. These project to .grimoire/docs/constraints.md
+  — NOT to a feature file.
+-->
+
+## Decided / Open
+
+<!--
+  Two lists. Decided = settled calls (cross-reference the D-IDs). Open = live unknowns.
+  Resolve an Open IN PLACE — rewrite it as `RESOLVED: <answer> (Dn)`, do not delete it.
+  The struck-through trail is the record of the thinking. Design is "done" when Decided is
+  stable and Open is empty-or-deferred.
+-->
+
+**Decided:**
+-
+
+**Open:**
+-
+
+## Cut / deferred           <!-- as-needed; greenfield-leaning -->
+
+<!--
+  What was deliberately removed or deferred, so it is not silently lost. Table:
+  cut · what it was · why cut · re-add when. Design by subtraction, recorded.
+-->
+
+| Cut | What it was | Why cut | Re-add when |
+|-----|-------------|---------|-------------|
+|     |             |         |             |