diff --git a/src/bmm/workflows/4-implementation/create-story/checklist.md b/src/bmm/workflows/4-implementation/create-story/checklist.md
index 0f5075e9f..991f651c2 100644
--- a/src/bmm/workflows/4-implementation/create-story/checklist.md
+++ b/src/bmm/workflows/4-implementation/create-story/checklist.md
@@ -35,7 +35,7 @@ This is a COMPETITION to create the **ULTIMATE story context** that makes LLM de
- The `{project-root}/_bmad/core/tasks/validate-workflow.xml` framework will automatically:
- Load this checklist file
- - Load the newly created story file (`{default_output_file}`)
+ - Load the story file (`{story_file}` when provided, otherwise `{default_output_file}`)
- Load workflow variables from `{installed_path}/workflow.yaml`
- Execute the validation process
@@ -62,15 +62,17 @@ You will systematically re-do the entire story creation process, but with a crit
### **Step 1: Load and Understand the Target**
1. **Load the workflow configuration**: `{installed_path}/workflow.yaml` for variable inclusion
-2. **Load the story file**: `{default_output_file}` (or explicit `{document}` input)
+2. **Load the story file**: `{story_file}` first, fallback to `{default_output_file}` (or explicit `{document}` input)
3. **Load validation framework**: `{project-root}/_bmad/core/tasks/validate-workflow.xml`
4. **Resolve variables deterministically**:
+ - Load config_source file if present
- Parse workflow.yaml key/value pairs
- - For any value matching `{config_source}:key`, load the referenced config file and resolve `key`
+ - For any value matching `{config_source}:key`, resolve from the loaded config source
- Resolve system path variables (for example `{project-root}`, `{installed_path}`) in every path value
- - Required for this checklist flow: `{default_output_file}`, `{epics_file}`, `{architecture_file}`, `{implementation_artifacts}`, `{project-root}`, `{installed_path}`
- - Optional/fallback-capable values: `{story_file}`, validation `{checklist}` input, validation `{report}` input
+ - Required for this checklist flow: `{epics_file}`, `{architecture_file}`, `{implementation_artifacts}`, `{project-root}`, `{installed_path}`, and at least one story locator (`{story_file}` or `{default_output_file}`)
+ - Optional/fallback-capable values: validation `{checklist}` input and validation `{report}` input
- Validation task input contract: `workflow` is required; `checklist`, `document`, and `report` are optional with deterministic fallback
+ - Note: create-story invoke-task passes `document={default_output_file}` explicitly, which overrides fallback discovery
- If any required value remains unresolved, stop and request explicit user input before continuing
5. **Extract metadata**: epic_num, story_num, story_key, story_title from story file
6. **Understand current status**: What story implementation guidance is currently provided?
diff --git a/src/bmm/workflows/4-implementation/create-story/instructions.xml b/src/bmm/workflows/4-implementation/create-story/instructions.xml
index 0612001de..8ddc1c08c 100644
--- a/src/bmm/workflows/4-implementation/create-story/instructions.xml
+++ b/src/bmm/workflows/4-implementation/create-story/instructions.xml
@@ -280,15 +280,15 @@
testing_requirements
- If previous story learnings are unavailable (for example this is story 1 in epic), set previous_story_intelligence to an explicit N/A note with reason
+ If previous story learnings are unavailable (for example this is story 1 in epic), set previous_story_intelligence to the canonical format: N/A: {one-line reason}previous_story_intelligence
- If git analysis is unavailable or not relevant, set git_intelligence_summary to an explicit N/A note with reason
+ If git analysis is unavailable or not relevant, set git_intelligence_summary to the canonical format: N/A: {one-line reason}git_intelligence_summary
- If web research was not completed or not needed, set latest_tech_information to an explicit N/A note with reason
+ If web research was not completed or not needed, set latest_tech_information to the canonical format: N/A: {one-line reason}latest_tech_information
@@ -306,8 +306,8 @@
- Run {project-root}/_bmad/core/tasks/validate-workflow.xml with workflow={installed_path}/workflow.yaml checklist={installed_path}/checklist.md document={default_output_file}Save story document unconditionally
+ Run {project-root}/_bmad/core/tasks/validate-workflow.xml with workflow={installed_path}/workflow.yaml checklist={installed_path}/checklist.md document={default_output_file}
diff --git a/src/core/tasks/validate-workflow.xml b/src/core/tasks/validate-workflow.xml
index 773115fe3..82d23ac27 100644
--- a/src/core/tasks/validate-workflow.xml
+++ b/src/core/tasks/validate-workflow.xml
@@ -9,6 +9,7 @@
+
@@ -49,10 +50,15 @@
Load full target document content (use chunked sequential reads only when needed for large files, and record covered ranges)Extract story metadata when available (epic_num, story_num, story_id, story_key, title) from filename, heading, or frontmatterParse checklist into ordered sections and atomic validation items; assign each item a stable id (section_index.item_index)
- Determine critical checks from explicit signals only: item-level markers ([CRITICAL], critical:true, MUST FIX) or critical section labels; do not infer criticality from generic keywords alone
+ Determine critical checks from explicit signals only:
+ - item-level markers: [CRITICAL], critical:true, MUST FIX
+ - section-level markers: headings containing CRITICAL (case-insensitive), MUST FIX, MUST-FIX, or the exact phrase "Must Fix Before Proceeding"
+ - XML section attributes: critical="true" or critical="yes"
+ - do not infer criticality from generic keywords alone
+ Detect conditional expressions in checklist items (for example: if/when/unless + variable references)HALT with error: "Checklist is empty or unparsable"
- Ask user to provide missing metadata fields (epic_num, story_num, story_id/story_key) and WAIT before evaluating checklist items
+ Ask user to provide all missing referenced metadata fields (epic_num, story_num, story_id, story_key, title/story_title) and WAIT before evaluating checklist items
@@ -66,7 +72,6 @@
For each item:
- restate requirement in one short sentence
- if item contains explicit condition (for example "If story_num > 1") and condition is false, mark N/A with the exact reason
- - if item condition depends on missing metadata, mark PARTIAL (not N/A) and specify required metadata
- locate explicit evidence in document (include line references when possible)
- consider implied coverage only when explicit text is absent
- assign verdict and rationale
@@ -78,7 +83,12 @@
HALT with error: "Validation incomplete: one or more checklist items were not processed"Compute applicable_count = pass_count + partial_count + fail_countCompute pass_percent using applicable_count (if 0, set pass_percent=0)
+ Set gate_warning:
+ - "No applicable checklist items were evaluated; manual confirmation required" if applicable_count == 0
+ - "N/A" otherwise
+ Set gate decision deterministically:
+ - NEEDS_REVIEW if applicable_count == 0
- FAIL if critical_fail_count > 0
- FAIL if critical_partial_count > 0
- FAIL if fail_count > 0
@@ -110,7 +120,8 @@
- Overall pass rate: {pass_count}/{applicable_count} ({pass_percent}%)
- Critical failures: {critical_fail_count}
- Critical partials: {critical_partial_count}
- - Gate decision: {PASS|FAIL}
+ - Gate decision: {PASS|FAIL|NEEDS_REVIEW}
+ - Gate warning: {gate_warning}
## Section Results
### {Section Name}
@@ -126,7 +137,7 @@
- Action (if PARTIAL/FAIL): {specific remediation}
## Must Fix Before Proceeding
- - {all critical FAIL items}
+ - {all critical FAIL and PARTIAL items}
## Should Improve
- {all non-critical FAIL and PARTIAL items}
@@ -142,7 +153,8 @@
Present concise summary with counts and gate decisionProvide report pathState clearly that workflow should not proceed until fixes are applied
- HALT and wait for user direction
+ Return control immediately without waiting for user direction
+ HALT and wait for user direction