BUILD_PR_REPO_CLEANUP_AND_ROADMAP_UPDATE: apply conservative roadmap bracket-state updates and generate reference-safe cleanup evidence reports without deleting, moving, renaming, or touching templates/.

Author: DavidQ

docs/dev/CODEX_COMMANDS.md

@@ -1,16 +1,27 @@
 MODEL: GPT-5.4
 REASONING: high
 
-COMMAND:
-Create PLAN_PR_REPO_CLEANUP_AND_ROADMAP_UPDATE as a docs-only package.
+PRIMARY COMMAND:
+Create BUILD_PR_REPO_CLEANUP_AND_ROADMAP_UPDATE exactly as specified in `docs/pr/BUILD_PR_REPO_CLEANUP_AND_ROADMAP_UPDATE.md`.
 
-Scope:
-- commit updated master roadmap with conservative status rebaseline
-- add tracked cleanup item for templates/ with explicit deferment
-- document cleanup targets and sequencing
-- do not delete or move templates/
-- do not implement cleanup in this PR
-- keep this bundle docs-only
+Required actions:
+1. Update `docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md` using bracket-only state changes where exact roadmap text matches planned deltas.
+2. Create cleanup evidence reports:
+   - `docs/dev/reports/cleanup_live_reference_inventory.txt`
+   - `docs/dev/reports/cleanup_keep_move_future_delete_matrix.md`
+   - `docs/dev/reports/BUILD_PR_REPO_CLEANUP_AND_ROADMAP_UPDATE_report.md`
+   - `docs/dev/reports/validation_checklist.txt`
+3. Optionally refresh only if needed for accuracy:
+   - `docs/dev/reports/repo_cleanup_targets.txt`
+   - `docs/dev/reports/roadmap_status_delta.txt`
+4. Do not delete, move, rename, or modify `templates/`.
+5. Do not touch `docs/dev/start_of_day/chatGPT/` or `docs/dev/start_of_day/codex/`.
+6. Package the resulting repo-structured ZIP to:
+   - `<project folder>/tmp/BUILD_PR_REPO_CLEANUP_AND_ROADMAP_UPDATE.zip`
 
-Output:
-<project folder>/tmp/PLAN_PR_REPO_CLEANUP_AND_ROADMAP_UPDATE.zip
+Validation requirements:
+- prove roadmap edits were bracket-only
+- prove no protected start_of_day files changed
+- prove no delete/move/rename happened
+- prove `templates/` remained untouched
+- record unmatched roadmap deltas in the BUILD report instead of rewriting wording

docs/dev/COMMIT_COMMENT.txt

@@ -1 +1 @@
-docs: rebaseline roadmap and stage later repo cleanup targets including templates/ deferment
+BUILD_PR_REPO_CLEANUP_AND_ROADMAP_UPDATE: apply conservative roadmap bracket-state updates and generate reference-safe cleanup evidence reports without deleting, moving, renaming, or touching templates/.

docs/dev/NEXT_COMMAND.txt

@@ -1 +1,9 @@
-After Codex completes, produce APPLY_PR_SAMPLES_INDEX_FIXES_AND_TARGETED_PREVIEW_RETRY with acceptance docs only. Verify: samples/index.html header/dropdown text changes, Sample 1303 local-only fix with no engine edits, retry-only preview SVG replacements for the approved list, and explicit confirmation that 1316/1317/1318 were untouched.
+After Codex completes and validation is clean, the next recommended lane is:
+APPLY_PR_REPO_CLEANUP_AND_ROADMAP_UPDATE
+
+Only do that if this BUILD reports:
+- bracket-only roadmap changes
+- no protected directory edits
+- no deletion/move/rename
+- templates/ untouched
+- cleanup evidence reports complete

docs/dev/reports/BUILD_PR_REPO_CLEANUP_AND_ROADMAP_UPDATE_report.md

@@ -0,0 +1,57 @@
+# BUILD_PR_REPO_CLEANUP_AND_ROADMAP_UPDATE Report
+
+## Bundle Type
+- Execution-ready BUILD docs (non-destructive cleanup-evidence lane).
+
+## Exact Files Changed
+- `docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md`
+- `docs/dev/reports/validation_checklist.txt`
+
+## Exact Files Created
+- `docs/dev/reports/cleanup_live_reference_inventory.txt`
+- `docs/dev/reports/cleanup_keep_move_future_delete_matrix.md`
+- `docs/dev/reports/BUILD_PR_REPO_CLEANUP_AND_ROADMAP_UPDATE_report.md`
+
+## Optional Alignment Files
+- `docs/dev/reports/repo_cleanup_targets.txt`: unchanged (already aligned)
+- `docs/dev/reports/roadmap_status_delta.txt`: unchanged (already aligned)
+
+## Roadmap Bracket Changes Applied
+Applied bracket-only state changes where exact text matched planned deltas:
+- `- [.] smoke validation aligned to samples/tools/games`
+- `+ [x] smoke validation aligned to samples/tools/games`
+
+Other planned in-progress deltas were already in `[.]` state and required no additional bracket edits.
+
+## Unapplied Planned Delta (No Wording Rewrite Per Rule)
+The following planned deltas were not force-applied because exact text match was not clean without rewriting wording:
+- `SpriteEditor_old_keep policy defined`
+  - Roadmap wording currently uses backticks: `` `SpriteEditor_old_keep` policy defined ``
+- `templates/ folder evaluated for keep vs move vs future-delete during cleanup phase`
+  - Roadmap wording currently includes backticks and an explicit deferment suffix.
+
+Per BUILD constraints, wording was left intact and no forced rewrite was performed.
+
+## Cleanup Inventory Findings Summary
+- `templates/`: exists; live references in active tooling/tests/docs; classification requires manual review in later cleanup lane.
+- `tools/SpriteEditor_old_keep/`: exists; live references in registry/spec/report docs; remains keep-only legacy candidate for later policy PR.
+- `classes_old_keep`: path does not exist; docs-only planning references present.
+- `docs/archive/` archived notes area: exists and actively referenced in documentation structure/policy docs.
+- Legacy import path scan (`/engine/`, `../engine/`, `./engine/` in tools/src/games/samples): no direct matches.
+- Legacy-retirement candidates are present and tracked in roadmap + cleanup planning docs.
+
+## Non-Destructive Assertions
+- No deletion, move, or rename occurred in this BUILD.
+- `templates/` was not modified.
+- Protected directories were untouched:
+  - `docs/dev/start_of_day/chatGPT/`
+  - `docs/dev/start_of_day/codex/`
+
+## Validation Results
+- Roadmap wording preserved: PASS
+- Roadmap changes bracket-only: PASS
+- Protected start_of_day directories untouched: PASS
+- No delete/move/rename executed: PASS
+- `templates/` untouched: PASS
+- Evidence reports created: PASS
+- No unrelated repo files changed (bundle-scoped): PASS

docs/dev/reports/cleanup_keep_move_future_delete_matrix.md

@@ -0,0 +1,15 @@
+# Cleanup Keep/Move/Future-Delete Matrix
+
+| Target | Exists? | Live References? | Proposed Classification | Evidence Summary | Action Now | Recommended Future PR Scope |
+| --- | --- | --- | --- | --- | --- | --- |
+| `templates/` | yes | yes | `needs-manual-review` | Active refs in `tools/shared/vectorNativeTemplate.js`, `tools/shared/vectorTemplateSampleGame.js`, `tests/tools/VectorNativeTemplate.test.mjs`, and docs/planning surfaces. | none in this PR | Dedicated cleanup/build lane to classify keep vs migrate-later with dependency verification. |
+| `tools/SpriteEditor_old_keep/` policy | yes | yes | `keep` | Legacy-hidden runtime registry entry in `tools/toolRegistry.js`; referenced in specs, roadmap, and reports. | none in this PR | Separate legacy policy PR to define exact retirement criteria and transition gates. |
+| `classes_old_keep` policy target | no | yes (docs-only) | `needs-manual-review` | Path not present on disk; only planning references found in roadmap/targets/build spec docs. | none in this PR | Clarify whether this is a historical placeholder, rename candidate, or retired concept before any cleanup execution. |
+| `docs/archive/` archived-notes policy | yes | yes | `keep` | Archive destination is actively documented across docs structure/readme/paths files; policy item still planned in roadmap. | none in this PR | Policy-definition PR to formalize retention + move criteria for archived notes. |
+| Legacy path imports (`/engine/`, `../engine/`, `./engine/`) | pattern check | no (active code) | `future-delete-candidate` | No matches for inspected old-engine import patterns in tools/src/games/samples. | none in this PR | Add guard/reporting checks in future cleanup PR to prevent regressions and retire stale legacy-import guidance. |
+| Eventual legacy-retirement candidates list | yes | yes (planning) | `migrate-later` | Explicitly tracked in roadmap + cleanup target docs and referenced by this BUILD spec. | none in this PR | Convert candidates into exact, dependency-ordered cleanup BUILDs after reference-safe verification. |
+
+## Notes
+- This matrix is decision-prep only.
+- No deletion, move, rename, or migration is executed in this PR.
+- `templates/` remains explicitly deferred.

docs/dev/reports/cleanup_live_reference_inventory.txt

@@ -0,0 +1,92 @@
+BUILD_PR_REPO_CLEANUP_AND_ROADMAP_UPDATE
+Cleanup Live Reference Inventory
+Generated: 2026-04-12
+
+Target 1: templates/
+- Exact path: templates/
+- Exists: yes
+- Inbound references:
+  - import/file refs (active code/tests):
+    - tools/shared/vectorNativeTemplate.js
+    - tools/shared/vectorTemplateSampleGame.js
+    - tests/tools/VectorNativeTemplate.test.mjs
+    - games/vector-arcade-sample/README.md
+  - docs refs (active docs):
+    - docs/pr/BUILD_PR_REPO_CLEANUP_AND_ROADMAP_UPDATE.md
+    - docs/dev/reports/repo_cleanup_targets.txt
+    - docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md
+- Reference count snapshot (non-archive scan): 63 matches
+- Assessment: live-reference
+- Notes: path is active for template-backed tooling and tests; cleanup decision must be deferred and reference-safe.
+
+Target 2: SpriteEditor_old_keep policy locations/references
+- Exact path: tools/SpriteEditor_old_keep/
+- Exists: yes
+- Inbound references:
+  - runtime/config refs:
+    - tools/toolRegistry.js (legacy hidden entry)
+    - docs/dev/reports/launch_smoke_report.md (tool launch coverage)
+  - docs refs:
+    - docs/specs/project_manifest_contract.md
+    - docs/specs/asset_usage_contract.md
+    - docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md
+    - docs/dev/reports/repo_cleanup_targets.txt
+- Reference count snapshot (non-archive scan): 44 matches
+- Assessment: live-reference
+- Notes: preserved-legacy lane is still explicitly tracked and surfaced in validation/tooling metadata.
+
+Target 3: classes_old_keep policy locations/references
+- Exact path: classes_old_keep/
+- Exists: no
+- Inbound references:
+  - docs planning refs:
+    - docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md
+    - docs/dev/reports/repo_cleanup_targets.txt
+    - docs/pr/BUILD_PR_REPO_CLEANUP_AND_ROADMAP_UPDATE.md
+- Reference count snapshot: 3 matches
+- Assessment: docs-reference-only
+- Notes: no runtime path currently exists; remains a planning placeholder requiring manual review before any action.
+
+Target 4: archived notes policy locations/references
+- Exact path: docs/archive/
+- Exists: yes
+- Inbound references:
+  - docs policy/location refs:
+    - docs/README.md
+    - docs/repo-directory-structure.md
+    - docs/dev/README.md
+    - docs/dev/paths.md
+    - docs/review-checklist.md
+    - docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md (policy item still planned)
+- Reference count snapshot (non-archive docs scan): 34 matches
+- Assessment: live-reference
+- Notes: archive location is active and documented, but explicit legacy 'archived notes policy' checklist item remains incomplete.
+
+Target 5: imports/references pointing to legacy paths
+- Exact paths/patterns inspected:
+  - from '/engine/'
+  - from '../engine/'
+  - from './engine/'
+  - require('/engine/')
+  - require('../engine/')
+  - require('./engine/')
+  - imports from SpriteEditor_old_keep/classes_old_keep paths
+- Exists: pattern-based check
+- Inbound references:
+  - old engine import patterns above: no matches in tools/src/games/samples
+  - legacy path docs references exist for tools/SpriteEditor_old_keep and templates/ (planning + archival context)
+- Assessment: mixed (code imports: zero-reference; docs/file refs: live-reference)
+- Notes: no direct legacy-engine import usage was found in active code for inspected patterns; legacy references persist in docs/planning surfaces.
+
+Target 6: eventual legacy-retirement candidates already called out in cleanup planning
+- Exact planning paths:
+  - docs/dev/reports/repo_cleanup_targets.txt
+  - docs/dev/reports/roadmap_status_delta.txt
+  - docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md
+  - docs/pr/BUILD_PR_REPO_CLEANUP_AND_ROADMAP_UPDATE.md
+- Exists: yes
+- Inbound references:
+  - roadmap item: "roadmap for eventual legacy retirement defined"
+  - cleanup targets list: "eventual legacy retirement roadmap"
+- Assessment: live-reference (planning)
+- Notes: candidate list exists and is referenced; execution remains deferred to dedicated cleanup PRs.

docs/dev/reports/validation_checklist.txt

@@ -1,12 +1,32 @@
-SESSION VALIDATION CHECK
-
-- Bundle type: BUILD
-- Single PR purpose only: YES
-- BUILD explicit and executable: YES
-- Exact target files/scope named: YES
-- Non-goals named: YES
-- Validation steps named: YES
-- Retry narrowed from prior attempt: YES
-- Protected start_of_day directories untouched: YES
-- No fake code-completion claims: YES
-- Repo-structured ZIP prepared: YES
+BUILD_PR_REPO_CLEANUP_AND_ROADMAP_UPDATE
+Validation Checklist
+Generated: 2026-04-12
+
+[PASS] roadmap wording preserved
+- Evidence: roadmap diff shows only one checkbox marker transition line and no non-bracket content edits.
+
+[PASS] roadmap changes bracket-only
+- Evidence:
+  - changed: "- [.] smoke validation aligned to samples/tools/games"
+  - to:      "- [x] smoke validation aligned to samples/tools/games"
+  - non-bracket changed lines: none
+
+[PASS] no protected start_of_day directories touched
+- Evidence: `git status --short -- docs/dev/start_of_day/chatGPT docs/dev/start_of_day/codex` returned no entries.
+
+[PASS] no deletion/move/rename executed
+- Evidence: `git diff --name-status -- <PR target files>` returned only `M` statuses for tracked files and no `D`/`R` entries.
+
+[PASS] templates/ untouched
+- Evidence: `git status --short -- templates` returned no entries.
+
+[PASS] evidence reports created
+- Evidence:
+  - docs/dev/reports/cleanup_live_reference_inventory.txt
+  - docs/dev/reports/cleanup_keep_move_future_delete_matrix.md
+  - docs/dev/reports/BUILD_PR_REPO_CLEANUP_AND_ROADMAP_UPDATE_report.md
+  - docs/dev/reports/validation_checklist.txt
+
+[PASS] no unrelated repo files changed (bundle-scoped)
+- Evidence: this BUILD bundle modifies/creates only roadmap + cleanup evidence report files listed in the BUILD report.
+- Note: unrelated pre-existing workspace changes outside this bundle were preserved and not altered by this BUILD.

docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md

@@ -549,7 +549,7 @@
 - [.] `tests/` structure normalized
 - [.] unit coverage aligned to engine/shared/games
 - [.] integration coverage aligned to state/replay/rendering/tools
-- [.] smoke validation aligned to samples/tools/games
+- [x] smoke validation aligned to samples/tools/games
 - [ ] fixtures/helpers organization normalized
 - [.] move/refactor validation strategy documented
 - [ ] post-PR acceptance criteria consistently enforced