Add MASTER_ROADMAP_SAMPLES2TOOLS with phased sample-to-tool integration plan, shared sample-xxxx.json contract, validation gates, and a parity-based Phase 20 decommission step.

Author: DavidQ

docs/dev/roadmaps/MASTER_ROADMAP_SAMPLES2TOOLS.md

@@ -0,0 +1,121 @@
+# MASTER ROADMAP - SAMPLES TO TOOLS
+
+## Status Key
+- [x] complete
+- [.] in progress
+- [ ] planned
+
+## Goal
+- Establish a single source of truth sample-data lane where sample JSON is reused by both:
+- sample execution (`samples/phase-xx/xxxx/index.html`)
+- tool preload flows (`tools/<tool>/index.html?...`)
+- Exclude `Phase 20 - Tool Preset Integration` from this roadmap lane.
+
+## Source Inputs
+- `tmp/tools_used.txt` (tool sample coverage and candidate sample list)
+- `samples/metadata/samples.index.metadata.json` (sample catalog metadata)
+- `tools/toolRegistry.js` (active tool registry and ids)
+
+## Canonical Data Contract
+- [ ] File naming standard: `samples/phase-xx/xxxx/sample-xxxx.json`
+- [ ] Required fields:
+- `sampleId` (string)
+- `phase` (string)
+- `title` (string)
+- `description` (string)
+- `toolHints` (array of tool ids)
+- `payload` (object, tool-consumable source data)
+- [ ] Optional fields:
+- `runtime` (sample-only materialization hints)
+- `toolState` (tool-specific hydration hints)
+- `provenance` (path, createdAt, version)
+
+## Launch Contract (Shared)
+- [ ] Standard query parameters for tool launch:
+- `sampleId=<id>`
+- `samplePresetPath=/samples/phase-xx/xxxx/sample-xxxx.json`
+- [ ] Tool boot behavior:
+- detect contract params
+- fetch JSON from `samplePresetPath`
+- validate minimal schema
+- map to tool state via tool-specific adapter
+- render status indicating source sample
+
+## Rollout Plan
+
+### Phase 1 - Foundation + One Vertical Slice
+- [ ] Add shared adapter guidance document for sample-to-tool loading.
+- [ ] Implement one full reference flow:
+- sample page loads `sample-xxxx.json`
+- same file is passed to tool launch
+- tool hydrates from same file
+- [ ] Suggested first slice: `Parallax Scene Studio` (clear, low candidate count).
+- [ ] Validate:
+- sample runs using file
+- tool opens from sample and loads matching content
+- no Phase 20 coupling
+
+### Phase 2 - Highest Value Tools (from tools_used.txt)
+- [ ] Parallax Scene Studio (4 candidate samples)
+- [ ] Performance Profiler (2 candidate samples)
+- [ ] Physics Sandbox (2 candidate samples)
+- [ ] Replay Visualizer (3 candidate samples)
+- [ ] Vector Asset Studio (1 candidate sample)
+- [ ] Vector Map Editor (1 candidate sample)
+- [ ] For each:
+- create/link `sample-xxxx.json` in selected sample folders
+- add/open tool link with shared launch contract
+- verify tool state visibly matches sample payload intent
+
+### Phase 3 - Core Editor/Workflow Tools
+- [ ] Sprite Editor (9 candidates)
+- [ ] Tilemap Studio (15 candidates)
+- [ ] Tile Model Converter (18 candidates)
+- [ ] Asset Browser / Import Hub (8 candidates)
+- [ ] Asset Pipeline Tool (10 candidates)
+- [ ] Palette Browser / Manager (6 candidates)
+- [ ] State Inspector (26 candidates)
+- [ ] For each tool:
+- select top 3-5 high-signal non-Phase-20 samples first
+- wire shared JSON loading
+- confirm deterministic load behavior
+
+### Phase 4 - 3D Utility Surfaces
+- [ ] 3D JSON Payload Normalizer (41 candidates; prioritize strict map/payload samples)
+- [ ] 3D Asset Viewer (31 candidates; prioritize asset-centric samples)
+- [ ] 3D Camera Path Editor (47 candidates; prioritize camera/path-centric samples)
+- [ ] Select precise, semantically aligned samples only (avoid broad keyword-only linkage).
+
+### Phase 5 - Phase 20 Decommission (After Parity)
+- [ ] Keep `Phase 20 - Tool Preset Integration` active until Samples2Tools parity is execution-validated.
+- [ ] Define parity gate:
+- sample-to-tool launch coverage equals or exceeds current Phase 20 matrix intent.
+- preset/state preload behavior is validated in replacement lane.
+- replacement reports exist and are repeatable.
+- [ ] Mark Phase 20 as `deprecated` in docs once parity gate passes.
+- [ ] Remove Phase 20 links from primary launch surfaces after deprecation window.
+- [ ] Remove Phase 20 artifacts only after final signoff (no dangling references in docs/tests/reports).
+
+## Prioritization Rules
+- [ ] Prefer semantically exact sample-tool matches over high volume.
+- [ ] Limit initial additions per tool card to 2-5 links.
+- [ ] Use non-Phase-20 samples only in this lane.
+- [ ] Maintain stable sample identity (`sample-xxxx.json`) for reproducibility.
+
+## Validation Checklist
+- [ ] Every linked sample has `sample-xxxx.json`.
+- [ ] Sample page consumes same JSON it passes to tool.
+- [ ] Tool launch with `samplePresetPath` succeeds without manual edits.
+- [ ] Tool status includes loaded sample id/path.
+- [ ] Metadata and tool card links resolve correctly.
+- [ ] No regressions to direct tool launch without sample params.
+
+## Reporting Outputs (per execution batch)
+- [ ] `docs/dev/reports/samples2tools_batch_<n>_summary.txt`
+- [ ] `docs/dev/reports/samples2tools_batch_<n>_validation.txt`
+- [ ] `docs/dev/reports/samples2tools_link_map_<n>.json`
+
+## Current Snapshot (from tools_used.txt)
+- [x] Current tagged samples across active tools: `0` (excluding Phase 20)
+- [x] Candidate coverage inventory exists for all active tools
+- [ ] Convert candidates into curated, validated sample-to-tool links