Merge 0f708d0b89 into 35ae4fd024

src/modules/bmm/workflows/4-implementation/code-review/checklist.md

@@ -0,0 +1,23 @@
+# Senior Developer Review - Validation Checklist
+
+- [ ] Story file loaded from `{{story_path}}`
+- [ ] Story Status verified as reviewable (review)
+- [ ] Epic and Story IDs resolved ({{epic_num}}.{{story_num}})
+- [ ] Story Context located or warning recorded
+- [ ] Epic Tech Spec located or warning recorded
+- [ ] Architecture/standards docs loaded (as available)
+- [ ] Tech stack detected and documented
+- [ ] MCP doc search performed (or web fallback) and references captured
+- [ ] Acceptance Criteria cross-checked against implementation
+- [ ] File List reviewed and validated for completeness
+- [ ] Tests identified and mapped to ACs; gaps noted
+- [ ] Code quality review performed on changed files
+- [ ] Security review performed on changed files and dependencies
+- [ ] Outcome decided (Approve/Changes Requested/Blocked)
+- [ ] Review notes appended under "Senior Developer Review (AI)"
+- [ ] Change Log updated with review entry
+- [ ] Status updated according to settings (if enabled)
+- [ ] Sprint status synced (if sprint tracking enabled)
+- [ ] Story saved successfully
+
+_Reviewer: {{user_name}} on {{date}}_

src/modules/bmm/workflows/4-implementation/code-review/steps/step-01-load-story.md

@@ -1,21 +1,27 @@
 ---
 name: 'step-01-load-story'
-description: "Compare story's file list against git changes"
+description: 'Load story file, discover git changes, establish review context'
+
+workflow_path: '{project-root}/_bmad/bmm/workflows/4-implementation/code-review'
+thisStepFile: '{workflow_path}/steps/step-01-load-story.md'
+nextStepFile: '{workflow_path}/steps/step-02-build-attack-plan.md'
 ---
 
 # Step 1: Load Story and Discover Changes
 
+**Goal:** Load story file, extract all sections, discover actual git changes for comparison.
+
 ---
 
 ## STATE VARIABLES (capture now, persist throughout)
 
 These variables MUST be set in this step and available to all subsequent steps:
 
-- `story_path` - Path to the story file being reviewed
-- `story_key` - Story identifier (e.g., "1-2-user-authentication")
-- `story_file_list` - Files claimed in story's Dev Agent Record → File List
-- `git_changed_files` - Files actually changed according to git
-- `git_discrepancies` - Mismatches between `story_file_list` and `git_changed_files`
+- `{story_path}` - Path to the story file being reviewed
+- `{story_key}` - Story identifier (e.g., "1-2-user-authentication")
+- `{story_file_list}` - Files claimed in story's Dev Agent Record → File List
+- `{git_changed_files}` - Files actually changed according to git
+- `{git_discrepancies}` - Differences between story claims and git reality
 
 ---
 
@@ -23,32 +29,19 @@ These variables MUST be set in this step and available to all subsequent steps:
 
 ### 1. Identify Story
 
-Ask user: "Which story would you like to review?"
+**If `{story_path}` provided by user:**
 
-**Try input as direct file path first:**
-If input resolves to an existing file:
-  - Verify it's in `sprint_status` with status `review` or `done`
-  - If verified → set `story_path` to that file path
-  - If NOT verified → Warn user the file is not in sprint_status (or wrong status). Ask: "Continue anyway?"
-    - If yes → set `story_path`
-    - If no → return to user prompt (ask "Which story would you like to review?" again)
+- Use the provided path directly
 
-**Search sprint_status** (if input is not a direct file):
-Search for stories with status `review` or `done`. Match by priority:
-1. Story number resembles input closely enough (e.g., "1-2" matches "1 2", "1.2", "one dash two", "one two"; "1-32" matches "one thirty two"). Do NOT match if numbers differ (e.g., "1-33" does not match "1-32")
-2. Exact story name/key (e.g., "1-2-user-auth-api")
-3. Story name/title resembles input closely enough
-4. Story description resembles input closely enough
+**If NOT provided:**
 
-**Resolution:**
-- **Single match**: Confident. Set `story_path`, proceed to substep 2
-- **Multiple matches**: Uncertain. Present all candidates to user. Wait for selection. Set `story_path`, proceed to substep 2
-- **No match**: Ask user to clarify or provide the full story path. Return to user prompt (ask "Which story would you like to review?" again)
+- Ask user which story file to review
+- Wait for response before proceeding
 
 ### 2. Load Story File
 
-- Read COMPLETE story file from {story_path}
-- Extract `story_key` from filename (e.g., "1-2-user-authentication.md" → "1-2-user-authentication") or story metadata
+- Read COMPLETE story file from `{story_path}`
+- Extract `{story_key}` from filename (e.g., "1-2-user-authentication.md" → "1-2-user-authentication") or story metadata
 
 ### 3. Parse Story Sections
 
@@ -60,15 +53,13 @@ Extract and store:
 - **Dev Agent Record → File List**: Claimed file changes
 - **Change Log**: History of modifications
 
-Set `story_file_list` = list of files from Dev Agent Record → File List
+Set `{story_file_list}` = list of files from Dev Agent Record → File List
 
 ### 4. Discover Git Changes
 
-Check if git repository exists.
+Check if git repository exists:
 
-**If NOT a git repo:** Set `git_changed_files` = NO_GIT, `git_discrepancies` = NO_GIT. Skip to substep 6.
-
-**If git repo detected:**
+**If Git repo detected:**
 
 ```bash
 git status --porcelain
@@ -76,21 +67,26 @@ git diff --name-only
 git diff --cached --name-only
 ```
 
-Compile `git_changed_files` = union of modified, staged, and new files.
+Compile `{git_changed_files}` = union of modified, staged, and new files
+
+**If NOT a Git repo:**
+
+Set `{git_changed_files}` = "NO_GIT"
 
 ### 5. Cross-Reference Story vs Git
 
-Compare {story_file_list} with {git_changed_files}:
+Compare `{story_file_list}` with `{git_changed_files}`:
 
-Set `git_discrepancies` with categories:
+Set `{git_discrepancies}` with categories:
 
 - **files_in_git_not_story**: Files changed in git but not in story File List
 - **files_in_story_not_git**: Files in story File List but no git changes
 - **uncommitted_undocumented**: Uncommitted changes not tracked in story
 
-### 6. Load Project Context
+### 6. Load Context
 
-- Load {project_context} if exists (**/project-context.md) for coding standards
+- Load `{project_context}` if exists (`**/project-context.md`)
+- Invoke `discover_inputs` protocol to load architecture, UX, epic docs as needed
 
 ---
 
@@ -104,19 +100,19 @@ Set `git_discrepancies` with categories:
 
 ## SUCCESS METRICS
 
-- `story_path` identified and loaded
-- `story_key` extracted
+- `{story_path}` identified and loaded
+- `{story_key}` extracted
 - All story sections parsed
-- `story_file_list` compiled from Dev Agent Record
-- `git_changed_files` discovered via git commands
-- `git_discrepancies` calculated
-- `project_context` loaded if exists
+- `{story_file_list}` compiled from Dev Agent Record
+- `{git_changed_files}` discovered via git commands
+- `{git_discrepancies}` calculated
+- Context documents loaded
 - Explicit NEXT directive provided
 
 ## FAILURE MODES
 
 - Proceeding without story file loaded
-- Missing `story_key` extraction
+- Missing `{story_key}` extraction
 - Not parsing all story sections
 - Skipping git change discovery
 - Not calculating discrepancies

src/modules/bmm/workflows/4-implementation/code-review/steps/step-02-build-attack-plan.md

@@ -1,6 +1,10 @@
 ---
 name: 'step-02-build-attack-plan'
 description: 'Extract ACs and tasks, create comprehensive review plan for both phases'
+
+workflow_path: '{project-root}/_bmad/bmm/workflows/4-implementation/code-review'
+thisStepFile: '{workflow_path}/steps/step-02-build-attack-plan.md'
+nextStepFile: '{workflow_path}/steps/step-03-context-aware-review.md'
 ---
 
 # Step 2: Build Review Attack Plan
@@ -121,7 +125,7 @@ Proceeding with dual-phase review...
 
 **CRITICAL:** When this step completes, explicitly state:
 
-"**NEXT:** Loading `step-03-adversarial-review.md`"
+"**NEXT:** Loading `step-03-context-aware-review.md`"
 
 ---
 

src/modules/bmm/workflows/4-implementation/code-review/steps/step-03-context-aware-review.md

@@ -1,9 +1,13 @@
 ---
-name: 'step-04-context-aware-review'
+name: 'step-03-context-aware-review'
 description: 'Story-aware validation: verify ACs, audit task completion, check git discrepancies'
+
+workflow_path: '{project-root}/_bmad/bmm/workflows/4-implementation/code-review'
+thisStepFile: '{workflow_path}/steps/step-03-context-aware-review.md'
+nextStepFile: '{workflow_path}/steps/step-04-adversarial-review.md'
 ---
 
-# Step 4: Context-Aware Review
+# Step 3: Context-Aware Review
 
 **Goal:** Perform story-aware validation - verify AC implementation, audit task completion, review code quality with full story context.
 
@@ -33,16 +37,6 @@ Initialize `{context_aware_findings}` as empty list.
 
 ## EXECUTION SEQUENCE
 
-### 0. Load Planning Context (JIT)
-
-Load planning documents for AC validation against system design:
-
-- **Architecture**: `{planning_artifacts}/*architecture*.md` (or sharded: `{planning_artifacts}/*architecture*/*.md`)
-- **UX Design**: `{planning_artifacts}/*ux*.md` (if UI review relevant)
-- **Epic**: `{planning_artifacts}/*epic*/epic-{epic_num}.md` (the epic containing this story)
-
-These provide the design context needed to validate AC implementation against system requirements.
-
 ### 1. Git vs Story Discrepancies
 
 Review `{git_discrepancies}` and create findings:
@@ -156,7 +150,7 @@ Store `{context_aware_findings}` for consolidation in step 5.
 
 **CRITICAL:** When this step completes, explicitly state:
 
-"**NEXT:** Loading `step-05-consolidate-findings.md`"
+"**NEXT:** Loading `step-04-adversarial-review.md`"
 
 ---
 

src/modules/bmm/workflows/4-implementation/code-review/steps/step-04-adversarial-review.md

@@ -1,9 +1,13 @@
 ---
-name: 'step-03-adversarial-review'
+name: 'step-04-adversarial-review'
 description: 'Context-independent adversarial diff review via subagent - no story knowledge'
+
+workflow_path: '{project-root}/_bmad/bmm/workflows/4-implementation/code-review'
+thisStepFile: '{workflow_path}/steps/step-04-adversarial-review.md'
+nextStepFile: '{workflow_path}/steps/step-05-consolidate-findings.md'
 ---
 
-# Step 3: Adversarial Review (Information Asymmetric)
+# Step 4: Adversarial Review (Information Asymmetric)
 
 **Goal:** Perform context-independent adversarial review of code changes. Reviewer sees ONLY the diff - no story, no ACs, no context about WHY changes were made.
 
@@ -129,7 +133,7 @@ Proceeding to findings consolidation...
 
 **CRITICAL:** When this step completes, explicitly state:
 
-"**NEXT:** Loading `step-04-context-aware-review.md`"
+"**NEXT:** Loading `step-05-consolidate-findings.md`"
 
 ---
 

src/modules/bmm/workflows/4-implementation/code-review/steps/step-05-consolidate-findings.md

@@ -1,6 +1,10 @@
 ---
 name: 'step-05-consolidate-findings'
 description: 'Merge and deduplicate findings from both review phases'
+
+workflow_path: '{project-root}/_bmad/bmm/workflows/4-implementation/code-review'
+thisStepFile: '{workflow_path}/steps/step-05-consolidate-findings.md'
+nextStepFile: '{workflow_path}/steps/step-06-resolve-and-update.md'
 ---
 
 # Step 5: Consolidate Findings

src/modules/bmm/workflows/4-implementation/code-review/steps/step-06-resolve-and-update.md

@@ -1,6 +1,9 @@
 ---
 name: 'step-06-resolve-and-update'
 description: 'Present findings, fix or create action items, update story and sprint status'
+
+workflow_path: '{project-root}/_bmad/bmm/workflows/4-implementation/code-review'
+thisStepFile: '{workflow_path}/steps/step-06-resolve-and-update.md'
 ---
 
 # Step 6: Resolve Findings and Update Status

src/modules/bmm/workflows/4-implementation/code-review/workflow.md

@@ -1,16 +1,23 @@
 ---
 name: code-review
-description: 'Code review for dev-story output. Audits acceptance criteria against implementation, performs adversarial diff review, can auto-fix with approval. A different LLM than the implementer is recommended.'
-web_bundle: false
+description: 'Perform an ADVERSARIAL Senior Developer code review with dual-phase analysis: context-aware story validation plus context-independent adversarial diff review. Finds 3-10 specific problems in every story. NEVER accepts "looks good" - must find minimum issues and can auto-fix with user approval.'
 ---
 
 # Code Review Workflow
 
-## WORKFLOW ARCHITECTURE: STEP FILES
+**Goal:** Execute a comprehensive two-phase code review that validates story claims AND performs context-independent adversarial analysis.
 
-- This file (workflow.md) stays in context throughout
-- Each step file is read just before processing (current step stays at end of context)
+**Your Role:** You are an elite senior developer performing adversarial review. Challenge everything. Verify claims against reality. Find what's wrong or missing.
+
+---
+
+## WORKFLOW ARCHITECTURE
+
+This uses **step-file architecture** for focused execution:
+
+- Each step loads fresh to combat "lost in the middle"
 - State persists via variables: `{story_path}`, `{story_key}`, `{context_aware_findings}`, `{asymmetric_findings}`
+- Dual-phase review: context-aware (step 3) + adversarial asymmetric (step 4)
 
 ---
 
@@ -24,16 +31,32 @@ Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve:
 - `planning_artifacts`, `implementation_artifacts`
 - `date` as system-generated current datetime
 
-- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
-
 ### Paths
 
 - `installed_path` = `{project-root}/_bmad/bmm/workflows/4-implementation/code-review`
 - `project_context` = `**/project-context.md` (load if exists)
 - `sprint_status` = `{implementation_artifacts}/sprint-status.yaml`
+- `validation` = `{installed_path}/checklist.md`
+
+### Related Tasks
+
+- `adversarial_review_task` = `{project-root}/_bmad/core/tasks/review-adversarial-general.xml`
+
+---
+
+## CRITICAL DIRECTIVES
+
+<critical>YOU ARE AN ADVERSARIAL CODE REVIEWER - Find what's wrong or missing!</critical>
+<critical>Your purpose: Validate story file claims against actual implementation</critical>
+<critical>Challenge everything: Are tasks marked [x] actually done? Are ACs really implemented?</critical>
+<critical>Find 3-10 specific issues in every review minimum - no lazy "looks good" reviews</critical>
+<critical>Read EVERY file in the File List - verify implementation against story requirements</critical>
+<critical>Tasks marked complete but not done = CRITICAL finding</critical>
+<critical>Acceptance Criteria not implemented = HIGH severity finding</critical>
+<critical>Exclude `_bmad/`, `_bmad-output/`, `.cursor/`, `.windsurf/`, `.claude/` from review</critical>
 
 ---
 
 ## EXECUTION
 
-Read and follow `steps/step-01-load-story.md` to begin the workflow.
+Load and execute `steps/step-01-load-story.md` to begin the workflow.