{
  "project": "Infrastruct — Project Metropolis",
  "updated": "2026-08-12",
  "current_phase": 1,
  "overall_progress_pct": 14,
  "document": {
    "version": "1.0",
    "pages": 232,
    "size": "1.2 MB",
    "built": "2026-08-12",
    "contents": [
      {
        "part": "I",
        "title": "Foundations",
        "detail": " — the thesis, the north star, the phase roadmap, the budget ledger, risks and phase gates."
      },
      {
        "part": "II",
        "title": "Agent architecture",
        "detail": " — the 13-agent roster, verbatim system prompts, orchestration, handoff and escalation protocol."
      },
      {
        "part": "III",
        "title": "Architecture decisions",
        "detail": " — ADR-001 to ADR-008: engine, data model, road network, routing, traffic, rendering, determinism, zoning."
      },
      {
        "part": "IV",
        "title": "Phase 1 — build plan",
        "detail": " — step-by-step tasks with acceptance criteria and the AI prompt for each step."
      },
      {
        "part": "V",
        "title": "Research dossiers",
        "detail": " — citation-backed surveys: traffic models, pathfinding, DOTS, road geometry, prior art."
      }
    ]
  },
  "phases": [
    {
      "id": 0,
      "name": "Preflight",
      "theme": "Toolchain · harnesses · decision records",
      "status": "active",
      "goal": "Make the project measurable and reversible before any gameplay exists. Nothing here is a feature; everything here is the apparatus that stops later phases from lying to us about performance and correctness.",
      "delivers": [
        "Repo scaffold, asmdef layer graph, pinned Unity + package manifest",
        "CI: compile, edit-mode tests, play-mode tests, headless run",
        "Benchmark harness with a scene corpus and machine-normalised reporting",
        "Determinism harness: record/replay, canonical world hashing, divergence bisection",
        "ADR-001 (engine) and ADR-002 (data model) accepted",
        "Empty DOTS world driving 1M dummy entities in a Bursted job"
      ],
      "exit": [
        "One command builds, tests, replays and benchmarks headlessly",
        "1M trivial entities update in under 1.0 ms/tick, 0 managed allocations per frame",
        "Two replays of a recorded session hash identically on two machines"
      ],
      "remains": [
        "Everything that is a game"
      ],
      "targets": {
        "entities": "1M",
        "tick": "<1.0 ms",
        "alloc": "0 B/frame"
      }
    },
    {
      "id": 1,
      "name": "Playable Prototype",
      "theme": "Roads · zoning · buildings · rudimentary traffic",
      "status": "detailed",
      "goal": "Prove the hard architecture — lane-level networks, cheap rerouting, agent LOD, instanced rendering — on a small map with a real play loop: draw roads, zone land, buildings appear, traffic flows between them. This is a load-bearing prototype, not a demo.",
      "delivers": [
        "Lane-level road network: nodes, segments, lanes, automatic junction geometry",
        "Derived lane-to-lane connections with player override",
        "Road draw / curve / bulldoze tools with previews and undo",
        "Zone painting, block detection, lot subdivision, demand-driven buildings",
        "Vehicles with real routes, IDM car-following, MOBIL lane changes",
        "Max-Pressure intersection control",
        "Instanced rendering with a numeric LOD ladder",
        "Budgets, profiler markers, determinism replay, conservation tests"
      ],
      "exit": [
        "1 km² map, ≥2 000 segments, ≥20 000 buildings, ≥10 000 vehicles",
        "≥60 FPS median, ≤20 ms p99 on the reference machine",
        "Simulation ≤8.0 ms/tick (half the eventual budget)",
        "≥500 route queries/s; full re-weighting ≤20 ms; zero despawns",
        "10 000-tick replay hash-identical across 3 runs and 2 machines",
        "Fundamental diagram reproduced within 15% of published values",
        "Degenerate-city corpus runs without crash, deadlock or budget breach"
      ],
      "remains": [
        "The 10k → 250k vehicle scale jump (all of Phase 2)",
        "Citizens as individuals",
        "Money, services, utilities, transit",
        "Terrain, weather, audio, art quality"
      ],
      "targets": {
        "area": "1 km²",
        "vehicles": "10k",
        "buildings": "20k",
        "fps": "60"
      }
    },
    {
      "id": 2,
      "name": "Scale & Routing Core",
      "theme": "Hierarchical routing · agent LOD · real intersections",
      "status": "outlined",
      "goal": "The 25× scale jump. This is where the two headline technical bets — cheap rerouting and flat frame time — are actually won or lost.",
      "delivers": [
        "Production CCH routing: metric-independent preprocessing, parallel customisation",
        "Incremental repair on network edit; stochastic route choice to prevent herding",
        "Full micro/meso/macro agent ladder with conservation guarantees",
        "Priority junctions, gap acceptance, roundabouts, gridlock relief",
        "Road hierarchy: highways, ramps, arterials, one-ways, elevated roads",
        "Congestion feedback re-weighting the routing metric on a fixed cadence",
        "Chunked world streaming for 25 km²"
      ],
      "exit": [
        "250k vehicles at 60 FPS",
        "≥20 000 route queries/s; customisation ≤50 ms off-thread",
        "Zero despawns; jams form, propagate and dissolve realistically",
        "Determinism holds at full scale"
      ],
      "remains": [
        "A traffic simulator with buildings — no citizens, money or services yet"
      ],
      "targets": {
        "area": "25 km²",
        "vehicles": "250k",
        "queries": "20k/s"
      }
    },
    {
      "id": 3,
      "name": "Citizens & Demand",
      "theme": "Households · jobs · activity chains · mode choice",
      "status": "outlined",
      "goal": "Replace synthetic trip generation with a million individuals whose daily activity chains produce the traffic.",
      "delivers": [
        "Households, individuals, jobs, schools, ages, life events",
        "Activity-based demand replacing the aggregate four-step model",
        "Discrete-choice (logit) destination and departure-time choice",
        "Mode choice with per-mode disutility",
        "Citizen fidelity ladder mirroring the vehicle ladder",
        "Pedestrian movement on sidewalks and crossings"
      ],
      "exit": [
        "1M citizens with coherent daily patterns",
        "Peak hours emerge from behaviour, not from a curve",
        "≤2.5 ms/tick; every trip attributable to a named citizen and reason"
      ],
      "remains": [
        "No services and no money — citizens live in a city without consequences"
      ],
      "targets": {
        "citizens": "1M",
        "tick": "≤2.5 ms"
      }
    },
    {
      "id": 4,
      "name": "Services & Utilities",
      "theme": "Power · water · waste · safety · health · education",
      "status": "outlined",
      "goal": "Consequence networks: the systems that make a badly planned city fail in legible ways.",
      "delivers": [
        "Power grid and water/sewage network flow solvers",
        "Garbage, healthcare, fire, police, education",
        "Service vehicles as first-class traffic agents",
        "Incrementally computed coverage and accessibility fields"
      ],
      "exit": [
        "All service networks solve within budget at Phase 2 scale",
        "Service vehicles use the same routing stack as everything else",
        "Failure states are causal, visible and explainable"
      ],
      "remains": [
        "No economy — services have no cost and no funding model"
      ],
      "targets": {}
    },
    {
      "id": 5,
      "name": "Economy & Land Use",
      "theme": "Firms · land value · taxation · budgets",
      "status": "outlined",
      "goal": "Make the city an economy, with land value as the connective tissue between transport, land use and money.",
      "delivers": [
        "Firms with supply chains, employment matching, wages, prices",
        "Land value from accessibility, amenity and nuisance (hedonic model)",
        "Bid-rent-driven land use change",
        "Taxation, budgets, loans, and the full causal chain behind abandonment",
        "Regional and outside connections"
      ],
      "exit": [
        "Economy inspectable end to end",
        "No runaway or degenerate equilibria across a 20-hour play test",
        "A deliberately bad city fails for legible reasons"
      ],
      "remains": [
        "No public transport — the city is car-only"
      ],
      "targets": {
        "area": "64 km²",
        "buildings": "300k"
      }
    },
    {
      "id": 6,
      "name": "Transit & Multimodal",
      "theme": "Bus · tram · metro · rail · freight",
      "status": "outlined",
      "goal": "Public transport as a first-class routing citizen, not a parallel system bolted alongside the road network.",
      "delivers": [
        "Line editor, stops and stations, timetables and headways",
        "Vehicle dispatch, capacity and crowding",
        "Multimodal journey planning (RAPTOR/CSA-class) coupled to the road router",
        "Park-and-ride; freight logistics and cargo terminals"
      ],
      "exit": [
        "A citizen can plan and execute walk→bus→metro→walk journeys",
        "Transit demonstrably relieves road congestion in an A/B test",
        "Transit routing stays within budget at 1M citizens"
      ],
      "remains": [
        "The world is still functional-but-plain: no terrain, weather or art pass"
      ],
      "targets": {}
    },
    {
      "id": 7,
      "name": "World & Fidelity",
      "theme": "Terrain · weather · day/night · GPU-driven rendering",
      "status": "outlined",
      "goal": "Make it a place, and take rendering to shipping quality.",
      "delivers": [
        "Large-scale terrain (clipmap/CDLOD-class) with road conforming and cut/fill",
        "Rivers, coastlines, resources",
        "Procedural and authored building variety",
        "Day/night, weather, seasons",
        "Two-phase HZB occlusion culling, impostors, HLOD",
        "Full audio"
      ],
      "exit": [
        "500k+ visible instances at target FPS",
        "The 100 km² world streams without hitches",
        "Art direction locked"
      ],
      "remains": [
        "A simulation, not yet a game: no progression, policies or onboarding"
      ],
      "targets": {
        "area": "100 km²",
        "instances": "500k"
      }
    },
    {
      "id": 8,
      "name": "Game Layer",
      "theme": "Progression · policies · districts · disasters · UX",
      "status": "outlined",
      "goal": "Turn the simulation into a game people can learn and want to keep playing.",
      "delivers": [
        "Progression, milestones, policies, districts, zoning ordinances",
        "Scenarios, challenges, disasters, achievements",
        "Tutorial and onboarding",
        "Full UX pass with information design, photo mode, statistics",
        "Save/load UX and cloud saves"
      ],
      "exit": [
        "A new player reaches a 10 000-population city unaided",
        "Complete play loop from empty map to metropolis"
      ],
      "remains": [
        "No modding or user content pipeline"
      ],
      "targets": {}
    },
    {
      "id": 9,
      "name": "Modding & Pipeline",
      "theme": "Mod API · asset editor · distribution",
      "status": "outlined",
      "goal": "Longevity. CS1's decade-long life was bought with mods; the mod API is a shipping feature, not an afterthought.",
      "delivers": [
        "Stable, versioned scripting/mod API with sandboxing",
        "Asset importer and in-game asset editor; map editor",
        "Content distribution and dependency resolution",
        "Compatibility policy and deprecation process",
        "Determinism harness extended to detect mod-induced divergence"
      ],
      "exit": [
        "A third party builds a non-trivial mod and custom asset from docs alone",
        "Mods cannot silently break determinism or saves"
      ],
      "remains": [
        "Hardening, ports, localisation, live ops"
      ],
      "targets": {}
    },
    {
      "id": 10,
      "name": "Ship & Sustain",
      "theme": "Hardening · ports · localisation · live ops",
      "status": "outlined",
      "goal": "Release, and keep it healthy afterwards.",
      "delivers": [
        "Performance hardening across a hardware matrix incl. handheld and 4K",
        "Platform ports, localisation, accessibility audit",
        "Telemetry and crash reporting",
        "Live-ops and patch cadence",
        "A public technical postmortem"
      ],
      "exit": [
        "Release candidate meets every north-star number on the reference machine",
        "Degrades gracefully below the reference spec"
      ],
      "remains": [
        "Post-launch content and expansions"
      ],
      "targets": {}
    }
  ],
  "board": {
    "done": [
      {
        "title": "Agent architecture defined",
        "detail": "13-agent roster with verbatim system prompts, orchestration protocol, handoff and escalation formats, definition of done.",
        "agent": "A0 ARCHON"
      },
      {
        "title": "Master roadmap + budget ledger",
        "detail": "Phases 0–10, frame-time and memory allocation per system, risk register, phase gate procedure.",
        "agent": "A0 ARCHON"
      },
      {
        "title": "ADR-001 engine baseline",
        "detail": "Unity 6 LTS + Entities 1.x + Burst + Jobs; URP Forward+; IL2CPP players. Unreal Mass compared honestly and rejected on iteration cost.",
        "agent": "A0 ARCHON"
      },
      {
        "title": "ADR-002 data model",
        "detail": "Hot/cold split, ≤64 B hot vehicle archetype, packed types, pooling over structural change, stable ids.",
        "agent": "A1 LATTICE"
      },
      {
        "title": "ADR-003 road network",
        "detail": "Node/segment/lane graph with OpenDRIVE-style s/t reference lines; lane-level from day one; half-edge overlay for blocks.",
        "agent": "A2 SPLINE"
      },
      {
        "title": "ADR-004 routing stack",
        "detail": "Customizable Contraction Hierarchies; strategic/tactical/operational split; stochastic route choice.",
        "agent": "A3 WAYFARE"
      },
      {
        "title": "ADR-007 determinism",
        "detail": "Fixed 20 Hz tick, fixed-point accumulators, FloatMode.Strict, canonical ordering, record/replay/hash/bisect harness.",
        "agent": "A9 PLUMB"
      },
      {
        "title": "Traffic + pathfinding dossier",
        "detail": "Primary-source survey: IDM/IIDM, MOBIL, NaSch, CTM, CCH/CRP, MaxPressure, ORCA, MATSim, with equations and parameters.",
        "agent": "A11 CODEX"
      },
      {
        "title": "PDF build pipeline",
        "detail": "Markdown → typeset PDF with cover, two-pass TOC, part dividers, callouts, code blocks. Grows by manifest entry.",
        "agent": "A10 FORGE"
      },
      {
        "title": "ADR-005 traffic model",
        "detail": "IDM/IIDM + MOBIL + Max-Pressure with the explicit micro/meso/macro fidelity ladder and conservation laws.",
        "agent": "A4 FLUX"
      },
      {
        "title": "ADR-006 rendering path",
        "detail": "BatchRendererGroup, mandatory numeric LOD ladder, GPU-side culling, impostor tier.",
        "agent": "A6 PRISM"
      },
      {
        "title": "ADR-008 zoning & lots",
        "detail": "4 m zone cells from lane geometry, planar-face block extraction, OBB-recursive subdivision, damped demand loop.",
        "agent": "A5 PARCEL"
      },
      {
        "title": "DOTS + road geometry dossiers",
        "detail": "Entities/Burst/BRG capabilities and limits; OpenDRIVE, clothoids, junction meshing, parcel subdivision, HZB culling.",
        "agent": "A11 CODEX"
      },
      {
        "title": "Phase 1 step-by-step plan",
        "detail": "Every task with scope, deliverables, acceptance criteria and the exact AI prompt to execute it.",
        "agent": "A0 ARCHON"
      },
      {
        "title": "Phase 1 AI prompt pack",
        "detail": "43 ready-to-paste task packets (T00–T42), each addressed to its owning agent with objective, context bundle, scope, deliverables, acceptance criteria, degenerate cases, verification and handoff. Plus five recurring cross-cutting prompts.",
        "agent": "A0 ARCHON"
      },
      {
        "title": "Design document assembled",
        "detail": "232 pages across five parts, compiled from the Markdown sources by tools/build_pdf.py and published here. Grows one part per phase.",
        "agent": "A10 FORGE"
      },
      {
        "title": "Status board published",
        "detail": "plan.aakhar.net over TLS, serving this board and the current design document. Private source repo GMPrakhar/Infrastruct.",
        "agent": "A10 FORGE"
      }
    ],
    "doing": [
      {
        "title": "Phase 0 — repo scaffold",
        "detail": "T01–T04: Unity 6 LTS project, pinned package manifest, asmdef layer graph with enforced dependency direction, CI that compiles, tests and runs headless.",
        "agent": "A10 FORGE"
      }
    ],
    "next": [
      {
        "title": "Determinism harness",
        "detail": "Record/replay, canonical world hashing, per-tick bisection reporting the diverging entity and field. Phase 0 exit criterion: two replays hash identically on two machines.",
        "agent": "A9 PLUMB"
      },
      {
        "title": "Benchmark harness + scene corpus",
        "detail": "Machine-normalised reporting, median and p99 per system, 1×/4×/16×/64× scaling curves. Every later gate is measured with this.",
        "agent": "A8 CALIPER"
      },
      {
        "title": "Degenerate-city corpus",
        "detail": "The adversarial scenes: single-lane spiral, saturated grid, disconnected districts, 1-tile lots, zero-length segments. Phase 1 must survive all of them.",
        "agent": "A12 HAZARD"
      },
      {
        "title": "Phase 1 execution — WP1 road network",
        "detail": "T05–T09: reference-line geometry, node/segment/lane graph, incremental edit pipeline, half-edge block extraction.",
        "agent": "A2 SPLINE"
      },
      {
        "title": "Phase 2 outline → detailed plan",
        "detail": "Expands the master plan's Phase 2 outline into a full work-package breakdown with its own prompt pack, and adds Part VI to this document.",
        "agent": "A0 ARCHON"
      }
    ]
  },
  "adrs": [
    {
      "id": "001",
      "status": "ACCEPTED",
      "title": "Engine, runtime & language baseline",
      "decision": "Unity 6 LTS with Entities 1.x, Burst, Jobs and Entities Graphics on URP. Pure ECS simulation; MonoBehaviour only at the boundary. Unreal's Mass framework was genuinely competitive and lost on iteration cost, rendering fit for many small instanced meshes, and ecosystem."
    },
    {
      "id": "002",
      "status": "ACCEPTED",
      "title": "ECS data model principles",
      "decision": "Memory layout is the performance ceiling. Hot/cold archetype split, ≤64 B hot vehicle archetype, aggressively packed types, lane-local fixed-point positions, pooling instead of per-tick structural change, stable ids for anything ordered or saved."
    },
    {
      "id": "003",
      "status": "ACCEPTED",
      "title": "Road network representation",
      "decision": "Explicit node/segment/lane graph with first-class lane-to-lane connectors. Reference line in (s,t) like OpenDRIVE; lanes are derived offsets. Lane-level from day one because retrofitting lanes is the most expensive available mistake."
    },
    {
      "id": "004",
      "status": "ACCEPTED",
      "title": "Routing & pathfinding stack",
      "decision": "Customizable Contraction Hierarchies: metric-independent contraction plus cheap parallel customisation, so congestion re-weighting is routine rather than exceptional. Three-layer strategic/tactical/operational split; stochastic route choice to stop herding."
    },
    {
      "id": "005",
      "status": "ACCEPTED",
      "title": "Traffic simulation model",
      "decision": "IDM/IIDM car-following with MOBIL lane changing and Max-Pressure signal control, wrapped in an explicit micro/meso/macro fidelity ladder with vehicle-conservation guarantees across transitions."
    },
    {
      "id": "006",
      "status": "ACCEPTED",
      "title": "Rendering path",
      "decision": "URP Forward+ with BatchRendererGroup. Every renderable ships a numeric LOD ladder including a cheapest impostor tier — the structural defence against the CS2 failure mode. GPU-side culling; draw calls must not scale with instance count."
    },
    {
      "id": "007",
      "status": "ACCEPTED",
      "title": "Time, determinism & numerics",
      "decision": "Fixed 20 Hz simulation tick decoupled from rendering; fixed-point accumulators; FloatMode.Strict; canonical ordering everywhere; record/replay/hash/bisect harness gating CI from Phase 0."
    },
    {
      "id": "008",
      "status": "ACCEPTED",
      "title": "Zoning, blocks & lots",
      "decision": "4 m zone cells derived from lane geometry, planar-face block extraction from the half-edge overlay, OBB-recursive lot subdivision, and demand modelled as a damped control loop rather than a random number."
    }
  ],
  "tech": [
    {
      "group": "Runtime",
      "items": [
        {
          "name": "Unity 6 LTS",
          "note": "Pinned; upgrades only at phase gates"
        },
        {
          "name": "Entities (DOTS) 1.x",
          "note": "Pure ECS simulation, ISystem + IJobEntity"
        },
        {
          "name": "Burst + Unity.Mathematics",
          "note": "HPC# subset, FloatMode.Strict in simulation"
        },
        {
          "name": "C# Job System",
          "note": "Every hot path off the main thread"
        },
        {
          "name": "IL2CPP",
          "note": "Player builds; Mono for editor iteration"
        }
      ]
    },
    {
      "group": "Simulation algorithms",
      "items": [
        {
          "name": "IDM / IIDM",
          "note": "Treiber, Hennecke & Helbing 2000; Treiber & Kesting 2013"
        },
        {
          "name": "MOBIL",
          "note": "Kesting, Treiber & Helbing 2007 — lane changing"
        },
        {
          "name": "Nagel–Schreckenberg CA",
          "note": "1992 — the cheap macro tier"
        },
        {
          "name": "Max-Pressure control",
          "note": "Varaiya 2013 — provably stabilising signals"
        },
        {
          "name": "ORCA / RVO2",
          "note": "van den Berg et al. — pedestrians near camera"
        }
      ]
    },
    {
      "group": "Routing",
      "items": [
        {
          "name": "Customizable Contraction Hierarchies",
          "note": "Dibbelt, Strasser & Wagner 2016"
        },
        {
          "name": "Customizable Route Planning",
          "note": "Delling et al. — the fallback if CCH customisation stalls"
        },
        {
          "name": "BPR volume-delay function",
          "note": "Congestion cost, α=0.15, β=4"
        },
        {
          "name": "Logit route choice",
          "note": "Stochastic assignment — the anti-herding mechanism"
        },
        {
          "name": "RAPTOR / CSA",
          "note": "Phase 6 — schedule-based transit routing"
        }
      ]
    },
    {
      "group": "Rendering",
      "items": [
        {
          "name": "BatchRendererGroup",
          "note": "Draw calls decoupled from instance count"
        },
        {
          "name": "Two-phase HZB occlusion culling",
          "note": "GPU-side, previous-frame depth pyramid"
        },
        {
          "name": "Octahedral impostors",
          "note": "The mandatory cheapest LOD tier"
        },
        {
          "name": "URP Forward+",
          "note": "Many small lights without a deferred G-buffer cost"
        }
      ]
    }
  ]
}