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

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

@@ -5,6 +5,88 @@ 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.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.4.2}/DEVELOPMENT.md

@@ -84,14 +84,16 @@ PYTHONPATH=src mypy --strict src/
 # Linting (0 violations expected)
 ruff check src/ tests/
 
-# Full test suite (551 tests expected)
+# Full test suite (568 tests expected)
 PYTHONPATH=src pytest
 ```
 
-Current baseline (3.4.0):
+Current baseline (3.4.2):
 - **mypy**: 0 errors (strict mode, 76 files)
 - **ruff**: 0 violations
-- **pytest**: 551 tests, 0 failures
+- **pytest**: 568 tests, 0 failures
+- 3.4.2 closes 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`) ship 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.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: belote-cli
-Version: 3.4.0
+Version: 3.4.2
 Summary: A 4-player terminal card game
 Project-URL: Homepage, https://github.com/ElysiumDisc/belote
 Project-URL: Repository, https://github.com/ElysiumDisc/belote
@@ -45,6 +45,20 @@ 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.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 +351,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 +367,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.4.2}/README.md

@@ -2,6 +2,20 @@
 
 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.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 +308,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 +324,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.4.2}/pyproject.toml

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

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

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

{belote_cli-3.4.0 → belote_cli-3.4.2}/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.4.2}/src/belote/belatro/items/jokers/contract.py

@@ -3,7 +3,7 @@ from __future__ import annotations
 from typing import Any
 
 from belote.deck import Rank, Suit, card_points
-from belote.game import Seat
+from belote.game import Seat, team_of
 
 from ...engine.event_bus import BeloteAnnouncedEvent, RoundEndEvent, TrickWonEvent
 from ..base import Joker, JokerResult
@@ -18,7 +18,7 @@ class LIdeologue(Joker):
 
     def on_trick_won(self, event: TrickWonEvent, state: dict[str, Any]) -> JokerResult | None:
         # Sans Atout has event.trump as None
-        if event.winner == Seat.SOUTH and event.trump is None:
+        if team_of(event.winner) == 0 and event.trump is None:
             jacks = sum(1 for c in event.cards if c.rank == Rank.JACK)
             if jacks > 0:
                 # In Sans Atout, Jack is worth 2. We want it to be 20.
@@ -42,7 +42,7 @@ class LeFanatique(Joker):
         if state.get("contract") != "tout_atout":
             return None
 
-        if event.winner == Seat.SOUTH:
+        if team_of(event.winner) == 0:
             wins = state.get(f"{self.id}_wins", 0) + 1
             state[f"{self.id}_wins"] = wins
             if wins > 4:
@@ -59,7 +59,7 @@ class LeDiplomate(Joker):
     cost = 7
 
     def on_trick_won(self, event: TrickWonEvent, state: dict[str, Any]) -> JokerResult | None:
-        if event.winner == Seat.SOUTH:
+        if team_of(event.winner) == 0:
             suits: dict[Suit, set[Rank]] = {}
             for c in event.cards:
                 if c.rank in (Rank.KING, Rank.QUEEN):
@@ -78,7 +78,7 @@ class LePatriote(Joker):
     cost = 6
 
     def on_trick_won(self, event: TrickWonEvent, state: dict[str, Any]) -> JokerResult | None:
-        if event.winner == Seat.SOUTH and event.trump:
+        if team_of(event.winner) == 0 and event.trump:
             trump_pts = sum(
                 card_points(c, event.trump) for c in event.cards if c.suit == event.trump
             )
@@ -125,7 +125,7 @@ class LIllusionniste(Joker):
     cost = 9
 
     def on_trick_won(self, event: TrickWonEvent, state: dict[str, Any]) -> JokerResult | None:
-        if event.winner == Seat.SOUTH and event.trump:
+        if team_of(event.winner) == 0 and event.trump:
             extra_pts = sum(
                 18 for c in event.cards if c.rank == Rank.JACK and c.suit != event.trump
             )

{belote_cli-3.4.0 → belote_cli-3.4.2}/src/belote/belatro/items/jokers/trick_timing.py

@@ -2,7 +2,7 @@ from __future__ import annotations
 
 from typing import Any
 
-from belote.game import Seat, team_of
+from belote.game import team_of
 
 from ...engine.event_bus import TrickWonEvent
 from ..base import Joker, JokerResult
@@ -23,11 +23,11 @@ class LePremierSang(Joker):
         # subsequent NS-won trick for the rest of the round.
         active = state.get(f"{self.id}_active", False)
         if event.trick_number == 1:
-            if event.winner == Seat.SOUTH:
+            if team_of(event.winner) == 0:
                 state[f"{self.id}_active"] = True
                 return JokerResult(add_mult=2.0)
             return None
-        if active and event.winner == Seat.SOUTH:
+        if active and team_of(event.winner) == 0:
             return JokerResult(add_mult=2.0)
         return None
 
@@ -43,7 +43,7 @@ class LeSergent(Joker):
         return None
 
     def on_trick_won(self, event: TrickWonEvent, state: dict[str, Any]) -> JokerResult | None:
-        if event.winner == Seat.SOUTH:
+        if team_of(event.winner) == 0:
             streak = state.get(f"{self.id}_streak", 0) + 1
             state[f"{self.id}_streak"] = streak
             return JokerResult(add_mult=0.5)
@@ -79,7 +79,7 @@ class LExecuteur(Joker):
     is_unlockable = True
 
     def on_trick_won(self, event: TrickWonEvent, state: dict[str, Any]) -> JokerResult | None:
-        if event.is_last and event.winner == Seat.SOUTH:
+        if event.is_last and team_of(event.winner) == 0:
             return JokerResult(add_chips=40, times_mult=1.5)
         return None
 

{belote_cli-3.4.0 → belote_cli-3.4.2}/src/belote/belatro/main.py

@@ -375,6 +375,7 @@ class BelAtroGame:
             if not lock_trust:
                 trust.blind_failed()
         else:
+            money_before = self.run.economy.money
             payout = self.run.economy.process_round_end(total - self.run.target_score)
             if auto_coinche_active:
                 self.run.economy.add_money(payout * 2)  # L'Avocat: triple total payout
@@ -409,7 +410,8 @@ class BelAtroGame:
             # awards bonus money, Café gives +1 trust on big-blind wins).
             theme = self.run.get_ante_theme()
             if theme is not None:
-                theme.on_blind_won(self.run, self.run.blind_index)
+                blind_payout = self.run.economy.money - money_before
+                theme.on_blind_won(self.run, self.run.blind_index, blind_payout)
 
         # Partner-specific trust events (skipped under Le Divorce)
         if not lock_trust:

{belote_cli-3.4.0 → belote_cli-3.4.2}/src/belote/belatro/partner/partner_state.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
 
 from belote.game import Seat
 
@@ -8,6 +9,9 @@ from ..items.base import Joker
 from .personality import LeCourageux, PartnerPersonality
 from .trust import TrustTrack
 
+if TYPE_CHECKING:
+    from ..core.run_state import BelAtroRun
+
 
 @dataclass
 class PartnerState:
@@ -31,8 +35,15 @@ class PartnerState:
             return "hard"
         return "medium"
 
-    def equip_joker(self, joker: Joker) -> bool:
+    def equip_joker(self, joker: Joker, run: BelAtroRun | None = None) -> bool:
         if len(self.jokers) < self.joker_slots:
             self.jokers.append(joker)
+            # Fire the joker's purchase hook when a run is provided. The
+            # shop path equips through this method; passing `run` lets
+            # purchase-time effects (e.g. permanent stat boosts) apply
+            # consistently with the main joker slot equip path. Latent
+            # until a partner joker actually defines on_purchase().
+            if run is not None:
+                joker.on_purchase(run)
             return True
         return False

{belote_cli-3.4.0 → belote_cli-3.4.2}/src/belote/belatro/progression/save.py

@@ -90,8 +90,17 @@ class SaveManager:
             _default_stats = dict.fromkeys(
                 ("runs_won", "total_capots", "sans_atout_wins", "tout_atout_wins"), 0
             )
+            # When a saved profile is missing `unlocked_ids` (older saves,
+            # manual edits, partial writes), fall back to the Profile
+            # dataclass default rather than an empty list — otherwise the
+            # player loses their starter unlocks on reload.
+            unlocked_ids = (
+                list(data["unlocked_ids"])
+                if "unlocked_ids" in data
+                else Profile().unlocked_ids
+            )
             return Profile(
-                unlocked_ids=data.get("unlocked_ids", []),
+                unlocked_ids=unlocked_ids,
                 discovered_items=data.get("discovered_items", []),
                 stats={**_default_stats, **data.get("stats", {})},
             )

{belote_cli-3.4.0 → belote_cli-3.4.2}/src/belote/belatro/run/ante_themes.py

@@ -27,8 +27,13 @@ class AnteTheme:
         """Per-blind multiplier on the target score. Default 1.0 (no change)."""
         return 1.0
 
-    def on_blind_won(self, run: BelAtroRun, blind_index: int) -> None:
-        """Hook fired after a blind is won under this theme."""
+    def on_blind_won(self, run: BelAtroRun, blind_index: int, blind_payout: int) -> None:
+        """Hook fired after a blind is won under this theme.
+
+        `blind_payout` is the net money awarded for the round (all sources:
+        base payout, L'Avocat doubling, bonus money, Le Puriste, L'Aristocrate).
+        Themes that want "X% of round payout" must derive it from this value.
+        """
 
 
 class CafeAnte(AnteTheme):
@@ -53,7 +58,7 @@ class CafeAnte(AnteTheme):
     def target_multiplier(self, blind_index: int) -> float:
         return 0.95 if blind_index == 2 else 1.0
 
-    def on_blind_won(self, run: BelAtroRun, blind_index: int) -> None:
+    def on_blind_won(self, run: BelAtroRun, blind_index: int, blind_payout: int) -> None:
         if blind_index == 1:
             run.partner.trust.blind_beaten()
 
@@ -70,10 +75,10 @@ class TournoiAnte(AnteTheme):
     def on_ante_start(self, run: BelAtroRun) -> None:
         run.card_enhancements["always_offer_coinche"] = True
 
-    def on_blind_won(self, run: BelAtroRun, blind_index: int) -> None:
-        # +50% bonus on top of whatever payout the round produced.
-        # We use bonus_per_round as a proxy — gets nudged once per blind.
-        run.economy.add_money(max(1, run.economy.bonus_per_round // 2 + 2))
+    def on_blind_won(self, run: BelAtroRun, blind_index: int, blind_payout: int) -> None:
+        # True 50% of the round's actual payout (all sources summed).
+        # `blind_payout` is computed by the caller from the economy delta.
+        run.economy.add_money(max(1, blind_payout // 2))
 
 
 ALL_ANTE_THEMES: list[type[AnteTheme]] = [CafeAnte, TournoiAnte]

{belote_cli-3.4.0 → belote_cli-3.4.2}/src/belote/game.py

@@ -1004,11 +1004,6 @@ def play_card(state: GameState, card: Card) -> GameState:
     )
 
 
-def advance_turn(state: GameState) -> GameState:
-    """Advance to the next player's turn (used after AI plays)."""
-    return replace(state, turn=state.turn.next_seat())
-
-
 def set_announced(state: GameState, msg: str) -> GameState:
     return replace(state, announced=msg)
 

{belote_cli-3.4.0 → belote_cli-3.4.2}/src/belote/gameflow.py

@@ -25,11 +25,11 @@ from .game import (
     bidding_turn,
     clear_announced,
     clear_legal_cards_cache,
+    compute_trick_winners,
     play_card,
     process_bid,
     start_round,
     team_of,
-    trick_winner_seat,
 )
 from .input import KeyReader, interruptible_sleep
 from .scoring import (
@@ -191,11 +191,16 @@ def run_play(
             # animations or is on the "instant" speed preset.
             interruptible_sleep(MIN_TRICK_DWELL, None)
             if len(current.completed_tricks) == 7:  # This was the 8th trick
-                se_trump = current.boss_modifiers.seven_eight_trump
                 is_sa = current.contract == "sans_atout"
-                winner = trick_winner_seat(
-                    display_state.current_trick, current.trump, se_trump, is_sa
-                )
+                # Use the Rupture-aware helper so the announcement names the
+                # team that actually gets credited in scoring (see
+                # `compute_trick_winners` in game.py). Pass the projected
+                # 8-trick list because the 8th trick hasn't been pushed to
+                # `completed_tricks` yet.
+                projected = list(current.completed_tricks) + [display_state.current_trick]
+                winner = compute_trick_winners(
+                    current, current.trump, is_sa, tricks=projected
+                )[-1]
                 if winner:
                     team = "NS" if team_of(winner) == 0 else "EW"
                     announce(

{belote_cli-3.4.0 → belote_cli-3.4.2}/src/belote/main.py

@@ -228,7 +228,7 @@ def main() -> None:
                         )
 
                         update_stats_game(
-                            won=(ns >= target and ns >= ew),
+                            won=(ns >= target and ns > ew),
                             num_rounds=len(state.score_history),
                             difficulty=difficulty_str,
                         )