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

{belote_cli-2.9.5 → 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.5 → belote_cli-3.0.2}/CHANGELOG.md

@@ -5,6 +5,107 @@ 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.

{belote_cli-2.9.5 → 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.5 → belote_cli-3.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: belote-cli
-Version: 2.9.5
+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! 
 
@@ -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.5 → 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! 
 
@@ -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.5 → belote_cli-3.0.2}/pyproject.toml

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

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

@@ -1,3 +1,3 @@
-__version__ = "2.9.5"
+__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

{belote_cli-2.9.5 → belote_cli-3.0.2}/src/belote/ai.py

@@ -35,6 +35,9 @@ class AIMemory:
         self.known_voids: dict[Seat, set[Suit]] = {s: set() for s in Seat}
         self.partner_hand: set[Card] = set()
         self.processed_tricks_count: int = 0
+        # (completed_count, current_trick_len) of the last _update_voids call.
+        # Lets us skip re-scanning a stable transient trick on each decision.
+        self.last_voids_key: tuple[int, int] | None = None
 
 
 class AIPlayer:
@@ -50,12 +53,16 @@ class AIPlayer:
     def update_memory(self, state: GameState) -> None:
         """Update memory with currently visible information."""
         if len(state.completed_tricks) == 0 and len(state.current_trick) == 0:
-            # New round - reset memory
+            # New round - reset memory. Including the void-cache key — without
+            # this a (0, 0) / (0, 1) key from the first decision of *this* round
+            # could coincidentally match a leftover from the previous round and
+            # cause _update_voids to skip processing entirely.
             self.memory.played.clear()
             for s in Seat:
                 self.memory.known_voids[s].clear()
             self.memory.partner_hand.clear()
             self.memory.processed_tricks_count = 0
+            self.memory.last_voids_key = None
 
         # Track all cards in completed tricks
         for trick in state.completed_tricks:
@@ -123,11 +130,15 @@ class AIPlayer:
         - Medium: weighted sum + personality jitter.
         - Hard: card-points-based + Jack/Ace bonuses.
         """
+        # The three special-bid heuristics each need a per-suit length count.
+        # Compute once and thread through; recomputing inside every branch
+        # was a measurable redundancy noted in the May-2026 perf audit.
+        lengths = self._suit_lengths(hand)
         if self.difficulty == Difficulty.EASY:
-            return self._easy_special(hand)
+            return self._easy_special(hand, lengths)
         if self.difficulty == Difficulty.MEDIUM:
-            return self._medium_special(hand, state)
-        return self._hard_special(hand, state)
+            return self._medium_special(hand, state, lengths)
+        return self._hard_special(hand, state, lengths)
 
     @staticmethod
     def _suit_lengths(hand: tuple[Card, ...]) -> dict[Suit, int]:
@@ -139,7 +150,9 @@ class AIPlayer:
                 lengths[c.suit] += 1
         return lengths
 
-    def _easy_special(self, hand: tuple[Card, ...]) -> BidValue:
+    def _easy_special(
+        self, hand: tuple[Card, ...], lengths: dict[Suit, int]
+    ) -> BidValue:
         """Pick the contract that best fits the hand shape:
         - Tout Atout if Jack-heavy (≥3 Jacks/9s across ≥3 suits) — Jacks are
           the dominant card under TA in every suit.
@@ -153,12 +166,13 @@ class AIPlayer:
             return Suit.TOUT_ATOUT
 
         ace_ten_count = sum(1 for c in hand if c.rank in (Rank.ACE, Rank.TEN))
-        lengths = self._suit_lengths(hand)
         if ace_ten_count >= 3 and max(lengths.values(), default=0) <= 3:
             return SANS_ATOUT_BID
         return None
 
-    def _medium_special(self, hand: tuple[Card, ...], state: GameState) -> BidValue:
+    def _medium_special(
+        self, hand: tuple[Card, ...], state: GameState, lengths: dict[Suit, int]
+    ) -> BidValue:
         """Weighted score: TA leans on Jacks (each acts like a trump master in
         its own suit), SA leans on Aces and 10s with a flat-distribution bonus."""
         personality = self._rng.uniform(-0.5, 0.5)
@@ -173,7 +187,6 @@ class AIPlayer:
         # SA score: Aces and 10s win lead-suit tricks; flat distribution helps.
         sa_weights = {Rank.ACE: 3.0, Rank.TEN: 2.0, Rank.KING: 1.0}
         sa_score = sum(sa_weights.get(c.rank, 0.0) for c in hand)
-        lengths = self._suit_lengths(hand)
         if max(lengths.values(), default=0) <= 3 and min(lengths.values(), default=8) >= 1:
             sa_score += 1.5  # flat-distribution bonus
 
@@ -188,7 +201,9 @@ class AIPlayer:
             return SANS_ATOUT_BID
         return None
 
-    def _hard_special(self, hand: tuple[Card, ...], state: GameState) -> BidValue:
+    def _hard_special(
+        self, hand: tuple[Card, ...], state: GameState, lengths: dict[Suit, int]
+    ) -> BidValue:
         """Use actual card_points scales as the heuristic.
 
         TA: every card scores on the trump scale; threshold against the average
@@ -203,7 +218,6 @@ class AIPlayer:
             card_points_fn(c, None) for c in hand  # type: ignore[arg-type, misc]
         )
         # Long suits are bad under SA — opponents won't follow your suit.
-        lengths = self._suit_lengths(hand)
         long_suit_penalty = sum(max(0, n - 3) ** 2 for n in lengths.values()) * 4
         sa_score = sa_pts - long_suit_penalty
 
@@ -624,20 +638,40 @@ class AIPlayer:
 
     def _update_voids(self, state: GameState) -> None:
         """Infer voids incrementally."""
+        # Skip the work if neither the completed-count nor the current-trick
+        # length has changed since last call (decide_card may run multiple
+        # times for the same trick during e.g. lookahead exploration).
+        completed_count = len(state.completed_tricks)
+        key = (completed_count, len(state.current_trick))
+        if self.memory.last_voids_key == key:
+            return
+
+        # Le Républicain (or any deck/voucher that sets the flag): 7s and 8s
+        # are wild and may be played on any suit, so an off-suit 7/8 doesn't
+        # prove void in lead suit.
+        wild_active = bool(state._joker_state.get("republicain_wild"))
+
         # 1. Process new completed tricks
-        while self.memory.processed_tricks_count < len(state.completed_tricks):
+        while self.memory.processed_tricks_count < completed_count:
             trick = state.completed_tricks[self.memory.processed_tricks_count]
-            self._process_trick_voids(trick)
+            self._process_trick_voids(trick, wild_active)
             self.memory.processed_tricks_count += 1
 
         # 2. Process current trick (transient, so we don't increment processed_tricks_count)
-        self._process_trick_voids(state.current_trick)
+        self._process_trick_voids(state.current_trick, wild_active)
+        self.memory.last_voids_key = key
 
-    def _process_trick_voids(self, trick: tuple[TrickCard, ...]) -> None:
+    def _process_trick_voids(
+        self, trick: tuple[TrickCard, ...], wild_active: bool = False
+    ) -> None:
         """Analyze a trick for voids."""
         if len(trick) < 2:
             return
         lead_suit = trick[0].card.suit
         for tc in trick[1:]:
             if tc.card.suit != lead_suit:
+                # Under republicain_wild a 7 or 8 may be played on any suit,
+                # so an off-suit 7/8 doesn't prove void in the lead suit.
+                if wild_active and tc.card.rank in (Rank.SEVEN, Rank.EIGHT):
+                    continue
                 self.memory.known_voids[tc.seat].add(lead_suit)