belote-cli 4.6.5__tar.gz → 4.7.2__tar.gz

belote_cli-4.7.2/.antigravitycli/69dd05ce-2c1c-4419-8755-e4dd0d4495e8.json

@@ -0,0 +1 @@
+/home/mrrobot/.gemini/config/projects/69dd05ce-2c1c-4419-8755-e4dd0d4495e8.json

{belote_cli-4.6.5 → belote_cli-4.7.2}/CHANGELOG.md

@@ -5,6 +5,243 @@ 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).
 
+## [4.7.2] - 2026-05-20
+
+Patch release: external-model audit verification pass. A prior audit (pasted
+from another LLM) flagged ~30 issues across bugs / perf / quality. Verifying
+each claim against the live code rejected the false positives (including one
+HIGH-severity claim — "160 event dispatches per round" — that the model
+invented out of whole cloth) and shipped only the genuinely confirmed
+findings. Two real correctness gaps the prior audit missed were caught via
+fresh-additions review. All baselines green: `ruff` 0 violations,
+`mypy --strict` 0 errors, `pytest` 1003/1003.
+
+### Fixed
+
+- **(Bug) Malédiction (`invert_scoring`) 4-4 trick tie.** Pre-fix the boss
+  flag zeroed the team that won MORE tricks, but a 4-4 split fell through
+  both branches and neither side was zeroed — both teams kept their full
+  scores under the curse. Rule chosen: the taker is zeroed (the cursed
+  side failed to break the tie). `scoring.py::_apply_invert_scoring` adds
+  an `else` branch; pinned by
+  `test_boss_invert_scoring_4_4_tie_zeros_taker` in
+  `tests/belatro/test_boss_modifiers_integration.py`.
+
+### Changed
+
+- **`bm: object` → `bm: BossModifiers`** on `_trick_zeroed_by_ban_clubs`,
+  `_card_points_with_zero_ranks`, `card_points_with_modifiers`, and
+  `_trick_points_with_modifiers` (`scoring.py`). All four helpers were
+  typed as `object` with `getattr(bm, "ban_clubs", False)` defensive
+  lookups; the actual callsites always pass `BossModifiers`. Now type-
+  safe attribute access — `mypy --strict` enforces every new field is
+  spelled correctly.
+- **`UICallbacks` extracted from `BelAtroGame._play_blind`** to a module-
+  top class in `belatro/main.py`. The nested class spanned 189 lines and
+  captured 8 closure variables (`run`, `profile`, `save_manager`, `hud`,
+  `acc`, `trust_bar`, `show_north`, plus a dead-write `last_display_state`
+  cell). Now an explicit constructor; `last_display_state` removed
+  (write-only, never read).
+- **Litige pool carry across all-pass redeals is now documented.** Added
+  a `reset_round_fields` docstring entry calling out that `litige_points`
+  is deliberately NOT in the reset list — the pool survives across
+  rounds (including all-pass redeals) until a non-litige scoring round
+  consumes it. Pinned by
+  `test_litige_pool_survives_all_pass_redeal` +
+  `test_litige_pool_survives_two_consecutive_all_pass_redeals` in
+  `tests/test_bidding_all_pass.py`.
+
+### Performance
+
+- **`detect_sequences` is now `@lru_cache(128)`.** Microbench placed it
+  at ~25% of `score_round` cost when `initial_hands` is populated, and
+  `get_declarations` runs the same 4 hand tuples through the helper
+  twice per round (once at bid-acceptance time in `game.py`, once during
+  `score_round` itself). Cache hits eliminate the second pass.
+  `score_round` macrobench: 300 µs → 227 µs (~24% on the full path).
+  Cards are frozen dataclasses (hashable); all callers treat the
+  returned list as read-only.
+
+### Tests strengthened
+
+- **`test_last_trick_bonus_applied`** (`tests/test_belote.py`) → split
+  into `test_capot_subsumes_last_trick_bonus` (asserts the actual
+  `CAPOT_BASE` total) and new `test_last_trick_bonus_applied_in_normal_round`
+  (deterministic 4-NS/4-EW non-capot fixture proving the +10 dix-de-der
+  actually lands on the taker side). Previously only asserted `is_capot
+  is True` — the +10 mechanic the test name promised was untested.
+- **`test_non_capot_points_sum_162`** (`tests/test_belote.py`) →
+  conditional `if not breakdown.is_capot:` replaced with explicit
+  `assert not breakdown.is_capot` plus the unconditional conservation
+  check. The old form passed vacuously if `make_deck()` ordering ever
+  produced a capot.
+
+### Internal
+
+- **Contract→word a11y mapping deduplicated** to a `_contract_word(state)`
+  helper in `gameflow.py`. Two near-identical 8-line blocks collapsed
+  into one helper call each (bid→play transition; round-result speak).
+
+### Documentation
+
+- README test count claims and CHANGELOG / DEVELOPMENT references
+  updated 999 → 1003.
+
+### Verified-false audit claims (re-investigate at your peril)
+
+For the record so the next audit cycle doesn't relitigate items the
+external model flagged but the code disagreed with:
+
+- `partner()` if-chain vs modular arithmetic — style only, not a bug.
+- `start_round` "doesn't reset belote_holders" — self-refuted (line 308
+  passes `belote_holders={}`).
+- Score-animation labels "confusing" — `gameflow.py:458` already labels
+  by `breakdown.taker_team`.
+- `_empty_breakdown` taker_team default — only returned on contract-
+  inactive states; harmless.
+- `BelAtroRun.consume()` "removes before use" — wrapped in
+  `contextlib.suppress(ValueError)`, semantically correct.
+- `_bonus_money` "race" — Le Fantôme writes to `acc._ledger.money`
+  directly since 4.6.2; main.py only consumes seal_round-routed amounts.
+- "160 event dispatches per round" — false. Jokers subscribe to
+  `TrickWonEvent` / `BeloteAnnouncedEvent` / `DeclarationScoredEvent`
+  only; per-card emit doesn't iterate jokers. Real count is ~85-100
+  dispatches per round and they're already O(jokers × events).
+- LeRebelle / RebeloteEcho / TierceCharger ungated under boss flags —
+  verified gated. `game.py:907` short-circuits `BeloteAnnouncedEvent`
+  under `no_belote`; `round_driver.py:467-473` documents
+  TierceCharger's intentional un-gating; LeMathématicien / QuinteRoyale
+  read `event.points` which Le Mime forces to 0.
+
+## [4.7.1] - 2026-05-19
+
+Patch release: post-4.7.0 audit pass that found two latent correctness
+foot-guns and three concrete AI hot-path wins, then reconciled the
+documentation surfaces with the actual code. Three parallel Explore-agent
+audits (core engine, BelAtro mode, performance) surfaced ~20 candidate
+issues; the seven false-positives were rejected against the live code
+and only the verified findings shipped. All baselines green: `ruff` 0
+violations, `mypy --strict` 0 errors, `pytest` 999/999.
+
+### Fixed
+
+- **(Major) Sans Atout partner-hand rank comparison.** `_score_winning_strategy`
+  computed the local `rank` via `_NONTRUMP_ORDER[card.rank]` under SA
+  (correct), but the partner-hand penalty block at the bottom of the
+  function unconditionally called `trick_rank(card, trump, self._se)` with
+  `trump=None` for BOTH the candidate card and every partner card.
+  `trick_rank(card, None, ...)` happens to collapse to the same ordering
+  as `_NONTRUMP_ORDER` today, so the bug is benign-by-coincidence — but
+  any future tweak to `trick_rank`'s SA branch (e.g. honor-scaling)
+  would silently break the partner-hand heuristic without any test
+  catching it. Now mirrors line 728's `if is_sa` branch on both rank
+  computations. Pinned by `test_winning_strategy_partner_hand_uses_nontrump_order_under_sa`
+  in `tests/test_ai.py`, which poisons `trick_rank` and confirms the
+  SA branch never touches it.
+- **(Minor) `prompt_card` silently substituted `hand[0]` on empty
+  `legal_cards`.** Belote's suit-follow / overtrump rules guarantee at
+  least one legal card whenever the hand is non-empty, so the path is
+  unreachable today — but the `return hand[0], state` fallback would
+  let an illegal card through to `play_card` if `legal_cards` ever
+  regressed. The AI path (`ai.py::decide_card`) already raises on the
+  same precondition; the human-input path now matches. Pinned by
+  `test_prompt_card_raises_on_empty_legal_cards`.
+
+### Performance
+
+- **Hoisted `highest_rank` and `opp_voids` out of the per-card scoring
+  loop in `_hard_play`.** Both depend only on `(trick, trump, is_sa,
+  self._se)` and the next-opp seat — all constant across the 1–8 legal
+  candidates being scored. Pre-fix they were recomputed inside
+  `_score_winning_strategy` per card. Now precomputed once and threaded
+  through `_score_card_play` → `_score_winning_strategy` as kwargs with
+  `None` defaults so standalone callers (tests, future ad-hoc
+  heuristics) still work. ~8–15% on hard-AI card decisions.
+- **Plumbed `points` through `_score_leading_strategy`.**
+  `_score_card_play` already computes `points = card_points_with_modifiers(card, trump, bm)`,
+  but the leading-strategy helper re-invoked the function to detect waste
+  cards. Now the helper accepts a keyword-only `points: int` and reuses
+  the caller's value. ~3–5% on lead decisions.
+
+### Changed
+
+- `tests/test_ai.py` test count: 22 → 24 (the two new pins above).
+  Total suite: 997 → **999**.
+
+### Documentation
+
+- `README.md` — test-count claims updated 997 → 999 in three places
+  (project-structure block, "Running Tests" section, "Technical
+  Integrity" bullet list). Joker/voucher/planet/tarot/boss/deck counts
+  reverified against `registry` / `ALL_BOSS_MODIFIERS` / `STARTING_DECKS`
+  (42 / 12 / 8 / 12 / 21 / 12) — all already accurate at 4.7.0, no
+  change.
+- `DEVELOPMENT.md` — code-quality command block now mentions 999 tests.
+  Release process now explicitly calls out that `pyproject.toml` AND
+  `src/belote/__init__.py` must be bumped together (they had been
+  drifting in older release attempts; `belote --version` /
+  `belatro --version` read `__version__` while PyPI / pipx read
+  `pyproject.toml`).
+
+## [4.7.0] - 2026-05-19
+
+Feature minor: ships the **Dix de Der Heist** (BelAtro roguelite gamble keyed off `economy.interest_rate`) and the **slot-machine score tally** that replaces the static per-trick popup with a rolling odometer animation. Includes a full 4.6.5-style multi-agent audit (six parallel Explore agents covering heist correctness, slot-machine boss safety, items integration, save/load, performance, and 21-boss crash safety) and the resulting fixes, plus a hands-on polish pass — heist-discoverability hint, persistent tally in HUD, and a new V-key inventory overlay. All baselines green: `ruff` 0 violations, `mypy --strict` 0 errors, `pytest` 997/997.
+
+### Added
+
+- **Dix de Der Heist (BelAtro)** — Player-only roguelite gamble declared at the start of trick phase. When SOUTH is the taker and `economy.interest_rate > 0` (gated; default rate = 0 = no reward = no prompt), the player can declare a heist that resolves on trick 8:
+  - On NS win: `ledger.mult *= (1 + interest_rate)` (`×2` with La Voûte, up to `×4` stacked with interest-bumping tarots).
+  - On NS loss: the card_points NS accumulated in tricks 1–7 are subtracted from `ledger.chips`. Declarations / belote / permanent / joker bonuses preserved.
+  - The multiplier resolves BEFORE `_fire_jokers("on_trick_won", event)` on trick 8 so jokers like LeDernierMot (×2) and LExecuteur (×1.5) compose on top. Documented in `belatro/core/scoring.py` to lock the composition rule in for future readers.
+  - State on `joker_state` as three scalar keys (`heist_declared`, `heist_ns_trick_chips`, `heist_outcome`) seeded fresh by `trigger_round_start`; per-round transient, never persisted. Sentinel `heist_outcome` guards resolution against the ~30 HUD `materialize()` re-reads per round.
+  - New `RoundUICallbacks.prompt_heist(state) -> bool` hook with a default no-op (classic Belote never offers the heist). BelAtro UICallbacks overrides in `belatro/main.py`.
+- **Slot-machine score tally** (`BelAtroAnnounce.slot_machine_tally`) — Per-trick odometer animation replacing the static `score_popup`. 20-frame ease-out over ~600ms; bucket bar shows trick card_points filling, mult indicator pulses, odometer ticks toward the new total with color shifts (cyan → white → gold) and a flame row (`≈ ▼ ◆ ▼ ≈`) when running total crosses 120% of target. Skippable on SPACE / ESC / ENTER / EOF. Suppressed under `hide_hud` (Le Brouillard), `separate_scoring` (La Compétition), and on terminals smaller than 6 rows. Module-level cache (`_last_tally_total`) cleared each round via `reset_tally_state()`.
+- **Persistent slot-machine readout in the BelAtro HUD (follow-up).** After the animation completes, the final-frame bucket + odometer lines stay visible at the bottom of the screen until the next trick or until `I` toggles the top HUD off. Adds a 1s skippable hold after the final frame so the player can read the result, then a new `_last_tally_readout` module cache feeds `BelAtroHUD.render()` / `_render_compact()` for the repaint. Cleared via `reset_tally_state()`. Bound to `is_top_hud_visible()` so `I` hides both the HUD and the readout in one shot.
+- **Inventory overlay on the V key** (`BelAtroAnnounce` peer `InventoryOverlay` in `belatro/ui/inventory.py`). Read-only detail-on-select pager that lists owned jokers (with edition tags + per-edition bonus blurb), vouchers, consumables (tarots/planets held but not yet activated), permanent chip / mult bonuses, and per-contract planet levels. List view → ↑/↓ navigate, Enter opens a per-item detail page; Esc/V/Q close. Mirrors the `C` key's `ConsumablesOverlay` paint pattern (`clear_screen` + `vcenter_lines` + `invalidate_diff()` in `finally`).
+- **Discoverability hint for the Dix de Der Heist.** The first time a player takes a contract while `economy.interest_rate == 0` (i.e. they haven't bought La Voûte yet), a one-time banner explains the gating: *"Tip: buy the La Voûte voucher in the shop to unlock the Dix de Der Heist (×2+ Mult on trick 8)."* Persisted via a new `Profile.seen_heist_hint: bool` field; no SCHEMA_VERSION bump needed (dataclass default kicks in for legacy saves).
+
+### Fixed (4.7.0 audit pass)
+
+- **(Critical) Slot-machine cache leak on mid-animation interrupt** (`belatro/ui/announce.py`). The `_last_tally_total = new_total` update lived inside the try-block; a `KeyboardInterrupt` or render-time raise mid-animation would skip the update and leave the next round animating from a stale baseline. Moved into the `finally` block alongside `invalidate_diff()`. Pinned by `test_slot_machine_cache_updates_even_if_render_raises`.
+- **(Critical) Slot-machine row collision on tiny terminals** (`belatro/ui/announce.py`). Row math (`term_h - 5..3`) collapsed when `term_h < 6`, painting the animation over the HUD row 1. Added a `term_h < 6` short-circuit that suppresses the animation while still updating the cache. Pinned by `test_slot_machine_tiny_terminal_renders_nothing`.
+- **(Critical) `BelAtroAnnounce.reset_tally_state` AttributeError on round start.** `belatro/main.py::_play_blind` called `BelAtroAnnounce.reset_tally_state()` but the function was defined at module level (mirroring `reset_top_hud_state` / `reset_overlay_state`), not as a static method on the class. Crashed at the first round. Now imported as a module function. User-surfaced.
+- **(Medium) Slot-machine paints misleading totals under La Compétition** (`belatro/ui/announce.py`). `acc.get_total(state)` is a running sum but `separate_scoring` uses a per-seat max at round-end; the animated total diverged from the eventual sealed total. Now gated like the HUD (`belatro/ui/hud.py:171-176`): cache update without paint. Pinned by `test_slot_machine_under_separate_scoring_renders_nothing`.
+- **(Medium) Heist outcome banner leaked under Le Brouillard** (`belatro/main.py`). The post-round "HEIST SECURED / BUSTED" banner ignored `hide_hud`, defeating the boss's "hide the score" promise. Now gated on `not final_state.boss_modifiers.hide_hud`.
+- **(Polish) Blank flame row consumed a screen row** (`belatro/ui/announce.py`). When `displayed < target × 1.2`, `ansi_center("")` painted a `term_w`-wide blank line, wasting vertical space. Now skip the paint when the flame line is empty.
+- **Sans Atout AI type safety.** The 4.6.6 in-flight Sans Atout Hard AI work shipped with type annotations that assumed `trump: Suit`, but the SA path has `trump = None`. Widened `_hard_lead` and `_score_card_play` signatures to `Suit | None`, added an explicit `trump is None` arm to the `opp_trumps` computation in `_hard_play`, and removed a dead `is_sa = True/False` branch (overwritten three lines later by the canonical `state.contract == Contract.SANS_ATOUT` read). `mypy --strict` now clean.
+
+### Changed
+
+- **`BelAtroAnnounce.score_popup` no longer called at `on_trick_end`.** Replaced by `slot_machine_tally`. The method is still defined for one release; if no consumer surfaces by 4.8 it will be removed. Bumped the `belatro/ui/announce.py` `invalidate_diff` count in `tests/test_alt_screen_scroll.py::test_belatro_overlays_invalidate_diff` from 4 to 5.
+- **`ScoreAccumulator` gained an `interest_rate: int = 0` field.** Snapshotted at `_play_blind` time alongside `target_score`, so a mid-round La Voûte purchase or tarot effect cannot retroactively change the resolved heist multiplier.
+- **`V` key is no longer an alias of `I`.** Pre-4.7.0 both keys mapped to `Key.OVERLAY` (top-HUD toggle). The follow-up pass split `V` into a new `Key.INVENTORY` enum value that opens the read-only inventory overlay. `I` keeps its existing toggle semantics (and now also covers the persistent tally readout). Wired in `belote/input.py` (both `_UnixKeyReader` and `_WindowsKeyReader`), dispatched in `belote/ui/prompts.py::prompt_card` (`"INVENTORY"` sentinel string), and handled by `belatro/main.py::UICallbacks._show_inventory`. Classic Belote's `gameflow.py` treats the sentinel as a no-op (re-prompt).
+
+### Internal
+
+- **Test count baseline**: 941 → 997 (+56 in 4.7.0: 23 heist tests including 3 hint-discoverability regressions, 16 slot-machine tests including 5 HUD-readout persistence regressions, 15 inventory-overlay tests, 2 audit-driven entries).
+- **Version markers bumped**: `pyproject.toml` (`4.6.6` → `4.7.0`), `src/belote/__init__.py` (`4.6.6` → `4.7.0`).
+- **No `SCHEMA_VERSION` bump required**: heist state is per-round transient on `joker_state`, seeded fresh by `trigger_round_start` and never persisted. `Economy.interest_rate` was already persisted as part of `BelAtroRun.economy`; existing saves load without migration.
+- **Six-agent audit highlights (all verified clean, no further action)**: per-round transient state hygiene (heist keys reset at round start, slot-machine cache reset at `_play_blind` entry); idempotency under HUD `materialize()` (sentinel-guarded, no re-application); composition with all trick-8 jokers (LeDernierMot, LExecuteur, Le Carnet, L'Infiltré); composition with planets (Pluton capot bonus, Mercure round-end money, Le Soleil Tout Atout per-trick mult); 21-boss safety smoke (La Rupture / La Compétition / L'Avocat / Le Mime / Le Zéro Final / L'Anarchie / L'Agent Double / La Solitude all verified). Performance: heist branches sub-microsecond per trick; slot-machine animation adds ~4.8s/round (designed, skippable).
+- **Documentation accuracy sweep**: README and DEVELOPMENT refreshed; item counts (42 jokers, 12 tarots, 8 planets, 12 vouchers, 12 starting decks, 21 bosses) unchanged from 4.6.6 and re-verified against the registry.
+- **Plan file**: `/home/mrrobot/.claude/plans/let-s-add-dix-de-steady-duckling.md`.
+
+---
+
+## [4.6.6] - 2026-05-19
+
+Performance and logic audit pass. Highlights: improved Hard AI strategy for Sans Atout, unified round scoring paths to remove redundancy, and end-to-end documentation accuracy verification. All baselines green: `ruff` 0 violations, `mypy --strict` 0 errors, `pytest` 941/941.
+
+### Fixed
+
+- **Hard AI fallback for Sans Atout rounds.** Pre-4.6.6, the 1-ply lookahead heuristic was trump-centric and fell back to random play when no trump was set. Now uses a non-trump ranking heuristic based on `_NONTRUMP_ORDER` (A > 10 > K > Q > J > 9 > 8 > 7), making the Hard AI significantly more competitive in Sans Atout play.
+- **Refactored `apply_round_score` in `scoring.py`.** Unified the NS-taker and EW-taker branches into a single path using conditional mapping, eliminating 50+ lines of duplicated code and reducing the risk of logic drift between teams.
+
+### Internal
+
+- **Test count baseline**: 941 (unchanged).
+- **Version markers bumped**: `pyproject.toml`, `src/belote/__init__.py`, and various documentation references (4.6.5 → 4.6.6).
+- **Documentation accuracy sweep**: Item counts (42 jokers, 12 tarots, 8 planets, 12 vouchers, 12 starting decks, 21 bosses) and test counts (941) verified across `README.md` and `DEVELOPMENT.md`.
+
 ## [4.6.5] - 2026-05-18
 
 Follow-up audit pass — six parallel Explore agents covered the surface area the 4.6.4 sweep didn't reach (partner-trust + bidding state machine, shop / economy / items / ghost-run, progression / replay / a11y / input). Result: two verified critical bugs in production paths the previous audit didn't touch (the LePrêteur economy exploit and a Windows-only EOF reader bug), three performance wins, and four quality items including the dead-but-declared `announce_round_result` helper finally wired up. Mechanics audits (partner trust, bidding state machine, capot detection, belote/rebelote under L'Anarchie, voucher idempotency, ghost-run write safety, save atomic-writes, achievement unlocks) all came back clean against current code. Plan file: `/home/mrrobot/.claude/plans/bug-hunt-code-performance-sparkling-fairy.md`. All baselines green: `ruff` 0 violations, `mypy --strict` 0 errors, `pytest` 941/941.

belote_cli-4.7.2/DEVELOPMENT.md

@@ -0,0 +1,185 @@
+# 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 (1003 tests expected)
+PYTHONPATH=src pytest
+```
+
+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, locked contracts (4.6.5), declarations (4.6.5), and round
+results to stderr — readable by terminal screen readers (Orca, NVDA over
+WSL, VoiceOver via iTerm2).
+
+The env var is read once at import; tests that mutate it must call
+`belote.a11y._refresh_enabled_from_env()` after the patch. Hook points live
+in `gameflow.py` (card plays, trick winners, contract announce at bid→play
+transition, round result) and `belatro/main.py` (boss reveal, ante advance,
+run won/lost).
+
+## 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`.
+- `NO_COLOR=<any-non-empty>` — suppress truecolor SGR escapes from
+  `fg()` / `bg()` per the [no-color.org](https://no-color.org/) spec.
+  Bold/dim/underline/reverse/strikethrough and cursor sequences remain
+  (they aren't color). Added in 3.9.0. Backed by `src/belote/ansi.py`.
+
+## Releasing a New Version
+
+### 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 BOTH `pyproject.toml` AND `src/belote/__init__.py`
+   (they must stay in sync — `belote --version` / `belatro --version` read
+   `__version__` while PyPI / pipx read `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
+   ```
+```

{belote_cli-4.6.5 → belote_cli-4.7.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: belote-cli
-Version: 4.6.5
+Version: 4.7.2
 Summary: A 4-player terminal card game
 Project-URL: Homepage, https://github.com/ElysiumDisc/belote
 Project-URL: Repository, https://github.com/ElysiumDisc/belote
@@ -175,7 +175,8 @@ belote --difficulty hard --target 500 --seed 123 --speed fast
 
 **General:**
 - `?`: Show keyboard shortcut help
-- `I` or `V` *(BelAtro only)*: Toggle the BelAtro top HUD overlay — see the BelAtro gameplay note below for details
+- `I` *(BelAtro only)*: Toggle the BelAtro top HUD overlay AND the persistent slot-machine tally readout — see the BelAtro gameplay note below for details
+- `V` *(4.7.0, BelAtro only)*: Open the **Inventory** overlay (jokers, vouchers, consumables, permanent bonuses, contract levels). ↑/↓ navigate, Enter for detail, Esc/V/Q close. Distinct from `C` (Consumables tray, action-oriented); `V` is read-only inspection.
 - `Q`: Quit to main menu or exit
 - `H`: View Game History (round-by-round, with contract / taker / tricks / declarations)
 - `T`: Cycle UI Theme
@@ -197,11 +198,15 @@ belote --difficulty hard --target 500 --seed 123 --speed fast
 - `Z`: Undo last move
 - `Space` or `Esc`: Skip animations
 - During bidding round 2: `P` = Pass, `X` = Tout Atout, `N` = Sans Atout *(remapped from A/S in 4.5.0 to make room for WASD nav)*
-- `I` or `V` *(4.6.3, BelAtro only)*: Toggle the BelAtro top HUD (joker pip strip, ante/blind/target line, chips×mult score, trust bar, synergy tooltip). Visible by default; press `I` to hide it and reveal the classic Belote HUD's `Trump:` / `Taker:` fields underneath. Press `I` again to bring the overlay back.
+- `I` *(4.6.3, BelAtro only)*: Toggle the BelAtro top HUD (joker pip strip, ante/blind/target line, chips×mult score, trust bar, synergy tooltip) AND, since 4.7.0, the persistent slot-machine tally readout at the bottom. Visible by default; press `I` to hide both and reveal the classic Belote HUD's `Trump:` / `Taker:` fields underneath. Press `I` again to bring them back.
+- `V` *(4.7.0, BelAtro only)*: Open the read-only inventory overlay (jokers, vouchers, consumables, permanent bonuses, contract levels). Pre-4.7.0 this was an alias of `I`; it's now its own thing.
 
 ## Features
 
 - **BelAtro Roguelite Mode:** A massive expansion featuring 42 Jokers, 12 Tarot cards, 8 Planets, 12 Vouchers, and permanent upgrades.
+- **Dix de Der Heist (4.7.0):** Take a contract and declare a heist before trick 1 — win trick 8 for a `×(1 + interest_rate)` Mult multiplier on your round score; lose it and forfeit your card chips from tricks 1–7. Gated on owning **La Voûte** voucher (`interest_rate > 0`). AI never declares.
+- **Slot-Machine Score Tally (4.7.0):** Per-trick odometer animation replaces the static popup. Chip-bucket fills, mult pulses, total ticks toward target, and a flame row crowns the odometer when you blow past 120% of the blind. Skippable on SPACE / ESC / ENTER. Final readout persists in the HUD between tricks (toggled by `I` alongside the top HUD). Suppressed under Le Brouillard (`hide_hud`) and La Compétition (`separate_scoring`).
+- **Inventory Overlay on V (4.7.0):** Press `V` mid-game to inspect everything you own — jokers (with edition tags + per-edition bonus blurb), vouchers, consumables, permanent chip / mult bonuses, and per-contract planet levels. List view → ↑/↓ navigate, Enter for detail, Esc/V/Q close. Read-only counterpart to the `C` consumables-action tray.
 - **Collection (Almanac):** Persistent tracker to browse every Joker, Planet, and Voucher you've discovered across your runs.
 - **Full Boss Blind Suite:** All 21 unique bosses implemented, including complex mechanics like *L'Anarchie* (dynamic trump) and *La Rupture* (no consecutive wins).
 - **Multiplier Scoring:** Use items to stack Multipliers and reach scores in the millions.
@@ -258,7 +263,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 (941 tests)
+├── tests/             # Comprehensive test suite (1003 tests)
 ├── scripts/           # Performance benchmarks
 ├── pyproject.toml      # Build system and dev dependencies (ruff/mypy)
 ├── LICENSE             # MIT License
@@ -273,14 +278,14 @@ belote/
 PYTHONPATH=src pytest
 ```
 
-Currently **941 tests** passing with 100% coverage on game-logic modules (4.6.5).
+Currently **1003 tests** passing with 100% coverage on game-logic modules (4.7.2).
 
 ## Technical Integrity
 
 The codebase is strictly validated with the following tools:
 - **mypy**: 0 errors (strict type safety)
 - **ruff**: 0 violations (linting & formatting)
-- **pytest**: 941/941 passed
+- **pytest**: 1003/1003 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-4.6.5 → belote_cli-4.7.2}/README.md

@@ -132,7 +132,8 @@ belote --difficulty hard --target 500 --seed 123 --speed fast
 
 **General:**
 - `?`: Show keyboard shortcut help
-- `I` or `V` *(BelAtro only)*: Toggle the BelAtro top HUD overlay — see the BelAtro gameplay note below for details
+- `I` *(BelAtro only)*: Toggle the BelAtro top HUD overlay AND the persistent slot-machine tally readout — see the BelAtro gameplay note below for details
+- `V` *(4.7.0, BelAtro only)*: Open the **Inventory** overlay (jokers, vouchers, consumables, permanent bonuses, contract levels). ↑/↓ navigate, Enter for detail, Esc/V/Q close. Distinct from `C` (Consumables tray, action-oriented); `V` is read-only inspection.
 - `Q`: Quit to main menu or exit
 - `H`: View Game History (round-by-round, with contract / taker / tricks / declarations)
 - `T`: Cycle UI Theme
@@ -154,11 +155,15 @@ belote --difficulty hard --target 500 --seed 123 --speed fast
 - `Z`: Undo last move
 - `Space` or `Esc`: Skip animations
 - During bidding round 2: `P` = Pass, `X` = Tout Atout, `N` = Sans Atout *(remapped from A/S in 4.5.0 to make room for WASD nav)*
-- `I` or `V` *(4.6.3, BelAtro only)*: Toggle the BelAtro top HUD (joker pip strip, ante/blind/target line, chips×mult score, trust bar, synergy tooltip). Visible by default; press `I` to hide it and reveal the classic Belote HUD's `Trump:` / `Taker:` fields underneath. Press `I` again to bring the overlay back.
+- `I` *(4.6.3, BelAtro only)*: Toggle the BelAtro top HUD (joker pip strip, ante/blind/target line, chips×mult score, trust bar, synergy tooltip) AND, since 4.7.0, the persistent slot-machine tally readout at the bottom. Visible by default; press `I` to hide both and reveal the classic Belote HUD's `Trump:` / `Taker:` fields underneath. Press `I` again to bring them back.
+- `V` *(4.7.0, BelAtro only)*: Open the read-only inventory overlay (jokers, vouchers, consumables, permanent bonuses, contract levels). Pre-4.7.0 this was an alias of `I`; it's now its own thing.
 
 ## Features
 
 - **BelAtro Roguelite Mode:** A massive expansion featuring 42 Jokers, 12 Tarot cards, 8 Planets, 12 Vouchers, and permanent upgrades.
+- **Dix de Der Heist (4.7.0):** Take a contract and declare a heist before trick 1 — win trick 8 for a `×(1 + interest_rate)` Mult multiplier on your round score; lose it and forfeit your card chips from tricks 1–7. Gated on owning **La Voûte** voucher (`interest_rate > 0`). AI never declares.
+- **Slot-Machine Score Tally (4.7.0):** Per-trick odometer animation replaces the static popup. Chip-bucket fills, mult pulses, total ticks toward target, and a flame row crowns the odometer when you blow past 120% of the blind. Skippable on SPACE / ESC / ENTER. Final readout persists in the HUD between tricks (toggled by `I` alongside the top HUD). Suppressed under Le Brouillard (`hide_hud`) and La Compétition (`separate_scoring`).
+- **Inventory Overlay on V (4.7.0):** Press `V` mid-game to inspect everything you own — jokers (with edition tags + per-edition bonus blurb), vouchers, consumables, permanent chip / mult bonuses, and per-contract planet levels. List view → ↑/↓ navigate, Enter for detail, Esc/V/Q close. Read-only counterpart to the `C` consumables-action tray.
 - **Collection (Almanac):** Persistent tracker to browse every Joker, Planet, and Voucher you've discovered across your runs.
 - **Full Boss Blind Suite:** All 21 unique bosses implemented, including complex mechanics like *L'Anarchie* (dynamic trump) and *La Rupture* (no consecutive wins).
 - **Multiplier Scoring:** Use items to stack Multipliers and reach scores in the millions.
@@ -215,7 +220,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 (941 tests)
+├── tests/             # Comprehensive test suite (1003 tests)
 ├── scripts/           # Performance benchmarks
 ├── pyproject.toml      # Build system and dev dependencies (ruff/mypy)
 ├── LICENSE             # MIT License
@@ -230,14 +235,14 @@ belote/
 PYTHONPATH=src pytest
 ```
 
-Currently **941 tests** passing with 100% coverage on game-logic modules (4.6.5).
+Currently **1003 tests** passing with 100% coverage on game-logic modules (4.7.2).
 
 ## Technical Integrity
 
 The codebase is strictly validated with the following tools:
 - **mypy**: 0 errors (strict type safety)
 - **ruff**: 0 violations (linting & formatting)
-- **pytest**: 941/941 passed
+- **pytest**: 1003/1003 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-4.6.5 → belote_cli-4.7.2}/pyproject.toml

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

{belote_cli-4.6.5 → belote_cli-4.7.2}/src/belote/__init__.py

@@ -1,3 +1,3 @@
-__version__ = "4.6.5"
+__version__ = "4.7.2"
 
 __all__ = ["__version__"]