# Roadmap

Work proceeds one phase at a time; each phase ends with its scores on the test boards
(the 6-layer board, ripped up and not, and its morph keyframes) and a commit.

## State at 2026-10-30

The MIT core (Phase 2c) is the router: the command, the studio and the benchmark all run it,
and copperroute is a legacy reference, its tools under `legacy/`. Stages 0 to 11 of a staged
remediation plan (`docs/review/REMEDIATION-2026-10-28.md`) are merged; Stage 12 (a global routing stage)
was measured and stopped (more vias, fewer clean boards; branch `remed/12-global` kept). Each
stage's measurements are in `~/Software/ultraroute-lab/pcbench/runs/remed-N-notes.md`. On the
200-board PCBench sample (`--sample 200 --sample-seed 1`, 120 s a board, one thread, judged by
KiCad 9):

- Stage 0 baseline (commit 184f640, on the dev machine, four runs): 160 to 161 boards clean. The same
  binary and seed twice disagreed on 3 boards, all at the time limit. The slowest board took
  648 s against the 120 s limit; 22 took over 125 s.
- Latest (Stage 9, commit 5192519, run `srv9-5192519` on the build server): 164 clean; the slowest
  board took 122 s (the harness's wall clock, loading and writing included), and 20 were at the
  limit. Stage 8's run (`srv8-120cd2f`) is also 164.
- Along the way: one deadline the whole run keeps (Stage 3); runs untouched by the deadline are
  byte-identical (Stage 4); median peak memory 164 -> 134 MB (Stage 5); median run 14.1 -> 9.2 s
  on the server (Stage 6); vias -6% from a 5 mm via price (Stage 7); the GPU solver parked
  (Stage 10).

Stage 0's and Stage 9's counts come from different machines; each stage was compared with the one before on
the same machine (`tools/pcbench.py compare`).

## Phase 1 — Topological routing with rip-up

- [x] `copper-topo`: rubber-band routing through a triangulation of the copper, as backend `topo`.
- [x] Rip-up: an open connection may cross other connections' copper at a price that grows with
      each rip; what it crosses is ripped and rerouted, and the board joining most is kept.
- [x] The maze stage after topo runs with a bounded via optimizer (it stalled on one pass).
- [x] The latest 6-layer board with its updated rules as a job.
- [x] Scores (open connections, all with 0 new errors): the latest 6-layer board topo+maze 12
      (grid 10, maze 16); its earlier revision 12; ripped up, topo alone 55 → 62 of 69 joined with
      rip-up, but after maze 14 without and 15 with (maze alone 9).
- [x] Keyframe reroute from bare pads, open connections (grid / topo / topo + rip-up): rectangle
      25 / 35 / 24, circle 26 / 33 / 35, diamond 21 / 29 / 33, stretched 53 / 59 / 65, rainbow
      155 / 157 / 157 (topo finds a channel for 5 of 69 there: the parts are packed shut).
- [ ] Known gaps, not blocking: legs from pads within clearance of a keepout, bends that push
      into the next obstacle, connections to traces and pours.

## Phase 2 — Physics diffusion placement

Placement migration after Ren et al. (DAC 2005): part density diffuses as heat does, and parts
ride the flow (velocity −∇d/d), so crowded regions spread while relative order is kept.

- [x] `copper-morph::diffuse`: density from part footprints per side, pin demand and optional
      routing demand (open airlines); walls at the outline; locked parts and groups.
- [x] Moves applied through `MoveOracle`, so no move adds a clearance conflict.
- [x] Backend `diffuse`: route, spread by the open connections' demand, reroute, keep the better.
- [x] Reshape: spread at keyframes, after ripping and before rerouting (`--diffuse-target`).
- [x] Unit tests: spreading lowers the peak, locked parts stay, groups move as one, the move
      limit holds, demand pushes, applied moves add no violation.
- [x] Scores: no gain yet. The backend's spread board was worse every time, so it kept the
      first route: the 6-layer board 10 open (29 spread; 17 at target 2.0 and 0.5 mm, 10 parts
      moved), ripped up 9 (70 spread). Keyframe reroute with spreading, open connections
      (vs. without): rectangle 56 (25), circle 62 (26), diamond 59 (21), stretched 83 (53),
      rainbow 104 (155); every keyframe hit the 10 min limit.
- [ ] Why: pin demand puts the peak density near fine-pitch parts above 1 (2.4–7), which no
      move can fix, so at target 0.8 nearly every part moves the full limit; and a moved board
      starts its route afresh within the same time budget. Next: normalise demand per part,
      spread only toward open airlines' congestion, and route moved parts incrementally.

## Phase 2b — Parts set the board's size; several complete layouts (later)

- [ ] Grow the outline until the board routes: start from the parts' packed area, route,
      enlarge where the open airlines crowd, repeat; the outline is an output, not an input.
- [ ] Present several complete laid-out options (placement, outline and copper) that differ
      in size, shape or layer count, each scored by the suite, for a person to choose from.

## Phase 2c — The MIT routing core (built; it is the router)

copperroute is ~106k lines, almost all a port of freerouting (GPL); ours inside it (copper-gpu,
copper-morph, copper-topo, copper-governor) is ~7k. A core written fresh, never ported from
copperroute or freerouting, lets the studio link the router under MIT. It does: the core routes
natively and, compiled to WebAssembly, in the browser tab, on the CPU in both. Estimated at
~15k lines when proposed:

- [x] Board I/O from `.kicad_pcb` directly (`core/crates/kicad-pcb`, from waffle-iron's reader):
      copper layers, tracks, arcs, vias, zones and rule areas, pad layer sets and exact shapes
      (custom pads included), `.kicad_pro` rules and net classes, and a writer that replaces
      routed copper and keeps every other byte. On the 6-layer board all 2290 tracks and 331 vias
      rewritten give KiCad's DRC the same result (0 violations, 0 unconnected).
- [x] Locked flags kept when copper is written back (`(locked yes)`, REMEDIATION Stage 9);
      `.kicad_dru` custom rules applied where the router models them (per-net track width,
      hole clearance, hole to hole, SMD clearance, edge clearance); any other rule is a warning.
- [x] Geometry in integer nanometres and a board model (`core/crates/board`): capsules and
      polygons per copper layer, a grid index, holes, keepouts and the outline; written without
      outside crates.
- [x] Connectivity as KiCad joins copper (at anchors: track ends, via and round-pad discs, pad
      centres; pours wherever they touch) and a clearance check (copper, edge, plated-hole, hole
      to hole, keepouts; KiCad's 0.5 µm epsilon). Against KiCad 9's DRC on the 6-layer board
      and the earring, clean, stripped, half-stripped and shifted: identical open-connection and
      clearance counts, except 455 vs 458 open on the half-stripped 6-layer board. 66 ms
      connectivity, 0.5 s full check on the 6-layer board.
- [x] Grid routing on the core (`core/crates/grid`, CPU): a conservative obstacle map per net
      class, our integer-cost search, legs out of crowded pads, every piece checked before it is
      kept. Pours are refilled around new copper (`tools/refill_zones.py`), so every connection is
      made in tracks. Judged by KiCad after a refill: the earring 249 → 14 open in 22 s, the
      6-layer board with its unlocked copper stripped 25 → 5 open in 13 s, 0 errors on both.
- [x] Holes as slots (oval drills), not only round (REMEDIATION Stage 9).
- [x] The GPU field solver (`--features gpu`) and negotiated congestion on the core. With
      negotiation then single routing for what is left, after a KiCad refill: the earring 10 open,
      the stripped 6-layer board 3 open, 0 errors on both. Slow yet: 30 rounds that do not converge,
      ~3 min on the earring; one field at a time leaves the GPU idle (58 s vs 22 s CPU, sequential).
- [x] `ultraroute route` (`core/crates/ultraroute`): routes a `.kicad_pcb` and writes it back,
      `--place`, `--strip`, `--negotiate`, `--gpu`, `--timeout`, a `stop` line, and `--live` in
      the studio's frame format, negotiation's trial routes included. The studio runs it as the
      Core router on the 6-layer board's and the earring's jobs.
- [x] Negotiation stops after 4 rounds without fewer collisions; pad outlines drawn outside
      their arcs so clearance to them is never overstated. Earring 8–14 open (runs vary),
      the 6-layer board 3, 0 errors.
- [ ] GPU batches for negotiation rounds work but are slow: ~110 s a round on the earring's
      3.5M-node fields against ~10 s on CPU threads. The relaxation kernel needs a better
      schedule (or a coarser grid) before the GPU pays. Parked (REMEDIATION Stage 10, 2026-10-30):
      off by default (`--features gpu` builds it in, `--gpu` warns), kept for a frontier or
      windowed kernel; the browser's WebGPU copy was deleted. What runs: A* on the CPU, natively
      and in the tab's worker pool.
- [x] Topological routing with its own rip-up (`topo`), and rip-up and nudge in the grid
      router (below). The command no longer links `topo` (REMEDIATION Stage 7); the crate
      builds and tests in the workspace.
- [x] A* search on the CPU (routes as cheap as the full field, a fraction of the work), zones
      sized per pair of net classes, legs necked down to the narrowest track out of crowded pads,
      and a rip-up finisher: a blocked connection may cross copper the router laid, which is
      ripped and rerouted, kept only if fewer connections stay open. After a KiCad refill: the
      earring 3 open in 54 s (copperroute's best is 3, nudge, 511 s; its grid recipe 4) and
      the stripped 6-layer board 4, 0 errors on both.
- [x] Deterministic runs (ordered connectivity), a finisher that rips any of the router's
      own copper and retries after progress, and a pull-tight pass that straightens each chain
      of router copper between fixed points while keeping everything it joins. Earring 5 open,
      3403 → 1305 segments, 1207 → 1164 mm; the stripped 6-layer board 4 (its leftovers are
      walled in by fixed copper: a job for nudging, not rip-up). 0 errors.
- [x] Courtyards read; a core nudger (`--nudge`): parts near a blocked airline stepped 0.25–1 mm
      in eight directions, kept only when legal (pads clear, no courtyard overlap) and fewer
      connections stay open. On the packed earring nearly every step is illegal and none helps.
- [x] `legacy/tools/kicad_bench.py`: both routers on the same KiCad board, judged by KiCad after a
      refill. Earring: core 5 open / 0 new errors / 304 vias / 48 s; copperroute grid 18 / 0 /
      196 / 427 s; copperroute maze 37 / 2 / 140 / 150 s. (Nudge still to run.)
- [ ] Fewer vias. The core used ~1.5× copperroute's on the earring, and 5.7× FreeRouting's on
      PCBench (base-1, `docs/pcbench.md`). Since then: a via pass after tightening, and a 5 mm
      via price that took 6% off the sample's vias (REMEDIATION Stage 7).
- [ ] Diffusion on the core.
- [x] The core replaced copperroute as the router (earring by `legacy/tools/kicad_bench.py`: core 5
      open, copperroute's grid 18). copperroute stays as a legacy reference across the process
      boundary.

## Phase 2d — Our code out of the copperroute fork

Everything we wrote lives in ultraroute under MIT; the `governance` fork keeps only patches to
copperroute's own files, as the reference router across the process boundary. Our crates there
(`copper-morph`, `copper-gpu`, `copper-topo`, ~7.7k lines) are built on copperroute's GPL data
model, so they move by being re-targeted onto the core's `board` crate, not copied. `shove.rs`
leans on copperroute's push-and-shove (a freerouting port) and is rewritten fresh.

- [x] Push field (the dipole, done our way): parts and copper flow together, only locked things
      stay, copper ripped only where pushed into something that cannot move (`grid::push`).
      Nudge steps push instead of ripping. The `--push` flag was removed in REMEDIATION Stage 7.
- [ ] copper-morph: warp field (CG), relax, reshape, move oracle and settle driver, diffusion
      placement, morph frames.
- [x] copper-topo: the topological router (world, funnel), as `topo`. Its `--topo` flags were
      removed in REMEDIATION Stage 7; the crate stays, unlinked.
- [x] copper-gpu's blame (who blocks an open connection), as `grid::blame` (`--blame`); the rest was already in the core.
- [ ] ultraroute commands for settle, reshape, band and frames. (Blame is `--blame`, above.)
- [ ] Our crates removed from the fork once each port matches it on the tests.

## Phase 2e — Everything KiCad's files say

The router reads most of a KiCad 9 board but only seven shapes of custom rule; the audit and the
order of work are in `docs/kicad-coverage.md`.

- [x] Dropped rules and board warnings in the `--report` JSON; a board loads without a
      `.kicad_pro`; `solder_mask_to_copper_clearance` read.
- [x] KiCad 9 net classes: every class a net has, combined by priority; missing fields from
      Default.
- [x] A custom-rules engine: the `.kicad_dru` language (conditions, `layer`, `severity`, last
      match wins) asked by the checker and the grid alike: clearances, holes, edges, widths, via
      sizes, `disallow` by net, layer and named area; pad clearances over rules, as KiCad orders
      them.
- [x] Zone connections and thermals: pads that no zone joins; thermal spokes kept free as KiCad
      counts them (`min_resolved_spokes`).
- [x] Length and via-count limits: reported after routing; routed to where every via counts.
- [ ] Pad geometry: KiCad 9 padstacks, `remove_unused_layers`, curves (warned of now).
- [x] Writer: arcs out (`--arcs MM`), tuning patterns held, teardrops warned of.
- [x] A benchmark of KiCad 9 boards with `.kicad_dru` files, judged with their rules
      (`tools/rulebench.py`).

## Phase 3 — The test suite as a library

The route-job bench becomes a package other projects import: boards, configs, governed runs,
the referee, leaderboards and best results.

- [ ] Python package (`ultraroute`): `Job`, `Config`, `run`, `score`, `compare`; usable as a
      library, a CLI and from JSON configs; any router (copperroute backends, freerouting, an
      external command) behind one interface; KiCad import/export and checks.
- [ ] Rust side: a stable options type for the core's routing and placement (today
      `ultraroute::Args` and the grid crate's option structs; `docs/library.md`).
- [ ] Documentation: quick start, API reference, how to add a board, a router, a placer; served
      locally with the project.
- [ ] Tests: unit tests for the runner and referee, small fixture boards end to end, and a
      single command that runs them.

## Phase 4 — ML diffusion placement

A denoising diffusion model that generates part positions, conditioned on the netlist graph and
the board outline (in the manner of diffusion models for chip placement), judged by the Phase 3
suite.

- [ ] Data: placements from PCBench and real boards, plus synthetic boards generated at scale.
- [ ] Model and training on the local GPU; guidance toward legality and routability.
- [ ] As a placer in the suite, followed by the physics spreader and the routers; scored against
      the human placements.

## Phase 5 — Live, interactive, autorouter-first layout tool

A front end that shows the router working in real time, at a high frame rate, as it tries
routes; then lets a person guide it while it runs. The aim is a PCB layout tool built around
the autorouter, and a place to explore the UX paradigms and algorithms that this kind of
collaboration needs.

Phase 5a (now) — play with what we have, on the web first, at `/studio/`:
- [x] `copperroute route --live`: frames of copper added and removed, throttled to the frame
      rate, diffed from the board itself so trial boards show as routes being tried.
- [x] `--place REF=x,y` so parts dragged in the client are honoured on the next run; the wiring
      on their pins, fixed or not, is ripped and rerouted.
- [x] `studio/`: a Rust server that runs the router as a child process and relays its frames
      over a WebSocket; a Rust core (scene, layers, picking) compiled to WASM; a Svelte + Vite
      client: pick a job and a router, watch it live, stop, drag parts, route again.
- [x] The board as designed is shown on opening, before any routing (`--backend none`).
- [x] Congestion: copper, pads and open connections against each 1 mm cell's capacity, as a map
      and a summary naming the parts nearest the fullest cells.
- [x] Locks shown on the board and listed; lock and unlock, arrow-key nudges, and "nudge it for
      me" (the nudger with every other part locked) for a selected part.
- [ ] Rubber-banding while a part is dragged: the attached wires keep their route through the
      board and are pulled taut live, falling back to airlines and a reroute when that fails.
- [x] Negotiation rounds as live frames: the core's `--live` sends each round's trial routes.
      (copperroute's grid router still shows its copper at once.)
- [ ] Steer a run without restarting it: lock or move a part, forbid a region, mid-run.
- [x] The core honours the time limit throughout: one deadline every stage and search keeps
      (REMEDIATION Stage 3). The slowest sample board at `--timeout 120` took 648 s before it,
      122 s at Stage 9.
- [ ] GTK client on the same core (needs `libgtk-4-dev`).

- [ ] Event stream from the routers (copper added, ripped, tried; costs; congestion) with a
      compact wire format, cheap enough to emit every attempt.
- [ ] Shared Rust core for scene, layers, picking and the stream protocol.
- [ ] Two clients on that core: native GTK (gtk4-rs, GPU-drawn) and web (Svelte + Vite, the
      core compiled to WASM, WebGPU/WebGL drawing).
- [ ] Interactivity while routing: lock or drag parts, keep or forbid regions, sketch a path
      for a net, reorder or pin connections; the router replans around the edits live.
- [ ] Written new: nothing copied from copperroute's `web/` (copperroute.net) or `copper-web`.

**Licensing (decided 2026-10-24).** ultraroute is MIT. copperroute stays GPL-3.0-only (a
derivative of freerouting, with parts of KiCad's DRC), and so is everything added inside the
fork. The studio reaches copperroute only across a process boundary (the live stream); linking
copperroute into the studio, including a WASM build in the web client, would make it GPL. The
MIT core has no such limit: the studio links it, natively and as WASM.

## Phase 6 — Planned routing: intent, bundles, lanes, frames, one copper writer

**On hold since 2026-11-10.** Phase 6 is paused until it is replanned with a stronger model. The
first round of agent branches (plan/hygiene, plan/intent, plan/layers, plan/bundles, plan/frames)
stays unmerged in its worktrees (`.claude/worktrees/plan-*`); their audits are in
`ultraroute-lab/planned/*/AUDIT.md`. Nothing from them is on main. The order of work below is
the latest thinking, not a commitment.

Spec: `docs/spec/planned-routing.md` (2026-11-09). The router plans nothing above one connection
and keeps no wire model below the cell path, so quality is patched after the fact: the
round-pendant requests (`docs/research/round-pendant-user-notes-2026-11.md`) and the spaghetti
look of clean boards share that root. Each step is opt-in until its gate passes (no board lost,
under 10% CPU, its own score moved).

Order revised 2026-11-10 after the plan/* audits: the wire model and one writer come before any
hygiene fix (mending passes without it were another local patch); owned zones are a price, not a
wall. Labels kept; listed in order of work.

- [ ] P0 request audit and hygiene measure: every request in the round-pendant notes checked
      against main; the hygiene audit in the report and pcbench. No new mending passes.
- [ ] P6a wire model and one copper writer, brought forward: a wire record per connection from
      search to Write; all router copper written from it with exact ends, collinear merge, prune.
- [ ] P1 intent: net roles, groups (buses, matrices), priority from `.kicad_dru` length and
      via-count rules, small zones owned (priced, not walled), zone-joined items connected.
- [ ] P2 layer roles: per-layer direction on 3+ signal layer boards, kept through negotiation.
- [ ] P3 bundles with lanes: groups routed together in pin order, sibling lane discount.
- [ ] P6b passes as edits of wires: tightening, via removal, squaring, mending move vertices.
- [ ] P4 relaxation: elastic-band spacing and alignment within channels (the "springs").
- [ ] P5 the plan: force-directed edge bundling over airlines, regions and channels from `topo`,
      bundle trees, layer assignment per bundle, the run budget.
- [ ] P7 frames: direction price, squaring and scores read a frame (cartesian default, polar with
      arcs for round boards).
- [ ] P8 symmetry and similarity: route a fundamental domain (sector) and copy; repeated
      sub-circuits routed once.
- [ ] Scores in pcbench: layer coherence, crossings, bundle continuity, vias per bus member,
      symmetry share, and the hygiene audit.
