acdream/docs/superpowers/specs/2026-07-08-185-outdoor-stairs-fix-design.md

Design: #185 — local player jams half-way up outdoor stairs (fix)

Date: 2026-07-08 · Status: DESIGN (approved approach: A) — implementation not started Milestone: M1.5 (indoor world feels right) · Family: #137 / TS-4 synthetic-sliding-normal at a walkable seam, stair edition Investigation handoff: docs/research/2026-07-08-185-outdoor-stairs-phantom-handoff.md Decomp cross-check workflow: wf_3c1120c4-a04 (5 tracers + 3 adversarial verifiers, all high-confidence)

---

1. Symptom

Running the LOCAL player up the outside stairs of a house-on-stilts, you hit an invisible block part-way up: you shuffle sideways but cannot advance. A jump clears it and you continue up normally. Pre-existing; unrelated to #184. Jam at world ≈ (132, 77.9, 61.5), landblock 0xf682, cell 0xF682002C.

2. Root cause — CONFIRMED (decomp cross-check + live apparatus)

2.1 The geometry (dumped this session)

The staircase is a continuous, coplanar 38.7° ramp built from stacked multi-part step-box objects (entityId 0x00F68220, 0x00F68221, 0x00F68222, …; each holds 3 step parts; gfxObj 0x01000AC5 = one step-box, 0x01000ACA = a sibling variant). Every step's tread (poly id 4, local plane (-0.625,0,0.781), world (0,-0.625,0.781)) lies on the same infinite plane — verified: adjacent treads share both normal AND plane-d, so they are genuinely coplanar, forming one continuous ramp. The tread quads abut at 0.5 m seams in world Y, and those seams fall on object boundaries (the objects interleave; e.g. 0xF68222 part-3 at Y≈76.49 abuts 0xF68221 part-1 at Y≈76.50). gfxobj dumps: …/scratchpad/gfxdump/0x01000AC5.gfxobj.json, 0x01000ACA.gfxobj.json.

2.2 The mechanism (live capture 185-recapture.jsonl + [step-walk] / [stepdown-decide])

Walking up, acdream re-grounds every frame via the step-down-to-maintain-contact recovery (DoStepDown, TransitionTypes.cs:1339). This succeeds at most positions (accept=True climbing to Y=77.914). At one seam it fails, and the fabrication chain runs:

1. The grounded forward move floats the foot past the current tread's polygon (kept "grounded" on the tread plane via the LastKnownContactPlane proximity restore) to Y=78.12, Z=61.65 — but the forward TransitionalInsert reaches the step-down dispatch with ci.ContactPlaneValid = false (the seed from body.ContactPlane is lost mid-sweep; pinning why is implementation step 1, §3). Note: ValidateTransition's LKCP proximity restore later re-validates it, so bodyAfter.contactPlaneValid = true in the capture even though the mover is wedged — the loss is transient-but-decisive, at the dispatch, not at frame end.
2. Because contact is invalid at the dispatch, the step-down branch fires. DoStepDown first drops the sphere the full stepDownHeight (Z 61.65 → 60.90) then sweeps find_walkable downward — but the continuation tread is coplanar (at the foot's level), now above the dropped sphere → nothing found → [stepdown-decide] accept=False (340× in the run).
3. DoStepDown fails → EdgeSlideAfterStepDownFailed → branch3 (TransitionTypes.cs:1516) → PrecipiceSlide → FindCrossedEdge returns cross(tread_normal, top_edge) = (0,±0.78,±0.62) → SlideSphere sets it as CollisionNormal.
4. ValidateTransition (:4635) → SetSlidingNormal zeroes Z → (0,±1,0).
5. Body persists it (PhysicsEngine.cs:1136); next frame seeds it (:1020); AdjustOffset absorbs the +Y up-stairs offset → sideways-only wedge, pinned at Y=77.914. Self-sustaining (seed→absorb→step-0-abort), with a fresh (0,0.78,0.62) re-fabricated every ~6 ticks. A jump's +Z velocity survives the horizontal (0,1,0) plane, which is why a jump clears it.

Capture signatures (185-recapture.jsonl): pinned result.position = (131.71, 77.914, 61.485); bodyAfter.slidingNormal = (0,1,0); result.collisionNormal = (0,0.78,0.62) on the re-fabrication ticks; contactPlane = walkablePlane = (0,-0.625,0.781) (the real tread).

2.3 The retail divergence (named-retail decomp, high confidence)

Retail's grounded forward move keeps contact_plane_valid and hits the short-circuit if (this->collision_info.contact_plane_valid != 0) return 1; (transitional_insert, pc 273244 / 0x0050b818) — it never runs step-down at an interior ramp point, so it never reaches edge_slide/precipice_slide. acdream instead loses grounding on the forward move and leans on the fragile per-frame step-down recovery, which cannot reach a coplanar (at-level) continuation because step-down is strictly downward. The wedge is a symptom of over-relying on step-down where retail stays grounded.

2.4 What is FAITHFUL — do NOT touch (adversarially verified)

• PrecipiceSlide math (find_crossed_edge → slide_sphere, conditional sign-negate to oppose travel): faithful (retail precipice_slide pc 274316/274354; conditional negate pc 274347).
• SetSlidingNormal zeroing Z: faithful — retail set_sliding_normal (0x0050a060, pc 272137) also sets sliding_normal.z = 0f then normalizes. Un-zeroing is a DEAD END and would itself be a divergence; and it is geometrically moot (both cp.N and the fabricated normal have x=0, so the crease is pure-X for both the zeroed (0,1,0) and the 3D (0,0.78,0.62) — the +Y offset is annihilated identically).
• The whole-cell multi-object search: faithful — FindObjCollisionsInCell iterates the full per-cell shadow list; both stair objects are tested ([resolve-bldg] confirms hits on 0xF68220/21/22). Not a scoping/registration gap.

3. The fix — Approach A (keep the mover grounded on the forward move)

Invariant to restore: a grounded mover walking a continuous walkable surface retains contact_plane_valid on the forward move (retail pc 273244), so it does not depend on the step-down recovery that fails at a coplanar seam.

Scope (narrow): the grounded forward-move path in Transition.TransitionalInsert / the contact-plane retention it feeds (TransitionTypes.cs ~1030–1110 Slid-clears + the neg-poly/ step-down dispatch ~1339, and the ValidateTransition LKCP retention ~4645–4735). The change: when the grounded foot sphere grazes the coplanar walkable continuation at an object seam, retain / re-establish the contact plane from the tread it is resting on, rather than clearing it (a spurious Slid) and dropping into the step-down recovery.

Explicitly NOT changed: the fabrication code, SetSlidingNormal, PrecipiceSlide, FindCrossedEdge, the multi-object search — all verified faithful (§2.4).

Pinning the exact line — the #137 method, not a guess: implementation step 1 is a dat-backed replay test reproducing this exact seam crossing (fixtures already captured — §6). The replay reproduces the wedge headlessly; the forward-move contact-plane transitions are instrumented inside the test (plus a short ACDREAM_PROBE_CONTACT_PLANE live pass ONLY if the replay can't reach the exact frame) to identify the precise line where contact_plane_valid is lost. The fix targets that line to match retail's retention. Same pattern as Issue137CorridorSeamReplayTests.

Scope guard: if pinning reveals the faithful fix is larger than a localized retention change, STOP and return to the user before expanding scope (frozen-internals rule).

4. Alternatives considered

• B — make step-down find the coplanar/at-level continuation. Bends DoStepDown/StepSphereDown away from retail's strictly-downward design; risks being a subtle divergence rather than a faithful fix. Rejected as primary.
• C — gate EdgeSlide/PrecipiceSlide to not fabricate when a live walkable continuation exists. Smallest blast radius, and retail's edge_slide does gate on walkable != 0, but it treats the symptom site and masks the upstream grounding loss (weaker against no-workarounds). Kept as the fallback if A proves too invasive.

5. Test strategy

• Red→green pin: a new dat-backed replay (Issue185OutdoorStairsSeamReplayTests, pattern of Issue137CorridorSeamReplayTests) driving the captured trajectory through the failing seam: pre-fix reproduces the wedge (no advance past Y≈77.9, slidingNormal=(0,1,0)); post-fix the mover climbs past the seam with no fabricated sliding normal.
• Regression net (the whole point — shared grounded-move path):
  • Issue137* suites (Issue137CorridorSeamReplayTests, Issue137SlidingNormalLifecycleTests, Issue137CorridorSeamInspectionTests) green / kept un-skipped.
  • Live spot checks (user visual gate): indoor cellar/corridor stairs, other outdoor buildings, ramps, and flat ground — no new phantom blocks AND no players sliding through walkable edges/ramps.
  • dotnet build + dotnet test green (Core / App / UI / Net).

6. Apparatus / fixtures (already captured this session)

• Structured resolve capture: …/scratchpad/185-recapture.jsonl (jam pinned at (131.71, 77.914, 61.485); slidingNormal (0,1,0); collisionNormal (0,0.78,0.62)).
• gfxobj geometry: …/scratchpad/gfxdump/0x01000AC5.gfxobj.json (+ 0x01000ACA) — the step-box tread (poly 4) + faces; local tread plane (-0.625,0,0.781, d=-0.312).
• [resolve-bldg] per-object world origins + hit-poly world verts (raw task .output); tread N world verts (132.75,77.495,61.015)…; per-step entOrigin_lb e.g. 0xF6822103 → (132.0,77.2,60.4).
• Reusable probes: ACDREAM_CAPTURE_RESOLVE, ACDREAM_PROBE_STEP_WALK, ACDREAM_PROBE_INDOOR_BSP ([stepdown-decide]), ACDREAM_PROBE_BUILDING ([resolve-bldg], heavy — raw .output, not the Tee'd log), ACDREAM_PROBE_CONTACT_PLANE (forward-move contact transitions — for site pinning), ACDREAM_DUMP_GFXOBJS (fixture extraction).

7. Bookkeeping (in the fix commit)

• Register: amend TS-4 (or add a new row) to record the grounding-retention change; retire/narrow as the faithful port dictates.
• claude-memory/project_physics_collision_digest.md: add the #185 banner + DO-NOT-RETRY entries.
• docs/ISSUES.md: move #185 to Recently closed with the fix SHA.
• Roadmap/milestones: note the M1.5 #137-family stair fix.

8. Acceptance

• The LOCAL player walks up the full outdoor staircase with no jam and no jump; no sideways-slide pin at the tread seams.
• Regression pass (§5): no new phantom blocks AND no players sliding through walkable ramps/edges; Issue137* green; build + test green.
• Register bookkeeping done in the fix commit.

9. DO-NOT-RETRY (carried from the handoff + this investigation)

• Do NOT touch step-up budget / step-up logic — there is no riser; it is a continuous walkable ramp.
• Do NOT "fix the geometry" — the dat is real, coplanar, walkable treads.
• Do NOT un-zero Z in SetSlidingNormal — faithful to retail and geometrically moot (§2.4).
• Do NOT ship a per-frame sliding-normal clear or a small-offset-abort patch — fix the PROVENANCE (the grounding loss), not the symptom (#137 lesson).
• Do NOT read the Tee'd launch log for [resolve-bldg] — it's buffered; read the raw task .output.