Normalize all sample palettes to canonical SSoT and remove palette-browser duplicates - PR 10.6F

Author: DavidQ

docs/dev/codex_commands.md

@@ -1,8 +1,16 @@
 # Codex Commands
 
-Model: GPT-5.4
+Model: GPT-5.4-codex
 Reasoning: high
 
+Run from repo root:
+
 ```powershell
-codex --model gpt-5.4 --reasoning high "Run BUILD_PR_LEVEL_10_6D_PALETTE_CONTRACT_EVIDENCE_CAPTURE exactly as documented in docs/pr/BUILD_PR_LEVEL_10_6D_PALETTE_CONTRACT_EVIDENCE_CAPTURE.md. Diagnostics only. Do not normalize palette files. Run npm run test:sample-standalone:data-flow fresh, collect the exact palette manifest/tool/schema files, produce docs/dev/reports/level_10_6d_palette_contract_evidence/palette_contract_evidence_report.md, and package repo-relative evidence into tmp/BUILD_PR_LEVEL_10_6D_PALETTE_CONTRACT_EVIDENCE_CAPTURE.zip."
+codex exec --model gpt-5.4-codex --reasoning high --file docs/pr/BUILD_PR_LEVEL_10_6F_ALL_SAMPLE_PALETTE_SSOT_NORMALIZATION.md
+```
+
+Codex must produce:
+
+```text
+tmp/BUILD_PR_LEVEL_10_6F_ALL_SAMPLE_PALETTE_SSOT_NORMALIZATION.zip
 ```

docs/dev/commit_comment.txt

@@ -1 +1 @@
-Capture palette contract evidence for explicit normalization follow-up - PR 10.6D
+Normalize all sample palettes to canonical SSoT and remove palette-browser duplicates - PR 10.6F

docs/dev/reports/launch_smoke_report.md

@@ -1,6 +1,6 @@
 # Launch Smoke Report
 
-Generated: 2026-04-27T16:40:59.455Z
+Generated: 2026-04-27T17:16:29.337Z
 
 Filters: games=true, samples=false, tools=false, sampleRange=all
 

docs/dev/reports/level_10_6e_launch_smoke_games_output.txt

@@ -0,0 +1,81 @@
+# level_10_6e_palette_ssot_normalization_report
+
+## build
+- BUILD: `BUILD_PR_LEVEL_10_6E_PALETTE_SSOT_NORMALIZATION`
+- Generated: 2026-04-27T17:18:26.803Z
+
+## objective
+- Normalize Sample 0313 palette flow to a single canonical source of truth: `samples/phase-03/0313/sample.0313.palette.json`.
+- De-reference duplicate tool-wrapped payload `samples/phase-03/0313/sample.0313.palette-browser.json` as a required runtime input.
+
+## duplicate reference audit
+- Runtime reference found before changes:
+  - `samples/metadata/samples.index.metadata.json:2835` -> `/samples/phase-03/0313/sample.0313.palette-browser.json`
+- Test boundary assumptions found before changes:
+  - `tests/runtime/SampleStandaloneToolDataFlow.test.mjs` used tool-file lookup for targeted cases and expected palette only at `config.palette`.
+- Generator audit:
+  - Searched `scripts/`, `tests/`, `tools/`, `samples/` (excluding docs) for emitted/reference coupling to `sample.0313.palette-browser.json`.
+  - No active generator emitting this file was found.
+- Post-change reference scan:
+  - No remaining matches in `tests/`, `scripts/`, `tools/`, or `samples/` for `sample.0313.palette-browser.json`.
+  - Remaining mentions are documentation/history only.
+
+## implementation
+1. Updated Sample 0313 palette-browser roundtrip preset binding to canonical palette JSON.
+- File: `samples/metadata/samples.index.metadata.json:2835`
+- Change: `/samples/phase-03/0313/sample.0313.palette-browser.json` -> `/samples/phase-03/0313/sample.0313.palette.json`
+
+2. Updated data-flow contract harness to accept canonical palette payload for palette-browser routes.
+- File: `tests/runtime/SampleStandaloneToolDataFlow.test.mjs`
+- Added shared palette contract validator: `appendPaletteContractFailures` (line ~390).
+- Added canonical preset detection for palette-browser rows: `canonicalPalettePresetFiles` (line ~435).
+- Added palette extraction that supports wrapped and canonical shapes: `extractPaletteFromPresetPayload` (line ~689).
+- Updated targeted-case preset loading to use metadata `row.presetPath` (line ~736) instead of forcing `sample.<id>.<tool>.json`.
+- Updated targeted palette-browser expectation to consume extracted palette payload (line ~1210).
+
+3. Removed duplicate Sample 0313 tool-wrapped palette payload file.
+- Deleted: `samples/phase-03/0313/sample.0313.palette-browser.json`
+
+## required final data flow (verified)
+- `sample manifest -> canonical palette JSON -> normalized tool input -> Palette Browser UI/state`
+
+## before/after evidence (sample 0313)
+- Before (from prior evidence capture report/run):
+  - targeted palette-browser summary indicated wrapper-origin source: `5 swatches | source: manifest`.
+  - Artifact: `docs/dev/reports/level_10_6d_palette_contract_evidence/test_sample_standalone_data_flow_output.txt`
+- After (this BUILD):
+  - targeted palette-browser summary for sample 0313: `5 swatches | source: generated-from-sample-colors`
+  - targeted title: `Sample 0313 Palette`
+  - swatchCount: `5`
+  - Artifact: `docs/dev/reports/level_10_6e_sample_standalone_data_flow_output.txt`
+
+## validation
+1. `npm run test:sample-standalone:data-flow`
+- Result: PASS
+- generatedAt: `2026-04-27T17:15:24.813Z`
+- schemaFailures: `0`
+- contractFailures: `0`
+- roundtripPathFailures: `0`
+- genericFailures: `0`
+
+2. `npm run test:launch-smoke:games`
+- Result: PASS
+- summary: PASS=12 FAIL=0 TOTAL=12
+- Artifact: `docs/dev/reports/level_10_6e_launch_smoke_games_output.txt`
+
+## guardrails check
+- No fallback palette data added.
+- No hardcoded Sample 0313 asset path introduced in Palette Browser runtime code.
+- No `start_of_day` folder changes.
+- No palette field rename or swatch reshaping applied to canonical sample palette.
+
+## files changed
+- `samples/metadata/samples.index.metadata.json`
+- `tests/runtime/SampleStandaloneToolDataFlow.test.mjs`
+- `docs/dev/reports/level_10_6e_sample_standalone_data_flow_output.txt`
+- `docs/dev/reports/level_10_6e_launch_smoke_games_output.txt`
+- `docs/dev/reports/launch_smoke_report.md` (updated by required launch-smoke test run)
+- `tmp/sample-standalone-tool-data-flow-results.json` (updated by required data-flow test run)
+
+## files removed
+- `samples/phase-03/0313/sample.0313.palette-browser.json`

docs/dev/reports/level_10_6e_palette_ssot_normalization_report.md

@@ -0,0 +1 @@
+samples/phase-03/0313/sample.0313.palette-browser.json

docs/dev/reports/level_10_6e_palette_ssot_removed_files.txt

@@ -0,0 +1,16 @@
+# LEVEL 10.6F Report Template
+
+Codex must replace this template with real execution output.
+
+Required summary:
+
+- Palette browser wrapper files found:
+- Palette browser wrapper files removed:
+- Canonical palette files retained:
+- References updated:
+- Generic failure signals detected:
+
+Required validation:
+
+- npm run test:launch-smoke:games
+- npm run test:sample-standalone:data-flow

docs/dev/reports/level_10_6e_sample_standalone_data_flow_output.txt

@@ -0,0 +1,55 @@
+# BUILD_PR_LEVEL_10_6E_PALETTE_SSOT_NORMALIZATION
+
+## Purpose
+
+Normalize Sample 0313 palette handling so there is exactly one palette source of truth.
+
+## Problem
+
+Two uploaded files show the same palette content in two shapes:
+
+- `sample.0313.palette.json` is the canonical palette payload.
+- `sample.0313.palette-browser.json` duplicates the same palette under `config.palette` with a tool-specific wrapper.
+
+Palette Browser must consume the canonical palette input directly through the sample manifest/data-flow. It must not require a duplicate tool-shaped palette JSON.
+
+## Explicit Codex Steps
+
+1. Locate the Sample 0313 palette files in the workspace:
+   - `sample.0313.palette.json`
+   - `sample.0313.palette-browser.json`
+2. Treat `sample.0313.palette.json` as the source of truth.
+3. Find every reference to `sample.0313.palette-browser.json`.
+4. Update the sample manifest or tool binding so Palette Browser receives the canonical palette directly.
+5. If a generator creates `sample.0313.palette-browser.json`, update it so it no longer emits duplicated palette data.
+6. If Palette Browser expects `$schema`, `tool`, or `config.palette`, move that adaptation to the normalization boundary and pass only the canonical palette payload into the tool.
+7. Do not rename palette fields.
+8. Do not reshape `swatches`.
+9. Do not convert the palette to `engine.paletteList`.
+10. Do not add fallback colors.
+11. Do not hardcode Sample 0313 paths inside Palette Browser.
+12. Remove or de-reference the duplicate browser JSON only after all references are updated.
+13. Update the report with exact files changed and before/after data-flow.
+14. Update the master roadmap status only if an execution-backed matching item exists. Status-only marker updates are allowed; no roadmap text rewrite.
+
+## Required Final Data Flow
+
+```text
+sample manifest → canonical palette JSON → normalized tool input → Palette Browser UI/state
+```
+
+## Acceptance Criteria
+
+- One canonical Sample 0313 palette JSON remains.
+- Palette Browser loads the canonical palette directly.
+- `sample.0313.palette-browser.json` is no longer required.
+- `npm run test:sample-standalone:data-flow` passes.
+- `npm run test:launch-smoke:games` passes.
+- Report lists all duplicate references found and the action taken.
+- No hidden default/fallback palette data exists.
+
+## Out of Scope
+
+- No start_of_day changes.
+- No broad tool registry refactor.
+- No unrelated sample changes.

docs/dev/reports/level_10_6f_all_sample_palette_ssot_normalization_report.md

@@ -0,0 +1,129 @@
+# BUILD_PR_LEVEL_10_6F_ALL_SAMPLE_PALETTE_SSOT_NORMALIZATION
+
+## Purpose
+Normalize every duplicate sample palette pair under `samples/` to a single canonical palette source of truth.
+
+Known pattern:
+- `sample.NNNN.palette.json` contains the canonical palette object.
+- `sample.NNNN.palette-browser.json` duplicates the same palette under a Palette Browser tool wrapper.
+
+This PR applies the normalization to all matching samples, not just sample 0313.
+
+## Scope
+- Search only under `samples/` and directly related sample metadata/test files needed to keep validation green.
+- Keep canonical `*.palette.json` as the only persisted palette JSON for each sample.
+- Remove/de-reference duplicate `*.palette-browser.json` files.
+- Update sample manifests/metadata/tool bindings so Palette Browser receives the canonical palette object from the sample manifest/normalized input path.
+- Update roadmap status markers only if execution-backed.
+
+## Do Not
+- Do not keep both palette files for the same sample.
+- Do not introduce a new persisted wrapper schema for Palette Browser.
+- Do not transform canonical palettes into `$schema`, `engine.paletteList`, `config.palette`, or another tool-specific persisted wrapper.
+- Do not add silent fallback palettes or hardcoded sample asset paths.
+- Do not modify `start_of_day` folders.
+- Do not do a repo-wide refactor.
+
+## Required Normalization Rules
+
+### Canonical persisted palette
+For each sample, the only persisted palette JSON must be:
+
+```text
+samples/**/sample.*.palette.json
+```
+
+This file owns the palette fields:
+
+```text
+schema
+version
+name
+source
+swatches
+```
+
+Preserve an existing `$schema` in the canonical file unless an existing schema/test contract explicitly requires removal.
+
+### Browser wrapper removal
+Remove or de-reference every duplicate file matching:
+
+```text
+samples/**/sample.*.palette-browser.json
+```
+
+Palette Browser must not depend on a persisted wrapper like:
+
+```json
+{
+  "tool": "palette-browser",
+  "config": {
+    "palette": {}
+  }
+}
+```
+
+### Runtime input contract
+Palette Browser may receive a runtime envelope only if the existing runner requires one, but that envelope must be built by the runner/normalizer from the canonical palette object. It must not be stored as a second sample JSON file.
+
+### No fallback data
+If a sample has no palette input, Palette Browser must show a safe empty state. It must not auto-load hidden/default/sample palettes.
+
+## Codex Targeted Discovery
+Run:
+
+```powershell
+Get-ChildItem .\samples -Recurse -Filter "*.palette-browser.json" | Select-Object -ExpandProperty FullName
+Get-ChildItem .\samples -Recurse -Filter "*.palette.json" | Select-Object -ExpandProperty FullName
+Select-String -Path .\samples\**\*.json -Pattern "palette-browser|palette.json|config.palette|paletteList" -List
+Select-String -Path .\tests\**\*.mjs,.\samples\metadata\*.json -Pattern "palette-browser|palette.json|config.palette|paletteList" -List
+```
+
+## Implementation Steps
+1. Inventory every `samples/**/sample.*.palette-browser.json` file.
+2. Match each wrapper file to its sibling or referenced `sample.*.palette.json`.
+3. Compare `wrapper.config.palette` to the canonical palette object.
+4. If the content is the same palette with only wrapper/source/schema drift, keep canonical `*.palette.json` and remove the wrapper file.
+5. Update all sample metadata/manifest/tool references that point to `*.palette-browser.json` so they point to canonical `*.palette.json` or manifest palette data.
+6. Update sample standalone normalizer/test expectations only if they currently require persisted wrapper files.
+7. Ensure the flow remains: `sample -> schema -> normalized input -> tool -> UI/state`.
+8. Generate a report listing each removed wrapper and each updated reference.
+9. Run required tests and place outputs under `docs/dev/reports/`.
+
+## Required Tests
+
+```powershell
+npm run test:launch-smoke:games
+npm run test:sample-standalone:data-flow
+```
+
+## Required Report
+Create:
+
+```text
+docs/dev/reports/level_10_6f_all_sample_palette_ssot_normalization_report.md
+```
+
+It must include:
+
+```text
+Palette browser wrapper files found: N
+Palette browser wrapper files removed: N
+Canonical palette files retained: N
+References updated: N
+Generic failure signals detected: X
+```
+
+Also include:
+
+```text
+sample | removed palette-browser file | canonical palette file | updated references | validation result
+```
+
+## Acceptance
+- No `samples/**/sample.*.palette-browser.json` duplicate files remain unless listed as blocked with a concrete reason.
+- No sample metadata points to a palette-browser JSON wrapper as the palette source.
+- Palette Browser uses the canonical palette object from manifest/normalized input.
+- `npm run test:launch-smoke:games` passes.
+- `npm run test:sample-standalone:data-flow` passes.
+- Report shows `Generic failure signals detected: 0`.