@zigrivers/scaffold 3.24.3 → 3.25.0

package/content/knowledge/core/automated-review-tooling.md

@@ -14,7 +14,7 @@ Automated code review leverages AI models to provide consistent, thorough code r
 
 See `review-methodology` for severity definitions (P0-P3). See `multi-model-review-dispatch` for finding reconciliation rules.
 
-**Action thresholds:** P0/P1/P2 findings must be fixed before proceeding to the next task. P3 findings are recorded but not actioned.
+**Action thresholds:** Findings at or above the configured `fix_threshold` (read from `results.fix_threshold` in the verdict JSON; default `P2`) must be fixed before proceeding to the next task. Findings below threshold are recorded as advisory but not actioned.
 
 ### Degraded-Mode Behavior
 
@@ -24,8 +24,8 @@ These are the authoritative verdict definitions. Tool files (`review-code.md`, `
 
 | Verdict | Condition |
 |---------|-----------|
-| `pass` | All channels completed, no unresolved P0/P1/P2 |
-| `degraded-pass` | Some channels unavailable, compensating passes ran, no unresolved P0/P1/P2 |
+| `pass` | All channels completed, no unresolved findings at or above `fix_threshold` |
+| `degraded-pass` | Some channels unavailable, compensating passes ran, no unresolved findings at or above `fix_threshold` |
 | `blocked` | Findings at or above fix threshold remain unresolved |
 | `needs-user-decision` | No channels completed — insufficient data for a determination |
 
@@ -47,7 +47,7 @@ When a channel (Codex or Gemini) is unavailable, the CLI dispatches a compensati
 - Missing Gemini → focus on architectural patterns, design reasoning, broad context.
 - Missing both → two compensating passes (one per missing channel's strength area).
 - Compensating-pass findings are **single-source confidence** — they do NOT raise to high confidence even if they agree with another channel's findings.
-- Normal mandatory-fix thresholds apply: P0/P1/P2 findings from compensating passes still require fixing.
+- Normal mandatory-fix thresholds apply: findings at or above `fix_threshold` from compensating passes still require fixing.
 
 #### Foreground-Only Execution
 
@@ -63,7 +63,7 @@ After all channels complete (including compensating passes), reconcile findings
 
 Reconciliation normalizes findings from all channels (real and compensating) to a common schema, then matches findings across channels by location and category. The purpose is to detect when multiple independent channels agree on a finding (raising confidence) and to surface contradictions that require human judgment. A finding reported by Codex alone has lower confidence than the same finding reported by both Codex and Gemini.
 
-The reconciliation output is a deduplicated list of findings with confidence scores. High-confidence findings (agreed by 2+ real channels) are actionable without further discussion. Low-confidence findings (single-source, or from compensating passes) still require action at P0/P1/P2 but should be noted as lower-confidence in the review summary.
+The reconciliation output is a deduplicated list of findings with confidence scores. High-confidence findings (agreed by 2+ real channels) are actionable without further discussion. Low-confidence findings (single-source, or from compensating passes) still require action when at or above `fix_threshold` but should be noted as lower-confidence in the review summary.
 
 Findings that appear in all three channels (Codex, Gemini, Claude) are considered maximum-confidence and should be surfaced first in the review summary. Findings that appear in only one channel should include the channel name in the finding description to help the developer assess confidence independently.
 
@@ -112,16 +112,16 @@ Apply the following evaluation order to determine the final verdict. The first m
 ```
 Verdict evaluation order:
 1. No channels completed? → needs-user-decision
-2. Any unresolved P0/P1/P2 after 3 fix rounds? → blocked
+2. Any unresolved findings at or above `fix_threshold` after 3 fix rounds? → blocked
 3. Any channel not at full coverage? → degraded-pass
-4. All channels completed, no unresolved P0/P1/P2? → pass
+4. All channels completed, no unresolved findings at or above `fix_threshold`? → pass
 ```
 
 A channel is "not at full coverage" when: it ran as a compensating pass instead of a real tool, or it timed out.
 
 **Verdict precedence reminder:** `needs-user-decision` > `blocked` > `degraded-pass` > `pass`. When multiple conditions apply simultaneously, the higher-precedence verdict wins.
 
-The verdict is always computed after all fix rounds are exhausted — do not emit a partial verdict mid-cycle. If a fix round resolves all P0/P1/P2 findings, the verdict upgrades from `blocked` to `pass` or `degraded-pass` depending on channel coverage. This upgrade must be verified explicitly by re-running the reconciliation step after each fix round, not assumed from the fact that fixes were applied.
+The verdict is always computed after all fix rounds are exhausted — do not emit a partial verdict mid-cycle. If a fix round resolves all findings at or above `fix_threshold`, the verdict upgrades from `blocked` to `pass` or `degraded-pass` depending on channel coverage. This upgrade must be verified explicitly by re-running the reconciliation step after each fix round, not assumed from the fact that fixes were applied.
 
 ### Security-Focused Review Checklist
 

package/content/pipeline/build/multi-agent-resume.md

@@ -168,7 +168,7 @@ Once in-progress work is complete (or if there was none):
    - This reviews the local delivery candidate without requiring a PR
    - Surface auth failures immediately and retry after recovery
    - If recovery is not possible, document reduced review coverage and continue with the available channels
-   - Fix any P0/P1/P2 findings before proceeding
+   - Fix any findings at or above `fix_threshold` before proceeding
 
 3. **Create PR** (if not already created for in-progress work)
    - Push the branch: `git push -u origin HEAD`
@@ -184,7 +184,7 @@ Once in-progress work is complete (or if there was none):
      4. **Superpowers code-reviewer** (4th channel): dispatch `superpowers:code-reviewer` subagent with BASE_SHA and HEAD_SHA
    - Verify auth before each CLI (`mmr config test` pre-flights all three at once)
    - All four channels should execute. Missing Codex or Gemini → MMR runs a compensating Claude pass in its place (degraded-pass verdict). Missing Claude CLI → review proceeds without compensation.
-   - Fix any P0/P1/P2 findings before proceeding
+   - Fix any findings at or above `fix_threshold` before proceeding
    - Do NOT move to the next task until the review completes
 
 5. **Between-task cleanup**
@@ -239,7 +239,7 @@ Once in-progress work is complete (or if there was none):
 5. **TDD is not optional** — Continue the red-green-refactor cycle for any in-progress work.
 6. **Quality gates before PR** — Never create a PR with failing checks.
 7. **Honor pre-push review when requested** — If the user or project workflow asks for pre-push multi-model review, run `scaffold run review-code` after quality gates and before `git push`.
-8. **Code review before next task** — After creating a PR, run `scaffold run review-pr`: three CLI channels (Codex CLI, Gemini CLI, Claude CLI) via MMR plus the Superpowers code-reviewer agent as a complementary 4th channel. Fix all P0/P1/P2 findings before moving on.
+8. **Code review before next task** — After creating a PR, run `scaffold run review-pr`: three CLI channels (Codex CLI, Gemini CLI, Claude CLI) via MMR plus the Superpowers code-reviewer agent as a complementary 4th channel. Fix all findings at or above `fix_threshold` before moving on.
 9. **Follow CLAUDE.md** — It is the authority on project conventions and commands.
 
 ---

package/content/pipeline/build/multi-agent-start.md

@@ -171,7 +171,7 @@ For each task:
    - This reviews the local delivery candidate without requiring a PR
    - Surface auth failures immediately and retry after recovery
    - If recovery is not possible, document reduced review coverage and continue with the available channels
-   - Fix any P0/P1/P2 findings before proceeding
+   - Fix any findings at or above `fix_threshold` before proceeding
 
 7. **Create PR**
    - Push the branch: `git push -u origin HEAD`
@@ -188,7 +188,7 @@ For each task:
      4. **Superpowers code-reviewer** (4th channel): dispatch `superpowers:code-reviewer` subagent with BASE_SHA and HEAD_SHA
    - Verify auth before each CLI (`mmr config test` pre-flights all three at once)
    - All four channels should execute. Missing Codex or Gemini → MMR runs a compensating Claude pass in its place (degraded-pass verdict). Missing Claude CLI → review proceeds without compensation.
-   - Fix any P0/P1/P2 findings before proceeding
+   - Fix any findings at or above `fix_threshold` before proceeding
    - Do NOT move to the next task until the review completes
 
 9. **Between-task cleanup**
@@ -231,7 +231,7 @@ For each task:
 4. **TDD is not optional** — Write failing tests before implementation. No exceptions.
 5. **Quality gates before PR** — Never create a PR with failing checks.
 6. **Honor pre-push review when requested** — If the user or project workflow asks for pre-push multi-model review, run `scaffold run review-code` after quality gates and before `git push`.
-7. **Code review before next task** — After creating a PR, run `scaffold run review-pr`: three CLI channels (Codex CLI, Gemini CLI, Claude CLI) via MMR plus the Superpowers code-reviewer agent as a complementary 4th channel. Fix all P0/P1/P2 findings before moving on.
+7. **Code review before next task** — After creating a PR, run `scaffold run review-pr`: three CLI channels (Codex CLI, Gemini CLI, Claude CLI) via MMR plus the Superpowers code-reviewer agent as a complementary 4th channel. Fix all findings at or above `fix_threshold` before moving on.
 8. **Avoid task conflicts** — Check what other agents are working on before claiming.
 9. **Follow CLAUDE.md** — It is the authority on project conventions and commands.
 

package/content/pipeline/build/single-agent-resume.md

@@ -145,7 +145,7 @@ Once in-progress work is complete (or if there was none):
    - This reviews the local delivery candidate without requiring a PR
    - Surface auth failures immediately and retry after recovery
    - If recovery is not possible, document reduced review coverage and continue with the available channels
-   - Fix any P0/P1/P2 findings before proceeding
+   - Fix any findings at or above `fix_threshold` before proceeding
 
 3. **Create PR** (if not already created for in-progress work)
    - Push the branch: `git push -u origin HEAD`
@@ -161,7 +161,7 @@ Once in-progress work is complete (or if there was none):
      4. **Superpowers code-reviewer** (4th channel): dispatch `superpowers:code-reviewer` subagent with BASE_SHA and HEAD_SHA
    - Verify auth before each CLI (`mmr config test` pre-flights all three at once)
    - All four channels should execute. Missing Codex or Gemini → MMR runs a compensating Claude pass in its place (degraded-pass verdict). Missing Claude CLI → review proceeds without compensation.
-   - Fix any P0/P1/P2 findings before proceeding
+   - Fix any findings at or above `fix_threshold` before proceeding
    - Do NOT move to the next task until the review completes
 
 5. **Claim next task**
@@ -204,7 +204,7 @@ Once in-progress work is complete (or if there was none):
 4. **TDD is not optional** — Continue the red-green-refactor cycle for any in-progress work.
 5. **Quality gates before PR** — Never create a PR with failing checks.
 6. **Honor pre-push review when requested** — If the user or project workflow asks for pre-push multi-model review, run `scaffold run review-code` after quality gates and before `git push`.
-7. **Code review before next task** — After creating a PR, run `scaffold run review-pr`: three CLI channels (Codex CLI, Gemini CLI, Claude CLI) via MMR plus the Superpowers code-reviewer agent as a complementary 4th channel. Fix all P0/P1/P2 findings before moving on.
+7. **Code review before next task** — After creating a PR, run `scaffold run review-pr`: three CLI channels (Codex CLI, Gemini CLI, Claude CLI) via MMR plus the Superpowers code-reviewer agent as a complementary 4th channel. Fix all findings at or above `fix_threshold` before moving on.
 8. **Follow CLAUDE.md** — It is the authority on project conventions and commands.
 
 ---

package/content/pipeline/build/single-agent-start.md

@@ -150,7 +150,7 @@ For each task:
    - This reviews the local delivery candidate without requiring a PR
    - Surface auth failures immediately and retry after recovery
    - If recovery is not possible, document reduced review coverage and continue with the available channels
-   - Fix any P0/P1/P2 findings before proceeding
+   - Fix any findings at or above `fix_threshold` before proceeding
 
 7. **Create PR**
    - Push the branch: `git push -u origin HEAD`
@@ -167,7 +167,7 @@ For each task:
      4. **Superpowers code-reviewer** (4th channel): dispatch `superpowers:code-reviewer` subagent with BASE_SHA and HEAD_SHA
    - Verify auth before each CLI (`mmr config test` pre-flights all three at once)
    - All four channels should execute. Missing Codex or Gemini → MMR runs a compensating Claude pass in its place (degraded-pass verdict). Missing Claude CLI → review proceeds without compensation.
-   - Fix any P0/P1/P2 findings before proceeding
+   - Fix any findings at or above `fix_threshold` before proceeding
    - Do NOT move to the next task until the review completes
 
 9. **Update status**
@@ -202,7 +202,7 @@ For each task:
 2. **One task at a time** — Complete the current task fully before starting the next.
 3. **Quality gates before PR** — Never create a PR with failing checks.
 4. **Honor pre-push review when requested** — If the user or project workflow asks for pre-push multi-model review, run `scaffold run review-code` after quality gates and before `git push`.
-5. **Code review before next task** — After creating a PR, run `scaffold run review-pr`: three CLI channels (Codex CLI, Gemini CLI, Claude CLI) via MMR plus the Superpowers code-reviewer agent as a complementary 4th channel. Fix all P0/P1/P2 findings before moving on.
+5. **Code review before next task** — After creating a PR, run `scaffold run review-pr`: three CLI channels (Codex CLI, Gemini CLI, Claude CLI) via MMR plus the Superpowers code-reviewer agent as a complementary 4th channel. Fix all findings at or above `fix_threshold` before moving on.
 6. **Update status immediately** — Mark tasks complete as soon as review passes.
 7. **Consult lessons.md** — Check for relevant anti-patterns before each task.
 8. **Follow CLAUDE.md** — It is the authority on project conventions and commands.

package/content/pipeline/environment/automated-pr-review.md

@@ -100,6 +100,18 @@ Check if AGENTS.md exists first. If it exists, check for scaffold tracking comme
 
 ## Instructions
 
+### MMR Configuration
+
+If `.mmr.yaml` does not exist in the project root and `mmr` is on `PATH`,
+run `mmr config init` once to create one. The generated file pins
+`fix_threshold: P2` (the recommended default for typical software work)
+with an explanatory comment block describing each severity tier — edit
+the value if your project warrants a different gate (`P1` for low-friction
+prototypes; `P3` for security-sensitive work).
+
+If `mmr` is not installed, install it before running multi-model review;
+otherwise channels will degrade.
+
 ### Configure Review Enforcement Hook
 
 Add a Claude Code hook to the project's `.claude/settings.json` that fires after
@@ -118,7 +130,7 @@ Add this to `.claude/settings.json`:
         "hooks": [
           {
             "type": "command",
-            "command": "if echo \"$CC_BASH_COMMAND\" | grep -q 'gh pr create'; then echo '\\n⚠️  MANDATORY: Run all 3 CLI review channels plus the Superpowers 4th channel before proceeding to the next task:\\n\\n  1. Codex CLI:\\n     Auth: codex login status 2>/dev/null\\n     Run:  codex exec --skip-git-repo-check -s read-only --ephemeral \"REVIEW_PROMPT\" 2>/dev/null\\n\\n  2. Gemini CLI:\\n     Auth: NO_BROWSER=true gemini -p \"respond with ok\" -o json 2>&1\\n     Run:  NO_BROWSER=true gemini -p \"REVIEW_PROMPT\" --output-format json --approval-mode yolo 2>/dev/null\\n\\n  3. Claude CLI:\\n     Auth: claude -p \"respond with ok\" 2>/dev/null\\n     Run:  claude -p \"REVIEW_PROMPT\" --output-format json 2>/dev/null\\n\\n  4. Superpowers code-reviewer (complementary 4th channel):\\n     Dispatch superpowers:code-reviewer subagent with BASE_SHA and HEAD_SHA\\n\\nIf auth fails: tell user to run ! codex login, ! gemini -p \"hello\", or ! claude login (as applicable).\\nDo not silently skip channels — surface auth failures and let MMR decide: missing Codex/Gemini get compensating Claude passes (degraded-pass verdict); missing Claude proceeds without compensation.\\nFix all P0/P1/P2 findings before moving on.\\nFull instructions: scaffold run review-pr'; fi"
+            "command": "if echo \"$CC_BASH_COMMAND\" | grep -q 'gh pr create'; then echo '\\n⚠️  MANDATORY: Run all 3 CLI review channels plus the Superpowers 4th channel before proceeding to the next task:\\n\\n  1. Codex CLI:\\n     Auth: codex login status 2>/dev/null\\n     Run:  codex exec --skip-git-repo-check -s read-only --ephemeral \"REVIEW_PROMPT\" 2>/dev/null\\n\\n  2. Gemini CLI:\\n     Auth: NO_BROWSER=true gemini -p \"respond with ok\" -o json 2>&1\\n     Run:  NO_BROWSER=true gemini -p \"REVIEW_PROMPT\" --output-format json --approval-mode yolo 2>/dev/null\\n\\n  3. Claude CLI:\\n     Auth: claude -p \"respond with ok\" 2>/dev/null\\n     Run:  claude -p \"REVIEW_PROMPT\" --output-format json 2>/dev/null\\n\\n  4. Superpowers code-reviewer (complementary 4th channel):\\n     Dispatch superpowers:code-reviewer subagent with BASE_SHA and HEAD_SHA\\n\\nIf auth fails: tell user to run ! codex login, ! gemini -p \"hello\", or ! claude login (as applicable).\\nDo not silently skip channels — surface auth failures and let MMR decide: missing Codex/Gemini get compensating Claude passes (degraded-pass verdict); missing Claude proceeds without compensation.\\nFix all findings at or above the configured fix_threshold (see results.fix_threshold in the verdict JSON; default P2).\\nFull instructions: scaffold run review-pr'; fi"
           }
         ]
       }
@@ -151,8 +163,8 @@ markers, replace it in place and add the markers.
 <!-- scaffold:automated-pr-review:claude-md start -->
 **Mandatory after `gh pr create`** — run `/scaffold:review-pr <PR#>` to execute
 all three review channels (Codex CLI, Gemini CLI, Claude CLI), plus the
-Superpowers code-reviewer agent as a complementary 4th channel. Fix P0/P1/P2
-findings before moving to the next task. A post-hook on `gh pr create` will
+Superpowers code-reviewer agent as a complementary 4th channel. Fix findings
+at or above `fix_threshold` before moving to the next task. A post-hook on `gh pr create` will
 remind you.
 
 **Optional but supported** for non-PR targets — the review is not PR-gated.

package/content/skills/mmr/SKILL.md

@@ -119,13 +119,20 @@ Re-run `mmr config test` after re-authenticating to verify.
 
 ## Severity Gate
 
-Default threshold is P2 (fix P0/P1/P2, skip P3). Override per-review:
+Default threshold is `P2` (the verdict gate blocks on P0, P1, and P2;
+P3 findings are kept in the result as **advisory** but don't cause
+`blocked`). Override per-review:
 
 ```bash
 mmr review --pr 47 --fix-threshold P1   # Only fix P0 and P1
 mmr review --pr 47 --fix-threshold P0   # Only fix critical issues
 ```
 
+The verdict JSON includes `advisory_count` (count of findings strictly
+below the threshold). Formatted output shows `Advisory: N` (text) or
+`**Advisory:** N` (markdown) when non-zero — useful for spotting real
+findings that the gate didn't block.
+
 ## Output Formats
 
 ```bash

package/content/skills/multi-model-dispatch/SKILL.md

@@ -147,13 +147,13 @@ When dispatching a review, bundle all relevant context into the prompt. Each CLI
 ### Template for Artifact Review
 
 ```
-You are reviewing a project artifact for quality issues. Report P0 (critical), P1 (high), and P2 (medium) issues.
+You are reviewing a project artifact for quality issues. Report all P0, P1, P2, and P3 findings; the project's fix threshold is applied downstream.
 
 ## Severity Definitions
 - P0: Will cause implementation failure, data loss, security vulnerability, or fundamental architectural flaw
 - P1: Will cause bugs in normal usage, inconsistency across documents, or blocks downstream work
 - P2: Improvement opportunity — style, naming, documentation, minor optimization
-- Do NOT report P3 issues (personal preference, trivial nits)
+- P3: Personal preference, trivial nits — included so a strict project (`fix_threshold: P3`) can act on them; otherwise advisory
 
 ## Review Standards
 [paste contents of docs/review-standards.md if it exists, otherwise use severity definitions above]
@@ -170,7 +170,7 @@ Respond with a JSON object:
   "approved": true/false,
   "findings": [
     {
-      "severity": "P0" or "P1" or "P2",
+      "severity": "P0" or "P1" or "P2" or "P3",
       "location": "section or line reference",
       "description": "what's wrong",
       "suggestion": "specific fix"
@@ -179,13 +179,13 @@ Respond with a JSON object:
   "summary": "one-line assessment"
 }
 
-If no P0/P1/P2 issues found, respond with: { "approved": true, "findings": [], "summary": "No issues found." }
+If no findings, respond with: { "approved": true, "findings": [], "summary": "No issues found." }
 ```
 
 ### Template for PR Diff Review
 
 ```
-You are reviewing a pull request diff. Report P0, P1, and P2 issues.
+You are reviewing a pull request diff. Report all P0, P1, P2, and P3 findings; the project's fix threshold is applied downstream.
 
 ## Review Standards
 [paste docs/review-standards.md]

package/content/tools/post-implementation-review.md

@@ -10,7 +10,7 @@ conditional: null
 stateless: true
 category: tool
 knowledge-base: [multi-model-review-dispatch, automated-review-tooling, post-implementation-review-methodology]
-argument-hint: "[--report-only]"
+argument-hint: "[--report-only] [--fix-threshold P0|P1|P2|P3]"
 ---
 
 ## Purpose
@@ -30,7 +30,7 @@ The three channels are:
 
 ## Inputs
 
-- `$ARGUMENTS` — `--report-only` flag (optional; omit to review + fix)
+- `$ARGUMENTS` — `--report-only` flag and/or `--fix-threshold P0|P1|P2|P3` (both optional)
 - `docs/user-stories.md` (required) — user stories with acceptance criteria; organizing manifest for Phase 2
 - `docs/implementation-plan.md` (optional) — implementation tasks; used to cross-check that all planned deliverables were built
 - `docs/coding-standards.md` (required) — coding conventions for review context
@@ -43,13 +43,13 @@ The three channels are:
 ## Expected Outputs
 
 - `docs/reviews/post-implementation-review.md` — consolidated findings report
-- Fixed code (P0/P1/P2 findings resolved) — in review+fix and update modes
+- Fixed code (findings at or above `fix_threshold` resolved) — in review+fix and update modes
 
 ## Mode Detection
 
 | Condition | Mode |
 |-----------|------|
-| No prior report, no `--report-only` | **Review + Fix** — run all phases, then fix P0/P1/P2 |
+| No prior report, no `--report-only` | **Review + Fix** — run all phases, then fix findings at or above `fix_threshold` |
 | No prior report, `--report-only` | **Report Only** — run all phases, write report, no code changes |
 | Prior report exists, no `--report-only` | **Update Mode** — load prior findings, skip to Phase 3 fix execution |
 | Prior report exists, `--report-only` | **Re-review** — run full review fresh, overwrite prior report |
@@ -63,6 +63,12 @@ The three channels are:
 REPORT_ONLY=false
 [[ "$ARGUMENTS" == *"--report-only"* ]] && REPORT_ONLY=true
 
+# Detect --fix-threshold flag
+FIX_THRESHOLD=""
+if [[ "$ARGUMENTS" =~ (^|[[:space:]])--fix-threshold[[:space:]]+(P[0-3])($|[[:space:]]) ]]; then
+  FIX_THRESHOLD="${BASH_REMATCH[2]}"
+fi
+
 # Detect prior report
 PRIOR_REPORT="docs/reviews/post-implementation-review.md"
 [[ -f "$PRIOR_REPORT" ]] && PRIOR_EXISTS=true || PRIOR_EXISTS=false
@@ -482,6 +488,12 @@ diff-only), so it operates independently of `mmr review`. Use `mmr reconcile` on
 when you want to merge post-implementation findings into an existing MMR job for a
 single unified verdict.
 
+If `$FIX_THRESHOLD` is set and a fresh `mmr review` is dispatched as part
+of this flow (e.g., to seed a job for `mmr reconcile`), forward it to that
+invocation: `mmr review … --fix-threshold "$FIX_THRESHOLD" …`. The
+existing `mmr reconcile` call does not take `--fix-threshold` directly —
+the job's threshold is set at `mmr review` time.
+
 ### Step 6: Consolidate Findings
 
 Merge all findings from Phase 1 (`CODEX_PHASE1_FINDINGS`, `GEMINI_PHASE1_FINDINGS`,
@@ -495,8 +507,12 @@ entry. Record all source channels in a `sources` array on the merged finding.
 
 **Sorting:** P0 first, then P1, then P2, then P3.
 
-**Fix queue:** P0, P1, and P2 findings enter the fix queue. P3 findings are recorded
-in the report but not actioned.
+**Fix queue:** Findings at or above the configured `fix_threshold` enter the
+fix queue. The threshold defaults to `P2` (so P0, P1, P2 enter the queue and
+P3 is advisory) and is configurable via `.mmr.yaml`, `--fix-threshold`
+passed to this command, or the user's `~/.mmr/config.yaml`. The agent
+reads the active threshold from `$FIX_THRESHOLD` if set; otherwise from
+`.mmr.yaml` or the built-in default.
 
 ### Step 7: Write the Findings Report
 
@@ -543,7 +559,7 @@ Create `docs/reviews/` if it does not exist. Write the following to
 - [criterion]: satisfied | partial | not-satisfied
 
 **Findings:**
-[P0/P1/P2/P3 findings for this story, or "No findings."]
+[Findings sorted by severity, or "No findings."]
 
 [Repeat for each story]
 
@@ -574,7 +590,10 @@ PRE_FIX_SHA=$(git rev-parse HEAD)
 This is used in Step 9 to identify all files modified across all fix commits,
 regardless of how many severity-tier commits are made.
 
-Process the fix queue in priority order: all P0s first, then all P1s, then all P2s.
+Process the fix queue in priority order: iterate severity tiers from most
+critical to least, processing every tier from `P0` down to and including
+the configured `fix_threshold` (default `P2`). At threshold `P3` this
+includes all four tiers; at `P0` only critical findings are processed.
 Within each severity tier, fix high-confidence findings (multi-source) first.
 
 For each finding:
@@ -593,15 +612,16 @@ For each finding:
    - Stop attempting to fix it
    - Continue to the next finding in the queue
 
-After all P0s are fixed, re-read each P0-modified file once to confirm correctness
-before moving to P1s.
+After all findings in a severity tier are fixed, re-read each modified file
+once to confirm correctness before moving to the next tier.
 
-Commit after each severity tier:
+Commit after each severity tier processed (the tier label varies by run —
+`P0`, `P1`, `P2`, or `P3` depending on the configured threshold):
 
 ```bash
 git add [modified source files only — not the report]
-git commit -m "fix: resolve P0 post-implementation review findings"
-# Replace P0 with P1 or P2 for the respective tiers
+git commit -m "fix: resolve <tier> post-implementation review findings"
+# Substitute <tier> with the severity label of the tier you just processed
 ```
 
 ### Step 9: Final Verification Pass
@@ -616,7 +636,7 @@ recorded at the start of Step 8:
 git diff --name-only $PRE_FIX_SHA..HEAD
 ```
 
-This captures files from every severity-tier commit (P0, P1, P2), not just
+This captures files from every severity-tier commit, not just
 the most recent one.
 
 Dispatch `superpowers:code-reviewer` with:
@@ -701,7 +721,7 @@ the user they require manual attention before the project is ready to release.
 3. **Auth failures are not silent** — always surface to the user with the exact recovery command (`! codex login` or `! gemini -p "hello"`). Wait for user response before queuing a compensating pass.
 4. **Independence** — never share one channel's output with another. Each reviews independently.
 5. **Verify every fix** — run tests (or re-read the file) immediately after each fix before moving on.
-6. **3-round limit (per finding)** — never attempt to fix the *same* P0/P1/P2 finding more than 3 times. Each round that surfaces a *new, different, fixable* finding is healthy iteration — keep going. Stop only when the same finding recurs across 3 attempts, channels contradict each other, or the user asks to stop. Surface unresolved findings to the user.
+6. **3-round limit (per finding)** — never attempt to fix the *same* blocking finding more than 3 times. Each round that surfaces a *new, different, fixable* finding is healthy iteration — keep going. Stop only when the same finding recurs across 3 attempts, channels contradict each other, or the user asks to stop. Surface unresolved findings to the user.
 7. **Document everything** — the report must show which channels ran, which were compensating, which were skipped, and the root cause for any degraded channel.
 8. **No auto-merge** — this tool modifies local files only. It never pushes, merges, or creates PRs.
 9. **Dispatch pattern cross-reference** — Phase 2 parallel dispatch uses `superpowers:dispatching-parallel-agents`. Each story subagent dispatches its own `superpowers:code-reviewer` as Channel 3. This two-level nesting is intentional and supported.

package/content/tools/review-code.md

@@ -10,7 +10,7 @@ conditional: null
 stateless: true
 category: tool
 knowledge-base: [multi-model-review-dispatch, automated-review-tooling]
-argument-hint: "[--base <ref>] [--head <ref>] [--staged] [--report-only]"
+argument-hint: "[--base <ref>] [--head <ref>] [--staged] [--report-only] [--fix-threshold P0|P1|P2|P3]"
 ---
 
 ## Purpose
@@ -44,6 +44,7 @@ brand-new files.
   - `--head <ref>` — explicit head ref for diff review
   - `--staged` — review only staged changes (`git diff --cached`)
   - `--report-only` — collect findings and verdict, but do not apply fixes
+  - `--fix-threshold P0|P1|P2|P3` — override the project's configured threshold for this run
 - `docs/coding-standards.md` (required) — coding conventions for review context
 - `docs/tdd-standards.md` (optional) — test expectations
 - `docs/review-standards.md` (optional) — severity definitions and review criteria
@@ -63,6 +64,17 @@ brand-new files.
 When the MMR CLI is installed, use it as the primary entry point. Pick the
 invocation that matches the scope the user asked for:
 
+A common helper across all four invocation modes — set `MMR_FLAGS` once
+and reuse it. **Note:** `FIX_THRESHOLD` is parsed from `$ARGUMENTS` in
+Step 1 below; if you're skipping ahead to the invocations, run Step 1's
+detection block first so the `--fix-threshold` flag actually flows
+through.
+
+```bash
+MMR_FLAGS=(--sync --format json)
+[ -n "$FIX_THRESHOLD" ] && MMR_FLAGS+=(--fix-threshold "$FIX_THRESHOLD")
+```
+
 ```bash
 # Default (no flags) — full local delivery candidate:
 # committed branch diff (vs origin/main or main) + staged + unstaged.
@@ -93,16 +105,16 @@ fi
 # that covers committed branch work + staged + unstaged edits, with
 # repeated edits to the same file collapsed into a single final hunk.
 MERGE_BASE=$(git merge-base "$BASE_REF" HEAD 2>/dev/null || echo "$BASE_REF")
-git diff "$MERGE_BASE" | mmr review --diff - --sync --format json
+git diff "$MERGE_BASE" | mmr review --diff - "${MMR_FLAGS[@]}"
 
 # Staged changes only:
-mmr review --staged --sync --format json
+mmr review --staged "${MMR_FLAGS[@]}"
 
 # Branch diff against main (committed only, no staged/unstaged):
-mmr review --base main --sync --format json
+mmr review --base main "${MMR_FLAGS[@]}"
 
 # Explicit ref range:
-mmr review --base <base-ref> --head <head-ref> --sync --format json
+mmr review --base <base-ref> --head <head-ref> "${MMR_FLAGS[@]}"
 ```
 
 Routing rules:
@@ -133,6 +145,14 @@ Parse `$ARGUMENTS` and set:
 - `STAGED_ONLY=true` if `$ARGUMENTS` contains `--staged`
 - `BASE_REF` from `--base <ref>` if present
 - `HEAD_REF` from `--head <ref>` if present
+- `FIX_THRESHOLD` from `--fix-threshold <value>` if present (must match `P0`, `P1`, `P2`, or `P3`); leave empty to defer to `.mmr.yaml`/built-in default
+
+```bash
+FIX_THRESHOLD=""
+if [[ "$ARGUMENTS" =~ (^|[[:space:]])--fix-threshold[[:space:]]+(P[0-3])($|[[:space:]]) ]]; then
+  FIX_THRESHOLD="${BASH_REMATCH[2]}"
+fi
+```
 
 If `--head` is provided without `--base`, stop and tell the user both refs are
 required for explicit-range review.
@@ -312,14 +332,14 @@ clean ref range exists.
 All channels should receive an equivalent prompt bundle built from the local review scope:
 
 ```text
-You are reviewing local code changes before commit or push. Report only P0, P1,
-and P2 issues.
+You are reviewing local code changes before commit or push. Report all P0, P1,
+P2, and P3 findings; the project's fix threshold is applied downstream.
 
 ## Scope
 [scope label]
 
 ## Review Standards
-[docs/review-standards.md if present, otherwise define P0/P1/P2]
+[docs/review-standards.md if present, otherwise define P0–P3]
 
 ## Coding Standards
 [docs/coding-standards.md]
@@ -342,7 +362,7 @@ Respond with JSON:
   "approved": true/false,
   "findings": [
     {
-      "severity": "P0" | "P1" | "P2",
+      "severity": "P0" | "P1" | "P2" | "P3",
       "location": "file:line or section",
       "description": "what is wrong",
       "suggestion": "specific fix"
@@ -364,7 +384,7 @@ Use these rules:
 | Any single P2 | Fix unless clearly inapplicable; if disputed, surface to user |
 | All executed channels approve | Candidate passes review |
 | Strong contradiction on a medium-severity issue | Verdict becomes `needs-user-decision` |
-| Compensating-pass P0/P1/P2 finding | Single-source confidence — fix per normal thresholds, but label as compensating in summary |
+| Compensating-pass blocking finding | Single-source confidence — fix per normal thresholds, but label as compensating in summary |
 
 ### Step 7: Apply Fixes Unless in Report-Only Mode
 
@@ -374,10 +394,10 @@ If `REPORT_ONLY=true`:
 - Stop
 
 Otherwise:
-1. Fix all P0/P1/P2 findings
+1. Fix all findings at or above `fix_threshold` (read from `results.fix_threshold` in the verdict JSON; default `P2`)
 2. Re-run the channels that produced findings
 3. Keep iterating as long as each new round surfaces *different, concrete, fixable* findings — that is healthy review/fix iteration, not a stuck loop
-4. The 3-round limit is **per finding**: stop and surface to the user when the *same* P0/P1/P2 finding (or set) recurs across 3 attempts without progress. Other stop conditions: a finding is genuinely ambiguous (channels contradict each other), or the user explicitly asks to stop. Use verdict `needs-user-decision` for ambiguity, `blocked` for stuck-loop cases.
+4. The 3-round limit is **per finding**: stop and surface to the user when the *same* blocking finding (or set) recurs across 3 attempts without progress. Other stop conditions: a finding is genuinely ambiguous (channels contradict each other), or the user explicitly asks to stop. Use verdict `needs-user-decision` for ambiguity, `blocked` for stuck-loop cases.
 
 **Fix cycle channel rule:** Re-run only channels that originally completed or ran as compensating passes. Never retry a channel marked `not_installed`, `auth_failed`, or `timeout` during fix rounds — its availability does not change within a session.
 
@@ -385,9 +405,9 @@ Otherwise:
 
 Return exactly one verdict:
 
-- `pass` — all channels completed with `full` coverage, no unresolved P0/P1/P2
-- `degraded-pass` — at least one channel was skipped/compensated (coverage is not all `full`), but all executed and compensating channels have no unresolved P0/P1/P2
-- `blocked` — gate failed: at least one unresolved finding sits at or above the fix threshold (typically the *same* finding(s) remain unresolved after 3 fix attempts; default threshold is `P2`, so this means an unresolved P0/P1/P2)
+- `pass` — all channels completed with `full` coverage, no unresolved findings at or above `fix_threshold`
+- `degraded-pass` — at least one channel was skipped/compensated (coverage is not all `full`), but all executed and compensating channels have no unresolved findings at or above `fix_threshold`
+- `blocked` — gate failed: at least one unresolved finding sits at or above the fix threshold (typically the *same* finding(s) remain unresolved after 3 fix attempts; the threshold defaults to `P2` but is configurable via `.mmr.yaml` or `--fix-threshold`)
 - `needs-user-decision` — no channels completed (no reconciled result was possible), reviewer disagreement / contradictions, or a finding requires human judgment that automated iteration can't resolve
 
 When compensating passes ran for any channel, the maximum achievable verdict is `degraded-pass` — never `pass`, even if all findings are resolved. When both external channels were compensated, the review summary must note: "All findings are single-model (Claude only)."
@@ -424,5 +444,5 @@ for the next delivery step (commit, push, or PR creation).
 2. **All 3 channels are mandatory** — skip only when a tool is genuinely not installed, never by choice.
 3. **Auth failures are not silent** — always surface to the user with recovery instructions.
 4. **Independence** — never share one channel's output with another.
-5. **Fix before proceeding** — P0/P1/P2 findings must be resolved before moving to the next task.
+5. **Fix before proceeding** — findings at or above `fix_threshold` must be resolved before moving to the next task.
 6. **Dispatch pattern** follows `multi-model-review-dispatch` knowledge entry. When modifying channel dispatch in this file, verify consistency with `review-pr.md` and `post-implementation-review.md`.

package/content/tools/review-pr.md

@@ -9,7 +9,7 @@ conditional: null
 stateless: true
 category: tool
 knowledge-base: [multi-model-review-dispatch, automated-review-tooling]
-argument-hint: "<PR number or blank for current branch>"
+argument-hint: "<PR# or blank> [--fix-threshold P0|P1|P2|P3]"
 ---
 
 ## Purpose
@@ -44,7 +44,7 @@ The three channels are:
 
 ## Inputs
 
-- $ARGUMENTS — PR number (optional; auto-detected from current branch if omitted)
+- $ARGUMENTS — PR number (optional; auto-detected from current branch if omitted) and/or `--fix-threshold P0|P1|P2|P3` to override the project's configured threshold for this run
 - `.mmr.yaml` — MMR CLI configuration (channels, review_criteria, defaults)
 
 The CLI handles review context via config (`review_criteria` in `.mmr.yaml`).
@@ -54,7 +54,7 @@ in the review criteria config rather than read at dispatch time.
 ## Expected Outputs
 
 - All three CLI review channels executed (or fallback documented) plus the Superpowers code-reviewer 4th channel reconciled via `mmr reconcile`
-- P0/P1/P2 findings fixed before proceeding
+- findings at or above the configured `fix_threshold` fixed before proceeding (read from `results.fix_threshold` in the verdict JSON; default `P2`)
 - Review summary with per-channel results and reconciliation
 
 ## Instructions
@@ -62,8 +62,21 @@ in the review criteria config rather than read at dispatch time.
 ### Step 1: Identify the PR
 
 ```bash
-# Use argument if provided, otherwise detect from current branch
-PR_NUMBER="${ARGUMENTS:-$(gh pr view --json number -q .number 2>/dev/null)}"
+# Strip --fix-threshold from $ARGUMENTS if present; remainder is the PR number.
+# Strip the entire matched span (BASH_REMATCH[0]) — including whatever
+# whitespace separator was used (space, tab, multi-space). Replacing with a
+# single space preserves token boundaries; tr -d '[:space:]' below drops
+# everything else.
+FIX_THRESHOLD=""
+ARGS_REMAINING="$ARGUMENTS"
+if [[ "$ARGS_REMAINING" =~ (^|[[:space:]])--fix-threshold[[:space:]]+(P[0-3])($|[[:space:]]) ]]; then
+  FIX_THRESHOLD="${BASH_REMATCH[2]}"
+  ARGS_REMAINING="${ARGS_REMAINING//${BASH_REMATCH[0]}/ }"
+fi
+
+# Use remaining argument if provided, otherwise detect from current branch
+PR_NUMBER="$(echo "$ARGS_REMAINING" | tr -d '[:space:]')"
+PR_NUMBER="${PR_NUMBER:-$(gh pr view --json number -q .number 2>/dev/null)}"
 ```
 
 If no PR is found, stop and tell the user to create a PR first.
@@ -73,7 +86,9 @@ If no PR is found, stop and tell the user to create a PR first.
 Use the MMR CLI as the primary entry point for automated dispatch, reconciliation, and verdict:
 
 ```bash
-MMR_RESULT=$(mmr review --pr "$PR_NUMBER" --sync --format json)
+MMR_FLAGS=(--pr "$PR_NUMBER" --sync --format json)
+[ -n "$FIX_THRESHOLD" ] && MMR_FLAGS+=(--fix-threshold "$FIX_THRESHOLD")
+MMR_RESULT=$(mmr review "${MMR_FLAGS[@]}")
 # Extract job_id from JSON output for use in mmr reconcile
 JOB_ID=$(echo "$MMR_RESULT" | grep -o '"job_id": "[^"]*"' | head -1 | cut -d'"' -f4)
 ```
@@ -168,7 +183,7 @@ reconcile findings after all channels complete:
 | One channel flags P0, others approve | **High** | Fix it — P0 is critical from any source |
 | One channel flags P1, others approve | **Medium** | Fix it — P1 findings are mandatory regardless of source count |
 | Channels contradict each other | **Low** | Present to user for adjudication |
-| Compensating-pass P0/P1/P2 finding | **Single-source** | Fix per normal thresholds, label as compensating |
+| Compensating-pass blocking finding | **Single-source** | Fix per normal thresholds, label as compensating |
 
 ### Step 6: Report Results
 
@@ -200,7 +215,7 @@ Output a review summary in this format:
 
 Return exactly one verdict:
 
-- `pass` — all channels completed and the gate passed (no unresolved findings at or above the configured fix threshold; default threshold is `P2`, so this means no unresolved P0/P1/P2)
+- `pass` — all channels completed and the gate passed (no unresolved findings at or above the configured fix threshold; the threshold defaults to `P2` but is configurable via `.mmr.yaml` or `--fix-threshold`)
 - `degraded-pass` — gate passed but some channels were skipped or replaced by compensating passes (max achievable verdict when any channel was compensated)
 - `blocked` — gate failed: at least one unresolved finding sits at or above the fix threshold (typically the *same* finding(s) remain unresolved after 3 fix attempts)
 - `needs-user-decision` — no channels completed (no reconciled result was possible), reviewer disagreement / contradictions, or a finding requires human judgment that automated iteration can't resolve
@@ -209,15 +224,15 @@ Verdict precedence: `needs-user-decision` > `blocked` > `degraded-pass` > `pass`
 
 When compensating passes ran, maximum achievable verdict is `degraded-pass`. When both external channels were compensated, note "All findings are single-model."
 
-### Step 7: Fix P0/P1/P2 Findings
+### Step 7: Fix Blocking Findings
 
-If any P0, P1, or P2 findings exist:
+If any findings sit at or above `fix_threshold` (the verdict JSON's `fix_threshold` field; default `P2`):
 1. Fix them in the code
 2. Push the fixes: `git push`
 3. Re-run the review to verify fixes: `mmr review --pr "$PR_NUMBER" --sync --format json`
 4. The 3-round limit is **per finding**, not total rounds:
    - **Keep going** when each new round surfaces *different, concrete, fixable* findings — that is healthy review/fix iteration.
-   - **Stop and ask the user** when (a) the *same* P0/P1/P2 finding (or set) recurs across 3 attempts without progress, (b) a finding is genuinely ambiguous (channels contradict each other), or (c) the user explicitly asks to stop.
+   - **Stop and ask the user** when (a) the *same* blocking finding (or set) recurs across 3 attempts without progress, (b) a finding is genuinely ambiguous (channels contradict each other), or (c) the user explicitly asks to stop.
    - **When stopped**, do NOT merge automatically. Document the unresolved findings (severity, location, attempt count) and let the user decide whether to continue fixing, create follow-up issues, or override.
 
 **Note:** Fix cycles are an orchestration concern — the caller (agent or human) handles the fix loop. The CLI provides the review and verdict; the caller decides whether to fix and re-run.
@@ -261,8 +276,8 @@ In either path, output the message and stop. Do NOT proceed to the next task wit
 2. **All three CLI channels are mandatory** — Codex CLI, Gemini CLI, and Claude CLI. Plus the Superpowers code-reviewer agent as a complementary 4th channel reconciled via `mmr reconcile` (Step 3). Skip a CLI channel only when a tool is genuinely not installed or auth cannot be recovered (in which case MMR emits a compensating pass for missing Codex/Gemini channels; a missing Claude CLI has no compensator). Never skip by choice.
 3. **Auth failures are not silent** — always surface to the user with the exact recovery command.
 4. **Independence** — never share one channel's output with another. Each reviews the diff independently.
-5. **Fix before proceeding** — P0/P1/P2 findings must be resolved before moving to the next task.
-6. **3-round limit (per finding)** — never attempt to fix the *same* P0/P1/P2 finding more than 3 times. Each round that surfaces a *new* fixable finding is healthy iteration — keep going. Stop only when the same finding recurs across 3 attempts, channels contradict each other, or the user asks to stop.
+5. **Fix before proceeding** — findings at or above `fix_threshold` must be resolved before moving to the next task.
+6. **3-round limit (per finding)** — never attempt to fix the *same* blocking finding more than 3 times. Each round that surfaces a *new* fixable finding is healthy iteration — keep going. Stop only when the same finding recurs across 3 attempts, channels contradict each other, or the user asks to stop.
 7. **Document everything** — the review summary must show which channels ran and which were skipped, with reasons.
 8. **CLI-first** — use `mmr review --sync` as the primary entry point. Manual dispatch is a fallback only.
 9. **Job storage** — the CLI stores job data at `~/.mmr/jobs/{job-id}/results.json`. Review results are available via `mmr results <job-id>`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zigrivers/scaffold",
-  "version": "3.24.3",
+  "version": "3.25.0",
   "description": "AI-powered software project scaffolding pipeline",
   "type": "module",
   "workspaces": [

package/skills/mmr/SKILL.md

@@ -119,13 +119,20 @@ Re-run `mmr config test` after re-authenticating to verify.
 
 ## Severity Gate
 
-Default threshold is P2 (fix P0/P1/P2, skip P3). Override per-review:
+Default threshold is `P2` (the verdict gate blocks on P0, P1, and P2;
+P3 findings are kept in the result as **advisory** but don't cause
+`blocked`). Override per-review:
 
 ```bash
 mmr review --pr 47 --fix-threshold P1   # Only fix P0 and P1
 mmr review --pr 47 --fix-threshold P0   # Only fix critical issues
 ```
 
+The verdict JSON includes `advisory_count` (count of findings strictly
+below the threshold). Formatted output shows `Advisory: N` (text) or
+`**Advisory:** N` (markdown) when non-zero — useful for spotting real
+findings that the gate didn't block.
+
 ## Output Formats
 
 ```bash

package/skills/multi-model-dispatch/SKILL.md

@@ -147,13 +147,13 @@ When dispatching a review, bundle all relevant context into the prompt. Each CLI
 ### Template for Artifact Review
 
 ```
-You are reviewing a project artifact for quality issues. Report P0 (critical), P1 (high), and P2 (medium) issues.
+You are reviewing a project artifact for quality issues. Report all P0, P1, P2, and P3 findings; the project's fix threshold is applied downstream.
 
 ## Severity Definitions
 - P0: Will cause implementation failure, data loss, security vulnerability, or fundamental architectural flaw
 - P1: Will cause bugs in normal usage, inconsistency across documents, or blocks downstream work
 - P2: Improvement opportunity — style, naming, documentation, minor optimization
-- Do NOT report P3 issues (personal preference, trivial nits)
+- P3: Personal preference, trivial nits — included so a strict project (`fix_threshold: P3`) can act on them; otherwise advisory
 
 ## Review Standards
 [paste contents of docs/review-standards.md if it exists, otherwise use severity definitions above]
@@ -170,7 +170,7 @@ Respond with a JSON object:
   "approved": true/false,
   "findings": [
     {
-      "severity": "P0" or "P1" or "P2",
+      "severity": "P0" or "P1" or "P2" or "P3",
       "location": "section or line reference",
       "description": "what's wrong",
       "suggestion": "specific fix"
@@ -179,13 +179,13 @@ Respond with a JSON object:
   "summary": "one-line assessment"
 }
 
-If no P0/P1/P2 issues found, respond with: { "approved": true, "findings": [], "summary": "No issues found." }
+If no findings, respond with: { "approved": true, "findings": [], "summary": "No issues found." }
 ```
 
 ### Template for PR Diff Review
 
 ```
-You are reviewing a pull request diff. Report P0, P1, and P2 issues.
+You are reviewing a pull request diff. Report all P0, P1, P2, and P3 findings; the project's fix threshold is applied downstream.
 
 ## Review Standards
 [paste docs/review-standards.md]