PROCITY/docs/LANES/ROUND18_INSTRUCTIONS.md

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