Core Improvements Roadmap: Move Validation, Stability, AI & UX

[nikhilachale]

🎯 Overview

Comprehensive 5-phase improvement plan focusing on core correctness, multiplayer stability, AI quality, UX polish, and production hardening.

---

Phase 1 (Day 1): Core Correctness First

Move Legality Validation

• File: apps/socket/index.ts:1
• Task: Add authoritative move-legality validation before executing moves
• Priority: Critical - prevents illegal moves from being accepted

Castling Edge Cases

• File: packages/Chess/Game.ts:1
• Task: Fix castling rules - cannot castle out of, through, or into check
• Priority: Critical - fundamental chess rule

Promotion Choice Support

• Files: packages/Chess/Game.ts:1, apps/socket/index.ts:1, apps/ui/app/page.tsx:1
• Task: Add full promotion choice support (Q/R/B/N) across engine + socket + UI flow
• Priority: High - affects endgame gameplay

Insufficient Material Logic

• File: packages/Chess/Game.ts:1
• Task: Fix insufficient-material bishop-color logic
• Priority: Medium - affects draw detection

---

Phase 2 (Day 2): Multiplayer Stability Improvements

Player Identity Validation

• File: apps/socket/index.ts:1
• Task: Validate player identity/role inputs and reject spoofed values
• Priority: High - security concern

Room Cleanup Lifecycle

• File: apps/socket/index.ts:1
• Task: Add room cleanup to prevent stale in-memory games
• Priority: High - memory leak prevention

Reconnect Handling

• Files: apps/ui/hooks/useSocket.tsx:1, apps/ui/store/chessStore.ts:1
• Task: Add reconnect retry + rejoin handling
• Priority: Medium - improves reliability

Non-blocking Feedback

• File: apps/ui/app/page.tsx:1
• Task: Replace blocking alerts with non-blocking feedback
• Priority: Medium - UX improvement

---

Phase 3 (Day 3): AI Quality Quick Wins

Opening Depth Behavior

• File: packages/Chess/MoveEvaluator.ts:1
• Task: Fix opening-depth behavior so requested search depth is actually used
• Priority: High - affects AI strength

Reduce Cloning Overhead

• File: packages/Chess/MoveEvaluator.ts:1
• Task: Reduce heavy cloning overhead in evaluator simulations
• Priority: High - performance improvement

AI Sanity Checks

• Files: packages/Chess/src/
• Task: Add deterministic AI sanity checks in tests
• Priority: Medium - reliability

---

Phase 4 (Day 4): UX Polish and Accessibility

Move History Rendering

• Files: apps/ui/components/MoveHistory.tsx:1, apps/ui/store/chessStore.ts:1
• Task: Wire real move history rendering
• Priority: High - core feature

Turn-State Clarity

• File: apps/ui/app/page.tsx:1
• Task: Improve turn-state clarity and move feedback
• Priority: High - UX critical

Mobile Board Scaling

• Files: apps/ui/components/ChessSquare.tsx:1, apps/ui/components/PieceIcon.tsx:1
• Task: Improve mobile board scaling + piece contrast
• Priority: Medium - accessibility

Keyboard Interactions

• File: apps/ui/utils/handleclick.ts:1
• Task: Add basic keyboard interactions
• Priority: Low - accessibility bonus

---

Phase 5 (Day 5): Hardening and Release Checks

Edge Case Testing

• Files: packages/Chess/src/, apps/socket/src/
• Task: Add tests for rule edge cases and socket behavior
• Priority: High - quality assurance

Regression Testing

• Task: Run workspace lint/typecheck/tests and fix regressions
• Priority: Critical - before release

End-to-End Scenarios

• Scenarios to test:
  • Promotion
  • Castling restrictions
  • Reconnect
  • Illegal move rejection
  • Mobile playability
• Priority: Critical - before release

---

⚠️ Dependencies

• Phase 5 depends on Phases 1-4 completion
• Phase 2 and Phase 3 can be worked in parallel
• Testing should accompany each phase

---

📊 Success Criteria

• All illegal moves rejected
• Castling follows full rules
• Promotion choices work across all layers
• Room cleanup prevents memory leaks
• Reconnect flow is reliable
• AI uses requested search depth
• Move history displays correctly
• Mobile experience is playable
• All tests pass
• Manual E2E scenarios pass

🤖 Generated by Claude Code