BUILD_PR_TEMPLATES_POLICY_CLASSIFICATION: add templates usage inventory, conservative policy baseline, and future cleanup validation guards without moving or rewriting templates.

DavidQ · DavidQ · commit 9a1c7bc9dda3 · 2026-04-12T15:44:28.000-04:00
diff --git a/docs/dev/CODEX_COMMANDS.md b/docs/dev/CODEX_COMMANDS.md
@@ -1,27 +1,4 @@
 MODEL: GPT-5.4
 REASONING: high
-
-PRIMARY COMMAND:
-Create BUILD_PR_REPO_CLEANUP_AND_ROADMAP_UPDATE exactly as specified in `docs/pr/BUILD_PR_REPO_CLEANUP_AND_ROADMAP_UPDATE.md`.
-
-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`
-
-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
+COMMAND:
+Create BUILD_PR_TEMPLATES_POLICY_CLASSIFICATION as a single execution-ready, testable BUILD lane. Work only within the exact scope in `docs/pr/BUILD_PR_TEMPLATES_POLICY_CLASSIFICATION.md`. Produce the required reports, keep the lane non-destructive, do not move/rename/delete `templates/`, do not rewrite runtime imports, do not touch protected start_of_day directories, and package the repo-structured ZIP to `<project folder>/tmp/BUILD_PR_TEMPLATES_POLICY_CLASSIFICATION.zip`.
diff --git a/docs/dev/COMMIT_COMMENT.txt b/docs/dev/COMMIT_COMMENT.txt
@@ -1 +1 @@
-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/.
+BUILD_PR_TEMPLATES_POLICY_CLASSIFICATION: add templates usage inventory, conservative policy baseline, and future cleanup validation guards without moving or rewriting templates.
diff --git a/docs/dev/NEXT_COMMAND.txt b/docs/dev/NEXT_COMMAND.txt
@@ -1,9 +1 @@
-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
+After this BUILD completes, create the next exact-scope cleanup BUILD from the resulting templates policy: either a templates-retain-and-guard lane or a tightly scoped templates-migration lane, whichever the evidence supports.
diff --git a/docs/dev/reports/BUILD_PR_TEMPLATES_POLICY_CLASSIFICATION_report.md b/docs/dev/reports/BUILD_PR_TEMPLATES_POLICY_CLASSIFICATION_report.md
@@ -0,0 +1,72 @@
+﻿# BUILD_PR_TEMPLATES_POLICY_CLASSIFICATION Report
+
+Generated: 2026-04-12
+Bundle type: execution-ready BUILD docs (non-destructive templates policy lane)
+
+## Exact Files Created
+- `docs/dev/reports/templates_live_usage_inventory.md`
+- `docs/dev/reports/templates_policy_decision.md`
+- `docs/dev/reports/templates_validation_guard.md`
+- `docs/dev/reports/BUILD_PR_TEMPLATES_POLICY_CLASSIFICATION_report.md`
+
+## Exact Files Changed
+- `docs/dev/reports/validation_checklist.txt`
+- `docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md` (single bracket-only state change)
+
+## Template Inventory Findings (Evidence Summary)
+- `templates/` currently contains 17 files (starter-project-template + vector-native-arcade trees).
+- Active code/test/docs consumers were found for `templates/` path references.
+- Direct module import/require/export references to `templates/` were not found in `tools/`, `src/`, `games/`, `samples/`, `tests/`.
+- Runtime coupling remains path-string based, centered on:
+  - `tools/shared/vectorNativeTemplate.js`
+  - `tools/shared/vectorTemplateSampleGame.js`
+  - `tests/tools/VectorNativeTemplate.test.mjs`
+  - `games/vector-arcade-sample/README.md`
+
+## Chosen Policy Classification
+- Classification options considered: `keep-in-place-for-now`, `migrate-later`, `needs-manual-review`.
+- Chosen for this BUILD: `keep-in-place-for-now`.
+- Rationale: live runtime/test/docs path coupling makes move/delete unsafe without synchronized migration work.
+
+## Roadmap Bracket Changes Applied
+- Applied exactly one bracket-state update in `docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md`:
+  - `- [ ] templates/ folder evaluated for keep vs move vs future-delete ...`
+  - `+ [.] templates/ folder evaluated for keep vs move vs future-delete ...`
+- No wording rewrite and no item reordering.
+
+## Unapplied Planned Delta
+- None.
+- The targeted roadmap line existed as exact wording, so bracket-only update was applied directly.
+
+## Non-Destructive Statement
+- `templates/` was not moved, renamed, deleted, or modified in this BUILD.
+- No runtime import rewrites were performed in this BUILD.
+- Protected directories were untouched:
+  - `docs/dev/start_of_day/chatGPT/`
+  - `docs/dev/start_of_day/codex/`
+
+## Validation Results (Command-Backed)
+1. Search all `templates/` references and list consumer files:
+   - `rg -n "templates/" tools src games samples tests --glob "!**/node_modules/**"`
+   - Consumers found: `tools/shared/vectorNativeTemplate.js`, `tools/shared/vectorTemplateSampleGame.js`, `tests/tools/VectorNativeTemplate.test.mjs`, `games/vector-arcade-sample/README.md`.
+
+2. Confirm no move/rename/delete under `templates/`:
+   - `git diff --name-status -- templates`
+   - Result: no entries.
+
+3. Confirm protected start_of_day directories unchanged:
+   - `git status --short -- docs/dev/start_of_day/chatGPT docs/dev/start_of_day/codex`
+   - Result: no entries.
+
+4. If roadmap changed, verify bracket-only:
+   - `git diff --unified=0 -- docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md`
+   - Result: one checkbox state change only.
+   - Automated guard result: `BRACKET_ONLY_CHECK: PASS`.
+
+5. Confirm no delete/move/rename happened in working-tree diff:
+   - `git diff --name-status`
+   - Guard result: `DELETE_MOVE_RENAME_CHECK: PASS`.
+
+## Notes
+- This BUILD lane intentionally stays docs-only and policy/guard focused.
+- Runtime consumer migration is deferred to a future exact-scope migration lane.
diff --git a/docs/dev/reports/templates_live_usage_inventory.md b/docs/dev/reports/templates_live_usage_inventory.md
@@ -0,0 +1,77 @@
+# templates/ Live Usage Inventory
+
+Generated: 2026-04-12
+Scope: `templates/` only (non-archive evidence for active docs; code/tests from active runtime surfaces)
+
+## 1) Exact Files Under templates/
+Observed files:
+1. `templates/starter-project-template/README.md`
+2. `templates/starter-project-template/config/starter.project.json`
+3. `templates/vector-native-arcade/README.md`
+4. `templates/vector-native-arcade/assets/palettes/vector-native-primary.palette.json`
+5. `templates/vector-native-arcade/assets/parallax/template-backdrop.parallax.json`
+6. `templates/vector-native-arcade/assets/parallax/template-backdrop.svg`
+7. `templates/vector-native-arcade/assets/tilemaps/template-arena.tilemap.json`
+8. `templates/vector-native-arcade/assets/tilemaps/template-ui.tileset.json`
+9. `templates/vector-native-arcade/assets/vectors/template-hud.vector.json`
+10. `templates/vector-native-arcade/assets/vectors/template-obstacle-large.vector.json`
+11. `templates/vector-native-arcade/assets/vectors/template-obstacle-small.vector.json`
+12. `templates/vector-native-arcade/assets/vectors/template-player.vector.json`
+13. `templates/vector-native-arcade/assets/vectors/template-title.vector.json`
+14. `templates/vector-native-arcade/config/template.project.json`
+15. `templates/vector-native-arcade/docs/ROLLBACK_NOTES.md`
+16. `templates/vector-native-arcade/docs/STARTER_GUIDE.md`
+17. `templates/vector-native-arcade/runtime/bootstrap.runtime.json`
+
+## 2) Direct imports / requires
+Command pattern used:
+- `^\s*import .*templates/`
+- `^\s*.*require\(.*templates/`
+- `^\s*export .* from .*templates/`
+
+Result:
+- No direct JS import/require/export module references to `templates/` in `tools/`, `src/`, `games/`, `samples/`, `tests/`.
+
+Assessment:
+- Consumer coupling is path-string based, not module-import based.
+
+## 3) String Path References (Code + Tests + Runtime-Adjacent)
+
+| Consumer File | Evidence Shape | Consumer Type | Classification | Notes |
+| --- | --- | --- | --- | --- |
+| `tools/shared/vectorNativeTemplate.js` | Hard-coded `templates/vector-native-arcade/...` paths for asset/config/runtime/docs references | runtime | canonical | Primary active template contract surface; high coupling to exact folder structure. |
+| `tools/shared/vectorTemplateSampleGame.js` | String replace from `templates/vector-native-arcade/` -> `games/vector-arcade-sample/` | runtime | transitional | Explicit migration bridge assumption on exact prefix. |
+| `tests/tools/VectorNativeTemplate.test.mjs` | Assertions against `templatePath === "templates/vector-native-arcade/"` and report text | test-only | canonical | Tests lock the current template root and report formatting. |
+| `games/vector-arcade-sample/README.md` | Documentation string references source template path | docs-only (game doc) | transitional | Human-facing provenance reference to template origin. |
+
+## 4) Docs / Planning References (Non-Archive)
+
+Active docs with `templates/` references:
+- `docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md`
+- `docs/dev/reports/repo_cleanup_targets.txt`
+- `docs/dev/reports/roadmap_status_delta.txt`
+- `docs/pr/BUILD_PR_TEMPLATES_POLICY_CLASSIFICATION.md`
+- `docs/pr/BUILD_PR_REPO_CLEANUP_AND_ROADMAP_UPDATE.md`
+- `docs/pr/PLAN_PR_REPO_CLEANUP_AND_ROADMAP_UPDATE.md`
+- Additional active report/planning docs under `docs/dev/reports/` and `docs/pr/` that cite template cleanup constraints.
+
+Classification:
+- docs-only and planning-oriented; primarily transitional governance references.
+
+## 5) Coupling / Path Assumptions Blocking Safe Move
+
+Blocking assumptions identified:
+1. Exact hard-coded prefix `templates/vector-native-arcade/` in runtime helper surfaces (`vectorNativeTemplate.js`, `vectorTemplateSampleGame.js`).
+2. Template contract tests assert exact path strings, so directory relocation would fail tests without synchronized updates.
+3. Runtime bootstrap/config/docs path strings are part of generated/report output contracts from `vectorNativeTemplate.js`.
+4. Cleanup planning docs currently encode explicit deferment rules; moving now would violate active planning constraints.
+
+## 6) Legacy/Transitional/Cleanliness Assessment
+- `templates/` is not an orphaned legacy surface.
+- It has live runtime + test + docs references.
+- Current usage indicates **active canonical template source with transitional migration coupling**.
+
+## 7) Inventory Conclusion
+- `templates/` currently has live references and coupling that block safe move/delete in this lane.
+- Any future migration must update runtime helpers, tests, and synchronized docs/contracts in one controlled PR sequence.
+- No destructive action is warranted in this BUILD.
diff --git a/docs/dev/reports/templates_policy_decision.md b/docs/dev/reports/templates_policy_decision.md
@@ -0,0 +1,55 @@
+# templates/ Policy Decision
+
+Generated: 2026-04-12
+Scope: Policy classification for `templates/` only.
+
+## Current Classification Options
+- `keep-in-place-for-now`
+- `migrate-later`
+- `needs-manual-review`
+
+## Chosen Classification (This PR)
+- `keep-in-place-for-now`
+
+## Rationale (Evidence-Grounded)
+From `templates_live_usage_inventory.md`:
+- `templates/` has live code + test + docs references.
+- Runtime helpers (`tools/shared/vectorNativeTemplate.js`, `tools/shared/vectorTemplateSampleGame.js`) rely on exact path strings.
+- Tests (`tests/tools/VectorNativeTemplate.test.mjs`) assert exact template path values.
+- Active planning/docs currently enforce deferment and non-destructive cleanup sequencing.
+
+Given this coupling, move/delete/repath actions are unsafe without coordinated multi-surface updates.
+
+## Allowed Now
+- Document inventory and policy.
+- Add validation guards for future cleanup lanes.
+- Keep roadmap/docs tracking in sync without rewriting runtime/template consumers.
+
+## Forbidden Now
+- Move, rename, or delete `templates/` or any file under it.
+- Rewrite runtime imports/paths to remove `templates/` references.
+- Mix template migration with unrelated cleanup targets or feature work.
+
+## Exact Prerequisites For Future Migration/Removal Lane
+1. Full reference inventory refreshed and confirmed (code/tests/docs).
+2. Runtime helper path abstraction plan approved (remove hard-coded template-root coupling).
+3. Test suite updates prepared to align with new canonical template location.
+4. Docs/contracts synchronized in same PR (roadmap + cleanup targets + template guidance docs).
+5. Pre/post validation checklist executed (search + tests + smoke surfaces).
+6. Explicit rollback plan and path map included in the migration PR.
+
+## Reclassification Signals (When Policy Can Change)
+Policy may move from `keep-in-place-for-now` to `migrate-later` only when:
+- hard-coded runtime path assumptions are abstracted or isolated,
+- template path assertions in tests are intentionally updated with equivalent coverage,
+- docs/contracts are prepared for synchronized path changes,
+- migration can be executed as one exact-scope, test-backed lane.
+
+Policy may move to `future-delete-candidate` only when:
+- no live runtime/test/docs dependencies remain,
+- replacement source-of-truth exists and is validated,
+- delete decision is proven by zero-reference scans and acceptance checks.
+
+## Decision Summary
+- `templates/` remains intentionally retained in place for now.
+- This BUILD records policy and guards only; no structural repo change is executed.
diff --git a/docs/dev/reports/templates_validation_guard.md b/docs/dev/reports/templates_validation_guard.md
@@ -0,0 +1,82 @@
+# templates/ Validation Guard
+
+Generated: 2026-04-12
+Purpose: Define mandatory checks that must pass before any future PR can move/rename/delete `templates/`.
+
+## A) Reference Scan Commands (Pre + Post)
+Run from repo root.
+
+1. Code/tests template path usage:
+```powershell
+rg -n "templates/" tools src games samples tests
+```
+
+2. Active docs/planning usage (exclude archives):
+```powershell
+rg -n "templates/" docs --glob "!docs/archive/**"
+```
+
+3. Direct module import/require guard:
+```powershell
+rg -n "^\s*import .*templates/|^\s*.*require\(.*templates/|^\s*export .* from .*templates/" tools src games samples tests
+```
+
+4. Old/legacy path regression guard:
+```powershell
+rg -n -F "from '/engine/" tools src games samples
+rg -n -F "from '../engine/" tools src games samples
+rg -n -F "from './engine/" tools src games samples
+```
+
+## B) templates/ Structural Integrity Checks
+1. Confirm no accidental template edits in docs-only lanes:
+```powershell
+git status --short -- templates
+```
+
+2. Confirm no template move/rename/delete in PR scope:
+```powershell
+git diff --name-status -- templates
+```
+
+## C) Smoke Validation Surfaces (When Migration Is Attempted)
+Run both before and after migration:
+```powershell
+npm run test:launch-smoke -- --tools
+```
+
+Recommended follow-up smoke (if migration touches game/sample references):
+```powershell
+npm run test:launch-smoke -- --games --samples
+```
+
+## D) Test Surfaces To Re-run
+1. Template contract tests:
+```powershell
+node -e "import('./tests/tools/VectorNativeTemplate.test.mjs').then(m=>m.run())"
+node -e "import('./tests/tools/GameTemplates.test.mjs').then(m=>m.run())"
+```
+
+2. Any test suite asserting template path text/contract output must be updated and rerun in the same PR.
+
+## E) Docs/Contracts Requiring Synchronized Updates (If Path Changes)
+- `docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md`
+- `docs/dev/reports/repo_cleanup_targets.txt`
+- `docs/dev/reports/roadmap_status_delta.txt`
+- `docs/dev/reports/templates_live_usage_inventory.md`
+- `docs/dev/reports/templates_policy_decision.md`
+- `docs/dev/reports/validation_checklist.txt`
+- Any active `docs/pr/*` build/plan spec that references template path policy
+- Consumer docs such as `games/vector-arcade-sample/README.md` if provenance path changes
+
+## F) Blocking Failure Conditions
+Stop migration execution if any of the following occur:
+- unresolved `templates/` references remain without explicit path-map coverage;
+- runtime helper paths are rewritten without synchronized tests;
+- tests/smoke regress after path changes;
+- docs/contracts are out of sync with actual template location;
+- `templates/` was moved/deleted without validated rollback and evidence report;
+- unrelated cleanup targets are mixed into the same migration lane.
+
+## Guard Summary
+No future `templates/` cleanup lane should execute structural changes unless all reference scans, test/smoke checks, and doc-sync requirements pass as a single exact-scope bundle.
diff --git a/docs/dev/reports/validation_checklist.txt b/docs/dev/reports/validation_checklist.txt
@@ -1,32 +1,28 @@
-BUILD_PR_REPO_CLEANUP_AND_ROADMAP_UPDATE
+﻿BUILD_PR_TEMPLATES_POLICY_CLASSIFICATION
 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] protected start_of_day directories untouched
+Evidence: `git status --short -- docs/dev/start_of_day/chatGPT docs/dev/start_of_day/codex` -> no entries
 
-[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] `templates/` not moved/renamed/deleted
+Evidence: `git diff --name-status -- templates` -> no entries
 
-[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 runtime import rewrites performed
+Evidence: working-tree changes are docs-only (`git diff --name-only`); import/require guard scan shows no direct module imports from `templates/`
 
-[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 evidence reports created
+Evidence:
+- `docs/dev/reports/templates_live_usage_inventory.md`
+- `docs/dev/reports/templates_policy_decision.md`
+- `docs/dev/reports/templates_validation_guard.md`
+- `docs/dev/reports/BUILD_PR_TEMPLATES_POLICY_CLASSIFICATION_report.md`
 
-[PASS] templates/ untouched
-- Evidence: `git status --short -- templates` returned no entries.
+[PASS] no unrelated cleanup targets changed
+Evidence: no changes under `SpriteEditor_old_keep` or `classes_old_keep`; no unrelated cleanup-matrix/inventory files modified in this lane
 
-[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] roadmap wording preserved if roadmap changed
+Evidence: `git diff --unified=0 -- docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md` shows only checkbox state update on existing line
 
-[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.
+[PASS] roadmap changes bracket-only if roadmap changed
+Evidence: automated check -> `BRACKET_ONLY_CHECK: PASS`
diff --git a/docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md b/docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md
@@ -564,7 +564,7 @@
 - [ ] archived notes policy defined
 - [ ] imports pointing to legacy paths reduced
 - [.] roadmap for eventual legacy retirement defined
-- [ ] `templates/` folder evaluated for keep vs move vs future-delete during cleanup phase (explicitly deferred in this docs-only bundle)
+- [.] `templates/` folder evaluated for keep vs move vs future-delete during cleanup phase (explicitly deferred in this docs-only bundle)
 
 ---
 
diff --git a/docs/pr/BUILD_PR_TEMPLATES_POLICY_CLASSIFICATION.md b/docs/pr/BUILD_PR_TEMPLATES_POLICY_CLASSIFICATION.md

Original file line number	Diff line number	Diff line change
`@@ -1 +1 @@`
`1`		`-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/.`
	`1`	`+BUILD_PR_TEMPLATES_POLICY_CLASSIFICATION: add templates usage inventory, conservative policy baseline, and future cleanup validation guards without moving or rewriting templates.`