# Codex Commands — BUILD_PR_LEVEL_20_8_IMPLEMENT_TOOL_LAUNCH_SSOT_ROUTING

## Model
GPT-5.4 or GPT-5.3-codex

## Reasoning
High

## Command

```text
Read docs/dev/codex_rules.md first.
Read docs/dev/specs/TOOL_LAUNCH_SSOT.md second.

Execute BUILD_PR_LEVEL_20_8_IMPLEMENT_TOOL_LAUNCH_SSOT_ROUTING.

Goal:
Implement the first runtime slice of TOOL_LAUNCH_SSOT.

Required behavior:
- samples launch tools through tools/<tool>/index.html
- games launch workspace flows through tools/Workspace Manager/index.html
- external launches from samples/games clear launch memory before loading
- launch data comes from the existing single source of truth
- no default/fallback route/tool/workspace behavior in touched launch flow
- invalid or missing launch context fails visibly

Hard constraints:
- smallest valid change
- no unrelated cleanup
- no repo-wide rewrite
- no start_of_day changes
- no roadmap text rewrite except status markers
- no anti-patterns listed in docs/dev/codex_rules.md

Validation:
Create docs/dev/reports/tool_launch_ssot_routing_validation.md with:
- changed files
- tested UAT paths
- proof samples route to tools/<tool>/index.html
- proof games route to tools/Workspace Manager/index.html
- proof external launch memory is cleared
- proof missing context does not fallback
- anti-pattern self-check

Return ZIP at:
tmp/BUILD_PR_LEVEL_20_8_IMPLEMENT_TOOL_LAUNCH_SSOT_ROUTING.zip
```

Author: DavidQ

docs/dev/codex_rules.md

@@ -1,59 +1,55 @@
 # Codex Rules (MANDATORY — HARD CONSTRAINTS)
 
 These rules OVERRIDE all other instructions.
-If any rule is violated, the output is incorrect.
 
 Codex must prefer the existing repo pattern over any new pattern, unless the PR explicitly says otherwise.
 
-## Baseline
+## Required Spec
 
-The last known assistant-produced baseline is:
+Read and obey:
 
-- commit: `3f7e9df`
-- PR: `BUILD_PR_LEVEL_20_1_PHASE20_TOOL_PRESET_INTEGRATION`
+- docs/dev/specs/TOOL_LAUNCH_SSOT.md
 
-All recovery analysis must compare current repo state against this baseline.
+## This PR
 
-## Recovery Safety
+Allowed:
+- smallest implementation changes needed for launch routing SSoT
+- validation report
+- roadmap status marker update only if execution-backed
 
-- Do NOT run destructive git commands.
-- Do NOT run `git reset --hard`.
-- Do NOT delete files.
-- Do NOT modify implementation files in this PR.
-- Do NOT rewrite roadmap text.
-- Do NOT modify `start_of_day` folders.
-- Do NOT invent fallback/default behavior.
-- Do NOT preserve junk code silently.
+Forbidden:
+- broad cleanup
+- unrelated refactoring
+- new route systems
+- fallback/default behavior
+- implementation outside touched launch path
+- start_of_day changes
+- roadmap text rewrite
 
-## Anti-Patterns Strictly Forbidden
+## Anti-Patterns Forbidden
 
-- variable aliasing: one concept renamed into another variable
+- variable aliasing
 - pass-through variables
 - duplicate state
 - stored derived state
-- vague names such as data, temp, obj, item, thing, value
+- vague names
 - hidden fallback behavior
-- default behavior where explicit routing is required
-- broad truthy/falsy checks that alter behavior
-- magic strings or magic numbers
+- duplicated launch paths
+- silent redirects
+- broad truthy/falsy behavior changes
+- magic strings or magic numbers outside existing SSoT/config pattern
 - duplicate event listeners
 - globals
-- new managers/factories/service layers unless explicitly requested
-- route/URL/ID/label changes unless explicitly requested
-- public API changes unless explicitly requested
-- unrelated cleanup
-- unrelated refactoring
+- new managers/factories/service layers unless already required by existing pattern
+- public API changes unless required by this PR
 - scope expansion
-- duplicated launch paths
-- sample/game launch bypasses
-- workspace launch memory carryover from external entry
-
-## Validation
 
-Before completing, verify:
+## Required Failure Behavior
 
-- no implementation files changed
-- no destructive command used
-- all required reports exist
-- reset recommendation is explicit
-- all identified anti-patterns include file paths
+If launch context is missing or invalid:
+- fail visibly
+- report the missing field
+- do not guess
+- do not select the first item
+- do not reuse memory
+- do not silently redirect

docs/dev/reports/tool_launch_ssot_routing_validation.md

@@ -0,0 +1,130 @@
+# Tool Launch SSoT Routing Validation
+
+## Changed Files
+
+- `tools/shared/toolLaunchSSoT.js`
+- `games/index.render.js`
+- `docs/dev/reports/tool_launch_ssot_routing_validation.md`
+
+## Tested UAT Paths
+
+1. Samples hub roundtrip launch href resolution via `resolveSampleToolLaunchHref(...)`.
+2. Games hub workspace launch href resolution via `resolveGameWorkspaceLaunchHref(...)`.
+3. External launch memory clearing via `clearExternalToolWorkspaceMemory()` and `launchWithExternalToolWorkspaceReset(...)`.
+4. Missing launch context handling for:
+   - sample launch missing `sampleId`
+   - games metadata entries missing valid `href`
+
+## Proof: Samples Route To `tools/<tool>/index.html`
+
+Command run:
+
+```bash
+node --input-type=module -
+```
+
+Script output:
+
+```text
+sampleLaunch {
+  href: '/tools/Sprite%20Editor/index.html?sampleId=1208&sampleTitle=Tool+Formatted+Tiles+Parallax',
+  error: ''
+}
+```
+
+Implementation references:
+
+- `tools/shared/toolLaunchSSoT.js:75`
+- `tools/shared/toolLaunchSSoT.js:91`
+- `samples/index.render.js:92`
+
+## Proof: Games Route To `tools/Workspace Manager/index.html`
+
+Command run:
+
+```bash
+node --input-type=module -
+```
+
+Script output:
+
+```text
+gameLaunch {
+  href: '/tools/Workspace%20Manager/index.html?gameId=2001&mount=game',
+  error: ''
+}
+```
+
+Implementation references:
+
+- `tools/shared/toolLaunchSSoT.js:105`
+- `tools/shared/toolLaunchSSoT.js:117`
+- `tools/shared/toolLaunchSSoT.js:118`
+- `games/index.render.js:147`
+
+## Proof: External Launch Memory Is Cleared
+
+Command run:
+
+```bash
+node --input-type=module -
+```
+
+Script output:
+
+```text
+clearResult true
+localAfterClear [ [ 'keep.one', 'x' ] ]
+sessionAfterClear [ [ 'keep.two', 'y' ] ]
+launchResult true
+assignCalls [ '/tools/Sprite%20Editor/index.html?sampleId=1208' ]
+localAfterLaunch [ [ 'keep.one', 'x' ] ]
+sessionAfterLaunch [ [ 'keep.two', 'y' ] ]
+```
+
+Implementation references:
+
+- `tools/shared/toolLaunchSSoT.js:123`
+- `tools/shared/toolLaunchSSoT.js:140`
+- `samples/index.render.js:537`
+- `games/index.render.js:424`
+- `games/index.render.js:444`
+
+## Proof: Missing Context Does Not Fallback
+
+1. Sample launch now requires `sampleId`; missing context returns explicit error and empty href:
+
+```text
+missingSampleContext { href: '', error: 'Tool "sprite-editor" launch is missing sampleId.' }
+```
+
+2. Games rows missing valid game `href` now emit explicit visible launch errors instead of silent empty launch state:
+
+- `games/index.render.js:147`
+- `games/index.render.js:271`
+- `games/index.render.js:336`
+
+3. Workspace launch links are only bound when explicit `workspaceHref` exists, so missing context cannot route through a fallback launcher:
+
+- `games/index.render.js:266`
+- `games/index.render.js:416`
+
+## Static Validation
+
+Commands run:
+
+```bash
+node --check tools/shared/toolLaunchSSoT.js
+node --check games/index.render.js
+node --check samples/index.render.js
+```
+
+All commands exited successfully.
+
+## Anti-Pattern Self-Check
+
+- No new duplicate launch state introduced.
+- No new hidden/default/fallback launch route added in touched flow.
+- No duplicate event listeners added.
+- No new globals/managers/factories introduced.
+- No unrelated files changed for behavior.

docs/operations/dev/codex_commands.md

@@ -1,4 +1,4 @@
-# Codex Commands — BUILD_PR_LEVEL_20_5_RECOVERY_AUDIT_FROM_20_1_BASELINE
+# Codex Commands — BUILD_PR_LEVEL_20_8_IMPLEMENT_TOOL_LAUNCH_SSOT_ROUTING
 
 ## Model
 GPT-5.4 or GPT-5.3-codex
@@ -10,57 +10,39 @@ High
 
 ```text
 Read docs/dev/codex_rules.md first.
+Read docs/dev/specs/TOOL_LAUNCH_SSOT.md second.
 
-Execute BUILD_PR_LEVEL_20_5_RECOVERY_AUDIT_FROM_20_1_BASELINE.
-
-Baseline:
-- commit: 3f7e9df
-- PR: BUILD_PR_LEVEL_20_1_PHASE20_TOOL_PRESET_INTEGRATION
-- commit message: Add Phase 20 numbered tool presets and sample-to-tool launch integration
+Execute BUILD_PR_LEVEL_20_8_IMPLEMENT_TOOL_LAUNCH_SSOT_ROUTING.
 
 Goal:
-Audit every change after 3f7e9df and recommend whether to reset to 3f7e9df or clean surgically.
-
-Hard constraints:
-- No implementation code changes.
-- No git reset.
-- No file deletion.
-- No roadmap rewrite.
-- No start_of_day changes.
-- Create reports only.
-
-Run and capture these inspections:
-- git status --short
-- git branch --show-current
-- git rev-parse HEAD
-- git log 3f7e9df..HEAD --oneline --decorate --name-status
-- git diff --stat 3f7e9df..HEAD
-- git diff --name-status 3f7e9df..HEAD
-- git diff --check 3f7e9df..HEAD
-- git ls-files --others --exclude-standard
+Implement the first runtime slice of TOOL_LAUNCH_SSOT.
 
-Also inspect current UAT-relevant files if present:
-- games/index.html
-- samples/index.html
-- tools/Workspace Manager/index.html
-- tools/*/index.html
-- docs/dev/roadmaps/MASTER_ROADMAP_ENGINE.md
+Required behavior:
+- samples launch tools through tools/<tool>/index.html
+- games launch workspace flows through tools/Workspace Manager/index.html
+- external launches from samples/games clear launch memory before loading
+- launch data comes from the existing single source of truth
+- no default/fallback route/tool/workspace behavior in touched launch flow
+- invalid or missing launch context fails visibly
 
-Required outputs:
-- docs/dev/reports/recovery_change_audit_from_20_1.md
-- docs/dev/reports/recovery_antipattern_audit_from_20_1.md
-- docs/dev/reports/recovery_reset_decision_from_20_1.md
-- docs/dev/reports/recovery_file_risk_list_from_20_1.md
-
-In recovery_reset_decision_from_20_1.md include:
-- recommended path
-- whether reset to 3f7e9df is safer than surgical cleanup
-- files to preserve
-- files to discard
-- files requiring manual review
-- exact next APPLY_PR name
-- exact reason for the recommendation
-
-Return a ZIP artifact at:
-tmp/BUILD_PR_LEVEL_20_5_RECOVERY_AUDIT_FROM_20_1_BASELINE.zip
+Hard constraints:
+- smallest valid change
+- no unrelated cleanup
+- no repo-wide rewrite
+- no start_of_day changes
+- no roadmap text rewrite except status markers
+- no anti-patterns listed in docs/dev/codex_rules.md
+
+Validation:
+Create docs/dev/reports/tool_launch_ssot_routing_validation.md with:
+- changed files
+- tested UAT paths
+- proof samples route to tools/<tool>/index.html
+- proof games route to tools/Workspace Manager/index.html
+- proof external launch memory is cleared
+- proof missing context does not fallback
+- anti-pattern self-check
+
+Return ZIP at:
+tmp/BUILD_PR_LEVEL_20_8_IMPLEMENT_TOOL_LAUNCH_SSOT_ROUTING.zip
 ```

docs/operations/dev/commit_comment.txt

@@ -1,8 +1,8 @@
-Recovery audit from 20.1 baseline
+Implement tool launch SSoT routing
 
 PR Details:
-- Uses 3f7e9df / BUILD_PR_LEVEL_20_1_PHASE20_TOOL_PRESET_INTEGRATION as the last known assistant-produced baseline.
-- Audits all later changes.
-- Documents anti-patterns and junk code.
-- Produces reset-vs-surgical-cleanup decision.
-- Forbids destructive reset in this PR.
+- Routes sample-launched tools through explicit tools/<tool>/index.html targets.
+- Routes game workspace flows through tools/Workspace Manager/index.html.
+- Clears launch memory for external sample/game launches.
+- Removes default/fallback behavior from touched launch flow.
+- Adds validation report for SSoT routing.