@kiwidata/grimoire 0.1.3 → 0.1.5

package/skills/grimoire-plan/SKILL.md

@@ -28,6 +28,34 @@ Derive implementation tasks from approved Gherkin features and MADR decisions. T
 
 ## Workflow
 
+### Operating Rules (apply to every step)
+
+**1. Verify, don't delegate.** Any claim that can be answered by reading the codebase is *your* job — do it now, do not punt it to the implementer or the user. Forbidden task shapes:
+
+- "Check whether `foo()` is already used somewhere"
+- "Verify if module X exists"
+- "Confirm the import path for Y"
+- "See if there's an existing utility for Z"
+- "TODO: check if this conflicts with…"
+
+Resolve each one yourself before writing the task. Tools: codebase-memory-mcp (`search_graph`, `trace_path`, `get_code_snippet`) for symbols and reusable code, `.grimoire/docs/<area>.md` for conventions/boundaries, `Grep`, neighbor files. The task should state the *answer* ("Reuse `parse_invoice` in `src/billing/parsing.py:42`" or "No existing utility — write new"), never the *question*.
+
+**2. Clarify or propose, never assume.** When the spec is ambiguous or silent on something you need to plan:
+
+- **Ambiguous** (spec contradicts itself, two readings are plausible) → ask the user one specific question. Do not pick a reading and proceed.
+- **Silent on a scenario you think is needed** (e.g., "what if the login attempt rate-limits?") → propose adding it. Route back to `grimoire-draft` for the spec update, or ask the user to confirm before you add a corresponding task. **Do not silently invent scenarios, edge cases, or tasks not derivable from approved features / ADRs / `data.yml` / manifest sections.**
+- **Confident** (spec is clear or the unstated detail follows obviously from project conventions) → plan, but note the inference in a `<!-- inferred: ... -->` comment so the user can override.
+
+The plan implements what's approved. It does not expand scope to hit a checklist.
+
+**3. Plan to the principles.** Every task is gated by the four principles in `../references/principles.md` — **one right way, DRY, don't reinvent the wheel, keep it simple.** Concretely, before writing each task:
+- **One right way:** name the single sanctioned approach. If the spec leaves two ways open, pick one (record why in the task) — never plan both.
+- **DRY:** reuse before write (search the graph); don't plan a task that stores a fact already derivable from code/mcp or already homed elsewhere.
+- **Don't reinvent:** prefer an existing tool/library/proven pattern over a bespoke mechanism. git for change process, standard libs for crypto/auth/parsing.
+- **Keep it simple:** choose the least-code option inside the non-goals. Flag any task that adds an abstraction, a dependency, or a second mechanism — it needs an explicit reason.
+
+These are gates, not aspirations — a task that adds a duplicate home or a reinvented wheel is rejected, not refined.
+
 ### 1. Select Change
 - List active changes in `.grimoire/changes/`
 - If multiple, ask user which one to plan
@@ -39,9 +67,10 @@ Derive implementation tasks from approved Gherkin features and MADR decisions. T
 
 **Always read:**
 - `manifest.md` for the change summary, **including complexity level, Assumptions, Pre-Mortem, and Prior Art sections**
-- All proposed `.feature` files
-- All proposed decision records, **including Cost of Ownership sections**
-- The current baseline (`features/`, `.grimoire/decisions/`) for context on what's changing
+- All `.feature` files for this change (edited live in `features/` on the branch)
+- All decision records for this change (edited live in `.grimoire/decisions/`), **including Cost of Ownership sections**
+- `.grimoire/docs/constraints.md` — any constraints (security/NFR/observability) this change adds or touches. These produce `unit-invariant` tasks, not scenarios.
+- The current baseline (`features/`, `.grimoire/decisions/`) via `git diff main` to see exactly what this change adds vs. what already existed
 
 **Validate the build-vs-buy decision:**
 - Check that `manifest.md` has a **Prior Art** section documenting what existing solutions were researched. If it's missing or empty, **stop and tell the user** — planning without a build-vs-buy analysis produces plans that ignore cheaper alternatives.
@@ -50,16 +79,21 @@ Derive implementation tasks from approved Gherkin features and MADR decisions. T
 - If the decision was **hybrid** (adopt for part, build for part), ensure the boundary between adopted and custom code is clear in the tasks.
 
 **Read from grimoire docs (these replace codebase exploration):**
-- **`.grimoire/docs/<area>.md`** for each area the change touches — these contain: key files with responsibilities, reusable utilities (exact function names, file paths, line numbers), naming conventions, structural patterns, and "Where New Code Goes" guidance. This is the information that lets you write tasks with exact file paths without reading every source file.
+- **`.grimoire/docs/<area>.md`** for each area the change touches — these contain Purpose, Boundaries, Conventions (naming/structure), and "Where New Code Goes" guidance. For key files, exact symbols, reusable utilities (function names, file paths, line numbers), and call graphs, **query the graph** — `search_graph` / `get_code_snippet` / `get_architecture`. Area docs give you intent and placement; the graph gives you the live structure to write exact file paths and reuse existing code.
 - **`.grimoire/docs/data/schema.yml`** — the full data model: every table/collection, field types, relationships, indexes, and external API contracts with `source:` pointers to ORM code. Read this instead of reading individual model files.
 - **`.grimoire/docs/context.yml`** — the project's deployment environment, related services, infrastructure dependencies, CI/CD pipelines, and observability setup. Read this to understand deployment constraints (e.g., Lambda means no long-running processes, Kubernetes means you may need health check endpoints), cross-service boundaries (e.g., auth is handled by a sibling service, not this project), and infrastructure available at runtime (e.g., Redis is available for caching, RabbitMQ for async tasks).
-- **`.grimoire/docs/.snapshot.json`** `duplicates` section if present — existing clones in areas you're touching, so tasks consolidate rather than add more.
+- Existing duplication in areas you're touching — query codebase-memory-mcp (`search_graph` for similar functions) or run `grimoire health` (its config-driven `duplicates` metric) so tasks consolidate rather than add more clones.
 
 **Read proposed data changes:**
 - **`data.yml`** if present — proposed schema changes need migration and model tasks
 
+**Staleness gate:** For each area doc loaded, check its `last_updated` date against `git log -1 --format=%ci <directory>`. If any doc is older than the most recent commit to its directory, it's stale — the file paths, utility names, and patterns it describes may no longer be accurate.
+
+- **Level 1-2:** Warn ("Area doc for `<area>` is behind recent commits — its boundaries/conventions may be wrong; rely on the graph for structure") and proceed. Note inferred paths with `<!-- inferred: area doc may be stale -->`.
+- **Level 3-4:** Treat as a blocker. Do not generate tasks until the user refreshes stale docs via `grimoire-discover` targeted refresh. Planning with stale docs at this complexity produces wrong file paths and misses recent utilities — the cost of re-planning outweighs the cost of refreshing first.
+
 **Read specific source files only when:**
-- Area docs don't exist yet (tell the user to run `grimoire map` + `/grimoire:discover` first — planning without area docs produces worse tasks)
+- Area docs don't exist yet (tell the user to run `/grimoire:discover` first — planning without area docs produces worse tasks)
 - Area docs exist but you need to verify a specific implementation detail (e.g., exact function signature, exact import path)
 - You need to read existing step definitions to understand the test setup
 
@@ -69,41 +103,70 @@ Derive implementation tasks from approved Gherkin features and MADR decisions. T
 
 Before generating tasks, evaluate whether the specifications are detailed enough to plan against. Underspecified requirements produce vague tasks, which produce wrong code.
 
-Review the specs through each persona's lens and flag gaps. **Only check personas relevant to the change** — don't manufacture issues.
+**Flag real gaps only — do not manufacture issues to hit a checklist.** A "gap" exists when:
+- The spec contradicts itself (a scenario violates a non-goal; two scenarios disagree).
+- A scenario you need to plan against has missing detail you cannot infer from project conventions (e.g., "redirect to dashboard" — which dashboard URL?).
+- The manifest is missing a section the complexity level requires (Assumptions / Pre-Mortem / Prior Art on level 3-4).
+- A scenario references an external API or data model with no contract in `data.yml` / `schema.yml`.
+
+**Not a gap** (do not flag):
+- The spec doesn't include a scenario you personally would have added. The approved feature set is the scope. If you think a scenario is missing, see "Clarify or propose, never assume" in Operating Rules — propose it back to draft, do not silently add planning for it.
+- A negative path is unspecified but project conventions make it obvious (e.g., invalid input returns 400 — that's the framework default, not a spec gap).
+- A non-functional concern (perf, observability) is unspecified at level 1-2.
 
 #### Outcome & Scope check
 - Does the manifest have a clear **Why** that describes the outcome, not just the mechanism? ("Users can reset passwords" not "Add password reset endpoint.")
 - Does the manifest have a **Non-goals** section? If missing or empty on a level 3-4 change, flag it — without non-goals, scope creep is invisible during implementation.
 - Do any scenarios appear to implement something listed as a non-goal? Flag as **blocker** — the draft contradicts itself.
 
-Evaluate through each relevant persona's lens — see `../references/elicitation-personas.md` for the full question set. In plan, you're checking completeness, not asking questions. Flag gaps as issues.
+Persona lens (only those relevant to the change) — see `../references/elicitation-personas.md` for the full set:
+
+- **Outcome & Scope**: Why states outcome (not mechanism)? Non-goals exist? No scenario contradicts a non-goal?
+- **PM**: User stories present? Given/When/Then specific?
+- **Engineer**: Critical-path assumptions validated or flagged? Prior art documented (if building custom)?
+- **Security**: Scenarios with auth/input/sensitive-data tags have corresponding constraints? Quality Attribute targets not blank?
+- **Data**: External APIs or new models have `data.yml`? Constraints (required/unique/nullable) specified?
+- **QA**: Where the spec explicitly references an error path, is the expected behavior specified?
 
-**Key checks per persona:**
-- **Outcome & Scope**: Does the manifest have a clear Why (outcome, not mechanism)? Does it have Non-goals? Do any scenarios contradict non-goals?
-- **PM**: Scenarios for success AND errors? User stories on every feature? Specific Given/When/Then (not vague)?
-- **Engineer**: Unvalidated assumptions on critical path? Prior art patterns documented (if building custom)? Scenarios specific enough for concrete file paths?
-- **Security**: Input/auth/sensitive-data scenarios have corresponding error/abuse scenarios? Quality Attribute targets not blank?
-- **Data**: External APIs or new models without `data.yml`? Data constraints specified (required, unique, nullable)?
-- **QA**: Negative scenario for every happy path? Boundary values specified?
+**Response paths when a gap is found:**
 
-**If issues are found:**
+1. **Ambiguous** (the spec is contradictory or admits two readings) → ask the user one specific question. Do not pick a reading.
+2. **Missing scenario the planner believes is required** → propose adding it via `grimoire-draft`. State the rationale ("this feature handles money — failure-path behavior should be in the spec"). Do not silently add a planning task for it.
+3. **Missing detail derivable from conventions** → infer, plan, and annotate the task with `<!-- inferred: ... -->` so the user can override.
+4. **Missing manifest section the complexity level requires** → ask the user; flag as a gate for level 3-4.
 
-1. Present findings grouped by persona, with a specific question for each gap
-2. Ask the user to choose:
-   - **Clarify now** — answer the questions and update the draft before continuing to task generation
-   - **Proceed anyway** — acknowledge the gaps and plan around them (tasks will note where assumptions were made)
-   - **Return to draft** — go back to `grimoire-draft` to fill in the gaps
+If multiple gaps are found, batch them and present once. Wait for the user's response before generating tasks.
 
-This is not a gate — level 1-2 changes (from manifest `complexity`) can proceed with minor gaps. Level 3-4 changes with multiple signals should strongly recommend clarification before planning.
+Level 1-2 changes with minor gaps may proceed; level 3-4 with multiple gaps should not.
 
-**If no issues are found**, proceed directly to task generation.
+**If no real gaps**, proceed directly to task generation.
 
 ### 4. Generate Tasks
-Create `.grimoire/changes/<change-id>/tasks.md`. **Every scenario must produce both production code AND tests.** Tasks are structured as pairs: step definitions first, then production code.
+Create `.grimoire/changes/<change-id>/tasks.md`. **Every task produces both production code AND a test — but the test level matches the artifact the task derives from.** Tasks are structured as pairs: the failing test first, then the production code.
+
+**Tag every implementation task with a `verify:` level** — this tells `grimoire-apply` which test vehicle to use. Match the artifact:
+
+| Task derives from | `verify:` | Test vehicle |
+|-------------------|-----------|--------------|
+| a `.feature` scenario (actor-observable behavior) | `scenario` | step definitions + Gherkin |
+| a constraint in `constraints.md` (security/NFR/observability) | `unit-invariant` | unit/integration test asserting the invariant |
+| an ADR consequence, refactor, or internal change with no spec | `characterization` | unit / characterization test |
+
+**Do not plan a `.feature` scenario task for a constraint or an internal change.** Constraints get `unit-invariant` unit tests; internal changes get `characterization` tests. Forcing Gherkin onto a non-behavioral concern is the antipattern that fills feature files with slop (one right way: behavior → scenario, everything else → unit test).
+
+**THE PLAN'S SCOPE IS WHAT WAS APPROVED.** Tasks may only derive from:
+- `.feature` scenarios in this change → `verify: scenario`
+- Constraints added/touched in `.grimoire/docs/constraints.md` → `verify: unit-invariant`
+- ADRs in this change (and their Confirmation sections) → `verify: unit-invariant` or `characterization`
+- `data.yml` entries in this change
+- The manifest's Assumptions, Pre-Mortem mitigations, and Prior Art borrowings
+- Verification tasks (run feature suite, run project suite, validate ADR confirmation)
+
+Do not add tasks for scenarios you wish existed, edge cases you imagine, observability you'd like, or refactors you'd prefer. If you think one is needed, see Operating Rules §2 — propose, don't insert.
 
 **THE PLAN MUST RESPECT NON-GOALS.** Read the manifest's Non-goals section. If a task would touch, implement, or extend something listed as a non-goal, do not include it. If you think a non-goal should be reconsidered, flag it to the user — don't silently include it.
 
-**THE PLAN MUST BE SPECIFIC ENOUGH TO EXECUTE WITHOUT FURTHER PLANNING.**
+**THE PLAN MUST BE SPECIFIC ENOUGH TO EXECUTE WITHOUT FURTHER PLANNING.** Specific means *answered*, not *delegated*: file paths resolved (not "find the right file"), reusable utilities named with exact symbol + path (not "check if one exists"), import paths verified (not "confirm the import"). See Operating Rules §1.
 
 **THE PLAN MUST PREFER SIMPLICITY.** For each task, choose the approach with the least code, fewest new files, and smallest surface area. If a task can be solved by adding a few lines to an existing file, don't create a new module. If a standard library function does the job, don't pull in a dependency. If three lines of inline code are clearer than a helper, keep them inline. Flag any task that introduces a new abstraction, utility, or pattern — it needs a reason.
 
@@ -216,8 +279,8 @@ Follow the rules in `../references/testing-contracts.md`. Key points: mock at HT
 - If a library was rejected for a specific reason (e.g., doesn't support X), add a comment to the relevant task noting this so future developers don't re-evaluate the same option
 
 **Existing code to reuse:**
-- If `.grimoire/docs/` has area docs, check the Reusable Code tables for utilities that apply to this change
-- If the snapshot has duplicate data, check whether the area you're touching already has clones — tasks should consolidate rather than add more
+- Query the graph (`search_graph` by concept/name) for existing utilities that apply to this change; area docs give conventions, the graph gives the reusable symbols
+- If `grimoire health`/mcp shows existing clones in the area you're touching, tasks should consolidate rather than add more
 - Add a "Reuse" section at the top of tasks.md listing specific functions/classes to import instead of rewriting
 
 **Verification (always last):**
@@ -239,12 +302,12 @@ The tasks file starts with a context block so any LLM can orient without re-read
 
 ## 1. <Capability/Area>
 <!-- context:
-  - .grimoire/changes/<change-id>/features/<capability>/<name>.feature
+  - features/<name>.feature
   - .grimoire/docs/<area>.md
   - src/<area>/<file-to-edit>.ts
   - tests/<area>/<test-file>.ts
 -->
-- [ ] 1.1 Write step defs in `<exact path>` for scenario: "<scenario name>" in `<file>`
+- [ ] 1.1 (verify: scenario) Write step defs in `<exact path>` for scenario: "<scenario name>" in `features/<file>`
       - Given: <what the step does, what it calls>
       - When: <what the step does, what it calls>
       - Then: <what to assert — specific expected values/states>
@@ -252,32 +315,40 @@ The tasks file starts with a context block so any LLM can orient without re-read
       - <specific function/class/view to create or modify>
       - <specific behavior to implement>
       - <edge cases to handle>
-- [ ] 1.3 Write step defs in `<exact path>` for scenario: "<next scenario>"
-      ...
-- [ ] 1.4 Implement in `<exact path>`:
-      ...
 
-## 2. Shared Steps
+## 2. Constraints
+<!-- context:
+  - .grimoire/docs/constraints.md
+  - src/<area>/<file-to-edit>.ts
+  - tests/<area>/<unit-test-file>.ts
+-->
+- [ ] 2.1 (verify: unit-invariant) Write unit test in `<exact path>` asserting constraint: "<assertion from constraints.md>"
+      - Arrange: <setup>
+      - Assert: <the invariant — exact expected behavior, no Gherkin>
+- [ ] 2.2 Implement in `<exact path>`:
+      - <specific change that satisfies the invariant>
+
+## 3. Shared Steps
 <!-- context:
   - tests/step_defs/common.py
-  - .grimoire/changes/<change-id>/features/<all relevant .feature files>
+  - features/<all relevant .feature files>
 -->
-- [ ] 2.1 Add to `<exact path>`:
+- [ ] 3.1 Add to `<exact path>`:
       - Given "<step text>": <what it does>
       - Given "<step text>": <what it does>
 
-## 3. Architecture
+## 4. Architecture
 <!-- context:
-  - .grimoire/changes/<change-id>/decisions/<nnnn-title>.md
+  - .grimoire/decisions/<nnnn-title>.md
   - src/<files affected by decision>
 -->
-- [ ] 3.1 In `<exact path>`: <specific change from ADR>
-- [ ] 3.2 Add test in `<exact path>`: <ADR confirmation check — what to assert>
+- [ ] 4.1 (verify: characterization) In `<exact path>`: <specific change from ADR>
+- [ ] 4.2 Add test in `<exact path>`: <ADR confirmation check — what to assert>
 
-## 4. Verification
-- [ ] 4.1 Run `<exact test command>` — all new scenarios green
-- [ ] 4.2 Run `<exact test command>` — no regressions
-- [ ] 4.3 Run `<exact test command>` — full project suite
+## 5. Verification
+- [ ] 5.1 Run `<exact test command>` — all new scenarios green
+- [ ] 5.2 Run `<exact test command>` — no regressions
+- [ ] 5.3 Run `<exact test command>` — full project suite
 ```
 
 **Context blocks are mandatory.** Every task section (except Verification) must have a `<!-- context: ... -->` listing the files needed. This serves two purposes:
@@ -287,11 +358,13 @@ The tasks file starts with a context block so any LLM can orient without re-read
 ### 6. Quality Check
 Before presenting to the user, verify the plan:
 - [ ] Every task references a specific file path (no "implement the feature")
-- [ ] Every step definition task describes what to assert (no "write a test")
+- [ ] Every implementation task carries a `verify:` tag matching its source artifact — `scenario` only for `.feature` behavior; `unit-invariant` for constraints; `characterization` for internal/refactor. No `.feature` scenario task for a constraint or internal change.
+- [ ] Every test task describes what to assert (no "write a test")
 - [ ] Every implementation task describes what to create/modify (no "add the code")
 - [ ] The verification section has the exact commands to run
-- [ ] Tasks are ordered: shared steps → step defs → production code → verification
+- [ ] Tasks are ordered: shared steps → test → production code → verification
 - [ ] No task requires the LLM to make architectural decisions — those should already be in the ADR
+- [ ] **Principles gate** (`../references/principles.md`): no task introduces a duplicate home for an existing fact (DRY), a second way to do an existing thing (one right way), a reinvented wheel where a tool/library/proven pattern exists (don't reinvent), or an abstraction/dependency justified only by a hypothetical (KISS). Any that does has a stated reason.
 
 If any task is too vague, make it more specific before presenting. Read more codebase if needed.
 

package/skills/grimoire-pr/SKILL.md

@@ -17,16 +17,14 @@ Generate a pull request description from grimoire change artifacts and optionall
 - Loose match: "PR", "pull request", "ready to merge", "create PR"
 
 ## Routing
-- Tasks incomplete → `grimoire-apply` first (or create a draft PR)
+- Tasks incomplete or finalize not done → `grimoire-apply` first. Do not create a PR before the change is finalized — the PR reflects the finished branch state (decisions accepted, change folder removed).
 - Haven't committed yet → `grimoire-commit` first
 - Want a pre-merge design review → this skill includes optional post-implementation review
 
 ## Prerequisites
-- A change exists in `.grimoire/changes/<change-id>/` with:
-  - `manifest.md`
-  - `tasks.md` with all (or most) tasks checked
-  - Feature files and/or decision records
-- The change should be on a feature branch (created during apply)
+- Change has been finalized: `.grimoire/changes/<change-id>/` is removed (manifest/tasks were ephemeral scaffolding)
+- Decision records are live in `.grimoire/decisions/` with status `accepted`
+- The change is on a feature branch (created during draft/apply); its diff vs. `main` is the change
 
 ## Workflow
 
@@ -119,9 +117,8 @@ Check that the branch is pushed to the remote before creating. If not, offer to
 
 ### 6. Link Back
 After PR creation:
-- Update manifest's status to `complete` if not already
-- Add the PR URL to the manifest as a comment or field
-- Suggest running `grimoire archive <change-id>` to complete the lifecycle
+- The `Change: <change-id>` trailer on the commits links them to the change; the PR body + git log are the durable record (the change folder was already removed at finalize).
+- Suggest merging the PR to complete the change. There is no archive step — git history is the history.
 
 ## Important
 - The PR description must trace back to grimoire artifacts — this is what makes the audit trail work.
@@ -131,4 +128,4 @@ After PR creation:
 - If tasks are incomplete, warn the user but don't block PR creation — they may want a draft PR.
 
 ## Done
-When the PR is created (or description is presented for manual creation), the workflow is complete. Suggest `grimoire archive <change-id>` to complete the lifecycle.
+When the PR is created (or description is presented for manual creation), the workflow is complete. Suggest merging the PR to complete the change — git history + the `Change:` trailer are the record; there is no separate archive step.

package/skills/grimoire-pr-review/SKILL.md

@@ -1,15 +1,15 @@
 ---
 name: grimoire-pr-review
-description: Review a teammate's pull request using the same multi-persona lens as pre-commit review, but against the actual diff. Fetches the PR, loads linked grimoire artifacts via the Change trailer, and produces structured findings suitable for PR comments.
+description: Review a teammate's pull request using the shared multi-persona engine, against the actual PR diff. Fetches the PR, loads linked grimoire artifacts via the Change trailer, and produces structured findings suitable for PR comments.
 compatibility: Designed for Claude Code (or similar products)
 metadata:
   author: kiwi-data
-  version: "0.1"
+  version: "0.2"
 ---
 
 # grimoire-pr-review
 
-Review a pull request authored by someone else. Applies the same persona lens as `grimoire-review` (product, engineer, security, QA, data) to the real diff, cross-referenced with the PR's linked grimoire change (if any).
+Review a pull request authored by someone else. Applies the shared persona engine in `../references/review-personas.md` to the real diff, cross-referenced with the PR's linked grimoire change (if any).
 
 ## Triggers
 - User asks to review a teammate's PR / MR
@@ -18,6 +18,7 @@ Review a pull request authored by someone else. Applies the same persona lens as
 
 ## Routing
 - Reviewing your own pre-merge change you just built → `grimoire-pr` (has optional post-impl review)
+- Reviewing your own staged but uncommitted diff → `grimoire-precommit-review`
 - Reviewing a design before any code exists → `grimoire-review`
 - Verifying scenarios pass after merge → `grimoire-verify`
 - Writing a bug report against merged behavior → `grimoire-bug-report`
@@ -63,111 +64,43 @@ git log <base>..<head> --format="%B" | grep -E "^Change:"
 
 If present:
 - Change ID = trailer value
-- Load artifacts: first check `.grimoire/changes/<change-id>/` (in-progress), then `.grimoire/archive/*<change-id>*/` (archived). Try the PR's head branch checked out locally if needed.
+- Load artifacts: check `.grimoire/changes/<change-id>/` for an active change. If the change is already finalized/merged the change folder is gone — read the artifacts from the PR's head branch (`git diff main` shows the live `features/`, `.grimoire/decisions/`, `.grimoire/docs/constraints.md`) and use the `Change:` trailer to correlate commits.
 - Read `manifest.md`, all `.feature` files in the change, decision records, `tasks.md`, `data.yml`
 - Also grep for `Scenarios:` and `Decisions:` trailers to scope review to the named items
 
 If no `Change:` trailer exists, that's itself a finding for a grimoire-managed repo: flag as **suggestion** ("commits missing audit trailer — `grimoire trace` won't find this PR") unless the project clearly doesn't use grimoire.
 
 ### 4. Gather Project Context
-- `.grimoire/config.yaml` — language, tools, `commit_style`, `project.compliance`, `dep_audit`
+- `.grimoire/config.yaml` — language, tools, `commit_style`, `comment_style`, `project.compliance`, `dep_audit`
 - `.grimoire/docs/context.yml` — deployment environment, related services
 - `.grimoire/docs/data/schema.yml` — current data baseline
 - Relevant `.grimoire/docs/<area>.md` for the directories touched by the diff
 
-### 5. Complexity-Gated Depth
-Read `complexity` from the linked manifest frontmatter if available. Fall back to heuristics on the diff:
+### 5. Build Project Briefing
+Follow `../references/review-personas.md` §1 (Project Briefing) to construct the briefing block. Inject as preface to every persona run below.
 
-| Signal | Depth |
-|---|---|
-| Docs only, ≤50 lines | Senior engineer skim only |
-| Linked manifest complexity 1-2, diff <200 lines, no security tags | Senior engineer + security quick scan |
-| Linked manifest complexity 3, OR diff touches auth/data/API | All relevant personas (skip data if no schema change, skip QA if no user-facing change) |
-| Linked manifest complexity 4, OR diff >500 lines, OR touches multiple domains | All personas mandatory |
+### 6. Pick Personas — Diff Review Gating
+Use the **Diff review** table in `../references/review-personas.md` §3 (Complexity Gating). Read `complexity` from the linked manifest if present; otherwise infer from diff size and touched areas. User can override ("full review", "just security", "just code style", etc.).
 
-User can override: "full review", "just security", "just engineer", etc.
+### 7. Run Personas
+For each selected persona, follow its evaluation criteria in `../references/review-personas.md` §4 against the **PR diff** (with linked artifacts as cross-reference where relevant). Apply the materiality gate (§2) — every finding cites a briefing axis or feature-inventory gap, or is dropped.
 
-### 6. Product Manager Review
-*(Skip if PR is pure internal refactor with no user-facing change.)*
+Persona scope for PR review:
+- 4.1 Product Manager — skip if pure internal refactor
+- 4.2 Senior Engineer — always
+- 4.3 Security Engineer — always; full STRIDE + code-level scan + compliance
+- 4.4 QA Engineer — skip if pure internal
+- 4.5 Data Engineer — skip if no migrations / models / schema / external API client touched
+- 4.6 Code Style Reviewer — always
+- 4.7 Adversarial User — engage per matrix in `../references/adversarial-personas.md` when the diff touches a user-facing surface
+- 4.8 Contrarian — runs last when any persona produced a blocker; calibrates other personas' findings post-hoc
 
-Evaluate against the linked feature files (if any) or the PR body:
+### 7.5 Visual Fidelity (cheap tier)
 
-- **Scenario coverage**: If a feature file exists in the change, does the diff implement every scenario? Any scenario with no matching code change?
-- **Non-goals**: Does the diff touch anything the manifest's Non-goals section excludes?
-- **Acceptance**: From the diff alone, could a PM validate this meets the feature's acceptance criteria?
-- **Clarity**: Does the PR body (or linked manifest) make the user-visible outcome clear?
+Follow `../references/visual-fidelity.md` for the code-phase invocation (PR diff scope, auto-invoked when `.grimoire/brand/tokens.json` exists). Skip silently when tokens.json is absent and the diff has no styling-surface changes. Fold the engine's output under the "Visual Fidelity" section of the report.
 
-Flag as **blocker** or **suggestion**.
-
-### 7. Senior Engineer Review
-Review the actual code:
-
-- **Simplicity**: Is this the simplest implementation? Any unnecessary abstraction, indirection, or config that could be inlined?
-- **Conventions**: Does the new code match the file layout, naming, and patterns already in the touched areas? Check `.grimoire/docs/<area>.md` if present.
-- **Reuse**: Are there existing utilities/functions that were re-implemented? `grep` for similar names or check the area doc's reusable-code list.
-- **Dead code**: Functions added but not called, imports unused, commented-out code, stubs with no implementation.
-- **Scope creep**: Files changed outside the scope implied by the change-id or manifest. Formatting-only changes to unrelated files = noise.
-- **Error handling**: Are errors handled at boundaries? Internal code shouldn't be littered with defensive checks; external inputs must be validated.
-- **Tests**: Do new behaviors have tests? Do the tests make real assertions (not just `assert true` / mock everything)? Check `../references/testing-contracts.md` if the framework matches.
-- **Contract compatibility**: If `data.yml` / `schema.yml` exists, does the diff change request/response shape for a documented API? If yes, where's the contract test update?
-- **Dependencies**: Any new packages in `package.json` / `requirements.txt` / `Cargo.toml` etc. not mentioned in tasks? Any version bumps that aren't noted?
-- **Task alignment**: If `tasks.md` exists for the change, does the diff complete the tasks as written? Any task that was "done" but has no corresponding code?
-
-Flag as **blocker** or **suggestion**.
-
-### 8. Security Engineer Review
-Apply `../references/security-compliance.md`.
-
-#### 8a. STRIDE on the diff
-For every new entry point, data flow, or trust boundary introduced by the diff:
-
-| Threat | Question |
-|---|---|
-| **S**poofing | Auth check at every new route/handler? |
-| **T**ampering | Input/message integrity validated? CSRF on state-changing requests? |
-| **R**epudiation | Security-relevant actions logged? |
-| **I**nfo disclosure | Error responses, logs, stack traces leaking PII/tokens/secrets? |
-| **D**oS | Unbounded loops, unlimited file uploads, expensive queries on user input, no rate limit? |
-| **E**oP | Role/permission checks at the right layer? Any bypass via missing middleware? |
-
-Skip categories that don't apply.
-
-#### 8b. Code-level scan
-- **Secrets**: Grep the diff for hardcoded keys, tokens, passwords, cloud credentials, JWT secrets. Flag any hit as **blocker**.
-- **Injection**: Raw SQL with string concatenation, shell-exec with user input, `eval`/`exec`, unsafe deserialization. Tag with OWASP + CWE.
-- **Input validation**: New endpoints without schema validation, file uploads without size/type limits, path params used directly in filesystem calls (path traversal).
-- **Auth**: New routes/handlers missing auth decorators / middleware. Compare against neighbors in the same file.
-- **Dependencies**: New packages in lockfile — check the name is real (typosquat risk), check project's `dep_audit` tool output if committed. Flag packages with zero downloads or suspicious maintainers.
-- **PII**: New logging statements that could emit PII; new storage of personal data without encryption.
-- **Cross-service auth**: If `context.yml` lists related services, are service-to-service calls authenticated?
-
-#### 8c. Compliance
-If `project.compliance` configured, verify per `../references/security-compliance.md` section "Compliance Framework Verification". Any security-tagged scenario in the linked change with no corresponding verification in the diff = **blocker**.
-
-#### 8d. Tag findings
-Every security finding gets OWASP 2021 + CWE tags. See the CWE quick-reference in `../references/security-compliance.md`.
-
-### 9. QA Engineer Review (optional)
-Skip if PR is purely internal.
-
-- **Test presence**: Every new user-facing behavior has a test? Every scenario from the linked feature file has step definitions?
-- **Test quality**: Are tests asserting outputs, or just that code "ran"? Over-mocked tests are a red flag.
-- **Negative paths**: For each happy path in the diff, is there a failure-path test?
-- **Observability**: New feature — how will it be debugged in prod? Structured logs / metrics / error surfaces?
-- **Regression risk**: Which existing tests cover the touched code? Were any tests removed or weakened in the diff?
-- **Accessibility**: New UI — keyboard nav, aria labels, contrast?
-
-### 10. Data Engineer Review (optional)
-Skip unless diff touches migrations, models, schema files, or external API clients.
-
-- **Migrations**: Safe to run on a live DB? Adding a NOT NULL without default on a large table = **blocker**. Renames without a two-step migration = **blocker**.
-- **Indexes**: New foreign keys with no index? New query patterns against unindexed columns?
-- **Naming**: New fields follow existing schema conventions?
-- **Breaking contract**: Compare `data.yml` vs `schema.yml` — removed/renamed/retyped response fields or new required request fields = **blocker** unless a migration path is documented.
-- **Transactions**: Multi-step writes wrapped in a transaction?
-
-### 11. Present Findings
-Compile into a single report structured for PR comments:
+### 8. Present Findings
+Compile into the standard report layout (§5 of the personas reference):
 
 ```markdown
 # PR Review: <PR title> (#<number>)
@@ -177,41 +110,38 @@ Compile into a single report structured for PR comments:
 **Complexity:** <1-4 or "inferred: moderate">
 **Files changed:** <N>  **Lines:** +<add> / -<del>
 
+## Project Briefing
+<briefing block>
+
 ## Product Manager
-- **[blocker]** Scenario "Login with expired TOTP code" is in the feature file but no corresponding code path in `auth/verify.py`
-- **[suggestion]** PR body doesn't mention the rate-limit change — add it
+- ...
 
 ## Senior Engineer
-- **[blocker]** `utils/hash_helpers.py` duplicates `security/crypto.py::hash_password` — reuse instead
-- **[suggestion]** New abstraction `AuthProviderFactory` has one caller; inline it
+- ...
 
 ## Security Engineer
 ### STRIDE
-- Spoofing: N/A
-- Tampering: new `/api/profile` PATCH has no CSRF token check
-- Info disclosure: `logger.info(f"login attempt for {email}")` emits PII
-
+- ...
 ### Findings
-- **[blocker]** [A01:2021 / CWE-352] Missing CSRF check on `/api/profile` PATCH (`views/profile.py:42`)
-- **[blocker]** [A09:2021 / CWE-532] Email logged in plaintext (`auth/login.py:88`)
-- **[suggestion]** [A07:2021 / CWE-307] No rate limiting on login handler
+- ...
 
 ## QA Engineer
-- **[blocker]** New TOTP verification path has no test (`auth/totp.py:15-48`)
-- **[suggestion]** Add negative test for malformed TOTP string
+- ...
 
 ## Data Engineer
-- **[blocker]** Migration `0042_add_2fa.py` adds NOT NULL `totp_secret` on existing `users` table — will fail on deploy
-(or: "No schema changes — skipped.")
+- ...
+
+## Code Style
+- ...
 
 ## Summary
-- **5 blockers** — must be addressed before merge
-- **3 suggestions** — consider addressing
+- **N blockers** — must be addressed before merge
+- **M suggestions** — consider addressing
 
-Recommendation: Request changes.
+Recommendation: Request changes / Approve.
 ```
 
-### 12. Post to PR (optional)
+### 9. Post to PR (optional)
 Offer three modes:
 
 - **Print only** (default) — just show the report
@@ -224,17 +154,18 @@ Offer three modes:
 
 Ask the user which mode before posting. Never post without confirmation — PR comments are visible to the whole team.
 
-### 13. Link Back
+### 10. Link Back
 If a linked grimoire change was found and the review surfaced blockers that need spec changes (not just code changes), suggest the author run `grimoire-draft` or `grimoire-plan` on that change to update the artifacts before pushing fixes.
 
 ## Important
 - This is a code review against a real diff — reference specific files and line numbers for every finding.
-- Be direct. Don't pad with praise. Blockers are things that should stop the merge; suggestions are things the author should consider.
-- Respect the author. Findings describe the code, not the person. "This query is vulnerable to injection" not "you wrote an injection".
-- A PR without a `Change:` trailer in a grimoire repo is a soft finding, not a hard blocker — the team may have reasons.
+- Be direct. Don't pad with praise. Blockers stop the merge; suggestions are advisory.
+- Respect the author. Findings describe the code, not the person.
+- A PR without a `Change:` trailer in a grimoire repo is a soft finding, not a hard blocker.
 - Don't re-derive tasks or specs. If the linked change's artifacts are wrong, that's a separate `grimoire-draft` / `grimoire-plan` cycle.
 - If the diff is too large or too sprawling to review meaningfully, say so — offer to focus on a subset rather than producing a shallow full-pass review.
 - Never post to the PR without explicit user confirmation.
+- All persona evaluation criteria, the materiality gate, the briefing structure, and the complexity-depth table live in `../references/review-personas.md`. Don't duplicate them here — read that file when running a persona.
 
 ## Done
 When the report is presented (and optionally posted), the workflow is complete. If blockers exist, suggest the author address them; if not, suggest approving via `gh pr review <id> --approve`.