Finalize classes_old_keep decision

Author: DavidQ

docs/dev/CODEX_COMMANDS.md

@@ -1,16 +1,28 @@
 MODEL: GPT-5.3-codex
-REASONING: medium
+REASONING: high
 
 COMMAND:
-Execute BUILD_PR_TARGETED_REPO_CLEANUP_PASS_6_CLASSES_OLD_KEEP_REFERENCE_NORMALIZATION.
+Execute BUILD_PR_TARGETED_REPO_CLEANUP_PASS_7_FINAL_REVIEW_AND_DECISION
 
-- Normalize wording of classes_old_keep references across docs
-- Do not change meaning, only clarify as docs-only placeholder
-- Do not create/delete/move any files or folders
-- Generate:
-  docs/dev/reports/classes_old_keep_normalization_report.md
-  docs/dev/reports/BUILD_PR_TARGETED_REPO_CLEANUP_PASS_6_CLASSES_OLD_KEEP_REFERENCE_NORMALIZATION_report.md
-  docs/dev/reports/validation_checklist.txt
+Input:
+- normalization complete
+- classes_old_keep = docs-only placeholder
 
-Package to:
-<project folder>/tmp/BUILD_PR_TARGETED_REPO_CLEANUP_PASS_6_CLASSES_OLD_KEEP_REFERENCE_NORMALIZATION.zip
+Steps:
+1. Review all normalized references
+2. Decide:
+   a) remove references OR
+   b) keep placeholder
+3. Justify decision
+4. Create:
+   docs/dev/reports/classes_old_keep_final_decision_report.md
+   docs/dev/reports/classes_old_keep_cleanup_recommendation.md
+   docs/dev/reports/validation_checklist.txt
+
+Constraints:
+- no file deletion in this PR
+- no folder creation
+- no runtime changes
+
+Output:
+<project folder>/tmp/BUILD_PR_TARGETED_REPO_CLEANUP_PASS_7_FINAL_REVIEW_AND_DECISION.zip

docs/dev/COMMIT_COMMENT.txt

@@ -1 +1 @@
-Normalize classes_old_keep references to docs-only placeholder
+Finalize classes_old_keep decision

docs/dev/NEXT_COMMAND.txt

@@ -1 +1 @@
-Next: BUILD_PR_TARGETED_REPO_CLEANUP_PASS_7_FINAL_REVIEW
+Next: APPLY_PR_TARGETED_REPO_CLEANUP_PASS_7_DECISION

docs/dev/reports/change_summary.txt

@@ -1 +1 @@
-classes_old_keep reference normalization
+final decision for classes_old_keep

docs/dev/reports/classes_old_keep_cleanup_recommendation.md

@@ -0,0 +1,31 @@
+# classes_old_keep Cleanup Recommendation
+
+Generated: 2026-04-12
+Recommendation type: follow-up execution guidance
+
+## Recommended Path
+Keep placeholder now; plan optional removal later in a dedicated docs-only lane.
+
+## Immediate Recommendation (Current PR)
+- Preserve normalized terminology:
+  - `classes_old_keep (docs-only placeholder, no on-disk path)`
+- Do not remove references in this lane.
+
+## Future Removal Readiness Criteria
+Run a dedicated retirement lane only when all are true:
+1. Roadmap, cleanup inventory, cleanup matrix, enforcement map, and normalization report can be updated together.
+2. PR/build specs referencing `classes_old_keep` can be updated in one synchronized docs pass.
+3. Command/report metadata references are either intentionally retained or updated with explicit rationale.
+4. Validation confirms:
+   - no `classes_old_keep` directory on disk,
+   - no runtime/code references,
+   - no collateral changes to `templates/`, `docs/archive/`, or SpriteEditor archive surfaces.
+
+## Recommended Future Lane Shape
+- docs-only
+- no runtime edits
+- no file/folder structural operations
+- include explicit before/after reference inventory and rollback notes
+
+## Risk Note
+Removing references prematurely can erase audit context for legacy-cleanup decisions; retaining a clearly labeled placeholder is lower risk until final retirement scope is approved.

docs/dev/reports/classes_old_keep_final_decision_report.md

@@ -0,0 +1,37 @@
+# classes_old_keep Final Decision Report
+
+Generated: 2026-04-12
+Lane: BUILD_PR_TARGETED_REPO_CLEANUP_PASS_7_FINAL_REVIEW_AND_DECISION
+
+## Input State
+- normalization complete
+- `classes_old_keep` treated as docs-only placeholder
+
+## Step 1) Final Review Summary
+Reviewed normalized references in active docs (`docs/`, excluding `docs/archive/`):
+- Canonical phrase matches:
+  - `classes_old_keep (docs-only placeholder, no on-disk path)` -> 60 matches
+- Residual raw-token matches (intentional/literal contexts + metadata/spec references):
+  - 71 matches
+- On-disk path check:
+  - `Test-Path classes_old_keep` -> `False`
+- Runtime/code import check scope (`tools/src/games/samples/tests`):
+  - no matches in this lane
+
+## Step 2) Decision
+Decision: **(b) keep placeholder**
+
+## Step 3) Justification
+1. `classes_old_keep` has no on-disk directory and no active runtime usage.
+2. References remain concentrated in governance/planning/report/spec surfaces, where the placeholder preserves traceability of prior cleanup decisions.
+3. Removing references now would create documentation churn without reducing runtime risk, and would require synchronized edits across roadmap + cleanup reports + PR specs.
+4. Current normalized wording already clarifies the target status as docs-only and non-runtime.
+
+## Decision Outcome
+- Keep `classes_old_keep` as a docs-only placeholder in current governance surfaces.
+- Defer reference removal to a future dedicated docs-retirement lane after synchronized scope is approved.
+
+## Constraints Check
+- no file deletion performed
+- no folder creation performed
+- no runtime changes performed

docs/dev/reports/validation_checklist.txt

@@ -1,36 +1,27 @@
-BUILD_PR_TARGETED_REPO_CLEANUP_PASS_6_CLASSES_OLD_KEEP_REFERENCE_NORMALIZATION
+BUILD_PR_TARGETED_REPO_CLEANUP_PASS_7_FINAL_REVIEW_AND_DECISION
 Validation Checklist
 Generated: 2026-04-12
 
-[PASS] wording normalized to docs-only placeholder terminology
-Evidence: canonical phrase applied across active docs; see `classes_old_keep_normalization_report.md`
+[PASS] final review of normalized references completed
+Evidence: canonical phrase scan + residual reference scan captured in final decision report
 
-[PASS] meaning preserved (no policy behavior change)
-Evidence: only terminology clarifications, no action/rule semantics changed
+[PASS] decision recorded (remove vs keep)
+Evidence: decision = keep placeholder in `classes_old_keep_final_decision_report.md`
 
-[PASS] no file/folder move/rename/delete operations
-Evidence: `MOVE_DELETE_RENAME_CHECK: PASS`
-
-[PASS] no `classes_old_keep/` directory created
-Evidence: `Test-Path classes_old_keep` remains False
-
-[PASS] `templates/` untouched
-Evidence: `git diff --name-status -- templates` -> no entries
-
-[PASS] `docs/archive/` untouched
-Evidence: `git diff --name-status -- docs/archive` -> no entries
-
-[PASS] SpriteEditor archive surfaces untouched
-Evidence: `git diff --name-status -- docs/archive/tools/SpriteEditor_old_keep` -> no entries
-
-[PASS] runtime code untouched
-Evidence: `git diff --name-only -- tools src games samples tests` -> no entries
+[PASS] decision justified
+Evidence: explicit multi-point rationale included in final decision report
 
 [PASS] required reports generated
 Evidence:
-- `docs/dev/reports/classes_old_keep_normalization_report.md`
-- `docs/dev/reports/BUILD_PR_TARGETED_REPO_CLEANUP_PASS_6_CLASSES_OLD_KEEP_REFERENCE_NORMALIZATION_report.md`
+- `docs/dev/reports/classes_old_keep_final_decision_report.md`
+- `docs/dev/reports/classes_old_keep_cleanup_recommendation.md`
 - `docs/dev/reports/validation_checklist.txt`
 
-[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] no file deletion in this PR
+Evidence: no D/R/C entries in current diff status filter
+
+[PASS] no folder creation in this PR scope
+Evidence: no new directories required for deliverables; reports written in existing `docs/dev/reports/`
+
+[PASS] no runtime changes
+Evidence: `git diff --name-only -- tools src games samples tests` -> no entries

docs/pr/BUILD_PR_TARGETED_REPO_CLEANUP_PASS_7_FINAL_REVIEW_AND_DECISION.md

@@ -0,0 +1,16 @@
+# BUILD_PR_TARGETED_REPO_CLEANUP_PASS_7_FINAL_REVIEW_AND_DECISION
+
+## Purpose
+Finalize decision for classes_old_keep after normalization.
+
+## Options
+- remove all references
+- keep as documented placeholder
+
+## Scope
+Docs-only decision. No structural changes unless explicitly approved in future PR.
+
+## Deliverables
+- final_decision_report.md
+- cleanup_recommendation.md
+- validation_checklist.txt