# Phase A8 — RR1 cleanup SHIPPED. Handoff for RR2 spike in fresh session.

**Date:** 2026-05-26 (PM, end of session)
**Branch:** `claude/strange-albattani-3fc83c` (worktree at `.claude/worktrees/strange-albattani-3fc83c`)
**HEAD:** `29e306b` (RR1 footer-marks)
**Build:** green (0 errors, 0 warnings in App; 6 warnings in test projects are pre-existing lint)
**Tests:** within documented 14-23 flaky window

---

## TL;DR

This session pivoted Phase A8 from "WB-faithful restructure" to "**full WorldBuilder RenderInsideOut + RenderOutsideIn port**" after RR0 falsification revealed R3+R3.5's bugs were structural (BFS-wide cell rendering), not just workaround-induced.

Shipped this session:
- ✅ RR0 falsification spike (proved Issues A+C are R3-caused, not pre-existing on main)
- ✅ Re-brainstorm with new design doc
- ✅ 12-task implementation plan
- ✅ RR1 cleanup: `[vis]` probe committed; R3+R3.5 v1+v2 reverted; old design+plan footer-marked as superseded

Next: **RR2 spike** — inspect `LandBlockInfo.Buildings` data shape + WB's interior-portal walk algorithm before implementing `BuildingLoader` in RR3.

---

## State altitudes

- **Currently working toward:** M1.5 — Indoor world feels right
- **Current phase:** A8 — full WorldBuilder RenderInsideOut + RenderOutsideIn port
- **Tasks remaining:** RR2 (spike) → RR3-RR11 (impl + visual gates) → RR12 (ship)
- **Estimated remaining:** 8-10 sessions / 1.5-2 weeks calendar

---

## What shipped this session (8 commits)

| SHA | What |
|---|---|
| `f9bab50` | docs(research): RR0 findings — A+C caused by R3, NOT pre-existing on main |
| `ea60d1f` | docs(spec): Full WB RenderInsideOut + RenderOutsideIn port design |
| `651e7e2` | docs(plan): 12-task implementation plan |
| `84c4a70` | diag(render): `[vis]` probe — light up dormant `ProbeVisibilityEnabled` |
| `664ca9c` | Revert R3.5 v2 (`2bfeafd`) |
| `b931038` | Revert R3.5 v1 (`38d5374`) |
| `fd721af` | Revert R3 (`60f07bc`) — with `[vis]` probe preserved through conflict |
| `29e306b` | docs: superseded the prior restructure design + plan |

Kept (NOT reverted): R1 (`ed72704` IsBuildingShell tag) + R2 (`55f26f2` EntitySet partition) + Tasks 1-6 infrastructure (PortalPolygons, IndoorCellStencilPipeline, portal_stencil shaders, ProbeVisibilityEnabled). All consumed as-is by the upcoming work.

---

## Canonical pickup docs (READ FIRST in fresh session)

In order:

1. **[docs/superpowers/specs/2026-05-26-phase-a8-wb-full-port-design.md](../superpowers/specs/2026-05-26-phase-a8-wb-full-port-design.md)** — the approved design. Single source of truth for what's being built.
2. **[docs/superpowers/plans/2026-05-26-phase-a8-wb-full-port.md](../superpowers/plans/2026-05-26-phase-a8-wb-full-port.md)** — 12-task plan. Pickup at RR2.
3. **[docs/research/2026-05-26-a8-rr0-falsification-findings.md](2026-05-26-a8-rr0-falsification-findings.md)** — evidence that triggered the scope expansion.
4. **[references/WorldBuilder/Chorizite.OpenGLSDLBackend/Lib/VisibilityManager.cs:73-330](../../references/WorldBuilder/Chorizite.OpenGLSDLBackend/Lib/VisibilityManager.cs)** — the proven reference (RenderInsideOut Steps 1-5 at 73-239; RenderOutsideIn at 241-330).
5. **[CLAUDE.md](../../CLAUDE.md)** — "Currently working toward" section.

---

## RR2 — the spike

### Goal

Before implementing `BuildingLoader` in RR3, verify (a) what fields `DatReaderWriter.Types.BuildingInfo` exposes (specifically the portal list field name + the per-portal `OtherCellId`); (b) how WB's `PortalRenderManager` actually computes a building's full cell set from BuildingInfo entries (the interior-portal walk algorithm).

The plan's RR3 tests reference `building.Portals` and `BldPortal.OtherCellId` — RR2 confirms or corrects those names.

### Steps (per plan §RR2, 6 sub-steps)

1. **RR2-S1** — Inspect `BuildingInfo` struct shape:
   ```bash
   grep -rn "class BuildingInfo\|struct BuildingInfo\|record BuildingInfo" references/Chorizite.DatReaderWriter/ 2>/dev/null | head -5
   ```
   Or look in NuGet cache: `~/.nuget/packages/chorizite.datreaderwriter/*/lib/*/BuildingInfo.cs`. Also document what `LandblockLoader.cs:74-87` references.

2. **RR2-S2** — Read WB `PortalRenderManager.cs:518-551` (or grep `BuildingPortalGPU` + `EnvCellIds`):
   ```bash
   grep -n "BuildingPortalGPU\|EnvCellIds" references/WorldBuilder/Chorizite.OpenGLSDLBackend/Lib/PortalRenderManager.cs | head -10
   ```
   Document the interior-portal walk algorithm.

3. **RR2-S3** — Live-inspect a Holtburg cottage's BuildingInfo. Add a temporary diagnostic in `src/AcDream.Core/World/LandblockLoader.cs:74-87` (the Buildings loop):

   ```csharp
   Console.WriteLine($"[building-shape] lb=0x{landblockId:X8} idx={i} ModelId=0x{building.ModelId:X8} " +
       $"Frame.Origin=({building.Frame.Origin.X:F1},{building.Frame.Origin.Y:F1},{building.Frame.Origin.Z:F1}) " +
       $"Portals={building.Portals?.Count ?? 0}");
   if (building.Portals is not null)
   {
       foreach (var p in building.Portals)
           Console.WriteLine($"[building-shape]   portal -> OtherCellId=0x{p.OtherCellId:X8} " +
               $"(remaining fields: {p.GetType().GetProperties().Length} total)");
   }
   ```

   Build + launch + walk to Holtburg. Capture log. Then `git checkout HEAD -- src/AcDream.Core/World/LandblockLoader.cs` to revert.

4. **RR2-S4** — Write `docs/research/2026-05-26-a8-buildings-data-shape.md` with 5 sections (per plan).

5. **RR2-S5** — Commit findings.

6. **RR2-S6** — Gate decision:
   - Data shape compatible with design → proceed to RR3.
   - Data shape incompatible → STOP, re-brainstorm.

### Expected duration

~30-60 minutes including live-inspect cycle.

### Human-in-the-loop step

RR2-S3 (live-inspect) needs the user to launch + walk into a cottage + report.

---

## Quick context primer for a fresh session

### Why this phase

RR0 falsification proved:
- HEAD (R3.5 v2): Issues A + C reproduce
- R3 baseline (60f07bc): same A + C (R3.5 patches didn't help)
- main (7034be9, no A8 work): A + C don't reproduce, BUT constant #78 (houses below terrain from inside)

R3's stencil work fixed #78 but introduced A + C by rendering all 16 BFS-reachable cells at full screen extent. The fix is **per-portal recursive culling** (what retail + WB both do). For acdream's stack, WB's stencil approach is closer to existing infrastructure than retail's polygon-clip scissor.

### Why full WB port (not minimum)

The user explicitly chose "full WB port now" over (a) revert all A8 and live with #78 or (b) keep R1+R2 and revert only R3+R3.5. Decision recorded in the design doc's "Brainstorm outcomes" section.

### What's in scope (per design)

- WB `RenderInsideOut` Steps 1-5 (including 3-stencil-bit cross-building visibility, Step 5)
- WB `RenderOutsideIn` (cottage interiors visible through windows from outside)
- Per-building cell association (Building + BuildingRegistry + LoadedCell.BuildingId — Option C dual-indexed per user's Q2 answer)
- Single strict `cameraInsideBuilding` gate (drop grace for render path; CellVisibility's grace stays alive for non-render consumers)
- Stencil-gated sky inside indoor branch (acdream enhancement over WB)

### What's NOT in scope

- Retail polygon-clip scissor port (multi-week alternative)
- Cell-side `BuildingId` as SOLE data source (Option B — rejected for awkward API)
- Reverting R1+R2 (kept — orthogonal infrastructure)

---

## Files state at session end

```
Branch:        claude/strange-albattani-3fc83c
HEAD:          29e306b (RR1 footer-marks)
Working tree:  clean (only untracked log files + research docs from prior sessions)
Build:         green
Tests:         within flaky window

Uncommitted predecessor docs (intentionally not committed by previous sessions):
  docs/research/2026-05-26-a8-entity-taxonomy.md
  docs/superpowers/plans/2026-05-26-phase-a8-indoor-cell-visibility-culling.md
  docs/superpowers/plans/2026-05-26-phase-a8-replan.md
  (plus several A6 / issue-78 / issue-101 / cellar saga docs)
These are not blocking — they were referenced by handoff docs that DID get
committed, so the chain works at the file-system level. If a fresh session
wants tidy git history, run a single tidy-up commit gathering these.
```

---

## Pickup prompt for fresh session

```
Phase A8 — full WB RenderInsideOut + RenderOutsideIn port. RR1 cleanup
shipped 2026-05-26 PM (commits 84c4a70 → 29e306b). Pick up at RR2 (spike).

Read first (REQUIRED, in order):
  1. docs/research/2026-05-26-a8-wb-full-port-rr1-shipped-handoff.md
     (this doc)
  2. docs/superpowers/specs/2026-05-26-phase-a8-wb-full-port-design.md
     (the approved design)
  3. docs/superpowers/plans/2026-05-26-phase-a8-wb-full-port.md
     (12-task plan; pick up at RR2)
  4. docs/research/2026-05-26-a8-rr0-falsification-findings.md
     (evidence triggering the scope expansion)
  5. references/WorldBuilder/Chorizite.OpenGLSDLBackend/Lib/VisibilityManager.cs:73-330
     (the proven reference)
  6. CLAUDE.md — "Currently working toward" line + A8 paragraph

State both altitudes:
  Currently working toward: M1.5 — Indoor world feels right
  Current phase: A8 — full WB port
  HEAD: 29e306b (RR1 footer-marks)
  Test baseline: build green; ~14-23 flaky test window (pre-existing)

Session flow:

### RR2 — spike (this session)

Per plan §RR2, 6 steps:
  S1: inspect DatReaderWriter.BuildingInfo via grep/nuget
  S2: read WB PortalRenderManager:518-551
  S3: live-inspect a Holtburg cottage's BuildingInfo (temp diagnostic in
      LandblockLoader.cs, launch, user walks to cottage, capture log,
      revert diagnostic)
  S4: write docs/research/2026-05-26-a8-buildings-data-shape.md
  S5: commit findings
  S6: gate — if data shape compatible, proceed to RR3; else re-brainstorm

Expected ~30-60 min. Single commit.

### RR3-RR12 — subsequent sessions

Subagent-driven (one fresh Sonnet subagent per code task with two-stage
review). Direct orchestration for RR8/RR10/RR12 visual gates.

## Constraints

- Per CLAUDE.md "no workarounds" rule — fix root causes. The new design
  is the proper fix; don't iterate on R3.5-style symptom patches.
- WB code under references/WorldBuilder/ is MIT-licensed and the same
  stack as acdream (Silk.NET, .NET); port verbatim where possible with
  WB line refs in comments.
- Visual verification is the acceptance test. RR8 gate must close #78
  + R4 Issues A + C BEFORE proceeding to RR9 (Step 5).
- DO NOT re-revert R1 (ed72704) + R2 (55f26f2) — they're orthogonal
  infrastructure consumed by the upcoming work.

## What success looks like

After all 12 tasks ship (~1.5-2 weeks calendar):
  - Standing inside Holtburg cottage / cellar / inn / dungeon: all walls
    solid. Sky visible through windows.
  - Exit/entry transitions clean (Issues A + C closed).
  - Cross-building visibility (Step 5) working — inn → cottage interior.
  - Cottage interiors visible from outside through windows
    (RenderOutsideIn).
  - #78 closed; #102 closed; no regression on #100.
  - M1.5 indoor scope fully shipped.
```

---

## Why pause now

The session has covered ~8 hours of brainstorm + design + plan + cleanup. Context budget is substantial. A fresh session for RR2 (the spike) lets the upcoming long stretch of RR3-RR12 implementation start with maximum context room for the subagents to consume. This is exactly the milestone-discipline rhythm CLAUDE.md describes.

Tomorrow's session opens with the pickup prompt above. The work is well-shaped: RR2 is small (≤1 hour); each of RR3-RR11 is one or two sessions of subagent-dispatched work with two-stage review; RR8 + RR10 + RR12 are visual gates that need ~30 min each of you driving the test client.

Good night. M1.5 is closer than it was this morning.