docs: build debug surfaces promotion extraction plan

DavidQ · DavidQ · commit 66c84d9431f4 · 2026-04-05T20:04:40.000-04:00
diff --git a/docs/dev/CODEX_COMMANDS.md b/docs/dev/CODEX_COMMANDS.md
@@ -2,17 +2,17 @@ MODEL: GPT-5.4-codex
 REASONING: high
 
 COMMAND:
-Create PLAN_PR_DEBUG_SURFACES_PROMOTION
+Create BUILD_PR_DEBUG_SURFACES_PROMOTION
 
 Requirements:
 - Follow PLAN_PR -> BUILD_PR -> APPLY_PR
 - Docs-first only
 - One PR per purpose
-- Minimize engine-core changes
-- Promote proven debug systems out of tools/dev
-- Define target ownership across engine-core, engine-debug, and project/sample/tool layers
-- Include target folder structure, migration phases, validation strategy, risk controls, and rollout notes
+- Extraction/relocation only; no feature expansion
+- Build authoritative target structure for engine-core vs engine-debug vs project-owned integrations
+- Include ownership matrix, ordered migration steps, validation goals, rollback strategy, and rollout notes
 - Keep sample-specific panels/providers/commands outside shared layers
+- Preserve `MultiSystemDemoScene.js` as the proving integration
 - Write outputs under docs/pr and docs/dev/reports
 - Put codex command and commit comment under docs/dev
-- Package to <project folder>/tmp/PLAN_PR_DEBUG_SURFACES_PROMOTION_delta.zip
+- Package to <project folder>/tmp/BUILD_PR_DEBUG_SURFACES_PROMOTION_delta.zip
diff --git a/docs/dev/COMMIT_COMMENT.txt b/docs/dev/COMMIT_COMMENT.txt
@@ -1 +1 @@
-docs: plan debug surfaces promotion from tools/dev to engine-debug with minimal engine-core contracts
+docs: build debug surfaces promotion extraction plan with authoritative ownership and migration rules
diff --git a/docs/dev/NEXT_COMMAND.txt b/docs/dev/NEXT_COMMAND.txt
@@ -1,2 +1,2 @@
 Next:
-BUILD_PR_DEBUG_SURFACES_PROMOTION
+APPLY_PR_DEBUG_SURFACES_PROMOTION
diff --git a/docs/dev/RULES_OF_ENGAGEMENT.md b/docs/dev/RULES_OF_ENGAGEMENT.md
@@ -23,7 +23,7 @@ This file is the canonical workflow and rules document for active repo operation
 - Planning/docs bundle defines scope and acceptance.
 - Implementation applies approved scope only.
 - Active execution control files are in `docs/dev/`.
-- Update docs/dev/BIG_PICTURE_ROADMAP.md when needed [ ] to [.] to [x].
+- Update docs/dev/BIG_PICTURE_ROADMAP.md when needed [ ] Todo to [.] inprogress to [x] complete.
 
 ## Active Dev Controls
 - `docs/dev/codex_commands.md`
diff --git a/docs/dev/reports/change_summary.txt b/docs/dev/reports/change_summary.txt
@@ -1,29 +1,31 @@
-PLAN_PR_DEBUG_SURFACES_PROMOTION change summary
+BUILD_PR_DEBUG_SURFACES_PROMOTION change summary
 
 Summary
-- Created docs-first planning bundle for debug surfaces promotion.
-- Kept scope to one PR purpose: promotion planning only.
-- Defined ownership across engine-core, engine-debug, and project/sample/tool layers.
+- Produced a docs-first BUILD bundle for debug surfaces promotion.
+- Kept scope to extraction/relocation planning only (no feature expansion).
+- Locked authoritative ownership across engine-core, engine-debug, and project/sample/tool layers.
 
-What this plan defines
-- target folder structure for promoted debug surfaces
-- migration phases from ownership lock through stabilization
-- validation strategy for contracts, behavior, regressions, and safety
-- risk controls and rollout notes
-- explicit rule that sample-specific panels/providers/commands stay outside shared layers
+Included
+- authoritative target structure
+- ownership matrix
+- ordered migration steps
+- validation goals
+- rollback strategy
+- rollout notes
+- codex command and commit comment
+- report files
 
-Key constraints preserved
-- no implementation migration in this PR
-- minimize engine-core changes
-- integration reference remains MultiSystemDemoScene.js
+Boundary outcomes
+- sample-specific panels/providers/commands remain outside shared layers
+- `MultiSystemDemoScene.js` preserved as proving integration
+- engine-core remains minimal and contract-only
 
-Files in this bundle
+Outputs
 - docs/pr/PLAN_PR_DEBUG_SURFACES_PROMOTION.md
+- docs/pr/BUILD_PR_DEBUG_SURFACES_PROMOTION.md
+- docs/pr/APPLY_PR_DEBUG_SURFACES_PROMOTION.md
 - docs/dev/codex_commands.md
 - docs/dev/commit_comment.txt
 - docs/dev/reports/change_summary.txt
 - docs/dev/reports/validation_checklist.txt
 - docs/dev/reports/file_tree.txt
-
-Next recommended command
-- BUILD_PR_DEBUG_SURFACES_PROMOTION
diff --git a/docs/dev/reports/file_tree.txt b/docs/dev/reports/file_tree.txt
@@ -1,7 +1,9 @@
 HTML-JavaScript-Gaming/
 |-- docs/
 |   |-- pr/
-|   |   `-- PLAN_PR_DEBUG_SURFACES_PROMOTION.md
+|   |   |-- PLAN_PR_DEBUG_SURFACES_PROMOTION.md
+|   |   |-- BUILD_PR_DEBUG_SURFACES_PROMOTION.md
+|   |   `-- APPLY_PR_DEBUG_SURFACES_PROMOTION.md
 |   `-- dev/
 |       |-- codex_commands.md
 |       |-- commit_comment.txt
@@ -10,4 +12,4 @@ HTML-JavaScript-Gaming/
 |           |-- validation_checklist.txt
 |           `-- file_tree.txt
 `-- tmp/
-    `-- PLAN_PR_DEBUG_SURFACES_PROMOTION_delta.zip
+    `-- BUILD_PR_DEBUG_SURFACES_PROMOTION_delta.zip
diff --git a/docs/dev/reports/validation_checklist.txt b/docs/dev/reports/validation_checklist.txt
@@ -1,27 +1,27 @@
-PLAN_PR_DEBUG_SURFACES_PROMOTION validation checklist
+BUILD_PR_DEBUG_SURFACES_PROMOTION validation checklist
 
 Workflow
-- [done] Followed PLAN_PR -> BUILD_PR -> APPLY_PR structure
+- [done] PLAN_PR -> BUILD_PR -> APPLY_PR structure preserved
 - [done] Docs-first only
 - [done] One PR per purpose
 
 Scope
-- [done] Plan focuses on debug surfaces promotion only
-- [done] No engine-core implementation changes in this PR
-- [done] Integration reference documented: MultiSystemDemoScene.js
+- [done] Extraction/relocation only (no feature expansion)
+- [done] Engine-core changes minimized by contract-only ownership model
+- [done] Integration proving reference preserved: MultiSystemDemoScene.js
 
-Plan Quality
-- [done] Ownership model defined for engine-core, engine-debug, project/sample/tool layers
-- [done] Target folder structure documented
-- [done] Migration phases documented
-- [done] Validation strategy documented
-- [done] Risk controls documented
+Build Content
+- [done] Authoritative target structure documented
+- [done] Ownership matrix documented
+- [done] Ordered migration steps documented
+- [done] Validation goals documented
+- [done] Rollback strategy documented
 - [done] Rollout notes documented
 - [done] Sample-specific panels/providers/commands explicitly kept outside shared layers
 
-Artifacts
-- [done] Plan doc under docs/pr
+Outputs
+- [done] Docs under docs/pr
+- [done] Reports under docs/dev/reports
 - [done] Codex command under docs/dev
 - [done] Commit comment under docs/dev
-- [done] Reports under docs/dev/reports
-- [done] Delta zip generated at <project folder>/tmp/PLAN_PR_DEBUG_SURFACES_PROMOTION_delta.zip
+- [done] Delta zip generated at <project folder>/tmp/BUILD_PR_DEBUG_SURFACES_PROMOTION_delta.zip
diff --git a/docs/pr/APPLY_PR_DEBUG_SURFACES_PROMOTION.md b/docs/pr/APPLY_PR_DEBUG_SURFACES_PROMOTION.md
@@ -1,45 +1,35 @@
 # APPLY_PR_DEBUG_SURFACES_PROMOTION
 
-## Purpose
-
-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.
+## Objective
+Apply the approved extraction/relocation plan for debug surfaces with no feature expansion and minimal engine-core changes.
 
 ## Apply Scope
-
-### Promote to `engine-debug`
-- console host
-- overlay host
-- panel registry
-- provider registry/plumbing
-- operator command wiring
-- persistence
-- debug bootstrap/composition
-
-### Promote to `engine-core`
-- debug interfaces
-- registration contracts
-- lifecycle hooks
-- environment/debug gating hooks
-
-### Keep Project-Owned
-- sample-specific commands
-- sample-specific panels
-- sample-specific providers
-- scene wiring
-- tool-specific adapters
-
-## Apply Rules
-
-- no UI policy in engine core
-- no sample panel migration into shared layers
-- no direct console-to-panel coupling
-- preserve public API boundaries
-- keep provider flow read-only
-- validate against existing demo integration
-
-## Exit Criteria
-
-- shared debug implementation no longer lives in `tools/dev`
-- engine-debug contains the reusable platform
-- engine-core contains only minimal contracts/hooks
-- sample integration still works with minimal wiring change
+- relocate proven reusable debug systems into `engine/debug`
+- keep engine-core changes limited to debug contracts/hooks
+- preserve local ownership for sample-specific panels/providers/commands
+- preserve `MultiSystemDemoScene.js` as proving integration
+
+## Guardrails
+- no feature expansion
+- no engine-core UI behavior ownership
+- no private console-overlay coupling
+- no promotion of sample-specific artifacts into shared layers
+
+## Apply Sequence
+1. core contracts/hooks extraction
+2. console relocation
+3. overlay/registry/persistence relocation
+4. provider plumbing relocation
+5. bootstrap integration
+6. sample proving rewire
+7. parity + boundary validation
+
+## Apply Validation
+- command/control and telemetry boundaries remain intact
+- overlay operator commands use public APIs only
+- registry remains runtime source of truth
+- provider and persistence behaviors remain stable
+- no unrelated files or systems changed
+
+## Expected Outcome
+Debug surfaces are promoted out of `tools/dev` into shared `engine/debug` structure while engine-core remains minimal and local sample integrations stay local.
diff --git a/docs/pr/BUILD_PR_DEBUG_SURFACES_PROMOTION.md b/docs/pr/BUILD_PR_DEBUG_SURFACES_PROMOTION.md
@@ -1,47 +1,97 @@
 # BUILD_PR_DEBUG_SURFACES_PROMOTION
 
-## Purpose
+## Objective
+Create an authoritative docs-only BUILD bundle for extraction/relocation of proven debug surfaces from `tools/dev` into shared layers, with no feature expansion.
 
-Turn the promotion plan into a docs-only extraction bundle that is ready for Codex implementation.
+## Workflow
+PLAN_PR -> BUILD_PR -> APPLY_PR
 
-## Build Scope
+## Build Constraints
+- docs-first only
+- one PR purpose only
+- extraction/relocation only
+- no feature expansion
+- minimize engine-core changes
+- preserve `MultiSystemDemoScene.js` as proving integration
 
-Produce docs that define:
+## Authoritative Target Structure
+```text
+engine/
+  core/
+    debug/
+      DebugSurfaceContracts.js
+      DebugRegistrationHooks.js
+      DebugEnvironmentGate.js
+  debug/
+    console/
+      DevConsoleHost.js
+      DevConsoleCommandBridge.js
+    overlay/
+      DebugOverlayHost.js
+      OverlayPanelRegistry.js
+      OverlayPersistenceAdapter.js
+    providers/
+      OverlayProviderRegistry.js
+    bootstrap/
+      DebugSurfacesBootstrap.js
 
-- final target folder structure
-- exact ownership mapping
-- migration sequence
-- implementation boundaries
-- validation and rollback strategy
+project|sample|tool/
+  debug/
+    panels/        (local only)
+    providers/     (local only)
+    commands/      (local only)
+```
 
-## Required Deliverables
+## Ownership Matrix
+| Capability | Engine Core | Engine Debug | Project/Sample/Tool |
+|---|---|---|---|
+| Debug contracts/hooks | Owns | Consumes | Consumes |
+| Console host runtime | No | Owns | Integrates |
+| Overlay host runtime | No | Owns | Integrates |
+| Panel registry | No | Owns | Extends via public registration |
+| Provider registry/plumbing | No | Owns | Extends via local providers |
+| Operator command wiring | No | Owns | May register local commands |
+| Persistence adapter boundary | No | Owns | May provide local storage key/config |
+| Sample-specific panels/providers/commands | No | No | Owns |
 
-- ownership matrix
-- target tree
-- migration checklist
-- validation checklist
-- change summary
-- Codex command
-- commit comment
-- next command
+## Ordered Migration Steps
+1. Freeze ownership boundaries and no-go rules.
+2. Extract minimal core contracts/hooks into `engine/core/debug`.
+3. Relocate console host/bridge to `engine/debug/console`.
+4. Relocate overlay host/registry/persistence adapter to `engine/debug/overlay`.
+5. Relocate provider registry/plumbing to `engine/debug/providers`.
+6. Add shared bootstrap/composition in `engine/debug/bootstrap`.
+7. Rewire `MultiSystemDemoScene.js` through public bootstrap/registration APIs.
+8. Validate parity and boundary compliance.
 
-## Build Rules
+## Validation Goals
+- no feature expansion introduced
+- console commands still function through public command registry
+- overlay still renders deterministically
+- provider reads remain read-only
+- panel persistence behavior remains stable
+- sample-specific artifacts remain outside shared layers
+- engine-core remains contract-only
+- `MultiSystemDemoScene.js` continues as proving integration
 
-- one PR purpose only
-- docs-first only
-- no direct runtime implementation in this bundle
-- keep engine-core changes minimal
-- assume `engine-debug` is the primary target
-- preserve sample-level proving path through `MultiSystemDemoScene.js`
+## Rollback Strategy
+If migration is unstable:
+1. keep extracted core contracts/hooks unchanged
+2. revert relocation stages in reverse order (bootstrap -> providers -> overlay -> console)
+3. restore prior sample wiring
+4. re-run parity checks before retry
 
-## Expected Build Output
+## Rollout Notes
+- BUILD bundle remains docs-only and implementation-ready
+- APPLY should execute incremental relocation with validation after each stage
+- stop and split scope if migration requires non-minimal core changes
 
+## Deliverables
 - `docs/pr/PLAN_PR_DEBUG_SURFACES_PROMOTION.md`
 - `docs/pr/BUILD_PR_DEBUG_SURFACES_PROMOTION.md`
 - `docs/pr/APPLY_PR_DEBUG_SURFACES_PROMOTION.md`
 - `docs/dev/codex_commands.md`
 - `docs/dev/commit_comment.txt`
-- `docs/dev/next_command.txt`
 - `docs/dev/reports/change_summary.txt`
 - `docs/dev/reports/validation_checklist.txt`
 - `docs/dev/reports/file_tree.txt`
diff --git a/docs/pr/PLAN_PR_DEBUG_SURFACES_PROMOTION.md b/docs/pr/PLAN_PR_DEBUG_SURFACES_PROMOTION.md

Original file line number	Diff line number	Diff line change
`@@ -1 +1 @@`
`1`		`-docs: plan debug surfaces promotion from tools/dev to engine-debug with minimal engine-core contracts`
	`1`	`+docs: build debug surfaces promotion extraction plan with authoritative ownership and migration rules`
Original file line number	Diff line number	Diff line change
`@@ -1,2 +1,2 @@`
`1`	`1`	`Next:`
`2`		`-BUILD_PR_DEBUG_SURFACES_PROMOTION`
	`2`	`+APPLY_PR_DEBUG_SURFACES_PROMOTION`