acdream/docs/research/2026-05-26-a8-r3.5-restructure-handoff.md

Phase A8 — R3.5 transition-flicker iteration PAUSED. Handoff for restructure session.

Date: 2026-05-26 (PM) Status: R1 + R2 + R3 + R3.5 v1 + R3.5 v2 all shipped. Primary #78 indoor fix WORKS. Three distinct transition/sky issues surfaced during R4 visual verification that resist symptom-level patching. Paused for proper brainstorm → write-plan → execute-plan workflow in a fresh session. Branch: claude/strange-albattani-3fc83c (worktree) HEAD: 2bfeafd Predecessor handoff: docs/research/2026-05-26-a8-revert-handoff.md Original re-plan: docs/superpowers/plans/2026-05-26-phase-a8-replan.md Entity-taxonomy fix-shape (approved): docs/research/2026-05-26-a8-entity-taxonomy.md

---

TL;DR

R1 (IsBuildingShell flag), R2 (EntitySet partition reshape), R3 (render-frame integration of WB-order stencil pipeline) all shipped clean. The primary #78 fix WORKS: standing inside a Holtburg cottage, the walls now block outdoor visibility — no see-through buildings, no see-through scenery. M1.5's "indoor world feels right" is partially achieved.

Visual verification (R4) surfaced three remaining issues that are NOT individual bugs — they're symptoms of an architectural mismatch between our render frame and WB's RenderInsideOut reference. Specifically: we draw terrain unconditionally before the stencil work and use depth-clear-if-inside as a workaround, while WB skips initial terrain entirely when inside and renders terrain ONLY at the stencil-gated step. Two patch attempts (R3.5 v1 and R3.5 v2) papered over parts of the symptom but kept producing new edge cases — the exact "patching symptoms" anti-pattern CLAUDE.md and the predecessor revert handoff explicitly call out.

Next session must brainstorm the right architecture, write a plan, and execute. Do NOT continue inline patches.

---

What shipped this session (5 commits)

Commit	Task	What it does
ed72704	R1	Adds WorldEntity.IsBuildingShell: bool init set in LandblockLoader.Buildings loop; propagated through GameWindow.cs:5129-5136 hydration. 2 LandblockLoader tests lock the data-layer guarantee.
55f26f2	R2 (amended)	Reshapes WbDrawDispatcher.EntitySet from IndoorOnly/OutdoorOnly to taxonomy-aware IndoorPass / OutdoorScenery / LiveDynamic. Adds private static bool EntityMatchesSet(WorldEntity, EntitySet) truth-table predicate. 7 tests cover the partition.
60f07bc	R3	Wires the stencil pipeline into GameWindow render frame with WB-order: MarkAndPunch → IndoorPass → EnableOutdoorPass → terrain re-draw → OutdoorScenery → DisableStencil → LiveDynamic. Stencil-marks camera's own cell's exit portals only (WB Step 5 deferred).
38d5374	R3.5 v1	Adds cameraReallyInside = PointInCell(camPos, visibility.CameraCell) gate for the stencil branch (kept cameraInsideCell for sky / lighting / depth-clear). Attempt to close the exit-transition flicker.
2bfeafd	R3.5 v2	Also gates the depth-clear-if-inside on cameraReallyInside. Attempt to close the "objects through ground" symptom the v1 fix exposed.

All 5 commits are kept; none are reverted. Build green at HEAD. Test failures within the documented 14-23 pre-existing flaky window.

---

What's WORKING (the primary fix)

Standing inside any Holtburg cottage (ground floor or cellar), looking around:

• Walls are solid. No outdoor scenery visible through walls. No buildings visible through walls.
• The original #78 symptom is gone. This is the primary acceptance criterion for the A8 phase.
• User confirmed: "Ok better. ... When I look out now from inside it is not showing buildings below or any windows inside the house."

The architectural win is real:

• WorldEntity.IsBuildingShell correctly tags cottage walls at the dat-source boundary (LandblockLoader.Buildings loop).
• WbDrawDispatcher.EntitySet.IndoorPass correctly routes cell mesh + cell statics + building shells together — fixing the previous Round-3 regression where cottage walls disappeared.
• Camera's-own-cell-portals-only approximation (Step 5 deferred) avoids the "see through wall to another room's outdoor" regression from previous Round 2.

---

What's NOT WORKING (3 transition/sky issues)

Verbatim user reports from R4 visual verification (post R3.5 v2):

Issue A — Exit indoor→outdoor: "objects through ground + building parts missing"

"If I stand outside or just pass outside I get the flicker where objects are visible through ground and walls of other buildings are missing"

My diagnosis: during the 3-frame grace window after camera physically exits a cell (CellVisibility._cellSwitchGraceFrames), cameraInsideCell stays true but cameraReallyInside becomes false (PointInCell on the previous cell returns false). With v2:

• Sky still skipped (cameraInsideCell)
• Initial terrain still drawn (unconditional, line 7115)
• depth-clear NOT fired (cameraReallyInside)
• Stencil branch NOT taken (cameraReallyInside)
• Outdoor branch (Draw(set: All)) runs

This should be correct — terrain depth preserved, all entities depth-tested. But the user still sees the symptom. Working hypothesis: with the depth buffer holding terrain Z (~99.99 post the -0.01 nudge from f48c74a), entities at world Z below terrain may still win depth tests in certain camera angles. Or the issue is something else entirely that the v2 didn't address.

Issue B — Inside looking through window: "Sky don't render"

"Sky dont render when I look from inside to outside"

My diagnosis: when inside, sky pass is skipped (if (!cameraInsideCell) { _skyRenderer?.RenderSky(...); ... } at line 7079). The stencil-gated outdoor pass re-draws terrain + outdoor scenery in portal silhouettes, but NOT sky. Through a window, the user sees terrain (where it projects in the portal silhouette) and beyond the terrain horizon — fog color (the framebuffer clear color is set to fog haze at line 6894, not sky color).

This is a known WB-pipeline limitation — WB itself doesn't draw sky inside-out. To fix in acdream we'd add a stencil-gated _skyRenderer.RenderSky call inside the indoor branch between EnableOutdoorPass and the terrain re-draw. Not done in any R3.5 patch.

Issue C — Entry outdoor→indoor: "floor transparent showing cellar + wrong texture"

"When going from outside to inside flickering so that parts of the floor is transparent so I see the cellar from above and wrong texture on the floor"

My diagnosis (LOWER CONFIDENCE): the cottage floor and cellar ceiling are at adjacent world Z values. Both meshes are loaded (cottage cell + cellar cell both in VisibleCellIds when standing in the cottage). During the entry transition frame, depth-fight may occur between cottage floor (Z=100.02 with the +0.02 cell origin bump) and cellar ceiling (whatever Z that mesh sits at). "Wrong texture" suggests the cellar ceiling is winning depth at floor pixels and its texture is showing through. This is likely a pre-existing data-model / multi-cell-Z artifact, not strictly an A8 bug, but it became visible because the new pipeline doesn't have the depth-clear-if-inside masking it on every frame anymore.

---

Architectural diagnosis — the root cause

Reading references/WorldBuilder/Chorizite.OpenGLSDLBackend/Lib/VisibilityManager.cs:73-239 carefully:

WB's RenderInsideOut order:

1. (No initial terrain. Depth buffer is empty from frame-start glClear.)
2. MarkAndPunch — stencil bit 1 + depth = 1.0 at exit-portal silhouettes only.
3. Render interior EnvCells with stencil OFF, normal DepthFunc.Less. Cell mesh wins fresh depth at most pixels.
4. Enable stencil restriction (StencilFunc Equal 1, 0x01).
5. Render terrain + scenery + static objects — at portal silhouettes ONLY (stencil-restricted). Terrain depth (close, ~99.99) wins against the 1.0 punch in portal areas → outdoor visible through windows.
6. (Step 5: WB's 3-stencil-bit pipeline for cross-building visibility — deferred.)

Our R3.5 v2 order:

1. Terrain drawn unconditionally (line 7115; color + depth at ~99.99).
2. depth-clear-if-cameraReallyInside (depth → 1.0; redundant with MarkAndPunch).
3. MarkAndPunch (no-op against the depth-cleared 1.0).
4. IndoorPass — cell mesh + statics + building shells.
5. EnableOutdoorPass + terrain RE-draw + OutdoorScenery (stencil-gated).
6. DisableStencil + LiveDynamic.

The mismatch: we draw terrain TWICE (initial + re-draw) and have a depth-clear that's a workaround for the initial terrain draw. WB avoids both by skipping the initial terrain entirely when inside. Our pipeline is a "FRANKENSTEIN" — it works in the steady-state indoor case (the primary #78 fix) but breaks at transitions and during grace frames because the interactions between (initial terrain + depth-clear + grace + cameraInsideCell vs cameraReallyInside flag asymmetry) keep producing new edge cases.

The R3.5 v1 and v2 patches were symptom-fixes, not root-cause fixes. CLAUDE.md is explicit about this: "When you spot a bug or encounter a behavioral mismatch, fix the underlying cause — do not ship a band-aid, suppression flag, grace period, retry loop, or any other 'make the symptom go away' shortcut, unless the user has explicitly approved that shape." The user has now correctly pulled the emergency brake.

---

Recommended next-session approach

Use the superpowers full workflow:

Phase 1: BRAINSTORM (use superpowers:brainstorming)

Settle the design BEFORE writing a plan. Key brainstorm questions:

1. Should the initial terrain draw be conditional?

   • WB faithfully: yes, skip when cameraReallyInside. Terrain draws only at stencil-gated step.
   • Hybrid: keep initial terrain unconditional but remove the depth-clear so terrain depth wins against indoor cells at non-portal pixels. (Would break the #78 fix — cottage floor at +0.02 would lose to terrain at -0.01.)
   • Probably WB-faithful is the right call.

2. Should sky be re-drawn stencil-gated when inside?

   • WB: no. Sky color shows as fog-clear-color through windows.
   • acdream enhancement: yes, render _skyRenderer.RenderSky between EnableOutdoorPass and the terrain re-draw inside the indoor branch.
   • Tradeoff: WB-faithfulness vs. user's expectation that windows show sky. Retail probably shows sky through windows; investigate retail's polygon-clip scissor approach.

3. What's the deal with the entry-flicker "floor transparent showing cellar"?

   • Is it depth-fight between cottage floor mesh (Z=100.02) and cellar ceiling mesh (Z=?)? Need a brief investigation to confirm.
   • Is it a one-frame visibility-update lag where cottage cell isn't yet in VisibleCellIds during the entry transition frame?
   • Is it pre-existing in main (test by reverting all of A8 and entering a cottage on main)?
   • Don't try to fix this in A8. Identify, file as separate follow-up (likely candidate for #103 family or new #106).

4. Should we eliminate cameraInsideCell vs cameraReallyInside asymmetry?

   • Today: cameraInsideCell (grace-aware) gates sky/lighting; cameraReallyInside (PointInCell, no grace) gates depth-clear + stencil branch.
   • The split is a workaround for the grace-mechanism conflict with the render path. With WB-faithful order (no initial terrain, no depth-clear), can we use cameraReallyInside everywhere? Or does that introduce sky flicker at the threshold?
   • The grace mechanism was added to prevent cell-id flicker at doorways. Does PointInCell with its existing epsilon already provide enough hysteresis?
   • Likely path: unify on cameraReallyInside and remove the grace mechanism entirely. Simpler is better.

5. Are R3.5 v1 + v2 patches worth keeping or should we revert them before the restructure?

   • v1 (stencil branch gate): subsumed by the restructure since the stencil branch will use cameraReallyInside.
   • v2 (depth-clear gate): subsumed since depth-clear gets DELETED entirely.
   • Recommendation: revert v1 and v2 (git revert 2bfeafd 38d5374 or new commits) at the start of the implementation session, work from the R3 baseline. Cleaner diff, easier review.

Phase 2: WRITE-PLAN (use superpowers:writing-plans)

Expected plan shape (TDD where possible):

• Task RR1: Revert R3.5 v1 + v2 (git revert 38d5374 2bfeafd). Result: HEAD at logical state of 60f07bc (R3 baseline).
• Task RR2: Restructure render frame to WB-faithful order. Sub-steps:
  • Move cameraReallyInside computation up next to cameraInsideCell (~line 7011-7014).
  • Gate the initial terrain draw (line 7115) on !cameraReallyInside.
  • Delete the depth-clear-if-inside block entirely.
  • Decide on cameraInsideCell vs cameraReallyInside unification (per Phase 1 brainstorm Q4).
  • Inside branch: keep existing structure (MarkAndPunch → IndoorPass → EnableOutdoorPass → terrain → OutdoorScenery → DisableStencil → LiveDynamic).
• Task RR3 (optional): Add stencil-gated sky pass for sky-through-windows (per Phase 1 brainstorm Q2). Or defer as #105.
• Task RR4: Visual verification matrix (same as R4: cottage interior, cellar, inn, dungeon; PLUS exit transition, entry transition, sky-through-windows).
• Task RR5: Ship docs (R5 from original plan; file the genuine follow-ups; close #78).

GL integration tasks are visual-verification-only by nature (the partition logic + EntitySet are already unit-tested). Don't burn cycles writing unit tests for GL state — the existing infrastructure tests (26 dispatcher + 5 stencil + 2 PortalPolygons + 1 ProbeVisibility = 34) already lock the non-GL bits.

Phase 3: EXECUTE-PLAN (use superpowers:subagent-driven-development)

Same pattern as this session: fresh Sonnet subagent per task, two-stage review (spec compliance + code quality). The CRITICAL extra review check beyond default — add to the spec reviewer prompt: "Does the implementation match WB's RenderInsideOut order at references/WorldBuilder/Chorizite.OpenGLSDLBackend/Lib/VisibilityManager.cs:73-239? Specifically: NO initial terrain draw when inside, NO depth-clear, terrain rendered ONLY stencil-gated?"

---

Pickup prompt for next session

Phase A8 — render frame restructure to match WB's RenderInsideOut order
faithfully. R1+R2+R3+R3.5 v1+v2 shipped this session (commits ed72704 →
2bfeafd). Primary #78 fix works (cottage interior solid walls). Three
transition/sky issues remain that resist symptom patching.

Read first (in this order — REQUIRED):
  1. docs/research/2026-05-26-a8-r3.5-restructure-handoff.md (this doc — full
     story of why we paused; the architectural mismatch; recommended path)
  2. docs/research/2026-05-26-a8-entity-taxonomy.md (approved fix-shape)
  3. docs/research/2026-05-26-a8-revert-handoff.md (predecessor; the original
     A8 attempt's revert lessons — still applies)
  4. docs/superpowers/plans/2026-05-26-phase-a8-replan.md (this session's
     plan — R1+R2+R3 still apply; R3.5 patches and the WB-faithful
     restructure are NEW work)
  5. references/WorldBuilder/Chorizite.OpenGLSDLBackend/Lib/VisibilityManager.cs:73-239
     (the proven reference — read it verbatim BEFORE designing the restructure)
  6. CLAUDE.md — find "currently working toward" to refresh state

State both altitudes:
  Currently working toward: M1.5 — Indoor world feels right
  Current phase: A8 — render frame restructure to WB-faithful order
  HEAD: 2bfeafd (R3.5 v2)
  Clean revert points: 60f07bc (R3 baseline) or 55f26f2 (R2)
  Test baseline: build green; 1238 pass / 14 fail (documented flaky window)

Session flow — MUST use full superpowers workflow:

### Phase 1 — BRAINSTORM (use superpowers:brainstorming)

Settle the design. Do NOT skip this. The previous session jumped to
patching after R3 and that produced this handoff. Five questions in the
recommended-next-session-approach section of this handoff doc must be
answered before any code is written.

Brainstorm output: a short design note in chat + an updated entry in the
entity-taxonomy doc OR a fresh design doc. Get user approval before
Phase 2.

### Phase 2 — WRITE-PLAN (use superpowers:writing-plans)

Expected: tasks RR1 (revert R3.5), RR2 (restructure render frame), RR3
(optional sky-through-windows), RR4 (visual verification), RR5 (ship
docs). Plan path: docs/superpowers/plans/2026-05-2X-phase-a8-restructure.md
(date when written).

### Phase 3 — EXECUTE (use superpowers:subagent-driven-development)

Fresh Sonnet subagent per task with two-stage review. Add the WB-order
check to the spec reviewer prompt (see handoff doc).

## Constraints

- Per CLAUDE.md "no workarounds without approval" — fix the root cause.
  The R3.5 v1+v2 patches were symptom fixes. Do not repeat that pattern.
- Visual verification is the acceptance test. Test scenarios in the
  handoff's "What's NOT working" section MUST all be re-tested.
- Existing infrastructure (Tasks 1-6 + R1 + R2 + R3) is correct and
  shipped. The restructure is a render-frame surgery, not a partition
  reshape or data-layer change.

## What success looks like

After this restructure ships:
  - Standing INSIDE cottage / cellar / inn / dungeon: solid walls
    (unchanged from this session's R3 win).
  - EXITING indoor → outdoor: clean transition. No "objects through
    ground." No "buildings missing." Brief lighting transition is OK if
    sky-on-cameraInsideCell is kept, otherwise no lighting transition.
  - ENTERING outdoor → indoor: clean transition. No floor-transparent
    showing cellar. If the floor-cellar-z-fight is pre-existing on
    main, file as a separate issue and accept it as not-A8-scope.
  - LOOKING THROUGH WINDOWS from inside: terrain visible at the
    portal silhouette. Sky visible (if RR3 included) OR fog color (if
    RR3 deferred and noted in #105).
  - dotnet build green; test failures within the documented 14-23
    flaky window.

---

Files state at session end

Branch:   claude/strange-albattani-3fc83c
HEAD:     2bfeafd fix(render): Phase A8 R3.5 v2 — gate depth-clear on cameraReallyInside too
Parent:   38d5374 fix(render): Phase A8 R3.5 — gate stencil branch on PointInCell containment
GP:       60f07bc feat(render): Phase A8 R3 — wire stencil pipeline into render frame (WB order)
GGP:      55f26f2 feat(render): Phase A8 R2 — WbDrawDispatcher.EntitySet taxonomy partition
GGGP:     ed72704 feat(world): Phase A8 R1 — tag WorldEntity.IsBuildingShell at LandblockLoader

Working tree: clean
Build:    green (0 warnings, 0 errors)
Tests:    1238 pass / 14 fail (all within documented 14-23 flaky window;
          zero new failures attributable to A8 R1/R2/R3/R3.5)
Untracked log files: launch-a8-verify*.log (deletable)

The five commits are all NEW additions to main; no destructive history rewrites. Next session can:

• Continue from HEAD with the restructure layered on top (R3.5 patches subsumed by it).
• OR git revert 38d5374 2bfeafd for a cleaner diff against R3 baseline.

Either path is valid — pick whichever the brainstorm settles on.