feat: hand history tracking (#35)

* feat: add chronological board card tracking to game engine

- Add boardOrder slice to HandState to preserve dealing sequence
- Implement BoardCards() method for chronological access
- Update hand_runner to use BoardCards() instead of bitset iteration
- Add TestBoardCardsPreserveDealingOrder with deterministic verification
- Add integration tests for board emission ordering

This fixes PHH board card ordering by tracking the actual sequence
cards are dealt rather than relying on bitset iteration order.

* feat: implement PHH hand history encoder and types

- Add HandHistory struct with all spec-compliant fields
- Implement TOML encoder with proper field ordering
- Add card notation helpers (10h → Th conversion)
- Support player rotation (SB-first ordering per spec)
- Implement bulk .phhs format with section headers
- Add comprehensive encoder tests

Implements the Poker Hand History (PHH) standard format
as specified at https://phh.readthedocs.io/

* feat: add hand history monitor with buffered recording

- Implement Monitor with mutex-protected buffer and async flushing
- Add Manager for server-wide flush coordination
- Support player rotation and blind tracking per PHH spec
- Track chronological board progression per street
- Implement failure state machine (3 strikes → disable)
- Prevent race conditions in CreateMonitor with double-check locking
- Add comprehensive tests with race detection

Buffering reduces disk I/O to ~1 write per 100 hands or 10 seconds.

* feat: integrate hand history into server with CLI flags

- Wire Manager into Server lifecycle with graceful shutdown
- Add hand history config fields (dir, flush interval, hole cards)
- Create Monitor per game with automatic registration
- Add --hand-history flags to spawn and server commands
- Flush all buffers on server shutdown (zero data loss)
- Update Server tests to cover hand history integration

Hand history recording disabled by default for backward compatibility.

* feat: add hand history render command and playback

- Implement 'hand-history render' command for PHH file replay
- Add playback engine that reverses player rotation to seat positions
- Infer button position from PHH ordering (SB-first convention)
- Support both .phh and .phhs formats
- Add comprehensive playback tests
- Support --limit flag for rendering subset of hands

Enables post-game analysis and hand review workflows.

* docs: add hand history documentation and examples

- Add comprehensive hand-history.md with format guide and examples
- Update operations.md with hand history usage instructions
- Add analyze-phh.py example for Python integration
- Add implementation plan document
- Update README with hand history feature
- Update TODO.md to mark v1.0 complete

Provides complete documentation for hand history feature including
PHH format specification, CLI usage, and integration examples.

* feat: use UTC for all hand history timestamps

- Convert all timestamps to UTC in populateTimeFields
- Remove time_zone_abbreviation field (non-standard)
- Update documentation to clarify UTC usage
- Update tests to reflect UTC-only format

Ensures consistent time handling across all PHH files regardless
of server timezone configuration.

* docs: update hand history plan to reflect completion

- Mark status as complete with all phases done
- Remove outdated bug section (all bugs fixed)
- Update file format examples to show [1] section headers
- Update acceptance criteria with all items checked
- Add completed implementation details (UTC, player rotation, showdown tracking)
- Remove reference to deleted analyze-phh.py example

* feat: add partial flush recovery and section counter resumption

- Add dedicated flushMu to prevent concurrent flush races
- Track partial flush progress and only remove successfully written hands
- Resume section counter from existing file on Monitor creation
- Prevent section number gaps on partial failures
- Add helpers: writeHand, finalizeFlush, readLastSectionCounter

Ensures hand history files maintain consistency even with partial
flush failures or server restarts.

Author: lox

README.md

@@ -50,6 +50,7 @@ pokerforbots client --name Alice
 - [Poker Rules](docs/poker-rules.md) - No-limit Hold'em rules implementation
 - [Go SDK](docs/sdk.md) - Bot development SDK
 - [Operations](docs/operations.md) - Server operation and monitoring
+- [Hand History](docs/hand-history.md) - PHH recording and tooling
 - [HTTP API](docs/http-api.md) - REST endpoints for stats and control
 - [Benchmarking](docs/benchmarking.md) - Performance testing
 
@@ -62,6 +63,7 @@ The `pokerforbots` CLI provides these sub-commands:
 - **`regression`** - Statistical bot comparison
 - **`server`** - Standalone poker server
 - **`client`** - Interactive human client
+- **`hand-history render`** - Pretty-print PHH session files
 
 Run `pokerforbots <command> --help` for detailed options.
 
@@ -125,4 +127,4 @@ task build
 
 ## License
 
-MIT
+MIT

TODO.md

@@ -29,6 +29,7 @@ PokerForBots is a complete, production-ready poker server for bot-vs-bot play.
 - `pokerforbots client` - Interactive human client
 - Multi-game support with independent hand limits
 - Deterministic testing with seed support
+- Optional PHH hand history recorder with buffered flushing (`--hand-history`)
 
 ### Testing ✅
 - Comprehensive unit tests for all core logic
@@ -121,4 +122,4 @@ This is research infrastructure. Contributions welcome for:
 Not accepting:
 - Feature creep (authentication, databases, etc.)
 - Breaking protocol changes
-- Non-deterministic behavior
+- Non-deterministic behavior