Refactor review action to multi-phase orchestrator with model routing

Author: matej

.claude/agents/compliance.md

@@ -0,0 +1,8 @@
+---
+name: compliance
+model: claude-sonnet-4-20250514
+description: CLAUDE.md compliance specialist
+---
+
+Audit changed files against relevant CLAUDE.md guidance.
+Return only JSON findings with concrete rule references.

.claude/agents/quality.md

@@ -0,0 +1,8 @@
+---
+name: quality
+model: claude-opus-4-5-20251101
+description: Code quality specialist for correctness and reliability
+---
+
+Find high-signal correctness, reliability, and performance issues.
+Return only JSON findings.

.claude/agents/security.md

@@ -0,0 +1,8 @@
+---
+name: security
+model: claude-opus-4-5-20251101
+description: Security specialist for exploitable vulnerabilities
+---
+
+Find exploitable vulnerabilities in changed code with concrete attack paths.
+Return only JSON findings including exploit preconditions and trust boundary.

.claude/agents/triage.md

@@ -0,0 +1,8 @@
+---
+name: triage
+model: claude-3-5-haiku-20241022
+description: Fast PR triage for skip/continue decisions
+---
+
+Determine whether review can be skipped safely.
+Return only JSON with `skip_review`, `reason`, and `risk_level`.

.claude/agents/validator.md

@@ -0,0 +1,8 @@
+---
+name: validator
+model: claude-sonnet-4-20250514
+description: Finding validation and deduplication specialist
+---
+
+Validate candidate findings with strict confidence and impact criteria.
+Return only JSON decisions for keep/drop.

.claude/commands/review.md

@@ -40,6 +40,12 @@ To do this, follow these steps precisely:
    Agent 4: Opus security agent
    Look for security vulnerabilities in the introduced code. This includes injection, auth bypass, data exposure, unsafe deserialization, or other exploitable issues. Only look for issues that fall within the changed code.
 
+   Security evidence requirements for every reported issue:
+   - Include a concrete exploit or abuse path.
+   - Include attacker preconditions.
+   - Identify the impacted trust boundary or sensitive asset.
+   - Provide an actionable mitigation.
+
    **CRITICAL: We only want HIGH SIGNAL issues.** Flag issues where:
    - The code will fail to compile or parse (syntax errors, type errors, missing imports, unresolved references)
    - The code will definitely produce wrong results regardless of inputs (clear logic errors)
@@ -52,6 +58,7 @@ To do this, follow these steps precisely:
    - Subjective suggestions or improvements
    - Security issues that depend on speculative inputs or unverified assumptions
    - Denial of Service (DoS) or rate limiting issues without concrete exploitability
+   - Findings based only on diff snippets without validating surrounding repository context
 
    If you are not certain an issue is real, do not flag it. False positives erode trust and waste reviewer time.
 

README.md

@@ -60,6 +60,11 @@ This action is not hardened against prompt injection attacks and should only be
 | `upload-results` | Whether to upload results as artifacts | `true` | No |
 | `exclude-directories` | Comma-separated list of directories to exclude from scanning | None | No |
 | `claude-model` | Claude [model name](https://docs.anthropic.com/en/docs/about-claude/models/overview#model-names) to use. Defaults to Opus 4.5. | `claude-opus-4-5-20251101` | No |
+| `model-triage` | Model used for triage phase (skip/continue decision). | `claude-3-5-haiku-20241022` | No |
+| `model-compliance` | Model used for CLAUDE.md compliance phase. | `claude-sonnet-4-20250514` | No |
+| `model-quality` | Model used for code quality phase. | `claude-opus-4-5-20251101` | No |
+| `model-security` | Model used for security phase. | `claude-opus-4-5-20251101` | No |
+| `model-validation` | Model used for finding validation phase. | `claude-sonnet-4-20250514` | No |
 | `claudecode-timeout` | Timeout for ClaudeCode analysis in minutes | `20` | No |
 | `run-every-commit` | Run ClaudeCode on every commit (skips cache check). Warning: May increase false positives on PRs with many commits. | `false` | No |
 | `false-positive-filtering-instructions` | Path to custom false positive filtering instructions text file | None | No |
@@ -68,6 +73,7 @@ This action is not hardened against prompt injection attacks and should only be
 | `dismiss-stale-reviews` | Dismiss previous bot reviews when posting a new review (useful for follow-up commits) | `true` | No |
 | `skip-draft-prs` | Skip code review on draft pull requests | `true` | No |
 | `require-label` | Only run review if this label is present. Leave empty to review all PRs. Add `labeled` to your workflow `pull_request` types to trigger on label addition. | None | No |
+| `max-diff-lines` | Maximum inline diff lines included as prompt anchor; repository tool reads are still required in all cases. | `5000` | No |
 
 ### Action Outputs
 
@@ -94,11 +100,12 @@ claudecode/
 
 ### Workflow
 
-1. **PR Analysis**: When a pull request is opened, Claude analyzes the diff to understand what changed
-2. **Contextual Review**: Claude examines the code changes in context, understanding the purpose and potential impacts
-3. **Finding Generation**: Issues are identified with detailed explanations, severity ratings, and remediation guidance
-4. **False Positive Filtering**: Advanced filtering removes low-impact or false positive prone findings to reduce noise
-5. **PR Comments**: Findings are posted as review comments on the specific lines of code
+1. **Triage Phase**: A fast triage pass determines if review should proceed.
+2. **Context Discovery**: Claude discovers relevant CLAUDE.md files, hotspots, and risky code paths.
+3. **Specialist Review**: Dedicated compliance, quality, and security phases run with configurable models.
+4. **Validation Phase**: Candidate findings are validated and deduplicated for high signal.
+5. **False Positive Filtering**: Additional filtering removes low-impact noise.
+6. **PR Comments**: Findings are posted as review comments on specific lines in the PR.
 
 ## Review Capabilities
 

action.yml

@@ -33,6 +33,31 @@ inputs:
     required: false
     default: ''
 
+  model-triage:
+    description: 'Model for triage phase'
+    required: false
+    default: 'claude-3-5-haiku-20241022'
+
+  model-compliance:
+    description: 'Model for CLAUDE.md compliance phase'
+    required: false
+    default: 'claude-sonnet-4-20250514'
+
+  model-quality:
+    description: 'Model for code quality phase'
+    required: false
+    default: 'claude-opus-4-5-20251101'
+
+  model-security:
+    description: 'Model for security phase'
+    required: false
+    default: 'claude-opus-4-5-20251101'
+
+  model-validation:
+    description: 'Model for validation phase'
+    required: false
+    default: 'claude-sonnet-4-20250514'
+
   run-every-commit:
     description: 'Run ClaudeCode on every commit (skips cache check). Warning: This may lead to more false positives on PRs with many commits as the AI analyzes the same code multiple times.'
     required: false
@@ -231,6 +256,11 @@ runs:
         CUSTOM_REVIEW_INSTRUCTIONS: ${{ inputs.custom-review-instructions }}
         CUSTOM_SECURITY_SCAN_INSTRUCTIONS: ${{ inputs.custom-security-scan-instructions }}
         CLAUDE_MODEL: ${{ inputs.claude-model }}
+        MODEL_TRIAGE: ${{ inputs.model-triage }}
+        MODEL_COMPLIANCE: ${{ inputs.model-compliance }}
+        MODEL_QUALITY: ${{ inputs.model-quality }}
+        MODEL_SECURITY: ${{ inputs.model-security }}
+        MODEL_VALIDATION: ${{ inputs.model-validation }}
         CLAUDECODE_TIMEOUT: ${{ inputs.claudecode-timeout }}
         MAX_DIFF_LINES: ${{ inputs.max-diff-lines }}
         ACTION_PATH: ${{ github.action_path }}

claudecode/__init__.py

@@ -12,11 +12,16 @@
 from claudecode.github_action_audit import (
     GitHubActionClient,
     SimpleClaudeRunner,
+    get_review_model_config,
     main
 )
+from claudecode.review_orchestrator import ReviewModelConfig, ReviewOrchestrator
 
 __all__ = [
     "GitHubActionClient",
     "SimpleClaudeRunner",
+    "ReviewModelConfig",
+    "ReviewOrchestrator",
+    "get_review_model_config",
     "main"
 ]

claudecode/findings_merge.py

@@ -0,0 +1,61 @@
+"""Utilities for merging and deduplicating findings from multiple phases."""
+
+from typing import Any, Dict, List, Tuple
+
+
+def _normalize_text(value: Any) -> str:
+    return str(value or "").strip().lower()
+
+
+def _finding_key(finding: Dict[str, Any]) -> Tuple[str, int, str, str]:
+    file_path = _normalize_text(finding.get("file"))
+    line = finding.get("line")
+    try:
+        line_no = int(line)
+    except (TypeError, ValueError):
+        line_no = 1
+    category = _normalize_text(finding.get("category"))
+    title = _normalize_text(finding.get("title"))
+    return file_path, line_no, category, title
+
+
+def _severity_rank(value: Any) -> int:
+    sev = _normalize_text(value).upper()
+    if sev == "HIGH":
+        return 3
+    if sev == "MEDIUM":
+        return 2
+    if sev == "LOW":
+        return 1
+    return 0
+
+
+def _confidence_value(value: Any) -> float:
+    try:
+        return float(value)
+    except (TypeError, ValueError):
+        return 0.0
+
+
+def merge_findings(findings: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
+    """Merge duplicate findings and keep the strongest candidate."""
+    merged: Dict[Tuple[str, int, str, str], Dict[str, Any]] = {}
+
+    for finding in findings:
+        if not isinstance(finding, dict):
+            continue
+
+        key = _finding_key(finding)
+        existing = merged.get(key)
+
+        if existing is None:
+            merged[key] = finding
+            continue
+
+        incoming_score = (_severity_rank(finding.get("severity")), _confidence_value(finding.get("confidence")))
+        existing_score = (_severity_rank(existing.get("severity")), _confidence_value(existing.get("confidence")))
+
+        if incoming_score > existing_score:
+            merged[key] = finding
+
+    return list(merged.values())