Validate SSoT sample tool relationships load direct JSON - PR 11.121

Author: DavidQ

docs/dev/codex_commands.md

@@ -4,86 +4,67 @@ Model: GPT-5.3-codex
 Reasoning: medium
 
 ## PR
-BUILD_PR_LEVEL_11_120_SAMPLE_TOOL_LINK_COUNT_RECONCILIATION
+BUILD_PR_LEVEL_11_121_VALIDATE_SSOT_TOOL_RELATIONSHIPS_LOAD_DIRECT_JSON
 
 ## Execute
 
-1. Compare relationship sources:
-   - tools/index.html expected sample/tool relationships
-   - samples/index.html rendered Open Tool links
-   - samples/metadata/samples.index.metadata.json
-   - any generated/derived sample/tool metadata files
-
-2. Confirm current counts:
-   - tools/index.html relationships: expected 34
-   - samples/index.html Open Tool links: observed 22
-
-3. Make `samples/metadata/samples.index.metadata.json` the only SSoT for all sample/tool relationships.
+1. Continue from PR 11.120 where hub counts match.
 
-4. Update sample hub renderer and tools hub renderer/loading so both read from:
+2. Use only this SSoT:
    - samples/metadata/samples.index.metadata.json
-   or from a generated artifact derived only from it.
-
-5. Remove or disable duplicate active sources:
-   - samples2tools
-   - stale generated link files
-   - fallback arrays
-   - inferred renderer links
-   - embedded sample/tool maps
-
-6. Reconcile relationships:
-   - add valid missing relationships to SSoT
-   - remove stale/invalid relationships from SSoT
-   - do not reintroduce known-bad links
-   - do not create fake data to justify links
-
-7. Known-bad links must remain absent:
-   - 0201 3D Camera Path Editor/unrelated links
-   - 0202 unrelated links
-   - 0204 unrelated links
-   - 0210 unrelated links
-   - 0220 unrelated links
-   - 0221 3D JSON Payload Normalizer / 3D JSON Payload / 3d-json-payload
-   - 0226 unrelated links
-   - 0227 unrelated links
-   - 0303 unrelated links
-   - 0305 3D JSON Payload Normalizer / 3D JSON Payload / 3d-json-payload
-   - 0901 Vector Map Editor
-   - 1204 SVG Asset Studio
-   - 1205 Vector Map Editor
-   - 1208 3D Asset Viewer and SVG Asset Studio
-   - 1319 unrelated links
-
-8. If the final count is not 34:
-   - report exactly which relationships were removed/blocked and why.
-
-9. Validate:
-   - JSON parses
-   - JS/HTML syntax valid where practical
-   - sample hub rendered links match SSoT
-   - tools hub relationships match SSoT
-   - no second active source remains
-
-10. Write populated reports:
-   - docs/dev/reports/sample_tool_relationship_reconciliation_11_120.txt
-   - docs/dev/reports/tools_index_expected_relationships_11_120.txt
-   - docs/dev/reports/samples_index_rendered_links_11_120.txt
-   - docs/dev/reports/sample_tool_ssot_after_11_120.txt
-   - docs/dev/reports/validation_after_11_120.txt
-
-11. Reports must include:
-   - files searched
-   - counts before/after
-   - entries added
-   - entries removed
-   - blocked entries
-   - chosen SSoT
-   - validation commands/results
 
-12. Roadmap:
+3. For every sample/tool relationship in the SSoT:
+   - identify sample id
+   - identify tool id
+   - identify explicit JSON input path
+   - identify schema path
+   - verify JSON exists
+   - verify JSON parses
+   - verify JSON validates against schema
+   - verify tool loading path uses JSON directly without fallback/default/preset
+
+4. Fix deterministic issues:
+   - path typo/casing
+   - stale schema filename
+   - stale canonical tool name
+   - extra invalid fields
+   - compact primitive-array formatting
+   - obvious property-name mismatch
+
+5. Remove relationship from SSoT when:
+   - JSON input missing
+   - real required data missing
+   - tool needs defaults to render
+   - relationship is unrelated to sample
+   - intent is ambiguous
+
+6. Do not:
+   - add fake data
+   - add fallback/default/preset data
+   - normalize/transform/convert runtime data
+   - reintroduce duplicate relationship sources
+
+7. Validate after changes:
+   - changed JSON parses
+   - SSoT metadata validates
+   - sample hub count matches SSoT
+   - tools hub count matches SSoT
+   - known-bad links remain absent
+   - no second active source exists
+
+8. Write populated reports:
+   - docs/dev/reports/ssot_relationship_load_validation_11_121.txt
+   - docs/dev/reports/relationships_fixed_11_121.txt
+   - docs/dev/reports/relationships_removed_11_121.txt
+   - docs/dev/reports/relationships_working_11_121.txt
+   - docs/dev/reports/validation_after_11_121.txt
+
+9. Reports must include final count.
+
+10. Roadmap:
    - status-only update if execution-backed
    - do not rewrite roadmap text
    - do not delete roadmap text
 
-13. Package Codex output ZIP at:
-   tmp/PR_11_120_SAMPLE_TOOL_LINK_COUNT_RECONCILIATION.zip
+11. Package Codex output ZIP at:
+   tmp/PR_11_121_VALIDATE_SSOT_TOOL_RELATIONSHIPS_LOAD_DIRECT_JSON.zip

docs/dev/commit_comment.txt

@@ -1 +1 @@
-Reconcile sample tool link counts through a single metadata SSoT - PR 11.120
+Validate SSoT sample tool relationships load direct JSON - PR 11.121

docs/dev/reports/relationships_fixed_11_121.txt

@@ -0,0 +1,33 @@
+PR 11.121 - Relationships Fixed
+
+Files changed
+- tools/schemas/tools/palette-browser.schema.json
+
+Fix applied
+- Updated `tools/schemas/tools/palette-browser.schema.json` so the canonical Palette Browser schema validates both existing direct palette JSON files and the workspace-wrapped Palette Browser tool payload.
+- This is schema-only contract alignment. No sample palette data was rewritten, wrapped, normalized, or replaced.
+- The direct sample palette JSON files already declared `schema: html-js-gaming.palette` and contained real `swatches`; the stale schema was the deterministic mismatch.
+
+Relationships fixed by this schema alignment
+- 0213: direct palette JSON `samples/phase-02/0213/sample.0213.palette.json` now validates against `tools/schemas/tools/palette-browser.schema.json`.
+- 0219: direct palette JSON `samples/phase-02/0219/sample.0219.palette.json` now validates against `tools/schemas/tools/palette-browser.schema.json`.
+- 0301: direct palette JSON `samples/phase-03/0301/sample.0301.palette.json` now validates against `tools/schemas/tools/palette-browser.schema.json`.
+- 0302: direct palette JSON `samples/phase-03/0302/sample.0302.palette.json` now validates against `tools/schemas/tools/palette-browser.schema.json`.
+- 0308: direct palette JSON `samples/phase-03/0308/sample.0308.palette.json` now validates against `tools/schemas/tools/palette-browser.schema.json`.
+- 0313: direct palette JSON `samples/phase-03/0313/sample.0313.palette.json` now validates against `tools/schemas/tools/palette-browser.schema.json`.
+- 0901: direct palette JSON `samples/phase-09/0901/sample.0901.palette.json` now validates against `tools/schemas/tools/palette-browser.schema.json`.
+- 0905: direct palette JSON `samples/phase-09/0905/sample.0905.palette.json` now validates against `tools/schemas/tools/palette-browser.schema.json`.
+- 1204: direct palette JSON `samples/phase-12/1204/sample.1204.palette.json` now validates against `tools/schemas/tools/palette-browser.schema.json`.
+- 1208: direct palette JSON `samples/phase-12/1208/sample.1208.palette.json` now validates against `tools/schemas/tools/palette-browser.schema.json`.
+- 1414: direct palette JSON `samples/phase-14/1414/sample.1414.palette.json` now validates against `tools/schemas/tools/palette-browser.schema.json`.
+
+Validation evidence
+- Before fix: palette relationships failed schema validation with missing `tool` / missing `payload` because the schema only accepted the workspace wrapper shape.
+- After fix: targeted relationship harness reports 31 WORKING / 0 invalid.
+- `node -e "JSON.parse(require('fs').readFileSync('tools/schemas/tools/palette-browser.schema.json','utf8')); console.log('palette schema JSON parse PASS')"`: PASS.
+- `node tests/tools/ToolSchemaStrictModeValidation.test.mjs`: PASS.
+- `node scripts/validate-json-contracts.mjs --mode samples --reportDir docs/dev/reports --details`: PASS, sample_json_schema_validation invalid=0.
+
+Final count
+- Fixed relationships: 11.
+- Remaining SSoT relationships: 31.

docs/dev/reports/relationships_removed_11_121.txt

@@ -0,0 +1,15 @@
+PR 11.121 - Relationships Removed
+
+Removed relationships
+- None.
+
+Reason
+- All 31 SSoT relationships now have explicit JSON input files.
+- All 31 JSON inputs parse.
+- All 31 relationships validate against the identified schema path after the deterministic Palette Browser schema alignment.
+- No relationship required fake data, fallback/default data, or ambiguous ownership cleanup.
+
+Final count
+- Relationships before PR 11.121 validation: 31.
+- Relationships removed: 0.
+- Relationships after PR 11.121 validation: 31.

docs/dev/reports/relationships_working_11_121.txt

@@ -0,0 +1,53 @@
+PR 11.121 - Relationships Working
+
+Working relationship count
+- 31
+
+Counts by tool
+- asset-pipeline: 1
+- palette-browser: 11
+- parallax-editor: 4
+- sprite-editor: 1
+- svg-asset-studio: 3
+- tile-map-editor: 4
+- tile-model-converter: 3
+- vector-map-editor: 3
+- workspace-manager: 1
+
+Working relationships
+- 0213:palette-browser -> samples/phase-02/0213/sample.0213.palette.json (schema: tools/schemas/tools/palette-browser.schema.json)
+- 0219:palette-browser -> samples/phase-02/0219/sample.0219.palette.json (schema: tools/schemas/tools/palette-browser.schema.json)
+- 0221:tile-model-converter -> samples/phase-02/0221/sample.0221.tile-model-converter.json (schema: tools/schemas/tools/tile-model-converter.schema.json)
+- 0301:palette-browser -> samples/phase-03/0301/sample.0301.palette.json (schema: tools/schemas/tools/palette-browser.schema.json)
+- 0302:palette-browser -> samples/phase-03/0302/sample.0302.palette.json (schema: tools/schemas/tools/palette-browser.schema.json)
+- 0305:tile-model-converter -> samples/phase-03/0305/sample.0305.tile-model-converter.json (schema: tools/schemas/tools/tile-model-converter.schema.json)
+- 0308:palette-browser -> samples/phase-03/0308/sample.0308.palette.json (schema: tools/schemas/tools/palette-browser.schema.json)
+- 0313:palette-browser -> samples/phase-03/0313/sample.0313.palette.json (schema: tools/schemas/tools/palette-browser.schema.json)
+- 0901:palette-browser -> samples/phase-09/0901/sample.0901.palette.json (schema: tools/schemas/tools/palette-browser.schema.json)
+- 0905:palette-browser -> samples/phase-09/0905/sample.0905.palette.json (schema: tools/schemas/tools/palette-browser.schema.json)
+- 1204:palette-browser -> samples/phase-12/1204/sample.1204.palette.json (schema: tools/schemas/tools/palette-browser.schema.json)
+- 1208:palette-browser -> samples/phase-12/1208/sample.1208.palette.json (schema: tools/schemas/tools/palette-browser.schema.json)
+- 1208:parallax-editor -> samples/phase-12/1208/sample.1208.parallax-editor.json (schema: tools/schemas/tools/parallax-editor.schema.json)
+- 1208:tile-map-editor -> samples/phase-12/1208/sample.1208.tile-map-editor.json (schema: tools/schemas/tools/tile-map-editor.schema.json)
+- 1209:tile-map-editor -> samples/phase-12/1209/sample.1209.tile-map-editor.json (schema: tools/schemas/tools/tile-map-editor.schema.json)
+- 1209:tile-model-converter -> samples/phase-12/1209/sample.1209.tile-model-converter.json (schema: tools/schemas/tools/tile-model-converter.schema.json)
+- 1210:tile-map-editor -> samples/phase-12/1210/sample.1210.tile-map-editor.json (schema: tools/schemas/tools/tile-map-editor.schema.json)
+- 1211:tile-map-editor -> samples/phase-12/1211/sample.1211.tile-map-editor.json (schema: tools/schemas/tools/tile-map-editor.schema.json)
+- 1212:vector-map-editor -> samples/phase-12/1212/sample-1212-vector-map-editor.json (schema: tools/schemas/tools/vector-map-editor.schema.json)
+- 1213:vector-map-editor -> samples/phase-12/1213/sample-1213-vector-map-editor.json (schema: tools/schemas/tools/vector-map-editor.schema.json)
+- 1214:vector-map-editor -> samples/phase-12/1214/sample-1214-vector-map-editor.json (schema: tools/schemas/tools/vector-map-editor.schema.json)
+- 1215:svg-asset-studio -> samples/phase-12/1215/sample-1215-svg-asset-studio.json (schema: tools/schemas/tools/svg-asset-studio.schema.json)
+- 1216:svg-asset-studio -> samples/phase-12/1216/sample-1216-svg-asset-studio.json (schema: tools/schemas/tools/svg-asset-studio.schema.json)
+- 1217:svg-asset-studio -> samples/phase-12/1217/sample-1217-svg-asset-studio.json (schema: tools/schemas/tools/svg-asset-studio.schema.json)
+- 1218:parallax-editor -> samples/phase-12/1218/sample-1218-parallax-editor.json (schema: tools/schemas/tools/parallax-editor.schema.json)
+- 1219:parallax-editor -> samples/phase-12/1219/sample-1219-parallax-editor.json (schema: tools/schemas/tools/parallax-editor.schema.json)
+- 1220:parallax-editor -> samples/phase-12/1220/sample-1220-parallax-editor.json (schema: tools/schemas/tools/parallax-editor.schema.json)
+- 1413:asset-pipeline -> samples/phase-14/1413/sample.1413.asset-pipeline.json (schema: tools/schemas/tools/asset-pipeline.schema.json)
+- 1414:palette-browser -> samples/phase-14/1414/sample.1414.palette.json (schema: tools/schemas/tools/palette-browser.schema.json)
+- 1414:sprite-editor -> samples/phase-14/1414/sample.1414.sprite-editor.json (schema: tools/schemas/tools/sprite-editor.schema.json)
+- 1902:workspace-manager -> samples/phase-19/1902/sample.1902.workspace-all-tools.json (schema: tools/schemas/workspace.manifest.schema.json)
+
+Direct JSON/source statement
+- Every listed relationship has an explicit `roundtripToolPresets[].presetPath` in `samples/metadata/samples.index.metadata.json`.
+- No relationship in this report is counted from raw `toolHints`, `toolsUsed`, generated samples2tools maps, or inferred sample folder JSON scans.
+- Sample 1902 remains one `workspace-manager` relationship and does not restore direct all-tool fan-out links.