From 7725e733b00e630d663f768b2bf91c4e1293f616 Mon Sep 17 00:00:00 2001
From: catlog22 <catlog22@github.com>
Date: Tue, 25 Nov 2025 09:08:41 +0800
Subject: [PATCH] refactor: simplify iteration-state.json by removing redundant
 fields
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Based on Gemini architectural analysis (verdict: "File necessary but simplify"):

Removed Redundant Fields:
- session_id → Derive from file path or workflow-session.json
- current_iteration → Calculate as iterations.length + 1
- max_iterations → Read from task.meta.max_iterations (single source)
- stuck_tests → Calculate by analyzing iterations[].failed_tests history
- regression_detected → Calculate from consecutive pass_rate values

Retained Essential Fields:
- current_task: Active task pointer (Resume critical)
- selected_strategy: Current iteration strategy (runtime state)
- next_action: State machine next step (Resume critical)
- iterations[]: Historical log (source of truth, cannot rebuild)

Enhanced iterations[] Array:
- Added failed_tests[] to each entry (was stuck_tests at top-level)
- Removed redundant regression_detected (calculated from pass_rate)

Benefits:
- Single source of truth (no data duplication)
- Less state to maintain and synchronize
- Clearer data ownership and calculation points
- Adheres to data normalization principles

Documentation Updates:
- Added "Purpose" and "Field Descriptions" sections
- Added "Removed Redundant Fields" with derivation logic
- Updated orchestrator responsibilities (Runtime Calculations)
- Updated agent template (Orchestrator-Calculated metadata)

Impact: File remains essential for Resume capability, but now leaner and normalized.
---
 .../commands/workflow/test-cycle-execute.md   | 55 +++++++++++++------
 1 file changed, 39 insertions(+), 16 deletions(-)

diff --git a/.claude/commands/workflow/test-cycle-execute.md b/.claude/commands/workflow/test-cycle-execute.md
index 31740748..cb0b5b76 100644
--- a/.claude/commands/workflow/test-cycle-execute.md
+++ b/.claude/commands/workflow/test-cycle-execute.md
@@ -188,7 +188,11 @@ Task(subagent_type="test-fix-agent", model="haiku", ...) x3
 - Pass rate calculation: `(passed / total) * 100` from test-results.json
 - Criticality assessment (high/medium/low)
 - Strategy selection based on context
-- Detection: stuck tests (3+ consecutive), regression (>10% drop)
+- **Runtime Calculations** (from iteration-state.json):
+  - Current iteration: `iterations.length + 1`
+  - Stuck tests: Tests appearing in `failed_tests` for 3+ consecutive iterations
+  - Regression: Compare consecutive `pass_rate` values (>10% drop)
+  - Max iterations: Read from `task.meta.max_iterations`
 - Iteration control (max 10, default)
 - CLI tool fallback chain: Gemini → Qwen → Codex
 - TodoWrite progress tracking
@@ -244,38 +248,56 @@ Task(subagent_type="test-fix-agent", model="haiku", ...) x3
 
 ### Iteration State JSON
 
+**Purpose**: Persisted state machine for iteration loop - enables Resume and historical analysis.
+
+**Simplified Structure** (removed redundant fields):
+
 ```json
 {
-  "session_id": "WFS-test-user-auth",
   "current_task": "IMPL-002",
-  "current_iteration": 3,
-  "max_iterations": 10,
   "selected_strategy": "aggressive",
+  "next_action": "execute_fix_task",
   "iterations": [
     {
       "iteration": 1,
       "pass_rate": 70,
       "strategy": "conservative",
-      "stuck_tests": [],
-      "regression_detected": false
+      "failed_tests": ["test_auth_flow", "test_user_permissions"]
     },
     {
       "iteration": 2,
       "pass_rate": 82,
-      "strategy": "conservative"
+      "strategy": "conservative",
+      "failed_tests": ["test_user_permissions", "test_token_expiry"]
     },
     {
       "iteration": 3,
       "pass_rate": 89,
       "strategy": "aggressive",
-      "stuck_tests": ["test_auth_edge_case"]
+      "failed_tests": ["test_auth_edge_case"]
     }
-  ],
-  "stuck_tests": ["test_auth_edge_case"],
-  "next_action": "execute_fix_task"
+  ]
 }
 ```
 
+**Field Descriptions**:
+- `current_task`: Pointer to active task (essential for Resume)
+- `selected_strategy`: Current iteration strategy (runtime state)
+- `next_action`: State machine next step (`execute_fix_task` | `retest` | `complete`)
+- `iterations[]`: Historical log of all iterations (source of truth for trends)
+
+**Removed Redundant Fields** (calculable from other sources):
+- ~~`session_id`~~ → Derive from file path or `workflow-session.json`
+- ~~`current_iteration`~~ → Calculate as `iterations.length + 1`
+- ~~`max_iterations`~~ → Read from `task.meta.max_iterations` (single source)
+- ~~`stuck_tests`~~ → Calculate by analyzing `iterations[].failed_tests` history
+- ~~`regression_detected`~~ → Calculate by comparing consecutive `pass_rate` values
+
+**Benefits of Simplification**:
+- Single source of truth (no duplication)
+- Less state to maintain and sync
+- Clearer data ownership
+
 ### Task JSON Template (Fix Iteration)
 
 ```json
@@ -331,12 +353,13 @@ Task(
     2. Read test output: ${session.test_output_path}
     3. Read iteration state: ${session.iteration_state_path}
 
-    ## Context Metadata
-    - Session ID: ${sessionId}
-    - Current Iteration: ${N} / ${maxIterations}
+    ## Context Metadata (Orchestrator-Calculated)
+    - Session ID: ${sessionId} (from file path)
+    - Current Iteration: ${N} (= iterations.length + 1)
+    - Max Iterations: ${maxIterations} (from task.meta.max_iterations)
     - Current Pass Rate: ${passRate}%
-    - Selected Strategy: ${selectedStrategy}
-    - Stuck Tests: ${stuckTests}
+    - Selected Strategy: ${selectedStrategy} (from iteration-state.json)
+    - Stuck Tests: ${stuckTests} (calculated from iterations[].failed_tests history)
 
     ## CLI Configuration
     - Tool Priority: gemini → qwen → codex