@zigrivers/scaffold 3.15.0 → 3.17.0

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

@@ -1,6 +1,6 @@
 ---
 name: automated-review-tooling
-description: Patterns for setting up automated PR code review using AI models (Codex, Gemini) via local CLI, including dual-model review, reconciliation, and CI integration
+description: Patterns for automated PR code review using AI CLI tools (Codex, Gemini, Claude) — orchestration, reconciliation, compensating passes, and CI integration
 topics: [code-review, automation, codex, gemini, pull-requests, ci-cd, review-tooling]
 ---
 
@@ -24,10 +24,10 @@ These are the authoritative verdict definitions. Tool files (`review-code.md`, `
 
 | Verdict | Condition |
 |---------|-----------|
-| `pass` | All configured channels ran, no unresolved P0/P1/P2 |
-| `degraded-pass` | Channels skipped, compensated, or have non-full coverage (e.g., partial timeout), no unresolved P0/P1/P2 |
-| `blocked` | Unresolved P0/P1/P2 after 3 fix rounds |
-| `needs-user-decision` | Contradictions or unresolvable findings |
+| `pass` | All channels completed, no unresolved P0/P1/P2 |
+| `degraded-pass` | Some channels unavailable, compensating passes ran, no unresolved P0/P1/P2 |
+| `blocked` | Findings at or above fix threshold remain unresolved |
+| `needs-user-decision` | No channels completed — insufficient data for a determination |
 
 **Verdict precedence:** `needs-user-decision` > `blocked` > `degraded-pass` > `pass`. When multiple conditions apply, the higher-precedence verdict wins.
 
@@ -35,13 +35,13 @@ These are the authoritative verdict definitions. Tool files (`review-code.md`, `
 
 #### Status Model
 
-`compensating` is a **coverage label** applied to a channel's output, not a replacement for the root-cause status. Each channel retains its root-cause status (`not_installed`, `auth_failed`, `auth_timeout`, `failed`) AND gains a coverage label (`compensating (X-equivalent)`) when a compensating pass ran. The fix cycle uses the **root-cause status** to decide whether to retry (never retry `not_installed`, `auth_failed`, `auth_timeout`). The report uses the **coverage label** to show the reader what ran.
+`compensating` is a **coverage label** applied to a channel's output, not a replacement for the root-cause status. Each channel retains its root-cause status (`not_installed`, `auth_failed`, `timeout`, `failed`) AND gains a coverage label (`compensating (X-equivalent)`) when a compensating pass ran. The fix cycle uses the **root-cause status** to decide whether to retry (never retry `not_installed`, `auth_failed`, `timeout`). The report uses the **coverage label** to show the reader what ran.
 
 #### Compensating Passes
 
-When an external channel (Codex or Gemini) is unavailable, run a compensating Claude self-review pass:
+When a channel (Codex or Gemini) is unavailable, the CLI dispatches a compensating pass via `claude -p`:
 
-- Same prompt structure as the missing channel, executed as a Claude self-review pass.
+- Same prompt structure as the missing channel, executed as a `claude -p` dispatch.
 - Labeled `[compensating: Codex-equivalent]` or `[compensating: Gemini-equivalent]` in the review summary.
 - Missing Codex → focus on implementation correctness, security, API contracts.
 - Missing Gemini → focus on architectural patterns, design reasoning, broad context.
@@ -49,8 +49,6 @@ When an external channel (Codex or Gemini) is unavailable, run a compensating Cl
 - 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.
 
-**Superpowers channel:** No compensating pass needed — Superpowers is a Claude subagent and is always available. If the Superpowers plugin is not installed, run available external CLIs and warn the user that review coverage is reduced.
-
 #### Foreground-Only Execution
 
 Always run Codex and Gemini CLI commands as foreground Bash calls. Never use `run_in_background`, `&`, or `nohup`. Background execution produces empty or truncated output from Codex and Gemini CLIs. Multiple foreground calls can still run in parallel if the tool runner supports parallel tool invocations.
@@ -67,7 +65,7 @@ Reconciliation normalizes findings from all channels (real and compensating) to
 
 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.
 
-Findings that appear in all three channels (Codex, Gemini, Superpowers) 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.
+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.
 
 ```bash
 # Orchestration reconciliation workflow
@@ -80,16 +78,15 @@ Findings that appear in all three channels (Codex, Gemini, Superpowers) are cons
 
 ### Channel Dispatch Pattern and Orchestration
 
-Each external channel (Codex, Gemini) follows the same dispatch pattern: check installation, check auth, then dispatch as a foreground call. If any step fails, record the root-cause status, queue a compensating pass, and continue to the next channel. The Superpowers channel is always available as a Claude subagent and does not require installation or auth checks.
+Each channel (Codex, Gemini, Claude) follows the same dispatch pattern: check installation, check auth, then dispatch as a foreground call. If any step fails, record the root-cause status, queue a compensating pass (for Codex/Gemini), and continue to the next channel.
 
 ```bash
 # Channel dispatch pattern
-# For each external channel (Codex, Gemini):
+# For each channel (codex, gemini, claude):
 #   1. command -v <tool> >/dev/null 2>&1 || { status=not_installed; queue_compensating; continue; }
 #   2. <auth_check> || { status=auth_failed; queue_compensating; continue; }
 #   3. <dispatch_foreground> || { status=failed; queue_compensating; continue; }
-# For Superpowers: dispatch subagent (always available)
-# After all: run queued compensating passes → reconcile → verdict
+# After all: run queued compensating passes (via claude -p) → reconcile → verdict
 ```
 
 After all channels and compensating passes complete, run the reconciliation workflow above and apply the verdict decision flow. Channel results and compensating-pass labels must be preserved in the review output for auditability — do not collapse or omit them even when findings are empty.
@@ -99,14 +96,14 @@ After all channels and compensating passes complete, run the reconciliation work
 When Codex is unavailable (not installed or auth failure), the orchestration proceeds as follows:
 
 1. The installation check (`command -v codex`) fails. Codex channel status is set to `not_installed`.
-2. A compensating Codex-equivalent pass is queued: a Claude self-review focused on implementation correctness, security, and API contracts.
-3. Gemini and Superpowers channels run normally.
+2. A compensating Codex-equivalent pass is queued: a `claude -p` dispatch focused on implementation correctness, security, and API contracts.
+3. Gemini and Claude channels run normally.
 4. The compensating pass runs, producing findings labeled `[compensating: Codex-equivalent]`.
-5. Reconciliation merges findings from all three sources (Gemini, Superpowers, compensating-Codex).
+5. Reconciliation merges findings from all three sources (Gemini, Claude, compensating-Codex).
 6. Maximum achievable verdict is `degraded-pass` because a real channel was absent.
 7. The review summary notes: "Codex channel: not_installed (compensating: Codex-equivalent pass ran)."
 
-**Fix-cycle channel rule:** Only re-run channels that originally completed or ran as compensating passes. `failed` channels are covered by their compensating pass and are not retried during fix rounds. Never retry a channel with status `not_installed`, `auth_failed`, or `auth_timeout` — these indicate persistent environment conditions that will not resolve between fix rounds.
+**Fix-cycle channel rule:** Only re-run channels that originally completed or ran as compensating passes. `failed` channels are covered by their compensating pass and are not retried during fix rounds. Never retry a channel with status `not_installed`, `auth_failed`, or `timeout` — these indicate persistent environment conditions that will not resolve between fix rounds.
 
 ### Verdict Decision Flow
 
@@ -114,19 +111,17 @@ Apply the following evaluation order to determine the final verdict. The first m
 
 ```
 Verdict evaluation order:
-1. Any contradictions or unresolvable findings? → needs-user-decision
+1. No channels completed? → needs-user-decision
 2. Any unresolved P0/P1/P2 after 3 fix rounds? → blocked
 3. Any channel not at full coverage? → degraded-pass
 4. All channels completed, no unresolved P0/P1/P2? → pass
 ```
 
-A "contradiction" exists when two channels report opposite conclusions about the same code location — for example, Codex flags a function as insecure while Gemini explicitly approves it. Contradictions cannot be resolved by the agent alone and must be surfaced to the user.
-
-A channel is "not at full coverage" when: it ran as a compensating pass instead of a real tool, it timed out partially, or the Superpowers plugin is not installed and available channels do not cover the full diff.
+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`. If multiple conditions apply simultaneously (for example, both a contradiction and an unresolved P0 exist), the higher-precedence verdict wins.
+**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 and no contradictions remain, 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 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.
 
 ### Security-Focused Review Checklist
 
@@ -197,4 +192,14 @@ When external CLIs are unavailable, the degraded-mode behavior defined in the Su
 5. When both external channels are unavailable, note "All findings are single-model (Claude only). External validation was unavailable." in the review summary.
 6. Never silently drop unavailable channels — always record the channel status and compensating coverage label in the review output.
 
-**Superpowers channel exception:** Superpowers is a Claude subagent and requires no external CLI or auth. It is always available as long as the Superpowers plugin is installed in the Claude Code environment. If the plugin is not installed, run available external CLIs and warn the user that review coverage is reduced — but do not run a compensating pass for Superpowers (the compensating-pass mechanism only applies to external CLIs that have an installation/auth gate).
+**Claude CLI channel:** Claude CLI handles its own auth and is generally always available. The compensating-pass mechanism applies to external CLIs (Codex, Gemini) that have an installation/auth gate. When Codex or Gemini are unavailable, compensating passes are dispatched via `claude -p` with focused prompts targeting the missing channel's strength area.
+
+### Auth Recovery Paths
+
+Each external CLI has a distinct auth recovery path. Agents should surface these directly to the user rather than silently downgrading to a compensating pass:
+
+- **Codex:** `codex login` — opens an interactive OAuth flow. After success, `codex login status` should return cleanly.
+- **Gemini:** `gemini -p "hello"` — refreshes the token if expired; `NO_BROWSER=true` is required in headless environments.
+- **Claude:** `claude auth login` if `claude -p` returns auth errors; rare in practice because Claude CLI tokens are long-lived.
+
+If the user cannot complete auth recovery within the review session, treat the channel as unavailable and document the compensating pass. Never attempt to work around auth failures by embedding credentials in review prompts or by piping through alternative providers that weren't explicitly requested.

package/content/knowledge/core/multi-model-review-dispatch.md

@@ -1,27 +1,18 @@
 ---
 name: multi-model-review-dispatch
-description: Patterns for dispatching reviews to external AI models (Codex, Gemini) at depth 4+, including fallback strategies and finding reconciliation
-topics: [multi-model, code-review, depth-scaling, codex, gemini, review-synthesis]
+description: Patterns for dispatching reviews to AI CLI tools (Codex, Gemini, Claude), including fallback strategies and finding reconciliation
+topics: [multi-model, code-review, codex, gemini, claude, review-synthesis]
 ---
 
 # Multi-Model Review Dispatch
 
-At higher methodology depths (4+), reviews benefit from independent validation by external AI models. Different models have different blind spots — Codex excels at code-centric analysis while Gemini brings strength in design and architectural reasoning. Dispatching to multiple models and reconciling their findings produces higher-quality reviews than any single model alone. This knowledge covers when to dispatch, how to dispatch, how to handle failures, and how to reconcile disagreements.
+Reviews benefit from independent validation by multiple AI models. Different models have different blind spots — Codex excels at code-centric analysis, Gemini brings strength in design and architectural reasoning, and Claude provides plan alignment and code quality assessment. Dispatching to multiple models and reconciling their findings produces higher-quality reviews than any single model alone. This knowledge covers how to dispatch, how to handle failures, and how to reconcile disagreements.
 
 ## Summary
 
 ### When to Dispatch
 
-Multi-model review activates at depth 4+ in the methodology scaling system:
-
-| Depth | Review Approach |
-|-------|----------------|
-| 1-2 | Claude-only, reduced pass count |
-| 3 | Claude-only, full pass count |
-| 4 | Full passes + one external model (if available) |
-| 5 | Full passes + multi-model with reconciliation |
-
-Dispatch is always optional. If no external model CLI is available, the review proceeds as a Claude-only enhanced review with additional self-review passes to partially compensate.
+Multi-model review runs all enabled channels on every review. The MMR CLI (`mmr review --sync`) is the primary entry point and handles dispatch, parsing, reconciliation, and verdict derivation automatically.
 
 ### Model Selection
 
@@ -29,15 +20,16 @@ Dispatch is always optional. If no external model CLI is available, the review p
 |-------|----------|----------|
 | **Codex** (OpenAI) | Code analysis, implementation correctness, API contract validation | Code reviews, security reviews, API reviews, database schema reviews |
 | **Gemini** (Google) | Design reasoning, architectural patterns, broad context understanding | Architecture reviews, PRD reviews, UX reviews, domain model reviews |
+| **Claude** (Anthropic) | Plan alignment, code quality, testing thoroughness | Code reviews, plan verification, test coverage |
 
-When both models are available at depth 5, dispatch to both and reconcile. At depth 4, choose the model best suited to the artifact type.
+All enabled channels run on every review. When a channel is unavailable, a compensating pass is dispatched via `claude -p` focused on the missing channel's strength area.
 
 ### Graceful Fallback
 
 External models are never required. The fallback chain:
 1. Attempt dispatch to selected model(s)
 2. If CLI unavailable → skip that model, note in report
-3. If timeout → use partial results if any, note incompleteness
+3. If timeout → CLI kills the process; no partial output preserved; compensating pass runs
 4. If all external models fail → Claude-only enhanced review (additional self-review passes)
 
 The review never blocks on external model availability.
@@ -82,15 +74,15 @@ If auth fails, report status `auth_failed` and surface recovery to the user:
 - Codex: "Codex auth expired — run `! codex login` to re-authenticate"
 - Gemini: "Gemini auth expired — run `! gemini -p \"hello\"` to re-authenticate"
 
-If auth check times out (~5 seconds), retry once. If still failing, report `auth_timeout`.
+If auth check times out (~5 seconds), retry once. If still failing, report `timeout`.
 If auth succeeds, report `ready` and proceed to dispatch.
 
 **Post-dispatch terminal states:**
 - `completed` — channel produced results, use normally
-- `partial_timeout` — partial output before timeout; use what was received, note incompleteness. Does NOT trigger compensating pass.
-- `failed` — crashed or unparseable output; triggers compensating pass.
+- `timeout` — channel exceeded time limit; CLI kills the process and marks it as `timeout`; triggers compensating pass
+- `failed` — crashed or unparseable output; triggers compensating pass
 
-Verdict impact: `partial_timeout` and `failed` channels mean the review is degraded. Maximum verdict is `degraded-pass` when any channel has a non-`completed` terminal state.
+Verdict impact: `timeout` and `failed` channels mean the review is degraded. Maximum verdict is `degraded-pass` when any channel has a non-`completed` terminal state.
 
 #### Prompt Formatting
 
@@ -126,10 +118,12 @@ Respond with a JSON array of findings:
     "severity": "P0|P1|P2|P3",
     "category": "coverage|consistency|correctness|completeness",
     "location": "section or line reference",
-    "finding": "description of the issue",
+    "description": "description of the issue",
     "suggestion": "recommended fix"
   }
 ]
+
+Note: `id` and `category` are optional — the CLI auto-generates IDs (F-001, F-002, ...) when omitted.
 ```
 
 #### Output Parsing
@@ -137,15 +131,11 @@ Respond with a JSON array of findings:
 External model output is parsed as JSON. Handle common parsing issues:
 - Strip markdown code fences (```json ... ```) if the model wraps output
 - Handle trailing commas in JSON arrays
-- Validate that each finding has the required fields (severity, category, finding)
+- Validate that each finding has the required fields (severity, location, description, suggestion)
 - Discard malformed entries rather than failing the entire parse
 
-Store raw output for audit:
-```
-docs/reviews/{artifact}/codex-review.json   — raw Codex findings
-docs/reviews/{artifact}/gemini-review.json  — raw Gemini findings
-docs/reviews/{artifact}/review-summary.md   — reconciled synthesis
-```
+The CLI stores raw output at `~/.mmr/jobs/{job-id}/` per channel. Review results
+are available via `mmr results <job-id>`.
 
 ### Timeout Handling
 
@@ -158,14 +148,7 @@ External model calls can hang or take unreasonably long. Set reasonable timeouts
 | Medium artifact review (2000-10000 words) | 120 seconds | Needs more processing time |
 | Large artifact review (>10000 words) | 180 seconds | Maximum reasonable wait |
 
-#### Partial Result Handling
-
-If a timeout occurs mid-response:
-1. Check if the partial output contains valid JSON entries
-2. If yes, use the valid entries and note "partial results" in the report
-3. If no, treat as a model failure and fall back
-
-Never wait indefinitely. A review that completes in 3 minutes with Claude-only findings is better than one that blocks for 10 minutes waiting for an external model.
+Never wait indefinitely. A review that completes in 3 minutes with Claude-only findings is better than one that blocks for 10 minutes waiting for an external model. When a channel times out, the CLI kills the process — no partial output is preserved. A compensating pass runs in its place.
 
 ### Finding Reconciliation
 
@@ -224,9 +207,9 @@ When synthesizing multi-model findings, classify each finding:
 # Multi-Model Review Summary: [Artifact Name]
 
 ## Models Used
-- Claude (primary reviewer)
-- Codex (external, depth 4+) — [available/unavailable/timeout]
-- Gemini (external, depth 5) — [available/unavailable/timeout]
+- Claude CLI — [available/unavailable/timeout]
+- Codex CLI — [available/unavailable/timeout]
+- Gemini CLI — [available/unavailable/timeout]
 
 ## Consensus Findings
 | # | Severity | Finding | Models | Confidence |
@@ -251,14 +234,10 @@ or areas where external models provided unique value]
 
 #### Raw JSON Preservation
 
-Always preserve the raw JSON output from external models, even after reconciliation. The raw findings serve as an audit trail and enable re-analysis if the reconciliation logic is later improved.
+Always preserve the raw JSON output from each channel, even after reconciliation. The raw findings serve as an audit trail and enable re-analysis if the reconciliation logic is later improved.
 
-```
-docs/reviews/{artifact}/
-  codex-review.json     — raw output from Codex
-  gemini-review.json    — raw output from Gemini
-  review-summary.md     — reconciled synthesis
-```
+The CLI stores raw output at `~/.mmr/jobs/{job-id}/` with per-channel result files.
+Results are accessible via `mmr results <job-id>`.
 
 ### Quality Gates
 
@@ -266,20 +245,18 @@ Minimum standards for a multi-model review to be considered complete:
 
 | Gate | Threshold | Rationale |
 |------|-----------|-----------|
-| Minimum finding count | At least 3 findings across all models | A review with zero findings likely missed something |
-| Coverage threshold | Every review pass has at least one finding or explicit "no issues found" note | Ensures all passes were actually executed |
+| Coverage threshold | Every channel has at least one finding or explicit "no issues found" note | Ensures all channels were actually executed |
 | Reconciliation completeness | All cross-model disagreements have documented resolutions | No unresolved conflicts |
-| Raw output preserved | JSON files exist for all models that were dispatched | Audit trail |
+| Raw output preserved | Per-channel results exist for all dispatched channels | Audit trail |
 
-If the primary Claude review produces zero findings and external models are unavailable, the review should explicitly note this as unusual and recommend a targeted re-review at a later stage.
+Zero findings across all channels is a valid outcome when the diff is clean.
 
 #### Degraded-Mode Gate Adaptation
 
 When channels are skipped and compensating passes are used:
 
-- **Minimum finding count** gate: compensating passes count toward the total but are not treated as separate external channels for consensus purposes.
 - **Reconciliation completeness** gate (cross-model disagreement documentation): applies whenever 2+ distinct model perspectives participate (Claude + one external counts). N/A only when Claude is the sole perspective (no external models and no compensating passes that introduce genuinely different framing).
-- **Coverage threshold** gate: compensating passes satisfy the "every pass has at least one finding or explicit no-issues note" requirement.
+- **Coverage threshold** gate: compensating passes satisfy the "every channel has at least one finding or explicit no-issues note" requirement.
 - The reconciled output must record which channels were real, which were compensating, and which were skipped, so the orchestration layer can apply appropriate verdict logic.
 
 ### Common Anti-Patterns
@@ -288,12 +265,10 @@ When channels are skipped and compensating passes are used:
 
 **Ignoring disagreements.** Two models disagree, and the reviewer picks one without analysis. Fix: disagreements are the most valuable signal in multi-model review. They identify areas of genuine ambiguity or complexity. Always investigate and document the resolution.
 
-**Dispatching at low depth.** Running external model reviews at depth 1-2 where the review scope is intentionally minimal. The external model does a full analysis anyway, producing findings that are out of scope. Fix: only dispatch at depth 4+. Lower depths use Claude-only review with reduced pass count.
-
-**No fallback plan.** The review pipeline assumes external models are always available. When Codex is down, the review fails entirely. Fix: external dispatch is always optional. The fallback to Claude-only enhanced review must be implemented and tested.
+**No fallback plan.** The review pipeline assumes external models are always available. When Codex is down, the review fails entirely. Fix: external dispatch is always optional. The CLI automatically dispatches compensating passes via `claude -p` when channels are unavailable.
 
 **Over-weighting consensus.** Two models agree on a finding, so it must be correct. But both models may share the same bias (e.g., both flag a pattern as an anti-pattern that is actually appropriate for this project's constraints). Fix: consensus increases confidence but does not guarantee correctness. All findings still require artifact-level verification.
 
 **Dispatching the full pipeline context.** Sending the entire project context (all docs, all code) to the external model. This exceeds context limits and dilutes focus. Fix: send only the artifact under review and the minimal upstream context needed for that specific review.
 
-**Ignoring partial results.** A model times out after producing 3 of 5 findings. The reviewer discards all results because the review is "incomplete." Fix: partial results are still valuable. Include them with a note about incompleteness. Three real findings are better than zero.
+**Treating a timeout as a silent skip.** A channel times out and the reviewer proceeds without documenting it. Fix: when a channel times out, record the root-cause status as `timeout`, queue a compensating pass, and include it in the review summary. The CLI kills timed-out processes — no partial output is available, but the compensating pass ensures coverage.