refactor: Optimize review cycle dashboard generation and merge JSON state files

Changes: - Dashboard generation: Split piped command into 4 independent steps (cp + 3x sed -i) for higher success rate - JSON consolidation: Merge review-metadata.json into review-state.json (2 files instead of 3) - Enhanced constraints: Add mandatory template usage requirements and post-generation modification prohibitions - Updated documentation: Sync changes across review-module-cycle and review-session-cycle Benefits: - Reduced command execution failures with independent steps - Simplified state management with unified metadata+state JSON - Clearer orchestrator/agent boundaries for dashboard interaction
2026-02-05 01:50:27 +08:00 · 2025-11-26 15:32:56 +08:00
parent 34a9a23d5b
commit 2cf8efec74
2 changed files with 71 additions and 36 deletions
--- a/.claude/commands/workflow/review-module-cycle.md
+++ b/.claude/commands/workflow/review-module-cycle.md
@@ -218,21 +218,32 @@ done
  ```

 **Step 4: Initialize Review State**
- Metadata creation: Create `review-metadata.json` with scope, dimensions, and configuration
- State initialization: Create `review-state.json` with dimensions, max_iterations, resolved_files
+- State initialization: Create `review-state.json` with metadata, dimensions, max_iterations, resolved_files (merged metadata + state)
 - Progress tracking: Create `review-progress.json` for dashboard polling

 **Step 5: Dashboard Generation**
-```bash
-# Copy template and replace placeholders in one command
-cat ~/.claude/templates/review-cycle-dashboard.html \
-  | sed "s|{{SESSION_ID}}|${sessionId}|g" \
-  | sed "s|{{REVIEW_TYPE}}|module|g" \
-  | sed "s|{{REVIEW_DIR}}|${reviewDir}|g" \
-  > ${sessionDir}/.review/dashboard.html

-# Output path to user
-echo "📊 Dashboard: file://${absolutePath}/.review/dashboard.html"
+**Constraints**:
+- **MANDATORY**: Dashboard MUST be generated from template: `~/.claude/templates/review-cycle-dashboard.html`
+- **PROHIBITED**: Direct creation or custom generation without template
+- **POST-GENERATION**: Orchestrator and agents MUST NOT read/write/modify dashboard.html after creation
+
+**Generation Commands** (3 independent steps):
+```bash
+# Step 1: Copy template to output location
+cp ~/.claude/templates/review-cycle-dashboard.html ${sessionDir}/.review/dashboard.html
+
+# Step 2: Replace SESSION_ID placeholder
+sed -i "s|{{SESSION_ID}}|${sessionId}|g" ${sessionDir}/.review/dashboard.html
+
+# Step 3: Replace REVIEW_TYPE placeholder
+sed -i "s|{{REVIEW_TYPE}}|module|g" ${sessionDir}/.review/dashboard.html
+
+# Step 4: Replace REVIEW_DIR placeholder
+sed -i "s|{{REVIEW_DIR}}|${reviewDir}|g" ${sessionDir}/.review/dashboard.html
+
+# Output: Dashboard path
+echo "📊 Dashboard: file://$(cd ${sessionDir} && pwd)/.review/dashboard.html"
 ```

 **Step 6: TodoWrite Initialization**
@@ -274,8 +285,7 @@ echo "📊 Dashboard: file://${absolutePath}/.review/dashboard.html"

 ```
 .workflow/active/WFS-{session-id}/.review/
-├── review-metadata.json                 # Review configuration and scope
-├── review-state.json                    # Orchestrator state machine
+├── review-state.json                    # Orchestrator state machine (includes metadata)
 ├── review-progress.json                 # Real-time progress for dashboard
 ├── dimensions/                          # Per-dimension results
 │   ├── security.json
@@ -311,22 +321,26 @@ echo "📊 Dashboard: file://${absolutePath}/.review/dashboard.html"

 ### Review State JSON

-**Purpose**: Persisted state machine for phase transitions and iteration control
+**Purpose**: Unified state machine and metadata (merged from metadata + state)

 ```json
 {
  "review_id": "review-20250125-143022",
  "review_type": "module",
  "session_id": "WFS-auth-system",
-  "target_pattern": "src/auth/**",
-  "resolved_files": [
-    "src/auth/service.ts",
-    "src/auth/validator.ts",
-    "src/auth/middleware.ts"
-  ],
+  "metadata": {
+    "created_at": "2025-01-25T14:30:22Z",
+    "target_pattern": "src/auth/**",
+    "resolved_files": [
+      "src/auth/service.ts",
+      "src/auth/validator.ts",
+      "src/auth/middleware.ts"
+    ],
+    "dimensions": ["security", "architecture", "quality", "action-items", "performance", "maintainability", "best-practices"],
+    "max_iterations": 3
+  },
  "phase": "parallel|aggregate|iterate|complete",
  "current_iteration": 1,
-  "max_iterations": 3,
  "dimensions_reviewed": ["security", "architecture", "quality", "action-items", "performance", "maintainability", "best-practices"],
  "selected_strategy": "comprehensive",
  "next_action": "execute_parallel_reviews|aggregate_findings|execute_deep_dive|generate_final_report|complete",
--- a/.claude/commands/workflow/review-session-cycle.md
+++ b/.claude/commands/workflow/review-session-cycle.md
@@ -198,21 +198,32 @@ git log --since="${sessionCreatedAt}" --name-only --pretty=format: | sort -u
  ```

 **Step 5: Initialize Review State**
- Metadata creation: Create `review-metadata.json` with scope, dimensions, and configuration
- State initialization: Create `review-state.json` with dimensions, max_iterations
+- State initialization: Create `review-state.json` with metadata, dimensions, max_iterations (merged metadata + state)
 - Progress tracking: Create `review-progress.json` for dashboard polling

 **Step 6: Dashboard Generation**
-```bash
-# Copy template and replace placeholders in one command
-cat ~/.claude/templates/review-cycle-dashboard.html \
-  | sed "s|{{SESSION_ID}}|${sessionId}|g" \
-  | sed "s|{{REVIEW_TYPE}}|session|g" \
-  | sed "s|{{REVIEW_DIR}}|${reviewDir}|g" \
-  > ${sessionDir}/.review/dashboard.html

-# Output path to user
-echo "📊 Dashboard: file://${absolutePath}/.review/dashboard.html"
+**Constraints**:
+- **MANDATORY**: Dashboard MUST be generated from template: `~/.claude/templates/review-cycle-dashboard.html`
+- **PROHIBITED**: Direct creation or custom generation without template
+- **POST-GENERATION**: Orchestrator and agents MUST NOT read/write/modify dashboard.html after creation
+
+**Generation Commands** (3 independent steps):
+```bash
+# Step 1: Copy template to output location
+cp ~/.claude/templates/review-cycle-dashboard.html ${sessionDir}/.review/dashboard.html
+
+# Step 2: Replace SESSION_ID placeholder
+sed -i "s|{{SESSION_ID}}|${sessionId}|g" ${sessionDir}/.review/dashboard.html
+
+# Step 3: Replace REVIEW_TYPE placeholder
+sed -i "s|{{REVIEW_TYPE}}|session|g" ${sessionDir}/.review/dashboard.html
+
+# Step 4: Replace REVIEW_DIR placeholder
+sed -i "s|{{REVIEW_DIR}}|${reviewDir}|g" ${sessionDir}/.review/dashboard.html
+
+# Output: Dashboard path
+echo "📊 Dashboard: file://$(cd ${sessionDir} && pwd)/.review/dashboard.html"
 ```

 **Step 7: TodoWrite Initialization**
@@ -254,8 +265,7 @@ echo "📊 Dashboard: file://${absolutePath}/.review/dashboard.html"

 ```
 .workflow/active/WFS-{session-id}/.review/
-├── review-metadata.json                 # Review configuration and scope
-├── review-state.json                    # Orchestrator state machine
+├── review-state.json                    # Orchestrator state machine (includes metadata)
 ├── review-progress.json                 # Real-time progress for dashboard
 ├── dimensions/                          # Per-dimension results
 │   ├── security.json
@@ -291,15 +301,26 @@ echo "📊 Dashboard: file://${absolutePath}/.review/dashboard.html"

 ### Review State JSON

-**Purpose**: Persisted state machine for phase transitions and iteration control
+**Purpose**: Unified state machine and metadata (merged from metadata + state)

 ```json
 {
  "session_id": "WFS-payment-integration",
  "review_id": "review-20250125-143022",
+  "review_type": "session",
+  "metadata": {
+    "created_at": "2025-01-25T14:30:22Z",
+    "git_changes": {
+      "commit_range": "abc123..def456",
+      "files_changed": 15,
+      "insertions": 342,
+      "deletions": 128
+    },
+    "dimensions": ["security", "architecture", "quality", "action-items", "performance", "maintainability", "best-practices"],
+    "max_iterations": 3
+  },
  "phase": "parallel|aggregate|iterate|complete",
  "current_iteration": 1,
-  "max_iterations": 3,
  "dimensions_reviewed": ["security", "architecture", "quality", "action-items", "performance", "maintainability", "best-practices"],
  "selected_strategy": "comprehensive",
  "next_action": "execute_parallel_reviews|aggregate_findings|execute_deep_dive|generate_final_report|complete",