diff --git a/src/modules/bmm/workflows/4-implementation/autonomous-epic/README.md b/src/modules/bmm/workflows/4-implementation/autonomous-epic/README.md
index a7b02bb6..0046be6b 100644
--- a/src/modules/bmm/workflows/4-implementation/autonomous-epic/README.md
+++ b/src/modules/bmm/workflows/4-implementation/autonomous-epic/README.md
@@ -96,6 +96,40 @@ autonomous_settings:
max_retry_per_story: 2 # Retry failed stories
create_git_commits: true # Commit after each story
git_branch_prefix: "auto-epic-" # Branch: auto-epic-{epic_num}
+
+# Task-based completion verification (NEW)
+completion_verification:
+ task_based_completion: true # Check actual tasks, not just status
+ process_review_with_unchecked: true # Process "review" stories with unchecked tasks
+ process_done_with_unchecked: true # Process "done" stories if tasks remain
+ verify_after_development: true # Re-check after each story
+ strict_epic_completion: true # Epic only done when ALL tasks complete
+```
+
+### Task-Based Completion (Important!)
+
+**The autonomous epic workflow now uses TASK-BASED completion**, not just status-based:
+
+| What Changed | Old Behavior | New Behavior |
+|--------------|--------------|--------------|
+| "review" status | ⏭️ Skipped | ✅ Processed if unchecked tasks exist |
+| "done" status | ⏭️ Skipped | ✅ Verified, processed if tasks remain |
+| Completion check | Status-based | Task-based (count `- [ ]`) |
+| Epic marked done | When all stories "done" | When ALL tasks `- [x]` |
+
+**Why this matters:** Code reviews often add new tasks (CR-1, CR-2, etc.) that need implementation. The old workflow would skip these stories because they were marked "review". Now we scan for actual unchecked tasks.
+
+```
+📊 Epic 4 Status (Task-Based Analysis)
+
+By Actual Task Completion:
+- ✅ Truly Done: 0 (all tasks checked, will skip)
+- 🔧 Needs Work: 7 (has unchecked tasks)
+ 4-1: 6 unchecked (CR tasks)
+ 4-2: 4 unchecked (original work)
+ 4-3: 7 unchecked (CR tasks)
+ ...
+- 📝 Backlog: 0 (will create + develop)
```
### Per-Epic Override
diff --git a/src/modules/bmm/workflows/4-implementation/autonomous-epic/instructions.xml b/src/modules/bmm/workflows/4-implementation/autonomous-epic/instructions.xml
index 6bf85a7a..590b4351 100644
--- a/src/modules/bmm/workflows/4-implementation/autonomous-epic/instructions.xml
+++ b/src/modules/bmm/workflows/4-implementation/autonomous-epic/instructions.xml
@@ -4,6 +4,21 @@
Communicate all responses in {communication_language}
🤖 AUTONOMOUS EPIC PROCESSING - Full automation of epic completion!
This workflow orchestrates create-story and super-dev-story for each story in an epic
+ TASK-BASED COMPLETION: A story is ONLY complete when it has ZERO unchecked tasks (- [ ])
+
+
+ ⚡ AUTONOMOUS MODE: When auto_accept_gap_analysis=true in workflow.yaml, you MUST:
+ - NEVER ask the user to approve gap analysis refinements
+ - AUTOMATICALLY accept all gap analysis proposals
+ - PROCEED immediately without waiting for user input on gap analysis
+ - Only ask for user input at the START of the workflow (epic selection, Y/D/n choice)
+
+ ⚡ INVOKING SUB-WORKFLOWS: When you see invoke-workflow, you must:
+ 1. Load the referenced workflow.yaml file
+ 2. Load its instructions.xml file
+ 3. Execute that workflow completely
+ 4. Return to this workflow and continue
+
-
- Get current branch name
- Create new branch: auto-epic-{{epic_num}}
-
+
+ Get current branch name and store as {{current_branch}}
+
+
+ Create new branch: auto-epic-{{epic_num}}
+
+
+
+
+
+
Initialize progress tracking file:
- epic_num
@@ -96,23 +141,28 @@
- 🔄 STORY LOOP - Create and develop each story
+ 🔄 STORY LOOP - Create and develop each story until ALL tasks complete
- Find all stories in epic {{epic_num}} needing work
- Sort by story number (ascending)
+ Build ordered list of stories needing work:
+ 1. All stories with unchecked tasks (regardless of status)
+ 2. All backlog stories
+ 3. Sort by story number (ascending)
+
Initialize counters: success=0, failure=0
Set {{current_story}}
+ Read story file and count unchecked tasks
-
+
@@ -131,38 +181,62 @@
-
-
+
+
+
-
-
-
-
- Includes: dev + post-gap + review + push-all
-
-
+
+
+
+
+
+ Includes: dev + post-gap + review + push-all (auto-accepting gap analysis)
+
+
-
-
-
-
+
+
+
+
+
-
-
- Commit and push story changes
-
-
+
+ Read story file and extract "File List" section
+ Parse all file paths, include the story file itself
+ Store as {{story_files}} - space-separated list
-
- Increment success_count
- Update progress file
-
+
+
+
+
+ Only commit files from this story (parallel-agent safe)
+
+
-
-
- Add to failed_stories, continue
- Increment failure_count
-
+
+ Re-read story file and count unchecked tasks
+
+
+
+ Log incomplete tasks for review
+ Mark as partial success
+
+
+
+
+ Update story status to "done" in sprint-status.yaml
+
+
+ Increment success_count
+ Update progress file
+
+
+
+
+ Add to failed_stories with error details
+ Increment failure_count
+
+
@@ -171,24 +245,39 @@
+
+ Re-scan all epic stories for unchecked tasks
+ Calculate: total_remaining_tasks across all stories
+
-
+
Update sprint-status: epic-{{epic_num}} = "done"
diff --git a/src/modules/bmm/workflows/4-implementation/autonomous-epic/workflow.yaml b/src/modules/bmm/workflows/4-implementation/autonomous-epic/workflow.yaml
index 43005ddd..8679007e 100644
--- a/src/modules/bmm/workflows/4-implementation/autonomous-epic/workflow.yaml
+++ b/src/modules/bmm/workflows/4-implementation/autonomous-epic/workflow.yaml
@@ -26,7 +26,29 @@ autonomous_settings:
halt_on_error: false # Continue even if story fails
max_retry_per_story: 2 # Retry failed stories
create_git_commits: true # Commit after each story
- git_branch_prefix: "auto-epic-" # Branch name format: auto-epic-{epic_num}
+ create_epic_branch: false # When false, stay on current branch (good for parallel epics)
+ git_branch_prefix: "auto-epic-" # Branch name format: auto-epic-{epic_num} (only used if create_epic_branch=true)
+
+# TASK-BASED COMPLETION SETTINGS (NEW)
+# These settings ensure stories are truly complete, not just marked as such
+completion_verification:
+ # Use task-based completion instead of status-based
+ # A story is ONLY complete when it has ZERO unchecked tasks (- [ ])
+ task_based_completion: true
+
+ # Include stories in "review" status if they have unchecked tasks
+ # This catches code review findings that were added but not implemented
+ process_review_with_unchecked: true
+
+ # Include stories in "done" status if they have unchecked tasks
+ # This catches stories incorrectly marked done
+ process_done_with_unchecked: true
+
+ # Verify completion after each story by re-scanning for unchecked tasks
+ verify_after_development: true
+
+ # Only mark epic as "done" if ALL stories have ZERO unchecked tasks
+ strict_epic_completion: true
standalone: true
diff --git a/src/modules/bmm/workflows/4-implementation/create-story-with-gap-analysis/README.md b/src/modules/bmm/workflows/4-implementation/create-story-with-gap-analysis/README.md
new file mode 100644
index 00000000..1cc40f3c
--- /dev/null
+++ b/src/modules/bmm/workflows/4-implementation/create-story-with-gap-analysis/README.md
@@ -0,0 +1,170 @@
+# Create Story With Gap Analysis
+
+**Custom Workflow by Jonah Schulte**
+**Created:** December 24, 2025
+**Purpose:** Generate stories with SYSTEMATIC codebase gap analysis (not inference-based)
+
+---
+
+## Problem This Solves
+
+**Standard `/create-story` workflow:**
+- ❌ Reads previous stories and git commits (passive)
+- ❌ Infers what probably exists (guessing)
+- ❌ Gap analysis quality varies by agent thoroughness
+- ❌ Checkboxes may not reflect reality
+
+**This custom workflow:**
+- ✅ Actively scans codebase with Glob/Read tools
+- ✅ Verifies file existence (not inference)
+- ✅ Reads key files to check implementation depth (mocked vs real)
+- ✅ Generates TRUTHFUL gap analysis
+- ✅ Checkboxes are FACTS verified by file system
+
+---
+
+## Usage
+
+```bash
+/create-story-with-gap-analysis
+
+# Or via Skill tool:
+Skill: "create-story-with-gap-analysis"
+Args: "1.9" (epic.story number)
+```
+
+**Workflow will:**
+1. Load existing story + epic context
+2. **SCAN codebase systematically** (Glob for files, Read to verify implementation)
+3. Generate gap analysis with verified ✅/❌/⚠️ status
+4. Update story file with truthful checkboxes
+5. Save to docs/sprint-artifacts/
+
+---
+
+## What It Scans
+
+**For each story, the workflow:**
+
+1. **Identifies target directories** (from story title/requirements)
+ - Example: "admin-user-service" → apps/backend/admin-user-service/
+
+2. **Globs for all files**
+ - `{target}/src/**/*.ts` - Find all TypeScript files
+ - `{target}/src/**/*.spec.ts` - Find all tests
+
+3. **Checks specific required files**
+ - Based on ACs, check if files exist
+ - Example: `src/auth/controllers/bridgeid-auth.controller.ts` → ❌ MISSING
+
+4. **Reads key files to verify depth**
+ - Check if mocked: Search for "MOCK" string
+ - Check if incomplete: Search for "TODO"
+ - Verify real implementation exists
+
+5. **Checks package.json**
+ - Verify required dependencies are installed
+ - Identify missing packages
+
+6. **Counts tests**
+ - How many test files exist
+ - Coverage for each component
+
+---
+
+## Output Format
+
+**Generates story with:**
+
+1. ✅ Standard BMAD 5 sections (Story, AC, Tasks, Dev Notes, Dev Agent Record)
+2. ✅ Enhanced Dev Notes with verified gap analysis subsections:
+ - Gap Analysis: Current State vs Requirements
+ - Library/Framework Requirements (from package.json)
+ - File Structure Requirements (from Glob results)
+ - Testing Requirements (from test file count)
+ - Architecture Compliance
+ - Previous Story Intelligence
+
+3. ✅ Truthful checkboxes based on verified file existence
+
+---
+
+## Difference from Standard /create-story
+
+| Feature | /create-story | /create-story-with-gap-analysis |
+|---------|---------------|--------------------------------|
+| Reads previous story | ✅ | ✅ |
+| Reads git commits | ✅ | ✅ |
+| Loads epic context | ✅ | ✅ |
+| **Scans codebase with Glob** | ❌ | ✅ SYSTEMATIC |
+| **Verifies files exist** | ❌ | ✅ VERIFIED |
+| **Reads files to check depth** | ❌ | ✅ MOCKED vs REAL |
+| **Checks package.json** | ❌ | ✅ DEPENDENCIES |
+| **Counts test coverage** | ❌ | ✅ COVERAGE |
+| Gap analysis quality | Variable (agent-dependent) | Systematic (tool-verified) |
+| Checkbox accuracy | Inference-based | File-existence-based |
+
+---
+
+## When to Use
+
+**This workflow (planning-time gap analysis):**
+- Use when regenerating/auditing stories
+- Use when you want verified checkboxes upfront
+- Best for stories that will be implemented immediately
+- Manual verification at planning time
+
+**Standard /create-story + /dev-story (dev-time gap analysis):**
+- Recommended for most workflows
+- Stories start as DRAFT, validated when dev begins
+- Prevents staleness in batch planning
+- Automatic verification at development time
+
+**Use standard /create-story when:**
+- Greenfield project (nothing exists yet)
+- Backlog stories (won't be implemented for months)
+- Epic planning phase (just sketching ideas)
+
+**Tip:** Both approaches are complementary. You can use this workflow to regenerate stories, then use `/dev-story` which will re-validate at dev-time.
+
+---
+
+## Examples
+
+**Regenerating Story 1.9:**
+```bash
+/create-story-with-gap-analysis
+
+Choice: 1.9
+
+# Workflow will:
+# 1. Load existing 1-9-admin-user-service-bridgeid-rbac.md
+# 2. Identify target: apps/backend/admin-user-service/
+# 3. Glob: apps/backend/admin-user-service/src/**/*.ts (finds 47 files)
+# 4. Check: src/auth/controllers/bridgeid-auth.controller.ts → ❌ MISSING
+# 5. Read: src/bridgeid/services/bridgeid-client.service.ts → ⚠️ MOCKED
+# 6. Read: package.json → axios ❌ NOT INSTALLED
+# 7. Generate gap analysis with verified status
+# 8. Write story with truthful checkboxes
+```
+
+**Result:** Story with verified gap analysis showing:
+- ✅ 7 components IMPLEMENTED (verified file existence)
+- ❌ 6 components MISSING (verified file not found)
+- ⚠️ 1 component PARTIAL (file exists but contains "MOCK")
+
+---
+
+## Installation
+
+This workflow is auto-discovered when BMAD is installed.
+
+**To use:**
+```bash
+/bmad:bmm:workflows:create-story-with-gap-analysis
+```
+
+---
+
+**Last Updated:** December 27, 2025
+**Status:** Integrated into BMAD-METHOD
diff --git a/src/modules/bmm/workflows/4-implementation/create-story-with-gap-analysis/step-01-initialize.md b/src/modules/bmm/workflows/4-implementation/create-story-with-gap-analysis/step-01-initialize.md
new file mode 100644
index 00000000..2b1c9499
--- /dev/null
+++ b/src/modules/bmm/workflows/4-implementation/create-story-with-gap-analysis/step-01-initialize.md
@@ -0,0 +1,82 @@
+# Step 1: Initialize and Extract Story Requirements
+
+## Goal
+Load epic context and identify what needs to be scanned in the codebase.
+
+## Execution
+
+### 1. Determine Story to Create
+
+**Ask user:**
+```
+Which story should I regenerate with gap analysis?
+
+Options:
+1. Provide story number (e.g., "1.9" or "1-9")
+2. Provide story filename (e.g., "1-9-admin-user-service-bridgeid-rbac.md")
+
+Your choice:
+```
+
+**Parse input:**
+- Extract epic_num (e.g., "1")
+- Extract story_num (e.g., "9")
+- Locate story file: `docs/sprint-artifacts/{epic_num}-{story_num}-*.md`
+
+### 2. Load Existing Story Content
+
+```bash
+Read: docs/sprint-artifacts/{epic_num}-{story_num}-*.md
+```
+
+**Extract from existing story:**
+- Story title
+- User story text (As a... I want... So that...)
+- Acceptance criteria (the requirements, not checkboxes)
+- Any existing Dev Notes or technical context
+
+**Store for later use.**
+
+### 3. Load Epic Context
+
+```bash
+Glob: docs/archive/planning-round-1-greenfield/epics/epic-{epic_num}-*.md
+Read: [found epic file]
+```
+
+**Extract from epic:**
+- Epic business objectives
+- This story's original requirements
+- Technical constraints
+- Dependencies on other stories
+
+### 4. Determine Target Directories
+
+**From story title and requirements, identify:**
+- Which service/app this story targets
+- Which directories to scan
+
+**Examples:**
+- "admin-user-service" → `apps/backend/admin-user-service/`
+- "Widget Batch 1" → `packages/widgets/`
+- "POE Integration" → `apps/frontend/web/`
+
+**Store target directories for Step 2 codebase scan.**
+
+### 5. Ready for Codebase Scan
+
+**Output:**
+```
+✅ Story Context Loaded
+
+Story: {epic_num}.{story_num} - {title}
+Target directories identified:
+ - {directory_1}
+ - {directory_2}
+
+Ready to scan codebase for gap analysis.
+
+[C] Continue to Codebase Scan
+```
+
+**WAIT for user to select Continue.**
diff --git a/src/modules/bmm/workflows/4-implementation/create-story-with-gap-analysis/step-02-codebase-scan.md b/src/modules/bmm/workflows/4-implementation/create-story-with-gap-analysis/step-02-codebase-scan.md
new file mode 100644
index 00000000..69f4022f
--- /dev/null
+++ b/src/modules/bmm/workflows/4-implementation/create-story-with-gap-analysis/step-02-codebase-scan.md
@@ -0,0 +1,184 @@
+# Step 2: Systematic Codebase Gap Analysis
+
+## Goal
+VERIFY what code actually exists vs what's missing using Glob and Read tools.
+
+## CRITICAL
+This step uses ACTUAL file system tools to generate TRUTHFUL gap analysis.
+No guessing. No inference. VERIFY with tools.
+
+## Execution
+
+### 1. Scan Target Directories
+
+**For each target directory identified in Step 1:**
+
+```bash
+# List all TypeScript files
+Glob: {target_dir}/src/**/*.ts
+Glob: {target_dir}/src/**/*.tsx
+
+# Store file list
+```
+
+**Output:**
+```
+📁 Codebase Scan Results for {target_dir}
+
+Found {count} TypeScript files:
+ - {file1}
+ - {file2}
+ ...
+```
+
+### 2. Check for Specific Required Components
+
+**Based on story Acceptance Criteria, check if required files exist:**
+
+**Example for Auth Story:**
+```bash
+# Check for OAuth endpoints
+Glob: {target_dir}/src/auth/controllers/*bridgeid*.ts
+Result: ❌ MISSING (0 files found)
+
+# Check for BridgeID client
+Glob: {target_dir}/src/bridgeid/**/*.ts
+Result: ✅ EXISTS (found: bridgeid-client.service.ts, bridgeid-sync.service.ts)
+
+# Check for permission guards
+Glob: {target_dir}/src/auth/guards/permissions*.ts
+Result: ❌ MISSING (0 files found)
+
+# Check for decorators
+Glob: {target_dir}/src/auth/decorators/*permission*.ts
+Result: ❌ MISSING (0 files found)
+```
+
+### 3. Verify Implementation Depth
+
+**For files that exist, read them to check if MOCKED or REAL:**
+
+```bash
+# Read key implementation file
+Read: {target_dir}/src/bridgeid/services/bridgeid-client.service.ts
+
+# Search for indicators:
+- Contains "MOCK" or "mock" → ⚠️ MOCKED (needs real implementation)
+- Contains "TODO" → ⚠️ INCOMPLETE
+- Contains real HTTP client (axios) → ✅ IMPLEMENTED
+```
+
+### 4. Check Dependencies
+
+```bash
+# Read package.json
+Read: {target_dir}/package.json
+
+# Verify required dependencies exist:
+Required: axios
+Found in package.json? → ❌ NO (needs to be added)
+
+Required: @aws-sdk/client-secrets-manager
+Found in package.json? → ❌ NO (needs to be added)
+```
+
+### 5. Check Test Coverage
+
+```bash
+# Find test files
+Glob: {target_dir}/src/**/*.spec.ts
+Glob: {target_dir}/test/**/*.test.ts
+
+# Count tests
+Found {test_count} test files
+
+# Check for specific test coverage
+Glob: {target_dir}/src/**/*bridgeid*.spec.ts
+Result: ✅ EXISTS (found 3 test files)
+```
+
+### 6. Generate Truthful Gap Analysis
+
+**Create structured gap analysis:**
+
+```markdown
+## Gap Analysis: Current State vs Requirements
+
+**✅ IMPLEMENTED (Verified by Codebase Scan):**
+
+1. **BridgeID Client Infrastructure** - MOCKED (needs real HTTP)
+ - File: src/bridgeid/services/bridgeid-client.service.ts ✅ EXISTS
+ - Implementation: Mock user data with circuit breaker
+ - Status: ⚠️ PARTIAL - Ready for real HTTP client
+ - Tests: 15 tests passing ✅
+
+2. **User Synchronization Service**
+ - File: src/bridgeid/services/bridgeid-sync.service.ts ✅ EXISTS
+ - Implementation: Bulk sync BridgeID → admin_users
+ - Status: ✅ COMPLETE
+ - Tests: 6 tests passing ✅
+
+3. **Role Mapping Logic**
+ - File: src/bridgeid/constants/role-mapping.constants.ts ✅ EXISTS
+ - Implementation: 7-tier role mapping with priority selection
+ - Status: ✅ COMPLETE
+ - Tests: 10 tests passing ✅
+
+**❌ MISSING (Required for AC Completion):**
+
+1. **BridgeID OAuth Endpoints**
+ - File: src/auth/controllers/bridgeid-auth.controller.ts ❌ NOT FOUND
+ - Need: POST /api/auth/bridgeid/login endpoint
+ - Need: GET /api/auth/bridgeid/callback endpoint
+ - Status: ❌ NOT IMPLEMENTED
+
+2. **Permission Guards**
+ - File: src/auth/guards/permissions.guard.ts ❌ NOT FOUND
+ - File: src/auth/decorators/require-permissions.decorator.ts ❌ NOT FOUND
+ - Status: ❌ NOT IMPLEMENTED
+
+3. **Real OAuth HTTP Client**
+ - Package: axios ❌ NOT in package.json
+ - Package: @aws-sdk/client-secrets-manager ❌ NOT in package.json
+ - Status: ❌ DEPENDENCIES NOT ADDED
+```
+
+### 7. Update Acceptance Criteria Checkboxes
+
+**Based on verified gap analysis, mark checkboxes:**
+
+```markdown
+### AC1: BridgeID OAuth Integration
+- [ ] OAuth login endpoint (VERIFIED MISSING - file not found)
+- [ ] OAuth callback endpoint (VERIFIED MISSING - file not found)
+- [ ] Client configuration (VERIFIED PARTIAL - exists but mocked)
+
+### AC3: RBAC Permission System
+- [x] Role mapping defined (VERIFIED COMPLETE - file exists, tests pass)
+- [ ] Permission guard (VERIFIED MISSING - file not found)
+- [ ] Permission decorator (VERIFIED MISSING - file not found)
+```
+
+**Checkboxes are now FACTS, not guesses.**
+
+### 8. Present Gap Analysis
+
+**Output:**
+```
+✅ Codebase Scan Complete
+
+Scanned: apps/backend/admin-user-service/
+Files found: 47 TypeScript files
+Tests found: 31 test files
+
+Gap Analysis Generated:
+ ✅ 7 components IMPLEMENTED (verified)
+ ❌ 6 components MISSING (verified)
+ ⚠️ 1 component PARTIAL (needs completion)
+
+Story checkboxes updated based on verified file existence.
+
+[C] Continue to Story Generation
+```
+
+**WAIT for user to continue.**
diff --git a/src/modules/bmm/workflows/4-implementation/create-story-with-gap-analysis/step-03-generate-story.md b/src/modules/bmm/workflows/4-implementation/create-story-with-gap-analysis/step-03-generate-story.md
new file mode 100644
index 00000000..c0a3a5e9
--- /dev/null
+++ b/src/modules/bmm/workflows/4-implementation/create-story-with-gap-analysis/step-03-generate-story.md
@@ -0,0 +1,181 @@
+# Step 3: Generate Story with Verified Gap Analysis
+
+## Goal
+Generate complete 7-section story file using verified gap analysis from Step 2.
+
+## Execution
+
+### 1. Load Template
+
+```bash
+Read: _bmad/custom/workflows/create-story-with-gap-analysis/template.md
+```
+
+### 2. Fill Template Variables
+
+**Basic Story Info:**
+- `{{epic_num}}` - from Step 1
+- `{{story_num}}` - from Step 1
+- `{{story_title}}` - from existing story or epic
+- `{{priority}}` - from epic (P0, P1, P2)
+- `{{effort}}` - from epic or estimate
+
+**Story Section:**
+- `{{role}}` - from existing story
+- `{{action}}` - from existing story
+- `{{benefit}}` - from existing story
+
+**Business Context:**
+- `{{business_value}}` - from epic context
+- `{{scale_requirements}}` - from epic/architecture
+- `{{compliance_requirements}}` - from epic/architecture
+- `{{urgency}}` - from epic priority
+
+**Acceptance Criteria:**
+- `{{acceptance_criteria}}` - from epic + existing story
+- Update checkboxes based on Step 2 gap analysis:
+ - [x] = Component verified EXISTS
+ - [ ] = Component verified MISSING
+ - [~] = Component verified PARTIAL (optional notation)
+
+**Tasks / Subtasks:**
+- `{{tasks_subtasks}}` - from epic + existing story
+- Add "✅ DONE", "⚠️ PARTIAL", "❌ TODO" markers based on gap analysis
+
+**Gap Analysis Section:**
+- `{{implemented_components}}` - from Step 2 codebase scan (verified ✅)
+- `{{missing_components}}` - from Step 2 codebase scan (verified ❌)
+- `{{partial_components}}` - from Step 2 codebase scan (verified ⚠️)
+
+**Architecture Compliance:**
+- `{{architecture_patterns}}` - from architecture doc + playbooks
+- Multi-tenant isolation requirements
+- Caching strategies
+- Error handling patterns
+- Performance requirements
+
+**Library/Framework Requirements:**
+- `{{current_dependencies}}` - from Step 2 package.json scan
+- `{{required_dependencies}}` - missing deps identified in Step 2
+
+**File Structure:**
+- `{{existing_files}}` - from Step 2 Glob results (verified ✅)
+- `{{required_files}}` - from gap analysis (verified ❌)
+
+**Testing Requirements:**
+- `{{test_count}}` - from Step 2 test file count
+- `{{required_tests}}` - based on missing components
+- `{{coverage_target}}` - from architecture or default 90%
+
+**Dev Agent Guardrails:**
+- `{{guardrails}}` - from playbooks + previous story lessons
+- What NOT to do
+- Common mistakes to avoid
+
+**Previous Story Intelligence:**
+- `{{previous_story_learnings}}` - from Step 1 previous story Dev Agent Record
+
+**Project Structure Notes:**
+- `{{structure_alignment}}` - from architecture compliance
+
+**References:**
+- `{{references}}` - Links to epic, architecture, playbooks, related stories
+
+**Definition of Done:**
+- Standard DoD checklist with story-specific coverage target
+
+### 3. Generate Complete Story
+
+**Write filled template:**
+```bash
+Write: docs/sprint-artifacts/{{epic_num}}-{{story_num}}-{{slug}}.md
+[Complete 7-section story with verified gap analysis]
+```
+
+### 4. Validate Generated Story
+
+```bash
+# Check section count
+grep "^## " docs/sprint-artifacts/{{story_file}} | wc -l
+# Should output: 7
+
+# Check for gap analysis
+grep -q "Gap Analysis.*Current State" docs/sprint-artifacts/{{story_file}}
+# Should find it
+
+# Run custom validation
+./scripts/validate-bmad-format.sh docs/sprint-artifacts/{{story_file}}
+# Update script to expect 7 sections + gap analysis subsection
+```
+
+### 5. Update Sprint Status
+
+```bash
+Read: docs/sprint-artifacts/sprint-status.yaml
+
+# Find story entry
+# Update status to "ready-for-dev" if was "backlog"
+# Preserve all comments and structure
+
+Write: docs/sprint-artifacts/sprint-status.yaml
+```
+
+### 6. Report Completion
+
+**Output:**
+```
+✅ Story {{epic_num}}.{{story_num}} Regenerated with Gap Analysis
+
+File: docs/sprint-artifacts/{{story_file}}
+Sections: 7/7 ✅
+Gap Analysis: VERIFIED with codebase scan
+
+Summary:
+ ✅ {{implemented_count}} components IMPLEMENTED (verified by file scan)
+ ❌ {{missing_count}} components MISSING (verified file not found)
+ ⚠️ {{partial_count}} components PARTIAL (file exists but mocked/incomplete)
+
+Checkboxes in ACs and Tasks reflect VERIFIED status (not guesses).
+
+Next Steps:
+1. Review story file for accuracy
+2. Use /dev-story to implement missing components
+3. Story provides complete context for flawless implementation
+
+Story is ready for development. 🚀
+```
+
+### 7. Cleanup
+
+**Ask user:**
+```
+Story regeneration complete!
+
+Would you like to:
+[N] Regenerate next story ({{next_story_num}})
+[Q] Quit workflow
+[R] Review generated story first
+
+Your choice:
+```
+
+**If N selected:** Loop back to Step 1 with next story number
+**If Q selected:** End workflow
+**If R selected:** Display story file, then show menu again
+
+---
+
+## Success Criteria
+
+**Story generation succeeds when:**
+1. ✅ 7 top-level ## sections present
+2. ✅ Gap Analysis subsection exists with ✅/❌/⚠️ verified status
+3. ✅ Checkboxes match codebase reality (spot-checked)
+4. ✅ Dev Notes has all mandatory subsections
+5. ✅ Definition of Done checklist included
+6. ✅ File saved to correct location
+7. ✅ Sprint status updated
+
+---
+
+**WORKFLOW COMPLETE - Ready to execute.**
diff --git a/src/modules/bmm/workflows/4-implementation/create-story-with-gap-analysis/template.md b/src/modules/bmm/workflows/4-implementation/create-story-with-gap-analysis/template.md
new file mode 100644
index 00000000..c0b7c87d
--- /dev/null
+++ b/src/modules/bmm/workflows/4-implementation/create-story-with-gap-analysis/template.md
@@ -0,0 +1,179 @@
+# Story {{epic_num}}.{{story_num}}: {{story_title}}
+
+**Status:** ready-for-dev
+**Epic:** {{epic_num}}
+**Priority:** {{priority}}
+**Estimated Effort:** {{effort}}
+
+---
+
+## Story
+
+As a **{{role}}**,
+I want to **{{action}}**,
+So that **{{benefit}}**.
+
+---
+
+## Business Context
+
+### Why This Matters
+
+{{business_value}}
+
+### Production Reality
+
+{{scale_requirements}}
+{{compliance_requirements}}
+{{urgency}}
+
+---
+
+## Acceptance Criteria
+
+{{acceptance_criteria}}
+
+---
+
+## Tasks / Subtasks
+
+{{tasks_subtasks}}
+
+---
+
+## Dev Notes
+
+### Gap Analysis: Current State vs Requirements
+
+**✅ IMPLEMENTED (Verified by Codebase Scan):**
+
+{{implemented_components}}
+
+**❌ MISSING (Required for AC Completion):**
+
+{{missing_components}}
+
+**⚠️ PARTIAL (Needs Enhancement):**
+
+{{partial_components}}
+
+### Architecture Compliance
+
+{{architecture_patterns}}
+
+### Library/Framework Requirements
+
+**Current Dependencies:**
+```json
+{{current_dependencies}}
+```
+
+**Required Additions:**
+```json
+{{required_dependencies}}
+```
+
+### File Structure Requirements
+
+**Completed Files:**
+```
+{{existing_files}}
+```
+
+**Required New Files:**
+```
+{{required_files}}
+```
+
+### Testing Requirements
+
+**Current Test Coverage:** {{test_count}} tests passing
+
+**Required Additional Tests:**
+{{required_tests}}
+
+**Target:** {{coverage_target}}
+
+### Dev Agent Guardrails
+
+{{guardrails}}
+
+### Previous Story Intelligence
+
+{{previous_story_learnings}}
+
+### Project Structure Notes
+
+{{structure_alignment}}
+
+### References
+
+{{references}}
+
+---
+
+## Definition of Done
+
+### Code Quality (BLOCKING)
+- [ ] Type check passes: `pnpm type-check` (zero errors)
+- [ ] Zero `any` types in new code
+- [ ] Lint passes: `pnpm lint` (zero errors in new code)
+- [ ] Build succeeds: `pnpm build`
+
+### Testing (BLOCKING)
+- [ ] Unit tests: {{coverage_target}} coverage
+- [ ] Integration tests: Key workflows validated
+- [ ] All tests pass: New + existing (zero regressions)
+
+### Security (BLOCKING)
+- [ ] Dependency scan: `pnpm audit` (zero high/critical)
+- [ ] No hardcoded secrets
+- [ ] Input validation on all endpoints
+- [ ] Auth checks on protected endpoints
+- [ ] Audit logging on mutations
+
+### Architecture Compliance (BLOCKING)
+- [ ] Multi-tenant isolation: dealerId in all queries
+- [ ] Cache namespacing: Cache keys include siteId
+- [ ] Performance: External APIs cached, no N+1 queries
+- [ ] Error handling: No silent failures
+- [ ] Follows patterns from playbooks
+
+### Deployment Validation (BLOCKING)
+- [ ] Service starts: `pnpm dev` runs successfully
+- [ ] Health check: `/health` returns 200
+- [ ] Smoke test: Primary functionality verified
+
+### Documentation (BLOCKING)
+- [ ] API docs: Swagger decorators on endpoints
+- [ ] Inline comments: Complex logic explained
+- [ ] Story file: Dev Agent Record complete
+
+---
+
+## Dev Agent Record
+
+### Agent Model Used
+
+(To be filled by dev agent)
+
+### Implementation Summary
+
+(To be filled by dev agent)
+
+### File List
+
+(To be filled by dev agent)
+
+### Test Results
+
+(To be filled by dev agent)
+
+### Completion Notes
+
+(To be filled by dev agent)
+
+---
+
+**Generated by:** /create-story-with-gap-analysis
+**Date:** {{date}}
diff --git a/src/modules/bmm/workflows/4-implementation/create-story-with-gap-analysis/workflow.yaml b/src/modules/bmm/workflows/4-implementation/create-story-with-gap-analysis/workflow.yaml
new file mode 100644
index 00000000..b408bbed
--- /dev/null
+++ b/src/modules/bmm/workflows/4-implementation/create-story-with-gap-analysis/workflow.yaml
@@ -0,0 +1,38 @@
+name: create-story-with-gap-analysis
+description: "Create/regenerate story with SYSTEMATIC codebase gap analysis using verified file scanning (Glob/Read tools)"
+author: "Jonah Schulte"
+
+# Critical variables from config
+config_source: "{project-root}/_bmad/bmm/config.yaml"
+user_name: "{config_source}:user_name"
+communication_language: "{config_source}:communication_language"
+date: system-generated
+implementation_artifacts: "{config_source}:implementation_artifacts"
+output_folder: "{implementation_artifacts}"
+story_dir: "{implementation_artifacts}"
+
+# Workflow components
+installed_path: "{project-root}/_bmad/bmm/workflows/4-implementation/create-story-with-gap-analysis"
+template: "{installed_path}/template.md"
+instructions: "{installed_path}/step-01-initialize.md"
+
+# Variables and inputs
+variables:
+ sprint_status: "{implementation_artifacts}/sprint-status.yaml"
+ epics_file: "{output_folder}/epics.md"
+ prd_file: "{output_folder}/PRD.md"
+
+# Project context
+project_context: "**/project-context.md"
+
+default_output_file: "{story_dir}/{{story_key}}.md"
+
+# Workflow steps (processed in order)
+steps:
+ - step-01-initialize.md
+ - step-02-codebase-scan.md
+ - step-03-generate-story.md
+
+standalone: true
+
+web_bundle: false
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 41c1bd69..e56b1639 100644
--- a/src/modules/bmm/workflows/4-implementation/dev-story/instructions.xml
+++ b/src/modules/bmm/workflows/4-implementation/dev-story/instructions.xml
@@ -217,6 +217,20 @@
+
+
+
+ Update story file with refined tasks in Tasks/Subtasks section
+ Add new "Gap Analysis" section to story file with findings:
+ - Scan timestamp
+ - What Exists summary
+ - What's Missing summary
+ - Task changes applied
+
+ Add Change Log entry: "Tasks refined based on codebase gap analysis - auto-accepted ({{date}})"
+
+
+
**Approve these task updates?**
Options:
diff --git a/src/modules/bmm/workflows/4-implementation/dev-story/workflow.yaml b/src/modules/bmm/workflows/4-implementation/dev-story/workflow.yaml
index d5824ee1..0dc61a8d 100644
--- a/src/modules/bmm/workflows/4-implementation/dev-story/workflow.yaml
+++ b/src/modules/bmm/workflows/4-implementation/dev-story/workflow.yaml
@@ -22,6 +22,9 @@ implementation_artifacts: "{config_source}:implementation_artifacts"
sprint_status: "{implementation_artifacts}/sprint-status.yaml"
project_context: "**/project-context.md"
+# Autonomous mode settings (passed from parent workflow like autonomous-epic)
+auto_accept_gap_analysis: false # When true, skip gap analysis approval prompt
+
standalone: true
web_bundle: false
diff --git a/src/modules/bmm/workflows/4-implementation/push-all/instructions.xml b/src/modules/bmm/workflows/4-implementation/push-all/instructions.xml
index 31a614a1..9e5b715d 100644
--- a/src/modules/bmm/workflows/4-implementation/push-all/instructions.xml
+++ b/src/modules/bmm/workflows/4-implementation/push-all/instructions.xml
@@ -2,8 +2,19 @@
The workflow execution engine is governed by: {project-root}/_bmad/core/tasks/workflow.xml
You MUST have already loaded and processed: {installed_path}/workflow.yaml
Communicate all responses in {communication_language}
- 📝 PUSH-ALL - Stage, commit, and push all changes with comprehensive safety validation
- ⚠️ Use with caution - commits ALL repository changes
+ 📝 PUSH-ALL - Stage, commit, and push changes with comprehensive safety validation
+
+
+ ⚡ PARALLEL AGENT MODE: When {{target_files}} is provided:
+ - ONLY stage and commit the specified files
+ - Do NOT use `git add .` or `git add -A`
+ - Use `git add [specific files]` instead
+ - This prevents committing work from other parallel agents
+
+ 📋 ALL FILES MODE: When {{target_files}} is empty:
+ - Stage ALL changes with `git add .`
+ - Original behavior for single-agent execution
+
- Execute: git add .
- Execute: git status
+
+
+
+
+
+
+
+ Execute: git add .
+ Execute: git status
+
+
diff --git a/src/modules/bmm/workflows/4-implementation/push-all/workflow.yaml b/src/modules/bmm/workflows/4-implementation/push-all/workflow.yaml
index 8f35fd5e..1eedfe30 100644
--- a/src/modules/bmm/workflows/4-implementation/push-all/workflow.yaml
+++ b/src/modules/bmm/workflows/4-implementation/push-all/workflow.yaml
@@ -1,5 +1,5 @@
name: push-all
-description: "Stage all changes, create commit with safety checks, and push to remote - use with caution"
+description: "Stage changes, create commit with safety checks, and push to remote"
author: "BMad"
# Critical variables from config
@@ -11,6 +11,12 @@ communication_language: "{config_source}:communication_language"
installed_path: "{project-root}/_bmad/bmm/workflows/4-implementation/push-all"
instructions: "{installed_path}/instructions.xml"
+# Target files to commit (for parallel agent execution)
+# When empty/not provided: commits ALL changes (original behavior)
+# When provided: only commits the specified files (safe for parallel agents)
+target_files: "" # Space-separated list of file paths, or empty for all
+story_key: "" # Optional: story identifier for commit message context
+
standalone: true
web_bundle: false
diff --git a/src/modules/bmm/workflows/4-implementation/sprint-planning/instructions.md b/src/modules/bmm/workflows/4-implementation/sprint-planning/instructions.md
index c4f4bd42..d5bb1d91 100644
--- a/src/modules/bmm/workflows/4-implementation/sprint-planning/instructions.md
+++ b/src/modules/bmm/workflows/4-implementation/sprint-planning/instructions.md
@@ -75,10 +75,33 @@ development_status:
- Check: `{story_location_absolute}/{story-key}.md` (e.g., `stories/1-1-user-authentication.md`)
- If exists → upgrade status to at least `ready-for-dev`
+**Story file status sync (CRITICAL):**
+
+- If story file exists, read the `Status:` field from the story markdown header
+- Common status field patterns: `Status: done`, `Status: review`, `Status: in-progress`
+- If story file has a more advanced status than current sprint-status entry:
+ - Update sprint-status to match the story file status
+ - This ensures sprint-status stays in sync when stories are manually marked done
+
+**Status priority order** (lowest to highest):
+1. `backlog` (no story file)
+2. `ready-for-dev` (story file exists)
+3. `in-progress` (developer working)
+4. `review` (code review pending)
+5. `done` (story complete)
+
**Preservation rule:**
- If existing `{status_file}` exists and has more advanced status, preserve it
- Never downgrade status (e.g., don't change `done` to `ready-for-dev`)
+- Story file status is the **source of truth** - always sync from story file to sprint-status
+
+**Epic status auto-detection:**
+
+- After syncing all story statuses, calculate epic status:
+ - If ALL stories in epic are `done` → set epic to `done`
+ - If ANY story is `in-progress`, `review`, or `done` → set epic to `in-progress`
+ - Otherwise → keep epic as `backlog`
**Status Flow Reference:**
diff --git a/src/modules/bmm/workflows/4-implementation/super-dev-story/instructions.xml b/src/modules/bmm/workflows/4-implementation/super-dev-story/instructions.xml
index d777ad93..b296847a 100644
--- a/src/modules/bmm/workflows/4-implementation/super-dev-story/instructions.xml
+++ b/src/modules/bmm/workflows/4-implementation/super-dev-story/instructions.xml
@@ -33,7 +33,8 @@
- Pass through any user-provided story file path
+
+ Pass through any user-provided story file path and auto-accept setting
@@ -113,6 +114,7 @@
+
Resume with added tasks for missing work
@@ -167,6 +169,7 @@
+
Fix code review issues
@@ -186,6 +189,7 @@
Add review findings as tasks
+
@@ -208,16 +212,28 @@
-
+
📝 PUSH-ALL - Stage, commit, and push with safety validation
+ ⚡ TARGETED COMMIT: Only commit files from THIS story's File List (safe for parallel agents)
-