Description

I had BMAD do this analysis and write this up itself.

Component: bmm module — dev-story workflow
Affected file: _bmad/bmm/workflows/4-implementation/dev-story/instructions.xml
BMAD version: 6.0.3 (installed 2026-02-25)
Severity: Medium — causes a recurring MEDIUM finding in every code-review run

Description

The dev-story workflow produces a File List in the Dev Agent Record that reliably omits infrastructure files that change as predictable side-effects of story implementation. The same class of omission has occurred in every story implemented so far in this project (Stories 1-1, 1-2, 1-3).

The omitted files are always the same:

• pnpm-lock.yaml — updated whenever any package is installed or upgraded
• _bmad-output/implementation-artifacts/.md — the story file itself is modified throughout implementation but never self-listed
• _bmad-output/implementation-artifacts/sprint-status.yaml — updated by the workflow at start (→ in-progress) and completion
  (→ review)

These files are genuinely changed in git. The code-review workflow correctly detects them as "files changed but not in story File List" and raises a MEDIUM finding every time. This is wasted review signal — reviewers have to acknowledge a known-false positive on every single story.

Root Cause

The problem has two parts:

1. The File List instruction is per-task and agent-driven (Step 8, line 299)

Update File List section with ALL new, modified, or deleted files (paths relative to repo root)

This fires after each task completes. The agent updates the File List based on what it believes it changed during that task — which is the application source files it just wrote. It has no awareness that pnpm install (run as a subtask) also mutated pnpm-lock.yaml.

2. The Step 9 completeness check is also agent-driven (lines 326, 339, 369)

Confirm File List includes every changed file
...

• File List includes every new/modified/deleted file (relative paths)
  ...
  HALT - Update File List with all changed files

The agent self-evaluates "is the File List complete?" against its own mental model of what it changed — which already excludes the infrastructure files. The HALT gate fires only if the agent knows something is missing. Since it never knew about pnpm-lock.yaml, it doesn't HALT. The check passes vacuously.

3. The story template provides no guidance (template.md, line 49)

File List

The section is a bare heading with no examples, no hints, and no reminder about infrastructure side-effects. The agent has nothing to anchor on beyond the generic instruction in Step 8.

Proposed Fix

Replace the agent's self-assessment in Step 8 and Step 9 with ground-truth git output. After each task and at story completion, run git status --porcelain and git diff --name-only to get the actual set of changed files, then cross-reference against the current File List and append any missing entries.

Step 8 change — after the current File List update action, add:

Run git status --porcelain to get the actual set of changed files on disk
Run git diff --name-only to get unstaged modified files
Run git diff --cached --name-only to get staged files
Compare git-reported changed files against current File List content
Append any files present in git output but absent from File List (exclude _bmad/ and _bmad-output/
directories)

Step 9 change — replace the current text-instruction check with the same git-driven verification, and make the HALT gate use git output as the source of truth rather than agent recall:

Run git status --porcelain and git diff --name-only to enumerate ALL changed files
Cross-reference against File List — any git-reported file not in File List is an omission
Append missing files to File List before continuing

This eliminates the class of problem entirely — the File List is now derived from git reality rather than agent memory, so infrastructure side-effects (lockfile, sprint tracker, story file) are captured automatically.

Exclusion rule

The code-review instructions already exclude _bmad/ and _bmad-output/ from code review (instructions.xml line 15). The same exclusion should apply to the File List population — the story file and sprint tracker are workflow artifacts, not application source. The fix should exclude _bmad-output/ from the git cross-reference so they don't clutter the File List. Only pnpm-lock.yaml and similar repo-root infrastructure files should be added.

Steps to reproduce

Given a story that requires installing new dependencies.

1. /bmad-bmm-create-story
2. /bmad-bmm-dev-story
3. /bmad-bmm-code-review

Expected behavior

No code review issue reported for files missing from story File List.

Actual behavior

Code review reports:

M3 — Git-undocumented changes in story File List
The story File List omits three files that have real git changes: pnpm-lock.yaml (modified by pnpm install), the story file itself, and sprint-status.yaml. While these are workflow artifacts, incomplete File Lists make future audit difficult. Both pnpm-lock.yaml and the sprint tracker should appear under "Modified files."

Screenshots

No response

Which module is this for?

BMad Method (BMM) - Core Framework

BMad Version

6.0.3

Which AI IDE are you using?

Claude Code

Operating System

Linux

Relevant log output

Confirm

• I've searched for existing issues
• I'm using the latest version