erik/acdream
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 1

docs(handoff): Phase A8 RR1 shipped — pickup prompt for RR2 spike

Browse source 
Session-end handoff capturing:
- RR0 findings + design + plan + RR1 cleanup all shipped (8 commits)
- Working tree at logical R2-baseline + [vis] probe
- RR2 (BuildingInfo spike) is next; ~30-60 min; human-in-the-loop step
  for live-inspect
- Canonical doc-read order for fresh session
- Pickup prompt with state-both-altitudes header

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Erik 2026-05-27 10:46:32 +02:00
parent 29e306b0f6
commit a5d2244467
1 changed files with 250 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

250
docs/research/2026-05-26-a8-wb-full-port-rr1-shipped-handoff.md Normal file
View file

@ -0,0 +1,250 @@
# 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.