mtg_python_deckbuilder/docs/user_guides/bracket_compliance.md

Bracket Compliance

Select a power level for your deck and get a detailed compliance report against the official Commander bracket rules.

---

Overview

Commander brackets define five power tiers from Exhibition (casual) to cEDH (competitive). The builder checks your finished deck against the rules for your selected bracket and surfaces a PASS / WARN / FAIL report per category.

Bracket selection lives in the New Deck modal. The compliance report appears in Step 5 and is exported to the compliance JSON sidecar (deck_files/*_compliance.json).

---

Bracket Tiers

Bracket	Name	Key restrictions
1	Exhibition	No Game Changers; no two-card infinite combos; no mass land denial; extra turns discouraged; tutors sparse
2	Core	No Game Changers; no two-card infinite combos; no mass land denial; extra turns not chained; tutors sparse
3	Upgraded	Up to 3 Game Changers; no mass land denial; no early/cheap two-card combos; extra turns not chained
4	Optimized	No bracket restrictions (banned list still applies)
5	cEDH	No bracket restrictions (banned list still applies; competitive mindset)

Bracket rules follow the official Wizards of the Coast Commander bracket definitions. The card lists used for compliance checks are stored in config/card_lists/ and can be updated as WotC revises the lists.

---

Compliance Categories

For each build, the compliance report checks:

Category	What is checked
Game Changers	Cards on the official Game Changers list (config/card_lists/game_changers.json)
Extra turns	Cards that grant extra turns (extra_turns.json)
Mass land denial	Cards that destroy, exile, or bounce many lands (mass_land_denial.json)
Non-land tutors	Cards that search the library for non-land cards
Two-card combos	Known two-card infinite combos (combos.json), with a flag for early/cheap combos

Each category returns a PASS / WARN / FAIL verdict and lists the flagged cards with links.

If the commander itself is on the Game Changers list, it is surfaced separately at the top of the report.

---

Enforcement Mode

Set enforcement_mode in your JSON config to control how the builder handles bracket violations:

Mode	Behavior
validate	Build freely, then report violations. No cards are blocked. (default)
prefer	During selection, avoid adding disallowed categories; cap Game Changers for Bracket 3.
strict	Block additions that would violate the bracket. Build fails with a clear message if unavoidable.

{
  "bracket": "core",
  "enforcement_mode": "prefer"
}

---

Rule Zero Notes

The rule_zero_notes field in the JSON config lets you document table agreements that override standard bracket rules:

{
  "bracket": "upgraded",
  "rule_zero_notes": "Mass land denial allowed by table agreement. Two-card combos capped at 1."
}

Rule zero notes appear in the compliance report header and are exported to the compliance JSON.

---

Web UI

• The bracket dropdown in the New Deck modal defaults to Core (Bracket 2) when no bracket is set.
• The compliance banner in Step 5 shows a color-coded overall verdict (green=PASS, yellow=WARN, red=FAIL) and expandable per-category details.
• WEB_AUTO_ENFORCE=1 re-runs compliance export automatically after each completed build.

---

Maintaining the Card Lists

The Game Changers list and companion lists are static JSON files in config/card_lists/. Each file includes source_url and generated_at metadata. Update them manually when WotC publishes revisions. Unknown cards in lookups are skipped with a note in the compliance report — they do not cause a hard failure.

---

Environment Variables

Variable	Default	Purpose
WEB_AUTO_ENFORCE	0	Auto-run compliance export after every build.

---

JSON Config Keys

Key	Values	Purpose
bracket	exhibition | core | upgraded | optimized | cedh	Bracket selection. Defaults to core if unset.
enforcement_mode	validate | prefer | strict	How violations are handled during building.
rule_zero_notes	string	Optional table agreement notes included in the compliance report.