bmad-method 6.10.1-next.8 → 6.11.0

package/src/bmm-skills/{4-implementation/bmad-quick-dev → ship/bmad-build}/step-04-review.md

@@ -1,12 +1,8 @@
----
-deferred_work_file: '{implementation_artifacts}/deferred-work.md'
----
-
 # Step 4: Review
 
 ## RULES
 
-- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
+- **Language** — Speak in `{{.communication_language}}`. Write any file output in `{{.document_output_language}}`.
 - All review subagents must run at the same model capability as the current session.
 - Run subagents synchronously: launch them together, then wait for all results before continuing.
 
@@ -22,13 +18,11 @@ Do NOT `git add` anything — this is read-only inspection.
 
 ### Review
 
-The review layers are `{workflow.review_layers}`, resolved during activation.
-
-Skip every layer whose `instruction` is empty or missing — that is how an override disables a default layer — and every layer whose `when` condition (if present) does not hold in the current context. If no layers remain, HALT with status `blocked` and blocking condition `no active review layers`.
+Execute these review layers in parallel wherever their execution methods allow: substitute the runtime placeholders (e.g. `{diff_output}`) into each layer's instruction. When an instruction launches a reviewer subagent, launch that child with the prompt text after placeholder substitution; do not load the reviewer instruction file yourself. For any other customized instruction, execute it as written. Parallel means several blocking calls awaited together in this turn — never backgrounded or detached, never ending the turn to await results. When running layers as subagents, spawn every reviewer before reading or reacting to any of their output; begin collection and triage only once all are launched.
 
-Execute all remaining layers in parallel wherever their execution methods allow: substitute the runtime placeholders (e.g. `{diff_output}`) into each layer's `instruction`, then follow it verbatim.
+{workflow.review_layers}
 
-If a layer's instruction requires subagents and none are available, generate one review prompt file per such layer in `{implementation_artifacts}` and HALT. Ask the human to run each in a separate session (ideally a different LLM) and paste back the findings.
+If a layer's instruction requires subagents and none are available, for each such layer write under `{{.implementation_artifacts}}` the exact child prompt from that layer's instruction after placeholder substitution (not a path-only pointer), then HALT. Ask the human to run each in a separate session (ideally a different LLM) and paste back the findings.
 
 ### Classify
 
@@ -45,10 +39,10 @@ If a layer's instruction requires subagents and none are available, generate one
    - **defer** — pre-existing issue not caused by this story, surfaced incidentally by the review. Collect for later focused attention.
    - **reject** — noise. Drop silently. When unsure between defer and reject, prefer reject — only defer findings you are confident are real.
 4. Process findings in cascading order. If intent_gap or bad_spec findings exist, they trigger a loopback — lower findings are moot since code will be re-derived. If neither exists, process patch and defer normally. Before each loopback, read `{spec_file}` frontmatter `review_loop_iteration` (missing means `0`), increment it by 1, and write it back. If it exceeds 5, HALT and escalate to the human.
-   - **intent_gap** — Root cause is inside `<frozen-after-approval>`. Revert code changes. Loop back to the human to resolve. Once resolved, read fully and follow `./step-02-plan.md` to re-run steps 2–4.
-   - **bad_spec** — Root cause is outside `<frozen-after-approval>`. Before reverting code: extract KEEP instructions for positive preservation (what worked well and must survive re-derivation). Revert code changes. Read the `## Spec Change Log` in `{spec_file}` and strictly respect all logged constraints when amending the non-frozen sections that contain the root cause. Append a new change-log entry recording: the triggering finding, what was amended, the known-bad state avoided, and the KEEP instructions. Read fully and follow `./step-03-implement.md` to re-derive the code, then this step will run again.
-   - **patch** — Auto-fix. These are the only findings that survive loopbacks.
-   - **defer** — Append one new entry to `{deferred_work_file}` using this format. Do not modify existing entries or look for duplicates.
+   - **intent_gap** — Root cause is inside `<frozen-after-approval>`. Revert code changes. Loop back to the human to resolve. Once resolved, read fully and follow `[[bmad-snapshot:step-02-plan.md]]` to re-run steps 2–4.
+   - **bad_spec** — Root cause is outside `<frozen-after-approval>`. Before reverting code: extract KEEP instructions for positive preservation (what worked well and must survive re-derivation). Revert code changes. Read the `## Spec Change Log` in `{spec_file}` and strictly respect all logged constraints when amending the non-frozen sections that contain the root cause. Append a new change-log entry recording: the triggering finding, what was amended, the known-bad state avoided, and the KEEP instructions. Read fully and follow `[[bmad-snapshot:step-03-implement.md]]` to re-derive the code, then this step will run again.
+   - **patch** — Auto-fix. These are the only findings that survive loopbacks. If the step-03 implementation subagent can be re-engaged with its context intact, send it all patch findings in one synchronous message — for each: the file, what is wrong, and what the fix must do. If it cannot be re-engaged, apply the patches yourself. Then re-run the checks in `{spec_file}`'s `## Verification` section, if present; if verification fails and the failure cannot be fixed, HALT and escalate to the human.
+   - **defer** — Append one new entry to `{{.implementation_artifacts}}/deferred-work.md` using this format. Do not modify existing entries or look for duplicates.
      ```markdown
      - source_spec: `{spec_file}`
        summary: <one sentence>
@@ -58,4 +52,4 @@ If a layer's instruction requires subagents and none are available, generate one
 
 ## NEXT
 
-Read fully and follow `./step-05-present.md`
+Read fully and follow `[[bmad-snapshot:step-05-present.md]]`

package/src/bmm-skills/{4-implementation/bmad-quick-dev → ship/bmad-build}/step-05-present.md

@@ -5,7 +5,7 @@
 
 ## RULES
 
-- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
+- **Language** — Speak in `{{.communication_language}}`. Write any file output in `{{.document_output_language}}`.
 - NEVER auto-push.
 
 ## INSTRUCTIONS
@@ -52,27 +52,24 @@ When there is only one concern, omit the bold label — just list the stops dire
 
 Change `{spec_file}` status to `done` in the frontmatter.
 
-Follow `./sync-sprint-status.md` with `{target_status}` = `review`.
+Follow `[[bmad-snapshot:sync-sprint-status.md]]` with `target_status` = `review`.
 
-### Commit and Open
+### Commit and Complete
 
-1. If version control is available and the tree is dirty, create a local commit with a conventional message derived from the spec title.
-2. Open the spec in the user's editor so they can click through the Suggested Review Order:
-   - Resolve two absolute paths: (1) the repository root (`git rev-parse --show-toplevel` — returns the worktree root when in a worktree, project root otherwise; if this fails, fall back to the current working directory), (2) `{spec_file}`. Run `code -r "{absolute-root}" "{absolute-spec-file}"` — the root first so VS Code opens in the right context, then the spec file. Always double-quote paths to handle spaces and special characters.
-   - If `code` is not available (command fails), skip gracefully and tell the user the spec file path instead.
+If version control is available and the tree is dirty, create a local commit with a conventional message derived from the spec title.
+
+{workflow.open_spec}
 
 ### Display Summary
 
-Display summary of your work to the user, including the commit hash if one was created. Any file paths shown in conversation/terminal output must use CWD-relative format (no leading `/`) with `:line` notation (e.g., `src/path/file.ts:42`) for terminal clickability — the goal is to make paths clickable in terminal emulators. Include:
+Display summary of your work to the user, including the commit hash if one was created. Any file paths shown in conversation/terminal output must use CWD-relative format (no leading `/`) with `:line` notation (e.g., `src/path/file.ts:42`) for terminal clickability — the goal is to make paths clickable in terminal emulators.
 
-- A note that the spec is open in their editor (or the file path if it couldn't be opened). Mention that `{spec_file}` now contains a Suggested Review Order.
-- **Navigation tip:** "Ctrl+click (Cmd+click on macOS) the links in the Suggested Review Order to jump to each stop."
-- Offer to push and/or create a pull request.
+Offer to push and/or create a pull request.
 
 Workflow complete.
 
 ## On Complete
 
-Run: `python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow.on_complete`
+If anything appears below, follow it as the final terminal instruction before exiting; otherwise exit normally.
 
-If the resolved `workflow.on_complete` is non-empty, follow it as the final terminal instruction before exiting.
+{workflow.on_complete}

package/src/bmm-skills/ship/bmad-build/step-oneshot.md

@@ -0,0 +1,77 @@
+# Step One-Shot: Implement, Review, Present
+
+## RULES
+
+- **Language** — Speak in `{{.communication_language}}`. Write any file output in `{{.document_output_language}}`.
+- NEVER auto-push.
+- All review subagents must run at the same model capability as the current session.
+- Run subagents synchronously: launch them together, then wait for all results before continuing.
+
+## INSTRUCTIONS
+
+### Implement
+
+Follow `[[bmad-snapshot:sync-sprint-status.md]]` with `target_status` = `in-progress`.
+
+Implement the clarified intent directly.
+
+### Review
+
+Execute these review layers in parallel wherever their execution methods allow. After substituting runtime placeholders, when an instruction launches a reviewer subagent, launch that child with the prompt text; do not load the reviewer instruction file yourself. For any other customized instruction, execute it as written:
+
+{workflow.oneshot_review_layers}
+
+If a layer's instruction requires subagents and none are available, for each such layer write under `{{.implementation_artifacts}}` the exact child prompt from that layer's instruction after placeholder substitution (not a path-only pointer), then HALT. Ask the human to run each in a separate session and paste back the findings.
+
+### Classify
+
+Deduplicate all review findings. Three categories only:
+
+- **patch** — trivially fixable. Auto-fix immediately.
+- **defer** — pre-existing issue not caused by this change. Append one new entry to `{{.implementation_artifacts}}/deferred-work.md` using this format. Do not modify existing entries or look for duplicates.
+  ```markdown
+  - source_spec: `{spec_file}`
+    summary: <one sentence>
+    evidence: <why this is real>
+  ```
+- **reject** — noise. Drop silently.
+
+If a finding is caused by this change but too significant for a trivial patch, HALT and present it to the human for decision before proceeding.
+
+### Generate Spec Trace
+
+Set `title` = a concise title derived from the clarified intent.
+
+Write `{spec_file}` using `[[bmad-snapshot:spec-template.md]]`. Fill only these sections — delete all others:
+
+1. **Frontmatter** — set `title: '{title}'`, `type`, `created`, `status: 'done'`. Add `route: 'one-shot'`.
+2. **Title and Intent** — `# {title}` heading and `## Intent` with **Problem** and **Approach** lines. Reuse the summary you already generated for the terminal.
+3. **Suggested Review Order** — append after Intent. Build using the same convention as `[[bmad-snapshot:step-05-present.md]]` § "Generate Suggested Review Order" (spec-file-relative links, concern-based ordering, ultra-concise framing).
+
+Follow `[[bmad-snapshot:sync-sprint-status.md]]` with `target_status` = `review`.
+
+### Commit
+
+If version control is available and the tree is dirty, create a local commit with a conventional message derived from the intent. If VCS is unavailable, skip.
+
+### Present
+
+{workflow.open_spec}
+
+Display a summary in conversation output, including:
+
+- The commit hash (if one was created).
+- List of files changed with one-line descriptions. Any file paths shown in conversation/terminal output must use CWD-relative format (no leading `/`) with `:line` notation (e.g., `src/path/file.ts:42`) for terminal clickability — this differs from spec-file links which use spec-file-relative paths.
+- Review findings breakdown: patches applied, items deferred, items rejected. If all findings were rejected, say so.
+
+Offer to push and/or create a pull request.
+
+HALT and wait for human input.
+
+Workflow complete.
+
+## On Complete
+
+If anything appears below, follow it as the final terminal instruction before exiting; otherwise exit normally.
+
+{workflow.on_complete}

package/src/bmm-skills/ship/bmad-build/sync-sprint-status.md

@@ -0,0 +1,19 @@
+# Sync Sprint Status
+
+Shared sub-step for updating `sprint-status.yaml` during build. Called from any route (plan-code-review, one-shot, future routes) with a `target_status` parameter.
+
+## Preconditions
+
+Skip this entire file (return to caller) if ANY of:
+- `story_key` is unset
+- `{{.implementation_artifacts}}/sprint-status.yaml` does not exist on disk
+
+## Instructions
+
+1. Load the FULL `{{.implementation_artifacts}}/sprint-status.yaml` file.
+2. Find the `development_status` entry matching `{story_key}`. If not found, warn the user once (`"{story_key} not found in sprint-status; skipping sprint sync"`) and return to caller.
+3. **Idempotency check.** If `development_status[{story_key}]` is already at `target_status` or a later state (`review` is later than `in-progress`; `done` is later than both), return to caller — no write needed. Never regress a story's status.
+4. Set `development_status[{story_key}]` to `{target_status}`.
+5. **Epic lift (only when `target_status` = `in-progress`).** Derive the parent epic key as `epic-{N}` from the leading numeric segment of `{story_key}` (e.g., `3-2-digest-delivery` → `epic-3`). If that entry exists and is `backlog`, set it to `in-progress`. Leave it alone otherwise. Skip this sub-step entirely when `target_status` is not `in-progress`.
+6. Refresh `last_updated` to the current date.
+7. Save the file, preserving ALL comments and structure including STATUS DEFINITIONS and WORKFLOW NOTES.

package/src/bmm-skills/ship/bmad-build/workflow.md

@@ -0,0 +1,84 @@
+# Build New Preview Workflow
+
+**Goal:** Turn user intent into a hardened, reviewable artifact.
+
+**CRITICAL:** If a step directs you to another snapshot file, read it fully and follow it. No exceptions.
+
+Subagents, when the capability is available, are an important part of this workflow. Use them as directed by the workflow steps.
+If you need an explicit user instruction to run them, ask once now for the whole workflow run.
+
+## READY FOR DEVELOPMENT STANDARD
+
+A specification is "Ready for Development" when:
+
+- **Actionable**: Every task has a file path and specific action.
+- **Logical**: Tasks ordered by dependency.
+- **Testable**: All ACs use Given/When/Then.
+- **Complete**: No placeholders or TBDs.
+- **Sufficient**: No known requirement, acceptance, dependency, or implementation gaps remain unresolved.
+- **Coherent**: No unresolved ambiguities or internal contradictions.
+
+## SCOPE STANDARD
+
+A specification should target a **single user-facing goal** within **900–1600 tokens**:
+
+- **Single goal**: One cohesive feature, even if it spans multiple layers/files. Multi-goal means >=2 **top-level independent shippable deliverables** — each could be reviewed, tested, and merged as a separate PR without breaking the others. Never count surface verbs, "and" conjunctions, or noun phrases. Never split cross-layer implementation details inside one user goal.
+  - Split: "add dark mode toggle AND refactor auth to JWT AND build admin dashboard"
+  - Don't split: "add validation and display errors" / "support drag-and-drop AND paste AND retry"
+- **900–1600 tokens**: Optimal range for LLM consumption. Below 900 risks ambiguity; above 1600 risks context-rot in implementation agents.
+- **Neither limit is a gate.** Both are proposals with user override.
+
+## Conventions
+
+- Every operational cross-file reference in this workflow is an absolute snapshot path. Open it directly; do not resolve it relative to a skill directory.
+- `{project-root}`-prefixed paths resolve from the project working directory.
+- Whenever this workflow captures or records a version-control revision, obtain the full canonical identifier directly from version control and preserve it verbatim.
+
+## On Activation
+
+### Step 1: Execute Prepend Steps
+
+Execute each of these steps in order before proceeding (`_None._` means skip):
+
+{workflow.activation_steps_prepend}
+
+### Step 2: Load Persistent Facts
+
+Treat every entry below as foundational context you carry for the rest of the workflow run. Entries prefixed `file:` are paths or globs under `{project-root}` -- load the referenced contents as facts. All other entries are facts verbatim (`_None._` means none):
+
+{workflow.persistent_facts}
+
+### Step 3: Execute Append Steps
+
+Execute each of these steps in order (`_None._` means skip):
+
+{workflow.activation_steps_append}
+
+## WORKFLOW ARCHITECTURE
+
+This uses **step-file architecture** for disciplined execution:
+
+- **Micro-file Design**: Each step is self-contained and followed exactly
+- **Just-In-Time Loading**: Only load the current step file
+- **Sequential Enforcement**: Complete steps in order, no skipping
+- **State Tracking**: Persist progress via spec frontmatter and in-memory variables
+- **Append-Only Building**: Build artifacts incrementally
+
+### Step Processing Rules
+
+1. **READ COMPLETELY**: Read the entire step file before acting
+2. **FOLLOW SEQUENCE**: Execute sections in order
+3. **WAIT FOR INPUT**: Halt at checkpoints and wait for human
+4. **LOAD NEXT**: When directed, read fully and follow the next step file
+
+### Critical Rules (NO EXCEPTIONS)
+
+- **NEVER** load multiple step files simultaneously
+- **ALWAYS** read entire step file before execution
+- **NEVER** skip steps or optimize the sequence
+- **ALWAYS** follow the exact instructions in the step file
+- **ALWAYS** halt at checkpoints and wait for human input
+
+## FIRST STEP
+
+Read fully and follow: `[[bmad-snapshot:step-01-clarify-and-route.md]]` to begin the workflow.

package/src/bmm-skills/ship/bmad-build-auto/SKILL.md

@@ -0,0 +1,13 @@
+---
+name: bmad-build-auto
+description: 'One iteration of an unattended development loop. Use when invoked by name.'
+---
+
+Run the following command exactly once without changing the current working directory. Replace `{project-root}` with the absolute path to the project root and `{skill-root}` with the absolute path to this skill's directory:
+
+```bash
+uv run --no-cache "{project-root}/_bmad/scripts/render_skill.py" --project-root "{project-root}" --skill "{skill-root}"
+```
+
+- On success, read and follow the one absolute `workflow.md` instruction printed to stdout.
+- On failure (including `uv` being unavailable), report the command output and HALT. Do not run any workflow source directly.

package/src/bmm-skills/{4-implementation/bmad-dev-auto → ship/bmad-build-auto}/compile-epic-context.md

@@ -52,7 +52,7 @@ Use these headings:
 - **No full copies.** Never quote source documents, section numbers, or paste large blocks verbatim. Always distill.
 - **No story-level details.** The story list is for orientation only. Individual story specs handle the details.
 - **Nothing derivable from the codebase.** Don't document what a developer can learn by reading the code.
-- **Be concise and actionable.** Target 800–1500 tokens total. This file loads into bmad-dev-auto's context alongside other material.
+- **Be concise and actionable.** Target 800–1500 tokens total. This file loads into bmad-build-auto's context alongside other material.
 - **Never hallucinate content.** If source material doesn't say something, don't invent it.
 - **Omit empty sections entirely**, except Goal and Stories, which are always required.
 

package/src/bmm-skills/ship/bmad-build-auto/customize.toml

@@ -0,0 +1,121 @@
+# DO NOT EDIT -- overwritten on every update.
+#
+# Default customization values for bmad-build-auto.
+# Override in _bmad/custom/bmad-build-auto.toml or
+# _bmad/custom/bmad-build-auto.user.toml.
+#
+# Merge rules:
+# - Strings replace the default.
+# - Lists append to the default list.
+# - Tables merge key by key.
+# - Arrays of tables merge by `id`: matching `id` replaces, new `id`s append.
+
+[workflow]
+
+# Extra instructions to run before config is loaded.
+
+activation_steps_prepend = []
+
+# Extra instructions to run after config is loaded and before step 01.
+
+activation_steps_append = []
+
+# Facts kept in context for the whole run.
+# Entries are literal text or file references prefixed with "file:".
+# File entries may use globs and are loaded during activation.
+
+persistent_facts = [
+  "file:{project-root}/**/project-context.md",
+]
+
+# Instruction run by HALT after writing the terminal result.
+# Empty means no extra terminal behavior.
+
+on_complete = ""
+
+# Handoff for the implementation subagent in step 03. The whole execution
+# recipe — a subagent by default, but an override may run it any other way
+# (a different model, an external coding tool via bash). {spec_file} is
+# substituted at run time.
+
+implementation_handoff = """
+Launch a subagent with no prior conversation context, with this prompt:
+
+> Read {spec_file} fully and implement it — the spec is the sole source of truth. Load every file listed in its frontmatter `context:` before you start.
+>
+> When done, report what you changed, how you verified it, and anything left incomplete or risky.
+"""
+
+# Review layers for the review step. `instruction` is the layer's whole
+# execution recipe — subagents by default, but an override may run anything
+# (e.g. an external reviewer via bash). {diff_output} is substituted at run
+# time. `when` (optional) gates a layer; empty `instruction` disables it.
+
+[[workflow.review_layers]]
+id = "blind-hunter"
+name = "Blind Hunter"
+instruction = """
+Launch a context-free subagent with this prompt:
+
+Conduct a review of CONTENT.
+Look for what's missing, not only what's wrong.
+Find at least ten issues to fix or improve.
+Output a Markdown list of findings only — no severity, priority, or ranking.
+If the content is empty, stop and say so.
+If you have zero findings, re-check and keep thinking; do not stop with an empty list.
+
+CONTENT:
+{diff_output}
+
+Do not invoke any skill. Return only the review result.
+
+"""
+
+[[workflow.review_layers]]
+id = "edge-case-hunter"
+name = "Edge Case Hunter"
+instruction = """
+Launch a context-free subagent with this prompt:
+
+Read `{skill-root}/review-prompts/edge-case-hunter.md` completely and follow it as your review instructions.
+
+Review content:
+
+{diff_output}
+
+Do not invoke any skill. If the instruction file is unreadable, report that exact failure and stop. Return only the review result.
+
+"""
+
+[[workflow.review_layers]]
+id = "verification-gap"
+name = "Verification Gap Reviewer"
+instruction = """
+Launch a context-free subagent with this prompt:
+
+Read `{skill-root}/review-prompts/verification-gap.md` completely and follow it as your review instructions.
+
+Review content:
+
+{diff_output}
+
+Do not invoke any skill. If the instruction file is unreadable, report that exact failure and stop. Return only the review result.
+
+"""
+
+[[workflow.review_layers]]
+id = "intent-alignment"
+name = "Intent Alignment Auditor"
+instruction = """
+Launch a subagent with this prompt:
+
+You are an intent-alignment auditor. You have no other context about how this change was produced. Here is the verbatim intent this work started from:
+
+{verbatim_intent}
+
+Here is the diff:
+
+{diff_output}
+
+Your task is strictly descriptive — do not prescribe additional work. Report: (1) the defensible readings of the intent, enumerated; (2) which reading this diff implements; (3) where the readings and the diff diverge — specifically, which surface the intent's expectations live at versus which surface the diff's changes and its tests exercise.
+"""

package/src/{core-skills/bmad-review-edge-case-hunter/SKILL.md → bmm-skills/ship/bmad-build-auto/review-prompts/edge-case-hunter.md}

@@ -1,8 +1,3 @@
----
-name: bmad-review-edge-case-hunter
-description: 'Walk every branching path and boundary condition in content, report only unhandled edge cases. Orthogonal to adversarial review - method-driven not attitude-driven. Use when you need exhaustive edge-case analysis of code, specs, or diffs.'
----
-
 # Edge Case Hunter Review
 
 **Goal:** You are a pure path tracer. Never comment on whether code is good or bad; only list missing handling.
@@ -24,7 +19,7 @@ A brief secondary deletion check runs as Step 4 when the diff removes code.
 
 ### Step 1: Receive Content
 
-- Load the content to review strictly from provided input
+- Load the content to review strictly from the parent message that launched you (not from this instruction file)
 - If content is empty, or cannot be decoded as text, return `[{"location":"N/A","trigger_condition":"Input empty or undecodable","guard_snippet":"Provide valid content to review","potential_consequence":"Review skipped — no analysis performed"}]` and stop
 - Identify content type (diff, full file, or function) to determine scope rules
 
@@ -71,3 +66,23 @@ No extra text, no explanations, no markdown wrapping. An empty array `[]` is val
 ## HALT CONDITIONS
 
 - If content is empty or cannot be decoded as text, return `[{"location":"N/A","trigger_condition":"Input empty or undecodable","guard_snippet":"Provide valid content to review","potential_consequence":"Review skipped — no analysis performed"}]` and stop
+<reference path="references/deletion-check.md">
+# Deletion Check
+
+Secondary pass for the Edge Case Hunter — runs only when the diff removed meaningful code. Subordinate to the edge-case pass; findings are usually few or none.
+
+For each chunk of removed or replaced code (ignore pure renames and whitespace), ask: did it carry behavior or a contract that the change neither re-established nor intentionally retired? Add a finding for any resulting regression, orphaned reference, or newly-dead code. Skip anything already covered by your edge-case findings.
+
+Append each finding to the same JSON array as the edge-case findings, with the four standard fields plus:
+
+- `kind`: `"deletion"`
+- `confidence`: `"high"`, `"medium"`, or `"low"` — these are inferences; rate them
+
+For a deletion finding the standard fields read as: `location` = the removed item; `trigger_condition` = the behavior or contract it enforced; `guard_snippet` = where or how to re-establish it; `potential_consequence` = the regression or orphan.
+
+Add nothing if nothing qualifies.
+</reference>
+
+## CONTENT SOURCE
+
+Review the content supplied under "Review content:" in the message that launched you.

package/src/{core-skills/bmad-review-verification-gap/SKILL.md → bmm-skills/ship/bmad-build-auto/review-prompts/verification-gap.md}

@@ -1,8 +1,3 @@
----
-name: bmad-review-verification-gap
-description: 'Review a code change for changed behavior that could regress without reliable verification catching it. Use when checking whether a change is adequately verified.'
----
-
 # Verification Gap Review
 
 **Goal:** Find changed behavior that could break without reliable verification catching it. Ask one question — "if the behavior this change is supposed to produce broke where it's actually used, would verification fail?" Do not hunt for correctness bugs, but report genuine problems you notice while tracing verification.
@@ -25,10 +20,14 @@ The main verification gap shapes are:
 
 ### Step 1: Screen for behavioral change
 
-If the change is non-behavioral, stop here and output the clean result (see Output Format). Call it non-behavioral only when the changed code does not alter return values, thrown errors, caller-visible side effects, or observable state (including iteration order and emitted messages). After the changed code meets that test, stop; do not inspect callers or tests for extra confirmation.
+Screen each part of the change separately. If a part is non-behavioral, skip it. Call a part non-behavioral only when the changed code does not alter return values, thrown errors, caller-visible side effects, or observable state (including iteration order and emitted messages). Once a part meets that test, move on; do not inspect callers or tests for extra confirmation.
 
 Common non-behavioral examples: formatting, comments, whitespace; pure renames; trivial getters/setters and pass-throughs; type-only or compiler-enforced changes with no runtime effect; etc.
 
+Only outcomes produced by deterministic code are worth automatically testing; tests are useless on static source text and brittle on LLM output. Skip those parts.
+
+If every part is skipped, output the clean result (see Output Format).
+
 ### Step 2: Find the behavior that changed
 
 Identify what behavior changed compared to the previous version: output, side effect, branch, error path, schema/event shape, config default, validation/authorization rule, external contract, etc. If the change affects more than one behavior, handle each separately.
@@ -53,7 +52,9 @@ Find and read the relevant test. Ask whether the Demonstration would make an ass
 - For a regression-style Demonstration: if no test runs the path, the test is skipped/flaky/not run normally, or the test runs the code without checking the changed result, report a `Regression gap` or `Broken-verification gap`.
 - For a qualifying Missing-adoption case: if none of the site tests you found assert it adopts the new behavior, report a `Missing-adoption gap`.
 
-A test counts only if it runs normally and an assertion observes the changed output, branch, or contract. These do not count: no execution; success/no-throw/snapshot-only checks; mock/log-call checks; human-only checks; tests that mock away the integration; e2e tests that pass through without checking the changed output; stale assertions or fixtures.
+A test counts only if it runs normally and an assertion observes the changed output, branch, or contract. These do not count: no execution; source-text assertions that match a file's wording instead of running it; success/no-throw/snapshot-only checks; mock/log-call checks; human-only checks; tests that mock away the integration; e2e tests that pass through without checking the changed output; stale assertions or fixtures.
+
+For example, `expect(x ?? DEFAULT).toBe(DEFAULT)` passes when `x` is missing.
 
 Common patterns:
 
@@ -62,12 +63,14 @@ Common patterns:
 - **Migration compatibility** — tests only create new-format rows or fresh schemas.
 - **Phantom exception** — handled partial-failure path has no test.
 - **Missing-adoption gap** — sibling site should use the new rule/helper and does not.
-- **Removed verification** — deleted test or weakened assertion leaves behavior unpinned.
+- **Removed verification** — deleted test or weakened assertion leaves behavior unpinned; removing a source-text assertion is not this, since it never counted.
 
 ### Step 5: Confirm each finding is real
 
 Before writing a finding, re-open the specific tests or search results the finding relies on. Verify the Demonstration would not make any test you checked fail, or that the absence claim is backed by the symbol/import-reference search. Do not claim more than you verified; drop any finding you cannot ground.
 
+Explain why the test misses the bug using what the test sets up and checks.
+
 Do not report: compiler/type-checker-enforced cases; behavior already verified by an integration, contract, or e2e test; implementation-detail or mock-only tests; low coverage or a missing test file by itself; legacy untested code the change did not affect.
 
 Report genuine problems you noticed while tracing verification, even if they are not verification gaps. Put them under `Other findings` in the output. This permits reporting what you already reached, not extra hunting.
@@ -104,3 +107,7 @@ If you noticed genuine non-gap problems while tracing verification, append:
 When you find no verification gaps and no other findings, output exactly this single line, not an empty response:
 
 `No verification gaps found.`
+
+## CONTENT SOURCE
+
+Review the content supplied under "Review content:" in the message that launched you. If none is supplied, stop with exactly: `No verification gaps found.`

package/src/bmm-skills/{4-implementation/bmad-dev-auto → ship/bmad-build-auto}/spec-template.md

@@ -4,9 +4,10 @@ type: 'feature' # feature | bugfix | refactor | chore
 created: '{date}'
 status: 'draft' # draft | ready-for-dev | in-progress | in-review | done | blocked
 review_loop_iteration: 0 # incremented by step-04 before each review loopback
-followup_review_recommended: false # set by step-04 on status: done from the final review pass significance judgment
+followup_review_recommended: false # set by step-04 on status: done — true if the LLM decided another review pass is worthwhile
 context: [] # optional: `{project-root}/`-prefixed paths to project-wide standards/docs the implementation agent should load. Keep short — only what isn't already distilled into the spec body.
 warnings: [] # optional: machine-readable warnings for orchestration, e.g. oversized, multiple-goals
+deferred: [] # append-only machine-readable deferred review findings; each item carries summary/evidence and optional location/severity
 ---
 
 <!-- Aim for 900–1600 tokens. If larger, add `oversized` to frontmatter `warnings` and continue.

package/src/bmm-skills/ship/bmad-build-auto/step-01-clarify-and-route.md

@@ -0,0 +1,83 @@
+---
+spec_file: '' # set at runtime once a route resolves it; some HALT branches exit before it is set
+spec_folder: '' # set at runtime under folder+id dispatch only
+story_id: '' # set at runtime under folder+id dispatch only
+---
+
+# Step 1: Clarify and Route
+
+## RULES
+
+- **Language** — Speak in `{{.communication_language}}`, tailored to `{{.user_skill_level}}`. Write files in `{{.document_output_language}}`.
+- Treat the invocation intent as workflow input, not as a substitute for step-02 investigation and spec generation.
+- **EARLY EXIT** means: stop this step immediately, then read and follow the target file. Return here only if a later step explicitly says to loop back.
+
+## Intent check (do this first)
+
+Use the invocation prompt as the intent.
+
+If the invocation prompt explicitly points to an existing spec file with recognized `status` frontmatter, set `spec_file`, then **EARLY EXIT** to the appropriate step:
+- `draft` → `[[bmad-snapshot:step-02-plan.md]]`
+- `ready-for-dev` or `in-progress` → `[[bmad-snapshot:step-03-implement.md]]`
+- `in-review` → `[[bmad-snapshot:step-04-review.md]]`
+- `blocked` → HALT with status `blocked` and blocking condition `blocked spec supplied`.
+- `done` → set `review_loop_iteration` to `0` in the frontmatter, then **EARLY EXIT** to `[[bmad-snapshot:step-04-review.md]]` for a fresh review pass. (A `done` spec is a completed run, so this starts a follow-up review, not a resumption.)
+
+If the invocation prompt instead supplies a spec folder and a story id, with no specific spec file path, this is a **folder+id dispatch**: set `spec_folder` (a `{project-root}`-relative or absolute path) and `story_id` from the prompt. Any further prompt text (e.g. `invoke_dev_with` guidance the caller appended) is additional planning context to carry into step-02 — not a competing description of what to implement.
+
+Read `{spec_folder}/stories.yaml`. If the file does not exist or fails to parse, HALT with status `blocked` and blocking condition `no stories.yaml found`. Find the entry whose `id` equals `{story_id}`; if none matches, HALT with status `blocked` and blocking condition `story id not found in stories.yaml`. Take only that entry's `title` and `description` — never read the checkpoint fields or `invoke_dev_with`; those are the caller's orchestration fields, not build-auto's.
+
+Look for files matching `{spec_folder}/stories/{story_id}-*.md` (id-prefix match — story ids are prefix-free, so at most one should match):
+- **If more than one matches**, HALT with status `blocked` and blocking condition `ambiguous story file match`.
+- **If exactly one matches**, set `spec_file` to that path.
+  - `draft` (planning was interrupted mid-flight): accumulate cross-story context before resuming — load every other file matching `{spec_folder}/stories/*.md` (every match except `{spec_file}` itself), regardless of `status`, and carry forward each one's **Code Map**, **Design Notes**, **Spec Change Log**, **Tasks & Acceptance** checklist state, and **Auto Run Result** details, where present, as additional planning context for step-02. Then **EARLY EXIT** to `[[bmad-snapshot:step-02-plan.md]]`.
+  - Any other recognized `status`: **EARLY EXIT** using the same routing as above, including the `review_loop_iteration` reset for `done`. One difference: a `blocked` story HALTs with blocking condition `story already blocked`, not `blocked spec supplied` — the caller did not supply this file; build-auto found it by id.
+  - `status` missing or unrecognized: HALT with status `blocked` and blocking condition `unrecognized status in existing story file`.
+- **If none matches**, this is the first dispatch for `{story_id}`. The entry's `title` and `description` are the resolved intent. If `{spec_folder}/SPEC.md` does not exist, HALT with status `blocked` and blocking condition `no epic spec found`. Otherwise load it and the files listed in its `companions:` frontmatter as planning context, then accumulate cross-story context the same way as the `draft` case above — load every file matching `{spec_folder}/stories/*.md` (none yet exists for `{story_id}` at this point, so nothing is excluded), regardless of `status`, carrying forward the same fields, where present, as additional planning context for step-02. Then continue to INSTRUCTIONS item 3 below — not `step-03-implement.md`, item 3 of the numbered list in this file (items 1 and 2 do not apply — context and intent are already resolved; item 1.A.5's previous-story continuity scan in particular never runs here, since folder+id dispatch already skips items 1 and 2 entirely — the cross-story accumulation above is its replacement for this dispatch mode).
+
+One `stories.yaml` entry per invocation: never read another entry, and never advance to a different story id regardless of outcome.
+
+Otherwise, treat the invocation prompt as starting intent. This may be a story ID, ticket ID, file path, short description, or longer free-form intent. Do not infer workflow state from non-spec files.
+If the invocation prompt does not contain enough intent to identify what to implement, HALT with status `blocked` and blocking condition `unclear intent`.
+
+## INSTRUCTIONS
+
+1. Load context.
+   - List files in `{{.planning_artifacts}}` and `{{.implementation_artifacts}}`.
+   - If the invocation prompt points to an unformatted spec or intent file, ingest that file. Do not scan for unrelated intent files.
+   - **Determine context strategy.** Using the intent and the artifact listing, infer whether the current work is a story from an epic. Do not rely on filename patterns or regex — reason about the intent, the listing, and any epics file content together.
+
+     **A) Epic story path** — if the intent is clearly an epic story:
+
+     1. Identify the epic number `{epic_num}` and (if present) the story number `{story_num}`. If you can't identify an epic number, use path B.
+
+     2. **Check for a valid cached epic context.** Look for `{{.implementation_artifacts}}/epic-<N>-context.md` (where `<N>` is the epic number). A file is **valid** when it exists, is non-empty, starts with `# Epic <N> Context:` (with the correct epic number), and no file in `{{.planning_artifacts}}` is newer.
+        - **If valid:** load it as the primary planning context. Do not load raw planning docs (PRD, architecture, UX, etc.).
+        - **If missing, empty, or invalid:** compile it in the next bullet.
+
+     3. **Compile epic context if needed.** If no valid cached epic context was loaded, produce `{{.implementation_artifacts}}/epic-<N>-context.md` by spawning a subagent synchronously with `[[bmad-snapshot:compile-epic-context.md]]` as its prompt. Pass it the epic number, epics file path, `{{.planning_artifacts}}`, and output path `{{.implementation_artifacts}}/epic-<N>-context.md`.
+
+     4. **Verify if compiled.** If epic context was compiled, verify the output file exists, is non-empty, and starts with `# Epic <N> Context:`. If valid, load it. If verification fails, HALT with status `blocked` and blocking condition `context compilation verification failed`.
+
+     5. **Previous story continuity.** Regardless of which context source succeeded above, scan `{{.implementation_artifacts}}` for specs from the same epic with `status: done` and a lower story number. Load the most recent one (highest story number below current). Extract its **Code Map**, **Design Notes**, **Spec Change Log**, and **task list** as continuity context for step-02 planning. If no `done` spec is found but an `in-review` spec exists for the same epic with a lower story number, HALT with status `blocked` and blocking condition `missing previous-story continuity decision`.
+
+     **B) Freeform path** — if the intent is not an epic story:
+     - Planning artifacts are the output of BMAD phases 1-3. Typical files include:
+       - **PRD** (`*prd*`) — product requirements and success criteria
+       - **Architecture** (`*architecture*`) — technical design decisions and constraints
+       - **UX/Design** (`*ux*`) — user experience and interaction design
+       - **Epics** (`*epic*`) — feature breakdown into implementable stories
+       - **Product Brief** (`*brief*`) — project vision and scope
+     - Scan the listing for files matching these patterns. If any look relevant to the current intent, load them selectively — you don't need all of them, but you need the right constraints and requirements rather than guessing from code alone.
+2. Resolve intent from the invocation prompt and loaded artifacts. Do not fantasize or leave open questions. If the intent cannot be resolved, HALT with status `blocked` and the unresolved questions as blocking condition.
+3. Version control sanity check. If version control is unavailable, skip this check. Otherwise require a clean working tree, a branch that fits the intent, and writable repository metadata. For Git, run `git add --refresh -- .`, then confirm the tree is still clean; on failure or change, HALT with status `blocked` and blocking condition `version-control metadata not writable`. Under folder+id dispatch, judge the branch against the epic, not the story. HALT on a dirty tree or obvious branch mismatch.
+4. Multi-goal warning. If the intent appears to contain multiple independently shippable goals, carry `multiple-goals` forward so step-02 can add it to `{spec_file}` frontmatter `warnings`. Do not split or block.
+5. Route:
+
+   **Folder+id dispatch:** derive a valid kebab-case slug from the entry's `title` (and `description` if needed) — the same kebab-casing convention as below, but never prefixed with `{story_id}`, since the id is already the filename's separate leading segment. Set `spec_file` = `{spec_folder}/stories/{story_id}-{slug}.md`. The id already disambiguates: no `{{.implementation_artifacts}}` fallback, no `-2`/`-3` suffixing.
+
+   **Otherwise:** derive a valid kebab-case slug from the clarified intent. If the intent references a tracking identifier (story number, issue number, ticket ID), lead the slug with it (e.g. `3-2-digest-delivery`, `gh-47-fix-auth`). If `{{.implementation_artifacts}}/spec-{slug}.md` already exists: if its status is `draft`, treat it as the same work and resume it (set `spec_file` to that path, **EARLY EXIT** → `[[bmad-snapshot:step-02-plan.md]]`); otherwise append `-2`, `-3`, etc. Set `spec_file` = `{{.implementation_artifacts}}/spec-{slug}.md`.
+
+## NEXT
+
+Read fully and follow `[[bmad-snapshot:step-02-plan.md]]`