fix: preflight renderer-backed dev skills

[pbean]

Summary

• Detect content-confirmed renderer-backed dev primitives and refuse runs when the project-local renderer script unit, central config, workflow entry, or declared snapshot sources are incomplete.
• Warn when _bmad/render/ is already tracked using the existing verify.path_tracked git chokepoint, and add _bmad/render/ idempotently to bmad-loop init's .gitignore entries.
• Cover validate, real run refusal, dry-run honesty, and a complete zero-token real-tmux/fake-CLI success path.

Phase 6F scope

• RENDERER_SEED_SENTINELS and renderer_stub_resolved intentionally land inert until Phase 6H; forward-port the 0.9.1 hotfix (#405) to main #433 tracks that later _bmad seeding/worktree-shielding work.
• validate --render-probe: execute the renderer instead of probing for its files #407 renderer execution and config-token probing remain out of scope.
• toml_artifact_parity: resurrect #155's check with a corrected renderer model #408 TOML parity remains out of scope.
• _absent_renderer_sources intentionally uses rglob("*.md") to mirror upstream renderer enumeration, while _copy_traversable intentionally keeps its iterdir() recursion; their symlinked-directory behavior differs because they answer different questions.
• SNAPSHOT_TOKEN_RE was verified byte-for-byte against BMAD-METHOD main at 57e70562e3776b47bce1a54710f1edb1f0bd3618.

Verification

• uv run pytest tests/test_install.py tests/test_cli.py -q — 619 passed
• uv run pytest tests/test_stories_e2e.py -q — 13 passed
• clean linked-worktree full suite — 3968 passed, 30 skipped
• uv run pyright — 0 diagnostics
• trunk check — clean
• 13 gate-discriminator ablations on Python 3.13 and 3.14, each against the same 3998-test collection with the paired witness inspected

Tracking: #433

Resolves #410

Summary by CodeRabbit

• New Features

  • Added validation for developer-rendered skills and their required configuration, scripts, workflows, and source files.
  • Added warnings when generated renderer output is tracked by Git, with remediation guidance.
  • Installation now automatically excludes generated renderer output from version control.

• Bug Fixes

  • Runs and dry-runs now stop early with actionable diagnostics when renderer requirements are incomplete.
  • Renderer issues in non-development skill trees no longer block execution.

[greptile-apps]

pbean has reached the 50-credit limit for trial accounts. To continue receiving code reviews, upgrade your plan.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 6e9e5d70-8af0-493f-9e08-5e73a3dd2c6e

📥 Commits

Reviewing files that changed from the base of the PR and between 90915aa and fc14e88.

📒 Files selected for processing (7)

• src/bmad_loop/checks.py
• src/bmad_loop/cli.py
• src/bmad_loop/install.py
• tests/conftest.py
• tests/test_cli.py
• tests/test_install.py
• tests/test_stories_e2e.py

---

Walkthrough

The PR adds renderer-aware skill validation, stable validation check IDs, tracked render-output warnings, renderer-directory Git exclusions, and CLI/E2E coverage for missing prerequisites, dry runs, and successful execution.

Changes

Renderer preflight

Layer / File(s)	Summary
Renderer detection and fixtures src/bmad_loop/install.py, tests/conftest.py, tests/test_install.py	Renderer-backed primitives are detected from skill content. Required scripts, helpers, configuration, workflow entries, and snapshot sources are resolved.
Renderer validation and Git checks src/bmad_loop/checks.py, src/bmad_loop/cli.py, src/bmad_loop/install.py, tests/test_cli.py, tests/test_install.py	Validation IDs and findings cover missing renderer prerequisites. cmd_validate warns when _bmad/render is tracked. Initialization adds the render directory to .gitignore.
Preflight and execution coverage tests/test_cli.py, tests/test_stories_e2e.py	Tests cover blocked runs, dry-run diagnostics, triage-only trees, complete renderer installations, and successful tmux execution.

Estimated code review effort: 4 (Complex) | ~60 minutes

Possibly related issues

• bmad-code-org/bmad-loop issue 433 — Directly tracks the renderer preflight checks implemented here.

Possibly related PRs

• bmad-code-org/bmad-loop#155 — Implements related renderer-era validation and installation logic.
• bmad-code-org/bmad-loop#406 — Overlaps with renderer validation and tracked render-output handling.
• bmad-code-org/bmad-loop#436 — Shares renderer-aware validation changes and renamed primitive handling.

Suggested reviewers: dracic

Poem

A rabbit checks the render trail,
Finds missing scripts beneath the veil.
Config and sources line up bright,
Git keeps generated files out of sight.
The build hops through its preflight gate,
Then tmux helps it celebrate. 🐇

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 31.43% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly identifies the renderer-backed development skill preflight change.
Linked Issues check	✅ Passed	The changes satisfy [#410] by blocking incomplete renderer support, preserving render handling, and excluding probing and parity work.
Out of Scope Changes check	✅ Passed	The source and test changes directly support renderer preflight validation, reporting, provisioning, and initialization requirements.

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/renderer-preflight-410

---

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.}