belote-cli 3.8.2__tar.gz → 3.9.3__tar.gz

{belote_cli-3.8.2 → belote_cli-3.9.3}/CHANGELOG.md

@@ -5,6 +5,99 @@ 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.9.3] - 2026-05-15
+
+Multi-agent audit pass (six Explore agents — three broad-sweep + three targeted deep-dives on AI, scoring edge cases, per-joker mechanics, endless mode, meta-progression). Every load-bearing finding verified against the live code before patching; **8 false positives** caught and documented (corrupted-joker seat semantics being intentional, ToutStreak persistence working correctly via `card_enhancements`, `_card_back` LRU cache being theme-keyed, etc.). **Six real fixes (R1–R7)** landed plus three larger phases: render-diff layer, endless-mode boss-variety guard, and a Quinte Royale unlock that had been marked `is_unlockable` for releases without a trigger. **Rematch entirely removed** at user request — game-over screen keeps only `[Enter/Q] Menu` and `[H] History`; players who want to play again use the menu. **+30 regression tests** (661 → 691).
+
+### Fixed
+
+- **`src/belote/ai.py::_hard_special` + `_hard_bid` (R1, MED) — AI bidding now honors zero-rank boss flags.** Pre-3.9.3 the heuristic summed raw `card_points` even when `jacks_zero` / `aces_zero` / `kings_zero` / `tens_zero` / `ban_clubs` were active, so the AI overbid Tout Atout on a jack-heavy hand under Le Sauvage even though those jacks would score 0. The fix routes evaluation through the new public `scoring.card_points_with_modifiers(card, trump, bm)` helper (a thin wrapper over the existing `_card_points_with_zero_ranks` — same canonical zero-rank logic the live HUD and final scoring use). Honor-counting in the regular-suit branch also drops a rank if its boss flag is active. Regression: `tests/test_ai.py::test_hard_ai_does_not_bid_ta_when_jacks_zero_suppresses_jacks`.
+- **`src/belote/game.py::_record_belote_announcement` + new `GameState.belote_trump` field (R2, LOW) — L'Anarchie preserves rebelote across mid-belote trump rotation.** When trump rotates after trick 2/4/6 (`dynamic_trump`), a K-trump played in trick 2 and Q-of-original-trump in trick 3 would silently drop the rebelote because the K/Q match used `card.suit == current_trump`. The fix captures the trump at first-belote into a new `belote_trump: Suit | None` GameState field (mirrors the existing `belote_announcer` pattern) and matches the rebelote K/Q against the captured suit. Regression: `tests/test_belote.py::test_anarchie_rebelote_survives_cross_rotation_play` + non-rotation sanity test.
+- **`src/belote/belatro/ui/hud.py::BelAtroHUD.render` + `_render_compact` (R3, LOW) — HUD score line gated under La Compétition boss.** The live running total (sequential trick-point sum) diverges from the final score under `separate_scoring` (which picks per-seat max). The HUD now shows a "Compétition: score par siège — total final caché" disclaimer instead of a misleading running total when this boss is active.
+- **`src/belote/belatro/items/jokers/economy.py::LeBanquier` (R4, LOW) — bonus cash now suppressed on failed rounds and on EW-taker rounds.** Description says "Earn $1 for every 10 card points you score above the Blind target"; that framing presumes NS held a successful contract. Pre-3.9.3 the joker paid out unconditionally — even on chute, even when EW was taker. Now gates on `not breakdown.is_failed and taker_seat in (SOUTH, NORTH)`. Other on-round-end jokers (LAvare, LeFantome, LaSentinelle, LAccumulateur, LaSentinelleP) were audited and intentionally remain ungated — their descriptions are state-based (cards in hand, jack never used to win, etc.), not win-conditional.
+
+### Changed
+
+- **`src/belote/belatro/items/base.py::Voucher` + `belatro/items/vouchers.py` + `belatro/run/shop.py` (R5) — voucher idempotency guard relocated from `Shop._apply_item` into the `Voucher` base class.** Subclasses now implement `_apply_once(run)`; the base's `apply(run)` consults `run._applied_voucher_ids` and short-circuits a second invocation. Any future caller (replay reconstruction, deck-builder preview, hypothetical save/load) inherits the same protection automatically — pre-3.9.3 the guard only fired when the shop was the call site, so a different caller would silently double-stack `+=` vouchers (LaTelescope, LaDoubleDonne, LesCartesDorees, LeCouteau). Regression: `tests/belatro/test_voucher_idempotency.py::test_direct_voucher_apply_is_idempotent_without_shop`.
+- **`src/belote/belatro/ui/hud.py` (R7) — every bare `print()` call batched into one `sys.stdout.write` + `flush`** per render entry point (`render`, `_render_compact`, `render_joker_pip_strip`, `render_synergy_tooltip`). ~9 fewer syscalls per BelAtro HUD frame. Mirrors the canonical `render.py:1002` pattern.
+- **`src/belote/ai.py:627` (R6) — comment fix.** Said "prefer keeping high value cards if not winning" but the code adds points to the play-score (i.e. biases toward *playing* high cards). Rewritten as "Small per-card tiebreaker: when win/loss heuristics are otherwise equal, slightly bias toward playing the higher-value card."
+
+### Added
+
+- **`src/belote/ui/render.py` (Phase 6) — diff-based render emit.** `display()` now compares each frame's per-row line list against the previously committed frame and writes only the rows that actually changed. Idle re-renders (polling input between keystrokes, hovering on a card without moving) collapse from ~28 row writes to zero. New module-level `_last_emitted_lines` baseline; reset on layout change (via the existing `_last_render_key` invalidation), theme change (via the existing `theme_manager.register_callback(clear_card_cache)` callback — `clear_card_cache` now also clears `_card_back` LRU + the diff baseline), and explicit `display(state, force=True)`. Escape hatch: `BELOTE_NO_DIFF=1`. The full `render()` string contract is unchanged — tests calling `render(state)` directly still get the complete frame. Regression: `tests/test_render_diff.py` (6 tests).
+- **`src/belote/scoring.py::card_points_with_modifiers` (public)** — thin wrapper exposing the existing `_card_points_with_zero_ranks` for callers outside `scoring.py` (notably `ai.py` for R1).
+- **`src/belote/game.py::GameState.belote_trump: Suit | None`** — new field set when `belote_tracker[0]` first flips True, read by the rebelote check (R2).
+- **`src/belote/belatro/core/run_state.py::BelAtroRun._recent_boss_ids: list[str]` (Phase 5) — endless-mode boss variety guard.** The boss selector in `belatro/main.py` now suppresses immediate boss repeats in endless by rerolling against the last-2 window (capped at 8 reroll attempts to never loop on degenerate pools / monkeypatched single-boss tests). Normal-run boss selection is unchanged — variety is only enforced when `run.endless` is True. Regression: `tests/belatro/test_endless.py::test_recent_boss_window_is_bounded_to_two`.
+- **`src/belote/belatro/progression/unlocks.py::UnlockTracker._handle_declaration` (Phase 8) — Quinte Royale now unlocks on a Quinte announcement.** The Legendary joker was marked `is_unlockable = True` in `annonces.py:71` for several releases but had no path to actually unlock — `_handle_round_end` never set the flag, so the joker was filtered out of every shop pool. `UnlockTracker.on_event` now also dispatches `DeclarationScoredEvent`; when NS announces a sequence ≥ 100 pts, `quinte_royale` unlocks and the pending-announcement banner fires. Regression: `tests/belatro/test_progression.py::test_quinte_declaration_unlocks_quinte_royale` + negative tests (short sequence / opponent quinte).
+- **`src/belote/gameflow.py::_undo_pop_to_south` + visible undo banner (Phase 7b user request).** Pressing `Z` previously popped one history-stack entry — but the stack records *every* play including AI moves, so a Z after the AI finished a trick landed on an AI mid-trick state, and the AI re-played deterministically with no visible effect. The new helper pops until the restored state has `turn == SOUTH` (the user's actual prior decision point), bounded by `stack_base` so undo can't cross round boundaries. After each successful pop, `announce("↶ Undo", duration=0.8, reader=reader)` paints a 0.8 s banner before the rolled-back position is redrawn so the player sees the undo take effect. Same UX applied to the bidding-undo path. Regression: `tests/test_undo.py::test_undo_pop_to_south_skips_intermediate_ai_states` + 2 boundary tests.
+
+### Removed
+
+- **Rematch feature (user request).** `src/belote/main.py` no longer offers `[R] Rematch` on the game-over screen; the only post-game choices are `[Enter/Q] Menu` and `[H] History`. The `rematch` variable, the conditional-menu-skip flag, and the dedicated reset path are all gone. `src/belote/ui/prompts.py::show_help` line `"[R] Rematch (Game Over)"` deleted.
+
+### Audit verdict — verified clean, false positives caught
+
+Six Explore agents flagged a number of "critical" issues that were verified against the actual code and rejected:
+
+1. **Corrupted jokers (Le Traître / Le Démon / L'Égoïste / L'Agent Double) using `event.winner == Seat.SOUTH` instead of team scope** — intentional design. The class names and descriptions ("partner is irrelevant", "partner plays for opponents", "partner throws one trick per round") explicitly mark these as themed sabotage jokers. South-only is the design contract.
+2. **Tout Streak streak persistence at `main.py:367-369` being "dead code"** — false. Verified at `round_driver.py:121-123`: `card_enhancements` is merged into `state._joker_state` at the start of every round, so the persisted `tout_streak_streak` flows back in. The persistence works.
+3. **`_card_back` LRU cache going stale on theme change** — false. The cache is keyed by `theme_name` so a new theme produces a new key and a fresh render; old entries are LRU-evicted naturally. (3.9.3 still adds `_card_back.cache_clear()` to `clear_card_cache()` for memory hygiene since the diff-layer change now invalidates the frame baseline on theme change too — but the original "stale render" concern was wrong.)
+4. **Negative-edition jokers "bypassing" the slot check** — intentional. `_can_accept` at `shop.py:152-154` returns True for Negative jokers by design; that's the whole point of the Negative edition.
+5. **The Sun (Tout Atout) planet firing regardless of taker** — false. The parent block at `belatro/core/scoring.py:198+` gates on `event.winner in _NS_TEAM` already.
+6. **BelAtro HUD `print()` calls causing "torn frames"** — theoretical only. Python stdout is single-threaded line-buffered; a bare `print()` is atomic per call in a TTY. We batched anyway (R7) as a micro-perf win, but there was no visual bug.
+7. **L'Anarchie rebelote always broken** — partially false. Within the standard sequence (K then Q in the same trick or in trick 1+2 before the first rotation), rebelote already worked. Only the cross-rotation case was real (fixed as R2).
+8. **`clear_card_cache()` being "incomplete"** — cosmetic at worst. Both LRU caches are theme-keyed, so staleness is impossible.
+
+The "fake risky" agent finding (jokers in `risky.py` / `shaper.py` needing `is_failed` gates) cited files that don't exist — the real joker files are `annonces` / `coinche` / `contract` / `corrupted` / `economy` / `hand_comp` / `trick_timing` + `partner_jokers/{passive,shaper}`. Audit re-done against the actual files; only LeBanquier needed gating (R4).
+
+### Performance verdict
+
+- Benchmark smoke: 203–235 rounds/sec end-to-end (was 235 pre-3.9.3; well within budget, variance is system load).
+- New render diff layer: idle re-render byte count drops to < 25% of the first frame (regression test pins this).
+- No measured hotspot in scoring, AI decision, or trick-play paths. The 3.6 / 3.7.1 / 3.8.0 audits already covered the obvious cost centers.
+
+### Internal
+
+- **Tests**: 661 → 691 (+30). R1 (×1), R2 (×2), R4 (×3), R5 (×2), Phase 6 (×6), Phase 5 (×6), Phase 7b (×3), Phase 8 (×7).
+- **Strict gates**: pytest 691/691 green; benchmark smoke green.
+- **Version markers bumped**: `pyproject.toml`, `src/belote/__init__.py`.
+- **Plan file**: `/home/mrrobot/.claude/plans/bug-hunt-code-performance-mutable-blanket.md`.
+
+
+## [3.9.0] - 2026-05-14
+
+Comprehensive bug-hunt, logic, and performance audit pass. Three parallel Explore agents covered the classic engine (`game.py` / `scoring.py` / `ai.py` / `gameflow.py` / `deck.py`), the BelAtro engine (`round_driver.py` / `modifier_patch.py` / `event_bus.py` / `belatro/core/scoring.py` / `boss.py` / `run_state.py` / `shop.py` / `belatro/main.py`), and the items catalogue + UI hot paths (`registry.py` + every joker / planet / tarot / voucher + `render.py` / `hud.py` / shop UI). Every load-bearing claim was spot-checked against the current code. **One real bug** (LOW), **one feature gap** filled, and a defensive cosmetic cleanup. Performance verdict: no measured hotspot — prior 3.6 / 3.7.1 / 3.8.0 audits already addressed the obvious paths. All 21 boss modifiers, 36 jokers, 8 planets, 12 tarots, 12 vouchers verified wired end-to-end. **+6 regression tests** (655 → 661). Plan file at `/home/mrrobot/.claude/plans/bug-hunt-code-performance-wise-puzzle.md`.
+
+### Fixed
+
+- **`src/belote/belatro/ui/announce.py:98` (LOW) — `BelAtroAnnounce.yes_no()` no longer hangs on `Key.EOF`.** Pre-3.9.0 the prompt loop exited on `Key.ENTER`, `Key.ESC`, `Key.QUIT`, or character `y`/`n`/`o`, but had no `Key.EOF` return path. Two call sites in `belatro/main.py` (the post-Ante-8 endless prompt at line 137 and the player-side surcoinche prompt at line 267) would hang the process on Ctrl-D / piped-empty stdin / closed terminal. Established inconsistency: sibling `banner()` (line 75) and `score_popup()` (line 126) in the same file already handled EOF. Regression test in `tests/test_input_eof.py::test_announce_yes_no_returns_false_on_eof`.
+
+### Added
+
+- **`src/belote/ansi.py` — `NO_COLOR` env-var support** per the [no-color.org](https://no-color.org/) spec. When `NO_COLOR` is set to any non-empty value, `fg()` / `bg()` return the empty string. SGR formatting (`BOLD`, `DIM`, `REVERSE`, `UNDERLINE`, `STRIKETHROUGH`, `RESET`) and cursor/clear sequences are unchanged — they aren't color. Read once at import (mirrors `a11y._ENABLED`); `_refresh_no_color_from_env()` exported for tests. 4 new tests in `tests/test_no_color.py`.
+- **`scripts/benchmark.py::benchmark_belatro_round` (new)** — end-to-end `drive_round` rounds/sec probe under a deterministic seed (mean + p95 + rounds/sec). Regression sentinel for round-driver throughput. New `--smoke` flag runs every benchmark at iterations=2 for a fast CI-friendly check; pinned by `tests/test_benchmark_smoke.py`.
+
+### Changed
+
+- **`src/belote/scoring.py::resolve_declarations` (cosmetic)** — the 4-seat announce-order tuple (clockwise from taker) is now built once in the enclosing function and shared by `_resolve_tie_carre` and `_resolve_tie_seq` via closure. Pre-3.9.0 each helper rebuilt the same tuple inline. Behavior-preserving; the regression guard is the existing `tests/test_declaration_tiebreak.py` suite.
+- **`scripts/benchmark.py` cleanup** — auto-fixed 17 long-standing ruff issues (W293/W291/I001/F401) in the file as part of the enhancement-pass scope.
+
+### Audit verdict — verified clean, no fix needed
+
+- **Classic engine** (game.py / scoring.py / ai.py / gameflow.py / deck.py): all 19 game mechanics wired end-to-end (bidding pass/normal/TA/SA/coinche/surcoinche, trump-play follow/trump/overtrump/partner-master exception, declarations + tie-break, belote/rebelote, contract-aware Capot 220/348/252, Dix-de-der, litige, taker-failed redistribution). AI memoization (`processed_tricks_count` / `last_voids_key` / `last_partner_hand_key`) resets correctly on both new-round and undo paths.
+- **BelAtro engine**: all 21 boss modifiers patch → state → read end-to-end; no `boss.id == "…"` string branching anywhere; event bus correctly round-scoped; `ScoreAccumulator.update_state` already coalesces into one `replace()` per event; voucher idempotency guard live; endless mode (×2.2) scaling correct.
+- **Items + UI**: all 36 jokers' `on_event` signatures match bus dispatch; team-not-seat convention applied correctly (jokers checking "did our team win" use `team_of(event.winner) == 0`, partner jokers deliberately key on `Seat.NORTH`). Theme cache invalidates on theme change; `_card_face` and `visible_len` both `lru_cache(4096)` with proper invalidation; HUD opt-in rebuild via `force_hud=False` since 3.8.0. Shop layout: card frame 16 cells, gap 2→1→0 degradation works.
+
+### Performance verdict
+
+No measured hotspot. `dataclasses.replace()` on the frozen `GameState` runs ~256 calls/round at sub-µs each — well under the 1 ms/round budget. Joker triggers linear-scan over ≤ 5 jokers (max slots). The "enhancement plan" here is the regression sentinel (`benchmark_belatro_round`), not a speculative rewrite.
+
+### Internal
+
+- **Tests**: 655 → 661 (+6). yes_no EOF ×1, NO_COLOR ×4, benchmark smoke ×1.
+- **Strict gates**: pytest 661/661 green, mypy `--strict` 0 errors (77 files), ruff 0 violations.
+- **Version markers bumped**: `pyproject.toml`, `src/belote/__init__.py`.
+
 ## [3.8.2] - 2026-05-14
 
 Final logic audit and performance hardening. This release addresses the remaining edge cases identified during the deep-dive audit, focusing on BelAtro joker persistence, declaration scoring correctness, and test suite optimization. All 655 tests passing.

{belote_cli-3.8.2 → belote_cli-3.9.3}/DEVELOPMENT.md

@@ -84,14 +84,27 @@ PYTHONPATH=src mypy --strict src/
 # Linting (0 violations expected)
 ruff check src/ tests/
 
-# Full test suite (655 tests expected)
+# Full test suite (691 tests expected)
 PYTHONPATH=src pytest
 ```
 
-Current baseline (3.8.1):
-Current baseline (3.8.2):
+Current baseline (3.9.3):
+
+- **691 tests** passing (3.9.0 had 661; +30 in 3.9.3 across R1/R2/R4/R5 regressions + 3 new test files: `test_render_diff.py`, `test_endless.py`, expanded `test_progression.py` / `test_undo.py` / `test_voucher_idempotency.py` / `test_phase2_content.py`).
+- 3.9.3 ships a multi-agent audit pass (six Explore agents — three broad-sweep + three targeted deep-dives on AI, scoring edge cases, per-joker mechanics, endless mode, meta-progression). **8 false positives caught and documented** (corrupted-joker seat semantics intentional, ToutStreak persistence working via `card_enhancements`, `_card_back` LRU theme-keyed, etc.). **Six real fixes (R1–R7)** plus three larger phases (render-diff layer, endless boss-variety guard, Quinte Royale unlock). **Rematch removed** at user request — game-over screen now `[Enter/Q] Menu  [H] History` only. Headline changes:
+  - **R1 — AI bidding zero-rank awareness** (`src/belote/ai.py::_hard_special` / `_hard_bid`): new public `scoring.card_points_with_modifiers(card, trump, bm)` helper threads the same canonical zero-rank logic the live HUD uses into the AI's bid evaluation; AI no longer overbids Tout Atout on jack-heavy hands under Le Sauvage. Honor-counting in regular-suit branch also boss-aware.
+  - **R2 — L'Anarchie rebelote preservation** (`src/belote/game.py:919-920` + new `GameState.belote_trump: Suit | None` field): rebelote check matches against the captured belote trump, not `state.trump`, so a K-trump in trick 2 + Q in trick 3 still fires rebelote across the post-trick-2 rotation.
+  - **R5 — voucher idempotency relocated to `Voucher.apply()`** (`src/belote/belatro/items/base.py`): subclasses now implement `_apply_once(run)`; the base wrapper consults `run._applied_voucher_ids` so any future caller (replay, save/load) gets idempotency, not just the shop.
+  - **Phase 6 — diff-based render emit** (`src/belote/ui/render.py::display`): idle re-renders drop from ~28 row writes to zero by diffing the post-vcenter line list against `_last_emitted_lines`. Layout/theme changes invalidate the baseline automatically. `BELOTE_NO_DIFF=1` escape hatch.
+  - **Phase 5 — endless boss-variety guard** (`belatro/main.py:285+`): in endless, reroll if the picked boss is in the last-2 window (`run._recent_boss_ids`).
+  - **Phase 7b — undo improvements** (`gameflow.py::_undo_pop_to_south`): `Z` now pops past AI snapshots to the player's actual prior decision point and displays a 0.8 s "↶ Undo" banner so the action is visible.
+  - **Phase 8 — Quinte Royale unlock** (`belatro/progression/unlocks.py::_handle_declaration`): the Legendary joker was marked `is_unlockable` but had no path to actually unlock; `UnlockTracker.on_event` now dispatches `DeclarationScoredEvent` and grants on NS sequence ≥ 100 pts.
+  Performance verdict: 203–235 rounds/sec end-to-end (unchanged); render-diff idle byte count < 25% of full frame. Plan file at `/home/mrrobot/.claude/plans/bug-hunt-code-performance-mutable-blanket.md`.
+
+Past baselines:
+
+- 3.9.0 shipped a clean three-agent audit pass (classic engine / BelAtro engine / items+UI). One LOW bug — `BelAtroAnnounce.yes_no()` hung on `Key.EOF`. Added `NO_COLOR` env-var support and the `--smoke` benchmark flag. Plan file at `/home/mrrobot/.claude/plans/bug-hunt-code-performance-wise-puzzle.md`.
 
-- **655 tests** passing.
 - 3.8.2 completes the five-agent audit pass. Final hardening includes Tout Atout streak persistence in BelAtro, Quinte trigger refinement, belote-pair timing fixes for jokers, and declaration scoring correctness for carrés and long sequences.
 - Performance: test suite speed increased by mocking `interruptible_sleep`.
 - Regression coverage maintained at 100% for game-logic modules.
@@ -162,6 +175,10 @@ once at startup; toggling mid-run has no effect.
   `~/.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`.
+- `NO_COLOR=<any-non-empty>` — suppress truecolor SGR escapes from
+  `fg()` / `bg()` per the [no-color.org](https://no-color.org/) spec.
+  Bold/dim/underline/reverse/strikethrough and cursor sequences remain
+  (they aren't color). Added in 3.9.0. Backed by `src/belote/ansi.py`.
 
 ## Releasing a New Version
 

{belote_cli-3.8.2 → belote_cli-3.9.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: belote-cli
-Version: 3.8.2
+Version: 3.9.3
 Summary: A 4-player terminal card game
 Project-URL: Homepage, https://github.com/ElysiumDisc/belote
 Project-URL: Repository, https://github.com/ElysiumDisc/belote
@@ -215,7 +215,7 @@ belote --difficulty hard --target 500 --seed 123 --speed fast
 - **Alternate Screen Buffer:** Both classic Belote and BelAtro run in a dedicated terminal buffer for a clean, non-overlapping interface — your shell scrollback stays untouched after you quit.
 - **Declarations:** Automatic detection and announcement of sequences (Tierce, Quarte, etc.) and Carrés after the first trick.
 - **Live HUD:** Real-time round scoring displays points won during the current round, with a smooth "rolling" numerical animation for total scores.
-- **High Fidelity:** Implementation of French Belote rules according to the [official rules of the Fédération Française de Belote](https://www.ffbelote.org/regles-officielle-belote/), including a two-round bidding system, "Dix de Der", "Capot" (252 pts), and "Litige" (tie-break). All six contracts are bidable in round 2: the four card suits, **Tout Atout** (every suit acts as trump within its own led-suit group; press `a`), and **Sans Atout** (no trump, lead-suit highest wins; press `s`).
+- **High Fidelity:** Implementation of French Belote rules according to the [official rules of the Fédération Française de Belote](https://www.ffbelote.org/regles-officielle-belote/), including a two-round bidding system, "Dix de Der", contract-aware **Capot** (252 normal / 220 Sans Atout / 348 Tout Atout), and "Litige" (tie-break). All six contracts are bidable in round 2: the four card suits, **Tout Atout** (every suit acts as trump within its own led-suit group; press `a`), and **Sans Atout** (no trump, lead-suit highest wins; press `s`).
 - **Rules & History Viewer:** A scrollable, bilingual (English/French) in-game reference for the game's heritage and mechanics.
 
 ## AI
@@ -254,7 +254,7 @@ belote/
 │   ├── input.py       # Platform-dispatched key reader and interruptible sleep
 │   ├── stats.py       # Global and session statistics tracking
 │   └── rules.py       # Game rules content
-├── tests/             # Comprehensive test suite (655 tests)
+├── tests/             # Comprehensive test suite (691 tests)
 ├── scripts/           # Performance benchmarks
 ├── pyproject.toml      # Build system and dev dependencies (ruff/mypy)
 ├── LICENSE             # MIT License
@@ -270,14 +270,14 @@ belote/
 PYTHONPATH=src pytest
 ```
 
-Currently **655 tests** passing with 100% coverage on game-logic modules (3.8.2).
+Currently **691 tests** passing with 100% coverage on game-logic modules (3.9.3).
 
 ## Technical Integrity
 
 The codebase is strictly validated with the following tools:
 - **mypy**: 0 errors (strict type safety)
 - **ruff**: 0 violations (linting & formatting)
-- **pytest**: 655/655 passed
+- **pytest**: 691/691 passed
 - **Functional Architecture**: Purely immutable state transitions using `dataclasses.replace`
 - **Performance**: High-efficiency rendering and sub-millisecond AI decision times (see `scripts/benchmark.py`)
 

{belote_cli-3.8.2 → belote_cli-3.9.3}/README.md

@@ -172,7 +172,7 @@ belote --difficulty hard --target 500 --seed 123 --speed fast
 - **Alternate Screen Buffer:** Both classic Belote and BelAtro run in a dedicated terminal buffer for a clean, non-overlapping interface — your shell scrollback stays untouched after you quit.
 - **Declarations:** Automatic detection and announcement of sequences (Tierce, Quarte, etc.) and Carrés after the first trick.
 - **Live HUD:** Real-time round scoring displays points won during the current round, with a smooth "rolling" numerical animation for total scores.
-- **High Fidelity:** Implementation of French Belote rules according to the [official rules of the Fédération Française de Belote](https://www.ffbelote.org/regles-officielle-belote/), including a two-round bidding system, "Dix de Der", "Capot" (252 pts), and "Litige" (tie-break). All six contracts are bidable in round 2: the four card suits, **Tout Atout** (every suit acts as trump within its own led-suit group; press `a`), and **Sans Atout** (no trump, lead-suit highest wins; press `s`).
+- **High Fidelity:** Implementation of French Belote rules according to the [official rules of the Fédération Française de Belote](https://www.ffbelote.org/regles-officielle-belote/), including a two-round bidding system, "Dix de Der", contract-aware **Capot** (252 normal / 220 Sans Atout / 348 Tout Atout), and "Litige" (tie-break). All six contracts are bidable in round 2: the four card suits, **Tout Atout** (every suit acts as trump within its own led-suit group; press `a`), and **Sans Atout** (no trump, lead-suit highest wins; press `s`).
 - **Rules & History Viewer:** A scrollable, bilingual (English/French) in-game reference for the game's heritage and mechanics.
 
 ## AI
@@ -211,7 +211,7 @@ belote/
 │   ├── input.py       # Platform-dispatched key reader and interruptible sleep
 │   ├── stats.py       # Global and session statistics tracking
 │   └── rules.py       # Game rules content
-├── tests/             # Comprehensive test suite (655 tests)
+├── tests/             # Comprehensive test suite (691 tests)
 ├── scripts/           # Performance benchmarks
 ├── pyproject.toml      # Build system and dev dependencies (ruff/mypy)
 ├── LICENSE             # MIT License
@@ -227,14 +227,14 @@ belote/
 PYTHONPATH=src pytest
 ```
 
-Currently **655 tests** passing with 100% coverage on game-logic modules (3.8.2).
+Currently **691 tests** passing with 100% coverage on game-logic modules (3.9.3).
 
 ## Technical Integrity
 
 The codebase is strictly validated with the following tools:
 - **mypy**: 0 errors (strict type safety)
 - **ruff**: 0 violations (linting & formatting)
-- **pytest**: 655/655 passed
+- **pytest**: 691/691 passed
 - **Functional Architecture**: Purely immutable state transitions using `dataclasses.replace`
 - **Performance**: High-efficiency rendering and sub-millisecond AI decision times (see `scripts/benchmark.py`)
 

{belote_cli-3.8.2 → belote_cli-3.9.3}/pyproject.toml

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

{belote_cli-3.8.2 → belote_cli-3.9.3}/scripts/benchmark.py

@@ -68,17 +68,16 @@ def benchmark_ai(difficulty: Difficulty, iterations: int = 50) -> float:
 
 def benchmark_belatro_bus(num_jokers: int = 5, iterations: int = 1000) -> float:
     from belote.belatro.core.scoring import ScoreAccumulator
-    from belote.belatro.engine.event_bus import EventBus, TrickWonEvent
+    from belote.belatro.engine.event_bus import TrickWonEvent
     from belote.belatro.items.jokers.contract import LeDiplomate
     from belote.deck import Card, Rank
-    from belote.game import GameState
 
     print(f"Benchmarking BelAtro State Update ({num_jokers} Jokers) over {iterations} iterations...")
 
     jokers = [LeDiplomate() for _ in range(num_jokers)]
     acc = ScoreAccumulator()
     acc.attach_jokers(jokers)
-    
+
     state = new_game()
     event = TrickWonEvent(
         winner=Seat.SOUTH,
@@ -102,28 +101,28 @@ def benchmark_belatro_bus(num_jokers: int = 5, iterations: int = 1000) -> float:
 
 
 def benchmark_scoring(iterations: int = 1000) -> float:
-    from belote.scoring import score_round
     from belote.deck import Card, Rank
-    from belote.game import TrickCard, Phase, replace
-    
+    from belote.game import Phase, TrickCard, replace
+    from belote.scoring import score_round
+
     print(f"Benchmarking score_round() over {iterations} iterations...")
-    
+
     state = new_game()
     state = replace(
-        state, 
-        phase=Phase.SCORING, 
-        trump=Suit.SPADES, 
+        state,
+        phase=Phase.SCORING,
+        trump=Suit.SPADES,
         taker=Seat.SOUTH,
         completed_tricks=tuple([(TrickCard(Seat.SOUTH, Card(Suit.SPADES, Rank.ACE)),) * 4] * 8),
         last_trick_winner=Seat.SOUTH
     )
-    
+
     times = []
     for _ in range(iterations):
         start = time.perf_counter()
         _ = score_round(state)
         times.append(time.perf_counter() - start)
-        
+
     avg = statistics.mean(times) * 1000
     print(f"  Scoring Time: {avg:.3f}ms")
     return avg
@@ -132,23 +131,23 @@ def benchmark_scoring(iterations: int = 1000) -> float:
 def benchmark_deal(iterations: int = 1000) -> float:
     from belote.game import start_round
     print(f"Benchmarking start_round() (deal) over {iterations} iterations...")
-    
+
     state = new_game()
     rng = random.Random(42)
-    
+
     times = []
     for _ in range(iterations):
         start = time.perf_counter()
         _ = start_round(state, rng)
         times.append(time.perf_counter() - start)
-        
+
     avg = statistics.mean(times) * 1000
     print(f"  Deal Time: {avg:.3f}ms")
     return avg
 
 
 def benchmark_legal_cards(iterations: int = 1000) -> float:
-    from belote.game import legal_cards, clear_legal_cards_cache, replace
+    from belote.game import clear_legal_cards_cache, legal_cards, replace
     print(f"Benchmarking legal_cards() (cache cleared per call) over {iterations} iterations...")
 
     state = new_game()
@@ -173,7 +172,7 @@ def benchmark_legal_cards_cached(iterations: int = 1000) -> float:
     `benchmark_legal_cards` above invalidates every iteration and so reflects
     worst-case-only time.
     """
-    from belote.game import legal_cards, clear_legal_cards_cache, replace
+    from belote.game import clear_legal_cards_cache, legal_cards, replace
     print(f"Benchmarking legal_cards() (warm cache) over {iterations} iterations...")
 
     state = new_game()
@@ -198,8 +197,8 @@ def benchmark_trick_scoring(iterations: int = 1000) -> float:
     (HUD running total) and again from `scoring.py::_calculate_base_points`
     (final round score). One of the hottest functions in a played round.
     """
-    from belote.game import TrickCard, replace
     from belote.deck import Card, Rank
+    from belote.game import TrickCard, replace
     from belote.scoring import trick_card_points
 
     print(f"Benchmarking trick_card_points() over {iterations} iterations...")
@@ -249,6 +248,55 @@ def benchmark_ai_legality_filter(iterations: int = 500) -> float:
     return avg
 
 
+def benchmark_belatro_round(rounds: int = 30, seed: int = 42) -> float:
+    """End-to-end BelAtro round throughput under a deterministic seed.
+
+    Drives a full round (bid → 8 tricks → score) headlessly via the same
+    round_driver path the game uses, with AI on every seat. The seed is
+    threaded into drive_round so the per-round work is reproducible — a
+    regression sentinel, not a wall-clock target.
+    """
+    from belote.belatro.core.scoring import ScoreAccumulator
+    from belote.belatro.engine.event_bus import EventBus
+    from belote.belatro.engine.round_driver import RoundUICallbacks, drive_round
+    from belote.belatro.partner.partner_state import PartnerState
+    from belote.deck import Card
+    from belote.game import GameState, legal_cards
+
+    class _HeadlessUI(RoundUICallbacks):
+        def prompt_bid(self, state: GameState) -> Suit | None:
+            return None  # pass; AI seats may take
+
+        def prompt_card(self, state: GameState) -> tuple[Card, GameState]:
+            return legal_cards(state, Seat.SOUTH)[0], state
+
+        def on_card_played(self, state: GameState, seat: Seat, card: Card) -> None:
+            pass
+
+        def on_trick_end(self, state: GameState, winner: Seat, points: int) -> None:
+            pass
+
+        def on_round_end(self, breakdown: object) -> None:
+            pass
+
+    print(f"Benchmarking drive_round() E2E over {rounds} rounds (seed={seed})...")
+
+    times = []
+    for i in range(rounds):
+        bus = EventBus()
+        partner = PartnerState()
+        acc = ScoreAccumulator()
+        start = time.perf_counter()
+        drive_round(bus=bus, partner=partner, ui_callbacks=_HeadlessUI(), acc=acc, seed=seed + i)
+        times.append(time.perf_counter() - start)
+
+    mean = statistics.mean(times) * 1000
+    p95 = sorted(times)[int(len(times) * 0.95) - 1] * 1000 if len(times) > 1 else mean
+    rps = 1.0 / statistics.mean(times) if times else 0.0
+    print(f"  E2E Round Time: mean {mean:.2f}ms, p95 {p95:.2f}ms ({rps:.1f} rounds/sec)")
+    return mean
+
+
 def run_benchmarks() -> None:
     print("=== Belote-CLI Performance Benchmark ===")
     benchmark_render()
@@ -265,9 +313,29 @@ def run_benchmarks() -> None:
     benchmark_legal_cards_cached()
     benchmark_trick_scoring()
     benchmark_ai_legality_filter()
+    print()
+    benchmark_belatro_round()
     print("========================================")
 
 
+def run_smoke() -> None:
+    """Tiny smoke pass: every benchmark runs once at minimum iteration count.
+    Used by the test suite to keep the script from rotting.
+    """
+    benchmark_render(iterations=2)
+    benchmark_ai(Difficulty.EASY, iterations=2)
+    benchmark_belatro_bus(iterations=2)
+    benchmark_scoring(iterations=2)
+    benchmark_deal(iterations=2)
+    benchmark_legal_cards(iterations=2)
+    benchmark_legal_cards_cached(iterations=2)
+    benchmark_trick_scoring(iterations=2)
+    benchmark_ai_legality_filter(iterations=2)
+    benchmark_belatro_round(rounds=2)
+
 
 if __name__ == "__main__":
-    run_benchmarks()
+    if "--smoke" in sys.argv:
+        run_smoke()
+    else:
+        run_benchmarks()

{belote_cli-3.8.2 → belote_cli-3.9.3}/src/belote/__init__.py

@@ -1,3 +1,3 @@
-__version__ = "3.8.2"
+__version__ = "3.9.3"
 
 __all__ = ["__version__"]

{belote_cli-3.8.2 → belote_cli-3.9.3}/src/belote/ai.py

@@ -16,6 +16,7 @@ from .game import (
     legal_cards,
     partner,
 )
+from .scoring import card_points_with_modifiers
 
 # trick_rank(Card(trump, Rank.NINE), trump) == 8 + 6 == 14 for any trump
 _NINE_TRUMP_RANK = 14
@@ -249,12 +250,25 @@ class AIPlayer:
         TA: every card scores on the trump scale; threshold against the average
             taker total (~62 raw). Plus a Jack-count bonus.
         SA: every card scores on the non-trump scale; flat-Aces hand favored.
+
+        3.9.3: card values are evaluated through `card_points_with_modifiers`
+        so active zero-rank bosses (jacks_zero / aces_zero / kings_zero /
+        tens_zero / ban_clubs) suppress those ranks in the bid heuristic.
+        Pre-3.9.3 the raw `card_points` totals made the AI overbid TA on a
+        jack-heavy hand under Le Sauvage even though those jacks would score
+        zero in actual play.
         """
-        ta_pts = sum(card_points_fn(c, Suit.TOUT_ATOUT) for c in hand)
-        jack_bonus = sum(1 for c in hand if c.rank == Rank.JACK) * 6  # Jacks dominate TA
+        bm = state.boss_modifiers
+        ta_pts = sum(card_points_with_modifiers(c, Suit.TOUT_ATOUT, bm) for c in hand)
+        # The Jack-count bonus is the AI's TA strength signal — drop it if
+        # jacks are suppressed.
+        jack_bonus = (
+            0 if bm.jacks_zero
+            else sum(1 for c in hand if c.rank == Rank.JACK) * 6
+        )
         ta_score = ta_pts + jack_bonus
 
-        sa_pts = sum(card_points_fn(c, None) for c in hand)
+        sa_pts = sum(card_points_with_modifiers(c, None, bm) for c in hand)
         # Long suits are bad under SA — opponents won't follow your suit.
         long_suit_penalty = sum(max(0, n - 3) ** 2 for n in lengths.values()) * 4
         sa_score = sa_pts - long_suit_penalty
@@ -487,10 +501,19 @@ class AIPlayer:
             if c.suit in suit_cards:
                 suit_cards[c.suit].append(c)
 
+        bm = state.boss_modifiers
         for suit in card_suits:
             trump_cards = suit_cards[suit]
-            honor_count = sum(1 for c in trump_cards if c.rank in (Rank.JACK, Rank.NINE, Rank.ACE))
-            point_total = sum(card_points_fn(c, suit, self._se) for c in trump_cards)
+            # Honors are J/9/A; drop a rank from the count if it's zeroed by a
+            # boss flag (3.9.3 — honor-counting was previously boss-blind).
+            def _is_honor(c: Card) -> bool:
+                if c.rank == Rank.JACK and bm.jacks_zero:
+                    return False
+                if c.rank == Rank.ACE and bm.aces_zero:
+                    return False
+                return c.rank in (Rank.JACK, Rank.NINE, Rank.ACE)
+            honor_count = sum(1 for c in trump_cards if _is_honor(c))
+            point_total = sum(card_points_with_modifiers(c, suit, bm) for c in trump_cards)
 
             suit_scores[suit] = point_total * 0.5 + honor_count * 3
 
@@ -601,7 +624,10 @@ class AIPlayer:
         """Score a card play decision with advanced heuristics."""
         score = 0.0
         points = card_points_fn(card, trump, self._se)
-        # Base: card point value (prefer keeping high value cards if not winning)
+        # Small per-card tiebreaker: when win/loss heuristics are otherwise
+        # equal, slightly bias toward playing the higher-value card. The
+        # 0.1 coefficient keeps this strictly subordinate to the win/loss
+        # bonuses (~+5 to ~-9) below.
         score += points * 0.1
 
         if not trick:

{belote_cli-3.8.2 → belote_cli-3.9.3}/src/belote/ansi.py

@@ -1,10 +1,26 @@
 from __future__ import annotations
 
+import os
 import re
 from functools import lru_cache
 
 from .themes import Theme, theme_manager
 
+# Respect https://no-color.org/. Read once at import; tests use
+# _refresh_no_color_from_env() after monkeypatch.setenv. Only color escapes
+# are suppressed; SGR formatting (BOLD/DIM/etc.) and cursor sequences remain,
+# per the spec.
+_NO_COLOR: bool = bool(os.environ.get("NO_COLOR", ""))
+
+
+def _refresh_no_color_from_env() -> None:
+    global _NO_COLOR
+    _NO_COLOR = bool(os.environ.get("NO_COLOR", ""))
+
+
+def no_color_active() -> bool:
+    return _NO_COLOR
+
 # ── Theme cache ────────────────────────────────────────────────────────────
 # Each color flavor (felt_bg, red_fg, etc.) is hit dozens of times per render.
 # Pre-3.0.0 each call walked into theme_manager.get_current() (a dict lookup);
@@ -58,15 +74,27 @@ def ansi_ljust(s: str, width: int) -> str:
 
 
 @lru_cache(maxsize=512)
-def fg(r: int, g: int, b: int) -> str:
+def _fg_seq(r: int, g: int, b: int) -> str:
     return f"\x1b[38;2;{r};{g};{b}m"
 
 
 @lru_cache(maxsize=512)
-def bg(r: int, g: int, b: int) -> str:
+def _bg_seq(r: int, g: int, b: int) -> str:
     return f"\x1b[48;2;{r};{g};{b}m"
 
 
+def fg(r: int, g: int, b: int) -> str:
+    if _NO_COLOR:
+        return ""
+    return _fg_seq(r, g, b)
+
+
+def bg(r: int, g: int, b: int) -> str:
+    if _NO_COLOR:
+        return ""
+    return _bg_seq(r, g, b)
+
+
 BOLD = "\x1b[1m"
 DIM = "\x1b[2m"
 REVERSE = "\x1b[7m"

{belote_cli-3.8.2 → belote_cli-3.9.3}/src/belote/belatro/core/run_state.py

@@ -99,13 +99,18 @@ class BelAtroRun:
 
     # ── Idempotency guard for voucher.apply() ──────────────
     # Several vouchers (LaTelescope, LaDoubleDonne, LesCartesDorees, LeCouteau)
-    # use `+=` against run-level counters in their `apply()`. Today the only
-    # call site is `Shop.buy_item`, which fires apply() exactly once per
-    # purchase. This set lets the shop short-circuit re-application if a
-    # future save/load path ever re-invokes apply() on a voucher already in
-    # `vouchers` — preventing silent double-stacking.
+    # use `+=` against run-level counters in their `apply()`. The guard now
+    # lives on `Voucher.apply()` (3.9.3 R5) so any caller — shop, replay, a
+    # future save/load round-trip — gets the same protection automatically.
     _applied_voucher_ids: set[str] = field(default_factory=set)
 
+    # ── Recent-boss tracker (3.9.3 Phase 5) ────────────────
+    # Used by the BelAtro main loop to suppress immediate boss repeats in
+    # endless mode. The deque holds at most 2 recent boss ids; the selector
+    # rerolls if its pick is in this window. Empty by default — bounded so
+    # the run-state JSON snapshot stays small.
+    _recent_boss_ids: list[str] = field(default_factory=list)
+
     def consume(self, item: Any, context: object = None) -> None:
         """Centralised consumable activation.
 

{belote_cli-3.8.2 → belote_cli-3.9.3}/src/belote/belatro/items/base.py

@@ -144,6 +144,19 @@ class Tarot(ABC):
 
 
 class Voucher(ABC):
+    """Permanent run-level upgrade.
+
+    Subclasses implement `_apply_once(run)` for the actual effect. The base
+    class wraps it with `apply(run)` which consults `run._applied_voucher_ids`
+    to guarantee a no-op on a second invocation — important for vouchers that
+    use `+=` semantics (LaTelescope's `+=` on joker_slots, LeCouteau's `+=`
+    on consumable_slots, etc.) that would silently double-stack on a future
+    save/load or replay round-trip.
+
+    3.9.3 — guard relocated here from `Shop._apply_item` so any future
+    caller of `voucher.apply()` (replays, deck-builder previews, etc.)
+    inherits the same protection.
+    """
     id: str
     name: str
     description: str
@@ -151,9 +164,16 @@ class Voucher(ABC):
     rarity: Rarity = Rarity.COMMON
     purchased: bool = False
 
-    @abstractmethod
     def apply(self, run: BelAtroRun) -> None:
-        """Apply permanent effect to the run."""
+        """Idempotent wrapper. Calls `_apply_once` only the first time per run."""
+        if self.id in run._applied_voucher_ids:
+            return
+        run._applied_voucher_ids.add(self.id)
+        self._apply_once(run)
+
+    @abstractmethod
+    def _apply_once(self, run: BelAtroRun) -> None:
+        """Subclass-defined permanent effect. Called exactly once per run."""
         ...