@kiwidata/grimoire 0.1.3 → 0.1.4

package/skills/grimoire-draft/SKILL.md

@@ -35,7 +35,7 @@ Before doing anything, determine what kind of change this is:
 - **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.
 
-If unclear, ask the user one clarifying question to route correctly.
+If unclear, ask the user one clarifying question to route correctly. **Do not guess the routing and proceed.** A wrong routing wastes both your context and the user's time — one question costs less.
 
 ### 2. Score Complexity
 
@@ -63,7 +63,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 +87,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,6 +113,7 @@ 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-`)
@@ -89,7 +121,44 @@ Present a Requirements Summary (template in the reference) and wait for user con
 
 ### 7. Draft Artifacts
 **For behavioral changes:**
-- Write proposed `.feature` files in `.grimoire/changes/<change-id>/features/<capability>/`
+
+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**
+
+- **Extend:** copy the matching baseline file to `.grimoire/changes/<change-id>/features/<same-relative-path>/` and add scenarios there.
+- **New file (requires justification):** state which existing files were considered and why none fit. Then create `.grimoire/changes/<change-id>/features/<capability>/<name>.feature`.
+
+Signals a scenario belongs in an existing file: same actor, same domain object, same entry point, same HTTP resource or screen.
+Signals a genuinely new file: new actor type with no existing file, entirely new domain object, or existing file's Feature title would need "and" to cover both.
+
 - If modifying an existing feature, copy the current baseline first, then modify
 - Follow Gherkin best practices:
   - Feature title + user story (As a / I want / So that)
@@ -98,6 +167,19 @@ 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>/features/`, do NOT re-propose them; treat them as the baseline 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.
 
@@ -195,6 +277,7 @@ This is the contract. Downstream skills (plan, review, verify) use it to generat
 - Features describe behavior, not implementation. If you catch yourself writing step-level implementation details, you've gone too far.
 - 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:

package/skills/grimoire-plan/SKILL.md

@@ -28,6 +28,26 @@ 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`), `.grimoire/docs/<area>.md` reusable-code tables, `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.
+
 ### 1. Select Change
 - List active changes in `.grimoire/changes/`
 - If multiple, ask user which one to plan
@@ -58,6 +78,11 @@ Derive implementation tasks from approved Gherkin features and MADR decisions. T
 **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 — reusable utilities and file paths may be wrong") 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 exist but you need to verify a specific implementation detail (e.g., exact function signature, exact import path)
@@ -69,41 +94,59 @@ 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:
 
-**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?
+- **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?
 
-**If issues are found:**
+**Response paths when a gap is found:**
 
-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
+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.
 
-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.
+If multiple gaps are found, batch them and present once. Wait for the user's response before generating tasks.
 
-**If no issues are found**, proceed directly to task generation.
+Level 1-2 changes with minor gaps may proceed; level 3-4 with multiple gaps should not.
+
+**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.
 
+**THE PLAN'S SCOPE IS WHAT WAS APPROVED.** Tasks may only derive from:
+- Approved `.feature` scenarios in this change
+- Approved ADRs in this change (and their Confirmation sections)
+- `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.
 

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 — PR must reflect the archived state (decisions promoted, manifest archived, change directory 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 is in `.grimoire/archive/`
+- All decisions promoted to `.grimoire/decisions/`
+- The change is on a feature branch (created during apply)
 
 ## Workflow
 

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`
@@ -70,104 +71,36 @@ If present:
 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`.