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

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

@@ -5,6 +5,137 @@ 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.7.1] - 2026-05-13
+
+Bug-hunt, performance, and logic audit pass plus the three items 3.6.0 deferred to 3.7.0. Three Explore agents ran in parallel against the documented false-positive catalogue. The classic-engine sweep returned **no novel findings** — the 3.4.x → 3.6.0 audits have absorbed the available correctness surface. The BelAtro layer produced **2 confirmed bugs** (one HIGH, one MEDIUM) and **1 polish item**. The deferred 3.7.0 items — `score_round` / `play_card` refactor, partner-joker test coverage, player-facing NS-taker surcoinche — all land here. **+36 regression tests** (599 → 635). Plan file at `/home/mrrobot/.claude/plans/bug-hunt-code-performance-sequential-map.md`.
+
+### Fixed
+
+- **`src/belote/belatro/items/jokers/hand_comp.py:88` (BA-L2, HIGH) — L'Accumulateur now credits team trick wins, not just South.** Pre-3.7.1 the joker gated on `event.winner == Seat.SOUTH`, silently dropping +5 chips per 7/8 whenever the partner (NORTH) won the trick. The description says *"For every 7 or 8 **you** win in a trick"* and in BelAtro "you" = team (NS) — same convention applied to Le Patriote / Le Premier Sang / Le Sergent in 3.5.0. L'Accumulateur was missed in that pass. Fixed: `if team_of(event.winner) == 0:`. 6 regression tests in `tests/belatro/test_belatro.py::TestLAccumulateurTeamCredit` covering NORTH credit, EAST/WEST non-credit, mixed-round accumulation, and rank-8 parity with rank-7.
+- **`src/belote/belatro/core/scoring.py:43,48,54` (BA-L1, MEDIUM) — `ContractReward` TypedDict now correctly annotates float fields as `float`.** `add_mult`, `bonus_mult_per_trick`, and `coinche_multiplier` were annotated `int` but populated with `0.3` / `1.0` / `1.0` by `planets.py`. Python's numeric coercion masked this at runtime, but the TypedDict was introduced explicitly to catch planet-reward key typos at type-check time — broken annotations defeated the purpose. Fixed; `mypy --strict` stays green (after pinning `libra_bonus: float` on the consumer side to keep the inference path explicit).
+
+### Changed
+
+- **`src/belote/scoring.py:599-878` (D1) — `score_round` extracted behind `_ScoringContext`.** ~280-LOC / ~30-branch monolith split into `_compute_belote_points`, `_compute_declaration_points`, `_score_capot_outcome`, `_score_normal_outcome`, with a `_ScoringContext` frozen+slotted dataclass threading pre-computed values (trump, taker, winners, tricks_ns/ew) into the helpers. Behaviour unchanged: zero test edits required. 3.6.0 deferred this because the natural extraction passed 15+ parameters between siblings; the context dataclass collapses that to one.
+- **`src/belote/game.py:857-1018` (D1) — `play_card` extracted behind `_PlayContext`.** ~163-LOC / ~18-branch function split into `_record_belote_announcement`, `_resolve_trick_winner`, `_compute_live_round_points`, `_rotate_dynamic_trump`. The mid-trick early-return is now visually adjacent to the trick-complete branch instead of the trick-complete branch swallowing the entire function body. Zero test edits.
+- **`src/belote/achievements.py` (P1-1) — achievement lookup via dict; `Achievement` gets `slots=True`.** Two `for a in ACHIEVEMENTS: if a.id == aid:` loops collapse to `_ACHIEVEMENT_BY_ID[aid]`. Catalog is 6 items so the perf win is microscopic; the readability win is real. `slots=True` brings the dataclass in line with every other frozen dataclass in the codebase.
+
+### Added
+
+- **`tests/belatro/test_partner_jokers.py` (D2) — focused matrix for 9 partner jokers.** Pre-3.7.1 the partner-joker modules (`passive` / `risky` / `shaper`) carried shallow smoke-tests in `test_belatro.py`. New file covers happy-path / non-trigger / round-boundary-reset for `LeMiroir`, `LaSymbiose`, `LeRelais`, `LAventurier`, `LeMartyr`, `LeParasite`, `LeGenereux`, `LaSentinelleP`, `LeCalculateur` — 26 tests, **100% line coverage** for the three modules (was effectively 0% direct coverage despite import-time references). Audit note pinned in the docstring: partner jokers correctly key on seat (NORTH), not team — they are the deliberate complement of L'Accumulateur, NOT subject to the BA-L2 fix.
+- **`src/belote/belatro/engine/round_driver.py:89-98` + `belatro/main.py` (D3) — `prompt_surcoinche` callback on `RoundUICallbacks`; NS-taker player surcoinche.** Pre-3.7.1 the NS-taker branch only consulted the EW-AI heuristic; when EW coinched the player had no way to surcoinche back. New optional callback (default returns False, preserves backward compatibility for any third-party `RoundUICallbacks` impl), wired into `round_driver.py:268-279` so the player gets first refusal before the existing 30% AI surcoinche fallback fires. `BelAtroMain`'s `UICallbacks` implements it via `BelAtroAnnounce.yes_no`. 4 regression tests in `test_round_driver.py` (accept / decline-AI-skips / decline-AI-takes / default-no-op).
+
+### Verified clean — audit findings rejected after source verification
+
+Documented so the next cycle doesn't re-investigate:
+
+- **Classic engine** (`game.py`, `scoring.py`, `deck.py`, `ai.py`, `gameflow.py`) — three-Explore-agent pass returned no novel findings. The 3.4.x → 3.6.0 audits absorbed the correctness surface.
+- **`visible_len()` "duplicated" in `_build_hud()`** (`ui/render.py:669-670, 705-706`) — calls are on different strings in different layout branches; not redundant.
+- **`detect_synergies()` recomputed per HUD render** (`belatro/ui/hud.py:67-82`) — O(joker_count × 6 pairs), microseconds per render; caching adds invalidation surface for no user-visible win.
+- **`_slot_anchors()` called 3× per trick-mat render** (`ui/render.py:379/409/446`) — pure arithmetic, sub-microsecond.
+- **`announce()` / `BelAtroAnnounce.banner()` duplication** — modal off-the-critical-path code with intentionally different positioning semantics.
+- **Two history-overlay code paths (wide vs narrow term)** — intentional split for narrow-terminal readability.
+- **Round-2 bid prompt ANSI redundancy** (`ui/render.py:751-753`) — visually correct (REVERSE wraps the segment); cosmetic only.
+
+### Deferred to 3.7.2
+
+- **Player surcoinche when EW is taker** — the symmetric mirror of D3. Today the EW-taker branch lets the player coinche but cannot surcoinche when partner-AI surcoinches the bid. Out of scope for the current pass; the `prompt_surcoinche` callback added in D3 can be reused.
+
+### Internal
+
+- **Tests**: 599 → 635 (+36). Two new test files: `tests/belatro/test_partner_jokers.py` (26), 4 new D3 tests in `tests/belatro/test_round_driver.py`, 6 new BA-L2 tests in `tests/belatro/test_belatro.py`.
+- **Strict gates**: pytest 635/635 green, mypy --strict 0 errors (77 files), ruff 0 violations.
+- **Version markers bumped**: `pyproject.toml`, `src/belote/__init__.py`.
+
+## [3.6.0] - 2026-05-12
+
+Verified bug-hunt and refactor pass over both the classic Belote engine and the BelAtro roguelite layer. A three-Explore-agent audit produced ~50 candidate findings; verification against current source rejected several as **false positives** (notably "dix-de-der double counting" — independent counters; "underscore-boss-attr anti-pattern" — already pinned; "M5 `last_voids_key` cross-round bleed" — already fixed). The items below are the ones confirmed against current code and shipped. **+4 regression tests** (595 → 599). Plan file at `/home/mrrobot/.claude/plans/bug-hunt-code-performance-functional-naur.md`.
+
+### Fixed
+
+- **`src/belote/belatro/engine/round_driver.py:210-289` (H1) — EW AI can now coinche an NS taker; Libra planet is reachable in natural play.** Pre-3.6.0 the coinche flow only branched on `state.taker in (Seat.EAST, Seat.WEST)`. When NS was taker there was no path that set `coinche_level > 0` outside of L'Avocat's `auto_coinche` or Le Coincheur's `start_coinched`. The `Libra` planet at `belatro/core/scoring.py:237-250` is gated on `event.coinche_level > 0 AND event.taker_seat in _NS_TEAM AND not failed`, so its content was effectively unreachable. New `_ew_should_coinche(state, rng)` heuristic (baseline 20 %, +15 % if either defender holds 2+ honour cards) gives the EW AI defenders a seeded chance; AI surcoinche from NS follows the existing 30 % pattern gated by `surcoinche_unlocked`. The branch also collapses the previous duplicated `auto_coinche` re-emit so the boss path lives in one site. 2 regression tests in `tests/belatro/test_round_driver.py` (one for the heuristic in isolation, one end-to-end via `ScoreAccumulator` joker capture).
+- **`src/belote/belatro/items/registry.py:184-194` (H2) — synergy-ID validation now survives `python -O`.** The 3.0.1 check used `assert not missing, ...`. Under `PYTHONOPTIMIZE=1` (the default for packaged installs and `python -O`) the assertion is stripped and a typo in `belatro/ui/hud.py::_SYNERGY_PAIRS` would silently break every HUD synergy badge for that pair. Replaced with `if missing: raise RuntimeError(...)`. Verified by importing the registry in a subprocess under `-O`.
+- **`src/belote/belatro/engine/event_bus.py:emit` (H3) — handler exceptions no longer halt remaining subscribers.** `emit()` now wraps each handler call in `try/except Exception`, logs via `logging.exception`, and continues iterating. `BaseException` (KeyboardInterrupt etc.) still propagates so a user Ctrl-C tears down the round cleanly. Pre-3.6.0 a single raising joker `on_event` would skip every subsequent subscriber for the rest of the round. 1 regression test in `tests/belatro/test_event_bus.py::test_raising_subscriber_does_not_skip_siblings`.
+- **`src/belote/belatro/engine/modifier_patch.py:patch` (M3) — `PatchedGameState` no longer rejects legitimate `_`-prefixed sets.** The 3.1.0 anti-shim raised on **any** leading-underscore patch key, but `GameState` has legitimate `_chips`, `_mult`, `_joker_state`, `_rng` fields. Narrowed the guard to reject only `_X` where `X` IS a `BossModifiers` field — the precise 3.0.x anti-pattern target. A future joker / boss effect that needs to adjust accumulator scalars no longer hits a confusing "3.0.x shim was removed" error. 1 regression test in `tests/belatro/test_boss_modifiers_integration.py::test_patched_state_rejects_only_underscore_boss_attrs`.
+
+### Changed
+
+- **`src/belote/scoring.py` (M1+M2) — zero-rank / `ban_clubs` flag logic extracted to module-level helpers.** Three sites previously inlined the same `kings_zero` / `tens_zero` / `aces_zero` / `jacks_zero` / `ban_clubs` table (`trick_card_points`, `_calculate_base_points`, `_apply_scoring_modifiers`). New `_card_points_with_zero_ranks(card, trump, bm)`, `_trick_zeroed_by_ban_clubs(trick, bm)`, and `_trick_points_with_modifiers(trick, trump, bm)` are the single source of truth. Adding a new zero-rank boss flag is now one edit instead of three (the audit's drift-risk concern). No behaviour change; full suite green.
+- **`src/belote/deck.py:Contract` (M4/R1) — added `class Contract(str, Enum)`** with values `NORMAL` / `SANS_ATOUT` / `TOUT_ATOUT` / `COINCHE` / `SURCOINCHE`. Inherits from `str` so values ARE plain strings — existing comparisons (`state.contract == "sans_atout"`) and JSON serialisation are unaffected. Migrated the dense comparison sites in `scoring.py`, `game.py`, `ai.py`, `gameflow.py`, and `belatro/engine/round_driver.py` to `state.contract == Contract.SANS_ATOUT`. UI label strings and joker / planet registry keys left as plain strings — `StrEnum`-style equality means they're interchangeable.
+- **`src/belote/game.py:sort_hand` (P4) — now `@lru_cache(maxsize=512)`.** Bench: ~34 % wall-clock win on the UI render-loop access pattern (same `(hand, trump)` requested across consecutive frames). P2 (`deck.card_points` caching) was tested with the same harness and **rejected** — the function is too small for `lru_cache` overhead to amortise (1.86× slower with cache).
+- **`src/belote/belatro/core/scoring.py:ContractReward` (R4) — TypedDict for `contract_levels` entries.** Documents the known keys (`add_chips`, `add_mult`, `jack_9_bonus`, `honor_bonus`, `bonus_mult_per_trick`, `add_money`, `capot_bonus`, `coinche_multiplier`) so mypy catches planet-reward key typos at type-check time. `BelAtroRun.contract_levels` stays as the wider `dict[str, dict[str, Any]]` to avoid an import cycle; the cast happens at the consumer boundary in `belatro/main.py`.
+- **`src/belote/game.py` belote detection (L1)** — single-pass per hand. Previously rebuilt a `(rank, suit)` set and looped 4 suits per seat; now tracks two `set[Suit]` (kings, queens) in one pass and intersects.
+- **`src/belote/deck.py` (L2)** — `card_points` and `trick_rank` type annotations widened to `trump: Suit | None` to match the SA call sites at `scoring.py` and elsewhere. Runtime behaviour was already correct.
+- **`src/belote/scoring.py:_carre_points` (L3)** — uses `.get(..., 0)` for symmetry with `get_declaration_points` and `_sequence_points`. The dict is currently complete so this is fail-soft only; protects against a future `Rank` extension crashing scoring mid-round.
+
+### Added
+
+- **`tests/test_properties.py` (T1) — three new invariants.**
+  - `test_chute_and_capot_are_mutually_exclusive`: under capot, credited points always live on exactly one side.
+  - `test_dynamic_trump_never_overrides_sans_atout`: La Anarchie's per-2-trick trump rotation never fires under SA (`state.trump` stays None for the whole round).
+  - `test_no_consecutive_team_wins_invariant_when_rupture_active`: under La Rupture, no team sweeps all 8 tricks (30 seeded rounds).
+- **`tests/belatro/test_round_driver.py` (H1 backfill)** — `test_ew_should_coinche_baseline_rate` and `test_ew_ai_can_coinche_ns_taker_under_seed`.
+- **`tests/belatro/test_event_bus.py` (H3 backfill)** — `test_raising_subscriber_does_not_skip_siblings`.
+- **`tests/belatro/test_boss_modifiers_integration.py` (M3 backfill)** — `test_patched_state_rejects_only_underscore_boss_attrs`.
+
+### Verified clean (audit false positives — do not re-investigate)
+
+- **Dix-de-der is NOT double-counted.** `game.py:play_card` writes the live HUD's `current_round_points` on the 8th trick; `score_round` derives from `state.completed_tricks` independently. The two counters are independent — verified by reading both code paths.
+- **The `getattr(state, "_X", False)` boss-flag anti-pattern is already pinned.** `tests/belatro/test_boss_modifiers_integration.py::test_invariant_no_underscore_boss_attrs` covers it. No leading-underscore boss attribute resolves on a vanilla GameState.
+- **`AIMemory.last_voids_key` cross-round reset is already in place.** `ai.py:78` clears the cache key in the new-round branch alongside `played` / `known_voids` / `processed_tricks_count`. Covered by `tests/test_ai.py::test_void_cache_invalidates_across_rounds`.
+- **Negative-edition joker slot growth is intentionally irreversible.** No sell mechanism exists today; the asymmetry is by design and documented at the increment site (`belatro/run/shop.py:166-168`).
+
+### Deferred to 3.7.0
+
+- Full `score_round()` and `play_card()` helper splits (L4/L5/R2/R3). Both functions are long (~280 LOC / ~30 branches; ~130 LOC / ~18 branches respectively) but the natural extraction passes 15+ parameters between siblings; a clean split needs an intermediate `ScoringContext` / `PlayContext` dataclass, which is its own refactor.
+- Partner-jokers test coverage (T5) — `belatro/items/partner_jokers/{passive,risky,shaper}.py` are at ~0 % coverage per the perf audit. Out of scope for a single audit pass.
+- Player-facing coinche / surcoinche prompts when NS is taker. Today only the AI surcoinches NS-taker rounds; the `RoundUICallbacks` layer doesn't expose a `prompt_surcoinche` callback yet.
+
+## [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`.

belote_cli-3.7.1/DEVELOPMENT.md

@@ -0,0 +1,197 @@
+# Development Guide
+
+Welcome to the Belote development guide. This project is structured as a standard Python package.
+
+## Setup
+
+1. **Clone the repository:**
+   ```bash
+   git clone <repository-url>
+   cd belote
+   ```
+
+2. **Create a virtual environment:**
+   ```bash
+   python -m venv .venv
+   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+   ```
+
+3. **Install in editable mode:**
+   ```bash
+   pip install -e .
+   ```
+
+## Running the Game
+
+After installing, you can run the game using the `belote` command for Classic mode:
+```bash
+belote
+```
+
+Or the `belatro` command for the Roguelite expansion:
+```bash
+belatro
+```
+
+Or via python:
+```bash
+python -m belote.main
+python -m belote.belatro.main
+PYTHONPATH=src python3 -m belote.main
+```
+
+## Testing
+
+We use `pytest` for testing. Install it if you haven't already:
+```bash
+pip install pytest
+```
+
+Run tests:
+```bash
+# Run all tests (Classic + BelAtro)
+PYTHONPATH=src pytest
+
+# Run only Classic Belote tests
+PYTHONPATH=src pytest tests/
+
+# Run only BelAtro tests
+PYTHONPATH=src pytest tests/belatro/
+
+# Run a single test file
+PYTHONPATH=src pytest tests/test_game.py
+PYTHONPATH=src pytest tests/belatro/test_scoring.py
+
+# Run a single test by name
+PYTHONPATH=src pytest tests/test_game.py::test_play_card_legal
+PYTHONPATH=src pytest -k "test_scoring"
+
+# Run with verbose output
+PYTHONPATH=src pytest -v
+
+# Run with coverage report
+PYTHONPATH=src pytest --cov=belote --cov-report=term-missing
+```
+
+## Code Quality
+
+The project maintains zero lint and type-check violations. Run all checks with:
+
+```bash
+# Type checking (0 errors expected, strict mode)
+PYTHONPATH=src mypy --strict src/
+
+# Linting (0 violations expected)
+ruff check src/ tests/
+
+# Full test suite (635 tests expected)
+PYTHONPATH=src pytest
+```
+
+Current baseline (3.7.1):
+- **mypy**: 0 errors (strict mode, 77 files)
+- **ruff**: 0 violations
+- **pytest**: 635 tests, 0 failures
+- 3.7.1 lands the deferred 3.7.0 items plus a fresh audit pass. Three Explore agents ran in parallel against the documented false-positive catalogue. The classic-engine sweep returned no novel findings (3.4.x → 3.6.0 absorbed the surface); the BelAtro layer produced **BA-L2** (L'Accumulateur team→seat bug, HIGH) and **BA-L1** (`ContractReward` TypedDict float annotations, MEDIUM). Deferred items: **D1** — `score_round` and `play_card` extracted behind `_ScoringContext` / `_PlayContext` (zero test edits, behaviour-preserving); **D2** — `tests/belatro/test_partner_jokers.py` adds 26 tests, **100% coverage** for `passive` / `risky` / `shaper` partner-joker modules; **D3** — `prompt_surcoinche` callback on `RoundUICallbacks` plus NS-taker player-surcoinche path in `round_driver.py:268-283`. **+36 regression tests** (599 → 635). Plan file at `/home/mrrobot/.claude/plans/bug-hunt-code-performance-sequential-map.md`.
+- 3.6.0 lands a verified bug-hunt and refactor pass over the classic engine and the BelAtro roguelite layer. Three Explore agents produced ~50 candidate findings; verification against current code rejected several as false positives (notably "dix-de-der double counting" — separate counters; "underscore-boss-attr anti-pattern" — already pinned by tests) and confirmed the items shipped here. **+4 regression tests** (595 → 599). Plan file at `/home/mrrobot/.claude/plans/bug-hunt-code-performance-functional-naur.md`.
+  - **H1** (`belatro/engine/round_driver.py:210-289`) — EW AI can now coinche an NS taker via a new `_ew_should_coinche` heuristic. Pre-3.6.0 there was no path that set `coinche_level > 0` when NS was taker (outside `auto_coinche` / `start_coinched`), making the Libra planet effectively unreachable in natural play.
+  - **H2** (`belatro/items/registry.py:184-194`) — synergy-ID validation converted from `assert` to a real `raise RuntimeError(...)` so the check survives `python -O` / `PYTHONOPTIMIZE=1` in packaged installs.
+  - **H3** (`belatro/engine/event_bus.py:emit`) — handler exceptions are now logged and the remaining subscribers still fire. A single buggy joker's `on_event` can no longer halt mid-round accumulator/unlock dispatch.
+  - **M1+M2** (`scoring.py`) — extracted `_card_points_with_zero_ranks`, `_trick_zeroed_by_ban_clubs`, and `_trick_points_with_modifiers`. Three sites that previously inlined the zero-rank flag table (drift-prone) now route through one helper. New zero-rank boss flags need one edit, not three.
+  - **M3** (`belatro/engine/modifier_patch.py:patch`) — narrowed the leading-underscore guard to reject ONLY `_<boss_field>` (the actual 3.0.x anti-pattern). Legitimate scalar GameState fields (`_chips`, `_mult`, `_joker_state`, `_rng`) are now patchable through `PatchedGameState`.
+  - **M4/R1** (`deck.py:Contract`, plus `scoring.py`/`game.py`/`ai.py`/`gameflow.py`/`belatro/engine/round_driver.py`) — `class Contract(str, Enum)` defines `NORMAL`/`SANS_ATOUT`/`TOUT_ATOUT`/`COINCHE`/`SURCOINCHE` and the dense comparison sites switched from string literals. Values remain plain strings so JSON serialisation and legacy comparisons keep working.
+  - **P4** (`game.py:sort_hand`) — `@lru_cache(maxsize=512)`. Benchmark showed ~34 % wall-clock win on the UI render's repeated `(hand, trump)` access pattern. P2 (`deck.card_points` caching) was **rejected** by benchmark — the function is too small for `lru_cache` to win against call overhead (1.86× slower with cache).
+  - **R4** (`belatro/core/scoring.py:ContractReward`) — `TypedDict` schema for `contract_levels` entries; catches planet-reward key typos (e.g. `bonus_per_trick` vs `bonus_mult_per_trick`) at type-check time. `BelAtroRun.contract_levels` keeps its wider `dict[str, dict[str, Any]]` type to avoid an import cycle; the consumer site casts at the boundary.
+  - **L1** (`game.py:place_bid` belote detection) — single-pass per hand: previously rebuilt a `(rank, suit)` set and re-iterated 4 suits.
+  - **L2** (`deck.py`) — `card_points`/`trick_rank` signatures widened to `trump: Suit | None` to match the SA call sites.
+  - **L3** (`scoring.py:_carre_points`) — switched from dict `[]` access to `.get(..., 0)` for asymmetry with sibling lookups; the dict is complete today so this is fail-soft only.
+  - **T1** (`tests/test_properties.py`) — three new invariants: `test_chute_and_capot_are_mutually_exclusive`, `test_dynamic_trump_never_overrides_sans_atout`, `test_no_consecutive_team_wins_invariant_when_rupture_active`.
+  - **Verified clean (NOT bugs)**: the "dix-de-der double counting" the audit initially flagged turned out to be two independent counters (`play_card` writes the HUD's `current_round_points`; `score_round` derives from `completed_tricks`). The "underscore-boss-attr anti-pattern" is already pinned by `tests/belatro/test_boss_modifiers_integration.py::test_invariant_no_underscore_boss_attrs`. `AIMemory.last_voids_key` reset on new round is already correct and covered by `tests/test_ai.py::test_void_cache_invalidates_across_rounds`.
+  - **Deferred to 3.7.0**: full `score_round()` / `play_card()` helper splits (L4/L5/R2/R3) — would need an intermediate `ScoringContext` dataclass to avoid 15-param helper signatures, which is its own refactor. Partner-jokers test coverage (T5) — broader surface than this audit's scope. Player-side coinche / surcoinche UI prompts when NS is taker (currently AI-only).
+- 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:
+
+```bash
+PYTHONPATH=src python -m pytest --tb=short -q && \
+  python -m mypy --strict src/ && \
+  python -m ruff check src/ tests/
+```
+
+## Benchmarking
+
+A benchmarking script is provided to measure rendering and AI performance:
+```bash
+PYTHONPATH=src python scripts/benchmark.py
+```
+
+3.0.0 baseline numbers (Linux, Python 3.10+, 1000 iterations):
+- Render: 0.27 ms (±0.04)
+- AI Hard decide_card: 0.026 ms (±0.003)
+- BelAtro state update: 0.032 ms (±0.004)
+- score_round: 0.169 ms
+- legal_cards: 0.012 ms
+
+Use these as a regression-detection floor for future changes.
+
+## Accessibility
+
+Set `BELOTE_A11Y=1` to emit one-line plain-text descriptions of card plays,
+trick winners, and round results to stderr — readable by terminal screen
+readers (Orca, NVDA over WSL, VoiceOver via iTerm2).
+
+## Optional Runtime Flags
+
+The following environment variables enable opt-in features. Each is read
+once at startup; toggling mid-run has no effect.
+
+- `BELOTE_REPLAY=1` — after every Classic round, print a one-line summary
+  of how often South's plays matched the Hard-AI's preferred line
+  (e.g. `Replay: Optimal plays: 6/8 (75%)`). Educational only — never
+  affects scoring. Backed by `src/belote/replay.py`.
+- `BELOTE_GHOST=1` — silently record every BelAtro run (seed, deck,
+  bids, plays, round outcomes) to
+  `~/.local/share/belote/ghosts/<label>-<seed>.json`. The file is written
+  once when the run ends. Useful for sharing or replaying interesting
+  runs. Backed by `src/belote/belatro/ghost_run.py`.
+
+## Releasing a New Version
+
+### Code-only update (push to GitHub without releasing a new PyPI version)
+
+If you're just iterating on code, fixing typos, updating docs, etc., and don't want to cut a new PyPI release yet:
+
+```bash
+git add <files>
+git commit -m "<what changed>"
+git push origin master
+```
+
+## Releasing a New Version (Manual)
+
+1. **Bump the version** in `pyproject.toml`.
+2. **Add a CHANGELOG entry** at the top of `CHANGELOG.md`.
+3. **Clean stale build artifacts:**
+   ```bash
+   rm -rf dist/ build/ *.egg-info/
+   ```
+4. **Build, validate, and upload:**
+   ```bash
+   pipx run build --sdist --wheel
+   pipx run twine check dist/*
+   pipx run twine upload dist/*
+   ```
+
+   *Note: `twine upload` will prompt for your PyPI credentials or use your `~/.pypirc` file.*
+
+5. **Commit and tag in git:**
+   ```bash
+   git add pyproject.toml CHANGELOG.md
+   git commit -m "Release vX.Y.Z"
+   git tag -a vX.Y.Z -m "vX.Y.Z"
+   git push origin master --tags
+   ```
+```