|
| 1 | +# BUILD_PR_LEVEL_08_04_PUCKMAN_BOUNDARY_NORMALIZATION |
| 2 | + |
| 3 | +## Purpose |
| 4 | +Normalize **Puckman** to the Phase 08 games-layer boundary model only. |
| 5 | + |
| 6 | +This PR is intentionally narrow: |
| 7 | +- no engine edits |
| 8 | +- no repo-wide restructuring |
| 9 | +- no Space Invaders edits |
| 10 | +- no unrelated sample cleanup |
| 11 | +- no gameplay feature expansion |
| 12 | + |
| 13 | +## Why this is next |
| 14 | +`PR_08_03_GAMES_MIGRATION` added placeholder `rules` folders across many games, but it did **not** complete Phase 08. |
| 15 | + |
| 16 | +What is now true: |
| 17 | +- broad folder coverage improved |
| 18 | +- placeholder boundaries exist for many games |
| 19 | + |
| 20 | +What is still not true: |
| 21 | +- repo-wide flow standardization is not earned |
| 22 | +- shared-vs-game utility enforcement is not earned |
| 23 | +- Puckman normalization is still not earned |
| 24 | +- full current-games migration is still not earned |
| 25 | + |
| 26 | +The smallest valid next move is: |
| 27 | +1. normalize **Puckman** to the same game-local boundary model used for focused game migrations, |
| 28 | +2. keep the PR game-local and surgical, |
| 29 | +3. update Phase 08 status only where actually earned. |
| 30 | + |
| 31 | +## Required boundary target |
| 32 | +Puckman should follow this ownership model: |
| 33 | + |
| 34 | +- `games/Puckman/flow/*` |
| 35 | + - attract / intro / highscore flow modules when those states exist |
| 36 | + - no duplicated rule constants |
| 37 | +- `games/Puckman/game/*` |
| 38 | + - runtime orchestration and scene wiring only |
| 39 | +- `games/Puckman/entities/*` |
| 40 | + - player, ghost, pellet, fruit, tunnel, collision-domain entities |
| 41 | +- `games/Puckman/levels/*` |
| 42 | + - maze/layout/start-state progression definitions |
| 43 | +- `games/Puckman/rules/*` |
| 44 | + - authoritative game-local constants and flow/rules contracts |
| 45 | +- `games/Puckman/assets/*` and platform-local assets |
| 46 | + - only Puckman-owned media/content |
| 47 | +- `games/Puckman/systems/*` and `games/Puckman/utils/*` |
| 48 | + - game-specific helpers only |
| 49 | + |
| 50 | +## Implementation goals |
| 51 | +Codex should make only the smallest changes needed to achieve the following: |
| 52 | + |
| 53 | +1. Create or normalize a Puckman rules surface |
| 54 | + - add a game-local rules module if missing |
| 55 | + - move duplicated flow/gameplay constants there |
| 56 | + - make flow + gameplay import from one source of truth |
| 57 | + |
| 58 | +2. Normalize flow contract files |
| 59 | + - ensure `flow/attract.js`, `flow/intro.js`, and `flow/highscore.js` exist if the game supports those states |
| 60 | + - keep exports stable unless a correction is required |
| 61 | + - do not change player-facing behavior unless needed to preserve current behavior |
| 62 | + |
| 63 | +3. Normalize gameplay ownership |
| 64 | + - move game-flow constants out of gameplay scene/runtime files into rules |
| 65 | + - keep scene/runtime files focused on orchestration |
| 66 | + |
| 67 | +4. Preserve game-local ownership |
| 68 | + - do not move Puckman assets/utilities into shared unless they are already clearly cross-game |
| 69 | + - do not pull engine utilities into the game folder |
| 70 | + |
| 71 | +5. Update status truthfully |
| 72 | + - only mark roadmap items complete when the repo actually satisfies them after this PR |
| 73 | + - preserve full roadmap line text when editing status markers |
| 74 | + - do not downgrade any item that is already truly complete |
| 75 | + |
| 76 | +## Non-goals |
| 77 | +- no engine API redesign |
| 78 | +- no start_of_day edits |
| 79 | +- no network work |
| 80 | +- no sample index work |
| 81 | +- no broad tools cleanup |
| 82 | +- no Phase 09+ work |
| 83 | + |
| 84 | +## Expected touched areas |
| 85 | +- `games/Puckman/flow/*` |
| 86 | +- `games/Puckman/game/*` |
| 87 | +- `games/Puckman/rules/*` |
| 88 | +- optional: `games/Puckman/entities/*`, `levels/*`, `systems/*`, `utils/*` |
| 89 | +- roadmap/status docs only if already part of the repo’s active tracking files |
| 90 | + |
| 91 | +## Acceptance criteria |
| 92 | +- Puckman has a clear local boundary split for flow/game/rules |
| 93 | +- no duplicated flow-rule constants across flow and gameplay |
| 94 | +- gameplay scene/runtime files consume rules constants instead of defining them |
| 95 | +- no engine files changed |
| 96 | +- targeted validation passes |
| 97 | +- roadmap status updated only to reflect actual repo truth |
| 98 | + |
| 99 | +## Corrected Phase 08 status after reviewing `PR_08_03_GAMES_MIGRATION` |
| 100 | + |
| 101 | +Earned now: |
| 102 | +- [x] `games/_template/` created |
| 103 | +- [.] per-game structure normalized |
| 104 | +- [.] current games migrated to target structure |
| 105 | + |
| 106 | +Still not earned from the uploaded PRs: |
| 107 | +- [ ] game flow pattern standardized (`flow/attract.js`, `flow/intro.js`, `flow/highscore.js`) |
| 108 | +- [ ] gameplay/entities/levels/rules/assets boundaries normalized |
| 109 | +- [ ] shared-vs-game utility boundaries enforced |
| 110 | +- [ ] space_invaders normalized |
| 111 | +- [ ] puckman normalized |
| 112 | +- [ ] future games follow template-first path |
| 113 | + |
| 114 | +## Suggested commit title |
| 115 | +`build(games): normalize puckman boundaries for phase 08` |
| 116 | + |
| 117 | +## After this PR |
| 118 | +Phase 08 should be reassessed strictly from repo truth. Likely remaining work after Puckman will be: |
| 119 | +- Space Invaders normalization, if not already fully implemented in repo |
| 120 | +- shared-vs-game utility boundary enforcement |
| 121 | +- final truthful status alignment |
0 commit comments