Skip to content

Commit 8b0dbf8

Browse files
author
DavidQ
committed
BUILD_PR_TARGETED_REPO_CLEANUP_PASS_1 - targeted cleanup enforcement/normalization docs lane
1 parent 9a1c7bc commit 8b0dbf8

10 files changed

Lines changed: 493 additions & 45 deletions

‎docs/dev/CODEX_COMMANDS.md‎

Lines changed: 11 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,13 @@
1-
MODEL: GPT-5.4
1+
MODEL: GPT-5.3-codex
22
REASONING: high
3+
34
COMMAND:
4-
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`.
5+
Execute BUILD_PR_TARGETED_REPO_CLEANUP_PASS_1.
6+
7+
- Create `docs/dev/reports/cleanup_target_enforcement_map.md`, `docs/dev/reports/cleanup_execution_guard.md`, `docs/dev/reports/cleanup_target_normalization_report.md`, `docs/dev/reports/BUILD_PR_TARGETED_REPO_CLEANUP_PASS_1_report.md`, and `docs/dev/reports/validation_checklist.txt` exactly as specified in `docs/pr/BUILD_PR_TARGETED_REPO_CLEANUP_PASS_1.md`.
8+
- Use only the existing cleanup inventory, cleanup matrix, prior cleanup BUILD report, templates inventory, templates policy, templates validation guard, templates BUILD report, repo cleanup targets list, and master roadmap as source evidence.
9+
- Do not modify `templates/`, runtime code, test logic, repo structure, or protected start_of_day directories.
10+
- Do not introduce new cleanup targets.
11+
- If roadmap alignment is attempted, it must be bracket-only and only if the exact existing text already supports it.
12+
- Package output to:
13+
<project folder>/tmp/BUILD_PR_TARGETED_REPO_CLEANUP_PASS_1.zip

‎docs/dev/COMMIT_COMMENT.txt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
BUILD_PR_TEMPLATES_POLICY_CLASSIFICATION: add templates usage inventory, conservative policy baseline, and future cleanup validation guards without moving or rewriting templates.
1+
BUILD_PR_TARGETED_REPO_CLEANUP_PASS_1 - targeted cleanup enforcement/normalization docs lane

‎docs/dev/NEXT_COMMAND.txt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
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.
1+
After Codex completes this BUILD and the output files validate, the next testable lane should be a single-target cleanup BUILD such as a legacy-import-guard lane or an archived-notes-policy lane, chosen strictly from the approved cleanup target set.

‎docs/dev/reports/BUILD_PR_TARGETED_REPO_CLEANUP_PASS_1_report.md‎

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
# BUILD_PR_TARGETED_REPO_CLEANUP_PASS_1 Report
2+
3+
Generated: 2026-04-12
4+
Bundle type: execution-ready BUILD docs
5+
6+
## Exact Files Created
7+
- `docs/dev/reports/cleanup_target_enforcement_map.md`
8+
- `docs/dev/reports/cleanup_execution_guard.md`
9+
- `docs/dev/reports/cleanup_target_normalization_report.md`
10+
- `docs/dev/reports/BUILD_PR_TARGETED_REPO_CLEANUP_PASS_1_report.md`
11+
12+
## Exact Files Changed
13+
- `docs/dev/reports/validation_checklist.txt`
14+
15+
## Enforcement-Map Summary
16+
- Formalized enforcement for exactly six approved cleanup targets:
17+
- `templates/`
18+
- `tools/SpriteEditor_old_keep/` policy target
19+
- `classes_old_keep` policy target
20+
- `docs/archive/` archived-notes policy target
21+
- legacy import path patterns
22+
- eventual legacy-retirement planning target
23+
- Each target now has evidence-grounded allowed/forbidden actions, validation requirements, coupled surfaces, risk level, and recommended future PR type.
24+
- No new cleanup targets were introduced.
25+
26+
## Execution-Guard Summary
27+
- Added global cleanup pre-check requirements (reference state, existence/path, classification, target-specific guard selection).
28+
- Added required validation surfaces (smoke expectations, docs-sync surfaces, target-specific tests when path changes are attempted).
29+
- Added reusable command patterns for reference scans, structural diff checks, protected directory checks, runtime/test-surface checks, and roadmap checks.
30+
- Added global forbidden actions and blocking failure conditions.
31+
32+
## Normalization Findings Summary
33+
- Target naming/path/classification/tracking were compared across approved cleanup and roadmap sources.
34+
- One mismatch identified:
35+
- `templates/` classification differs between matrix (`needs-manual-review`) and templates policy (`keep-in-place-for-now`).
36+
- All other approved targets were aligned sufficiently for this enforcement pass.
37+
- No wording rewrites were applied to force alignment in this PR.
38+
39+
## Roadmap Changes Applied
40+
- None.
41+
- Roadmap was left untouched in this lane.
42+
43+
## Unapplied Planned Delta
44+
- None.
45+
- No bracket-only roadmap progression was attempted in this pass.
46+
47+
## Non-Destructive Assertions
48+
- No deletion, move, or rename was executed.
49+
- `templates/` was untouched.
50+
- Runtime code was untouched.
51+
- Test logic was untouched.
52+
- Protected directories were untouched:
53+
- `docs/dev/start_of_day/chatGPT/`
54+
- `docs/dev/start_of_day/codex/`
55+
56+
## Validation Results (Command-Backed)
57+
1. Confirm no structural changes beyond allowed docs files:
58+
- `git diff --name-status`
59+
- Result: modified docs files only; no D/R/C entries.
60+
- Guard result: `STRUCTURAL_CHECK: PASS`.
61+
62+
2. Confirm `templates/` untouched:
63+
- `git diff --name-status -- templates`
64+
- Result: no entries.
65+
- Guard result: `TEMPLATES_TOUCH_CHECK: PASS`.
66+
67+
3. Confirm protected start_of_day directories unchanged:
68+
- `git status --short -- docs/dev/start_of_day/chatGPT docs/dev/start_of_day/codex`
69+
- Result: no entries.
70+
- Guard result: `PROTECTED_DIR_CHECK: PASS`.
71+
72+
4. If roadmap changed, verify bracket-only diff:
73+
- `git diff --unified=0 -- docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md`
74+
- Result: no roadmap diff in this lane.
75+
- Guard result: `ROADMAP_DIFF_PRESENT: NO (check not required)`.
76+
77+
5. Confirm no runtime/test files changed:
78+
- `git diff --name-only -- tools src games samples tests`
79+
- Result: no entries.
80+
- Guard result: `RUNTIME_TEST_SURFACE_CHECK: PASS`.

‎docs/dev/reports/change_summary.txt‎

Lines changed: 14 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -1,22 +1,14 @@
1-
PR: BUILD_PR_SAMPLES_INDEX_FIXES_AND_TARGETED_PREVIEW_RETRY
2-
3-
Bundle contents:
4-
- docs/pr/BUILD_PR_SAMPLES_INDEX_FIXES_AND_TARGETED_PREVIEW_RETRY.md
5-
- docs/dev/codex_commands.md
6-
- docs/dev/commit_comment.txt
7-
- docs/dev/next_command.txt
8-
- docs/dev/reports/change_summary.txt
9-
- docs/dev/reports/validation_checklist.txt
10-
- docs/dev/reports/file_tree.txt
11-
12-
Requested runtime/code scope for Codex:
13-
- samples/index.html label/header text correction only
14-
- Sample 1303 local asteroid speed cap only
15-
- targeted preview SVG retry only for the enumerated samples and only when SVG contains `Capture timeout`
16-
17-
Explicit exclusions:
18-
- no engine/core edits
19-
- no metadata/tag changes
20-
- no broad layout changes
21-
- no modifications to 1316, 1317, 1318
22-
- no protected start_of_day directory changes
1+
Bundle type: execution-ready BUILD docs only
2+
PR purpose: targeted cleanup enforcement/normalization pass
3+
Scope:
4+
- create cleanup target enforcement map
5+
- create cleanup execution guard
6+
- create cleanup target normalization report
7+
- create BUILD report
8+
- create validation checklist
9+
Constraints:
10+
- non-destructive
11+
- templates untouched
12+
- no runtime/test changes
13+
- no start_of_day changes
14+
- no new cleanup targets

‎docs/dev/reports/cleanup_execution_guard.md‎

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
# Cleanup Execution Guard
2+
3+
Generated: 2026-04-12
4+
Scope: Global execution rules for future cleanup PRs, derived from approved cleanup/templates evidence.
5+
6+
## A) Required Pre-Checks
7+
1. Reference scan requirement:
8+
- Confirm current reference state for the exact target before proposing any action.
9+
2. Existence/path verification:
10+
- Verify whether the target path exists on disk and whether references are runtime, test, docs-only, or mixed.
11+
3. Target classification confirmation:
12+
- Confirm classification from `cleanup_keep_move_future_delete_matrix.md` and any overriding target policy artifact (for `templates/`, policy remains keep-in-place-for-now).
13+
4. Target-specific guard selection requirement:
14+
- Select and apply the guard set appropriate to the target:
15+
- `templates/`: use `templates_validation_guard.md` in full.
16+
- Legacy policy/docs targets: use this global guard plus target-specific reference scans.
17+
18+
## B) Required Validation Surfaces
19+
1. Before/after smoke validation expectations:
20+
- If a future PR attempts any path/structure change, run before and after smoke checks:
21+
- `npm run test:launch-smoke -- --tools`
22+
- Add `--games --samples` when changes could affect sample/game surfaces.
23+
2. Docs sync surfaces:
24+
- Synchronize relevant docs in the same PR when path/policy states change:
25+
- `docs/dev/reports/repo_cleanup_targets.txt`
26+
- `docs/dev/reports/cleanup_live_reference_inventory.txt`
27+
- `docs/dev/reports/cleanup_keep_move_future_delete_matrix.md`
28+
- `docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md`
29+
- target-specific policy/guard reports (including templates reports where relevant)
30+
3. Target-specific tests if path change is attempted:
31+
- For `templates/`, rerun template contract tests from `templates_validation_guard.md`.
32+
- For tool-path targets, include tool launch smoke validation surfaces.
33+
34+
## C) Required Command Patterns
35+
Run from repo root.
36+
37+
1. Reference scans:
38+
```powershell
39+
rg -n "templates/" tools src games samples tests
40+
rg -n "SpriteEditor_old_keep|classes_old_keep|docs/archive/|legacy retirement|imports pointing to legacy paths" docs --glob "!docs/archive/**"
41+
rg -n "from '/engine/|from '../engine/|from './engine/" tools src games samples tests
42+
```
43+
44+
2. Structural-change diff checks:
45+
```powershell
46+
git diff --name-status
47+
git diff --name-status -- templates
48+
```
49+
50+
3. Protected-directory checks:
51+
```powershell
52+
git status --short -- docs/dev/start_of_day/chatGPT docs/dev/start_of_day/codex
53+
```
54+
55+
4. Runtime/test surface change checks:
56+
```powershell
57+
git diff --name-only -- tools src games samples tests
58+
```
59+
60+
5. Roadmap diff checks (when roadmap is modified):
61+
```powershell
62+
git diff --unified=0 -- docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md
63+
```
64+
65+
## D) Global Forbidden Actions
66+
- Repo-wide cleanup scans used as execution scope for structural edits.
67+
- Mixed-purpose cleanup PRs combining policy, migration, and unrelated runtime changes.
68+
- Delete/move/rename of live-reference targets without synchronized validation and docs alignment.
69+
- Any `templates/` structural action that conflicts with active templates policy/guard artifacts.
70+
- Structural cleanup changes inside docs-only evidence/policy lanes.
71+
72+
## E) Blocking Failure Conditions
73+
Stop execution immediately if any of the following occur:
74+
- target classification cannot be reconciled with current policy artifacts;
75+
- unresolved live references remain for a target proposed for move/delete;
76+
- runtime/test files change in a docs-only cleanup lane;
77+
- protected start_of_day directories show any changes;
78+
- roadmap wording changes are needed (non bracket-only) to represent progress;
79+
- cleanup scope expands beyond approved targets.
80+
81+
## Guard Summary
82+
Future cleanup execution must stay target-specific, evidence-backed, and validation-first. Policy and enforcement docs alone do not authorize structural cleanup.

‎docs/dev/reports/cleanup_target_enforcement_map.md‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Cleanup Target Enforcement Map
2+
3+
Generated: 2026-04-12
4+
Scope: Approved cleanup targets only; evidence-grounded from existing cleanup and templates policy artifacts.
5+
6+
## Target Enforcement Table
7+
8+
| Target | Current Classification (Matrix) | Current Reference State (Inventory) | Allowed Actions Now | Forbidden Actions Now | Required Validation Before Any Future Change | Dependency Surfaces / Coupled Files (Evidence) | Risk Level | Recommended Future PR Type |
9+
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
10+
| `templates/` | `needs-manual-review` | `live-reference` | Keep in place; policy/guard documentation updates only. | Move/rename/delete `templates/`; rewrite runtime path usage; unsynchronized template migration. | Run reference scans and structural checks from `templates_validation_guard.md`; run smoke and template contract tests if path change is proposed; synchronize docs/contracts listed in the templates guard. | `tools/shared/vectorNativeTemplate.js`; `tools/shared/vectorTemplateSampleGame.js`; `tests/tools/VectorNativeTemplate.test.mjs`; `games/vector-arcade-sample/README.md`; roadmap templates deferment lines. | `high` | `manual-review` |
11+
| `tools/SpriteEditor_old_keep/` policy target | `keep` | `live-reference` | Keep policy tracking and legacy visibility as-is; docs-only policy clarification in isolated lane. | Delete/move/rename target path in cleanup docs lane; runtime/tool registry edits bundled with policy-only cleanup docs. | Confirm reference state and target classification first; if any structural change is proposed later, run pre/post smoke validation and synchronized docs updates. | `tools/toolRegistry.js`; `docs/specs/project_manifest_contract.md`; `docs/specs/asset_usage_contract.md`; roadmap legacy policy line; cleanup targets report. | `high` | `policy-only` |
12+
| `classes_old_keep` policy target | `needs-manual-review` | `docs-reference-only` | Keep as planning placeholder; clarify meaning in docs-only manual-review lane. | Creating or deleting a runtime path based on assumption; structural cleanup action without first resolving what target represents. | Verify on-disk existence and references; reconcile naming/path intent across roadmap/targets/inventory before any execution lane. | `docs/dev/reports/repo_cleanup_targets.txt`; `docs/dev/reports/cleanup_live_reference_inventory.txt`; `docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md`. | `medium` | `manual-review` |
13+
| `docs/archive/` archived-notes policy target | `keep` | `live-reference` | Retain archive location and policy tracking; define archival criteria in policy-only lane. | Move/delete archive tree in enforcement lane; mixed structural cleanup with unrelated targets. | Re-scan docs references; confirm policy alignment in roadmap/targets docs; if path move is ever proposed, include synchronized docs updates and smoke checks where affected. | `docs/README.md`; `docs/repo-directory-structure.md`; `docs/dev/README.md`; `docs/dev/paths.md`; `docs/review-checklist.md`; roadmap archived-notes policy line. | `medium` | `policy-only` |
14+
| Legacy import path patterns (`/engine/`, `../engine/`, `./engine/`) | `future-delete-candidate` | `mixed` (code imports: zero-reference; docs/planning refs: live-reference) | Keep guard scans active; document zero-reference code state. | Repo-wide rewrite/delete passes without targeted validation; claiming cleanup completion without scan evidence. | Run pattern scans across active runtime/test surfaces; if changes are made later, run smoke validation and verify no regressions in imports. | Cleanup inventory target 5 pattern scan results; cleanup matrix legacy import row; roadmap legacy imports reduction line. | `medium` | `future-delete` |
15+
| Eventual legacy-retirement planning target | `migrate-later` | `live-reference` (planning) | Keep planning target tracked; sequence follow-up lanes dependency-first. | Executing retirement changes in a docs-only enforcement lane; combining multiple structural retirements in one pass. | Confirm target-specific evidence and dependency ordering before execution; run structural/smoke validations per target in future implementation lanes. | `docs/dev/reports/repo_cleanup_targets.txt`; `docs/dev/reports/roadmap_status_delta.txt`; `docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md`; prior cleanup BUILD report. | `medium` | `migration-later` |
16+
17+
## Enforcement Notes
18+
- No new cleanup targets were introduced.
19+
- Actions above are constrained to currently approved targets and evidence only.
20+
- This map is enforcement guidance and does not authorize structural cleanup by itself.

‎docs/dev/reports/cleanup_target_normalization_report.md‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
# Cleanup Target Normalization Report
2+
3+
Generated: 2026-04-12
4+
Scope: Consistency check across approved sources only.
5+
6+
Compared Sources:
7+
- `docs/dev/reports/repo_cleanup_targets.txt`
8+
- `docs/dev/reports/cleanup_live_reference_inventory.txt`
9+
- `docs/dev/reports/cleanup_keep_move_future_delete_matrix.md`
10+
- `docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md`
11+
- templates-policy artifacts where relevant
12+
13+
## Target Consistency Matrix
14+
15+
| Target | Name Consistency | Path Consistency | Classification Consistency | Tracking Presence | Mismatch Found? |
16+
| --- | --- | --- | --- | --- | --- |
17+
| `templates/` | yes | yes | no | yes | yes |
18+
| `tools/SpriteEditor_old_keep/` policy target | yes (policy label vs path label both map to same target) | yes | yes | yes | no |
19+
| `classes_old_keep` policy target | yes | yes (as policy placeholder path) | yes | yes | no |
20+
| `docs/archive/` archived-notes policy target | yes | yes | yes | yes | no |
21+
| Legacy import path patterns | yes | yes (pattern-based target) | yes | yes | no |
22+
| Eventual legacy-retirement planning target | yes | yes (planning-path target) | yes | yes | no |
23+
24+
## Mismatch Details
25+
26+
### `templates/`
27+
- Exact mismatch:
28+
- Matrix classification in `cleanup_keep_move_future_delete_matrix.md`: `needs-manual-review`.
29+
- Templates policy decision in `templates_policy_decision.md`: `keep-in-place-for-now`.
30+
- Impact:
31+
- Enforcement lanes must treat templates as retained/deferred by active templates policy, while matrix classification remains broader.
32+
- Correction recommendation:
33+
- In a future docs-only alignment lane, reconcile matrix classification with the active templates policy decision (without introducing structural cleanup actions).
34+
35+
## Alignment Summary
36+
- All approved targets are present and traceable across cleanup targets, inventory, matrix, and roadmap tracking.
37+
- Aside from the templates classification terminology mismatch, alignment is acceptable for this enforcement/normalization pass.
38+
- No wording rewrites were applied in this PR to force normalization.

‎docs/dev/reports/validation_checklist.txt‎

Lines changed: 24 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -1,28 +1,33 @@
1-
BUILD_PR_TEMPLATES_POLICY_CLASSIFICATION
1+
BUILD_PR_TARGETED_REPO_CLEANUP_PASS_1
22
Validation Checklist
33
Generated: 2026-04-12
44

5-
[PASS] protected start_of_day directories untouched
6-
Evidence: `git status --short -- docs/dev/start_of_day/chatGPT docs/dev/start_of_day/codex` -> no entries
5+
[PASS] no deletion/move/rename executed
6+
Evidence: `git diff --name-status` + structural guard => `STRUCTURAL_CHECK: PASS` (no D/R/C entries)
7+
8+
[PASS] `templates/` untouched
9+
Evidence: `git diff --name-status -- templates` => no entries (`TEMPLATES_TOUCH_CHECK: PASS`)
10+
11+
[PASS] no runtime code changes
12+
Evidence: `git diff --name-only -- tools src games samples tests` => no entries
713

8-
[PASS] `templates/` not moved/renamed/deleted
9-
Evidence: `git diff --name-status -- templates` -> no entries
14+
[PASS] no test logic changes
15+
Evidence: `git diff --name-only -- tools src games samples tests` => no entries
1016

11-
[PASS] no runtime import rewrites performed
12-
Evidence: working-tree changes are docs-only (`git diff --name-only`); import/require guard scan shows no direct module imports from `templates/`
17+
[PASS] enforcement map created
18+
Evidence: `docs/dev/reports/cleanup_target_enforcement_map.md`
1319

14-
[PASS] templates evidence reports created
15-
Evidence:
16-
- `docs/dev/reports/templates_live_usage_inventory.md`
17-
- `docs/dev/reports/templates_policy_decision.md`
18-
- `docs/dev/reports/templates_validation_guard.md`
19-
- `docs/dev/reports/BUILD_PR_TEMPLATES_POLICY_CLASSIFICATION_report.md`
20+
[PASS] cleanup execution guard created
21+
Evidence: `docs/dev/reports/cleanup_execution_guard.md`
2022

21-
[PASS] no unrelated cleanup targets changed
22-
Evidence: no changes under `SpriteEditor_old_keep` or `classes_old_keep`; no unrelated cleanup-matrix/inventory files modified in this lane
23+
[PASS] normalization report created
24+
Evidence: `docs/dev/reports/cleanup_target_normalization_report.md`
2325

24-
[PASS] roadmap wording preserved if roadmap changed
25-
Evidence: `git diff --unified=0 -- docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md` shows only checkbox state update on existing line
26+
[PASS] no new cleanup targets introduced
27+
Evidence: enforcement map contains only approved six targets from PR spec
2628

27-
[PASS] roadmap changes bracket-only if roadmap changed
28-
Evidence: automated check -> `BRACKET_ONLY_CHECK: PASS`
29+
[PASS] roadmap unchanged or bracket-only if changed
30+
Evidence: `git diff --unified=0 -- docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md` => no diff in this lane
31+
32+
[PASS] protected start_of_day directories untouched
33+
Evidence: `git status --short -- docs/dev/start_of_day/chatGPT docs/dev/start_of_day/codex` => no entries

0 commit comments

Comments
 (0)