PROCITY/docs/LANES/ROUND9_INSTRUCTIONS.md

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

Date: 2026-07-14 · Written after the Fable round-8 review. You are an Opus 4.8 agent
assigned ONE lane (read your session prompt). Read this file, your lane spec, your
`<X>-progress.md`, and NOTES addressed to you first.

Repo state: `main` at `9cc00ad` = `v2.0-rc`, **fully pushed** (origin synced, all five
version tags live). `tools/qa.sh --strict` GREEN 5/5 with **zero warnings** — every smoke
incl. the warn-level ones (buy, patronage, book/toy stock, katoomba) is green. Round 8 had
**no slips**: weather, Katoomba, three real-stock packs (record 350 / book 311 / toy 273),
buy loop, patronage all live. Goldens: synthetic `0x3fa36874` · melbourne `0x34cfdec0` ·
katoomba `0x0f652510`. fal ~$21.36.

## Theme: ship v2.0

The rc is healthy and warning-free. Round 9 hardens it into **`v2.0`**: graduate every
smoke to strict, make the crowd visible *inside* shops, widen buying beyond the dig,
re-shoot the tour so it shows the living town, and freeze the docs. One new toy (B's tram)
rides along but does NOT block the tag.

What v2.0 means when tagged: seed → real-or-synthetic AU town → streamed streets with
weather and a living crowd that shops → every door opens → real browsable stock you can
buy with a wallet → all of it deterministic, leak-free, budget-clean, and enforced by a
strict harness.

## Prime law (unchanged post-amendment)

Default boot = streamed roster + patronage at the pinned baseline; plan goldens frozen;
new features behind default-off flags; flags compose; qa strict green at every commit.
Baseline re-pins only by the one-commit protocol.

## Integrator decisions (so nobody blocks)

1. **Interior presence (the round's one cross-lane seam — C↔D, F wires).** Peds who duck
   into a shop should be *there* when the player follows. Contract: D tracks per-shop
   occupancy (who's inside + their identity seeds, already implied by patronage state);
   C exposes 1–3 **browse points** per room in the room API (aisle spots, like the keeper's
   counter spot); F passes occupancy → interior build so browser rigs (KeeperManager-style
   fleet clones, idle/browse pose) stand at browse points. Cap 3/room; ≤350 draws holds;
   leak-free like keepers (proven pattern). D owns occupancy truth, C owns points + room
   fit, F owns the handoff. Agree the two interfaces in NOTES before code (half-day
   handshake rule).
2. **Buy-anywhere scope (C):** book/toy shelves get pull-and-buy (aim at a real-stock
   spine/box → pull-out card with title/price → BUY via the same wallet). No new dig
   mechanics — reuse the pull-panel pattern. Record digs stay the deep interaction.
3. **Tram (B): now a real task, but explicitly NON-BLOCKING for v2.0** (no-hostage rule
   pre-applied). `?tram=1`: one instanced tram on a seeded main-street loop over the
   bus_shelter stops, door-pause at each, budget-neutral (≤2 draws). If it lands, it
   enters the harness at warn and the tour gets a shot.
4. **Audio stays parked** — STANDING ASK TO JOHN (third round running): one decision line
   ("generate ambience freely" / "use library X" / "skip for v2") unlocks street ambience,
   rain-on-roof, and the milk-bar door bell. Until then no lane touches audio.
5. **fal: no new spends** (broken-prop clause stands).
6. **Tag `v2.0`** (F, end of round) when: all round-8 warn smokes strict + green ·
   interior presence live + smoked · buy-anywhere live + smoked · v2 tour re-shot ·
   full-defaults soak green · docs frozen. Tram/third-town slippage does not block.
   This is the epoch tag — after it, Fable + John pick the v3 epoch (editor/overrides vs
   venue district vs multiplayer presence — V2_IDEAS).

## Process rules (unchanged)

- ONE shared working tree; exact-path staging; options before `--`; new files `add`ed
  first; durable lane refs; qa green at every commit; progress docs + NOTES.
- F owns `web/index.html` + `tools/`; document call sites for F.
- Slip rule: partial commit + cut-line note, never silent.
- `procityprogress.txt` / `settings.local.json` untracked; staging dirs gitignored.
- Repo `/Users/m3ultra/Documents/procity`; dev `:8130`.

## Sequencing

```
C1 (browse points) ──┬──→ D1 (occupancy + browsers) ──→ F1 (wire handoff + smoke)
                     └──→ C2 (buy-anywhere)
B1 (tram, non-blocking) · A1 (contract freeze + docs) · E1 (VRAM audit) — parallel
                all land ──→ F2 (graduate smokes strict) ──→ F3 (tour + soak) ──→ F4 (tag v2.0)
```
C starts first (both seams hang off the room API). F1 needs C1+D1.

---

## Lane A (Citygen) — freeze the contract, polish the docs

Small round — you're the most "done" lane; make it official.

1. **CITY_SPEC v2 contract freeze**: document the final CityPlan producer contract as
   built — both sources, the town-key mechanism, the goldens table (synthetic/melbourne/
   katoomba + how to pin a new one), the normalization rules the osm importer applies,
   the openLate/hours/storeys laws. This becomes the reference for the v3 epoch (the
   editor/override layer reads THIS contract).
2. **Recipe sanity**: dry-run your own "add a town" recipe against the doc (don't ship a
   third town unless it falls out for free — if it does, pin its golden and tell F).
3. **On-call** for D's patronage/occupancy questions (shop doors, hours edge cases —
   e.g. what happens to occupants at closing time; give D a ruling and document it).

**Acceptance**: CITY_SPEC v2 section complete + matches reality (F will diff claims vs
code in review); closing-time ruling documented; qa green.

## Lane B (Streetscape) — the tram (non-blocking) + tour poses

1. **`?tram=1`** (decision #3): one instanced tram/small bus, seeded main-street loop
   over your bus_shelter stops, door-pause dwell at each stop, bell-ready (no audio yet).
   Deterministic (same seed → same schedule), budget ≤2 draws, composes with weather/
   night (headlights at night if cheap). Flag-off identical. It slipping does NOT block
   v2.0 — commit partial + cut line if needed.
2. **v2 tour bookmarks** (F shoots this round — do early): add named poses for the new
   life — `rain_verandah` (rain through a lit winmap window), `patronage_door` (peds at a
   shop door), `dig_real` (a bin of real covers), `katoomba_main` (2nd town), `tram_stop`
   (if tram lands), plus your judgment for 2–3 more. Verify via `shots.py`.
3. **Weather polish debt** (only if quick): any visual nits from your own R8 notes.

**Acceptance**: tram loops deterministically under budget (or documented cut); tour poses
live + un-letterboxed; qa green.

## Lane C (Interiors) — browse points + buy-anywhere

1. **C1 — browse points (DO FIRST — D and F build on it).** Room API: 1–3 seeded browse
   points per room (position + facing, aisle-adjacent, never blocking the door or the
   counter), exposed like the keeper's counter spot. Deterministic per shop.seed; works
   in every archetype (drawSweep proves no collisions with fittings). Document the
   interface in LANE_C_NOTES *first* (decision #1 handshake).
2. **C2 — buy-anywhere (decision #2):** aiming at a real-stock spine/box on book/toy
   shelves raises the pull-out card (title/artist-or-maker/price from the pack index);
   BUY debits the wallet, removes the item from the shelf (your batched-stock
   addressability from R6 — same trick as dug bins), adds to inventory. Parody stock =
   not buyable (card shows "not for sale" or simply no card — your call, document it).
   Fail-soft, deterministic, leak-free, ≤350 draws; extend the soak to buy 1 shelf item
   per room type.
3. **Support F1**: when browsers spawn at your points, verify keeper/stock/dig all still
   compose in a room WITH browsers (the soak covers it).

**Acceptance**: browse points in every archetype, documented, D/F consuming; shelf
buying works end-to-end with the wallet; soaks green; ≤350; qa green.

## Lane D (Citizens) — occupancy truth + browsers inside

1. **D1 — occupancy + browser rigs (after C1's interface note).** Track per-shop
   occupancy from patronage (who ducked in: identity seed + entry time + seeded dwell).
   When the player enters an occupied shop, browser rigs (fleet clones, KeeperManager-
   style lifecycle — the leak-proven pattern) stand/idle at C's browse points, matching
   occupancy count (cap 3, decision #1). They exit on dwell-expiry (walk-out tell if
   cheap, despawn otherwise); at closing time follow A's ruling. Deterministic: same
   seed + same time → same occupants. Leak-free over N enter/exit cycles (extend your
   soak). Coordinate the F-facing handoff shape (occupancy query per shopId) in NOTES.
2. **D2 — street↔interior consistency tells**: the ped who ducked in shouldn't ALSO be
   visible on the street (your despawn already handles it); re-emergence spawns at the
   door. Verify with patronage + occupancy both on.
3. Budget: browsers ride the interior ≤350 law (C's sweep with browsers on proves it).

**Acceptance**: follow a ped into a shop and find them browsing; count matches
occupancy; deterministic + leak-free + ≤350 with browsers; closing-time behavior per A's
ruling; qa green.

## Lane E (Assets) — the VRAM/texture audit + on-call

1. **E1 — memory audit (the ship-round due diligence).** Nobody has measured total
   texture/VRAM weight since the packs landed. Audit: all atlases (3 stock packs), skins,
   facade atlas, ped fleet, GLB textures — sizes on disk + estimated GPU memory + what's
   resident in a default boot vs `?stock=real` boot vs worst case (all flags). Numbers in
   AUDIT.md + a one-para verdict (fine / needs compression pass / needs lazy-load).
   If a cheap win exists (e.g. a pack atlas that should be WebP/half-res), take it —
   bigger restructuring gets flagged for v3, not done now.
2. **E2 — depot + manifest hygiene**: `validate --depot` + pack-QA + provenance-drift all
   green post-R8 (they should be — confirm); prune any orphaned depot files your audit
   finds (list first in NOTES, delete only your own procity_* uploads).
3. **On-call**: B may want a tram texture/GLB (procedural/primitive first — a box tram
   with the right silhouette beats a heavy model; flux/local gen only if it truly reads
   wrong); C may want a "browse pose" check on fleet clips (that's D's domain — redirect).

**Acceptance**: audit published with numbers + verdict; cheap wins taken; depot hygiene
confirmed; qa green.

## Lane F (Integration) — graduate, shoot, freeze, tag

1. **F1 — interior-presence wiring (after C1+D1):** occupancy query → interior build →
   browser spawn at browse points; smoke at warn (enter occupied shop, assert browser
   count > 0 matching occupancy, 0 errors, dispose clean on exit).
2. **F2 — graduate round-8 smokes to strict**: buy-v0, patronage, book/toy stock,
   katoomba golden. New this round at warn: interior presence, shelf-buy, tram (if B
   lands). Everything green before F3.
3. **F3 — the v2 tour + full-defaults soak**: re-shoot `docs/shots/v2_tour/` (12 shots:
   B's new poses + the classics re-taken on current defaults — busy street, rain money
   shot, dig with real covers, browsers in a shop, katoomba, night video-shop crowd,
   tram if landed) + contact sheet. Full soak on pure defaults (no flags) + the all-on
   combo; both leak-free, 0 errors.
4. **F4 — docs freeze + tag `v2.0`** (decision #6): runbook gate table updated to the v2
   reality; flags table final (what's default, what's flagged, what graduated);
   README/CITY_SPEC claims match code (diff A's contract freeze vs reality as part of
   review); F-progress round-9 section. Tag with a proper epoch summary. Local tag —
   John pushes (the push pattern is proven now).
5. **Marshal**: C1 is the round's single point of failure (two lanes build on it) —
   check for its commit early; if C stalls, escalate in F-progress immediately.

**Acceptance**: presence wired + smoked; all r8 smokes strict; tour + soaks green;
docs frozen; `v2.0` tagged on an all-green tree.

---

*— Fable (integrator). Nine rounds from empty repo to this: a seed becomes a town where
it rains, the crowd shops, and you can follow someone into a record store, flip past
three hundred real sleeves, and buy one. Round 9 makes that official. Commit atomically,
pin your refs, leave it green.*