claude-code-workflow 7.2.29 → 7.3.0

package/.codex/skills/issue-discover/phases/01-issue-new.md

@@ -145,7 +145,7 @@ if (clarityScore >= 1 && clarityScore <= 2 && !issueData.affected_components?.le
 ```javascript
 // ONLY ask questions if clarity is low
 if (clarityScore < 2 && (!issueData.context || issueData.context.length < 20)) {
-  const answer = request_user_input({
+  const answer = functions.request_user_input({
     questions: [{
       header: "Clarify",
       id: "clarify",

package/.codex/skills/issue-discover/phases/02-discover.md

@@ -87,7 +87,7 @@ if (args.perspectives) {
   selectedPerspectives = args.perspectives.split(',').map(p => p.trim());
 } else {
   // Interactive selection via request_user_input
-  const response = request_user_input({
+  const response = functions.request_user_input({
     questions: [{
       header: "Focus",
       id: "focus",
@@ -273,7 +273,7 @@ await updateDiscoveryState(outputDir, {
 ```javascript
 const hasHighPriority = issues.some(i => i.priority === 'critical' || i.priority === 'high');
 
-await request_user_input({
+await functions.request_user_input({
   questions: [{
     header: "Next Step",
     id: "next_step",

package/.codex/skills/issue-discover/phases/03-discover-by-prompt.md

@@ -390,7 +390,7 @@ await updateDiscoveryState(outputDir, {
 });
 
 // Prompt user for next action
-await request_user_input({
+await functions.request_user_input({
   questions: [{
     header: "Next Step",
     id: "next_step",

package/.codex/skills/issue-discover/phases/04-quick-execute.md

@@ -157,7 +157,7 @@ Quick Execute Summary:
 request_user_input:
 
 ```javascript
-request_user_input({
+functions.request_user_input({
   questions: [{
     header: "Confirm",
     id: "confirm_execute",
@@ -212,7 +212,7 @@ for each task in sortedTasks:
 // 计算未执行 findings
 const remainingFindings = allFindings.filter(f => !executedFindingIds.has(f.id))
 
-request_user_input({
+functions.request_user_input({
   questions: [{
     header: "Post Execute",
     id: "post_quick_execute",

package/.codex/skills/parallel-dev-cycle/SKILL.md

@@ -92,6 +92,7 @@ Prep packages are generated by the interactive prompt `/prompts:prep-cycle`. See
 Input Parsing:
    └─ Parse arguments (TASK | --cycle-id + --extend)
    └─ Convert to structured context (cycleId, state, progressDir)
+   └─ Initialize progress tracking: functions.update_plan([...phases])
 
 Phase 1: Session Initialization
    └─ Ref: phases/01-session-init.md
@@ -219,43 +220,49 @@ Master state file: `{projectRoot}/.workflow/.cycle/{cycleId}.json`
 
 **Recovery**: If state corrupted, rebuild from `.progress/` markdown files and changes.log.
 
-## TodoWrite Pattern
+## Progress Tracking
 
-### Phase-Level Tracking (Tasks Attached)
+### Initialization (MANDATORY)
 
-```json
-[
-  {"content": "Phase 1: Session Initialization", "status": "completed"},
-  {"content": "Phase 2: Agent Execution", "status": "in_progress"},
-  {"content": "  → Spawn RA Agent", "status": "completed"},
-  {"content": "  → Spawn EP Agent", "status": "completed"},
-  {"content": "  → Spawn CD Agent", "status": "in_progress"},
-  {"content": "  → Spawn VAS Agent", "status": "pending"},
-  {"content": "Phase 3: Result Aggregation", "status": "pending"},
-  {"content": "Phase 4: Completion & Summary", "status": "pending"}
-]
+```javascript
+// Initialize progress tracking after input parsing
+functions.update_plan([
+  { id: "phase-1", title: "Phase 1: Session Initialization", status: "in_progress" },
+  { id: "phase-2", title: "Phase 2: Agent Execution", status: "pending" },
+  { id: "phase-3", title: "Phase 3: Result Aggregation", status: "pending" },
+  { id: "phase-4", title: "Phase 4: Completion & Summary", status: "pending" }
+])
 ```
 
-### Phase-Level Tracking (Collapsed)
-
-```json
-[
-  {"content": "Phase 1: Session Initialization", "status": "completed"},
-  {"content": "Phase 2: Agent Execution (4 agents completed)", "status": "completed"},
-  {"content": "Phase 3: Result Aggregation", "status": "in_progress"},
-  {"content": "Phase 4: Completion & Summary", "status": "pending"}
-]
-```
-
-### Iteration Loop Tracking
-
-```json
-[
-  {"content": "Phase 1: Session Initialization", "status": "completed"},
-  {"content": "Iteration 1: Agent Execution + Aggregation", "status": "completed"},
-  {"content": "Iteration 2: Feedback → Re-execution → Aggregation", "status": "in_progress"},
-  {"content": "Phase 4: Completion & Summary", "status": "pending"}
-]
+### Phase Transitions
+
+```javascript
+// After Phase 1 completes
+functions.update_plan([
+  { id: "phase-1", status: "completed" },
+  { id: "phase-2", status: "in_progress" }
+])
+
+// After Phase 2 completes
+functions.update_plan([
+  { id: "phase-2", status: "completed" },
+  { id: "phase-3", status: "in_progress" }
+])
+
+// After Phase 3 — iterate or complete
+// If iterating back to Phase 2:
+functions.update_plan([
+  { id: "phase-3", status: "completed" },
+  { id: "phase-2", title: "Phase 2: Agent Execution (Iteration N)", status: "in_progress" }
+])
+// If proceeding to Phase 4:
+functions.update_plan([
+  { id: "phase-3", status: "completed" },
+  { id: "phase-4", status: "in_progress" }
+])
+
+// After Phase 4 completes
+functions.update_plan([{ id: "phase-4", status: "completed" }])
 ```
 
 ## Versioning
@@ -344,11 +351,11 @@ Feedback via `assign_task` (file refs + issue summary, never full content):
 
 ## Core Rules
 
-1. **Start Immediately**: First action is TodoWrite initialization, then Phase 1 execution
+1. **Start Immediately**: First action is `functions.update_plan` initialization, then Phase 1 execution
 2. **Progressive Phase Loading**: Read phase docs ONLY when that phase is about to execute
 3. **Parse Every Output**: Extract PHASE_RESULT data from each agent for next phase
 4. **Auto-Continue**: After each phase, execute next pending phase automatically
-5. **Track Progress**: Update TodoWrite dynamically with attachment/collapse pattern
+5. **Track Progress**: Update `functions.update_plan` at each phase transition
 6. **Single Writer**: Only main flow writes to master state file; agents report via PHASE_RESULT
 7. **File References**: Pass file paths between agents, not content
 8. **DO NOT STOP**: Continuous execution until all phases complete or max iterations reached
@@ -370,13 +377,13 @@ Feedback via `assign_task` (file refs + issue summary, never full content):
 
 - [ ] Read phase reference document
 - [ ] Check current state for dependencies
-- [ ] Update TodoWrite with phase tasks
+- [ ] Update `functions.update_plan` with phase status
 
 ### After Each Phase
 
 - [ ] Parse agent outputs (PHASE_RESULT)
 - [ ] Update master state file
-- [ ] Collapse TodoWrite sub-tasks
+- [ ] Update `functions.update_plan` phase completion
 - [ ] Determine next action (continue / iterate / complete)
 
 ## Reference Documents

package/.codex/skills/project-documentation-workflow/SKILL.md

@@ -295,7 +295,7 @@ ${waveDistribution.map(w => `║   Wave ${w.wave}: ${w.tasks} tasks${' '.repeat(
     }
   }
   
-  const answer = request_user_input({
+  const answer = functions.request_user_input({
     questions: [{
       header: "确认任务",
       id: "confirm_tasks",

package/.codex/skills/review-cycle/SKILL.md

@@ -363,15 +363,25 @@ close_agent({ id: agentId })
 
 ## Progress Tracking Pattern
 
-**Review Pipeline Initialization**:
+**Review Pipeline Initialization** (before Phase 1):
 ```
-Phase 1: Discovery & Initialization     → pending
-Phase 2: Parallel Reviews (7 dimensions) → pending
-Phase 3: Aggregation                     → pending
-Phase 4: Deep-dive (conditional)         → pending
-Phase 5: Review Completion               → pending
+functions.update_plan([
+  { id: "phase-1", title: "Phase 1: Discovery & Initialization", status: "in_progress" },
+  { id: "phase-2", title: "Phase 2: Parallel Reviews (7 dimensions)", status: "pending" },
+  { id: "phase-3", title: "Phase 3: Aggregation", status: "pending" },
+  { id: "phase-4", title: "Phase 4: Deep-dive (conditional)", status: "pending" },
+  { id: "phase-5", title: "Phase 5: Review Completion", status: "pending" }
+])
 ```
 
+**Phase Transitions**:
+- **Phase 1 complete**: `functions.update_plan([{id: "phase-1", status: "completed"}, {id: "phase-2", status: "in_progress"}])`
+- **Phase 2 complete**: `functions.update_plan([{id: "phase-2", status: "completed"}, {id: "phase-3", status: "in_progress"}])`
+- **Phase 3 → Phase 4 (iteration needed)**: `functions.update_plan([{id: "phase-3", status: "completed"}, {id: "phase-4", status: "in_progress"}])`
+- **Phase 3 → Phase 5 (no iteration)**: `functions.update_plan([{id: "phase-3", status: "completed"}, {id: "phase-4", status: "completed"}, {id: "phase-5", status: "in_progress"}])`
+- **Phase 4 complete**: `functions.update_plan([{id: "phase-4", status: "completed"}, {id: "phase-5", status: "in_progress"}])`
+- **Phase 5 complete**: `functions.update_plan([{id: "phase-5", status: "completed"}])`
+
 **During Phase 2 (sub-tasks for each dimension)**:
 ```
   → Security review       → in_progress / completed
@@ -380,15 +390,24 @@ Phase 5: Review Completion               → pending
   ... other dimensions
 ```
 
-**Fix Pipeline (added after Phase 5 if triggered)**:
+**Fix Pipeline (added after Phase 5 if --fix triggered)**:
 ```
-Phase 6: Fix Discovery & Batching   → pending
-Phase 7: Parallel Planning          → pending
-Phase 7.5: Export to Task JSON      → pending
-Phase 8: Execution                  → pending
-Phase 9: Fix Completion             → pending
+functions.update_plan([
+  { id: "phase-6", title: "Phase 6: Fix Discovery & Batching", status: "in_progress" },
+  { id: "phase-7", title: "Phase 7: Parallel Planning", status: "pending" },
+  { id: "phase-7.5", title: "Phase 7.5: Export to Task JSON", status: "pending" },
+  { id: "phase-8", title: "Phase 8: Execution", status: "pending" },
+  { id: "phase-9", title: "Phase 9: Fix Completion", status: "pending" }
+])
 ```
 
+**Fix Pipeline Transitions**:
+- **Phase 6 complete**: `functions.update_plan([{id: "phase-6", status: "completed"}, {id: "phase-7", status: "in_progress"}])`
+- **Phase 7 complete**: `functions.update_plan([{id: "phase-7", status: "completed"}, {id: "phase-7.5", status: "in_progress"}])`
+- **Phase 7.5 complete**: `functions.update_plan([{id: "phase-7.5", status: "completed"}, {id: "phase-8", status: "in_progress"}])`
+- **Phase 8 complete**: `functions.update_plan([{id: "phase-8", status: "completed"}, {id: "phase-9", status: "in_progress"}])`
+- **Phase 9 complete**: `functions.update_plan([{id: "phase-9", status: "completed"}])`
+
 ## Error Handling
 
 ### Review Pipeline Errors

package/.codex/skills/roadmap-with-file/SKILL.md

@@ -119,34 +119,54 @@ Strategic requirement roadmap with **iterative decomposition**. Creates a single
 
 **Core workflow**: Understand → Decompose → Iterate → Validate → Handoff
 
+**Key features**:
+- **roadmap.md**: Single source of truth — strategy, roadmap, convergence, iteration history
+- **Dual decomposition**: Progressive (MVP→Optimized) or Direct (topological tasks)
+- **External research**: Web search for architecture patterns and best practices via `web.run`
+- **Issue creation**: Issues persisted to global `issues.jsonl` for execution pipeline
+- **Progress tracking**: `functions.update_plan` for real-time phase progress visibility
+- **Decision recording**: Structured decision trail with context and rationale
+- **Structured handoff**: Terminal gate with execution planning, issue viewing, or completion
+
 ```
 ┌─────────────────────────────────────────────────────────────────────────┐
 │                    ROADMAP ITERATIVE WORKFLOW                            │
 ├─────────────────────────────────────────────────────────────────────────┤
 │                                                                          │
+│  Session Init                                                            │
+│     ├─ Parse flags, generate session ID                                  │
+│     ├─ functions.exec_command (mkdir session folder)                      │
+│     └─ functions.update_plan (5 phases: Understand → Decompose →         │
+│        Refine → Handoff → GATE)                                          │
+│                                                                          │
 │  Phase 1: Requirement Understanding & Strategy                           │
 │     ├─ Parse requirement: goal / constraints / stakeholders              │
 │     ├─ Assess uncertainty level → recommend mode                         │
-│     ├─ User confirms strategy (-m skips, -y auto-selects)                │
+│     ├─ User confirms strategy via functions.request_user_input           │
 │     └─ Initialize roadmap.md with Strategy Assessment                    │
 │                                                                          │
 │  Phase 2: Decomposition & Issue Creation                                 │
+│     ├─ Optional codebase exploration (functions.exec_command detection)   │
 │     ├─ cli-roadmap-plan-agent executes decomposition                     │
 │     ├─ Progressive: 2-4 layers (MVP→Optimized) with convergence          │
 │     ├─ Direct: Topological task sequence with convergence                │
 │     ├─ Create issues via ccw issue create → issues.jsonl                 │
 │     └─ Update roadmap.md with Roadmap table + Issue references           │
 │                                                                          │
-│  Phase 3: Iterative Refinement (Multi-Round)                             │
-│     ├─ Present roadmap to user                                           │
-│     ├─ Feedback: Approve | Adjust Scope | Modify Convergence | Replan    │
-│     ├─ Update roadmap.md with each round                                 │
+│  Phase 3: Iterative Refinement (Multi-Round, Decision Recording)         │
+│     ├─ Present roadmap to user (Cumulative Context)                      │
+│     ├─ Feedback via functions.request_user_input:                        │
+│     │   Approve | Adjust Scope | Refine Criteria | Research/Re-decompose │
+│     ├─ External research via web.run (optional — patterns, practices)    │
+│     ├─ Record decisions in Iteration History (Record-Before-Continue)     │
 │     └─ Repeat until approved (max 5 rounds)                              │
 │                                                                          │
 │  Phase 4: Handoff (PLANNING ENDS HERE)                                   │
 │     ├─ Final roadmap.md with Issue ID references                         │
-│     ├─ Options: view issues | done (show next-step commands)             │
-│     └─ Issues ready in .workflow/issues/issues.jsonl                     │
+│     └─ MANDATORY Terminal Gate: 执行计划 / 查看Issue / 完成              │
+│         ├─ Execute Plan → display csv-wave-pipeline command               │
+│         ├─ View Issues → ccw issue list                                  │
+│         └─ Done → end workflow                                           │
 │                                                                          │
 └─────────────────────────────────────────────────────────────────────────┘
 ```
@@ -360,7 +380,16 @@ if (continueMode || file_exists(`${sessionFolder}/roadmap.md`)) {
   // Extract current phase and continue from there
 }
 
-Bash(`mkdir -p ${sessionFolder}`)
+functions.exec_command(`mkdir -p ${sessionFolder}`)
+
+// Initialize progress tracking (MANDATORY)
+functions.update_plan([
+  { id: "phase-1", title: "Phase 1: Requirement Understanding & Strategy", status: "in_progress" },
+  { id: "phase-2", title: "Phase 2: Decomposition & Issue Creation", status: "pending" },
+  { id: "phase-3", title: "Phase 3: Iterative Refinement", status: "pending" },
+  { id: "phase-4", title: "Phase 4: Handoff", status: "pending" },
+  { id: "next-step", title: "GATE: Post-Completion Next Step", status: "pending" }
+])
 ```
 
 ---
@@ -403,19 +432,19 @@ Bash(`mkdir -p ${sessionFolder}`)
    } else if (AUTO_YES) {
      selectedMode = recommendedMode
    } else {
-     const answer = request_user_input({
+     const answer = functions.request_user_input({
        questions: [{
-         header: "Strategy",
-         id: "strategy",
-         question: `Decomposition strategy:\nUncertainty: ${uncertaintyLevel}\nRecommended: ${recommendedMode}`,
+         header: "Strategy",   // max 12 chars
+         question: `Decomposition strategy: Uncertainty=${uncertaintyLevel}, Recommended=${recommendedMode}`,
+         multiSelect: false,
          options: [
-           { label: recommendedMode === 'progressive' ? "Progressive (Recommended)" : "Progressive" },
-           { label: recommendedMode === 'direct' ? "Direct (Recommended)" : "Direct" }
+           { label: recommendedMode === 'progressive' ? "Progressive (Recommended)" : "Progressive", description: "MVP → Usable → Refined → Optimized layers" },
+           { label: recommendedMode === 'direct' ? "Direct (Recommended)" : "Direct", description: "Topological task sequence" }
          ]
        }]
-     })  // BLOCKS (wait for user response)
+     })
 
-     selectedMode = answer.answers.strategy.answers[0]
+     selectedMode = answer // parsed from user selection
    }
    ```
 
@@ -489,7 +518,10 @@ Bash(`mkdir -p ${sessionFolder}`)
 
 1. **Optional Codebase Exploration** (if codebase detected)
    ```javascript
-   const hasCodebase = Bash(`
+   // Update progress
+   functions.update_plan([{ id: "phase-2", title: "Phase 2: Decomposition & Issue Creation", status: "in_progress" }])
+
+   const hasCodebase = functions.exec_command(`
      test -f package.json && echo "nodejs" ||
      test -f go.mod && echo "golang" ||
      test -f Cargo.toml && echo "rust" ||
@@ -655,6 +687,17 @@ ${selectedMode === 'progressive' ? `**Progressive Mode**:
 
 **Objective**: Multi-round user feedback to refine roadmap.
 
+**Cumulative Context Rule**: Each round's presentation MUST include ALL prior feedback and changes. Never present in isolation — always show cumulative state.
+
+**Decision Recording**: Every user feedback choice and resulting change MUST be recorded in Iteration History with Decision Record format:
+```markdown
+> **Decision**: [Description]
+> - **Context**: [What triggered this]
+> - **Options**: [What was considered]
+> - **Chosen**: [Selected] — **Reason**: [Why]
+> - **Impact**: [What changed in roadmap]
+```
+
 **Steps**:
 
 1. **Display Current Roadmap**
@@ -663,96 +706,67 @@ ${selectedMode === 'progressive' ? `**Progressive Mode**:
 
 2. **Feedback Loop** (skip if AUTO_YES)
    ```javascript
+   // Update progress
+   functions.update_plan([{ id: "phase-3", title: "Phase 3: Iterative Refinement", status: "in_progress" }])
+
    let round = 0
    let approved = false
 
    while (!approved && round < 5) {
      round++
 
-     const feedback = request_user_input({
+     // Dynamic options — include research if not yet done
+     const baseOptions = [
+       { label: "Approve", description: "Proceed to handoff" },
+       { label: "Adjust Scope", description: "Modify issue scopes" },
+       { label: "Refine Criteria", description: "Improve convergence criteria/verification" }
+     ]
+
+     // Add research option if architecture decisions need external validation
+     if (!researchDone) {
+       baseOptions.push({ label: "Research", description: "Search for architecture patterns and best practices" })
+     } else {
+       baseOptions.push({ label: "Re-decompose", description: "Change strategy/layering" })
+     }
+
+     const feedback = functions.request_user_input({
        questions: [{
-         header: "Validate",
-         id: "feedback",
-         question: `Roadmap validation (round ${round}):\n${issueIds.length} issues across ${waveCount} waves. Feedback?`,
-         options: [
-           { label: "Approve", description: "Proceed to handoff" },
-           { label: "Adjust Scope", description: "Modify issue scopes" },
-           { label: "Modify Convergence", description: "Refine criteria/verification" },
-           { label: "Re-decompose", description: "Change strategy/layering" }
-         ]
+         header: "Validate",    // max 12 chars
+         question: `Roadmap round ${round}: ${issueIds.length} issues across ${waveCount} waves. Your decision:`,
+         multiSelect: false,
+         options: baseOptions
        }]
-     })  // BLOCKS (wait for user response)
+     })
 
-     const feedbackChoice = feedback.answers.feedback.answers[0]
-     if (feedbackChoice === 'Approve') {
+     if (feedback === 'Approve') {
        approved = true
+     } else if (feedback === 'Research') {
+       // Execute web.run for architecture patterns and best practices
+       const researchQueries = generateResearchQueries(requirement, selectedMode)
+       researchQueries.forEach(query => {
+         const results = web.run({ search_query: query })
+         // Extract: architecture patterns, best practices, risk mitigations
+       })
+       researchDone = true
+       // Record research findings in roadmap.md Iteration History
      } else {
-       // CONSTRAINT: All modifications below ONLY touch roadmap.md and issues.jsonl
+       // For Adjust Scope, Refine Criteria, Re-decompose:
+       // Collect details via functions.request_user_input or free text
+       // CONSTRAINT: All modifications ONLY touch roadmap.md and issues.jsonl
        // NEVER modify source code or project files during interactive rounds
-       switch (feedbackChoice) {
-         case 'Adjust Scope':
-           // Collect scope adjustments
-           const scopeAdjustments = request_user_input({
-             questions: [{
-               header: "Scope",
-               id: "adjustments",
-               question: "Describe scope adjustments needed:"
-             }]
-           })  // BLOCKS
-
-           // Update ONLY roadmap.md Roadmap table + Convergence sections
-           Edit({ path: `${sessionFolder}/roadmap.md`, /* scope changes */ })
-           // Update ONLY issues.jsonl entries (scope/context fields)
-
-           break
-
-         case 'Modify Convergence':
-           // Collect convergence refinements
-           const convergenceRefinements = request_user_input({
-             questions: [{
-               header: "Convergence",
-               id: "refinements",
-               question: "Describe convergence refinements needed:"
-             }]
-           })  // BLOCKS
-
-           // Update ONLY roadmap.md Convergence Criteria section
-           Edit({ path: `${sessionFolder}/roadmap.md`, /* convergence changes */ })
-
-           break
-
-         case 'Re-decompose':
-           // Return to Phase 2 with new strategy
-           const newStrategy = request_user_input({
-             questions: [{
-               header: "Strategy",
-               id: "strategy",
-               question: "Select new decomposition strategy:",
-               options: [
-                 { label: "Progressive" },
-                 { label: "Direct" }
-               ]
-             }]
-           })  // BLOCKS
-
-           selectedMode = newStrategy.answers.strategy.answers[0]
-           // Re-execute Phase 2 (updates roadmap.md + issues.jsonl only)
-           break
-       }
-
-       // Update Iteration History in roadmap.md
-       const iterationEntry = `
+
+       // Record decision in Iteration History using Decision Record format
+     }
+
+     // Update Iteration History in roadmap.md (Record-Before-Continue)
+     const iterationEntry = `
 ### Round ${round} - ${getUtc8ISOString()}
-**User Feedback**: ${feedback.feedback}
+**User Feedback**: ${feedback}
 **Changes Made**: ${changesMade}
-**Status**: continue iteration
+**Decision**: ${decisionRecord}
+**Status**: ${approved ? 'approved' : 'continue iteration'}
 `
-       Edit({
-         path: `${sessionFolder}/roadmap.md`,
-         old_string: "## Iteration History\n\n> To be populated during Phase 3 refinement",
-         new_string: `## Iteration History\n${iterationEntry}`
-       })
-     }
+     // Append to Iteration History section in roadmap.md
    }
    ```
 
@@ -775,7 +789,7 @@ ${selectedMode === 'progressive' ? `**Progressive Mode**:
 
 ### Phase 4: Handoff
 
-**Objective**: Present final roadmap, offer execution options.
+**Objective**: Present final roadmap, execute MANDATORY terminal gate for next step selection.
 
 **Steps**:
 
@@ -794,50 +808,42 @@ ${selectedMode === 'progressive' ? `**Progressive Mode**:
    | 2 | 3 | Usable / feature |
    ```
 
-2. **Offer Options** (skip if AUTO_YES)
+2. **MANDATORY Terminal Gate** (CRITICAL — MUST execute, workflow MUST NOT end without this)
    ```javascript
-   let nextStep
-
-   if (AUTO_YES) {
-     nextStep = "done"  // Default to done in auto mode
-   } else {
-     const answer = request_user_input({
-       questions: [{
-         header: "Next Step",
-         id: "next_step",
-         question: `${issueIds.length} issues ready. Next step:`,
-         options: [
-           { label: "View issues", description: "Display issue details" },
-           { label: "Done", description: "Planning complete — show next-step commands" }
-         ]
-       }]
-     })  // BLOCKS (wait for user response)
+   // Update progress
+   functions.update_plan([
+     { id: "phase-4", title: "Phase 4: Handoff", status: "completed" },
+     { id: "next-step", title: "GATE: Post-Completion Next Step", status: "in_progress" }
+   ])
+
+   const nextStep = functions.request_user_input({
+     questions: [{
+       header: "Next Step",    // max 12 chars
+       question: `${issueIds.length} issues ready in roadmap. What would you like to do next?`,
+       multiSelect: false,
+       options: [
+         { label: "Execute Plan", description: "Hand off to execution pipeline (csv-wave-pipeline)" },
+         { label: "View Issues", description: "Display issue details before deciding" },
+         { label: "Done", description: "Planning complete, all artifacts saved" }
+       ]
+     }]
+   })
 
-     nextStep = answer.answers.next_step.answers[0]
+   // Handle next step
+   if (nextStep === "Execute Plan") {
+     // Display execution command for user to run manually
+     // "Run: $csv-wave-pipeline '${requirement}'" or "/issue:execute"
+     // This skill is planning-only — NEVER auto-launch execution
+   } else if (nextStep === "View Issues") {
+     functions.exec_command(`ccw issue list --session ${sessionId}`)
+     // After viewing, show execution commands
    }
-   ```
+   // "Done" → end workflow
 
-3. **Execute Selection**
-   ```javascript
-   switch (nextStep) {
-     case 'view':
-       // Display issues from issues.jsonl
-       Bash(`ccw issue list --session ${sessionId}`)
-       // Fall through to show next-step commands
-       // STOP — do not execute anything
-
-     case 'done':
-       // Output paths and end — this skill is planning-only
-       console.log([
-         `Roadmap saved: ${sessionFolder}/roadmap.md`,
-         `Issues created: ${issueIds.length}`,
-         '',
-         'Planning complete. To execute, run:',
-         `  $csv-wave-pipeline "${requirement}"`,
-         `  ccw issue list --session ${sessionId}`
-       ].join('\n'))
-       return  // STOP — this skill is planning-only, NEVER proceed to execution
-   }
+   // Mark terminal gate complete
+   functions.update_plan([
+     { id: "next-step", title: "GATE: Post-Completion Next Step", status: "completed" }
+   ])
    ```
 
 **Success Criteria**:
@@ -854,6 +860,8 @@ ${selectedMode === 'progressive' ? `**Progressive Mode**:
 | cli-explore-agent fails | Skip code exploration, proceed with pure requirement decomposition |
 | cli-roadmap-plan-agent fails | Retry once, fallback to manual decomposition prompt |
 | No codebase | Normal flow, skip exploration step |
+| Web research fails | Continue without external findings, rely on inline analysis |
+| Research conflicts with plan | Present as competing evidence, let user decide direction |
 | Circular dependency detected | Prompt user, re-decompose |
 | User timeout in feedback loop | Save roadmap.md, show `--continue` command |
 | Max rounds reached | Force proceed with current roadmap |