valmathieu · valmathieu · Jul 25, 2026 · Jun 20, 2026 · Jun 20, 2026 · Jun 21, 2026
diff --git a/.gitignore b/.gitignore
@@ -38,4 +38,9 @@ Thumbs.db
 # commands, hooks) but NOT per-user local overrides (machine-specific paths,
 # personal preferences).
 .claude/settings.local.json
-CLAUDE.md
+CLAUDE.md
+
+# Superpowers planning documents (brainstorm specs, implementation plans) are
+# session artifacts, not repo docs - keep them local.
+docs/superpowers/
+docs/plans/
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,17 +2,68 @@
 
 All notable changes to the ContrAI workspace are documented here.
 
-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).
+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).
 All four workspace packages (`contrai-core`, `contrai-engine`, `contrai-analyzer`,
 `contrai-scraper`) are versioned in lockstep — a single version covers the whole workspace.
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-07-25
+
+Hardening release: the play phase moves into the core as an immutable `PlayState` state machine with an imperfect-information `PlayObservation` for AI strategies, the expert AI bids and plays from sounder rules, and the whole TUI took a review pass.
+
+### Added
+
+- (core) `PlayState` play-phase state machine, the play-side sibling of `Auction`: an
+  immutable, trick-by-trick state that owns the follow/trump legality rules, enforces turn order and the new `OUT_OF_TURN`/`CARD_NOT_IN_HAND` violation reasons through `apply`, and can be forked onto replacement hands via `with_hands` for future search-based AIs.
+- (core) `PlayObservation` imperfect-information view: the projection of a `PlayState` that a single player is allowed to see (own hand, public trick history, legal cards), the input surface for AI card-play strategies.
+- (engine) The expert AI's card play now reasons from sound card tracking: fallen cards and
+  per-seat voids (trump and plain suits alike) are derived from the public trick history, with
+  careful inference — any failure to follow records a void, but a seat discarding behind its
+  master partner is not read as trump-void. On that foundation the AI stops pulling trumps once
+  both opponents are known void in trump (remaining unseen trumps can only sit in partner's
+  hand), preserves master cards behind a winning partner by giving the next-highest card instead
+  (partner's Ace promotes its Ten to suit master — the Ten is kept for a later trick, trump-led
+  tricks included), and anticipates opponent ruffs — when an opponent still to play is proven
+  void in the led suit and may still hold trump, it stops piling points behind a winning partner
+  and contests a losing trick with the smallest card that beats the current best rather than the
+  fattest.
+
+### Changed
+
+- (engine) Card-play strategies now receive a single frozen `PlayObservation` — the
+  seat's own hand, the public trick history, and its legal cards — and derive any card
+  tracking from it, so a strategy is sealed off from another seat's hand by construction through what it is handed; sealing the live player refs on `Play` is a noted follow-up.
+- (engine) The trick loop is now driven by the core `PlayState`: `Round` seeds an
+  immutable play-phase state at the start of play, derives the legal cards from it, and
+  mirrors the players' hands and the current trick from it each play; card-play legality
+  moved to `contrai-core` wholesale. An absent or illegal card now raises
+  `IllegalPlayError` (`CARD_NOT_IN_HAND`) instead of being silently skipped.
+- (engine) Unify the internal bid representation on core `Bid`/`Auction` objects and
+  remove the legacy wire-format bridge — the rule-based AI and the bidding view now operate directly on typed `Bid` objects. Behaviour is unchanged.
+- (engine) The expert AI now resolves its best (contract, suit) pair once per bidding
+  turn — the duplicated best-contract scans in the overbid check and the initial-bid
+  builder are folded into a single helper that also owns the suit tie-break.
+
+### Removed
+
+- (engine) The `initialize_card_tracking` / `update_card_tracking` hooks on
+  `CardPlayStrategy` / `AiPlayer` (public since 0.1.0) — card tracking is now derived
+  from the observation rather than pushed to per-strategy state each play.
+
+### Fixed
+
+- (engine) Expert AI partner-support escalation: every supporting turn re-added the seat's full complement (+10 per external ace, +10 for the trump complement) on top of the *standing* contract, so partners alternately raised each other far past their combined strength (an 80 opening ratcheting to 160+, at which point the opponents' double heuristic armed itself on the inflated value), and a seat could even "support" its own bid after an opponent overbid. Support is now capped at a team ceiling — partner's opening bid plus the supporter's complement, announced once — and a seat never supports a suit it opened itself.
+- (engine) Landing screen now labels the three AI seats `AI · expert` instead of `AI · medium` — the bots play the expert strategy, which is the only level wired today.
+- (engine) Expert AI suit tie-break: with several suits tied for the best contract, the
+  AI always fell back to Spades — even when Spades never met the bidding table — and ignored the belote preference when more than one tied suit held a belote. It now picks among the tied suits only, preferring belote holders.
+- (engine) The "Unrecognized bid" notice now suggests the cheapest raise the auction still allows (e.g. `'100 h'` once 90 stands) instead of a fixed `'80 h'`, dropping the numeric example entirely once only Slam-family raises remain.
+- (engine) A game no longer ends without a winner when both teams finish a round level at or above the target score: the tie is sudden death — tiebreaker rounds are dealt until one team leads, the round recap announcing each one — so the game-over banner always names a winning team.
+- (core) Illegal-play errors now name the acting seat: `PlayState.apply` attaches a `<position> card play` context to every `IllegalPlayError`, so rejection diagnostics say who misplayed as well as which card and why.
+
 ## [0.1.0] - 2026-06-21
 
-First playable release: a complete CLI Contrée engine backed by a shared domain model,
-plus the standalone hand analyzer and the spectator-mode scraper.
+First playable release: a complete CLI Contrée engine backed by a shared domain model, plus the standalone hand analyzer and the spectator-mode scraper.
 
 ### Added
 
@@ -32,5 +83,6 @@ plus the standalone hand analyzer and the spectator-mode scraper.
   Online → Spectator → Contree → Tournament navigation, seat identification, and `#tour`
   round polling.
 
-[Unreleased]: https://github.com/valmathieu/ContrAI/compare/v0.1.0...HEAD
+[Unreleased]: https://github.com/valmathieu/ContrAI/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/valmathieu/ContrAI/compare/v0.1.0...v0.2.0
 [0.1.0]: https://github.com/valmathieu/ContrAI/releases/tag/v0.1.0
diff --git a/contree-domain.md b/contree-domain.md
@@ -287,6 +287,28 @@ Slam grid below:
 always credited to the team **holding** K + Q of trump (not whoever captures
 those cards in a trick — see §6.5), on top of everything else, win or lose.
 
+#### Unannounced capot
+
+If the declaring team wins **all 8 tricks** on a numeric contract *without
+having bid a Slam*, the trick pile (152 cards + 10 *dix de der* = 162) is
+replaced by a flat **250** substitute: the declarer scores `C + 250`, the
+defense scores nothing, and the contract is necessarily **made** (sweeping
+every trick cannot fail). This mirrors the announced-Slam shape but keeps the
+numeric contract value `C` as the base.
+
+- Whether the contracting player took all 8 tricks **personally** (a *grand
+  slam*) or the team split them (a plain *slam*), the substitute is the same
+  250 — the distinction is only descriptive.
+- **Un-doubled only.** A doubled / redoubled sweep keeps the winner-takes-all
+  `160 + C × M` shape above; the 250 substitute does **not** apply.
+- **Declaring team only.** If the *defense* takes all 8 tricks the declarer
+  has simply *chuté* — score it as an ordinary failed contract (`160 + C`),
+  not as a capot.
+- **Belote (+20)** still layers on top for the holding team, as everywhere.
+
+> Worked example: contract `100 ♠`, declarer sweeps all 8 → declarer
+> 350 (`100 + 250`), defense 0.
+
 #### Slam and Solo Slam
 
 Slam-family contracts keep the same shape as numeric contracts — the at-risk
@@ -342,6 +364,9 @@ defense.
 - A target score is agreed before the game (typical: **1500** or **2000**).
 - The first team to reach or exceed the target at the end of a round wins.
 - If both teams cross the target in the same round, the higher score wins.
+- If both teams sit at the **same score** at or above the target, nobody has
+  won yet: play continues with additional rounds (sudden death) until one
+  team leads.
 
 ---
 
@@ -487,7 +512,8 @@ threshold; details live alongside the AI implementation.*
 [Scoring]   → sum cards + dix de der (+ belote if applicable)
               apply contract success/failure + multiplier
    ↓
-[Check]     → if any team ≥ target (1500/2000): end game
+[Check]     → if one team strictly leads at ≥ target (1500/2000): end game
+              tie at ≥ target: sudden death, keep playing until one team leads
               else next round, dealer rotates right
 ```
 

diff --git a/docs/ai-ladder/rule_based.md b/docs/ai-ladder/rule_based.md
@@ -1,7 +1,9 @@
 # Rule-based AI
 
-Hand-coded expert strategies. Currently implemented as `AiPlayer` in `contrai-engine` (expert bidding table + card-play heuristics; specs SF-09, SF-10).
+Hand-coded expert strategies (expert bidding table + card-play heuristics; specs SF-09, SF-10). They are the **first concrete rung** of the AI ladder, implemented in `contrai-engine` as the `RuleBasedBiddingStrategy` / `RuleBasedCardPlayStrategy` pair — concrete implementations of the `BiddingStrategy` / `CardPlayStrategy` interfaces. They are injected into `AiPlayer` (the default strategies) and registered as `AI_LEVELS["expert"]`, so a future MCTS or learned level is a new strategy class rather than an edit to `AiPlayer`. See the [engine docs](../engine/index.md#ai-players) for the injection seam.
 
-**Explainability:** the rule trace is the rationale — log which rule fired for each bid/play.
+`RuleBasedCardPlayStrategy` is stateless between calls: every decision is a pure function of the single frozen `PlayObservation` it is handed for that turn. Whatever card tracking the heuristics need — which cards have fallen, which seats are known void in trump — is derived fresh each turn by replaying the observation's public trick history, never carried across calls or rounds. Because the observation is the only input a strategy ever receives, it is sealed off from another seat's hand by construction — through what it is handed; sealing the live player refs on `Play` is a noted follow-up.
+
+**Explainability:** the rule trace is the rationale — log which rule fired for each bid/play. The strategy object is the natural home for that trace (AI roadmap §6.1).
 
 > TODO: rule catalogue; planned extensions (deeper card counting, partner inference, signal-based bidding).
diff --git a/docs/architecture.md b/docs/architecture.md
@@ -7,7 +7,7 @@ Overview of how the four ContrAI packages fit together.
 The repository is a [uv workspace](https://docs.astral.sh/uv/concepts/projects/workspaces/) with four members under `packages/`:
 
 - **`contrai-core`** — shared domain model. Owns `Suit`/`Rank`/`CARD_SUITS`, `Card`, `Deck`, `Hand`, `Team`, `BasePlayer`, the frozen `Bid` sum type, the `Auction` state-and-rule oracle, `Contract`, `Trick`, and the model-level exceptions (a `ContraiError` base, plus `IllegalBidError` / `IllegalPlayError` and friends). Pure data and invariants, no orchestration.
-- **`contrai-engine`** — game engine on top of `contrai-core`. Extends `BasePlayer` with `Player` / `HumanPlayer` / `AiPlayer`, owns `Game` and `Round` orchestration, and ships the Rich-based `contrai` terminal UI (`view/rich_view.py` + `cli.py`). See [Engine — CLI](engine/index.md#cli).
+- **`contrai-engine`** — game engine on top of `contrai-core`. Extends `BasePlayer` with `Player` / `HumanPlayer` / `AiPlayer`, owns `Game` and `Round` orchestration, and ships the Rich-based `contrai` terminal UI (the `view/` package — `RichView` orchestrator plus per-screen builders — wired in `cli.py`). See [Engine — CLI](engine/index.md#cli).
 - **`contrai-analyzer`** — Streamlit dashboard for opening-hand strength (hypergeometric distribution + bidding truth-table). Deliberately independent of `contrai-core`; see [`analyzer/index.md`](analyzer/index.md) for the rationale behind the `SuitSlot` abstraction.
 - **`contrai-scraper`** — Playwright spectator-mode scraper for online Coinche games. v1 ships login + table navigation + per-round polling; bidding/play observation and persistence are still to be wired up.