gates.retrospective="auto": spawn a headless retro session at the epic boundary

[pbean]

Context

Upstream BMAD-METHOD PR #2612 (evidence-based bmad-retrospective rework, evaluated at 861cff8b) now provides the contract this feature was blocked on:

• -H <epic> is declared the stable orchestrator-facing interface — headless mode takes the epic from the invocation; epic auto-detection is explicitly demoted to a human convenience (detect-epic picks the highest epic with any done story, which can be a half-finished epic).
• Machine-readable verdict — the retro document opens with YAML frontmatter (epic, date, verdict: accepted | accepted-with-open-items | rejected, criteria, headless), and the sprint_status.py update result JSON echoes --verdict. The sprint-status retro key value stays done, so existing lifecycle consumers are untouched.

gates.retrospective = "auto" is already reserved in RETRO_MODES (policy.py:17) and validated, but the settings template still says "auto unsupported in v1" (policy.py:959). Today the epic boundary only emits a notify nudge (engine.py:3090-3096).

Proposal

When gates.retrospective = "auto", at _epic_boundary (engine.py:3086-3105) spawn a retrospective session instead of (or in addition to) the nudge:

• Launch a "retro"-role session running /bmad-retrospective -H <epic> — always pass the finished epic explicitly, never rely on detect-epic.
• Completion via the same Stop-hook invariant as dev/review sessions (sessions complete only on Stop/window-death).
• On completion, read the verdict from the retro document's frontmatter — verify.read_frontmatter (verify.py:938-959) already parses this shape. Treat an unknown/missing verdict conservatively (as not-accepted).
• Policy decision needed: what rejected (and accepted-with-open-items?) does to the run — pause at the boundary vs notify-and-continue. Suggest a sub-knob or documented default (notify-and-continue, pause only on rejected).

Dependencies / notes

• "retro" must become a real role: ROLES (cli.py:122) currently is ("dev", "review", "triage"); spawn paths only handle dev/review (engine.py:2636). The adapter seam already reserves it (adapters/base.py:28 role comment).
• Adapter profiles need a retro entry (which CLI/profile runs the retro session) — same mechanism as dev/review.
• Optional follow-up: the skill's on_complete hook → bmad-loop relay event, which depends on the generic relay primitive (PR feat(relay): shared event-write primitive + bmad-loop relay <Event> #238) landing; not required for v1 (Stop-hook suffices).
• Compatibility of the skill's sprint-status writes with sprintstatus.advance()'s line-regex editing was probe-verified against the PR head (ruamel rt + preserve_quotes keeps story keys plain; comments survive; advance() still works on the mutated file).

Related: upstream bmad-code-org/BMAD-METHOD#2612; sibling issues for action-item ingestion and journal-override customization.

[pbean]

Triage: blocked:upstream.

Blocked on bmad-code-org/BMAD-METHOD#2612
(the evidence-based bmad-retrospective rework), verified OPEN and unmerged as of 2026-07-24.

Every contract this issue and its siblings consume ships in that PR and does not exist in any
release yet:

• -H <epic> as the declared orchestrator-facing headless interface
• the retro document's verdict: accepted | accepted-with-open-items | rejected frontmatter
• the stable epic-<N>-retro-item-<n>-<slug> action-item id
• the ref field pointing at the sourced finding

Implementing against these before the PR merges means building on an interface that can still
change. Grouped as: #250 (parent — gates.retrospective="auto"), with #251 (action-item
ingestion) and #252 (customization override + docs) as sub-issues.