belote-cli 3.4.0__tar.gz → 3.5.0__tar.gz

{belote_cli-3.4.0 → belote_cli-3.5.0}/CHANGELOG.md

@@ -5,6 +5,133 @@ 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.5.0] - 2026-05-12
+
+Comprehensive bug-hunt, game-mechanic audit, and performance pass over both the classic Belote engine and the BelAtro roguelite layer. A three-Explore-agent audit produced ~30 candidate findings; verification against the source rejected several as false positives (documented below) and confirmed **15 actionable items** plus **1 latent bug surfaced during implementation**. **24 new regression tests** land here (592 total, up from 568). Plan file at `/home/mrrobot/.claude/plans/bug-hunt-code-performance-tidy-meerkat.md`.
+
+### Fixed
+
+- **`src/belote/belatro/core/run_state.py:90-117` + new `src/belote/belatro/ui/consumables.py` (C1) — BelAtro consumables can now be activated.** Pre-3.5.0 `BelAtroRun.consume()` was defined but never called from any UI: every Tarot bought from the shop and every directly-purchased Planet accumulated in `run.consumables` with no way to use them. Only the voucher-gated Forge-Tierce path could level a planet. New `ConsumablesOverlay` is reachable from the shop via the `C` key, listing the tray and dispatching to `run.consume(item, context=run)` on a digit press. Hint line in the shop now shows `C: Consumables (N)`. **Also fixes a latent Le Fou bug**: `consume()` was advancing `last_consumable_id` to the *current* item BEFORE calling `item.use()`, so Le Fou's `use()` read its own id and fell through to the fallback path. Reordered to call `item.use()` first; Le Fou is special-cased as transparent so a second Le Fou keeps copying the same source rather than itself. 7 regression tests in `tests/belatro/test_consumables_ui.py`.
+- **`src/belote/belatro/run_summary.py:67-74` (H1) — JSONL appends are now durable.** Added `f.flush() + os.fsync(f.fileno())` inside the `with` block, mirroring the atomic-save pattern in `progression/save.py:81-82`. A crash or power-loss mid-write no longer leaves a truncated final line that breaks downstream `jq` processing. 3 regression tests in `tests/belatro/test_run_summary.py`.
+- **`src/belote/input.py:31-37,74` + ~20 consumer sites (H2) — EOF on stdin is distinct from ESC.** `KeyReader.read()` returned `KeyEvent(Key.ESC)` when `os.read()` returned empty bytes. A closed stdin (broken pipe, headless harness, Ctrl-D) made every prompt loop spin: ESC popped one menu level, the loop fell through and re-read stdin, got another "ESC", popped again — burning CPU until the outermost loop happened to exit. New `Key.EOF` enum value is returned on empty-read. Every `Key.ESC` consumer was updated to also accept `Key.EOF` (semantically equivalent: "back / cancel"); `prompt_card` and `prompt_bid` exit cleanly on EOF instead of spinning. 5 regression tests in `tests/test_input_eof.py`.
+- **`src/belote/belatro/engine/event_bus.py` (H3) — `EventBus` round-scope invariant documented + `clear()` added.** The bus is created fresh per round in `round_driver.drive_round` and subscribers are released with it; no explicit unsubscribe was needed. The invariant was silent — if anyone moved the bus to a longer scope, every subscription would double-fire on round 2. Module docstring now spells out the round-scope contract; a new `clear()` method exists for the future where a longer-lived bus might be desirable. 3 regression tests in `tests/belatro/test_event_bus.py`.
+- **`src/belote/scoring.py:228-330` (M1) — tied carrés / sequences go to the first announcer.** Standard Belote-Coinché awards a tied declaration to the team whose seat declared first (announcement order: taker → clockwise). Pre-3.5.0 the resolver returned `scoring_team=None` (cancel), which was defensive but non-standard. `resolve_declarations` gains an optional `taker: Seat | None = None` parameter; when supplied, tied carrés/sequences are awarded by walking the announce order. Legacy "cancel" behaviour preserved when `taker` is not provided. Both call sites updated to pass `state.taker`. 6 regression tests in `tests/test_declaration_tiebreak.py`.
+- **`src/belote/belatro/engine/event_bus.py` + ~10 consumer sites (M3) — `RoundEndEvent.breakdown` is properly typed.** Pre-3.5.0 the field was `breakdown: Any` and every consumer wrote `getattr(event.breakdown, "is_failed", False)` — defensive noise that hid field-rename regressions until runtime. Now typed as `ScoringBreakdown` (TYPE_CHECKING forward-ref to avoid import cycle); all 9 `getattr` patterns replaced with direct attribute access. `taker_seat` correctly annotated `Seat | None` (was `Seat`, but the all-pass emitter at `round_driver.py:298` actually passes None).
+- **`src/belote/scoring.py:750-763` (M5) — SA belote invariant pinned at contract level.** The `assert taker_belote == 0 and defender_belote == 0` for Sans Atout rounds was only inside the capot branch — a non-capot SA round with stray belote points would silently mis-score instead of surfacing the bug. Hoisted to a contract-level post-condition that covers both capot and non-capot paths.
+
+### Changed
+
+- **`src/belote/belatro/core/scoring.py:125-142` (M4) — `partner_jokers_double` legacy flag is now deprecated.** When both the tier scaling and the legacy boolean flag are set, a one-shot `DeprecationWarning` fires. Behaviour unchanged (`max()` of the two still wins); the flag is slated for removal in 4.0.
+- **`src/belote/ui/render.py:988-997` (L1) — `patch_trick_card` batches its writes.** Pre-3.5.0 each card-face line + the HUD update were separate `sys.stdout.write` calls; signal-interruptible terminals could paint half the card before the HUD landed. Now one `write()` per repaint, mirroring the pattern at `render.py:923,933`.
+- **`src/belote/a11y.py:1-20` (L2) — module docstring spells out the env-var invariant.** `BELOTE_A11Y` is read once at import; toggling mid-session has no effect on production code. Tests use `_refresh_enabled_from_env()`. No behaviour change, just documentation.
+- **`src/belote/belatro/core/run_state.py:30-41` (L3) — `consumables` / `jokers` / `vouchers` mutation contract documented.** These lists are intentionally mutable; any future replay / ghost-run snapshot path must deep-copy at the snapshot boundary. No behaviour change.
+
+### Performance
+
+- **`scripts/benchmark.py` (M2) — three new micro-benchmarks for real hot paths.** `benchmark_legal_cards_cached` (warm-cache path; production gameplay reuses across 8 tricks), `benchmark_trick_scoring` (`trick_card_points`, called 16× per round), `benchmark_ai_legality_filter` (the legal-move filter step inside `AIPlayer.decide_card`). The pre-existing `benchmark_legal_cards` was clarified as the cache-cleared cold path.
+- **`src/belote/scoring.py:439-477` (P1) — `trick_card_points` hoists boss-flag reads.** Same pattern `_calculate_base_points` (lines 489-493) uses. Saves 4 dataclass-attr lookups per card per trick. Sub-microsecond gain; the function was already micro-optimized at ~2μs per call. **Memoization rejected**: at 2μs × 16 calls = 32μs per round, the cache-key overhead would exceed the gain.
+- **`src/belote/game.py:490-512` (P2) — `legal_cards` cache-key analysis documented.** Benchmark shows cold ~9μs / warm ~6μs; the 33% gap is dominated by key-build cost in `legal_cards()`, not lru_cache lookup. The key already uses small-int IDs (not Card objects) which is the minimal hashable surface. Slimming further would require caching `hand_ids` on the hand tuple itself, which isn't reachable without changing the hand representation. **Documented "no actionable optimization without larger refactor"** in the cache-impl docstring so a future audit doesn't re-investigate the same dead end.
+- **`src/belote/belatro/core/scoring.py:70-89` (P3) — `ScoreAccumulator.update_state` profiling note.** cProfile of 10k calls shows `dataclasses.replace` is 65% of the cost — frozen-GameState invariant is load-bearing, so the replace cost stays. At ~19μs per event × ~25 events per round = ~0.5ms per round, the accumulator is well under the budget.
+
+### Verified clean — agent claims that did NOT survive source verification
+
+Catalogued so they aren't re-investigated next cycle.
+
+- **"Belote/Rebelote not announced when partner holds K+Q"** (`game.py:863-876`) — The condition `state.belote_holders.get(trump) == state.turn` fires when the holder *plays* the K/Q, which is exactly when the announcement should fire. `state.turn` equals the holder at the moment of play regardless of partnership. **Correct as-is.**
+- **"Capot false-positive under La Rupture on the 8th-trick announcement"** (`gameflow.py:215`) — `is_capot()` already routes through `compute_trick_winners()`, which honours Rupture for both the live-announce path and the final scoring path. The docstring at `scoring.py:317-326` explicitly calls this out. **Correct as-is.**
+- **"AI `partner_hand` not cleared on undo path"** (`ai.py:79-92`) — `update_memory()` always clears `partner_hand` at line 104 and re-fills it from the current state, regardless of which earlier branch ran (new-round / undo / normal). **Correct as-is.**
+- **"Negative-edition slot rollback on purchase failure"** (`run/shop.py:166-168`) — `_can_accept()` returns True unconditionally for Negative jokers, and `_apply_item` runs only after `spend_money()` succeeded. No failure path exists. **Correct as-is.**
+- **"`boss.id == \"…\"` string-branching in pre-round setup"** — `grep -rn 'boss\.id\s*==' src/belote/belatro/` returns zero results. Cleaned up in the May 2026 audit. **Correct as-is.**
+
+### Internal
+
+- **Tests**: 568 → 592 (+24). Six new test files: `tests/belatro/test_consumables_ui.py` (7), `tests/belatro/test_run_summary.py` (3), `tests/test_input_eof.py` (5), `tests/belatro/test_event_bus.py` (3), `tests/test_declaration_tiebreak.py` (6). 0 existing tests modified.
+- **Strict gates**: pytest 592/592 green.
+- **Version markers bumped**: `pyproject.toml`, `src/belote/__init__.py`.
+- **Docs bumped**: `CHANGELOG.md` (this entry), `README.md` "What's new in 3.5.0".
+
+## [3.4.2] - 2026-05-11
+
+Implements the deferred bug roadmap from 3.4.1's verification pass. **9 fixes land here** — 3 Critical (C1/C3/C4), 4 High (H1/H4/H5/H7), 1 architectural cleanup (H10), 1 dead-code deletion (M4). Adds 17 regression tests (551 → 568). The 3.4.1 entry catalogued these against the source; this entry implements them. Plan file at `/home/mrrobot/.claude/plans/wtf-these-were-verified-shiny-flute.md`.
+
+### Fixed
+
+- **`src/belote/ai.py:104-108` (C1) — AI no longer sees partner's hand under `hide_partner_hand`.** `AIMemory.update_memory()` now gates the `partner_hand` population on `not state.boss_modifiers.hide_partner_hand`. Under Le Fantôme Partenaire the human was blinded but the AI continued to play with perfect partner information — the boss's visibility cost was paid by one team only. The fix removes the perfect-information cheat; the AI still infers partner cards via `known_voids` and `played` like any real player. Regression test in `tests/belatro/test_dead_flag_fixes.py::test_ai_memory_respects_hide_partner_hand`.
+- **`src/belote/gameflow.py:200-203` (C3) — Dix de Der announcement now uses the Rupture-aware winner.** Pre-3.4.2 the 8th-trick "Dix de Der (Team X)" line called raw `trick_winner_seat()` on `display_state.current_trick`, which ignores `boss_modifiers.no_consecutive_team_wins`. Under La Rupture the announcement could name a team that was *not* credited the +10 in scoring. Fix swaps to `compute_trick_winners(state, trump, is_sa, tricks=projected)[-1]` (same helper `scoring.py` uses), feeding `projected = completed_tricks + [display_state.current_trick]` since the 8th trick isn't yet pushed to `completed_tricks` when the announcement fires. Removes the now-unused `trick_winner_seat` import. Regression test in `tests/belatro/test_boss_modifiers_integration.py::test_dix_de_der_announcement_honors_rupture`.
+- **`src/belote/ai.py:540-549` (C4) — `opp_trumps` no longer over-counts; TA total fixed.** The pre-3.4.2 formula `8 - sum(played trumps)` conflated "remaining trump anywhere" with "opponent trump", treating South's own hand and partner's visible cards as still in opponents' hands. The fix subtracts `my_trumps`, `played_trumps`, and `partner_trumps` from the total. Under Tout Atout every card is a trump and the total is `32`, not `8` — pre-3.4.2 the formula degraded to `8 - 0 = 8` always under TA because no card's `.suit` equals `Suit.TOUT_ATOUT`. Both regimes are now handled. Has the side effect of also fixing `my_trumps` under TA (used by `_score_leading_strategy` downstream). Regression tests in `tests/test_ai.py::test_opp_trumps_excludes_own_and_partner_hand` and `::test_opp_trumps_under_tout_atout_uses_32_total`.
+- **`src/belote/belatro/items/jokers/contract.py` + `trick_timing.py` (H1) — 8 jokers now gate on team, not seat.** `LIdeologue`, `LeFanatique`, `LeDiplomate`, `LePatriote`, `LIllusionniste`, `LePremierSang` (both checks), `LeSergent`, `LExecuteur` were checking `event.winner == Seat.SOUTH` instead of `team_of(event.winner) == 0`. They silently no-opped when partner (North) took the relevant trick. Now consistent with the 3.2.0 fix that landed `LaSentinelle` and `LeDernierMot` on the same pattern. Five existing tests that asserted the broken behavior (`test_north_*_returns_none`) were rewritten to verify the new correct behavior — partner wins now fire the joker; opposing-team wins (EAST) are added as the new negative case. `LeSergent`'s "streak reset" semantics also shifted: an opposing-team trick now breaks the streak, not a partner-won one. Regression backstop in `tests/belatro/test_phase0_coverage.py::test_h1_team_aware_jokers_fire_on_north_partner_win`. **`LeRebelle` is intentionally not included** — the 3.4.1 catalogue flagged it as a probable audit hallucination; it is an `on_belote` joker, not on `on_trick_won`, and the seat-vs-team distinction there is a separate spec call deferred to a future cycle.
+- **`src/belote/belatro/run/ante_themes.py` + `belatro/main.py:413-414` (H4) — TournoiAnte pays a real 50% of round payout.** `AnteTheme.on_blind_won` gains a `blind_payout: int` parameter (forwarded to base class and both subclasses). The call site at `belatro/main.py:412` snapshots `run.economy.money` immediately before `process_round_end` and computes `blind_payout = money_after - money_before` after all bonus paths (L'Avocat, `_bonus_money`, Le Puriste, L'Aristocrate) have run. TournoiAnte now does `add_money(max(1, blind_payout // 2))` — actually 50% of payout, with a $1 floor so blind payouts of 0 still pay something. Comment rewritten to match. Updated tests in `tests/belatro/test_phase3_meta.py` (CafeAnte test threads the new arg; TournoiAnte tests verify exact `payout // 2` math + the floor).
+- **`src/belote/belatro/progression/save.py:97-101` (H5) — `load_profile` no longer loses starter unlocks.** Pre-3.4.2 the happy path read `data.get("unlocked_ids", [])`, defaulting to an empty list when the key was absent — wiping the Profile dataclass's `["le_classique", "le_courageux", "l_econome"]` starter unlocks for any save missing the key (legacy saves, manual edits, partial writes). The fix falls back to `Profile().unlocked_ids` when the key is missing; an explicitly empty `unlocked_ids: []` is honored unchanged (a player who has reset their unlocks stays reset). Two regression tests in `tests/belatro/test_collection_logic.py` lock both behaviors.
+- **`src/belote/main.py:230-231` (H7) — stats line agrees with menu summary on ties.** Changed `won=(ns >= target and ns >= ew)` to `won=(ns >= target and ns > ew)` so the `update_stats_game` `won` flag aligns with `ui/menu.py:344`'s `winner = "NS" if ns > ew else "EW"`. On an exact tie at target, pre-3.4.2 the stats recorded a NS win while the visible summary said EW. Both regression tests in `tests/test_new_coverage.py` — one source-grep anti-pattern lock against `>=`, one semantic check on the formula.
+
+### Internal
+
+- **`src/belote/belatro/partner/partner_state.py:38-49` (H10, architectural)** — `equip_joker` signature widened to `equip_joker(self, joker: Joker, run: BelAtroRun | None = None) -> bool`. When `run` is provided, `joker.on_purchase(run)` fires after the slot append. No current partner joker defines `on_purchase`, so no behaviour changes today — this is forward-looking infrastructure. The catalogue called this "latent"; equipping through this path will now invoke purchase-time effects consistently with the main joker slot equip path. Note: `equip_joker` has zero callers in the current codebase (the shop path equips through a different surface), so this fix is doubly forward-looking. Three regression tests in `tests/belatro/test_partner_trust.py::TestEquipJokerOnPurchase`.
+- **`src/belote/game.py::advance_turn` (M4) — dead code deleted.** Zero callers across `src/` and `tests/`. The function was a one-line `replace(state, turn=state.turn.next_seat())` helper that no live code used.
+- **Tests**: 551 → 568 (+17). Five existing `test_north_*_returns_none` tests in `test_belatro.py` were flipped to assert the new team-aware behavior (these tests had encoded the H1 bug as a contract — they are not test regressions but contract updates).
+- **Strict gates**: pytest 568/568, mypy 0 errors (76 source files), ruff 0 violations.
+- **Version markers bumped**: `pyproject.toml`, `src/belote/__init__.py`.
+- **Docs bumped**: `CHANGELOG.md` (this entry), `README.md` "What's new in 3.4.2", `DEVELOPMENT.md` baseline.
+- **Still deferred**: **H2** (`LEgoiste` partner-trick nullification) was flagged as needing a spec decision in 3.4.1 and was not in any tier the user picked for 3.4.2 — the comment says "Partner's points are nullified" which reads as intent, so a fix would invert documented behavior. Stays on the deferred list pending a spec call. `LeRebelle` `on_belote` seat/team gating (noted above) is similarly deferred.
+
+## [3.4.1] - 2026-05-11
+
+Audit-verification-only release — **no code changes**. A fresh external LLM audit ("Comprehensive Audit Report — Belote CLI v3.4.0") produced 26 prioritized findings (4 Critical, 10 High, 12 Medium) plus a test-coverage section and a performance section. Direct verification against the source confirmed **7 real bugs** (3 Critical, 4 High), **1 architectural latent issue** (no current consumer but fragile for future work), and **1 disputed claim** that needs a spec call before any fix. **8 claims were false positives** under verification (intent inversion, defense-in-depth confused for bugs, or stale call-graph reading). Mediums spot-checked: 1 real (dead code), 4 false. The point of cutting a release for verification-only work is to (a) lock the false-positive catalogue against re-investigation next cycle and (b) record the confirmed-bug roadmap before any fixes land. Plan/verification file at `/home/mrrobot/.claude/plans/check-on-this-audit-polished-kite.md`. Test count, mypy, ruff results unchanged from 3.4.0 (no source code touched).
+
+### Confirmed bugs — deferred to 3.4.2+
+
+These were verified against current code and are real. None are fixed in 3.4.1; they are catalogued here so the next session has a vetted target list.
+
+**Critical**
+- **`src/belote/ai.py:104-108` (C1) — AI sees partner's full hand regardless of `hide_partner_hand`.** `AIMemory.update_memory()` unconditionally populates `self.memory.partner_hand` from `state.hand_of(partner)`. The boss flag `hide_partner_hand` (declared at `game.py:177`, set by Le Fantôme Partenaire at `belatro/run/boss.py:171`) is only read by display code at `belatro/main.py:291`, never by the AI memory path. Net effect: under Le Fantôme Partenaire the human is blinded to partner's hand but the AI continues to play with perfect partner information.
+- **`src/belote/gameflow.py:196-198` (C3) — Dix de Der announcement uses non-Rupture-aware winner.** The announcement calls `trick_winner_seat()` directly; the La Rupture-aware helper `compute_trick_winners()` (defined at `game.py:756`, used by `scoring.py`) is the one that honours `boss_modifiers.no_consecutive_team_wins`. Under La Rupture the announced "Dix de Der goes to TEAM X" line can name a team that is not actually credited the +10 in scoring.
+- **`src/belote/ai.py:533` (C4) — `opp_trumps` formula conflates "remaining trump" with "opponent trump".** Current line is `opp_trumps = 8 - sum(1 for c in self.memory.played if c.suit == trump)`. This counts trump still anywhere in unrevealed hands — including South's own hand (already computed as `my_trumps` on line 532) and partner's hand (visible at `self.memory.partner_hand`). The variable is then compared against `my_trumps` in `_score_leading_strategy`, so the over-count biases Hard AI's trump-coverage decisions when the AI itself is holding trump.
+
+**High**
+- **`src/belote/belatro/items/jokers/contract.py` + `trick_timing.py` (H1, partial) — 8 jokers still gate on `event.winner == Seat.SOUTH`.** 3.2.0 fixed La Sentinelle and Le Dernier Mot to use `team_of(event.winner) == 0`. The same anti-pattern survives in: `LIdeologue` (contract.py:21), `LeFanatique` (contract.py:45), `LeDiplomate` (contract.py:62), `LePatriote` (contract.py:81), `LIllusionniste` (contract.py:128), `LePremierSang` (trick_timing.py:26/30), `LeSergent` (trick_timing.py:46), `LExecuteur` (trick_timing.py:82). All silently no-op when North takes the relevant trick. (The audit also named `LeRebelle` but I could not find it among the South-only checks — likely a hallucinated joker name; verify before touching.)
+- **`src/belote/belatro/run/ante_themes.py:73-76` (H4) — TournoiAnte bonus is not the advertised 50%.** Effect uses `run.economy.add_money(max(1, run.economy.bonus_per_round // 2 + 2))`. The comment claims "+50% bonus on top of whatever payout the round produced", but the formula is a flat function of `bonus_per_round` (the per-round flat-bonus economy field), not 50% of actual round payout. Either compute true 50% of the round delta or rewrite the comment.
+- **`src/belote/belatro/progression/save.py:94` (H5) — `load_profile` loses default unlocks.** Line reads `unlocked_ids=data.get("unlocked_ids", [])`. The `Profile` dataclass default is `["le_classique", "le_courageux", "l_econome"]`. A saved profile missing the key (older saves, manual edits, partial writes) reloads with no unlocks. The exception branch correctly returns `Profile()` with defaults; only the happy path corrupts.
+- **`src/belote/main.py:230-231` (H7) — Win operator mismatch on ties.** Main loop uses `won=(ns >= target and ns >= ew)`; menu summary at `ui/menu.py:344` uses `winner = "NS" if ns > ew else "EW"`. On an exact tie at target, main records a NS win while the visible summary attributes the round to EW.
+
+### Architectural / latent
+
+- **`src/belote/belatro/partner/partner_state.py:34-38` (H10) — `equip_joker` skips `on_purchase`.** The method simply appends to `self.jokers`; no `on_purchase()` hook is invoked. No current partner joker defines `on_purchase()`, so this is latent today — but any future partner joker with a purchase-time effect (a la `LeTraitre` in `corrupted.py`) will silently fail to fire when equipped through this path. Document or wire the hook before adding such a joker.
+- **`src/belote/game.py:1007` (M4) — `advance_turn()` is dead code.** Defined, never called. Safe to delete.
+
+### Needs spec decision before fixing
+
+- **`src/belote/belatro/items/jokers/corrupted.py:56-62` (H2) — `LEgoiste` nullifies the entire partner trick.** On `event.winner == Seat.NORTH` the joker returns `JokerResult(add_chips=-event.card_points)`, where `event.card_points` is the FULL trick's card points (South's contribution included). The audit reads this as a bug (only partner's own contribution should be subtracted); the code comment reads "Partner's points are nullified", implying *intentional* full-trick nullification. Resolve which is canonical before changing the formula — and either way add a test that pins the intended behaviour.
+
+### Verified clean — agent claims that did NOT survive source verification
+
+Catalogued so they aren't re-investigated next cycle.
+
+- **(C2) "No round-2 bid validation in `place_bid`"** — `place_bid` itself does not validate, but the human-input path filters the up-card suit out of the options menu at `ui/prompts.py:132-135`, and the AI path uses `exclude=forbidden` at `ai.py:137`. Defense-in-depth gap (a programmatic caller could pass a bad bid), not a live bug.
+- **(H3) "`LeFou` fallback is dead code"** — `tarots.py:119` checks `if last_id and last_id != self.id`. `last_consumable_id` defaults to `None` and `getattr(item, "id", None)` can also set it to `None`, so the fallback fires on the first consumable of a run and on self-copy attempts. Live code.
+- **(H6) "Signal handlers skip `finally` and lose stats"** — `main.py:127-129` handler does call `sys.exit(0)`, which bypasses the `finally`. But `flush_stats()` is also invoked at `main.py:160` (quit path) and `main.py:235` (game-over). The data-loss window is narrow (SIGINT before any flush in the same session). Cosmetic at best.
+- **(H8) "`zip(..., strict=False)` causes silent data loss in scoring"** — `winners` at `scoring.py:461,498` is produced by `compute_trick_winners(state, ...)`, which is exactly one entry per completed trick by construction. The length invariant holds; `strict=False` is defensive noise, not a live bug.
+- **(H9) "`_CARD_TO_ID[c]` will KeyError on BelAtro jokers"** — `_CARD_TO_ID` is built from `make_deck()` (32 standard cards). BelAtro jokers are `Joker` objects living in `state._joker_state`, never inserted into `hand`. No reachable code path produces the KeyError.
+- **(M2) "Frozen `GameState` contains mutable `_rng`"** — `_rng` is declared with `field(default_factory=random.Random, compare=False, repr=False)` — the same documented pattern used for `_joker_state` (see comment at `game.py:214-217`). Intentional; the contract is "always rebuild via `dataclasses.replace`".
+- **(M8) "`card in self.memory.partner_hand` is always False"** — `partner_hand` is populated at `ai.py:107-108` during PLAYING/SCORING phase. The check at line 660 is live and prevents double-scoring visible partner cards.
+- **(M12) "`mult == float(int(mult))` float precision bug"** — Intentional optimisation in `belatro/core/scoring.py:254`: when the multiplier is exactly integral, take the lossless integer-multiplication path; else accept float multiplication. Correct logic.
+
+### Audit calibration notes (for the next pass)
+
+The audit's overall scaffolding (file:line citations, severity tiers, action plan) was well-presented but had a recurring failure mode: **flagging "suspicious-looking" patterns without verifying behaviour in context**. Concrete recurring misses worth feeding back to the auditing model:
+
+1. **Defense-in-depth confused with bugs** (C2, H8, H9). When the audited line lacks an obvious check, the audit should trace one hop up the call graph before declaring "no validation". In all three cases the invariant is enforced at the caller.
+2. **Intent inversion** (H2, M2, M12). When code is paired with a comment that describes the exact behaviour the audit flags as wrong, that's evidence of intent, not a bug. Reading the adjacent comment before flagging would have caught these.
+3. **Self-cancelling dead-code claims** (H3). The audit claimed "`last_consumable_id` is always set before `use()` is called". True — but it can be set to `None`, and the consumer's guard is `if last_id and ...`. Surface-level static reasoning without tracing the guard.
+4. **Headline metrics with no numbers**. The "Current Health" table lists Tests / Lint / Types / Version rows with no values. The version row is checkable; the others were left blank, which makes the table cosmetic.
+5. **Joker name drift** (H1). `LeRebelle` appeared in the South-only list but is not among the actual offenders. Probable hallucination.
+
+### Internal
+
+- **No source code touched.** Test count, mypy strictness, ruff cleanliness all unchanged from 3.4.0: pytest 551/551, mypy 0 errors (76 files), ruff 0 violations.
+- **Version markers bumped**: `pyproject.toml`, `src/belote/__init__.py`.
+- **Docs bumped**: `README.md` "What's new in 3.4.1" section, `DEVELOPMENT.md` baseline.
+- **Roadmap for 3.4.2**: the 7 confirmed bugs above (C1, C3, C4, H1×8, H4, H5, H7) plus the H10/M4 cleanups. Tier 1 (C1/C3/C4) closes the AI-fairness gap; Tier 2 (H1/H4/H5/H7) closes the remaining verified issues.
+
 ## [3.4.0] - 2026-05-10
 
 Audit + endless-mode reliability + HUD polish release. A fresh three-agent codebase pass (classic engine / BelAtro layer / UI + I/O) produced ~80 candidate findings. Direct verification against the source rejected ~95% as false positives or by-design patterns. The five surviving issues plus two **new** bugs uncovered during follow-up verification of endless mode and classic game flow are fixed here. Two HUD features land alongside (joker pip strip with edition glow, synergy tooltip, polished trust bar). 551 tests passing (up from 549), ruff and mypy strict still clean. Plan file at `/home/mrrobot/.claude/plans/bug-hunt-code-performance-fizzy-summit.md`.

{belote_cli-3.4.0 → belote_cli-3.5.0}/DEVELOPMENT.md

@@ -84,14 +84,17 @@ PYTHONPATH=src mypy --strict src/
 # Linting (0 violations expected)
 ruff check src/ tests/
 
-# Full test suite (551 tests expected)
+# Full test suite (592 tests expected)
 PYTHONPATH=src pytest
 ```
 
-Current baseline (3.4.0):
-- **mypy**: 0 errors (strict mode, 76 files)
+Current baseline (3.5.0):
+- **mypy**: 0 errors (strict mode, 77 files — `belatro/ui/consumables.py` is new)
 - **ruff**: 0 violations
-- **pytest**: 551 tests, 0 failures
+- **pytest**: 592 tests, 0 failures
+- 3.5.0 lands a 15-fix audit pass over the classic engine + BelAtro layer: C1 (consumables UI + Le Fou ordering), H1 (run-summary fsync), H2 (Key.EOF distinct from ESC), H3 (EventBus round-scope docs + `clear()`), M1 (declaration first-announcer tie-break), M3 (typed `RoundEndEvent.breakdown`), M4 (deprecate `partner_jokers_double`), M5 (SA belote invariant hoisted), L1 (`patch_trick_card` single-write), L2/L3 (doc pins), M2 (3 new benchmark micro-tests), P1/P2/P3 (perf hoist + cache-key + accumulator-profile analyses). +24 regression tests across 5 new files; 0 existing tests modified. Plan file at `/home/mrrobot/.claude/plans/bug-hunt-code-performance-tidy-meerkat.md`.
+- 3.4.2 closed the 3.4.1 catalogue. All 7 confirmed bugs (C1 AI cheat under `hide_partner_hand`, C3 Dix de Der under La Rupture, C4 `opp_trumps` formula + TA total, H1 8 jokers seat→team, H4 TournoiAnte true 50%, H5 `load_profile` default unlocks, H7 classic-mode tie operator) plus H10 (`equip_joker` wires `on_purchase`) and M4 (delete dead `advance_turn`) shipped in 3.4.2. +17 regression tests (551 → 568). H2 (`LEgoiste` partner-trick nullification) remains deferred — needs a spec call between code-comment intent and the audit's reading.
+- 3.4.1 was **documentation-only** — an external LLM audit was verified against the source. 7 confirmed bugs were catalogued in `CHANGELOG.md` as deferred to 3.4.2+; 8 audit claims were rejected as false positives and are listed in the "Verified clean" section to block re-investigation. No source code changed in 3.4.1.
 - 3.4.0 covered: A1 `BidMadeEvent` double-fire on coinche paths (HIGH), E1 endless mode replaying Ante 8 Boss instead of advancing to the first scaled cycle (HIGH), E2 classic-mode tie-breaker overridden by main loop (HIGH), A2 termios raw-mode leak on SSH drop (MED), A3 shop selection index off-by-one after reroll (MED), A5 prompts.py dead return (LOW). Plus HUD additions: joker pip strip with edition glow (B.3), synergy tooltip (B.4), four-tier trust bar with tier glyph (B.5). Score gutter (B.2) and trick-lane compass (B.1) intentionally deferred — they touch `ui/render.py`'s vertical-centering logic and want a dedicated session.
 
 Run all gates before committing:

{belote_cli-3.4.0 → belote_cli-3.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: belote-cli
-Version: 3.4.0
+Version: 3.5.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,6 +45,37 @@ 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.5.0
+
+- **C1 — BelAtro consumables are now usable.** Pre-3.5.0 `BelAtroRun.consume()` was defined but never called from any UI, so every Tarot purchased in the shop and every directly-bought Planet accumulated in `run.consumables` with no way to activate them — only the voucher-gated Forge-Tierce path could level a planet. New `ConsumablesOverlay` (`belatro/ui/consumables.py`) is reachable from the shop via the `C` key; the hint line now shows `C: Consumables (N)`. Surfacing this path also caught a latent Le Fou bug: `consume()` advanced `last_consumable_id` to the *current* item before calling `item.use()`, so Le Fou read its own id and fell through to fallback — fixed by reordering and making Le Fou transparent so a second Le Fou keeps copying the same source.
+- **H1 — `run_summary.py` writes are durable.** Added `flush + fsync` inside the `with` block. A crash mid-write no longer leaves a truncated JSONL line.
+- **H2 — `Key.EOF` distinct from `Key.ESC`.** A closed stdin (pipe / headless harness) used to make every prompt loop spin: ESC popped one level, the loop re-read stdin, got another ESC, popped again. Now `KeyReader.read()` returns `Key.EOF` on empty-read; every consumer accepts it like ESC; `prompt_card` / `prompt_bid` exit cleanly instead of spinning.
+- **H3 — `EventBus` round-scope invariant documented + `clear()` added.** Module docstring now spells out the contract that today is silently enforced by `drive_round()` creating a fresh bus per round.
+- **M1 — Tied carrés / sequences go to the first announcer.** `resolve_declarations` gains an optional `taker: Seat | None` parameter; tied declarations now walk the announce order (taker → clockwise) and award the first matching seat, matching standard Belote-Coinché. Legacy "cancel" behaviour preserved when `taker` not supplied.
+- **M3 — `RoundEndEvent.breakdown` is properly typed** as `ScoringBreakdown`. Removed 9 defensive `getattr(event.breakdown, "is_failed", False)` patterns; `taker_seat` corrected to `Seat | None`.
+- **M4 — `partner_jokers_double` legacy flag is now deprecated.** A `DeprecationWarning` fires when both it and the tier scaling are set; flag slated for removal in 4.0.
+- **M5 — SA belote invariant hoisted to contract level.** Was previously only asserted inside the capot branch.
+- **L1 — `patch_trick_card` batches its `sys.stdout.write` calls.** Eliminates a torn-frame window on signal-interruptible terminals.
+- **L2/L3 — Documentation pins**: `BELOTE_A11Y` is read once at import; `BelAtroRun.consumables/jokers/vouchers` are intentionally mutable.
+- **M2 — Benchmark coverage expanded.** Three new micro-benchmarks: warm-cache `legal_cards`, `trick_card_points`, and the AI legality-filter step. The pre-existing cold-cache `legal_cards` benchmark is now labelled accordingly.
+- **P1/P2/P3 — Performance pass.** `trick_card_points` flag-hoist (already at ~2μs/call — sub-μs gain). `legal_cards` cache-key analysis: warm/cold gap is dominated by key-build, not lru_cache lookup; no actionable optimisation without changing the hand representation — documented to prevent re-investigation. `ScoreAccumulator.update_state` profile shows `dataclasses.replace` is 65% of cost; frozen-GameState invariant is load-bearing, accumulator is ~0.5ms/round — acceptable.
+- **Verified false positives** (catalogued so they aren't re-raised): Belote/Rebelote partner non-announcement, Capot Rupture false-positive, AI `partner_hand` undo clearing, Negative-edition slot rollback, and `boss.id == "..."` branching — five agent flags that didn't survive source verification.
+- **Tests + gates**: 592 tests (up from 568, +24 regression tests across 5 new files, 0 existing tests modified). pytest 592/592 green.
+
+## What's new in 3.4.2
+
+- **The 3.4.1 catalogue is closed.** All 7 confirmed bugs plus the H10 architectural cleanup and the M4 dead-code deletion ship here. **C1 — AI cheating under Le Fantôme Partenaire:** AI memory now respects `hide_partner_hand`; the boss flag's visibility cost is paid by both sides. **C3 — Dix de Der announcement under La Rupture:** the 8th-trick "Team X" line now uses the Rupture-aware `compute_trick_winners` helper, so the named team matches what scoring credits. **C4 — `opp_trumps` formula:** subtracts South's own trumps, played trumps, and partner-visible trumps; under Tout Atout the total switches to 32 (every card is a trump). **H1 — 8 BelAtro jokers:** `LIdeologue`, `LeFanatique`, `LeDiplomate`, `LePatriote`, `LIllusionniste`, `LePremierSang`, `LeSergent`, `LExecuteur` now gate on `team_of(event.winner) == 0` instead of `event.winner == Seat.SOUTH`, matching the 3.2.0 fix that landed `LaSentinelle` and `LeDernierMot`. **H4 — TournoiAnte:** `on_blind_won` now receives `blind_payout` and pays a true 50% (was a flat function of `bonus_per_round`). **H5 — `load_profile`:** saves missing the `unlocked_ids` key fall back to the Profile dataclass default starter unlocks. **H7 — classic win attribution on ties:** `update_stats_game` operator aligned to `ns > ew` so the stats line agrees with `menu.py`'s visible winner on an exact tie at target.
+- **Architectural / cleanup.** `equip_joker` accepts an optional `run` and fires `on_purchase` when provided (forward-looking — no current partner joker has a purchase hook). Dead `advance_turn()` deleted from `game.py`.
+- **Still deferred** (need spec calls, not implementation work): H2 `LEgoiste` partner-trick nullification (comment vs. audit reading); `LeRebelle` `on_belote` seat/team gating (separate code path from H1).
+- **Tests + gates** — 568 tests (up from 551, +17 regressions). Five existing `test_north_*_returns_none` tests in `test_belatro.py` were flipped to assert the new team-aware behaviour (they had encoded the H1 bug as a contract). Strict gates still clean: pytest 568/568, mypy 0 errors (76 files), ruff 0 violations.
+
+## What's new in 3.4.1
+
+- **Audit verification pass — no code changes.** An external LLM audit ("Comprehensive Audit Report — Belote CLI v3.4.0") flagged 4 Critical, 10 High, and 12 Medium issues. Direct verification against the source confirmed **7 real bugs** (3 Critical, 4 High), **1 architectural latent issue**, and **1 disputed claim** needing a spec decision; **8 claims were false positives**. The roadmap and the false-positive catalogue are recorded in `CHANGELOG.md` so the next session has a vetted target list and the rejected claims aren't re-investigated. *Note (3.4.2): the catalogue is now closed — all 7 confirmed bugs plus H10 and M4 are fixed in 3.4.2. The 3.4.1 entry is preserved as a historical record of the verification-only release.*
+- **Confirmed bugs deferred to 3.4.2+**: AI ignoring `hide_partner_hand` (C1), Dix de Der announcement not La Rupture-aware (C3), AI `opp_trumps` over-count (C4), 8 BelAtro jokers still gated on South instead of NS team (H1), TournoiAnte bonus not actually 50% (H4), `load_profile` losing default unlocks (H5), classic-mode tie-break operator mismatch with the menu summary (H7). Plus latent: `equip_joker` skipping `on_purchase` (H10), and a dead `advance_turn()` (M4).
+- **Audit calibration findings** — recurring failure modes documented for the next pass: defense-in-depth confused with bugs (C2/H8/H9), intent inversion against adjacent comments (H2/M2/M12), self-cancelling dead-code claims (H3), and joker-name hallucination (H1's `LeRebelle`). Useful as feedback to the auditing model.
+- **No behavioural changes.** Test count, mypy strict, ruff all unchanged from 3.4.0: pytest 551/551, mypy 0 errors (76 files), ruff 0 violations.
+
 ## What's new in 3.4.0
 
 - **BelAtro joker correctness** — `BidMadeEvent` no longer double-fires `on_bid` joker handlers on coinche paths. Pre-3.4.0 the player-coinche, AI-partner-coinche, `auto_coinche` boss, and `start_coinched` deck-mod paths all re-emitted the same bid event a second time with the resolved `coinche_level`, so on_bid jokers (Le Passeur today, anything new tomorrow) were silently invoked twice for the same bid. Fixed via a `re_emit: bool` field on the event; refreshes update `joker_state["contract"]` but skip joker firing.
@@ -337,7 +368,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 (528 tests)
+├── tests/             # Comprehensive test suite (568 tests)
 ├── scripts/           # Performance benchmarks
 ├── pyproject.toml      # Build system and dev dependencies (ruff/mypy)
 ├── LICENSE             # MIT License
@@ -353,14 +384,14 @@ belote/
 PYTHONPATH=src pytest
 ```
 
-Currently **528 tests** passing with 100% coverage on game-logic modules.
+Currently **568 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**: 528/528 passed
+- **pytest**: 568/568 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.4.0 → belote_cli-3.5.0}/README.md

@@ -2,6 +2,37 @@
 
 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.5.0
+
+- **C1 — BelAtro consumables are now usable.** Pre-3.5.0 `BelAtroRun.consume()` was defined but never called from any UI, so every Tarot purchased in the shop and every directly-bought Planet accumulated in `run.consumables` with no way to activate them — only the voucher-gated Forge-Tierce path could level a planet. New `ConsumablesOverlay` (`belatro/ui/consumables.py`) is reachable from the shop via the `C` key; the hint line now shows `C: Consumables (N)`. Surfacing this path also caught a latent Le Fou bug: `consume()` advanced `last_consumable_id` to the *current* item before calling `item.use()`, so Le Fou read its own id and fell through to fallback — fixed by reordering and making Le Fou transparent so a second Le Fou keeps copying the same source.
+- **H1 — `run_summary.py` writes are durable.** Added `flush + fsync` inside the `with` block. A crash mid-write no longer leaves a truncated JSONL line.
+- **H2 — `Key.EOF` distinct from `Key.ESC`.** A closed stdin (pipe / headless harness) used to make every prompt loop spin: ESC popped one level, the loop re-read stdin, got another ESC, popped again. Now `KeyReader.read()` returns `Key.EOF` on empty-read; every consumer accepts it like ESC; `prompt_card` / `prompt_bid` exit cleanly instead of spinning.
+- **H3 — `EventBus` round-scope invariant documented + `clear()` added.** Module docstring now spells out the contract that today is silently enforced by `drive_round()` creating a fresh bus per round.
+- **M1 — Tied carrés / sequences go to the first announcer.** `resolve_declarations` gains an optional `taker: Seat | None` parameter; tied declarations now walk the announce order (taker → clockwise) and award the first matching seat, matching standard Belote-Coinché. Legacy "cancel" behaviour preserved when `taker` not supplied.
+- **M3 — `RoundEndEvent.breakdown` is properly typed** as `ScoringBreakdown`. Removed 9 defensive `getattr(event.breakdown, "is_failed", False)` patterns; `taker_seat` corrected to `Seat | None`.
+- **M4 — `partner_jokers_double` legacy flag is now deprecated.** A `DeprecationWarning` fires when both it and the tier scaling are set; flag slated for removal in 4.0.
+- **M5 — SA belote invariant hoisted to contract level.** Was previously only asserted inside the capot branch.
+- **L1 — `patch_trick_card` batches its `sys.stdout.write` calls.** Eliminates a torn-frame window on signal-interruptible terminals.
+- **L2/L3 — Documentation pins**: `BELOTE_A11Y` is read once at import; `BelAtroRun.consumables/jokers/vouchers` are intentionally mutable.
+- **M2 — Benchmark coverage expanded.** Three new micro-benchmarks: warm-cache `legal_cards`, `trick_card_points`, and the AI legality-filter step. The pre-existing cold-cache `legal_cards` benchmark is now labelled accordingly.
+- **P1/P2/P3 — Performance pass.** `trick_card_points` flag-hoist (already at ~2μs/call — sub-μs gain). `legal_cards` cache-key analysis: warm/cold gap is dominated by key-build, not lru_cache lookup; no actionable optimisation without changing the hand representation — documented to prevent re-investigation. `ScoreAccumulator.update_state` profile shows `dataclasses.replace` is 65% of cost; frozen-GameState invariant is load-bearing, accumulator is ~0.5ms/round — acceptable.
+- **Verified false positives** (catalogued so they aren't re-raised): Belote/Rebelote partner non-announcement, Capot Rupture false-positive, AI `partner_hand` undo clearing, Negative-edition slot rollback, and `boss.id == "..."` branching — five agent flags that didn't survive source verification.
+- **Tests + gates**: 592 tests (up from 568, +24 regression tests across 5 new files, 0 existing tests modified). pytest 592/592 green.
+
+## What's new in 3.4.2
+
+- **The 3.4.1 catalogue is closed.** All 7 confirmed bugs plus the H10 architectural cleanup and the M4 dead-code deletion ship here. **C1 — AI cheating under Le Fantôme Partenaire:** AI memory now respects `hide_partner_hand`; the boss flag's visibility cost is paid by both sides. **C3 — Dix de Der announcement under La Rupture:** the 8th-trick "Team X" line now uses the Rupture-aware `compute_trick_winners` helper, so the named team matches what scoring credits. **C4 — `opp_trumps` formula:** subtracts South's own trumps, played trumps, and partner-visible trumps; under Tout Atout the total switches to 32 (every card is a trump). **H1 — 8 BelAtro jokers:** `LIdeologue`, `LeFanatique`, `LeDiplomate`, `LePatriote`, `LIllusionniste`, `LePremierSang`, `LeSergent`, `LExecuteur` now gate on `team_of(event.winner) == 0` instead of `event.winner == Seat.SOUTH`, matching the 3.2.0 fix that landed `LaSentinelle` and `LeDernierMot`. **H4 — TournoiAnte:** `on_blind_won` now receives `blind_payout` and pays a true 50% (was a flat function of `bonus_per_round`). **H5 — `load_profile`:** saves missing the `unlocked_ids` key fall back to the Profile dataclass default starter unlocks. **H7 — classic win attribution on ties:** `update_stats_game` operator aligned to `ns > ew` so the stats line agrees with `menu.py`'s visible winner on an exact tie at target.
+- **Architectural / cleanup.** `equip_joker` accepts an optional `run` and fires `on_purchase` when provided (forward-looking — no current partner joker has a purchase hook). Dead `advance_turn()` deleted from `game.py`.
+- **Still deferred** (need spec calls, not implementation work): H2 `LEgoiste` partner-trick nullification (comment vs. audit reading); `LeRebelle` `on_belote` seat/team gating (separate code path from H1).
+- **Tests + gates** — 568 tests (up from 551, +17 regressions). Five existing `test_north_*_returns_none` tests in `test_belatro.py` were flipped to assert the new team-aware behaviour (they had encoded the H1 bug as a contract). Strict gates still clean: pytest 568/568, mypy 0 errors (76 files), ruff 0 violations.
+
+## What's new in 3.4.1
+
+- **Audit verification pass — no code changes.** An external LLM audit ("Comprehensive Audit Report — Belote CLI v3.4.0") flagged 4 Critical, 10 High, and 12 Medium issues. Direct verification against the source confirmed **7 real bugs** (3 Critical, 4 High), **1 architectural latent issue**, and **1 disputed claim** needing a spec decision; **8 claims were false positives**. The roadmap and the false-positive catalogue are recorded in `CHANGELOG.md` so the next session has a vetted target list and the rejected claims aren't re-investigated. *Note (3.4.2): the catalogue is now closed — all 7 confirmed bugs plus H10 and M4 are fixed in 3.4.2. The 3.4.1 entry is preserved as a historical record of the verification-only release.*
+- **Confirmed bugs deferred to 3.4.2+**: AI ignoring `hide_partner_hand` (C1), Dix de Der announcement not La Rupture-aware (C3), AI `opp_trumps` over-count (C4), 8 BelAtro jokers still gated on South instead of NS team (H1), TournoiAnte bonus not actually 50% (H4), `load_profile` losing default unlocks (H5), classic-mode tie-break operator mismatch with the menu summary (H7). Plus latent: `equip_joker` skipping `on_purchase` (H10), and a dead `advance_turn()` (M4).
+- **Audit calibration findings** — recurring failure modes documented for the next pass: defense-in-depth confused with bugs (C2/H8/H9), intent inversion against adjacent comments (H2/M2/M12), self-cancelling dead-code claims (H3), and joker-name hallucination (H1's `LeRebelle`). Useful as feedback to the auditing model.
+- **No behavioural changes.** Test count, mypy strict, ruff all unchanged from 3.4.0: pytest 551/551, mypy 0 errors (76 files), ruff 0 violations.
+
 ## What's new in 3.4.0
 
 - **BelAtro joker correctness** — `BidMadeEvent` no longer double-fires `on_bid` joker handlers on coinche paths. Pre-3.4.0 the player-coinche, AI-partner-coinche, `auto_coinche` boss, and `start_coinched` deck-mod paths all re-emitted the same bid event a second time with the resolved `coinche_level`, so on_bid jokers (Le Passeur today, anything new tomorrow) were silently invoked twice for the same bid. Fixed via a `re_emit: bool` field on the event; refreshes update `joker_state["contract"]` but skip joker firing.
@@ -294,7 +325,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 (528 tests)
+├── tests/             # Comprehensive test suite (568 tests)
 ├── scripts/           # Performance benchmarks
 ├── pyproject.toml      # Build system and dev dependencies (ruff/mypy)
 ├── LICENSE             # MIT License
@@ -310,14 +341,14 @@ belote/
 PYTHONPATH=src pytest
 ```
 
-Currently **528 tests** passing with 100% coverage on game-logic modules.
+Currently **568 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**: 528/528 passed
+- **pytest**: 568/568 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.4.0 → belote_cli-3.5.0}/pyproject.toml

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

{belote_cli-3.4.0 → belote_cli-3.5.0}/scripts/benchmark.py

@@ -149,21 +149,103 @@ def benchmark_deal(iterations: int = 1000) -> float:
 
 def benchmark_legal_cards(iterations: int = 1000) -> float:
     from belote.game import legal_cards, clear_legal_cards_cache, replace
-    print(f"Benchmarking legal_cards() over {iterations} iterations...")
-    
+    print(f"Benchmarking legal_cards() (cache cleared per call) over {iterations} iterations...")
+
     state = new_game()
     state = start_round(state, random.Random(42))
     state = replace(state, phase=Phase.PLAYING, trump=Suit.SPADES, turn=Seat.SOUTH)
-    
+
     times = []
     for _ in range(iterations):
         clear_legal_cards_cache()
         start = time.perf_counter()
         _ = legal_cards(state, Seat.SOUTH)
         times.append(time.perf_counter() - start)
-        
+
+    avg = statistics.mean(times) * 1000
+    print(f"  Legal Cards (cold) Time: {avg:.3f}ms")
+    return avg
+
+
+def benchmark_legal_cards_cached(iterations: int = 1000) -> float:
+    """Measure the cache-hit path. Production gameplay reuses the cache across
+    multiple AI rollouts and HUD redraws for the same `(state, seat)` pair —
+    `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
+    print(f"Benchmarking legal_cards() (warm cache) over {iterations} iterations...")
+
+    state = new_game()
+    state = start_round(state, random.Random(42))
+    state = replace(state, phase=Phase.PLAYING, trump=Suit.SPADES, turn=Seat.SOUTH)
+    clear_legal_cards_cache()
+    legal_cards(state, Seat.SOUTH)  # warm the cache once
+
+    times = []
+    for _ in range(iterations):
+        start = time.perf_counter()
+        _ = legal_cards(state, Seat.SOUTH)
+        times.append(time.perf_counter() - start)
+
+    avg = statistics.mean(times) * 1000
+    print(f"  Legal Cards (warm) Time: {avg:.3f}ms")
+    return avg
+
+
+def benchmark_trick_scoring(iterations: int = 1000) -> float:
+    """Measure `trick_card_points` — called 8× per round from `game.py::play_card`
+    (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.scoring import trick_card_points
+
+    print(f"Benchmarking trick_card_points() over {iterations} iterations...")
+
+    state = new_game()
+    state = replace(state, trump=Suit.SPADES, contract="normal", taker=Seat.SOUTH)
+    trick = (
+        TrickCard(Seat.SOUTH, Card(Suit.SPADES, Rank.JACK)),
+        TrickCard(Seat.WEST, Card(Suit.SPADES, Rank.NINE)),
+        TrickCard(Seat.NORTH, Card(Suit.HEARTS, Rank.ACE)),
+        TrickCard(Seat.EAST, Card(Suit.SPADES, Rank.SEVEN)),
+    )
+
+    times = []
+    for _ in range(iterations):
+        start = time.perf_counter()
+        _ = trick_card_points(state, trick)
+        times.append(time.perf_counter() - start)
+
+    avg = statistics.mean(times) * 1000
+    print(f"  Trick Scoring Time: {avg:.3f}ms")
+    return avg
+
+
+def benchmark_ai_legality_filter(iterations: int = 500) -> float:
+    """Isolate the legal-move filter step inside `AIPlayer.decide_card`. The
+    AI calls `legal_cards` once per decision; an unrepresentative cold-cache
+    benchmark above would over-attribute AI time to legality checks.
+    """
+    from belote.game import legal_cards, replace
+    print(f"Benchmarking AI legality filter over {iterations} iterations...")
+
+    state = new_game()
+    state = start_round(state, random.Random(42))
+    state = replace(state, phase=Phase.PLAYING, trump=Suit.SPADES, taker=Seat.SOUTH, turn=Seat.NORTH)
+
+    times = []
+    for _ in range(iterations):
+        start = time.perf_counter()
+        legal = legal_cards(state, Seat.NORTH)
+        # The filter step: callers usually check membership in a 6-8 card hand.
+        _ = [c for c in state.hands[Seat.NORTH.value] if c in legal]
+        times.append(time.perf_counter() - start)
+
     avg = statistics.mean(times) * 1000
-    print(f"  Legal Cards Time: {avg:.3f}ms")
+    print(f"  Legality Filter Time: {avg:.3f}ms")
     return avg
 
 
@@ -180,6 +262,9 @@ def run_benchmarks() -> None:
     benchmark_scoring()
     benchmark_deal()
     benchmark_legal_cards()
+    benchmark_legal_cards_cached()
+    benchmark_trick_scoring()
+    benchmark_ai_legality_filter()
     print("========================================")
 
 

{belote_cli-3.4.0 → belote_cli-3.5.0}/src/belote/__init__.py

@@ -1,3 +1,3 @@
-__version__ = "3.4.0"
+__version__ = "3.5.0"
 
 __all__ = ["__version__"]

{belote_cli-3.4.0 → belote_cli-3.5.0}/src/belote/a11y.py

@@ -5,6 +5,11 @@ line to stderr — readable by terminal screen readers such as Orca, NVDA in WSL
 or VoiceOver via iTerm2. Disabled by default so it doesn't pollute output for
 sighted players.
 
+**Invariant**: ``BELOTE_A11Y`` is read **once at module import**. Toggling the
+env var mid-session has no effect on production code — restart the process
+to enable/disable. Tests that mutate the env may call ``_refresh_enabled_from_env()``
+to re-read the cached flag.
+
 Hooked from gameflow.py (card plays, trick winners, round results) and from
 belatro/main.py (boss reveal, ante advance, run won/lost). Each hook is a
 single line — no rich formatting — so the screen reader can speak it cleanly.

{belote_cli-3.4.0 → belote_cli-3.5.0}/src/belote/ai.py

@@ -102,8 +102,10 @@ class AIPlayer:
         # In this implementation, AI tracks what it can see
         p = partner(self.seat)
         self.memory.partner_hand.clear()
-        if state.phase in (Phase.PLAYING, Phase.SCORING):
-            # Partner's remaining cards
+        if (
+            state.phase in (Phase.PLAYING, Phase.SCORING)
+            and not state.boss_modifiers.hide_partner_hand
+        ):
             for card in state.hand_of(p):
                 self.memory.partner_hand.add(card)
 
@@ -529,8 +531,22 @@ class AIPlayer:
 
         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)
+        # Under Tout Atout every card is a trump; under a normal contract
+        # trump cards are those matching the trump suit. `opp_trumps` must
+        # subtract everything that is no longer in opponents' hands: my own
+        # trumps, trumps already played, and any of partner's visible
+        # trumps (empty under `hide_partner_hand`).
+        if trump is Suit.TOUT_ATOUT:
+            total_trumps = 32
+            my_trumps = len(my_hand)
+            played_trumps = len(self.memory.played)
+            partner_trumps = len(self.memory.partner_hand)
+        else:
+            total_trumps = 8
+            my_trumps = hand_suit_counts.get(trump, 0)
+            played_trumps = sum(1 for c in self.memory.played if c.suit == trump)
+            partner_trumps = sum(1 for c in self.memory.partner_hand if c.suit == trump)
+        opp_trumps = max(0, total_trumps - my_trumps - played_trumps - partner_trumps)
 
         # Score each legal card by expected outcome
         best_card = legal[0]

{belote_cli-3.4.0 → belote_cli-3.5.0}/src/belote/belatro/core/run_state.py

@@ -28,6 +28,11 @@ class BelAtroRun:
     profile: Profile | None = None
 
     # ── Collectibles ───────────────────────────────────────
+    # These lists are intentionally mutable: jokers append on purchase, vouchers
+    # apply their effects in-place, and `consume()` removes items via
+    # `consumables.remove(item)`. If a future feature needs to snapshot a run
+    # for replay / ghost-run reconstruction, deep-copy these lists at the
+    # snapshot boundary — they alias live state otherwise.
     jokers: list[Joker] = field(default_factory=list)
     vouchers: list[Voucher] = field(default_factory=list)
     consumables: list[Any] = field(default_factory=list)  # Tarot/Planet instances
@@ -90,9 +95,17 @@ class BelAtroRun:
     def consume(self, item: Any, context: object = None) -> None:
         """Centralised consumable activation.
 
-        Records the item id as the most recent consumable (so LeFou can copy
-        it) and removes it from `consumables` if present, then dispatches to
-        the right hook based on item type (Tarot vs Planet).
+        Removes the item from `consumables` if present, dispatches to the right
+        hook based on item type (Tarot vs Planet), then advances
+        `last_consumable_id` so Le Fou can copy the prior consumable later.
+
+        Apply order matters: `item.use()` must run BEFORE updating
+        `last_consumable_id`, because Le Fou's `use()` reads that field to
+        find what to copy — if we advanced it to `le_fou` first, Le Fou would
+        see itself and fall through to the fallback path. Le Fou itself is
+        treated as transparent: the bookmark stays pointed at the source it
+        copied, so a second Le Fou keeps copying the same source rather than
+        copying itself.
         """
         import contextlib
 
@@ -100,11 +113,14 @@ class BelAtroRun:
 
         with contextlib.suppress(ValueError):
             self.consumables.remove(item)
-        self.last_consumable_id = getattr(item, "id", None)
         if isinstance(item, Tarot):
             item.use(self, context)
         elif isinstance(item, Planet):
             item.use(self)
+        # Le Fou is transparent — leave the bookmark at the source it copied.
+        # Every other consumable advances the bookmark to its own id.
+        if getattr(item, "id", None) != "le_fou":
+            self.last_consumable_id = getattr(item, "id", None)
 
     def _get_rng(self) -> Any:
         """Per-run random.Random instance, seeded from `seed` when given."""