BUILD_PR_LEVEL_8_28_MANIFEST_SSOT_IMPLEMENTATION_ASTEROIDS_FIRST

- Added Asteroids-first game manifest SSoT plan
- Wired Asteroids palette/HUD/bezel requirements into manifest acceptance
- Kept legacy catalogs intact for parity review

PR Details:
- First concrete SSoT implementation pattern
- No broad all-games rollout
- No validators
- No start_of_day changes

Author: ToolboxAid

docs/dev/reports/expected_delta_template.md

@@ -1,18 +1,23 @@
 # Expected Codex Return / Delta Template
 
-## Expected Reports
-- `docs/dev/reports/level_8_26_manifest_ssot_audit.md`
-- `docs/dev/reports/level_8_26_unused_json_audit.md`
-- `docs/dev/reports/level_8_26_palette_alpha_normalization_report.md`
-- `docs/dev/reports/level_8_26_user_blockers.md`
+## Expected Changed/Added Files
+- `games/Asteroids/game.manifest.json`
+- `games/Asteroids/assets/palettes/asteroids-hud.palette.json` if HUD is converted to separate palette
+- `docs/dev/reports/level_8_28_asteroids_manifest_ssot_report.md`
+- `docs/dev/roadmaps/MASTER_ROADMAP_ENGINE.md` if status update needed
 
 ## Expected Validation Summary
-- `workspace_manifest_has_samples=<true|false>`
-- `manifest_ssot_conflicts=<count>`
-- `unwired_game_json_files=<count>`
-- `palette_hex_alpha_ff_normalized=<count>`
-- `deletion_candidates=<count>`
-- `deleted_files=<count, only if proven safe>`
+- `asteroids_game_manifest_exists=true`
+- `asteroids_bezel_override_wired=true`
+- `asteroids_main_palette_wired=true`
+- `asteroids_hud_data_typed=true`
+- `asteroids_unreferenced_json_after=<count>`
+- `legacy_catalogs_deleted=0`
 - `runtime_changes=0`
 - `validators_added=0`
 - `start_of_day_changes=0`
+
+## Expected Delta ZIP
+Codex must create:
+
+`tmp/BUILD_PR_LEVEL_8_28_MANIFEST_SSOT_IMPLEMENTATION_ASTEROIDS_FIRST_delta.zip`

docs/dev/reports/level_8_27_code_asset_extraction_audit.md

@@ -0,0 +1,108 @@
+# Level 8.27 Code Asset Extraction Audit
+
+## Scope
+Scanned game/sample source for code-defined content/data candidates that should be tool-owned JSON inputs.
+
+Scan targets:
+- `games/**/*.js`
+- `games/**/*.mjs`
+- `samples/**/*.js`
+- `samples/**/*.mjs`
+
+Pattern families audited:
+- color literals: `#RGB`, `#RRGGBB`, `#RRGGBBAA`, `rgb(...)`, `rgba(...)`
+- HUD color groups / palette-style objects
+- inline shape arrays / vector primitives / point lists
+- sprite frame arrays / tile arrays
+- primitive skin-like objects
+- parallax/layout/bezel-style inline data
+
+## Quantitative Findings
+- `files_scanned=850`
+- `files_with_hits=314`
+- `hex_hits=1614`
+- `rgb_hits=201`
+- `shape_array_defs=43`
+- `obj_data_defs=18`
+
+Top high-signal files:
+1. `games/SpaceInvaders/game/SpaceInvadersScene.js` (score 69)
+2. `games/Asteroids/game/AsteroidsGameScene.js` (score 38)
+3. `games/SpaceDuel/game/SpaceDuelScene.js` (score 36)
+4. `games/Pacman/game/PacmanFullAIScene.js` (score 26)
+5. `games/SolarSystem/game/SolarSystemWorld.js` (score 20)
+6. `games/Pong/game/PongScene.js` (score 14)
+7. `games/GravityWell/game/GravityWellWorld.js` (score 16)
+8. `samples/phase-02/0221/TilemapSystemScene.js` (inline tile/palette fallback)
+9. `samples/phase-02/0224/TileCameraSpriteSliceScene.js` (fallback tile/sprite color data)
+10. `samples/phase-12/1205/MultiSystemDemoScene.js` (tile/parallax inline color/layout data)
+
+## Required Category Coverage
+### Colors / HUD Colors
+Observed broadly in game/sample render loops and theme constants, especially:
+- `games/SpaceInvaders/game/SpaceInvadersScene.js`
+- `games/Asteroids/game/AsteroidsGameScene.js`
+- `games/SpaceDuel/game/SpaceDuelScene.js`
+- `games/Pong/game/PongScene.js`
+- `games/SolarSystem/game/SolarSystemScene.js`
+
+### Shape Arrays / Vector Primitives
+Observed in:
+- `games/SpaceDuel/game/SpaceDuelScene.js` (`*_SEGMENTS` arrays)
+- `games/GravityWell/game/GravityWellWorld.js` (`SHIP_SHAPE`, `BEACON_SHAPE`)
+- `games/Asteroids/game/AsteroidsGameScene.js` (`LIFE_ICON_POINTS`)
+
+### Sprite / Tile Arrays
+Observed in:
+- `games/SpaceInvaders/game/SpaceInvadersSpriteData.js` (bitmap frame arrays)
+- `samples/phase-02/0221/TilemapSystemScene.js` (inline tile rows fallback)
+- `samples/phase-02/0224/TileCameraSpriteSliceScene.js` (tile fallback rows)
+
+### Primitive Skin Objects
+Observed as default skin/data objects in world/scene code:
+- `games/Breakout/game/BreakoutWorld.js`
+- `games/Pong/game/PongScene.js`
+- `games/SolarSystem/game/SolarSystemWorld.js`
+
+### Parallax / Layout / Bezel Data
+Observed in:
+- `samples/phase-12/1205/MultiSystemDemoScene.js` (parallax layer layout/color)
+- `games/AITargetDummy/game/AITargetDummyController.js` (waypoint layout)
+- Asteroids asset-side overrides present but not fully wired as runtime SSoT:
+  - `games/Asteroids/assets/images/bezel.stretch.override.json`
+  - `games/Asteroids/assets/palettes/hud.json`
+
+## Safe Extraction Decision (This PR)
+Extraction criteria required all of:
+1. owning schema exists
+2. target JSON path obvious
+3. wiring path already exists
+4. no runtime rewrite beyond tiny manifest/input reference
+
+Result:
+- `candidates_meeting_all_criteria=0`
+- `extracted_candidates=0`
+- `unreferenced_extracted_json=0`
+
+Primary blockers preventing safe extraction now:
+- many candidates require runtime loader changes (scene/world code directly consumes inline constants)
+- several targets lack an already-active manifest/input hook for the specific data type
+- some game skins/palettes exist but inline constants still act as required runtime defaults (removal would change behavior)
+
+## Existing Partial Wiring Noted
+Games already using `loadGameSkin(...)` in main boot:
+- `games/Bouncing-ball/main.js`
+- `games/Pong/main.js`
+- `games/SolarSystem/main.js`
+- `games/Breakout/main.js`
+
+This reduces future extraction risk for skin-color/sizing constants in those games.
+
+## Palette Normalization Check
+No newly extracted palettes were created in this PR.
+(Existing palette normalization from prior PRs remains intact.)
+
+## Constraints Check
+- no runtime rewrite performed
+- no validators added
+- no `start_of_day` changes

docs/dev/reports/level_8_27_extraction_candidate_matrix.md

@@ -0,0 +1,30 @@
+# Level 8.27 Extraction Candidate Matrix
+
+| Source File | Hardcoded Data | Type | Proposed Tool Owner | Proposed JSON Path | Safe To Extract Now |
+|---|---|---|---|---|---|
+| `games/SpaceInvaders/game/SpaceInvadersScene.js` | dozens of HUD/render colors (`#66ff66`, `#ffffff`, overlay rgba) | HUD colors / palette groups | Palette Browser + `tools/schemas/palette.schema.json` | `games/SpaceInvaders/assets/palettes/space-invaders-hud.palette.json` | No |
+| `games/SpaceInvaders/game/SpaceInvadersSpriteData.js` | bitmap frame arrays (`SQUID_LIVING_FRAMES`, `PLAYER_DYING_FRAMES`, etc.) | sprite frame arrays | Sprite Editor + `tools/schemas/tools/sprite-editor.schema.json` | `games/SpaceInvaders/assets/sprites/space-invaders.sprite-sheet.json` | No |
+| `games/SpaceDuel/game/SpaceDuelScene.js` | `SHIP_SEGMENTS`, `ENEMY_*_SEGMENTS`, `HAZARD_SEGMENTS`, `SHOT_SEGMENTS` | vector primitives / shape arrays | Vector Asset Studio + `tools/schemas/tools/vector-asset-studio.schema.json` | `games/SpaceDuel/assets/vectors/space-duel-shapes.vector.json` | No |
+| `games/SpaceDuel/game/SpaceDuelScene.js` | `COLORS` object (`background`, `player1`, `enemy`, etc.) | HUD/skin colors | Palette Browser + `tools/schemas/palette.schema.json` | `games/SpaceDuel/assets/palettes/space-duel-hud.palette.json` | No |
+| `games/Asteroids/game/AsteroidsGameScene.js` | `LIFE_ICON_POINTS`, pause/initials overlay colors | HUD layout + HUD colors | overlay/bezel manifest ref + palette schema | `games/Asteroids/assets/images/bezel.stretch.override.json` and `games/Asteroids/assets/palettes/hud.json` | No |
+| `games/AITargetDummy/game/AITargetDummyController.js` | normalized waypoint list (`this.waypoints`) | layout/path points | Vector Map Editor + `tools/schemas/tools/vector-map-editor.schema.json` | `games/AITargetDummy/assets/layout/ai-waypoints.map.json` | No |
+| `games/GravityWell/game/GravityWellWorld.js` | `SHIP_SHAPE`, `BEACON_SHAPE` arrays | vector primitives | Vector Asset Studio + `tools/schemas/tools/vector-asset-studio.schema.json` | `games/GravityWell/assets/vectors/gravitywell-shapes.vector.json` | No |
+| `games/GravityWell/game/GravityWellWorld.js` | `DEFAULT_PLANETS`, `DEFAULT_BEACONS` with color/radius/strength | primitive skin + palette-like data | Primitive Skin Editor + palette schema | `games/GravityWell/assets/skins/skin.main.json` + `games/GravityWell/assets/palettes/gravitywell-classic.palette.json` | No |
+| `games/SolarSystem/game/SolarSystemWorld.js` | `BODY_DEFINITIONS`, `MOON_DEFINITIONS`, default sun/ring skin values | primitive skin object + layout constants | Primitive Skin Editor + `tools/schemas/tools/skin-editor.schema.json` | `games/SolarSystem/assets/skins/skin.main.json` (already present; partial parity) | No |
+| `games/SolarSystem/game/SolarSystemScene.js` | `DEFAULT_COLORS` object | HUD colors | Primitive Skin Editor / palette schema | `games/SolarSystem/assets/skins/skin.main.json` (already present; fallback still hardcoded) | No |
+| `games/Pong/game/PongScene.js` | `DEFAULT_COLORS`, `DEFAULT_SIZING` | primitive skin object | Primitive Skin Editor + `tools/schemas/tools/skin-editor.schema.json` | `games/pong/assets/skins/skin.main.json` (already present; fallback still hardcoded) | No |
+| `games/Pong/game/PongWorld.js` | `PONG_MODE_LIST` (`accent`, `arenaColor`, mode shape/sizing) | gameplay mode config + color data | skin/palette for color subset; no clear existing mode schema | `games/pong/assets/modes/pong.modes.json` (new) | No |
+| `games/Breakout/game/BreakoutWorld.js` | `DEFAULT_BRICK_COLORS`, `DEFAULT_BREAKOUT_SKIN` | primitive skin + brick palette | Primitive Skin Editor + palette schema | `games/breakout/assets/skins/skin.main.json` (already present; fallback still hardcoded) | No |
+| `samples/phase-02/0221/TilemapSystemScene.js` | inline fallback `tiles` rows + `palette` map | tile arrays + tile palette | Tilemap Studio + `tools/schemas/tools/tile-map-editor.schema.json` | `samples/phase-02/0221/sample-0221-tile-map-editor.json` / `sample.0221.tile-map-editor.json` (already consumed path exists) | No |
+| `samples/phase-02/0224/TileCameraSpriteSliceScene.js` | `FALLBACK_TILEMAP_ROWS`, fallback atlas frame colors | tile + sprite fallback data | Tilemap Studio + Sprite Editor schemas | `samples/phase-02/0224/sample-0224-tile-map-editor.json` and `sample-0224-sprite-editor.json` (already consumed path exists) | No |
+| `samples/phase-03/0301/demoSpriteFactory.js` | hardcoded frame palettes (`body`, `accent`, `visor`, `boots`) | sprite color presets | Sprite Editor + palette schema | `samples/phase-03/0301/sample.0301.palette.json` + sprite payload | No |
+| `samples/phase-12/1205/MultiSystemDemoScene.js` | tile palette object + parallax layer color/layout data | tile/parallax layout + colors | Tilemap Studio + Parallax Scene Studio schemas | `samples/phase-12/1205/sample.1205.tile-map-editor.json` and `sample.1205.parallax-editor.json` | No |
+
+## Safe/Defer Rationale
+All listed candidates were deferred in this PR because at least one required extraction criterion failed (most commonly missing active wiring path or requiring scene/runtime code rewrite beyond tiny manifest/input ref).
+
+Summary:
+- `safe_to_extract_now_yes=0`
+- `safe_to_extract_now_no=17`
+- `extracted_in_this_pr=0`
+- `unreferenced_extracted_json=0`

docs/dev/reports/level_8_28_asteroids_manifest_ssot_report.md

@@ -0,0 +1,61 @@
+# Level 8.28 Asteroids Manifest SSoT Report
+
+## Source Files Read
+- `docs/pr/PLAN_PR_LEVEL_8_28_MANIFEST_SSOT_IMPLEMENTATION_ASTEROIDS_FIRST.md`
+- `docs/pr/BUILD_PR_LEVEL_8_28_MANIFEST_SSOT_IMPLEMENTATION_ASTEROIDS_FIRST.md`
+- `games/Asteroids/assets/workspace.asset-catalog.json`
+- `games/Asteroids/assets/tools.manifest.json`
+- `games/Asteroids/assets/palettes/asteroids-classic.palette.json`
+- `games/Asteroids/assets/palettes/hud.json`
+- `games/Asteroids/assets/images/bezel.stretch.override.json`
+
+## SSoT Output
+- Created `games/Asteroids/game.manifest.json` as Asteroids-first manifest SSoT.
+- Preserved legacy catalogs:
+  - `games/Asteroids/assets/workspace.asset-catalog.json`
+  - `games/Asteroids/assets/tools.manifest.json`
+
+## Assets Wired In `games/Asteroids/game.manifest.json`
+- Palettes:
+  - `games/Asteroids/assets/palettes/asteroids-classic.palette.json`
+  - `games/Asteroids/assets/palettes/asteroids-hud.palette.json` (new typed HUD palette)
+- Legacy HUD compatibility path:
+  - `games/Asteroids/assets/palettes/hud.json` (retained as typed legacy palette path)
+- Bezel override:
+  - `games/Asteroids/assets/images/bezel.stretch.override.json`
+- Tool/runtime lineage from legacy `tools.manifest.json`:
+  - Sprites: `games/Asteroids/assets/sprites/demo.json`, `games/Asteroids/assets/sprites/data/demo.data.json`
+  - Tilemaps: `games/Asteroids/assets/tilemaps/stage.json`, `games/Asteroids/assets/tilemaps/data/stage.data.json`
+  - Parallax: `games/Asteroids/assets/parallax/title.json`, `games/Asteroids/assets/parallax/overlay.json`, `games/Asteroids/assets/parallax/data/title.data.json`, `games/Asteroids/assets/parallax/data/overlay.data.json`
+  - Vectors: `games/Asteroids/assets/vectors/ship.json`, `games/Asteroids/assets/vectors/asteroid-large.json`, `games/Asteroids/assets/vectors/asteroid-medium.json`, `games/Asteroids/assets/vectors/asteroid-small.json`, `games/Asteroids/assets/vectors/title.json`, `games/Asteroids/assets/vectors/data/library.data.json`
+  - Tileset: `games/Asteroids/assets/tilesets/ui.json`
+- Workspace asset-catalog lineage:
+  - Audio assets from `workspace.asset-catalog.json`
+  - Bezel image `games/Asteroids/assets/images/bezel.png`
+
+## HUD Conversion Decision
+- `hud.json` contained loose untyped color data.
+- Implemented typed conversion by creating:
+  - `games/Asteroids/assets/palettes/asteroids-hud.palette.json` using `palette.schema.json`.
+- Retained `games/Asteroids/assets/palettes/hud.json` for compatibility, but converted it to typed palette-schema format and marked legacy via `source: "legacy-compatibility"` and `sourceId`.
+
+## Palette Normalization
+- Normalized HUD colors from `#RRGGBBFF` to `#RRGGBB` in both:
+  - `games/Asteroids/assets/palettes/asteroids-hud.palette.json`
+  - `games/Asteroids/assets/palettes/hud.json`
+- Non-`FF` alpha cases were not present in HUD source data.
+
+## Unreferenced Asteroids JSON After Migration
+- Verified all Asteroids asset JSON files are referenced by `games/Asteroids/game.manifest.json`.
+- `asteroids_asset_json_files=21`
+- `manifest_referenced_asset_json=21`
+- `asteroids_unreferenced_json_after=0`
+
+## Legacy Catalog Deprecation Readiness
+- Old catalogs are still intact and readable.
+- With `game.manifest.json` now owning Asteroids SSoT references, old catalogs can be treated as legacy/derived inputs in follow-up migration PRs.
+
+## Constraints Check
+- `runtime_changes=0`
+- `validators_added=0`
+- `start_of_day_changes=0`

docs/dev/roadmaps/MASTER_ROADMAP_ENGINE.md

@@ -880,5 +880,9 @@
 - [ ] Verify palette/shared data never embeds inside tool payload files.
 - [.] Verify workspace schema has no sample-only concepts.
 - [.] Manifest SSoT audit across game workspace catalogs/tool manifests is in progress.
+- [x] Asteroids-first `game.manifest.json` SSoT example implemented (palette + HUD typing + bezel override wiring).
 - [.] Unused JSON cleanup audit (tools + explicit deletion candidates) is in progress.
 - [.] Palette opaque alpha normalization (`#RRGGBBFF` -> `#RRGGBB`) is in progress.
+- [x] Code-defined asset extraction audit across games/samples is complete.
+- [.] Tool-owned JSON asset input wiring for extracted code-defined assets is in progress.
+- [.] Hardcoded color/shape removal plan is in progress.

docs/operations/dev/codex_commands.md

@@ -2,58 +2,45 @@ MODEL: GPT-5.3-codex
 REASONING: high
 
 TASK:
-Apply BUILD_PR_LEVEL_8_26_MANIFEST_SSOT_AND_UNUSED_JSON_AUDIT.
-
-IMPORTANT:
-This is an audit/cleanup PR. Do not do broad UI rewrites. Do not remove files unless proven unused by import/reference/script/doc/test search.
+Apply BUILD_PR_LEVEL_8_28_MANIFEST_SSOT_IMPLEMENTATION_ASTEROIDS_FIRST.
 
 STEPS:
-1. Read docs/pr/PLAN_PR_LEVEL_8_26_MANIFEST_SSOt_AND_UNUSED_JSON_AUDIT.md.
-2. Read docs/pr/BUILD_PR_LEVEL_8_26_MANIFEST_SSOt_AND_UNUSED_JSON_AUDIT.md.
-3. Create/update docs/dev/reports/level_8_26_user_blockers.md with all blocker questions and decisions.
-4. Audit root files:
-   - workspace.manifest.json
-   - package.json
-   - package-lock.json
-5. Confirm package.json/package-lock.json root purpose in report; do not move them.
-6. Audit manifest SSoT conflicts:
-   - games/**/assets/tools.manifest.json
-   - games/**/assets/workspace.asset-catalog.json
-   - game/workspace project JSON
-7. For each game, report:
-   - referenced JSON assets
-   - unreferenced JSON assets
-   - duplicate/overlapping references
-   - proposed SSoT target
-8. Specifically audit Asteroids:
-   - games/Asteroids/assets/images/bezel.stretch.override.json
+1. Read docs/pr/PLAN_PR_LEVEL_8_28_MANIFEST_SSOT_IMPLEMENTATION_ASTEROIDS_FIRST.md.
+2. Read docs/pr/BUILD_PR_LEVEL_8_28_MANIFEST_SSOT_IMPLEMENTATION_ASTEROIDS_FIRST.md.
+3. Inspect:
+   - games/Asteroids/assets/workspace.asset-catalog.json
+   - games/Asteroids/assets/tools.manifest.json
    - games/Asteroids/assets/palettes/asteroids-classic.palette.json
    - games/Asteroids/assets/palettes/hud.json
-9. Normalize palette swatch hex:
+   - games/Asteroids/assets/images/bezel.stretch.override.json
+4. Create or normalize:
+   - games/Asteroids/game.manifest.json
+5. Preserve existing asset data. Do not delete old catalogs.
+6. Ensure game.manifest.json references:
+   - asteroids-classic.palette.json
+   - bezel.stretch.override.json
+   - HUD palette/skin data after conversion
+   - existing referenced vector/sprite/tilemap/parallax JSON assets
+7. If hud.json is color data:
+   - convert to palette schema as games/Asteroids/assets/palettes/asteroids-hud.palette.json
+   - do not leave hud.json as loose untyped color data
+   - if retaining hud.json for compatibility, mark legacy in report
+8. Normalize palette colors:
    - #RRGGBBFF -> #RRGGBB
-   - keep #RRGGBBAA when AA != FF
-10. Audit deletion candidates:
-   - tools/codex/sample_maaping_example.json
-   - tools/dev/checkPhase24*
-   - tools/dev/checkSharedExt*.json
-   - tools/samples/*
-   - tools/shared/samples/*
-   - other unused JSON under tools/
-11. Delete only if unused by imports, scripts, docs, tests, samples, games, and tool registry references.
-12. Add a follow-up plan for removing sample dropdown/selects from tools and migrating any tool-local samples to /samples/phase-*.
-13. Update docs/dev/roadmaps/MASTER_ROADMAP_ENGINE.md status only:
-   - [ ] -> [.] or [.] -> [x] only
-   - no prose rewrite/delete
-14. Do not modify runtime code unless only manifest wiring of existing data is required and safe.
-15. Do not add validators.
-16. Do not modify start_of_day.
-17. Return a delta ZIP at:
-   tmp/BUILD_PR_LEVEL_8_26_MANIFEST_SSOt_AND_UNUSED_JSON_AUDIT_delta.zip
+   - preserve non-FF alpha
+9. Write docs/dev/reports/level_8_28_asteroids_manifest_ssot_report.md.
+10. Update docs/dev/roadmaps/MASTER_ROADMAP_ENGINE.md status only:
+    - [ ] -> [.] or [.] -> [x]
+    - no prose rewrite/delete
+11. Do not add validators.
+12. Do not modify start_of_day.
+13. Avoid runtime code changes unless only a safe manifest input reference is required.
+14. Create Codex delta ZIP:
+    tmp/BUILD_PR_LEVEL_8_28_MANIFEST_SSOT_IMPLEMENTATION_ASTEROIDS_FIRST_delta.zip
 
 ACCEPTANCE:
-- User blockers captured.
-- Manifest SSoT audit complete.
-- Unused JSON audit complete.
-- Palette alpha normalization complete or zero-change reported.
-- No runtime rewrite.
-- No start_of_day changes.
+- asteroids_game_manifest_exists=true
+- asteroids_bezel_override_wired=true
+- asteroids_hud_data_typed=true
+- old catalogs intact
+- no validators/start_of_day changes

docs/operations/dev/commit_comment.txt

@@ -1,12 +1,11 @@
-BUILD_PR_LEVEL_8_26_MANIFEST_SSOT_AND_UNUSED_JSON_AUDIT
+BUILD_PR_LEVEL_8_28_MANIFEST_SSOT_IMPLEMENTATION_ASTEROIDS_FIRST
 
-- Added user blocker list for manifest SSoT, game asset wiring, palette normalization, and unused JSON cleanup
-- Added audit requirements for tools.manifest.json vs workspace.asset-catalog.json
-- Added deletion candidate audit scope
-- Added palette opaque alpha normalization rule
+- Added Asteroids-first game manifest SSoT plan
+- Wired Asteroids palette/HUD/bezel requirements into manifest acceptance
+- Kept legacy catalogs intact for parity review
 
 PR Details:
-- Focused audit/cleanup PR
-- No runtime rewrite intended
+- First concrete SSoT implementation pattern
+- No broad all-games rollout
 - No validators
 - No start_of_day changes