Test Fixes (609/609 passing):
- Fixed DiceSystem API to accept team_id/player_id parameters for audit trails
- Fixed dice roll history timing issue in test
- Fixed terminal client mock to match resolve_play signature (X-Check params)
- Fixed result chart test mocks with missing pitching fields
- Fixed flaky test by using groundball_a (exists in both batting/pitching)
Documentation Updates:
- Added Testing Policy section to backend/CLAUDE.md
- Added Testing Policy section to tests/CLAUDE.md
- Documented 100% unit test requirement before commits
- Added git hook setup instructions
Git Hook System:
- Created .git-hooks/pre-commit script (enforces 100% test pass)
- Created .git-hooks/install-hooks.sh (easy installation)
- Created .git-hooks/README.md (hook documentation)
- Hook automatically runs all unit tests before each commit
- Blocks commits if any test fails
All 609 unit tests now passing (100%)
Integration tests have known asyncpg connection issues (documented)
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
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>
Updated runner_advancement.py and its tests to use the new GameState
structure where current_batter is a LineupPlayerState object instead of
an integer ID.
Changes:
- runner_advancement.py: Replaced all 17 references to
state.current_batter_lineup_id with state.current_batter.lineup_id
- tests/unit/core/test_runner_advancement.py: Updated test fixtures
- Mock fixture: Added mock_batter object with lineup_id attribute
- GameState constructor calls: Create LineupPlayerState objects instead
of using current_batter_lineup_id parameter (9 tests fixed)
All 34 runner advancement tests now passing. This fixes the AttributeError
that was preventing X-Check resolution from completing in the terminal
client ("'GameState' object has no attribute 'current_batter_lineup_id'").
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Added ability to test X-Check defensive plays directly in the terminal
client using the resolve_with command. This allows testing the complete
X-Check resolution system (defense tables, error charts, runner advancement)
with actual player ratings.
Changes:
- repl.py: Updated do_resolve_with() to parse "x-check <position>" syntax
- Accepts "x-check", "xcheck", or "x_check" followed by position
- Validates position (P, C, 1B, 2B, 3B, SS, LF, CF, RF)
- Passes xcheck_position parameter through to commands
- commands.py: Updated resolve_play() to accept xcheck_position parameter
- Passes xcheck_position to game_engine.resolve_play()
- Shows "🎯 Forcing X-Check to: <position>" message
- game_engine.py: Updated resolve_play() to accept xcheck_position parameter
- For X_CHECK outcomes, uses xcheck_position as hit_location
- Enables full X-Check resolution with defense tables and error charts
- help_text.py: Updated resolve_with help documentation
- Added x-check usage syntax and examples
- Documented position parameter requirement
- Added note about using actual player ratings
Usage:
⚾ > defensive
⚾ > offensive
⚾ > resolve_with x-check SS # Test X-Check to shortstop
⚾ > resolve_with x-check LF # Test X-Check to left field
This integrates the existing play_resolver._resolve_x_check() logic,
providing a way to test the complete X-Check system including defense
range adjustments, table lookups, SPD tests, G2#/G3# conversion, error
charts, and runner advancement.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Added documentation for 8 X-Check testing and gameplay commands that
were implemented but missing from the help system:
X-Check Testing Commands:
- roll_jump: Roll jump dice for stolen base testing
- test_jump: Test jump roll distribution statistics
- roll_fielding: Roll fielding check dice for X-Check defensive plays
- test_fielding: Test fielding roll distribution
Testing & Development:
- test_location: Test hit location distribution
- rollback: Roll back the last N plays
Interrupt Plays:
- force_wild_pitch: Force a wild pitch interrupt play
- force_passed_ball: Force a passed ball interrupt play
Changes:
- help_text.py: Added new command categories to show_command_list()
- "X-Check Testing" section with 4 dice testing commands
- "Interrupt Plays" section with 2 force commands
- Moved test_location and rollback to "Testing & Development"
- help_text.py: Added detailed HELP_DATA entries for all 8 commands
- Complete usage, options, examples, and notes for each
- Includes dice component explanations and expected distributions
Users can now run 'help' to see all commands or 'help <command>' for
detailed information about X-Check testing features.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Fixed state_manager._rebuild_state_from_data to provide required
current_batter field when recovering games from database. The GameState
model now requires current_batter as a LineupPlayerState object, but
recovery was not populating this field, causing validation errors.
Changes:
- state_manager.py: Create placeholder current_batter during recovery
- Build LineupPlayerState from first active batter (batting_order=1)
- Fallback to first available lineup if no #1 batter found
- Raise error if no lineups exist (invalid game state)
- _prepare_next_play() will correct the batter after recovery
- Moved get_lineup_player helper to top of method (removed duplicate)
- tests/unit/core/test_state_manager.py: Update test to use new structure
- test_update_state_nonexistent_raises_error: Create LineupPlayerState
instead of using old current_batter_lineup_id field
All 26 state_manager unit tests passing. Game recovery now works
correctly in terminal client - fixes "current_batter Field required"
validation error when running status command on recovered games.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Updated terminal client REPL to work with refactored GameState structure
where current_batter/pitcher/catcher are now LineupPlayerState objects
instead of integer IDs. Also standardized all documentation to properly
show 'uv run' prefixes for Python commands.
REPL Updates:
- terminal_client/display.py: Access lineup_id from LineupPlayerState objects
- terminal_client/repl.py: Fix typos (self.current_game → self.current_game_id)
- tests/unit/terminal_client/test_commands.py: Create proper LineupPlayerState
objects in test fixtures (2 tests fixed, all 105 terminal client tests passing)
Documentation Updates (100+ command examples):
- CLAUDE.md: Updated pytest examples to use 'uv run' prefix
- terminal_client/CLAUDE.md: Updated ~40 command examples
- tests/CLAUDE.md: Updated all test commands (unit, integration, debugging)
- app/*/CLAUDE.md: Updated test and server startup commands (5 files)
All Python commands now consistently use 'uv run' prefix to align with
project's UV migration, improving developer experience and preventing
confusion about virtual environment activation.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Updated terminal_client/CLAUDE.md to use UV commands.
## Changes
- Updated REPL start command: uv run python -m terminal_client
- Updated standalone commands to use uv run prefix
- Added alternative manual activation option
- Consistent with all other project documentation
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Fixed Docker build issues to complete UV migration.
## Changes
### README.md
- Created backend README.md (required by hatchling build system)
- Simple quick start guide referencing CLAUDE.md
### Dockerfile
- Added `build-essential` for compiling native extensions (pendulum Rust code)
- Updated copy steps to include README.md in both dev and prod stages
- Dockerfile now successfully builds both development and production images
### .dockerignore
- Added exception `!README.md` to allow README.md through
- Keeps other *.md files excluded as intended
## Testing
- ✅ Development image builds successfully (paper-dynasty-backend:dev-uv)
- ✅ Production image builds successfully (paper-dynasty-backend:prod-uv)
- ✅ Container starts and UV installs dependencies correctly
- ✅ Application attempts to start (fails only on missing .env, as expected)
## Build Results
- Dev image: 73 packages installed (with dev deps)
- Prod image: 57 packages installed (no dev deps)
- Both stages use `uv sync --frozen` for reproducible builds
- Build time: ~1-2 minutes per stage
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Migrated from pip to UV (v0.9.7) for faster, more reliable package management.
## Changes
### Package Management
- Created `pyproject.toml` with project metadata and dependencies
- Generated `uv.lock` for reproducible builds (198KB)
- Migrated all dependencies from requirements.txt:
- Production: 20 packages (FastAPI, SQLAlchemy, Pydantic, etc.)
- Development: 6 packages (pytest, black, mypy, flake8)
- Virtual environment moved from `venv/` to `.venv/` (UV default)
### Dockerfile Updates
- Updated base image: python:3.11-slim → python:3.13-slim
- Added UV installation via official image copy
- Development stage: Uses `uv sync --frozen` for all deps
- Production stage: Uses `uv sync --frozen --no-dev` for prod only
- Commands now use `uv run` prefix for auto-activation
- Set UV environment variables:
- UV_LINK_MODE=copy (for Docker compatibility)
- UV_COMPILE_BYTECODE=1 (performance)
- UV_PYTHON_DOWNLOADS=never (use system Python)
### Code Fixes
- Fixed Pydantic model circular import in `app/models/game_models.py`
- Added runtime import of PositionRating at end of file
- Called `model_rebuild()` on LineupPlayerState and GameState
- Resolves "not fully defined" errors in tests
### Documentation
- Updated `backend/CLAUDE.md` with UV usage:
- Package management section with UV commands
- Updated all code examples to use `uv run`
- Daily development workflow now uses UV
- Added dependency management guide (add/remove/update)
- Updated virtual environment location (.venv/)
### Project Files
- Added `.python-version` (3.13) for UV Python version tracking
- Removed UV template files (main.py, README.md)
- Kept existing .gitignore (already includes venv/ and .venv/)
## Testing
- ✅ All imports work correctly
- ✅ 55/55 game model tests passing
- ✅ 500+ unit tests passing (same as before migration)
- ✅ Test failures are pre-existing (not UV-related)
## Benefits
- 10-100x faster dependency resolution
- 2-3x faster installation
- Better dependency conflict resolution
- Single tool for everything (replaces pip, pip-tools, virtualenv)
- Reproducible builds with uv.lock
## Migration Path for Team
```bash
# One-time: Install UV
curl -LsSf https://astral.sh/uv/install.sh | sh
# In project
cd backend
uv sync # Creates .venv and installs everything
# Daily usage
uv run python -m app.main
uv run pytest tests/ -v
```
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Updated NEXT_SESSION.md to reflect Phase 3E-Main completion:
- Marked Phase 3E-Main as 100% complete (position ratings integration)
- Overall Phase 3E progress now 90%
- Updated Phase 3 overall progress to ~95%
- Documented all accomplishments and live test results
- Outlined remaining Phase 3E-Final tasks (10%):
* WebSocket event handlers for X-Check UI
* Redis caching upgrade from in-memory
* Full defensive lineup evaluation
* Manual vs Auto mode workflows
Included comprehensive session handoff:
- Live API test results with player 8807 (7 positions)
- Performance metrics (16,601x cache speedup)
- All files created/modified
- Quick start guide for next session
- Technical architecture notes
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Complete integration of position ratings system enabling X-Check defensive plays
to use actual player ratings from PD API with intelligent fallbacks for SBA.
**Live API Testing Verified**: ✅
- Endpoint: GET https://pd.manticorum.com/api/v2/cardpositions?player_id=8807
- Response: 200 OK, 7 positions retrieved successfully
- Cache performance: 16,601x faster (API: 0.214s, Cache: 0.000s)
- Data quality: Real defensive ratings (range 1-5, error 0-88)
**Architecture Overview**:
- League-aware: PD league fetches ratings from API, SBA uses defaults
- StateManager integration: Defenders retrieved from lineup cache
- Self-contained GameState: All data needed for X-Check in memory
- Graceful degradation: Falls back to league averages if ratings unavailable
**Files Created**:
1. app/services/pd_api_client.py (NEW)
- PdApiClient class for PD API integration
- Endpoint: GET /api/v2/cardpositions?player_id={id}&position={pos}
- Async HTTP client using httpx (already in requirements.txt)
- Optional position filtering: get_position_ratings(8807, ['SS', '2B'])
- Returns List[PositionRating] for all positions player can play
- Handles both list and dict response formats
- Comprehensive error handling with logging
2. app/services/position_rating_service.py (NEW)
- PositionRatingService with in-memory caching
- get_ratings_for_card(card_id, league_id) - All positions
- get_rating_for_position(card_id, position, league_id) - Specific position
- Cache performance: >16,000x faster on hits
- Singleton pattern: position_rating_service instance
- TODO Phase 3E-Final: Upgrade to Redis
3. app/services/__init__.py (NEW)
- Package exports for clean imports
4. test_pd_api_live.py (NEW)
- Live API integration test script
- Tests with real PD player 8807 (7 positions)
- Verifies caching, filtering, GameState integration
- Run: `python test_pd_api_live.py`
5. test_pd_api_mock.py (NEW)
- Mock integration test for CI/CD
- Demonstrates flow without API dependency
6. tests/integration/test_position_ratings_api.py (NEW)
- Pytest integration test suite
- Real API tests with player 8807
- Cache verification, SBA skip logic
- Full end-to-end GameState flow
**Files Modified**:
1. app/models/game_models.py
- LineupPlayerState: Added position_rating field (Optional[PositionRating])
- GameState: Added get_defender_for_position(position, state_manager)
- Uses StateManager's lineup cache to find active defender by position
- Iterates through lineup.players to match position + is_active
2. app/config/league_configs.py
- SbaConfig: Added supports_position_ratings() → False
- PdConfig: Added supports_position_ratings() → True
- Enables league-specific behavior without hardcoded conditionals
3. app/core/play_resolver.py
- __init__: Added state_manager parameter for X-Check defender lookup
- _resolve_x_check(): Replaced placeholder defender ratings with actual lookup
- Uses league config to check if ratings supported
- Fetches defender via state.get_defender_for_position()
- Falls back to defaults (range=3, error=15) if ratings unavailable
- Detailed logging for debugging rating lookups
4. app/core/game_engine.py
- Added _load_position_ratings_for_lineup() method
- Loads all position ratings at game start for PD league
- Skips loading for SBA (league config check)
- start_game(): Calls rating loader for both teams before marking active
- PlayResolver instantiation: Now passes state_manager parameter
- Logs: "Loaded X/9 position ratings for team Y"
**X-Check Resolution Flow**:
1. League check: config.supports_position_ratings()?
2. Get defender: state.get_defender_for_position(pos, state_manager)
3. If PD + defender.position_rating exists: Use actual range/error
4. Else if defender found: Use defaults (range=3, error=15)
5. Else: Log warning, use defaults
**Position Rating Loading (Game Start)**:
1. Check if league supports ratings (PD only)
2. Get lineup from StateManager cache
3. For each player:
- Fetch rating from position_rating_service (with caching)
- Set player.position_rating field
4. Cache API responses (16,000x faster on subsequent access)
5. Log success: "Loaded X/9 position ratings for team Y"
**Live Test Results (Player 8807)**:
```
Position Range Error Innings
CF 3 2 372
2B 3 8 212
SS 4 12 159
RF 2 2 74
LF 3 2 62
1B 4 0 46
3B 3 65 34
```
**Testing**:
- ✅ Live API: Player 8807 → 7 positions retrieved successfully
- ✅ Caching: 16,601x performance improvement
- ✅ League config: SBA=False, PD=True
- ✅ GameState integration: Defender lookup working
- ✅ Existing tests: 27/28 config tests passing (1 pre-existing URL failure)
- ✅ Syntax validation: All files compile successfully
**Benefits**:
- ✅ X-Check now uses real defensive ratings in PD league
- ✅ SBA league continues working with manual entry (uses defaults)
- ✅ No breaking changes to existing functionality
- ✅ Graceful degradation if API unavailable
- ✅ In-memory caching reduces API calls by >99%
- ✅ League-agnostic design via config system
- ✅ Production-ready with live API verification
**Phase 3E Status**: Main complete (85% → 90%)
**Next**: Phase 3E-Final (WebSocket events, Redis upgrade, full defensive lineup)
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
**Architectural Improvement**: Unified player references in GameState
**Changed**: Make all player references consistent
- BEFORE: current_batter/pitcher/catcher were IDs (int)
- AFTER: current_batter/pitcher/catcher are full LineupPlayerState objects
- Matches pattern of on_first/on_second/on_third (already objects)
**Benefits**:
1. Consistent API - all player references use same type
2. Self-contained GameState - everything needed for resolution
3. No lookups needed - direct access to player data
4. Sets foundation for Phase 3E-Main (adding position ratings)
**Files Modified**:
- app/models/game_models.py: Changed current_batter/pitcher/catcher to objects
- app/core/game_engine.py: Updated _prepare_next_play() to populate full objects
- app/core/state_manager.py: Create placeholder batter on game creation
- tests/unit/models/test_game_models.py: Updated all 27 GameState tests
**Database Operations**:
- No schema changes needed
- Play table still stores IDs (for referential integrity)
- IDs extracted from objects when saving: state.current_batter.lineup_id
**Testing**:
- All 27 GameState tests passing
- No regressions in existing functionality
- Type checking passes
**Next**: Phase 3E-Main - Add PositionRating dataclass and load ratings at game start
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Updated X-Check runner advancement functions to properly delegate to
existing result handlers for non-error cases.
Changes:
- Updated x_check_g1/g2/g3 signatures to accept GameState, hit_location,
and defensive_decision parameters
- Updated x_check_f1/f2/f3 signatures to accept GameState and hit_location
- Implemented delegation logic: error cases use simple tables, non-error
cases delegate to existing tested result handlers (_execute_result,
_fb_result_*)
- Updated PlayResolver._get_x_check_advancement() to pass new parameters
- Updated all tests to provide required GameState fixtures
Benefits:
- Reuses 13 existing groundball + 4 flyball result handlers (DRY)
- No DP probability needed - X-Check d20 already tested defender
- Full game context: real lineup IDs, outs count, conditional logic
- Error cases remain simple and efficient
Test Results: 264/265 core tests passing (1 pre-existing dice failure)
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Fixed incorrect double play logic that was rolling for probability
twice - once for the chart result and again for execution.
Changes:
- Removed _calculate_double_play_probability() method entirely
- Updated _gb_result_2() to execute DP deterministically
- Updated _gb_result_10() to execute DP deterministically
- Updated _gb_result_13() to execute DP deterministically
- Removed TestDoublePlayProbability test class (5 tests)
- Updated DP tests to reflect deterministic behavior
Logic: Chart already determines outcome via dice roll. When chart
says "Result 2: Double Play", the DP happens (if <2 outs and runner
on 1st exists). No additional probability roll needed.
Tests: 55/55 runner advancement tests passing
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Fixed two critical bugs in Phase 3D X-Check implementation plus
improved dice audit trail for better tracking.
BUG #1: on_base_code Mapping Error (Sequential vs Bit Field)
============================================================
The implementation incorrectly treated on_base_code as a bit field
when it is actually a sequential lookup mapping.
WRONG (bit field):
Code 3 (0b011) → R1 + R2
Code 4 (0b100) → R3 only
CORRECT (sequential):
Code 3 → R3 only
Code 4 → R1 + R2
Fixed:
- build_advancement_from_code() decoder (sequential mapping)
- build_flyball_advancement_with_error() decoder (sequential mapping)
- 13 test on_base_code values (3↔4 corrections)
- Updated documentation to clarify NOT a bit field
BUG #2: Table Data Not Matching Official Charts
================================================
7 table entries in G1_ADVANCEMENT_TABLE and G2_ADVANCEMENT_TABLE
did not match the official rulebook charts provided by user.
Fixed table entries:
- G1 Code 1, Infield In: Changed Result 3 → 2
- G1 Code 3, Normal: Changed Result 13 → 3
- G1 Code 3, Infield In: Changed Result 3 → 1
- G1 Code 4, Normal: Changed Result 3 → 13
- G1 Code 4, Infield In: Changed Result 4 → 2
- G2 Code 3, Infield In: Changed Result 3 → 1
- G2 Code 4, Normal: Changed Result 5 → 4
Also fixed 7 test expectations to match corrected tables.
IMPROVEMENT: Better Dice Audit Trail
=====================================
Updated _resolve_x_check() in PlayResolver to use proper
dice_system.roll_fielding() instead of manual die rolling.
Benefits:
- All dice tracked in audit trail (roll_id, timestamp, position)
- Automatic error_total calculation (no manual 3d6 addition)
- Consistent with codebase patterns
- Position recorded for historical analysis
Testing:
- All 59 X-Check advancement tests passing (100%)
- All 9 PlayResolver tests passing (100%)
- All table entries validated against official charts
- Complete codebase scan: no bit field operations found
Files modified:
- backend/app/core/x_check_advancement_tables.py
- backend/tests/unit/core/test_x_check_advancement_tables.py
- backend/app/core/play_resolver.py
- .claude/implementation/PHASE_3D_CRITICAL_FIX.md (documentation)
- .claude/implementation/GROUNDBALL_CHART_REFERENCE.md (new)
- .claude/implementation/XCHECK_TEST_VALIDATION.md (new)
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Added comprehensive Phase 3C documentation to CLAUDE.md:
- X-Check resolution logic implementation details
- Helper methods and integration points
- Key features and algorithms
- Placeholders for future phases
- Test coverage and verification results
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Implemented complete X-Check resolution system in PlayResolver with
defense range and error table lookups.
Changes:
- Added X_CHECK case to resolve_outcome() method
- Implemented _resolve_x_check() main resolution method
- Added _adjust_range_for_defensive_position() for playing in logic
- Added _lookup_defense_table() for defense range table lookups
- Added _apply_hash_conversion() for G2#/G3# to SI2 conversion
- Added _lookup_error_chart() for error determination
- Added _determine_final_x_check_outcome() for final outcome mapping
- Added XCheckResult to PlayResult dataclass
- Integrated all Phase 3B tables (defense, error, holding runners)
Features:
- Full defense table lookup (infield, outfield, catcher)
- Error chart lookup with priority ordering (RP > E3 > E2 > E1 > NO)
- Range adjustment for playing in (+1, max 5)
- Hash conversion based on playing in OR holding runner
- Error overrides outs to ERROR outcome
- Rare play handling
- Detailed X-Check audit trail in XCheckResult
Placeholders (to be completed in later phases):
- Defender retrieval from lineup (currently uses placeholder ratings)
- SPD test implementation (currently defaults to G3)
- Batter handedness from player model
- Runner advancement tables (Phase 3D)
Testing:
- All 9 PlayResolver tests passing
- All 36 X-Check table tests passing
- All 51 runner advancement tests passing
- 325/327 total tests passing (2 pre-existing failures unrelated)
- play_resolver.py compiles successfully
Phase 3C Status: 100% COMPLETE ✅
Ready for Phase 3D (Runner Advancement Tables)
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Add foundational data structures for X-Check play resolution system:
Models Added:
- PositionRating: Defensive ratings (range 1-5, error 0-88) for X-Check resolution
- XCheckResult: Dataclass tracking complete X-Check resolution flow with dice rolls,
conversions (SPD test, G2#/G3#→SI2), error results, and final outcomes
- BasePlayer.active_position_rating: Optional field for current defensive position
Enums Extended:
- PlayOutcome.X_CHECK: New outcome type requiring special resolution
- PlayOutcome.is_x_check(): Helper method for type checking
Documentation Enhanced:
- Play.check_pos: Documented as X-Check position identifier
- Play.hit_type: Documented with examples (single_2_plus_error_1, etc.)
Utilities Added:
- app/core/cache.py: Redis cache key helpers for player positions and game state
Implementation Planning:
- Complete 6-phase implementation plan (3A-3F) documented in .claude/implementation/
- Phase 3A complete with all acceptance criteria met
- Zero breaking changes, all existing tests passing
Next: Phase 3B will add defense tables, error charts, and advancement logic
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Major Phase 2 refactoring to consolidate runner advancement logic:
**Flyball System Enhancement**:
- Add FLYOUT_BQ variant (medium-shallow depth)
- 4 flyball types with clear semantics: A (deep), B (medium), BQ (medium-shallow), C (shallow)
- Updated helper methods to include FLYOUT_BQ
**RunnerAdvancement Integration**:
- Extend runner_advancement.py to handle both groundballs AND flyballs
- advance_runners() routes to _advance_runners_groundball() or _advance_runners_flyball()
- Comprehensive flyball logic with proper DECIDE mechanics per flyball type
- No-op movements recorded for state recovery consistency
**PlayResolver Refactoring**:
- Consolidate all 4 flyball outcomes to delegate to RunnerAdvancement (DRY)
- Eliminate duplicate flyball resolution code
- Rename helpers for clarity: _advance_on_single_1/_advance_on_single_2 (was _advance_on_single)
- Fix single/double advancement logic for different hit types
**State Recovery Fix**:
- Fix state_manager.py game recovery to build LineupPlayerState objects properly
- Use get_lineup_player() helper to construct from lineup data
- Correctly track runners in on_first/on_second/on_third fields (matches Phase 2 model)
**Database Support**:
- Add runner tracking fields to play data for accurate recovery
- Include batter_id, on_first_id, on_second_id, on_third_id, and *_final fields
**Type Safety Improvements**:
- Fix lineup_id access throughout runner_advancement.py (was accessing on_first directly, now on_first.lineup_id)
- Make current_batter_lineup_id non-optional (always set by _prepare_next_play)
- Add type: ignore for known SQLAlchemy false positives
**Documentation**:
- Update CLAUDE.md with comprehensive flyball documentation
- Add flyball types table, usage examples, and test coverage notes
- Document differences between groundball and flyball mechanics
**Testing**:
- Add test_flyball_advancement.py with 21 flyball tests
- Coverage: all 4 types, DECIDE scenarios, no-op movements, edge cases
🚀 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Update test fixtures to provide required current_batter_lineup_id field
- Update validator tests for new infield depth values (infield_in, normal, corners_in)
- Update runner advancement tests to match refactored runner management
- Update game model tests to work with direct base references
- Update play resolver tests for enhanced logic
- Add missing imports in test files
All changes ensure tests align with recent Phase 2 implementation updates
including the transition from RunnerState list to direct base references
(on_first, on_second, on_third) in GameState model.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Major Refactor: Outcome-First Architecture
- PlayResolver now accepts league_id and auto_mode in constructor
- Added core resolve_outcome() method - all resolution logic in one place
- Added resolve_manual_play() wrapper for manual submissions (primary)
- Added resolve_auto_play() wrapper for PD auto mode (rare)
- Removed SimplifiedResultChart (obsolete with new architecture)
- Removed play_resolver singleton
RunnerAdvancement Integration:
- All groundball outcomes (GROUNDBALL_A/B/C) now use RunnerAdvancement
- Proper DP probability calculation with positioning modifiers
- Hit location tracked for all relevant outcomes
- 13 result types fully integrated from advancement charts
Game State Updates:
- Added auto_mode field to GameState (stored per-game)
- Updated state_manager.create_game() to accept auto_mode parameter
- GameEngine now uses state.auto_mode to create appropriate resolver
League Configuration:
- Added supports_auto_mode() to BaseGameConfig
- SbaConfig: returns False (no digitized cards)
- PdConfig: returns True (has digitized ratings)
- PlayResolver validates auto mode support and raises error for SBA
Play Results:
- Added hit_location field to PlayResult
- Groundballs include location from RunnerAdvancement
- Flyouts track hit_location for tag-up logic (future)
- Other outcomes have hit_location=None
Testing:
- Completely rewrote test_play_resolver.py for new architecture
- 9 new tests covering initialization, strikeouts, walks, groundballs, home runs
- All 9 tests passing
- All 180 core tests still passing (1 pre-existing failure unrelated)
Terminal Client:
- No changes needed - defaults to manual mode (auto_mode=False)
- Perfect for human testing of manual submissions
This completes Week 7 Task 6 - the final task of Week 7!
Week 7 is now 100% complete with all 8 tasks done.
🎯 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Created runner_advancement.py with complete groundball advancement system
- Implemented GroundballResultType IntEnum with 13 rulebook-aligned results
- Built RunnerAdvancement class with chart lookup logic (Infield Back/In)
- Implemented all 13 result handlers (gb_result_1 through gb_result_13)
- Added DECIDE mechanic support for interactive runner advancement decisions
- Implemented double play probability calculation with positioning modifiers
- Created 30 comprehensive unit tests covering all scenarios (100% passing)
Key Features:
- Supports Infield Back and Infield In defensive positioning
- Handles Corners In hybrid positioning (applies In rules to corner fielders)
- Conditional results based on hit location (middle IF, right side, corners)
- Force play detection and advancement logic
- Double play mechanics with probability-based success (45% base rate)
- Result types match official rulebook exactly (1-13)
Architecture:
- IntEnum for result types (type-safe, self-documenting)
- Comprehensive hit location tracking (1B, 2B, SS, 3B, P, C, LF, CF, RF)
- Dataclasses for movements (RunnerMovement, AdvancementResult)
- Probability modifiers: Infield In (-15%), hit location (±10%)
Testing:
- 30 unit tests covering chart lookup, all result types, and edge cases
- Double play probability validation
- All on-base codes (0-7) tested
- All groundball types (A, B, C) verified
Status: Week 7 Tasks 4 & 5 complete (~87% of Week 7 finished)
Next: Task 6 (PlayResolver Integration)
Related: #task4 #task5 #runner-advancement #double-play #week7
Complete manual outcome workflow for SBA and PD manual mode gameplay:
**WebSocket Event Handlers** (app/websocket/handlers.py):
- roll_dice: Server rolls dice, stores in state, broadcasts to players
- submit_manual_outcome: Validates and processes player submissions
- Events: dice_rolled, outcome_accepted, outcome_rejected, play_resolved
**Game Engine Integration** (app/core/game_engine.py):
- resolve_manual_play(): Processes manual outcomes with server dice
- Uses ab_roll for audit trail, player outcome for resolution
- Same orchestration as resolve_play() (save, update, advance inning)
**Data Model** (app/models/game_models.py):
- pending_manual_roll: Stores server dice between roll and submission
**Terminal Client** (terminal_client/):
- roll_dice command: Roll dice and display results
- manual_outcome command: Submit outcomes from physical cards
- Both integrated into REPL for testing
**Tests** (tests/unit/websocket/test_manual_outcome_handlers.py):
- 12 comprehensive tests covering all validation paths
- All tests passing (roll_dice: 4, submit_manual_outcome: 8)
**Key Decisions**:
- Server rolls dice for fairness (not players!)
- One-time roll usage (cleared after submission)
- Early validation (check pending roll before accepting)
- Field-level error messages for clear feedback
**Impact**:
- Complete manual mode workflow ready
- Frontend WebSocket integration supported
- Terminal testing commands available
- Audit trail with server-rolled dice maintained
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Add ability to roll back the last N plays, useful for correcting mistakes
or recovering from corrupted plays. Deletes plays from database and
reconstructs game state by replaying remaining plays.
Database Operations (app/database/operations.py):
- delete_plays_after(): Delete plays with play_number > target
- delete_substitutions_after(): Delete lineup entries with after_play >= target
- delete_rolls_after(): Delete dice rolls (kept for reference, not used)
Game Engine (app/core/game_engine.py):
- rollback_plays(): Main rollback orchestration
- Validates: num_plays > 0, enough plays exist, game not completed
- Deletes plays and substitutions from database
- Clears in-memory roll tracking
- Calls state_manager.recover_game() to rebuild state
- Returns updated GameState
Terminal Client (terminal_client/commands.py, terminal_client/repl.py):
- rollback_plays(): Command wrapper with user-friendly output
- do_rollback(): REPL command with argument parsing
Usage:
⚾ > rollback 3
Validations:
- Cannot roll back more plays than exist
- Cannot roll back completed games
- Rolling back across innings is allowed
- Substitutions after rolled-back plays are undone
Testing:
- ✅ Successfully rolls back 2 plays from 5-play game
- ✅ Correctly validates rollback of 10 plays when only 2 exist
- ✅ Game state properly reconstructed via replay
Note: Dice rolls kept in database for auditing (don't affect state).
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Add ability to force specific play outcomes instead of random dice rolls,
enabling targeted testing of specific game scenarios.
Changes:
- play_resolver.resolve_play(): Add forced_outcome parameter, bypass dice
rolls when provided, create dummy AbRoll with placeholder values
- game_engine.resolve_play(): Accept and pass through forced_outcome param
- terminal_client/commands.py: Pass forced_outcome to game engine
Testing:
- Verified TRIPLE, HOMERUN, and STRIKEOUT outcomes work correctly
- Dummy AbRoll properly constructed with all required fields
- Game state updates correctly with forced outcomes
Example usage in REPL:
resolve_with triple
resolve_with homerun
Fixes terminal client testing workflow to allow controlled scenarios.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Remove unused PlayResult creation code that had incorrect import path
and missing required fields. The forced outcome feature is experimental
and not yet implemented - the code was just showing warnings anyway.
Fixes ImportError when running 'resolve_with <outcome>' command.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
New Commands:
- manual_outcome <outcome> [location] - Validates ManualOutcomeSubmission
- Tests outcome and location validation
- Shows which outcomes require hit location
- Displays clear validation errors
- test_location <outcome> [handedness] [count] - Tests hit location distribution
- Generates sample hit locations for an outcome
- Shows distribution table with percentages
- Validates pull rates (45% pull, 35% center, 20% opposite)
- Supports both LHB and RHB
Implementation:
- Added validate_manual_outcome() to GameCommands class
- Added test_hit_location() to GameCommands class
- Added do_manual_outcome() to REPL
- Added do_test_location() to REPL
- Uses ManualOutcomeSubmission model from Task 3
- Uses calculate_hit_location() helper from Task 3
Testing:
- Tested manual_outcome with valid outcomes (groundball_c SS, strikeout)
- Tested manual_outcome with invalid outcome (proper error display)
- Tested test_location with groundball_c for RHB (shows distribution)
- All validation and display working correctly
Note: Full play resolution integration deferred to Week 7 Task 6 (WebSocket handlers).
These commands validate and test the new models but don't resolve plays yet.
Files Modified:
- terminal_client/commands.py (+117 lines)
- terminal_client/repl.py (+65 lines)
- Enhanced validate_defensive_decision() with comprehensive validation:
- Validate all alignments (normal, shifted_left, shifted_right, extreme_shift)
- Validate all infield depths (in, normal, back, double_play)
- Validate all outfield depths (in, normal, back)
- Validate hold_runners require actual runners on specified bases
- Validate hold_runners only on bases 1, 2, or 3
- Validate double_play depth requires runner on first
- Validate double_play depth not allowed with 2 outs
- Enhanced validate_offensive_decision() with comprehensive validation:
- Validate all approaches (normal, contact, power, patient)
- Validate steal_attempts only to bases 2, 3, or 4
- Validate steal_attempts require runner on base-1
- Validate bunt_attempt not allowed with 2 outs
- Validate bunt_attempt and hit_and_run cannot be simultaneous
- Validate hit_and_run requires at least one runner on base
- Added 24+ comprehensive test cases covering all edge cases:
- 13 new defensive decision validation tests
- 16 new offensive decision validation tests
- All tests pass (54/54 passing)
Clear error messages for all validation failures.
Follows 'Raise or Return' pattern with ValidationError exceptions.
Terminal Client Enhancements:
- Added list_outcomes command to display all PlayOutcome values
- Added resolve_with <outcome> command for testing specific scenarios
- TAB completion for all outcome names
- Full help documentation and examples
- Infrastructure ready for Week 7 integration
Files Modified:
- terminal_client/commands.py - list_outcomes() and forced outcome support
- terminal_client/repl.py - do_list_outcomes() and do_resolve_with() commands
- terminal_client/completions.py - VALID_OUTCOMES and complete_resolve_with()
- terminal_client/help_text.py - Help entries for new commands
Phase 3 Planning:
- Created comprehensive Week 7 implementation plan (25 pages)
- 6 major tasks covering strategic decisions and result charts
- Updated 00-index.md to mark Week 6 as 100% complete
- Documented manual outcome testing feature
Week 6: 100% Complete ✅
Phase 3 Week 7: Ready to begin
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Renamed check_d20 → chaos_d20 throughout dice system
- Expanded PlayOutcome enum with granular variants (SINGLE_1/2, DOUBLE_2/3, GROUNDBALL_A/B/C, etc.)
- Integrated PlayOutcome from app.config into PlayResolver
- Added play_metadata support for uncapped hit tracking
- Updated all tests (139/140 passing)
Week 6: 100% Complete - Ready for Phase 3
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
