Engine collaborator extraction: worktree + rollback clusters, rehome provision_worktree

[pbean]

Findings F-3 + F-9a of the "Brownfield CLI/TUI Refactor Assessment" (local report, gitignored under _bmad-output/implementation-artifacts/).

Evidence

engine.py (3,108 lines) is a god-class with banner-separated state clusters:

• Worktree isolation: engine.py:472-825.
• Rollback/preserve: engine.py:980-1345.
• Plugin hook bus: engine.py:1496-1665 (~170 lines over plugins/bus — explicitly OUT of scope; leave in place).

Additionally engine.py:33 imports provision_worktree from install.py — runtime importing the installer.

Verified facts extraction may rely on: SweepEngine (sweep.py) and StoriesEngine (stories_engine.py) override only _loop/_dev_prompt/_verify_*/_post_dev_state_sync/the _drive_story family — NOTHING in either extraction cluster. tests/test_engine.py references Engine private methods 18× (and test_engine_worktree.py 1×) → delegator strategy required.

Recommendation — two PRs

PR 1 (worktree cluster): extract engine.py:472-825 into a collaborator (e.g. src/bmad_loop/worktree_flow.py) taking narrow deps (repo path, policy slice, journal/escalate callables) — never the whole Engine. Move provision_worktree from install.py into the new module, leaving a re-export in install.py. Add unit tests for the collaborator in a NEW test file.

PR 2 (rollback/preserve cluster): extract engine.py:980-1345 into a recovery collaborator, same pattern and constraints.

Acceptance criterion for both: Engine keeps same-name delegating private methods so test_engine*.py stays byte-untouched and green.

Ordering

Sessions 9-10 of the refactor program; ideally after the pyright basic gate lands. PR 2 requires PR 1 merged (verify on main). Line ranges may drift — re-locate by the section banner comments.

Traps

• Do not touch the override seams (engine.py:2179 banner) or anything SweepEngine/StoriesEngine overrides.
• install.py re-export needs a noqa: F401 pin; ruff autofix deletes re-exports — trunk check --no-fix.
• Behavior-preserving only; no CHANGELOG. Confirm Windows CI coverage of the worktree/rollback paths before starting (assessment deferred-decisions list).

[coderabbitai]

🔗 Related PRs

#103 - fix(platform): overwrite-safe deferred stash + ref-safe unit branch names [merged]
#107 - refactor(restore): one latch validator, one path normalizer, one exclusion site [merged]
#155 - fix(worktree): survive the renderer-era bmad-dev-auto (BMAD-METHOD #2587/#2588) [open]
#162 - fix: accept ancestor baselines for dw bundles; auto-recover unit worktrees on retry (#161) [merged]
#182 - fix(worktree): degrade post-merge teardown failures instead of crashing the run (#139) [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!