Complete Tool UI Readiness DoD with per-tool control and lifecycle acceptance targets - PR 10.6Q

Author: DavidQ

docs/dev/codex_commands.md

@@ -1,13 +1,8 @@
-# Codex Commands — BUILD_PR_LEVEL_10_6P_COMPLETE_TOOL_UI_READINESS_DOD
+# Codex command
 
-## Model
-GPT-5.4
-
-## Reasoning
-high
-
-## Command
+Model: GPT-5.4
+Reasoning: high
 
 ```powershell
-codex --model gpt-5.4 --reasoning high "Execute BUILD_PR_LEVEL_10_6P_COMPLETE_TOOL_UI_READINESS_DOD. Read docs/dev/dod/tool_ui_readiness_dod.md. Inspect the current repo tools opened from games/index.html, samples/index.html, Workspace Manager, and sample/game manifests. Do not make broad implementation fixes. First validate whether the DoD misses any required input fields, output fields, UI controls, control-to-data bindings, ready states, error/empty states, or lifecycle/timer reset checks. If anything is missing, update docs/dev/dod/tool_ui_readiness_dod.md in place. Create docs/dev/reports/level_10_6p_tool_ui_readiness_dod_gap_report.md with per-tool findings and explicit yes/no answers. Run npm run test:launch-smoke:games and npm run test:sample-standalone:data-flow if available. Place final ZIP at tmp/BUILD_PR_LEVEL_10_6P_COMPLETE_TOOL_UI_READINESS_DOD.zip."
+codex --model gpt-5.4 --reasoning high "Run BUILD_PR_LEVEL_10_6Q_TOOL_UI_READINESS_DOD_COMPLETION. Complete the Tool UI Readiness DoD across all current tools. Do not implement runtime fixes. Inspect actual tool files only as needed. Add or update docs/pr/BUILD_PR_LEVEL_10_6Q_TOOL_UI_READINESS_DOD_COMPLETION.md and write docs/dev/reports/level_10_6Q_tool_ui_readiness_dod_completion_report.md. Explicitly report any missed fields, controls, bindings, inputs, lifecycle/timer checks, and tool-specific acceptance checks. Keep one PR purpose only. Do not modify start_of_day folders. Do not rewrite roadmap content; status-only if execution-backed. Return ZIP at tmp/BUILD_PR_LEVEL_10_6Q_TOOL_UI_READINESS_DOD_COMPLETION.zip." 
 ```

docs/dev/commit_comment.txt

@@ -1 +1 @@
-Complete tool UI readiness DoD and require per-tool gap report - PR 10.6P
+Complete Tool UI Readiness DoD with per-tool control and lifecycle acceptance targets - PR 10.6Q

docs/dev/dod/tool_ui_readiness_dod.md

@@ -22,6 +22,7 @@ all required files fetched
 all required file shapes validated
 all required UI controls populated from loaded data
 all required controls emit readiness diagnostics
+safe empty/error state exists for missing required data
 no required control uses fallback/demo/default data
 no required control silently self-populates
 ```
@@ -41,6 +42,7 @@ accordion/section auto-closes without user action
 tool says success before controls are ready
 tool loads from hardcoded sample path
 tool loads duplicate wrapper data instead of canonical data
+safe empty/error state is missing for required data failures
 ```
 
 ## Mandatory diagnostic events
@@ -56,6 +58,7 @@ Every tool with required data must emit these diagnostics during launch:
 [tool-load:classification]
 [tool-ui:control-ready]
 [tool-ui:lifecycle]
+[tool-ui:final-ready]
 ```
 
 ### Required diagnostic fields
@@ -75,6 +78,7 @@ actual.controlValues
 actual.outputValues
 actual.expectedCount
 actual.actualCount
+actual.finalReady
 classification
 ```
 
@@ -91,6 +95,7 @@ empty
 defaulted
 stale
 reset
+lifecycle-failure
 ```
 
 ## Required output fields (all tools)
@@ -128,6 +133,19 @@ cause
 classification
 ```
 
+### Required final-ready diagnostics
+
+```text
+[tool-ui:final-ready]
+toolId
+sampleId or gameId when available
+requiredInputsReady: true|false
+requiredControlsReady: true|false
+requiredOutputsReady: true|false
+lifecycleStable: true|false
+classification
+```
+
 ### Failure
 
 ```text
@@ -401,6 +419,7 @@ palette control populated from canonical palette when visible
 paint/fill control binds loaded paint/fill data
 stroke control binds loaded stroke data
 transform controls bind selected loaded shape/path
+for samples 1215/1216/1217, final-ready must fail when palette/paint/stroke bindings are missing
 ```
 
 ### Failure
@@ -456,6 +475,7 @@ entity list populated from vector map entities
 selected entity panel binds selected loaded entity
 palette/color controls bind canonical palette when required
 zoom/pan controls operate on loaded map
+samples 1212/1213/1214 may be used as known-good acceptance references for loaded layer/entity bindings
 ```
 
 ### Failure
@@ -505,7 +525,7 @@ event list populated from events array
 timeline/scrubber range matches loaded events
 playback uses loaded events
 current event display updates from loaded event data
-speed control affects loaded replay
+time readout tracks loaded replay timeline
 ```
 
 ### Failure
@@ -539,6 +559,15 @@ classification/status panel
 control readiness table
 ```
 
+### Required output fields
+
+```text
+status text that reports Loaded preset or load failure
+required input count output (expected vs actual)
+required control count output (expected vs actual)
+final readiness output/classification
+```
+
 ### Success
 
 ```text
@@ -1150,7 +1179,7 @@ lifecycle/timer reset checks
 Codex must write findings to:
 
 ```text
-docs/dev/reports/level_10_6p_tool_ui_readiness_dod_gap_report.md
+docs/dev/reports/level_10_6Q_tool_ui_readiness_dod_completion_report.md
 ```
 
 If Codex finds a missing field/control/check, it must update this DoD document in the same PR before implementing any stabilization logic.
@@ -1175,6 +1204,6 @@ Codex is done only when:
 ```text
 all required input classifications are success
 all required control classifications are success
-no required control classification is missing, wrong-shape, empty, defaulted, stale, or reset
+no required control classification is missing, wrong-path, wrong-shape, empty, defaulted, stale, reset, or lifecycle-failure
 Generic failure signals detected: 0
 ```

docs/dev/reports/level_10_6Q_tool_ui_readiness_dod_completion_report.md

@@ -0,0 +1,83 @@
+# Level 10.6Q Tool UI Readiness DoD Completion Report
+
+## 1. Tools inspected
+Inspected active launchable tool surfaces and launch hosts (focused file-backed audit):
+- `vector-map-editor`
+- `vector-asset-studio`
+- `tile-map-editor`
+- `parallax-editor`
+- `sprite-editor`
+- `skin-editor`
+- `asset-browser`
+- `palette-browser`
+- `state-inspector`
+- `replay-visualizer`
+- `performance-profiler`
+- `physics-sandbox`
+- `asset-pipeline-tool`
+- `tile-model-converter`
+- `3d-json-payload-normalizer`
+- `3d-asset-viewer`
+- `3d-camera-path-editor`
+- `workspace-manager`
+- sample launch tiles (`samples/index.render.js`)
+- game launch tiles (`games/index.render.js`)
+- shared diagnostics (`tools/shared/toolLoadDiagnostics.js`)
+- shared shell accordion behavior (`tools/shared/platformShell.js`)
+
+## 2. Missing required inputs found
+Yes.
+- Sample launch tiles currently route `samplePresetPath` only; downstream required dependency keys are not surfaced as a required pre-launch contract in launch UI.
+- Workspace Manager forwards query params and validates path prefix/sanitization, but does not expose a per-tool required-input contract table before mount.
+- Manifest/Data Flow Inspector is a required DoD category, but no standalone active tool id exists in the current registry for that exact surface.
+
+## 3. Missing UI controls found
+Yes (runtime-vs-DoD delta that remains implementation work).
+- Sprite Editor: DoD requires explicit `Color 1` / `Color 2` selectors; runtime exposes active color and palette controls but no dedicated Color1/Color2 control ids.
+- Replay Visualizer: DoD previously referenced speed control in success logic; runtime exposes timeline/time readout controls, not a dedicated speed control UI.
+- Cross-tool: several tools still lack explicit final-ready control surfaces that summarize required inputs/controls/outputs in one place.
+
+## 4. Controls not bound to loaded data
+Yes.
+- Control-ready diagnostics are not emitted uniformly across all tools.
+- `logToolUiControlReady` exists in shared diagnostics but many tools currently only emit load diagnostics (`request/fetch/loaded/warning/error`) without per-control readiness evidence.
+- Lifecycle and final-ready diagnostics are not currently emitted from shared diagnostics API (`[tool-ui:lifecycle]` and `[tool-ui:final-ready]` are DoD-required but not implemented as emitters in `toolLoadDiagnostics.js`).
+
+## 5. Timer/lifecycle risks found
+Yes.
+- DoD now requires lifecycle stability and explicit lifecycle/final-ready diagnostics, but runtime diagnostic coverage is incomplete.
+- Shared shell uses accordion state persistence and emits control-ready logs for accordion state; however lifecycle classification events are not emitted as a first-class diagnostic family.
+- A delayed watcher start exists in shared shell (`setTimeout` before `startWatching` for sample launches), which reinforces need for lifecycle-phase diagnostics to prove no post-load reset behavior.
+
+## 6. Palette contract gaps found
+Yes (mostly diagnostics/readiness proof gaps, not canonical source regression).
+- Canonical palette source rules are encoded in DoD; active metadata uses canonical palette paths for palette-browser roundtrips.
+- Remaining gap is readiness proof consistency: final-ready/lifecycle diagnostics and per-control readiness are not uniformly emitted across palette-backed tools.
+- Sprite Editor still does not expose dedicated Color1/Color2 controls even though DoD requires those acceptance checks.
+
+## 7. Per-tool DoD additions made
+Updated `docs/dev/dod/tool_ui_readiness_dod.md` to complete remaining 6Q gaps:
+- Added safe empty/error-state requirement to global success/failure rules.
+- Added `[tool-ui:final-ready]` to mandatory diagnostic events.
+- Added `actual.finalReady` to required diagnostic fields.
+- Added `lifecycle-failure` classification value.
+- Added explicit required final-ready diagnostic payload block.
+- Corrected Replay success criteria to use timeline/time-readout behavior.
+- Added Vector Asset Studio sample-specific acceptance check for 1215/1216/1217 palette/paint/stroke readiness.
+- Added Vector Map Editor known-good acceptance reference check for 1212/1213/1214.
+- Added required output fields block to Manifest/Data Flow Inspector section.
+- Updated Codex review output path reference to this 6Q report.
+- Tightened final acceptance classification exclusions to include `wrong-path` and `lifecycle-failure`.
+
+## 8. Remaining blockers before UAT
+Implementation blockers remain (outside this docs-only PR scope):
+- Missing runtime emitters for `[tool-ui:lifecycle]` and `[tool-ui:final-ready]` across active tools.
+- Incomplete cross-tool adoption of `[tool-ui:control-ready]` per required control/output.
+- Workspace/launch surfaces do not yet show complete downstream required-input readiness before tool mount.
+- Sprite Editor dedicated Color1/Color2 control requirement is not yet implemented.
+- Manifest/Data Flow Inspector required surface is not represented as an active standalone tool id.
+
+## 9. UAT readiness decision
+`NOT READY - DoD complete, implementation fixes required`
+
+The DoD document is now completed for current tool coverage and acceptance language, but runtime diagnostics/control-readiness implementation is not yet complete enough for reliable UAT pass/fail automation.