Skip to content

Commit 8a47ee5

Browse files
author
DavidQ
committed
docs: plan debug surfaces promotion from tools/dev to engine-debug
1 parent bb61fc0 commit 8a47ee5

10 files changed

+287
-64
lines changed

‎docs/dev/CODEX_COMMANDS.md‎

Lines changed: 10 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -2,32 +2,17 @@ MODEL: GPT-5.4-codex
22
REASONING: high
33

44
COMMAND:
5-
Follow PLAN_PR -> BUILD_PR -> APPLY_PR
6-
7-
Create BUILD_PR_OVERLAY_PANEL_PERSISTENCE
5+
Create PLAN_PR_DEBUG_SURFACES_PROMOTION
86

97
Requirements:
10-
- Docs-first unless BUILD/APPLY implementation work is explicitly requested
11-
- No engine core changes in this PR
8+
- Follow PLAN_PR -> BUILD_PR -> APPLY_PR
9+
- Docs-first only
1210
- One PR per purpose
13-
- Keep integration sample-level
14-
- Use MultiSystemDemoScene.js as the integration reference
15-
- Add a clean overlay persistence adapter boundary
16-
- Persist overlay panel enabled/disabled state only
17-
- Registry remains runtime source of truth
18-
- Operator commands save through public APIs only
19-
- Handle invalid/unknown stored panel ids safely
20-
- Add versioned snapshot shape
11+
- Minimize engine-core changes
12+
- Promote proven debug systems out of tools/dev
13+
- Define target ownership across engine-core, engine-debug, and project/sample/tool layers
14+
- Include target folder structure, migration phases, validation strategy, risk controls, and rollout notes
15+
- Keep sample-specific panels/providers/commands outside shared layers
2116
- Write outputs under docs/pr and docs/dev/reports
22-
- Package to <project folder>/tmp/BUILD_PR_OVERLAY_PANEL_PERSISTENCE_delta.zip
23-
24-
NEXT RECOMMENDED COMMAND:
25-
Create PLAN_PR_DEBUG_SURFACES_ENGINE_PROMOTION
26-
27-
Requirements:
28-
- Docs-only
29-
- Evaluate whether dev console and debug overlay should move into engine core
30-
- Compare promotion options: keep sample-owned, move to engine debug package, or partial core extraction
31-
- Preserve console vs overlay separation
32-
- Define promotion criteria, boundaries, risks, and rollout phases
33-
- Do not implement core migration yet
17+
- Put codex command and commit comment under docs/dev
18+
- Package to <project folder>/tmp/PLAN_PR_DEBUG_SURFACES_PROMOTION_delta.zip

‎docs/dev/COMMIT_COMMENT.txt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
BUILD_PR_OVERLAY_PANEL_PERSISTENCE: define versioned, debug-only persistence contract for overlay panel state; keep registry as runtime source of truth and preserve sample-level integration.
1+
docs: plan debug surfaces promotion from tools/dev to engine-debug with minimal engine-core contracts

‎docs/dev/NEXT_COMMAND.txt‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,2 @@
1-
Create PLAN_PR_DEBUG_SURFACES_ENGINE_PROMOTION with docs-only evaluation of dev console and debug overlay promotion into engine-level debug surfaces after persistence validation.
1+
Next:
2+
BUILD_PR_DEBUG_SURFACES_PROMOTION

‎docs/dev/RULES_OF_ENGAGEMENT.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,7 @@ This file is the canonical workflow and rules document for active repo operation
2323
- Planning/docs bundle defines scope and acceptance.
2424
- Implementation applies approved scope only.
2525
- Active execution control files are in `docs/dev/`.
26+
- Update docs/dev/BIG_PICTURE_ROADMAP.md when needed [ ] to [.] to [x].
2627

2728
## Active Dev Controls
2829
- `docs/dev/codex_commands.md`

‎docs/dev/reports/change_summary.txt‎

Lines changed: 19 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,25 +1,29 @@
1-
BUILD_PR_OVERLAY_PANEL_PERSISTENCE change summary
1+
PLAN_PR_DEBUG_SURFACES_PROMOTION change summary
22

33
Summary
4-
- Refreshed PLAN/BUILD/APPLY docs for overlay panel persistence.
5-
- Kept this bundle docs-first and single-purpose.
6-
- Preserved debug-only, sample-level scope with MultiSystemDemoScene.js as reference.
4+
- Created docs-first planning bundle for debug surfaces promotion.
5+
- Kept scope to one PR purpose: promotion planning only.
6+
- Defined ownership across engine-core, engine-debug, and project/sample/tool layers.
77

8-
Key decisions
9-
- Added a clean persistence adapter boundary (`load/save/clear`).
10-
- Persist enabled/disabled panel state only.
11-
- Registry remains runtime source of truth.
12-
- Operator commands save state via public APIs only.
13-
- Unknown/invalid stored panel IDs are ignored safely.
14-
- Added versioned snapshot contract (`contract`, `version`, `panels`, `savedAt`).
8+
What this plan defines
9+
- target folder structure for promoted debug surfaces
10+
- migration phases from ownership lock through stabilization
11+
- validation strategy for contracts, behavior, regressions, and safety
12+
- risk controls and rollout notes
13+
- explicit rule that sample-specific panels/providers/commands stay outside shared layers
14+
15+
Key constraints preserved
16+
- no implementation migration in this PR
17+
- minimize engine-core changes
18+
- integration reference remains MultiSystemDemoScene.js
1519

1620
Files in this bundle
17-
- docs/pr/PLAN_PR_OVERLAY_PANEL_PERSISTENCE.md
18-
- docs/pr/BUILD_PR_OVERLAY_PANEL_PERSISTENCE.md
19-
- docs/pr/APPLY_PR_OVERLAY_PANEL_PERSISTENCE.md
21+
- docs/pr/PLAN_PR_DEBUG_SURFACES_PROMOTION.md
22+
- docs/dev/codex_commands.md
23+
- docs/dev/commit_comment.txt
2024
- docs/dev/reports/change_summary.txt
2125
- docs/dev/reports/validation_checklist.txt
2226
- docs/dev/reports/file_tree.txt
2327

2428
Next recommended command
25-
- PLAN_PR_DEBUG_SURFACES_ENGINE_PROMOTION
29+
- BUILD_PR_DEBUG_SURFACES_PROMOTION

‎docs/dev/reports/file_tree.txt‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,13 @@
11
HTML-JavaScript-Gaming/
22
|-- docs/
33
| |-- pr/
4-
| | |-- PLAN_PR_OVERLAY_PANEL_PERSISTENCE.md
5-
| | |-- BUILD_PR_OVERLAY_PANEL_PERSISTENCE.md
6-
| | `-- APPLY_PR_OVERLAY_PANEL_PERSISTENCE.md
4+
| | `-- PLAN_PR_DEBUG_SURFACES_PROMOTION.md
75
| `-- dev/
6+
| |-- codex_commands.md
7+
| |-- commit_comment.txt
88
| `-- reports/
99
| |-- change_summary.txt
1010
| |-- validation_checklist.txt
1111
| `-- file_tree.txt
1212
`-- tmp/
13-
`-- BUILD_PR_OVERLAY_PANEL_PERSISTENCE_delta.zip
13+
`-- PLAN_PR_DEBUG_SURFACES_PROMOTION_delta.zip

‎docs/dev/reports/validation_checklist.txt‎

Lines changed: 21 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -1,24 +1,27 @@
1-
BUILD_PR_OVERLAY_PANEL_PERSISTENCE validation checklist
1+
PLAN_PR_DEBUG_SURFACES_PROMOTION validation checklist
22

33
Workflow
4-
- [done] Followed PLAN_PR -> BUILD_PR -> APPLY_PR
5-
- [done] One PR purpose only
6-
- [done] Docs-first bundle
4+
- [done] Followed PLAN_PR -> BUILD_PR -> APPLY_PR structure
5+
- [done] Docs-first only
6+
- [done] One PR per purpose
77

88
Scope
9-
- [done] No engine core changes in this PR
10-
- [done] Integration remains sample-level
11-
- [done] MultiSystemDemoScene.js used as integration reference
9+
- [done] Plan focuses on debug surfaces promotion only
10+
- [done] No engine-core implementation changes in this PR
11+
- [done] Integration reference documented: MultiSystemDemoScene.js
1212

13-
Contract
14-
- [done] Clean persistence adapter boundary defined
15-
- [done] Persist enabled/disabled panel state only
16-
- [done] Registry remains runtime source of truth
17-
- [done] Operator commands save through public APIs only
18-
- [done] Unknown/invalid stored panel IDs handled safely
19-
- [done] Versioned snapshot shape documented
13+
Plan Quality
14+
- [done] Ownership model defined for engine-core, engine-debug, project/sample/tool layers
15+
- [done] Target folder structure documented
16+
- [done] Migration phases documented
17+
- [done] Validation strategy documented
18+
- [done] Risk controls documented
19+
- [done] Rollout notes documented
20+
- [done] Sample-specific panels/providers/commands explicitly kept outside shared layers
2021

21-
Outputs
22-
- [done] Docs written under docs/pr
23-
- [done] Reports written under docs/dev/reports
24-
- [done] Delta zip generated at <project folder>/tmp/BUILD_PR_OVERLAY_PANEL_PERSISTENCE_delta.zip
22+
Artifacts
23+
- [done] Plan doc under docs/pr
24+
- [done] Codex command under docs/dev
25+
- [done] Commit comment under docs/dev
26+
- [done] Reports under docs/dev/reports
27+
- [done] Delta zip generated at <project folder>/tmp/PLAN_PR_DEBUG_SURFACES_PROMOTION_delta.zip

‎docs/pr/APPLY_PR_DEBUG_SURFACES_PROMOTION.md‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
# APPLY_PR_DEBUG_SURFACES_PROMOTION
2+
3+
## Purpose
4+
5+
Apply the approved promotion plan by moving the proven debug-surface stack into a reusable `engine-debug` layer, while moving only minimal contracts/hooks into engine core.
6+
7+
## Apply Scope
8+
9+
### Promote to `engine-debug`
10+
- console host
11+
- overlay host
12+
- panel registry
13+
- provider registry/plumbing
14+
- operator command wiring
15+
- persistence
16+
- debug bootstrap/composition
17+
18+
### Promote to `engine-core`
19+
- debug interfaces
20+
- registration contracts
21+
- lifecycle hooks
22+
- environment/debug gating hooks
23+
24+
### Keep Project-Owned
25+
- sample-specific commands
26+
- sample-specific panels
27+
- sample-specific providers
28+
- scene wiring
29+
- tool-specific adapters
30+
31+
## Apply Rules
32+
33+
- no UI policy in engine core
34+
- no sample panel migration into shared layers
35+
- no direct console-to-panel coupling
36+
- preserve public API boundaries
37+
- keep provider flow read-only
38+
- validate against existing demo integration
39+
40+
## Exit Criteria
41+
42+
- shared debug implementation no longer lives in `tools/dev`
43+
- engine-debug contains the reusable platform
44+
- engine-core contains only minimal contracts/hooks
45+
- sample integration still works with minimal wiring change

‎docs/pr/BUILD_PR_DEBUG_SURFACES_PROMOTION.md‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
# BUILD_PR_DEBUG_SURFACES_PROMOTION
2+
3+
## Purpose
4+
5+
Turn the promotion plan into a docs-only extraction bundle that is ready for Codex implementation.
6+
7+
## Build Scope
8+
9+
Produce docs that define:
10+
11+
- final target folder structure
12+
- exact ownership mapping
13+
- migration sequence
14+
- implementation boundaries
15+
- validation and rollback strategy
16+
17+
## Required Deliverables
18+
19+
- ownership matrix
20+
- target tree
21+
- migration checklist
22+
- validation checklist
23+
- change summary
24+
- Codex command
25+
- commit comment
26+
- next command
27+
28+
## Build Rules
29+
30+
- one PR purpose only
31+
- docs-first only
32+
- no direct runtime implementation in this bundle
33+
- keep engine-core changes minimal
34+
- assume `engine-debug` is the primary target
35+
- preserve sample-level proving path through `MultiSystemDemoScene.js`
36+
37+
## Expected Build Output
38+
39+
- `docs/pr/PLAN_PR_DEBUG_SURFACES_PROMOTION.md`
40+
- `docs/pr/BUILD_PR_DEBUG_SURFACES_PROMOTION.md`
41+
- `docs/pr/APPLY_PR_DEBUG_SURFACES_PROMOTION.md`
42+
- `docs/dev/codex_commands.md`
43+
- `docs/dev/commit_comment.txt`
44+
- `docs/dev/next_command.txt`
45+
- `docs/dev/reports/change_summary.txt`
46+
- `docs/dev/reports/validation_checklist.txt`
47+
- `docs/dev/reports/file_tree.txt`

‎docs/pr/PLAN_PR_DEBUG_SURFACES_PROMOTION.md‎

Lines changed: 137 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,137 @@
1+
# PLAN_PR_DEBUG_SURFACES_PROMOTION
2+
3+
## Objective
4+
Plan a docs-first promotion path for proven debug surfaces from `tools/dev` into shared layers while minimizing engine-core changes.
5+
6+
## Workflow
7+
PLAN_PR -> BUILD_PR -> APPLY_PR
8+
9+
## PR Purpose
10+
Promote proven debug systems with clear ownership boundaries.
11+
12+
## Scope
13+
In scope:
14+
- ownership model for `engine-core`, `engine-debug`, and `project/sample/tool` layers
15+
- target folder structure for promoted debug systems
16+
- phased migration plan
17+
- validation strategy
18+
- risk controls
19+
- rollout notes
20+
21+
Out of scope:
22+
- implementation migration in this PR
23+
- engine-core rewrite
24+
- promotion of sample-specific panels/providers/commands
25+
26+
## Current Proven Surface Set
27+
- Dev Console host
28+
- Debug Overlay host
29+
- Overlay panel registry
30+
- Overlay data providers
31+
- Overlay operator commands
32+
- Overlay panel persistence
33+
34+
## Target Ownership
35+
### Engine Core (minimal contracts only)
36+
Own only stable contracts and gates:
37+
- debug surface interfaces
38+
- registration hooks
39+
- environment/debug gates
40+
41+
Engine core must not own:
42+
- console UI details
43+
- overlay UI policy
44+
- provider implementation details
45+
- persistence policy/storage specifics
46+
- sample-specific debug assets
47+
48+
### Engine Debug (primary promoted implementation)
49+
Own shared reusable debug implementations:
50+
- console runtime host and command bridge
51+
- overlay runtime host
52+
- panel registry
53+
- provider registry/plumbing
54+
- operator command adapters
55+
- persistence adapter boundary and wiring
56+
- debug bootstrap/composition
57+
58+
### Project/Sample/Tool Layers
59+
Remain local and non-promoted:
60+
- sample-specific panels
61+
- sample-specific providers
62+
- sample-specific operator commands
63+
- scene-level wiring and defaults
64+
- tool-specific debug adapters
65+
66+
## Target Folder Structure
67+
```text
68+
engine/
69+
core/
70+
debug/
71+
DebugSurfaceContracts.js
72+
DebugRegistrationHooks.js
73+
DebugEnvironmentGate.js
74+
debug/
75+
console/
76+
DevConsoleHost.js
77+
DevConsoleCommandBridge.js
78+
overlay/
79+
DebugOverlayHost.js
80+
OverlayPanelRegistry.js
81+
OverlayPersistenceAdapter.js
82+
providers/
83+
OverlayProviderRegistry.js
84+
bootstrap/
85+
DebugSurfacesBootstrap.js
86+
87+
samples/
88+
Phase 12 - Demo Games/
89+
Demo 1205 - Multi-System Demo/
90+
MultiSystemDemoScene.js (integration reference)
91+
```
92+
93+
## Migration Phases
94+
### Phase 1: Ownership Lock
95+
- freeze boundary rules and ownership matrix
96+
- confirm sample-owned items remain local
97+
98+
### Phase 2: Contract Extraction
99+
- define minimal core contracts/hooks
100+
- keep core surface narrow and stable
101+
102+
### Phase 3: Engine-Debug Assembly
103+
- move reusable debug implementations into `engine/debug`
104+
- preserve existing public API seams
105+
106+
### Phase 4: Sample Rewire
107+
- keep `MultiSystemDemoScene.js` as proving target
108+
- verify sample-specific panel/provider/command ownership remains local
109+
110+
### Phase 5: Stabilization
111+
- validate behavior parity and rollback readiness
112+
- document promotion-ready state for BUILD/APPLY
113+
114+
## Validation Strategy
115+
- contract validation: boundary and ownership checks pass
116+
- behavior validation: console and overlay continue to operate through public APIs
117+
- regression validation: sample commands, panel visibility, provider snapshots, and persistence remain stable
118+
- safety validation: unknown panel IDs and degraded states fail safely
119+
120+
## Risk Controls
121+
- minimize engine-core changes by promoting implementation to `engine/debug`
122+
- reject direct console-overlay private coupling
123+
- block promotion of sample-specific panels/providers/commands
124+
- preserve phased rollback points at each migration stage
125+
126+
## Rollout Notes
127+
- start with docs-only plan (this PR)
128+
- BUILD PR should define surgical implementation mapping and test/validation execution
129+
- APPLY PR should execute migration incrementally with sample-level validation first
130+
- no broad refactors outside this purpose
131+
132+
## Integration Reference
133+
- `samples/Phase 12 - Demo Games/Demo 1205 - Multi-System Demo/MultiSystemDemoScene.js`
134+
135+
## Next Commands
136+
1. `BUILD_PR_DEBUG_SURFACES_PROMOTION`
137+
2. `APPLY_PR_DEBUG_SURFACES_PROMOTION`

0 commit comments

Comments
 (0)