cal/strat-gameplay-webapp
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

CLAUDE: Update documentation for GameState refactoring and X-Check testing

Browse Source 
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 <position> 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 <noreply@anthropic.com>
This commit is contained in:
Cal Corum 2025-11-04 16:09:58 -06:00
parent 76e01420a3
commit c7b376df4f
2 changed files with 156 additions and 5 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

75
backend/app/models/CLAUDE.md
View File

@ -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` - **Game State**: `status`, `inning`, `half`, `outs`, `home_score`, `away_score`
- **Runners**: `on_first`, `on_second`, `on_third` (direct LineupPlayerState references) - **Runners**: `on_first`, `on_second`, `on_third` (direct LineupPlayerState references)
- **Batting Order**: `away_team_batter_idx` (0-8), `home_team_batter_idx` (0-8) - **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` - **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) - **Manual Mode**: `pending_manual_roll` (AbRoll stored when dice rolled in manual mode)
- **Play History**: `play_count`, `last_play_result` - **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 ```python
from app.models import GameState, LineupPlayerState 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 # Create game state
state = GameState( state = GameState(
game_id=uuid4(), game_id=uuid4(),
league_id="sba", league_id="sba",
home_team_id=1, home_team_id=1,
away_team_id=2, away_team_id=2,
current_batter_lineup_id=10 current_batter=current_batter # Required LineupPlayerState object
) )
# Add runner # 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) state.add_runner(runner, base=1)
# Advance runner and score # Advance runner and score
state.advance_runner(from_base=1, to_base=4) # Auto-increments 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 # Check game over
if state.is_game_over(): if state.is_game_over():
state.status = "completed" 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 ## Design Rationale
### Why Separate Pydantic and SQLAlchemy Models? ### Why Separate Pydantic and SQLAlchemy Models?

86
backend/terminal_client/CLAUDE.md
View File

@ -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 <position>`
- 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 **Created**: 2025-10-26
**Author**: Claude **Author**: Claude
**Purpose**: Testing tool for Phase 2 game engine development **Purpose**: Testing tool for Phase 2 game engine development
**Status**: ✅ Complete - Interactive REPL with persistent state working perfectly! **Status**: ✅ Complete - Interactive REPL with persistent state and full X-Check testing!
**Last Updated**: 2025-10-28 **Last Updated**: 2025-11-04