From c7b376df4f9ccd33dd73090939079abc90a74581 Mon Sep 17 00:00:00 2001 From: Cal Corum Date: Tue, 4 Nov 2025 16:09:58 -0600 Subject: [PATCH] CLAUDE: Update documentation for GameState refactoring and X-Check testing MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Updated CLAUDE.md files to document recent changes including the GameState refactoring and new X-Check testing capabilities in the terminal client. Changes to app/models/CLAUDE.md: - Updated GameState field documentation - Replaced current_batter_lineup_id references with current_batter - Documented LineupPlayerState requirement for current players - Added comprehensive usage examples - Added "Recent Updates" section documenting GameState refactoring - Before/after code examples showing migration path - Explanation of why the change was made - Migration notes for developers - List of all affected files (7 files updated) Changes to terminal_client/CLAUDE.md: - Added "2025-11-04: X-Check Testing & GameState Refactoring" section - New feature: resolve_with x-check command - Complete X-Check resolution with defense tables and error charts - Shows all resolution steps with audit trail - Works with actual player ratings from PD API - Documented 8 X-Check commands now in help system - roll_jump / test_jump, roll_fielding / test_fielding - test_location, rollback, force_wild_pitch, force_passed_ball - Bug fixes documented - GameState structure updates (display.py, repl.py) - Game recovery fix (state_manager.py) - DO3 advancement fix (play_resolver.py) - Complete testing workflow examples - List of 7 files updated - Test coverage status (all passing) - Updated footer: Last Updated 2025-11-04 These documentation updates provide clear migration guides for the GameState refactoring and comprehensive examples for the new X-Check testing features. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- backend/app/models/CLAUDE.md | 75 +++++++++++++++++++++++++-- backend/terminal_client/CLAUDE.md | 86 ++++++++++++++++++++++++++++++- 2 files changed, 156 insertions(+), 5 deletions(-) diff --git a/backend/app/models/CLAUDE.md b/backend/app/models/CLAUDE.md index ab07dd9..bdc803c 100644 --- a/backend/app/models/CLAUDE.md +++ b/backend/app/models/CLAUDE.md @@ -60,7 +60,7 @@ Complete in-memory representation of an active game. The heart of the game engin - **Game State**: `status`, `inning`, `half`, `outs`, `home_score`, `away_score` - **Runners**: `on_first`, `on_second`, `on_third` (direct LineupPlayerState references) - **Batting Order**: `away_team_batter_idx` (0-8), `home_team_batter_idx` (0-8) -- **Play Snapshot**: `current_batter_lineup_id`, `current_pitcher_lineup_id`, `current_catcher_lineup_id`, `current_on_base_code` +- **Current Players**: `current_batter` (LineupPlayerState, required), `current_pitcher` (Optional[LineupPlayerState]), `current_catcher` (Optional[LineupPlayerState]), `current_on_base_code` - **Decision Tracking**: `pending_decision`, `decisions_this_play`, `pending_defensive_decision`, `pending_offensive_decision`, `decision_phase` - **Manual Mode**: `pending_manual_roll` (AbRoll stored when dice rolled in manual mode) - **Play History**: `play_count`, `last_play_result` @@ -75,22 +75,35 @@ Complete in-memory representation of an active game. The heart of the game engin ```python from app.models import GameState, LineupPlayerState +# Create current batter (required field) +current_batter = LineupPlayerState( + lineup_id=10, + card_id=100, + position="CF", + batting_order=1 +) + # Create game state state = GameState( game_id=uuid4(), league_id="sba", home_team_id=1, away_team_id=2, - current_batter_lineup_id=10 + current_batter=current_batter # Required LineupPlayerState object ) # Add runner -runner = LineupPlayerState(lineup_id=5, card_id=123, position="CF", batting_order=2) +runner = LineupPlayerState(lineup_id=5, card_id=123, position="SS", batting_order=2) state.add_runner(runner, base=1) # Advance runner and score state.advance_runner(from_base=1, to_base=4) # Auto-increments score +# Access current player info +print(f"Current batter: {state.current_batter.lineup_id}") +if state.current_pitcher: + print(f"Current pitcher: {state.current_pitcher.lineup_id}") + # Check game over if state.is_game_over(): state.status = "completed" @@ -1064,6 +1077,62 @@ uv run pytest tests/unit/models/ --cov=app.models --cov-report=html --- +## Recent Updates + +### GameState Refactoring (2025-11-04) + +**Changed**: `current_batter`, `current_pitcher`, and `current_catcher` fields + +**Before** (Old Structure): +```python +state = GameState( + game_id=uuid4(), + league_id="sba", + home_team_id=1, + away_team_id=2, + current_batter_lineup_id=10 # Integer ID +) +# Access: state.current_batter_lineup_id +``` + +**After** (New Structure): +```python +current_batter = LineupPlayerState(lineup_id=10, card_id=100, position="CF", batting_order=1) + +state = GameState( + game_id=uuid4(), + league_id="sba", + home_team_id=1, + away_team_id=2, + current_batter=current_batter # LineupPlayerState object (required) +) +# Access: state.current_batter.lineup_id +``` + +**Why**: +- More type-safe (full player context instead of just ID) +- Enables position rating access during X-Check resolution +- Matches pattern used for `on_first`, `on_second`, `on_third` runners +- Simplifies game engine logic + +**Migration Notes**: +- `current_batter` is **required** (not Optional) +- `current_pitcher` and `current_catcher` are **Optional[LineupPlayerState]** +- All code accessing `state.current_batter_lineup_id` must change to `state.current_batter.lineup_id` +- Game recovery creates placeholder `current_batter` from first active batter in lineup +- `_prepare_next_play()` sets correct current players after recovery + +**Affected Files**: +- ✅ `app/models/game_models.py` - Model definition updated +- ✅ `app/core/game_engine.py` - Uses new structure throughout +- ✅ `app/core/state_manager.py` - Recovery creates placeholders +- ✅ `app/core/runner_advancement.py` - All 17 references updated +- ✅ `terminal_client/display.py` - Display updated +- ✅ `terminal_client/repl.py` - Commands updated +- ✅ All test files - Fixtures updated to create LineupPlayerState objects + +--- + ## Design Rationale ### Why Separate Pydantic and SQLAlchemy Models? diff --git a/backend/terminal_client/CLAUDE.md b/backend/terminal_client/CLAUDE.md index 5b93b83..2eb75fa 100644 --- a/backend/terminal_client/CLAUDE.md +++ b/backend/terminal_client/CLAUDE.md @@ -761,8 +761,90 @@ Automatically managed by: --- +### 2025-11-04: X-Check Testing & GameState Refactoring + +**Major Update**: Added complete X-Check defensive play testing capabilities and fixed GameState structure. + +**New Features**: + +1. **X-Check Resolution Testing** - `resolve_with x-check ` + - Test complete X-Check defensive plays with actual player ratings + - Includes defense range tables, error charts, SPD tests, G2#/G3# conversions + - Shows full XCheckResult audit trail with all resolution steps + + ```bash + ⚾ > defensive + ⚾ > offensive + ⚾ > resolve_with x-check SS # Test X-Check to shortstop + ⚾ > resolve_with x-check LF # Test X-Check to left field + ``` + + **What It Shows**: + - Dice rolls (1d20 range + 3d6 error) + - Defender ratings (range/error from PD API or defaults) + - Defense table lookup (G1, G2, F3, SI2, DO3, etc.) + - SPD test results (if applicable) + - G2#/G3# conversion (playing in or holding runners) + - Error chart lookup (NO, E1, E2, E3, RP) + - Final outcome with error modifiers + - Complete runner advancement + +2. **X-Check Help Documentation** (8 commands documented) + - `roll_jump` / `test_jump` - Stolen base jump dice testing + - `roll_fielding` / `test_fielding` - Fielding dice testing + - `test_location` - Hit location distribution testing + - `rollback` - Undo plays + - `force_wild_pitch` / `force_passed_ball` - Interrupt play testing + - All commands now appear in `help` output + +**Bug Fixes**: + +1. **GameState Structure** - Updated for LineupPlayerState refactoring + - `display.py`: Now accesses `state.current_batter.lineup_id` instead of `state.current_batter_lineup_id` + - `repl.py`: Fixed typos (self.current_game → self.current_game_id) + - All 105 terminal client tests passing + +2. **Game Recovery** - Fixed validation error when loading saved games + - State manager now creates placeholder `current_batter` during recovery + - Placeholder is corrected by `_prepare_next_play()` after recovery + +3. **DO3 Advancement** - Fixed incorrect batter advancement + - DO3 now correctly: Batter reaches 2B (it's a double), runners advance 3 bases + - Was incorrectly sending batter to 3B + +**Testing Workflow**: +```bash +# Complete X-Check testing workflow +⚾ > new_game +⚾ > defensive --infield in # Set defensive positioning +⚾ > offensive --approach power # Set offensive approach +⚾ > resolve_with x-check 2B # Test X-Check to second base + +# See complete resolution: +# - Defense table: d20=15 + range=4 → G2 +# - Error chart: 3d6=8 vs error=12 → NO +# - Final: G2 + NO = groundout to 2B +# - Runner advancement based on G2 tables +``` + +**Files Updated**: +- `terminal_client/repl.py` - Added x-check parsing to resolve_with +- `terminal_client/commands.py` - Added xcheck_position parameter +- `terminal_client/help_text.py` - Documented 8 X-Check commands +- `terminal_client/display.py` - Fixed GameState references +- `app/core/game_engine.py` - Added xcheck_position support +- `app/core/play_resolver.py` - Fixed DO3 batter advancement +- `app/core/runner_advancement.py` - Updated all 17 GameState references + +**Test Coverage**: +- ✅ All 34 runner_advancement tests passing +- ✅ All 105 terminal_client tests passing +- ✅ All 26 state_manager tests passing + +--- + **Created**: 2025-10-26 **Author**: Claude **Purpose**: Testing tool for Phase 2 game engine development -**Status**: ✅ Complete - Interactive REPL with persistent state working perfectly! -**Last Updated**: 2025-10-28 +**Status**: ✅ Complete - Interactive REPL with persistent state and full X-Check testing! +**Last Updated**: 2025-11-04