docs(phase-2): add validation strategy
This commit is contained in:
Dabit
136
.planning/phases/02-core-gameplay/02-VALIDATION.md
Normal file
136
.planning/phases/02-core-gameplay/02-VALIDATION.md
Normal file
@@ -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
|
||||
Reference in New Issue
Block a user