Level 09.02 — normalize asset ownership by moving owner-specific platform assets under owning game/sample/tool assets

Author: DavidQ

docs/dev/CODEX_COMMANDS.md

@@ -2,13 +2,5 @@
 REASONING: high
 
 COMMAND GOAL:
-Create BUILD_PR_LEVEL_09_01_FLOW_RULES_VS_FLOW_CONTENT_SPLIT as a repo-wide docs-first implementation
-bundle that separates behavioral flow rules from player-facing flow content across all games.
-
-CONSTRAINTS:
-- one PR purpose only
-- preserve behavior exactly
-- no engine changes
-- no launcher changes
-- no config migration in this PR
-- only split existing flow-related rules/content
+Create BUILD_PR_LEVEL_09_02_ASSET_OWNERSHIP_NORMALIZATION as a docs-first, repo-structured bundle
+that corrects owner-specific asset placement across games, samples, and tools.

docs/dev/COMMIT_COMMENT.txt

@@ -1 +1 @@
-build(games): split flow behavior rules vs flow content across game rules surfaces
+build(assets): normalize owner-specific platform asset placement under owner assets roots

docs/dev/reports/change_summary.txt

@@ -1,37 +1,34 @@
-BUILD_PR_LEVEL_09_01_FLOW_RULES_VS_FLOW_CONTENT_SPLIT
+BUILD_PR_LEVEL_09_02_ASSET_OWNERSHIP_NORMALIZATION
 
-What changed
-- Added rules split modules per game: rules/flowRules.js and rules/flowContent.js.
-- Converted rules/gameFlowRules.js into a compatibility shim re-exporting flowRules + flowContent.
-- Updated flow/ and game/ import consumers to read behavior constants from flowRules and player-facing text from flowContent.
+Moved owner-specific asset payloads
+games/Asteroids/platform/assets/palettes/asteroids-hud.palette.json => games/Asteroids/assets/platform/palettes/asteroids-hud.palette.json
+games/Asteroids/platform/assets/parallax/asteroids-overlay.parallax.json => games/Asteroids/assets/platform/parallax/asteroids-overlay.parallax.json
+games/Asteroids/platform/assets/parallax/asteroids-title.parallax.json => games/Asteroids/assets/platform/parallax/asteroids-title.parallax.json
+games/Asteroids/platform/assets/sprites/asteroids-demo.sprite.json => games/Asteroids/assets/platform/sprites/asteroids-demo.sprite.json
+games/Asteroids/platform/assets/tilemaps/asteroids-stage.tilemap.json => games/Asteroids/assets/platform/tilemaps/asteroids-stage.tilemap.json
+games/Asteroids/platform/assets/tilesets/asteroids-ui.tileset.json => games/Asteroids/assets/platform/tilesets/asteroids-ui.tileset.json
+games/Asteroids/platform/assets/vectors/asteroids-asteroid-large.vector.json => games/Asteroids/assets/platform/vectors/asteroids-asteroid-large.vector.json
+games/Asteroids/platform/assets/vectors/asteroids-asteroid-medium.vector.json => games/Asteroids/assets/platform/vectors/asteroids-asteroid-medium.vector.json
+games/Asteroids/platform/assets/vectors/asteroids-asteroid-small.vector.json => games/Asteroids/assets/platform/vectors/asteroids-asteroid-small.vector.json
+games/Asteroids/platform/assets/vectors/asteroids-ship.vector.json => games/Asteroids/assets/platform/vectors/asteroids-ship.vector.json
+games/Asteroids/platform/assets/vectors/asteroids-title.vector.json => games/Asteroids/assets/platform/vectors/asteroids-title.vector.json
 
-Classification applied
-- behavior/timing/mode/contract/booleans/selectors => flowRules.js
-- visible flow text/prompts/headings/labels => flowContent.js
+Updated references in active surfaces
+- tools/Asset Browser/main.js
+- tools/shared/asteroidsPlatformDemo.js
+- tools/shared/vectorAssetSystem.js
+- tools/templates/starter-project-template/README.md
+- tools/templates/starter-project-template/config/starter.project.json
+- tests/tools/VectorAssetSystem.test.mjs
+- docs/specs/asset_usage_contract.md
 
-Behavior preservation
-- No engine files changed.
-- No launcher/bootstrap changes.
-- No config migration included.
-- Split is extraction-only; constants remain same values.
+Classification result
+- Game-owned moved: Asteroids platform asset payloads
+- Sample-owned moved: none found
+- Tool-owned moved: none found
+- Truly shared assets requiring retention outside owner roots: none found in scanned owner scopes
 
-Games affected: 19
-- AITargetDummy
-- Asteroids
-- Bouncing-ball
-- Breakout
-- Gravity
-- GravityWell
-- MultiBallChaos
-- Orbit
-- PacmanFullAI
-- PacmanLite
-- PaddleIntercept
-- Pong
-- ProjectileLab
-- Puckman
-- SolarSystem
-- SpaceDuel
-- SpaceInvaders
-- Thruster
-- vector-arcade-sample
+Out-of-scope preserved
+- no platform/runtime code moved
+- no engine abstractions moved
+- no shared infrastructure code moved

docs/dev/reports/file_tree.txt

@@ -1,121 +1,23 @@
-Flow Rules vs Content Split Tree
+Asset Ownership Normalization - File Tree (Changed)
 
-games/AITargetDummy/rules/flowRules.js
-games/AITargetDummy/rules/flowContent.js
-games/AITargetDummy/rules/gameFlowRules.js
-games/Asteroids/rules/flowRules.js
-games/Asteroids/rules/flowContent.js
-games/Asteroids/rules/gameFlowRules.js
-games/Bouncing-ball/rules/flowRules.js
-games/Bouncing-ball/rules/flowContent.js
-games/Bouncing-ball/rules/gameFlowRules.js
-games/Breakout/rules/flowRules.js
-games/Breakout/rules/flowContent.js
-games/Breakout/rules/gameFlowRules.js
-games/Gravity/rules/flowRules.js
-games/Gravity/rules/flowContent.js
-games/Gravity/rules/gameFlowRules.js
-games/GravityWell/rules/flowRules.js
-games/GravityWell/rules/flowContent.js
-games/GravityWell/rules/gameFlowRules.js
-games/MultiBallChaos/rules/flowRules.js
-games/MultiBallChaos/rules/flowContent.js
-games/MultiBallChaos/rules/gameFlowRules.js
-games/Orbit/rules/flowRules.js
-games/Orbit/rules/flowContent.js
-games/Orbit/rules/gameFlowRules.js
-games/PacmanFullAI/rules/flowRules.js
-games/PacmanFullAI/rules/flowContent.js
-games/PacmanFullAI/rules/gameFlowRules.js
-games/PacmanLite/rules/flowRules.js
-games/PacmanLite/rules/flowContent.js
-games/PacmanLite/rules/gameFlowRules.js
-games/PaddleIntercept/rules/flowRules.js
-games/PaddleIntercept/rules/flowContent.js
-games/PaddleIntercept/rules/gameFlowRules.js
-games/Pong/rules/flowRules.js
-games/Pong/rules/flowContent.js
-games/Pong/rules/gameFlowRules.js
-games/ProjectileLab/rules/flowRules.js
-games/ProjectileLab/rules/flowContent.js
-games/ProjectileLab/rules/gameFlowRules.js
-games/Puckman/rules/flowRules.js
-games/Puckman/rules/flowContent.js
-games/Puckman/rules/gameFlowRules.js
-games/SolarSystem/rules/flowRules.js
-games/SolarSystem/rules/flowContent.js
-games/SolarSystem/rules/gameFlowRules.js
-games/SpaceDuel/rules/flowRules.js
-games/SpaceDuel/rules/flowContent.js
-games/SpaceDuel/rules/gameFlowRules.js
-games/SpaceInvaders/rules/flowRules.js
-games/SpaceInvaders/rules/flowContent.js
-games/SpaceInvaders/rules/gameFlowRules.js
-games/Thruster/rules/flowRules.js
-games/Thruster/rules/flowContent.js
-games/Thruster/rules/gameFlowRules.js
-games/vector-arcade-sample/rules/flowRules.js
-games/vector-arcade-sample/rules/flowContent.js
-games/vector-arcade-sample/rules/gameFlowRules.js
+games/Asteroids/assets/platform/
+  palettes/asteroids-hud.palette.json
+  parallax/asteroids-overlay.parallax.json
+  parallax/asteroids-title.parallax.json
+  sprites/asteroids-demo.sprite.json
+  tilemaps/asteroids-stage.tilemap.json
+  tilesets/asteroids-ui.tileset.json
+  vectors/asteroids-asteroid-large.vector.json
+  vectors/asteroids-asteroid-medium.vector.json
+  vectors/asteroids-asteroid-small.vector.json
+  vectors/asteroids-ship.vector.json
+  vectors/asteroids-title.vector.json
 
-Updated import consumers:
-games\AITargetDummy\flow\attract.js
-games\AITargetDummy\flow\highscore.js
-games\AITargetDummy\flow\intro.js
-games\Asteroids\flow\attract.js
-games\Asteroids\flow\highscore.js
-games\Asteroids\flow\intro.js
-games\Asteroids\game\AsteroidsGameScene.js
-games\Bouncing-ball\flow\attract.js
-games\Bouncing-ball\flow\highscore.js
-games\Bouncing-ball\flow\intro.js
-games\Breakout\flow\attract.js
-games\Breakout\flow\highscore.js
-games\Breakout\flow\intro.js
-games\Gravity\flow\attract.js
-games\Gravity\flow\highscore.js
-games\Gravity\flow\intro.js
-games\GravityWell\flow\attract.js
-games\GravityWell\flow\highscore.js
-games\GravityWell\flow\intro.js
-games\MultiBallChaos\flow\attract.js
-games\MultiBallChaos\flow\highscore.js
-games\MultiBallChaos\flow\intro.js
-games\Orbit\flow\attract.js
-games\Orbit\flow\highscore.js
-games\Orbit\flow\intro.js
-games\PacmanFullAI\flow\attract.js
-games\PacmanFullAI\flow\highscore.js
-games\PacmanFullAI\flow\intro.js
-games\PacmanLite\flow\attract.js
-games\PacmanLite\flow\highscore.js
-games\PacmanLite\flow\intro.js
-games\PaddleIntercept\flow\attract.js
-games\PaddleIntercept\flow\highscore.js
-games\PaddleIntercept\flow\intro.js
-games\Pong\flow\attract.js
-games\Pong\flow\highscore.js
-games\Pong\flow\intro.js
-games\ProjectileLab\flow\attract.js
-games\ProjectileLab\flow\highscore.js
-games\ProjectileLab\flow\intro.js
-games\Puckman\flow\attract.js
-games\Puckman\flow\highscore.js
-games\Puckman\flow\intro.js
-games\Puckman\game\PuckmanGameScene.js
-games\Puckman\game\PuckmanRuntime.js
-games\SolarSystem\flow\attract.js
-games\SolarSystem\flow\highscore.js
-games\SolarSystem\flow\intro.js
-games\SpaceDuel\flow\attract.js
-games\SpaceDuel\flow\highscore.js
-games\SpaceDuel\flow\intro.js
-games\SpaceInvaders\flow\attract.js
-games\SpaceInvaders\flow\highscore.js
-games\SpaceInvaders\flow\intro.js
-games\Thruster\flow\attract.js
-games\Thruster\flow\highscore.js
-games\Thruster\flow\intro.js
-games\vector-arcade-sample\flow\attract.js
-games\vector-arcade-sample\flow\highscore.js
-games\vector-arcade-sample\flow\intro.js
+Reference updates
+- tools/Asset Browser/main.js
+- tools/shared/asteroidsPlatformDemo.js
+- tools/shared/vectorAssetSystem.js
+- tools/templates/starter-project-template/README.md
+- tools/templates/starter-project-template/config/starter.project.json
+- tests/tools/VectorAssetSystem.test.mjs
+- docs/specs/asset_usage_contract.md

docs/dev/reports/validation_checklist.txt

@@ -1,20 +1,43 @@
-BUILD_PR_LEVEL_09_01_FLOW_RULES_VS_FLOW_CONTENT_SPLIT - Validation Checklist
+BUILD_PR_LEVEL_09_02_ASSET_OWNERSHIP_NORMALIZATION - Validation Checklist
 
-Scope and constraints
+Scope
 - [x] one PR purpose only
-- [x] no engine changes
-- [x] no launcher changes
-- [x] no config migration
-- [x] preserve behavior via constant extraction only
+- [x] no engine modifications
+- [x] no launcher/bootstrap changes
+- [x] no config migration as a separate lane
+- [x] no start_of_day modifications
 
-Required pattern
-- [x] games/<GameName>/rules/flowRules.js present for all affected games
-- [x] games/<GameName>/rules/flowContent.js present for all affected games
-- [x] flow/ and game/ import consumers updated to split modules
+Required work
+1. scan repo for owner-specific assets outside owner assets/
+- [x] scanned games/, samples/, tools/ for */platform/assets payloads
+
+2. classify by owner
+- [x] game-owned: Asteroids payloads found
+- [x] sample-owned: none found
+- [x] tool-owned: none found
+- [x] truly shared: none found in scanned owner scopes
+
+3. move only asset payloads
+- [x] 11 asset payload files moved from games/Asteroids/platform/assets/* to games/Asteroids/assets/platform/*
+
+4. update references
+- [x] updated active path references to games/Asteroids/assets/platform/
+
+5. remove old asset locations when safe
+- [x] moved payload files out of old location
+- [x] no owner payload files remain under games/Asteroids/platform/assets
+
+6. preserve exact assets / avoid code moves
+- [x] payload files preserved (move only)
+- [x] no runtime/platform code moved
 
 Command evidence
-- node --check on all rules split files + all import consumers: PASS (117 files)
-- node tests/runtime/LaunchSmokeAllEntries.test.mjs: PASS
+- rg scan for old active paths (tools/tests/docs/specs): no stale games/Asteroids/platform/assets refs remain
+- node --check tools/Asset Browser/main.js : PASS
+- node --check tools/shared/asteroidsPlatformDemo.js : PASS
+- node --check tools/shared/vectorAssetSystem.js : PASS
+- node tests/runtime/LaunchSmokeAllEntries.test.mjs : PASS
+- tests/tools/VectorAssetSystem.test.mjs : blocked by existing baseline env/module resolution issue (C:/src/engine/assets/AssetRegistry.js)
 
 Result
-- PASS
+- PASS (with noted baseline test-environment blocker unrelated to this move)

docs/pr/BUILD_PR_LEVEL_09_02_ASSET_OWNERSHIP_NORMALIZATION.md

@@ -0,0 +1,95 @@
+# BUILD_PR — LEVEL 09.02 ASSET OWNERSHIP NORMALIZATION
+
+## Purpose
+Normalize asset ownership so asset folders live under the owning scope instead of under broad shared
+buckets that hide ownership.
+
+## Architectural decision
+If `platform` contains art/audio/data assets for a specific game, sample, or tool, then it should
+move under that owner as:
+
+- `games/<GameName>/assets/platform/`
+- `samples/<SampleName>/assets/platform/`
+- `tools/<ToolName>/assets/platform/`
+
+## Important distinction
+This rule applies only to **assets**.
+
+Do **not** move:
+- engine/runtime platform code
+- browser/platform abstraction code
+- shared non-asset infrastructure
+
+Only move folders/files that are truly asset payloads:
+- images
+- sprites
+- tile sets
+- audio
+- json/data payloads used as content
+- SVG/background/parallax payloads
+
+## Why this is the right rule
+`platform/assets` hides ownership.
+If the asset belongs to one game/sample/tool, it should live with that owner.
+This improves:
+- clarity
+- portability
+- deletion safety
+- packaging
+- future per-owner publishing
+
+## Scope
+Docs-first repo-wide ownership correction specification for:
+- games
+- samples
+- tools
+
+## Ownership rules
+### Game-owned
+Move to:
+- `games/<GameName>/assets/...`
+
+### Sample-owned
+Move to:
+- `samples/<SampleName>/assets/...`
+
+### Tool-owned
+Move to:
+- `tools/<ToolName>/assets/...`
+
+### Truly shared assets
+Keep shared only if they are genuinely reused across multiple owners and are not owner-specific.
+These must be documented explicitly as shared assets, not treated as default storage.
+
+## Migration rule
+When moving assets:
+1. preserve exact payloads
+2. update references/import paths
+3. do not duplicate unless temporary transition requires it
+4. remove old location after references are verified
+5. do not move runtime/platform code in this PR
+
+## Required scan
+Codex must scan for:
+- `platform/assets`
+- `*/platform/assets`
+- any owner-specific assets stored outside owner `assets/`
+
+## Deliverables
+This PR should produce a docs-first implementation plan and Codex execution instructions for a
+repo-wide ownership correction pass.
+
+## Acceptance criteria
+1. no owner-specific asset remains under broad `platform/assets`
+2. game assets live under `games/<GameName>/assets/`
+3. sample assets live under `samples/<SampleName>/assets/`
+4. tool assets live under `tools/<ToolName>/assets/`
+5. path references are updated
+6. no runtime/platform code moved
+7. genuinely shared assets, if any, are called out explicitly
+
+## Out of scope
+- engine refactors
+- runtime platform abstraction changes
+- asset content redesign
+- compression/optimization work