Combine legacy reduction and documentation-system closeout into one low-PR pass

DavidQ · DavidQ · commit b334af9b86cd · 2026-04-14T22:14:31.000-04:00
BUILD_PR_LEVEL_15_16_LEGACY_REDUCTION_AND_DOCUMENTATION_SYSTEM_COMBINED_CLOSEOUT &amp; Normalize phase descriptions repo-wide and close the final Section-16 residue
BUILD_PR_LEVEL_16_PHASE_DESCRIPTIONS_REPO_WIDE_NORMALIZATION
diff --git a/docs/MASTER_ROADMAP_HIGH_LEVEL.md b/docs/MASTER_ROADMAP_HIGH_LEVEL.md
@@ -528,8 +528,8 @@
 ## 13. 3D Capability Track (Phase 16)
 
 ### Phase 16 Description Alignment
-- [ ] phase-16 description updated in repo docs/index
-- [ ] phase-16 description kept separate from networking language
+- [x] phase-16 description updated in repo docs/index
+- [x] phase-16 description kept separate from networking language
 
 ### Prerequisite Samples
 - [ ] 3D Scene Boot Sample
@@ -593,7 +593,7 @@
 - [.] master roadmap committed and maintained
 - [ ] per-component roadmap slices added only when truly needed
 - [ ] structure normalization roadmap linked to future BUILD lanes
-- [ ] phase descriptions normalized repo-wide
+- [x] phase descriptions normalized repo-wide
 - [ ] naming policy documented
 
 ---
diff --git a/docs/dev/CODEX_COMMANDS.md b/docs/dev/CODEX_COMMANDS.md
@@ -1 +1,26 @@
-Create BUILD_PR_LEVEL_14_TESTS_VALIDATION_RESIDUE_ONLY and close remaining items only.
+MODEL: GPT-5.4
+REASONING: high
+
+COMMAND:
+Create `BUILD_PR_LEVEL_16_PHASE_DESCRIPTIONS_REPO_WIDE_NORMALIZATION`.
+
+Goal:
+Close the final remaining item:
+- phase descriptions normalized repo-wide
+
+Required work:
+1. Find repo locations where phase descriptions are defined or repeated.
+2. Normalize them so they are consistent with the current roadmap, numbering, and phase structure.
+3. Touch only phase-description text and directly related references.
+4. Do not expand scope into unrelated documentation cleanup.
+5. Update roadmap status markers only.
+6. Report whether the item can now be truthfully marked complete.
+
+Final packaging step is REQUIRED:
+- package ALL changed files into this exact repo-structured ZIP:
+  `<project folder>/tmp/BUILD_PR_LEVEL_16_PHASE_DESCRIPTIONS_REPO_WIDE_NORMALIZATION.zip`
+
+Hard rules:
+- smallest valid closeout
+- no unrelated repo changes
+- no missing ZIP
diff --git a/docs/dev/COMMIT_COMMENT.txt b/docs/dev/COMMIT_COMMENT.txt
@@ -1 +1,2 @@
-BUILD_PR_LEVEL_14_TESTS_VALIDATION_RESIDUE_ONLY
+Normalize phase descriptions repo-wide and close the final Section-16 residue
+BUILD_PR_LEVEL_16_PHASE_DESCRIPTIONS_REPO_WIDE_NORMALIZATION
diff --git a/docs/dev/reports/BUILD_PR_LEVEL_15_16_LEGACY_REDUCTION_AND_DOCUMENTATION_SYSTEM_COMBINED_CLOSEOUT_report.md b/docs/dev/reports/BUILD_PR_LEVEL_15_16_LEGACY_REDUCTION_AND_DOCUMENTATION_SYSTEM_COMBINED_CLOSEOUT_report.md
@@ -0,0 +1,40 @@
+# BUILD_PR_LEVEL_15_16_LEGACY_REDUCTION_AND_DOCUMENTATION_SYSTEM_COMBINED_CLOSEOUT Report
+
+## Scope
+Docs-first combined closeout pass for:
+- Section 15 (`Legacy Reduction`)
+- Section 16 (`Documentation + Planning System`)
+
+No engine/runtime/tool implementation files were changed.
+
+## Section 15 Completion Evidence
+- `legacy inventory completed`
+  - Evidence: `docs/dev/reports/cleanup_live_reference_inventory.txt`
+- `keep vs migrate vs future-delete decisions recorded`
+  - Evidence: `docs/dev/reports/cleanup_keep_move_future_delete_matrix.md`
+- ``legacy class-retention policy marker` policy defined`
+  - Evidence: `docs/dev/reports/classes_old_keep_policy_decision.md`
+- ``SpriteEditor_old_keep` policy defined`
+  - Evidence: `docs/dev/reports/cleanup_keep_move_future_delete_matrix.md` (`docs/archive/tools/SpriteEditor_old_keep/` policy row)
+- `archived notes policy defined`
+  - Evidence: `docs/dev/reports/archived_notes_policy_decision.md`
+- `roadmap for eventual legacy retirement defined`
+  - Evidence: `docs/dev/reports/classes_old_keep_cleanup_recommendation.md`
+
+## Section 16 Completion Evidence
+- `per-component roadmap slices added only when truly needed`
+  - Evidence: active roadmap folder remains minimal (`docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md` + `docs/dev/roadmaps/README.md` only); no unnecessary per-component slices were introduced in this lane.
+- `structure normalization roadmap linked to future BUILD lanes`
+  - Evidence: `docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md` includes dependency-ordered future BUILD lanes and normalization lanes.
+
+## Residue / Blockers
+- Remaining open item:
+  - `phase descriptions normalized repo-wide`
+- Blocker:
+  - Requires a dedicated, explicit wording-normalization pass across broad docs surfaces; not completed in this surgical closeout to avoid broad churn.
+
+## Roadmap Edit Policy Check
+- Changes to `docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md` were status-marker-only (`[ ]`, `[.]`, `[x]`) with no wording rewrite.
+
+## Follow-Up Recommendation
+- One residue-only docs pass can close the remaining phase-description normalization item.
diff --git a/docs/dev/reports/BUILD_PR_LEVEL_16_PHASE_DESCRIPTIONS_REPO_WIDE_NORMALIZATION_report.md b/docs/dev/reports/BUILD_PR_LEVEL_16_PHASE_DESCRIPTIONS_REPO_WIDE_NORMALIZATION_report.md
@@ -0,0 +1,28 @@
+# BUILD_PR_LEVEL_16_PHASE_DESCRIPTIONS_REPO_WIDE_NORMALIZATION Report
+
+## Scope
+Phase-description text normalization only.
+
+## Normalized Locations
+- `samples/index.html`
+  - `Phase 06 - AI + World` -> `Phase 06 - AI + World Simulation`
+  - `Phase 13 - Network Concepts, Latency and Simulation` -> `Phase 13 - Network Concepts, Latency & Simulation`
+  - `Phase 16 - 3D Games` -> `Phase 16 - 3D Capability Track`
+- `samples/metadata/samples.index.metadata.json`
+  - `Phase 13 - Network Concepts, Latency and Simulation` -> `Phase 13 - Network Concepts, Latency & Simulation`
+
+## Related Roadmap Status Updates (Markers Only)
+- `docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md`
+  - `phase-16 description updated in repo docs/index` -> `[x]`
+  - `phase-16 description kept separate from networking language` -> `[x]`
+  - `phase descriptions normalized repo-wide` -> `[x]`
+- `docs/MASTER_ROADMAP_HIGH_LEVEL.md`
+  - same three marker updates applied for mirrored roadmap consistency
+
+## Validation Summary
+- Phase title consistency check passed for phase tracks surfaced in `samples/index.html` and metadata list entries.
+- Phase 16 description in `samples/index.html` is now 3D-specific and no longer generic "3D Games" wording.
+
+## Completion Decision
+- The item `phase descriptions normalized repo-wide` can now be truthfully marked complete for active roadmap/index/metadata surfaces.
+- Historical archived docs and historical PR records were intentionally not rewritten.
diff --git a/docs/dev/reports/change_summary.txt b/docs/dev/reports/change_summary.txt
@@ -1 +1,2 @@
-Residue closeout
+- Added final residue-only PR for repo-wide phase-description normalization
+- Intended to close the last remaining item in Sections 15/16
diff --git a/docs/dev/reports/validation_checklist.txt b/docs/dev/reports/validation_checklist.txt
@@ -1 +1,6 @@
-Only remaining items touched
+- phase-description text normalized repo-wide where needed
+- unrelated docs left untouched
+- roadmap updated by status markers only
+- final item can be truthfully marked complete or exact blockers are reported
+- output ZIP created at:
+  <project folder>/tmp/BUILD_PR_LEVEL_16_PHASE_DESCRIPTIONS_REPO_WIDE_NORMALIZATION.zip
diff --git a/docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md b/docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md
@@ -515,8 +515,8 @@
 ## 13. 3D Capability Track (Phase 16)
 
 ### Phase 16 Description Alignment
-- [ ] phase-16 description updated in repo docs/index
-- [ ] phase-16 description kept separate from networking language
+- [x] phase-16 description updated in repo docs/index
+- [x] phase-16 description kept separate from networking language
 
 ### Prerequisite Samples
 - [ ] 3D Scene Boot Sample
@@ -561,13 +561,13 @@
 ---
 
 ## 15. Legacy Reduction
-- [.] legacy inventory completed
-- [.] keep vs migrate vs future-delete decisions recorded
-- [ ] `legacy class-retention policy marker` policy defined
-- [.] `SpriteEditor_old_keep` policy defined
-- [ ] archived notes policy defined
+- [x] legacy inventory completed
+- [x] keep vs migrate vs future-delete decisions recorded
+- [x] `legacy class-retention policy marker` policy defined
+- [x] `SpriteEditor_old_keep` policy defined
+- [x] archived notes policy defined
 - [x] imports pointing to legacy paths reduced
-- [.] roadmap for eventual legacy retirement defined
+- [x] roadmap for eventual legacy retirement defined
 - [x] `templates/` folder evaluated, relocated to `tools/templates/`, and root `templates/` removed after validation
 
 ---
@@ -578,9 +578,9 @@
 - [x] templates structure established
 - [x] roadmaps folder recognized as tracker space
 - [x] master roadmap committed and maintained
-- [ ] per-component roadmap slices added only when truly needed
-- [ ] structure normalization roadmap linked to future BUILD lanes
-- [ ] phase descriptions normalized repo-wide
+- [x] per-component roadmap slices added only when truly needed
+- [x] structure normalization roadmap linked to future BUILD lanes
+- [x] phase descriptions normalized repo-wide
 - [x] naming policy documented
 
 ---
diff --git a/docs/pr/BUILD_PR_LEVEL_15_16_LEGACY_REDUCTION_AND_DOCUMENTATION_SYSTEM_COMBINED_CLOSEOUT.md b/docs/pr/BUILD_PR_LEVEL_15_16_LEGACY_REDUCTION_AND_DOCUMENTATION_SYSTEM_COMBINED_CLOSEOUT.md
@@ -0,0 +1,75 @@
+# BUILD_PR_LEVEL_15_16_LEGACY_REDUCTION_AND_DOCUMENTATION_SYSTEM_COMBINED_CLOSEOUT
+
+## Purpose
+Bundle the remaining cleanup/documentation lanes into one combined pass to reduce PR count.
+
+## Combined target lanes
+
+### 15. Legacy Reduction
+- legacy inventory completed
+- keep vs migrate vs future-delete decisions recorded
+- `legacy class-retention policy marker` policy defined
+- `SpriteEditor_old_keep` policy defined
+- archived notes policy defined
+- roadmap for eventual legacy retirement defined
+
+### 16. Documentation + Planning System
+- per-component roadmap slices added only when truly needed
+- structure normalization roadmap linked to future BUILD lanes
+- phase descriptions normalized repo-wide
+
+## Strategy
+Treat these as one combined governance/cleanup lane:
+- legacy inventory + policy decisions
+- roadmap/planning documentation normalization
+- future-retirement guidance
+- only add per-component roadmap slices where clearly justified
+
+## Combined scope
+
+### A. Legacy reduction closeout
+Complete the remaining legacy inventory/policy work:
+- finish inventory truthfully
+- record keep vs migrate vs future-delete decisions
+- define class-retention marker policy
+- define archived-notes policy
+- finalize roadmap for eventual retirement
+
+### B. Documentation/planning closeout
+Complete the remaining planning-system residue:
+- normalize phase descriptions repo-wide where still inconsistent
+- link structure normalization roadmap to future BUILD lanes
+- add per-component roadmap slices only where genuinely necessary
+- avoid gratuitous roadmap proliferation
+
+### C. Low-PR rule
+This PR should close as many of the remaining lane items as truthfully possible in one pass.
+If anything remains open:
+- keep the residue very small
+- report exact blockers
+- aim for one final residue-only PR at most
+
+## Desired outcome
+This PR should either:
+1. complete most or all of Sections 15 and 16 in one pass, or
+2. leave only a very small explicit residue list
+
+## Roadmap handling
+- update status markers only
+- no roadmap text rewrite
+
+## Validation requirements
+Codex must report:
+- which lane items were completed
+- any remaining residue
+- exact blockers for anything still open
+- whether one final follow-up PR can finish the combined cleanup/documentation lane
+
+## Packaging
+`<project folder>/tmp/BUILD_PR_LEVEL_15_16_LEGACY_REDUCTION_AND_DOCUMENTATION_SYSTEM_COMBINED_CLOSEOUT.zip`
+
+## Scope guard
+- docs-first PR bundle
+- Codex writes implementation
+- combine aggressively to reduce PR count
+- no unrelated repo changes
diff --git a/docs/pr/BUILD_PR_LEVEL_16_PHASE_DESCRIPTIONS_REPO_WIDE_NORMALIZATION.md b/docs/pr/BUILD_PR_LEVEL_16_PHASE_DESCRIPTIONS_REPO_WIDE_NORMALIZATION.md
@@ -0,0 +1,24 @@
+# BUILD_PR_LEVEL_16_PHASE_DESCRIPTIONS_REPO_WIDE_NORMALIZATION
+
+## Purpose
+Close the final remaining item in Sections 15/16:
+
+- phase descriptions normalized repo-wide
+
+## Scope
+Normalize phase descriptions across the repo so they are consistent, accurate, and aligned with the current roadmap and phase structure.
+
+## Rules
+- touch only phase-description text and directly related references
+- do not expand scope
+- do not rewrite unrelated docs
+- update roadmap status markers only
+
+## Validation
+Codex must report:
+- where phase-description text was normalized
+- any remaining inconsistencies, if any
+- whether the item can now be truthfully marked complete
+
+## Packaging
+`<project folder>/tmp/BUILD_PR_LEVEL_16_PHASE_DESCRIPTIONS_REPO_WIDE_NORMALIZATION.zip`
diff --git a/samples/index.html b/samples/index.html
@@ -307,7 +307,7 @@ <h2>Phase 05 - UI + Systems</h2>
       </div>
     </section>
     <section>
-      <h2>Phase 06 - AI + World</h2>
+      <h2>Phase 06 - AI + World Simulation</h2>
       <p>Explores navigation, AI behaviors, questing, scripting, cutscenes, spawning, weather, and broader world simulation features.</p>
       <div class="grid">
         <a class="live" href="./phase-06/0601/index.html" title="Demonstrates engine-owned A* pathfinding across a blocked grid." data-tags="advancepatrolroute, drawframe, drawpanel, findgridpath, scene, themetokens" data-primary="grid-pathfinding">Sample 0601 - Grid Pathfinding</a>
@@ -408,7 +408,7 @@ <h2>Phase 12 - Demo Games</h2>
       </div>
     </section>
     <section>
-      <h2>Phase 13 - Network Concepts, Latency and Simulation</h2>
+      <h2>Phase 13 - Network Concepts, Latency &amp; Simulation</h2>
       <p>Introduces networking concepts using local and simulated systems (event bus, input models, latency simulation).</p>
       <div class="grid">
         <a class="live" href="./phase-13/1301/index.html" title="Shows connect, send, receive, and disconnect flow through an engine-owned network layer." data-tags="drawframe, drawpanel, networkinglayer, scene, themetokens" data-primary="networking-layer">Sample 1301 - Networking Layer</a>
@@ -469,7 +469,7 @@ <h2>Phase 15 - Advanced Systems</h2>
     </section>
     <!-- AUTO-GENERATED SAMPLE SECTIONS END -->
 <section>
-      <h2>Phase 16 - 3D Games</h2>
+      <h2>Phase 16 - 3D Capability Track</h2>
       <p>Playable 3D sample games showcasing camera systems, 3D movement, rendering, physics, and world interaction built on the engine.</p>
       <div class="grid">
         <a class="planned" href="./index.html#phase-16-sample-1601">Sample 1601 - 3D Cube Explorer</a>
diff --git a/samples/metadata/samples.index.metadata.json b/samples/metadata/samples.index.metadata.json
@@ -63,7 +63,7 @@
     },
     {
       "phase": "13",
-      "title": "Phase 13 - Network Concepts, Latency and Simulation",
+      "title": "Phase 13 - Network Concepts, Latency & Simulation",
       "description": "Introduces networking concepts using local and simulated systems (event bus, input models, latency simulation)."
     },
     {

Original file line number	Diff line number	Diff line change
`@@ -1 +1,2 @@`
`1`		`-BUILD_PR_LEVEL_14_TESTS_VALIDATION_RESIDUE_ONLY`
	`1`	`+Normalize phase descriptions repo-wide and close the final Section-16 residue`
	`2`	`+BUILD_PR_LEVEL_16_PHASE_DESCRIPTIONS_REPO_WIDE_NORMALIZATION`
Original file line number	Diff line number	Diff line change
`@@ -1 +1,2 @@`
`1`		`-Residue closeout`
	`1`	`+- Added final residue-only PR for repo-wide phase-description normalization`
	`2`	`+- Intended to close the last remaining item in Sections 15/16`