Phase 08.05 — Space Invaders boundary normalization completion

Author: DavidQ

docs/dev/CODEX_COMMANDS.md

@@ -1,32 +1,13 @@
-MODEL: GPT-5.4
+MODEL: GPT-5.3-codex
 REASONING: medium
 
-COMMAND:
-Validate roadmap status using repo evidence only.
+TASK:
+Normalize SpaceInvaders to match Puckman/Asteroids structure.
 
-Scope:
-- Read docs/dev/ROADMAP_RULES.md
-- Do not implement code
-- Do not change roadmap statuses directly
-- Do not infer completion from partial structure
+CONSTRAINTS:
+- DO NOT modify engine
+- DO NOT add index.html
+- DO NOT standardize flow behavior beyond file presence
 
-Required outputs:
-1. docs/dev/reports/file_tree.txt
-   - scoped file tree only
-2. docs/dev/reports/validation_checklist.txt
-   - criterion-by-criterion pass/fail with evidence
-3. docs/dev/reports/change_summary.txt
-   - concise facts found, missing evidence, and recommended status
-
-Rules:
-- Facts only
-- No repo-wide scanning unless the roadmap line itself is repo-wide
-- One roadmap line at a time
-- Placeholder folders do not count as completion
-- A recommendation may be [ ], [.] or [x], but only if justified by checklist evidence
-
-Suggested execution pattern:
-1. Load roadmap line and acceptance criteria
-2. Scan only the minimum required repo area
-3. Produce evidence-backed checklist
-4. Recommend status without editing implementation files
+OUTPUT:
+Return ZIP to <project folder>/tmp/

docs/dev/COMMIT_COMMENT.txt

@@ -1 +1 @@
-Add roadmap validation guardrails so status changes require explicit evidence and facts-only validation reports.
+Phase 08.05 — Space Invaders boundary normalization completion

docs/dev/reports/change_summary.txt

@@ -1,23 +1 @@
-Change Summary (Evidence-Only)
-
-Facts found
-- A game-local Puckman rules source exists: games/Puckman/rules/gameFlowRules.js.
-- Flow modules exist and import from rules:
-  - games/Puckman/flow/attract.js
-  - games/Puckman/flow/intro.js
-  - games/Puckman/flow/highscore.js
-- Gameplay runtime/scene exist and import from rules:
-  - games/Puckman/game/PuckmanRuntime.js
-  - games/Puckman/game/PuckmanGameScene.js
-- Puckman boundary folders are present (assets/config/debug/entities/levels/rules/systems/ui/utils).
-
-Missing evidence / limits
-- This validation is intentionally scoped to one roadmap line only: "puckman normalized".
-- No claim is made here about repo-wide lines such as:
-  - game flow pattern standardized
-  - gameplay/entities/levels/rules/assets boundaries normalized (repo-wide)
-  - shared-vs-game utility boundaries enforced
-
-Recommended status (single-line)
-- Games Layer -> puckman normalized: [x]
-- Reason: scoped acceptance criteria are met by non-placeholder flow/game/rules implementation evidence.
+Adds Space Invaders completion PR. No code included.

docs/dev/reports/file_tree.txt

@@ -1,36 +1,2 @@
-Scoped Validation Tree
-
-docs/
-  dev/
-    ROADMAP_RULES.md
-  pr/
-    BUILD_PR_LEVEL_08_04_PUCKMAN_BOUNDARY_NORMALIZATION.md
-  MASTER_ROADMAP_HIGH_LEVEL.md
-
-games/
-  Puckman/
-    assets/
-      .gitkeep
-    config/
-      .gitkeep
-    debug/
-      .gitkeep
-    entities/
-      .gitkeep
-    flow/
-      attract.js
-      intro.js
-      highscore.js
-    game/
-      PuckmanRuntime.js
-      PuckmanGameScene.js
-    levels/
-      .gitkeep
-    rules/
-      gameFlowRules.js
-    systems/
-      .gitkeep
-    ui/
-      .gitkeep
-    utils/
-      .gitkeep
+docs/pr/BUILD_PR_LEVEL_08_05_SPACE_INVADERS_COMPLETION.md
+...

docs/dev/reports/validation_checklist.txt

@@ -1,58 +1 @@
-Roadmap Validation Checklist
-
-Roadmap line under review
-- Section 8 (Games Layer): puckman normalized
-- Current marker in docs/MASTER_ROADMAP_HIGH_LEVEL.md: [x]
-
-Acceptance source
-- docs/pr/BUILD_PR_LEVEL_08_04_PUCKMAN_BOUNDARY_NORMALIZATION.md
-- docs/dev/ROADMAP_RULES.md
-
-Criteria-by-criteria evidence
-1) Puckman has a clear local boundary split for flow/game/rules
-- Result: PASS
-- Evidence:
-  - games/Puckman/flow/{attract.js,intro.js,highscore.js}
-  - games/Puckman/game/{PuckmanRuntime.js,PuckmanGameScene.js}
-  - games/Puckman/rules/gameFlowRules.js
-
-2) No duplicated flow-rule constants across flow and gameplay
-- Result: PASS
-- Evidence:
-  - Constants defined in games/Puckman/rules/gameFlowRules.js:
-    - PUCKMAN_GAME_OVER_AUTO_EXIT_SECONDS
-    - PUCKMAN_GAME_OVER_RETURN_MODE
-    - PUCKMAN_GAME_OVER_RETURN_STATUS
-    - PUCKMAN_HIGHSCORE_AUTO_EXIT_SECONDS
-  - Flow files import constants from ../rules/gameFlowRules.js (no duplicate literal definitions).
-  - Gameplay files import constants from ../rules/gameFlowRules.js (no duplicate literal definitions).
-
-3) Gameplay scene/runtime files consume rules constants instead of defining them
-- Result: PASS
-- Evidence:
-  - games/Puckman/game/PuckmanRuntime.js imports PUCKMAN_* constants from rules.
-  - games/Puckman/game/PuckmanGameScene.js imports PUCKMAN_* constants from rules.
-
-4) Placeholder folders are not counted as completion by themselves
-- Result: PASS
-- Evidence:
-  - Completion evidence is based on non-placeholder files in flow/game/rules, not on .gitkeep-only folders.
-
-5) Status recommendation must be evidence-backed and strict under uncertainty
-- Result: PASS
-- Evidence:
-  - Required line is game-specific (not repo-wide).
-  - Criteria above are satisfied in scoped Puckman surface.
-
-Smallest relevant validation commands (already run in prior implementation evidence)
-- node --check games/Puckman/rules/gameFlowRules.js
-- node --check games/Puckman/flow/attract.js
-- node --check games/Puckman/flow/intro.js
-- node --check games/Puckman/flow/highscore.js
-- node --check games/Puckman/game/PuckmanRuntime.js
-- node --check games/Puckman/game/PuckmanGameScene.js
-- node tests/runtime/LaunchSmokeAllEntries.test.mjs
-
-Recommendation for this one roadmap line
-- puckman normalized => [x]
-- Justification: all scoped acceptance criteria for Puckman boundary normalization are met with direct file evidence.
+Verify flow/game/rules separation and no duplication.

docs/pr/BUILD_PR_LEVEL_08_05_SPACE_INVADERS_COMPLETION.md

@@ -0,0 +1,33 @@
+# BUILD_PR — LEVEL 08.05 SPACE INVADERS COMPLETION
+
+## Purpose
+Complete Space Invaders boundary normalization to match Asteroids and Puckman.
+
+## Scope
+- Only Space Invaders game folder
+- No engine changes
+- No flow standardization enforcement
+- No cross-game refactor
+
+## Required Structure
+games/SpaceInvaders/
+  flow/
+  game/
+  rules/
+  entities/
+  levels/
+  assets/
+  systems/
+  ui/
+  utils/
+
+## Acceptance Criteria
+- flow files exist (attract, intro, highscore)
+- rules centralized in rules/
+- game runtime consumes rules
+- no duplicate constants across flow/game
+
+## Out of Scope
+- index.html
+- launcher/bootstrap
+- engine wiring

games/SpaceInvaders/flow/attract.js

@@ -0,0 +1,19 @@
+import {
+  SPACE_INVADERS_FLOW_IDS,
+  SPACE_INVADERS_FLOW_LABELS,
+  SPACE_INVADERS_GAME_OVER_RETURN_MODE,
+  SPACE_INVADERS_GAME_OVER_RETURN_RESET_IDLE,
+  SPACE_INVADERS_GAME_OVER_RETURN_STATUS,
+  createSpaceInvadersFlowDescriptor
+} from "../rules/gameFlowRules.js";
+
+export const SPACE_INVADERS_ATTRACT_FLOW_NEXT_ID = SPACE_INVADERS_FLOW_IDS.intro;
+
+export const attractFlow = createSpaceInvadersFlowDescriptor(SPACE_INVADERS_FLOW_IDS.attract, {
+  label: SPACE_INVADERS_FLOW_LABELS.attract,
+  nextFlowId: SPACE_INVADERS_ATTRACT_FLOW_NEXT_ID,
+  autoAdvanceSeconds: null,
+  statusText: SPACE_INVADERS_GAME_OVER_RETURN_STATUS,
+  returnMode: SPACE_INVADERS_GAME_OVER_RETURN_MODE,
+  resetIdleOnReturn: SPACE_INVADERS_GAME_OVER_RETURN_RESET_IDLE
+});

games/SpaceInvaders/flow/highscore.js

@@ -0,0 +1,16 @@
+import {
+  SPACE_INVADERS_FLOW_IDS,
+  SPACE_INVADERS_FLOW_LABELS,
+  SPACE_INVADERS_HIGHSCORE_AUTO_EXIT_SECONDS,
+  SPACE_INVADERS_HIGHSCORE_STATUS,
+  createSpaceInvadersFlowDescriptor
+} from "../rules/gameFlowRules.js";
+
+export const SPACE_INVADERS_HIGHSCORE_FLOW_NEXT_ID = SPACE_INVADERS_FLOW_IDS.attract;
+
+export const highscoreFlow = createSpaceInvadersFlowDescriptor(SPACE_INVADERS_FLOW_IDS.highscore, {
+  label: SPACE_INVADERS_FLOW_LABELS.highscore,
+  nextFlowId: SPACE_INVADERS_HIGHSCORE_FLOW_NEXT_ID,
+  autoAdvanceSeconds: SPACE_INVADERS_HIGHSCORE_AUTO_EXIT_SECONDS,
+  statusText: SPACE_INVADERS_HIGHSCORE_STATUS
+});

games/SpaceInvaders/flow/intro.js

@@ -0,0 +1,20 @@
+import {
+  SPACE_INVADERS_FLOW_IDS,
+  SPACE_INVADERS_FLOW_LABELS,
+  SPACE_INVADERS_GAME_OVER_AUTO_EXIT_SECONDS,
+  SPACE_INVADERS_GAME_OVER_RETURN_MODE,
+  SPACE_INVADERS_GAME_OVER_RETURN_RESET_IDLE,
+  SPACE_INVADERS_GAME_OVER_RETURN_STATUS,
+  createSpaceInvadersFlowDescriptor
+} from "../rules/gameFlowRules.js";
+
+export const SPACE_INVADERS_INTRO_FLOW_NEXT_ID = SPACE_INVADERS_FLOW_IDS.highscore;
+
+export const introFlow = createSpaceInvadersFlowDescriptor(SPACE_INVADERS_FLOW_IDS.intro, {
+  label: SPACE_INVADERS_FLOW_LABELS.intro,
+  nextFlowId: SPACE_INVADERS_INTRO_FLOW_NEXT_ID,
+  autoAdvanceSeconds: SPACE_INVADERS_GAME_OVER_AUTO_EXIT_SECONDS,
+  statusText: SPACE_INVADERS_GAME_OVER_RETURN_STATUS,
+  returnMode: SPACE_INVADERS_GAME_OVER_RETURN_MODE,
+  resetIdleOnReturn: SPACE_INVADERS_GAME_OVER_RETURN_RESET_IDLE
+});

games/SpaceInvaders/rules/gameFlowRules.js

@@ -0,0 +1,35 @@
+export const SPACE_INVADERS_FLOW_CONTRACT_VERSION = "1";
+
+export const SPACE_INVADERS_FLOW_IDS = Object.freeze({
+  attract: "attract",
+  intro: "intro",
+  highscore: "highscore"
+});
+
+export const SPACE_INVADERS_FLOW_LABELS = Object.freeze({
+  attract: "Attract",
+  intro: "Intro",
+  highscore: "Highscore"
+});
+
+export const SPACE_INVADERS_GAME_OVER_AUTO_EXIT_SECONDS = 30;
+export const SPACE_INVADERS_GAME_OVER_RETURN_MODE = "menu";
+export const SPACE_INVADERS_GAME_OVER_RETURN_STATUS = "Press 1 for one player or 2 for two players.";
+export const SPACE_INVADERS_GAME_OVER_RETURN_RESET_IDLE = true;
+
+export const SPACE_INVADERS_HIGHSCORE_AUTO_EXIT_SECONDS = 12;
+export const SPACE_INVADERS_HIGHSCORE_STATUS = "High scores";
+
+export function createSpaceInvadersFlowDescriptor(id, options = {}) {
+  return Object.freeze({
+    id,
+    label: options.label || id,
+    contractVersion: SPACE_INVADERS_FLOW_CONTRACT_VERSION,
+    nextFlowId: options.nextFlowId || SPACE_INVADERS_FLOW_IDS.attract,
+    autoAdvanceSeconds: options.autoAdvanceSeconds ?? null,
+    statusText: options.statusText || "",
+    returnMode: options.returnMode || SPACE_INVADERS_GAME_OVER_RETURN_MODE,
+    resetIdleOnReturn: options.resetIdleOnReturn ?? SPACE_INVADERS_GAME_OVER_RETURN_RESET_IDLE,
+    debugPluginFactory: options.debugPluginFactory || null
+  });
+}