Finalize section 1 structure planning and re-anchor roadmap to top-down execution

BUILD_PR_LEVEL_01_STRUCTURE_FINALIZATION_AND_ROADMAP_CORRECTION

Author: DavidQ

docs/dev/CODEX_COMMANDS.md

@@ -2,40 +2,39 @@ MODEL: GPT-5.4
 REASONING: high
 
 COMMAND:
-Create `BUILD_PR_ROADMAP_REPAIR_ADDITIVE_MOVE_ONLY`.
+Create `BUILD_PR_LEVEL_01_STRUCTURE_FINALIZATION_AND_ROADMAP_CORRECTION`.
 
-Repair:
-`docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md`
+Goals:
+1. Finalize the remaining planning/definition work for roadmap section 1.
+2. Re-anchor execution order to the correct top-down next lane.
+3. Keep this PR docs-first and surgical.
 
-Hard rules:
-- NO delete
-- NO text rewrite
-- NO summarization
-- ONLY adds, moves, and status marker updates
-- preserve every existing roadmap line somewhere in the repaired file
+Required work:
+1. Complete the remaining section-1 definition items where possible:
+   - map current folder inventory to target homes
+   - define remaining move-map lanes
+   - define ambiguous-name rename map where still needed
+   - define legacy migration map where still needed
+   - confirm structure targets and boundaries against current repo state
 
-Required actions:
-1. Repair roadmap structure using MOVE operations first
-2. Preserve all existing text exactly as written
-3. If duplicated/appended content exists:
-   - move it into the correct location when clear
-   - otherwise preserve it in an additive `Recovery / Preserved Content` section
-4. Productization-rule style content:
-   - move to the correct policy/instruction area if touched
-   - do not delete
-   - do not rewrite
-5. Update status markers only where execution truth clearly supports it
-6. Do not change any other wording
+2. Update roadmap status markers only where truthfully supported.
+   - do NOT rewrite roadmap text
+   - do NOT jump to already-complete sections as the next lane
+   - section 1 should become the active anchor if validation supports it
 
-Validation output must explicitly confirm:
-- no roadmap text deleted
-- no roadmap wording changed
-- only adds, moves, and status updates were used
+3. Produce clear handoff guidance for later implementation PRs:
+   - exact move-map lanes
+   - exact rename-map lanes
+   - exact validation gates
+   - explicit no-go areas for now
 
-Final packaging step is REQUIRED:
-`<project folder>/tmp/BUILD_PR_ROADMAP_REPAIR_ADDITIVE_MOVE_ONLY.zip`
+4. Final packaging step is REQUIRED:
+   - package ALL changed files into this exact repo-structured ZIP:
+     `<project folder>/tmp/BUILD_PR_LEVEL_01_STRUCTURE_FINALIZATION_AND_ROADMAP_CORRECTION.zip`
 
 Hard rules:
-- roadmap repair only
+- docs-first only
+- no implementation code by ChatGPT
+- no broad repo churn
 - no unrelated repo changes
 - no missing ZIP

docs/dev/COMMIT_COMMENT.txt

@@ -1,2 +1,2 @@
-Repair master roadmap using additive and move-only rules
-BUILD_PR_ROADMAP_REPAIR_ADDITIVE_MOVE_ONLY
+Finalize section 1 structure planning and re-anchor roadmap to top-down execution
+BUILD_PR_LEVEL_01_STRUCTURE_FINALIZATION_AND_ROADMAP_CORRECTION

docs/dev/NEXT_COMMAND.txt

@@ -1 +1 @@
-BUILD_PR_LEVEL_01_STRUCTURE_FINALIZATION_AND_ROADMAP_CORRECTION
+BUILD_PR_LEVEL_01_MOVE_MAP_IMPLEMENTATION_CANDIDATE

docs/dev/reports/change_summary.txt

@@ -1,4 +1,3 @@
-- Added strict roadmap-repair bundle
-- Enforced no-delete and no-text-change rules
-- Limited Codex to adds, moves, and status-marker updates only
-- Added recovery section fallback to preserve uncertain content rather than deleting it
+- Added section-1 finalization PR as the correct top-down next lane
+- Re-anchored execution away from already-complete section 11
+- Focused on move-map, rename-map, legacy-map, and validation-gate definition only

docs/dev/reports/validation_checklist.txt

@@ -1,7 +1,7 @@
-- No roadmap text deleted
-- No roadmap wording changed
-- Only adds, moves, and status-marker updates used
-- Duplicated/appended content preserved and relocated
-- Recovery / Preserved Content section used if placement uncertainty remained
+- Section 1 is treated as the active next lane if roadmap truth supports it
+- Remaining section-1 definition items are addressed
+- Roadmap updates are status-only
+- No broad file moves are performed in this PR
+- Later implementation lanes are clearly defined
 - Output ZIP created at:
-  <project folder>/tmp/BUILD_PR_ROADMAP_REPAIR_ADDITIVE_MOVE_ONLY.zip
+  <project folder>/tmp/BUILD_PR_LEVEL_01_STRUCTURE_FINALIZATION_AND_ROADMAP_CORRECTION.zip

docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md

@@ -101,11 +101,11 @@
 - [.] dependency direction rules defined
 - [.] shared asset promotion rules defined
 - [.] network samples classified as sample-phase content
-- [ ] current folder inventory mapped to target homes
-- [ ] move-map defined for root `engine/` -> `src/engine/`
+- [x] current folder inventory mapped to target homes
+- [x] move-map defined for root `engine/` -> `src/engine/`
 - [x] duplicate-helper migration map defined
-- [ ] ambiguous-name rename map defined
-- [ ] legacy migration map defined
+- [x] ambiguous-name rename map defined
+- [x] legacy migration map defined
 - [.] implementation PRs executed
 - [x] imports normalized after moves
 - [x] post-move validation complete
@@ -122,8 +122,8 @@
 - [x] `src/shared/math`
 - [x] `src/shared/state`
 - [x] `games/_template/flow`
-- [ ] `samples/phase-01`
-- [ ] `samples/phase-13`
+- [x] `samples/phase-01`
+- [x] `samples/phase-13`
 - [x] `tools/shared`
 
 ### Recent Checkpoint Notes
@@ -617,7 +617,7 @@
 - [x] Execute `templates/` relocation and root removal cleanup PR
 
 ### Recommended Final Status Summary
-- [.] current active execution lanes are 3 / 6 / 8
+- [ ] current active execution lanes are 3 / 6 / 8
 - [ ] next planning lanes are 2 / 5 / 7 / 9 / 10
 - [ ] later capability lanes are 11 / 12
 - [ ] final cleanup lane is 13

docs/pr/BUILD_PR_LEVEL_01_STRUCTURE_FINALIZATION_AND_ROADMAP_CORRECTION.md

@@ -0,0 +1,81 @@
+# BUILD_PR_LEVEL_01_STRUCTURE_FINALIZATION_AND_ROADMAP_CORRECTION
+
+## Purpose
+Finalize the remaining planning/definition work for roadmap section 1 and re-anchor execution order to the correct top-down next lane.
+
+## Scope
+- docs-first only
+- roadmap status markers only
+- no implementation code or broad file churn
+
+## Evidence Snapshot (Current Repo State)
+- Root structure contains `src/`, `games/`, `samples/`, `tools/`, `scripts/`, `docs/`, `tests/`.
+- Legacy root folders targeted by section-1 move-map are already absent at root: `engine/`, `shared/`, `templates/`.
+- Structure-target evidence:
+  - `samples/phase-01` exists.
+  - `samples/phase-13` exists.
+  - `src/engine/render` and `src/engine/scenes` exist, while `src/engine/rendering` and `src/engine/scene` remain pending target names.
+  - legacy retention candidate still exists in archive path: `docs/archive/tools/SpriteEditor_old_keep/`.
+
+## Folder Inventory To Target Homes (Definition Closeout)
+- Root runtime/shared home: `src/`
+- Game ownership home: `games/`
+- Tool ownership home: `tools/`
+- Sample ownership home: `samples/`
+- Docs/archive retention home: `docs/archive/`
+
+## Exact Move-Map Lanes (For Later Implementation PRs)
+1. `MOVE_MAP_L1_ENGINE_ALIAS_CONVERGENCE`
+- Scope: converge `src/engine/render` -> `src/engine/rendering` and `src/engine/scenes` -> `src/engine/scene`.
+- Guard: move-only with import/path fixups and targeted runtime/tool launch checks.
+2. `MOVE_MAP_L1_SAMPLE_SHARED_SURFACE_CONVERGENCE`
+- Scope: resolve `samples/shared` vs `samples/_shared` to one canonical shared sample surface.
+- Guard: no sample behavior rewrite; path and import normalization only.
+3. `MOVE_MAP_L1_TOOL_NAME_PATH_ALIGNMENT`
+- Scope: align active tool path names with roadmap naming conventions where mismatched.
+- Guard: preserve tool entry behavior; no UI redesign.
+
+## Exact Rename-Map Lanes (For Later Implementation PRs)
+1. `RENAME_MAP_L1_ENGINE_DIRECTORY_NAMES`
+- Targets: `render` -> `rendering`, `scenes` -> `scene`.
+2. `RENAME_MAP_L1_TOOL_DIRECTORY_NAMES`
+- Targets (where touched): directory names that drift from active canonical tool naming in roadmap and docs.
+3. `RENAME_MAP_L1_SAMPLE_SHARED_NAMESPACE`
+- Target: one canonical shared-samples namespace.
+
+## Legacy Migration Map (For Later Implementation PRs)
+1. `LEGACY_MAP_L1_ARCHIVE_BOUNDARY_CONFIRMATION`
+- Keep legacy tool snapshots under `docs/archive/` unless explicitly reactivated.
+2. `LEGACY_MAP_L1_IMPORT_AND_REFERENCE_QUARANTINE`
+- Ensure active paths do not depend on archive-only legacy paths.
+3. `LEGACY_MAP_L1_RETIREMENT_PREREQ_INDEX`
+- Add explicit retirement prerequisites before any archive removal decision.
+
+## Validation Gates (For Later Implementation PRs)
+1. Path resolution and import normalization checks for touched files.
+2. `node --check` for touched JavaScript modules.
+3. Focused launch/smoke checks for touched games/tools only.
+4. Boundary check: no cross-layer dependency inversion introduced.
+5. Delta check: no unrelated repo churn outside defined move/rename lanes.
+
+## Explicit No-Go Areas (For Now)
+- No engine core API redesign.
+- No asset moves under `games/*/assets/**` in section-1 move-map PRs.
+- No runtime feature changes bundled with structure-only PRs.
+- No archive deletion from `docs/archive/**` during mapping/definition lanes.
+
+## Roadmap Status Marker Updates Applied
+- `current folder inventory mapped to target homes` -> `[x]`
+- `move-map defined for root engine -> src/engine` -> `[x]`
+- `ambiguous-name rename map defined` -> `[x]`
+- `legacy migration map defined` -> `[x]`
+- `samples/phase-01` structure target -> `[x]`
+- `samples/phase-13` structure target -> `[x]`
+- `current active execution lanes are 3 / 6 / 8` -> `[ ]` (de-anchored as next lane signal)
+
+## Next Active Anchor
+- Section 1 remains the active top-down anchor via:
+  - `Apply repo structure normalization implementation plan` as `[.]`
+
+## Packaging
+`<project folder>/tmp/BUILD_PR_LEVEL_01_STRUCTURE_FINALIZATION_AND_ROADMAP_CORRECTION.zip`