# Codex Commands — BUILD_PR_LEVEL_20_10_REMOVE_LEGACY_LAUNCH_FALLBACK_RESIDUE

DavidQ · DavidQ · commit 75ebe008110d · 2026-04-25T22:00:36.000-04:00
## 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.
Read docs/dev/reports/tool_launch_ssot_routing_validation.md third.
Read docs/dev/reports/tool_launch_ssot_data_layer_validation.md fourth.

Execute BUILD_PR_LEVEL_20_10_REMOVE_LEGACY_LAUNCH_FALLBACK_RESIDUE.

Goal:
Remove remaining legacy launch routing residue and default/fallback behavior from the touched SSoT launch flow.

If either validation report is missing:
- create docs/dev/reports/legacy_launch_fallback_residue_validation.md
- mark status BLOCKED
- explain missing prerequisite
- stop without implementation changes

Required behavior to preserve:
- samples use label: Open &lt;tool&gt;
- samples launch tools through SSoT target paths: tools/&lt;tool&gt;/index.html
- games use label: Open with Workspace Manager
- games launch Workspace Manager through SSoT target path: tools/Workspace Manager/index.html
- external launches from samples/games clear launch memory before loading
- invalid or missing SSoT target/context fails visibly

Remove only in touched launch flow:
- duplicated hardcoded launch paths
- default tool/workspace selections
- fallback routes
- stale memory reuse
- first-item selection
- label-text guessing
- DOM-order guessing
- compatibility branches that bypass SSoT

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
- no second source of truth
- do not alter required label meanings

Validation:
Create docs/dev/reports/legacy_launch_fallback_residue_validation.md with:
- changed files
- exact residue removed
- proof sample actions still say Open &lt;tool&gt;
- proof game actions still say Open with Workspace Manager
- proof sample target paths come from SSoT
- proof game Workspace Manager target path comes from SSoT
- proof external launch memory clear remains intact
- proof missing target/context does not fallback
- anti-pattern self-check

Return ZIP at:
tmp/BUILD_PR_LEVEL_20_10_REMOVE_LEGACY_LAUNCH_FALLBACK_RESIDUE.zip
```
diff --git a/docs/dev/codex_rules.md b/docs/dev/codex_rules.md
@@ -9,36 +9,41 @@ Codex must prefer the existing repo pattern over any new pattern, unless the PR
 Read and obey:
 
 - docs/dev/specs/TOOL_LAUNCH_SSOT.md
-- docs/dev/reports/tool_launch_ssot_routing_validation.md if present
+- docs/dev/reports/tool_launch_ssot_routing_validation.md
+- docs/dev/reports/tool_launch_ssot_data_layer_validation.md
+
+If required reports are missing:
+- create blocked report
+- stop without implementation changes
 
 ## Required UI Labels
 
 Samples:
-- use `Open <tool>` for sample-to-tool launch actions
+- keep `Open <tool>`
 - do NOT use `Open with Workspace Manager`
 
 Games:
-- use `Open with Workspace Manager` for game-to-workspace launch actions
+- keep `Open with Workspace Manager`
 - do NOT use `Open <tool>`
 
 ## This PR
 
 Allowed:
-- create or normalize one launch SSoT data source
-- replace duplicated launch-path reads only where needed
+- remove legacy launch fallback residue only in touched launch flow
+- remove duplicated launch-path constants only when replaced by SSoT
 - validation report
 - roadmap status marker update only if execution-backed
 
 Forbidden:
 - broad cleanup
 - unrelated refactoring
-- new route systems beyond SSoT
+- second SSoT
+- new route systems beyond existing SSoT
 - fallback/default behavior
 - implementation outside touched launch path
 - start_of_day changes
 - roadmap text rewrite
 - changing required UI label semantics
-- second source of truth
 
 ## Anti-Patterns Forbidden
 
@@ -57,13 +62,3 @@ Forbidden:
 - new managers/factories/service layers unless already required by existing pattern
 - public API changes unless required by this PR
 - scope expansion
-
-## Required Failure Behavior
-
-If launch SSoT data 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
diff --git a/docs/dev/reports/legacy_launch_fallback_residue_validation.md b/docs/dev/reports/legacy_launch_fallback_residue_validation.md
@@ -0,0 +1,171 @@
+# Legacy Launch Fallback Residue Validation
+
+## Changed Files
+
+- `tools/shared/toolLaunchSSoTData.js`
+- `docs/dev/reports/legacy_launch_fallback_residue_validation.md`
+
+## Exact Residue Removed
+
+1. Removed fallback-style tool lookup that could bypass launch SSoT visibility scope:
+
+- removed `getToolById` usage (full registry lookup)
+- replaced with active+visible-only lookup in launch SSoT data (`findActiveVisibleToolById`)
+
+2. Removed label-text fallback chain in launch SSoT data:
+
+- removed `displayName || name || id`
+- now requires explicit `displayName` from SSoT-backed tool metadata
+
+3. Removed weak missing-target error wording tied to generic registry presence:
+
+- `Tool "..." is not registered.`
+- replaced with SSoT-scoped failure: `Tool "..." is not available in launch SSoT.`
+
+These changes remove compatibility-style branches that could permit non-SSoT launch selection and label guessing.
+
+## Proof Sample Actions Still Say `Open <tool>`
+
+- `samples/index.render.js:104`
+
+```text
+const label = `Open ${normalize(tool.displayName) || normalize(tool.name) || toolId}`;
+```
+
+## Proof Game Actions Still Say `Open with Workspace Manager`
+
+- `games/index.render.js:263`
+
+```text
+Open with Workspace Manager
+```
+
+## Proof Sample Target Paths Come From SSoT
+
+Code path:
+
+- `tools/shared/toolLaunchSSoT.js:68`
+- `tools/shared/toolLaunchSSoT.js:72`
+- `tools/shared/toolLaunchSSoTData.js:53`
+- `tools/shared/toolLaunchSSoTData.js:57`
+- `samples/index.render.js:92`
+
+Command output:
+
+```text
+sampleDefinition {
+  launchDefinition: {
+    launchId: 'tool.sprite-editor',
+    displayName: 'Sprite Editor',
+    targetPath: '/tools/Sprite%20Editor/index.html',
+    allowedLaunchSources: [ 'samples', 'tools', 'workspace', 'internal' ],
+    allowedLaunchTypes: [ 'sample-to-tool', 'tool-internal', 'workspace-internal' ]
+  },
+  error: ''
+}
+sampleLaunch {
+  href: '/tools/Sprite%20Editor/index.html?sampleId=1208&sampleTitle=Tool+Formatted+Tiles+Parallax',
+  error: ''
+}
+```
+
+## Proof Game Workspace Manager Target Path Comes From SSoT
+
+Code path:
+
+- `tools/shared/toolLaunchSSoT.js:101`
+- `tools/shared/toolLaunchSSoT.js:105`
+- `tools/shared/toolLaunchSSoTData.js:67`
+- `games/index.render.js:148`
+
+Command output:
+
+```text
+gameDefinition {
+  launchDefinition: {
+    launchId: 'workspace-manager.game-to-workspace',
+    displayName: 'Workspace Manager',
+    targetPath: '/tools/Workspace%20Manager/index.html',
+    allowedLaunchSources: [ 'games', 'workspace', 'internal' ],
+    allowedLaunchTypes: [ 'game-to-workspace', 'workspace-internal' ]
+  },
+  error: ''
+}
+gameLaunch {
+  href: '/tools/Workspace%20Manager/index.html?gameId=2001&mount=game',
+  error: ''
+}
+```
+
+## Proof External Launch Memory Clear Remains Intact
+
+Code path:
+
+- `tools/shared/toolLaunchSSoT.js:121`
+- `tools/shared/toolLaunchSSoT.js:138`
+- `samples/index.render.js:539`
+- `games/index.render.js:419`
+
+Command output:
+
+```text
+clearResult true
+localAfterClear [ [ 'keep.one', 'x' ] ]
+sessionAfterClear [ [ 'keep.two', 'y' ] ]
+launchResult true
+assignCalls [ '/tools/Workspace%20Manager/index.html?gameId=2001&mount=game' ]
+localAfterLaunch [ [ 'keep.one', 'x' ] ]
+sessionAfterLaunch [ [ 'keep.two', 'y' ] ]
+```
+
+## Proof Missing Target/Context Does Not Fallback
+
+1. Missing target id fails visibly with no route fallback:
+
+```text
+missingSsotTarget {
+  href: '',
+  error: 'Tool "not-a-real-tool" is not available in launch SSoT.'
+}
+```
+
+2. Invalid launch context (source/type) fails visibly with no route fallback:
+
+```text
+disallowedContext {
+  href: '',
+  error: 'Launch "workspace-manager.game-to-workspace" does not allow source "samples".'
+}
+```
+
+3. Resolver still enforces explicit source/type access checks:
+
+- `tools/shared/toolLaunchSSoTData.js:130`
+- `tools/shared/toolLaunchSSoT.js:72`
+- `tools/shared/toolLaunchSSoT.js:105`
+
+## Proof No Default/Fallback Residue Remains In Touched Launch Flow
+
+- No full-registry fallback lookup remains in touched SSoT data path (`getToolById` removed).
+- No label fallback chain remains in touched SSoT data path (`displayName || name || id` removed).
+- Launch selection in touched resolver path remains SSoT-gated by launch id + allowed source/type.
+
+## Static Validation
+
+Commands run:
+
+```bash
+node --check tools/shared/toolLaunchSSoTData.js
+node --check tools/shared/toolLaunchSSoT.js
+node --check samples/index.render.js
+node --check games/index.render.js
+```
+
+All commands exited successfully.
+
+## Anti-Pattern Self-Check
+
+- No second source of truth introduced.
+- No fallback/default route selection introduced.
+- No duplicate listeners or globals introduced.
+- No unrelated cleanup or scope expansion.
diff --git a/docs/operations/dev/codex_commands.md b/docs/operations/dev/codex_commands.md
@@ -1,4 +1,4 @@
-# Codex Commands — BUILD_PR_LEVEL_20_9_TOOL_LAUNCH_SSOT_DATA_LAYER
+# Codex Commands — BUILD_PR_LEVEL_20_10_REMOVE_LEGACY_LAUNCH_FALLBACK_RESIDUE
 
 ## Model
 GPT-5.4 or GPT-5.3-codex
@@ -11,28 +11,37 @@ High
 ```text
 Read docs/dev/codex_rules.md first.
 Read docs/dev/specs/TOOL_LAUNCH_SSOT.md second.
-Read docs/dev/reports/tool_launch_ssot_routing_validation.md if present.
+Read docs/dev/reports/tool_launch_ssot_routing_validation.md third.
+Read docs/dev/reports/tool_launch_ssot_data_layer_validation.md fourth.
 
-Execute BUILD_PR_LEVEL_20_9_TOOL_LAUNCH_SSOT_DATA_LAYER.
+Execute BUILD_PR_LEVEL_20_10_REMOVE_LEGACY_LAUNCH_FALLBACK_RESIDUE.
 
 Goal:
-Create or normalize one runtime launch SSoT data layer for tool/workspace launch targets.
+Remove remaining legacy launch routing residue and default/fallback behavior from the touched SSoT launch flow.
 
-Required behavior:
-- samples continue to use label: Open <tool>
+If either validation report is missing:
+- create docs/dev/reports/legacy_launch_fallback_residue_validation.md
+- mark status BLOCKED
+- explain missing prerequisite
+- stop without implementation changes
+
+Required behavior to preserve:
+- samples use label: Open <tool>
 - samples launch tools through SSoT target paths: tools/<tool>/index.html
-- games continue to use label: Open with Workspace Manager
+- games use label: Open with Workspace Manager
 - games launch Workspace Manager through SSoT target path: tools/Workspace Manager/index.html
-- external launches from samples/games still clear launch memory before loading
-- no default/fallback route/tool/workspace behavior in touched launch flow
-- invalid or missing SSoT target fails visibly
+- external launches from samples/games clear launch memory before loading
+- invalid or missing SSoT target/context fails visibly
 
-SSoT must define:
-- launch id
-- display name
-- target path
-- allowed launch sources
-- allowed launch types
+Remove only in touched launch flow:
+- duplicated hardcoded launch paths
+- default tool/workspace selections
+- fallback routes
+- stale memory reuse
+- first-item selection
+- label-text guessing
+- DOM-order guessing
+- compatibility branches that bypass SSoT
 
 Hard constraints:
 - smallest valid change
@@ -45,18 +54,17 @@ Hard constraints:
 - do not alter required label meanings
 
 Validation:
-Create docs/dev/reports/tool_launch_ssot_data_layer_validation.md with:
-- exact SSoT file path
+Create docs/dev/reports/legacy_launch_fallback_residue_validation.md with:
 - changed files
-- list of launch ids
+- exact residue removed
 - proof sample actions still say Open <tool>
 - proof game actions still say Open with Workspace Manager
 - proof sample target paths come from SSoT
 - proof game Workspace Manager target path comes from SSoT
 - proof external launch memory clear remains intact
-- proof missing target does not fallback
+- proof missing target/context does not fallback
 - anti-pattern self-check
 
 Return ZIP at:
-tmp/BUILD_PR_LEVEL_20_9_TOOL_LAUNCH_SSOT_DATA_LAYER.zip
+tmp/BUILD_PR_LEVEL_20_10_REMOVE_LEGACY_LAUNCH_FALLBACK_RESIDUE.zip
 ```
diff --git a/docs/operations/dev/commit_comment.txt b/docs/operations/dev/commit_comment.txt
@@ -1,9 +1,9 @@
-Create tool launch SSoT data layer
+Remove legacy launch fallback residue
 
 PR Details:
-- Adds/normalizes one authoritative launch metadata source.
-- Keeps sample actions labeled Open <tool>.
-- Keeps game actions labeled Open with Workspace Manager.
-- Routes sample and game launch targets through the SSoT.
+- Removes legacy duplicated launch paths and fallback/default routing from touched SSoT launch flow.
+- Preserves sample labels as Open <tool>.
+- Preserves game labels as Open with Workspace Manager.
+- Keeps sample/game launch targets resolved from the launch SSoT.
 - Preserves external launch memory clear behavior.
-- Adds validation report for SSoT data-layer behavior.
+- Adds validation report for legacy fallback residue removal.
diff --git a/docs/pr/BUILD_PR_LEVEL_20_10_REMOVE_LEGACY_LAUNCH_FALLBACK_RESIDUE.md b/docs/pr/BUILD_PR_LEVEL_20_10_REMOVE_LEGACY_LAUNCH_FALLBACK_RESIDUE.md
diff --git a/tools/shared/toolLaunchSSoTData.js b/tools/shared/toolLaunchSSoTData.js
