wizz-method 2.1.1 → 2.2.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "wizz-method",
-  "version": "2.1.1",
+  "version": "2.2.0",
   "description": "Wizz Method: método de agência orientado por IA em PT-BR",
   "keywords": [
     "agile",

package/src/bmm-skills/4-implementation/wizz-code-review/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: wizz-code-review
-description: 'Review code changes adversarially using parallel review layers (Blind Hunter, Edge Case Hunter, Verification Gap Reviewer, Acceptance Auditor) with structured triage into actionable categories. Use when the user says "run code review" or "review this code"'
+description: 'Adversarial code review in Forte-tier layers that scale with diff size, with triage into actionable categories. Use when the user says "run code review" or "review this code"'
 ---
 
 # Code Review Workflow
 
-> **Cross-reference:** this is the orchestrator. It gathers context, runs the review layers declared in `customize.toml` (Blind Hunter, Edge Case Hunter, Verification Gap Reviewer, Acceptance Auditor) as parallel context-free subagents driven by the prompt files under `review-prompts/`, then verifies, triages and presents findings by severity. Use it for a real diff/PR review. For a quick single-pass adversarial read with no workflow overhead, use `wizz-adversarial-reviewer` directly instead.
+> **Cross-reference:** this is the orchestrator. It gathers context, deterministically cleans the diff and picks a tier by its size, runs the review layers declared in `customize.toml` (Blind Hunter, Edge Case Hunter, Verification Gap Reviewer, Acceptance Auditor) as parallel context-free subagents — 1, 2 or up to 4 Forte-tier subagents depending on the tier — driven by the prompt files under `review-prompts/`, then verifies, triages on the Forte tier and presents findings by severity. Use it for a real diff/PR review. For a quick single-pass adversarial read with no workflow overhead, use `wizz-adversarial-reviewer` directly instead.
 
 **Goal:** Review code changes adversarially. No noise, no filler.
 

package/src/bmm-skills/4-implementation/wizz-code-review/customize.toml

@@ -40,22 +40,104 @@ persistent_facts = [
 
 on_complete = ""
 
+# Git pathspec globs to exclude from the diff. See references/review-economy.md
+# § 1. This is a plain array, so a team/user override entry is APPENDED to the
+# defaults below (per the merge rules above) — the defaults can never be
+# removed by an override, only added to.
+
+review_exclude = [
+  "**/package-lock.json",
+  "**/npm-shrinkwrap.json",
+  "**/yarn.lock",
+  "**/pnpm-lock.yaml",
+  "**/bun.lock",
+  "**/bun.lockb",
+  "**/Cargo.lock",
+  "**/poetry.lock",
+  "**/Pipfile.lock",
+  "**/Gemfile.lock",
+  "**/composer.lock",
+  "**/go.sum",
+  "**/uv.lock",
+  "**/__snapshots__/**",
+  "**/*.snap",
+  "**/*.min.js",
+  "**/*.min.css",
+  "**/*.js.map",
+  "**/*.css.map",
+]
+
+# Plain-language sensitive areas the session judges the diff against to
+# decide the `critical` tier — not patterns, guidance for the session's own
+# reading of the changed files. See references/review-economy.md § 2.
+
+review_critical_paths = [
+  "authentication",
+  "sessions",
+  "passwords and credentials",
+  "authorization",
+  "permissions and RLS",
+  "payments, billing and checkout",
+  "database migrations, schema and SQL",
+  "secrets, keys and .env files",
+  "cryptography",
+  "CI and deploy workflows",
+]
+
 # Review layers for the review step. `instruction` is the layer's whole
 # execution recipe — subagents by default, but an override may run anything
-# (e.g. an external reviewer via bash). {diff_file} and {spec_file} are
-# substituted at run time; both are paths, and {diff_file} is the unified
-# diff file the layer reads. `when` (optional) gates a layer; empty
-# `instruction` disables it.
+# (e.g. an external reviewer via bash). Layers read `{clean_diff_file}`, the
+# deterministically cleaned diff. The step substitutes `{clean_diff_file}`,
+# `{diff_file}`, `{claims_file}`, `{spec_file}` and `{max_calls}` at run
+# time. `{review_mode}` is never substituted into instruction text — it only
+# gates a layer's `when` condition (see the Acceptance Auditor layer below).
+# Optional `tiers` (a list of `small`/`normal`/`critical`) gates a layer by
+# diff size — absent means every tier. `max_calls` caps the layer's tool
+# calls; at the cap the layer stops and its final message ends with a
+# `PARTIAL:` line. See `references/review-economy.md`. `when` (optional)
+# gates a layer; empty `instruction` disables it.
+#
+# This is an array of tables keyed by `id`: an override entry with the same
+# `id` as one below REPLACES that whole layer, it does not merge field by
+# field. An override that only means to change one field (e.g. `max_calls`)
+# must still restate `tiers` and `max_calls` in full, or the layer loses
+# whichever of those two it did not restate.
+
+[[workflow.review_layers]]
+id = "blind-verification"
+name = "Blind Hunter + Verification Gap"
+tiers = ["small", "normal"]
+max_calls = 35
+instruction = """
+Launch a context-free `wizz-exec-review` subagent with this prompt — pinned to the platform's Forte tier (`opus` in Claude Code), never inheriting the session model. Tell the user the tier and count of this dispatch.
+
+You run two review passes in order, and each pass follows its own instruction file.
+
+Pass 1, Blind Hunter: read `{skill-root}/review-prompts/blind-hunter.md` completely and follow it against the review content alone. Do not open any other file during this pass. In this combined layer the minimum-issue count in blind-hunter.md does not apply: report only real issues. Write its findings under a `## Blind Hunter` heading.
+
+Pass 2, Verification Gap: only after pass 1 is written, read `{skill-root}/review-prompts/verification-gap.md` completely and follow it. Write its output under a `## Verification Gap` heading.
+
+Review content: the unified diff at `{clean_diff_file}`. Read that file — it is the content under review.
+
+max_calls: {max_calls}. At the cap, stop and return what you have, ending with a final line `PARTIAL: <what you did not cover>`.
+
+Do not invoke any skill, and do not spawn subagents of your own — you are the reviewer. If `blind-hunter.md` is unreadable, report that exact failure and stop. If `verification-gap.md` is unreadable, keep the Blind Hunter output you already wrote and end with a final line `PARTIAL: verification-gap pass not run` instead of stopping empty. Return your findings as text in your final message; do not route them through any findings-reporting tool the host may offer.
+
+"""
 
 [[workflow.review_layers]]
 id = "blind-hunter"
 name = "Blind Hunter"
+tiers = ["critical"]
+max_calls = 20
 instruction = """
 Launch a context-free `wizz-exec-review` subagent with this prompt — pinned to the platform's Forte tier (`opus` in Claude Code), never inheriting the session model. Tell the user the tier and count of this dispatch.
 
 Read `{skill-root}/review-prompts/blind-hunter.md` completely and follow it as your review instructions.
 
-Review content: the unified diff at `{diff_file}`. Read that file — it is the content under review.
+Review content: the unified diff at `{clean_diff_file}`. Read that file — it is the content under review.
+
+max_calls: {max_calls}. At the cap, stop and return what you have, ending with a final line `PARTIAL: <what you did not cover>`.
 
 Do not invoke any skill, and do not spawn subagents of your own — you are the reviewer. If the instruction file is unreadable, report that exact failure and stop. Return your findings as text in your final message; do not route them through any findings-reporting tool the host may offer.
 
@@ -64,6 +146,8 @@ Do not invoke any skill, and do not spawn subagents of your own — you are the
 [[workflow.review_layers]]
 id = "edge-case-hunter"
 name = "Edge Case Hunter"
+tiers = ["normal", "critical"]
+max_calls = 25
 instruction = """
 Launch a context-free `wizz-exec-review` subagent with this prompt — pinned to the platform's Forte tier (`opus` in Claude Code), never inheriting the session model. Tell the user the tier and count of this dispatch.
 
@@ -71,7 +155,9 @@ Read `{skill-root}/review-prompts/edge-case-hunter.md` completely and follow it
 
 claims_file (leave unread until your instructions call for it): {claims_file}
 
-Review content: the unified diff at `{diff_file}`. Read that file — it is the content under review.
+Review content: the unified diff at `{clean_diff_file}`. Read that file — it is the content under review.
+
+max_calls: {max_calls}. At the cap, stop and return what you have, ending with a final line `PARTIAL: <what you did not cover>`.
 
 Do not invoke any skill, and do not spawn subagents of your own — you are the reviewer. If the instruction file is unreadable, report that exact failure and stop. Return your findings as text in your final message; do not route them through any findings-reporting tool the host may offer.
 
@@ -80,12 +166,16 @@ Do not invoke any skill, and do not spawn subagents of your own — you are the
 [[workflow.review_layers]]
 id = "verification-gap"
 name = "Verification Gap Reviewer"
+tiers = ["critical"]
+max_calls = 25
 instruction = """
 Launch a context-free `wizz-exec-review` subagent with this prompt — pinned to the platform's Forte tier (`opus` in Claude Code), never inheriting the session model. Tell the user the tier and count of this dispatch.
 
 Read `{skill-root}/review-prompts/verification-gap.md` completely and follow it as your review instructions.
 
-Review content: the unified diff at `{diff_file}`. Read that file — it is the content under review.
+Review content: the unified diff at `{clean_diff_file}`. Read that file — it is the content under review.
+
+max_calls: {max_calls}. At the cap, stop and return what you have, ending with a final line `PARTIAL: <what you did not cover>`.
 
 Do not invoke any skill, and do not spawn subagents of your own — you are the reviewer. If the instruction file is unreadable, report that exact failure and stop. Return your findings as text in your final message; do not route them through any findings-reporting tool the host may offer.
 
@@ -94,13 +184,17 @@ Do not invoke any skill, and do not spawn subagents of your own — you are the
 [[workflow.review_layers]]
 id = "acceptance-auditor"
 name = "Acceptance Auditor"
+tiers = ["critical"]
+max_calls = 15
 when = 'Only when {review_mode} = "full".'
 instruction = """
 Launch a `wizz-exec-review` subagent with this prompt — pinned to the platform's Forte tier (`opus` in Claude Code), never inheriting the session model. Tell the user the tier and count of this dispatch.
 
 You are an Acceptance Auditor. Review the provided diff against `{spec_file}` and any loaded context docs. Check for: violations of acceptance criteria, deviations from spec intent, missing implementation of specified behavior, contradictions between spec constraints and actual code. Output findings as a Markdown list. Each finding: one-line title, which AC/constraint it violates, and evidence from the diff.
 
-Diff: the unified diff at `{diff_file}`. Read that file — it is the content under review.
+Diff: the unified diff at `{clean_diff_file}`. Read that file — it is the content under review.
+
+max_calls: {max_calls}. At the cap, stop and return what you have, ending with a final line `PARTIAL: <what you did not cover>`.
 
 Do not invoke any skill, and do not spawn subagents of your own — you are the reviewer. Return your findings as text in your final message; do not route them through any findings-reporting tool the host may offer.
 

package/src/bmm-skills/4-implementation/wizz-code-review/references/review-economy.md

@@ -0,0 +1,75 @@
+# Review Economy
+
+Shared rules that keep the review layers on the Forte tier (`opus` in Claude Code) while cutting what they read and how many of them run. Two byte-identical copies live in `wizz-code-review/references/review-economy.md` and `wizz-quick-dev/references/review-economy.md`. Diffs are built with plain git commands; the tier is picked by session judgment.
+
+## 1. Build the diff
+
+Every diff command here runs against the repository root, never a bare `.`: compute `TOP="$(git rev-parse --show-toplevel)"` once, then run every git command as `git -C "$TOP" ...`. Every flag goes before the `--`: `--no-ext-diff --no-color --no-textconv`. `{diff_file}` and `{clean_diff_file}` are written by the identical command for a given source — same flags, same source args — differing only in the pathspecs that follow the single `--`.
+
+- **Pathspecs.** Positive pathspecs come first, always: `:(top)` for the whole tree, or one `:(top,literal)<path>` per path for a file-list or chunked source. `{clean_diff_file}` then adds exclude pathspecs after the positive ones — one `:(top,exclude,glob)<pattern>` per `{workflow.review_exclude}` entry (`wizz-quick-dev` adds `:(top,exclude,literal)<repo-relative spec path>` first — see "Spec path" below). `{diff_file}` never carries an exclude pathspec.
+- **Per-source command.** `git -C "$TOP" diff <source-args> --no-ext-diff --no-color --no-textconv -- <pathspecs>`, where `<source-args>` is:
+  | Source | `<source-args>` |
+  |---|---|
+  | Staged changes only | `--cached` |
+  | Uncommitted changes (staged + unstaged) | `HEAD` |
+  | Branch diff | `<base-branch>...HEAD` — only after `git -C "$TOP" merge-base <base-branch> HEAD` has already succeeded |
+  | Commit range | `<range>` |
+  | File list / chunk | `HEAD`, with `:(top,literal)<path>` positive pathspecs, one per listed or chunked path |
+- **Exclusions.** `{workflow.review_exclude}` is a list of git pathspec globs. The default in `customize.toml`:
+  `**/package-lock.json`, `**/npm-shrinkwrap.json`, `**/yarn.lock`, `**/pnpm-lock.yaml`, `**/bun.lock`, `**/bun.lockb`, `**/Cargo.lock`, `**/poetry.lock`, `**/Pipfile.lock`, `**/Gemfile.lock`, `**/composer.lock`, `**/go.sum`, `**/uv.lock`, `**/__snapshots__/**`, `**/*.snap`, `**/*.min.js`, `**/*.min.css`, `**/*.js.map`, `**/*.css.map`.
+- **Spec path (`wizz-quick-dev` only).** Compute the spec's repo-relative path first — `git -C "$TOP" ls-files --full-name -- <spec-path>` when it is tracked, otherwise a path relative to `$TOP` (e.g. via `realpath`) — then exclude it as `:(top,exclude,literal)<repo-relative path>`, ahead of the `review_exclude` excludes. If that one exclusion alone empties `{clean_diff_file}` (untracked files included) — meaning the spec's own edit was the only change — there is nothing to review: skip the review layers entirely and go straight to triage with no findings. Do not fall back to the raw diff in this case.
+- **Untracked files (uncommitted changes and file-list sources).** List them with `git -C "$TOP" ls-files --others --exclude-standard -z -- <pathspecs>` — the same positive-plus-exclude pathspecs as `{clean_diff_file}` for its own list, the positive pathspecs alone for `{diff_file}`'s list. For every path the `-z` listing returns, append it to that diff with `git -C "$TOP" diff --no-index --no-color -- /dev/null <path>`. Exit code `1` means "files differ" — that is success, append the output; only an exit code greater than `1` is a failure. Both `{diff_file}` and `{clean_diff_file}` include every untracked file that passes their own pathspecs.
+- **Counts.** `files` and `changed_lines` come from `git -C "$TOP" diff <source-args> --no-ext-diff --no-color --no-textconv --numstat -- <pathspecs>` (the same pathspecs as the diff being counted) plus, for every untracked path, `git -C "$TOP" diff --no-index --numstat -- /dev/null <path>`. `files` is the number of lines printed across both; `changed_lines` is the sum of their numeric columns. A binary (`-`) counts as a file with 0 lines.
+- **Provided or pasted diffs, and no VCS.** No git at all — `{clean_diff_file}` = `{diff_file}`. See § 2 for how `files`/`changed_lines` are counted here instead.
+- **Nothing left after exclusions.** `{clean_diff_file}` is empty — untracked files included, not merely that `--numstat` printed nothing for the tracked part. `wizz-code-review` HALTs, lists the exclusions, and asks whether to review the raw diff anyway. `wizz-quick-dev` reviews the raw diff instead, except for the spec-only case above.
+- **Git failure.** Review the raw `{diff_file}` at `critical`.
+- `{clean_diff_file}` is a uniquely-named file in the system temp directory.
+
+## 2. Pick the tier (session judgment)
+
+| Tier | Rule | Active layers | Forte subagents |
+|---|---|---|---|
+| `small` | at most 3 files and 80 changed lines (after exclusion), no critical hit | `blind-verification` | 1 |
+| `normal` | anything above `small`, no critical hit | `blind-verification`, `edge-case-hunter` | 2 |
+| `critical` | the change touches a sensitive area, or the user asks for every layer | `blind-hunter`, `edge-case-hunter`, `verification-gap`, `acceptance-auditor` (`wizz-quick-dev` has no `acceptance-auditor` layer: 3 layers there) | up to 4 (`wizz-quick-dev`: up to 3) |
+
+The session reads the file list (`git diff --name-status`) and, when unsure, the relevant hunks, then decides the tier itself by judgment.
+
+**Provided or pasted diffs, and no VCS.** There is no `git --numstat` to read. Count `files` from the diff's own `diff --git` (or, lacking that, `+++`) headers, and `changed_lines` from the `+`/`-` body lines (the `+++`/`---` header lines themselves don't count). The table above applies without exception in both workflows — `small` included.
+
+`{workflow.review_critical_paths}` is a plain-language list of sensitive areas, not a pattern list. Default: authentication, sessions, passwords and credentials, authorization, permissions and RLS, payments, billing and checkout, database migrations, schema and SQL, secrets, keys and `.env` files, cryptography, CI and deploy workflows. Judge by meaning, not by substring: a security check added inside an otherwise generic file counts as `critical`; a document that merely talks about auth does not.
+
+Raise the tier when in doubt, never lower it — a change that clearly touches something the list above doesn't name (e.g. a data migration done in application code) still earns `critical`. State the tier, the reason and the resulting layer count to the user before launching any layer.
+
+A layer is active only when `{tier}` is listed in its `tiers` field. A layer without `tiers` is active in every tier.
+
+If `{tier}` is empty or not one of `small`/`normal`/`critical` when the review step (`wizz-code-review` step 2) or the `wizz-quick-dev` Review section starts, set it to `critical` now and say so before evaluating any layer.
+
+Track each configured layer's outcome as `{layer_status}` — every `id` marked `active` or `dropped: <reason>` (tier, disabled by override, or its `when` condition). This list travels into triage so a delegated triager can tell, for example, whether `acceptance-auditor` ran.
+
+## 3. Cap each layer
+
+Every layer carries `max_calls` in its config. Substitute `{max_calls}` in its instruction. A layer that hits the cap stops and ends its final message with a line `PARTIAL: <what you did not cover>` — that exact marker is what the steps and triage look for to detect a partial layer. Triage treats a layer that returned that marker like a failed layer: the review may be incomplete and the user is told so.
+
+A layer that returns an explicit no-findings result (e.g. `[]`, or "No verification gaps found.") has succeeded, not failed — it found nothing to report. Only errors, timeouts, unreadable output, or a `PARTIAL:` ending count against a layer.
+
+A layer whose review-prompts method returns JSON (e.g. Edge Case Hunter's array) may still hit the cap mid-run and end with a trailing `PARTIAL: <...>` line after the JSON payload. Parse the JSON that precedes that line as the layer's findings — the trailing line only marks the run partial, it does not invalidate the JSON before it.
+
+When the brief names a `review-prompts/` file, that file owns the method and the output format. The reviewer ignores its generic verdict format and does not re-run the project's test suite unless the review prompt itself asks for it.
+
+## 4. Decide who triages
+
+The Forte tier is defined in `_shared/model-ladder.md`.
+
+- **Session runs on the Forte tier:** the session triages, as the triage instructions say. It already holds the context, so a subagent would only re-read it.
+- **Any session model other than the Forte tier:** write the collected findings, each with its originating layer `id`, to a uniquely-named temp file and launch one `wizz-exec-opus` subagent. Its brief is: the triage instructions (the path of the step file that holds them), the findings file, `{diff_file}`, `{spec_file}` when present, the paths of any loaded context docs, `{tier}`, `{failed_layers}`, `{layer_status}` (the active/dropped layer ids with drop reasons, so the triager knows which layers actually ran), and — only in workflows that set it (`wizz-code-review`) — `{review_mode}`. The subagent runs the whole pipeline itself: verdicts, the acceptance audit, grouping, and routing into categories. It returns every entry with severity, category and evidence, plus every dismissal with its reason — it never writes to any file; the session writes every log. The session then re-checks the subagent's own verdicts and routing against the evidence it returned — this is the session validating a delegated triager's work, not a new prompt to the user — and carries on per each workflow's own step. In `wizz-code-review`, `decision_needed` entries still get a genuine human confirmation before continuing, exactly as the presentation step already does; a confirmed entry the user rejects there is logged as dismissed with the user's own reason, never forced through. In `wizz-quick-dev`, `intent_gap` still loops back to the human as part of resolving it, and `bad_spec` still loops back automatically — the session's re-check adds no new user prompt for either.
+
+`{failed_layers}` stores layer `id`s (append ` (partial)` for a partial layer); every check against it compares ids, not names.
+
+**Acceptance audit.** Runs before the per-finding verdicts, as one more source of findings that then get verdicts like any other. In `wizz-code-review`, run it when a spec is present and the `acceptance-auditor` layer did not run to completion for any reason: `{layer_status}` marks it `dropped` (tier, disabled by override, or its `when` condition), or it failed or ended `PARTIAL:` (its id appears in `{failed_layers}`) — a `critical` tier where that layer actually ran to completion does not also get the triage-side audit. In `wizz-quick-dev`, run it on every tier — that workflow has no `acceptance-auditor` layer. Either way, check the diff against the spec's acceptance criteria and constraints, and add a finding with source `triage-acceptance` for each violation, deviation or missing behavior.
+
+## 5. Cleanup
+
+Delete `{diff_file}` only when `{diff_file_owned}` is true — never a file the user supplied directly by path. Delete `{clean_diff_file}` only when it is a different path from `{diff_file}`; when the two are the same path (a provided, pasted or no-VCS diff, a git failure, or a raw review after exclusions emptied the clean diff), the `{diff_file}` rule above decides. Also delete `{claims_file}` when it is non-empty, and any findings temp files. Delete them when the workflow ends, including every HALT that ends it outright. The one exception is the subagents-unavailable HALT: it keeps `{diff_file}` and `{clean_diff_file}`, because that HALT resumes when the human pastes findings back rather than ending the workflow.
+
+In `wizz-quick-dev`, each review loop iteration writes a new `{diff_file}`/`{clean_diff_file}` generation; before overwriting them for the next loop, save the previous generation's paths and delete those old files per this section.

package/src/bmm-skills/4-implementation/wizz-code-review/steps/step-01-gather-context.md

@@ -1,5 +1,8 @@
 ---
 diff_file: '' # set at runtime: path to the diff file
+diff_file_owned: '' # set at runtime: true when this workflow wrote {diff_file}, false when the user supplied its path
+clean_diff_file: '' # set at runtime: path to the cleaned diff file
+tier: '' # set at runtime: "small", "normal" or "critical"
 claims_file: '' # set at runtime (path or empty)
 spec_file: '' # set at runtime (path or empty)
 review_mode: '' # set at runtime: "full" or "no-spec"
@@ -12,7 +15,7 @@ story_key: '' # set at runtime when discovered from sprint status
 
 - YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
 - The prompt that triggered this workflow IS the intent — not a hint.
-- Writing `{diff_file}` and the claims file is the only change this step may make. Otherwise it is read-only.
+- Writing `{diff_file}`, `{clean_diff_file}` and the claims file is the only change this step may make. Otherwise it is read-only.
 
 ## INSTRUCTIONS
 
@@ -58,19 +61,30 @@ story_key: '' # set at runtime when discovered from sprint status
    - **Specific commit range** (ask for the range)
    - **Provided diff or file list** (user pastes or provides a path)
 
-3. Write the diff for the chosen source to `{diff_file}` — a uniquely-named file in the system temp directory, so concurrent reviews cannot collide. The review layers read that file; the diff text is never pasted into their prompts.
-   - For **staged changes only**: run `git diff --cached > {diff_file}`.
-   - For **uncommitted changes** (staged + unstaged): run `git diff HEAD > {diff_file}`.
-   - For **branch diff**: verify the base branch exists, then run `git diff <base-branch>...HEAD > {diff_file}`. If it does not exist, HALT and ask the user for a valid branch.
-   - For **commit range**: verify the range resolves, then run `git diff <range> > {diff_file}`. If it does not resolve, HALT and ask the user for a valid range.
-   - For **provided diff**: validate the content is non-empty and parseable as a unified diff. If it is not parseable, HALT and ask the user to provide a valid diff. Write the validated diff to `{diff_file}`.
-   - For **file list**: validate each path exists in the working tree. Run `git diff HEAD -- <path1> <path2> ... > {diff_file}`. If any paths are untracked (new files not yet staged), append them with `git diff --no-index /dev/null <path> >> {diff_file}`. If the diff is empty (files have no uncommitted changes and are not untracked), ask the user whether to review the full file contents or to specify a different baseline.
-   - After writing `{diff_file}`, verify it is non-empty regardless of source type. If empty, HALT and tell the user there is nothing to review.
+3. Write the diff for the chosen source to `{diff_file}` — a uniquely-named file in the system temp directory, so concurrent reviews cannot collide. The review layers read that file; the diff text is never pasted into their prompts. Compute `TOP="$(git rev-parse --show-toplevel)"` once and reuse it for every git command below (`references/review-economy.md` § 1). Set `{diff_file_owned}` = `true` unless a source below says otherwise.
+   - For **staged changes only**: `git -C "$TOP" diff --cached --no-ext-diff --no-color --no-textconv -- ':(top)' > {diff_file}`.
+   - For **uncommitted changes** (staged + unstaged): `git -C "$TOP" diff HEAD --no-ext-diff --no-color --no-textconv -- ':(top)' > {diff_file}`, then append untracked files per § 1 — list them with `git -C "$TOP" ls-files --others --exclude-standard -z -- ':(top)'` and append each with `git -C "$TOP" diff --no-index --no-color -- /dev/null <path> >> {diff_file}`.
+   - For **branch diff**: verify the base branch exists, then compute `git -C "$TOP" merge-base <base-branch> HEAD` and confirm it succeeded — never build a diff with an empty base. If either check fails, HALT, delete any temp file this instruction already created per `references/review-economy.md` § 5, and ask the user for a valid branch. Only once both succeed: `git -C "$TOP" diff <base-branch>...HEAD --no-ext-diff --no-color --no-textconv -- ':(top)' > {diff_file}`.
+   - For **commit range**: verify the range resolves, then `git -C "$TOP" diff <range> --no-ext-diff --no-color --no-textconv -- ':(top)' > {diff_file}`. If it does not resolve, HALT, delete any temp file this instruction already created per `references/review-economy.md` § 5, and ask the user for a valid range.
+   - For **provided diff**:
+     - Pasted text: validate it is non-empty and parseable as a unified diff. If it is not parseable, HALT and ask the user to provide a valid diff (nothing to clean up yet). Write it to `{diff_file}` — a workflow-owned temp copy, safe for cleanup to delete later.
+     - A file path: validate the file exists, is non-empty, and parseable as a unified diff. If it is not parseable, HALT and ask for a valid diff. Set `{diff_file}` to that path directly — do not copy it — and set `{diff_file_owned}` = `false`. This file is user-owned: cleanup (`references/review-economy.md` § 5) must never delete it, unconditionally — regardless of whether `{clean_diff_file}` ends up equal to it.
+   - For **file list**: validate each path exists in the working tree. Run `git -C "$TOP" diff HEAD --no-ext-diff --no-color --no-textconv -- ':(top,literal)<path1>' ':(top,literal)<path2>' ... > {diff_file}` — one `:(top,literal)<path>` pathspec per listed path. If any paths are untracked (new files not yet staged), append them with `git -C "$TOP" diff --no-index --no-color -- /dev/null <path> >> {diff_file}`. If the diff is empty (files have no uncommitted changes and are not untracked), ask the user whether to review the full file contents or to specify a different baseline.
+   - After writing `{diff_file}`, verify it is non-empty regardless of source type. If empty, HALT, delete `{diff_file}` (when `{diff_file_owned}` is true) per `references/review-economy.md` § 5, and tell the user there is nothing to review.
    - Read `{diff_file}` yourself whenever you need the diff for your own context — triage and presentation later in this workflow.
 
-4. **Stage the claims file.** Collect the change's own narrative: for a branch diff or commit range, the commit messages it covers (`git log <base>..<head>`); for other sources, whatever description of the change the user or conversation supplied. Write it verbatim to a uniquely-named file in the system temp directory and set `{claims_file}` to its path. If there is no narrative, set `{claims_file}` = `''`. Do not analyze or summarize the narrative — it is input for one review layer, staged as a file precisely so the other layers never see it.
+4. **Clean the diff and pick the tier.** A branch diff's base was already validated against `merge-base` in instruction 3 — do not re-check it here.
 
-5. **Set the spec context.**
+   - **Provided diff, pasted diff, or no VCS:** skip exclusions entirely — `{clean_diff_file}` = `{diff_file}`. Pick the tier per § 2 by judgment.
+   - **Otherwise:** build `{clean_diff_file}` per § 1 — the identical git command that wrote `{diff_file}` for the chosen source, plus one `:(top,exclude,glob)<pattern>` pathspec per entry in `{workflow.review_exclude}`, appended after the positive pathspecs. For **uncommitted changes**, also append untracked files to `{clean_diff_file}` the same way they were appended to `{diff_file}`, but listed with the positive-plus-exclude pathspecs from § 1 so any excluded file is skipped. Get `files` and `changed_lines` from `git -C "$TOP" diff --no-ext-diff --no-color --no-textconv --numstat` with the same source args and pathspecs, plus per-file `git -C "$TOP" diff --no-index --numstat -- /dev/null <path>` for the untracked ones (§ 1).
+   - If a git command in this instruction fails: delete any partially written `{clean_diff_file}` temp file, then set `{clean_diff_file}` = `{diff_file}` and `{tier}` = `critical`, say so, and continue.
+   - If nothing is left after exclusions (`{clean_diff_file}` is empty, untracked files included, even though `{diff_file}` is non-empty): HALT, list the exclusions, and ask the user whether to review the raw diff anyway. If they do, set `{clean_diff_file}` = `{diff_file}` and pick the tier per § 2 from the raw diff. If they decline, delete `{diff_file}` (when `{diff_file_owned}` is true) and `{clean_diff_file}` per § 5 and end the workflow.
+   - Otherwise, pick the tier per § 2: read `git diff --name-status` for the same source (and the relevant hunks when unsure) and judge it against `{workflow.review_critical_paths}`.
+   - State the tier, the reason, and the resulting Forte subagent count to the user before launching any layer.
+
+5. **Stage the claims file.** Collect the change's own narrative: for a branch diff or commit range, the commit messages it covers (`git log <base>..<head>`); for other sources, whatever description of the change the user or conversation supplied. Write it verbatim to a uniquely-named file in the system temp directory and set `{claims_file}` to its path. If there is no narrative, set `{claims_file}` = `''`. Do not analyze or summarize the narrative — it is input for one review layer, staged as a file precisely so the other layers never see it.
+
+6. **Set the spec context.**
    - If the triggering request or recent conversation **explicitly** states there is no spec (e.g. "no spec", "without a spec", "no-spec"): set `{review_mode}` = `"no-spec"` and clear `{spec_file}` (set it to `''`). Do **not** ask for a spec. Do **not** infer no-spec mode merely because the invocation omitted a spec path.
    - Else if `{spec_file}` is already set (from Tier 1 or Tier 2): verify the file exists and is readable, then set `{review_mode}` = `"full"`.
    - Else (neither a spec path nor an explicit no-spec declaration is present): ask the user to choose:
@@ -79,15 +93,15 @@ story_key: '' # set at runtime when discovered from sprint status
      - If the user provides a path: set `{spec_file}` to that path, verify the file exists and is readable, then set `{review_mode}` = `"full"`.
      - If the user explicitly chooses to continue without a spec: set `{review_mode}` = `"no-spec"`.
 
-6. If `{review_mode}` = `"full"` and the file at `{spec_file}` has a `context` field in its frontmatter listing additional docs, load each referenced document. Warn the user about any docs that cannot be found.
+7. If `{review_mode}` = `"full"` and the file at `{spec_file}` has a `context` field in its frontmatter listing additional docs, load each referenced document. Warn the user about any docs that cannot be found.
 
-7. Sanity check: if `wc -l {diff_file}` exceeds approximately 3000 lines, warn the user and offer to chunk the review by file group.
-   - If the user opts to chunk: agree on the first group, rebuild `{diff_file}` narrowed to that group, and list the remaining groups for the user to note for follow-up runs.
+8. Sanity check: if `wc -l {clean_diff_file}` or `wc -l {diff_file}` exceeds approximately 3000 lines, warn the user and offer to chunk the review by file group. Check both — `{diff_file}` is read directly later, for triage and presentation, regardless of how much `{clean_diff_file}` was filtered down.
+   - If the user opts to chunk: agree on the first group, then rebuild both `{diff_file}` and `{clean_diff_file}` narrowed to that file group (add the group's paths as a pathspec to the same git commands from instructions 3-4, re-applying the exclusions from § 1 to the narrowed `{clean_diff_file}`); the resulting `{tier}` for the chunk is never lower than the tier from the full, unchunked run. List the remaining groups for the user to note for follow-up runs.
    - If the user declines: proceed as-is with the full diff.
 
 ### CHECKPOINT
 
-Present a summary before proceeding: diff stats (files changed, lines added/removed), `{review_mode}`, and loaded spec/context docs (if any). HALT and wait for user confirmation to proceed.
+Present a summary before proceeding: diff stats (files changed, lines added/removed), the excluded files — the file paths present in `{diff_file}` but absent from `{clean_diff_file}`, each with the exclusion pattern that matched it — `{tier}` and how many Forte review subagents that tier will launch, `{review_mode}`, and loaded spec/context docs (if any). HALT and wait for user confirmation to proceed. If the user declines, delete `{diff_file}` (when `{diff_file_owned}` is true), `{clean_diff_file}`, and `{claims_file}` (when non-empty) per `references/review-economy.md` § 5, and end the workflow.
 
 ## NEXT
 

package/src/bmm-skills/4-implementation/wizz-code-review/steps/step-02-review.md

@@ -1,5 +1,6 @@
 ---
-failed_layers: '' # set at runtime: comma-separated list of layers that failed or returned empty
+failed_layers: '' # set at runtime: comma-separated list of layer ids that failed, timed out, or ended PARTIAL
+layer_status: '' # set at runtime: every configured layer's id marked active or dropped (with the drop reason)
 ---
 
 # Step 2: Review
@@ -9,23 +10,25 @@ failed_layers: '' # set at runtime: comma-separated list of layers that failed o
 - YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
 - Review subagents run pinned to the platform's Forte tier via `wizz-exec-review` (`opus` in Claude Code) — never at the same model capability as the current session. See `_shared/model-ladder.md`.
 - Run subagents synchronously: launch them together as blocking calls awaited in this turn — never backgrounded or detached, never ending the turn to await results.
+- Layers scale with `{tier}` and read `{clean_diff_file}`. See `references/review-economy.md`.
 
 ## INSTRUCTIONS
 
-1. The review layers are `{workflow.review_layers}`, resolved during activation.
+1. The review layers are `{workflow.review_layers}`, resolved during activation. If `{tier}` is empty or not one of `small`/`normal`/`critical`, set it to `critical` now and tell the user why, per `references/review-economy.md` § 2.
 
-2. For each layer in `{workflow.review_layers}`:
-   - `instruction` empty or missing → drop the layer silently (an override disabled it).
-   - `when` condition present and not satisfied by the current context (`{review_mode}`, `{spec_file}`) → drop the layer and tell the user, e.g. "Acceptance Auditor skipped — no spec file provided."
-   - otherwise → the layer is active.
+2. For each layer in `{workflow.review_layers}`, record the outcome in `{layer_status}` as you go:
+   - `tiers` present and `{tier}` not listed in it → drop the layer silently (the checkpoint already announced the tier). Record `<id>: dropped (tier)`.
+   - `instruction` empty or missing → drop the layer silently (an override disabled it). Record `<id>: dropped (disabled by override)`.
+   - `when` condition present and not satisfied by the current context (`{review_mode}`, `{spec_file}`) → drop the layer and tell the user, e.g. "Acceptance Auditor skipped — no spec file provided." Record `<id>: dropped (when condition not met)`.
+   - otherwise → the layer is active. Record `<id>: active`.
 
-   If no layer is active, HALT with status `blocked` and blocking condition `no active review layers`.
+   If no layer is active, delete `{diff_file}`, `{clean_diff_file}` and any findings temp files per `references/review-economy.md` § 5, then HALT with status `blocked` and blocking condition `no active review layers`.
 
-3. Announce skipped layers first, then launch every active layer before handling any layer's result. Try running all active layers simultaneously: expand `{skill-root}` in each layer's `instruction` to this skill's absolute installed directory, then substitute the runtime placeholders (`{diff_file}`, `{claims_file}`, `{spec_file}`). `{diff_file}` is a path: substitute the path itself and let the layer read the file — a launch prompt never carries diff text. For an instruction that launches a reviewer subagent, launch that child with the prompt text after placeholder substitution; do not load the reviewer instruction file yourself. For any other customized instruction, execute it as written. Do not leave `{skill-root}` unresolved in a child prompt, and resolve `{diff_file}` to an absolute path — the child's working directory is not yours. If a layer's instruction requires subagents and subagents are not available, for each such layer write under `{implementation_artifacts}` that layer's child prompt with everything after its content label replaced by the contents of `{diff_file}` (not a path-only pointer) — that session may not share this filesystem, so its prompt must be self-contained. Then HALT. Ask the user to run each in a separate session (ideally a different LLM) and paste back the findings. When findings are pasted, treat them as those layers' findings and resume from this point. This is the only allowed parent-side read of a reviewer instruction file.
+3. Announce skipped layers first, then launch every active layer before handling any layer's result. Try running all active layers simultaneously: expand `{skill-root}` in each layer's `instruction` to this skill's absolute installed directory, then substitute the runtime placeholders (`{clean_diff_file}`, `{diff_file}`, `{claims_file}`, `{spec_file}`, and `{max_calls}` from the layer's `max_calls` — if the layer has none, remove the whole `max_calls:` line). `{clean_diff_file}` is a path: substitute the path itself and let the layer read the file — a launch prompt never carries diff text. For an instruction that launches a reviewer subagent, launch that child with the prompt text after placeholder substitution; do not load the reviewer instruction file yourself. For any other customized instruction, execute it as written. Do not leave `{skill-root}` unresolved in a child prompt, and resolve `{clean_diff_file}` to an absolute path — the child's working directory is not yours. If a layer's instruction requires subagents and subagents are not available, for each such layer write under `{implementation_artifacts}` that layer's child prompt with everything after its content label replaced by the contents of `{clean_diff_file}` (not a path-only pointer) — that session may not share this filesystem, so its prompt must be self-contained. Then HALT — do NOT delete `{diff_file}` or `{clean_diff_file}`; this HALT resumes when findings are pasted back, so triage still needs them. Ask the user to run each in a separate session (ideally a different LLM) and paste back the findings. When findings are pasted, treat them as those layers' findings and resume from this point. This is the only allowed parent-side read of a reviewer instruction file.
 
-4. **Layer failure handling**: If any layer fails, times out, or returns empty results, append the layer's `name` to `{failed_layers}` (comma-separated) and proceed with findings from the remaining layers.
+4. **Layer failure handling**: If any layer errors, times out, or returns unreadable output, append the layer's `id` to `{failed_layers}` (comma-separated) and proceed with findings from the remaining layers. A layer that returns an explicit no-findings result (e.g. `[]`, or "No verification gaps found.") has succeeded — do not append it to `{failed_layers}`. A layer whose final message ends with a `PARTIAL:` line counts as partial: append `<id> (partial)` to `{failed_layers}` and keep its findings.
 
-5. Collect all findings from the completed layers, keeping track of each finding's originating layer `id`.
+5. Collect all findings from the completed layers, keeping track of each finding's originating layer `id`. Carry `{layer_status}` forward into triage along with `{failed_layers}`.
 
 ## NEXT
 

package/src/bmm-skills/4-implementation/wizz-code-review/steps/step-03-triage.md

@@ -9,6 +9,8 @@
 
 ## INSTRUCTIONS
 
+0. **Decide who triages**, per `references/review-economy.md` section 4. When a `wizz-exec-opus` subagent triages, its brief includes `{layer_status}` so it can tell which layers ran; it runs every instruction of this step through routing (instructions 1-5 below) and returns the result. The session then re-checks the subagent's verdicts and routing against the evidence, confirms `decision_needed` entries with the user, and continues with instruction 6.
+
 1. **Normalize** findings from all layers into a unified list where each finding has:
    - `id` -- sequential integer
    - `source` -- the `id` of the layer that produced the finding (e.g., `blind-hunter`)
@@ -16,7 +18,9 @@
    - `detail` -- full description
    - `location` -- file and line reference (if available)
 
-2. Once every layer has reported -- and not before -- render a verdict on each finding on its own, ahead of any deduplication or grouping. For each finding:
+2. Run the acceptance audit from `references/review-economy.md` section 4 and add its findings with source `triage-acceptance` to the unified list, before verdicts, when `{review_mode}` = `"full"` and the `acceptance-auditor` layer did not run to completion for any reason: `{layer_status}` marks it `dropped` (tier, disabled by override, or its `when` condition), or it failed or ended `PARTIAL:` (its id appears in `{failed_layers}`) — a `critical` tier where that layer actually ran to completion does not also get this audit. They get a verdict like any other finding, per instruction 3 below.
+
+3. Once every layer has reported -- and not before -- render a verdict on each finding on its own, ahead of any deduplication or grouping. For each finding:
    - **Verify its own claimed consequence** at the location it names. Read past the diff hunk -- into the callers, the guards upstream, whatever else the site depends on -- far enough to tell whether that consequence actually occurs. Another finding's outcome, however adjacent, never settles this one.
    - **Assign severity** from the verified consequence for the artifact's main consumer (software user, document reader, etc). Disregard any severity assigned by a reviewing subagent. Review subagents operate under by-design information asymmetry and do not have enough context to set final severity for this workflow.
      - `low` -- none or cosmetic
@@ -25,18 +29,20 @@
    - **Keep or dismiss.** Keep a finding only where verification confirmed its consequence. Dismiss noise, claims the verification refuted, and claims it could not substantiate -- no path to the claimed consequence at the named site is a valid disposal. Whatever the reason, it must dispose of the finding's own claim: a true fact about neighboring code that leaves the claim standing is not a dismissal, and the finding stays kept. Record each dismissal with its reason for the summary; never drop a finding silently.
    - A finding whose fix edits the spec under review: dismiss. A finding whose fix edits an agent-context document (e.g. CLAUDE.md, AGENTS.md, rules files, other specs): defer, never patch.
 
-3. **Group the survivors by shared root cause** -- two findings belong in one entry only when the same underlying defect produced both. Same location alone is not a shared root cause, and neither is a shared fix. An entry carries every member's verified consequence in `detail` and the highest severity among them; set `source` to the contributing layers joined with `+` (e.g., `blind-hunter+edge-case-hunter`).
+4. **Group the survivors by shared root cause** -- two findings belong in one entry only when the same underlying defect produced both. Same location alone is not a shared root cause, and neither is a shared fix. An entry carries every member's verified consequence in `detail` and the highest severity among them; set `source` to the contributing layers joined with `+` (e.g., `blind-hunter+edge-case-hunter`).
 
-4. **Route** each entry into exactly one triage bucket:
+5. **Route** each entry into exactly one triage bucket:
    - **decision_needed** -- There is an ambiguous choice that requires human input. The code cannot be correctly patched without knowing the user's intent. Only possible if `{review_mode}` = `"full"`.
    - **patch** -- Code issue that is fixable without human input. The correct fix is unambiguous.
    - **defer** -- Pre-existing issue not caused by the current change. Real but not actionable now.
 
    If `{review_mode}` = `"no-spec"` and an entry would otherwise be `decision_needed`, reclassify it as `patch` (if the fix is unambiguous) or `defer` (if not).
 
-5. If `{failed_layers}` is non-empty, report which layers failed before announcing results. If zero entries remain after dismissals AND `{failed_layers}` is non-empty, warn the user that the review may be incomplete rather than announcing a clean review.
+6. If `{failed_layers}` is non-empty, report which layers failed before announcing results. If zero entries remain after dismissals AND `{failed_layers}` is non-empty, warn the user that the review may be incomplete rather than announcing a clean review.
 
-6. If zero entries remain after triage (all dismissed or none raised): state "✅ Clean review — all layers passed." (Step 3 already warned if any review layers failed via `{failed_layers}`.)
+7. If zero entries remain after triage (all dismissed or none raised):
+   - `{failed_layers}` is empty: state "✅ Clean review — all layers passed."
+   - `{failed_layers}` is non-empty: never call it clean — state that the review found nothing but is incomplete, naming the failed/partial layers (already flagged in instruction 6).
 
 ## NEXT
 

package/src/bmm-skills/4-implementation/wizz-code-review/steps/step-04-present.md

@@ -127,6 +127,10 @@ Present the user with follow-up options:
 
 **HALT** — I am waiting for your choice. Do not proceed until the user selects an option.
 
+### 8. Cleanup
+
+Once the user's choice from section 7 of this step is handled, delete `{diff_file}`, `{clean_diff_file}` and any findings temp files, per `references/review-economy.md` section 5.
+
 ## On Complete
 
 Run: read `workflow.on_complete` from the `{project-root}/_wizz/_resolved/wizz-code-review.json` snapshot loaded in step 1