diff --git a/.planning/phases/02-core-gameplay/02-VALIDATION.md b/.planning/phases/02-core-gameplay/02-VALIDATION.md new file mode 100644 index 0000000..04c3332 --- /dev/null +++ b/.planning/phases/02-core-gameplay/02-VALIDATION.md @@ -0,0 +1,136 @@ +--- +phase: 2 +slug: core-gameplay +status: draft +nyquist_compliant: false +wave_0_complete: false +created: 2026-03-10 +--- + +# Phase 2 — Validation Strategy + +> Per-phase validation contract for feedback sampling during execution. + +--- + +## Test Infrastructure + +| Property | Value | +|----------|-------| +| **Framework** | Manual testing + browser DevTools (no test runner in Phase 2) | +| **Config file** | None — vanilla JavaScript, no test config needed | +| **Quick run command** | `open index.html` — play 1 full round; verify score and no crashes | +| **Full suite command** | Play 10 rounds (Easy, Medium, Hard, 2-Player); verify memory stable | +| **Estimated runtime** | ~15 minutes (manual playtesting) | + +--- + +## Sampling Rate + +- **After every task commit:** Run `open index.html` — play 1 full game round (until winner); verify score tracking and no crashes +- **After every plan wave:** Play 5 rounds (1 Easy, 1 Medium, 1 Hard, 2x 2-Player); verify all modes work; no memory growth observed +- **Before `/gsd:verify-work`:** Full suite (all checklist items below) must pass +- **Max feedback latency:** ~5 minutes per task + +--- + +## Per-Task Verification Map + +| Task ID | Plan | Wave | Requirement | Test Type | Automated Command | File Exists | Status | +|---------|------|------|-------------|-----------|-------------------|-------------|--------| +| 2-01-01 | 01 | 1 | CORE-08 | manual | Open index.html; press Up/Down arrows | ✅ existing | ⬜ pending | +| 2-01-02 | 01 | 1 | AI-01 | manual | Open index.html; observe AI tracks ball | ✅ existing | ⬜ pending | +| 2-01-03 | 01 | 1 | AI-02 | manual | Play Easy difficulty 3 rounds | ✅ existing | ⬜ pending | +| 2-01-04 | 01 | 1 | AI-03 | manual | Play Medium difficulty 3 rounds | ✅ existing | ⬜ pending | +| 2-01-05 | 01 | 1 | AI-04 | manual | Play Hard difficulty 3 rounds | ✅ existing | ⬜ pending | +| 2-02-01 | 02 | 1 | CORE-05 | manual | Play until score; verify correct player scored | ✅ existing | ⬜ pending | +| 2-02-02 | 02 | 1 | CORE-06 | manual | Play to 7 points; verify winner message appears | ✅ existing | ⬜ pending | + +*Status: ⬜ pending · ✅ green · ❌ red · ⚠️ flaky* + +--- + +## Wave 0 Requirements + +Existing infrastructure covers all phase requirements. No automated test framework is used in Phase 2 (vanilla JS, single HTML file). All verification is manual play-testing using the checklist below. + +*If test framework is added in Phase 3 or later, retroactive unit tests can be added for core logic: AI prediction, score detection, state transitions.* + +--- + +## Manual-Only Verifications + +| Behavior | Requirement | Why Manual | Test Instructions | +|----------|-------------|------------|-------------------| +| Player 2 Up/Down arrow keys move paddle | CORE-08 | Browser input — no test runner | Open index.html; press Up/Down; verify smooth movement | +| AI tracks and intercepts ball | AI-01 | Real-time physics simulation | Play Solo vs AI; observe AI paddle moves toward ball | +| Easy AI is beatable | AI-02 | Human judgment required | Play Easy 5 rounds; average player should win | +| Medium AI provides fair challenge | AI-03 | Human judgment required | Play Medium 5 rounds; ~50% win rate for experienced player | +| Hard AI requires skill | AI-04 | Human judgment required | Play Hard 5 rounds; hard but possible to win | +| Ball passes paddle → opponent scores | CORE-05 | UI + state verification | Play until ball exits; verify score increments correctly | +| Reach 7 points → match ends | CORE-06 | Game state verification | Play to conclusion; verify winner message | +| No memory leaks after 10 rounds | (implicit) | DevTools heap snapshot required | Chrome DevTools Memory: heap before vs after 10 rounds; <10MB growth | + +--- + +## Phase 2 Full Validation Checklist + +Before marking Phase 2 complete: + +- [ ] **Player 2 Input** + - [ ] Up arrow moves paddle2 up smoothly (no lag) + - [ ] Down arrow moves paddle2 down smoothly + - [ ] Up+Down pressed simultaneously → paddle stops (correct multi-key handling) + - [ ] Release key → paddle stops immediately (no drift) + +- [ ] **AI Interception** + - [ ] Easy AI misses about 20-30% of serves (beatable) + - [ ] Medium AI misses about 50% of serves (fair challenge) + - [ ] Hard AI misses about 70-80% of serves (skilled) + - [ ] AI still intercepts after wall bounces (prediction logic works) + +- [ ] **Scoring System** + - [ ] Ball passes left edge → score2 increments + - [ ] Ball passes right edge → score1 increments + - [ ] Scores display on-canvas (readable position) + - [ ] Scores reset on restart + +- [ ] **Match End** + - [ ] Player 1 reaches 7 points → "Player 1 Wins!" appears + - [ ] AI/Player 2 reaches 7 points → "AI Wins!" or "Player 2 Wins!" appears + - [ ] Winner message cleared on restart + - [ ] R key restarts game successfully + +- [ ] **Game Modes** + - [ ] Mode selection: press 1 → Solo vs AI; press 2 → 2-Player + - [ ] Difficulty selection: press 1/2/3 → Easy/Medium/Hard + - [ ] 2-Player mode: both paddles controllable (W/S and Up/Down) + - [ ] AI mode: only Player 1 controllable; paddle2 is AI + +- [ ] **Memory & Stability** + - [ ] Play 10 game rounds (variety of modes/difficulties) + - [ ] Chrome DevTools Memory: heap snapshot before → 10 rounds → heap snapshot after + - [ ] Memory growth <10MB (stable, not creeping) + - [ ] No console errors or warnings during gameplay + +- [ ] **Ball Re-serve Timing** + - [ ] After score, ~1 second pause before ball re-serves + - [ ] During pause, ball is stationary + - [ ] After pause, ball serves automatically (no player input needed) + +- [ ] **Edge Cases** + - [ ] Rapidly scoring multiple points → scores tracked correctly + - [ ] Switching modes mid-game → clean restart (scores reset) + +--- + +## Validation Sign-Off + +- [ ] All tasks have manual verify steps documented +- [ ] Sampling continuity: no 3 consecutive tasks without manual verify +- [ ] Wave 0 has no MISSING references (manual testing only — no framework needed) +- [ ] No watch-mode flags +- [ ] Feedback latency <15 minutes (manual playtesting) +- [ ] `nyquist_compliant: true` set in frontmatter + +**Approval:** pending