PLAN_PR_DEV_CONSOLE_AND_DEBUG_OVERLAY

- defined dev console and debug overlay plan
- locked diagnostics, command, and panel contract direction
- formalized render ordering and engine mapping boundaries
- documented hot reload interaction, validation, and test expectations

Author: DavidQ

docs/dev/CODEX_COMMANDS.md

@@ -5,31 +5,25 @@ codex_commands.md
 
 # CODEX COMMANDS
 
-## APPLY_PR_RUNTIME_SCENE_LOADER_AND_HOT_RELOAD
+## APPLY_PR_DEV_CONSOLE_AND_DEBUG_OVERLAY
 
-MODEL: GPT-5.3-codex
+MODEL: GPT-5.4
 REASONING: high
 
 COMMAND:
-Apply APPLY_PR_RUNTIME_SCENE_LOADER_AND_HOT_RELOAD as a focused implementation PR.
+Apply APPLY_PR_DEV_CONSOLE_AND_DEBUG_OVERLAY as a focused implementation PR.
 
 Requirements:
-- Implement the approved runtime scene loader and hot reload flow only
-- Keep orchestration above engine core; do not pollute engine systems with tool-specific quirks
-- Consume existing approved render pipeline/composition contracts rather than inventing new ones
-- Preserve deterministic render order
-- Add structured validation-aware reload behavior
-- Preserve last-known-good scene on reload failure
-- Add focused automated tests for load, reload, validation failure, disposal, and repeated reload stability
+- Implement only the approved dev console and debug overlay contracts
+- Keep diagnostics orchestration above engine core
+- Consume approved runtime scene loader and render pipeline contracts
+- Preserve deterministic render order with debug overlay last and console surface after overlay
+- Add structured validation and failure isolation for adapters, commands, and panels
+- Preserve hot reload survival behavior and last-known-good runtime safety
+- Add focused tests for contracts, ordering, failure isolation, and reload stability
 - Keep changes surgical and architecture-aligned
-- Do not introduce destructive runtime-breaking changes unless absolutely required and documented
-- Produce repo-structured implementation delta ZIP at:
-  <project folder>/tmp/APPLY_PR_RUNTIME_SCENE_LOADER_AND_HOT_RELOAD_delta.zip
-
-Expected documentation updates:
-- docs/dev/change_summary.txt
-- docs/dev/file_tree.txt
-- docs/dev/validation_checklist.txt
+- Update docs/dev reports after validation
 
-Commit comment source:
-- docs/dev/commit_comment.txt
+Package:
+- Produce repo-structured implementation delta ZIP at:
+  <project folder>/tmp/APPLY_PR_DEV_CONSOLE_AND_DEBUG_OVERLAY_delta.zip

docs/dev/COMMIT_COMMENT.txt

@@ -1,6 +1 @@
-Toolbox Aid
-David Quesenberry
-04/05/2026
-commit_comment.txt
-
-apply(runtime): implement runtime scene loader and validation-aware hot reload with deterministic ordering and last-known-good fallback
+docs: build dev console and debug overlay contract bundle

docs/dev/NEXT_COMMAND.txt

@@ -3,4 +3,4 @@ David Quesenberry
 04/05/2026
 next_command.txt
 
-PLAN_PR_DEV_CONSOLE_AND_DEBUG_OVERLAY
+APPLY_PR_DEV_CONSOLE_AND_DEBUG_OVERLAY

docs/dev/change_summary.txt

@@ -3,48 +3,14 @@ David Quesenberry
 04/05/2026
 change_summary.txt
 
-APPLY_PR_RUNTIME_SCENE_LOADER_AND_HOT_RELOAD summary
-
-Implemented focused runtime orchestration module:
-- Added `tools/shared/runtimeSceneLoaderHotReload.js`
-- Keeps orchestration above engine core and consumes existing approved render pipeline contracts
-- Uses `runRenderContractRuntimePath` for contract validation/normalization/composition/sequencing
-- Preserves deterministic runtime domain ordering: parallax -> tilemap -> sprite -> vector -> overlay
-
-Implemented runtime responsibilities:
-- `createSceneCompositionLoader` for composition/asset-document contract loading
-- `createRuntimeSceneLoader` for deterministic runtime domain assembly
-- `createHotReloadCoordinator` for validation-aware reload and scene-state management
-- `createWatcherBridge` for change-event normalization and watcher boundary isolation
-
-Implemented reload safety behavior:
-- Contract validation is required before applying reload
-- Reload rejects invalid changes with structured reports
-- Last-known-good runtime scene remains active on reload failure
-- Targeted reload domains supported when changed paths map to composition references
-- Full reload used for composition changes or unknown path impact
-- Replaced domain handles are disposed with guarded error reporting
-
-Implemented focused automated coverage:
-- Added `tests/tools/RuntimeSceneLoaderHotReload.test.mjs`
-- Covers initial load success
-- Covers targeted reload success
-- Covers validation failure fallback to last-known-good
-- Covers watcher bridge normalization/coalescing behavior
-- Covers repeated reload stability and disposal behavior
-
-Test harness integration:
-- Updated `tests/run-tests.mjs` to include `RuntimeSceneLoaderHotReload`
-
-Validation:
-- `node --check tools/shared/runtimeSceneLoaderHotReload.js`
-- `node --check tests/tools/RuntimeSceneLoaderHotReload.test.mjs`
-- `node --check tests/run-tests.mjs`
-- Targeted test run for `RuntimeSceneLoaderHotReload` passed
-- Full suite run passed (`112/112 explicit run() tests passed`)
-
-Scope guardrails honored:
-- No engine-core API rewrites
-- No tool-specific quirks moved into engine systems
-- No unrelated refactors
-- Changes remain surgical and architecture-aligned
+BUILD_PR_DEV_CONSOLE_AND_DEBUG_OVERLAY summary
+
+- Added docs-only BUILD contract for development console and debug overlay
+- Defined formal diagnostics contract with structured error envelope
+- Defined command registry contract with deterministic conflict handling and no-eval rule
+- Defined overlay panel contract with deterministic ordering and failure isolation
+- Locked deterministic render order with debug overlay last and console surface after overlay
+- Locked public engine mappings and boundary rules
+- Defined hot reload survival rules for diagnostics shell state and duplication prevention
+- Defined validation gates and test requirements for future APPLY implementation
+- Updated docs/dev command, commit, validation checklist, file tree, and next command artifacts

docs/dev/file_tree.txt

@@ -3,10 +3,10 @@ David Quesenberry
 04/05/2026
 file_tree.txt
 
-tools/shared/runtimeSceneLoaderHotReload.js
-tests/tools/RuntimeSceneLoaderHotReload.test.mjs
-tests/run-tests.mjs
+docs/pr/BUILD_PR_DEV_CONSOLE_AND_DEBUG_OVERLAY.md
+docs/dev/codex_commands.md
+docs/dev/commit_comment.txt
 docs/dev/change_summary.txt
-docs/dev/file_tree.txt
 docs/dev/validation_checklist.txt
-docs/dev/commit_comment.txt
+docs/dev/file_tree.txt
+docs/dev/next_command.txt

docs/dev/validation_checklist.txt

@@ -3,37 +3,18 @@ David Quesenberry
 04/05/2026
 validation_checklist.txt
 
-APPLY_PR_RUNTIME_SCENE_LOADER_AND_HOT_RELOAD validation checklist
+BUILD_PR_DEV_CONSOLE_AND_DEBUG_OVERLAY validation checklist
 
-Runtime scene loader and hot reload flow
-[x] Runtime scene loader orchestration implemented above engine core
-[x] Existing approved render/composition contract runtime path is consumed
-[x] Deterministic runtime domain ordering preserved
-[x] Structured validation-aware reload behavior implemented
-[x] Last-known-good scene preserved on reload failure
-[x] Composition-driven targeted/full reload decision rules implemented
-
-Watcher bridge boundaries
-[x] Watcher bridge normalizes project-relative path events
-[x] Watcher bridge remains orchestration boundary and does not own scene assembly
-[x] Watcher events can be coalesced by path before reload application
-
-Automated tests
-[x] Load success test added
-[x] Reload success test added
-[x] Validation failure fallback test added
-[x] Disposal behavior test added
-[x] Repeated reload stability test added
-[x] New test wired into `tests/run-tests.mjs`
-
-Execution evidence
-[x] `node --check tools/shared/runtimeSceneLoaderHotReload.js`
-[x] `node --check tests/tools/RuntimeSceneLoaderHotReload.test.mjs`
-[x] `node --check tests/run-tests.mjs`
-[x] Targeted runtime scene loader/hot reload test run passed
-[x] Full test suite passed (`112/112 explicit run() tests passed`)
-
-Scope safety
-[x] No destructive runtime-breaking changes introduced
-[x] No unrelated sample/game/tool refactors introduced
-[x] Changes kept focused to approved APPLY scope
+[x] Bundle is docs-only
+[x] No implementation code included
+[x] Workflow preserved: PLAN_PR -> BUILD_PR -> APPLY_PR
+[x] Diagnostics contract defined
+[x] Command registry contract defined
+[x] Overlay panel contract defined
+[x] Deterministic render order defined with debug overlay last
+[x] Engine mappings locked to public adapters only
+[x] Hot reload survival rules defined
+[x] Validation and test requirements defined
+[x] `docs/dev/commit_comment.txt` has no file header
+[x] Command and commit artifacts are in docs/dev
+[x] Repo-relative bundle structure preserved