Skip to content

Commit 1a4109b

Browse files
author
DavidQ
committed
Validate and lock Phase 20 recovery gate
PR Details: - Validates sample-to-tool launch UAT. - Validates game-to-Workspace Manager launch UAT. - Validates external-launch memory clearing. - Validates no fallback/default launch behavior. - Rechecks Codex anti-pattern rules on the recovery lane. - Updates recovery roadmap status markers only if the gate passes.
1 parent b03a2f8 commit 1a4109b

7 files changed

Lines changed: 427 additions & 50 deletions

‎docs/dev/codex_rules.md‎

Lines changed: 43 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -4,46 +4,48 @@ These rules OVERRIDE all other instructions.
44

55
Codex must prefer the existing repo pattern over any new pattern, unless the PR explicitly says otherwise.
66

7-
## Required Inputs
7+
## This PR
88

9-
Read and obey:
9+
This PR is a validation and gate-lock PR.
1010

11-
- docs/dev/specs/TOOL_LAUNCH_SSOT.md
12-
- docs/dev/reports/tool_launch_ssot_routing_validation.md
13-
- docs/dev/reports/tool_launch_ssot_data_layer_validation.md
11+
Allowed:
12+
- validation reports
13+
- recovery roadmap status markers only
14+
- blocked decision report if validation fails
1415

15-
If required reports are missing:
16-
- create blocked report
17-
- stop without implementation changes
16+
Forbidden:
17+
- implementation code changes
18+
- broad cleanup
19+
- unrelated refactoring
20+
- new route systems
21+
- second SSoT
22+
- fallback/default behavior
23+
- start_of_day changes
24+
- roadmap text rewrite outside status markers
25+
- changing required UI labels
1826

1927
## Required UI Labels
2028

2129
Samples:
22-
- keep `Open <tool>`
23-
- do NOT use `Open with Workspace Manager`
30+
- must use `Open <tool>`
2431

2532
Games:
26-
- keep `Open with Workspace Manager`
27-
- do NOT use `Open <tool>`
33+
- must use `Open with Workspace Manager`
2834

29-
## This PR
35+
## Required Launch Targets
3036

31-
Allowed:
32-
- remove legacy launch fallback residue only in touched launch flow
33-
- remove duplicated launch-path constants only when replaced by SSoT
34-
- validation report
35-
- roadmap status marker update only if execution-backed
37+
Samples:
38+
- must route tools to `tools/<tool>/index.html`
3639

37-
Forbidden:
38-
- broad cleanup
39-
- unrelated refactoring
40-
- second SSoT
41-
- new route systems beyond existing SSoT
42-
- fallback/default behavior
43-
- implementation outside touched launch path
44-
- start_of_day changes
45-
- roadmap text rewrite
46-
- changing required UI label semantics
40+
Games:
41+
- must route Workspace Manager to `tools/Workspace Manager/index.html`
42+
43+
## Required Memory Behavior
44+
45+
External launches from samples or games:
46+
- must clear launch memory before loading target
47+
- must not reuse stale state
48+
- must not fallback to old context
4749

4850
## Anti-Patterns Forbidden
4951

@@ -56,9 +58,19 @@ Forbidden:
5658
- duplicated launch paths
5759
- silent redirects
5860
- broad truthy/falsy behavior changes
59-
- magic strings or magic numbers outside SSoT/config pattern
61+
- magic strings outside SSoT/config pattern
6062
- duplicate event listeners
6163
- globals
62-
- new managers/factories/service layers unless already required by existing pattern
63-
- public API changes unless required by this PR
64+
- new managers/factories/service layers
65+
- public API changes
6466
- scope expansion
67+
68+
## Required Failure Behavior
69+
70+
If launch SSoT data is missing or invalid:
71+
- fail visibly
72+
- report the missing field
73+
- do not guess
74+
- do not select the first item
75+
- do not reuse memory
76+
- do not silently redirect

‎docs/dev/reports/phase20_codex_rules_recheck.md‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
# Phase 20 Codex Rules Recheck
2+
3+
## Status
4+
5+
BLOCKED
6+
7+
## Recheck Scope
8+
9+
- `tools/shared/toolLaunchSSoTData.js`
10+
- `tools/shared/toolLaunchSSoT.js`
11+
- `samples/index.render.js`
12+
- `games/index.render.js`
13+
- `tools/Workspace Manager/main.js` (Workspace Manager UAT gate path)
14+
15+
## Rule Checks
16+
17+
- no alias variables: PASS
18+
- no pass-through variables: PASS
19+
- no duplicate launch state: PASS
20+
- no duplicated launch paths in SSoT resolver path: PASS
21+
- no silent redirects: PASS
22+
- no stale memory reuse: PASS
23+
- no label-text guessing: PASS
24+
- no DOM-order guessing: PASS
25+
- no default/fallback behavior in recovery gate path: FAIL
26+
27+
## Failing Evidence
28+
29+
Default/fallback residues still present in Workspace Manager gate-path file:
30+
31+
- `tools/Workspace Manager/main.js:270` -> `return toolIds[0] || "";`
32+
- `tools/Workspace Manager/main.js:463` -> select fallback to `toolIds[0]`
33+
- `tools/Workspace Manager/main.js:475` -> `initialToolId` fallback to `toolIds[0]`
34+
- `tools/Workspace Manager/main.js:153` -> query compatibility fallback `gameId || game`
35+
- `tools/Workspace Manager/main.js:284` -> query compatibility fallback `game || gameId`
36+
37+
## Conclusion
38+
39+
Codex rules recheck fails on the no-default/no-fallback requirement for gate lock.
40+
41+
Required follow-up:
42+
43+
`BUILD_PR_LEVEL_20_13_REMOVE_WORKSPACE_MANAGER_DEFAULT_AND_QUERY_FALLBACKS`

‎docs/dev/reports/phase20_recovery_gate_decision.md‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
# Phase 20 Recovery Gate Decision
2+
3+
BLOCKED - recovery gate remains open
4+
5+
## Exact Blocker
6+
7+
Workspace Manager launch flow still contains default/fallback residue in the validated path file.
8+
9+
## File Path
10+
11+
- `tools/Workspace Manager/main.js`
12+
13+
## Failing UAT Path
14+
15+
`games/index.html -> Open with Workspace Manager -> tools/Workspace Manager/index.html?gameId=<id>&mount=game`
16+
17+
Blocking fallback/default residues found:
18+
19+
- default first-item selection: `toolIds[0]` at lines 270, 463, 475
20+
- legacy query fallback compatibility: `gameId || game` at lines 153 and 284
21+
22+
## Next Required BUILD_PR
23+
24+
`BUILD_PR_LEVEL_20_13_REMOVE_WORKSPACE_MANAGER_DEFAULT_AND_QUERY_FALLBACKS`

‎docs/dev/reports/phase20_recovery_uat_validation.md‎

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
# Phase 20 Recovery UAT Validation
2+
3+
## Status
4+
5+
BLOCKED
6+
7+
## Required Inputs Read
8+
9+
- `docs/dev/codex_rules.md`
10+
- `docs/dev/reports/tool_launch_ssot_routing_validation.md`
11+
- `docs/dev/reports/tool_launch_ssot_data_layer_validation.md`
12+
- `docs/dev/reports/legacy_launch_fallback_residue_validation.md`
13+
14+
`docs/dev/specs/TOOL_LAUNCH_SSOT.md` is still not present at the requested path in this repository.
15+
16+
## Validation Scope
17+
18+
Validation-only pass. No runtime implementation changes were made.
19+
20+
## Samples Validation
21+
22+
Result: PASS
23+
24+
- Action label remains `Open <tool>` in `samples/index.render.js:104`.
25+
- Sample launch resolves through SSoT resolver in `samples/index.render.js:92` and `tools/shared/toolLaunchSSoT.js:62`.
26+
- Target path resolves to `tools/<tool>/index.html` via SSoT data (`tools/shared/toolLaunchSSoTData.js:53`, `tools/shared/toolLaunchSSoTData.js:57`).
27+
- External launch memory clear remains in use through `launchWithExternalToolWorkspaceReset` (`samples/index.render.js:539`, `tools/shared/toolLaunchSSoT.js:121`, `tools/shared/toolLaunchSSoT.js:138`).
28+
- Missing/invalid context fails visibly:
29+
- `sampleMissingContext { href: '', error: 'Tool "sprite-editor" launch is missing sampleId.' }`
30+
- `sampleMissingTarget { href: '', error: 'Tool "not-a-real-tool" is not available in launch SSoT.' }`
31+
- No default/fallback route chosen in sample launch resolver path.
32+
33+
## Games Validation
34+
35+
Result: PASS
36+
37+
- Action label remains `Open with Workspace Manager` in `games/index.render.js:263`.
38+
- Game launch resolves through SSoT resolver in `games/index.render.js:148` and `tools/shared/toolLaunchSSoT.js:95`.
39+
- Target path resolves to `tools/Workspace Manager/index.html` via SSoT data (`tools/shared/toolLaunchSSoTData.js:67`).
40+
- External launch memory clear remains in use through `launchWithExternalToolWorkspaceReset` (`games/index.render.js:419`, `tools/shared/toolLaunchSSoT.js:121`, `tools/shared/toolLaunchSSoT.js:138`).
41+
- Missing/invalid context fails visibly:
42+
- invalid source/type returns no href in `gameInvalidContext`.
43+
- missing game metadata href yields visible `Workspace launch error` text (`games/index.render.js:268`, `games/index.render.js:334`).
44+
- No default/fallback route chosen in game launch resolver path.
45+
46+
## Workspace Manager UAT Validation
47+
48+
Result: FAIL
49+
50+
Validated path:
51+
52+
`games/index.html -> Open with Workspace Manager -> /tools/Workspace%20Manager/index.html?gameId=2001&mount=game`
53+
54+
Observed/pass evidence:
55+
56+
- Route is correct from SSoT (`gameLaunch` output).
57+
- Memory clear is executed before navigation (`assignCalls` output after clear).
58+
- Explicit context load logic exists (`writeToolHostSharedContext` with `hostMode: "game"`, `gameId`) in `tools/Workspace Manager/main.js:381-388`.
59+
60+
Blocking evidence (fallback/default residue still present in this touched flow file):
61+
62+
- Default first-item selection remains in Workspace Manager:
63+
- `tools/Workspace Manager/main.js:270` (`return toolIds[0] || "";`)
64+
- `tools/Workspace Manager/main.js:463` and `tools/Workspace Manager/main.js:475` (tool select fallback to `toolIds[0]`).
65+
- Legacy compatibility branch remains for query fallback:
66+
- `tools/Workspace Manager/main.js:153` (`gameId || game`)
67+
- `tools/Workspace Manager/main.js:284` (`searchParams.get("game") || searchParams.get("gameId")`).
68+
69+
These branches violate the gate requirement that validated launch flow should not depend on default/fallback behavior.
70+
71+
## Gate Outcome
72+
73+
- Workspace Manager UAT requirement is not fully satisfied.
74+
- Recovery gate cannot be locked in this PR.
75+
- Next required repair PR: `BUILD_PR_LEVEL_20_13_REMOVE_WORKSPACE_MANAGER_DEFAULT_AND_QUERY_FALLBACKS`.
76+
77+
## Validation Commands Run
78+
79+
- `node --check tools/shared/toolLaunchSSoTData.js`
80+
- `node --check tools/shared/toolLaunchSSoT.js`
81+
- `node --check samples/index.render.js`
82+
- `node --check games/index.render.js`
83+
- `node --check tools/Workspace Manager/main.js`
84+
- module validation scripts for launch ids, route resolution, error behavior, and memory-clear behavior

‎docs/operations/dev/codex_commands.md‎

Lines changed: 70 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,30 +1,85 @@
1-
# Codex Commands — BUILD_PR_LEVEL_20_11_RECOVERY_STATUS_GATE
1+
# Codex Commands — BUILD_PR_LEVEL_20_12_UAT_VALIDATE_AND_LOCK_RECOVERY_GATE
22

33
## Model
44
GPT-5.4 or GPT-5.3-codex
55

66
## Reasoning
7-
Medium
7+
High
88

99
## Command
1010

1111
```text
12-
Execute BUILD_PR_LEVEL_20_11_RECOVERY_STATUS_GATE.
12+
Read docs/dev/codex_rules.md first.
13+
Read docs/dev/specs/TOOL_LAUNCH_SSOT.md second.
14+
Read existing Phase 20 validation reports:
15+
- docs/dev/reports/tool_launch_ssot_routing_validation.md
16+
- docs/dev/reports/tool_launch_ssot_data_layer_validation.md
17+
- docs/dev/reports/legacy_launch_fallback_residue_validation.md
1318
14-
Purpose:
15-
Update recovery roadmap status only.
19+
Execute BUILD_PR_LEVEL_20_12_UAT_VALIDATE_AND_LOCK_RECOVERY_GATE.
1620
17-
Allowed:
18-
- create/update docs/dev/roadmaps/MASTER_ROADMAP_RECOVERY.md
19-
- create docs/dev/reports/recovery_status_gate.md
21+
Goal:
22+
Validate and lock the Phase 20 recovery gate.
2023
21-
Forbidden:
22-
- implementation code
23-
- runtime changes
24-
- git reset
25-
- roadmap rewrite outside recovery roadmap
26-
- start_of_day changes
24+
Do not implement new runtime behavior.
25+
Do not perform broad cleanup.
26+
Do not change start_of_day.
27+
Do not rewrite roadmap text.
28+
29+
Validate:
30+
1. Samples
31+
- actions labeled Open <tool>
32+
- targets come from SSoT
33+
- targets resolve to tools/<tool>/index.html
34+
- external launch memory is cleared
35+
- missing/invalid context fails visibly
36+
- no fallback/default behavior
37+
38+
2. Games
39+
- actions labeled Open with Workspace Manager
40+
- target comes from SSoT
41+
- target resolves to tools/Workspace Manager/index.html
42+
- external launch memory is cleared
43+
- missing/invalid context fails visibly
44+
- no fallback/default behavior
45+
46+
3. Workspace Manager UAT
47+
- games/index.html -> Open with Workspace Manager -> tools/Workspace Manager/index.html
48+
- memory cleared
49+
- explicit context loaded
50+
- no fallback/default behavior
51+
52+
4. Codex rules recheck
53+
- no alias variables
54+
- no pass-through variables
55+
- no duplicate launch state
56+
- no duplicated launch paths
57+
- no silent redirects
58+
- no stale memory reuse
59+
- no label-text or DOM-order guessing
60+
61+
Create:
62+
- docs/dev/reports/phase20_recovery_uat_validation.md
63+
- docs/dev/reports/phase20_recovery_gate_decision.md
64+
- docs/dev/reports/phase20_codex_rules_recheck.md
65+
66+
Gate decision must be exactly one:
67+
- PASS - recovery gate complete; normal roadmap may resume
68+
- BLOCKED - recovery gate remains open
69+
70+
If PASS:
71+
Update docs/dev/roadmaps/MASTER_ROADMAP_RECOVERY.md status markers only:
72+
- anti-pattern drift -> [x]
73+
- SSoT tool launch -> [x]
74+
- external launch memory reset -> [x]
75+
- Workspace Manager games/index.html validation -> [x]
76+
- codex rule enforcement recheck -> [x]
77+
- normal roadmap progression -> [x]
78+
79+
If BLOCKED:
80+
Do not update those markers to [x].
81+
List exact blocker, file path, failing UAT path, and next required BUILD_PR name.
2782
2883
Return ZIP at:
29-
tmp/BUILD_PR_LEVEL_20_11_RECOVERY_STATUS_GATE.zip
84+
tmp/BUILD_PR_LEVEL_20_12_UAT_VALIDATE_AND_LOCK_RECOVERY_GATE.zip
3085
```

‎docs/operations/dev/commit_comment.txt‎

Lines changed: 7 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,9 @@
1-
Update Phase 20 recovery status gate
1+
Validate and lock Phase 20 recovery gate
22

33
PR Details:
4-
- Records reset-to-baseline plus constrained replay as the active recovery method.
5-
- Marks SSoT, memory reset, anti-pattern replay, and Codex rule enforcement as in progress.
6-
- Keeps Workspace Manager UAT validation as the remaining recovery gate.
4+
- Validates sample-to-tool launch UAT.
5+
- Validates game-to-Workspace Manager launch UAT.
6+
- Validates external-launch memory clearing.
7+
- Validates no fallback/default launch behavior.
8+
- Rechecks Codex anti-pattern rules on the recovery lane.
9+
- Updates recovery roadmap status markers only if the gate passes.

0 commit comments

Comments
 (0)