belote-cli 2.9.2__tar.gz → 3.0.2__tar.gz

{belote_cli-2.9.2 → belote_cli-3.0.2}/.claude/settings.local.json

@@ -10,7 +10,8 @@
       "Bash(python3 -m pytest tests/ -q --tb=no)",
       "Bash(python3 -m pytest tests/ -x -q)",
       "Bash(PYTHONPATH=src python3 *)",
-      "Bash(.venv/bin/python -m mypy src/)"
+      "Bash(.venv/bin/python -m mypy src/)",
+      "Bash(PYTHONPATH=src python -m pytest --tb=short -q)"
     ]
   }
 }

{belote_cli-2.9.2 → belote_cli-3.0.2}/CHANGELOG.md

@@ -5,6 +5,144 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.0.2] - 2026-05-08
+
+Audit pass — wired two previously-dead 3.0.0 modules behind opt-in env vars, removed redundant work from `score_round()`, and pinned every boss modifier's patch keys against typo regressions.
+
+### Fixed
+
+- **`src/belote/belatro/main.py` + `src/belote/belatro/engine/round_driver.py`** — `GhostRecorder` (`src/belote/belatro/ghost_run.py`) was imported nowhere outside its own tests since it shipped in 3.0.0; ghost recording silently never happened. Wired through `drive_round()` via a new optional `recorder` param so bids, plays, and round-end breakdowns are now captured. Gated on `BELOTE_GHOST=1` so default play is unchanged. Saves to `~/.local/share/belote/ghosts/<label>-<seed>.json` on run end.
+- **`src/belote/gameflow.py`** — `replay.analyze_round()` / `summarize()` (`src/belote/replay.py`) was never called from any runtime path since it shipped in 3.0.0; the post-round Hard-AI comparison the README advertised silently never fired. `run_play()` now optionally accumulates `(state, played_card)` pairs for South; `run_round()` reads `BELOTE_REPLAY=1` once per round, runs the analyzer post-scoring, and prints a one-line `Replay: Optimal plays: N/M (P%)` summary. UNDO clears the buffer so the report matches the play that actually finished the round.
+
+### Improved
+
+- **`src/belote/scoring.py::score_round`** — pre-computes the per-trick winner list once at the top and threads it into `_calculate_base_points` and `_apply_scoring_modifiers`. Both helpers used to re-call `trick_winner_seat()` for every completed trick; under `separate_scoring` + `queen_spades_penalty` the 8-trick walk could run 3× per round.
+- **`src/belote/belatro/items/registry.py::register_all_items`** — now idempotent. A module-level `_registered` flag short-circuits subsequent calls; second clause `and registry.jokers` re-runs when a caller has swapped the global to a fresh empty `ItemRegistry` (the test-suite pattern at `tests/belatro/test_belatro.py::TestItemRegistry.setup_method`). Saves the 4× `dir(mod)` walk on every `BelAtroRun` after the first.
+- **`src/belote/ai.py::_special_bid`** — `_suit_lengths(hand)` is now computed once and threaded into `_easy_special` / `_medium_special` / `_hard_special`. The three branches each used to rebuild it from scratch.
+
+### Added
+
+- **`tests/belatro/test_phase0_coverage.py::test_every_boss_modifier_actually_patches_a_flag`** — pin against a typo'd `state.patch("_misspelled", True)` key silently producing a no-op boss. Iterates `ALL_BOSS_MODIFIERS`, asserts each `.flags()` differs from default `BossModifiers()`. The `boss_fields` allow-list in `engine/modifier_patch.py` is now load-bearing for correctness — this test surfaces drift.
+- **`DEVELOPMENT.md`** — new "Optional Runtime Flags" section documenting `BELOTE_REPLAY` and `BELOTE_GHOST` next to the existing `BELOTE_A11Y` entry.
+
+### Internal
+
+- **Tests**: 509 → 510 (+1).
+- **Strict gates**: pytest 510/510, mypy 0 errors, ruff 0 violations.
+
+### Known issue (not fixed in this cut)
+
+- `src/belote/belatro/engine/event_bus.py::EventBus.emit` is never called anywhere in the source. `unlock_tracker.subscribe_to(bus)` registers `on_event` but receives no events, so `_handle_round_end`'s unlocks for **L'Exécuteur** (first Capot), **L'Idéologue** (Sans Atout NS win), and **Le Fanatique** (Tout Atout NS win) silently never fire under normal play. Out of scope for 3.0.2 (fix would change ordering with `acc.update_state` in `round_driver._emit`); flagged for a follow-up.
+
+## [3.0.1] - 2026-05-07
+
+Post-3.0.0 audit pass — four player-visible / correctness bugs introduced or missed by the 3.0.0 cut, plus a batch of test-coverage and small-correctness improvements. No behaviour changes for code paths that were already correct.
+
+### Fixed
+
+- **`src/belote/game.py:860-873`** — `play_card()`'s per-trick running total honoured `kings_zero` and `tens_zero` but ignored the new 3.0.0 `aces_zero` and `jacks_zero` flags. Final scoring (`scoring.py::_calculate_base_points`) was correct, but the live HUD running total under Le Sauvage / L'Iconoclaste was wrong until the round ended. Mirrored the canonical `scoring.py` zero-rank pattern; `bm` aliased once for readability.
+- **`src/belote/belatro/ui/hud.py::_SYNERGY_PAIRS`** — referenced four joker IDs (`le_finisseur`, `le_dix_de_der`, `le_marseillais`, `carre_aces_x2`) that don't exist in the registry. Two of the four pairs were dead code that could never fire. Removed; `validate_synergy_ids()` now exposes a self-check, and `register_all_items()` asserts every synergy ID resolves so future typos surface at import time.
+- **`src/belote/gameflow.py:248-258`** — the a11y trick-winner announcement used raw `card_points()` and ignored every boss zero-rank flag, so screen-reader users heard inflated trick scores under Le Sauvage / L'Iconoclaste / Le Roi Mort / Les Dix Maudits / Les Clubs Bannis. New canonical helper `scoring.trick_card_points(state, trick)` is now the single source of truth for per-trick boss-aware totals.
+- **`src/belote/ai.py::AIMemory.last_voids_key`** — the new-round reset in `update_memory()` cleared `played`, `known_voids`, and `processed_tricks_count` but not the cache key. After the prior round's final key (e.g. `(7, 4)`), a fresh-round `(0, 0)` or `(0, 1)` could coincidentally match a key seen during round 1 and cause `_update_voids` to skip processing. Added `last_voids_key = None` to the reset.
+
+### Added
+
+- **`src/belote/scoring.py::trick_card_points`** — public helper for "card-point sum of one trick under all active boss zero-rank flags." Used by gameflow's a11y hook.
+- **`src/belote/belatro/ui/hud.py::validate_synergy_ids`** — return the synergy IDs that aren't registered as jokers. Used by `register_all_items()` for the new startup self-check.
+- **Tests**: `tests/test_a11y.py` (8 cases for `trick_card_points` + a11y stderr emit), `tests/belatro/test_hud_synergy.py` (5 cases for the synergy registry), HOLO/POLYCHROME edition tests + four `separate_scoring × zero-flag` composition tests in `tests/belatro/test_dead_flag_fixes.py`, cross-round void-cache regression test in `tests/test_ai.py`. Tests grew 489 → 509 (+20).
+
+### Improved
+
+- **`src/belote/belatro/run_summary.py`** — resolved path is cached at module level after the first call, so `mkdir` is no longer re-attempted on every BelAtro exit.
+- **`src/belote/a11y.py`** — `BELOTE_A11Y` env var resolved once at module import (`_ENABLED` module variable). Tests use `_refresh_enabled_from_env()` to re-read after `monkeypatch.setenv`. Saves ~30 environ lookups per round in the disabled path.
+- **`src/belote/scoring.py:649-668`** — Sans Atout Capot branch now asserts `taker_belote == 0 and defender_belote == 0`. Belote/Rebelote requires a unique trump suit, so this invariant should always hold under SA — the assertion documents it and surfaces any future regression that leaks belote points into the SA path.
+- **`src/belote/belatro/run/boss.py::LeMime`** — docstring notes the redundancy between `declarations_zero` and `separate_scoring` and points to the regression test that pins their composition.
+
+### Internal
+
+- **Tests**: 489 → 509 (+20). All new modules covered: a11y boss-aware pts (8), HUD synergy registry (5), HOLO/POLYCHROME editions (2), separate_scoring × zero-flag matrix (4), cross-round void cache (1).
+- **Strict gates**: pytest 509/509, mypy 0 errors, ruff 0 violations.
+- **Perf baseline**: unchanged from 3.0.0 (sub-millisecond throughout).
+
+## [3.0.0] - 2026-05-07
+
+Bug-hunt + audit pass — three player-visible features that were registered but silently no-ops are now wired, the Capot scoring under Sans Atout / Tout Atout has been corrected, mypy is once again strict-clean, and a batch of P3 features lands behind the new BelAtro Endless mode flow.
+
+### Fixed
+
+- **`src/belote/scoring.py::score_round`** — Capot reward used a flat `CAPOT_BASE = 252` for every contract, over-paying SA Capots (252 vs the contract-correct 220) and under-paying TA Capots (252 vs 348). New `CAPOT_BASE_SANS_ATOUT = 220` and `CAPOT_BASE_TOUT_ATOUT = 348` constants in `config.py`; scoring now branches on `state.contract`. `tests/test_belote.py::TestCapotPerContract` covers all three contracts; `tests/test_official_rules.py::test_sans_atout_score_round_baseline` updated from 252 → 220.
+- **`src/belote/belatro/items/planets.py::TheSun`** — `level_up_reward()` returned `{"bonus_mult_per_trick": 1.0}` but no consumer ever read the key. Wired into `belatro/core/scoring.py::ScoreAccumulator` on `TrickWonEvent` when `event.trump == Suit.TOUT_ATOUT and event.trick_number > 4`.
+- **`src/belote/belatro/items/planets.py::Libra`** — `coinche_multiplier` was set on the contract level but never read. Now consumed at `RoundEndEvent` time, scaled by `event.coinche_level`, and gated on the round being a non-failed taker win for NS.
+- **`src/belote/scoring.py`** — `RoundScore` was constructed via `**common_kwargs` splat; mypy lost the per-field types and reported 8 errors. Inlined into both branches.
+- **`src/belote/ui/render.py::_slot_frame_row`** — variable shadowing (`for c in range(...)` then `for c in cells`) made mypy infer `cells[i]` as `int`. Renamed the inner loop variables (`c → i`, `c → cell`).
+- **`src/belote/ui/prompts.py`** — three untyped helpers (`_hist_taker_label`, `_hist_contract_label`, `_hist_status`) now annotated with `RoundScore`.
+- **`src/belote/ui/prompts.py::show_history`** — N806 lint on `W_RD/W_TKR/...` constants resolved by lowercasing the locals; behaviour unchanged.
+- **`src/belote/ai.py::_process_trick_voids`** — under the `republicain_wild` flag (Le Républicain deck / boss reuse), playing a 7 or 8 off-suit no longer falsely flags the player as void in the lead suit. Hard AI's void inference now skips wild ranks when the flag is active.
+
+### Added
+
+- **`src/belote/belatro/main.py`** — post-Ante-8 endless prompt. After winning Ante 8, the run offers `Continue into Endless Mode? (Ante 9+ scales ×2.2)`. Built on the existing `BelAtroRun.endless` / `endless_ante_offset` infrastructure plus a new `BelAtroAnnounce.yes_no` helper.
+- **`src/belote/belatro/items/base.py::Edition`** — new enum (NONE/FOIL/HOLO/POLYCHROME/NEGATIVE). Shop generation rolls per-joker editions; Foil adds +50 chips per trigger, Holo +10 mult, Polychrome ×1.5 mult, Negative grants an extra joker slot at purchase. Wiring lives in `belatro/run/shop.py` and `belatro/core/scoring.py::_apply_edition`.
+- **`src/belote/belatro/run/boss.py`** — three new boss blinds (Le Sauvage / L'Iconoclaste / Le Mime) and three new `BossModifiers` flags (`aces_zero`, `jacks_zero`, `declarations_zero`) read by the existing scoring path.
+- **`src/belote/belatro/ui/hud.py::detect_synergies`** — small registry of known joker pair combos; renders a `★ SYN×N` badge on the HUD when any pair (or 3+ jokers) is held.
+- **`src/belote/achievements.py`** + **`src/belote/stats.py::Statistics.achievements`** — six classic-mode achievements (first Capot, 3 Capots in a session, 2 Capot streak, 300+ point round, hard win, ten games played) auto-evaluated post-round / post-game.
+- **`src/belote/themes.py::THEMES["colorblind"]`** — deuteranopia/protanopia-friendly palette using blue/cyan/orange instead of red/green.
+- **`src/belote/a11y.py`** — screen-reader hints. Cards played, trick winners, and round results emit one-line plain-text descriptions to stderr when the env var `BELOTE_A11Y=1` is set.
+- **`src/belote/replay.py`** — `analyze_round()` runs the just-played decisions through the Hard AI and reports per-decision agreement; `summarize()` produces a one-line `Optimal: N/M (X%)` string.
+- **`src/belote/belatro/ghost_run.py`** — `GhostRecorder` accumulates seed + bid + play events and serializes them to JSONL under the user data dir. Foundation for a future ghost-replay viewer; the JSON format is versioned (v1).
+- **`src/belote/belatro/run_summary.py`** — appends a one-line per-run summary (deck, ante, jokers, won) to `~/.local/share/belote/run_history.jsonl` on BelAtro exit. Best-effort, OSError-swallowed.
+- **`src/belote/gameflow.py::show_hand_preview`** — short `Dealing…` flourish before the hand preview, gated on the existing speed setting and skippable via Space/Esc.
+
+### Improved
+
+- **`src/belote/ansi.py`** — 16 palette accessors (`felt_bg()`, `red_fg()`, …) previously hit `theme_manager.get_current()` per call. Cached the active `Theme` at module level and registered an invalidation callback with `theme_manager`. Lower per-render dict-lookup overhead.
+- **`src/belote/themes.py::ThemeManager`** — redundant class-level `_current_theme_name` removed; new public `current_name` property; `_initialized` guard now uses `getattr` for clarity. Eight call sites in `ui/menu.py`, `ui/prompts.py`, and `ui/render.py` migrated off `_current_theme_name`.
+- **`src/belote/ui/render.py`** — `_LAST_RENDER_KEY` list-of-one singleton replaced with a module-level variable + `global` declaration; same behaviour, less Python idiom drag.
+- **`src/belote/ai.py::AIMemory.last_voids_key`** — caches `(completed_count, current_trick_len)` so `_update_voids` short-circuits on repeat calls within the same trick decision (lookahead exploration triggered redundant scans).
+
+### Internal
+
+- **Performance baseline (post-fix)**: `scripts/benchmark.py` reports render 0.271ms (±0.044), AI Easy/Med/Hard 0.015 / 0.030 / 0.026 ms, BelAtro update 0.032 ms, scoring 0.169 ms, deal 0.071 ms, legal_cards 0.012 ms.
+- **Tests**: 446 → 489 (+43). New files: `tests/test_ansi_helpers.py`, `tests/test_achievements.py`, `tests/test_replay.py`, `tests/belatro/test_ghost_run.py`. Existing files extended with Capot-per-contract, Sun/Libra wiring, TA→le_fanatique unlock, republicain-void edge case, and three new boss tests.
+- **Strict mode**: README's "0 mypy errors / 0 ruff violations" claim was inaccurate at 2.9.5 (18 mypy + 10 ruff at audit time). Both gates are now actually clean.
+
+## [2.9.5] - 2026-05-07
+
+In-game keyboard shortcuts cleaned up, the trick mat now anchors every played card inside a visible per-seat slot, the round history overlay carries the full per-round picture, and the cards have been redrawn in a GRIMAUD-1898 style with both-corner indices and patterned pip layouts.
+
+### Fixed
+
+- **`src/belote/input.py`** — `Key.THEME` was defined but never mapped to a keystroke; the help text falsely advertised `Shift+T` (which terminals can't generally distinguish in raw mode). Theme cycling during gameplay was unreachable. New mapping: `t/T → Key.THEME`, `h/H → Key.HIST`, `?` → `Key.HELP`, `o/O → Key.SORT`. Both the Unix and Windows readers updated.
+- **`src/belote/input.py`** — `s` was previously stolen by `Key.SORT`, so pressing `S` in round-2 bidding triggered a sort instead of the **Sans Atout** quick-bid the help text promised. Sort now lives on `O` (matching what the help screen always claimed) and `s` falls through to `Key.CHAR` so SA bidding works.
+- **`src/belote/gameflow.py::run_play`** — when the user had already pressed any key earlier in the round (which sets `skip_anims`), the post-trick pause was skipped entirely and the 4th card vanished before it could be read. New `MIN_TRICK_DWELL = 0.5s` non-skippable hold runs after every completed trick (even on the `instant` speed preset) so the player always sees all four cards before the mat clears.
+
+### Added
+
+- **`src/belote/ui/render.py`** — visible **slot frames** drawn around each compass position on the trick mat. Implemented via three new helpers (`_slot_anchors`, `_slot_frame_row`, `_felt_pad_ns`, `_we_row`) that paint thin `─`/`│` borders on the felt cells immediately surrounding each card slot, in the felt-placeholder dim colour. Total mat dimensions (`6 + 3*card_h`) are unchanged, so `_calculate_base_row` and `patch_trick_card` continue to work without any coordinate adjustments — patched cards land exactly inside the existing frame.
+- **`src/belote/game.py::RoundScore`** — eight new optional fields (`contract`, `trump`, `taker_seat`, `tricks_ns`, `tricks_ew`, `last_trick_winner`, `decl_summary_ns`, `decl_summary_ew`) populated from `state` and `state.completed_tricks` at scoring time. All fields default so existing test fixtures and any historical `RoundScore` constructions remain valid.
+- **`src/belote/scoring.py::apply_round_score`** — now computes per-team trick counts via `trick_winner_seat`/`team_of`, builds short declaration labels (`"100♥"`, `"Belote"`, `"Carré-J"`, …) gated on the team's `*_decl_pts > 0` so only the *scored* declarations appear, and threads everything into `RoundScore`. New helper `_decl_short_label` covers belote/rebelote/sequence/carre.
+- **`src/belote/ui/prompts.py::show_history`** — rewritten as an 8-column table (`RD | TAKER | CONTRACT | TRICKS | DECLARATIONS | NS | EW | STATUS`) for terminals ≥78 cols, with a 2-line-per-round fallback for narrower terminals. Status colouring: gold `CAPOT`, red `CHUTE`, dim `LITIGE`. Existing scrolling, view-height clamp, and exit-on-any-key behaviour preserved.
+- **`src/belote/ui/render.py::_card_face_internal`** — full GRIMAUD-1898-inspired redraw:
+  - Both corners now carry a 3-cell `rank+suit` index (`A♠` top-left, `♠A` bottom-right). The index padding scales with `inner_w`.
+  - Pip cards (7-10) at `card_h ≥ 7` get a recognisable pip arrangement instead of a single centred suit symbol.
+  - Court cards J/Q/K each get a distinct multi-row motif (sword, jewelled headdress, crown).
+  - Aces get a decorative `╭─◆─╮` / `╰─◆─╯` wreath around the central suit.
+  - Compact 6×5 layout keeps the single inner row but still benefits from both-corner indices.
+  - All variants honour the active theme (`face_card_bg`, `card_face_bg`, `highlight_bg`, `red_fg`/`black_fg`) and the `DIM` prefix for illegal cards. ASCII fallback paths preserved.
+- **`tests/test_extended.py::test_round_score_history_extra_fields`** — pins the new `RoundScore` fields end-to-end through `apply_round_score`.
+
+### Changed
+
+- **`src/belote/ui/menu.py`** — main-menu loop now handles `Key.THEME` (cycles forward through `THEMES`), so the new in-game `T` shortcut works at the menu too.
+- **`src/belote/main.py`**, **`src/belote/ui/render.py`** — game-over hint and HUD compact hint updated to advertise the new `[H] History` / `[T] Theme` shortcuts.
+- **`src/belote/ui/prompts.py::show_help`** — help-screen text rewritten to match the new bindings.
+- **`README.md`** — Controls section rewritten; theme section now lists all six themes by name.
+- **`tests/test_layout.py::test_hud_compact_omits_help_hints_and_theme`** — assertion updated for the new compact-HUD hint substring.
+
+### Notes
+
+436/436 tests pass. No gameplay, scoring, or AI-decision changes — all updates are UX (keys, slot framing, dwell, history depth, card glyphs).
+
 ## [2.9.2] - 2026-05-07
 
 Render-pipeline fix for Konsole (KDE/Kubuntu) and other strict ANSI terminals where UI elements visibly stacked on top of each other — the top HUD repeating ~6 times, "Theme: Sepia Vintage" duplicating in the right column, "Partner" doubling, the bid prompt repainting below itself, and bid history accumulating between frames. The bug existed in the code on every terminal but VTE-based emulators (LXTerminal, GNOME Terminal, xterm) auto-blanked the leaking cells, masking it. Konsole's Vt102Emulation does not, so the leakage was visible.

{belote_cli-2.9.2 → belote_cli-3.0.2}/DEVELOPMENT.md

@@ -78,21 +78,28 @@ PYTHONPATH=src pytest --cov=belote --cov-report=term-missing
 The project maintains zero lint and type-check violations. Run all checks with:
 
 ```bash
-# Type checking (0 errors expected)
-PYTHONPATH=src mypy .
+# Type checking (0 errors expected, strict mode)
+PYTHONPATH=src mypy --strict src/
 
 # Linting (0 violations expected)
-ruff check .
-# Full test suite (435 tests expected)
-PYTHONPATH=src pytest
+ruff check src/ tests/
 
-# ...
+# Full test suite (510 tests expected)
+PYTHONPATH=src pytest
+```
 
-Current baseline:
+Current baseline (3.0.2):
 - **mypy**: 0 errors (strict mode)
 - **ruff**: 0 violations
-- **pytest**: 435 tests, 0 failures
+- **pytest**: 510 tests, 0 failures
 
+Run all gates before committing:
+
+```bash
+PYTHONPATH=src python -m pytest --tb=short -q && \
+  python -m mypy --strict src/ && \
+  python -m ruff check src/ tests/
+```
 
 ## Benchmarking
 
@@ -101,6 +108,36 @@ A benchmarking script is provided to measure rendering and AI performance:
 PYTHONPATH=src python scripts/benchmark.py
 ```
 
+3.0.0 baseline numbers (Linux, Python 3.10+, 1000 iterations):
+- Render: 0.27 ms (±0.04)
+- AI Hard decide_card: 0.026 ms (±0.003)
+- BelAtro state update: 0.032 ms (±0.004)
+- score_round: 0.169 ms
+- legal_cards: 0.012 ms
+
+Use these as a regression-detection floor for future changes.
+
+## Accessibility
+
+Set `BELOTE_A11Y=1` to emit one-line plain-text descriptions of card plays,
+trick winners, and round results to stderr — readable by terminal screen
+readers (Orca, NVDA over WSL, VoiceOver via iTerm2).
+
+## Optional Runtime Flags
+
+The following environment variables enable opt-in features. Each is read
+once at startup; toggling mid-run has no effect.
+
+- `BELOTE_REPLAY=1` — after every Classic round, print a one-line summary
+  of how often South's plays matched the Hard-AI's preferred line
+  (e.g. `Replay: Optimal plays: 6/8 (75%)`). Educational only — never
+  affects scoring. Backed by `src/belote/replay.py`.
+- `BELOTE_GHOST=1` — silently record every BelAtro run (seed, deck,
+  bids, plays, round outcomes) to
+  `~/.local/share/belote/ghosts/<label>-<seed>.json`. The file is written
+  once when the run ends. Useful for sharing or replaying interesting
+  runs. Backed by `src/belote/belatro/ghost_run.py`.
+
 ## Releasing a New Version
 
 ### Code-only update (push to GitHub without releasing a new PyPI version)

{belote_cli-2.9.2 → belote_cli-3.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: belote-cli
-Version: 2.9.2
+Version: 3.0.2
 Summary: A 4-player terminal card game
 Project-URL: Homepage, https://github.com/ElysiumDisc/belote
 Project-URL: Repository, https://github.com/ElysiumDisc/belote
@@ -45,7 +45,30 @@ Description-Content-Type: text/markdown
 
 Complete implementation of the French card game Belote for the terminal, with a full-screen green felt table and full card graphics at compass positions (N/W/E/S).
 
-## Now Featuring: BelAtro Expansion
+## What's new in 3.0.2
+
+- **Replay analyzer + Ghost run wired up** — both shipped in 3.0.0 as code modules but were never called from the running game. Now opt-in behind `BELOTE_REPLAY=1` (post-round Hard-AI comparison) and `BELOTE_GHOST=1` (per-run JSON dump to `~/.local/share/belote/ghosts/`). See DEVELOPMENT.md › Optional Runtime Flags.
+- **Performance** — `score_round()` now caches per-trick winners once instead of recomputing them in each boss-modifier helper (2-3× walks → 1× walk per round). `register_all_items()` is now idempotent so test setup no longer re-walks every items module per `BelAtroRun`. Bidding's special-bid path (TA / SA) hoists `_suit_lengths` out of the per-difficulty branches.
+- **Defensive pin** — every entry in `ALL_BOSS_MODIFIERS` is now asserted to actually toggle a `BossModifiers` field via `.flags()`. Catches typo'd `state.patch("_misspelled", True)` keys at test time rather than letting the boss silently no-op.
+- **Test coverage** — 510 tests (up from 509).
+
+## What's new in 3.0.1
+
+- **Bug fixes** — `play_card()` running total now honours `aces_zero` / `jacks_zero` (Le Sauvage / L'Iconoclaste); the screen-reader trick-winner pts are now boss-aware; the HUD synergy registry no longer references nonexistent joker IDs; the AI void-cache key is now reset across rounds.
+- **Test coverage** — 509 tests (up from 489): HOLO/POLYCHROME editions, multi-boss composition (`separate_scoring × zero-flag`), a11y boss-aware pts, synergy registry self-check.
+
+## What's new in 3.0.0
+
+- **Endless mode** — beat Ante 8 in BelAtro and the run offers a continuation: targets scale ×2.2 per ante and a furthest-ante leaderboard tracks how deep you go.
+- **Joker editions** — Foil (+50 chips), Holo (+10 mult), Polychrome (×1.5 mult), Negative (extra slot) randomly stamp shop jokers.
+- **Three new boss blinds** — Le Sauvage (Aces = 0), L'Iconoclaste (Jacks = 0, even trump-J), Le Mime (Declarations = 0).
+- **Achievements** — six classic-mode milestones tracked across sessions.
+- **Colorblind palette** + **screen-reader hints** (`BELOTE_A11Y=1`) for accessibility.
+- **Replay analyzer** — module added (post-round Hard-AI comparison). User-facing wiring landed in 3.0.2 behind `BELOTE_REPLAY=1`.
+- **Ghost run recording** + **run summary log** — modules added (serialize a run / append per-run JSON). Run-summary fires automatically; ghost-run user-facing wiring landed in 3.0.2 behind `BELOTE_GHOST=1`.
+- **Bug fixes** — Capot under Sans Atout / Tout Atout now uses the correct base (220 / 348, not 252); The Sun and Libra planets actually do something now; AI void inference no longer mis-flags voids under Le Républicain wild 7/8.
+
+## BelAtro Expansion
 
 **BelAtro** is a major roguelite expansion inspired by *Balatro*. Play through 8 Antes of escalating difficulty, build a deck of powerful Jokers, and use Tarot cards and Planets to break the game! 
 
@@ -170,12 +193,12 @@ belote --difficulty hard --target 500 --seed 123 --speed fast
 ## Controls
 
 **General:**
-- `?` or `H`: Show keyboard shortcut help
+- `?`: Show keyboard shortcut help
 - `M`: Toggle sound effects on/off
-- `I`: Toggle BelAtro score overlay (per-trick breakdown popup)
+- `I` or `V`: Toggle BelAtro score overlay (per-trick breakdown popup)
 - `Q`: Quit to main menu or exit
-- `t`: View Game History (Round-by-round)
-- `T`: Switch UI Theme
+- `H`: View Game History (round-by-round, with contract / taker / tricks / declarations)
+- `T`: Cycle UI Theme
 
 **Classic Belote:**
 - `↑` `↓`: Navigate options
@@ -183,7 +206,6 @@ belote --difficulty hard --target 500 --seed 123 --speed fast
 - `Enter`: Select option / Enter submenu
 
 **BelAtro (Roguelite):**
-- `S`: View current Run State and Jokers
 - `1`-`5`: Inspect specific Jokers in the Shop
 - `U`: Use a consumable (Tarot/Planet) during gameplay
 
@@ -194,6 +216,7 @@ belote --difficulty hard --target 500 --seed 123 --speed fast
 - `O`: Sort hand by suit and rank
 - `Z`: Undo last move
 - `Space` or `Esc`: Skip animations
+- During bidding round 2: `P` = Pass, `A` = Tout Atout, `S` = Sans Atout
 
 ## Features
 
@@ -204,7 +227,7 @@ belote --difficulty hard --target 500 --seed 123 --speed fast
 - **Partner Trust:** Build a relationship with your AI partner to unlock synergies.
 - **Rich Terminal UI:** Full-screen green felt table with detailed card graphics and "You" vs "Partner" terminology.
 - **Enhanced Hard AI**: Advanced void inference and 2-ply lookahead for critical tricks (Dix de Der).
-- **Customizable Themes:** Switch between different color palettes (e.g., Classic Green, Dark Blue, Royal Purple) using the `T` key during gameplay.
+- **Customizable Themes:** Switch between six color palettes (Classic Green, Dark Mode, Blue Velvet, Red Casino, Sepia Vintage, High Contrast) using the `T` key during gameplay.
 - **Incremental Rendering:** High-performance cursor-based updates for zero-flicker gameplay even at high speeds.
 - **Hand Sorting:** Strategic "play value" organization (honors grouped together) for better tactical awareness.
 - **Main Menu:** Simple single-player entry point with configurable AI difficulty, Target Score, and Speed.
@@ -267,7 +290,7 @@ belote/
 PYTHONPATH=src pytest
 ```
 
-Currently **435 tests** passing with 100% coverage on core logic.
+Currently **510 tests** passing with 100% coverage on game-logic modules.
 
 ## Technical Integrity
 

{belote_cli-2.9.2 → belote_cli-3.0.2}/README.md

@@ -2,7 +2,30 @@
 
 Complete implementation of the French card game Belote for the terminal, with a full-screen green felt table and full card graphics at compass positions (N/W/E/S).
 
-## Now Featuring: BelAtro Expansion
+## What's new in 3.0.2
+
+- **Replay analyzer + Ghost run wired up** — both shipped in 3.0.0 as code modules but were never called from the running game. Now opt-in behind `BELOTE_REPLAY=1` (post-round Hard-AI comparison) and `BELOTE_GHOST=1` (per-run JSON dump to `~/.local/share/belote/ghosts/`). See DEVELOPMENT.md › Optional Runtime Flags.
+- **Performance** — `score_round()` now caches per-trick winners once instead of recomputing them in each boss-modifier helper (2-3× walks → 1× walk per round). `register_all_items()` is now idempotent so test setup no longer re-walks every items module per `BelAtroRun`. Bidding's special-bid path (TA / SA) hoists `_suit_lengths` out of the per-difficulty branches.
+- **Defensive pin** — every entry in `ALL_BOSS_MODIFIERS` is now asserted to actually toggle a `BossModifiers` field via `.flags()`. Catches typo'd `state.patch("_misspelled", True)` keys at test time rather than letting the boss silently no-op.
+- **Test coverage** — 510 tests (up from 509).
+
+## What's new in 3.0.1
+
+- **Bug fixes** — `play_card()` running total now honours `aces_zero` / `jacks_zero` (Le Sauvage / L'Iconoclaste); the screen-reader trick-winner pts are now boss-aware; the HUD synergy registry no longer references nonexistent joker IDs; the AI void-cache key is now reset across rounds.
+- **Test coverage** — 509 tests (up from 489): HOLO/POLYCHROME editions, multi-boss composition (`separate_scoring × zero-flag`), a11y boss-aware pts, synergy registry self-check.
+
+## What's new in 3.0.0
+
+- **Endless mode** — beat Ante 8 in BelAtro and the run offers a continuation: targets scale ×2.2 per ante and a furthest-ante leaderboard tracks how deep you go.
+- **Joker editions** — Foil (+50 chips), Holo (+10 mult), Polychrome (×1.5 mult), Negative (extra slot) randomly stamp shop jokers.
+- **Three new boss blinds** — Le Sauvage (Aces = 0), L'Iconoclaste (Jacks = 0, even trump-J), Le Mime (Declarations = 0).
+- **Achievements** — six classic-mode milestones tracked across sessions.
+- **Colorblind palette** + **screen-reader hints** (`BELOTE_A11Y=1`) for accessibility.
+- **Replay analyzer** — module added (post-round Hard-AI comparison). User-facing wiring landed in 3.0.2 behind `BELOTE_REPLAY=1`.
+- **Ghost run recording** + **run summary log** — modules added (serialize a run / append per-run JSON). Run-summary fires automatically; ghost-run user-facing wiring landed in 3.0.2 behind `BELOTE_GHOST=1`.
+- **Bug fixes** — Capot under Sans Atout / Tout Atout now uses the correct base (220 / 348, not 252); The Sun and Libra planets actually do something now; AI void inference no longer mis-flags voids under Le Républicain wild 7/8.
+
+## BelAtro Expansion
 
 **BelAtro** is a major roguelite expansion inspired by *Balatro*. Play through 8 Antes of escalating difficulty, build a deck of powerful Jokers, and use Tarot cards and Planets to break the game! 
 
@@ -127,12 +150,12 @@ belote --difficulty hard --target 500 --seed 123 --speed fast
 ## Controls
 
 **General:**
-- `?` or `H`: Show keyboard shortcut help
+- `?`: Show keyboard shortcut help
 - `M`: Toggle sound effects on/off
-- `I`: Toggle BelAtro score overlay (per-trick breakdown popup)
+- `I` or `V`: Toggle BelAtro score overlay (per-trick breakdown popup)
 - `Q`: Quit to main menu or exit
-- `t`: View Game History (Round-by-round)
-- `T`: Switch UI Theme
+- `H`: View Game History (round-by-round, with contract / taker / tricks / declarations)
+- `T`: Cycle UI Theme
 
 **Classic Belote:**
 - `↑` `↓`: Navigate options
@@ -140,7 +163,6 @@ belote --difficulty hard --target 500 --seed 123 --speed fast
 - `Enter`: Select option / Enter submenu
 
 **BelAtro (Roguelite):**
-- `S`: View current Run State and Jokers
 - `1`-`5`: Inspect specific Jokers in the Shop
 - `U`: Use a consumable (Tarot/Planet) during gameplay
 
@@ -151,6 +173,7 @@ belote --difficulty hard --target 500 --seed 123 --speed fast
 - `O`: Sort hand by suit and rank
 - `Z`: Undo last move
 - `Space` or `Esc`: Skip animations
+- During bidding round 2: `P` = Pass, `A` = Tout Atout, `S` = Sans Atout
 
 ## Features
 
@@ -161,7 +184,7 @@ belote --difficulty hard --target 500 --seed 123 --speed fast
 - **Partner Trust:** Build a relationship with your AI partner to unlock synergies.
 - **Rich Terminal UI:** Full-screen green felt table with detailed card graphics and "You" vs "Partner" terminology.
 - **Enhanced Hard AI**: Advanced void inference and 2-ply lookahead for critical tricks (Dix de Der).
-- **Customizable Themes:** Switch between different color palettes (e.g., Classic Green, Dark Blue, Royal Purple) using the `T` key during gameplay.
+- **Customizable Themes:** Switch between six color palettes (Classic Green, Dark Mode, Blue Velvet, Red Casino, Sepia Vintage, High Contrast) using the `T` key during gameplay.
 - **Incremental Rendering:** High-performance cursor-based updates for zero-flicker gameplay even at high speeds.
 - **Hand Sorting:** Strategic "play value" organization (honors grouped together) for better tactical awareness.
 - **Main Menu:** Simple single-player entry point with configurable AI difficulty, Target Score, and Speed.
@@ -224,7 +247,7 @@ belote/
 PYTHONPATH=src pytest
 ```
 
-Currently **435 tests** passing with 100% coverage on core logic.
+Currently **510 tests** passing with 100% coverage on game-logic modules.
 
 ## Technical Integrity
 

{belote_cli-2.9.2 → belote_cli-3.0.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "belote-cli"
-version = "2.9.2"
+version = "3.0.2"
 description = "A 4-player terminal card game"
 readme = "README.md"
 requires-python = ">=3.10"

{belote_cli-2.9.2 → belote_cli-3.0.2}/src/belote/__init__.py

@@ -1,3 +1,3 @@
-__version__ = "2.9.2"
+__version__ = "3.0.2"
 
 __all__ = ["__version__"]

belote_cli-3.0.2/src/belote/a11y.py

@@ -0,0 +1,93 @@
+"""3.0.0: optional screen-reader hints.
+
+When the env var ``BELOTE_A11Y`` is truthy, key in-game events emit a plain-text
+line to stderr — readable by terminal screen readers such as Orca, NVDA in WSL,
+or VoiceOver via iTerm2. Disabled by default so it doesn't pollute output for
+sighted players.
+
+Hooked from gameflow.py (card plays, trick winners, round results) and from
+belatro/main.py (boss reveal, ante advance, run won/lost). Each hook is a
+single line — no rich formatting — so the screen reader can speak it cleanly.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .deck import Card
+    from .game import Seat
+
+
+# 3.0.1: resolve the env var once at import. The flag is read on every card
+# play (~32 times/round); a dict lookup is cheap but bypassing it keeps
+# `speak()` essentially free in the disabled path.
+_TRUTHY = {"1", "true", "yes", "on"}
+_ENABLED: bool = os.environ.get("BELOTE_A11Y", "").lower() in _TRUTHY
+
+
+def is_enabled() -> bool:
+    """Return whether a11y hints are enabled.
+
+    Reads the cached module-level value (set at import). Tests that use
+    `monkeypatch.setenv("BELOTE_A11Y", ...)` should call
+    `_refresh_enabled_from_env()` after the patch.
+    """
+    return _ENABLED
+
+
+def _refresh_enabled_from_env() -> None:
+    """Re-read BELOTE_A11Y from the live environment. Public for tests."""
+    global _ENABLED
+    _ENABLED = os.environ.get("BELOTE_A11Y", "").lower() in _TRUTHY
+
+
+def speak(line: str) -> None:
+    """Emit one line to stderr — only when BELOTE_A11Y is enabled."""
+    if _ENABLED:
+        sys.stderr.write(line + "\n")
+        sys.stderr.flush()
+
+
+# ── Convenience formatters ────────────────────────────────────────────────
+
+
+def _suit_word(suit_symbol: str) -> str:
+    return {
+        "♠": "spades",
+        "♥": "hearts",
+        "♦": "diamonds",
+        "♣": "clubs",
+    }.get(suit_symbol, suit_symbol)
+
+
+def card_word(card: Card) -> str:
+    rank = card.rank.value
+    rank_word = {
+        "7": "seven",
+        "8": "eight",
+        "9": "nine",
+        "10": "ten",
+        "J": "jack",
+        "Q": "queen",
+        "K": "king",
+        "A": "ace",
+    }.get(rank, rank)
+    return f"{rank_word} of {_suit_word(card.suit.symbol)}"
+
+
+def announce_play(seat: Seat, card: Card) -> None:
+    speak(f"{seat.name.lower()} plays {card_word(card)}.")
+
+
+def announce_trick_won(winner: Seat, points: int) -> None:
+    speak(f"{winner.name.lower()} wins the trick worth {points} points.")
+
+
+def announce_round_result(taker_total: int, defender_total: int, taker_team_label: str) -> None:
+    speak(
+        f"round complete. {taker_team_label} taker scores {taker_total}; "
+        f"defenders score {defender_total}."
+    )

belote_cli-3.0.2/src/belote/achievements.py

@@ -0,0 +1,104 @@
+"""3.0.0: lightweight achievement registry for classic Belote.
+
+Achievements are defined statically here, evaluated against the running
+``Statistics`` object after each round/game, and persisted via the existing
+``stats.save_stats()`` path. BelAtro has its own unlock system in
+``progression/save.py``; this module is for the classic mode only.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from .stats import Statistics
+
+
+@dataclass(frozen=True)
+class Achievement:
+    id: str
+    title: str
+    description: str
+
+
+# Catalog. New achievements: add a row here AND a check in
+# `evaluate_round` / `evaluate_game`. IDs are stable strings — never rename.
+ACHIEVEMENTS: tuple[Achievement, ...] = (
+    Achievement(
+        "first_capot",
+        "Le Grand Chelem",
+        "Score your first Capot.",
+    ),
+    Achievement(
+        "capot_x3",
+        "Triple Coup",
+        "Score 3 Capots in a single session.",
+    ),
+    Achievement(
+        "capot_streak_2",
+        "Vague de Capots",
+        "Capot two rounds in a row.",
+    ),
+    Achievement(
+        "high_round_300",
+        "Cartes Pleines",
+        "Score 300+ points in a single round (declarations + Capot).",
+    ),
+    Achievement(
+        "win_hard",
+        "Le Maître",
+        "Win a game on Hard difficulty.",
+    ),
+    Achievement(
+        "ten_games_played",
+        "Habitué",
+        "Play 10 games.",
+    ),
+)
+
+
+def evaluate_round(stats: Statistics, *, points_scored: int, was_capot: bool) -> list[Achievement]:
+    """Check post-round triggers; return list of newly unlocked achievements.
+
+    Mutates ``stats.achievements`` to record unlocks.
+    """
+    newly: list[Achievement] = []
+
+    def _try(aid: str) -> None:
+        if stats.unlock_achievement(aid):
+            for a in ACHIEVEMENTS:
+                if a.id == aid:
+                    newly.append(a)
+                    break
+
+    if was_capot:
+        if stats.capots_achieved == 1:
+            _try("first_capot")
+        if stats.capots_achieved >= 3:
+            _try("capot_x3")
+        if stats.current_capot_streak >= 2:
+            _try("capot_streak_2")
+
+    if points_scored >= 300:
+        _try("high_round_300")
+
+    return newly
+
+
+def evaluate_game(
+    stats: Statistics, *, won: bool, difficulty: str
+) -> list[Achievement]:
+    newly: list[Achievement] = []
+
+    def _try(aid: str) -> None:
+        if stats.unlock_achievement(aid):
+            for a in ACHIEVEMENTS:
+                if a.id == aid:
+                    newly.append(a)
+                    break
+
+    if won and difficulty == "hard":
+        _try("win_hard")
+    if stats.games_played >= 10:
+        _try("ten_games_played")
+
+    return newly