@kiwidata/grimoire 0.1.3 → 0.1.5

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,84 +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`)
+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.
 
-Use this as your roadmap. The snapshot tells you WHERE to look; you add WHAT it means.
-
-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:
-- **Full scan** — document all areas from the snapshot (default for first run)
+Ask the user what to document (or accept the scope passed in by a calling skill):
+- **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 (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>
@@ -109,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.
@@ -174,6 +142,66 @@ Scan the codebase for data models, ORM definitions, migration files, and schema
 
 If `.grimoire/docs/data/` already exists, update it rather than regenerating. Diff against existing schema.yml to flag new models or removed fields.
 
+### 5.5 Component Inventory (optional)
+
+Scan the codebase for an existing UI component library, then produce `.grimoire/docs/components.md` documenting reusable components. This inventory lets `grimoire-design` reuse what exists instead of generating duplicate components.
+
+**Detection — component library:**
+
+| Signal | What it tells you |
+|--------|------------------|
+| `components.json` | shadcn/ui — components live under the configured `aliases.components` path (typically `components/ui/`) |
+| `tailwind.config.{js,ts}` | Tailwind project — utility-first; components are project-local |
+| `package.json` deps: `@mui/material` | Material UI — components imported from `@mui/material/*` |
+| `package.json` deps: `@chakra-ui/react` | Chakra UI — components imported from `@chakra-ui/react` |
+| `package.json` deps: `@mantine/core` (or any `mantine` package) | Mantine |
+| `package.json` deps: `@radix-ui/*` | Radix primitives — usually wrapped by shadcn or project components |
+
+**Detection — Storybook:**
+
+| Signal | What it tells you |
+|--------|------------------|
+| `.storybook/main.{ts,js}` | Storybook configured — stories define canonical component variants |
+| `*.stories.{ts,tsx,jsx,js}` | Story files — each story is a documented component variant |
+
+**Skip condition:** If no library signal and no story files are found, emit a single-line note ("No UI component signals detected — skipping component inventory.") and continue to §6. Do not create `components.md`.
+
+**Workflow:**
+1. Detect the library (or libraries) using the signals above
+2. Locate component source files — for shadcn, walk `components/ui/`; for project-local components, look under `src/components/`, `app/components/`, or wherever the convention places them
+3. For each component file, extract: name, file path, exported variants (e.g., `variant="primary|secondary"`), and notable props (especially required ones)
+4. If Storybook is present, walk `*.stories.*` files to harvest the canonical variant list per component — stories are the source of truth for which variants exist
+5. Write `.grimoire/docs/components.md` listing each component with file path, variants, and key props
+
+**`components.md` format:**
+
+```markdown
+# Component Inventory
+> Last updated: YYYY-MM-DD
+> Library: <shadcn | MUI | Chakra | Mantine | project-local | mixed>
+
+## Components
+
+| Component | Location | Variants | Key Props | Notes |
+|-----------|----------|----------|-----------|-------|
+| `Button` | `components/ui/button.tsx` | `default`, `destructive`, `outline`, `ghost`, `link` | `variant`, `size`, `asChild` | Wraps Radix Slot when `asChild` |
+| `Dialog` | `components/ui/dialog.tsx` | — | `open`, `onOpenChange` | Compound: `Dialog`, `DialogTrigger`, `DialogContent` |
+
+## Stories
+<Only if Storybook detected. List story files and the variants they document.>
+
+| Story File | Component | Documented Variants |
+|------------|-----------|---------------------|
+| `Button.stories.tsx` | `Button` | Primary, Secondary, Destructive, Loading |
+```
+
+**Rules:**
+- Document what exists in code, not what should exist. If the project has both shadcn and ad-hoc components, list both and note the inconsistency.
+- Point to source files; do not duplicate component code into the doc.
+- Variants come from prop unions in the type signature OR from the canonical Storybook stories — prefer Storybook when present.
+- Only list components meant for reuse. Skip one-off page-level components (e.g., `LoginPage`) unless they're imported elsewhere.
+- If `.grimoire/docs/components.md` already exists, update it — diff against existing entries to flag new or removed components.
+
 ### 6. Generate Project Context
 
 Scan the codebase for deployment and infrastructure artifacts, then populate `.grimoire/docs/context.yml`. This file captures the project's ecosystem — how it's deployed, what services it talks to, and what infrastructure it depends on. If `context.yml` doesn't exist, copy it from the template first (`grimoire init` creates it, but this handles projects initialized before this feature).
@@ -229,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
 
@@ -262,36 +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
-- Run `grimoire map --refresh` periodically to detect new undocumented areas, then `/grimoire:discover` to fill the gaps
+- The **design** skill reads `.grimoire/docs/components.md` first to avoid generating duplicate components
+- 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.
+| 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
 
@@ -63,7 +79,20 @@ Before designing, research what already exists. Do not ask the user to research
 
 Follow the methodology in `../references/build-vs-buy.md`. Present findings to the user and wait for agreement before proceeding.
 
+### 4.0 Design Input Check
+
+Before interviewing, check whether design artifacts already exist for this change. If so, the interview is grounded in real components and states rather than imagined ones.
+
+- **Existing design output**: If `.grimoire/changes/<change-id>/designs/` is already populated (a prior `grimoire-design` run produced `problem.md`, `variants.md`, `variant-{n}.html`, or `figma-snapshot.json`), read those artifacts now. Treat them as authoritative for component shape, states, and visual tokens — do not re-query Figma.
+- **Figma MCP available, no design folder**: If `project.design_tool.mcp` is configured and `designs/` is absent, ask: "Figma file URL or node ID? (or skip)". On a URL or node reference, query the Figma MCP for frame data and cache the response at `.grimoire/changes/<change-id>/designs/figma-snapshot.json` per `../references/design-input-formats.md` §1 Cache. On "skip" or empty input, continue to standard elicitation.
+- **No MCP and no design folder**: skip this step silently. Fall back to the standard interview elicitation in step 4 below.
+
+When design input is consumed (either path), carry the extracted component list, states, and any token references into the elicitation in step 4 — these become concrete anchors for the questions you ask the user, replacing generic prompts.
+
 ### 4. Elicit Requirements
+
+**Interview, don't assume.** The most common drafting failure is filling in gaps with plausible-sounding guesses. Every unstated detail is either (a) something the user has an opinion on and you must ask, or (b) something project conventions answer unambiguously. Never a third option where you invent.
+
 Now that you know whether you're building, adopting, or going hybrid, surface the requirements the user hasn't specified.
 
 - **Level 1**: Skip this step.
@@ -74,6 +103,24 @@ The build-vs-buy outcome shapes which questions matter:
 - **Building custom**: Full elicitation — business rules, edge cases, data contracts, security, NFRs.
 - **Hybrid**: Elicit deeply for custom parts. For adopted parts, focus on integration boundaries.
 
+#### Interview protocol
+
+1. **Outcome & Non-goals first.** Always ask these two before any persona questions — they set scope. Restate the answers back to the user before continuing.
+2. **Batch questions, then wait.** Ask 3-5 questions at a time, grouped by persona. Stop. Wait for the user's reply. Do not draft scenarios until the batch is answered.
+3. **Ask the question; don't pre-answer it.** "Should locked accounts get an email?" — not "I'll assume locked accounts get an email, let me know if not." The pre-answered form lets the user nod through assumptions they'd otherwise correct.
+4. **One question per ambiguity, not a checklist dump.** If the user said "users can reset password", do not ask 12 generic questions. Ask the 3 that matter for *this* feature.
+5. **Disambiguate immediately.** If the user's answer is vague ("yeah, handle errors gracefully"), ask the specific follow-up ("for invalid tokens, do we redirect to login with a flash message, return a 400, or something else?"). Never leave a vague answer in the spec.
+6. **Capture, don't extrapolate.** If the user explicitly says "out of scope for now", note it as a non-goal and stop. Don't draft a scenario "just in case".
+7. **When the user pushes back on a question** ("just write something reasonable"), record their delegation explicitly: "Defaulting to <choice> per user delegation — flag in review if wrong." This makes the assumption visible later.
+
+#### Open-question discipline
+
+After the interview, list every open question that wasn't answered. These become:
+- **Manifest Assumptions** (level 3-4) — each open question becomes an unvalidated assumption with the reading you chose.
+- **Open questions in the Requirements Summary** — explicitly listed so the user sees what you guessed.
+
+Never silently fill in an open question. Either ask, defer to a non-goal, or record the inference.
+
 Present a Requirements Summary (template in the reference) and wait for user confirmation before proceeding.
 
 ### 5. Check Existing State
@@ -82,15 +129,56 @@ Present a Requirements Summary (template in the reference) and wait for user con
 - Read `.grimoire/docs/context.yml` (if it exists) to understand the deployment environment, related services, and infrastructure — this tells you what's available (caches, queues, sibling services) and what constraints apply (deployment target, environments)
 - Check `.grimoire/changes/` for any in-progress changes that might overlap
 - If there's a conflict with an active change, flag it
+- If `.grimoire/changes/<change-id>/consult.md` exists (from a prior `grimoire-design-consult` run), parse the `## Inferred assumptions` and `## Inferred givens` sections verbatim. Copy the contents of `## Inferred assumptions` into the manifest's Assumptions section, and copy `## Inferred givens` into a new Givens section at the same heading level (Givens applies to level 3-4 only — skip for level 1-2). The H2 headers `## Inferred assumptions` and `## Inferred givens` are load-bearing — they are the exact section names `grimoire-design-consult` writes; do not paraphrase, retitle, or fuzzy-match. Open questions from `consult.md` are NOT copied — they remain in `consult.md` as designer follow-up items.
 
 ### 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:**
-- Write proposed `.feature` files in `.grimoire/changes/<change-id>/features/<capability>/`
-- If modifying an existing feature, copy the current baseline first, then modify
+
+Before writing any `.feature` file, triage existing files. **The default is always extend. New files are the exception and require explicit justification.**
+
+**Step 1 — List existing feature files (required, not skippable)**
+
+Read `features/` recursively. Print a table before doing anything else:
+
+```
+Existing feature files:
+  features/auth/login.feature         — "User Login"
+  features/auth/registration.feature  — "User Registration"
+  features/billing/invoices.feature   — "Invoice Management"
+  ...
+```
+
+If `features/` is empty or doesn't exist, skip to step 3.
+
+**Step 2 — Match each proposed scenario to an existing file**
+
+For each scenario you intend to draft, explicitly decide: extend or new? Show the decision:
+
+```
+Scenario triage:
+  "Admin resets a user's password"  → extend features/auth/login.feature  (same actor domain: auth)
+  "User exports invoices as CSV"    → extend features/billing/invoices.feature  (same resource)
+  "User configures SSO provider"    → NEW  (no existing file owns SSO configuration)
+```
+
+Do not proceed to writing until this table is complete. If unsure about a match, default to extend.
+
+**Step 3 — Execute (edit live on the branch)**
+
+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.
+
+- 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
@@ -98,13 +186,36 @@ Present a Requirements Summary (template in the reference) and wait for user con
   - Given/When/Then — describe WHAT, never HOW
   - No implementation details in feature files
 
+**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>/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`.
+- Hardcoded hex values in scenarios drift silently when tokens change. Token names stay correct across re-skins.
+
+**Component-library awareness:**
+- When `.grimoire/docs/components.md` exists, prefer references to existing components by name in scenarios (e.g., `Then a Button with variant="primary" is rendered` over `Then a blue button appears`).
+- Flag net-new components explicitly: emit "new component required — confirm before plan stage" alongside any scenario that introduces a component not listed in `components.md`. The plan stage will then decide whether to add it to the inventory or reuse an existing variant.
+
 **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)
@@ -189,12 +300,17 @@ 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.
 
 ## Done
 When the user approves the draft, the workflow is complete. Present the change directory path and suggest next steps: