Canonicalize palette schema and enforce direct strict tool payload schemas - PR 11.19

Author: DavidQ

docs/dev/codex_commands.md

@@ -3,22 +3,22 @@
 model: gpt-5.3-codex
 reasoning: high
 
-Apply PR_11_18_FULL_STRICT_SCHEMA_MODE.
+Apply PR_11_19_SCHEMA_CLEANUP_TOOL_PAYLOADS_AND_PALETTE_CANONICALIZATION.
 
 Required:
-- Enforce `additionalProperties: false` on every object schema under `tools/schemas/**/*.json`.
-- No schema object may use `additionalProperties: true`.
-- No schema object may omit `additionalProperties`.
-- Explicitly define every allowed field instead of allowing loose payloads.
-- Complete missing/weak tool schemas rather than bypassing validation.
-- Workspace manifest must reference tool schemas via `$ref`.
-- Workspace `tools.palette` remains singular and required.
-- Workspace `tools.additionalProperties` must be false.
-- Validate all `$ref` targets resolve.
-- Add tests/checks that unknown fields fail validation.
+- Make `tools/schemas/tools/palette-browser.schema.json` the only canonical palette schema.
+- Move/merge correct palette schema content into `palette-browser.schema.json`.
+- Delete/remove all `tools/schemas/palette.schema*` files.
+- Ensure palette-browser schema is strict with `additionalProperties: false` everywhere.
+- Review `tools/schemas/sample.tool-payload.schema.json`; tools must validate only direct tool JSON schemas, not broad sample wrapper objects.
+- Remove/demote/narrow `sample.tool-payload.schema.json` so it cannot be used to validate arbitrary extra objects as tool payloads.
+- Rename tool schema `config` fields to a clearer field, preferably `payload`, consistently across schemas and sample 1902.
+- Replace generic use of `gameId` with a more generic identifier, preferably `projectId`; keep `gameId` only inside explicitly game-specific schemas.
+- Update Workspace manifest `$ref` targets to the canonical tool schemas.
+- Keep full strict mode: no `additionalProperties: true`, no omitted object `additionalProperties`.
 - Validate/rebuild only sample 1902 as needed.
-- Ensure sample 1902 Workspace shows all valid tools, not only Palette.
+- Do not modify other samples.
 - Do not add fallback/default/hidden data.
 - Do not modify start_of_day folders.
-- Add validation report at docs/dev/reports/PR_11_18_FULL_STRICT_SCHEMA_MODE_report.md.
-- Return ZIP artifact at tmp/PR_11_18_FULL_STRICT_SCHEMA_MODE_delta.zip.
+- Add validation report at docs/dev/reports/PR_11_19_SCHEMA_CLEANUP_TOOL_PAYLOADS_AND_PALETTE_CANONICALIZATION_report.md.
+- Return ZIP artifact at tmp/PR_11_19_SCHEMA_CLEANUP_TOOL_PAYLOADS_AND_PALETTE_CANONICALIZATION_delta.zip.

docs/dev/commit_comment.txt

@@ -1 +1 @@
-Enforce full strict schema mode across tool and workspace schemas - PR 11.18
+Canonicalize palette schema and enforce direct strict tool payload schemas - PR 11.19

docs/dev/reports/PR_11_19_SCHEMA_CLEANUP_TOOL_PAYLOADS_AND_PALETTE_CANONICALIZATION_report.md

@@ -0,0 +1,100 @@
+# PR_11_19_SCHEMA_CLEANUP_TOOL_PAYLOADS_AND_PALETTE_CANONICALIZATION Report
+
+## Result
+- PASS
+
+## Palette Schema Canonicalization
+
+### Palette schema files found (pre-change)
+- `tools/schemas/palette.schema.json`
+- `tools/schemas/tools/palette.schema.json`
+- `tools/schemas/tools/palette-browser.schema.json`
+
+### Palette schema files deleted
+- `tools/schemas/palette.schema.json`
+- `tools/schemas/tools/palette.schema.json`
+
+### Final canonical palette schema path
+- `tools/schemas/tools/palette-browser.schema.json`
+
+### Canonical palette schema contract
+- strict root with `additionalProperties: false`
+- required: `tool`, `version`, `payload`
+- `tool` const: `palette-browser`
+- `payload` strict object with required `schema`, `version`, `name`, `swatches`
+- `swatches[].symbol|hex|name` explicit and strict
+- no object schema uses `additionalProperties: true`
+
+## Tool Payload Schema Cleanup
+
+### `sample.tool-payload.schema.json` handling
+- Kept file path but demoted/narrowed its role to **sample wrapper only**.
+- Added explicit description that runtime tool payloads must validate against `tools/schemas/tools/*.schema.json`.
+- Added strict guard (`not` requiring `tool` + `payload`) so it cannot be used as tool payload schema.
+- Kept strict mode (`additionalProperties: false`) while allowing sample wrapper document keys via `patternProperties` + strict JSON value defs.
+
+### `config` replacement choice
+- Chosen field: `payload`
+- Applied consistently across tool schemas and sample 1902 tool entries.
+
+### generic `gameId` replacement choice
+- Chosen generic field: `projectId`
+- Replaced generic schema-level usage in `tools/schemas/tools/skin-editor.schema.json` (root field now `projectId`).
+- Updated sample 1902 generic payload usage:
+  - `tools.skin-editor.projectId`
+  - `tools.asset-pipeline-tool.payload.pipelinePayload.projectId`
+- Kept game-specific `gameId` only inside game-specific skin document section (`games.pong.skin/1`) in sample 1902.
+
+## Workspace `$ref` Integration
+- Updated workspace manifest palette ref:
+  - `tools/schemas/workspace.manifest.schema.json`
+  - `tools.properties.palette -> $ref: ./tools/palette-browser.schema.json`
+- `tools.additionalProperties` remains `false`.
+- tool refs remain explicit by tool id.
+
+## Schemas Updated
+- `tools/schemas/workspace.manifest.schema.json`
+- `tools/schemas/sample.tool-payload.schema.json`
+- `tools/schemas/tools/3d-asset-viewer.schema.json`
+- `tools/schemas/tools/3d-camera-path-editor.schema.json`
+- `tools/schemas/tools/3d-json-payload-normalizer.schema.json`
+- `tools/schemas/tools/asset-browser.schema.json`
+- `tools/schemas/tools/asset-pipeline-tool.schema.json`
+- `tools/schemas/tools/palette-browser.schema.json`
+- `tools/schemas/tools/parallax-editor.schema.json`
+- `tools/schemas/tools/performance-profiler.schema.json`
+- `tools/schemas/tools/physics-sandbox.schema.json`
+- `tools/schemas/tools/replay-visualizer.schema.json`
+- `tools/schemas/tools/skin-editor.schema.json`
+- `tools/schemas/tools/sprite-editor.schema.json`
+- `tools/schemas/tools/state-inspector.schema.json`
+- `tools/schemas/tools/tile-map-editor.schema.json`
+- `tools/schemas/tools/tile-model-converter.schema.json`
+- `tools/schemas/tools/vector-asset-studio.schema.json`
+- `tools/schemas/tools/vector-map-editor.schema.json`
+
+## Sample 1902 Validation/Rebuild
+- Updated only:
+  - `samples/phase-19/1902/sample.1902.workspace-all-tools.json`
+- Changes include:
+  - tool entry `config` -> `payload`
+  - `tools.palette` migrated to canonical palette-browser payload shape
+  - `tools.palette-browser` given explicit strict payload
+  - generic `projectId` replacements
+  - removed nested tile payload `$schema` reference to `sample.tool-payload.schema.json`
+
+## Unknown Field Rejection Result
+- Test injects `root.tools.asset-browser.payload.__unknown = true`.
+- Validation rejects injection (PASS).
+
+## Validation Commands and Results
+- `node --check tests/tools/ToolSchemaStrictModeValidation.test.mjs` -> PASS
+- `node --check tests/tools/ToolWorkspaceSchemaManifestBoundaries.test.mjs` -> PASS
+- strict object audit across `tools/schemas/**/*.json` -> PASS (`issues: 0`)
+- `node -e "import { run } from './tests/tools/ToolSchemaStrictModeValidation.test.mjs'; await run();"` -> PASS
+- `npm run test:launch-smoke -- --tools` -> PASS (`PASS=287 FAIL=0 TOTAL=287`, includes sample `1902` PASS)
+
+## Scope Confirmations
+- No samples changed outside `samples/phase-19/1902/`.
+- No `start_of_day` folders modified.
+- No fallback/default/hidden data added.

docs/dev/reports/REPORT_PR_11_19.md

@@ -0,0 +1,11 @@
+# REPORT_PR_11_19_SCHEMA_CLEANUP_TOOL_PAYLOADS_AND_PALETTE_CANONICALIZATION
+
+## Summary
+This PR cleans up schema SSoT:
+- one palette schema at tools/schemas/tools/palette-browser.schema.json
+- no broad sample wrapper schema for tool payloads
+- clearer payload naming instead of config
+- generic project/source identity instead of gameId where appropriate
+
+## Target
+Tools validate direct strict tool JSON only.

docs/dev/reports/launch_smoke_report.md

@@ -1,6 +1,6 @@
 # Launch Smoke Report
 
-Generated: 2026-04-29T02:30:38.214Z
+Generated: 2026-04-29T02:49:57.040Z
 
 Filters: games=true, samples=true, tools=true, sampleRange=all
 

docs/pr/PR_11_19_SCHEMA_CLEANUP_TOOL_PAYLOADS_AND_PALETTE_CANONICALIZATION/BUILD.md

@@ -0,0 +1,102 @@
+# BUILD_PR_11_19_SCHEMA_CLEANUP_TOOL_PAYLOADS_AND_PALETTE_CANONICALIZATION
+
+## Required Codex Work
+
+### 1. Canonicalize Palette schema
+Use:
+`tools/schemas/tools/palette-browser.schema.json`
+
+This is the only valid palette schema location/name.
+
+Current uploaded palette-browser schema is too loose:
+- `additionalProperties: true`
+- generic `config`
+- does not define swatches
+
+Replace/merge it with the correct palette content from existing `tools/schemas/palette.schema*`.
+
+Delete/remove all `tools/schemas/palette.schema*` files after migration.
+
+Expected strict palette-browser payload:
+- `tool`: const `palette-browser`
+- `version`
+- clear payload field, not loose config
+- palette id/name/source/sourceId as needed
+- swatches array
+- each swatch explicitly defines symbol/hex/name or repo standard fields
+- `additionalProperties: false` on every object
+
+### 2. Remove broad sample wrapper validation from tool loading
+Review:
+`tools/schemas/sample.tool-payload.schema.json`
+
+Goal:
+- Tools should accept only tool JSON files.
+- Extra objects/wrapper objects should not validate.
+- If sample tooling still needs a wrapper schema, move it to a sample/test-specific role and do not use it as the tool payload schema.
+
+Update tool launch/load validation so tool payloads `$ref` their actual tool schema.
+
+### 3. Rename generic `config`
+Across tool schemas, replace `config` with a clearer field.
+
+Preferred field:
+`payload`
+
+Rationale:
+- `config` is too vague.
+- `payload` means the tool-owned document/data to render/edit.
+
+If an existing repo standard is discovered, use it consistently and document the choice.
+
+Update sample 1902 and validation fixtures as needed.
+
+### 4. Make `gameId` generic
+Replace tool/workspace schema fields that require `gameId` when the payload may represent a sample/tool/workspace.
+
+Preferred:
+- `projectId`
+
+Allowed alternatives if already used consistently:
+- `sourceId`
+- `workspaceId`
+
+Rules:
+- Do not require `gameId` for generic tool payloads.
+- If game-specific schemas need `gameId`, keep it only in game-specific schema sections.
+- Sample 1902 must validate without pretending to be a game.
+
+### 5. Workspace schema integration
+Update Workspace manifest `$ref` targets to use:
+- `tools/schemas/tools/palette-browser.schema.json`
+- other tool schemas directly
+
+Ensure:
+- `tools.additionalProperties: false`
+- all referenced tool schemas are strict
+- unknown keys fail validation
+- unknown fields inside payloads fail validation
+
+### 6. Validation report
+Create:
+docs/dev/reports/PR_11_19_SCHEMA_CLEANUP_TOOL_PAYLOADS_AND_PALETTE_CANONICALIZATION_report.md
+
+Report must include:
+- palette schema files found
+- palette schema files deleted
+- final canonical palette schema path
+- how `sample.tool-payload.schema.json` was handled
+- chosen replacement for `config`
+- chosen replacement for generic `gameId`
+- schemas updated
+- sample 1902 validation result
+- unknown-field rejection result
+- confirmation no other samples changed
+- confirmation no start_of_day changes
+
+## Constraints
+- One PR purpose only.
+- Do not loosen schemas to make validation pass.
+- Do not keep duplicate palette schemas.
+- Do not modify unrelated samples.
+- No fallback/default/hidden data.

docs/pr/PR_11_19_SCHEMA_CLEANUP_TOOL_PAYLOADS_AND_PALETTE_CANONICALIZATION/PLAN.md

@@ -0,0 +1,43 @@
+# PLAN_PR_11_19_SCHEMA_CLEANUP_TOOL_PAYLOADS_AND_PALETTE_CANONICALIZATION
+
+## Purpose
+Clean up schema ownership so tools accept only valid tool JSON payloads, Palette has one canonical schema, and confusing generic schema fields are renamed.
+
+## Problems
+1. Palette schema duplication:
+   - Correct canonical location/name should be:
+     `tools/schemas/tools/palette-browser.schema.json`
+   - Existing `tools/schemas/palette.schema*` files should be removed after their content is moved/merged.
+   - Only one palette schema should remain: palette-browser.
+
+2. `sample.tool-payload.schema.json` is too broad:
+   - Tools should accept only tool JSON payloads.
+   - Sample wrapper objects and extra objects should not validate as tool payloads.
+   - Tool schemas should be referenced directly with `$ref`.
+
+3. Tool schemas use a generic `config` section:
+   - Rename to a clearer field name that describes what it contains.
+   - Suggested: `payload`
+   - Alternative acceptable if repo standard exists: `toolData` or `document`
+
+4. `gameId` is too narrow:
+   - Workspace/sample 1902 is not necessarily a game.
+   - Replace or supplement with a generic identifier.
+   - Suggested: `projectId`, `sourceId`, or `workspaceId` depending on context.
+
+## Scope
+- Schema files under `tools/schemas/`
+- Tool payload validation
+- Workspace manifest schema references
+- Sample 1902 only if required to validate
+- Do not modify other samples
+- Do not modify start_of_day folders
+
+## Acceptance
+- Only one canonical palette schema exists: `tools/schemas/tools/palette-browser.schema.json`
+- `tools/schemas/palette.schema*` files are deleted/removed
+- `palette-browser.schema.json` contains the real strict palette payload schema
+- Tools validate against tool-specific schemas directly, not broad sample wrapper schema
+- `sample.tool-payload.schema.json` is removed, demoted, or narrowed so it cannot accept extra wrapper data
+- `config` is renamed to a clearer schema field consistently
+- `gameId` is replaced/supplemented with a generic identifier suitable for samples and games