claude-code-workflow 6.3.53 → 7.0.0

package/.codex/skills/review-cycle/phases/06-fix-discovery-batching.md

@@ -0,0 +1,238 @@
+# Phase 6: Fix Discovery & Batching
+
+> Source: `commands/workflow/review-cycle-fix.md` Phase 1 + Phase 1.5
+
+## Overview
+
+Validate fix input source, create fix session structure, and perform intelligent grouping of findings into batches for parallel planning.
+
+## Quick Start
+
+```bash
+# Fix from exported findings file (session-based path)
+review-cycle --fix ${projectRoot}/.workflow/active/WFS-123/.review/fix-export-1706184622000.json
+
+# Fix from review directory (auto-discovers latest export)
+review-cycle --fix ${projectRoot}/.workflow/active/WFS-123/.review/
+
+# Resume interrupted fix session
+review-cycle --fix --resume
+
+# Custom max retry attempts per finding
+review-cycle --fix ${projectRoot}/.workflow/active/WFS-123/.review/ --max-iterations=5
+
+# Custom batch size for parallel planning (default: 5 findings per batch)
+review-cycle --fix ${projectRoot}/.workflow/active/WFS-123/.review/ --batch-size=3
+```
+
+**Fix Source**: Exported findings from review cycle dashboard
+**Output Directory**: `{review-dir}/fixes/{fix-session-id}/` (within session .review/)
+**Default Max Iterations**: 3 (per finding, adjustable)
+**Default Batch Size**: 5 (findings per planning batch, adjustable)
+**Max Parallel Agents**: 10 (concurrent planning agents)
+**CLI Tools**: @cli-planning-agent (planning), @cli-execute-agent (fixing)
+
+## Core Concept
+
+Automated fix orchestrator with **parallel planning architecture**: Multiple AI agents analyze findings concurrently in batches, then coordinate parallel/serial execution. Generates fix timeline with intelligent grouping and dependency analysis, executes fixes with conservative test verification.
+
+**Fix Process**:
+- **Batching Phase (1.5)**: Orchestrator groups findings by file+dimension similarity, creates batches
+- **Planning Phase (2)**: Up to 10 agents plan batches in parallel, generate partial plans, orchestrator aggregates
+- **Execution Phase (3)**: Main orchestrator coordinates agents per aggregated timeline stages
+- **Parallel Efficiency**: Customizable batch size (default: 5), MAX_PARALLEL=10 agents
+- **No rigid structure**: Adapts to task requirements, not bound to fixed JSON format
+
+**vs Manual Fixing**:
+- **Manual**: Developer reviews findings one-by-one, fixes sequentially
+- **Automated**: AI groups related issues, multiple agents plan in parallel, executes in optimal parallel/serial order with automatic test verification
+
+### Value Proposition
+1. **Parallel Planning**: Multiple agents analyze findings concurrently, reducing planning time for large batches (10+ findings)
+2. **Intelligent Batching**: Semantic similarity grouping ensures related findings are analyzed together
+3. **Multi-stage Coordination**: Supports complex parallel + serial execution with cross-batch dependency management
+4. **Conservative Safety**: Mandatory test verification with automatic rollback on failure
+5. **Resume Support**: Checkpoint-based recovery for interrupted sessions
+
+### Orchestrator Boundary (CRITICAL)
+- **ONLY command** for automated review finding fixes
+- Manages: Intelligent batching (Phase 1.5), parallel planning coordination (spawn N agents), plan aggregation (merge partial plans, resolve cross-batch dependencies), stage-based execution scheduling, agent scheduling, progress tracking
+- Delegates: Batch planning to @cli-planning-agent, fix execution to @cli-execute-agent
+
+## Fix Process Overview
+
+```
+Phase 1: Discovery & Initialization
+   └─ Validate export file, create fix session structure, initialize state files
+
+Phase 1.5: Intelligent Grouping & Batching
+   ├─ Analyze findings metadata (file, dimension, severity)
+   ├─ Group by semantic similarity (file proximity + dimension affinity)
+   ├─ Create batches respecting --batch-size (default: 5)
+   └─ Output: Finding batches for parallel planning
+
+Phase 2: Parallel Planning Coordination (@cli-planning-agent × N)
+   ├─ Spawn MAX_PARALLEL planning agents concurrently (default: 10)
+   ├─ Each agent processes one batch:
+   │  ├─ Analyze findings for patterns and dependencies
+   │  ├─ Group by file + dimension + root cause similarity
+   │  ├─ Determine execution strategy (parallel/serial/hybrid)
+   │  ├─ Generate fix timeline with stages
+   │  └─ Output: partial-plan-{batch-id}.json
+   ├─ Collect results from all agents
+   └─ Aggregate: Merge partial plans → fix-plan.json (resolve cross-batch dependencies)
+
+Phase 3: Execution Orchestration (Stage-based)
+   For each timeline stage:
+   ├─ Load groups for this stage
+   ├─ If parallel: Spawn all group agents simultaneously
+   ├─ If serial: Execute groups sequentially
+   ├─ Each agent:
+   │  ├─ Analyze code context
+   │  ├─ Apply fix per strategy
+   │  ├─ Run affected tests
+   │  ├─ On test failure: Rollback, retry up to max_iterations
+   │  └─ On success: Commit, update fix-progress-{N}.json
+   └─ Advance to next stage
+
+Phase 4: Completion & Aggregation
+   └─ Aggregate results → Generate fix-summary.md → Update history → Output summary
+
+Phase 5: Session Completion (Optional)
+   └─ If all fixes successful → Prompt to complete workflow session
+```
+
+## Agent Roles
+
+| Agent | Responsibility |
+|-------|---------------|
+| **Orchestrator** | Input validation, session management, intelligent batching (Phase 1.5), parallel planning coordination (spawn N agents), plan aggregation (merge partial plans, resolve cross-batch dependencies), stage-based execution scheduling, progress tracking, result aggregation |
+| **@cli-planning-agent** | Batch findings analysis, intelligent grouping (file+dimension+root cause), execution strategy determination (parallel/serial/hybrid), timeline generation with dependency mapping, partial plan output |
+| **@cli-execute-agent** | Fix execution per group, code context analysis, Edit tool operations, test verification, git rollback on failure, completion JSON generation |
+
+## Parallel Planning Architecture
+
+**Batch Processing Strategy**:
+
+| Phase | Agent Count | Input | Output | Purpose |
+|-------|-------------|-------|--------|---------|
+| **Batching (1.5)** | Orchestrator | All findings | Finding batches | Semantic grouping by file+dimension, respecting --batch-size |
+| **Planning (2)** | N agents (≤10) | 1 batch each | partial-plan-{batch-id}.json | Analyze batch in parallel, generate execution groups and timeline |
+| **Aggregation (2)** | Orchestrator | All partial plans | fix-plan.json | Merge timelines, resolve cross-batch dependencies |
+| **Execution (3)** | M agents (dynamic) | 1 group each | fix-progress-{N}.json | Execute fixes per aggregated plan with test verification |
+
+**Benefits**:
+- **Speed**: N agents plan concurrently, reducing planning time for large batches
+- **Scalability**: MAX_PARALLEL=10 prevents resource exhaustion
+- **Flexibility**: Batch size customizable via --batch-size (default: 5)
+- **Isolation**: Each planning agent focuses on related findings (semantic grouping)
+- **Reusable**: Aggregated plan can be re-executed without re-planning
+
+## Intelligent Grouping Strategy
+
+**Three-Level Grouping**:
+
+```javascript
+// Level 1: Primary grouping by file + dimension
+{file: "auth.ts", dimension: "security"} → Group A
+{file: "auth.ts", dimension: "quality"} → Group B
+{file: "query-builder.ts", dimension: "security"} → Group C
+
+// Level 2: Secondary grouping by root cause similarity
+Group A findings → Semantic similarity analysis (threshold 0.7)
+  → Sub-group A1: "missing-input-validation" (findings 1, 2)
+  → Sub-group A2: "insecure-crypto" (finding 3)
+
+// Level 3: Dependency analysis
+Sub-group A1 creates validation utilities
+Sub-group C4 depends on those utilities
+→ A1 must execute before C4 (serial stage dependency)
+```
+
+**Similarity Computation**:
+- Combine: `description + recommendation + category`
+- Vectorize: TF-IDF or LLM embedding
+- Cluster: Greedy algorithm with cosine similarity > 0.7
+
+## Phase 1: Discovery & Initialization (Orchestrator)
+
+**Phase 1 Orchestrator Responsibilities**:
+- Input validation: Check export file exists and is valid JSON
+- Auto-discovery: If review-dir provided, find latest `*-fix-export.json`
+- Session creation: Generate fix-session-id (`fix-{timestamp}`)
+- Directory structure: Create `{review-dir}/fixes/{fix-session-id}/` with subdirectories
+- State files: Initialize active-fix-session.json (session marker)
+- Progress tracking initialization: Set up 5-phase tracking (including Phase 1.5)
+
+## Phase 1.5: Intelligent Grouping & Batching (Orchestrator)
+
+- Load all findings metadata (id, file, dimension, severity, title)
+- Semantic similarity analysis:
+  - Primary: Group by file proximity (same file or related modules)
+  - Secondary: Group by dimension affinity (same review dimension)
+  - Tertiary: Analyze title/description similarity (root cause clustering)
+- Create batches respecting --batch-size (default: 5 findings per batch)
+- Balance workload: Distribute high-severity findings across batches
+- Output: Array of finding batches for parallel planning
+
+```javascript
+// Load findings
+const findings = JSON.parse(Read(exportFile));
+const batchSize = flags.batchSize || 5;
+
+// Semantic similarity analysis: group by file+dimension
+const batches = [];
+const grouped = new Map(); // key: "${file}:${dimension}"
+
+for (const finding of findings) {
+  const key = `${finding.file || 'unknown'}:${finding.dimension || 'general'}`;
+  if (!grouped.has(key)) grouped.set(key, []);
+  grouped.get(key).push(finding);
+}
+
+// Create batches respecting batchSize
+for (const [key, group] of grouped) {
+  while (group.length > 0) {
+    const batch = group.splice(0, batchSize);
+    batches.push({
+      batch_id: batches.length + 1,
+      findings: batch,
+      metadata: { primary_file: batch[0].file, primary_dimension: batch[0].dimension }
+    });
+  }
+}
+
+console.log(`Created ${batches.length} batches (${batchSize} findings per batch)`);
+```
+
+## Output File Structure
+
+```
+{projectRoot}/.workflow/active/WFS-{session-id}/.review/
+├── fix-export-{timestamp}.json     # Exported findings (input)
+└── fixes/{fix-session-id}/
+    ├── partial-plan-1.json         # Batch 1 partial plan (planning agent 1 output)
+    ├── partial-plan-2.json         # Batch 2 partial plan (planning agent 2 output)
+    ├── partial-plan-N.json         # Batch N partial plan (planning agent N output)
+    ├── fix-plan.json               # Aggregated execution plan (orchestrator merges partials)
+    ├── fix-progress-1.json         # Group 1 progress (planning agent init → agent updates)
+    ├── fix-progress-2.json         # Group 2 progress (planning agent init → agent updates)
+    ├── fix-progress-3.json         # Group 3 progress (planning agent init → agent updates)
+    ├── fix-summary.md              # Final report (orchestrator generates)
+    ├── active-fix-session.json     # Active session marker
+    └── fix-history.json            # All sessions history
+```
+
+**File Producers**:
+- **Orchestrator**: Batches findings (Phase 1.5), aggregates partial plans → `fix-plan.json` (Phase 2), spawns parallel planning agents
+- **Planning Agents (N)**: Each outputs `partial-plan-{batch-id}.json` + initializes `fix-progress-*.json` for assigned groups
+- **Execution Agents (M)**: Update assigned `fix-progress-{N}.json` in real-time
+
+## Output
+
+- Variables: batches (array), fixSessionId, sessionDir
+- Files: active-fix-session.json, directory structure created
+
+## Next Phase
+
+Return to orchestrator, then auto-continue to [Phase 7: Fix Parallel Planning](07-fix-parallel-planning.md).

package/.codex/skills/review-cycle/phases/07-fix-parallel-planning.md

@@ -0,0 +1,223 @@
+# Phase 7: Fix Parallel Planning
+
+> Source: `commands/workflow/review-cycle-fix.md` Phase 2
+
+## Overview
+Launch N planning agents (up to MAX_PARALLEL=10) to analyze finding batches concurrently. Each agent outputs a partial plan. Orchestrator aggregates partial plans into unified fix-plan.json.
+
+## Execution Strategy Determination
+
+**Strategy Types**:
+
+| Strategy | When to Use | Stage Structure |
+|----------|-------------|-----------------|
+| **Parallel** | All groups independent, different files | Single stage, all groups in parallel |
+| **Serial** | Strong dependencies, shared resources | Multiple stages, one group per stage |
+| **Hybrid** | Mixed dependencies | Multiple stages, parallel within stages |
+
+**Dependency Detection**:
+- Shared file modifications
+- Utility creation + usage patterns
+- Test dependency chains
+- Risk level clustering (high-risk groups isolated)
+
+## Phase 2: Parallel Planning Coordination (Orchestrator)
+
+```javascript
+const MAX_PARALLEL = 10;
+const partialPlans = [];
+
+// Process batches in chunks of MAX_PARALLEL
+for (let i = 0; i < batches.length; i += MAX_PARALLEL) {
+  const chunk = batches.slice(i, i + MAX_PARALLEL);
+  const agentIds = [];
+
+  // Step 1: Spawn agents in parallel
+  for (const batch of chunk) {
+    const agentId = spawn_agent({
+      message: planningPrompt(batch)  // See Planning Agent template below
+    });
+    agentIds.push({ agentId, batch });
+  }
+
+  console.log(`Spawned ${agentIds.length} planning agents...`);
+
+  // Step 2: Batch wait for all agents in this chunk
+  const chunkResults = wait({
+    ids: agentIds.map(a => a.agentId),
+    timeout_ms: 600000  // 10 minutes
+  });
+
+  // Step 3: Collect results from this chunk
+  for (const { agentId, batch } of agentIds) {
+    if (chunkResults.status[agentId].completed) {
+      const partialPlan = JSON.parse(Read(`${sessionDir}/partial-plan-${batch.batch_id}.json`));
+      partialPlans.push(partialPlan);
+      console.log(`Batch ${batch.batch_id} planning completed`);
+    } else {
+      console.log(`Batch ${batch.batch_id} planning failed/timed out`);
+    }
+  }
+
+  // Step 4: Cleanup agents in this chunk
+  agentIds.forEach(({ agentId }) => close_agent({ id: agentId }));
+}
+
+// Aggregate partial plans → fix-plan.json
+let groupCounter = 1;
+const groupIdMap = new Map();
+
+for (const partial of partialPlans) {
+  for (const group of partial.groups) {
+    const newGroupId = `G${groupCounter}`;
+    groupIdMap.set(`${partial.batch_id}:${group.group_id}`, newGroupId);
+    aggregatedPlan.groups.push({ ...group, group_id: newGroupId, progress_file: `fix-progress-${groupCounter}.json` });
+    groupCounter++;
+  }
+}
+
+// Merge timelines, resolve cross-batch conflicts (shared files → serialize)
+let stageCounter = 1;
+for (const partial of partialPlans) {
+  for (const stage of partial.timeline) {
+    aggregatedPlan.timeline.push({
+      ...stage, stage_id: stageCounter,
+      groups: stage.groups.map(gid => groupIdMap.get(`${partial.batch_id}:${gid}`))
+    });
+    stageCounter++;
+  }
+}
+
+// Write aggregated plan + initialize progress files
+Write(`${sessionDir}/fix-plan.json`, JSON.stringify(aggregatedPlan, null, 2));
+for (let i = 1; i <= aggregatedPlan.groups.length; i++) {
+  Write(`${sessionDir}/fix-progress-${i}.json`, JSON.stringify(initProgressFile(aggregatedPlan.groups[i-1]), null, 2));
+}
+```
+
+## Planning Agent Template (Batch Mode)
+
+```javascript
+// Spawn planning agent for a batch
+const agentId = spawn_agent({
+  message: `
+## TASK ASSIGNMENT
+
+### MANDATORY FIRST STEPS (Agent Execute)
+1. **Read role definition**: ~/.codex/agents/cli-planning-agent.md (MUST read first)
+2. Execute: ccw spec load --category planning
+
+---
+
+## Task Objective
+Analyze code review findings in batch ${batch.batch_id} and generate **partial** execution plan.
+
+## Input Data
+Review Session: ${reviewId}
+Fix Session ID: ${fixSessionId}
+Batch ID: ${batch.batch_id}
+Batch Findings: ${batch.findings.length}
+
+Findings:
+${JSON.stringify(batch.findings, null, 2)}
+
+Project Context:
+- Structure: ${projectStructure}
+- Test Framework: ${testFramework}
+- Git Status: ${gitStatus}
+
+## Output Requirements
+
+### 1. partial-plan-${batch.batch_id}.json
+Generate partial execution plan with structure:
+{
+  "batch_id": ${batch.batch_id},
+  "groups": [...],  // Groups created from batch findings (use local IDs: G1, G2, ...)
+  "timeline": [...],  // Local timeline for this batch only
+  "metadata": {
+    "findings_count": ${batch.findings.length},
+    "groups_count": N,
+    "created_at": "ISO-8601-timestamp"
+  }
+}
+
+**Key Generation Rules**:
+- **Groups**: Create groups with local IDs (G1, G2, ...) using intelligent grouping (file+dimension+root cause)
+- **Timeline**: Define stages for this batch only (local dependencies within batch)
+- **Progress Files**: DO NOT generate fix-progress-*.json here (orchestrator handles after aggregation)
+
+## Analysis Requirements
+
+### Intelligent Grouping Strategy
+Group findings using these criteria (in priority order):
+
+1. **File Proximity**: Findings in same file or related files
+2. **Dimension Affinity**: Same dimension (security, performance, etc.)
+3. **Root Cause Similarity**: Similar underlying issues
+4. **Fix Approach Commonality**: Can be fixed with similar approach
+
+**Grouping Guidelines**:
+- Optimal group size: 2-5 findings per group
+- Avoid cross-cutting concerns in same group
+- Consider test isolation (different test suites → different groups)
+- Balance workload across groups for parallel execution
+
+### Execution Strategy Determination (Local Only)
+
+**Parallel Mode**: Use when groups are independent, no shared files
+**Serial Mode**: Use when groups have dependencies or shared resources
+**Hybrid Mode**: Use for mixed dependency graphs (recommended for most cases)
+
+**Dependency Analysis**:
+- Identify shared files between groups
+- Detect test dependency chains
+- Evaluate risk of concurrent modifications
+
+### Risk Assessment
+
+For each group, evaluate:
+- **Complexity**: Based on code structure, file size, existing tests
+- **Impact Scope**: Number of files affected, API surface changes
+- **Rollback Feasibility**: Ease of reverting changes if tests fail
+
+### Test Strategy
+
+For each group, determine:
+- **Test Pattern**: Glob pattern matching affected tests
+- **Pass Criteria**: All tests must pass (100% pass rate)
+- **Test Command**: Infer from project (package.json, pytest.ini, etc.)
+
+## Output Files
+
+Write to ${sessionDir}:
+- ./partial-plan-${batch.batch_id}.json
+
+## Quality Checklist
+
+Before finalizing outputs:
+- All batch findings assigned to exactly one group
+- Group dependencies (within batch) correctly identified
+- Timeline stages respect local dependencies
+- Test patterns are valid and specific
+- Risk assessments are realistic
+`
+});
+
+// Wait for completion
+const result = wait({
+  ids: [agentId],
+  timeout_ms: 600000  // 10 minutes
+});
+
+// Cleanup
+close_agent({ id: agentId });
+```
+
+## Output
+
+- Files: `partial-plan-{batch-id}.json` (per agent), `fix-plan.json` (aggregated), `fix-progress-*.json` (initialized)
+- Progress: Mark Phase 7 completed, Phase 8 in_progress
+
+## Next Phase
+
+Return to orchestrator, then auto-continue to [Phase 8: Fix Execution](08-fix-execution.md).

package/.codex/skills/review-cycle/phases/08-fix-execution.md

@@ -0,0 +1,238 @@
+# Phase 8: Fix Execution
+
+> Source: `commands/workflow/review-cycle-fix.md` Phase 3
+
+## Overview
+Stage-based execution using aggregated fix-plan.json timeline. Each group gets a cli-execute-agent that applies fixes, runs tests, and commits on success or rolls back on failure.
+
+## Conservative Test Verification
+
+**Test Strategy** (per fix):
+
+```javascript
+// 1. Identify affected tests
+const testPattern = identifyTestPattern(finding.file);
+// e.g., "tests/auth/**/*.test.*" for src/auth/service.ts
+
+// 2. Run tests
+const result = await runTests(testPattern);
+
+// 3. Evaluate
+if (result.passRate < 100%) {
+  // Rollback
+  await gitCheckout(finding.file);
+
+  // Retry with failure context
+  if (attempts < maxIterations) {
+    const fixContext = analyzeFailure(result.stderr);
+    regenerateFix(finding, fixContext);
+    retry();
+  } else {
+    markFailed(finding.id);
+  }
+} else {
+  // Commit
+  await gitCommit(`Fix: ${finding.title} [${finding.id}]`);
+  markFixed(finding.id);
+}
+```
+
+**Pass Criteria**: 100% test pass rate (no partial fixes)
+
+## Phase 3: Execution Orchestration (Orchestrator)
+
+- Load fix-plan.json timeline stages
+- For each stage:
+  - If parallel mode: Spawn all group agents, batch wait
+  - If serial mode: Spawn groups sequentially with wait between each
+  - Assign agent IDs (agents update their fix-progress-{N}.json)
+- Handle agent failures gracefully (mark group as failed, continue)
+- Advance to next stage only when current stage complete
+- Lifecycle: spawn_agent → wait → close_agent per group/batch
+
+## Execution Agent Template (Per Group)
+
+```javascript
+// Spawn execution agent for a group
+const execAgentId = spawn_agent({
+  message: `
+## TASK ASSIGNMENT
+
+### MANDATORY FIRST STEPS (Agent Execute)
+1. **Read role definition**: ~/.codex/agents/cli-execution-agent.md (MUST read first)
+2. Execute: ccw spec load --category execution
+
+---
+
+## Task Objective
+Execute fixes for code review findings in group ${group.group_id}. Update progress file in real-time with flow control tracking.
+
+## Assignment
+- Group ID: ${group.group_id}
+- Group Name: ${group.group_name}
+- Progress File: ${sessionDir}/${group.progress_file}
+- Findings Count: ${group.findings.length}
+- Max Iterations: ${maxIterations} (per finding)
+
+## Fix Strategy
+${JSON.stringify(group.fix_strategy, null, 2)}
+
+## Risk Assessment
+${JSON.stringify(group.risk_assessment, null, 2)}
+
+## Execution Flow
+
+### Initialization (Before Starting)
+
+1. Read ${group.progress_file} to load initial state
+2. Update progress file:
+   - assigned_agent: "${agentId}"
+   - status: "in-progress"
+   - started_at: Current ISO 8601 timestamp
+   - last_update: Current ISO 8601 timestamp
+3. Write updated state back to ${group.progress_file}
+
+### Main Execution Loop
+
+For EACH finding in ${group.progress_file}.findings:
+
+#### Step 1: Analyze Context
+
+**Before Step**:
+- Update finding: status→"in-progress", started_at→now()
+- Update current_finding: Populate with finding details, status→"analyzing", action→"Reading file and understanding code structure"
+- Update phase→"analyzing"
+- Update flow_control: Add "analyze_context" step to implementation_approach (status→"in-progress"), set current_step→"analyze_context"
+- Update last_update→now(), write to ${group.progress_file}
+
+**Action**:
+- Read file: finding.file
+- Understand code structure around line: finding.line
+- Analyze surrounding context (imports, dependencies, related functions)
+- Review recommendations: finding.recommendations
+
+**After Step**:
+- Update flow_control: Mark "analyze_context" step as "completed" with completed_at→now()
+- Update last_update→now(), write to ${group.progress_file}
+
+#### Step 2: Apply Fix
+
+**Before Step**:
+- Update current_finding: status→"fixing", action→"Applying code changes per recommendations"
+- Update phase→"fixing"
+- Update flow_control: Add "apply_fix" step to implementation_approach (status→"in-progress"), set current_step→"apply_fix"
+- Update last_update→now(), write to ${group.progress_file}
+
+**Action**:
+- Use Edit tool to implement code changes per finding.recommendations
+- Follow fix_strategy.approach
+- Maintain code style and existing patterns
+
+**After Step**:
+- Update flow_control: Mark "apply_fix" step as "completed" with completed_at→now()
+- Update last_update→now(), write to ${group.progress_file}
+
+#### Step 3: Test Verification
+
+**Before Step**:
+- Update current_finding: status→"testing", action→"Running test suite to verify fix"
+- Update phase→"testing"
+- Update flow_control: Add "run_tests" step to implementation_approach (status→"in-progress"), set current_step→"run_tests"
+- Update last_update→now(), write to ${group.progress_file}
+
+**Action**:
+- Run tests using fix_strategy.test_pattern
+- Require 100% pass rate
+- Capture test output
+
+**On Test Failure**:
+- Git rollback: \`git checkout -- \${finding.file}\`
+- Increment finding.attempts
+- Update flow_control: Mark "run_tests" step as "failed" with completed_at→now()
+- Update errors: Add entry (finding_id, error_type→"test_failure", message, timestamp)
+- If finding.attempts < ${maxIterations}:
+  - Reset flow_control: implementation_approach→[], current_step→null
+  - Retry from Step 1
+- Else:
+  - Update finding: status→"completed", result→"failed", error_message→"Max iterations reached", completed_at→now()
+  - Update summary counts, move to next finding
+
+**On Test Success**:
+- Update flow_control: Mark "run_tests" step as "completed" with completed_at→now()
+- Update last_update→now(), write to ${group.progress_file}
+- Proceed to Step 4
+
+#### Step 4: Commit Changes
+
+**Before Step**:
+- Update current_finding: status→"committing", action→"Creating git commit for successful fix"
+- Update phase→"committing"
+- Update flow_control: Add "commit_changes" step to implementation_approach (status→"in-progress"), set current_step→"commit_changes"
+- Update last_update→now(), write to ${group.progress_file}
+
+**Action**:
+- Git commit: \`git commit -m "fix(${finding.dimension}): ${finding.title} [${finding.id}]"\`
+- Capture commit hash
+
+**After Step**:
+- Update finding: status→"completed", result→"fixed", commit_hash→<captured>, test_passed→true, completed_at→now()
+- Update flow_control: Mark "commit_changes" step as "completed" with completed_at→now()
+- Update last_update→now(), write to ${group.progress_file}
+
+#### After Each Finding
+
+- Update summary: Recalculate counts (pending/in_progress/fixed/failed) and percent_complete
+- If all findings completed: Clear current_finding, reset flow_control
+- Update last_update→now(), write to ${group.progress_file}
+
+### Final Completion
+
+When all findings processed:
+- Update status→"completed", phase→"done", summary.percent_complete→100.0
+- Update last_update→now(), write final state to ${group.progress_file}
+
+## Critical Requirements
+
+### Progress File Updates
+- **MUST update after every significant action** (before/after each step)
+- **Always maintain complete structure** - never write partial updates
+- **Use ISO 8601 timestamps** - e.g., "2025-01-25T14:36:00Z"
+
+### Flow Control Format
+Follow action-planning-agent flow_control.implementation_approach format:
+- step: Identifier (e.g., "analyze_context", "apply_fix")
+- action: Human-readable description
+- status: "pending" | "in-progress" | "completed" | "failed"
+- started_at: ISO 8601 timestamp or null
+- completed_at: ISO 8601 timestamp or null
+
+### Error Handling
+- Capture all errors in errors[] array
+- Never leave progress file in invalid state
+- Always write complete updates, never partial
+- On unrecoverable error: Mark group as failed, preserve state
+
+## Test Patterns
+Use fix_strategy.test_pattern to run affected tests:
+- Pattern: ${group.fix_strategy.test_pattern}
+- Command: Infer from project (npm test, pytest, etc.)
+- Pass Criteria: 100% pass rate required
+`
+});
+
+// Wait for completion
+const execResult = wait({
+  ids: [execAgentId],
+  timeout_ms: 1200000  // 20 minutes per group
+});
+
+// Cleanup
+close_agent({ id: execAgentId });
+```
+
+## Output
+- Files: fix-progress-{N}.json (updated per group), git commits
+- Progress: Mark Phase 8 completed, Phase 9 in_progress
+
+## Next Phase
+Return to orchestrator, then auto-continue to [Phase 9: Fix Completion](09-fix-completion.md).