@kiwidata/grimoire 0.1.4 → 0.1.6

package/.claude-plugin/plugin.json

@@ -1,8 +1,8 @@
 {
   "name": "grimoire",
   "description": "BDD-powered AI coding assistant — Gherkin specs, MADR decisions, and red-green development for AI agents",
-  "version": "0.1.1",
+  "version": "0.1.5",
   "author": "Kiwi Data",
-  "homepage": "https://github.com/kiwi-data/grimoire",
+  "homepage": "https://github.com/KiwiData-AI/grimoire",
   "license": "MIT"
 }

package/AGENTS.md

@@ -22,7 +22,7 @@ These principles govern all grimoire work — drafting, planning, reviewing, and
 
 **Errors at the boundary.** Validate user input and external data at the edges. Internal code can trust its callers — don't defensive-program against situations that can't happen.
 
-**Verify before using.** Before importing a module, calling a function, or adding a dependency — confirm it exists. Check `.grimoire/docs/<area>.md` for reusable code with exact paths. Check `.grimoire/docs/data/schema.yml` for real model fields and API endpoints. If you haven't read the file you're importing from, read it (or its area doc) first. Never guess at package names, function signatures, or API paths.
+**Verify before using.** Before importing a module, calling a function, or adding a dependency — confirm it exists. Query the codebase graph (codebase-memory-mcp: `search_graph`, `get_code_snippet`) for reusable code, exact symbols, and file paths — structure is read live, never from a frozen doc. Read `.grimoire/docs/<area>.md` for an area's purpose, boundaries, and conventions, and the data schema for real model fields and API endpoints. If you haven't read the file you're importing from, read it first. Never guess at package names, function signatures, or API paths.
 
 ## Anti-Loop Protocol
 
@@ -131,7 +131,7 @@ User has a request
 │
 ├─ "Setting up grimoire on an existing project"
 │  1. `grimoire init` → creates .grimoire/ directory and config
-│  2. `/grimoire:discover` → generates conventions files, data schema, project context (requires codebase-memory-mcp)
+│  2. `/grimoire:discover` → generates intent-focused area docs + data schema (queries codebase-memory-mcp for live structure when available)
 │  3. `/grimoire:audit` → discovers undocumented features and decisions
 │  4. Start working: `/grimoire:draft` for new changes, `/grimoire:bug` for fixes
 │
@@ -148,17 +148,16 @@ Skills also have a **Done** section that signals when the workflow is complete.
 
 ## Workflow: Creating or Changing a Feature
 
-This is the end-to-end flow for the most common operation — adding or modifying behavior:
+The end-to-end flow for adding or modifying behavior is six stages, each owned by a skill:
 
-1. **User describes what they want**
-2. **Draft** (`/grimoire:draft`): Qualify the request. Draft `.feature` files and/or ADRs. Write manifest. Collaborate until the user approves. Update manifest status to `approved`.
-3. **Plan** (`/grimoire:plan`): Read approved artifacts. Generate `tasks.md` with red-green test pairs for each scenario. Review with user.
-4. **Review** (`/grimoire:review`): *Optional.* Multi-persona design review — product manager (completeness), senior engineer (simplicity and feasibility), security engineer (vulnerabilities), QA engineer (testability and edge cases). Fix blockers before coding.
-5. **Apply** (`/grimoire:apply`): Work through tasks. For each: write test (must fail), write code (must pass), mark done. Update manifest status to `implementing`.
-6. **Verify** (`/grimoire:verify`): Confirm all scenarios pass, no regressions, decisions followed. Generate report.
-7. **Archive** (`grimoire archive <id>`): Sync features/decisions to baseline. Archive manifest. Update manifest status to `complete`.
+**Draft** (`/grimoire:draft`) → **Plan** (`/grimoire:plan`) → **Review** (`/grimoire:review`, optional) → **Apply** (`/grimoire:apply`) → **Verify** (`/grimoire:verify`) → **PR** (`grimoire pr`).
 
-Each stage has a skill. The user drives the pace. In review mode (default), every file change is approved before writing. In autonomous mode, the agent works through the full task list, stopping only on blockers.
+Each skill's SKILL.md is the authoritative home for that stage's mechanics; the README "Workflow" section is the narrative walkthrough. Do not re-derive stage steps here — invoke the skill. The operational invariants that bind every stage:
+
+- **Manifest status tracks progress:** `approved` after draft, `implementing` during apply, `accepted` at PR.
+- **Live on the branch.** Features, decisions, constraints, and schema are edited directly on the feature branch — no copy-into-change-folder, no promote step.
+- **No archive step.** The PR diff *is* the change; git history plus the `Change: <id>` commit trailer are the record. PR finalize just flips decision status to `accepted` and removes the ephemeral change folder.
+- **The user drives the pace.** Review mode (default) approves every file change before writing; autonomous mode works the full task list, stopping only on blockers.
 
 ### IMPORTANT: tasks.md Is the Plan
 
@@ -179,24 +178,22 @@ If a task seems wrong or impossible during apply:
 
 ## Directory Structure
 
+Features, decisions, constraints, and schema are edited **live on the feature branch** — `git diff` is the staging area. A change folder holds only the ephemeral coordination artifacts (manifest + tasks) and is removed at finalize; the PR diff and git history are the record. There is no proposed-copy tree and no archive tree.
+
 ```
 project-root/
-├── features/                 # Gherkin baseline — behavioral truth
+├── features/                 # Gherkin specs — behavioral truth (edited live)
 │   └── <capability>/
 │       └── <name>.feature
 ├── .grimoire/
-│   ├── decisions/            # MADR baseline — architectural truth
+│   ├── decisions/            # MADR records — architectural truth (edited live)
 │   │   ├── 0001-short-title.md
 │   │   └── template.md
-│   ├── changes/              # proposed changes (in progress)
-│   │   └── <change-id>/
-│   │       ├── manifest.md
-│   │       ├── tasks.md
-│   │       ├── features/     # proposed .feature file state
-│   │       └── decisions/    # new/updated ADRs
-│   └── archive/              # completed changes (manifests only)
-│       └── YYYY-MM-DD-<change-id>/
-│           └── manifest.md
+│   ├── docs/                 # intent-focused area docs, data schema, constraints.md register, OVERVIEW.md
+│   └── changes/              # ephemeral per-change coordination — removed at finalize
+│       └── <change-id>/
+│           ├── manifest.md
+│           └── tasks.md
 ```
 
 ## Conventions
@@ -206,9 +203,8 @@ Every manifest has a `status` field in YAML frontmatter:
 - `draft` — being written, not yet reviewed
 - `approved` — reviewed by user, ready for planning/implementation
 - `implementing` — tasks are being worked on
-- `complete` — all tasks done, ready to archive
 
-Update the status as the change progresses. The CLI reads this to report change state.
+Update the status as the change progresses. The CLI reads this to report change state. There is no `complete`/archive state — finalize removes the ephemeral change folder once the PR is opened; git history is the record.
 
 ### Change IDs
 - Kebab-case, verb-led: `add-two-factor-auth`, `update-login-flow`, `remove-legacy-api`
@@ -237,7 +233,7 @@ Change: add-2fa-login
 Scenarios: "Login with valid TOTP code", "Login with expired TOTP code"
 ```
 
-This is what makes `grimoire trace` and `grimoire log` work. Without it, the commit is invisible to the audit trail. `Scenarios:` and `Decisions:` trailers are included when relevant.
+This is what makes `grimoire trace` work. Without it, the commit is invisible to the audit trail. `Scenarios:` and `Decisions:` trailers are included when relevant.
 
 ### Feature Organization
 - One capability per directory: `features/auth/`, `features/documents/`

package/LICENSE

@@ -0,0 +1,36 @@
+MIT License
+
+Copyright (c) 2026 Kiwi Data
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+--- Additional Restriction ---
+
+Notwithstanding the permissions granted above, the Software and its
+accompanying documentation may NOT be used, in whole or in part, as training
+data, fine-tuning data, or any other input for training, developing, or
+improving any machine learning model, large language model, generative AI
+system, or similar automated system, without the prior written permission of
+the copyright holder.
+
+This restriction is an additional condition on the rights granted above. Use
+of the Software constitutes acceptance of this condition. For the avoidance of
+doubt, this restriction applies regardless of whether such use would otherwise
+be considered fair use or permitted under applicable law, to the maximum
+extent such a restriction is enforceable.

package/README.md

@@ -15,10 +15,10 @@ The software industry spent decades learning hard lessons about building reliabl
 
 Grimoire adds the missing discipline:
 
-- **Specs before code** — every behavior is a Gherkin `.feature` file that doubles as an executable acceptance test
+- **One home per fact** — actor-observable behavior is a Gherkin `.feature`; security/NFR/observability invariants are a constraints register; trade-offs are MADR decisions; data is a schema; code structure is the live graph. No fact lives in two places.
 - **Plans before implementation** — concrete task lists with exact file paths, not "implement the feature"
-- **Tests that actually test** — mandatory red-green BDD cycle with assertion quality checks
-- **Codebase knowledge without exploration** — area docs, data schemas, and symbol maps so the AI doesn't waste context reading files
+- **Tests that actually test** — test-first discipline at the right level (red-green BDD for behavior, unit tests for invariants) with assertion quality checks
+- **Codebase knowledge without exploration** — intent-focused area docs + data schemas, with live structure (symbols, call graphs, reusable code) from codebase-memory-mcp so the AI doesn't waste context reading files
 - **Full audit trail** — every commit traces back to a requirement via git trailers
 - **Architecture decisions on record** — MADR decision records so the AI doesn't re-litigate choices
 
@@ -36,12 +36,12 @@ npm install -g @kiwidata/grimoire
 Requires Node.js 20+ and git.
 
 ```bash
-git clone https://github.com/kiwi-data/grimoire.git
+git clone https://github.com/KiwiData-AI/grimoire.git
 cd grimoire
 npm install
 npm run build
 npm link              # makes `grimoire` available globally
-grimoire --version    # should print 0.1.2
+grimoire --version    # should print the installed version
 ```
 
 To update after pulling new changes:
@@ -64,7 +64,8 @@ To unlink: `npm unlink -g @kiwidata/grimoire`
 ```bash
 cd my-project
 grimoire init          # Auto-detect tools, configure checks, install skills
-grimoire map           # Snapshot codebase structure into .grimoire/docs/
+# Structure comes from codebase-memory-mcp (live). Run /grimoire:discover
+# once to generate intent-focused area docs + data schema.
 ```
 
 Then talk to your AI assistant:
@@ -73,14 +74,15 @@ Then talk to your AI assistant:
 You: "Users should be able to log in with 2FA"
 
 → /grimoire:draft    Creates login.feature with Given/When/Then scenarios
-→ /grimoire:plan     Generates tasks: write step defs, then production code
-→ /grimoire:review   (optional) Product, security, and engineering review
-→ /grimoire:apply    Implements with strict red-green BDD
+→ /grimoire:plan     Generates tasks: write the test, then production code
+→ /grimoire:review   (optional) Product, security, engineering + principles review
+→ /grimoire:apply    Implements test-first (BDD for behavior, unit for invariants)
 → /grimoire:verify   Confirms all scenarios pass, no regressions
-→ grimoire archive    Syncs to baseline, archives manifest
 → grimoire pr         Generates PR description from artifacts
 ```
 
+Artifacts are edited **live on a feature branch** — `git diff` is the staging area. There is no copy-into-change-folder and no promote step.
+
 <details>
 <summary>What <code>grimoire init</code> creates</summary>
 
@@ -88,7 +90,7 @@ Interactive setup that auto-detects your project's tools and asks preferences fo
 
 - `AGENTS.md` — workflow instructions read by AI coding assistants
 - `.grimoire/config.yaml` — tool configuration and check pipeline
-- `.grimoire/` — decisions, docs, change tracking, archive directories
+- `.grimoire/` — decisions, docs (area docs + `constraints.md` register), and change tracking
 - `features/` — where Gherkin specs live
 - `.claude/skills/` — Claude Code skill definitions (ignored by other agents)
 - `.git/hooks/pre-commit` — runs `grimoire check` before commits
@@ -101,43 +103,49 @@ Use `grimoire init --no-detect` to skip interactive tool detection. Most unconfi
 
 ### 1. Draft — Define what you're building
 
-Grimoire routes your request to the right format:
+Grimoire routes your request to its one correct home (an admission test keeps each artifact type clean):
 
-- **"Users should be able to log in with 2FA"** → Gherkin feature
+- **"Users should be able to log in with 2FA"** (external actor, observable) → Gherkin feature
+- **"Logs must never contain PII"** (an invariant, no actor) → `constraints.md` register, **not** a `.feature`
 - **"We should use PostgreSQL instead of MySQL"** → MADR decision record
 - **"The login page is broken"** → `/grimoire:bug` (reproduce first, then fix)
 - **"A tester found a problem"** → `/grimoire:bug-report` → `/grimoire:bug-triage` → routed fix
 
-Produces `.feature` files (with security tags like `@security`, `@auth`, `@pii`, `@pci-dss` when applicable), decision records, `data.yml` for schema changes, and a manifest tracking the change.
+A `.feature` is allowed only if it has an external actor, is observable without reading code/logs, uses domain language, and survives a reimplementation. Security controls, NFRs, and observability guarantees are invariants → they live in the constraints register. Produces `.feature` files (with security tags like `@security`, `@auth`, `@pii`, `@pci-dss` when applicable), constraint entries, decision records, `data.yml` for schema changes, and a manifest tracking the change.
 
 ### 2. Plan — Generate concrete tasks
 
 Every scenario becomes a pair: write the step definition (test), then write the production code. Tasks reference exact file paths, exact assertions, and real patterns from area docs. Data changes (models, migrations) are ordered before feature code.
 
-The plan skill reads `.grimoire/docs/` to find reusable utilities, coding patterns, and where new code should go — so the AI plans with real codebase knowledge, not guesses.
+The plan skill reads area docs for conventions and boundaries, and queries the code graph for reusable utilities and exact symbols — so the AI plans with real codebase knowledge, not guesses. Each task is tagged with its verification level: `scenario` (behavior), `unit-invariant` (a constraint), or `characterization` (internal/refactor).
 
 ### 3. Review — Multi-perspective design review (optional)
 
-Five personas validate the change before any code is written:
+Personas validate the change before any code is written:
 
 - **Product manager** — completeness, missing edge cases, unclear requirements
 - **Senior engineer** — simplicity, code reuse, architecture fit, task quality
 - **Security engineer** — STRIDE threat analysis, OWASP Top 10 / CWE classification, compliance verification (PCI-DSS, HIPAA, GDPR, SOC2 when configured), input validation, auth boundaries, vulnerable dependencies, secrets
 - **QA engineer** — testability, negative scenarios, edge cases, observability, regression risk
 - **Data engineer** — schema design, migration safety, index coverage (when `data.yml` present)
+- **Principles auditor** — flags duplicate homes (DRY), second ways to do a thing (one right way), reinvented wheels, speculative complexity (KISS), and any `.feature` that is really a constraint
 
 Issues flagged as **blocker** or **suggestion**. Security findings tagged with OWASP category and CWE ID. Skip for small/low-risk changes.
 
-### 4. Apply — Build with strict red-green BDD
+### 4. Apply — Build test-first at the right level
+
+Red-green discipline stays; the test *vehicle* matches the task's `verify:` tag — a Gherkin step definition for `scenario` tasks, a unit/integration test for `unit-invariant` and `characterization` tasks. (No `.feature` is forced onto a constraint or an internal change — that's what filled feature files with slop.)
 
 For each task:
-1. Write the step definition (test)
+1. Write the failing test at the task's level
 2. Run it — **must fail** (red). A test that passes immediately is broken.
 3. Write production code
 4. Run it — **must pass** (green)
 5. Test quality check — verify strong assertions, not `assert True`
 6. Mark done, move to next task
 
+Artifacts are edited **live on the feature branch** the whole time — no promote step. Finalize just flips decision status to `accepted` and removes the ephemeral change folder.
+
 **Session management:** Each task (or group of 2-3) runs in a fresh subagent to avoid context bloat. `tasks.md` is the coordination mechanism — if the session is interrupted, the next agent picks up where you left off.
 
 **Stuck detection:** After 3 failed attempts with different approaches on a single task, the agent stops and asks for help instead of looping.
@@ -151,11 +159,11 @@ For each task:
 - **Security compliance** — verifies plan-stage security patterns were followed (parameterized queries, bcrypt, no hardcoded secrets), checks review blockers were addressed, runs OWASP Top 10 surface scan on the diff, validates security-tagged scenarios (`@security`, `@auth`, `@pii`, `@pci-dss`, etc.)
 - **Dead features** — specs that exist but code no longer implements
 
-### 6. PR & Archive
+### 6. PR
 
-`grimoire pr` generates a PR description from manifests, features, decisions, and task progress. Optional `--review` runs an LLM review of the actual diff. `--create` creates via `gh` or `glab`.
+`grimoire pr` generates a PR description from the branch diff, features, decisions, and task progress. Optional `--review` runs an LLM review of the actual diff. `--create` creates via `gh` or `glab`.
 
-`grimoire archive` syncs features to baseline, accepts decisions, updates data schema, and archives the manifest.
+There is no archive step. Features, decisions, constraints, and schema were edited live on the branch; the PR diff *is* the change, and git history + the `Change: <id>` commit trailer are the record.
 
 ## For UI/UX designers
 
@@ -310,17 +318,16 @@ The AI runs `/grimoire:verify`:
 ## Suggestions
 - Consider adding a rate-limiting scenario for repeated failed TOTP attempts
 
-Recommendation: Ready to archive.
+Recommendation: Ready to commit and open a PR.
 ```
 
-### PR & Archive
+### PR
 
 ```bash
 grimoire pr --create        # Creates PR via gh with full description
-grimoire archive add-2fa-login  # Syncs features, accepts decision, archives manifest
 ```
 
-The feature files move to `features/auth/login.feature` (baseline). The decision moves to `.grimoire/decisions/0003-totp-library.md` with status `accepted`. The manifest is archived to `.grimoire/archive/`.
+The feature file was edited live at `features/auth/login.feature` on the branch; the decision is live at `.grimoire/decisions/0003-totp-library.md` with status flipped to `accepted` at finalize; the ephemeral change folder was removed. The PR diff is the change — there's no archive step.
 
 `grimoire trace src/views/auth.py:42` now shows: commit `abc123` → Change: `add-2fa-login` → features: `auth/login.feature` → decision: `0003-totp-library.md`.
 
@@ -396,7 +403,7 @@ Skill also drafts the missing scenario into `features/checkout/place-order.featu
 - [ ] No regression in existing checkout suite
 ```
 
-Commit trailer: `Bug: 0042-place-order-timeout`. Tester runs through the checklist, marks complete, and the bug archives alongside the change.
+Commit trailer: `Bug: 0042-place-order-timeout`. Tester runs through the checklist, marks complete, and the bug closes alongside the change when the PR merges.
 
 </details>
 
@@ -434,13 +441,15 @@ Grimoire owns the **inner loop** — the Dev and Sec portions of DevSecOps. Ops
 | Requirements engineering | Gherkin specs as executable acceptance tests | Draft skill |
 | Architecture decisions | MADR records with cost-of-ownership | Draft skill |
 | Design review | Multi-persona review before code is written | Review skill |
-| Test-driven development | Strict red-green BDD enforcement | Apply skill |
+| Test-driven development | Test-first: red-green BDD for behavior, unit tests for invariants | Apply skill |
 | Test quality | Static analysis for weak/empty/tautological tests | `grimoire test-quality`, verify skill |
 | Regression prevention | All existing tests must pass; regressions block completion | Apply + verify skills |
-| Change management | Manifests, task tracking, session resumption, archive | Full lifecycle |
+| Change management | Manifests, task tracking, session resumption, live-on-branch edits | Full lifecycle |
 | Traceability | Every commit → change → feature → decision | `grimoire trace` |
 | Security review | STRIDE threat modeling, OWASP/CWE tagging at design time | Review + plan + verify skills |
 | Security tooling | SAST, SCA, secrets scanning in pre-commit pipeline | `grimoire check` |
+| Vulnerability triage | CVE noise → VEX verdict + hotfix-now/next-release, scored on KEV/EPSS/reachability vs deployment + recorded controls | Vuln-triage skill |
+| Vulnerability remediation | Triaged findings → bug-tracker tickets, risk-accept register with expiry (feeds back into triage *and* the `dep_audit`/`security` check gate), change stubs for non-trivial fixes | Vuln-remediate skill |
 | Bug discipline | Reproduce-first fixes, structured triage, confidential security handling | Bug workflow skills |
 | Exploratory testing | Gap analysis, coverage mapping, charter-based sessions | Bug-explore + bug-session skills |
 | Tech debt tracking | Structured debt register with severity and formal exceptions | Refactor skill |
@@ -465,6 +474,8 @@ Grimoire's security capabilities are **AI-mediated at design time**, not static
 
 This means security coverage depends on: (1) configuring the right tools in your check pipeline, and (2) the AI following its own instructions. Projects that run `grimoire init` with detection get solid defaults. Projects that skip detection should configure `tools.security`, `tools.dep_audit`, and `tools.secrets` in `.grimoire/config.yaml`.
 
+**Vulnerability triage.** Scanners (`npm audit`, `pip-audit`, `osv-scanner`) rank CVEs by CVSS base score, which knows nothing about your deployment — so they over-escalate. The vuln-triage skill scores each advisory the way it actually matters here: KEV (known-exploited), EPSS (exploit probability), reachability (is the vulnerable code even on our execute path), and exposure/controls read from `context.yml` + MADR decisions — never a new config file. The output is a [VEX](https://www.cisa.gov/sites/default/files/2023-04/minimum-requirements-for-vex-508c.pdf) verdict per CVE (`not_affected` with a justification code suppresses noise auditably) and, for the survivors, the only decision that matters: **drop-everything hotfix vs next release cycle**. A Contrarian calibration pass (the same one from the review engine) steel-mans "we're not affected" against every escalation to kill manufactured emergencies. Full rubric in `skills/references/dependency-vuln-triage.md`. Accepted findings land in `.grimoire/security/accepted-risks.yml` with an expiry; the `dep_audit` and `security` check steps read that register and suppress an advisory only while its entry is unexpired — so the commit gate stops blocking on triaged-away findings (e.g. a dev-only CVE) without silently ignoring new ones.
+
 **Supply chain defense.** For apps and services, the review and verify skills treat any dependency add/upgrade without a committed lockfile (and integrity hashes, where the ecosystem supports them) as a **blocker** — motivated by recent npm / PyPI / RubyGems / Cargo maintainer-account compromises that auto-installed through floating version ranges. Per-ecosystem rules cover `package.json` + lockfile (no `^`/`~`/`*`/`latest` for apps), `uv.lock` / `poetry.lock` / `pip-compile --generate-hashes`, `Gemfile.lock` with `CHECKSUMS` (Bundler 2.5+), `Cargo.lock` for binaries, and `go.mod` + `go.sum`. CI must install from the lockfile (`npm ci`, `pnpm install --frozen-lockfile`, `yarn install --immutable`, `uv sync --frozen`, `pip install --require-hashes`, `bundle install --deployment`, `cargo build --locked`, `go build` with `-mod=readonly`). Libraries published to a registry are out of scope — keep compatible ranges in your published manifest. Full ruleset in `skills/references/security-compliance.md`.
 
 Grimoire does not provide compliance framework enforcement (OWASP ASVS checklists, CWE mapping), SBOM generation, artifact signing, or DAST. These require dedicated security tooling.
@@ -473,29 +484,40 @@ Grimoire does not provide compliance framework enforcement (OWASP ASVS checklist
 
 ### Codebase Intelligence
 
-```bash
-grimoire map                # Structural snapshot (.grimoire/docs/.snapshot.json)
-grimoire map --refresh      # Diff against existing docs, show gaps
-grimoire map --duplicates   # Run jscpd duplicate detection
-grimoire map --depth <n>    # Max directory depth to scan (default 4)
-```
-
-Snapshots the directory layout, language mix, and per-area metrics so area docs and plans don't have to re-explore the tree. No native dependencies.
+Structure is **live, not stored.** Symbols, call graphs, data-flow, dead code, and reusable utilities come from [codebase-memory-mcp](https://github.com/DeusData/codebase-memory-mcp) on demand (`search_graph`, `get_architecture`, `trace_path`) — there is no frozen snapshot to go stale. `grimoire init` offers to install it.
 
-For richer intelligence (call graphs, data flow tracing, dependency analysis), grimoire integrates with [codebase-memory-mcp](https://github.com/DeusData/codebase-memory-mcp). `grimoire init` offers to install it.
+Duplicate detection and convention-drift checks live in `grimoire health` (config-driven). Grimoire stores only what the graph *can't* derive — intent, boundaries, decisions, constraints.
 
 ### Area Docs & Data Schema
 
-`grimoire map` + `/grimoire:discover` generates docs in `.grimoire/docs/`:
+`/grimoire:discover` generates **intent-focused** docs in `.grimoire/docs/`:
 
 - Purpose and boundaries of each module
-- Key files with responsibilities
-- **Reusable code inventory** — exact function names, file paths, line numbers
-- Naming conventions, structural patterns, where new code goes
+- Conventions (naming, structure) with exemplar file references
+- Where new code of each type goes
+
+Area docs deliberately do **not** list key files or a reusable-code inventory — that's structure, and the graph regenerates it live (a frozen copy drifts). Discover runs only when an area's *intent* changes, not on every code change.
 
 `.grimoire/docs/data/schema.yml` captures your data layer — SQL tables, document collections, external API contracts — so the AI reads this instead of model files.
 
-`grimoire docs` generates a browsable `.grimoire/docs/OVERVIEW.md` project summary.
+`grimoire docs` generates a browsable `.grimoire/docs/OVERVIEW.md` — the single human entry point: what the app is, its actors, capabilities (grouped by functional story), constraints, architecture, and decisions, each linking down.
+
+### Rendering into your doc site
+
+`grimoire docs` emits **portable CommonMark** — grimoire owns the spec *storage* (features, constraints, decisions, schema); your existing doc tool owns *rendering*. Grimoire ships no renderer and standardizes on no doc tool. Include the output wherever your project already publishes:
+
+- **Sphinx** (with [myst-parser](https://myst-parser.readthedocs.io)): point grimoire at your docs tree and include the page in a toctree —
+  ```bash
+  grimoire docs -o docs/overview.md
+  ```
+  ````markdown
+  ```{include} overview.md
+  ```
+  ````
+- **MkDocs**: `grimoire docs -o docs/overview.md`, then add `overview.md` to `nav:`.
+- **No doc tool**: read `.grimoire/docs/OVERVIEW.md` directly — it's plain markdown.
+
+The source artifacts stay tool-agnostic, so the AI workflow doesn't depend on any renderer. Regenerate `OVERVIEW.md` whenever artifacts change (`grimoire-apply` does this at finalize).
 
 ### Pre-Commit Pipeline
 
@@ -518,6 +540,8 @@ grimoire check
 
 Auto-detected during `grimoire init`. Any tool can use `name: llm` with a `prompt:` for AI-powered review. Also sets up enforcement hooks for Claude Code (`.claude/hooks.json`) and git (`.git/hooks/pre-commit`).
 
+> ⚠️ **Security: `.grimoire/config.yaml` is trusted code.** `grimoire check` and `grimoire health` execute the shell commands defined in your config's tool steps (`command:` / `check_command:`), and the installed pre-commit hook runs `grimoire check` automatically on every commit. This is the same trust model as `npm` scripts, `Makefile`s, or git hooks — the config can run any command on your machine. **Do not run `grimoire check`/`health`, commit, or let an AI agent commit in a freshly cloned untrusted repository** until you have reviewed its `.grimoire/config.yaml`. Grimoire never sends your code anywhere: the only network calls are an npm version check (your package name only; opt out with `GRIMOIRE_NO_UPDATE_CHECK=1`) and piping diffs to the LLM CLI *you* configured.
+
 ### Test Quality
 
 ```bash
@@ -563,8 +587,8 @@ Developer picks it up → /grimoire:bug-triage → classify root cause
 Every commit includes a `Change:` git trailer linking code → commit → change → feature → decision.
 
 ```bash
-grimoire trace src/auth.py:42   # What requirement introduced this line?
-grimoire log --from v1.0        # Release notes from archived changes
+grimoire trace src/auth.py:42        # What requirement introduced this line?
+git log --grep "Change: add-2fa-login"   # Every commit for a change, via its trailer
 ```
 
 ### Project Health
@@ -574,14 +598,15 @@ grimoire health
 
   features          100%  ██████████  12 scenarios in 5 files
   decisions          89%  █████████░  8/9 current
-  area docs          75%  ████████░░  6/8 areas documented
+  area docs         100%  ██████████  6 areas documented
   data schema       100%  ██████████  4 models documented
+  conventions drift 100%  ██████████  no drift — paths match
   test coverage      60%  ██████░░░░  3/5 features have step definitions
   unit coverage      82%  █████████░  82% line coverage
   duplicates           —              2 clones detected
   complexity           —              no high-complexity functions
 
-  Overall            84%  █████████░
+  Overall            87%  █████████░
 ```
 
 ### Contract Testing
@@ -640,16 +665,18 @@ grimoire init --agent copilot                   # .github/copilot-instructions.m
 |-------|---------|
 | `/grimoire:draft` | Draft features and/or decisions collaboratively |
 | `/grimoire:plan` | Generate detailed implementation tasks from specs |
-| `/grimoire:review` | Multi-perspective design review (PM, engineer, security, QA, data) |
-| `/grimoire:apply` | Execute tasks with strict red-green BDD |
+| `/grimoire:review` | Multi-perspective design review (PM, engineer, security, QA, data, principles) |
+| `/grimoire:apply` | Execute tasks test-first at the right level (BDD for behavior, unit for invariants) |
 | `/grimoire:verify` | Post-implementation verification + test quality |
 | `/grimoire:audit` | Discover undocumented features and decisions |
 | `/grimoire:remove` | Tracked feature removal with impact assessment |
-| `/grimoire:discover` | Generate area docs and data schema from codebase |
+| `/grimoire:discover` | Generate intent-focused area docs and data schema |
 | `/grimoire:refactor` | Find, prioritize, and track tech debt |
 | `/grimoire:bug` | Disciplined bug fix with reproduction test first |
 | `/grimoire:bug-report` | Structured bug reporting (accepts test tool output) |
 | `/grimoire:bug-triage` | Classify and route bug reports |
+| `/grimoire:vuln-triage` | Triage vuln scans (npm audit / pip-audit / Trivy / any tool) against deployment + controls — hotfix-now vs next release |
+| `/grimoire:vuln-remediate` | File triaged vulns — tickets in the bug tracker, risk-accept register with expiry, change stubs for big fixes |
 | `/grimoire:bug-explore` | AI-guided exploratory testing and gap analysis |
 | `/grimoire:bug-session` | Charter-based exploratory testing sessions |
 | `/grimoire:branch-guard` | Enforce branch hygiene before starting new feature work (also wired as a hook) |
@@ -672,22 +699,19 @@ grimoire init --agent copilot                   # .github/copilot-instructions.m
 | `grimoire init --skip-agents` | Skip generating AGENTS.md instructions |
 | `grimoire init --skip-skills` | Skip installing skills for selected agents |
 | `grimoire init --no-detect` | Skip auto-detection of project tools |
+| `grimoire init --full` | Also run all deferred configure sections (compliance, design, LLM models, bug trackers, testing tools) |
 | `grimoire init --install-codebase-memory-mcp` | Mark codebase-memory-mcp as a recommended integration |
 | `grimoire init --install-caveman-plugin` | Mark caveman skill plugin as a recommended integration |
 | `grimoire update [path]` | Update AGENTS.md, skills, and hooks to latest version |
 | `grimoire update --skip-agents\|--skip-skills\|--skip-hooks\|--skip-templates\|--skip-config` | Skip parts of the update |
 | `grimoire update --force-templates` | Overwrite existing template files |
+| `grimoire configure [section]` | Configure options deferred from init: compliance, design tool, LLM models, bug trackers, testing tools (omit section for interactive menu) |
 | `grimoire list` | List active changes (with conflict detection) |
 | `grimoire list --features` | List feature files |
 | `grimoire list --decisions` | List decision records |
 | `grimoire status <id>` | Show change status, branch, and task progress |
 | `grimoire validate [id]` | Validate features, decisions, and manifests |
 | `grimoire validate --strict` | Enable strict validation |
-| `grimoire archive <id> [-y]` | Archive a completed change (`-y` skips confirmation) |
-| `grimoire map` | Structural codebase scan |
-| `grimoire map --duplicates` | Run jscpd duplicate detection |
-| `grimoire map --refresh` | Diff against existing docs, show gaps |
-| `grimoire map --depth <n>` | Max directory depth to scan (default 4) |
 | `grimoire check [steps...]` | Run pre-commit pipeline |
 | `grimoire ci` | Run CI pipeline |
 | `grimoire ci --setup` | Generate `.github/workflows/grimoire.yml` template |
@@ -697,7 +721,6 @@ grimoire init --agent copilot                   # .github/copilot-instructions.m
 | `grimoire pr --create` | Create PR via gh/glab |
 | `grimoire pr --review` | Run post-implementation LLM review of diff |
 | `grimoire test-quality [files]` | Analyze test files for quality issues |
-| `grimoire log [--from <ref>] [--to <ref>]` | Generate change log / release notes |
 | `grimoire trace <file[:line]>` | Trace file to originating grimoire change |
 | `grimoire diff <id>` | Compare proposed change specs against the baseline |
 | `grimoire docs [-o <path>]` | Generate human-readable project overview |
@@ -810,7 +833,7 @@ testing_tools:
 
 ## Contributing
 
-Issues and pull requests welcome at [github.com/kiwi-data/grimoire](https://github.com/kiwi-data/grimoire). Grimoire dogfoods itself — `.grimoire/` in this repo is built using grimoire skills, so contributions are expected to go through the same `draft → plan → apply → verify → pr` workflow described above.
+Issues and pull requests welcome at [github.com/KiwiData-AI/grimoire](https://github.com/KiwiData-AI/grimoire). Grimoire dogfoods itself — `.grimoire/` in this repo is built using grimoire skills, so contributions are expected to go through the same `draft → plan → apply → verify → pr` workflow described above.
 
 **Before opening a PR:**
 
@@ -826,7 +849,7 @@ Issues and pull requests welcome at [github.com/kiwi-data/grimoire](https://gith
 ### Development Setup
 
 ```bash
-git clone https://github.com/kiwi-data/grimoire.git
+git clone https://github.com/KiwiData-AI/grimoire.git
 cd grimoire
 npm install
 npm run build        # Compile TypeScript
@@ -853,7 +876,7 @@ grimoire/
 ### Adding a New Skill
 
 1. Create `skills/grimoire-<name>/SKILL.md` with trigger, prerequisites, workflow, and important notes
-2. Add `"grimoire-<name>"` to the `skillNames` array in both `src/core/init.ts` and `src/core/update.ts`
+2. Add `"grimoire-<name>"` to the `SKILL_NAMES` array in `src/core/shared-setup.ts` (shared by init and update)
 3. Build and test: `npm run build && node bin/grimoire.js update .`
 
 Skills are pure markdown — instructions for the AI, not executable code.
@@ -874,12 +897,14 @@ Skills are pure markdown — instructions for the AI, not executable code.
 
 ## Philosophy
 
-- **Features are tests.** A `.feature` file is both the requirement and the acceptance test.
-- **Red-green is mandatory.** A test must fail before it passes. If it doesn't fail, it's not a real test.
+- **One home per fact.** Behavior → feature; invariant → constraint; trade-off → decision; data → schema; structure → the live graph. No fact in two places (DRY).
+- **One right way.** Each thing has a single sanctioned approach. Two ways to do the same job is a defect, even if both work.
+- **Don't reinvent the wheel.** Use the tool that exists — git for isolation/staging/history, standard libraries for crypto/auth/parsing — not a bespoke grimoire clone of it.
+- **Features are tests — when they're behavior.** A `.feature` is the requirement and the acceptance test, but only for actor-observable behavior. Invariants are unit-tested constraints, not Gherkin.
+- **Red-green is mandatory.** A test must fail before it passes — at the right level (BDD for behavior, unit for invariants).
 - **Decisions are documented.** Architecture choices that aren't written down get relitigated.
 - **Reproduce before you fix.** Every bug gets a failing test before any code changes.
 - **Simple over clever.** Less code, fewer abstractions, smallest surface area.
-- **Verify before using.** Confirm imports, functions, and packages exist before writing code that depends on them.
 - **Removal is deliberate.** Removing a feature gets the same rigor as adding one.
 - **The fix is upstream.** You don't fix codebase entropy by reviewing harder — you fix it by requiring specs before code.
 

package/dist/cli/index.js

@@ -1,44 +1,3 @@
-import { Command } from "commander";
-import { initCommand } from "../commands/init.js";
-import { updateCommand } from "../commands/update.js";
-import { validateCommand } from "../commands/validate.js";
-import { listCommand } from "../commands/list.js";
-import { statusCommand } from "../commands/status.js";
-import { archiveCommand } from "../commands/archive.js";
-import { mapCommand } from "../commands/map.js";
-import { checkCommand } from "../commands/check.js";
-import { logCommand } from "../commands/log.js";
-import { traceCommand } from "../commands/trace.js";
-import { docsCommand } from "../commands/docs.js";
-import { healthCommand } from "../commands/health.js";
-import { prCommand } from "../commands/pr.js";
-import { testQualityCommand } from "../commands/test-quality.js";
-import { diffCommand } from "../commands/diff.js";
-import { ciCommand } from "../commands/ci.js";
-import { branchCheckCommand } from "../commands/branch-check.js";
-import { configureCommand } from "../commands/configure.js";
-const program = new Command();
-program
-    .name("grimoire")
-    .description("Gherkin + MADR spec-driven development for AI coding assistants")
-    .version("0.1.2");
-program.addCommand(initCommand);
-program.addCommand(updateCommand);
-program.addCommand(validateCommand);
-program.addCommand(listCommand);
-program.addCommand(statusCommand);
-program.addCommand(archiveCommand);
-program.addCommand(mapCommand);
-program.addCommand(checkCommand);
-program.addCommand(logCommand);
-program.addCommand(traceCommand);
-program.addCommand(docsCommand);
-program.addCommand(healthCommand);
-program.addCommand(prCommand);
-program.addCommand(testQualityCommand);
-program.addCommand(diffCommand);
-program.addCommand(ciCommand);
-program.addCommand(branchCheckCommand);
-program.addCommand(configureCommand);
-program.parse();
+import { buildProgram } from "./program.js";
+buildProgram().parse();
 //# sourceMappingURL=index.js.map

package/dist/cli/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AACtD,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAC1D,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AACtD,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AACxD,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAChD,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACpD,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAChD,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACpD,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AACtD,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAC9C,OAAO,EAAE,kBAAkB,EAAE,MAAM,6BAA6B,CAAC;AACjE,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAC9C,OAAO,EAAE,kBAAkB,EAAE,MAAM,6BAA6B,CAAC;AACjE,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAE5D,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAC;AAE9B,OAAO;KACJ,IAAI,CAAC,UAAU,CAAC;KAChB,WAAW,CACV,iEAAiE,CAClE;KACA,OAAO,CAAC,OAAO,CAAC,CAAC;AAEpB,OAAO,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC;AAChC,OAAO,CAAC,UAAU,CAAC,aAAa,CAAC,CAAC;AAClC,OAAO,CAAC,UAAU,CAAC,eAAe,CAAC,CAAC;AACpC,OAAO,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC;AAChC,OAAO,CAAC,UAAU,CAAC,aAAa,CAAC,CAAC;AAClC,OAAO,CAAC,UAAU,CAAC,cAAc,CAAC,CAAC;AACnC,OAAO,CAAC,UAAU,CAAC,UAAU,CAAC,CAAC;AAC/B,OAAO,CAAC,UAAU,CAAC,YAAY,CAAC,CAAC;AACjC,OAAO,CAAC,UAAU,CAAC,UAAU,CAAC,CAAC;AAC/B,OAAO,CAAC,UAAU,CAAC,YAAY,CAAC,CAAC;AACjC,OAAO,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC;AAChC,OAAO,CAAC,UAAU,CAAC,aAAa,CAAC,CAAC;AAClC,OAAO,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC;AAC9B,OAAO,CAAC,UAAU,CAAC,kBAAkB,CAAC,CAAC;AACvC,OAAO,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC;AAChC,OAAO,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC;AAC9B,OAAO,CAAC,UAAU,CAAC,kBAAkB,CAAC,CAAC;AACvC,OAAO,CAAC,UAAU,CAAC,gBAAgB,CAAC,CAAC;AAErC,OAAO,CAAC,KAAK,EAAE,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAE5C,YAAY,EAAE,CAAC,KAAK,EAAE,CAAC"}

package/dist/cli/program.d.ts

@@ -0,0 +1,4 @@
+import { Command } from "commander";
+/** Build the configured CLI. Single source for the executable and the docs generator. */
+export declare function buildProgram(): Command;
+//# sourceMappingURL=program.d.ts.map

package/dist/cli/program.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"program.d.ts","sourceRoot":"","sources":["../../src/cli/program.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAqBpC,yFAAyF;AACzF,wBAAgB,YAAY,IAAI,OAAO,CAyBtC"}