From 0420f12ca90dc758c9298d19f7356ebc5e6567b3 Mon Sep 17 00:00:00 2001 From: Cristiano Justo Date: Tue, 3 Mar 2026 19:45:13 -0300 Subject: [PATCH 1/4] fix: add mandatory post-verdict status update steps to task workflows MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit validate-next-story.md and qa-gate.md define complete validation workflows but lack imperative steps to update story status after verdict. Status transitions are defined in story-lifecycle.md (advisory rules) but agents follow task files procedurally and skip advisory rules not embedded in the workflow. Added: - Step 12 to validate-next-story.md: Draft → Ready on GO, keep Draft on NO-GO - Post-Gate Status Update to qa-gate.md: InReview → Done on PASS/CONCERNS/WAIVED, InReview → InProgress on FAIL Both steps include Change Log entry requirements and rationale explaining the advisory vs imperative gap. Co-Authored-By: Claude Opus 4.6 --- .aiox-core/development/tasks/qa-gate.md | 45 +++++++++++++++++-- .../development/tasks/validate-next-story.md | 32 ++++++++++++- 2 files changed, 73 insertions(+), 4 deletions(-) diff --git a/.aiox-core/development/tasks/qa-gate.md b/.aiox-core/development/tasks/qa-gate.md index 7cf7a1b45f..8e9240dc43 100644 --- a/.aiox-core/development/tasks/qa-gate.md +++ b/.aiox-core/development/tasks/qa-gate.md @@ -420,11 +420,50 @@ Gate: CONCERNS → qa.qaLocation/gates/{epic}.{story}-{slug}.yml - Always update story with gate reference - Clear, actionable findings +## Post-Gate Status Update (MANDATORY) + +**Reference:** `.claude/rules/story-lifecycle.md` — Status transitions are @qa responsibility during QA gate. + +**This step MUST be executed before presenting results to user.** + +### IF verdict is PASS or CONCERNS: + +1. **Update story Status field** in the story file: change `**InReview**` to `**Done**` +2. **Add Change Log entry:** + ``` + | {today's date} | {next version} | QA Gate {PASS|CONCERNS} — Status: InReview → Done | @qa | + ``` +3. **Log:** "✅ Story status updated: InReview → Done" + +### IF verdict is FAIL: + +1. **Update story Status field** in the story file: change `**InReview**` to `**InProgress**` +2. **Add Change Log entry:** + ``` + | {today's date} | {next version} | QA Gate FAIL — Status: InReview → InProgress — {reason} | @qa | + ``` +3. **Log:** "❌ Story returned to InProgress — fixes required" + +### IF verdict is WAIVED: + +1. **Update story Status field** in the story file: change `**InReview**` to `**Done**` +2. **Add Change Log entry:** + ``` + | {today's date} | {next version} | QA Gate WAIVED — Status: InReview → Done — {waiver reason} | @qa | + ``` +3. **Log:** "⚠️ Story status updated: InReview → Done (waived)" + +### Rationale + +Status transitions defined in `story-lifecycle.md` are advisory (contextual rules). This step makes them imperative (procedural), ensuring agents always execute the transition as part of the workflow rather than relying on contextual rule awareness. + +--- + ## Handoff next_agent: @devops next_command: *push -condition: QA gate verdict is PASS +condition: QA gate verdict is PASS (status updated to Done) alternatives: - - agent: @dev, command: *apply-qa-fixes, condition: QA gate verdict is FAIL or CONCERNS - - agent: @po, command: *close-story {story-id}, condition: QA gate verdict is WAIVED + - agent: @dev, command: *apply-qa-fixes, condition: QA gate verdict is FAIL (status updated to InProgress) + - agent: @po, command: *close-story {story-id}, condition: QA gate verdict is WAIVED (status updated to Done) \ No newline at end of file diff --git a/.aiox-core/development/tasks/validate-next-story.md b/.aiox-core/development/tasks/validate-next-story.md index 20157eb2cd..7ffeea046f 100644 --- a/.aiox-core/development/tasks/validate-next-story.md +++ b/.aiox-core/development/tasks/validate-next-story.md @@ -463,10 +463,40 @@ Provide a structured validation report including: - **Implementation Readiness Score**: 1-10 scale - **Confidence Level**: High/Medium/Low for successful implementation +### 12. Post-Validation Status Update (MANDATORY) + +**Reference:** `.claude/rules/story-lifecycle.md` — Draft → Ready transition is @po responsibility. + +**This step MUST be executed before presenting results to user.** + +#### IF verdict is GO (score >= 7): + +1. **Update story Status field** in the story file: change `**Draft**` to `**Ready**` +2. **Add Change Log entry:** + ``` + | {today's date} | {next version} | Validated GO ({score}/10) — Status: Draft → Ready | @po | + ``` +3. **Log:** "✅ Story status updated: Draft → Ready" + +#### IF verdict is NO-GO (score < 7): + +1. **Keep** story Status as `**Draft**` +2. **Add Change Log entry:** + ``` + | {today's date} | {next version} | Validation NO-GO — {reason summary} | @po | + ``` +3. **Log:** "❌ Story remains Draft — fixes required before re-validation" + +#### Rationale + +Status transitions defined in `story-lifecycle.md` are advisory (contextual rules). This step makes them imperative (procedural), ensuring agents always execute the transition as part of the workflow rather than relying on contextual rule awareness. + +--- + ## Handoff next_agent: @dev next_command: *develop {story-id} -condition: Story status is Approved (GO decision) +condition: Story status is Ready (GO decision, status updated in Step 12) alternatives: - agent: @sm, command: *draft, condition: Story rejected (NO-GO), needs rework \ No newline at end of file From e339dd8ef949b6c6796189394e5c5c3db55c9aac Mon Sep 17 00:00:00 2001 From: Cristiano Justo Date: Tue, 3 Mar 2026 19:58:10 -0300 Subject: [PATCH 2/4] fix: address CodeRabbit review feedback - Add pre-check guards before status mutations (verify current status and Change Log section exist before transitioning) - Add language labels to fenced code blocks (```text) for markdownlint MD040 - Add explicit handoff alternative for CONCERNS verdict routing to @po Co-Authored-By: Claude Opus 4.6 --- .aiox-core/development/tasks/qa-gate.md | 16 +++++++++++++--- .../development/tasks/validate-next-story.md | 10 ++++++++-- 2 files changed, 21 insertions(+), 5 deletions(-) diff --git a/.aiox-core/development/tasks/qa-gate.md b/.aiox-core/development/tasks/qa-gate.md index 8e9240dc43..337c72b9d9 100644 --- a/.aiox-core/development/tasks/qa-gate.md +++ b/.aiox-core/development/tasks/qa-gate.md @@ -428,27 +428,36 @@ Gate: CONCERNS → qa.qaLocation/gates/{epic}.{story}-{slug}.yml ### IF verdict is PASS or CONCERNS: +0. **Pre-check (blocking):** + - If current Status is not `**InReview**`, HALT and log: "Cannot apply PASS/CONCERNS transition: expected InReview, found {current status}." + - If Change Log section is missing, HALT and request user to restore template structure. 1. **Update story Status field** in the story file: change `**InReview**` to `**Done**` 2. **Add Change Log entry:** - ``` + ```text | {today's date} | {next version} | QA Gate {PASS|CONCERNS} — Status: InReview → Done | @qa | ``` 3. **Log:** "✅ Story status updated: InReview → Done" ### IF verdict is FAIL: +0. **Pre-check (blocking):** + - If current Status is not `**InReview**`, HALT and log: "Cannot apply FAIL transition: expected InReview, found {current status}." + - If Change Log section is missing, HALT and request user to restore template structure. 1. **Update story Status field** in the story file: change `**InReview**` to `**InProgress**` 2. **Add Change Log entry:** - ``` + ```text | {today's date} | {next version} | QA Gate FAIL — Status: InReview → InProgress — {reason} | @qa | ``` 3. **Log:** "❌ Story returned to InProgress — fixes required" ### IF verdict is WAIVED: +0. **Pre-check (blocking):** + - If current Status is not `**InReview**`, HALT and log: "Cannot apply WAIVED transition: expected InReview, found {current status}." + - If Change Log section is missing, HALT and request user to restore template structure. 1. **Update story Status field** in the story file: change `**InReview**` to `**Done**` 2. **Add Change Log entry:** - ``` + ```text | {today's date} | {next version} | QA Gate WAIVED — Status: InReview → Done — {waiver reason} | @qa | ``` 3. **Log:** "⚠️ Story status updated: InReview → Done (waived)" @@ -464,6 +473,7 @@ next_agent: @devops next_command: *push condition: QA gate verdict is PASS (status updated to Done) alternatives: + - agent: @po, command: *review-concerns {story-id}, condition: QA gate verdict is CONCERNS (status updated to Done) - agent: @dev, command: *apply-qa-fixes, condition: QA gate verdict is FAIL (status updated to InProgress) - agent: @po, command: *close-story {story-id}, condition: QA gate verdict is WAIVED (status updated to Done) \ No newline at end of file diff --git a/.aiox-core/development/tasks/validate-next-story.md b/.aiox-core/development/tasks/validate-next-story.md index 7ffeea046f..c8bac3beab 100644 --- a/.aiox-core/development/tasks/validate-next-story.md +++ b/.aiox-core/development/tasks/validate-next-story.md @@ -471,18 +471,24 @@ Provide a structured validation report including: #### IF verdict is GO (score >= 7): +0. **Pre-check (blocking):** + - If current Status is not `**Draft**`, HALT and log: "Cannot apply GO transition: expected Draft, found {current status}." + - If Change Log section is missing, HALT and request user to restore template structure. 1. **Update story Status field** in the story file: change `**Draft**` to `**Ready**` 2. **Add Change Log entry:** - ``` + ```text | {today's date} | {next version} | Validated GO ({score}/10) — Status: Draft → Ready | @po | ``` 3. **Log:** "✅ Story status updated: Draft → Ready" #### IF verdict is NO-GO (score < 7): +0. **Pre-check (blocking):** + - If current Status is not `**Draft**`, HALT and log: "Cannot apply NO-GO outcome: expected Draft, found {current status}." + - If Change Log section is missing, HALT and request user to restore template structure. 1. **Keep** story Status as `**Draft**` 2. **Add Change Log entry:** - ``` + ```text | {today's date} | {next version} | Validation NO-GO — {reason summary} | @po | ``` 3. **Log:** "❌ Story remains Draft — fixes required before re-validation" From f6303b43db798e316d26a687431c34c685ed2d8e Mon Sep 17 00:00:00 2001 From: Cristiano Justo Date: Tue, 3 Mar 2026 20:22:13 -0300 Subject: [PATCH 3/4] fix: add mandatory status transitions to dev-develop-story.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The @dev task workflow set status to "Ready for Review" (non-standard) instead of following the story-lifecycle.md transitions: - Ready → InProgress (on development start) - InProgress → InReview (on development complete) Added: - Status Transitions section with pre-checks, Change Log entries, and logging for both start and completion transitions - Updated all 3 execution modes (YOLO, Interactive, Pre-Flight) to reference InReview instead of Ready for Review - Updated handoff condition to reflect correct status Co-Authored-By: Claude Opus 4.6 --- .../development/tasks/dev-develop-story.md | 46 +++++++++++++++++-- 1 file changed, 41 insertions(+), 5 deletions(-) diff --git a/.aiox-core/development/tasks/dev-develop-story.md b/.aiox-core/development/tasks/dev-develop-story.md index 253025a4dd..3052742b9a 100644 --- a/.aiox-core/development/tasks/dev-develop-story.md +++ b/.aiox-core/development/tasks/dev-develop-story.md @@ -370,7 +370,7 @@ const { - All tasks complete - All tests pass - Execute story-dod-checklist - - Set status: "Ready for Review" + - Set status: "InReview" (see Status Transitions section) - **Generate decision log**: ```javascript const logPath = await completeDecisionLogging(storyId, 'completed'); @@ -416,7 +416,7 @@ const { - All tests pass - Execute story-dod-checklist - Present completion summary to user - - Set status: "Ready for Review" + - Set status: "InReview" (see Status Transitions section) **User Prompts**: 5-10 (balanced for control and speed) @@ -467,7 +467,7 @@ const { - All tests pass - Execute story-dod-checklist - Present execution summary vs. plan - - Set status: "Ready for Review" + - Set status: "InReview" (see Status Transitions section) **User Prompts**: All upfront (questionnaire phase), then 0 during execution @@ -501,7 +501,7 @@ const { - Completion Notes List - File List - Change Log (add entry on completion) -- Status (set to "Ready for Review" when complete) +- Status (set to "InReview" when complete — see Status Transitions section) **DO NOT modify**: Story, Acceptance Criteria, Dev Notes, Testing sections @@ -915,10 +915,46 @@ Found 5 technical decisions needed. - **Educational Value**: Interactive mode explanations help developers learn framework patterns - **Scope Drift Prevention**: Pre-flight mode eliminates mid-development ambiguity +## Status Transitions (MANDATORY — All Modes) + +**Reference:** `.claude/rules/story-lifecycle.md` — @dev owns Ready → InProgress and InProgress → InReview transitions. + +**These steps MUST be executed at the specified points, regardless of execution mode.** + +### On Development Start (before first task): + +0. **Pre-check (blocking):** + - If current Status is not `**Ready**`, HALT and log: "Cannot start development: expected Ready, found {current status}." + - If Change Log section is missing, HALT and request user to restore template structure. +1. **Update story Status field:** change `**Ready**` to `**InProgress**` +2. **Add Change Log entry:** + ```text + | {today's date} | {next version} | Development started ({mode} mode) — Status: Ready → InProgress | @dev | + ``` +3. **Log:** "🚀 Story status updated: Ready → InProgress" + +### On Development Complete (after DOD checklist, before HALT): + +0. **Pre-check (blocking):** + - If current Status is not `**InProgress**`, HALT and log: "Cannot mark for review: expected InProgress, found {current status}." + - If Change Log section is missing, HALT and request user to restore template structure. +1. **Update story Status field:** change `**InProgress**` to `**InReview**` +2. **Add Change Log entry:** + ```text + | {today's date} | {next version} | Development complete — Status: InProgress → InReview | @dev | + ``` +3. **Log:** "✅ Story status updated: InProgress → InReview" + +### Rationale + +Status transitions defined in `story-lifecycle.md` are advisory (contextual rules). These steps make them imperative (procedural), ensuring agents always execute the transitions as part of the workflow rather than relying on contextual rule awareness. + +--- + ## Handoff next_agent: @qa next_command: *review {story-id} -condition: Story status is Ready for Review +condition: Story status is InReview (updated in Status Transitions above) alternatives: - agent: @qa, command: *gate {story-id}, condition: Quick gate decision needed - agent: @dev, command: *apply-qa-fixes, condition: Self-identified issues during dev From 06b284a45672ca953d35b9921d7a9e3650844b87 Mon Sep 17 00:00:00 2001 From: Cristiano Justo Date: Thu, 5 Mar 2026 17:18:57 -0300 Subject: [PATCH 4/4] fix: address CodeRabbit review feedback on task workflows - Make InProgress pre-check idempotent for resume scenarios (dev-develop-story) - Rename "Ready for Review" to "InReview" for status consistency (dev-develop-story) - Add CONCERNS to PASS handoff condition (qa-gate) - Fix trailing whitespace in qa-gate and validate-next-story Co-Authored-By: Claude Opus 4.6 --- .aiox-core/development/tasks/dev-develop-story.md | 9 +++++---- .aiox-core/development/tasks/qa-gate.md | 5 ++--- .aiox-core/development/tasks/validate-next-story.md | 1 - 3 files changed, 7 insertions(+), 8 deletions(-) diff --git a/.aiox-core/development/tasks/dev-develop-story.md b/.aiox-core/development/tasks/dev-develop-story.md index 3052742b9a..048faadf76 100644 --- a/.aiox-core/development/tasks/dev-develop-story.md +++ b/.aiox-core/development/tasks/dev-develop-story.md @@ -514,7 +514,7 @@ const { - Missing configuration - Failing regression tests -### Ready for Review Criteria (All Modes) +### InReview Criteria (All Modes) - Code matches all requirements - All validations pass @@ -530,7 +530,7 @@ const { 5. File List is complete 6. **Execute CodeRabbit Self-Healing Loop** (see below) 7. Execute `.aiox-core/product/checklists/story-dod-checklist.md` -8. Set story status: "Ready for Review" +8. Set story status: "InReview" (see Status Transitions section) 9. HALT (do not proceed further) --- @@ -924,9 +924,10 @@ Found 5 technical decisions needed. ### On Development Start (before first task): 0. **Pre-check (blocking):** - - If current Status is not `**Ready**`, HALT and log: "Cannot start development: expected Ready, found {current status}." + - If current Status is `**InProgress**`, skip to first uncompleted task (resume scenario — no status change needed). + - If current Status is not `**Ready**` and not `**InProgress**`, HALT and log: "Cannot start development: expected Ready or InProgress, found {current status}." - If Change Log section is missing, HALT and request user to restore template structure. -1. **Update story Status field:** change `**Ready**` to `**InProgress**` +1. **Update story Status field:** change `**Ready**` to `**InProgress**` (skip if already InProgress) 2. **Add Change Log entry:** ```text | {today's date} | {next version} | Development started ({mode} mode) — Status: Ready → InProgress | @dev | diff --git a/.aiox-core/development/tasks/qa-gate.md b/.aiox-core/development/tasks/qa-gate.md index 337c72b9d9..b0279fb230 100644 --- a/.aiox-core/development/tasks/qa-gate.md +++ b/.aiox-core/development/tasks/qa-gate.md @@ -471,9 +471,8 @@ Status transitions defined in `story-lifecycle.md` are advisory (contextual rule ## Handoff next_agent: @devops next_command: *push -condition: QA gate verdict is PASS (status updated to Done) +condition: QA gate verdict is PASS or CONCERNS (status updated to Done) alternatives: - - agent: @po, command: *review-concerns {story-id}, condition: QA gate verdict is CONCERNS (status updated to Done) + - agent: @po, command: *review-concerns {story-id}, condition: QA gate verdict is CONCERNS (status updated to Done, has non-blocking issues) - agent: @dev, command: *apply-qa-fixes, condition: QA gate verdict is FAIL (status updated to InProgress) - agent: @po, command: *close-story {story-id}, condition: QA gate verdict is WAIVED (status updated to Done) - \ No newline at end of file diff --git a/.aiox-core/development/tasks/validate-next-story.md b/.aiox-core/development/tasks/validate-next-story.md index c8bac3beab..5821c40dc4 100644 --- a/.aiox-core/development/tasks/validate-next-story.md +++ b/.aiox-core/development/tasks/validate-next-story.md @@ -505,4 +505,3 @@ next_command: *develop {story-id} condition: Story status is Ready (GO decision, status updated in Step 12) alternatives: - agent: @sm, command: *draft, condition: Story rejected (NO-GO), needs rework - \ No newline at end of file