remediation.

Phase 1: State Initialization & Persistence

Unlike ephemeral CLI sessions, the pipeline requires a durable state layer. We serialize review metadata, aggregated findings, and user annotations into a versioned JSON artifact. This enables context clearing between stages without losing historical analysis. The state file acts as the single source of truth, allowing agents to read previous outputs and write new findings without cross-contamination.

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;
}

Phase 2: Parallel Agent Dispatch

The analysis phase spawns isolated agent instances, each scoped to a specific analytical domain. Instead of a single prompt handling all concerns, we route the diff to specialized workers. This isolation prevents attention dilution and allows tailored system prompts, tool access, and output schemas per domain.

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.

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.