Validate and close remaining roadmap residue in one combined pass

DavidQ · DavidQ · commit c0cf2e0ab3fd · 2026-04-14T22:59:06.000-04:00
BUILD_PR_REMAINING_ROADMAP_VALIDATE_OR_CLOSEOUT_COMBINED
diff --git a/docs/MASTER_ROADMAP_HIGH_LEVEL.md b/docs/MASTER_ROADMAP_HIGH_LEVEL.md
diff --git a/docs/dev/CODEX_COMMANDS.md b/docs/dev/CODEX_COMMANDS.md
@@ -2,52 +2,57 @@ MODEL: GPT-5.4
 REASONING: high
 
 COMMAND:
-Create `BUILD_PR_LEVEL_06_SAMPLE_PHASE_TRACKS_AND_2D_SAMPLE_BUILDS_INSPECT_FIRST`.
+Create `BUILD_PR_REMAINING_ROADMAP_VALIDATE_OR_CLOSEOUT_COMBINED`.
 
 Goal:
-Close as much of the remaining sample-phase and 2D dependency-driven sample lane as truthfully possible, but DO NOT blindly create items that may already exist.
+Validate the remaining listed roadmap items against repo truth and close them in one combined pass wherever possible.
 
-Inspect-first requirements:
-1. Inspect the repo first for each target item.
+Validate-first requirements:
+1. Inspect repo truth for each target item before changing anything.
 2. Classify each item as:
-   - already exists and complete
-   - partially exists and needs normalization
-   - missing and needs creation
-   - exists under the wrong name/location and needs alignment
+   - already complete
+   - partially complete
+   - incomplete
+3. If already complete:
+   - update roadmap status only
+4. If partially complete or incomplete:
+   - do the smallest valid work needed to close it
+   - avoid unrelated expansion
 
 Target items:
 
-Sample Phase Tracks
-- foundational phases normalized
-- tilemap / camera / rendering phases normalized
-- tool-linked sample phases normalized
-- network concepts / latency / simulation phase normalized
+Tooling Strategy By Need
+- 2D tool stabilization before 3D tool expansion
 
-Dependency-Driven Sample Builds
-- 2D camera sample
-- tilemap scrolling sample
-- collision sample
-- enemy behavior sample
-- full 2D reference game sample
+Next Planning / Normalization Lanes
+- Apply master roadmap baseline
+- Normalize samples phase structure
+
+Repo Operator + Asset Conversion Scripting Lanes
+- Existing games asset folders updated so existing images / vectors / related runtime assets can be transformed into tool-editable `data/` objects, with corresponding project JSON updates
+
+Later Capability Lanes
+- FEATURE: Fullscreen Bezel Overlay System
+
+Final Cleanup Lane
+- Reduce legacy footprint after replacements are proven
 
 Required work:
-1. Reuse and normalize existing sample assets/surfaces wherever possible.
-2. Do NOT recreate samples that already exist under acceptable names/locations.
-3. Create only the truly missing items.
-4. Keep changes surgical and truth-based.
-5. Update roadmap status markers only.
-6. Report:
-   - what already existed
-   - what was normalized
-   - what was newly created
-   - what remains open, if anything
+1. Reuse already-completed repo work wherever truth supports closure.
+2. Perform only the smallest valid residue work for any incomplete items.
+3. Keep changes coherent and surgical.
+4. Update roadmap status markers only.
+5. Report:
+   - what was already complete
+   - what was completed in this PR
+   - what remains open, if anything, with exact blockers
 
 Final packaging step is REQUIRED:
 - package ALL changed files into this exact repo-structured ZIP:
-  `<project folder>/tmp/BUILD_PR_LEVEL_06_SAMPLE_PHASE_TRACKS_AND_2D_SAMPLE_BUILDS_INSPECT_FIRST.zip`
+  `<project folder>/tmp/BUILD_PR_REMAINING_ROADMAP_VALIDATE_OR_CLOSEOUT_COMBINED.zip`
 
 Hard rules:
-- inspect first, create second
-- no blind sample creation
+- validate first, build second
+- combine aggressively to reduce PR count
 - no unrelated repo changes
 - no missing ZIP
diff --git a/docs/dev/COMMIT_COMMENT.txt b/docs/dev/COMMIT_COMMENT.txt
@@ -1,2 +1,2 @@
-Inspect-first closeout for sample phase tracks and 2D dependency-driven sample builds
-BUILD_PR_LEVEL_06_SAMPLE_PHASE_TRACKS_AND_2D_SAMPLE_BUILDS_INSPECT_FIRST
+Validate and close remaining roadmap residue in one combined pass
+BUILD_PR_REMAINING_ROADMAP_VALIDATE_OR_CLOSEOUT_COMBINED
diff --git a/docs/dev/NEXT_COMMAND.txt b/docs/dev/NEXT_COMMAND.txt
@@ -1 +1 @@
-BUILD_PR_LEVEL_06_SAMPLE_PHASE_TRACKS_AND_2D_SAMPLE_BUILDS_RESIDUE_ONLY
+BUILD_PR_REMAINING_ROADMAP_RESIDUE_ONLY_IF_NEEDED
diff --git a/docs/dev/reports/BUILD_PR_REMAINING_ROADMAP_VALIDATE_OR_CLOSEOUT_COMBINED_report.md b/docs/dev/reports/BUILD_PR_REMAINING_ROADMAP_VALIDATE_OR_CLOSEOUT_COMBINED_report.md
@@ -0,0 +1,77 @@
+# BUILD_PR_REMAINING_ROADMAP_VALIDATE_OR_CLOSEOUT_COMBINED Report
+
+## Validate-First Classification
+
+### Tooling Strategy By Need
+- `2D tool stabilization before 3D tool expansion`
+  - classification: already complete
+  - evidence:
+    - 2D/active tool cluster present: `tools/Tilemap Studio`, `tools/Parallax Scene Studio`, `tools/Vector Map Editor`, `tools/Vector Asset Studio`, `tools/Physics Sandbox`, `tools/State Inspector`, `tools/Replay Visualizer`, `tools/Performance Profiler`, `tools/Asset Pipeline Tool`, `tools/Tile Model Converter`
+    - 3D expansion tools present as a separate follow-on cluster: `tools/3D Map Editor`, `tools/3D Asset Viewer`, `tools/3D Camera Path Editor`
+    - prior docs lane sequencing confirms 2D normalization cluster and then 3D residue add-on (`docs/pr/BUILD_PR_LEVEL_09_TOOLS_NORMALIZATION_AND_REQUIRED_TOOLS_COMBINED_PASS.md`, `docs/pr/BUILD_PR_LEVEL_09_TOOLS_RESIDUE_ONLY.md`)
+
+### Next Planning / Normalization Lanes
+- `Apply master roadmap baseline`
+  - classification: already complete
+  - evidence:
+    - active-roadmap location/rule in `docs/dev/roadmaps/README.md`
+    - active master roadmap maintained at `docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md`
+- `Normalize samples phase structure`
+  - classification: already complete
+  - evidence:
+    - canonical phase directories exist: `samples/phase-01` through `samples/phase-15`
+    - `samples/index.html` phase sections and links are in canonical `phase-XX/<id>/index.html` format
+    - `samples/metadata/samples.index.metadata.json` tracks phases `01..15`
+
+### Repo Operator + Asset Conversion Scripting Lanes
+- `Existing games asset folders updated so existing images / vectors / related runtime assets can be transformed into tool-editable data objects, with corresponding project JSON updates`
+  - classification: partially complete
+  - evidence:
+    - Asteroids is converted (`games/Asteroids/assets/tools.manifest.json` + `sprites/tilemaps/parallax/vectors/data`)
+    - broader game set is not fully converted (inspection found only 1/19 games with full data-contract shape)
+  - blocker:
+    - full closure requires dependency-ordered, multi-game conversion and per-game JSON/manifest alignment; this is broader than a residue-only marker pass
+
+### Later Capability Lanes
+- `FEATURE: Fullscreen Bezel Overlay System ...`
+  - classification: already complete
+  - evidence:
+    - runtime modules: `src/engine/runtime/fullscreenBezel.js`, `src/engine/runtime/backgroundImage.js`
+    - engine integration: `src/engine/core/Engine.js`
+    - focused tests: `tests/core/BackgroundImageAndFullscreenBezel.test.mjs`, `tests/games/FullscreenBezelOverlay.test.mjs`
+    - focused test run in this PR: `node tests/core/BackgroundImageAndFullscreenBezel.test.mjs` PASS
+
+### Final Cleanup Lane
+- `Reduce legacy footprint after replacements are proven`
+  - classification: partially complete
+  - evidence:
+    - policy/inventory work is complete (Section 15 markers are complete)
+    - retained legacy surfaces still exist by design (`docs/archive/tools/SpriteEditor_old_keep`, docs-only placeholder policy artifacts)
+  - blocker:
+    - final reduction requires an explicit replacement-proven cleanup execution lane, not only status reconciliation
+
+## Roadmap Status Updates Applied (Markers Only)
+- closed (`[x]`):
+  - `2D tool stabilization before 3D tool expansion`
+  - `Apply master roadmap baseline`
+  - `Normalize samples phase structure`
+  - `FEATURE: Fullscreen Bezel Overlay System ...`
+- left open by truth:
+  - `Existing games asset folders updated ...` (remains partial)
+  - `Reduce legacy footprint after replacements are proven` (remains open)
+
+## Completed In This PR vs Already Complete
+- already complete and marker-closed in this PR:
+  - 2D tool stabilization before 3D tool expansion
+  - Apply master roadmap baseline
+  - Normalize samples phase structure
+  - Fullscreen Bezel Overlay System
+- partially complete and left open:
+  - Existing games asset folders conversion lane
+  - Final legacy-footprint reduction lane
+
+## Remaining Open Items + Exact Blockers
+1. `Existing games asset folders updated ... data objects ... project JSON updates`
+   - blocker: conversion currently complete for Asteroids, not for the full existing-games set.
+2. `Reduce legacy footprint after replacements are proven`
+   - blocker: final cleanup execution remains pending after replacement-proof gating.
diff --git a/docs/dev/reports/change_summary.txt b/docs/dev/reports/change_summary.txt
@@ -1,3 +1,3 @@
-- Added an inspect-first PR for remaining Sample Phase Tracks and Dependency-Driven Sample Builds
-- Requires repo truth classification before any creation or normalization
-- Prevents duplicate sample creation and unnecessary churn
+- Added validate-first combined closeout PR for the remaining listed roadmap items
+- Requires repo-truth inspection before any new work is created
+- Intended to reduce PR count by closing already-complete items with status-only updates and building only true residue
diff --git a/docs/dev/reports/validation_checklist.txt b/docs/dev/reports/validation_checklist.txt
@@ -1,7 +1,7 @@
-- each target item was inspected before any creation
-- already-existing items were reused instead of recreated
-- only missing items were created
+- each listed item inspected before any creation/work
+- already-complete items closed by status update only
+- only incomplete residue received implementation work
 - roadmap updated by status markers only
-- any residue is explicit and minimal
+- any remaining blockers are explicit
 - output ZIP created at:
-  <project folder>/tmp/BUILD_PR_LEVEL_06_SAMPLE_PHASE_TRACKS_AND_2D_SAMPLE_BUILDS_INSPECT_FIRST.zip
+  <project folder>/tmp/BUILD_PR_REMAINING_ROADMAP_VALIDATE_OR_CLOSEOUT_COMBINED.zip
diff --git a/docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md b/docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md
@@ -457,7 +457,7 @@
 - [x] Tile/Model Converter Tool
 
 ### Tooling Strategy By Need
-- [ ] 2D tool stabilization before 3D tool expansion
+- [x] 2D tool stabilization before 3D tool expansion
 - [ ] 3D prerequisite samples before advanced 3D tools
 - [x] content pipeline tools after asset complexity justifies them
 - [x] debug tools align with engine/debug maturity
@@ -592,8 +592,8 @@
 - [.] Normalize phase-13 network concepts samples
 
 ### Next Planning / Normalization Lanes
-- [ ] Apply master roadmap baseline
-- [ ] Normalize samples phase structure
+- [x] Apply master roadmap baseline
+- [x] Normalize samples phase structure
 - [x] Establish games/_template and normalize games layer
 - [x] Normalize tools/shared and tool boundaries
 - [x] Normalize assets/data ownership
@@ -606,7 +606,7 @@
 - [x] Add scripts to switch between Pay-as-you-go and Codex plan modes, and scripts to input API key material and validate it
 
 ### Later Capability Lanes
-- [.] FEATURE: Fullscreen Bezel Overlay System - Render game in full screen with optional bezel artwork layer (static or animated) surrounding the active playfield, preserving aspect ratio and supporting per-game/theme bezel assets without modifying core engine rendering.
+- [x] FEATURE: Fullscreen Bezel Overlay System - Render game in full screen with optional bezel artwork layer (static or animated) surrounding the active playfield, preserving aspect ratio and supporting per-game/theme bezel assets without modifying core engine rendering.
 
 ### Later Capability Lanes
 - [.] Execute 2D capability polish lanes
diff --git a/docs/pr/BUILD_PR_REMAINING_ROADMAP_VALIDATE_OR_CLOSEOUT_COMBINED.md b/docs/pr/BUILD_PR_REMAINING_ROADMAP_VALIDATE_OR_CLOSEOUT_COMBINED.md
@@ -0,0 +1,73 @@
+# BUILD_PR_REMAINING_ROADMAP_VALIDATE_OR_CLOSEOUT_COMBINED
+
+## Purpose
+Validate the remaining listed roadmap items against repo truth and close them in the fewest practical PRs.
+
+## Validate-first rule
+For each target item:
+1. Inspect repo truth first.
+2. If already complete, mark complete.
+3. If partially complete, do the smallest valid work to finish it.
+4. If not complete, perform the minimum PLAN/BUILD/APPLY-equivalent work needed through this one combined PR.
+5. Do not blindly recreate work that already exists.
+
+## Target items
+
+### Tooling Strategy By Need
+- 2D tool stabilization before 3D tool expansion
+
+### Next Planning / Normalization Lanes
+- Apply master roadmap baseline
+- Normalize samples phase structure
+
+### Repo Operator + Asset Conversion Scripting Lanes
+- Existing games asset folders updated so existing images / vectors / related runtime assets can be transformed into tool-editable `data/` objects, with corresponding project JSON updates
+
+### Later Capability Lanes
+- FEATURE: Fullscreen Bezel Overlay System
+
+### Final Cleanup Lane
+- Reduce legacy footprint after replacements are proven
+
+## Combined scope
+
+### A. Validation-first completion
+Codex must inspect whether each listed item is already complete or partially complete before changing anything.
+
+### B. Smallest valid closeout
+If work is still needed:
+- complete only the smallest valid remaining surface
+- keep changes surgical
+- avoid unrelated lane expansion
+
+### C. Mixed-lane handling
+Because these items span strategy, normalization, scripting, capability, and cleanup:
+- reuse already completed work wherever possible
+- prefer status closure when repo truth already supports it
+- only implement missing residue where necessary
+
+### D. Roadmap handling
+- update status markers only
+- no roadmap text rewrite
+- if an item is still not truthfully complete, leave it open and report exact blockers
+
+## Desired outcome
+This PR should close as many of the listed items as truthfully possible in one pass, and leave only explicit residue if any real blocker remains.
+
+## Validation requirements
+Codex must report:
+- which target items were already complete
+- which were partially complete
+- what minimal work was done to close any incomplete items
+- which items remain open, if any, and exact blockers
+- whether one final residue-only PR would be needed at all
+
+## Packaging
+`<project folder>/tmp/BUILD_PR_REMAINING_ROADMAP_VALIDATE_OR_CLOSEOUT_COMBINED.zip`
+
+## Scope guard
+- docs-first PR bundle
+- Codex writes implementation
+- validate first, build second
+- combine aggressively to reduce PR count
+- no unrelated repo changes

Original file line number	Diff line number	Diff line change
`@@ -1 +1 @@`
`1`		`-BUILD_PR_LEVEL_06_SAMPLE_PHASE_TRACKS_AND_2D_SAMPLE_BUILDS_RESIDUE_ONLY`
	`1`	`+BUILD_PR_REMAINING_ROADMAP_RESIDUE_ONLY_IF_NEEDED`