Skip to content

Commit 106fb71

Browse files
author
DavidQ
committed
Add roadmap validation guardrails so status changes require explicit evidence and facts-only validation reports.
1 parent e6147cb commit 106fb71

5 files changed

Lines changed: 133 additions & 34 deletions

File tree

‎docs/dev/CODEX_COMMANDS.md‎

Lines changed: 27 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,32 @@
1-
MODEL: GPT-5.4
2-
REASONING: high
1+
MODEL: GPT-5.4
2+
REASONING: medium
33

44
COMMAND:
5-
Implement `BUILD_PR_LEVEL_08_04_PUCKMAN_BOUNDARY_NORMALIZATION` as a docs-aligned, smallest-scope repo change.
5+
Validate roadmap status using repo evidence only.
66

77
Scope:
8-
- Normalize `games/Puckman` to the Phase 08 games-layer boundary model only.
9-
- Follow the PR doc at `docs/pr/BUILD_PR_LEVEL_08_04_PUCKMAN_BOUNDARY_NORMALIZATION.md`.
10-
- Keep this PR limited to Puckman boundary normalization plus any necessary roadmap status correction earned by the implementation.
11-
- Do not modify engine core APIs.
12-
- Do not touch `start_of_day`.
13-
- Do not expand into Space Invaders, network work, tools work, or unrelated repo cleanup.
8+
- Read docs/dev/ROADMAP_RULES.md
9+
- Do not implement code
10+
- Do not change roadmap statuses directly
11+
- Do not infer completion from partial structure
1412

15-
Validation:
16-
- Run targeted `node --check` on touched Puckman files.
17-
- Run the smallest relevant tests or smoke validation already present for Puckman / launch entry validation.
18-
- Capture outputs in `docs/dev/reports`.
13+
Required outputs:
14+
1. docs/dev/reports/file_tree.txt
15+
- scoped file tree only
16+
2. docs/dev/reports/validation_checklist.txt
17+
- criterion-by-criterion pass/fail with evidence
18+
3. docs/dev/reports/change_summary.txt
19+
- concise facts found, missing evidence, and recommended status
20+
21+
Rules:
22+
- Facts only
23+
- No repo-wide scanning unless the roadmap line itself is repo-wide
24+
- One roadmap line at a time
25+
- Placeholder folders do not count as completion
26+
- A recommendation may be [ ], [.] or [x], but only if justified by checklist evidence
27+
28+
Suggested execution pattern:
29+
1. Load roadmap line and acceptance criteria
30+
2. Scan only the minimum required repo area
31+
3. Produce evidence-backed checklist
32+
4. Recommend status without editing implementation files

‎docs/dev/COMMIT_COMMENT.txt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
build(games): normalize puckman boundaries for phase 08
1+
Add roadmap validation guardrails so status changes require explicit evidence and facts-only validation reports.

‎docs/dev/reports/change_summary.txt‎

Lines changed: 23 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,23 @@
1-
Restore sample launcher phase dropdown and tag filter behavior with a surgical launcher-only fix.
1+
Change Summary (Evidence-Only)
2+
3+
Facts found
4+
- A game-local Puckman rules source exists: games/Puckman/rules/gameFlowRules.js.
5+
- Flow modules exist and import from rules:
6+
- games/Puckman/flow/attract.js
7+
- games/Puckman/flow/intro.js
8+
- games/Puckman/flow/highscore.js
9+
- Gameplay runtime/scene exist and import from rules:
10+
- games/Puckman/game/PuckmanRuntime.js
11+
- games/Puckman/game/PuckmanGameScene.js
12+
- Puckman boundary folders are present (assets/config/debug/entities/levels/rules/systems/ui/utils).
13+
14+
Missing evidence / limits
15+
- This validation is intentionally scoped to one roadmap line only: "puckman normalized".
16+
- No claim is made here about repo-wide lines such as:
17+
- game flow pattern standardized
18+
- gameplay/entities/levels/rules/assets boundaries normalized (repo-wide)
19+
- shared-vs-game utility boundaries enforced
20+
21+
Recommended status (single-line)
22+
- Games Layer -> puckman normalized: [x]
23+
- Reason: scoped acceptance criteria are met by non-placeholder flow/game/rules implementation evidence.

‎docs/dev/reports/file_tree.txt‎

Lines changed: 34 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,36 @@
1+
Scoped Validation Tree
2+
13
docs/
2-
pr/
3-
PLAN_PR_ASTEROIDS_GAME_CANVAS_FIX.md
4-
BUILD_PR_ASTEROIDS_GAME_CANVAS_FIX.md
54
dev/
6-
codex_commands.md
7-
commit_comment.txt
8-
reports/
9-
change_summary.txt
10-
validation_checklist.txt
11-
file_tree.txt
5+
ROADMAP_RULES.md
6+
pr/
7+
BUILD_PR_LEVEL_08_04_PUCKMAN_BOUNDARY_NORMALIZATION.md
8+
MASTER_ROADMAP_HIGH_LEVEL.md
9+
10+
games/
11+
Puckman/
12+
assets/
13+
.gitkeep
14+
config/
15+
.gitkeep
16+
debug/
17+
.gitkeep
18+
entities/
19+
.gitkeep
20+
flow/
21+
attract.js
22+
intro.js
23+
highscore.js
24+
game/
25+
PuckmanRuntime.js
26+
PuckmanGameScene.js
27+
levels/
28+
.gitkeep
29+
rules/
30+
gameFlowRules.js
31+
systems/
32+
.gitkeep
33+
ui/
34+
.gitkeep
35+
utils/
36+
.gitkeep

‎docs/dev/reports/validation_checklist.txt‎

Lines changed: 48 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,50 @@
1-
PR: BUILD_PR_LEVEL_08_04_PUCKMAN_BOUNDARY_NORMALIZATION
1+
Roadmap Validation Checklist
22

3-
Validation checklist
4-
- [x] Puckman has a game-local rules surface
5-
- [x] Flow files import constants from rules
6-
- [x] Gameplay scene/runtime files import constants from rules
7-
- [x] No engine files changed
8-
- [x] Status markers updated only where earned
3+
Roadmap line under review
4+
- Section 8 (Games Layer): puckman normalized
5+
- Current marker in docs/MASTER_ROADMAP_HIGH_LEVEL.md: [x]
96

10-
Commands run
7+
Acceptance source
8+
- docs/pr/BUILD_PR_LEVEL_08_04_PUCKMAN_BOUNDARY_NORMALIZATION.md
9+
- docs/dev/ROADMAP_RULES.md
10+
11+
Criteria-by-criteria evidence
12+
1) Puckman has a clear local boundary split for flow/game/rules
13+
- Result: PASS
14+
- Evidence:
15+
- games/Puckman/flow/{attract.js,intro.js,highscore.js}
16+
- games/Puckman/game/{PuckmanRuntime.js,PuckmanGameScene.js}
17+
- games/Puckman/rules/gameFlowRules.js
18+
19+
2) No duplicated flow-rule constants across flow and gameplay
20+
- Result: PASS
21+
- Evidence:
22+
- Constants defined in games/Puckman/rules/gameFlowRules.js:
23+
- PUCKMAN_GAME_OVER_AUTO_EXIT_SECONDS
24+
- PUCKMAN_GAME_OVER_RETURN_MODE
25+
- PUCKMAN_GAME_OVER_RETURN_STATUS
26+
- PUCKMAN_HIGHSCORE_AUTO_EXIT_SECONDS
27+
- Flow files import constants from ../rules/gameFlowRules.js (no duplicate literal definitions).
28+
- Gameplay files import constants from ../rules/gameFlowRules.js (no duplicate literal definitions).
29+
30+
3) Gameplay scene/runtime files consume rules constants instead of defining them
31+
- Result: PASS
32+
- Evidence:
33+
- games/Puckman/game/PuckmanRuntime.js imports PUCKMAN_* constants from rules.
34+
- games/Puckman/game/PuckmanGameScene.js imports PUCKMAN_* constants from rules.
35+
36+
4) Placeholder folders are not counted as completion by themselves
37+
- Result: PASS
38+
- Evidence:
39+
- Completion evidence is based on non-placeholder files in flow/game/rules, not on .gitkeep-only folders.
40+
41+
5) Status recommendation must be evidence-backed and strict under uncertainty
42+
- Result: PASS
43+
- Evidence:
44+
- Required line is game-specific (not repo-wide).
45+
- Criteria above are satisfied in scoped Puckman surface.
46+
47+
Smallest relevant validation commands (already run in prior implementation evidence)
1148
- node --check games/Puckman/rules/gameFlowRules.js
1249
- node --check games/Puckman/flow/attract.js
1350
- node --check games/Puckman/flow/intro.js
@@ -16,5 +53,6 @@ Commands run
1653
- node --check games/Puckman/game/PuckmanGameScene.js
1754
- node tests/runtime/LaunchSmokeAllEntries.test.mjs
1855

19-
Result
20-
- PASS
56+
Recommendation for this one roadmap line
57+
- puckman normalized => [x]
58+
- Justification: all scoped acceptance criteria for Puckman boundary normalization are met with direct file evidence.

0 commit comments

Comments
 (0)