Fable (integrator): round-5 lane instructions — v1.1 close-out + v2 foundations behind flags
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
m3ultra
parent
2698b402d1
commit
130c183910
235
docs/LANES/ROUND5_INSTRUCTIONS.md
Normal file
235
docs/LANES/ROUND5_INSTRUCTIONS.md
Normal file
@ -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_<X>_*.md` spec, your `<X>-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-<x>/round5-<topic>` / tag).
|
||||
- Leave `qa.sh --strict` GREEN. Update `<X>-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.*
|
||||
Loading…
Reference in New Issue
Block a user