mozempk/scopone
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 228 Activity

feat(SCOPONE-0010): improve capture pacing and settings

Browse Source
This commit is contained in:
Giancarmine Salucci
2026-04-09 23:00:59 +02:00
parent 77ab1f43a6
commit c107489b0a
7 changed files with 740 additions and 176 deletions
Download Patch File Download Diff File Expand all files Collapse all files

116
docs/ARCHITECTURE.md
View File

@@ -1,6 +1,6 @@
# Architecture
> Last Updated: 2026-04-08T19:48:08.000Z
> Last Updated: 2026-04-09T20:59:51.000Z
## Overview
@@ -8,14 +8,15 @@
|-----------|-------|
| Primary language | TypeScript |
| Secondary language | Java |
| Source counts | 15 TypeScript files under `src/`, 3 Java files under `android/` |
| Project type | Phaser browser game packaged for Android with Capacitor |
| Framework | Phaser 3.87.0 |
| Tooling | Vite 5, TypeScript 5.x, Capacitor 8.3 |
| Tooling | Vite 5, TypeScript 5.x, Capacitor 8.3, tsx 4.19 |
| Runtime layout | 1280 x 720, `Phaser.Scale.FIT`, centered in `#game` |
| Build command | `npm run build` |
| Test command | `npx tsc --noEmit` |
The repository is a TypeScript-first implementation of Scopone Scientifico. Gameplay rules, scoring, inference, and AI live in framework-independent modules under `src/game/`. Phaser scenes under `src/scenes/` own rendering, input, UI, animation, and scene transitions. The `android/` tree is a Capacitor wrapper with a small custom `MainActivity` for immersive full-screen behavior.
The repository is a TypeScript-first implementation of Scopone Scientifico. Pure game rules, scoring, imperfect-information tracking, AI heuristics, worker transport, and benchmark code live under `src/game/`. Phaser scenes under `src/scenes/` own rendering, input, animation, menu flow, status messaging, and procedural audio. The `android/` tree is a Capacitor wrapper with a small custom `MainActivity` that forces immersive full-screen behavior.
## Project Structure
@@ -27,13 +28,17 @@ scopone-phaser/
| | |- types.ts
| | |- engine.ts
| | |- card-tracker.ts
| | |- preferences.ts
| | |- ai.ts
| | |- ai-worker-protocol.ts
| | |- ai-worker-client.ts
| | `- ai.worker.ts
| | |- ai.worker.ts
| | |- ai-benchmark.ts
| | `- ai-benchmark-fixtures.ts
| `- scenes/
| |- BootScene.ts
| |- MenuScene.ts
| |- SettingsScene.ts
| `- GameScene.ts
|- public/
|- android/
@@ -51,9 +56,9 @@ scopone-phaser/
| Directory | Purpose |
|-----------|---------|
| `src/game/` | Rules engine, score calculation, imperfect-information tracking, AI heuristics, and master search |
| `src/scenes/` | Phaser scene lifecycle, menus, board rendering, interaction, HUD, audio, and FX |
| `public/` | Atlas metadata and other static assets loaded by Phaser |
| `src/game/` | Rules engine, score calculation, imperfect-information tracking, audio preference persistence, AI heuristics, worker transport, and benchmark harnesses |
| `src/scenes/` | Phaser scene lifecycle, menus, settings UI, board rendering, interaction, HUD, audio, and FX |
| `public/` | Atlas metadata and static assets loaded by Phaser |
| `android/` | Capacitor Android project, Gradle configuration, generated wrapper assets, and the native activity |
| `docs/` | Architecture, code style, findings, and cache metadata |
| `prompts/` | JIRA workflow artifacts and iteration state |
@@ -66,46 +71,53 @@ Observed architectural patterns:
| Pattern | Where it appears |
|---------|------------------|
| Scene-based flow | `BootScene -> MenuScene -> GameScene` via Phaser scene registration |
| Scene-based flow | `BootScene -> MenuScene -> GameScene`, with `SettingsScene` opened from the menu and returning to it |
| Functional core / imperative shell | `src/game/` avoids Phaser imports while `src/scenes/` owns runtime side effects |
| Immutable state transitions | `applyMove()` clones `GameState` before mutating round state |
| Worker offload with fallback | `AIWorkerClient` uses `ai.worker.ts` when available and falls back to direct `chooseMove()` otherwise |
| Typed message protocol | `ai-worker-protocol.ts` defines worker request, progress, result, and error shapes |
| Imperfect-information search | `CardTracker` plus determinization sampling support the `master` AI tier |
| Typed message protocol | `ai-worker-protocol.ts` defines worker request, progress, result, and serialized error shapes |
| Persistence adapter | `preferences.ts` normalizes and stores audio settings through a storage boundary instead of scene-local flags |
| Deterministic benchmark harness | `ai-benchmark.ts` uses fixtures, seeded self-play, and simulated timing sources to evaluate AI quality |
## Key Components
### `src/main.ts`
- Creates the `Phaser.Game` instance.
- Registers `BootScene`, `MenuScene`, and `GameScene`.
- Installs a one-shot fullscreen request on first user input when supported.
- Registers `BootScene`, `MenuScene`, `GameScene`, and a local `SettingsScene` placeholder; `MenuScene` replaces that placeholder with the concrete `src/scenes/SettingsScene.ts` class before navigation.
### `src/game/types.ts`
- Defines the core game model: `Card`, `Capture`, `Player`, `GameState`, `TeamScore`, and `ScoreBreakdown`.
- Models constrained domains with unions such as `PlayerIndex` and `Difficulty`.
- Models constrained domains with unions such as `PlayerIndex`, `Difficulty`, and `DealerRelativeRole`.
- Stores `PRIMIERA_VALUES` for end-of-round scoring.
### `src/game/engine.ts`
- Builds and shuffles the 40-card deck.
- Creates a round state for four players with dealer-relative opening order.
- Implements capture rules where direct value matches take priority over subset-sum captures.
- Applies moves immutably, awards scope, assigns leftover table cards, and computes round and match scoring.
- Creates a round state for four players with dealer-relative opening order and stable player labels.
- Implements Scopone capture rules where direct value matches take priority over subset-sum captures.
- Applies moves immutably, awards scopa only before the final play, assigns leftover table cards to the last capturing team, and computes round and match scoring.
### `src/game/card-tracker.ts`
- Tracks cards visible through play and capture events without exposing hidden hands.
- Reconstructs unseen cards from `played + myHand + table`.
- Supplies value and suit residue helpers used by AI inference and probability estimates.
- Supplies suit counts, same-rank residue summaries, and hand-value probabilities used by the AI tiers.
### `src/game/preferences.ts`
- Defines the persisted audio preference model.
- Normalizes possibly invalid storage payloads back to safe defaults.
- Loads and saves preferences through `localStorage` when available, with browser-safe fallbacks.
### `src/game/ai.ts`
- Exposes `chooseMove()` as the async AI entry point.
- Implements three difficulty tiers: `beginner`, `advanced`, and `master`.
- Uses table-driven search profiles, role-aware heuristics, tracker-based inference, and determinization plus alpha-beta search.
- Configures the current master profile with a 4600 ms budget, 10 samples, depth 6, and batch size 2.
- Uses role-aware heuristics, tracker-based inference, tactical priority scoring, determinization sampling, and alpha-beta search.
- Applies dynamic master search profiles based on total cards remaining, ranging from the base profile `4300 ms / 8 samples / depth 5 / batch 2` down to `3200 ms / 4 samples / exact endgame depth / batch 1` in the last four cards.
### `src/game/ai-worker-protocol.ts`
@@ -117,7 +129,7 @@ Observed architectural patterns:
- Wraps worker lifecycle and pending-request tracking behind the same `chooseMove()` API that scenes consume.
- Creates the worker as an ES module with `new Worker(new URL('./ai.worker.ts', import.meta.url), { type: 'module' })`.
- Fails over pending requests to in-thread AI execution if worker creation, messaging, or deserialization fails.
- Fails over pending requests to in-thread AI execution if worker creation, posting, or deserialization fails.
### `src/game/ai.worker.ts`
@@ -125,6 +137,12 @@ Observed architectural patterns:
- Delegates move selection to `chooseMove()`.
- Posts progress, result, or serialized error messages back to the main thread.
### `src/game/ai-benchmark.ts` and `src/game/ai-benchmark-fixtures.ts`
- Define the AI quality harness invoked by `npm run benchmark:ai-quality`.
- Combine fixed fixtures, critical-concept checks, seeded self-play, regression watchlists, and simulated timing sources.
- Encode the current iteration 5 benchmark contract: 13 fixed fixtures, 6 critical concepts, and 48 self-play matches.
### `src/scenes/BootScene.ts`
- Loads the card atlas and card back.
@@ -133,13 +151,22 @@ Observed architectural patterns:
### `src/scenes/MenuScene.ts`
- Renders the title, rules summary, and difficulty selection.
- Starts `GameScene` with the chosen difficulty.
- Renders the title, compact rules summary, difficulty selection, and audio-settings entry point.
- Reads persisted audio preferences to describe current state before match start.
- Ensures the concrete `SettingsScene` class is registered before opening it.
### `src/scenes/SettingsScene.ts`
- Provides a dedicated audio settings surface.
- Toggles music and effects independently.
- Saves each change immediately and returns control to the menu scene.
### `src/scenes/GameScene.ts`
- Owns match flow, dealing, selection, capture resolution, AI turn orchestration, score HUD, status UI, think bar, particles, and procedural audio.
- Instantiates and disposes `AIWorkerClient` on scene lifecycle events.
- Enforces a minimum AI think display time and timer-based move outcome status messages.
- Reads normalized audio preferences from scene data or persisted storage.
- Updates `CardTracker` after play and capture events so AI inference remains derived from visible information.
### `android/app/src/main/java/com/phaser/scopa/MainActivity.java`
@@ -163,6 +190,7 @@ Observed architectural patterns:
| Package | Version | Purpose |
|---------|---------|---------|
| `tsx` | `^4.19.2` | TypeScript execution for benchmark and prompt-local tooling |
| `typescript` | `^5.0.0` | Static type checking and TS compilation step |
| `vite` | `^5.0.0` | Dev server and production bundler |
@@ -191,14 +219,21 @@ Observed architectural patterns:
main.ts
-> BootScene
-> MenuScene
-> GameScene
-> engine.ts
-> types.ts
-> card-tracker.ts
-> ai-worker-client.ts
-> ai-worker-protocol.ts
-> ai.worker.ts
-> ai.ts
-> SettingsScene (opened on demand after dynamic registration)
-> GameScene
-> engine.ts
-> types.ts
-> preferences.ts
-> card-tracker.ts
-> ai-worker-client.ts
-> ai-worker-protocol.ts
-> ai.worker.ts
-> ai.ts
ai-benchmark.ts
-> ai.ts
-> ai-benchmark-fixtures.ts
-> engine.ts
-> card-tracker.ts
```
Application-level dependency direction is one-way:
@@ -209,16 +244,18 @@ Application-level dependency direction is one-way:
## Data Flow
1. `main.ts` creates the Phaser app and registers all scenes.
2. `BootScene` loads textures and starts `MenuScene`.
3. `MenuScene` passes the chosen difficulty to `GameScene`.
4. `GameScene.create()` creates a fresh `CardTracker`, constructs a new `GameState`, and starts the opening deal.
5. Human turns use pointer-driven card selection and `findCaptures()` output to choose legal captures.
6. AI turns call `AIWorkerClient.chooseMove(state, playerIdx, difficulty, tracker, onProgress)`.
7. `AIWorkerClient` posts a typed request to `ai.worker.ts`; if workers are unavailable, it reruns the same request in-thread.
8. `chooseMove()` returns a heuristic move for lower tiers or performs batched master search while emitting `AIDecisionProgress`.
9. `GameScene` updates the think bar from progress callbacks, executes the returned move, records tracker state, and advances turn order.
10. When every hand is empty, `engine.ts` finalizes scoring and `GameScene` presents the round or match outcome.
1. `main.ts` creates the Phaser app, installs fullscreen-on-first-input, and registers the scene list.
2. `BootScene` loads atlas assets and starts `MenuScene`.
3. `MenuScene` reads persisted audio preferences, lets the player choose difficulty, and can open `SettingsScene` for audio toggles.
4. `SettingsScene` writes audio preferences immediately and returns to `MenuScene`.
5. `GameScene.create()` normalizes incoming scene data, creates a fresh `CardTracker`, constructs a new `GameState`, and starts the opening deal.
6. Human turns use pointer-driven card selection and `findCaptures()` output to choose legal captures.
7. AI turns call `AIWorkerClient.chooseMove(state, playerIdx, difficulty, tracker, onProgress)`.
8. `AIWorkerClient` posts a typed request to `ai.worker.ts`; if workers are unavailable, it reruns the same request in-thread.
9. `chooseMove()` returns a heuristic move for lower tiers or performs batched master search while emitting `AIDecisionProgress`.
10. `GameScene` updates the think bar from progress callbacks, enforces a minimum visible think time, executes the returned move, records tracker state, and advances turn order.
11. When every hand is empty, `engine.ts` finalizes scoring and `GameScene` presents the round or match outcome.
12. Separately, `ai-benchmark.ts` exercises the same game and AI modules through fixed fixtures, seeded self-play, and simulated timing to produce quality summaries.
## Build System
@@ -227,4 +264,5 @@ Application-level dependency direction is one-way:
| `npm run dev` | `package.json` | Starts the Vite dev server |
| `npm run build` | user-provided build command | Runs `tsc && vite build` and writes web output to `dist/` |
| `npm run preview` | `package.json` | Serves the built app with Vite preview |
| `npm run benchmark:ai-quality` | `package.json` | Runs the AI benchmark harness through `tsx` |
| `npx tsc --noEmit` | user-provided test command | Type-checks the TypeScript codebase without emitting files |

84
docs/FINDINGS.md
View File

@@ -1,34 +1,40 @@
# Findings
> Last Updated: 2026-04-09T00:00:00.000Z
> Last Updated: 2026-04-09T20:59:51.000Z
## Summary
Initializer refresh for SCOPONE-0009. The cached findings were stale relative to the live source tree, so the observations below reflect the current Phaser, worker, and AI implementation.
Initializer refresh for SCOPONE-0010. The cache was invalid because `docs/FINDINGS.md` no longer matched its recorded hash, and the architecture document no longer matched the live source layout after settings, preferences, and benchmark changes. The observations below reflect the current repository state.
## Codebase Observations
- Primary gameplay code currently lives in 10 TypeScript source files under `src/`; the Android wrapper adds 3 Java files.
- Primary gameplay code currently lives in 15 TypeScript source files under `src/`; the Android wrapper adds 3 Java files.
- The project is structurally split between framework-free gameplay modules in `src/game/` and Phaser scene code in `src/scenes/`.
- `src/scenes/GameScene.ts` and `src/game/ai.ts` remain the two largest concentrations of application logic.
- The AI transport layer is now a stable three-file path: `ai-worker-protocol.ts`, `ai-worker-client.ts`, and `ai.worker.ts`.
- A dedicated audio preference path now exists: `src/game/preferences.ts`, `src/scenes/MenuScene.ts`, and `src/scenes/SettingsScene.ts`.
- `main.ts` still contains a local `SettingsScene` placeholder class, while `MenuScene.ensureSettingsSceneAvailable()` swaps in the concrete imported scene before navigation.
- The AI transport layer is a stable three-file path: `ai-worker-protocol.ts`, `ai-worker-client.ts`, and `ai.worker.ts`.
- The AI exposes three difficulty levels: `beginner`, `advanced`, and `master`.
- `advanced` and `master` both use `CardTracker` to reason about unseen cards without directly reading hidden hands.
- The current `master` search profile is `timeBudgetMs: 4600`, `sampleCount: 10`, `maxDepth: 6`, `batchSize: 2`.
- The base `master` search profile is `4300 ms / 8 samples / depth 5 / batch 2`, with tighter endgame branches down to `3200 ms / 4 samples / exact remaining depth / batch 1` when 4 cards remain.
- `GameScene` consumes AI progress callbacks to update an on-screen think bar while a worker request is running.
- `GameScene` now enforces `AI_MIN_THINK_MS = 1000` and `MOVE_OUTCOME_STATUS_MS = 2000` through timer-backed scene logic.
- `AIWorkerClient` fails over pending work to in-thread `chooseMove()` if worker creation, posting, or deserialization fails.
- The AI benchmark harness is now in source under `src/game/ai-benchmark.ts` and `src/game/ai-benchmark-fixtures.ts`, and `package.json` exposes it as `npm run benchmark:ai-quality`.
- The current benchmark contract is iteration 5: 13 fixed fixtures, 6 critical concepts, and 48 self-play matches.
- The Android wrapper targets SDK 36 with `minSdkVersion` 24 and applies immersive mode from the native activity.
- Audio remains procedural via Web Audio; no dedicated audio asset pipeline is present in the source tree.
- Audio remains procedural via Web Audio; there is still no dedicated audio asset pipeline in the source tree.
- No ESLint or Prettier configuration is present.
- The only repository-wide verification command supplied is `npx tsc --noEmit`.
## Potential Improvement Areas
- `GameScene.ts` still centralizes layout, turn flow, HUD updates, effects, and audio in one scene class, which raises maintenance cost.
- `ai.ts` still combines heuristic tiers, inference helpers, determinization, and alpha-beta evaluation in one module.
- Worker transport is isolated cleanly, but progress rendering remains coupled to scene-level UI concerns.
- A 4600 ms master search budget may still be noticeable on slower mobile devices even with batch yielding.
- There is no dedicated automated rules or AI test suite beyond type-checking.
- `GameScene.ts` still centralizes layout, turn flow, HUD updates, effects, audio, status messaging, and AI orchestration in one scene class.
- `ai.ts` still combines heuristic tiers, inference helpers, determinization, move ordering, and alpha-beta evaluation in one module.
- The current settings flow works, but the dual registration pattern for `SettingsScene` in `main.ts` plus dynamic replacement in `MenuScene` is fragile and worth simplifying later.
- Worker transport is isolated cleanly, but progress rendering and fallback behavior remain coupled to scene-level UI concerns.
- A 3.2 to 4.35 second master search window may still be noticeable on slower mobile devices even with yielding and the minimum-think pacing already in place.
- There is no dedicated automated rules test suite beyond type-checking and the AI benchmark harness.
- Formatting and style are enforced socially rather than by automated linting or formatting tools.
## Current Rule / Implementation Notes
@@ -39,14 +45,15 @@ Initializer refresh for SCOPONE-0009. The cached findings were stale relative to
- When multiple direct matches exist, `findCaptures()` returns one single-card option per matching card.
- Subset-sum captures are considered only when no direct match exists.
- `applyMove()` defaults to the first legal capture if no explicit capture choice is supplied.
- Scope is awarded only when a capture clears the table before the final play of the round.
- Scopa is awarded only when a capture clears the table before the final play of the round.
### AI implementation snapshot
- `beginner` uses a simpler heuristic with noise to remain beatable.
- `advanced` adds race awareness, anti-scopa logic, partner setup, anchor play, and tracker-based probability estimates.
- `master` orders legal moves with a quick evaluator, samples hidden hands, and scores them with alpha-beta search under the active deadline.
- `advanced` adds race awareness, anti-scopa logic, partner setup, denari pressure, and tracker-based probability estimates.
- `master` orders legal moves with a quick evaluator, samples hidden hands, and scores them with alpha-beta search under a dynamic deadline.
- Progress is reported through `AIDecisionProgress` so the scene can keep the think bar responsive.
- `CardTracker` now exposes same-rank residue summaries through `getValueRankResidue()` and `getValueRankResidueSummary()`, and those semantics are the live inference surface for unseen-value reasoning.
### Worker execution snapshot
@@ -59,11 +66,19 @@ Initializer refresh for SCOPONE-0009. The cached findings were stale relative to
### Scene / UI implementation snapshot
- `BootScene` loads atlas assets and presents a simple loading bar.
- `MenuScene` exposes difficulty selection before match start.
- `MenuScene` now exposes both difficulty selection and a dedicated entry point into `SettingsScene`.
- `SettingsScene` persists music and effects toggles immediately through `saveAudioPreferences()`.
- `GameScene` reads normalized audio preferences from scene data or persisted storage before match start.
- `GameScene` tracks played and captured cards in `CardTracker` as the round evolves.
- The scene owns score HUD rendering, player labels, status text, think-bar rendering, and procedural particle effects.
- The scene owns score HUD rendering, player labels, status text, think-bar rendering, procedural audio, and particle effects.
- Round-end and match-end flows remain managed inside the scene instead of separate overlay components.
### Benchmark snapshot
- `ai-benchmark.ts` now uses a simulated timing source for fixture and self-play evaluation instead of depending only on wall-clock timing.
- The benchmark summary records per-seed aggregates, dual-loss seeds, and a regression watchlist intersection.
- The harness remains source-local under `src/`, so it is covered by the default `npx tsc --noEmit` include set.
## Research Performed
### Web Research: Scopone Scientifico Rules (2026-03-31)
@@ -118,34 +133,11 @@ Initializer refresh for SCOPONE-0009. The cached findings were stale relative to
- The current `GameScene` pattern of registering one-shot shutdown and destroy handlers is aligned with Phaser guidance for worker disposal and UI cleanup.
- Dealer rotation and next-round state changes can stay inside the existing in-scene orchestration without requiring a different Phaser lifecycle primitive.
### SCOPONE-0009: Iteration 3 strength-planning notes (2026-04-08)
### SCOPONE-0010: UI, settings, and benchmark refresh notes (2026-04-09)
- `src/game/ai.ts` currently generates master determinization samples by uniformly shuffling all unseen cards and slicing them into opponents' hidden hands; it does not yet bias assignments by dealer role, parity residue, or observed capture semantics.
- The transposition-table key in `src/game/ai.ts` includes the exact sampled hidden hands, so reuse is effective within a determinized sample but does not merge equivalent uncertainty classes across different sample assignments.
- No executable benchmark harness or AI quality test module exists under `src/`; the current timing evidence lives only in prompt artifacts such as `prompts/SCOPONE-0009/iteration_2/benchmark_summary.md`.
- `tsconfig.json` includes only `src`, so any automated quality or self-play harness that should be typechecked by the default `npx tsc --noEmit` command needs to live under `src/` unless the project configuration changes.
### SCOPONE-0009: Iteration 3 continuation notes (2026-04-09)
- The accepted iteration 3 benchmark work is now present in source: `src/game/ai-benchmark.ts` and `src/game/ai-benchmark-fixtures.ts` exist under `src/`, `package.json` exposes `benchmark:ai-quality`, and the harness already measures fixed fixtures, self-play, and production-master timing.
- The live production master budgets in `src/game/ai.ts` are already below the requested five-second ceiling in every shipped branch: base `4300`, `<= 20 cards` `4350`, `<= 12 cards` `4200`, `<= 8 cards` `3900`, `<= 6 cards` `3600`, and `<= 4 cards` `3200` milliseconds.
- `src/scenes/GameScene.ts` still executes AI turns immediately after `await aiClient.chooseMove(...)` resolves in `doAIMove()`; there is currently no scene-level minimum think-time floor.
- `src/scenes/GameScene.ts` still uses a bare `setStatus(msg)` helper that only calls `this.statusText.setText(msg)`; there is no timed persistence policy, no cancellation of prior status timers, and no dedicated post-move outcome message path.
- Phaser 3.87 scene timers can be cancelled with `TimerEvent.remove()` and their references cleaned with `TimerEvent.destroy()`; the current scene already listens to `shutdown` and `destroy`, so timed status cleanup belongs in the existing `handleSceneShutdown()` path.
### SCOPONE-0009: Iteration 3 refresh notes (2026-04-09)
- The current `src/game/ai.ts` heuristic does not reason about numeric even/odd card values; it already computes the unseen copy count for each rank and stores whether the remaining copies for that rank are in a singleton residue or a paired residue, but the internal names still use `oddResidue`, `evenResidue`, and `scoreParityTableState`, which can mislead future work.
- The live tactical seam that needs refresh is therefore naming and policy framing, not a wholesale replacement of the underlying signal: the AI should explicitly treat `apparigliare` / `sparigliare` as preserving or breaking same-rank copy residues and connect that to table control, scopa prevention, and forced replies.
- The accepted benchmark harness in `src/game/ai-benchmark.ts` still measures runtime with `performance.now()` and therefore depends on wall-clock search time. It does not yet use an injected or simulated search clock for fast validation runs.
- `src/scenes/GameScene.ts` already contains the previously planned pacing and status work: `AI_MIN_THINK_MS = 1000`, `MOVE_OUTCOME_STATUS_MS = 2000`, a timer-backed `setStatus(...)`, and `handleSceneShutdown()` timer cleanup are all present in source and should be preserved rather than re-planned.
- `src/game/ai-benchmark-fixtures.ts` still contains one fixture and tag using the stale label `dealer-parity-preserve-pair` / `critical-dealer-parity`; if benchmark files are reopened for simulated timing, that terminology should be refreshed to rank-residue wording at the same time.
### SCOPONE-0009: Iteration 5 planning notes (2026-04-09)
- The live AI quality harness in `src/game/ai-benchmark.ts` still hard-codes an `iteration: 4` quality gate with targets of `12` fixed fixtures, `4` critical concepts, and `48` self-play matches requiring `>= 30` wins and `<= 12` losses; the readable summary does not yet surface cross-seed aggregation such as the recurring dual-loss seeds from the latest rejected run.
- `src/game/ai-benchmark-fixtures.ts` currently covers `settebello-capture`, `anti-scopa-defense`, `dealer-rank-residue-preservation`, and `exact-endgame-resolution` as critical concepts, but it does not yet encode an explicit critical fixture for partner invitation / partner scopa setup and does not yet make `fare scopa` itself a critical concept despite the user's new ordering.
- Non-critical fixtures already exist for denari pressure, late denari shielding, and seven pressure, so the benchmark seam for iteration 5 is to rebalance critical-vs-fixed coverage and ordering expectations rather than to introduce a second harness.
- Cross-tier heuristic priorities are concentrated in `src/game/ai.ts`: beginner logic in `scoreCaptureBeginner()` / `scoreDumpBeginner()`, advanced logic in `scoreCaptureAdv()` / `scoreDumpAdv()`, and master root/search logic in `quickEval()`, `orderSearchMoves()`, `generateSamples()`, and `evaluateFast()`.
- Partner-aware logic already exists in all three tiers, but it is currently additive and distributed across multiple heuristics; there is no single explicit priority ladder that guarantees `partner setup` outranks seven denial, denari denial, and generic material capture across the whole file.
- Anti-scopa prevention is already strong enough to pass the fixed tactical fixtures, but the rejected iteration 4 result (`18` wins, `30` losses over `48` seeded self-play matches) indicates that full-game strength is still limited by strategic continuity across seed-intrinsic lines rather than by isolated tactical blindness.
- `src/game/preferences.ts` is now the authoritative audio preference seam. It normalizes stored values and shields scenes from malformed storage state.
- `src/scenes/MenuScene.ts` now reads persisted audio preferences and exposes a dedicated settings entry point instead of keeping audio options implicit.
- `src/scenes/SettingsScene.ts` exists as a real scene and persists music and effects toggles independently through `saveAudioPreferences()`.
- `src/scenes/GameScene.ts` already contains the previously planned pacing and status work: `AI_MIN_THINK_MS = 1000`, `MOVE_OUTCOME_STATUS_MS = 2000`, timer-backed `setStatus(...)`, and `handleSceneShutdown()` timer cleanup are all present in source and should be treated as current behavior, not future work.
- `src/game/ai-benchmark.ts` now enforces an iteration 5 contract with simulated timing, cross-seed aggregation, dual-loss reporting, and a regression watchlist intersection. Older findings that described iteration 4 targets or wall-clock-only timing are stale.
- `main.ts` still registers a local `SettingsScene` stub while `MenuScene` dynamically installs the concrete scene implementation before use. This works today but is an architectural wrinkle worth remembering in later planning.