feat: isolate delivery plan validation

[kurtthomas]

What

Separates epic/story authoring from final delivery-plan auditing inside
bmad-create-epics-and-stories.

The outward-facing agent and user workflow remain unchanged. Internally, final
validation runs under a bounded Delivery Plan Auditor role that receives the
completed epics.md, its declared source documents, and an explicit audit
rubric, but not the authoring conversation.

The auditor writes structured findings to a separate artifact and does not
modify epics.md directly.

Why

This is a narrow vertical-slice test of internal modularization beneath stable
outward-facing personas.

The practical motivation is that artifact production and validation can benefit
from different instructions, context boundaries, and objectives. The broader
hypothesis is that selected responsibilities currently bundled inside one
outward-facing role may become more reliable when separated through explicit
interfaces.

This does not propose splitting every workflow. Broader adoption should depend
on demonstrated audit value relative to token, latency, and maintenance cost.

The research basis for this design hypothesis is summarized in #2552.

Fixes #2552

Testing

• git diff --check — passed
• npm run lint:md — passed
• npm run validate:refs — failed on one unrelated existing reference outside
  the changed workflow
• npm run validate:skills — failed on repository-wide SKILL.md validation
  findings unrelated to these files

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR adds documentation on internal roles beneath named agents and introduces a new "Delivery Plan Auditor" reference contract for the bmad-create-epics-and-stories skill. Step 4 (Final Validation) is rewritten to isolate epic/story audit logic from the authoring conversation, dispatching a bounded audit contract with a preferred isolated-subagent path and a sequential fallback, writing structured findings reports, and gating completion on resolved critical findings.

Changes

Isolated Delivery-Plan Audit Role

Layer / File(s)	Summary
Internal roles concept documentation docs/explanation/named-agents.md	Adds a section explaining that skills may modularize work into narrower internal roles beneath stable named agent personas, invisible to users, communicating via artifacts, with the delivery-plan auditor as an example.
Delivery Plan Auditor contract src/bmm-skills/3-solutioning/bmad-create-epics-and-stories/references/delivery-plan-auditor.md	New reference document defining the auditor's role, input constraints, required checks (Traceability, Architecture, Story Quality, Epic Cohesion), findings format/severity taxonomy, report template, verdict definitions, and return contract.
Step 4 auditor-driven validation rewrite src/bmm-skills/3-solutioning/bmad-create-epics-and-stories/steps/step-04-final-validation.md	Rewrites execution rules and context boundaries to isolate the audit from Step 1–3 conversation, adds verify-inputs/run-audit (preferred isolated subagent + fallback)/present-triage/confirm-corrections steps, and tightens completion criteria around unresolved critical findings.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Sequence Diagram(s)

sequenceDiagram
  participant User
  participant Facilitator as Step4 Facilitator
  participant Subagent as Isolated Auditor Subagent
  participant Report as delivery-plan-audit.md

  User->>Facilitator: Trigger final validation
  Facilitator->>Facilitator: Verify Inputs (epics.md, inputDocuments, contract)
  Facilitator->>Subagent: Dispatch isolated audit (epics.md, declared inputs, contract)
  Subagent->>Report: Write full audit report
  Subagent-->>Facilitator: Return compact verdict + top findings
  Facilitator->>User: Present verdict, triage critical/high findings
  User-->>Facilitator: Accept corrections / risk
  Facilitator->>Subagent: Re-run bounded confirmation audit (if corrections applied)
  Subagent->>Report: Write confirmation report
  Facilitator->>User: Confirm completion (HALT for input)

Loading

Possibly related PRs

• bmad-code-org/BMAD-METHOD#1826: Also rewrites Step 4 "Final Validation" logic in the same workflow file, overlapping the epic-structure validation flow.
• bmad-code-org/BMAD-METHOD#1989: Modifies the same step-04-final-validation.md around completion/HALT prompt behavior.
• bmad-code-org/BMAD-METHOD#2446: Updates Step 1's inputDocuments population, which feeds the input contract this PR's Step 4 auditor validates.

Suggested reviewers: bmadcode

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	The changes implement the requested split, bounded inputs, separate findings artifact, and fallback path for #2552.
Out of Scope Changes check	✅ Passed	The added docs and workflow changes stay aligned with the delivery-plan isolation objective.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Title check	✅ Passed	The title accurately summarizes the main change: isolating delivery-plan validation into a separate bounded role.
Description check	✅ Passed	The description is clearly related to the changeset and explains the workflow split, rationale, and testing.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In
`@src/bmm-skills/3-solutioning/bmad-create-epics-and-stories/steps/step-04-final-validation.md`:
- Around line 108-113: The final validation gate in step-04-final-validation.md
only checks for unresolved critical findings, so a BLOCKED audit can still
complete. Update the completion criteria to also fail when the audit verdict is
BLOCKED, and keep the step halted until the audit can be rerun with usable
evidence. Use the existing audit-report validation logic in
step-04-final-validation.md and align it with the BLOCKED status already emitted
by delivery-plan-auditor.md.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: c133f3d4-3a91-4d21-b4a6-a026920c68cb

📥 Commits

Reviewing files that changed from the base of the PR and between 1f29bd3 and 5f0dbc2.

📒 Files selected for processing (3)

• docs/explanation/named-agents.md
• src/bmm-skills/3-solutioning/bmad-create-epics-and-stories/references/delivery-plan-auditor.md
• src/bmm-skills/3-solutioning/bmad-create-epics-and-stories/steps/step-04-final-validation.md