docs(#185): handoff for the outdoor-stairs phantom fix (synthetic sliding-normal, #137/TS-4 family)

docs/research/2026-07-08-185-outdoor-stairs-phantom-handoff.md

@@ -0,0 +1,158 @@
+# Handoff: #185 — LOCAL player jams half-way up outdoor stairs (house on stilts)
+
+**Date:** 2026-07-08 · **Status:** ROOT CAUSE PINNED (definitive, probe-confirmed) — fix NOT
+started. The fix touches the **frozen collision internals** (the #137 / TS-4 sliding-normal
+family), so per the project workflow it needs a **brainstorming gate BEFORE any code**. This
+handoff is the investigation; do the brainstorm + fix in the new session.
+
+**Read these first, in order:**
+1. This handoff.
+2. `claude-memory/project_physics_collision_digest.md` — the #137 banners + the DO-NOT-RETRY
+   table + the sliding-normal-provenance lessons (this is the SSOT for the collision arc).
+3. `docs/research/2026-07-06-137-sliding-normal-lifecycle-audit.md` — the #137 sliding-normal
+   lifecycle audit (persist / absorb / clear; the synthetic-normal mechanism).
+4. `docs/architecture/retail-divergence-register.md` — rows **TS-4** (steep-tangent
+   `SetSlidingNormal`), **TS-45** (retired — `SphereCollision` leak), **AP-83/84** (CSphere/
+   CylSphere family).
+5. `docs/ISSUES.md` #185 (the one-paragraph version).
+
+---
+
+## 0. Symptom
+
+Running the **LOCAL player** up the outside stairs of a house-on-stilts, you hit an invisible
+block **half-way up** — you shuffle sideways in place but cannot advance up. **A jump clears
+it** and you continue up the rest of the stairs normally. Pre-existing (seen before the #184
+work); unrelated to the remote de-overlap thread.
+
+---
+
+## 1. Root cause — DEFINITIVE (probe-confirmed): a SYNTHETIC sliding normal, not geometry
+
+The stairs are **real, walkable 38.7° tread quads** in the building collision mesh. The player
+walks straight up them. At **one convex tread edge** (near a building-part seam), the foot
+sphere straddles the edge, hits the lower tread poly, and the collision **RESPONSE fabricates a
+perpendicular normal** — the tread normal **rotated 90°** — which is then flattened to a pure
+horizontal `(0,1,0)` sliding plane. The player's +Y (up-stairs) movement is fully absorbed by
+that plane → **sideways-only slide** (pinned in Y and Z). The jump clears it because the jump's
++Z velocity is not in the horizontal slide plane.
+
+**It is NOT geometry, NOT a step-height / step-up-budget issue, NOT a missing riser.**
+
+### The evidence
+
+**A — `ACDREAM_CAPTURE_RESOLVE` (structured player-resolve JSONL).** At the jam the player is
+pinned at **Y=77.812, Z=61.404** and only slides in X (~0.10 m of the ~0.68 m requested).
+Constant across every stuck frame:
+- `collisionNormal = (0.00, 0.78, 0.62)` — a ~52° face (**NOT** the #137 negated-run-direction).
+- `slidingNormal = (0, 1, 0)` — that collision normal with **Z zeroed + renormalised** (horizontalised).
+- `contactPlane / walkablePlane = (0, -0.625, 0.781)` — the 38.7° tread the player stands on.
+- `result.collisionNormalValid=false` on the zero-move frames (the offset is pre-absorbed → target==current).
+
+**B — `ACDREAM_PROBE_BUILDING=1` (`[resolve-bldg]` hit-poly log).** The decisive read: at the
+jam, **ALL 156 building collisions are ONE polygon** — the 38.7° tread:
+```
+[resolve-bldg] obj=0xF6822103 entityId=0x00F68221 partIdx=3
+   gfxObj=0x01000AC5 hasPhys=True bspR=1.05 vAabbR=1.15
+   entOrigin_lb=(132.0,77.2,60.4)
+   hitPoly: numVerts=4 plane=(-0.625,0.000,0.781,-0.312)
+      v0_world=(132.75, 77.50, 61.01)  v1_world=(131.25, 77.50, 61.01)
+      v2_world=(131.25, 77.00, 60.62)  v3_world=(132.75, 77.00, 60.62)
+```
+- **No riser / wall polygon exists in the collision mesh** — the only distinct hit-poly plane
+  across all 156 hits is that tread.
+- Local plane `(-0.625,0,0.781)` maps (building rotation ≈ +90° about Z) to the **world tread
+  normal `(0,-0.625,0.781)`** — matching capture A's contact plane.
+- The capture's blocking normal `(0,0.78,0.62)` is that **tread normal rotated 90°**
+  (perpendicular: dot ≈ 0). It does **not** exist in the dat → **synthetic**, fabricated by the
+  collision response.
+
+### Geometry facts (for the repro / test fixture)
+- Object `0xF6822103` (entity), `entityId=0x00F68221`, `partIdx=3`; **gfxObj `0x01000AC5`**
+  (+ a neighbouring building part `gfxObj 0x01000ACA`, `obj 0xF6821201`, right at the seam).
+- Landblock `0xf682`, cell `0xF682002C`. **Login spawn `@0xF682002C` is at the house** (the
+  streaming recenters to (246,130) on spawn), so the stairs load immediately — no travel needed.
+- Jam world position ≈ **(132, 77.8, 61.4)**; the involved tread quad world verts are listed
+  above (X 131.25–132.75, Y 77.00–77.50, Z 60.62–61.01; ~0.4 m rise / 0.5 m run = 38.7°).
+- The player collides as a **body SPHERE** (human Setup 0x02000001; r≈0.48), so the relevant
+  response is the **CSphere family** (dispatcher `0x00537A80`, `slide_sphere 0x00537440`) — the
+  one the #182 port (`96ae2740`) rebuilt.
+
+---
+
+## 2. Classification + where the fix lives
+
+**#137 / TS-4 "synthetic sliding-normal at a convex edge/seam" family — stair edition.** Same
+class as the corridor-phantom work (`a11df5b8`, `e8651b38`) and the seam-shake fix
+(`d4869154`). The building geometry is fine; our slide/validate response invents the wall.
+
+**The core open question for the brainstorm:** *where does the 90°-rotated normal get
+fabricated?* Candidates (trace these):
+- `CSphere::slide_sphere` (`0x00537440`) — the crease `collisionNormal × contactPlane.Normal`
+  at a convex edge (a cross product IS a 90° rotation; the tread × something could yield the
+  perpendicular normal). **Prime suspect.**
+- `validate_transition` (`0x0050aa70`) sliding-normal epilogue (the only in-transition
+  sliding-normal writer per the #137 audit) — is it persisting a fabricated normal?
+- The step-up / neg-poly path at a convex edge (the seam-shake class — a lifted CheckPos lost,
+  re-test grazes the neighbour tread).
+- The CSphere `collide_with_point` / edge-vertex case at the tread top edge.
+
+The `(0,1,0)` horizontalisation of `(0,0.78,0.62)` (Z zeroed) is the **absorb** step — the
+player's forward offset is projected out. Find who WRITES `(0,0.78,0.62)` first.
+
+---
+
+## 3. Apparatus (reusable — RE-CAPTURE in the new session; the temp files won't persist)
+
+Repro: launch (canonical live command, CLAUDE.md), spawn `@0xF682002C`, run up the outside
+stairs, hold forward against the jam (~world 132,77.8,61.4) for a couple of seconds.
+
+- `ACDREAM_CAPTURE_RESOLVE=<path>` → per-player-resolve JSONL (inputs + PhysicsBody before/after
+  + ResolveResult, filtered to IsPlayer). Analyse: find blocked-while-moving frames
+  (`|target−cur|_xy > 0.03` but `|result−cur|_xy < 0.4×that`); read `collisionNormal`,
+  `slidingNormal`, `contactPlane`, `walkableVertices`.
+- `ACDREAM_PROBE_BUILDING=1` → `[resolve-bldg]` blocks (gfxObj, hit-poly plane + world verts).
+  **⚠️ GOTCHA:** the diagnostic Console output lands in the **raw background-task `.output`
+  file** (the process stdout captured by `run_in_background`), **NOT** the `Tee-Object` log —
+  `Tee` buffers and shows almost nothing. Grep the task `.output`. Also enables `[bsp-test]` /
+  `[bldg-channel]` (very high volume) — grep for `resolve-bldg` / `hitPoly`.
+- Optional: `ACDREAM_PROBE_RESOLVE=1` / `ACDREAM_PROBE_PUSH_BACK=1` for the step-up / push-back
+  dispatch internals if the fabrication site needs a finer trace.
+- Build a **dat-backed replay test** reproducing the tread-edge hit to the millimetre (pattern:
+  `Issue137CorridorSeamReplayTests`) — the fix's red→green pin. Dump the cell/GfxObj with
+  `ACDREAM_DUMP_GFXOBJS=0x01000AC5` (+ `_DIR`) for the fixture.
+
+---
+
+## 4. DO-NOT-RETRY
+
+- **Do NOT touch the step-up budget or step-up logic.** There is no riser here — it's a
+  continuous walkable 38.7° ramp of tread quads; the jam is a fabricated normal, not a tall
+  step. (The register/digest already warned: stair sticks are the sliding-normal family; six
+  past step-up attempts were all wrong.)
+- **Do NOT "fix the geometry" / mesh generation.** All 156 building hits are ONE real, walkable
+  tread poly; the dat is fine. There is no bad 52° face to remove.
+- **Do NOT read the Tee'd launch log for `[resolve-bldg]`** — it's buffered/empty; read the raw
+  task `.output` (§3 gotcha).
+- **Do NOT ship a per-frame sliding-normal clear or a small-offset-abort patch** (the #137
+  DO-NOT-RETRY): fix the normal's PROVENANCE, not the symptom. A leaked/fabricated normal +
+  success writeback = an absorbing wedge at empty space — the exact pattern the corridor fix
+  addressed by routing through the faithful `SlideSphere` and returning COLLIDED on the
+  opposing branch.
+
+---
+
+## 5. Acceptance
+- The LOCAL player **walks up the full outdoor staircase without jamming or jumping**; no
+  sideways-slide pin at the ~Y 77.5 / Z 61.0 tread edge.
+- **Regression pass** (the whole point — this is the shared slide response): indoor cellar/
+  corridor stairs (#137 repros), other outdoor buildings, ramps, and flat ground — **no new
+  phantom blocks AND no players sliding through walkable ramps/edges.** Un-skip / keep green the
+  `Issue137*` replay suites.
+- Register bookkeeping in the fix commit (amend TS-4 / add a row as the change dictates).
+
+## 6. Pointers
+- ISSUES `#185`; committed root cause `99c22fad` (+ filing `29e01c38`).
+- Collision digest DO-NOT-RETRY table + the #137 corridor/​seam banners.
+- Register TS-4 / TS-45 / AP-83 / AP-84; #137 fixes `a11df5b8`, `e8651b38`, `d4869154`;
+  CSphere port `96ae2740`.