@zigrivers/scaffold 3.22.0 → 3.24.0

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

@@ -1,7 +1,7 @@
 ---
 name: automated-pr-review
-description: Agent-driven automated PR review with external reviewers (Codex Cloud, Gemini Code Assist, or custom)
-summary: "Configures automated code review — using Codex and/or Gemini CLIs for dual-model review when available, or an external bot — with severity definitions and review criteria tailored to your project."
+description: "Agent-driven automated code review via MMR (Codex, Gemini, Claude CLIs + Superpowers as 4th channel in wrappers), for PRs and non-PR targets"
+summary: "Configures agent-driven automated code review: mandatory after `gh pr create` and also usable on any non-PR target. Direct `mmr review` runs three CLI channels (Codex, Gemini, Claude); `scaffold run review-pr` / `scaffold run review-code` add the Superpowers code-reviewer agent as a complementary 4th channel. An external GitHub App reviewer is supported as a fallback when CLIs are unavailable."
 phase: "environment"
 order: 340
 dependencies: [git-workflow]
@@ -12,10 +12,21 @@ knowledge-base: [review-methodology, automated-review-tooling]
 ---
 
 ## Purpose
-Configure an agent-driven automated PR review system using local CLI reviewers
-(Codex, Gemini — runs both when available for dual-model quality) or external
-GitHub App reviewers. Zero GitHub Actions workflows. The agent manages the
-entire review-fix loop locally.
+Configure an agent-driven automated code review system using local CLI
+reviewers dispatched through MMR (Codex, Gemini, Claude — runs all three when
+available) plus the Superpowers code-reviewer agent as a complementary 4th
+channel when using the MMR wrappers `scaffold run review-pr` and
+`scaffold run review-code`. The review is mandatory after `gh pr create` and
+also runs on non-PR targets (local staged/unstaged code, branch diffs,
+specific files) via the same `mmr review` CLI.
+`scaffold run post-implementation-review` is a separate full-codebase review
+(Codex CLI + Gemini CLI + Superpowers code-reviewer) that runs after an AI
+agent completes all implementation tasks; it does not currently use Claude
+CLI as a standard channel and is not an MMR wrapper, though it can inject
+findings into an existing MMR job via `mmr reconcile`.
+External GitHub App reviewers remain supported as a fallback when CLIs are
+unavailable. Zero GitHub Actions workflows. The agent manages the entire
+review-fix loop locally.
 
 ## Inputs
 - docs/coding-standards.md (required) — review criteria reference
@@ -26,7 +37,7 @@ entire review-fix loop locally.
 ## Expected Outputs
 - AGENTS.md — Reviewer instructions with project-specific rules
 - docs/review-standards.md — severity definitions (P0-P3) and review criteria
-- scripts/cli-pr-review.sh (local CLI mode) — dual-model review with reconciliation
+- scripts/cli-pr-review.sh (legacy dual-model fallback) — Codex+Gemini review with manual reconciliation, used when MMR / `scaffold run review-pr` is unavailable
 - scripts/await-pr-review.sh (external bot mode) — polling script with JSON output
 - docs/git-workflow.md updated with review loop integration
 - CLAUDE.md updated with agent-driven review workflow and review-pr hook
@@ -36,23 +47,27 @@ entire review-fix loop locally.
 - (mvp) Review standards document matches project coding conventions
 - (deep) Await script handles all exit conditions (approved, findings, cap, skip, timeout)
 - (mvp) CLAUDE.md workflow documents the agent-driven loop
+- (mvp) CLAUDE.md review block covers both PR and non-PR targets (staged, branch diff, single file)
 - (mvp) No GitHub Actions workflows created (zero Actions minutes)
 - (mvp) No ANTHROPIC_API_KEY secret required
 - (mvp) Post-PR-creation hook configured in settings to remind agents to run review-pr
 - (deep) Legacy GitHub Actions workflows detected and cleanup offered
-- (deep) Dual-model review enabled when both CLIs available
+- (deep) Three-CLI review (Codex, Gemini, Claude) enabled when all three CLIs available, with per-channel auth checks and compensating passes
+- (deep) The MMR scaffold wrappers (review-pr, review-code) add the Superpowers code-reviewer agent as a complementary 4th channel and reconcile its findings through MMR. `post-implementation-review` follows a separate channel layout (Codex + Gemini + Superpowers, with optional `mmr reconcile` injection) and is not one of the MMR wrappers.
 
 ## Methodology Scaling
-- **deep**: Full setup with local CLI review (dual-model when both available),
-  review-standards.md, AGENTS.md, and comprehensive CLAUDE.md workflow.
-  Falls back to external bot review if no CLIs available.
+- **deep**: Full setup with local three-CLI review dispatched through MMR
+  (Codex, Gemini, Claude), scaffold wrappers adding the Superpowers
+  code-reviewer as a complementary 4th channel, review-standards.md,
+  AGENTS.md, and comprehensive CLAUDE.md workflow covering PR and non-PR
+  targets. Falls back to external bot review if no CLIs available.
 - **mvp**: Step is disabled. Local self-review from git-workflow suffices.
 - **custom:depth(1-5)**:
   - Depth 1: disabled — local self-review from git-workflow suffices.
   - Depth 2: disabled — same as depth 1.
-  - Depth 3: basic review-standards.md + single-CLI review (whichever CLI is available).
-  - Depth 4: add dual-model review when both CLIs available, AGENTS.md with project-specific rules.
-  - Depth 5: full suite with dual-model review, legacy Actions cleanup, and comprehensive CLAUDE.md workflow integration.
+  - Depth 3: basic review-standards.md + MMR dispatch using whichever CLIs are available (graceful compensating Claude passes for missing Codex or Gemini channels; if Claude CLI itself is unavailable, the review proceeds with the remaining channels — no compensating pass for missing Claude).
+  - Depth 4: three-CLI review via MMR when all CLIs available, plus AGENTS.md with project-specific rules and the Superpowers 4th channel on wrapper invocations.
+  - Depth 5: full suite — three-CLI + Superpowers review, legacy GitHub Actions cleanup, comprehensive CLAUDE.md workflow integration covering PR and non-PR targets.
 
 ## Conditional Evaluation
 Enable when: project uses GitHub for version control, team size > 1 or CI/CD is
@@ -74,10 +89,14 @@ Check if AGENTS.md exists first. If it exists, check for scaffold tracking comme
   script customizations
 - **Triggers for update**: coding-standards.md changed (new review criteria),
   tdd-standards.md changed (coverage expectations), new external reviewer
-  CLI became available, git-workflow.md changed PR workflow steps
+  CLI became available, git-workflow.md changed PR workflow steps, review
+  scope expanded beyond PRs (e.g., MMR now supports staged / diff / branch
+  / file targets)
 - **Conflict resolution**: if review criteria changed in coding-standards.md,
-  update AGENTS.md review rules to match; if both CLI reviewers are now
-  available, offer to enable dual-model review
+  update AGENTS.md review rules to match; if additional CLI reviewers have
+  become available, offer to enable the full three-CLI MMR flow (Codex,
+  Gemini, Claude) and, on wrapper invocations, surface Superpowers
+  code-reviewer as the complementary 4th channel
 
 ## Instructions
 
@@ -99,7 +118,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 code review channels 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. Superpowers code-reviewer:\\n     Dispatch superpowers:code-reviewer subagent with BASE_SHA and HEAD_SHA\\n\\nIf auth fails: tell user to run ! codex login or ! gemini -p \"hello\"\\nFix all P0/P1/P2 findings before moving on. Do NOT skip any channel.\\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 P0/P1/P2 findings before moving on.\\nFull instructions: scaffold run review-pr'; fi"
           }
         ]
       }
@@ -120,21 +139,54 @@ the actual CLI invocations ensures the agent can execute reviews even if the
 
 ### Add Review Workflow to CLAUDE.md
 
-Add the following to the project's CLAUDE.md in the Code Review section:
+Add the following to the project's CLAUDE.md in the Code Review section. Wrap
+the managed section in the `<!-- scaffold:automated-pr-review:claude-md -->`
+markers shown below so Update Mode can idempotently rewrite this block without
+duplicating it on re-run. If a prior version of the block exists **without**
+markers, replace it in place and add the markers.
 
 ```markdown
 ## Code Review
 
-After creating a PR, run `/scaffold:review-pr <PR#>` to execute all three review
-channels (Codex CLI, Gemini CLI, Superpowers code-reviewer). Fix P0/P1/P2 findings
-before moving to the next task. A post-hook on `gh pr create` will remind you.
-
-| Command | Purpose |
-|---------|---------|
-| `/scaffold:review-pr <PR#>` | Run all 3 review channels on a PR |
-| `scripts/cli-pr-review.sh <PR#>` | Run dual-model CLI review only |
+<!-- 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
+remind you.
+
+**Optional but supported** for non-PR targets — the review is not PR-gated.
+Direct `mmr review` runs the three CLI channels (Codex, Gemini, Claude) on
+any diff or file. `scaffold run review-code` adds the Superpowers
+code-reviewer agent as a complementary 4th channel on top of those three
+CLIs for the local pre-commit review path.
+
+| When | Command |
+|------|---------|
+| After creating a PR | `/scaffold:review-pr <PR#>` |
+| Before commit / push (tracked local code: committed + staged + unstaged) | `scaffold run review-code` |
+| Pending edits to a tracked file (changes since HEAD) | `git diff HEAD -- <path> \| mmr review --diff - --sync --format json` |
+| Current contents of any file (tracked-with-no-changes, untracked, or brand-new) | `(diff -u /dev/null <path> \|\| true) \| mmr review --diff - --sync --format json` |
+| Branch diff | `mmr review --base <ref> --head <ref> --sync --format json` |
+| Staged changes only | `mmr review --staged --sync --format json` |
+| All tracked uncommitted changes (staged + unstaged, no untracked) | `git diff HEAD \| mmr review --diff - --sync --format json` |
+| Existing patch or diff file | `mmr review --diff <path.patch> --sync --format json` |
+| Dual-model CLI only (no reconciliation) | `scripts/cli-pr-review.sh <PR#>` |
+
+Note: `mmr review --diff` expects diff-format content; use the `git diff …`
+or `(diff -u /dev/null … || true)` wrappers shown above to review plain
+files. The `|| true` guard on `diff` is required because `diff` exits with
+status 1 whenever files differ, which breaks pipelines under `pipefail`.
+<!-- scaffold:automated-pr-review:claude-md end -->
 ```
 
+**Idempotency note:** In Update Mode, find the `<!-- scaffold:automated-pr-review:claude-md start -->`
+and `<!-- scaffold:automated-pr-review:claude-md end -->` markers and replace
+everything between them with the current version of the block above. If the
+markers are missing (pre-marker versions), locate the prior block by its
+"After creating a PR, run `/scaffold:review-pr`" lead-in and replace it in
+place, adding the markers around the new content. Never append a second copy.
+
 ### Configure AGENTS.md, Review Standards, and CLI Scripts
 
 Follow the existing instructions for creating AGENTS.md, docs/review-standards.md,

package/content/skills/mmr/SKILL.md

@@ -14,10 +14,38 @@ Dispatch code reviews to multiple AI model CLIs, poll for results, and collect r
 
 ## Quick Reference
 
+`mmr review` works for any review target — not just PRs. Pick the input mode
+that matches what you want reviewed:
+
 ```bash
-# Dispatch a review for a PR
+# GitHub PR (fetches diff via `gh pr diff`)
 mmr review --pr <number> --focus "description of what to focus on"
 
+# Staged git changes (pre-commit review)
+mmr review --staged --focus "..."
+
+# All tracked uncommitted changes (staged + unstaged) — excludes untracked
+# files; use `scaffold run review-code` for full-worktree coverage
+git diff HEAD | mmr review --diff - --focus "..."
+
+# Branch diff / ref range
+mmr review --base main --head <branch> --focus "..."
+
+# Changes to a specific tracked file since HEAD (pending edits only).
+# If the file has no local changes this pipeline sends an empty diff
+# and MMR will refuse with "no diff content"; use the next form instead
+# to review the file's current contents regardless of git state.
+git diff HEAD -- path/to/file.md | mmr review --diff - --focus "..."
+
+# A file's current contents, regardless of git state (tracked-with-no-
+# changes, untracked, or brand-new). Synthesizes an "all added" diff.
+# `|| true` is required: diff exits 1 whenever files differ, which breaks
+# pipelines under `set -o pipefail`.
+(diff -u /dev/null path/to/file.md || true) | mmr review --diff - --focus "..."
+
+# Existing patch or diff file
+mmr review --diff path/to/changes.patch --focus "..."
+
 # Check progress
 mmr status <job-id>
 
@@ -28,7 +56,20 @@ mmr results <job-id>
 mmr config test
 ```
 
-## After Creating a PR
+All input modes accept `--focus`, `--sync`, `--format`, and `--fix-threshold`
+the same way. The "3-channel review" is not PR-specific — it reviews whatever
+diff you point it at.
+
+**`--diff` contract:** the flag expects diff-format content (a path to a
+`.patch`/`.diff` file, or `-` for stdin). It does not read raw document
+content — wrap the target in a diff first (see the `git diff …` and
+`(diff -u /dev/null … || true)` patterns above). The `|| true` guard is
+required because `diff` exits 1 whenever files differ, which breaks
+pipelines under `set -o pipefail`.
+
+## Common Workflows
+
+**After creating a PR**
 
 1. Run `mmr review --pr <number>`
 2. Note the job ID from the output
@@ -38,6 +79,35 @@ mmr config test
 6. If gate failed: fix findings at or above the threshold severity
 7. If gate passed: proceed to merge
 
+**Reviewing a document or arbitrary file**
+
+Pick the case that matches what the user wants reviewed:
+
+- **Just the pending edits** to a tracked file (what changed since last
+  commit): `git diff HEAD -- path/to/doc.md | mmr review --diff -
+  --focus "..."`. Fails with "no diff content" if the file has no
+  local changes.
+- **The file's current contents**, whether it's tracked-with-no-
+  changes, untracked, or brand-new: wrap as a synthetic "all added"
+  diff first: `(diff -u /dev/null path/to/doc.md || true) |
+  mmr review --diff - --focus "..."`. The `|| true` guard avoids
+  `diff`'s exit-1-on-differences breaking the pipeline under
+  `set -o pipefail`.
+
+Same dispatch / status / results flow as above.
+
+**Reviewing uncommitted work before push**
+
+1. `git add` the files you want reviewed
+2. Run `mmr review --staged`
+3. Fix findings at or above the gate threshold, re-stage, re-run as needed
+
+Prefer the wrapper tools (`scaffold run review-pr`, `scaffold run review-code`)
+when they cover your target — they add auth checks, compensating passes, and
+the agent-review channel on top of `mmr review`. Call `mmr review` directly
+for targets the wrappers don't cover (docs, arbitrary diffs, ref ranges
+outside `main`).
+
 ## Auth Failures
 
 If `mmr review` reports auth failures, follow the recovery instructions in the output:

package/content/skills/scaffold-runner/SKILL.md

@@ -202,9 +202,9 @@ When the user asks "what tools are available?", "what can I build?", or "show me
 | `scaffold run update` | Update scaffold to the latest version |
 | `scaffold run dashboard` | Open a visual progress dashboard in your browser |
 | `scaffold run prompt-pipeline` | Print the full pipeline reference table |
-| `scaffold run review-code` | Run all 3 code review channels on local code before commit or push |
-| `scaffold run review-pr` | Run all 3 code review channels (Codex CLI, Gemini CLI, Superpowers) on a PR |
-| `scaffold run post-implementation-review` | Full 3-channel codebase review after an AI agent completes all tasks |
+| `scaffold run review-code` | Run all 3 CLI review channels (Codex CLI, Gemini CLI, Claude CLI) on tracked local code (committed branch diff + staged + unstaged — no untracked files) before commit or push, plus Superpowers code-reviewer as a complementary 4th channel |
+| `scaffold run review-pr` | Run all 3 code review channels (Codex CLI, Gemini CLI, Claude CLI) on a PR, plus Superpowers code-reviewer as a complementary 4th channel |
+| `scaffold run post-implementation-review` | Full codebase review (Codex CLI, Gemini CLI, Superpowers code-reviewer) after an AI agent completes all tasks |
 | `scaffold run session-analyzer` | Analyze Claude Code session logs for patterns and insights |
 
 **Display rules:**
@@ -240,7 +240,8 @@ Respond to these natural language requests:
 | "Is X applicable?" / "Do I need X?" | Run `scaffold check <step>` to detect platform and brownfield status |
 | "Set up memory" / "Configure AI memory" / "Add memory" | Run `scaffold run ai-memory-setup` — sets up modular rules, optional MCP memory server, and external context |
 | "Set up testing" / "Add Playwright" / "Add Maestro" | Run `scaffold run add-e2e-testing` — auto-detects web/mobile and configures the right framework(s) |
-| "Run multi-model review" / "Review stories with other models" | Run `scaffold run review-user-stories` at depth 5 (multi-model capabilities are now built into review-user-stories) |
+| "Run multi-model review" / "Review X with all three models" | Route by target — see [Multi-Model Review Routing](#multi-model-review-routing) |
+| "Review stories with other models" | Run `scaffold run review-user-stories` at depth 5 (multi-model capabilities are built into review-user-stories) |
 | "Skip X" | Run `scaffold skip <step> --reason "<user's reason>"` |
 | "Skip X, Y, and Z" | Run `scaffold skip <step1> <step2> <step3> --reason "<reason>"` |
 | "What's left?" / "Show remaining" | Run `scaffold status --compact`, show only pending/in-progress steps |
@@ -338,28 +339,73 @@ scaffold check add-e2e-testing
 
 This is useful when the user asks "Do I need this step?" or when previewing which optional steps apply before running them.
 
+### Multi-Model Review Routing
+
+When the user asks for a "multi-model review", "review this with all three models",
+"run MMR on X", or similar — **do not assume the target is a PR**. Route based on
+what the user is pointing at:
+
+| Target | Command |
+|---|---|
+| GitHub PR (explicit number or current branch's PR) | `scaffold run review-pr [<PR#>]` |
+| Local uncommitted / staged code, before commit or push | `scaffold run review-code` |
+| Pending edits to a tracked file (changes since HEAD) | `git diff HEAD -- <path> \| mmr review --diff - --sync --format json` |
+| Current contents of any file (tracked-with-no-changes, untracked, or brand-new) | `(diff -u /dev/null <path> \|\| true) \| mmr review --diff - --sync --format json` |
+| A branch diff against main (or another ref) | `mmr review --base <ref> --head <ref> --sync --format json` |
+| An existing patch or diff file | `mmr review --diff <path.patch> --sync --format json` |
+| A diff piped from another command | `<cmd> \| mmr review --diff - --sync --format json` (stdin) |
+| A user-story review specifically at depth 5 | `scaffold run review-user-stories` |
+
+If the user's target is ambiguous ("review this with MMR"), ask once which of
+the above applies — don't default to `review-pr` just because it's the most
+common entry point. Doc reviews and uncommitted-work reviews are equally
+first-class.
+
+Pass `--focus "..."` to MMR when the user describes what to evaluate (clarity,
+completeness, security, performance, etc.). See the `mmr` skill for all input
+modes and flags.
+
+**Note on `--diff`:** the flag requires diff-format content (path to a
+`.patch`/`.diff` file, or `-` for stdin). To review a regular document or
+source file, wrap it in a diff first using `git diff HEAD -- <path>`
+(tracked) or `(diff -u /dev/null <path> || true)` (untracked — the
+`|| true` guard is required because `diff` exits 1 whenever files
+differ, which breaks pipelines under `set -o pipefail`) and pipe the
+result into `mmr review --diff -`.
+
 ### Multi-Model Review at Depth 4-5
 
-All review and validation steps now support independent multi-model validation at depth 4-5 using Codex and/or Gemini CLIs. The `multi-model-dispatch` skill documents the correct invocation patterns:
+All review and validation steps support independent multi-model validation at depth 4-5. Two distinct paths exist — **never mix them** — pick based on what step is running:
 
-- **Codex**: `codex exec --skip-git-repo-check -s read-only --ephemeral "prompt" 2>/dev/null` (NOT bare `codex`)
-- **Gemini**: `NO_BROWSER=true gemini -p "prompt" --output-format json --approval-mode yolo 2>/dev/null`
+#### Path A: MMR-backed review (PREFERRED — always use for these steps)
 
-**`NO_BROWSER=true` is required for all Gemini invocations** from Claude Code's Bash tool. Without it, Gemini's child process relaunch shows a consent prompt that hangs in non-TTY shells.
+Applies to: `scaffold run review-pr`, `scaffold run review-code`, and any pipeline review step that invokes `mmr review` directly.
 
-**Auth verification is mandatory before dispatch.** CLI tokens expire mid-session. Before running any review at depth 4-5:
-1. Check Codex auth: `codex login status`
-2. Check Gemini auth: `NO_BROWSER=true gemini -p "respond with ok" -o json` (exit 41 = auth failure)
-3. If auth fails, tell the user to re-authenticate: `! gemini -p "hello"` or `! codex login` (the `!` prefix runs it interactively with TTY access)
-4. **Never silently skip a CLI due to auth failure** — surface it to the user
+- **Channel model:** three CLIs (Codex + Gemini + Claude) dispatched and reconciled by the MMR CLI; scaffold wrappers add the Superpowers code-reviewer agent as a complementary 4th channel reconciled into the same MMR job via `mmr reconcile`.
+- **Note:** `scaffold run post-implementation-review` follows a different channel layout (raw-CLI dispatch of Codex + Gemini + Superpowers, with optional `mmr reconcile` injection if a prior `mmr review` job exists). Treat it as its own path — consult `content/tools/post-implementation-review.md` for specifics.
+- **Invocation:** go through the wrapper (`scaffold run …`) or call `mmr review …` directly. Do NOT shell out to `codex`/`gemini`/`claude` yourself for these steps — MMR handles dispatch, parsing, compensating passes, and verdict.
+- **Auth pre-flight:** run `mmr config test` once per session — it probes all three CLIs and reports status in one call.
+- **If auth fails** for any channel, surface recovery commands to the user: `! codex login`, `! gemini -p "hello"`, or `! claude login`. MMR will emit a compensating pass (via `claude -p`) for each missing external channel, labelled `[compensating: Codex-equivalent]` / `[compensating: Gemini-equivalent]`. Maximum achievable verdict in that case is `degraded-pass`.
+- **Never silently skip a CLI due to auth failure** — surface it to the user.
+
+#### Path B: Legacy / non-MMR direct dispatch
+
+Applies to: some older depth-5 validation steps and any ad-hoc manual dispatch not routed through MMR. The `multi-model-dispatch` skill documents the raw invocation patterns:
+
+- **Codex:** `codex exec --skip-git-repo-check -s read-only --ephemeral "prompt" 2>/dev/null` (NOT bare `codex`)
+- **Gemini:** `NO_BROWSER=true gemini -p "prompt" --output-format json --approval-mode yolo 2>/dev/null`
+- **Claude CLI:** `claude -p "prompt" --output-format json 2>/dev/null`
+
+**`NO_BROWSER=true` is required for all Gemini invocations** from Claude Code's Bash tool. Without it, Gemini's child process relaunch shows a consent prompt that hangs in non-TTY shells.
 
-When running a review step at depth 4-5:
-1. Check CLI availability before dispatching
-2. If both available, run dual-model review for highest quality
-3. If one available, run single-model external review
-4. If neither available, fall back to Claude-only adversarial self-review
+Auth pre-flight for Path B dispatch:
+1. Codex: `codex login status`
+2. Gemini: `NO_BROWSER=true gemini -p "respond with ok" -o json` (exit 41 = auth failure)
+3. Claude CLI: `claude -p "respond with ok"` (typically uses the active Claude Code session)
+4. If any fail: `! codex login`, `! gemini -p "hello"`, or `! claude login` (the `!` prefix runs it interactively with TTY access).
+5. **Never silently skip a CLI due to auth failure** — surface it to the user.
 
-The runner should surface the depth choice as a decision point for review steps, noting that depth 4-5 enables multi-model validation if CLIs are available.
+The runner should surface the depth choice as a decision point for review steps, noting that depth 4-5 enables three-CLI multi-model validation when the CLIs are available.
 
 ## Batch Execution
 

package/content/tools/review-code.md

@@ -1,7 +1,7 @@
 ---
 name: review-code
 description: Run all configured code review channels on local code before commit or push
-summary: "Review the current local delivery candidate with Codex CLI, Gemini CLI, and Superpowers before committing or pushing, using staged changes, an explicit ref range, or the current branch diff."
+summary: "Review the current local delivery candidate with the three MMR CLI channels (Codex CLI, Gemini CLI, Claude CLI) plus the Superpowers code-reviewer agent as a complementary 4th channel reconciled into the same MMR job, before committing or pushing. Supports staged changes, an explicit ref range, or the full local delivery candidate (committed branch diff + staged + unstaged); untracked files are not included."
 phase: null
 order: null
 dependencies: []
@@ -15,15 +15,27 @@ argument-hint: "[--base <ref>] [--head <ref>] [--staged] [--report-only]"
 
 ## Purpose
 
-Run the same three-channel review stack used by `review-pr`, but on local code
-before commit or push. This is the preflight review entry point for bug fixes,
-small features, and quick tasks when the user wants multi-model review before
-anything leaves the machine.
+Run the same review stack used by `review-pr` (three MMR CLI channels plus
+the Superpowers code-reviewer agent as a complementary 4th channel), but on
+local code before commit or push. This is the preflight review entry point
+for bug fixes, small features, and quick tasks when the user wants
+multi-model review before anything leaves the machine.
 
-The three channels are:
+The three CLI channels are:
 1. **Codex CLI** — implementation correctness, security, API contracts
 2. **Gemini CLI** — architectural patterns, broad-context reasoning
-3. **Claude CLI** — Claude subagent review of code quality, tests, and plan alignment
+3. **Claude CLI** — code quality, tests, and plan alignment
+
+Plus the 4th channel:
+4. **Superpowers code-reviewer** — agent-based review dispatched via the
+   `superpowers:code-reviewer` skill, reconciled into the same MMR job via
+   `mmr reconcile` for a unified verdict.
+
+Scope: the full local delivery candidate (committed branch diff + staged +
+unstaged changes) by default, or a narrower slice when `--staged` or
+`--base`/`--head` flags are provided. **Untracked files are not reviewed** —
+use `(diff -u /dev/null <path> || true) | mmr review --diff -` directly for
+brand-new files.
 
 ## Inputs
 
@@ -40,7 +52,7 @@ The three channels are:
 
 ## Expected Outputs
 
-- A three-channel review summary for the local delivery candidate
+- A reconciled four-channel review summary for the local delivery candidate (three MMR CLI channels + Superpowers code-reviewer)
 - One of these verdicts: `pass`, `degraded-pass`, `blocked`, `needs-user-decision`
 - Fixed code when findings are resolved in normal mode
 
@@ -48,16 +60,58 @@ The three channels are:
 
 ### Primary: MMR CLI + Agent Reconcile
 
-When the MMR CLI is installed, use it as the primary entry point:
+When the MMR CLI is installed, use it as the primary entry point. Pick the
+invocation that matches the scope the user asked for:
 
 ```bash
-# Staged changes
+# Default (no flags) — full local delivery candidate:
+# committed branch diff (vs origin/main or main) + staged + unstaged.
+# `mmr review` with no input flags defaults to `git diff` alone
+# (unstaged only), so we MUST synthesize the combined bundle explicitly
+# and pipe it in via --diff -:
+# Resolve the TRUNK ref (not the branch's own upstream — we want the
+# full delivery candidate, not just un-pushed work). Precedence:
+# origin/HEAD (the remote's default branch) → origin/main → main →
+# origin/master → master → HEAD~1 → HEAD (working-tree-only fallback).
+# NOTE: do NOT use `@{u}` / branch upstream here — on a feature branch
+# that tracks `origin/<branch>`, `@{u}` is that remote branch, so
+# diffing against its merge-base would silently exclude already-pushed
+# branch commits from the review.
+BASE_REF=""
+if   ORIGIN_HEAD=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null); then BASE_REF="${ORIGIN_HEAD#refs/remotes/}"
+elif git rev-parse --verify origin/main   >/dev/null 2>&1; then BASE_REF=origin/main
+elif git rev-parse --verify main          >/dev/null 2>&1; then BASE_REF=main
+elif git rev-parse --verify origin/master >/dev/null 2>&1; then BASE_REF=origin/master
+elif git rev-parse --verify master        >/dev/null 2>&1; then BASE_REF=master
+elif git rev-parse --verify HEAD~1        >/dev/null 2>&1; then BASE_REF=HEAD~1
+else                                                           BASE_REF=HEAD
+fi
+# Compute the merge-base so we only review the local delivery candidate,
+# not unrelated upstream changes that have accumulated on BASE_REF since
+# the branch diverged. `git diff <merge-base>` then compares that point
+# to the working tree (including the index), giving one coherent patch
+# 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
+
+# Staged changes only:
 mmr review --staged --sync --format json
 
-# Branch diff against main
+# Branch diff against main (committed only, no staged/unstaged):
 mmr review --base main --sync --format json
+
+# Explicit ref range:
+mmr review --base <base-ref> --head <head-ref> --sync --format json
 ```
 
+Routing rules:
+- If `--staged` flag passed to the tool → use the `--staged` MMR invocation
+- If `--base`/`--head` flags passed → use the ref-range MMR invocation
+- Otherwise (no flags) → use the synthesized full-delivery-candidate form
+  above. Do NOT fall back to bare `mmr review` — it would miss committed
+  and staged work.
+
 After the CLI review completes, dispatch the agent's code-reviewer skill (4th channel) and inject findings into the MMR job for unified reconciliation:
 
 ```bash
@@ -89,11 +143,14 @@ Determine the delivery candidate to review.
 
 #### Mode A: Explicit ref range
 
-If both `BASE_REF` and `HEAD_REF` are provided:
+If `BASE_REF` is provided (with or without `HEAD_REF`):
 
 ```bash
 git rev-parse --verify "$BASE_REF"
-git rev-parse --verify "$HEAD_REF"
+# When --head is omitted, default head to HEAD so the base-only form
+# mirrors the MMR primary path (`mmr review --base <ref>`).
+HEAD_REF="${HEAD_REF:-HEAD}"
+[ "$HEAD_REF" != "HEAD" ] && git rev-parse --verify "$HEAD_REF"
 REVIEW_DIFF=$(git diff "$BASE_REF...$HEAD_REF")
 CHANGED_FILES=$(git diff --name-only "$BASE_REF...$HEAD_REF")
 ```
@@ -198,7 +255,7 @@ codex login status 2>/dev/null
 - If `codex` is not installed: skip this channel and record root-cause `not_installed`
 - If auth fails: tell the user to run `! codex login`, retry after recovery, and if recovery is not possible, record root-cause `auth_failed` and continue with the remaining channels
 
-If auth cannot be recovered, or if Codex is not installed, queue a compensating Claude self-review pass focused on implementation correctness, security, and API contracts. Label findings as `[compensating: Codex-equivalent]`. If auth check times out (~5s), retry once; if still failing, record `timeout` and queue compensating pass. This pass runs after all channel dispatch attempts complete.
+If auth cannot be recovered, or if Codex is not installed, queue a compensating Claude self-review pass focused on implementation correctness, security, and API contracts. Label findings as `[compensating: Codex-equivalent]`. If the auth check times out (the configured `channels.codex.auth.timeout`; 5s by default since Codex's check is a local file probe), retry once; if still failing, record `timeout` and queue compensating pass. This pass runs after all channel dispatch attempts complete.
 
 Build the prompt in a temporary file and pass it over stdin:
 
@@ -222,7 +279,7 @@ NO_BROWSER=true gemini -p "respond with ok" -o json 2>&1
 - If `gemini` is not installed: skip this channel and record root-cause `not_installed`
 - If auth fails (including exit 41): tell the user to run `! gemini -p "hello"`, retry after recovery, and if recovery is not possible, record root-cause `auth_failed` and continue with the remaining channels
 
-If auth cannot be recovered, or if Gemini is not installed, queue a compensating Claude self-review pass focused on architectural patterns, design reasoning, and broad context. Label findings as `[compensating: Gemini-equivalent]`. If auth check times out (~5s), retry once; if still failing, record `auth timeout` and queue compensating pass. This pass runs after all channel dispatch attempts complete.
+If auth cannot be recovered, or if Gemini is not installed, queue a compensating Claude self-review pass focused on architectural patterns, design reasoning, and broad context. Label findings as `[compensating: Gemini-equivalent]`. If the auth check times out (the configured `channels.gemini.auth.timeout`; 20s by default since Gemini's check is a full LLM round-trip), retry once; if still failing, record `auth timeout` and queue compensating pass. This pass runs after all channel dispatch attempts complete.
 
 Build the prompt in a temporary file and pass it as a single prompt string:
 
@@ -348,7 +405,8 @@ Output a concise summary in this format:
 ### Channels Executed
 - Codex CLI — root cause: [completed / not_installed / auth_failed / timeout / failed], coverage: [full / compensating (Codex-equivalent)]
 - Gemini CLI — root cause: [completed / not_installed / auth_failed / timeout / failed], coverage: [full / compensating (Gemini-equivalent)]
-- Claude CLI — root cause: [completed / not_installed / auth_failed / timeout / failed], coverage: [full / compensating]
+- Claude CLI — root cause: [completed / not_installed / auth_failed / timeout / failed], coverage: [full / none (Claude is never compensated — it IS the compensator for Codex/Gemini)]
+- Agent review (Superpowers code-reviewer, 4th channel) — [completed / skipped], injected via `mmr reconcile`
 
 ### Findings
 [consensus findings first, then single-source findings]

package/content/tools/review-pr.md

@@ -14,9 +14,28 @@ argument-hint: "<PR number or blank for current branch>"
 
 ## Purpose
 
-Run all three code review channels on a pull request and reconcile findings.
-This is the single entry point for PR code review — agents call this once instead
-of remembering three separate review invocations.
+Run the three CLI review channels (Codex, Gemini, Claude) on a pull request
+**plus** the Superpowers code-reviewer agent as a complementary 4th channel,
+and reconcile all findings through MMR. This is the single entry point for
+**PR-scoped** code review — agents call this once instead of remembering four
+separate review invocations.
+
+**For non-PR targets**, don't use this tool. Call `mmr review` directly with
+the appropriate input mode, or use `scaffold run review-code` for local
+pre-commit review:
+
+- `mmr review --staged` — staged changes
+- `mmr review --base <ref> --head <ref>` — branch diff
+- `mmr review --diff <path.patch>` — existing diff/patch file
+- `<git diff …> | mmr review --diff -` — any piped diff (including a single
+  tracked file via `git diff HEAD -- <path>`, or a new file via
+  `(diff -u /dev/null <path> || true)` — the `|| true` guard is required
+  because `diff` exits 1 whenever files differ, which breaks pipelines
+  under `set -o pipefail`)
+
+The `--diff` flag expects diff-format content; it does not read raw document
+content. The three-channel review itself is not PR-specific — this tool is
+just the PR wrapper around the more general `mmr review` CLI.
 
 The three channels are:
 1. **Codex CLI** — OpenAI's code analysis (implementation correctness, security, API contracts)
@@ -34,7 +53,7 @@ in the review criteria config rather than read at dispatch time.
 
 ## Expected Outputs
 
-- All three review channels executed (or fallback documented)
+- 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
 - Review summary with per-channel results and reconciliation
 
@@ -161,7 +180,7 @@ Output a review summary in this format:
 ### Channels Executed
 - [ ] Codex CLI — root cause: [completed / not installed / auth failed / timeout / failed], coverage: [full / compensating (Codex-equivalent)]
 - [ ] Gemini CLI — root cause: [completed / not installed / auth failed / timeout / failed], coverage: [full / compensating (Gemini-equivalent)]
-- [ ] Claude CLI — root cause: [completed / not_installed / auth_failed / timeout / failed], coverage: [full / compensating]
+- [ ] Claude CLI — root cause: [completed / not_installed / auth_failed / timeout / failed], coverage: [full / none (Claude is never compensated — it IS the compensator for Codex/Gemini)]
 - [ ] Agent review — [completed / skipped], injected via mmr reconcile
 
 ### Consensus Findings (High Confidence)
@@ -226,7 +245,7 @@ Do NOT proceed to the next task or merge until this confirmation is output.
 ## Process Rules
 
 1. **Foreground only** — Always run Codex, Gemini, and Claude CLI commands as foreground Bash calls. Never use `run_in_background`, `&`, or `nohup`.
-2. **All three channels are mandatory** — Codex CLI, Gemini CLI, and Claude CLI. Skip only when a tool is genuinely not installed, never by choice.
+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.

package/dist/cli/commands/check.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"check.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/check.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,OAAO,CAAA;AAW1C,UAAU,SAAS;IACjB,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,KAAK,CAAC,EAAE,OAAO,CAAA;CAChB;AA+FD,QAAA,MAAM,YAAY,EAAE,aAAa,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,SAAS,CA0NnE,CAAA;AAED,eAAe,YAAY,CAAA"}
+{"version":3,"file":"check.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/check.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,OAAO,CAAA;AAW1C,UAAU,SAAS;IACjB,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,KAAK,CAAC,EAAE,OAAO,CAAA;CAChB;AA+FD,QAAA,MAAM,YAAY,EAAE,aAAa,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,SAAS,CAmOnE,CAAA;AAED,eAAe,YAAY,CAAA"}