interface ReviewState {
  version: string;
  commitHash: string;
  baseBranch: string;
  targetFiles: string[];
  findings: FindingRecord[];
  userAnnotations: UserNote[];
  pipelineStage: 'INIT' | 'ANALYSIS' | 'VALIDATION' | 'REMEDIATION' | 'COMPLETE';
  metadata: {
    tokenBudgetUsed: number;
    lastUpdated: string;
  };
}

interface FindingRecord {
  id: string;
  stage: string;
  agentId: string;
  filePath: string;
  lineRange: [number, number];
  category: 'SECURITY' | 'PERFORMANCE' | 'MAINTAINABILITY' | 'LOGIC' | 'STYLE';
  severity: 'CRITICAL' | 'HIGH' | 'MEDIUM' | 'LOW';
  description: string;
  confidence: number;
  requiresHumanReview: boolean;
}

class AgentDispatcher {
  private registry: Map<string, AgentConfig> = new Map();

  constructor() {
    this.registry.set('security', {
      model: 'claude-code',
      systemPrompt: 'Focus exclusively on injection vectors, auth bypass, and data exposure.',
      outputSchema: 'security_finding',
      maxTokens: 4000
    });
    this.registry.set('performance', {
      model: 'claude-code',
      systemPrompt: 'Identify algorithmic inefficiencies, memory leaks, and N+1 patterns.',
      outputSchema: 'perf_finding',
      maxTokens: 3000
    });
    this.registry.set('logic', {
      model: 'claude-code',
      systemPrompt: 'Detect off-by-one errors, race conditions, and null dereferences.',
      outputSchema: 'logic_finding',
      maxTokens: 3500
    });
  }

  async executeParallel(state: ReviewState): Promise<FindingRecord[]> {
    const tasks = Array.from(this.registry.entries()).map(([id, config]) => 
      this.invokeAgent(id, config, state)
    );
    const results = await Promise.allSettled(tasks);
    return results
      .filter((r):

r is PromiseFulfilledResult<FindingRecord[]> => r.status === 'fulfilled') .flatMap(r => r.value); } }

### Phase 3: Sequential Validation & Consolidation
Parallel outputs inevitably contain overlapping or contradictory findings. A dedicated validator agent performs cross-referencing to eliminate duplicates, resolve severity conflicts, and map interdependencies. This stage applies a weighted consensus algorithm: if multiple agents flag the same code region, confidence increases. If findings conflict, the validator requests clarification or downgrades severity pending human review.

### Phase 4: Human-in-the-Loop Routing
Not all findings require immediate automated action. The pipeline integrates interactive questioning to surface ambiguous cases, domain-specific edge cases, or architectural trade-offs that exceed the model's training distribution. Using Claude Code's `AskUserQuestion` capability, the system iteratively presents low-confidence or high-impact findings, captures developer feedback, and updates the state artifact. Developers can also explicitly promote findings to critical status, overriding automated severity calculations.

### Phase 5: Safe Remediation & Regression Gating
Automated fixing is where most AI tools fail. The remediation phase groups related findings by file dependency and logical scope. Each group is assigned to a dedicated fix agent that proposes changes, stages them, and triggers a post-fix validation pass. Crucially, the pipeline runs a subset of the original analysis agents against the modified code to detect regressions. If unit tests are available, they execute synchronously. Only changes that pass both static re-validation and test suites are committed. Failed fixes are reverted, and the findings return to the state queue with updated diagnostic metadata.

```typescript
class FixCoordinator {
  async processRemediation(state: ReviewState): Promise<CommitResult> {
    const fixGroups = this.clusterByDependency(state.findings);
    const approvedChanges: Patch[] = [];

    for (const group of fixGroups) {
      const proposedPatch = await this.generateFix(group);
      const postFixState = await this.runPostFixValidation(proposedPatch, state);
      
      if (postFixState.regressionDetected) {
        this.logRejection(group, postFixState);
        continue;
      }

      const testResult = await this.executeTestSuite(proposedPatch);
      if (testResult.passed) {
        approvedChanges.push(proposedPatch);
      }
    }

    return this.applySurvivorCommit(approvedChanges);
  }
}

Architecture Rationale

• Why JSON state? Enables deterministic rollback, audit trails, and cross-session continuity. Binary or in-memory state would lose persistence across CLI restarts or context clears.
• Why parallel then sequential? Parallel execution maximizes throughput and isolates domain reasoning. Sequential validation ensures consistency, removes noise, and establishes a unified severity baseline before human intervention.
• Why fix grouping? Code changes rarely exist in isolation. Grouping by dependency graph prevents partial fixes that break compilation or introduce new defects.
• Why survivor commit? Automated remediation must be fail-safe. Committing only validated, regression-free changes prevents pipeline corruption and maintains developer trust.

Pitfall Guide

1. Context Bleed Between Agents

Explanation: When agents share unscoped state or inherit previous findings without isolation, they begin reinforcing each other's hallucinations or biases. This creates feedback loops where false positives multiply across stages. Fix: Implement strict state slicing. Each agent receives only the raw diff, its domain-specific system prompt, and a read-only snapshot of prior findings. Never allow agents to modify another agent's output directly.

2. State File Corruption & Race Conditions

Explanation: Concurrent CLI sessions or interrupted writes can corrupt the JSON state artifact, causing pipeline failures or data loss. Fix: Use atomic file writes (write to .tmp, then rename). Implement schema versioning and validation on load. Add file locking mechanisms for multi-developer environments.

3. Token Budget Exhaustion

Explanation: Unbounded agent prompts or verbose output schemas quickly consume context windows, causing truncation or API failures. Fix: Enforce strict token budgets per agent. Implement chunking strategies for large diffs. Prune low-confidence findings before validation. Use streaming responses with early termination on confidence thresholds.

4. Infinite Human Loop

Explanation: Over-reliance on interactive questioning can trap developers in endless clarification cycles, especially when confidence thresholds are set too low. Fix: Establish hard limits on interaction rounds. Auto-escalate unresolved findings to default severity after N attempts. Provide skip/defer options with audit logging.

5. Cross-Model Conflict Without Consensus Logic

Explanation: When integrating ensemble reviews (e.g., Claude + Codex CLI), conflicting outputs create ambiguity. Without a resolution strategy, teams receive contradictory recommendations. Fix: Implement a weighted consensus algorithm. Assign trust scores per model based on historical accuracy per domain. Flag conflicts for human review rather than auto-resolving.

6. Ignoring Static Dependency Graphs

Explanation: Fix agents that operate on isolated findings often break cross-file contracts, imports, or shared interfaces. Fix: Run a lightweight static analysis pre-pass to map dependencies. Use this graph to cluster findings into fix groups. Validate proposed patches against interface contracts before commit.

7. Missing Rollback & Audit Trails

Explanation: Automated fixes that pass validation but fail in staging environments leave teams without a clear path to revert or diagnose. Fix: Maintain a commit history of all AI-generated patches. Store pre-fix and post-fix diffs. Tag commits with pipeline run IDs for traceability. Provide one-click rollback commands.

Production Bundle

Action Checklist

• Initialize versioned state schema with atomic write guarantees and file locking
• Configure agent registry with isolated system prompts, output schemas, and token budgets
• Implement parallel dispatch with Promise.allSettled and graceful degradation on agent failure
• Build sequential validator with cross-referencing, duplicate elimination, and severity weighting
• Integrate interactive questioning with confidence thresholds, skip options, and round limits
• Design fix coordinator with dependency clustering, post-fix validation, and test gating
• Establish survivor commit logic with automatic revert on regression or test failure
• Add audit logging, commit tagging, and one-click rollback for all AI-generated changes

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
Small PR (<200 lines), low risk	Single-pass LLM review	Faster execution, lower token cost, sufficient for straightforward changes	Low
Medium PR (200-800 lines), cross-file changes	Multi-stage multi-agent pipeline	Isolates domains, reduces false positives, maintains state across stages	Medium
High-risk PR (security/auth, >800 lines)	Multi-agent + ensemble validation + human gating	Cross-model consensus catches subtle flaws, human routing handles domain complexity	High
Automated remediation required	Fix coordinator with regression gating	Prevents broken builds, ensures test coverage, maintains commit safety	Medium-High
CI/CD integration needed	Stateless pipeline wrapper + artifact upload	Decouples review from local CLI, enables parallel CI runs, preserves audit trails	Low

Configuration Template

review_pipeline:
  state:
    path: ".review/state.json"
    version: "2.1"
    atomic_writes: true
    max_concurrent_sessions: 3

  agents:
    security:
      model: "claude-code"
      system_prompt: "Focus on injection, auth, data exposure, and dependency vulnerabilities."
      max_tokens: 4000
      confidence_threshold: 0.75
    performance:
      model: "claude-code"
      system_prompt: "Identify algorithmic inefficiencies, memory issues, and N+1 patterns."
      max_tokens: 3000
      confidence_threshold: 0.70
    logic:
      model: "claude-code"
      system_prompt: "Detect off-by-one errors, race conditions, null dereferences, and edge cases."
      max_tokens: 3500
      confidence_threshold: 0.80

  validation:
    cross_reference: true
    severity_weighting: "consensus"
    max_conflicts_before_human: 2

  human_loop:
    ask_user_question: true
    max_interactions: 5
    auto_defer_threshold: 0.45
    promotion_allowed: true

  remediation:
    group_by_dependency: true
    post_fix_validation: true
    run_unit_tests: true
    survivor_commit: true
    rollback_on_regression: true

  ensemble:
    enabled: false
    secondary_model: "codex-cli"
    consensus_algorithm: "weighted_average"
    trust_scores:
      claude-code: 0.85
      codex-cli: 0.75

Quick Start Guide

1. Initialize the pipeline state: Run review-cli init --state-path .review/state.json --schema-version 2.1. This creates the versioned JSON artifact with atomic write configuration and default agent registry.
2. Configure agent scopes: Edit the YAML template to match your tech stack. Adjust confidence thresholds, token budgets, and domain prompts. Enable ensemble mode if cross-model validation is required.
3. Execute parallel analysis: Run review-cli analyze --diff HEAD~1..HEAD. The dispatcher spawns isolated agents, aggregates findings, and writes results to the state file.
4. Validate & route: Run review-cli validate --interactive. The sequential validator cross-references outputs, applies severity weighting, and surfaces low-confidence findings for human questioning.
5. Apply safe fixes: Run review-cli fix --test-gating. The coordinator clusters dependencies, generates patches, runs post-fix validation and tests, and commits only survivor changes. Use review-cli rollback --last if staging reveals issues.