Skip to content

Commit d6fbb04

Browse files
author
DavidQ
committed
BUILD_PR_TARGETED_REPO_CLEANUP_PASS_3_ARCHIVED_NOTES_POLICY
Create archived notes policy inventory, decision, and validation guard as a docs-only, non-destructive cleanup lane.
1 parent 347ee37 commit d6fbb04

12 files changed

Lines changed: 520 additions & 10 deletions

‎docs/dev.zip‎

-92 KB
Binary file not shown.

‎docs/dev/CODEX_COMMANDS.md‎

Lines changed: 12 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,4 +2,15 @@ MODEL: GPT-5.3-codex
22
REASONING: high
33

44
COMMAND:
5-
Scan repo for legacy engine import paths and generate guard report.
5+
Execute BUILD_PR_TARGETED_REPO_CLEANUP_PASS_3_ARCHIVED_NOTES_POLICY.
6+
7+
- Create archived notes policy inventory, policy decision, validation guard, BUILD report, and validation checklist exactly as specified in:
8+
docs/pr/BUILD_PR_TARGETED_REPO_CLEANUP_PASS_3_ARCHIVED_NOTES_POLICY.md
9+
- Use existing cleanup evidence as the source of truth for archived notes:
10+
- docs/dev/reports/cleanup_live_reference_inventory.txt
11+
- docs/dev/reports/cleanup_keep_move_future_delete_matrix.md
12+
- Do NOT modify docs/archive/, templates/, runtime code, or repo structure.
13+
- Do NOT introduce new cleanup targets.
14+
- If roadmap updates are needed, apply bracket-only changes only where exact wording already exists.
15+
- Package output to:
16+
<project folder>/tmp/BUILD_PR_TARGETED_REPO_CLEANUP_PASS_3_ARCHIVED_NOTES_POLICY.zip

‎docs/dev/COMMIT_COMMENT.txt‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,3 @@
1-
BUILD_PR_TARGETED_REPO_CLEANUP_PASS_2
1+
BUILD_PR_TARGETED_REPO_CLEANUP_PASS_3_ARCHIVED_NOTES_POLICY
22

3-
Adds legacy import guard and report.
3+
Create archived notes policy inventory, decision, and validation guard as a docs-only, non-destructive cleanup lane.

‎docs/dev/NEXT_COMMAND.txt‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,2 @@
1-
Proceed to APPLY_PR_TARGETED_REPO_CLEANUP_PASS_2 if validation passes.
1+
After Codex completes and validation passes, proceed to:
2+
APPLY_PR_TARGETED_REPO_CLEANUP_PASS_3_ARCHIVED_NOTES_POLICY

‎docs/dev/reports/BUILD_PR_TARGETED_REPO_CLEANUP_PASS_3_ARCHIVED_NOTES_POLICY_report.md‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
# BUILD_PR_TARGETED_REPO_CLEANUP_PASS_3_ARCHIVED_NOTES_POLICY Report
2+
3+
Generated: 2026-04-12
4+
Bundle type: execution-ready BUILD docs (archived-notes policy lane)
5+
6+
## Exact Files Created
7+
- `docs/dev/reports/archived_notes_policy_inventory.md`
8+
- `docs/dev/reports/archived_notes_policy_decision.md`
9+
- `docs/dev/reports/archived_notes_validation_guard.md`
10+
- `docs/dev/reports/BUILD_PR_TARGETED_REPO_CLEANUP_PASS_3_ARCHIVED_NOTES_POLICY_report.md`
11+
12+
## Exact Files Changed
13+
- `docs/dev/reports/validation_checklist.txt`
14+
15+
## Archived Notes Inventory Findings Summary
16+
- `docs/archive/` exists and remains an active documentation/archive destination.
17+
- Evidence baseline from cleanup source-of-truth confirms archived notes target is live-reference (`cleanup_live_reference_inventory.txt`) and keep-classified in matrix (`cleanup_keep_move_future_delete_matrix.md`).
18+
- Current scan found active `docs/archive/` references across docs structure/navigation/policy surfaces.
19+
- No test references and no JSON/YAML config references to `docs/archive/` were found.
20+
- Path assumptions for archive destinations are currently explicit in active docs contracts and cleanup governance artifacts.
21+
22+
## Chosen Policy Classification
23+
- Options considered: `keep-in-place-for-now`, `migrate-later`, `needs-manual-review`.
24+
- Chosen classification: `keep-in-place-for-now`.
25+
- Rationale: active documentation coupling and cleanup governance references require conservative retention in this lane.
26+
27+
## Roadmap Changes Applied
28+
- None.
29+
- Roadmap remained unchanged in this lane.
30+
31+
## Unapplied Planned Delta
32+
- None.
33+
- Optional roadmap alignment was not required for acceptance in this pass.
34+
35+
## Non-Destructive Assertions
36+
- `docs/archive/` was not moved, renamed, deleted, or modified.
37+
- `templates/` was untouched.
38+
- No runtime code, tests, or repo-structure files were modified as part of this archived-notes policy lane.
39+
40+
## Validation Results (Command-Backed)
41+
1. Search all references to `docs/archive/` and list exact consumer files:
42+
- `rg -n "docs/archive/" docs tools src games samples tests --glob "!docs/archive/**" --glob "!**/node_modules/**"`
43+
- Active consumer files include docs structure/policy surfaces such as:
44+
- `docs/README.md`
45+
- `docs/repo-directory-structure.md`
46+
- `docs/dev/README.md`
47+
- `docs/dev/paths.md`
48+
- `docs/review-checklist.md`
49+
- plus cleanup reports/specs and archive-cleanup planning/build specs.
50+
51+
2. Confirm no file deletions/renames/moves under `docs/archive/`:
52+
- `git diff --name-status -- docs/archive`
53+
- Result: no entries.
54+
55+
3. Confirm protected start_of_day directories unchanged:
56+
- `git status --short -- docs/dev/start_of_day/chatGPT docs/dev/start_of_day/codex`
57+
- Result: no entries.
58+
59+
4. Roadmap bracket-only check (if roadmap changed):
60+
- `git diff --unified=0 -- docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md`
61+
- Result: no roadmap diff in this lane; bracket-only check not required.
62+
63+
5. Templates untouched confirmation:
64+
- `git diff --name-status -- templates`
65+
- Result: no entries.

‎docs/dev/reports/archived_notes_policy_decision.md‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
# Archived Notes Policy Decision
2+
3+
Generated: 2026-04-12
4+
Scope: Policy classification for archived notes target `docs/archive/`.
5+
6+
## Classification Options Considered
7+
- `keep-in-place-for-now`
8+
- `migrate-later`
9+
- `needs-manual-review`
10+
11+
## Chosen Classification (This PR)
12+
- `keep-in-place-for-now`
13+
14+
## Rationale (Evidence-Grounded)
15+
From cleanup source-of-truth artifacts:
16+
- `cleanup_live_reference_inventory.txt` classifies archived notes target as live-reference and documented.
17+
- `cleanup_keep_move_future_delete_matrix.md` classifies archived-notes policy target as `keep` with policy-definition follow-up.
18+
19+
From current inventory scan:
20+
- `docs/archive/` exists with active docs references across structure/navigation/policy surfaces.
21+
- Explicit path destinations under `docs/archive/` are encoded in active docs contracts.
22+
- No test/config references were found, but documentation coupling is broad and active.
23+
24+
Given this coupling, move/delete/repath actions are unsafe without synchronized multi-doc updates and explicit migration sequencing.
25+
26+
## Allowed Now
27+
- Document archived-notes inventory, policy, and validation guard artifacts.
28+
- Keep policy tracking synchronized in cleanup reports/roadmap state (bracket-only if used).
29+
- Retain `docs/archive/` in place.
30+
31+
## Forbidden Now
32+
- Move, rename, delete, or rewrite any file/path under `docs/archive/` in this lane.
33+
- Structural cleanup mixed with unrelated targets (`templates`, `SpriteEditor_old_keep`, `classes_old_keep`, legacy import guard work).
34+
- Runtime or repo-structure edits under this policy-only BUILD.
35+
36+
## Exact Prerequisites For Future Migration/Removal Lane
37+
1. Refresh reference inventory and confirm all consumers of `docs/archive/`.
38+
2. Produce explicit source->destination path map for any archive movement.
39+
3. Prepare synchronized docs updates for all structure/navigation/policy references in the same PR.
40+
4. Define rollback plan with reversible path map.
41+
5. Execute pre/post validation guard checks (reference scan, structural diff checks, protected path checks, and docs consistency checks).
42+
6. If any tooling/tests become path-coupled in the future, include those validations in the same migration lane.
43+
44+
## Reclassification Signals (Future)
45+
Policy may move from `keep-in-place-for-now` to `migrate-later` only when:
46+
- reference surface is fully enumerated and destination mapping is approved,
47+
- synchronized docs update set is prepared,
48+
- migration can run as one exact-scope validated lane.
49+
50+
Policy may move to deletion-oriented consideration only when:
51+
- no active references remain,
52+
- retained historical value is addressed by an approved replacement retention strategy,
53+
- validation evidence confirms zero-reference state and no policy/navigation regressions.
54+
55+
## Decision Summary
56+
- Archived notes remain retained in place for now.
57+
- This BUILD is policy/guard documentation only and performs no structural repo change.

‎docs/dev/reports/archived_notes_policy_inventory.md‎

Lines changed: 116 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,116 @@
1+
# Archived Notes Policy Inventory
2+
3+
Generated: 2026-04-12
4+
Scope: `docs/archive/` policy surface only (non-destructive, docs-only lane).
5+
6+
## Source-Of-Truth Baseline (Existing Cleanup Evidence)
7+
- `docs/dev/reports/cleanup_live_reference_inventory.txt` (Target 4):
8+
- Exact path: `docs/archive/`
9+
- Exists: yes
10+
- Assessment: `live-reference`
11+
- Notes: archive location is active/documented; policy item still incomplete.
12+
- `docs/dev/reports/cleanup_keep_move_future_delete_matrix.md`:
13+
- Target row: ``docs/archive/` archived-notes policy``
14+
- Proposed classification: `keep`
15+
- Recommended future scope: policy-definition PR.
16+
17+
## 1) Path Existence And Archive Contents
18+
- `docs/archive/` exists: **yes**
19+
- Recursive file count under `docs/archive/`: **446**
20+
- Recursive directory count under `docs/archive/`: **5**
21+
22+
Exact directories under `docs/archive/`:
23+
- `docs/archive/dev-ops`
24+
- `docs/archive/generated-reports`
25+
- `docs/archive/pr`
26+
- `docs/archive/generated-reports/dev-reports`
27+
- `docs/archive/pr/legacy-pr-history`
28+
29+
Exact file inventory command used:
30+
```powershell
31+
rg --files docs/archive
32+
```
33+
34+
## 2) Active References To `docs/archive/`
35+
Reference scan command used:
36+
```powershell
37+
rg -n "docs/archive/" docs tools src games samples tests --glob "!docs/archive/**" --glob "!**/node_modules/**"
38+
```
39+
40+
Unique active consumer files found:
41+
- `docs/README.md`
42+
- `docs/repo-directory-structure.md`
43+
- `docs/getting-started.md`
44+
- `docs/review-checklist.md`
45+
- `docs/architecture/repo-operating-model.md`
46+
- `docs/architecture/engine-api-boundary.md`
47+
- `docs/dev/README.md`
48+
- `docs/dev/paths.md`
49+
- `docs/dev/file_tree.txt`
50+
- `docs/dev/codex_commands.md`
51+
- `docs/dev/validation_checklist.txt`
52+
- `docs/dev/reports/README.md`
53+
- `docs/dev/reports/cleanup_live_reference_inventory.txt`
54+
- `docs/dev/reports/cleanup_keep_move_future_delete_matrix.md`
55+
- `docs/dev/reports/BUILD_PR_REPO_CLEANUP_AND_ROADMAP_UPDATE_report.md`
56+
- `docs/dev/reports/BUILD_PR_TARGETED_REPO_CLEANUP_PASS_1_report.md`
57+
- `docs/dev/reports/cleanup_execution_guard.md`
58+
- `docs/dev/reports/cleanup_target_enforcement_map.md`
59+
- `docs/dev/reports/cleanup_target_normalization_report.md`
60+
- `docs/dev/reports/templates_validation_guard.md`
61+
- `docs/dev/reports/docs_path_cleanup_plan.txt`
62+
- `docs/pr/PLAN_PR_DOCS_ARCHIVE_CLEANUP.md`
63+
- `docs/pr/BUILD_PR_DOCS_ARCHIVE_CLEANUP.md`
64+
- `docs/pr/BUILD_PR_TARGETED_REPO_CLEANUP_PASS_1.md`
65+
- `docs/pr/BUILD_PR_TARGETED_REPO_CLEANUP_PASS_3_ARCHIVED_NOTES_POLICY.md`
66+
67+
### Reference Classification (Policy / Structure / Navigation / Historical)
68+
| File | Classification | Notes |
69+
| --- | --- | --- |
70+
| `docs/README.md` | structure/navigation | Canonical docs entry points include archive destinations. |
71+
| `docs/repo-directory-structure.md` | structure | Declares archive folders as part of repo structure. |
72+
| `docs/getting-started.md` | navigation | Explains archive location for onboarding. |
73+
| `docs/review-checklist.md` | policy | Review rules cite archive destinations. |
74+
| `docs/architecture/repo-operating-model.md` | policy/structure | Operating model includes archive paths. |
75+
| `docs/architecture/engine-api-boundary.md` | policy | Boundary guidance references archived outputs. |
76+
| `docs/dev/README.md` | structure/navigation | Dev docs index references archive subpaths. |
77+
| `docs/dev/paths.md` | policy/structure | Explicit path constants map to archive locations. |
78+
| `docs/dev/file_tree.txt` | historical/structure | Snapshot includes archive tree placement. |
79+
| `docs/dev/codex_commands.md` | policy | Command constraints include archive protections. |
80+
| `docs/dev/validation_checklist.txt` | policy | Validation wording references archive destination. |
81+
| `docs/dev/reports/README.md` | navigation/policy | Report retention guidance points to archive reports path. |
82+
| Cleanup reports/specs listed above | policy | Cleanup governance tracks archive target and guard rules. |
83+
| Docs archive cleanup plan/build specs | historical/policy | Historical movement plan and manifest contract references archive destination. |
84+
| Current archived-notes policy BUILD spec | policy | Defines this exact policy lane scope/constraints. |
85+
86+
## 3) Required Separation
87+
88+
### Direct path references
89+
- Direct literal `docs/archive/` references are present and active in the unique consumer files listed above.
90+
91+
### Documentation/policy references
92+
- All current active references found by scan are documentation/policy/governance surfaces under `docs/`.
93+
94+
### Test/config references
95+
Commands used:
96+
```powershell
97+
rg -n "docs/archive/" tests --glob "!**/node_modules/**"
98+
rg -n "docs/archive/" --glob "*.json" --glob "*.yml" --glob "*.yaml" --glob "!**/node_modules/**"
99+
```
100+
Result:
101+
- No test references found.
102+
- No JSON/YAML config references found.
103+
104+
## 4) Path Assumptions That Block Safe Move/Delete
105+
1. Documentation contracts currently encode specific archive destinations:
106+
- `docs/archive/dev-ops/`
107+
- `docs/archive/generated-reports/`
108+
- `docs/archive/pr/legacy-pr-history/`
109+
2. Cleanup governance artifacts already track `docs/archive/` as a retained policy target.
110+
3. Existing archive-cleanup plan/build specs depend on the exact archive destination path for manifest-based movement and rollback.
111+
4. Moving/deleting archive paths would require synchronized updates across multiple docs governance surfaces to avoid broken navigation/policy references.
112+
113+
## 5) Inventory Conclusion
114+
- `docs/archive/` is an active policy/structure target with live documentation references.
115+
- Current evidence supports a conservative keep/defer posture in this lane.
116+
- No movement, deletion, or rewrite action is justified in this BUILD.

‎docs/dev/reports/archived_notes_validation_guard.md‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
# Archived Notes Validation Guard
2+
3+
Generated: 2026-04-12
4+
Purpose: Define mandatory checks before any future PR can move/rename/delete archived notes content.
5+
6+
## A) Reference Scan Commands (Pre + Post)
7+
Run from repo root.
8+
9+
1. Active reference scan for archived notes path usage:
10+
```powershell
11+
rg -n "docs/archive/" docs tools src games samples tests --glob "!docs/archive/**" --glob "!**/node_modules/**"
12+
```
13+
14+
2. Docs-only reference scan (non-archive surfaces):
15+
```powershell
16+
rg -n "docs/archive/" docs --glob "!docs/archive/**"
17+
```
18+
19+
3. Optional classification assist for consumer file list:
20+
```powershell
21+
rg -l "docs/archive/" docs tools src games samples tests --glob "!docs/archive/**" --glob "!**/node_modules/**"
22+
```
23+
24+
## B) Structural Integrity Checks
25+
1. Confirm no accidental edits under archive tree in docs-only policy lanes:
26+
```powershell
27+
git status --short -- docs/archive
28+
```
29+
30+
2. Confirm no archive move/rename/delete in PR scope:
31+
```powershell
32+
git diff --name-status -- docs/archive
33+
```
34+
35+
3. Confirm no protected start_of_day changes:
36+
```powershell
37+
git status --short -- docs/dev/start_of_day/chatGPT docs/dev/start_of_day/codex
38+
```
39+
40+
## C) Validation Surfaces If Archive Movement Is Ever Attempted
41+
1. Documentation contract surfaces requiring synchronized updates:
42+
- `docs/README.md`
43+
- `docs/repo-directory-structure.md`
44+
- `docs/getting-started.md`
45+
- `docs/review-checklist.md`
46+
- `docs/dev/README.md`
47+
- `docs/dev/paths.md`
48+
- cleanup policy/report artifacts that reference archive paths
49+
50+
2. Governance surfaces:
51+
- `docs/dev/reports/cleanup_live_reference_inventory.txt`
52+
- `docs/dev/reports/cleanup_keep_move_future_delete_matrix.md`
53+
- `docs/dev/reports/repo_cleanup_targets.txt`
54+
- `docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md`
55+
56+
3. Recommended smoke run if movement lane also touches tooling/docs integrations:
57+
```powershell
58+
npm run test:launch-smoke -- --tools
59+
```
60+
61+
## D) Roadmap Check Rule (Only if Roadmap Is Modified)
62+
```powershell
63+
git diff --unified=0 -- docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md
64+
```
65+
Accept only bracket-state changes on exact existing lines.
66+
67+
## E) Blocking Failure Conditions
68+
Stop cleanup execution immediately if:
69+
- unresolved `docs/archive/` references remain without synchronized updates;
70+
- `docs/archive/` has move/delete/rename entries without explicit destination and rollback map;
71+
- protected start_of_day directories show any change;
72+
- roadmap requires wording rewrite (non bracket-only) to reflect status;
73+
- cleanup scope expands into unrelated targets (`templates`, `SpriteEditor_old_keep`, `classes_old_keep`, legacy import guard) in the same lane.
74+
75+
## Guard Summary
76+
No future archived-notes structural cleanup should proceed without full reference proof, synchronized docs updates, structural integrity checks, and rollback-ready execution evidence.

‎docs/dev/reports/change_summary.txt‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,4 @@
1-
- Added legacy import guard report
2-
- No structural repo changes
1+
- Replaces the prior non-executable APPLY step with a real Codex-run BUILD lane.
2+
- Narrows scope to one cleanup target only: archived notes policy.
3+
- Keeps the lane non-destructive and docs-only.
4+
- Leaves templates/, runtime code, and repo structure untouched.

‎docs/dev/reports/validation_checklist.txt‎

Lines changed: 28 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,28 @@
1-
[PASS] no deletion/move/rename
2-
[PASS] templates untouched
3-
[PASS] no runtime changes
4-
[PASS] guard report created
1+
BUILD_PR_TARGETED_REPO_CLEANUP_PASS_3_ARCHIVED_NOTES_POLICY
2+
Validation Checklist
3+
Generated: 2026-04-12
4+
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
7+
8+
[PASS] `docs/archive/` not moved/renamed/deleted
9+
Evidence: `git diff --name-status -- docs/archive` -> no entries
10+
11+
[PASS] `templates/` untouched
12+
Evidence: `git diff --name-status -- templates` -> no entries
13+
14+
[PASS] archived notes evidence reports created
15+
Evidence:
16+
- `docs/dev/reports/archived_notes_policy_inventory.md`
17+
- `docs/dev/reports/archived_notes_policy_decision.md`
18+
- `docs/dev/reports/archived_notes_validation_guard.md`
19+
- `docs/dev/reports/BUILD_PR_TARGETED_REPO_CLEANUP_PASS_3_ARCHIVED_NOTES_POLICY_report.md`
20+
21+
[PASS] no unrelated cleanup targets changed
22+
Evidence: changed files for this lane are archived-notes policy docs plus validation checklist only
23+
24+
[PASS] roadmap wording preserved if roadmap changed
25+
Evidence: `git diff --unified=0 -- docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md` -> no diff in this lane
26+
27+
[PASS] roadmap changes bracket-only if roadmap changed
28+
Evidence: N/A (roadmap unchanged)

0 commit comments

Comments
 (0)