PROCITY/docs/LANES/ROUND4_INSTRUCTIONS.md

# PROCITY — Round 4 lane instructions (from Fable, integrator)

> **⚠ SUPERSEDED by [ROUND5_INSTRUCTIONS.md](ROUND5_INSTRUCTIONS.md) (2026-07-14).** Round 4 is
> complete — v1.0 tagged (`2698b40`, all 6 gates green). Historical reference only; do not action.

Date: 2026-07-14 · Written after all six lanes finished round 3. You are an Opus 4.8 agent
assigned ONE lane (read your session prompt). Read this file, your `docs/LANES/LANE_<X>_*.md`
spec, your `<X>-progress.md`, and any `LANE_*_NOTES.md` addressed to you before touching code.

Repo state as of these instructions: **everything committed on `main` at `bd40ec7`**
(Lane E's round-3 work was reviewed and landed by Fable — nothing of yours is uncommitted).
`tools/qa.sh --strict` **GREEN** (4/4 gates, selfcheck 1283/1283, manifest `--depot` 0 errors,
**all 22 GLBs live on the depot**). The only yellow: 5–10 benign storeys warnings per seed in
the consistency checker (proven stale by Lane A in R3 — fixed this round, see Lane F task 2).

## Where we are

v1 is integrated and playable: generated town (seed 20261990 → "Boolarra Heads", 493 shops),
streamed streetscape under draw budget, enterable interiors with GLB hero props, rig-fleet
peds + keepers, shop hours with closed-shop gating, 22 GLBs live on the depot, QA harness
green. **Round 4 is the v1-tag round.** Two gates block the tag:

- **Gate 3 (budget): tris FAIL** — ~279k at the busiest intersection vs the ≤200k budget.
  Cause: the 20 ped rig GLBs in `web/models/peds/` are ~1.1–2.5 MB (~45k tris) each.
  → Lane E decimates, Lane D validates, Lane F re-measures. This is the critical path.
- **Gate 6 (shots): letterbox + poses** — `DBG.shot()` headless-composer letterbox bug +
  3 missing bookmark poses. → Lane B fixes, Lane F re-captures the v1 tour.

Everything else this round is polish that makes the tag worth taking: closed-shop facade
visuals, the 4 new hero props actually appearing in rooms, impostor exposure sync.

## Integrator decisions (so nobody blocks on them)

1. **Ped decimation target: ≤3k tris per ped rig.** With the near cap at 24 rigs that bounds
   the fleet's contribution to ~72k, leaving ~130k for the town — comfortably ≤200k. Use
   `gltf-transform` `simplify` (meshoptimizer) — these are proper manifold skinned character
   meshes, NOT TRELLIS shell-soup, so simplify works (the R3 shell-soup finding does not
   apply). Preserve skinning weights + the separate `walk.glb`/`idle.glb` animation clips.
2. **Hero-prop tris stay as-is for v1** (25–77k). They are focal, one-per-room, and gate 3
   measures the street. The bake-to-lowpoly pass is a follow-up, NOT round-4 work — unless
   Lane C's interior measurements show a single room blowing budget (then flag, don't fix).
3. **fal.ai fallback for glass-case + bus-shelter (~$2.70) stays parked.** Do NOT spend it.
   Both have primitive fallbacks; John triggers the spend himself if he wants them.
4. **The depot is live and canonical** — `validate --depot` green, publish is done. Lane C:
   validate GLBs through the normal `depot:` path (or `?localdepot=1`); the R3 `localBase`
   shim and the `web/assets/_local_glb/` copy are obsolete (C task 3 removes the dir).
5. **v1 tag criteria**: all 6 gates green in §4 of LANE_F_NOTES → Lane F tags `v1.0` on main.
   Nothing is pushed anywhere — tagging is local, John pushes.

## Process rules (unchanged — they matter, agents run concurrently)

- Lanes share ONE working tree. Never `git add .` / `git add -A` / `git commit -a`. Run
  `git status` first; stage **only your files by exact path** (`git add <paths>` then
  `git commit -m ... -- <paths>` — options BEFORE the `--`; new files must be `add`ed first)
  and commit immediately. Touch nothing another lane has modified.
- After committing, pin a durable per-lane ref (`git branch lane-<x>/round4-<topic> <sha>`
  and/or a tag) so a concurrent `git reset` can't orphan your work.
- Real repo path is `/Users/m3ultra/Documents/procity` (old prompts saying /Users/jing are wrong).
- Leave `bash tools/qa.sh --strict` GREEN before you finish. Update your `<X>-progress.md`;
  leave cross-lane notes in `docs/LANES/LANE_<X>_NOTES.md`, not silent edits to others' files.
- `procityprogress.txt` and `settings.local.json` in the tree root are untracked on purpose —
  leave them alone, do not commit them.
- Dev server: `python3 -m http.server 8130 -d web` (may already be up on :8130 — reuse it).

## Sequencing (who unblocks whom)

```
E1 (ped decimate) ──→ D2 (validate rigs) ──→ F3 (gate-3 re-measure) ─┐
B2 (DBG.shot fix + poses) ──────────────────→ F4 (gate-6 shots) ─────┼─→ F5 (tag v1)
F1 (setExposure wire) ──→ D3 (verify sync)                           │
F2 (storeys checker fix) ──→ A1 (confirm 0 warnings)                 │
B1 (closed facades) · C1 (hero props in rooms) · E2 (asset re-exports) → C2
```
Start-of-round: E and B have the critical-path items — start E1/B2 immediately. F1/F2 are
small and early. Everything else is parallel.

---

## Lane A (Citygen) — standby + two confirmations

Small round again. Your R3 verdict (storeys warnings = benign corner anchors) drives F's
checker fix this round.

1. **After F lands task F2** (the consistency-checker `permittedMax` scoping you specified in
   LANE_A_NOTES.md): re-run `bash tools/qa.sh --strict` across ≥5 seeds and confirm the
   storeys warnings are now **0** with no new false-negatives (deliberately test that a real
   violation would still be caught — e.g. temporarily fake a `video@2` in a scratch copy of
   the checker's input, NOT in the plan code). Confirm `GOLDEN.hash` still `0x098eec2b`.
2. **openLate contract audit**: F's night gate asserts `plan.shops.some(s => s.hours[1] >= 22)`.
   Confirm across ≥5 seeds that (a) exactly ONE shop per town qualifies, (b) it is always the
   video rental, (c) the threshold 22 matches your convention. If any seed violates it, fix in
   plan.js + add a selfcheck assertion; if the convention differs, document the correct
   predicate in LANE_A_NOTES.md for F.
3. Otherwise standby: answer cross-lane questions (LANE_A_NOTES.md is your channel).

**Acceptance**: qa.sh consistency shows 0 storeys warnings (post-F2); golden hash unchanged;
openLate holds on ≥5 seeds or is fixed + asserted.

## Lane B (Streetscape) — closed facades, shot harness, furniture verify

1. **Closed-facade visual (§3.5 render side — the headline item).** Predicate is ready:
   `window.PROCITY.isOpen(shop)` + `window.PROCITY.currentHour()`. When closed: dark/unlit
   windows + a CLOSED plate (or shutter) on the facade; when open (esp. at night for the one
   `openLate` video shop): lit windows. Also a "CLOSED" door tooltip on aim. Facade state must
   update when the day segment changes (hook the same seam `lighting.js` uses — don't poll per
   frame). Keep it batched: this must NOT break your facade atlas — aim for a per-instance
   uniform/attribute or an overlay quad, not per-shop materials. Re-measure worst view ≤300
   draws with citizens after.
2. **Shot-harness fixes F requested (gate-6 blocker — do early).** In `dbg.js`:
   (a) fix the headless-composer letterbox in `DBG.shot()` (shots come out letterboxed when
   the composer runs headless — see F-progress R3 notes); (b) add the 3 missing named
   bookmark poses F listed in LANE_F_NOTES §9 (check the exact names there — the tour wants
   `street_noon`-style bookmarks incl. a night-neon and market pose). Verify by running
   `python3 tools/shots.py` and eyeballing output.
3. **Furniture GLB footprint/collision verify (your R3 task 3, now unblocked).** F's §3.4
   manifest-GLB furniture upgrade is live. Verify street furniture placement: GLBs sit on
   their reserved footprints, no sidewalk clipping, player collision sane, and the new
   `novelty_record` street prop (manifest furniture #8) actually spawns somewhere sensible.
   If it isn't placed by the streetscape yet, place it (record-store adjacency is the obvious
   home).
4. Optional polish: fresh beauty stills for docs/shots/ once 1–3 land.

**Acceptance**: at 22:00 only the video shop reads open and every other facade reads closed
(screenshot evidence); `shots.py` produces un-letterboxed shots incl. the 3 new poses;
worst-view draws ≤300 with citizens; qa.sh green.

## Lane C (Interiors) — hero props into rooms

Your R3 validated the 9 library fittings. The manifest now has **14 fittings** — the 4 new
hero props + cash_register are unmapped in `glb.js`.

1. **Map + validate the new hero fittings** in `web/js/interiors/glb.js`:
   - `arcade_cabinet` → video store (it's the focal prop)
   - `listening_booth` → record store
   - `drinks_fridge` + `milkshake_mixer` → milkbar (mixer is a counter-top item — it likely
     sits ON the counter, not on the floor; check its manifest footprint/height and place
     accordingly)
   - `cash_register` → counter-top on the primitive counter (the till upgrade), all shop types
     if it reads well, else the till-less ones
   Reuse your R3 approach: real-metre scale clamped to footprint, per-kind yaw, fail-soft.
   Load via the normal `depot:` path or `?localdepot=1` — all 5 are published and live.
2. **Sweep + soak with the new mappings on** (same bar as R3): 0 throws / 0 path-fails /
   0 determinism-fails / 0 leaks, worst build <50 ms. Screenshot each new prop in its room →
   `docs/shots/laneC/` (extend the contact sheet).
3. **Cleanup**: delete `web/assets/_local_glb/` (your R3 validation copy — superseded by
   Lane E's `?localdepot=1` + `stage_local_depot.py`). It's untracked; just `rm -rf` it.
   Keep (don't remove) the `localBase` manifest hook if it costs nothing, but the dir goes.
4. **Measure a hero-prop room**: draws + tris inside the video store (arcade cabinet is 25–77k
   tris territory). If any single room exceeds interior budget expectations, REPORT the number
   in LANE_C_GLB_VALIDATION.md for E's future bake pass — do not block or fix.
5. **Standing by for E2**: when Lane E re-exports `record_crate` (currently broken) and the
   ~2 m counter-with-till, re-map both and validate (may land late in the round or not at all —
   don't wait on it).

**Acceptance**: 4 new hero props (+cash_register) render in their rooms, planted, scaled,
facing right, stock/keeper unbroken; soak passes with them on; contact sheet updated; qa green.

## Lane D (Citizens) — in-shell rig verify + decimation validation

1. **In-shell §3.4 verification (now unblocked — F wired the fleet in R3).** In the real game
   (`web/index.html`, not your test page): confirm peds AND keepers upgrade placeholder→rig
   once the fleet loads; enter/exit 10+ shops and confirm `renderer.info.memory` returns to
   baseline (your R3 leak proof, but in-shell); confirm determinism (same seed → same
   identities) and `?noassets=1` still runs fully placeholder with zero fetches.
2. **Validate E's decimated peds (critical path — coordinates with E1).** When E stages the
   decimated `web/models/peds/*.glb`: rigs still bind + animate (walk/idle), no skinning
   explosions, silhouettes read at street distance, impostor atlas bakes clean, identity
   variety intact. Measure per-ped tris (≤3k target) and re-run your determinism + leak
   checks. Report the numbers in LANE_D_NOTES.md; F re-measures gate 3 after your OK.
3. **Verify exposure sync once F lands F1** (the `setExposure` call site you specified —
   F did NOT wire it in R3, it's queued this round): at dusk/night, mid-tier impostors match
   near-rig brightness through segment transitions, incl. across a placeholder→rig upgrade.
4. Chunk-streamed roster stays design-only (your R3 note). No implementation this round.

**Acceptance**: rigs live in-shell and leak-free; decimated peds validated ≤3k tris each with
anims intact; exposure visually consistent across tiers at night; qa green.

## Lane E (Assets) — ped decimation (critical path) + asset fixes

1. **Decimate the 20 ped rigs in `web/models/peds/` (THE gate-3 blocker — start immediately).**
   Use `gltf-transform` (npx) `simplify` — meshoptimizer works here: these are manifold skinned
   character meshes, not TRELLIS shell-soup. Requirements:
   - target **≤3k tris per ped** (integrator decision #1); keep textures (WebP/resize if easy
     wins are there — file size matters less than tris)
   - PRESERVE skinning (joints/weights) and do not touch `walk.glb` / `idle.glb` (the shared
     animation clips) beyond confirming they still retarget
   - back up originals to a gitignored dir (e.g. `pipeline/.peds_orig/` — add to .gitignore)
   - stage in place (`web/models/peds/`), eyeball a contact sheet (no melted faces/hands),
     then hand to Lane D for rig validation (task D2). Record before/after tris + method in
     pipeline/AUDIT.md.
2. **Two asset re-exports for Lane C** (from LANE_C_GLB_VALIDATION.md):
   - `procity_fit_record_crate_01.glb` — broken (undefined `uri` reference, won't parse).
     Re-run normalize from source or regenerate; validate it loads in three.js before handing.
   - counter: a **~2.0–2.3 m long counter WITH a till** (the R3 one is 4 m, till-less, and
     squashes). Local pipeline (flux_local → trellis_mac), ≤2 attempts each; if both fail,
     add to the fal fallback list and move on.
   Publish any new/re-exported GLBs to the depot (the R3 passwordless tailnet path) + re-run
   `validate_manifest.py --depot` → 0 errors. Note for C in LANE_E notes when live.
3. **Do NOT**: spend the fal.ai budget (decision #3), or start the hero-prop bake-to-lowpoly
   pass (decision #2) — parked unless C reports a room blowing budget AND Fable re-scopes.

**Acceptance**: all 20 peds ≤3k tris with skinning/anims intact and D's sign-off; record_crate
loads; counter attempt resolved (shipped or documented-failed); depot validate 0 errors; qa green.

## Lane F (Integration) — wire-ups, gate closure, tag v1

1. **Wire Lane D's `setExposure` call site** (you didn't in R3 — D's NOTES give the exact
   one-liner; it belongs right after the `citizens.setTimeOfDay(...)` call at
   `web/index.html:244`): pass the shell's animated `renderer.toneMappingExposure` into
   `citizens.setExposure(...)` on segment change. Verify with D (D3).
2. **Apply Lane A's storeys-checker fix** in the consistency checker (tools/): scope the
   check to `permittedMax = (max >= 2) ? min(max + 1, 3) : max` per LANE_A_NOTES.md, so the
   intentional 3-storey corner anchors stop warning while real drift still trips. Expect
   consistency warnings → 0; A confirms (A1).
3. **Gate 3 re-measure** after D2 signs off on E1's decimated peds: busiest intersection,
   clean single-pass, with rig fleet + citizens at busy midday. Need ≤300 draws AND ≤200k tris.
   Record in the runbook gate table.
4. **Gate 6 closure** after B2: re-run `tools/shots.py` → 10 un-letterboxed beauty shots incl.
   the 3 new poses → `docs/shots/v1_tour/` + contact sheet. Also capture B1's closed-facade
   night shot for the tour (the 🔒 toast + dark facades sell §3.5).
5. **Tag v1.** When the §4 gate table in LANE_F_NOTES is all-green (1,2,4,5 already ✅; 3 and 6
   land this round): update the gate table + F-progress, run a final full
   `bash tools/qa.sh --strict`, then `git tag v1.0` with a summary message. Do NOT push —
   John pushes. If a gate won't close, document exactly what's short in F-progress and stop
   at the documentation (no half-tag).
6. Ongoing: you own `web/index.html` and tools/ seams — other lanes leave those edits to you
   (they document call sites in their NOTES instead, as D did).

**Acceptance**: exposure wired + D-verified; consistency 0 warnings; gates 3 + 6 measured
green (or precisely documented why not); v1.0 tagged locally on an all-green qa run.

---

*— Fable (integrator). Questions → leave them in your NOTES file addressed to Fable; I read
everything at round end. Commit atomically, pin your refs, leave it green.*