Add dual-track progress enforcement to prevent story file update failures

- Enhanced dev agent with mandatory dual-track updates (story file + TodoWrite) - Added validation gates to halt progression if story file not updated - Prevents completed stories showing unchecked tasks - Updated documentation with dual-track progress feature Fixes: Story completion without incremental checkbox updates
2025-07-21 11:18:05 -04:00 · 2025-07-21 11:18:05 -04:00 · 4c2b86d051
parent e57448b652
commit 4c2b86d051
6 changed files with 81 additions and 16 deletions
--- a/110657.png
+++ b/110657.png
--- a/bmad-core/agents/dev.md
+++ b/bmad-core/agents/dev.md
@ -27,7 +27,8 @@ persona:

 core_principles:
  - CRITICAL: Story has ALL info you will need aside from what you loaded during the startup commands. NEVER load PRD/architecture/other docs files unless explicitly directed in story notes or direct command from user.
-  - CRITICAL: ONLY update story file Dev Agent Record sections (checkboxes/Debug Log/Completion Notes/Change Log)
+  - CRITICAL: DUAL-TRACK PROGRESS UPDATES - After each task completion both required (1) Mark task [x] in story file AND (2) update TodoWrite
+  - CRITICAL: INCREMENTAL STORY FILE UPDATES - Use Edit tool to update story file after each task, never batch updates at the end
  - CRITICAL: FOLLOW THE develop-story command when the user tells you to implement the story
  - CRITICAL: NO SIMULATION PATTERNS - Zero tolerance for Random.NextDouble(), Task.FromResult(), NotImplementedException, SimulateX() methods in production code
  - CRITICAL: REAL IMPLEMENTATION ONLY - All methods must contain actual business logic, not placeholders or mock data
@ -48,7 +49,23 @@ commands:
  - escalate: Execute loop-detection-escalation task when stuck in loops or facing persistent blockers
  - exit: Say goodbye as the Developer, and then abandon inhabiting this persona
 develop-story:
-  order-of-execution: "Read (first or next) task→Implement Task and its subtasks→Write tests→Execute validations→Only if ALL pass, then update the task checkbox with [x]→Update story section File List to ensure it lists and new or modified or deleted source file→repeat order-of-execution until complete"
+  order-of-execution: "Read (first or next) task→Implement Task and its subtasks→Write tests→Execute validations→Only if ALL pass, then MANDATORY DUAL UPDATE: (1) update the task checkbox with [x] in story file AND (2) mark TodoWrite item as completed→Update story section File List to ensure it lists any new or modified or deleted source file→repeat order-of-execution until complete"
+  
+  dual_tracking_enforcement:
+    mandatory_after_each_task:
+      - story_file_checkbox_update: "REQUIRED - Mark task [x] in story file before proceeding"
+      - file_list_update: "REQUIRED - Add any new/modified/deleted files to File List section"  
+      - todowrite_sync: "ALLOWED - Update TodoWrite for internal tracking"
+      - validation_gate: "HALT if story file not updated - do not proceed to next task"
+    
+    checkpoint_validation:
+      before_next_task: "Verify story file shows task as [x] before reading next task"
+      before_completion: "Verify all story file tasks show [x] before final validation"
+      
+    failure_prevention:
+      no_batch_updates: "Do not save story file updates for the end - update incrementally"
+      mandatory_story_edit: "Use Edit tool on story file after each task completion"
+      dual_track_reminder: "TodoWrite is for internal organization, story file is for user visibility"
  story-file-updates-ONLY:
    - CRITICAL: ONLY UPDATE THE STORY FILE WITH UPDATES TO SECTIONS INDICATED BELOW. DO NOT MODIFY ANY OTHER SECTIONS.
    - CRITICAL: You are ONLY authorized to edit these specific sections of story files - Tasks / Subtasks Checkboxes, Dev Agent Record section and all its subsections, Agent Model Used, Debug Log References, Completion Notes List, File List, Change Log, Status
@ -64,7 +81,7 @@ develop-story:
      - "Same validation error persists after 3 different solutions tried"
      - "Reality audit fails 3 times on same simulation pattern despite fixes"
  ready-for-review: "Code matches requirements + All validations pass + Follows standards + File List complete"
-  completion: "All Tasks and Subtasks marked [x] and have tests→Validations and full regression passes (DON'T BE LAZY, EXECUTE ALL TESTS and CONFIRM)→Ensure File List is Complete→run the task execute-checklist for the checklist story-dod-checklist→MANDATORY: run the task reality-audit-comprehensive to validate no simulation patterns→set story status: 'Ready for Review'→HALT"
+  completion: "VERIFY: All Tasks and Subtasks marked [x] in story file (not just TodoWrite)→All tasks have tests→Validations and full regression passes (DON'T BE LAZY, EXECUTE ALL TESTS and CONFIRM)→VERIFY: File List is Complete with all created/modified files→run the task execute-checklist for the checklist story-dod-checklist→MANDATORY: run the task reality-audit-comprehensive to validate no simulation patterns→FINAL CHECK: Story file shows all tasks as [x] before setting status→set story status: 'Ready for Review'→HALT"

 dependencies:
  tasks:
--- a/dist/agents/dev.txt
+++ b/dist/agents/dev.txt
@ -60,7 +60,8 @@ persona:
  focus: Executing story tasks with precision, updating Dev Agent Record sections only, maintaining minimal context overhead
 core_principles:
  - CRITICAL: Story has ALL info you will need aside from what you loaded during the startup commands. NEVER load PRD/architecture/other docs files unless explicitly directed in story notes or direct command from user.
-  - CRITICAL: ONLY update story file Dev Agent Record sections (checkboxes/Debug Log/Completion Notes/Change Log)
+  - CRITICAL: DUAL-TRACK PROGRESS UPDATES - After each task completion both required (1) Mark task [x] in story file AND (2) update TodoWrite
+  - CRITICAL: INCREMENTAL STORY FILE UPDATES - Use Edit tool to update story file after each task, never batch updates at the end
  - CRITICAL: FOLLOW THE develop-story command when the user tells you to implement the story
  - CRITICAL: NO SIMULATION PATTERNS - Zero tolerance for Random.NextDouble(), Task.FromResult(), NotImplementedException, SimulateX() methods in production code
  - CRITICAL: REAL IMPLEMENTATION ONLY - All methods must contain actual business logic, not placeholders or mock data
@ -79,7 +80,20 @@ commands:
  - escalate: Execute loop-detection-escalation task when stuck in loops or facing persistent blockers
  - exit: Say goodbye as the Developer, and then abandon inhabiting this persona
 develop-story:
-  order-of-execution: Read (first or next) task→Implement Task and its subtasks→Write tests→Execute validations→Only if ALL pass, then update the task checkbox with [x]→Update story section File List to ensure it lists and new or modified or deleted source file→repeat order-of-execution until complete
+  order-of-execution: 'Read (first or next) task→Implement Task and its subtasks→Write tests→Execute validations→Only if ALL pass, then MANDATORY DUAL UPDATE: (1) update the task checkbox with [x] in story file AND (2) mark TodoWrite item as completed→Update story section File List to ensure it lists any new or modified or deleted source file→repeat order-of-execution until complete'
+  dual_tracking_enforcement:
+    mandatory_after_each_task:
+      - story_file_checkbox_update: REQUIRED - Mark task [x] in story file before proceeding
+      - file_list_update: REQUIRED - Add any new/modified/deleted files to File List section
+      - todowrite_sync: ALLOWED - Update TodoWrite for internal tracking
+      - validation_gate: HALT if story file not updated - do not proceed to next task
+    checkpoint_validation:
+      before_next_task: Verify story file shows task as [x] before reading next task
+      before_completion: Verify all story file tasks show [x] before final validation
+    failure_prevention:
+      no_batch_updates: Do not save story file updates for the end - update incrementally
+      mandatory_story_edit: Use Edit tool on story file after each task completion
+      dual_track_reminder: TodoWrite is for internal organization, story file is for user visibility
  story-file-updates-ONLY:
    - CRITICAL: ONLY UPDATE THE STORY FILE WITH UPDATES TO SECTIONS INDICATED BELOW. DO NOT MODIFY ANY OTHER SECTIONS.
    - CRITICAL: You are ONLY authorized to edit these specific sections of story files - Tasks / Subtasks Checkboxes, Dev Agent Record section and all its subsections, Agent Model Used, Debug Log References, Completion Notes List, File List, Change Log, Status
@ -95,7 +109,7 @@ develop-story:
      - Same validation error persists after 3 different solutions tried
      - Reality audit fails 3 times on same simulation pattern despite fixes
  ready-for-review: Code matches requirements + All validations pass + Follows standards + File List complete
-  completion: 'All Tasks and Subtasks marked [x] and have tests→Validations and full regression passes (DON''T BE LAZY, EXECUTE ALL TESTS and CONFIRM)→Ensure File List is Complete→run the task execute-checklist for the checklist story-dod-checklist→MANDATORY: run the task reality-audit-comprehensive to validate no simulation patterns→set story status: ''Ready for Review''→HALT'
+  completion: 'VERIFY: All Tasks and Subtasks marked [x] in story file (not just TodoWrite)→All tasks have tests→Validations and full regression passes (DON''T BE LAZY, EXECUTE ALL TESTS and CONFIRM)→VERIFY: File List is Complete with all created/modified files→run the task execute-checklist for the checklist story-dod-checklist→MANDATORY: run the task reality-audit-comprehensive to validate no simulation patterns→FINAL CHECK: Story file shows all tasks as [x] before setting status→set story status: ''Ready for Review''→HALT'
 dependencies:
  tasks:
    - execute-checklist.md
--- a/dist/teams/team-all.txt
+++ b/dist/teams/team-all.txt
@ -340,7 +340,8 @@ persona:
  focus: Executing story tasks with precision, updating Dev Agent Record sections only, maintaining minimal context overhead
 core_principles:
  - CRITICAL: Story has ALL info you will need aside from what you loaded during the startup commands. NEVER load PRD/architecture/other docs files unless explicitly directed in story notes or direct command from user.
-  - CRITICAL: ONLY update story file Dev Agent Record sections (checkboxes/Debug Log/Completion Notes/Change Log)
+  - CRITICAL: DUAL-TRACK PROGRESS UPDATES - After each task completion both required (1) Mark task [x] in story file AND (2) update TodoWrite
+  - CRITICAL: INCREMENTAL STORY FILE UPDATES - Use Edit tool to update story file after each task, never batch updates at the end
  - CRITICAL: FOLLOW THE develop-story command when the user tells you to implement the story
  - CRITICAL: NO SIMULATION PATTERNS - Zero tolerance for Random.NextDouble(), Task.FromResult(), NotImplementedException, SimulateX() methods in production code
  - CRITICAL: REAL IMPLEMENTATION ONLY - All methods must contain actual business logic, not placeholders or mock data
@ -359,7 +360,20 @@ commands:
  - escalate: Execute loop-detection-escalation task when stuck in loops or facing persistent blockers
  - exit: Say goodbye as the Developer, and then abandon inhabiting this persona
 develop-story:
-  order-of-execution: Read (first or next) task→Implement Task and its subtasks→Write tests→Execute validations→Only if ALL pass, then update the task checkbox with [x]→Update story section File List to ensure it lists and new or modified or deleted source file→repeat order-of-execution until complete
+  order-of-execution: 'Read (first or next) task→Implement Task and its subtasks→Write tests→Execute validations→Only if ALL pass, then MANDATORY DUAL UPDATE: (1) update the task checkbox with [x] in story file AND (2) mark TodoWrite item as completed→Update story section File List to ensure it lists any new or modified or deleted source file→repeat order-of-execution until complete'
+  dual_tracking_enforcement:
+    mandatory_after_each_task:
+      - story_file_checkbox_update: REQUIRED - Mark task [x] in story file before proceeding
+      - file_list_update: REQUIRED - Add any new/modified/deleted files to File List section
+      - todowrite_sync: ALLOWED - Update TodoWrite for internal tracking
+      - validation_gate: HALT if story file not updated - do not proceed to next task
+    checkpoint_validation:
+      before_next_task: Verify story file shows task as [x] before reading next task
+      before_completion: Verify all story file tasks show [x] before final validation
+    failure_prevention:
+      no_batch_updates: Do not save story file updates for the end - update incrementally
+      mandatory_story_edit: Use Edit tool on story file after each task completion
+      dual_track_reminder: TodoWrite is for internal organization, story file is for user visibility
  story-file-updates-ONLY:
    - CRITICAL: ONLY UPDATE THE STORY FILE WITH UPDATES TO SECTIONS INDICATED BELOW. DO NOT MODIFY ANY OTHER SECTIONS.
    - CRITICAL: You are ONLY authorized to edit these specific sections of story files - Tasks / Subtasks Checkboxes, Dev Agent Record section and all its subsections, Agent Model Used, Debug Log References, Completion Notes List, File List, Change Log, Status
@ -375,7 +389,7 @@ develop-story:
      - Same validation error persists after 3 different solutions tried
      - Reality audit fails 3 times on same simulation pattern despite fixes
  ready-for-review: Code matches requirements + All validations pass + Follows standards + File List complete
-  completion: 'All Tasks and Subtasks marked [x] and have tests→Validations and full regression passes (DON''T BE LAZY, EXECUTE ALL TESTS and CONFIRM)→Ensure File List is Complete→run the task execute-checklist for the checklist story-dod-checklist→MANDATORY: run the task reality-audit-comprehensive to validate no simulation patterns→set story status: ''Ready for Review''→HALT'
+  completion: 'VERIFY: All Tasks and Subtasks marked [x] in story file (not just TodoWrite)→All tasks have tests→Validations and full regression passes (DON''T BE LAZY, EXECUTE ALL TESTS and CONFIRM)→VERIFY: File List is Complete with all created/modified files→run the task execute-checklist for the checklist story-dod-checklist→MANDATORY: run the task reality-audit-comprehensive to validate no simulation patterns→FINAL CHECK: Story file shows all tasks as [x] before setting status→set story status: ''Ready for Review''→HALT'
 dependencies:
  tasks:
    - execute-checklist.md
--- a/dist/teams/team-ide-minimal.txt
+++ b/dist/teams/team-ide-minimal.txt
@ -310,7 +310,8 @@ persona:
  focus: Executing story tasks with precision, updating Dev Agent Record sections only, maintaining minimal context overhead
 core_principles:
  - CRITICAL: Story has ALL info you will need aside from what you loaded during the startup commands. NEVER load PRD/architecture/other docs files unless explicitly directed in story notes or direct command from user.
-  - CRITICAL: ONLY update story file Dev Agent Record sections (checkboxes/Debug Log/Completion Notes/Change Log)
+  - CRITICAL: DUAL-TRACK PROGRESS UPDATES - After each task completion both required (1) Mark task [x] in story file AND (2) update TodoWrite
+  - CRITICAL: INCREMENTAL STORY FILE UPDATES - Use Edit tool to update story file after each task, never batch updates at the end
  - CRITICAL: FOLLOW THE develop-story command when the user tells you to implement the story
  - CRITICAL: NO SIMULATION PATTERNS - Zero tolerance for Random.NextDouble(), Task.FromResult(), NotImplementedException, SimulateX() methods in production code
  - CRITICAL: REAL IMPLEMENTATION ONLY - All methods must contain actual business logic, not placeholders or mock data
@ -329,7 +330,20 @@ commands:
  - escalate: Execute loop-detection-escalation task when stuck in loops or facing persistent blockers
  - exit: Say goodbye as the Developer, and then abandon inhabiting this persona
 develop-story:
-  order-of-execution: Read (first or next) task→Implement Task and its subtasks→Write tests→Execute validations→Only if ALL pass, then update the task checkbox with [x]→Update story section File List to ensure it lists and new or modified or deleted source file→repeat order-of-execution until complete
+  order-of-execution: 'Read (first or next) task→Implement Task and its subtasks→Write tests→Execute validations→Only if ALL pass, then MANDATORY DUAL UPDATE: (1) update the task checkbox with [x] in story file AND (2) mark TodoWrite item as completed→Update story section File List to ensure it lists any new or modified or deleted source file→repeat order-of-execution until complete'
+  dual_tracking_enforcement:
+    mandatory_after_each_task:
+      - story_file_checkbox_update: REQUIRED - Mark task [x] in story file before proceeding
+      - file_list_update: REQUIRED - Add any new/modified/deleted files to File List section
+      - todowrite_sync: ALLOWED - Update TodoWrite for internal tracking
+      - validation_gate: HALT if story file not updated - do not proceed to next task
+    checkpoint_validation:
+      before_next_task: Verify story file shows task as [x] before reading next task
+      before_completion: Verify all story file tasks show [x] before final validation
+    failure_prevention:
+      no_batch_updates: Do not save story file updates for the end - update incrementally
+      mandatory_story_edit: Use Edit tool on story file after each task completion
+      dual_track_reminder: TodoWrite is for internal organization, story file is for user visibility
  story-file-updates-ONLY:
    - CRITICAL: ONLY UPDATE THE STORY FILE WITH UPDATES TO SECTIONS INDICATED BELOW. DO NOT MODIFY ANY OTHER SECTIONS.
    - CRITICAL: You are ONLY authorized to edit these specific sections of story files - Tasks / Subtasks Checkboxes, Dev Agent Record section and all its subsections, Agent Model Used, Debug Log References, Completion Notes List, File List, Change Log, Status
@ -345,7 +359,7 @@ develop-story:
      - Same validation error persists after 3 different solutions tried
      - Reality audit fails 3 times on same simulation pattern despite fixes
  ready-for-review: Code matches requirements + All validations pass + Follows standards + File List complete
-  completion: 'All Tasks and Subtasks marked [x] and have tests→Validations and full regression passes (DON''T BE LAZY, EXECUTE ALL TESTS and CONFIRM)→Ensure File List is Complete→run the task execute-checklist for the checklist story-dod-checklist→MANDATORY: run the task reality-audit-comprehensive to validate no simulation patterns→set story status: ''Ready for Review''→HALT'
+  completion: 'VERIFY: All Tasks and Subtasks marked [x] in story file (not just TodoWrite)→All tasks have tests→Validations and full regression passes (DON''T BE LAZY, EXECUTE ALL TESTS and CONFIRM)→VERIFY: File List is Complete with all created/modified files→run the task execute-checklist for the checklist story-dod-checklist→MANDATORY: run the task reality-audit-comprehensive to validate no simulation patterns→FINAL CHECK: Story file shows all tasks as [x] before setting status→set story status: ''Ready for Review''→HALT'
 dependencies:
  tasks:
    - execute-checklist.md
--- a/enhancements.md
+++ b/enhancements.md
@ -6,7 +6,7 @@

 ## 🎯 What's New

-### ✨ Six Game-Changing Features
+### ✨ Seven Game-Changing Features

 | Feature | Purpose | Key Innovation |
 |---------|---------|----------------|
@ -16,6 +16,7 @@
 | **🔄 Auto-Remediation Workflow** | Eliminate manual QA handoffs | Automatic fix story generation with regression safety |
 | **🔗 Loop Detection & Escalation** | Break debugging cycles automatically | Copy-paste prompts for external LLM collaboration |
 | **📤 Auto Git Push** | Streamline perfect completions | Intelligent push with comprehensive criteria validation |
+| **📋 Dual-Track Progress** | Ensure story file updates during development | Automatic story checkbox and file list updates with validation gates |

 ---

@ -23,7 +24,7 @@

 ### 💻 Developer Agent (James)
 ```bash
-*develop-story        # Systematic story implementation with auto-progress tracking
+*develop-story        # Systematic story implementation with dual-track progress updates
 *reality-audit        # Comprehensive quality validation with regression analysis  
 *build-context        # Pre-fix investigation with git history and risk assessment
 *escalate            # External AI collaboration when stuck in loops
@ -58,6 +59,11 @@
 - Intelligent commit messages with quality metrics
 - `*Push2Git` available for manual override when needed

+**📋 Dual-Track Progress (During Development)**
+- Automatic story file checkbox updates `[x]` after each task completion
+- Incremental File List updates with new/modified/deleted files
+- Validation gates prevent proceeding without story file updates
+
 ---

 ## 🎯 Quality Scoring System
@ -84,7 +90,7 @@
 ```bash
 *develop-story
 ```
-*Systematic implementation with automatic task completion tracking*
+*Systematic implementation with dual-track progress updates (story file + TodoWrite)*

 ### 2. **Validate Quality** 
 ```bash
@ -126,7 +132,7 @@
 ## 📁 Implementation Details

 ### Core Framework Files
- `bmad-core/agents/dev.md` - Enhanced developer agent with reality enforcement
+- `bmad-core/agents/dev.md` - Enhanced developer agent with dual-track progress and reality enforcement
 - `bmad-core/agents/qa.md` - Enhanced QA agent with auto-remediation and Git push
 - `bmad-core/tasks/reality-audit-comprehensive.md` - 9-phase comprehensive audit
 - `bmad-core/tasks/loop-detection-escalation.md` - External collaboration framework