Skip to content

Commit 2ac3097

Browse files
author
DavidQ
committed
Close Level 10 by combining sample/tool normalization, shared strategy finalization, and handoff
BUILD_PR_LEVEL_10_26_LEVEL_10_CLOSEOUT_SAMPLE_TOOL_NORMALIZATION_AND_SHARED_STRATEGY
1 parent 51386b2 commit 2ac3097

22 files changed

Lines changed: 566 additions & 55 deletions

‎docs/dev/CODEX_COMMANDS.md‎

Lines changed: 58 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -2,30 +2,62 @@ MODEL: GPT-5.4
22
REASONING: high
33

44
COMMAND:
5-
Create `BUILD_PR_LEVEL_10_25_POLISH_AND_EDGE_CASES`
6-
7-
1. Validate and polish the shared bezel/background system for edge cases:
8-
- bezel missing
9-
- bezel malformed
10-
- no valid transparency window
11-
- fullscreen enter/exit cycles
12-
- fullscreen resize
13-
- malformed or extreme override values
14-
- background missing
15-
- gameplay/non-gameplay transitions
16-
- starfield ordering regressions
17-
18-
2. Keep fixes surgical and minimal
19-
20-
3. Confirm shared code remains game-agnostic and works for:
21-
- Asteroids
22-
- games/_template
23-
- additional sample coverage already established
24-
25-
4. Final packaging step is REQUIRED:
26-
<project folder>/tmp/BUILD_PR_LEVEL_10_25_POLISH_AND_EDGE_CASES.zip
27-
28-
Rules:
5+
Create `BUILD_PR_LEVEL_10_26_LEVEL_10_CLOSEOUT_SAMPLE_TOOL_NORMALIZATION_AND_SHARED_STRATEGY` as the final combined Level 10 closeout PR.
6+
7+
Goal:
8+
Finish Level 10 with the fewest additional PRs by combining the remaining open section-10 work into one clean closeout.
9+
10+
Execute all of the following:
11+
12+
1. Level 10 closeout and handoff
13+
- validate Level 10 asset/data policy work across:
14+
- Asteroids
15+
- games/_template
16+
- at least one sample
17+
- at least one tool demo path
18+
- summarize results in the PR outputs
19+
20+
2. Sample asset ownership normalization
21+
- normalize sample asset ownership using the same ownership policy used for games
22+
- keep ownership local unless explicitly promoted
23+
- reduce ambiguous or duplicated sample asset placement where appropriate
24+
- keep changes surgical
25+
26+
3. Tool demo asset ownership normalization
27+
- normalize tool demo/demo-sample asset ownership under the same policy
28+
- keep demo assets local unless explicitly promoted
29+
- reduce ambiguous ownership and unnecessary duplication
30+
- preserve current tool-folder conventions
31+
32+
4. Promotion criteria enforcement
33+
- document and enforce explicit criteria for promoting an asset to shared status
34+
- no silent or convenience-based sharing
35+
36+
5. Final shared-asset strategy decision
37+
- explicitly finalize the top-level shared asset strategy if needed
38+
- if not needed, document local-first ownership with promotion-by-rule only
39+
- make this final enough to close the roadmap item
40+
41+
6. Asset duplication reduction
42+
- reduce clearly unnecessary duplication in the areas touched above
43+
- do not perform repo-wide churn
44+
- prefer targeted corrections
45+
46+
7. Roadmap handling
47+
- restore the correct full `docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md` from git history if it is not currently the full version
48+
- do NOT rewrite roadmap text
49+
- after validation, update status markers only for the section-10 items that are truly complete
50+
51+
8. Final validation
52+
- confirm whether all remaining section-10 items are now done
53+
- if any cannot truthfully be marked done, say so explicitly and leave only that item open
54+
55+
9. Final packaging step is REQUIRED
56+
- package ALL changed files into this exact repo-structured ZIP:
57+
`<project folder>/tmp/BUILD_PR_LEVEL_10_26_LEVEL_10_CLOSEOUT_SAMPLE_TOOL_NORMALIZATION_AND_SHARED_STRATEGY.zip`
58+
59+
Hard rules:
60+
- fewer PRs is the priority, so combine remaining Level 10 work here
61+
- keep changes surgical but sufficient to truly close Level 10 if validation supports it
2962
- no unrelated repo changes
30-
- no redesign
31-
- minimal corrections only
63+
- no missing ZIP

‎docs/dev/COMMIT_COMMENT.txt‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,2 @@
1-
Polish bezel/background system and close remaining Level 10 edge cases
2-
BUILD_PR_LEVEL_10_25_POLISH_AND_EDGE_CASES
1+
Close Level 10 by combining sample/tool normalization, shared strategy finalization, and handoff
2+
BUILD_PR_LEVEL_10_26_LEVEL_10_CLOSEOUT_SAMPLE_TOOL_NORMALIZATION_AND_SHARED_STRATEGY

‎docs/dev/NEXT_COMMAND.txt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
BUILD_PR_LEVEL_10_26_LEVEL_10_CLOSEOUT_AND_HANDOFF
1+
PLAN_PR_LEVEL_11_1_POST_LEVEL_10_HANDOFF_NEXT_PHASE

‎docs/dev/reports/asset_ownership_strategy_validation.txt‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
BUILD_PR_LEVEL_10_26 asset ownership strategy validation report
2+
3+
STATUS: PASS
4+
5+
Checks:
6+
- Strategy doc present: docs/specs/asset_ownership_strategy.md
7+
- Promotion registry present: docs/specs/shared_asset_promotion_registry.json
8+
- Validated game ownership manifest: games/Asteroids/assets/tools.manifest.json
9+
- Validated template ownership manifest: games/_template/assets/tools.manifest.json
10+
- Validated sample ownership path: samples/phase-15/1505/AssetBrowserScene.js
11+
- Validated tool demo ownership path: tools/shared/samples/project-asset-registry-demo/project.assets.json
12+
13+
Issues:
14+
- none

‎docs/dev/reports/change_summary.txt‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,3 @@
1-
- Added final Level 10 polish/edge-case PR
2-
- Focused on fullscreen cycles, malformed inputs, fallback behavior, and state transitions
3-
- Limited to surgical fixes only
1+
- Combined the remaining Level 10 work into one final closeout PR
2+
- Includes sample normalization, tool demo normalization, shared-asset strategy finalization, duplication reduction, and roadmap status closure
3+
- Designed specifically to minimize PR count while still finishing Level 10 cleanly

‎docs/dev/reports/validation_checklist.txt‎

Lines changed: 12 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,12 @@
1-
- Bezel missing-file case covered
2-
- Invalid transparency-window case covered
3-
- Fullscreen cycle case covered
4-
- Override malformed/extreme case covered
5-
- Background state-transition case covered
6-
- Shared code remains game-agnostic
1+
- Asteroids validated
2+
- games/_template validated
3+
- sample asset ownership normalized/validated
4+
- tool demo asset ownership normalized/validated
5+
- promotion criteria documented and enforced
6+
- shared asset strategy finalized
7+
- unnecessary duplication reduced in touched areas
8+
- full roadmap restored if needed
9+
- roadmap updated by status markers only
10+
- all remaining section-10 items either truthfully closed or explicitly called out
11+
- output ZIP created at:
12+
<project folder>/tmp/BUILD_PR_LEVEL_10_26_LEVEL_10_CLOSEOUT_SAMPLE_TOOL_NORMALIZATION_AND_SHARED_STRATEGY.zip

‎docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md‎

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -459,13 +459,13 @@
459459
---
460460

461461
## 10. Assets & Data Policy
462-
- [.] shared asset policy defined at planning level
463-
- [.] game asset ownership normalized
464-
- [ ] sample asset ownership normalized
465-
- [ ] tool demo asset ownership normalized
466-
- [ ] promotion criteria for shared assets enforced
467-
- [ ] asset duplication reduced
468-
- [ ] top-level shared asset strategy finalized if needed
462+
- [x] shared asset policy defined at planning level
463+
- [x] game asset ownership normalized
464+
- [x] sample asset ownership normalized
465+
- [x] tool demo asset ownership normalized
466+
- [x] promotion criteria for shared assets enforced
467+
- [x] asset duplication reduced
468+
- [x] top-level shared asset strategy finalized if needed
469469

470470
---
471471

‎docs/pr/BUILD_PR_LEVEL_10_26_LEVEL_10_CLOSEOUT_SAMPLE_TOOL_NORMALIZATION_AND_SHARED_STRATEGY.md‎

Lines changed: 166 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,166 @@
1+
# BUILD_PR_LEVEL_10_26_LEVEL_10_CLOSEOUT_SAMPLE_TOOL_NORMALIZATION_AND_SHARED_STRATEGY
2+
3+
## Purpose
4+
Close Level 10 in one combined PR by bundling the remaining open work into a single final handoff.
5+
6+
## Why this is combined
7+
The goal is to finish Level 10 with fewer PRs, not more.
8+
This PR combines:
9+
1. Level 10 closeout and handoff
10+
2. sample asset ownership normalization
11+
3. tool demo asset ownership normalization
12+
4. final shared-asset strategy decision and enforcement
13+
5. final status-only roadmap update after validation
14+
15+
## Targeted roadmap closure for section 10
16+
This PR is intended to close the remaining open items under:
17+
18+
## 10. Assets & Data Policy
19+
- [.] shared asset policy defined at planning level
20+
- [.] game asset ownership normalized
21+
- [ ] sample asset ownership normalized
22+
- [ ] tool demo asset ownership normalized
23+
- [ ] promotion criteria for shared assets enforced
24+
- [ ] asset duplication reduced
25+
- [ ] top-level shared asset strategy finalized if needed
26+
27+
## Scope
28+
29+
### A. Level 10 closeout and handoff
30+
Confirm the Level 10 lane is complete and stable across:
31+
- Asteroids
32+
- `games/_template`
33+
- samples
34+
- tool demos
35+
36+
Closeout must summarize:
37+
- conventions adopted
38+
- validations run
39+
- defects fixed
40+
- remaining risk, if any
41+
42+
### B. Sample asset ownership normalization
43+
Normalize sample asset ownership to the same policy used by games:
44+
- assets should live with the owning sample unless explicitly promoted
45+
- remove ambiguous ownership
46+
- reduce duplicated sample asset patterns where appropriate
47+
- align sample conventions with game/template conventions where it makes sense
48+
- do not perform broad destructive moves; keep changes surgical
49+
50+
### C. Tool demo asset ownership normalization
51+
Normalize tool demo assets using the same ownership rules:
52+
- demo assets stay with the tool/demo unless explicitly promoted
53+
- remove ambiguous shared/demo ownership
54+
- reduce duplication where appropriate
55+
- keep active tools under `tools/`
56+
- preserve repo conventions already established
57+
58+
### D. Promotion criteria for shared assets
59+
Finalize and enforce the rule for when an asset may become shared.
60+
61+
Required outcome:
62+
- explicit promotion criteria documented
63+
- promotion is intentional, not accidental
64+
- no silent sharing by convenience
65+
- ownership must be clear
66+
67+
### E. Top-level shared asset strategy finalization
68+
Make the final Level 10 decision on the top-level shared asset strategy.
69+
70+
Required outcome:
71+
- explicitly decide whether a top-level shared asset strategy is needed
72+
- if yes, define the boundary and promotion rule
73+
- if no, explicitly state local ownership first and promotion-by-rule only
74+
- document the decision clearly enough to support status closure
75+
76+
### F. Asset duplication reduction
77+
Use this PR to close the remaining duplication question in a controlled way:
78+
- remove or reduce duplication where it is clearly unnecessary
79+
- do not create risky wide-scope churn
80+
- prefer policy enforcement plus surgical fixes over mass movement
81+
82+
### G. Roadmap rule
83+
After validation:
84+
- restore the correct full `MASTER_ROADMAP_HIGH_LEVEL.md` if needed
85+
- update roadmap status markers only
86+
- no other roadmap text changes
87+
88+
## Expected Level 10 completion result
89+
This PR should allow section 10 to move to done, provided validation supports it.
90+
91+
## Validation requirements
92+
Codex must validate and summarize:
93+
- Asteroids remains correct
94+
- `_template` remains the convention source for new games
95+
- at least one sample is normalized/validated
96+
- at least one tool demo path is normalized/validated
97+
- shared promotion criteria are documented and enforced
98+
- duplication reductions are real and safe
99+
- roadmap updates are status-only
100+
101+
## Packaging requirement
102+
Codex must package all changed files into:
103+
`<project folder>/tmp/BUILD_PR_LEVEL_10_26_LEVEL_10_CLOSEOUT_SAMPLE_TOOL_NORMALIZATION_AND_SHARED_STRATEGY.zip`
104+
105+
## Scope guard
106+
- combine only what is needed to finish Level 10
107+
- no unrelated repo changes
108+
- prefer the smallest valid set of edits that closes the lane cleanly
109+
110+
## Implementation Delta
111+
- Added final local-first strategy + promotion-by-rule specification:
112+
- `docs/specs/asset_ownership_strategy.md`
113+
- `docs/specs/shared_asset_promotion_registry.json` (explicit registry, currently empty)
114+
- Added focused enforcement validator:
115+
- `scripts/validate-asset-ownership-strategy.mjs`
116+
- `tests/tools/AssetOwnershipStrategyCloseout.test.mjs`
117+
- wired into `tests/run-tests.mjs`
118+
- Normalized sample ownership path (`samples/phase-15/1505`):
119+
- updated `AssetBrowserScene.js` asset entries to explicit sample-local ownership paths
120+
- added owned sample assets:
121+
- `samples/phase-15/1505/assets/images/hero.png`
122+
- `samples/phase-15/1505/assets/audio/menu.mp3`
123+
- Normalized tool demo ownership path (`tools/shared/samples/project-asset-registry-demo`):
124+
- moved demo authored files under local demo `assets/` tree
125+
- updated project/demo references to explicit tool-demo-local ownership paths
126+
- added owned demo assets:
127+
- `tools/shared/samples/project-asset-registry-demo/assets/images/clouds-layer.svg`
128+
- `tools/shared/samples/project-asset-registry-demo/assets/tiles/overworld-main.png`
129+
- Reduced unnecessary duplication in touched scope:
130+
- `parallaxSources[].path` now points to local parallax source JSON instead of duplicating the image file path
131+
- removed ambiguous root-level placement for demo authored asset JSON files
132+
133+
## Level 10 Validation Coverage
134+
- Games:
135+
- Asteroids manifest ownership validated (`games/Asteroids/assets/tools.manifest.json`)
136+
- `_template` manifest ownership validated (`games/_template/assets/tools.manifest.json`)
137+
- Sample:
138+
- `samples/phase-15/1505` validated for local ownership pathing and existence
139+
- Tool demo:
140+
- `tools/shared/samples/project-asset-registry-demo/project.assets.json` validated for local ownership, existence, and dedupe guard
141+
- Shared runtime regressions (from prior Level 10 lane):
142+
- Asteroids bezel/background behavior still validated
143+
- `_template` contract checks still validated
144+
- additional sample regression (`SpaceInvaders`) still validated
145+
146+
## Roadmap Handling
147+
- Full roadmap version check: already full version (`639` lines), so no restore action was required.
148+
- Updated status markers only for section-10 items in `docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md`.
149+
- No roadmap prose rewrites were performed.
150+
151+
## Final Section-10 Status
152+
- Section-10 items are now marked complete based on validator-backed evidence.
153+
- Remaining open section-10 items after this PR: none.
154+
155+
## Validation Evidence (2026-04-14)
156+
- `node --check scripts/validate-asset-ownership-strategy.mjs` PASS
157+
- `node --check tests/tools/AssetOwnershipStrategyCloseout.test.mjs` PASS
158+
- `node --check samples/phase-15/1505/AssetBrowserScene.js` PASS
159+
- `node --check tests/run-tests.mjs` PASS
160+
- `node --check tools/shared/projectAssetRegistry.js` PASS
161+
- `validateAssetOwnershipStrategy` focused run PASS
162+
- `AssetOwnershipStrategyCloseout` test PASS
163+
- `BackgroundImageAndFullscreenBezel` focused run PASS
164+
- `AsteroidsPresentation` focused run PASS
165+
- `SpaceInvadersScene` focused run PASS
166+
- `GamesTemplateContractEnforcement` focused run PASS

‎docs/specs/asset_ownership_strategy.md‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
# Asset Ownership Strategy (Level 10 Closeout)
2+
3+
## Decision
4+
- Local-first ownership is the default strategy.
5+
- Assets stay with the owning surface:
6+
- games: `games/<gameId>/assets/...`
7+
- samples: `samples/<phase>/<sampleId>/assets/...`
8+
- tool demos: `tools/.../assets/...`
9+
- Shared ownership is promotion-by-rule only.
10+
11+
## Promotion Criteria (Required)
12+
An asset may be promoted to shared status only when all criteria are true:
13+
1. The asset is used by at least two independent owners.
14+
2. The asset has a stable identifier and stable format contract.
15+
3. The asset has an explicit owner handoff note with migration impact.
16+
4. The asset is added to the promotion registry at:
17+
- `docs/specs/shared_asset_promotion_registry.json`
18+
5. Validation passes with no unresolved ownership collisions.
19+
20+
## Enforcement Rules
21+
- No silent sharing by convenience pathing.
22+
- Cross-owner asset references are invalid unless registered in the promotion registry.
23+
- Tool demos do not claim game-owned assets by default.
24+
- Sample assets do not claim game/tool-owned assets by default.
25+
26+
## Scope Note
27+
- This strategy closes section-10 ownership policy by using local ownership as the default and explicit promotion criteria for shared exceptions.

‎docs/specs/shared_asset_promotion_registry.json‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
{
2+
"schema": "html-js-gaming.shared-asset-promotion-registry",
3+
"version": 1,
4+
"promotedAssets": []
5+
}

0 commit comments

Comments
 (0)