PR 8.11: Enforce explicit sample palette linkage

- Required sample tool payloads to reference sample.palette.json when present
- Preserved one-palette-per-sample-folder rule
- Kept palettes separate from tool payload files
- Avoided runtime and start_of_day changes

Author: DavidQ

docs/dev/codex_commands.md

@@ -2,25 +2,24 @@ MODEL: GPT-5.3-codex
 REASONING: medium
 
 TASK:
-Refactor samples to multi-file tool payload model.
+Apply PR 8.11 sample palette strict rule.
 
 STEPS:
-1. Remove any "tools" arrays inside sample JSON files.
-2. For each tool used in a sample:
-   - Create file: sample.<id>.<tool>.json
-3. Ensure each file:
-   - references tool schema via $schema
-   - matches EXACT structure of workspace manifest tool payload
-4. Remove wrapper fields:
-   - documentKind
-   - id
-   - type
-5. Keep palette as separate file if exists.
-6. Do NOT modify runtime.
-7. Do NOT add validators.
-8. Do NOT modify start_of_day.
+1. Find sample folders containing sample.palette.json.
+2. For each folder with sample.palette.json:
+   - update every sample.<id>.<tool>.json in that folder
+   - add or preserve: "palette": "./sample.palette.json"
+3. Verify every sample.palette.json uses:
+   - swatches
+   - single-character symbol
+   - uppercase hex
+4. Ensure no sample folder has more than one palette file.
+5. Do not edit runtime files.
+6. Do not edit old runtime/docs references to old sample path names in this PR.
+7. Do not add validators.
+8. Do not modify start_of_day.
 
 ACCEPTANCE:
-- Each sample tool is its own file
-- File format matches workspace tool payload
-- No arrays or wrappers remain
+- All sample tool files in palette folders explicitly reference ./sample.palette.json.
+- No duplicate palette files per sample folder.
+- Palette schema shape remains valid.

docs/dev/commit_comment.txt

@@ -1,6 +1,6 @@
-PR 8.10: Sample multi-file tool payload alignment
+PR 8.11: Enforce explicit sample palette linkage
 
-- Converted samples to one-file-per-tool model
-- Removed tools arrays from sample files
-- Aligned sample payloads with workspace tool payload structure
-- Standardized naming convention
+- Required sample tool payloads to reference sample.palette.json when present
+- Preserved one-palette-per-sample-folder rule
+- Kept palettes separate from tool payload files
+- Avoided runtime and start_of_day changes

docs/pr/PR_8.11_SAMPLE_PALETTE_STRICT_RULE.md

@@ -0,0 +1,76 @@
+# PR 8.11 — Sample Palette Strict Rule
+
+## Purpose
+Tighten sample palette handling after the multi-file tool payload refactor.
+
+Samples now use one tool payload per file:
+
+`sample.<id>.<tool>.json`
+
+Palette handling must be explicit and deterministic.
+
+## Current Repo Reality
+- Sample tool payload files are manifest-style:
+  - `$schema`
+  - `tool`
+  - `version`
+  - `config`
+- Palette files are separate:
+  - `sample.palette.json`
+- Runtime/docs references to old sample paths were intentionally not edited in the prior PR.
+
+## Required Rule
+
+If a sample uses colors, that sample folder MUST contain exactly one:
+
+`sample.palette.json`
+
+## Required Linkage
+
+Each `sample.<id>.<tool>.json` file in that sample folder MUST reference the palette when the palette exists.
+
+Use this field:
+
+```json
+{
+  "palette": "./sample.palette.json"
+}
+```
+
+## Payload Shape
+
+Sample tool payload files may contain:
+
+```json
+{
+  "$schema": "../../../tools/schemas/tools/<tool>.schema.json",
+  "tool": "<tool>",
+  "version": 1,
+  "palette": "./sample.palette.json",
+  "config": {}
+}
+```
+
+## Rules
+- One palette per sample folder.
+- Palette file name must be exactly `sample.palette.json`.
+- Palette must use `swatches`, not `entries`.
+- Each swatch must use a single-character `symbol`.
+- Each swatch must use uppercase `hex`.
+- If `sample.palette.json` exists, every tool payload file in that folder must reference it.
+- If no colors exist in the sample, do not create a palette.
+
+## Forbidden
+- Do not embed palette swatches inside tool payload files.
+- Do not create multiple palette files in one sample folder.
+- Do not use `entries`.
+- Do not use multi-character symbols like `s001`.
+- Do not add validators.
+- Do not modify runtime logic.
+- Do not modify `start_of_day`.
+
+## Acceptance
+- Every colored sample has exactly one `sample.palette.json`.
+- Every sample folder with `sample.palette.json` has all `sample.<id>.<tool>.json` files referencing `./sample.palette.json`.
+- No sample folder has duplicate palette files.
+- Palette schema remains `swatches` + single-character `symbol`.

docs/pr/sample_palette_linkage_rules.md

@@ -0,0 +1,27 @@
+# Sample Palette Linkage Rules
+
+## Palette File
+Use:
+
+`sample.palette.json`
+
+## Tool Payload Reference
+Every tool payload file in the same folder must include:
+
+```json
+"palette": "./sample.palette.json"
+```
+
+when the palette file exists.
+
+## No Palette Case
+If the sample has no color data:
+- no `sample.palette.json`
+- no `palette` field required
+
+## Audit Rules
+For each sample folder:
+1. Check for `sample.palette.json`.
+2. If present, check every `sample.<id>.<tool>.json`.
+3. Each tool payload must include `palette: "./sample.palette.json"`.
+4. Ensure there are no other palette files in the folder.

samples/phase-02/0207/sample.0207.sprite-editor.json

@@ -1071,5 +1071,6 @@
       ],
       "currentFrameIndex": 0
     }
-  }
+  },
+  "palette": "./sample.palette.json"
 }

samples/phase-02/0213/sample.0213.palette-browser.json

@@ -33,5 +33,6 @@
         }
       ]
     }
-  }
+  },
+  "palette": "./sample.palette.json"
 }

samples/phase-02/0213/sample.0213.sprite-editor.json

@@ -811,5 +811,6 @@
       ],
       "currentFrameIndex": 0
     }
-  }
+  },
+  "palette": "./sample.palette.json"
 }

samples/phase-02/0214/sample.0214.sprite-editor.json

@@ -551,5 +551,6 @@
       ],
       "currentFrameIndex": 0
     }
-  }
+  },
+  "palette": "./sample.palette.json"
 }

samples/phase-02/0219/sample.0219.sprite-editor.json

@@ -1071,5 +1071,6 @@
       ],
       "currentFrameIndex": 0
     }
-  }
+  },
+  "palette": "./sample.palette.json"
 }

samples/phase-02/0221/sample.0221.3d-json-payload-normalizer.json

@@ -51,5 +51,6 @@
         }
       ]
     }
-  }
+  },
+  "palette": "./sample.palette.json"
 }