Reconcile sample tool link counts through a single metadata SSoT - PR 11.120

Author: DavidQ

docs/dev/codex_commands.md

@@ -4,93 +4,86 @@ Model: GPT-5.3-codex
 Reasoning: medium
 
 ## PR
-BUILD_PR_LEVEL_11_119_SAMPLE_METADATA_SSOT_AND_RENDERER_GUARD_REMOVAL
+BUILD_PR_LEVEL_11_120_SAMPLE_TOOL_LINK_COUNT_RECONCILIATION
 
 ## Execute
 
-1. Treat this as the correction to PR 11.118.
-
-2. Confirm the active sample tile renderer path:
-   - inspect `samples/index.render.js`
-   - inspect any imports/loaders used by that renderer
-
-3. Make this the only SSoT for sample tile tool roundtrip links:
-   - `samples/metadata/samples.index.metadata.json`
-
-4. Remove renderer/toolhint logic that can create roundtrip links from anything except:
-   - `toolHints`
-   - `roundtripToolPresets`
-   in the metadata SSoT file.
-
-5. Remove logic that:
-   - infers tool hints from sample ids
-   - infers tool hints from sample titles
-   - infers tool hints from sample paths
-   - infers tool hints from JSON files in sample folders
-   - uses fallback/default tool hint arrays
-   - uses samples2tools as active sample tile source
-   - restores stale/generated tool links
-
-6. Ensure empty arrays mean no rendered section:
-   - `toolHints: []`
-   - `roundtripToolPresets: []`
-   must render no `sample-tool-roundtrip` section.
-
-7. Delete or disable stale duplicate source files that can feed sample tile tool links outside the SSoT.
-   - If unsafe to delete, remove runtime loading and report why file remains.
-
-8. Validate these known-bad links cannot render:
-   - 0201: 3D Camera Path Editor or unrelated Open Tool links
-   - 0202: unrelated Open Tool links
-   - 0204: unrelated Open Tool links
-   - 0210: unrelated Open Tool links
-   - 0220: unrelated Open Tool links
-   - 0221: 3D JSON Payload Normalizer / 3D JSON Payload / 3d-json-payload
-   - 0226: unrelated Open Tool links
-   - 0227: unrelated Open Tool links
-   - 0303: unrelated Open Tool 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 Open Tool links
-
-9. Do not add a runtime hardcoded denylist as the final fix.
-   - A temporary validation assertion is allowed only in tests/reports.
-
-10. Do not:
-   - add fake data
-   - add fallback/default/preset inputs
-   - reintroduce normalization
-   - reintroduce inference
-   - delete samples
-
-11. Validate:
-   - changed JSON parses
-   - changed JS syntax is valid
-   - 0201 metadata empty arrays render no roundtrip section
-   - known-bad links absent from active runtime-loaded source
+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.
+
+4. Update sample hub renderer and tools hub renderer/loading so both read from:
+   - 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
 
-12. Write populated reports:
-   - docs/dev/reports/sample_metadata_ssot_11_119.txt
-   - docs/dev/reports/renderer_toolhint_cleanup_11_119.txt
-   - docs/dev/reports/stale_roundtrip_sources_11_119.txt
-   - docs/dev/reports/known_bad_links_validation_11_119.txt
+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
 
-13. Reports must include:
+11. Reports must include:
    - files searched
-   - files changed
-   - exact removed logic
+   - counts before/after
+   - entries added
+   - entries removed
+   - blocked entries
    - chosen SSoT
-   - validation evidence for 0201
-   - blockers if any
+   - validation commands/results
 
-14. Roadmap:
+12. Roadmap:
    - status-only update if execution-backed
    - do not rewrite roadmap text
    - do not delete roadmap text
 
-15. Package Codex output ZIP at:
-   tmp/PR_11_119_SAMPLE_METADATA_SSOT_AND_RENDERER_GUARD_REMOVAL.zip
+13. Package Codex output ZIP at:
+   tmp/PR_11_120_SAMPLE_TOOL_LINK_COUNT_RECONCILIATION.zip

docs/dev/commit_comment.txt

@@ -1 +1 @@
-Enforce sample metadata SSoT and remove renderer tool-link inference - PR 11.119
+Reconcile sample tool link counts through a single metadata SSoT - PR 11.120

docs/dev/reports/sample_tool_relationship_reconciliation_11_120.txt

@@ -0,0 +1,109 @@
+PR 11.120 - Sample/Tool Relationship Reconciliation
+
+Chosen SSoT
+- samples/metadata/samples.index.metadata.json
+
+Files searched
+- docs/pr/BUILD_PR_LEVEL_11_120_SAMPLE_TOOL_LINK_COUNT_RECONCILIATION.md
+- tools/index.html
+- tools/renderToolsIndex.js
+- samples/index.html
+- samples/index.render.js
+- samples/shared/sampleDetailPageEnhancement.js
+- samples/metadata/samples.index.metadata.json
+- samples/phase-12/*/index.html
+- docs/dev/reports/samples2tools_link_map_*.json
+
+Files changed
+- samples/metadata/samples.index.metadata.json
+- samples/index.render.js
+- tools/renderToolsIndex.js
+- 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
+
+Baseline counts
+- BUILD-reported tools/index expected relationship count: 34.
+- BUILD-reported samples/index rendered Open Tool link count: 22.
+- User-observed current samples/index link count after prior cleanup: 31.
+- User-observed current tools/index Samples count after prior cleanup: 30.
+
+Reconciled counts
+- Final metadata SSoT relationships: 31.
+- Final samples hub visible relationships: 31 total = 30 Open <tool> links + 1 Open with Workspace Manager link.
+- Final tools hub Samples counts: 31.
+- samples/index.html and tools/index.html now agree at 31.
+
+Entries added or restored to SSoT
+- 1208:tile-map-editor -> /samples/phase-12/1208/sample.1208.tile-map-editor.json
+- 1208:parallax-editor -> /samples/phase-12/1208/sample.1208.parallax-editor.json
+- 1209:tile-map-editor -> /samples/phase-12/1209/sample.1209.tile-map-editor.json
+- 1210:tile-map-editor -> /samples/phase-12/1210/sample.1210.tile-map-editor.json
+- 1211:tile-map-editor -> /samples/phase-12/1211/sample.1211.tile-map-editor.json
+- 1212:vector-map-editor -> /samples/phase-12/1212/sample-1212-vector-map-editor.json
+- 1213:vector-map-editor -> /samples/phase-12/1213/sample-1213-vector-map-editor.json
+- 1214:vector-map-editor -> /samples/phase-12/1214/sample-1214-vector-map-editor.json
+- 1217:svg-asset-studio -> /samples/phase-12/1217/sample-1217-svg-asset-studio.json
+- 1218:parallax-editor -> /samples/phase-12/1218/sample-1218-parallax-editor.json
+- 1219:parallax-editor -> /samples/phase-12/1219/sample-1219-parallax-editor.json
+- 1220:parallax-editor -> /samples/phase-12/1220/sample-1220-parallax-editor.json
+- 1902:workspace-manager -> /samples/phase-19/1902/sample.1902.workspace-all-tools.json
+
+Entries removed from SSoT
+- 1902:vector-map-editor -> replaced by the single 1902:workspace-manager relationship
+- 1902:svg-asset-studio -> replaced by the single 1902:workspace-manager relationship
+- 1902:tile-map-editor -> replaced by the single 1902:workspace-manager relationship
+- 1902:parallax-editor -> replaced by the single 1902:workspace-manager relationship
+- 1902:sprite-editor -> replaced by the single 1902:workspace-manager relationship
+- 1902:skin-editor -> replaced by the single 1902:workspace-manager relationship
+- 1902:asset-browser -> replaced by the single 1902:workspace-manager relationship
+- 1902:palette-browser -> replaced by the single 1902:workspace-manager relationship
+- 1902:state-inspector -> replaced by the single 1902:workspace-manager relationship
+- 1902:replay-visualizer -> replaced by the single 1902:workspace-manager relationship
+- 1902:performance-profiler -> replaced by the single 1902:workspace-manager relationship
+- 1902:physics-sandbox -> replaced by the single 1902:workspace-manager relationship
+- 1902:asset-pipeline -> replaced by the single 1902:workspace-manager relationship
+- 1902:tile-model-converter -> replaced by the single 1902:workspace-manager relationship
+- 1902:3d-json-payload -> replaced by the single 1902:workspace-manager relationship
+- 1902:3d-asset-viewer -> replaced by the single 1902:workspace-manager relationship
+- 1902:3d-camera-path-editor -> replaced by the single 1902:workspace-manager relationship
+
+Renderer reconciliation
+- samples/index.render.js now reads only metadata-backed preset paths for tile roundtrip relationships.
+- samples/index.render.js now builds the 1902 Workspace Manager launch href from roundtripToolPresets instead of a hardcoded sample.1902 path constant.
+- samples/index.render.js derives tool filter tokens from renderable relationships, including workspace-manager for the 1902 workspace link.
+- samples/index.render.js no longer injects a skin-editor filter option when no renderable SSoT relationship exists.
+- tools/renderToolsIndex.js now counts explicit roundtripToolPresets with matching toolHints and presetPath.
+- tools/renderToolsIndex.js now counts workspace-manager and renders Samples (1) on the Workspace Manager card.
+- tools/renderToolsIndex.js no longer uses toolsUsed or raw toolHints as the relationship count source.
+
+Why final count is not 34
+- The old 34 count included direct visible-tool fan-out for sample 1902.
+- Sample 1902 is a workspace aggregation sample and must expose only Open with Workspace Manager from the sample hub.
+- The 17 prior 1902 direct tool rows were removed from sample metadata as direct relationships.
+- The single valid 1902 relationship is now workspace-manager.
+- The reconciled visible hub count is therefore 31, not 34.
+
+Blocked direct relationships
+- 1902:vector-map-editor - blocked because 1902 is workspace-only and launches through Workspace Manager
+- 1902:svg-asset-studio - blocked because 1902 is workspace-only and launches through Workspace Manager
+- 1902:tile-map-editor - blocked because 1902 is workspace-only and launches through Workspace Manager
+- 1902:parallax-editor - blocked because 1902 is workspace-only and launches through Workspace Manager
+- 1902:sprite-editor - blocked because 1902 is workspace-only and launches through Workspace Manager
+- 1902:skin-editor - blocked because 1902 is workspace-only and launches through Workspace Manager
+- 1902:asset-browser - blocked because 1902 is workspace-only and launches through Workspace Manager
+- 1902:palette-browser - blocked because 1902 is workspace-only and launches through Workspace Manager
+- 1902:state-inspector - blocked because 1902 is workspace-only and launches through Workspace Manager
+- 1902:replay-visualizer - blocked because 1902 is workspace-only and launches through Workspace Manager
+- 1902:performance-profiler - blocked because 1902 is workspace-only and launches through Workspace Manager
+- 1902:physics-sandbox - blocked because 1902 is workspace-only and launches through Workspace Manager
+- 1902:asset-pipeline - blocked because 1902 is workspace-only and launches through Workspace Manager
+- 1902:tile-model-converter - blocked because 1902 is workspace-only and launches through Workspace Manager
+- 1902:3d-json-payload - blocked because 1902 is workspace-only and launches through Workspace Manager
+- 1902:3d-asset-viewer - blocked because 1902 is workspace-only and launches through Workspace Manager
+- 1902:3d-camera-path-editor - blocked because 1902 is workspace-only and launches through Workspace Manager
+
+Blockers
+- None.

docs/dev/reports/sample_tool_ssot_after_11_120.txt

@@ -0,0 +1,77 @@
+PR 11.120 - SSoT After Reconciliation
+
+Active SSoT
+- samples/metadata/samples.index.metadata.json
+
+Runtime readers
+- samples/index.render.js reads samples/metadata/samples.index.metadata.json for sample tile links.
+- tools/renderToolsIndex.js reads samples/metadata/samples.index.metadata.json for Samples (x) counts.
+- samples/shared/sampleDetailPageEnhancement.js reads samples/metadata/samples.index.metadata.json for sample detail metadata.
+
+No second active hub source
+- No samples2tools runtime file is imported by samples/index.render.js.
+- No generated link-map report is imported by samples/index.render.js or tools/renderToolsIndex.js.
+- tools/renderToolsIndex.js no longer falls back to toolsUsed/raw toolHints counts.
+- samples/index.render.js no longer uses a hardcoded sample.1902 workspace preset constant.
+- samples/index.render.js no longer injects a fallback skin-editor filter option.
+
+Explicit metadata relationships after PR 11.120
+- Total SSoT relationships with matching toolHints and presetPath: 31.
+- Direct Open <tool> relationships: 30.
+- Workspace Manager relationships: 1.
+
+Entries added or restored
+- 1208:tile-map-editor -> /samples/phase-12/1208/sample.1208.tile-map-editor.json
+- 1208:parallax-editor -> /samples/phase-12/1208/sample.1208.parallax-editor.json
+- 1209:tile-map-editor -> /samples/phase-12/1209/sample.1209.tile-map-editor.json
+- 1210:tile-map-editor -> /samples/phase-12/1210/sample.1210.tile-map-editor.json
+- 1211:tile-map-editor -> /samples/phase-12/1211/sample.1211.tile-map-editor.json
+- 1212:vector-map-editor -> /samples/phase-12/1212/sample-1212-vector-map-editor.json
+- 1213:vector-map-editor -> /samples/phase-12/1213/sample-1213-vector-map-editor.json
+- 1214:vector-map-editor -> /samples/phase-12/1214/sample-1214-vector-map-editor.json
+- 1217:svg-asset-studio -> /samples/phase-12/1217/sample-1217-svg-asset-studio.json
+- 1218:parallax-editor -> /samples/phase-12/1218/sample-1218-parallax-editor.json
+- 1219:parallax-editor -> /samples/phase-12/1219/sample-1219-parallax-editor.json
+- 1220:parallax-editor -> /samples/phase-12/1220/sample-1220-parallax-editor.json
+- 1902:workspace-manager -> /samples/phase-19/1902/sample.1902.workspace-all-tools.json
+
+Entries removed
+- 1902:vector-map-editor
+- 1902:svg-asset-studio
+- 1902:tile-map-editor
+- 1902:parallax-editor
+- 1902:sprite-editor
+- 1902:skin-editor
+- 1902:asset-browser
+- 1902:palette-browser
+- 1902:state-inspector
+- 1902:replay-visualizer
+- 1902:performance-profiler
+- 1902:physics-sandbox
+- 1902:asset-pipeline
+- 1902:tile-model-converter
+- 1902:3d-json-payload
+- 1902:3d-asset-viewer
+- 1902:3d-camera-path-editor
+
+Known-bad links remain absent
+- 0201: no 3D Camera Path Editor or unrelated links
+- 0202: no unrelated links
+- 0204: no unrelated links
+- 0210: no unrelated links
+- 0220: no unrelated links
+- 0221: no 3D JSON Payload / 3d-json-payload link
+- 0226: no unrelated links
+- 0227: no unrelated links
+- 0303: no unrelated links
+- 0305: no 3D JSON Payload / 3d-json-payload link
+- 0901: no Vector Map Editor link
+- 1204: no SVG Asset Studio link
+- 1205: no Vector Map Editor link
+- 1208: no 3D Asset Viewer or SVG Asset Studio link
+- 1319: no unrelated links
+
+Notes
+- sample 1902 remains a workspace aggregation sample.
+- sample 1902 workspace-supported tool payload coverage remains inside samples/phase-19/1902/sample.1902.workspace-all-tools.json.
+- Metadata now records the sample hub relationship truthfully as 1902:workspace-manager only.