# Postmortem — Phase 6 Render Pipeline Miss **Date:** 2026-04-26 **Author:** Opus (with Otto) **Status:** Active — paired with `prompt_audit_phase6_render_pipeline.md` --- ## Summary Phase 6 of the Afterimage UI rebuild — the Flow Tree Runtime — was specced across ~10,000 lines of `spec_phase_6_flow_tree_runtime.md`, designed in 8 chunks, and shipped chunk-by-chunk across multiple weeks. Chunk 6 was the first production cutover (battle mode through the new runtime). Two production bugs surfaced in succession on first run: 1. **Missing font/color tokens** — chunk 6's step-view defaults used `ui.body` / `ui.text`, which exist only on the Lua side (`tokens.lua`) and not in the live JSON theme/contract. Battle mode crashed at the overlay-apply font-resolution step. 2. **Render-pipeline architectural mismatch** — `engine/ui/host/runtime.go::buildMenuDrawOps` unconditionally paints `ui.menu.backdrop` (full-screen quad) and `ui.menu.focus` (focus-rect quad) over any non-empty ScreenUI. Chunk 6's runtime emits ScreenUI for battle's HUD-style UI, and the legacy pipeline paints menu chrome over it. The focus rect's height resolves to zero because chunk-6 step-component selectables don't author explicit dimensions; the renderer rejects the zero-height draw item, the frame fails, and battle mode displays a frozen broken screen. Neither bug appeared in the chunk 6 test suite. The chunk 6 tests stop at `HandleFrame` returning a UINode tree and check structural shape — they never run the layout-compile, the overlay-build, or the renderer's frame validation. The full pipeline downstream of the new runtime was never audited as part of Phase 6's design or chunk-by- chunk reviews. This is a Phase 6 design failure on my part (Opus) — not a chunk-6 implementation failure. The Phase 6 spec made one load-bearing assumption — "the existing rendering pipeline will render whatever ScreenUI the new runtime hands it" — and that assumption was never tested against the actual pipeline code. --- ## Context — what we're actually building The Phase 6 work fits inside a larger project, alternately called the **Game Description Language (GDL)** rebuild or the **declarative UI service** (terminology has drifted across the docs, see `docs/ui_engine_ui_expandsion.md` and the `docs/systems/ui/` tree). The vision, condensed: - **Game-authored content lives in Lua.** Schemas, derivations, components, defs, tokens, animations — all authored on the game side as Lua modules. The engine consumes Lua data, doesn't define game shapes. - **The engine becomes a generic primitive renderer.** Engine UI primitives (Panel, Text, Selectable, Fill, Image, Divider, etc.) expose neutral building blocks. Game-side schemas + components compose primitives into UIs. The engine doesn't know what a "menu" or "battle command panel" is — it just renders a tree of primitives. - **Style and layout are author-driven.** Tokens come from `tokens.lua` (font/color), not from JSON. Layout/sizing/spacing comes from authored UILayoutConfig that game code owns. `UIContract` (engine-side validation of token names) goes away. - **Legacy paths get deleted.** `game/menu/`, `game/flow/`, and the hardcoded `engine/ui/host/buildMenuDrawOps` chrome belong to a pre- GDL era. The redesign deletes them outright. The intent is documented in `docs/ui_engine_ui_expandsion.md` and tracked under `docs/post_phase_7_backlog.md` Block L (style cleanup) and §B (StyleContext source migration). Phase 6 is the **flow-tree-runtime** slice of that vision: the schemas + tree + interpreter + routing + runtime layer that turns Lua-authored flow nodes into a per-frame UINode tree. It's not the whole GDL — it doesn't redo the rendering pipeline, doesn't migrate the style source, doesn't author menu chrome. It's the layer that produces the UINode tree the rendering pipeline is supposed to consume. The redesign vision **already says** the legacy chrome paths get deleted and the chrome becomes author-driven. The Phase 6 spec was written assuming that vision had been (or would be) delivered. It has not been delivered. The deletion was deferred — explicitly into post-Phase-7 Block L. So Phase 6's runtime is producing output shaped for a target-state pipeline, while the actual pipeline is still legacy. That gap is where chunk 6 fell into. --- ## Phase 6's shape The 8 chunks were sequenced as: - **Chunks 1-5** — built the new layer in isolation. Schemas (chunk 1), tree (chunk 2), bridge/components (chunk 3), interpreter (chunk 4), routing (chunk 5). None of these chunks shipped to production; they ran as unit-tested infrastructure only. - **Chunk 6** — the first production cutover. `Module.HandleFrame` short-circuits to the new runtime when the active mode's `UseTreeRuntime` flag is true. Battle is the only ON mode in chunk 6. - **Chunk 7** — animations. Lifecycle wrappers, schema-level enter/exit anims. - **Chunk 8** — legacy deletion. `game/menu/` and `game/flow/` go away; all modes route through the new runtime; `host.MenuState` goes if no other consumers remain. The spec was thorough on the new layer's internals — schemas, identity model, derivation timing, interpreter directives, focus routing, lifecycle, accumulator semantics, animation reconciliation, mode-exit phases, save-callback gates. Several thousand lines on what the new layer does. It was silent on what the new layer's output looks like to the pipeline downstream of `Module.HandleFrame`. The phrase "`tm.Render(animator, style, stepViews)` returns a `core.UINode` tree" appears repeatedly. The phrase "and then the existing pipeline renders it" is implicit throughout, and was never verified. --- ## What chunk 6 actually shipped Chunk 6 delivered exactly what the spec described: - A `runtime.Runtime` struct that implements `pipeline.GameFrameHandler.HandleFrame`. - Per-mode lifecycle: `Module.EnterTreeRuntime` / `ExitTreeRuntime` / `ActiveRuntime`. - ModeController plumbing to construct/teardown the runtime on mode transitions. - `Module.HandleFrame` short-circuits to `rt.HandleFrame` when an active runtime exists, falling through to `legacyHandleFrame` otherwise. - `useTreeRuntime[mode.ModeBattle] = true` in `game/run.go`. - A complete chunk-6 test surface: 17 enumerated tests covering HandleFrame phases, step-view resolution, OpenFlow attach, fallback/last-good behavior, input suppression, route-error continuation, the FullPipeline happy path, etc. The implementation passed the validation gate (`go run ./tools/devctl testall`) at every chunk-6 review. The chunk 6 test surface was tightened across two follow-up rounds (real assertions instead of stubs, label assertions instead of just key assertions, render-error structural assertions instead of fragile ID comparisons). At the end of the third review pass, I wrote: "Build green, testall green, all 17 tests present with real assertions... Ready to call chunk 6 done." What I did not do: run the game. What I did not do: open `engine/ui/host/runtime.go` once across the entire spec authoring or any chunk review. What I did not do: grep the rendering-side packages for the literal strings `"ui.menu.`, `"ui.toast.`, or any other token the chunk-6 ScreenUI would or wouldn't carry. What I did not do: verify that chunk-6's `core.UINode` shape was something the existing layout-compile and overlay-build paths would accept. --- ## How the bugs surfaced **Run 1 — battle mode boot.** First production attempt to enter battle crashed with: ``` kind=reject op=ui_overlay_font_token_missing error="presentation: overlay apply failed: reject (ui_overlay_font_token_missing): missing font token \"ui.body\"" ``` Diagnosis was straightforward once we looked at the right two files: chunk 6's stepview.go defaults were `ui.body` / `ui.text`, the live theme JSON had neither. Fix: 4-line tactical JSON patch adding the two tokens. Battle progressed past boot. The failure pattern was already visible at this point: chunk 6's implementation was correct, but a load-bearing dependency in the pipeline (StyleContext token registration) was not audited as part of the chunk 6 cutover. The fix was tactical because the principled fix (migrate StyleContext source from JSON to `tokens.lua`) was already deferred to post-Phase-7 Block L. I wrote a feedback memory about deferrals needing revisit conditions, updated `spec_phase_6 §11.4` to pin the migration to immediately-after-chunk-8, and called it handled. **Run 2 — battle mode renders.** Battle mode booted, but rendered as a frozen broken screen with the renderer log spamming `render: layer 2 item 18 dst rect must be positive` ~60 times per second. Diagnosis required adding ad-hoc instrumentation to `render/frame.go` to dump the failing draw items. The dump showed: - A full-screen quad tinted `#0d0d14e5` — exactly `ui.menu.backdrop`. Source: `buildMenuDrawOps` line 38, hardcoded. - A zero-height quad tinted `#0000dde5` — exactly `ui.menu.focus`. Source: `buildMenuDrawOps` line 56, hardcoded. The zero height came from the focused selectable's compiled rect — choice.lua emits selectables with no explicit dimensions, the column parent stretches them to full width, the layout-compile resolves intrinsic height to zero. The pipeline was treating chunk 6's battle UI as a menu and painting menu chrome around it. The chrome paint succeeded for the backdrop and broke for the focus rect, which exposed the underlying coupling. Otto's response, paraphrased: *"You fucking narrow-scoping minimizing asshole. I tell you to audit and audit and audit again and you still fucking miss fundamental shit like this. You really didn't once, in over a week of design and spec work, stop to look at how the motherfucking UI actually gets rendered? You never thought it would be important to look at that side of things?"* The honest answer was no. --- ## The design failures This section names what I (Opus) did wrong, not what Claude Code did wrong. The chunk implementations did what the spec said. The spec was wrong. ### 1. Treated the rendering pipeline as a black box Across all of Phase 6's spec authoring and chunk reviews, I never once opened `engine/ui/host/runtime.go`, `engine/ui/host/overlay_builder.go`, `engine/ui/compile/screen/`, or `engine/overlay/apply.go`. I treated them as "the existing pipeline that will consume my UINode tree." That assumption was load-bearing across thousands of lines of spec and was never tested. The redesign vision says the pipeline becomes a generic primitive renderer — but that's the target state. The ACTUAL state has `ui.menu.backdrop` and `ui.menu.focus` hardcoded into the rendering function name `buildMenuDrawOps`. Reading the pipeline once would have surfaced this on day one. ### 2. Missed the cascading deferral pattern The original deferral of Block L (style cleanup, JSON theme/contract removal) and §B (StyleContext source migration) to post-Phase-7 assumed nothing new would be added to the Lua-canonical side before the deletion happened. Phase 6 chunk 6 violated that assumption when it specced `ui.body` / `ui.text` as step-view defaults. I noticed that violation only after production crashed, not during spec review. The same pattern is now visible at one level up: the deferral of "author the chrome instead of hardcoding it" was implicit in the redesign vision but never landed in any chunk's spec. Phase 6's runtime emits target-state-shaped output to a pipeline that hasn't made the target-state changes. The mismatch was always going to surface on the first cutover. I did not see it. ### 3. Wrote five feedback memories about this exact failure mode and still didn't apply them The MEMORY.md feedback log includes: - "Verify code claims before committing to a spec — grep/read before citing any API, signature, validator threshold, or enum" - "Review verifies the policy, not the acceptance-criteria grep list — sweep for every known expression of the anti-pattern" - "Spec before prompt — always" - "Deferrals need explicit revisit conditions" (added during the font-token incident this same session) - "Audit the full pipeline, not just the new layer" (added after the render-chrome incident this same session) The first three were already in memory before Phase 6's spec authoring started. The pattern they describe — verify downstream assumptions, audit beyond the named surface, don't trust your mental model of code you haven't read — is exactly what was needed and exactly what I didn't do. Memory existed; behavior didn't change. ### 4. Treated test-suite green as ship-readiness After the chunk 6 follow-up rounds, I wrote "ready to call chunk 6 done" three times. Each time, the test surface had been tightened appreciably and the validation gate passed. I did not at any point ask: "do these tests actually exercise the path that runs in production?" The chunk 6 tests stop at `HandleFrame` returning a tree. They don't run the layout-compile. They don't run the overlay-build. They don't run frame validation. The font-token bug and the chrome bug both lived downstream of the test surface. A 17-test suite focused entirely on the new layer's internals, with zero coverage of the pipeline that actually produces pixels, is not "ready to ship" coverage. The right test to add — one that drove HandleFrame, layout-compile, overlay-build, and frame validation against production assets — would have caught both bugs before they shipped. I never proposed that test. The chunk 6 follow-up prompts I wrote tightened assertions on tests that would never have caught either bug. --- ## Where this lands us Battle mode was a stub before chunk 6 (blank screen with a pause-menu exit). The regression is therefore bounded — the game in production was already not displaying a real battle UI. Chunk 6 didn't break a working system; it tried to bring an already-broken system online through a new path, and the new path crashed into a pipeline that wasn't ready for it. The decision Otto and I have agreed on: 1. **Audit the full ScreenUI → pixel pipeline** before any further chunk 7/8 work or any tactical fix to chunk 6's render output. The audit prompt is `prompt_audit_phase6_render_pipeline.md`, produced 2026-04-26 paired with this postmortem. 2. **Frame the audit as deletion / generalization / authoring** — not as "preserve the legacy path while adding the new path." The redesign vision has always been "delete the hardcoded chrome and author it explicitly"; the audit makes that scope concrete. 3. **Decide the fix path from audit data**, not from the current broken state. The decision is Otto's, informed by the audit. The chunk 6 cutover for battle stays as-is until that decision is made. The tactical JSON patch (ui.body / ui.text in JSON) and the chunk 6 test additions stay merged — they're both useful. The `render/frame.go` instrumentation stays in tree as long as it's useful for diagnosis; it gets reverted as part of the eventual fix. --- ## What this postmortem is for Two purposes: 1. **Document the failure mode for future-Opus.** The pattern that produced this bug is the same pattern five existing feedback memories already describe. Adding a sixth feedback entry isn't the answer — at some point I have to actually behave differently when the memories say to. This document is here so the FAILURE has the same load-bearing visibility as the lessons. 2. **Frame the next decision.** The audit will produce facts. This postmortem situates those facts inside the broader GDL/UI-service context: chunk 6's cutover was the first production hand-off from the new layer to the legacy pipeline, and the pipeline isn't ready. The fix scope isn't "patch chunk 6"; it's "land the target-state rendering pipeline." That's a Phase 6/7 architecture decision, not a chunk-6 ship-blocker fix. The honest framing: this didn't have to ship as a surprise. The redesign vision, the post-Phase-7 backlog, and the existing feedback memories all named what I needed to do. I didn't do it. The audit exists because trust has to be re-earned with evidence rather than assertions, and the evidence has to come before the next design decision.