# A6.P3 handoff — 2026-05-22

**Status:** A6.P3 slices 1+2+3 SHIPPED. Issue #98 (cellar ascent stuck at top) **diagnosed but NOT fixed.** Sharp Path-5-vs-Path-6 BSP path-selection target identified with paired retail+acdream cdb evidence. Next session: fix #98 at `BSPQuery.FindCollisions` path-selection.

**Pasteable session-start prompt at the bottom of this doc.**

---

## TL;DR

Two full days of A6 work landed:

| Day | Slice | Result |
|---|---|---|
| 2026-05-21 | A6.P1 + A6.P2 + A6.P3 slice 1 (CP retention strip + Mechanism B) | Stairs + cellar descent work in acdream. A6.P2 Finding 1 (dispatcher freq) closed as side-effect of Finding 2 (CP-write blowup). |
| 2026-05-22 morning | A6.P3 slice 2 (L622 seed; v1 reverted; v2 no-op guard) | #96 partially addressed; accepted as documented retail divergence. |
| 2026-05-22 morning | A6.P3 slice 3 (cell-resolver stickiness; v1/v2/v3) | Cell-resolver ping-pong CLOSED. #90 workaround now redundant (defer A6.P4 removal). |
| 2026-05-22 noon | Slice 4 polydump probe + retail cdb capture | **Pinpointed #98 root cause:** our BSP picks Path 5 (Contact→step_up→adjust_sphere push-back) for the cellar ramp polygon when retail picks Path 6 (find_walkable → land on flat floor). |

**User-visible deltas vs Wed morning baseline (2026-05-20):**
- ✅ Inn stairs UP — works (was broken)
- ✅ Cellar descent — works (was broken)
- ✅ 2nd floor walking — works (was broken; with caveats — phantom collisions occasionally)
- ❌ Cellar ASCENT (stuck at top step) — still broken (this is issue #98)
- ❌ Visible-through-walls in dungeons — issue #95 (separate scope)
- ❌ Indoor lighting — A7 scope (separate phase)

## What shipped this session (2026-05-22)

| Commit | What |
|---|---|
| `892019b` | A6.P3 slice 2 v1: removed L622 per-tick CP seed (CP-write 91% reduction BUT broke BSP step_up at last step of stairs) |
| `f8d669b` | A6.P3 slice 2 v2: revert v1 + add no-op-if-unchanged guard inside `CollisionInfo.SetContactPlane` |
| `d868946` | Slice 2 ship docs + filed issue #98 (cellar ascent stuck — originally hypothesized as cell-resolver ping-pong) |
| `8898166` | A6.P3 slice 3 v1: sphere-overlap stickiness in `ResolveCellId` (over-corrected; blocked legitimate cell transitions) |
| `3e140cf` | A6.P3 slice 3 v2: switched to point-in stickiness — cell-resolver ping-pong CLOSED (data confirmed: 1 cell-transit event vs 20+ pre-fix) |
| `ceeb06b` | Slice 3 ship docs + #98 re-diagnosed (cellar-up symptom persists with NEW cause — BSP step-physics, not cell-resolver) |
| `0b44996` | Slice 4: added `[poly-dump]` probe in `AdjustSphereToPlane` — verifies dat fidelity by dumping polygon vertices+plane+sidesType on every push-back |
| `3198472` | Extended `[cell-cache]` probe with `portalTargets` list — shows which cells each portal connects to |
| `8bd3117` | A6.P3 slice 3 v3: REVERTED stickiness entirely (hypothesis-test for #98) — cellar-up symptom persists |
| `bbd1df4` | Slice 4: WalkInterp reset before placement_insert in DoStepDown (retail-faithful improvement; didn't fix #98 but kept as quality fix) |
| `134c9b8` | **Retail cellar-up cdb capture** — paired evidence for the Path-5 vs Path-6 diagnosis |
| `efb5f2c` | Issue #98 updated with sharpened diagnosis + failed-attempt log |

## The sharp diagnosis for issue #98

**Symptom:** User walks UP the Holtburg cottage cellar in acdream. Runs into "an invisible roof or wall" at the top step. Animation plays but no Z progress. Stuck.

**Paired evidence:**

| Metric | Retail (success) | Acdream (stuck) |
|---|---:|---:|
| BP1 transitional_insert | 2,651 | (no acdream BP1 mirror) |
| BP2 step_up | 29 (incl. 1 on ramp slope) | — |
| BP4 find_collisions | 4,032 | push-back-disp ~9000 |
| BP5 adjust_sphere | **30 (ALL on FLAT planes)** | **push-back ~1000 (270 on RAMP slope poly 0x0008)** |
| BP6 check_walkable | 25 | indoor-walkable ~700 |
| BP7 set_contact_plane | **18 (all set same flat plane: (0,0,1) d=-93.9998 = world Z=94 = cottage main floor)** | cp-write 229,300 (varying planes from many sites) |
| step_up_slide | (via BP2 = 29) | 159+ hits |

**The divergence (pinpointed):**

For the cellar ramp polygon (cellar cell 0xA9B40147, poly 0x0008, n=(0,-0.719,0.695), 46° walkable slope):

- **Retail's BSP picks Path 6 (find_walkable → land)** — treats the ramp as a walkable floor. Smoothly LANDS the sphere on the ramp surface during step_down probe. Sets ContactPlane to the cottage main floor (flat plane at world Z=94 — the END goal of the ascent).

- **Acdream's BSP picks Path 5 (Contact → step_sphere_up → adjust_sphere push-back)** — treats the ramp as a wall to push off. The push-back lifts the sphere by 0.75m and consumes all walk-interp. step_up's placement_insert then fails (the lifted position doesn't validate). step_up returns failure → step_up_slide fires → sphere slides along step_up_normal → loop. Player physically stuck.

**Both retail and ours classify the ramp as walkable** (N.Z=0.695 > FloorZ=0.6642). So the divergence isn't in the walkability check itself. It's in the **path-selection logic** inside `BSPQuery.FindCollisions` that decides whether to fire Path 5 vs Path 6 for a given polygon hit.

**Code anchors for the next session:**
- `src/AcDream.Core/Physics/BSPQuery.cs` — `FindCollisions` dispatcher. Search for "Path 5" + "Path 6" comments. The path selection branches on `ObjectInfo.State` (Contact flag) + `SpherePath.StepDown` + `SpherePath.StepUp`.
- The grounded player has Contact flag set (per `PhysicsEngine.cs:597-598`). So Path 5 fires first. Path 5 calls step_sphere_up → step_up → step_down (with step_up=1) → recursive BSP query.
- The recursive BSP query (with StepDown=1, StepUp=1) should fire Path 6 — but maybe doesn't, OR fires Path 6 but Path 6's adjust_sphere on the ramp is what produces the broken push-back.
- Retail's BSP behavior at the same site: step_up fires (BP2 hits), but adjust_sphere only fires on FLAT planes (BP5 all flat). So retail's step_down inside step_up doesn't push the sphere off the ramp slope.

## Why the failed attempts today didn't land

| Attempt | What we tried | Why it didn't fix #98 |
|---|---|---|
| Slice 2 v1 (`892019b`) — remove L622 seed | Eliminate the per-tick CP seed | The seed is load-bearing for step_up's AdjustOffset slope-projection on sub-step 1; removed it → all step_up broke |
| Slice 2 v2 (`f8d669b`) — no-op guard in SetContactPlane | Make redundant CP writes a true no-op | Guard doesn't fire for the L622 seed because each tick gets a fresh `Transition` (ci.ContactPlaneValid=false on entry); useful for OTHER call sites but not the seed |
| Slice 3 v1 (`8898166`) — sphere-overlap stickiness | Stop cell-resolver ping-pong | Over-corrected: held player in cellar even during legitimate transition; cellar-up still stuck |
| Slice 3 v2 (`3e140cf`) — point-in stickiness | Less aggressive stickiness | CLOSED the ping-pong (data confirmed: 1 cell-transit vs 20+) but cellar-up still stuck — bug isn't cell-resolver |
| Slice 3 v3 (`8bd3117`) — revert all stickiness | Hypothesis test: prove cell-resolver isn't the bug | Confirmed — cellar-up still stuck even without stickiness |
| Slice 4 (`bbd1df4`) — reset WalkInterp before placement_insert | Match retail's walk_interp=1 reset pattern | Logical retail-faithful improvement but doesn't unblock cellar-up; kept in tree as quality fix |

**Common pattern:** I was guessing fixes at higher levels (cell resolution, CP retention, walk_interp) when the actual bug is deeper in BSP path-selection. The paired retail cdb capture finally pinpointed the divergence.

## State of the four A6.P2 findings

| Finding | Status as of 2026-05-22 EOS |
|---|---|
| Finding 1 — dispatcher entry frequency mismatch | CLOSED (as side-effect of slice 1 Finding 2 fix) |
| Finding 2 — ContactPlane resynthesis blowup | PARTIALLY CLOSED (slice 1 stripped synthesis; slice 2 v2 added no-op guard; L622 seed retained as documented retail divergence per #96) |
| Finding 3 — Indoor cell-resolver instability | CLOSED (slice 3 v2 point-in stickiness; ping-pong fully eliminated per data) |
| Finding 4 — Portal-graph visibility blowup | OPEN as issue #95 (not A6 scope) |

## Known open issues touched by A6 work

| Issue | Status |
|---|---|
| #83 — Indoor multi-Z walking broken | Cellars + 2nd floor walking works; cellar-up still blocked by #98 |
| #88 — Indoor static objects vibrate | Unchanged (deferred; hypothesis: closes with Finding 2 family) |
| #90 — CellId ping-pong workaround | Now REDUNDANT after slice 3 v2; defer A6.P4 removal |
| #95 — Portal-graph visibility blowup | OPEN (not A6 scope) |
| #96 — L622 per-tick CP seed | PARTIALLY ADDRESSED, accepted as documented retail divergence |
| #97 — Phantom collisions + fall-through on 2nd floor | OPEN (not re-tested post-slice-3-revert; hypothesis: same Path-5/Path-6 family as #98) |
| #98 — Cellar ascent stuck at top step | OPEN — **sharp Path-5-vs-Path-6 diagnosis ready for next session** |

## Test suite status

1148 pass + 8 pre-existing fail (baseline maintained throughout the session).

## Next session — concrete starting steps

**Goal:** Fix #98 (cellar ascent stuck at top step) by correcting `BSPQuery.FindCollisions` path-selection so the cellar ramp triggers Path 6 (find_walkable land) instead of Path 5 (Contact step_up push-back).

**Approach:**

1. **Read retail's `BSPTREE::find_collisions` dispatcher** at `acclient_2013_pseudo_c.txt` (search for `BSPTREE::find_collisions`). Note exactly which path it picks for a grounded mover hitting a walkable slope. The 6-path dispatcher is at line ~322984 (where BP4 sits).

2. **Read our `BSPQuery.FindCollisions`** at `src/AcDream.Core/Physics/BSPQuery.cs:1500+`. Identify the path-selection branch that decides Path 5 vs Path 6 for the input `(grounded=true, step_down=false, step_up=false, polygon.N.Z=0.695)` case.

3. **Compare line-by-line.** Likely candidates for the divergence:
    - Wrong state flag check (e.g. checking Contact when retail checks something else)
    - Wrong walkability gate (e.g. requiring N.Z >= LandingZ when retail requires >= FloorZ)
    - Wrong polygon-sidedness check (one-sided poly being treated as two-sided or vice versa)
    - Off-by-one in path numbering (Path 5 vs Path 6 swapped in our port)

4. **Fix surgically + verify via re-capture.** Re-run the cellar-up scenario in acdream with `ACDREAM_PROBE_POLY_DUMP=1`. Compare the post-fix `[push-back]` distribution against retail's BP5 distribution from `134c9b8` capture. Target: zero push-back hits on the ramp slope; CP set to flat cottage floor (matching retail).

5. **If the fix lands cleanly:** also re-test #97 (phantom collisions + fall-through on 2nd floor — likely closes as side-effect because it's the same family).

**Files almost certainly touched by the fix:**
- `src/AcDream.Core/Physics/BSPQuery.cs` — path-selection in `FindCollisions`
- Possibly `src/AcDream.Core/Physics/PhysicsGlobals.cs` (LandingZ vs FloorZ threshold mismatch)

**Files that DON'T need changing** (already correct per today's investigation):
- `PhysicsEngine.cs` ResolveCellId (cell-resolver works post-slice-3)
- `PhysicsEngine.cs` L622 seed (retail divergence accepted)
- `TransitionTypes.cs` ValidateTransition (Mechanism B works)
- `TransitionTypes.cs` FindEnvCollisions indoor branch (slice 1 strip is correct)

## Captures available for the next session

| Capture | What it shows |
|---|---|
| `docs/research/2026-05-21-a6-captures/scen4_cottage_cellar_polydump/acdream.log` | Acdream stuck-at-cellar trace with `[poly-dump]` lines showing the ramp polygon vertices |
| `docs/research/2026-05-21-a6-captures/scen4_cottage_cellar_portaldump/acdream.log` | Same cellar with `[cell-cache] portalTargets=...` showing the cellar's portals to 0x0146 + 0x0148 |
| `docs/research/2026-05-21-a6-captures/scen4_cottage_cellar_retail_for_issue98/retail.{log,decoded.log}` | **Retail's successful cellar-up cdb trace — the gold-standard comparison data** |
| `docs/research/2026-05-21-a6-captures/scen4_cottage_cellar_slice3v2/acdream.log` | Pre-slice-3-revert cell-transit pattern (closed ping-pong, point-in stickiness) |
| `docs/research/2026-05-21-a6-captures/scen4_cottage_cellar_slice3v3_revert/acdream.log` | Post-slice-3-revert (no stickiness) — cellar-up still stuck → confirms cell-resolver isn't the bug |

## Pickup prompt for fresh session

Open a new Claude Code session at this worktree's branch
(`claude/strange-albattani-3fc83c`, HEAD at `efb5f2c`). Then paste:

---

```
Pick up A6.P3 — fix issue #98 (cellar ascent stuck at top step).

Read FIRST:
  docs/research/2026-05-22-a6-p3-handoff.md
  docs/ISSUES.md issue #98 entry (sharp diagnosis section)

Then state both altitudes:
  Currently working toward: M1.5 — Indoor world feels right
  Current phase: A6.P3 — fix issue #98 BSP path-selection
  Next concrete step: read retail's BSPTREE::find_collisions
  dispatcher (acclient_2013_pseudo_c.txt) + our BSPQuery.FindCollisions
  side-by-side; identify why our code picks Path 5 (Contact step_up)
  for the cellar ramp polygon when retail picks Path 6 (find_walkable
  land). The ramp is walkable (N.Z=0.695 > FloorZ=0.6642) so Path 6 is
  the correct choice for both clients.

Sharp diagnosis (from paired cdb captures committed 2026-05-22):
  - Retail's adjust_sphere fires 30x ALL on flat planes (Z=94 cottage main floor)
  - Acdream's push-back fires 270x on the RAMP slope (cellar 0xA9B40147 poly 0x0008)
  - Retail's BP7 set_contact_plane fires 18x with the SAME flat plane
  - Acdream cp-write fires 229,300x with varying planes from many sites

Captures available for comparison:
  - docs/research/2026-05-21-a6-captures/scen4_cottage_cellar_retail_for_issue98/
    (retail cellar-up cdb trace — gold-standard data)
  - docs/research/2026-05-21-a6-captures/scen4_cottage_cellar_polydump/
    (acdream stuck-at-cellar with [poly-dump] lines)

DO NOT re-attempt the failed fixes from 2026-05-22 (handoff doc has
the full list with reasons each one didn't land). Specifically:
  - Don't try removing the L622 seed (breaks step_up)
  - Don't try removing slice-3 stickiness (already reverted; didn't help #98)
  - Don't try cell-resolver fixes (Finding 3 is closed)

Fix expected in BSPQuery.cs path-selection (the dispatcher branch
that decides Path 5 vs Path 6 for grounded movers hitting walkable
polys). Likely 5-20 lines of code change once the divergence is found.

After fix lands: re-capture scen4_cottage_cellar with the same probe
env vars to verify acdream now matches retail's flat-plane BP7
pattern. Also re-test #97 (phantom collisions + fall-through on 2nd
floor — hypothesized to close as side-effect of #98 fix).

Test suite baseline: 1148 pass + 8 pre-existing fail. Maintain through
the fix.

CLAUDE.md rules apply. No workarounds without explicit user approval.
Three failed visual verifications = handoff (we hit this 4x on the
2026-05-22 session — discipline check before attempting another guess
fix).
```

---

## References

- A6 design spec: [`docs/superpowers/specs/2026-05-21-phase-a6-indoor-physics-fidelity-design.md`](../superpowers/specs/2026-05-21-phase-a6-indoor-physics-fidelity-design.md)
- A6.P2 findings doc: [`docs/research/2026-05-21-a6-cdb-capture-findings.md`](2026-05-21-a6-cdb-capture-findings.md)
- A6.P1 partial-ship handoff (yesterday): [`docs/research/2026-05-21-a6-p1-partial-ship-handoff.md`](2026-05-21-a6-p1-partial-ship-handoff.md)
- ISSUES.md #98 entry (sharp diagnosis section)
- cdb probe + decoder: `tools/cdb/a6-probe.cdb`, `tools/cdb/decode_retail_hex.py`