acdream/docs/research/2026-05-21-open-items-pickup-prompt.md

# Open items pickup prompt — 2026-05-21 session aftermath

After the 2026-05-21 collision-fix session, six discrete items remain.
This doc gives a fresh session the full landscape: how the items
relate, what depends on what, what order makes sense.

The pasteable session-start prompt is at the bottom of this doc.

## The landscape at a glance (updated 2026-05-20)

| # | Item | Domain | Depends on | M2-blocker? |
|---|---|---|---|:---:|
| **#90 ping-pong** | **NEW TOP BLOCKER** — CellId flips between outdoor `0xA9B40022` and indoor vestibule `0xA9B40164` on each wall push-back at the inn doorway; user perceives "walls walk through everywhere" | Collision — cell tracking | — | **YES** (M2) |
| A4 | ~~Walls walk-through in vestibule cells — multi-cell BSP iteration~~ | Collision | — | **CLOSED 2026-05-20** (shipped, but dormant in practice until #90 is fixed) |
| stairs | Stairs walk-through — likely same root cause as #90 (also a doorway-edge geometry issue) | Collision | #90 | YES (likely subsumed by #90) |
| A2 | PHSP inversion — `polygon_hits_sphere` early-return logically inverted vs retail | Collision math | — | Low (subtle correctness only) |
| A3 | Synthesis removal — delete `TryFindIndoorWalkablePlane`, rely on retail CP retention | Architectural | A4 + #90 + A2 | No (cleanup, retail-faithful) |
| L-indoor | Lighting indoors broken | Rendering | — | No (M7 polish) |
| L-spotlight | Items projecting spotlight on walls | Rendering | — | No (M7 polish) |

## Two domains, one critical-path chain

The 6 items split cleanly:

**Domain 1 — Collision (M2 critical path).** A4, stairs, A2, A3.
These block "kill a drudge" because dungeons have drudges and dungeons
have walls/stairs/floors that need to behave correctly. The dependency
chain is:

```
                  A4 (multi-cell iteration)
                       │
            ┌──────────┴──────────┐
            ▼                     ▼
        stairs (verify          A3 (remove
        post-A4)                synthesis,
                                relies on
                                A4 retention)
                                     ▲
                                     │
                                 A2 (PHSP fix
                                 — also useful
                                 standalone)
```

A4 is the biggest user-visible win and it unblocks A3. A2 is a small
self-contained correctness fix that pairs naturally with A3. Stairs
are likely an A4 side-effect.

**Domain 2 — Rendering (M7 polish).** L-indoor + L-spotlight. These
don't affect gameplay correctness — the world just looks wrong.
Different code paths (lighting, not physics), different files,
different domain knowledge. Best tackled in their own session,
ideally after collision is solid so the visual artifacts are easier
to isolate.

## Why this order

1. **A4 first.** Biggest user-visible improvement. Closes the
   "vestibule cells don't block walls" gap by querying every cell
   the sphere overlaps, not just the one cell the player's center
   is in. Retail oracle: `CTransition::check_other_cells` at
   `acclient_2013_pseudo_c.txt:272717-272798`. Existing
   `CellTransit.FindCellList` already enumerates the right cells;
   A4 wires that into `FindEnvCollisions`. Probably 1-2 days.

2. **Verify stairs after A4.** If A4 closes vestibule walls, it
   probably also closes stairs (same architectural gap — stairs
   span cells). If stairs still walk-through after A4, investigate
   per-cell physics-poly coverage for stair geometry as a separate
   sub-issue.

3. **A2.** One-line flip in `PolygonHitsSpherePrecise`
   ([BSPQuery.cs:117](src/AcDream.Core/Physics/BSPQuery.cs:117)) plus
   a unit test for the tangent boundary. Improves correctness across
   every BSP query (walls, step-up, step-down). Pairs cleanly with A3.

4. **A3.** Once A4 + A2 land, the architectural cleanup becomes safe.
   Delete `TryFindIndoorWalkablePlane` (TransitionTypes.cs:1294) and
   the synthesis call site. Retail's grounded path doesn't synthesize
   CP — it retains via Mechanisms A/B/C (already in our code at
   BSPQuery.cs:1615, TransitionTypes.cs:2618, TransitionTypes.cs:896).
   The 2026-05-20 session tried A3 prematurely (Bug A) and reverted
   because the doorway-exit case relied on multi-cell iteration that
   wasn't there. A4 closes that gap.

5. **Lighting (M7).** Separate session. Different domain. Defer until
   M2 ships.

## Per-item starter notes

### A4 — multi-cell BSP iteration

**Read first:**
- §"Phase A4" of `docs/research/2026-05-21-collision-fixes-shipped-handoff.md`
- `acclient_2013_pseudo_c.txt:272717-272798` (`check_other_cells`)
- [`src/AcDream.Core/Physics/TransitionTypes.cs:1407-1559`](src/AcDream.Core/Physics/TransitionTypes.cs:1407) (`FindEnvCollisions` — change site)
- [`src/AcDream.Core/Physics/CellTransit.cs`](src/AcDream.Core/Physics/CellTransit.cs) (helpers already exist)

**Approach:**
- Extract a "cell_array" set from the player's current cell via the
  existing CellTransit BFS.
- Iterate each cell, run `BSPQuery.FindCollisions` against each one.
- Combine results: any cell returning Collided/Adjusted halts; any
  cell returning Slid is remembered; all OK = return OK.

**Acceptance:** Walk into the Holtburg inn vestibule (cell `0xA9B40164`).
Walls in cell `0xA9B40157` should now block when the player's sphere
extends into them, even though the player's center is still in the
vestibule.

### Stairs walk-through

**Strategy:** verification-only, after A4. Launch with the same probe
set, walk up the inn stairs, watch the `[indoor-bsp]` results. If
stair hits fire correctly, done. If not, investigate the cell's
physics-poly data — stairs may be packed as static objects rather
than cell-structure polys.

### A2 — PHSP inversion fix

**Bug:** [`BSPQuery.cs:117`](src/AcDream.Core/Physics/BSPQuery.cs:117)
has `if (MathF.Abs(dist) > rad) return false;` — bails when sphere
is FAR from plane. Retail's `polygon_hits_sphere_slow_but_sure` at
`acclient_2013_pseudo_c.txt:322509-322517` does the opposite — bails
when sphere is OVERLAPPING plane.

**Fix:** flip the comparison. New unit test for the tangent boundary
(sphere center at `radius` distance from plane → continue, not
reject).

**Caveat:** doesn't fix walkable synthesis on its own —
`AdjustSphereToPlane` also rejects at the tangent boundary (strict
`<` check on interp). The two together gate the synthesis. Fixing A2
alone changes which side of the boundary the rejection happens on
but doesn't close the gap. Pair with A3 for the full benefit.

**Read first:**
- §"Phase A2" of `docs/research/2026-05-21-collision-fixes-shipped-handoff.md`
- `docs/research/2026-05-21-walk-miss-capture-findings.md` (the
  smoking-gun analysis of the 2 cm boundary)

### A3 — synthesis removal

**Bug:** retail's grounded path doesn't re-synthesize ContactPlane.
It retains via three mechanisms (Path 4 land, LKCP proximity restore,
post-OK step-down probe — all already in our code). Our
`TryFindIndoorWalkablePlane` runs every frame and is unfaithful.

**Fix:** delete `TryFindIndoorWalkablePlane` ([TransitionTypes.cs:1294](src/AcDream.Core/Physics/TransitionTypes.cs:1294))
and its call site. ~500 lines deleted.

**Critical prerequisite:** A4 must ship first. The 2026-05-20 session
tried A3 prematurely (Bug A) and reverted because doorway transitions
caused free-fall — Mechanism C couldn't find a floor poly at the
threshold because the indoor cell's BSP had no coverage past the
doorway, and multi-cell iteration wasn't there to query the adjacent
cell.

**Read first:**
- `docs/research/2026-05-20-indoor-walking-bug-a-handoff.md`
  (Bug A's premise + reversion)
- §"Phase A3" of the 2026-05-21 handoff

### L-indoor — lighting broken inside

**Symptom:** lights inside buildings don't illuminate correctly.

**Likely areas:**
- Cell-light association (which lights belong to which cell)
- Light visibility culling (visible-cells set + light bounds)
- Per-light projection matrix indoors

**Domain:** rendering, not physics. Separate session.

### L-spotlight — items projecting spotlight on walls

**Symptom:** held items (torches, etc.) project spotlight effects
onto walls in unexpected directions.

**Likely areas:**
- Per-entity light direction transform
- LightingHookSink owner-tracking

**Domain:** rendering, not physics. Separate session.

## CLAUDE.md rules to remember

1. **Work-order autonomy.** You pick what to work on. Recommended
   order above but adjust if you find something blocking.
2. **No workarounds, retail-faithful.** Same rule that drove A1
   through A1.7. If a fix starts to look like a band-aid, stop.
3. **Probe-first, design-second.** Already have rich probes
   (`[indoor-bsp]`, `[cell-transit]`, `[cell-cache]`,
   `[walk-miss]`, `[floor-polys]`, `[resolve-bldg]`). Capture before
   theorizing.
4. **Visual verification is the acceptance test.** Walk the building
   after each fix.
5. **Stop signals.** Three failed visual verifications in a session =
   write a handoff, don't push for a fourth.
6. **Don't enable `ACDREAM_PROBE_RESOLVE` for live play.** It lagged
   the client last session (400k+ lines at 30 Hz).
7. **Subagent policy: Sonnet for implementers, Opus only for
   load-bearing review.**
8. **Worktrees.** Use the `superpowers:using-git-worktrees` skill to
   create a fresh worktree branched from main before touching code.

## Launch command (light probes only)

```powershell
$env:ACDREAM_DAT_DIR              = "$env:USERPROFILE\Documents\Asheron's Call"
$env:ACDREAM_LIVE                 = "1"
$env:ACDREAM_TEST_HOST            = "127.0.0.1"
$env:ACDREAM_TEST_PORT            = "9000"
$env:ACDREAM_TEST_USER            = "testaccount"
$env:ACDREAM_TEST_PASS            = "testpassword"
$env:ACDREAM_DEVTOOLS             = "1"
$env:ACDREAM_PROBE_INDOOR_BSP     = "1"
$env:ACDREAM_PROBE_CELL           = "1"
$env:ACDREAM_PROBE_CELL_CACHE     = "1"
dotnet build -c Debug
dotnet run --project src\AcDream.App\AcDream.App.csproj --no-build -c Debug 2>&1 |
    Tee-Object -FilePath "launch.log"
```

UTF-16LE → UTF-8 conversion for grep:

```powershell
Get-Content launch.log -Encoding Unicode |
    Out-File launch.utf8.log -Encoding utf8
```

---

## The pasteable session-start prompt

Open a new Claude Code session in the main acdream worktree
(`C:\Users\erikn\source\repos\acdream`, branch `main` at SHA
`f80b537` or later). Then paste:

---

```
Pick up the acdream open-items cleanup. After the 2026-05-21 session,
6 items remain across collision + rendering.

1. Read docs/research/2026-05-21-open-items-pickup-prompt.md FIRST.
   It maps the 6 items, their dependencies, and the recommended
   order (A4 → verify-stairs → A2 → A3 → lighting in a separate
   session). Each item has its own "Read first" anchor list inside.

2. Branch state: main is at f80b537 with all 2026-05-21 fixes
   landed (A1, A1.5, A1.6, A1.7 + probe spike + handoff docs).
   Build green, 1129-test baseline holds, four user-visible
   improvements visually verified. Local main is ahead of
   origin/main (origin at 7034be9); push only if explicitly asked.

3. **Set up isolation FIRST.** Use the superpowers:using-git-worktrees
   skill to create a fresh worktree from main. Don't work directly
   in the parent worktree. The 2026-05-21 session's worktree
   (claude/lucid-goldberg-1ba520) is identical to main and can be
   removed.

4. Recommended first phase: **A4 (multi-cell BSP iteration)**. It
   has the biggest user-visible payoff (closes vestibule-cell wall
   walk-through, likely closes stairs too) and unblocks A3
   architectural cleanup. Retail oracle is at
   acclient_2013_pseudo_c.txt:272717-272798 (CTransition::check_other_cells).
   Existing CellTransit helpers (FindCellList, FindTransitCellsSphere,
   AddAllOutsideCells) already enumerate the right cells; A4's
   work is wiring them into Transition.FindEnvCollisions.

5. Use the superpowers:brainstorming skill before writing A4 code.
   A4 is a real architectural change (multi-day, 2 files modified +
   tests) and deserves its own spec + plan. Don't shortcut it.

6. CLAUDE.md rules:
   - No workarounds. Retail-faithful.
   - Probe-first, design-second.
   - Visual verification at Holtburg inn cell 0xA9B40164 vestibule
     is the A4 acceptance test (walls in adjacent cell 0xA9B40157
     should block when the player straddles the boundary).
   - Don't enable ACDREAM_PROBE_RESOLVE for live play (lags the
     client). Use [indoor-bsp] + [cell-transit] + [cell-cache] only.
   - Three failed visual verifications = handoff, not a fourth attempt.

7. M2 ("kill a drudge") is the active milestone. A4 + stair
   verification + A2 + A3 are all on the M2 critical path because
   dungeons need walkable indoor space. Lighting is M7 polish;
   defer.

8. Launch command (light probes only):
   $env:ACDREAM_DAT_DIR              = "$env:USERPROFILE\Documents\Asheron's Call"
   $env:ACDREAM_LIVE                 = "1"
   $env:ACDREAM_TEST_HOST            = "127.0.0.1"
   $env:ACDREAM_TEST_PORT            = "9000"
   $env:ACDREAM_TEST_USER            = "testaccount"
   $env:ACDREAM_TEST_PASS            = "testpassword"
   $env:ACDREAM_DEVTOOLS             = "1"
   $env:ACDREAM_PROBE_INDOOR_BSP     = "1"
   $env:ACDREAM_PROBE_CELL           = "1"
   $env:ACDREAM_PROBE_CELL_CACHE     = "1"
   dotnet build -c Debug
   dotnet run --project src\AcDream.App\AcDream.App.csproj --no-build -c Debug 2>&1 |
       Tee-Object -FilePath "launch.log"

State the milestone + chosen phase in your first action.
```