From 4eb889642db074633a19c5bf6d5cd03b89a94ca4 Mon Sep 17 00:00:00 2001 From: Jonah Schulte Date: Wed, 7 Jan 2026 17:28:52 -0500 Subject: [PATCH] feat: add continuous sprint-status tracking with task-level progress MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Implements requirements #1 and #2: stronger enforcement + progress tracking REQUIREMENT #1: Stronger Enforcement - dev-story Step 8 now MANDATES sprint-status.yaml update after EVERY task - Previously: Updated only at story start (step 4) and end (step 9) - Now: Updated after EACH task completion with CRITICAL + HALT enforcement - Validation: Re-reads file to verify update persisted, HALTs on failure REQUIREMENT #2: Progress Tracking - Extended sprint-status.yaml format with inline progress comments - Format: "story-key: in-progress # X/Y tasks (Z%)" - Real-time visibility into story progress without opening story files - Automatically updated by dev-story and batch-super-dev reconciliation Progress Comment Format: - in-progress: "# 3/10 tasks (30%)" - review: "# 10/10 tasks (100%) - awaiting review" - done: "# ✅ COMPLETED: Brief summary" Benefits: - Sprint-status.yaml becomes a real-time progress dashboard - No need to open individual story files to check progress - Immediate visibility when stories stall (same % for days) - Enables better sprint planning and resource allocation Files Modified: - dev-story/instructions.xml (BMM + BMGD): Added mandatory task-level updates - sprint-status/instructions.md (BMM + BMGD): Added progress parsing/display - batch-super-dev/step-4.5-reconcile-story-status.md: Added progress to reconciliation - docs/HOW-TO-VALIDATE-SPRINT-STATUS.md: Documented new format and enforcement Breaking Change: None (backward compatible with old format) - Old entries without progress comments still work - New entries automatically add progress - Gradual migration as stories are worked --- docs/HOW-TO-VALIDATE-SPRINT-STATUS.md | 30 +++++++++++++ .../4-production/dev-story/instructions.xml | 33 ++++++++++++++ .../sprint-status/instructions.md | 45 ++++++++++++++++--- .../step-4.5-reconcile-story-status.md | 24 +++++++++- .../dev-story/instructions.xml | 33 ++++++++++++++ .../sprint-status/instructions.md | 45 ++++++++++++++++--- 6 files changed, 196 insertions(+), 14 deletions(-) diff --git a/docs/HOW-TO-VALIDATE-SPRINT-STATUS.md b/docs/HOW-TO-VALIDATE-SPRINT-STATUS.md index 0afa30ba..f73a2e58 100644 --- a/docs/HOW-TO-VALIDATE-SPRINT-STATUS.md +++ b/docs/HOW-TO-VALIDATE-SPRINT-STATUS.md @@ -1,10 +1,40 @@ # How to Validate Sprint Status - Complete Guide **Created:** 2026-01-02 +**Updated:** 2026-01-07 (v1.3.0 - Continuous Progress Tracking) **Purpose:** Ensure sprint-status.yaml and story files reflect REALITY, not fiction --- +## 🆕 Progress Tracking (v1.3.0) + +**NEW:** sprint-status.yaml is now updated **after EVERY task completion**, not just at story start/end. + +### Progress Format + +```yaml +development_status: + 1-2-login: in-progress # 3/10 tasks (30%) + 1-3-auth: in-progress # 7/8 tasks (88%) + 1-4-api: review # 10/10 tasks (100%) - awaiting review + 1-5-ui: done # ✅ COMPLETED: Dashboard + widgets + tests +``` + +### Update Frequency + +| Event | Status Update | Progress Update | +|-------|---------------|-----------------| +| Story starts | `ready-for-dev` → `in-progress` | `# 0/10 tasks (0%)` | +| Task 1 completes | (no change) | `# 1/10 tasks (10%)` ✅ | +| Task 2 completes | (no change) | `# 2/10 tasks (20%)` ✅ | +| ... | ... | ... | +| Task 10 completes | `in-progress` → `review` | `# 10/10 tasks (100%) - awaiting review` | +| Review passes | `review` → `done` | `# ✅ COMPLETED: Summary` | + +**Enforcement:** dev-story Step 8 now includes CRITICAL enforcement that HALTs if sprint-status.yaml update fails. + +--- + ## Three Levels of Validation ### Level 1: Status Field Validation (FAST - Free) diff --git a/src/modules/bmgd/workflows/4-production/dev-story/instructions.xml b/src/modules/bmgd/workflows/4-production/dev-story/instructions.xml index 97aef086..b6c7112f 100644 --- a/src/modules/bmgd/workflows/4-production/dev-story/instructions.xml +++ b/src/modules/bmgd/workflows/4-production/dev-story/instructions.xml @@ -485,6 +485,39 @@ HALT if unable to fix validation failures + + + MUST update sprint-status.yaml after EVERY task completion - not just at story start/end + + Load the FULL file: {{sprint_status}} + Find development_status key matching {{story_key}} + + Count total tasks and checked tasks from story file: + - total_tasks = count of all [ ] and [x] in Tasks/Subtasks section (top-level only) + - checked_tasks = count of [x] only + - progress_pct = (checked_tasks / total_tasks) × 100 + + + Update sprint-status.yaml entry with inline progress comment: + Format: {{story_key}}: in-progress # {{checked_tasks}}/{{total_tasks}} tasks ({{progress_pct}}%) + + + Save file, preserving ALL comments and structure + + Re-read {sprint_status} file to verify update persisted + + + ❌ CRITICAL: sprint-status.yaml progress update failed! + + Task was completed but sprint status not updated. + This violates the continuous tracking requirement. + + HALT - Cannot proceed without valid progress tracking + + + ✅ Sprint progress updated: {{story_key}} → {{checked_tasks}}/{{total_tasks}} ({{progress_pct}}%) + + Count total resolved review items in this session Add Change Log entry: "Addressed code review findings - {{resolved_count}} items resolved (Date: {{date}})" diff --git a/src/modules/bmgd/workflows/4-production/sprint-status/instructions.md b/src/modules/bmgd/workflows/4-production/sprint-status/instructions.md index e160775e..145187c6 100644 --- a/src/modules/bmgd/workflows/4-production/sprint-status/instructions.md +++ b/src/modules/bmgd/workflows/4-production/sprint-status/instructions.md @@ -38,7 +38,7 @@ Run `/bmad:bmgd:workflows:sprint-planning` to generate it, then rerun sprint-sta Parse fields: generated, project, project_key, tracking_system, story_location Parse development_status map. Classify keys: - Epics: keys starting with "epic-" (and not ending with "-retrospective") - - Retrospectives: keys ending with "-retrospective" + - Retrospectives: keys ending with "-retrospective") - Stories: everything else (e.g., 1-2-login-form) Map legacy story status "drafted" → "ready-for-dev" Count story statuses: backlog, ready-for-dev, in-progress, review, done @@ -46,12 +46,25 @@ Run `/bmad:bmgd:workflows:sprint-planning` to generate it, then rerun sprint-sta Count epic statuses: backlog, in-progress, done Count retrospective statuses: optional, done + Parse inline progress comments (NEW v1.3.0): + - Extract task progress from comments: "# X/Y tasks (Z%)" + - Extract completion notes from comments: "# ✅ COMPLETED: ..." + - Store progress data for display + + Validate all statuses against known values: - Valid story statuses: backlog, ready-for-dev, in-progress, review, done, drafted (legacy) - Valid epic statuses: backlog, in-progress, done, contexted (legacy) - Valid retrospective statuses: optional, done +Progress comments (NEW v1.3.0): Inline comments now track task completion percentage for in-progress stories + + 1-2-login: in-progress # 7/10 tasks (70%) + 1-3-auth: review # 8/8 tasks (100%) - awaiting review + 1-4-api: done # ✅ COMPLETED: REST endpoints + validation + tests + + ⚠️ **Unknown status detected:** @@ -141,11 +154,31 @@ If the command targets a story, set `story_key={{next_story_id}}` when prompted. ### Stories by Status -- In Progress: {{stories_in_progress}} -- Review: {{stories_in_review}} -- Ready for Dev: {{stories_ready_for_dev}} -- Backlog: {{stories_backlog}} -- Done: {{stories_done}} + +**In Progress ({{count_in_progress}}):** +{{#each stories_in_progress}} +- {{story_key}}: {{status}} {{#if progress}}# {{progress.checked}}/{{progress.total}} ({{progress.pct}}%){{/if}} +{{/each}} + +**Review ({{count_review}}):** +{{#each stories_in_review}} +- {{story_key}}: {{status}} {{#if progress}}# {{progress.checked}}/{{progress.total}} ({{progress.pct}}%){{/if}} +{{/each}} + +**Ready for Dev ({{count_ready}}):** +{{#each stories_ready_for_dev}} +- {{story_key}}: {{status}} +{{/each}} + +**Backlog ({{count_backlog}}):** +{{#each stories_backlog}} +- {{story_key}}: {{status}} +{{/each}} + +**Done ({{count_done}}):** +{{#each stories_done}} +- {{story_key}}: {{status}} {{#if completion_note}}# {{completion_note}}{{/if}} +{{/each}} diff --git a/src/modules/bmm/workflows/4-implementation/batch-super-dev/step-4.5-reconcile-story-status.md b/src/modules/bmm/workflows/4-implementation/batch-super-dev/step-4.5-reconcile-story-status.md index c31b1e7c..ad2e49dc 100644 --- a/src/modules/bmm/workflows/4-implementation/batch-super-dev/step-4.5-reconcile-story-status.md +++ b/src/modules/bmm/workflows/4-implementation/batch-super-dev/step-4.5-reconcile-story-status.md @@ -274,12 +274,32 @@ Verify story file accuracy by reconciling: - + Use Edit tool to update status entry - Update comment if needed to reflect completion + + Count tasks from story file: + - total_tasks = all top-level tasks + - checked_tasks = tasks marked [x] + - progress_pct = (checked_tasks / total_tasks) × 100 + + + Update comment with progress tracking (NEW v1.3.0): + If status == "in-progress": + Format: {{story_key}}: in-progress # {{checked_tasks}}/{{total_tasks}} tasks ({{progress_pct}}%) + + If status == "review": + Format: {{story_key}}: review # {{checked_tasks}}/{{total_tasks}} tasks ({{progress_pct}}%) - awaiting review + + If status == "done": + Format: {{story_key}}: done # ✅ COMPLETED: {{brief_summary}} + + Before: 20-8-...: ready-for-dev # Story description + During: 20-8-...: in-progress # 3/10 tasks (30%) + During: 20-8-...: in-progress # 7/10 tasks (70%) + Review: 20-8-...: review # 10/10 tasks (100%) - awaiting review After: 20-8-...: done # ✅ COMPLETED: Component + tests + docs diff --git a/src/modules/bmm/workflows/4-implementation/dev-story/instructions.xml b/src/modules/bmm/workflows/4-implementation/dev-story/instructions.xml index 71a28aa7..3f0c54ed 100644 --- a/src/modules/bmm/workflows/4-implementation/dev-story/instructions.xml +++ b/src/modules/bmm/workflows/4-implementation/dev-story/instructions.xml @@ -499,6 +499,39 @@ HALT if unable to fix validation failures + + + MUST update sprint-status.yaml after EVERY task completion - not just at story start/end + + Load the FULL file: {{sprint_status}} + Find development_status key matching {{story_key}} + + Count total tasks and checked tasks from story file: + - total_tasks = count of all [ ] and [x] in Tasks/Subtasks section (top-level only) + - checked_tasks = count of [x] only + - progress_pct = (checked_tasks / total_tasks) × 100 + + + Update sprint-status.yaml entry with inline progress comment: + Format: {{story_key}}: in-progress # {{checked_tasks}}/{{total_tasks}} tasks ({{progress_pct}}%) + + + Save file, preserving ALL comments and structure + + Re-read {sprint_status} file to verify update persisted + + + ❌ CRITICAL: sprint-status.yaml progress update failed! + + Task was completed but sprint status not updated. + This violates the continuous tracking requirement. + + HALT - Cannot proceed without valid progress tracking + + + ✅ Sprint progress updated: {{story_key}} → {{checked_tasks}}/{{total_tasks}} ({{progress_pct}}%) + + Count total resolved review items in this session Add Change Log entry: "Addressed code review findings - {{resolved_count}} items resolved (Date: {{date}})" diff --git a/src/modules/bmm/workflows/4-implementation/sprint-status/instructions.md b/src/modules/bmm/workflows/4-implementation/sprint-status/instructions.md index 978b9229..77b54f96 100644 --- a/src/modules/bmm/workflows/4-implementation/sprint-status/instructions.md +++ b/src/modules/bmm/workflows/4-implementation/sprint-status/instructions.md @@ -38,7 +38,7 @@ Run `/bmad:bmm:workflows:sprint-planning` to generate it, then rerun sprint-stat Parse fields: generated, project, project_key, tracking_system, story_location Parse development_status map. Classify keys: - Epics: keys starting with "epic-" (and not ending with "-retrospective") - - Retrospectives: keys ending with "-retrospective" + - Retrospectives: keys ending with "-retrospective") - Stories: everything else (e.g., 1-2-login-form) Map legacy story status "drafted" → "ready-for-dev" Count story statuses: backlog, ready-for-dev, in-progress, review, done @@ -46,12 +46,25 @@ Run `/bmad:bmm:workflows:sprint-planning` to generate it, then rerun sprint-stat Count epic statuses: backlog, in-progress, done Count retrospective statuses: optional, done + Parse inline progress comments (NEW v1.3.0): + - Extract task progress from comments: "# X/Y tasks (Z%)" + - Extract completion notes from comments: "# ✅ COMPLETED: ..." + - Store progress data for display + + Validate all statuses against known values: - Valid story statuses: backlog, ready-for-dev, in-progress, review, done, drafted (legacy) - Valid epic statuses: backlog, in-progress, done, contexted (legacy) - Valid retrospective statuses: optional, done +Progress comments (NEW v1.3.0): Inline comments now track task completion percentage for in-progress stories + + 1-2-login: in-progress # 7/10 tasks (70%) + 1-3-auth: review # 8/8 tasks (100%) - awaiting review + 1-4-api: done # ✅ COMPLETED: REST endpoints + validation + tests + + ⚠️ **Unknown status detected:** @@ -141,11 +154,31 @@ If the command targets a story, set `story_key={{next_story_id}}` when prompted. ### Stories by Status -- In Progress: {{stories_in_progress}} -- Review: {{stories_in_review}} -- Ready for Dev: {{stories_ready_for_dev}} -- Backlog: {{stories_backlog}} -- Done: {{stories_done}} + +**In Progress ({{count_in_progress}}):** +{{#each stories_in_progress}} +- {{story_key}}: {{status}} {{#if progress}}# {{progress.checked}}/{{progress.total}} ({{progress.pct}}%){{/if}} +{{/each}} + +**Review ({{count_review}}):** +{{#each stories_in_review}} +- {{story_key}}: {{status}} {{#if progress}}# {{progress.checked}}/{{progress.total}} ({{progress.pct}}%){{/if}} +{{/each}} + +**Ready for Dev ({{count_ready}}):** +{{#each stories_ready_for_dev}} +- {{story_key}}: {{status}} +{{/each}} + +**Backlog ({{count_backlog}}):** +{{#each stories_backlog}} +- {{story_key}}: {{status}} +{{/each}} + +**Done ({{count_done}}):** +{{#each stories_done}} +- {{story_key}}: {{status}} {{#if completion_note}}# {{completion_note}}{{/if}} +{{/each}}