v3.1.0 - Compatibility guardrails (Phase 6a)

Phase 6a — Compatibility guardrails. Backward compatible with v3.0.

Highlights

• compatibility.json — structured BMAD compatibility matrix shipped with the module: tested[], blocked[], supported_range, structural invariants, agent/skill expected counts, remediation hints
• scripts/lib/compat-check.js — vanilla Node compatibility engine. Zero dependencies. Tiny semver subset, naive YAML reader, four check sections (BMAD version, structural invariants, TeamBuilder integrity, manifest counts). Modes: human, --json, --quiet, --strict. A clean v3.1 install reports 44 PASS / 0 WARN / 0 FAIL.
• scripts/doctor.{ps1,sh} — read-only diagnostics. Wraps compat-check + bmad status. Reports a structured pass/fail summary. Use this when something feels broken, after upgrading BMAD, before running update.*, or when filing a bug report.
• scripts/update.{ps1,sh} — safe in-place update with snapshot + rollback:
  • Never touches _bmad/teams-*/ (your generated teams are preserved)
  • Snapshots _bmad/teambuilder/ to _bmad/.tb-backup-{timestamp}/ before any change
  • Runs compat-check before AND after the update
  • Offers rollback from the snapshot if the post-update check fails
  • Re-runs BMAD installer after rollback to regenerate manifests
  • Refuses to run if BMAD is in the blocked list (override with -Force)

Updating from v3.0

# Windows
.\scripts\update.ps1                  # interactive
.\scripts\update.ps1 -Yes             # non-interactive

# Linux/macOS
bash scripts/update.sh                # interactive
bash scripts/update.sh -y             # non-interactive

Validation

All 7 Phase 6a tests pass: doctor on healthy install, doctor JSON output, doctor on corrupted install detects failure, update succeeds and re-validates, backup snapshot preservation, refusal on non-installed targets, cleanup.

See CHANGELOG.md for the complete per-section diff.