Require sprite-editor palette input and classify palette load failures - PR 10.6J

Author: DavidQ

docs/dev/codex_commands.md

@@ -1,12 +1,8 @@
-# Codex Commands — BUILD_PR_LEVEL_10_6I_TOOL_LOAD_EXPECTED_VS_ACTUAL_CLASSIFICATION_V3
+# Codex Command - BUILD_PR_LEVEL_10_6J_SPRITE_EDITOR_REQUIRED_PALETTE_INPUT
 
-## Model
-GPT-5.3-codex
+Model: GPT-5.4
+Reasoning: high
 
-## Reasoning
-high
-
-## Command
-```text
-Implement BUILD_PR_LEVEL_10_6I_TOOL_LOAD_EXPECTED_VS_ACTUAL_CLASSIFICATION_V3 from docs/pr/BUILD_PR_LEVEL_10_6I_TOOL_LOAD_EXPECTED_VS_ACTUAL_CLASSIFICATION_V3.md. Keep the change diagnostics-only. Add expected-vs-actual dependency classification to existing tool-load diagnostics. Do not normalize palette files in this PR. Do not add fallback data or hardcoded paths. Run npm run test:launch-smoke:games and npm run test:sample-standalone:data-flow. Put results in docs/dev/reports/level_10_6i_tool_load_expected_vs_actual_classification_report.md. Return a ZIP artifact at tmp/BUILD_PR_LEVEL_10_6I_TOOL_LOAD_EXPECTED_VS_ACTUAL_CLASSIFICATION_V3.zip.
+```powershell
+codex --model gpt-5.4 --reasoning high "Execute BUILD_PR_LEVEL_10_6J_SPRITE_EDITOR_REQUIRED_PALETTE_INPUT exactly as documented in docs/pr/BUILD_PR_LEVEL_10_6J_SPRITE_EDITOR_REQUIRED_PALETTE_INPUT.md. Make the smallest valid change. Do not add implementation outside sprite-editor launch/input loading and shared diagnostics needed for required palette input. Do not recreate palette-browser JSON wrappers. Do not use fallback palettes or hardcoded sample paths. Run npm run test:launch-smoke:games and npm run test:sample-standalone:data-flow. Place the result ZIP at tmp/BUILD_PR_LEVEL_10_6J_SPRITE_EDITOR_REQUIRED_PALETTE_INPUT.zip."
 ```

docs/dev/commit_comment.txt

@@ -1 +1 @@
-Add expected-vs-actual tool-load diagnostics classification - PR 10.6I
+Require sprite-editor palette input and classify palette load failures - PR 10.6J

docs/dev/reports/launch_smoke_report.md

@@ -1,6 +1,6 @@
 # Launch Smoke Report
 
-Generated: 2026-04-27T18:30:35.400Z
+Generated: 2026-04-27T18:47:39.988Z
 
 Filters: games=true, samples=false, tools=false, sampleRange=all
 

docs/dev/reports/level_10_6J_expected_results.md

@@ -0,0 +1,70 @@
+# Level 10.6J Expected Results
+
+## Files changed
+
+- `tools/Sprite Editor/modules/spriteEditorApp.js`
+- `tools/shared/toolLoadDiagnostics.js`
+- `docs/dev/reports/level_10_6J_expected_results.md`
+- `docs/dev/reports/launch_smoke_report.md` (test-generated refresh)
+
+## Sprite-editor palette input expectation
+
+- `sprite-editor` now resolves required palette input before applying sample preset load.
+- Palette input resolution order is launch-input based:
+  1. `palettePath` query parameter
+  2. palette-related query path keys in normalized requested data paths
+  3. canonical derivation from `samplePresetPath` (`*.sprite-editor.json` -> `*.palette.json`)
+- If no palette path can be resolved, load fails visibly and diagnostics emit a palette warning/error path.
+
+## Palette request path source
+
+Manual sample `0219` launch observed:
+
+- `pathSource`: `tool-input:derived.samplePresetPath`
+- resolved `palettePath`: `/samples/phase-02/0219/sample.0219.palette.json`
+
+## Palette fetch URL
+
+Manual sample `0219` launch observed:
+
+- `fetchUrl`: `http://127.0.0.1:<port>/samples/phase-02/0219/sample.0219.palette.json`
+- fetch response status: `200`
+
+## Palette loaded shape summary
+
+Manual sample `0219` launch observed from `[tool-load:loaded]` for dependency `palette`:
+
+- `loaded.loadedSchema`: `html-js-gaming.palette`
+- `loaded.topLevelKeys`: `[$schema, schema, version, name, source, swatches, sourceId, locked]`
+- `loaded.palette.swatchCount`: `8`
+- `expected.contractMatch`: `true`
+
+## Palette classification
+
+Manual sample `0219` launch observed:
+
+- `[tool-load:classification] dependencyId=palette classification=success`
+- expected/actual contract blocks include canonical palette expectations and actual top-level keys/array counts.
+
+Additional observed classification in same launch (unchanged from prior behavior):
+
+- `dependencyId=sprite-project classification=wrong-shape` (top-level wrapper remains `$schema/tool/version/config`)
+
+## Validation results
+
+1. `npm run test:launch-smoke:games`
+   - PASS
+   - Summary: `PASS=12`, `FAIL=0`, `TOTAL=12`
+
+2. `npm run test:sample-standalone:data-flow`
+   - PASS
+   - Summary arrays:
+     - `schemaFailures: []`
+     - `contractFailures: []`
+     - `roundtripPathFailures: []`
+     - `genericFailures: []`
+
+## Roadmap status-only update result
+
+- No `10.6J` status marker was found in `docs/dev/roadmaps/MASTER_ROADMAP_ENGINE.md`.
+- No roadmap edits were applied.

docs/pr/BUILD_PR_LEVEL_10_6J_SPRITE_EDITOR_REQUIRED_PALETTE_INPUT.md

@@ -0,0 +1,56 @@
+# BUILD_PR_LEVEL_10_6J_SPRITE_EDITOR_REQUIRED_PALETTE_INPUT
+
+## Purpose
+Make `sprite-editor` require a palette as an explicit tool input so sample launches show the full expected data contract and fail visibly when palette input is missing.
+
+## Scope
+- Target only `sprite-editor` launch/input loading and shared tool-load diagnostics needed for this contract.
+- Do not restore `*.palette-browser.json` wrappers.
+- Do not introduce fallback palettes or hidden sample paths.
+- Do not modify `start_of_day` folders.
+- Keep one palette SSoT: `*.palette.json`.
+
+## Problem Evidence
+Current logs show:
+- `sprite-editor` receives `samplePresetPath`.
+- `sprite-editor` fetches only `sample.0219.sprite-editor.json`.
+- diagnostics classify initial expected data as `missing`.
+- loaded preset is classified `wrong-shape` because the payload did not include the expected sprite project.
+- no palette fetch appears in the browser fetch list.
+
+This means the tool boundary does not yet require/resolve palette input as part of its expected contract.
+
+## Codex Tasks
+1. Locate the smallest `sprite-editor` launch/input path that reads query or manifest data into the tool.
+2. Add `palettePath` / canonical palette input to the expected data contract for `sprite-editor`.
+3. Require palette resolution from manifest/tool launch input, not from hardcoded sample paths.
+4. Fetch the canonical `*.palette.json` when present in requested data paths.
+5. Log diagnostics for palette at request, fetch, loaded, and classification stages.
+6. If palette is missing, classify as `missing` and show a clear visible warning/error.
+7. If palette is fetched but malformed, classify as `wrong-shape` with top-level keys.
+8. If palette is valid, classify as `success` and include swatch count in diagnostics.
+9. Preserve existing behavior for valid sprite project loading except for requiring palette.
+10. Update the Level 10.6 report with execution results only.
+11. Update `docs/dev/roadmaps/MASTER_ROADMAP_ENGINE.md` status markers only if execution-backed.
+
+## Acceptance
+- Launching sample 0219 into `sprite-editor` logs an expected palette requirement.
+- Browser fetch list includes the canonical sample palette JSON when the sample manifest provides it.
+- Missing palette is not silent.
+- No duplicate `*.palette-browser.json` files are created or required.
+- No fallback palette data is used.
+- `npm run test:sample-standalone:data-flow` passes or reports only explicit classified failures.
+- Roadmap change, if any, is status-only.
+
+## Validation Commands
+Run:
+```powershell
+npm run test:launch-smoke:games
+npm run test:sample-standalone:data-flow
+```
+
+Then manually launch:
+```text
+samples/phase-02/0219
+```
+Open sprite-editor and confirm console diagnostics include palette expected/fetch/loaded/classification.