docs(O-T1): session handoff prompt for Phase O Task 1 (WB usage audit)

Self-contained prompt for a fresh Claude Code session. The next session
reads it once, has all the context it needs, produces the WB-usage
closure audit at docs/research/2026-05-21-phase-o-t1-wb-audit.md,
and stops before any extraction. Investigation-only (the /investigate
skill applies). User reviews the audit before T2 begins.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

docs/research/2026-05-21-phase-o-t1-prompt.md

@@ -0,0 +1,179 @@
+# Phase O — Task O-T1 — Session Handoff Prompt
+
+**Copy everything below the line into a fresh Claude Code session.**
+The prompt is self-contained — the new session reads it once and has
+all the context it needs.
+
+---
+
+You are starting **Phase O — Task O-T1** on acdream. Phase O is **active**
+(pre-empts M1.5 by user direction 2026-05-21). The full phase spec is at:
+
+```
+docs/superpowers/specs/2026-05-21-phase-o-dat-path-unification-design.md
+```
+
+**Read that spec first** (sections 1-4 are the most relevant to this task).
+Also read the auto-loaded CLAUDE.md "Currently working toward: Phase O" block.
+
+## What you're doing
+
+Phase O extracts the WorldBuilder code we actually use into our own repo
+so we can drop the project references and run with **one dat reader**
+(`DatCollection`) instead of two. Task O-T1 is the safety pass that
+must happen BEFORE any extraction: produce a closure of every WB type
+and file we transitively use, so T2–T7 don't miss a dependency and
+break the build at the "drop project references" step.
+
+**This is the `/investigate` skill territory — REPORT-ONLY.** Do not
+move files, do not edit source, do not run `dotnet build/test`. Read
+files, run read-only diagnostics (`grep`, `git`, `find`), and produce
+a single markdown audit document. The user will review and approve
+before any extraction starts in a later session.
+
+## Inputs available to you
+
+- **Our code that consumes WB**:
+  - `src/AcDream.App/Rendering/Wb/*.cs` — adapters that wrap WB.
+    Start with `WbMeshAdapter.cs` and `WbDrawDispatcher.cs`.
+  - `src/AcDream.App/Rendering/TerrainModernRenderer.cs` — uses some
+    WB types but is our own renderer.
+  - Anywhere else with `using WorldBuilder.*` or
+    `using Chorizite.OpenGLSDLBackend*`. Grep for both.
+- **The WB source itself**:
+  - `references/WorldBuilder/WorldBuilder.Shared/` — types we use directly
+  - `references/WorldBuilder/Chorizite.OpenGLSDLBackend/` — the rendering code
+    we use (`ObjectMeshManager`, `TextureHelpers`, `SceneryHelpers`,
+    `LandSurfaceManager`, `OpenGLGraphicsDevice`, `Frustum`, etc.)
+- **CSProj files** (the formal dependency boundary):
+  - `src/AcDream.App/AcDream.App.csproj` — has the WB ProjectReference entries
+  - `src/AcDream.Core/AcDream.Core.csproj` — same
+
+## Concrete steps
+
+1. **Direct-use enumeration.** Find every `using WorldBuilder.*` and
+   `using Chorizite.OpenGLSDLBackend*` line in `src/AcDream.*`. For each
+   file, list the specific WB types it references (e.g.,
+   `ObjectMeshManager`, `OpenGLGraphicsDevice`, `TextureKey`,
+   `ObjectRenderBatch`). Don't forget `nameof()` and string references
+   in tests.
+
+2. **Transitive closure.** For each WB type in the direct-use set, open
+   its file in `references/WorldBuilder/` and list its dependencies on
+   *other* WB types. Walk the graph until closed. Be systematic —
+   `ObjectMeshManager` will pull on a lot.
+
+3. **Per-file inventory.** For each WB file in the closure:
+   - Path (relative to `references/WorldBuilder/`)
+   - Line count (`wc -l`)
+   - One-line role description
+   - Direct callers in our codebase (if any) or in WB (if transitive)
+   - Whether it touches `IDatReaderWriter` / `DefaultDatReaderWriter`
+     (these become DatCollection-swap candidates)
+   - Whether it touches GL state directly (matters for T3 — GL infra
+     extraction has different risk than dat-touching code)
+
+4. **Categorize by extraction task**. Bucket each file into one of:
+   - **T3 candidate** (texture / GL infrastructure, no dat dep)
+   - **T4 candidate** (mesh pipeline)
+   - **T5 candidate** (scenery / terrain blending)
+   - **T6 candidate** (EnvCell / portal)
+   - **NOT EXTRACTED** (we use it via project reference today but
+     can drop entirely — e.g., the WB editor tools, anything not in
+     our render path). Justify the "not extracted" call for each.
+
+5. **Hidden-dependency probes** (the things that bite at T7):
+   - Does WB use any `internal` types that are only accessible to
+     classes inside the WB project? If so, we'll have to make them
+     `public` or copy more.
+   - Does WB use any source generators, .targets files, or build
+     hooks that we'd need to replicate?
+   - Are there resource files (.png, .glsl, .shader) we need to copy?
+   - Does WB's `DefaultDatReaderWriter` differ from our `DatCollection`
+     in any behavioral way that would matter when we swap? (Caching,
+     thread safety, the same-file-different-handle thing, etc.)
+     Don't fully audit — just flag the questions.
+
+6. **Thread-model spot-check** (open question O-Q1 in the spec):
+   - Is `ObjectMeshManager` called from the render thread only, or
+     does our `LandblockStreamer` worker thread call into it?
+     `grep` for the call sites. If the worker thread reaches WB code,
+     flag it — we may have a latent race today that becomes obvious
+     after extraction.
+
+## Output
+
+Write the audit to:
+
+```
+docs/research/2026-05-21-phase-o-t1-wb-audit.md
+```
+
+Suggested structure:
+
+```markdown
+# Phase O — Task O-T1 — WB Usage Audit
+
+## Direct use surface
+(Table of (our file, WB types used))
+
+## Transitive closure
+(Tree or table walking from direct types through WB internals)
+
+## Per-file inventory
+(Table: path, LOC, role, dat-touch?, GL-touch?, target task bucket)
+
+## Extraction-task mapping
+- **T3 (GL infra):** N files, ~M LOC
+- **T4 (mesh):** N files, ~M LOC
+- **T5 (scenery/terrain):** N files, ~M LOC
+- **T6 (EnvCell/portal):** N files, ~M LOC
+- **NOT extracted:** N files, with justifications
+
+## Hidden-dependency risks
+(Bulleted list of things flagged in step 5)
+
+## Thread-model finding
+(Yes/no + evidence on whether WB is called from the worker thread)
+
+## Open questions for user
+(Anything unclear that the user needs to call before T2 starts)
+```
+
+**Cap the audit doc at ~500 lines.** If the closure is bigger than that,
+inline the per-file table for the top 30 files by LOC and link to a
+separate appendix file for the long tail.
+
+## Acceptance for O-T1
+
+- Audit doc exists at the path above.
+- Every file in the closure is bucketed (T3 / T4 / T5 / T6 / NOT).
+- Hidden-dependency risks section has at least the four items in
+  step 5 addressed (even if the answer is "none found").
+- No source code edited. No `dotnet build/test`. No project files
+  touched. (Verify with `git status` at the end — only the new
+  audit doc + maybe `git ls-files | grep WorldBuilder | wc -l`-style
+  diagnostic output should appear.)
+
+## When you're done
+
+Report back in chat with:
+
+1. Total LOC of the closure (the rough size of the extraction).
+2. The bucket breakdown (how many files / LOC per task).
+3. Any sharp edges flagged in the hidden-dependency risks section.
+4. Your honest read on whether the 7-8 day estimate in spec §5 is
+   reasonable given what you found, or whether it needs a revision.
+
+**Then stop.** Do not start T2. The user reviews the audit before
+extraction begins.
+
+## Reminders
+
+- You are operating under the `/investigate` skill rules (no edits).
+- `references/WorldBuilder/` is the source to grep through, NOT to edit.
+- WB is MIT-licensed; the eventual extraction is license-clean. You
+  don't need to think about that here.
+- If something in the audit surfaces a reason Phase O shouldn't
+  proceed (e.g., WB has a license clause we missed, or the closure
+  is 50K LOC instead of 5K), say so clearly. We'd rather know now.