@kiwidata/grimoire 0.1.4 → 0.1.5

package/skills/grimoire-apply/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: grimoire-apply
-description: Implement tasks from a planned grimoire change with strict red-green BDD. Use when tasks.md exists and is ready for implementation.
+description: Implement tasks from a planned grimoire change, test-first at the right level (BDD scenario, unit-invariant, or characterization). Use when tasks.md exists and is ready for implementation.
 compatibility: Designed for Claude Code (or similar products)
 metadata:
   author: kiwi-data
@@ -9,7 +9,19 @@ metadata:
 
 # grimoire-apply
 
-Implement tasks from a planned grimoire change using strict red-green BDD: write the failing test first, then the production code that makes it pass. A task is not complete until its scenarios pass.
+Implement tasks from a planned grimoire change using **test-first discipline at the right level**: write the failing test first, then the production code that makes it pass. A task is not complete until its test passes.
+
+**Red-green is the discipline; the test vehicle matches the artifact the task came from** (set by `grimoire-plan` as each task's `verify:` tag):
+
+| `verify:` | Task came from | Test vehicle |
+|-----------|----------------|--------------|
+| `scenario` | a `.feature` (actor-observable behavior) | Gherkin scenario + step definitions |
+| `unit-invariant` | the constraints register (security/NFR/observability) | unit/integration test asserting the invariant |
+| `characterization` | internal change / refactor (no spec) | unit / characterization test |
+
+Do NOT write a `.feature` scenario for a `unit-invariant` or `characterization` task — forcing Gherkin where a unit test is correct is the antipattern that fills feature files with slop. One right way: behavior → scenario, everything else → unit test.
+
+**Artifacts are edited live on the feature branch.** Features, decisions, constraints, and schema are real files in `features/`, `.grimoire/decisions/`, `.grimoire/docs/`. There is no copy-into-change-folder and no promote step — `git diff` is the staging area. The change folder holds only ephemeral process scaffolding (`manifest.md`, `tasks.md`).
 
 ## CRITICAL: Two Rules That Must Not Be Broken
 
@@ -41,8 +53,8 @@ This applies to all LLMs: Claude, Codex, Cursor, Copilot, etc. The task list is
 ## Prerequisites
 - A change exists in `.grimoire/changes/<change-id>/` with:
   - `manifest.md`
-  - `tasks.md` (from plan stage)
-  - At least one `.feature` file or decision record
+  - `tasks.md` (from plan stage, each task carrying a `verify:` tag)
+- The change's live artifacts exist on the branch — at least one `.feature` (in `features/`), constraint (in `.grimoire/docs/constraints.md`), or decision record (in `.grimoire/decisions/`)
 
 ## Workflow
 
@@ -185,26 +197,11 @@ Before writing any code, ensure you're on a feature branch for this change:
 git checkout -b <type>/<change-id>
 ```
 
-Where `<type>` is `feat`, `fix`, `refactor`, or `chore` based on the change. If a branch already exists (resuming work), switch to it. Update the manifest's `branch:` field with the branch name.
-
-This links the git history to the grimoire change — `grimoire trace` and `grimoire log` depend on it.
-
-### 3b. Promote Feature Files
-
-Before writing any code, copy the proposed feature files from the change directory into the live `features/` tree:
-
-```
-cp -r .grimoire/changes/<change-id>/features/* features/
-```
-
-For extended files (scenarios added to an existing feature), overwrite — the change copy already contains the baseline scenarios plus the new ones. For new files, place them at the correct path under `features/`.
+Where `<type>` is `feat`, `fix`, `refactor`, or `chore` based on the change. If a branch already exists (`grimoire-branch-guard` or `grimoire-draft` usually created it), switch to it. Update the manifest's `branch:` field with the branch name.
 
-**Why this comes first:** BDD test runners discover scenarios from `features/`. Scenarios that only exist in `.grimoire/changes/` are invisible to the test runner, so the red-green cycle cannot work. On a feature branch, `features/` is branch-local — promoting here has no effect on `main` until the PR merges.
+The branch links the git history to the change via the `Change: <change-id>` commit trailer. The branch IS the isolation and `git diff` IS the staging — there is no separate promote step.
 
-Commit the promoted files before writing any step definitions:
-```
-git add features/ && git commit -m "feat(<change-id>): promote feature specs to features/"
-```
+> **No promote.** Feature files, decisions, and constraints were drafted directly into their live locations (`features/`, `.grimoire/decisions/`, `.grimoire/docs/constraints.md`) on this branch. BDD runners already discover the scenarios from `features/`. Do not copy anything out of `.grimoire/changes/` — that folder holds only `manifest.md` and `tasks.md`.
 
 ### 4. Load Context
 
@@ -222,14 +219,15 @@ git add features/ && git commit -m "feat(<change-id>): promote feature specs to
 3. Tell the user: "Context is getting large. I've updated tasks.md with progress. A fresh session can resume from here."
 
 ### 5. Implement Tasks
-Work through `tasks.md` sequentially. **Every task follows the same cycle: test → red → code → green → next.**
+Work through `tasks.md` sequentially. **Every task follows the same cycle: test → red → code → green → next.** The cycle is identical at every level; only the *test vehicle* changes per the task's `verify:` tag (`scenario` → step definitions; `unit-invariant` / `characterization` → unit/integration test). "Step definitions" below means *the failing test at the task's level* — for non-`scenario` tasks, write a unit test, not a `.feature`.
 
 **For each task:**
 1. Announce which task you're working on
+   - Read the task's `verify:` tag — it decides the test vehicle. `scenario` → write/extend step definitions for the named scenario. `unit-invariant` → write a unit/integration test asserting the constraint. `characterization` → write a unit test pinning current/intended behavior. If a `unit-invariant` task has no matching constraint in `.grimoire/docs/constraints.md`, STOP and flag — don't invent a scenario to fill the gap.
    - **Pattern brief** (before writing anything): classify code type → `search_graph` for 3–5 peers (excluding last 60 days) → `get_code_snippet` → extract modal pattern across the four critical seams (error handling, dependency access, abstraction depth, return shape) → write a 5–8 rule brief. Skip if graph not indexed or < 3 peers. Full instructions in `../references/pattern-guard.md`.
-2. Write the step definitions FIRST (the test that will verify this task)
-3. Run the step definitions — **they MUST FAIL (red)**
-4. If the test passes immediately, STOP. The test is broken — it's not actually testing anything. Fix the step definition so it makes a real assertion that fails without production code. Common causes:
+2. Write the test FIRST, at the task's level (step definitions for `scenario`; unit/integration test for `unit-invariant`/`characterization`)
+3. Run the test — **it MUST FAIL (red)**
+4. If the test passes immediately, STOP. The test is broken — it's not actually testing anything. Fix it so it makes a real assertion that fails without production code. Common causes:
    - Empty step definition body (passes by default)
    - Assertion against a mock/fixture that already satisfies the condition
    - Step wired to wrong function or missing the actual check
@@ -241,7 +239,7 @@ Work through `tasks.md` sequentially. **Every task follows the same cycle: test
    - **Branching budget ~7.** If a function has more `if` / `else` / `case` / `&&` than that, split or drop dead guards.
    - **Function size ~30 lines.** One job per function. If the name needs "and", split.
    - **No premature abstraction.** Three near-identical copies is fine. No new `BaseX` / factory / strategy / config object for a single caller.
-   - **Comments: zero by default.** Do not add a comment unless you can state the non-obvious *why* in one sentence. No function docstrings unless the project's `comment_style` requires them. No inline comments restating what the code does (`# loop over users`, `# return result`). No block comments describing a section. No comments naming the task, PR, or ticket. If removing the comment would not confuse a future reader, do not write it.
+   - **Comments: terse, self-contained, no essays** (`../references/code-quality.md` §7). Default to none; add only a one-line non-obvious *why*. Terse voice — drop "this function", filler, restated types. **Self-contained:** never name an external artifact that moves independently — no feature/scenario/`.feature`, MADR/ADR number, change-id, ticket/PR, test name, or tag code (`LOG-OBS-003`) in a comment; describe the behavior, not where it's specced. **No paragraphs:** summary is 1–2 lines, then the `comment_style` params if the project requires them — no prose block before them. No comments restating the code (`# loop over users`). If removing it wouldn't confuse a future reader, don't write it.
 6. Run the step definitions again — they should PASS (green)
 7. If still red, fix the production code (not the test)
 8. **Hallucination check:** Before running tests, verify every external function/method your new code calls actually exists in the graph: `search_graph(name_pattern="<name>")` for each. If not found: find the correct function or stop and flag to user. Do not run tests against calls to non-existent functions. (Full instructions in `../references/pattern-guard.md` Step 6.)
@@ -280,23 +278,21 @@ When all implementation tasks are complete:
 **The verify step is not optional. Do not proceed to finalize with failing tests.**
 
 ### 7. Finalize
-When all tests are green:
-1. Move new decision records to `.grimoire/decisions/` with proper sequential numbering
-2. Update MADR status from `proposed` to `accepted` and set the date
-3. If `data.yml` exists, merge the changes into `.grimoire/docs/data/schema.yml` — apply adds/modifies/removes so the baseline schema stays current
-4. Move `manifest.md` to `.grimoire/archive/YYYY-MM-DD-<change-id>/`
-5. Remove the change directory from `.grimoire/changes/`
-
-Feature files were already promoted to `features/` in step 3b — no copy needed here.
+When all tests are green. Features, decisions, and constraints were edited live on the branch — finalize flips states, applies the schema delta, and clears the ephemeral scaffolding:
+1. Decision records already live in `.grimoire/decisions/` (drafted there, numbered at draft time). Flip MADR status from `proposed` to `accepted` and set the date.
+2. Constraints (`.grimoire/docs/constraints.md`) were edited in place — nothing to move.
+3. If the change has a `data.yml` (schema delta), apply its `add`/`modify`/`remove` entries to the live `.grimoire/docs/data/schema.yml` so the baseline schema stays current. `data.yml` is a migration-delta spec (ephemeral scaffolding carrying nullability/safety/ordering intent a raw diff wouldn't), not a copy of the schema — `schema.yml` is the live target; the delta is discarded with the change folder.
+4. Refresh the project overview: run `grimoire docs`. It regenerates `.grimoire/docs/OVERVIEW.md` (the human entry point) from the now-current features, constraints, decisions, and schema — superseded decisions drop out automatically. This is the existing `docs` command, not a new one.
+5. Remove the change directory `.grimoire/changes/<change-id>/`. Its `manifest.md` + `tasks.md` (+ any `data.yml`) are ephemeral process scaffolding. The durable record is the branch, the PR, and `git log` — linked by the `Change: <change-id>` trailer. **There is no archive tree** (don't reinvent git history).
 
 ### 8. Commit
 
-Finalize must be complete before committing — the commit captures the finished state including archived manifest and promoted decisions, not mid-flight change artefacts.
+Finalize must be complete before committing — the commit captures the finished state (accepted decisions, cleared scaffolding), not mid-flight change artefacts.
 
-Stage everything:
+Stage the live artifacts and the scaffolding removal:
 ```
-git add features/ .grimoire/decisions/ .grimoire/archive/ .grimoire/docs/ src/ tests/
-git add -u  # picks up any deleted files (removed change directory)
+git add features/ .grimoire/decisions/ .grimoire/docs/ src/ tests/
+git add -u  # picks up the removed change directory
 ```
 
 Then commit using `/grimoire:commit` (reads change context for the message) or write a manual message following `AGENTS.md` commit trailer conventions:

package/skills/grimoire-commit/SKILL.md

@@ -66,7 +66,7 @@ If `commit_style` in config is anything else, read it as a format hint and adapt
 - If multiple logical changes are staged, suggest splitting into separate commits
 
 ### 5. Git Trailers (mandatory for audit trail)
-When a grimoire change is active, the commit **MUST** include `Change:` as a git trailer. This is what makes `grimoire trace` and `grimoire log` work — without it, the commit is invisible to the audit trail.
+When a grimoire change is active, the commit **MUST** include `Change:` as a git trailer. This git-native anchor links the commit to its change — `grimoire trace` and `git log --grep "Change: <id>"` both rely on it. Without it, the commit is invisible to the audit trail.
 
 ```
 Change: add-2fa-login

package/skills/grimoire-design/SKILL.md

@@ -128,7 +128,7 @@ For HTML output, write a single `.grimoire/changes/<change-id>/designs/preview.h
 Skip preview rendering when output is Figma (the Figma file IS the preview) or ASCII (the markdown table IS the preview).
 
 ### 9. Derive Gherkin
-Propose draft `.feature` files at `.grimoire/changes/<change-id>/features/<capability>/`. One Scenario per (component × state). Each Scenario has Given / When / Then steps grounded in the design.
+Propose draft scenarios as a **design artifact** at `.grimoire/changes/<change-id>/designs/scenarios.feature` (a proposal, not the live baseline). One Scenario per (component × state), Given / When / Then grounded in the design. `grimoire-draft` writes the user-approved scenarios live into `features/` — design does not edit the live baseline directly. Every proposed scenario must still pass draft's feature admission test (external actor, observable, domain language).
 
 Apply surface-conditional adversarial scenarios per `../references/adversarial-personas.md`:
 
@@ -210,7 +210,7 @@ Brand-drift lint cross-references hardcoded values in code against `.grimoire/br
 
 ### Scope
 - Default: scan **staged files** (`git diff --cached --name-only`) — fast, dev-loop-friendly
-- `--all` / "scan all" → scan all tracked files (slower; honor `.grimoire/mapignore`)
+- `--all` / "scan all" → scan all tracked files (slower; honor `.gitignore`)
 - File types: `.css`, `.scss`, `.less`, `.html`, `.jsx`, `.tsx`, `.vue`, `.svelte` (configurable per project conventions)
 
 ### What it looks for
@@ -249,7 +249,7 @@ Do not error — absence is a valid state for projects that haven't onboarded br
 ## Important
 - **Pure markdown.** This skill is interpreted by an LLM per ADR-0010. Do not generate executable code or shell scripts to satisfy any step. The variant HTML files are output artifacts; the workflow itself is prose the AI follows.
 - **Ask before scanning large codebases.** Component-inventory scans (step 4) and `--lint --all` scans can be expensive on monorepos. Confirm with the user before scanning more than ~500 files.
-- **Honor `.grimoire/mapignore`.** Any scan (component inventory, brand lint) must respect mapignore patterns. Reuse the same exclusion logic as `grimoire map`.
+- **Honor `.gitignore`.** Any scan (component inventory, brand lint) must skip vendored, generated, and version-control-ignored paths.
 - **Do not create `.grimoire/brand/` unprompted.** The directory only appears when the user opts in via onboarding or `--capture-brand`. Reading from a missing brand directory is a valid state — fall back to neutral defaults.
 - **Never log Figma access tokens.** The token lives in `FIGMA_ACCESS_TOKEN` env var, read by the MCP server. Never write it to config, never echo it in transcripts, never include it in artifacts.
 - **Soft gates are warnings, not blockers.** The problem-statement gate (step 2) and the state-enumeration gate (step 7) warn aggressively but accept user override. Record overrides as assumptions so they surface in review.

package/skills/grimoire-discover/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: grimoire-discover
-description: Generate area docs and data schema from a codebase snapshot. Use when initializing grimoire on an existing project or when codebase structure has changed significantly.
+description: Generate intent-focused area docs and data schema by querying the codebase graph. Use when initializing grimoire on an existing project or when an area's intent/boundaries have changed.
 compatibility: Designed for Claude Code (or similar products)
 metadata:
   author: kiwi-data
@@ -9,13 +9,15 @@ metadata:
 
 # grimoire-discover
 
-Generate a structured project map in `.grimoire/docs/` from a codebase snapshot. This map helps LLMs understand the codebase layout, find reusable code, and follow existing patterns — preventing duplicate code and misplaced files.
+Generate **intent-focused** area docs and a data schema in `.grimoire/docs/`. Area docs capture what the graph can't know — an area's *purpose, boundaries, and conventions* — and point at the codebase-memory-mcp graph for everything structural (symbols, key files, call graphs, reusable code). The graph is the live source of structure; discover does not freeze it into a doc that drifts.
 
 ## Triggers
-- User wants to document or map the codebase structure
-- User asks about coding standards, patterns, or conventions
-- User wants to prevent duplicate code or find existing utilities
-- Loose match: "discover", "map", "standards", "conventions", "DRY", "utilities", "codebase layout"
+- User wants to document an area's purpose, boundaries, or conventions
+- User asks about coding standards or where new code of a type should go
+- User is onboarding an existing project to grimoire
+- Loose match: "discover", "standards", "conventions", "boundaries", "onboard codebase"
+
+Note: "find existing utilities", "what calls what", "codebase layout/structure" are **graph** queries, not discover — use codebase-memory-mcp (`search_graph`, `get_architecture`, `trace_path`) directly.
 
 ## Routing
 - Want to document existing behavior as Gherkin features → `grimoire-audit`
@@ -24,85 +26,63 @@ Generate a structured project map in `.grimoire/docs/` from a codebase snapshot.
 
 ## Prerequisites
 
-**Structural snapshot:** Run `grimoire map` first. This produces `.grimoire/docs/.snapshot.json` — a structural scan of the directory tree, key files, and file extension counts. The snapshot is the input for directory structure; this skill adds the semantic layer.
-
-If `.snapshot.json` doesn't exist or is stale, tell the user to run `grimoire map` (or `grimoire map --refresh` to diff against existing docs).
-
-**Symbol intelligence (recommended):** If `codebase-memory-mcp` is available as an MCP server, use its graph tools (`search_graph`, `get_architecture`, `query_graph`) to query symbols, call graphs, and architecture instead of reading source files manually. This provides AST-parsed symbols across 66 languages, call-path tracing, and dead code detection — far more accurate than regex extraction.
+**The codebase graph is the structure source.** `codebase-memory-mcp` should be indexed for this project — discover reads directory layout, symbols, key files, and call graphs from it (`get_architecture`, `search_graph`, `trace_path`), not from a filesystem snapshot. There is no `grimoire map` step and no `.snapshot.json` (both retired).
 
-If `codebase-memory-mcp` is not available, fall back to reading source files directly to identify symbols and patterns.
+If `codebase-memory-mcp` is not indexed, run `index_repository` first. Only if the graph is genuinely unavailable, fall back to reading source files directly to identify boundaries and conventions.
 
 ## What It Produces
 
 `.grimoire/docs/` with:
-- **`index.yml`** — master index of all documented areas with descriptions and directory mappings
-- **Area docs** — one markdown file per area of the codebase, each covering:
-  - Purpose and boundaries of the module/area
-  - Key files and their responsibilities
-  - Reusable utilities, helpers, and shared functions (the "reuse inventory")
-  - Naming conventions and patterns in use
+- **`index.yml`** — registry of documented areas (descriptions + directory mappings) and the functional-story map that groups capabilities in the OVERVIEW
+- **Area docs** — one markdown file per significant area, **intent only**:
+  - Purpose of the area
+  - Boundaries (what belongs here, what doesn't, where related code lives)
+  - Conventions (naming + structural patterns, with example file references)
   - Where new code of this type should go
-  - Example references (point to specific files as exemplars, don't duplicate code)
-
-## Workflow
-
-### 1. Load Snapshot and Graph
-Read `.grimoire/docs/.snapshot.json`. This gives you:
-- **directories** — every directory with file counts, extensions, key files, and subdirectories
-- **keyFiles** — significant files (entry points, configs, route files, etc.) with their detected type
-- **undocumented** — directories not yet covered by existing docs (only present on `--refresh`)
-- **removed** — directories that have docs but no longer exist (only present on `--refresh`)
 
-Use this as your roadmap. The snapshot tells you WHERE to look; you add WHAT it means.
+Area docs do NOT contain Key Files, a reusable-code inventory, or duplicate listings — those are structure, and the graph regenerates them live on demand (and would drift if frozen here). When a reader needs symbols or reuse candidates, they query the graph, not the doc.
 
-If the snapshot includes a `duplicates` section (from `grimoire map --duplicates`), use it to populate "Known Duplicates" sections in area docs. This tells the plan skill where code is already duplicated so it can consolidate rather than add more.
+## Workflow
 
-**If `codebase-memory-mcp` is available**, also query the graph for each area:
-- `search_graph` — find all symbols (functions, classes, types) in a directory
-- `trace_call_path` — understand how modules connect (inbound/outbound calls)
-- `get_architecture` — get a high-level module/dependency overview
-- `query_graph` — Cypher-like queries for specific relationships (e.g., `MATCH (f:Function)-[:CALLS]->(g) WHERE f.file STARTS WITH 'src/api/' RETURN f.name, g.name`)
+### 1. Load the Graph
+Query `codebase-memory-mcp` to understand the codebase live:
+- `get_architecture` — high-level module/dependency overview and directory layout (your roadmap of WHERE the areas are)
+- `search_graph` — symbols (functions, classes, types) in a directory, with signatures
+- `trace_path` — how modules connect (inbound/outbound calls)
+- `query_graph` — specific relationships (e.g., `MATCH (f:Function)-[:CALLS]->(g) WHERE f.file STARTS WITH 'src/api/' RETURN f.name, g.name`)
 
-This replaces the need to manually read every source file to extract symbols. The graph gives you AST-accurate function signatures, call relationships, and dead code detection across 66 languages.
+The graph gives AST-accurate structure across many languages. You use it to *understand* each area so you can write its intent doc — you do NOT copy its output into the doc (that's what regenerating live avoids).
 
 ### 2. Determine Scope
 Ask the user what to document (or accept the scope passed in by a calling skill):
-- **Full scan** — document all areas from the snapshot (default for first run)
+- **Full scan** — document all significant areas (default for first run); use `get_architecture` to enumerate them
 - **Area scan** — document specific directories (e.g., "just the API layer")
-- **Gap fill** — only document areas flagged as `undocumented` in the snapshot
-- **Targeted refresh** — a list of directories is passed in (from `grimoire-precommit-review` doc freshness check or `grimoire-plan` staleness gate). Skip the full snapshot walk. Go directly to step 3 for each named directory, regenerate only those area docs, and update their `last_updated` entries in `index.yml`. This is the fast-path mode for post-change maintenance — it does not touch areas outside the passed list.
+- **Targeted refresh** — a list of directories is passed in (e.g. from `grimoire-plan`'s staleness gate). Regenerate only those area docs and update their `last_updated` entries in `index.yml`. Fast-path for when an area's *intent* changed; does not touch areas outside the passed list.
 
-Check `.grimoire/docs/index.yml` if it exists — don't redo work unless refreshing.
+Check `.grimoire/docs/index.yml` if it exists — don't redo work unless refreshing. Remember discover runs when **intent** changes (new area, shifted boundary), not on every code change — structure is always live from the graph.
 
 ### 3. Analyze Each Area
-For each directory cluster in the snapshot, read the actual code to understand:
-
-**From the snapshot (already known):**
-- Directory path and file counts
-- File extensions (tells you the language/type mix)
-- Key files (tells you what framework patterns are in use)
-
-**From `codebase-memory-mcp` graph (if available):**
-- All symbols in the area: functions, classes, types, constants with signatures
-- Call graph: what calls what, both inbound and outbound
-- Dead code: functions with zero callers
-- Cross-service HTTP links: REST routes and their callers
-
-**From reading the code (your job — or to supplement the graph):**
-- What the module/area is responsible for
-- Reusable functions, classes, utilities that other code should import
-- Naming conventions and structural patterns
-- Where new code of this type should be created
-- Import relationships with other areas
-- **Data models and schemas** in or owned by this area (see Data Layer below)
+For each area, use the graph to understand it, then distill the **intent** a reader can't get from the graph:
+
+**From the graph (read, don't transcribe):**
+- Symbols, signatures, call relationships, dead code — context for understanding what the area does
+- Cross-area import/HTTP links — informs the Boundaries section
+
+**What you write down (the graph can't infer this):**
+- What the area is *responsible for* (Purpose)
+- What belongs here vs. where related code lives (Boundaries)
+- Naming and structural conventions in use, with an exemplar file reference
+- Where new code of this type should go
+- **Data models and schemas** owned by this area (see Data Layer below)
 
 ### 4. Generate Area Docs
 For each significant area, create a doc file in `.grimoire/docs/`.
 
-**Area doc format:**
+**Area doc format (intent only — no structure tables):**
 
 ```markdown
 # <Area Name>
+> Last updated: YYYY-MM-DD
 
 ## Purpose
 <1-2 sentences: what this area of the codebase is responsible for>
@@ -110,41 +90,28 @@ For each significant area, create a doc file in `.grimoire/docs/`.
 ## Boundaries
 <What belongs here and what doesn't. Where related code lives instead.>
 
-## Key Files
-| File | Responsibility |
-|------|---------------|
-| `path/to/file.py` | <what it does> |
-| `path/to/other.py` | <what it does> |
-
-## Reusable Code
-Utilities and helpers in this area that MUST be reused (not re-implemented):
-
-| Function/Class | Location | What It Does |
-|----------------|----------|-------------|
-| `format_currency()` | `utils/formatters.py:42` | Formats decimal as currency string |
-| `BaseAPIView` | `api/base.py:15` | Base view with auth, pagination, error handling |
-
-## Patterns
-<How things are done in this area. Reference specific files as exemplars.>
+## Conventions
+<How things are done in this area. Reference specific files as exemplars — don't list every file.>
 
 ### Naming
-- <naming convention with example>
+- <naming convention with one example file>
 
 ### Structure
-- <structural pattern with example file>
+- <structural pattern with one exemplar file>
 
 ## Where New Code Goes
 - New <type> → `path/to/directory/`
 - New <type> → `path/to/other/`
 
-## Known Duplicates
-<Only if duplicates data exists in snapshot. List clones that touch this area.>
-
-| Files | Lines | What's Duplicated |
-|-------|-------|------------------|
-| `views.py:42-68` ↔ `api/views.py:15-41` | 26 | Request validation logic |
+## Structure (live)
+For key files, symbols, reusable utilities, call graphs, and duplicates in this area,
+query the graph — it is always current:
+- `get_architecture(area="<dir>")` · `search_graph(qn_pattern="<dir>.*")`
+- duplicates: `grimoire health` (config-driven `duplicates` metric)
 ```
 
+Do not hand-list files, functions, or "reusable code" — that's the graph's job, and a frozen copy drifts. The single pointer above replaces the old Key Files / Reusable Code / Known Duplicates tables.
+
 ### 5. Generate Data Schema
 
 Scan the codebase for data models, ORM definitions, migration files, and schema declarations. Produce `.grimoire/docs/data/schema.yml` documenting the current data layer.
@@ -290,9 +257,22 @@ areas:
     path: .grimoire/docs/utils.md
     directory: src/utils
     description: Shared utilities, helpers, formatters
+
+# Functional stories — how capabilities group for a human reader.
+# `grimoire docs` uses this to group the OVERVIEW's Capabilities section.
+# `features` lists feature-file basenames (no .feature extension).
+stories:
+  chat-qa:
+    title: Chat & Q&A
+    features: [ai-chat, a2ui-integration, search]
+  extraction:
+    title: Document extraction
+    features: [document-pipeline, bbd-validation-rules]
 ```
 
-The `directory` field links each doc back to the source directory — this is what `grimoire map --refresh` uses to detect gaps.
+The `directory` field links each doc back to the source directory — it's how a targeted refresh maps a changed directory to the area doc that describes it.
+
+**Generate the `stories:` map.** Walk `features/`, then group the feature files by *functional story* — the user-facing capability area they serve, not the source directory. Propose the grouping to the user and let them rename/merge stories before writing. A feature not yet assigned to a story falls back to its feature-directory group in the OVERVIEW, so partial maps are fine. `stories` is the one place that grouping lives (DRY) — `grimoire docs` reads it, nothing else defines it.
 
 ### Freshness Tracking
 
@@ -323,38 +303,25 @@ areas:
 ### 8. Present Summary
 After generating, show the user:
 - How many areas documented
-- How many reusable utilities inventoried
-- Any areas that seem under-organized or have pattern inconsistencies
+- Any areas whose boundaries seem unclear or whose conventions are inconsistent
 - Suggest which area docs are most critical for the plan skill to read
 
-## Config Files
-
-Users can customize what gets scanned by editing files in `.grimoire/`:
-
-- **`.grimoire/mapignore`** — directories/patterns to skip during scanning (like .gitignore). Edit to exclude vendor code, generated files, etc.
-- **`.grimoire/mapkeys`** — key file definitions (format: `filename = type`). Edit to add project-specific indicators like `factories.py = test-factories` or `signals.py = django-signals`.
-
-These are read by `grimoire map` and affect the snapshot this skill consumes.
-
 ## Integration with Other Skills
 
-- The **plan** skill should read `.grimoire/docs/` before generating tasks — look for existing utilities in the reuse inventory, follow documented patterns
-- The **verify** skill can check new code against documented patterns
+- The **plan** skill reads `.grimoire/docs/` for Purpose/Boundaries/Conventions before generating tasks, and queries the **graph** for symbols and reusable utilities
+- The **verify** skill can check new code against documented conventions
 - The **audit** skill can trigger a discover pass as part of onboarding
 - The **design** skill reads `.grimoire/docs/components.md` first to avoid generating duplicate components
-- The **precommit-review** skill checks area doc freshness on every commit and invokes discover in targeted refresh mode for stale dirs — this is the primary maintenance trigger, not a periodic manual task
-- The **plan** skill gates on staleness for level 3-4 changes and directs the user to run targeted refresh before planning
+- The **plan** skill gates on staleness for level 3-4 changes (when an area's *intent* doc lags its directory) and directs the user to run a targeted refresh before planning
 
 ## Important
-- **Start from the snapshot.** Don't scan the filesystem yourself — `grimoire map` already did that. Read `.snapshot.json` for structure, then use `codebase-memory-mcp` graph queries for symbols and call graphs (if available), and read actual code files for meaning.
-- **Prefer graph queries over file reads.** If `codebase-memory-mcp` is available, use `search_graph` and `query_graph` to find symbols, call paths, and architecture rather than reading every source file. This is faster, more accurate (AST-parsed), and uses fewer tokens.
-- **Document what IS, not what should be.** This is a map of the actual codebase, not aspirational standards. If the code is inconsistent, note it — don't paper over it.
-- **Point, don't copy.** Reference files and line numbers as exemplars. Don't duplicate code into the docs — it goes stale.
-- **Focus on what helps LLMs.** The goal is preventing duplicate code and misplaced files. Prioritize: reusable utilities > file placement > naming conventions > architectural patterns.
-- **Keep docs lean.** Each area doc should be scannable in 30 seconds. If it's too long, split it.
-- **The reuse inventory is the most valuable output.** An LLM that knows `format_currency()` exists in `utils/formatters.py` won't write a new one.
-- **Don't document the obvious.** Skip areas that are self-explanatory from file names alone. Focus on areas where an LLM would make mistakes.
-- **Update, don't accumulate.** When refreshing, replace stale docs rather than appending. The docs should reflect the current codebase, not its history.
+- **Start from the graph.** Use `get_architecture` to enumerate areas and `search_graph`/`trace_path` to understand each one. Read source files only to pin down intent the graph can't express.
+- **Intent only — never transcribe structure.** Do not write Key Files lists, reusable-code inventories, or symbol tables into area docs. Those are derivable from the graph and would drift. The doc captures purpose, boundaries, and conventions; the doc points at the graph for everything else (DRY — one home per fact).
+- **Document what IS, not what should be.** This describes the actual codebase, not aspirational standards. If the code is inconsistent, note it — don't paper over it.
+- **Point, don't copy.** Reference one exemplar file per convention. Don't duplicate code into the docs.
+- **Keep docs lean.** Each area doc should be scannable in 30 seconds. If it's too long, it's probably transcribing structure — cut it back to intent.
+- **Don't document the obvious.** Skip areas self-explanatory from file names. Focus on areas where intent or boundaries are non-obvious.
+- **Update, don't accumulate.** When refreshing, replace stale docs rather than appending.
 
 ## Done
 When area docs, schema, context, and index are generated, the workflow is complete. Suggest `grimoire-audit` to document existing features and decisions as Gherkin specs and ADRs.

package/skills/grimoire-draft/SKILL.md

@@ -21,21 +21,37 @@ Draft or update Gherkin features and MADR architecture decisions collaboratively
 - Bug report ("something is broken") → `grimoire-bug` or `grimoire-bug-report`
 - Pure refactoring (no behavior change) → no grimoire artifact needed. Suggest an ADR only if architecturally significant.
 - Config, deps, formatting → not grimoire territory. Just do it.
-- If unclear after one clarifying question, default to drafting a feature.
+- If unclear, apply the jurisdiction table + admission test in step 1. Do NOT default to drafting a feature — default to finding the fact's correct home, and ask one clarifying question if the test is inconclusive.
 
 ## Workflow
 
-### 1. Qualify the Request
-Before doing anything, determine what kind of change this is:
+### 1. Qualify the Request — Jurisdiction
 
-- **Behavioral** (Given/When/Then expressible) → draft `.feature` files
-- **Architectural** (trade-off, choice, structural) → draft MADR decision record
-- **Both** → draft features AND decision records
-- **Bug fix** → STOP. Tell the user: "The feature file already describes the correct behavior. Let's just fix the code."
-- **Refactoring** → STOP. No behavior change = no grimoire artifact. Suggest an ADR only if it's a significant architectural shift.
-- **Config/deps/formatting** → STOP. Not grimoire territory.
+Before doing anything, route the change to the **one** artifact type that owns it. Each fact has exactly one home (see `../references/principles.md` — one right way, DRY). **The default is NOT "draft a feature."** The default is: figure out which home this fact belongs in.
 
-If unclear, ask the user one clarifying question to route correctly. **Do not guess the routing and proceed.** A wrong routing wastes both your context and the user's time — one question costs less.
+| What the change is | Home | Not |
+|--------------------|------|-----|
+| **Actor-observable behavior** — an external actor does something and observes a result | `.feature` (Gherkin) | — |
+| **Constraint** — security control, NFR, performance budget, observability/logging guarantee, compliance rule | `.grimoire/docs/constraints.md` (assertion + rationale + how-verified) | NOT a `.feature` |
+| **Architecture decision** — a trade-off or structural choice | MADR in `.grimoire/decisions/` | NOT a `.feature` |
+| **Data model / external API contract** | data schema | NOT a `.feature` |
+| **Both behavior + decision** | features AND a MADR | — |
+| **Bug fix** | STOP → `grimoire-bug`. "The spec already describes correct behavior; just fix the code." | — |
+| **Refactoring** (no behavior change) | STOP. No artifact. Suggest an ADR only if architecturally significant. | — |
+| **Config / deps / formatting** | STOP. Not grimoire territory. | — |
+
+#### The feature-file admission test
+
+A scenario may be written **only if it passes all four gates.** If it fails any, it is not a feature — route it to the home above.
+
+1. **External actor** — a user, operator, or external system does the thing. "As a developer, I want structured logs" / "the system retries" → fails. The actor is internal → it's a constraint or a decision, not a feature.
+2. **Observable** — the actor can see the outcome without reading code or logs. "logs are scrubbed of PII", "request completes in <200ms" → fails (not observable by an actor) → constraint.
+3. **Domain language** — the scenario uses domain nouns, zero implementation detail. If a step names a library, log level, function, table, or framework (`loguru`, `INFO`, `bcrypt`, `users` table) → fails → it's leaking implementation; rewrite declaratively or move to a constraint/MADR.
+4. **Survives reimplementation** — if the internals were rewritten from scratch, would the scenario still read the same? If it would change, it's pinned to implementation → not a feature.
+
+Common slop this catches (all belong in `constraints.md`, not `.feature`): "PII is scrubbed from logs", "all endpoints require auth", "responses are gzipped", "errors are logged with a trace id". These are invariants, not behaviors.
+
+If unclear after applying the test, ask the user one clarifying question to route correctly. **Do not guess the routing and proceed.** A wrong routing wastes both your context and the user's time — one question costs less.
 
 ### 2. Score Complexity
 
@@ -117,7 +133,8 @@ Present a Requirements Summary (template in the reference) and wait for user con
 
 ### 6. Scaffold the Change
 - Choose a `change-id`: kebab-case, verb-led (`add-`, `update-`, `remove-`)
-- Create `.grimoire/changes/<change-id>/`
+- Ensure you're on a feature branch for this change (`grimoire-branch-guard` usually created it). The branch is where all artifacts are edited live.
+- Create `.grimoire/changes/<change-id>/` — this folder holds **only ephemeral process scaffolding**: `manifest.md` (and later `tasks.md`). It does NOT hold copies of features, decisions, or constraints — those are edited live in their real locations and tracked by `git diff`. The folder is deleted at finalize; the branch + PR + git log are the durable record.
 
 ### 7. Draft Artifacts
 **For behavioral changes:**
@@ -151,15 +168,17 @@ Scenario triage:
 
 Do not proceed to writing until this table is complete. If unsure about a match, default to extend.
 
-**Step 3 — Execute**
+**Step 3 — Execute (edit live on the branch)**
 
-- **Extend:** copy the matching baseline file to `.grimoire/changes/<change-id>/features/<same-relative-path>/` and add scenarios there.
-- **New file (requires justification):** state which existing files were considered and why none fit. Then create `.grimoire/changes/<change-id>/features/<capability>/<name>.feature`.
+Artifacts are edited **directly in their real locations** on the feature branch. The branch is the isolation; `git diff` is the staging area. There is no copy into `.grimoire/changes/` and no promote step (see `../references/principles.md` — don't reinvent git).
+
+- **Extend:** add scenarios directly to the live `features/<same-relative-path>` file.
+- **New file (requires justification):** state which existing files were considered and why none fit. Then create `features/<capability>/<name>.feature` directly.
 
 Signals a scenario belongs in an existing file: same actor, same domain object, same entry point, same HTTP resource or screen.
 Signals a genuinely new file: new actor type with no existing file, entirely new domain object, or existing file's Feature title would need "and" to cover both.
 
-- If modifying an existing feature, copy the current baseline first, then modify
+- Every scenario must have passed the **admission test** in step 1. If you catch yourself writing a step that names a library/log-level/table, stop — that fact belongs in `constraints.md`, not here.
 - Follow Gherkin best practices:
   - Feature title + user story (As a / I want / So that)
   - Background for shared preconditions
@@ -170,7 +189,7 @@ Signals a genuinely new file: new actor type with no existing file, entirely new
 **When design data was provided (step 4.0):**
 - If a Figma snapshot or `grimoire-design` output is available, propose Gherkin scenarios per (component × state) grounded in those artifacts. Walk the component list and the enumerated states; emit one Scenario per pair.
 - Present the proposed scenarios for user review before writing to `.feature` files — accept all / accept some / edit / reject any. Rejected scenarios are not written.
-- If `grimoire-design` already produced user-accepted scenarios under `.grimoire/changes/<change-id>/features/`, do NOT re-propose them; treat them as the baseline and only fill gaps (e.g., new components not yet covered).
+- If `grimoire-design` already produced user-accepted scenarios under `.grimoire/changes/<change-id>/designs/scenarios.feature`, do NOT re-propose them; write the accepted ones live into `features/` (applying the admission test) and only fill gaps (e.g., new components not yet covered).
 
 **Brand-tokens grounding:**
 - When Figma variables map to tokens that also appear in `.grimoire/brand/tokens.json`, scenarios referencing visual properties must use token names, not hex values. Example: write `Then the submit button uses color.primary` not `Then the submit button is #0066ff`.
@@ -183,10 +202,20 @@ Signals a genuinely new file: new actor type with no existing file, entirely new
 **Security tags on scenarios:**
 Apply Gherkin tags per `../references/security-compliance.md` (section "Security Tags"). Tags drive stricter checks in plan, review, and verify stages. Apply compliance-specific tags only when `project.compliance` is configured. If no compliance frameworks and no security surface, don't add tags.
 
+**For constraints (security / NFR / observability / compliance):**
+
+Anything that failed the feature admission test because it's an invariant rather than an actor-observable behavior goes here — **not** into a `.feature`.
+
+- Append to the live `.grimoire/docs/constraints.md` (create it from `templates/constraints.md` if absent).
+- One row per constraint: **assertion · rationale · how-verified · links**. The assertion is a flat statement of what must always hold ("Log output never contains PII or secrets"), not a Given/When/Then.
+- `how-verified` names the test that proves it (a `unit-invariant` test the plan stage will create) — never a Gherkin scenario.
+- If the constraint stems from a decision, link the MADR; don't restate the decision (DRY).
+
 **For architecture decisions:**
-- Write MADR record in `.grimoire/changes/<change-id>/decisions/`
+- Write the MADR record directly into the live `.grimoire/decisions/` with the next sequential number (`NNNN-title.md`)
 - Use the template from `.grimoire/decisions/template.md` or the AGENTS.md format
 - Include considered options, decision drivers, and consequences
+- Draft status `proposed`; `grimoire-apply` flips it to `accepted` at finalize
 
 **For changes that touch data:**
 - Check `.grimoire/docs/data/schema.yml` for the current data schema (if it exists)
@@ -271,10 +300,14 @@ This is the contract. Downstream skills (plan, review, verify) use it to generat
 - Every Feature has a user story
 - Every Scenario has at least Given + When + Then
 - No implementation details leaked into features
+- **Re-run the admission test on every scenario you wrote** (step 1): external actor, observable, domain language, survives reimplementation. Any scenario that now fails is slop — move it to `constraints.md` or a MADR before proceeding.
+- **Principles gate** (`../references/principles.md`): no fact written to two homes (DRY), no second way to do an existing thing (one right way), no reinvented wheel (don't reinvent), no artifact created past the stated scope (KISS).
 
 ## Important
 - ONE change at a time. Don't combine unrelated changes.
-- Features describe behavior, not implementation. If you catch yourself writing step-level implementation details, you've gone too far.
+- **Features describe actor-observable behavior, not implementation, and not invariants.** If a scenario has no external actor, isn't observable, or names a library/log-level/table, it is not a feature — it's a constraint (→ `constraints.md`) or a decision (→ MADR). This is the #1 source of feature-file slop.
+- **One fact, one home** (`../references/principles.md`). A capability lives in one `.feature`; a control lives in one constraint row; a decision lives in one MADR. Never the same fact in two places.
+- Artifacts are edited **live on the branch** — never copied into `.grimoire/changes/`. git diff is the staging area.
 - The manifest is lightweight glue — don't over-document. Just enough to capture why.
 - Always check if a capability/feature already exists before creating a new one.
 - **Figma access token is read from `FIGMA_ACCESS_TOKEN` env var by the MCP server.** Never log the token, never write it to config, never include it in `manifest.md`, `consult.md`, `figma-snapshot.json`, or any other artifact. The MCP server handles authentication transparently — grimoire-draft never needs to see the token value.