From 130c183910dd8f9e88ccf2eb5666efbbde386b94 Mon Sep 17 00:00:00 2001 From: m3ultra Date: Tue, 14 Jul 2026 20:32:48 +1000 Subject: [PATCH] =?UTF-8?q?Fable=20(integrator):=20round-5=20lane=20instru?= =?UTF-8?q?ctions=20=E2=80=94=20v1.1=20close-out=20+=20v2=20foundations=20?= =?UTF-8?q?behind=20flags?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Fable 5 --- docs/LANES/ROUND5_INSTRUCTIONS.md | 235 ++++++++++++++++++++++++++++++ 1 file changed, 235 insertions(+) create mode 100644 docs/LANES/ROUND5_INSTRUCTIONS.md diff --git a/docs/LANES/ROUND5_INSTRUCTIONS.md b/docs/LANES/ROUND5_INSTRUCTIONS.md new file mode 100644 index 0000000..93844e8 --- /dev/null +++ b/docs/LANES/ROUND5_INSTRUCTIONS.md @@ -0,0 +1,235 @@ +# PROCITY — Round 5 lane instructions (from Fable, integrator) + +Date: 2026-07-14 · Written after **v1.0 tagged** (`2698b40`, all 6 QA gates green, 6-auditor +GO). You are an Opus 4.8 agent assigned ONE lane (read your session prompt). Read this file, +your `docs/LANES/LANE__*.md` spec, your `-progress.md`, `docs/V2_IDEAS.md`, and any +NOTES addressed to you before touching code. + +Repo state: everything committed on `main` at `2698b40` = `v1.0`. `tools/qa.sh --strict` +GREEN 4/4 (selfcheck 1301/1301, fingerprint `0x3fa36874`, consistency 0 warnings, manifest +`--depot` 0 errors, 23 GLBs live). Tag is local; pushing is John's. + +## Theme: v1.1 close-out + v2 foundations + +v1 shipped: seed → walkable 90s-AU town, every door opens, keepers, crowds, hours, day/night. +Round 5 does two things at once: + +1. **v1.1 (small, this week's polish):** land the ONE v1 loose end — Lane C re-maps the two + assets Lane E shipped late in R4 (`record_crate` fixed, `counter_till` new) — plus the + hero-prop lowpoly bake. F tags `v1.1`. +2. **v2 foundations (the real round):** each lane starts its highest-leverage V2_IDEAS item, + **behind a flag, default-off**. The parking-lot doc was written so v2 is wiring, not + rework — this round proves that. + +## The v2 prime law (read twice) + +**Default boot must stay v1-identical.** Every v2 feature lands behind a query flag or config +default-off. `GOLDEN.hash` (`0x3fa36874`) must not move unless Lane A intentionally versions +it (it should not this round). `qa.sh --strict` green at every commit. If your feature is on +and something breaks, that's your bug; if your feature is OFF and anything changes, that's a +land-blocker. + +## Integrator decisions (so nobody blocks) + +1. **v2 starts with the content firehose** (V2_IDEAS #1): Lane C ports `dig.js` (the + crate-riffle interaction) running on the EXISTING procedural stock via the `stockAdapter` + seam. Real GODVERSE/BaseGod stock + economy is round 6+ — do NOT wire external databases + or thriftgod's `mint()` this round. +2. **Hero-prop bake-to-lowpoly is UN-PARKED** (was decision R4#2). Lane C's measurements + (record interior ~273k tris; `drinks_fridge` 77k, `counter_till` 32k) justify it. Lane E + bakes: target **≤8k tris per hero prop** with baked base-colour (bake THEN simplify — + R3 taught us raw TRELLIS shell-soup won't simplify; a voxel-remesh + texture re-bake will). +3. **OSM plan import uses cached/fixture data ONLY.** Lane A builds the second plan source + against thriftgod's `city_source.json` cache (or a checked-in fixture extract). NO live + Overpass/network calls from the repo — the asset-free/zero-network law extends to citygen. +4. **fal.ai spend (glass-case/bus-shelter) stays parked; pushing stays John's.** Audio stays + greenfield-parked (needs an asset-sourcing decision from John). +5. **v1.1 tag**: Lane F tags after C1 (re-map) and E1 (bake) land and the tour still looks + right. v2 flags do NOT need to be done for v1.1. + +## Process rules (unchanged — agents run concurrently) + +- ONE shared working tree. `git status` first; stage **only your files by exact path**; + options before `--` in `git commit`; `add` new files first; commit immediately; pin a + durable ref (`git branch lane-/round5-` / tag). +- Leave `qa.sh --strict` GREEN. Update `-progress.md`; cross-lane asks go in your + NOTES file, not in others' code. F owns `web/index.html` + `tools/` seams — document your + call sites for F instead of editing (the D→F setExposure pattern from R3/R4). +- `procityprogress.txt` / `settings.local.json` stay untracked; don't commit them. +- Real repo path `/Users/m3ultra/Documents/procity`. Source repos for ports: + `~/Documents/90sDJsim` (dig.js), `~/Documents/thriftgod` (city_source/plan import), + `~/Documents/dealgod/GODVERSE.md` (read-only reference this round). + +## Sequencing + +``` +C1 (re-map counter_till + record_crate) ─┐ +E1 (hero-prop bake ≤8k) ──→ C verifies ─┼─→ F1 (tag v1.1) + │ +A2 (plan-source seam) · B2 (window shader) · C2 (dig.js) · D2 (streamed roster) · E2 (depot grow) + └────────── all behind flags ─────────→ F2 (v2 smoke + runbook) +``` +C1 is quick — do it first so F can tag v1.1 early. All v2 items are parallel and independent. + +--- + +## Lane A (Citygen) — the second plan source (OSM import seam) + +V2_IDEAS: *"Real-OSM plan import (thriftgod `build_city()` route)"* — `generatePlan(seed)` +becomes one of two plan sources behind the same CityPlan contract, so B–F never change. + +1. **Extract the contract.** Define/verify a single `CityPlan` producer interface (whatever + `generatePlan` returns IS the contract — document its exact shape in CITY_SPEC if not + already precise: nodes/edges/blocks/lots/shops/registry fields, hours, openLate, seeds). + Add a `planSource` selector: default `'synthetic'` (today's path, byte-identical output — + golden hash law), new `'osm'` behind `?plansrc=osm`. +2. **Build the OSM source.** Port the relevant parts of thriftgod `server.py:433 build_city()`: + read a **checked-in fixture** extracted from thriftgod's `city_source.json` cache (pick one + real AU town's worth of shops, a few hundred max — commit the fixture under + `web/assets/fixtures/` or `tools/fixtures/`), then dedupe → suburb inference → parody + names → seeded hours → emit a valid CityPlan. Deterministic: same fixture + seed → same + plan (hash it). +3. **Prove it downstream.** Boot the shell with `?plansrc=osm`: streets stream, doors open, + interiors build, selfcheck-style invariants hold (write an osm-mode selfcheck variant or + parameterize `selfcheck.js` by source — do NOT touch the synthetic golden hash). Screenshot + the imported town for docs. +4. Document the seam in LANE_A_NOTES for F's determinism-gate extension (F2). + +**Acceptance**: default boot byte-identical (golden `0x3fa36874` untouched); `?plansrc=osm` +boots a real-data town end-to-end with invariants green; fixture committed, zero network; +qa green. + +## Lane B (Streetscape) — the Vuntra window trick (interior-mapping shader) + +V2_IDEAS: *"parallax interior-mapping shader so a passing pedestrian sees a plausible room +through the glass without building it."* You own the facade glass + atlas — this is yours. + +1. **Interior-mapping shader** on shop window glass, behind `?winmap=1`: classic + single-cube parallax interior mapping (seeded per-shop room: wall/floor colours from the + shop's skin palette, a couple of shelf silhouettes). Must respect §3.5: **closed shops at + night show dark rooms** (reuse `window.PROCITY.isOpen`); open shops glow warm. +2. **Keep it batched.** One shader/material on the existing glass geometry (or a clone at the + same draw count) — per-instance variation via attributes/uniforms, NOT per-shop materials. + Re-measure worst continuous-walk view with citizens: **≤300 draws** flag-on. +3. **Determinism + fallback**: seeded from `shop.seed`; flag-off path byte-identical to v1 + (same materials, same draws). `?noassets=1` + winmap must not fetch anything (procedural + only). +4. Screenshot day + night (open vs closed) → `docs/shots/laneB/` for the v2 gallery. + +**Acceptance**: flag-off identical to v1; flag-on ≤300 draws worst view, rooms visible +through glass with parallax, closed shops dark at night; zero fetches; qa green. + +## Lane C (Interiors) — v1.1 re-map, then the dig + +1. **v1.1 re-map (DO FIRST — F tags v1.1 on it).** Lane E's R4 late shipment + (LANE_E_NOTES → Lane C): + - `record_crate` is FIXED (sourceless-texture slots stripped; verified loading in the + vendored GLTFLoader). Your `crate`/`recordBin` mapping already points at it — remove the + "fails to load" fail-soft comment, verify the bins actually upgrade now. + - `counter_till` is NEW (`procity_fit_counter_till_01.glb`, 1.61×0.64 m, 1.15 m tall, + base-origin): **re-add `counter` → `'counter_till'`** to `KIND_TO_GLB` (NOT the old 4 m + `counter`/balcao). Decide what happens to your separate `cash_register` counter-top + attach on counters that now have a modelled till — avoid double tills (keep + cash_register for shop types where it reads better, or drop the attach when the GLB + counter is live; your call, document it). + - Keeper stand pose must still work on the GLB counter (the counter contract). + - Re-run sweep + soak (same bar: 0 throws/leaks, <50 ms), update the contact sheet, + commit → tell F (v1.1). +2. **Port `dig.js` — the crate riffle (v2 headline, behind `?dig=1`).** Source: + `~/Documents/90sDJsim/web/world/dig.js` (self-contained, `onBuy/getCash/spawnClerk/ + spawnFittings` callback API, ported across 3 games before). Scope for this round: + - Walk to a record bin in a record store → riffle interaction (flip through sleeves) using + the EXISTING procedural stock via your `stockAdapter(shop, slotKind)` seam — the sleeves + you already generate become the riffled items. Seeded order per bin. + - Buy/economy: STUB it (a toast + remove-from-bin is fine; `getCash` returns a constant). + Real stock/economy is round 6+ (integrator decision #1). + - Keep it interior-mode-only and leak-free: entering/leaving the dig disposes cleanly + (extend your soak to enter a dig per interior when the flag is on). + - F owns the input/mode seam in the shell — document the exact hook you need + (e.g. `interiorMode.onInteract(fitting)`) in LANE_C notes; F wires it (F2). Build against + your test page in the meantime. +3. Re-measure the record interior after E1's baked props land (was ~273k tris) — record the + new number in LANE_C_GLB_VALIDATION.md. + +**Acceptance**: C1 committed early, bins + counter GLB-live, no double till, soak green → +F tags v1.1; `?dig=1` riffles a real bin on procedural stock, leak-free, flag-off identical; +qa green. + +## Lane D (Citizens) — implement the chunk-streamed roster + +Your R3 design note (LANE_D_NOTES) was design-only by instruction. v2 un-parks it: implement, +behind `?roster=stream`. + +1. **Implement per your own design**: chunk-local identity keying (same seed + chunk → same + residents), windowed spawn/despawn driven by Lane B's `ctx.onChunkBuilt/onChunkDisposed` + hooks (they exist — B shipped them in R2), global near-cap across live chunks, ownership + hand-off, and the v1 path untouched when the flag is off. +2. **Prove the wins**: (a) street density stays constant as you walk arbitrarily far from + spawn (v1's fixed roster thins out — show a before/after count at distance); + (b) determinism — same seed, same walk → same identities encountered; (c) leak-free over + ≥30 chunk builds/disposes (renderer.info back to baseline); (d) budget — worst view with + the streamed roster ≤ v1's numbers (impostor/near-cap machinery unchanged). +3. **Hours-aware density (small, if time allows)**: streamed spawns read the day fraction the + way v1 does; optionally bias spawn weights toward open shops at night (the queue/patronage + sim stays v2-later — don't build schedules this round). +4. Document the flag + any shell call-site change for F in LANE_D_NOTES (F wires index.html). + +**Acceptance**: flag-off identical to v1 (determinism + golden identities); flag-on constant +far-field density, deterministic, leak-free, within budget; design note updated to as-built; +qa green. + +## Lane E (Assets) — the bake pass + depot growth + +1. **Hero-prop bake-to-lowpoly (un-parked, DO FIRST — C re-measures on it).** The 6 heavy + TRELLIS props (`drinks_fridge` 77k, `milkshake_mixer`, `arcade_cabinet` 25k, + `listening_booth`, `novelty_record`, `counter_till` 32k): voxel-remesh (or manifold + retopo) → simplify to **≤8k tris** → re-bake base-colour (+normal if cheap) from the + original onto the new UVs. R3's lesson stands: simplify-only won't work on shell-soup; + the re-bake is the point. Pipeline it (`pipeline/bake_lowpoly.py` or a Blender headless + script) so it's repeatable; keep originals in a gitignored dir; record before/after in + AUDIT.md. Eyeball every prop (no melted labels/faces) → contact sheet. Re-publish to the + depot; `validate --depot` 0 errors. Tell C to re-measure. +2. **Depot growth for v2 (second priority).** From `~/Documents/3D=models/` pick a shortlist + (~8–12) that serves this round's v2 features — dig-scene props (crate variants, price-gun, + listening-station headphones), street-life props for D's roster (shopping bags, prams), + B's window-room silhouettes if any read better as real minis. Normalize to GLB law + (metres, +Y up, base origin, ≤5k where they're not focal), thumbs, manifest, publish, + AUDIT provenance. Do NOT add manifest entries no lane consumes — check the other lanes' + round-5 notes or ask in yours. +3. **Not doing** (still parked): fal.ai spend, MESHGOD_BATCH full run, audio assets. + +**Acceptance**: 6 hero props ≤8k tris with baked textures live on the depot, visually clean, +C's interior re-measure confirms the drop; new shortlist normalized + published with +consumers identified; validate --depot 0 errors; qa green. + +## Lane F (Integration) — v1.1 tag, v2 seams, gates that grow + +1. **Tag v1.1** once C1 + E1 land: verify the record/milkbar/opshop interiors live (GLB + counter + till story correct, bins upgraded, baked props look right), re-capture ONLY the + two interior tour shots if visibly improved, qa green → `git tag v1.1` (local; John + pushes). +2. **Wire the v2 flag seams** as lanes document them (you own `web/index.html` + `tools/`): + A's `?plansrc=`, B's `?winmap=`, C's `?dig=1` interact hook (this one is real work — the + interior-mode input seam; C specifies, you own the mode state machine), D's + `?roster=stream`. Keep every flag default-off and independent. +3. **Extend the QA harness for v2** (V2_IDEAS "determinism across engines"): + - determinism gate: pin plan-hash + first-interior-hash per (seed, plansrc) — synthetic + stays `0x3fa36874`; add the osm fixture hash when A lands. + - a **flags-off regression check**: boot with no flags, assert plan hash + a settled + draws/tris snapshot within tolerance of v1 numbers (catches "my flag leaks when off"). + - a v2 smoke: boot each flag on, walk 2 chunks, enter 1 interior (+1 dig if C landed), + 0 console errors. Wire into qa.sh as a non-strict (warning) gate this round; strict + next round. +4. **Runbook**: add a §v2 flags table (flag → owner → state → smoke result) to LANE_F_NOTES; + archive the R3/R4 instruction files' "current" claims (one line at top: superseded by R5). +5. Ongoing: shared-tree marshal — if two lanes collide on a file, you arbitrate. + +**Acceptance**: v1.1 tagged on a green tree; all landed v2 flags wired, independent, +default-off proven by the flags-off regression check; v2 smoke running in qa.sh (warn-level); +runbook current. + +--- + +*— Fable (integrator). The four hinges (stockAdapter, plan-source contract, shop.seed law, +B's mode machine) are now load-bearing — if your task fights one of them, stop and leave me a +note instead of bending it. Commit atomically, pin your refs, leave it green.*