docs: next-agent handoff prompt for C4 routes 2-7

Self-contained continuation prompt for the placement cutover. Records the
worktree/branch/HEAD (and that main is still at c7d5fc14 with these commits
unmerged, per the user's direction to work in the worktree), the read-first
list, binding rules, the 10,844/4/0 baseline to measure against, the 10
commits landed on this branch, and the work order: route 2 from its pinned
contract, route 3 with #280 beside it, routes 4-7 folding in #276/#277, C5
closeout, then AP-22 and AD-10.

Carries the two things a fresh session would otherwise have to rediscover:
route 2 is a seam-building slice rather than a wiring job (the accepted-Position
classifier's only production consumer is route 1's Create continuation), and
the complete-suite-before-every-commit gate that the #281-#284 regressions
bypassed.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

docs/research/2026-08-03-c4-handoff/NEXT-AGENT-PROMPT.md

@@ -0,0 +1,199 @@
+# Next-agent prompt — C4 placement routes 2–7
+
+Continue the acdream placement cutover from the 2026-08-03 regression-cleanup
+checkpoint. The code is modern; behaviour must remain retail-faithful.
+
+## Where to work
+
+```text
+C:\Users\erikn\source\repos\acdream\.claude\worktrees\peaceful-visvesvaraya-e0a196
+```
+
+Branch `claude/acdream-physics-divergence-5aa784`, expected HEAD
+`f2b06f378738474b0861e4d990d17f9645e07615`.
+
+**The user directed that work happen in this worktree, not in `main`.**
+`main` is still at `c7d5fc14` — the 10 commits below are NOT merged. Do not
+merge, rebase, or push unless the user explicitly asks. Preserve the main
+worktree's untracked research/tooling files.
+
+## Read before editing
+
+1. `CLAUDE.md` and `AGENTS.md`.
+2. `docs/research/2026-08-03-c4-route-2-contract.md` — **the pinned contract
+   for your first task.** It is the whole ramp-up for route 2.
+3. `docs/plans/2026-08-02-placement-cutover.md` — the C4/C5 campaign plan.
+4. `docs/research/2026-08-02-cutover-route-inventory.md` — the 8-route,
+   both-host call-chain inventory with exact file:line for every duplicate
+   authority. THE map for routes 3–7.
+5. `docs/plans/2026-08-03-recent-regression-cleanup.md` — closed; explains the
+   three defects fixed this session and why.
+6. `docs/ISSUES.md` — #276, #277, #280 (open); #281–#284 (closed this session).
+7. `docs/architecture/retail-divergence-register.md` rows AP-1, AP-22, AP-131,
+   AP-133, AD-1, AD-10, AD-60, TS-28.
+
+## Binding rules
+
+- Retail is the oracle. Grep
+  `docs/research/named-retail/acclient_2013_pseudo_c.txt` by named
+  `class::method` BEFORE any fresh decompilation.
+- Preserve the Runtime-owned, presentation-independent architecture. Graphical
+  and headless hosts use the same canonical owners.
+- Root causes only. No timeouts, grace periods, suppression flags,
+  catch-and-swallow, duplicated placement writers, or test-only bypasses.
+- The user's live observations outrank green automated tests.
+- Never `git add -A`, `git add .`, `git reset --hard`, or
+  `git checkout -- <path>`. Stage exact paths only.
+- Each independent fix is its own bisectable commit recording root cause and
+  evidence; issue and divergence ledgers update in that same commit.
+- **Run the COMPLETE Release solution suite green before every commit.** Not a
+  focused subset. Every regression cleaned up this session shipped because a
+  commit was gated on focused tests while the full suite was red. It costs
+  ~30 seconds:
+  ```
+  $env:ACDREAM_PAK_PATH='C:\Users\erikn\Documents\Asheron''s Call\acdream.pak'
+  dotnet test AcDream.slnx -c Release -m:1
+  ```
+- Close the client gracefully before reconnecting to ACE at `127.0.0.1:9000`.
+  The user manages client lifecycle; if a rebuild is lock-blocked, ASK.
+- Launch visual gates in **Release**, with `ACDREAM_RETAIL_UI=1` (the user
+  prefers the retail GUI).
+
+## Baseline
+
+Complete Release solution at HEAD: **10,844 passed / 4 skipped / 0 failed**
+(App 4,058/3, Bake 15, Cli 4, Content 124, Core.Net 762, Core 4,247/1,
+Headless 79, Runtime 1,012, UI 543). Treat any deviation as a regression you
+introduced.
+
+## Completed on this branch (10 commits)
+
+| Commit | What |
+|---|---|
+| `6dcb94ac` | Restored the world-frame precondition across 5 first-entry fixtures; added `RuntimeWorldFrameTests` |
+| `98e9f9e8` | Modelled the post-`f24532ad` effect cell / canonical body frame in 2 rendering fixtures |
+| `95ebc03a` | Filed #282–#284 + cleanup plan |
+| `97d11e6c` | **#284** — parked placements name their cause; terminal on the contradictory state |
+| `3c36b4cc` | **#282** — one cell owner (`WorldEntity.VisibilityCellId`); register row AP-133 |
+| `0c14c402` | Connected visual acceptance for #282/#284 |
+| `898ff18b` | #283 reachability probe (`ACDREAM_PROBE_WORLD_FRAME=1`) |
+| `89cf1e66` | **#283** — measured UNREACHABLE; permanent invariant instead of a restructure |
+| `2ef02f8c` | Closed the cleanup plan |
+| `f2b06f37` | **Pinned the route 2 contract** (your starting point) |
+
+Context worth carrying: the handoff that started this session claimed "six
+selected fixture failures". The measured baseline was **43** — the App suite
+was fully green at `01f4791e` and `670f307c` broke 28 tests in one commit,
+while the Runtime suite lost 13. All were stale fixtures, fixed without
+weakening a single assertion. Three real product defects (#282–#284) were
+found in the same sweep and are now closed.
+
+## Work order
+
+### 1. Route 2 — ForcePosition (start here)
+
+Execute `docs/research/2026-08-03-c4-route-2-contract.md`.
+
+Scoping is already done and it is **not** a small wiring job:
+`RuntimeAuthoritativePositionRouteClassifier.ClassifyAcceptedPosition` produces
+the retail-exact ForcePosition route but has exactly ONE production consumer —
+`RuntimeInitialCreateContinuationExecutor.cs:1948`, route 1's Create
+continuation. A live local player receiving a Position has no Runtime consumer
+at all. You must build the accepted-Position execution seam, then cut App over.
+
+Two duplicate authorities to delete:
+- `LocalForcePositionTransaction` (blip + pre-commit outbound ack);
+- the generic tail at `LiveEntityNetworkUpdateController.cs:1264-1281`, which
+  independently writes position/cell/rotation to the render entity and
+  rebuckets the SAME accepted Position.
+
+Named behaviour change to call out in the commit: the outbound
+`AutonomousPosition` ack currently fires BEFORE any canonical commit, and the
+trailing `isCurrent()` only suppresses the continuation — the packet has
+already gone. Retail makes it `SendPositionImmediately`, an output of the
+executed route.
+
+Retail: `SmartBox::HandleReceivedPosition` @0x00453FD0 — the FORCE_POSITION
+early return (~92932) precedes `unset_parent` (~92990) and the
+`!HasAnims`-gated `SetPlacementFrame` (~92992).
+
+### 2. Route 3 — portal placement
+
+`RuntimeWorldTransitState` → `RuntimePortalPlacementAuthority` adapter. Delete
+`LocalPlayerTeleportPlacement.Place`
+(`LocalPlayerTeleportController.cs:214-278`), which does its own resolve, body/
+cell write, world-entity write, rebucket and host-notify, and then calls
+`AcknowledgePortalMaterialized` AFTERWARDS — a rubber stamp, not a gate.
+Re-sequence so the acknowledgement is the actual gate.
+
+#283 is already settled, so the origin question is closed going in; the
+permanent guard is `LiveWorldOriginState.EnsureAgreesWithRuntimeFrame`.
+
+### 3. #280 — portal destination prefetch (land beside route 3)
+
+The reveal gate is a hardcoded 3×3 landblock neighbourhood
+(`WorldRevealReadinessBarrier.OutdoorNeighborhoodRadius = 1`, 576 m) while the
+configured view is 11×11 to 31×31 (2,112–5,952 m) depending on quality preset
+— so the viewport opens on ~1.4% of the visible world on High and the user
+watches the rest stream in. Compounded by `BeginOriginRecenter` detaching every
+resident landblock (no reuse) and `MaxCompletionsPerFrame` 2–6.
+
+Port retail's mechanism, not a bigger magic number: `CellManager::PreFetchCells`
+@0x00455820, `LScape::PreFetchCells` @0x00505660, `CLandBlock::PreFetchCells`,
+`CLandBlockInfo::PreFetchCells`, `SmartBox::UseTime` @0x00455410 while
+`blocking_for_cells`, and the `TAS_TUNNEL_CONTINUE` resume/reveal ordering.
+Use the configured quality/view-distance window; hold ONE generation-scoped
+reservation across terrain, statics/buildings, EnvCells, render publication,
+composites, and collision. Keep the wait cue responsive. Never reveal early on
+a timeout; never wait for an impossible "all dynamic objects delivered" marker.
+
+### 4. Routes 4–7
+
+- **4** — remote Create/Position; delete `RemoteTeleportController`/`Placement`
+  and the inline MoveOrTeleport duplicate. Retires AP-131.
+- **5** — authoritative projectile correction.
+- **6** — drops + split-recovery marking.
+- **7** — pickup, parent detach, delete/GUID-reuse residue.
+
+Fold in #276 (`SpawnPlacementSettler` must commit the settle's resolved
+`CellId`) and #277 (far Create needs a real service-window/cell-less lifecycle
+instead of relying on ACE's broadcast radius) where their route becomes
+authoritative. #284's parked-placement counts were deliberately NOT folded into
+`IsConverged` because #277 documents a legitimate session-long park — wire them
+into the connected gates when #277 makes "legitimately parked" definable.
+
+### 5. C5 closeout
+
+Delete every superseded writer; focused + complete suites; lifecycle/reconnect;
+canonical nine-stop soak **on the final binary** (read `report.json`, require
+`Passed=true`, zero failures, all checkpoints, `waitCueShown=false`, no pending
+publication/retirement/reveal debt, no render-shadow mismatch, graceful exit);
+two-client observation; user visual matrix. Then retire AP-1, AD-1, AP-131 and
+AD-60's legacy half.
+
+### 6. Then AP-22, then AD-10
+
+- **AP-22** — `ShadowShapeBuilder` as the sole authority for authored Setup
+  collision shapes. Preserve authored cylinder order; authored spheres when no
+  cylinders; cylinder-first for mixed; truly shapeless means no shadow. Remove
+  invented `Setup.Radius` cylinders, `Radius * 2` heights, sphere-to-cylinder
+  coercion, across graphical/headless/static/live together.
+- **AD-10** — remote slope projection through the real retained transition
+  contact plane. Prove remote motion uses the complete sweep, remove
+  terrain-normal preprojection, let `CTransition::adjust_offset` project
+  against the actual collision plane. Preserve interpolation queues,
+  authoritative correction replacement, Hidden state, network cadence.
+
+Then the final movement/collision matrix and ledger/architecture/roadmap/
+milestones/memory/`CLAUDE.md`/`AGENTS.md` updates. Vendor Slice 5 resumes only
+after the campaign is genuinely closed.
+
+## Reporting
+
+For every fix report: reproduction, retail evidence (named symbol + address),
+plain-language root cause, files/lines, the fix, tests, commit SHA, complete
+build/test numbers, user visual result where required, and which issues or
+divergence rows were closed, narrowed, or left open.
+
+Do not describe the campaign as complete while any C4 route, #280, the
+final-binary soak, AP-22, AD-10, or a required user visual gate remains.