diff --git a/docs/LANES/ROUND18_INSTRUCTIONS.md b/docs/LANES/ROUND18_INSTRUCTIONS.md new file mode 100644 index 0000000..0aa3222 --- /dev/null +++ b/docs/LANES/ROUND18_INSTRUCTIONS.md @@ -0,0 +1,84 @@ +# PROCITY — Round 18 lane instructions (from Fable, integrator) + +Date: 2026-07-16 · **v3.2 SHIPPED** (tag on origin, town matrix 10×5 green). R17 review, short +version: the tail is DRAINED — wind sway shipped after ten rounds parked (and the park reason +turned out to be a phantom: the tree material was B's own all along — measurement over folklore), +D's drummer leans into the kit and street peds sit on verandah steps (with a genuine finding en +route: the seated re-plant was scale-naive and had to become scale-aware for per-citizen-scaled +rigs), C closed the backline handshake AND proactively proved 18 real OSM shop types build valid +interiors, E's 5-town pipeline is deterministic and ODbL-clean, A hardened `plan_osm` against +2,828 real Canberra shops and handed the charter its risk list, F closed the last integration gap +(the shell never loaded the caches — the classic A-publishes/F-wires seam) and gated the whole +matrix. Every lane at full quality. The scout did its job: **John chartered v4 = THE REAL MAP.** + +**Read the charter first: [docs/V4_REAL_MAP.md](../V4_REAL_MAP.md).** Round 18 is +**v4.0-alpha: REAL ROADS** — one town (`katoomba_real`) gets its actual street geometry. The whole +alpha exists to surface what irregular real geometry breaks downstream. Tag **`v4.0-alpha`** at +close. + +## The ledger + +1. **Cache schema v2 — `roads[]` (A publishes FIRST, E builds to it).** The town cache grows an + optional `roads[]` (OSM way geometry, simplified): A defines the shape (suggested: polylines of + `{lat,lon}` points + a `kind` from the OSM `highway=*` class), bumps `schema` to + `procity-town-cache/2`, extends `validateTownCache` (v1 caches stay valid — roads absent ⇒ the + marched fallback, so nothing shipped regresses). +2. **Real road graph in the plan (A — the epoch's headline lift).** `plan_osm` consumes `roads[]`: + project to the local metre frame, simplify (Douglas-Peucker or your pick — you own the fidelity + knob, charter risk #4), build the CityPlan street graph from real topology (nodes at real + intersections, straight-segment edges), classify main/side from the OSM `highway` kind + shop + density, seat each shop's lot on its nearest real edge at its real position/side. SAME CityPlan + schema out — B/C/D/F consume it unchanged by contract. Golden per the amendment law + (`katoomba_real`'s re-pins; synthetic + fixtures untouched). District placement (`pickVenues`) + must still land 2–4 venues on the real graph. +3. **Roads fetch (E).** Extend `build_towns.py`: per-town bounded `highway=*` Overpass query + (same authorization + raw-cache discipline as R17 — commit the raw response, fetch once), + emit `roads[]` per A's v2 contract. **`katoomba_real` first** (the alpha town), then the other + four as data-only commits (A hardens against them as they land; only katoomba gates the round). +4. **Irregular-geometry audit (B — charter risk #3, the alpha's real risk).** Boot + `katoomba_real` with real roads and hunt what breaks: chunk streaming over a non-grid graph, + building/lot seating at acute intersections, footpath/verge furniture cadence on short or + curved-ish edge chains, tram (its loop assumes a spine — if the real graph breaks it, fence it: + tram disabled on roads-towns is an acceptable alpha fence, written down). Fix what's yours, + file what's A's (lot geometry) or D's (sim graph) with measurements. +5. **Citizens on real bones (D).** The sim walks the street graph + chunk-streamed rosters on the + real topology: verify walkers navigate real intersections, loiter/bench-sit/patronage behave, + identity + determinism hold on `katoomba_real`. Cheap if the graph contract really is the + contract — prove it, and file what leaks with measurements. +6. **Interior spot-soak on the alpha town (C — small).** Your R17 type-fallback proof covered + types; now enter every `katoomba_real` shop in-shell (20 doors), assert valid interiors, no + carve fails, budgets. One table. Otherwise on-call. +7. **The alpha gate (F, last).** Extend the town matrix with a roads dimension (`katoomba_real` + boots real-roads: boot/determinism/budget/district/noassets-fallback green); the classic + + default-boot gates prove the alpha changed nothing outside the flagged path; a first + real-street money shot (Katoomba main street, default flags, settled) into + `docs/shots/v4_alpha/`; docs (README gets a "real towns" paragraph, LANE_F_NOTES §18); tag + **`v4.0-alpha`**, push (standing authorization). + +## Laws for the round + +Everything in the charter's law section. Alpha-specific: real roads ride the **cache schema**, not +a URL flag (a v2 cache with roads = real roads; v1 = marched fallback — no new flag surface); +default + classic boots are untouched by construction (they never load a town cache); budgets +measured on `katoomba_real`'s busiest real block; every irregular-geometry failure gets WRITTEN +DOWN (fixed or fenced) — the alpha's deliverable is as much the failure list as the town. + +## Order + +**A first** (schema v2 contract — half-day rule), **E immediately after** (katoomba roads cache; +the other towns trail). Then **A again** (the graph lift, against real data), with **B + D + C** +auditing in parallel as soon as A's roads-plan boots (A→B/D/C handshake: "katoomba_real boots with +real roads, golden pinned"). **F last.** This round has a real serial spine (A→E→A→others→F) — +expect A to be the long pole; B/D/C, if you're blocked on A, your audit prep (test scaffolding, +assertion lists) is not. + +## Standing + +- **John — nothing blocks this round.** FYI: E's roads fetch rides your R17 Overpass + authorization (same API, same once-per-town + raw-cache discipline). The alpha hero town is + `katoomba_real` — if you'd rather see a different town first (Newtown/Fremantle/Bendigo/ + Castlemaine), say so before E starts. +- **v4.0-beta preview (next round, do not start):** all five towns on real roads · the town + selector UI (B) · districts/gigs proven per-town · tram ruling on real graphs. +- **Backlog (unchanged):** instrument LOD · tram tri diet · audioEmitter · flag retirement · + awning-canopy ripple (B's R17 note) · editor · multiplayer presence. diff --git a/docs/V4_REAL_MAP.md b/docs/V4_REAL_MAP.md new file mode 100644 index 0000000..4c75c9e --- /dev/null +++ b/docs/V4_REAL_MAP.md @@ -0,0 +1,52 @@ +# PROCITY v4 — THE REAL MAP (epoch charter) + +*Fable, 2026-07-16. John's pick (R17 kickoff). Grounded in the R17 scout: 5 real AU town caches +boot through the full gate matrix — deterministic, in-budget, districts place, `?noassets` silent. +The existing CityPlan contract eats real shop data. What it does NOT yet eat is real geography: +`plan_osm` marches real shops onto synthesized parallel avenues. v4 closes that gap.* + +## The vision + +**Walk the actual main street of a real Australian town.** Katoomba's real high street with its +real secondhand shops in their real order, PROCITY's stylized look (this is not photorealism — +the *town* is real, the *rendering* is PROCITY), the gig district, the citizens, the dig, the +weather — everything shipped, on real bones. The default boot stays the synthetic town; real +towns are a destination you pick. + +## The stages + +- **v4.0-alpha (R18): REAL ROADS, one town.** Real OSM street geometry (simplified to the + CityPlan edge schema — straight segments, real topology) for `katoomba_real`, shops seated + along their real streets, everything downstream unchanged by contract. Opt-in via the town + cache (schema v2 carries `roads[]`; caches without roads keep the marched fallback). +- **v4.0-beta: the district on real bones, five towns.** All scouted towns get roads; venues, + posters, queue, tram(?), citizens proven on irregular graphs; the town selector (B) so a player + can pick a town without URL surgery. +- **v4.0: the town pack + the tour.** A curated pack (~15–25 towns, E's bbox discipline), the + release tour shot on real streets, docs, tag. Default boot still synthetic; flag-flip for real + towns is a v4.x decision AFTER soak (the v3 pattern, proven twice). + +## The laws (inherited, plus two new) + +Classic covenant untouched (`?classic=1` byte-identical forever) · default boot untouched through +alpha/beta (real towns opt-in) · determinism from (town, citySeed) · budgets unchanged (≤300/200k +street, ≤350 interior) · asset law (cache fetch fail-soft; `?noassets` falls back to fixtures) · +amendment law for goldens · atomic pathspec commits · measurement over brief. + +**New — the bbox law (A's R17 risk #1):** a town cache is ONE compact town (span ≤ 5 km, +validator-enforced); town *selection* discipline lives in E's pipeline, because the generator +cannot rescue an over-broad query. **New — the ODbL law:** every cache ships +`license`/`attribution` + `SOURCES.md`; raw Overpass responses are committed so re-runs never +re-fetch; only public POI/way data, never private-individual data. + +## The risk list (from the R17 scout, kept current) + +1. Mega-strip / over-broad bbox — mitigated by the bbox law; watch per-town. +2. Sparse towns (< 6 shops) — curation floor; `MIN_TOWN_SHOPS` enforced. +3. **NEW, the alpha's real risk: irregular geometry downstream.** B's chunks/buildings/furniture + and D's sim have only ever seen A's synthetic graphs and the marched-avenue osm towns. + Non-grid intersections, acute angles, short edges, dead ends — the alpha exists to surface + exactly these. Every failure gets written down, fixed or fenced. +4. Road simplification fidelity — too coarse reads wrong, too fine costs edges; A owns the knob. +5. Settled non-risks: facade clearance on osm towns (R17), interior types (C proved 18 real + `shop=` values degrade cleanly), plan-side determinism (E's pipeline is byte-identical re-run).