python -m bmad_loop + installed-entry-point smoke tests

[pbean]

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

Evidence

• src/bmad_loop/__main__.py does not exist — python -m bmad_loop fails. The only entries are the console script (pyproject.toml:22, bmad-loop = "bmad_loop.cli:main") and the if __name__ == "__main__" guard at cli.py:2587-2588.
• Every CLI test calls cli.main() in-process; nothing spawns a real interpreter, so packaging regressions (startup import cycles, broken script wiring) are invisible to the suite.
• Exit-code semantics are unpinned: typed errors (PolicyError/GitError/BmadConfigError/SprintStatusError) and the broad backstop both return rc 1 (cli.py:2571-2584); argparse usage errors return rc 2.

Recommendation

1. Add src/bmad_loop/__main__.py delegating to cli.main() (~3 lines, mirroring the cli.py:2587-2588 guard).
2. Add subprocess-based smoke tests: python -m bmad_loop --version, --help, and one validate --json call — spawn a real interpreter via sys.executable, keep them xdist-safe.
3. Add characterization tests pinning CURRENT exit codes: typed errors → 1, broad backstop → 1, argparse usage error → 2.

Strictly no behavior changes — these tests pin today's semantics as the guard rail for the exit-code-taxonomy work and the cli.py composition extraction.

Ordering

Session 2 of the refactor program — first code PR; everything later leans on these characterization tests.

Traps

• Existing CLI tests are all in-process cli.main() calls; the new smoke tests must be the exception, not converted copies.
• Terse CHANGELOG line for python -m support (user-visible).

[coderabbitai]

🔗 Related PRs

#73 - fix(setup): never delete live core BMAD config/manifest (#64) [merged]
#136 - feat(mux): herdr cross-platform multiplexer backend [merged]
#146 - refactor(mux)!: extract the herdr backend to pbean/bmad-loop-adapter-herdr [merged]
#181 - feat(adapters): add native-Windows psmux multiplexer backend [merged]
#209 - feat(cli): validate --json emits the check findings as a document (#205) [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!