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 added 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.