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

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

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

belote_cli-3.2.0/AGENT.md

@@ -0,0 +1,12 @@
+You are auditing a Python codebase for bugs.
+
+  Rules:
+  1. Every finding has fields: file:line, claim, evidence, confidence (CONFIRMED|LIKELY|SPECULATIVE), severity.
+  2. CONFIRMED requires citing both the buggy code AND the code that proves the bug (e.g., the missing reader for a "dead
+   flag", the caller that passes the bad input).
+  3. Severity P0/P1 requires CONFIRMED. LIKELY findings max out at P2.
+  4. For any "X is unused/dead/never called" claim: paste `grep -rn "X" .` output. Zero non-test hits required.
+  5. For any "Y crashes" claim: name the input that triggers the crash and the call path that delivers it.
+  6. End the report with a "Findings I considered but rejected" section — at least 3 items. This forces you to
+  demonstrate you tried to falsify.
+  7. Use the tools provided (Read, Grep, Bash). Do not reason from memory about file contents.

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

@@ -5,6 +5,126 @@ 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.2.0] - 2026-05-10
+
+Two-audit reconciliation release — the prioritized fix list distilled from Qwen 3.6 27B + Ring 1T audits (~30 raw claims, ~half held up under verification). Twelve real bugs fixed across joker logic, registry hygiene, RNG determinism, and UI offsets; one new finding (Tarot RNG was also unseeded) caught by the fresh-hunt pass. Eleven audit claims rejected as false positives are catalogued in the plan file so they aren't re-investigated. 528 tests passing (up from 525), ruff and mypy strict still clean.
+
+### Fixed
+
+- **`src/belote/belatro/items/jokers/hand_comp.py::LaSentinelle`** — Detection of the trump Jack now keys on the NS *team* via `team_of(seat) == 0` instead of `seat == Seat.SOUTH`. Pre-3.2 the joker was silently no-op when North (the partner) was dealt the trump Jack, even though Belote's "you" is team-level. Trick-win detection follows the same team rule. Regressions: `tests/belatro/test_dead_flag_fixes.py::test_la_sentinelle_arms_when_partner_plays_trump_jack`, `test_la_sentinelle_does_not_arm_for_opponent_jack`.
+- **`src/belote/belatro/items/jokers/trick_timing.py::LeDernierMot`** — Dix de Der replacement now fires whenever the NS team wins the last trick (`team_of(event.winner) == 0`), not only when South personally takes it. Pre-3.2 the joker silently did nothing when partner won the closing trick. Regressions: `tests/belatro/test_belatro.py::TestLeDernierMot::test_north_last_trick_returns_result`, `test_east_last_trick_returns_none`.
+- **`src/belote/belatro/items/jokers/corrupted.py::LEgoiste` → `src/belote/belatro/core/scoring.py::ScoreAccumulator.get_total`** — Final chip total is now `max(0, state._chips)`. L'Égoïste subtracts `event.card_points` for every partner-won trick; with enough partner wins the running total could cross zero, producing a negative final round score. Clamping at the scoring boundary preserves the intermediate accounting log while guaranteeing the visible score is never negative.
+- **`src/belote/belatro/engine/round_driver.py:236-249`** — NS-taker `auto_coinche` path now re-emits `BidMadeEvent` with the new `coinche_level` so jokers/HUD subscribed to `on_bid` see the bump. The EW-taker branch above always emitted; this NS-side branch silently set `coinche_level = 1` without notifying subscribers.
+- **`src/belote/belatro/core/run_state.py::BelAtroRun.advance_blind`** — Victory now sets both `run_won = True` and `run_over = True`, so downstream callers can rely on `run_over` alone as the terminal-state signal. `enter_endless()` resets both, re-opening the run for endless mode. Pre-3.2 the main loop only terminated via a `break` after a `run_won` check — semantically correct but fragile under refactors.
+- **`src/belote/belatro/items/registry.py::ItemRegistry.register_*`** — All four register methods (`joker` / `planet` / `tarot` / `voucher`) now assert that an existing entry under the same `id` is the *same class*. Pre-3.2 a typo'd duplicate ID would silently overwrite the prior class, and the override would never surface until the original behaviour visibly broke. Idempotent re-registration of the same class still works for the test-suite swap pattern.
+- **`src/belote/belatro/engine/modifier_patch.py`** — `boss_fields` is now derived from `BossModifiers`' dataclass fields via `dataclasses.fields(BossModifiers)` instead of a hardcoded set. Pre-3.2 a new boss flag added to `BossModifiers` would be silently no-op'd until someone remembered to add it to the hardcoded allowlist in lock-step.
+
+### Determinism
+
+- **`src/belote/belatro/run/shop.py::Shop.generate_inventory`** — All RNG calls (`random.random` / `random.choice` / `random.sample` across edition rolls, joker pick, tarot/planet pick, voucher pick) now use `self.run._get_rng()` instead of the module-level `random`. Pre-3.2 shop contents were non-deterministic even with a seeded run, which broke ghost-run reproducibility. `Shop._roll_edition` signature changed to accept an explicit `rng` argument; the `test_shop_edition_weights_match_distribution` test was updated to pass the seeded RNG directly instead of monkey-patching `shop_mod.random.random`.
+- **`src/belote/belatro/items/tarots.py`** — `LeJugement`, `LaPretresse`, and `LeFou` all now draw from `run._get_rng()` instead of the module-level `random`. Module-level `import random` removed.
+
+### Improved
+
+- **`LaPretresse` planet picks now deduplicate** — switched from two independent `random.choice(planets)` calls to `rng.sample(planets, k=2)`, so the tarot can no longer pick the same planet twice. Falls back to a single pick when the planet pool has fewer than 2 entries.
+- **`LeJugement` slot-full notification** — new `BelAtroRun.last_tarot_message: str | None` field carries a non-fatal failure reason ("joker slots are full — no joker granted") when the tarot can't complete. Pre-3.2 the joker was silently dropped with no UI signal. Cleared whenever a tarot is used.
+- **`src/belote/ui/render.py::patch_trick_card`** — Now reads `_last_rendered_unpadded_h` (set by `render()`) and threads it into `_calculate_base_row`, so single-card patches re-apply the same vertical-centering offset `render()` used. Pre-3.2 it passed the "I don't know" sentinel (0) and skipped the offset entirely, drawing cards too high on tall terminals (>40 rows).
+- **`src/belote/ui/layout.py`** — `hud_style` docstring corrected. Pre-3.2 it claimed `"verbose" / "standard" / "compact"`, but no preset used `"standard"` and no consumer recognized it — only `"verbose"` and `"compact"` are real.
+
+### Rejected (catalogued so they aren't re-investigated)
+
+Eleven claims from the input audits were rejected after verification against the actual code:
+
+- LaBalance voucher (`tie_breaks_for_taker`) and LaCompetition (`separate_scoring`) flags — **both consumed** in `src/belote/scoring.py` and `src/belote/belatro/main.py`. Qwen flagged both as P0 dead-flag bugs; verification falsified both.
+- LeFou tarot "chain broken" — `run_state.py::consume` sets `last_consumable_id` *before* `item.use()` runs, so chaining works as intended.
+- `no_belote_rebelote` deck-mod flag — consumed at `src/belote/scoring.py:630`.
+- `_pending_tierce_charge` cross-round leak — each blind constructs a fresh `ScoreAccumulator` (main.py:126) and `drive_round` builds a fresh `GameState` via `new_game()` (round_driver.py:84), so `_joker_state` is empty at every round start. No cross-round persistence path exists.
+- `fuse_jokers` "loses `on_purchase` effects" — `on_purchase` mutates `run` state (which survives fusion); re-applying on the fused instance would *double-apply* cumulative effects (LeDemon's trust drop). Pre-3.2 behaviour is correct.
+- IllegalMoveError in `round_driver.py:291` — reachable only via test MockCallbacks; production `prompt_card` has a guard.
+- `_card_beats` defensive `assert trump is not None` — unreachable under current contract invariants.
+- `display_hud` no clear-to-EOL — HUD is rebuilt fresh per call; the claim was wrong.
+- Libra planet description — "×4 instead of ×3" matches the payout; mechanism is additive per coinche level but the description references the result.
+- `get_total()` float precision — explicit `int()` guard at scoring.py:248-249.
+- KeyboardInterrupt save — profile is saved *before* the loop starts; only intra-run delta is lost.
+
+### Internal
+
+- **Tests**: 525 → 528 (+3 net: −1 test renamed/repurposed for LeDernierMot team check, +2 new for La Sentinelle partner-detection and EW opponent rejection).
+- **Strict gates**: pytest 528/528, mypy 0 errors, ruff 0 violations across `src/` and `tests/`.
+- **Audit plan**: `~/.claude/plans/between-these-two-plans-graceful-puppy.md` — captures the two source audits, the verification pass that filtered them, the implementation order, and the catalogue of rejected claims.
+
+## [3.1.0] - 2026-05-08
+
+Audit-action release — implements the prioritized fix list from 3.0.3. One real correctness bug fixed, one unreachable feature wired up, one money-leak path closed, three measurable perf wins, and the long-standing `modifier_patch` underscore shim retired. 525 tests passing (up from 510), ruff and mypy strict still clean across 75 source files.
+
+### Fixed
+
+- **`src/belote/game.py:843-855` (HUD multi-boss running total)** — Under `Les Clubs Bannis + Le Roi Mort` (or any combo of `ban_clubs` with a rank-zero boss), the live HUD running total in `play_card` over-credited a clubs-led trick: the `ban_clubs → trick_pts = 0` branch was immediately overwritten by the rank-zero recompute. The eventual round score was already correct (different code path through `scoring.py`). Now `play_card` delegates to `scoring.trick_card_points`, the canonical helper that composes every boss zero-rank flag, `ban_clubs`, and the SE-trump scale in a single pass — the HUD cannot drift from the round score under any boss combo. Regression: `tests/test_official_rules.py::test_hud_running_total_under_multi_boss_ban_clubs_plus_kings_zero`.
+- **`src/belote/belatro/run/shop.py::buy_item` (consumable money-leak)** — Slot-capacity check is now hoisted *above* `Economy.spend_money`. Pre-3.1.0 the player's money was charged for a Tarot/Planet purchase even when consumable slots were full, and the item was silently dropped. New `Shop.last_buy_failure: str | None` carries the reason ("slots_full" / "no_money") so the shop UI surfaces a `BelAtroAnnounce.banner("Slots full — sell first")` banner. Regressions: `tests/belatro/test_belatro.py::TestShop::test_buy_consumable_with_full_slots_does_not_charge_money`, `test_buy_joker_with_full_slots_does_not_charge_money`, `test_buy_item_no_money_records_no_money_failure`.
+
+### Added
+
+- **TierceForge UI integration** (`src/belote/belatro/ui/shop.py`) — The `TierceForge` voucher shipped in 3.0.0 with a working `forge_tierce(run, planet_id)` backend (`src/belote/belatro/items/vouchers.py:129`) but no UI caller; the feature was unreachable. The shop now shows a "Forge ×N/3" tile when the voucher is owned, opens a numbered planet picker on Enter, and surfaces a confirmation banner on success. Regressions: `tests/belatro/test_phase2_content.py::test_forge_tierce_voucher_spends_charges_and_levels_planet`, `test_forge_tierce_blocked_when_charges_below_three`.
+- **Block-policy regressions for Tarot overflow** — `LeJugement` and `LaPretresse` are now pinned to no-op when joker/consumable slots are at capacity (rather than partial-grant). Tests: `test_le_jugement_no_op_when_joker_slots_full`, `test_la_pretresse_no_op_when_consumable_slots_full`.
+- **`tests/belatro/test_phase1_plumbing.py::test_joker_state_only_contains_scalar_values`** — Walks every registered joker through `on_round_start` + four event hooks and asserts no mutable container leaks into `_joker_state`. Locks the contract that lets the per-event copy stay shallow (3.1.0 dropped the deepcopy).
+- **`tests/belatro/test_phase1_plumbing.py::test_shop_edition_weights_match_distribution`** — 10 000-roll empirical check on `Shop._roll_edition()`, ±1% per bucket. Catches accidental edits to the `_EDITION_WEIGHTS` table.
+- **`tests/belatro/test_phase3_meta.py::test_endless_ante_target_scaling`** + `test_endless_ante_offset_zero_matches_base_table` — pin the `100 × 1.5^(ante-1) × blind × 2.2^offset` formula and the static-table parity invariant.
+- **`tests/belatro/test_phase2_content.py::test_le_fou_no_prior_consumable_falls_back_to_random_tarot`** — covers the `last_id == self.id` defensive branch in `tarots.py::LeFou.use`.
+- **`tests/belatro/test_boss_modifiers_integration.py::test_invariant_no_underscore_boss_attrs`** — anti-pattern lock for the architecture-pinned rule that boss flags must be reached via `state.boss_modifiers.X`, never `getattr(state, "_X", False)`.
+
+### Improved
+
+- **`src/belote/scoring.py` (winners-threading)** — `score_round` already pre-computed the per-trick winner list (3.0.2); the residual `trick_winner_seat` recomputations in the Malédiction branch (lines 776-793) and `apply_round_score` (lines 843-855) are now eliminated. Per-team trick counts ride on the new `ScoringBreakdown.tricks_ns` / `tricks_ew` fields (default 0; `apply_round_score` falls back to walking when a hand-constructed breakdown leaves them at default). Net: ~16 fewer `trick_winner_seat` calls per round.
+- **`src/belote/belatro/core/scoring.py::ScoreAccumulator.update_state` (deepcopy → shallow)** — Replaced the per-event `copy.deepcopy(state._joker_state)` with `dict(state._joker_state)`. All current `_joker_state` writers store scalars (bool/int/str), so the deep-copy was over-defensive — and ran ~20×/round. Module-level `import copy` and `from dataclasses import replace` removed (they were also reimported inside two methods). Contract is locked by the new scalar-invariant test.
+- **`src/belote/ai.py` (Hard AI hot-loop allocations)** — `_hard_play` precomputes `hand_suit_counts: Counter[Suit]`, `my_trumps`, `opp_trumps` once per turn and threads them into `_score_card_play` / `_score_leading_strategy` / `_score_discarding_strategy`. Pre-3.1.0 these counters were rebuilt for every candidate card — a four-card legal set walked the hand and `memory.played` four times each.
+- **`@dataclass(slots=True)` on `Statistics`, `SessionStats`, `ScoreAccumulator`** (`src/belote/stats.py`, `src/belote/belatro/core/scoring.py`). Frequently-instantiated containers; ~40 bytes saved per instance. `BelAtroRun` deliberately stays non-slotted (its `__post_init__` lazy-init pattern fights `slots=True`).
+- **`src/belote/stats.py:97-98`** — `print(..., file=sys.stderr)` on save failure swapped for `logging.getLogger(__name__).warning`. Removed unused `import sys`.
+- **`src/belote/input.py:138, 160`** — bare `except Exception:` in key-press parsing narrowed to `(UnicodeDecodeError,)` and `(ValueError, UnicodeDecodeError)`. Genuine bugs surface; key-press robustness preserved.
+- **`src/belote/replay.py:46`** — explanatory comment added above the `# noqa: BLE001` so the broad-except rationale is visible at the call site.
+- **`src/belote/game.py:213-217, 220-224`** — docstring on `belote_holders` and `_joker_state` documenting the "always replace, never mutate-in-place" contract for mutable dicts inside the frozen `GameState`.
+
+### Removed
+
+- **`modifier_patch.py` underscore shim** — The `state.patch("_X", True)` → `state.patch("X", True)` migration is complete. All 23 boss `apply()` methods in `src/belote/belatro/run/boss.py` were rewritten in lock-step. The leading-underscore strip in `PatchedGameState.patch()` and the `__getattr__` fallback to `boss_modifiers.X` are gone; `patch()` now asserts loud on a leading-underscore key. The `getattr(state, "_X", False)` reading anti-pattern is locked against in `test_invariant_no_underscore_boss_attrs`.
+
+### Internal
+
+- **Tests**: 510 → 525 (+15).
+- **Strict gates**: pytest 525/525, mypy 0 errors, ruff 0 violations across `src/` and `tests/`.
+- **Audit plan**: `~/.claude/plans/bug-hunt-code-performance-sleepy-ritchie.md`.
+
+## [3.0.3] - 2026-05-08
+
+Full-codebase audit pass + documentation accuracy. No behaviour changes; the audit produced a prioritized findings list and corrected three stale README counts. Planned fixes (one P0 functional, two P0 perf/quality, five P1, seven P2) are tracked for follow-up cuts and not yet implemented.
+
+### Fixed (documentation)
+
+- **`README.md`** — "Full Boss Blind Suite: All 18 unique bosses" → "All 21 unique bosses". 3.0.0 added Le Sauvage / L'Iconoclaste / Le Mime to bring `ALL_BOSS_MODIFIERS` (in `src/belote/belatro/run/boss.py`) to 21; the showcase line was never bumped.
+- **`README.md`** — two stale "(435 tests)" / "pytest: 435/435 passed" references corrected to 510, matching `pytest --collect-only` and the figure already present at `README.md:250` ("Currently 510 tests passing").
+
+### Audit findings (planning only — implementation deferred)
+
+A three-agent audit covered the classic engine vs. canonical Belote rules, BelAtro content wiring (jokers / bosses / planets / vouchers / tarots / editions / unlocks), and performance / code-quality hotspots across ~7,100 LOC. Headline: engine is rule-correct; BelAtro content matrix is 93/93 wired (21 bosses, 8 planets, 36 jokers, 4 editions, 12 vouchers, 12 tarots).
+
+Findings tracked at `~/.claude/plans/bug-hunt-code-performance-atomic-sutton.md`:
+- **P0-1** — `EventBus.emit` still never called (carried over from 3.0.2). `L'Exécuteur` / `L'Idéologue` / `Le Fanatique` unlocks silently never fire.
+- **P0-2** — `legal_cards()` LRU wrapper rebuilds `Card` objects on every cache hit (`src/belote/game.py:475-653`); est. 5–8% AI-turn regression vs. caching the resolved tuple.
+- **P0-3** — `play_card()` is 174 LOC / cyclomatic ~20 (`src/belote/game.py:777-950`); split into `_update_belote_tracker` / `_apply_play_modifiers` / `_resolve_trick_complete`.
+- **P0-4** — `_calculate_base_points()` accepts an optional pre-computed `winners` arg; cache-miss callers walk all 8 tricks twice (`src/belote/scoring.py:580-588`). Make required.
+- **P1-1** — `card_points(trump: Suit)` lies about None; 8 `# type: ignore` markers across `game.py` / `scoring.py` should drop once signature becomes `Suit | None`.
+- **P1-2** — Boss zero-rank logic duplicated across three sites (`game.py:856-872`, `scoring.py:390-400`, `scoring.py:429-440`); extract a single `apply_zero_rank_bosses(card, trump, bm)` helper. Highest-leverage maintenance fix.
+- **P1-3..P1-5** — `_hard_bid` recomputes void counts inside the suit loop; `trick_rank()` called twice per overtrump check; missing docstrings on hot APIs.
+- **P2** — carré KeyError harden, `REBELOTE_POINTS = 40` variant doc, AI memory reset hardening, `render()` 129-LOC split, `register_all_items` `__all__`, voucher / tarot integration test (24 effects to cover).
+
+### Internal
+
+- **Tests**: 510 (unchanged).
+- **Strict gates**: pytest 510/510, mypy 0 errors, ruff 0 violations (all unchanged from 3.0.2).
+
+### Carried forward
+
+- `EventBus.emit` wiring fix (P0-1 above) remains deferred. Now planned for 3.0.4 alongside the perf wins.
+
 ## [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.

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

@@ -84,14 +84,14 @@ PYTHONPATH=src mypy --strict src/
 # Linting (0 violations expected)
 ruff check src/ tests/
 
-# Full test suite (510 tests expected)
+# Full test suite (528 tests expected)
 PYTHONPATH=src pytest
 ```
 
-Current baseline (3.0.2):
+Current baseline (3.2.0):
 - **mypy**: 0 errors (strict mode)
 - **ruff**: 0 violations
-- **pytest**: 510 tests, 0 failures
+- **pytest**: 528 tests, 0 failures
 
 Run all gates before committing:
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: belote-cli
-Version: 3.0.2
+Version: 3.2.0
 Summary: A 4-player terminal card game
 Project-URL: Homepage, https://github.com/ElysiumDisc/belote
 Project-URL: Repository, https://github.com/ElysiumDisc/belote
@@ -45,12 +45,36 @@ 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).
 
+## What's new in 3.2.0
+
+- **Joker correctness** — La Sentinelle and Le Dernier Mot both used to key on `Seat.SOUTH` instead of the NS team, so the joker silently no-op'd when North (the AI partner) held the trump Jack or won the last trick. Both now correctly fire on team membership.
+- **Score floor** — L'Égoïste's `add_chips = -event.card_points` per partner-won trick could drive the running total negative and produce a negative final round score; `ScoreAccumulator.get_total` now clamps at 0 so the intermediate log can still show the deduction without the visible score going below zero.
+- **Auto-coinche event parity** — The NS-taker `auto_coinche` boss path now re-emits `BidMadeEvent` with the new `coinche_level`, matching the EW-taker branch. Pre-3.2 jokers and HUD subscribed to `on_bid` silently missed this code path.
+- **Determinism** — The shop and the three RNG-using tarots (`LeJugement`, `LaPretresse`, `LeFou`) now all draw from the run's seeded `_get_rng()` instead of the module-level `random`. Ghost-run replays are now reproducible across shop generations. `LaPretresse` additionally `sample`s instead of `choice`-ing twice, so the two planets it grants are always distinct.
+- **Registry / boss-field hygiene** — `register_joker/planet/tarot/voucher` now assert against duplicate IDs (typo'd registrations used to silently overwrite the original). `boss_fields` in `modifier_patch.py` is now derived from `BossModifiers`' dataclass fields, so adding a new flag no longer requires updating an out-of-band allowlist.
+- **UI fix** — `patch_trick_card` now re-applies `render`'s vertical-centering offset; on tall terminals (>40 rows) it used to draw single-card patches too high.
+- **Audit reconciliation** — This release consolidates the verified findings from two independent LLM code audits (Qwen 3.6 27B + Ring 1T). Both audits had load-bearing false positives — Qwen's two P0 "dead voucher / dead boss flag" claims were both wrong (the flags are consumed); Ring's "critical IllegalMoveError" only fires under test mocks. Eleven rejected claims are catalogued in the changelog so they aren't re-investigated.
+- **Test coverage** — 528 tests (up from 525). Strict gates still clean: pytest 528/528, mypy 0 errors, ruff 0 violations.
+
+## What's new in 3.1.0
+
+- **Bug fixes** — HUD running-total no longer drifts under multi-boss combos (`Les Clubs Bannis + Le Roi Mort` style: pre-3.1.0 the rank-zero recompute silently overwrote the `ban_clubs` zeroing). `Shop.buy_item` no longer charges money when consumable slots are full — the "Slots full — sell first" banner now fires before any spend.
+- **TierceForge wired up** — the voucher shipped in 3.0.0 with a working backend but no UI caller; the feature was unreachable. The shop now shows a "Forge ×N/3" tile when the voucher is owned, opens a numbered planet picker on Enter, and confirms the level-up via a banner.
+- **Performance** — `score_round` and `apply_round_score` no longer re-walk the trick list (~16 fewer `trick_winner_seat` calls per round). The per-event `copy.deepcopy` in `ScoreAccumulator.update_state` is gone (~20 deepcopies/round saved); replaced with a shallow `dict(...)` plus a scalar-only invariant test that locks the contract. Hard-AI's `_score_card_play` precomputes hand suit counts and trump tallies once per turn instead of per candidate.
+- **Cleanup** — the `modifier_patch` underscore-prefix shim is gone (23 boss `apply()` methods rewritten to use unprefixed field names; the `getattr(state, "_X", False)` anti-pattern is now locked against by a regression test). `slots=True` added to `Statistics`, `SessionStats`, `ScoreAccumulator`. Bare `except Exception:` in key-press parsing narrowed; `print → logging` in stats.
+- **Test coverage** — 525 tests (up from 510). Strict gates still clean: pytest 525/525, mypy 0 errors, ruff 0 violations.
+
+## What's new in 3.0.3
+
+- **Full-codebase audit** — three-agent pass over the classic engine, BelAtro content wiring, and perf / code-quality hotspots (~7,100 LOC). Headline: engine is rule-correct against canonical French Belote; BelAtro content matrix is **93/93 wired** (21 bosses, 8 planets, 36 jokers, 4 editions, 12 vouchers, 12 tarots). Prioritized findings list (1 P0 functional, 2 P0 perf, 5 P1, 7 P2) tracked for follow-up cuts; implementation landed in 3.1.0.
+- **Doc accuracy** — README boss-count corrected (18 → 21; 3.0.0 added Le Sauvage / L'Iconoclaste / Le Mime), and two stale `(435 tests)` references bumped to 510 to match the figure already present elsewhere in the file.
+
 ## 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).
+- **Test coverage** — 525 tests (up from 509).
 
 ## What's new in 3.0.1
 
@@ -222,7 +246,7 @@ belote --difficulty hard --target 500 --seed 123 --speed fast
 
 - **BelAtro Roguelite Mode:** A massive expansion featuring 36 Jokers, 12 Tarot cards, 8 Planets, 12 Vouchers, and permanent upgrades.
 - **Collection (Almanac):** Persistent tracker to browse every Joker, Planet, and Voucher you've discovered across your runs.
-- **Full Boss Blind Suite:** All 18 unique bosses implemented, including complex mechanics like *L'Anarchie* (dynamic trump) and *La Rupture* (no consecutive wins).
+- **Full Boss Blind Suite:** All 21 unique bosses implemented, including complex mechanics like *L'Anarchie* (dynamic trump) and *La Rupture* (no consecutive wins).
 - **Multiplier Scoring:** Use items to stack Multipliers and reach scores in the millions.
 - **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.
@@ -274,7 +298,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 (435 tests)
+├── tests/             # Comprehensive test suite (528 tests)
 ├── scripts/           # Performance benchmarks
 ├── pyproject.toml      # Build system and dev dependencies (ruff/mypy)
 ├── LICENSE             # MIT License
@@ -290,14 +314,14 @@ belote/
 PYTHONPATH=src pytest
 ```
 
-Currently **510 tests** passing with 100% coverage on game-logic modules.
+Currently **528 tests** passing with 100% coverage on game-logic modules.
 
 ## Technical Integrity
 
 The codebase is strictly validated with the following tools:
 - **mypy**: 0 errors (strict type safety)
 - **ruff**: 0 violations (linting & formatting)
-- **pytest**: 435/435 passed
+- **pytest**: 528/528 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.0.2 → belote_cli-3.2.0}/README.md

@@ -2,12 +2,36 @@
 
 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).
 
+## What's new in 3.2.0
+
+- **Joker correctness** — La Sentinelle and Le Dernier Mot both used to key on `Seat.SOUTH` instead of the NS team, so the joker silently no-op'd when North (the AI partner) held the trump Jack or won the last trick. Both now correctly fire on team membership.
+- **Score floor** — L'Égoïste's `add_chips = -event.card_points` per partner-won trick could drive the running total negative and produce a negative final round score; `ScoreAccumulator.get_total` now clamps at 0 so the intermediate log can still show the deduction without the visible score going below zero.
+- **Auto-coinche event parity** — The NS-taker `auto_coinche` boss path now re-emits `BidMadeEvent` with the new `coinche_level`, matching the EW-taker branch. Pre-3.2 jokers and HUD subscribed to `on_bid` silently missed this code path.
+- **Determinism** — The shop and the three RNG-using tarots (`LeJugement`, `LaPretresse`, `LeFou`) now all draw from the run's seeded `_get_rng()` instead of the module-level `random`. Ghost-run replays are now reproducible across shop generations. `LaPretresse` additionally `sample`s instead of `choice`-ing twice, so the two planets it grants are always distinct.
+- **Registry / boss-field hygiene** — `register_joker/planet/tarot/voucher` now assert against duplicate IDs (typo'd registrations used to silently overwrite the original). `boss_fields` in `modifier_patch.py` is now derived from `BossModifiers`' dataclass fields, so adding a new flag no longer requires updating an out-of-band allowlist.
+- **UI fix** — `patch_trick_card` now re-applies `render`'s vertical-centering offset; on tall terminals (>40 rows) it used to draw single-card patches too high.
+- **Audit reconciliation** — This release consolidates the verified findings from two independent LLM code audits (Qwen 3.6 27B + Ring 1T). Both audits had load-bearing false positives — Qwen's two P0 "dead voucher / dead boss flag" claims were both wrong (the flags are consumed); Ring's "critical IllegalMoveError" only fires under test mocks. Eleven rejected claims are catalogued in the changelog so they aren't re-investigated.
+- **Test coverage** — 528 tests (up from 525). Strict gates still clean: pytest 528/528, mypy 0 errors, ruff 0 violations.
+
+## What's new in 3.1.0
+
+- **Bug fixes** — HUD running-total no longer drifts under multi-boss combos (`Les Clubs Bannis + Le Roi Mort` style: pre-3.1.0 the rank-zero recompute silently overwrote the `ban_clubs` zeroing). `Shop.buy_item` no longer charges money when consumable slots are full — the "Slots full — sell first" banner now fires before any spend.
+- **TierceForge wired up** — the voucher shipped in 3.0.0 with a working backend but no UI caller; the feature was unreachable. The shop now shows a "Forge ×N/3" tile when the voucher is owned, opens a numbered planet picker on Enter, and confirms the level-up via a banner.
+- **Performance** — `score_round` and `apply_round_score` no longer re-walk the trick list (~16 fewer `trick_winner_seat` calls per round). The per-event `copy.deepcopy` in `ScoreAccumulator.update_state` is gone (~20 deepcopies/round saved); replaced with a shallow `dict(...)` plus a scalar-only invariant test that locks the contract. Hard-AI's `_score_card_play` precomputes hand suit counts and trump tallies once per turn instead of per candidate.
+- **Cleanup** — the `modifier_patch` underscore-prefix shim is gone (23 boss `apply()` methods rewritten to use unprefixed field names; the `getattr(state, "_X", False)` anti-pattern is now locked against by a regression test). `slots=True` added to `Statistics`, `SessionStats`, `ScoreAccumulator`. Bare `except Exception:` in key-press parsing narrowed; `print → logging` in stats.
+- **Test coverage** — 525 tests (up from 510). Strict gates still clean: pytest 525/525, mypy 0 errors, ruff 0 violations.
+
+## What's new in 3.0.3
+
+- **Full-codebase audit** — three-agent pass over the classic engine, BelAtro content wiring, and perf / code-quality hotspots (~7,100 LOC). Headline: engine is rule-correct against canonical French Belote; BelAtro content matrix is **93/93 wired** (21 bosses, 8 planets, 36 jokers, 4 editions, 12 vouchers, 12 tarots). Prioritized findings list (1 P0 functional, 2 P0 perf, 5 P1, 7 P2) tracked for follow-up cuts; implementation landed in 3.1.0.
+- **Doc accuracy** — README boss-count corrected (18 → 21; 3.0.0 added Le Sauvage / L'Iconoclaste / Le Mime), and two stale `(435 tests)` references bumped to 510 to match the figure already present elsewhere in the file.
+
 ## 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).
+- **Test coverage** — 525 tests (up from 509).
 
 ## What's new in 3.0.1
 
@@ -179,7 +203,7 @@ belote --difficulty hard --target 500 --seed 123 --speed fast
 
 - **BelAtro Roguelite Mode:** A massive expansion featuring 36 Jokers, 12 Tarot cards, 8 Planets, 12 Vouchers, and permanent upgrades.
 - **Collection (Almanac):** Persistent tracker to browse every Joker, Planet, and Voucher you've discovered across your runs.
-- **Full Boss Blind Suite:** All 18 unique bosses implemented, including complex mechanics like *L'Anarchie* (dynamic trump) and *La Rupture* (no consecutive wins).
+- **Full Boss Blind Suite:** All 21 unique bosses implemented, including complex mechanics like *L'Anarchie* (dynamic trump) and *La Rupture* (no consecutive wins).
 - **Multiplier Scoring:** Use items to stack Multipliers and reach scores in the millions.
 - **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.
@@ -231,7 +255,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 (435 tests)
+├── tests/             # Comprehensive test suite (528 tests)
 ├── scripts/           # Performance benchmarks
 ├── pyproject.toml      # Build system and dev dependencies (ruff/mypy)
 ├── LICENSE             # MIT License
@@ -247,14 +271,14 @@ belote/
 PYTHONPATH=src pytest
 ```
 
-Currently **510 tests** passing with 100% coverage on game-logic modules.
+Currently **528 tests** passing with 100% coverage on game-logic modules.
 
 ## Technical Integrity
 
 The codebase is strictly validated with the following tools:
 - **mypy**: 0 errors (strict type safety)
 - **ruff**: 0 violations (linting & formatting)
-- **pytest**: 435/435 passed
+- **pytest**: 528/528 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.0.2 → belote_cli-3.2.0}/pyproject.toml

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

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

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

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

@@ -490,12 +490,31 @@ class AIPlayer:
         )
         partner_winning = current_winner is not None and current_winner == p
 
+        # Precompute per-call counters used by every scoring branch — pre-3.1.0
+        # these were recomputed per candidate card (n×4 walks of the hand and
+        # memory.played for each legal card).
+        from collections import Counter
+
+        my_hand = state.hand_of(self.seat)
+        hand_suit_counts: dict[Suit, int] = Counter(c.suit for c in my_hand)
+        my_trumps = hand_suit_counts.get(trump, 0)
+        opp_trumps = 8 - sum(1 for c in self.memory.played if c.suit == trump)
+
         # Score each legal card by expected outcome
         best_card = legal[0]
         best_score: float = -999.0
 
         for card in legal:
-            score = self._score_card_play(card, state, trump, trick, partner_winning)
+            score = self._score_card_play(
+                card,
+                state,
+                trump,
+                trick,
+                partner_winning,
+                hand_suit_counts,
+                my_trumps,
+                opp_trumps,
+            )
             if score > best_score:
                 best_score = score
                 best_card = card
@@ -509,6 +528,9 @@ class AIPlayer:
         trump: Suit,
         trick: tuple[TrickCard, ...],
         partner_winning: bool,
+        hand_suit_counts: dict[Suit, int],
+        my_trumps: int,
+        opp_trumps: int,
     ) -> float:
         """Score a card play decision with advanced heuristics."""
         score = 0.0
@@ -517,20 +539,20 @@ class AIPlayer:
         score += points * 0.1
 
         if not trick:
-            return self._score_leading_strategy(card, state, trump)
+            return self._score_leading_strategy(card, trump, my_trumps, opp_trumps)
 
         if partner_winning and trick[0].card.suit != trump:
-            return self._score_discarding_strategy(card, state, trump, points)
+            return self._score_discarding_strategy(card, trump, points, hand_suit_counts)
 
         return self._score_winning_strategy(card, state, trump, trick, partner_winning, points)
 
-    def _score_leading_strategy(self, card: Card, state: GameState, trump: Suit) -> float:
+    def _score_leading_strategy(
+        self, card: Card, trump: Suit, my_trumps: int, opp_trumps: int
+    ) -> float:
         """Heuristics for when we are leading the trick."""
         score = 0.0
         if card.suit == trump:
             # Leading trump is good for pulling if opponents still have them
-            opp_trumps = 8 - sum(1 for c in self.memory.played if c.suit == trump)
-            my_trumps = sum(1 for c in state.hand_of(self.seat) if c.suit == trump)
             if opp_trumps > my_trumps:
                 score += 4
             else:
@@ -543,7 +565,7 @@ class AIPlayer:
         return score
 
     def _score_discarding_strategy(
-        self, card: Card, state: GameState, trump: Suit, points: int
+        self, card: Card, trump: Suit, points: int, hand_suit_counts: dict[Suit, int]
     ) -> float:
         """Heuristics for when partner is winning and we can discard."""
         score = 0.0
@@ -551,9 +573,7 @@ class AIPlayer:
         score -= points * 0.7  # Penalize throwing away points
 
         # Prefer discarding from short suits (to establish voids)
-        my_hand = state.hand_of(self.seat)
-        suit_count = sum(1 for c in my_hand if c.suit == card.suit)
-        if suit_count == 1:
+        if hand_suit_counts.get(card.suit, 0) == 1:
             score += 3
 
         # Prefer keeping cards that partner is void in (to trump later)

{belote_cli-3.0.2 → belote_cli-3.2.0}/src/belote/belatro/core/run_state.py

@@ -70,6 +70,12 @@ class BelAtroRun:
     # ── Last consumable used (read by LeFou tarot) ─────────
     last_consumable_id: str | None = None
 
+    # ── Last tarot status message ──────────────────────────
+    # Set by tarots that need to surface a non-fatal failure (e.g. LeJugement
+    # rolling a joker when joker_slots are full). The UI may read and display
+    # this; tests assert it. Cleared whenever a new tarot is used.
+    last_tarot_message: str | None = None
+
     # ── Determinism ────────────────────────────────────────
     seed: int | None = None
     _rng: Any = None
@@ -178,10 +184,15 @@ class BelAtroRun:
             self.endless_ante_offset += 1
             self.blind_index = 0
             return
-        # Standard run completion.
+        # Standard run completion. Set both flags so the terminal-state
+        # invariant (run_over ⇔ run is over, run_won ⇔ run is over AND we won)
+        # is consistent; main.py's loop break still handles the exit but
+        # downstream callers can now rely on run_over alone.
         self.run_won = True
+        self.run_over = True
 
     def enter_endless(self) -> None:
         """Toggle endless mode after beating ante 8."""
         self.endless = True
         self.run_won = False  # endless overrides run-won state
+        self.run_over = False  # ...and re-opens the run so the main loop continues

{belote_cli-3.0.2 → belote_cli-3.2.0}/src/belote/belatro/core/scoring.py

@@ -1,6 +1,6 @@
 from __future__ import annotations
 
-from dataclasses import dataclass, field
+from dataclasses import dataclass, field, replace
 from typing import TYPE_CHECKING, Any
 
 if TYPE_CHECKING:
@@ -28,7 +28,7 @@ _SUIT_TO_CONTRACT: dict[Suit, str] = {
 }
 
 
-@dataclass
+@dataclass(slots=True)
 class ScoreAccumulator:
     """
     Accumulates Chips and Mult across one round,
@@ -65,7 +65,6 @@ class ScoreAccumulator:
         new_chips = state._chips + self.permanent_chips
         new_mult = state._mult * self.permanent_mult if self.permanent_mult != 1.0 else state._mult
 
-        from dataclasses import replace
         return replace(state, _joker_state=joker_state, _chips=new_chips, _mult=new_mult)
 
     def update_state(self, state: GameState, event: object) -> GameState:
@@ -73,12 +72,11 @@ class ScoreAccumulator:
         new_chips = state._chips
         new_mult = state._mult
         new_money = state._bonus_money
-        # Deep-copy the joker state: a shallow dict() shares mutable values
-        # (lists/dicts/sets nested inside) across rounds, which has bitten us
-        # before with frozenset/list flags persisting after the round ended.
-        import copy
-
-        joker_state = copy.deepcopy(state._joker_state)
+        # Shallow copy is sufficient: every value written into _joker_state
+        # is a scalar (bool / int / str). The pre-3.1.0 deepcopy ran on every
+        # event (~20×/round) — see test_joker_state_only_contains_scalar_values
+        # in tests/belatro/test_phase1_plumbing.py for the locking invariant.
+        joker_state = dict(state._joker_state)
 
         def _apply(result: JokerResult, source: str) -> None:
             nonlocal new_chips, new_mult, new_money
@@ -235,7 +233,6 @@ class ScoreAccumulator:
             _fire_jokers("on_bid", event)
 
         # Update GameState with new values
-        from dataclasses import replace
         return replace(
             state,
             _chips=new_chips,
@@ -245,8 +242,11 @@ class ScoreAccumulator:
         )
 
     def get_total(self, state: GameState) -> int:
-        # Avoid float precision issues for large integers if mult is effectively an int
-        chips: int = state._chips
+        # Clamp at 0: corrupted jokers (L'Égoïste in particular) can subtract
+        # chips per trick won by partner, and with enough partner tricks the
+        # running total can go negative, producing a negative final score.
+        # Final score should never be negative — clamp at the scoring boundary.
+        chips: int = max(0, state._chips)
         mult: float = state._mult
         if mult == float(int(mult)):
             return chips * int(mult)

{belote_cli-3.0.2 → belote_cli-3.2.0}/src/belote/belatro/engine/modifier_patch.py

@@ -1,8 +1,14 @@
 from __future__ import annotations
 
+import dataclasses
 from typing import Any
 
-from belote.game import GameState
+from belote.game import BossModifiers, GameState
+
+# Derived from BossModifiers so new flags added there are picked up
+# automatically; previously this was a hardcoded set that silently no-op'd
+# any new boss field not added here in lockstep.
+_BOSS_FIELDS: frozenset[str] = frozenset(f.name for f in dataclasses.fields(BossModifiers))
 
 
 class PatchedGameState:
@@ -18,22 +24,21 @@ class PatchedGameState:
     # ── Patch registration ──────────────────────────────────────────────
 
     def patch(self, attr: str, value: Any) -> None:
-        """Override a specific attribute for this round."""
-        if attr.startswith("_"):
-            # Strip leading underscore if it was from the old system
-            attr = attr[1:]
+        """Override a specific attribute for this round.
 
-        # We'll treat all these flat patches as boss_modifiers fields
-        boss_fields = {
-            "no_belote", "dynamic_trump", "no_consecutive_team_wins", "seven_eight_trump",
-            "invert_scoring", "kings_zero", "auto_coinche", "queen_spades_penalty",
-            "hide_hud", "ban_clubs", "no_dix_de_der", "tens_zero", "hide_partner_hand",
-            "agent_double_active", "agent_double_late_only", "partner_forced_pass",
-            "lock_trust_zero", "separate_scoring",
-            "aces_zero", "jacks_zero", "declarations_zero",
-        }
+        Boss field names are unprefixed (e.g. "no_belote", not "_no_belote").
+        The 3.0.x backward-compat shim that stripped a leading underscore was
+        removed in 3.1.0 — call sites in `run/boss.py` were rewritten in lock-
+        step. The `getattr(state, "_X", False)` reading anti-pattern is locked
+        against in tests/belatro/test_boss_modifiers_integration.py
+        `test_invariant_no_underscore_boss_attrs`.
+        """
+        assert not attr.startswith("_"), (
+            f"patch() received leading-underscore attr {attr!r}; the 3.0.x shim "
+            "was removed in 3.1.0 — use the unprefixed boss field name."
+        )
 
-        if attr in boss_fields:
+        if attr in _BOSS_FIELDS:
             current_bm = self.boss_modifiers
             from belote.game import replace
             new_bm = replace(current_bm, **{attr: value})
@@ -47,13 +52,6 @@ class PatchedGameState:
         patches = object.__getattribute__(self, "_patches")
         if name in patches:
             return patches[name]
-
-        # Backward compatibility for old underscored names
-        if name.startswith("_"):
-            stripped = name[1:]
-            if hasattr(self.boss_modifiers, stripped):
-                return getattr(self.boss_modifiers, stripped)
-
         return getattr(object.__getattribute__(self, "_state"), name)
 
     def __setattr__(self, name: str, value: Any) -> None: