11 — Implementation roadmap¶
Part of the TraceMaker plan. Start at
../PLAN.md. Each milestone is sized for one to a few focused implementation sessions and ends with a gate: a test or benchmark that must pass before the next milestone starts. Visual feedback comes early (M3) so every later milestone can be watched while it is built.
| # | Milestone | Main deliverables | Gate |
|---|---|---|---|
| M0 | Toolchain and skeleton | CMake presets (debug, release, asan, cpu-only), CUDA build with a GCC host compiler that nvcc 12.4 accepts, Catch2, clang-format/clang-tidy config (or GCC equivalents), scripts/bootstrap.sh, kicad-cli available (Docker image or native), fixture download script |
ctest runs a CPU and a CUDA hello-kernel test on both GPUs; kicad-cli version works from the harness |
| M1 | KiCad I/O and board model | s-expression lexer/parser/writer; .kicad_pcb, .kicad_pro, .kicad_dru, .kicad_sch (netlist), .kicad_mod; board model with layers, stackup, footprints, pads, tracks, vias, zones, nets, net classes; DSN reader |
Byte-identical round-trip of every fixture board (parse → write); netlist equals kicad-cli sch export netlist on all fixture projects |
| M2 | Rules and DRC parity | Rule compiler (net classes, board constraints, custom rules subset), spatial indices, own DRC with KiCad violation names | Same violation multiset as kicad-cli pcb drc on all unrouted and routed fixture boards (documented, tested exceptions only) |
| M3 | Event bus, server, viewer v1 | Event types, ring buffers, WebSocket server, FlatBuffers schema, replay log; WebGL2 viewer (WebGPU backend optional): layers, pan/zoom, pads/tracks/vias/zones, ratsnest, dark theme | Viewer renders the largest fixture board at ≥ 60 fps; replay of a recorded log reproduces the final board |
| M4 | *First router (lattice A) | Rerun debug logging of searches (optional), transactions, scoring, union-find, bit-planes, A* + radix heap, insertion with exact validation, basic pull-tight; sequential routing in net order; tracemaker route CLI; bench harness v1 with KiCad-DRC judge and Freerouting runner |
Routes the simple fixture set with 0 added KiCad DRC errors; harness produces the comparison table |
| M5 | Failure memory T0–T2 + escalation R0–R3 + repair | Failure records, Zobrist signatures, nogood store, history + targeted penalties, conflict graph, activity ordering, bandit; negotiated rip-up; repair windows; aggressor/victim repair | Completion ≥ Freerouting on the Freerouting test set; ablation shows each learning mechanism helps or is removed |
| M6 | Global routing + GPU (closed 2026-10-06: GPU fields in use; global router built and measured, off; GPU global routing and GPU DRC broad-phase not built, doc 05 §19) | Port/adapt GAMER sweep and GGR pattern kernels from Xplace gpugr (BSD-3); tile graph, Steiner decomposition, CPU NCR, corridors; GPU pattern routing, GPU sweep maze routing, GPU cost-to-go fields, GPU DRC broad-phase |
CPU and GPU results identical on every fixture; time-to-route reduced on dense boards with no quality loss |
| M7 | Placement A–D | Constraint extraction, decoupling detection, quadratic B2B (PCG), electrostatic global placement (CPU then GPU batched), rotation/side assignment, LP legalisation; placement report with optimality levels and lower bound | Placements are legal (zero courtyard overlaps, inside outline); HPWL ≤ SA-PCB baseline on the placement set |
| M8 | Placement E–G + ECO | GPU parallel-tempering SA, LNS, CP-SAT windows, routability loop; R4 exact window solve, R5 trial ordering, R6 cut proofs, ECO placement moves | Schematic-to-board set: clean pass ≥ 90%; eco mode closes boards that none mode cannot |
| M9 | Escape planning | Min-cost-flow escape, layer assignment, NC fallback, escape templates | BGA boards in the academic set complete |
| M10 | Portfolio, determinism, knowledge base | Successive-halving portfolio, deterministic sync points, persistent KB (T3), warm starts | Bit-identical output across thread counts and GPU on/off; clean pass up at fixed time budget |
| M11 | KiCad integration | IPC plugin (live board in pcbnew, one undoable commit), Python bindings, PCM package | Round-trip in KiCad on the demo boards |
| M12 | Advanced rules and arms | Differential pairs, length/skew tuning, blind/micro vias, gridless tile-plane arm, learned ordering/congestion models | Each feature gated by its own benchmark subset; no regressions |
| M13 | Component-aware layout rules (in progress: P0–P2 built, P3 USB pairs; doc 15 §14) | Category detection from the BOM/netlist (USB, Ethernet, crystals, regulators, RF, …), role binding, rule catalogue (docs/component_rules.yaml) compiled into net classes, a sidecar .kicad_dru, keep-out areas and placer pseudo-nets; stackup-based impedance; detection/rule report |
Detection precision/recall on a labelled PCBench subset; every applied rule met or reported; no regression on the quick tier |
| M16 | Advice files and a pluggable advisor (stages 0–3 built; stage 4 placement not; doc 17, issue #26) | Structured unrouted list and stuck report (--stuck-report); strict advice file (--advice: nets first, connection priority, layer costs, net-scoped regions as rule areas) run as extra portfolio variants; --advisor CMD consulted only when connections are left, with redaction, time limit and failure containment; reference advisors (advisors/) |
Options off: quick/mid/planes byte-identical; same advice twice and at 1/2/4 threads identical; bad advice refused; advisor absent/slow/invalid leaves the run unadvised; advised result never fewer than unadvised; the hint channel proven without a model before a model is connected (doc 17 §8) |
| M17 | Installable and measured (built 2026-10-16, gate partly met; doc 18 §5, D121, D122) | CI-built CPU-only Linux release tarball and KiCad plugin archive on a tag (macOS arm64 if the runner allows); PCBWorld-Bench fetched and run with failure classes against its published baselines; --relax / --txn on the PCBench tier B–D failures |
A machine without a compiler installs the plugin and routes plane_smd in under five minutes (CI does the same in a clean container); the PCBWorld report states boards lost to each baseline; --relax gains and losses counted at equal work, KiCad-judged. Result: release files built and installed in clean Ubuntu 24.04, Debian 13 and Fedora containers in 5 s, and the unpacked plugin run in a live KiCad 10.0.6 (glibc 2.38 floor; Debian 12 fails; the workflow's package and install jobs passed on GitHub in the pull request, and on the v0.10.0 tag (2026-10-18) all three jobs passed and the publish step attached the two files and SHA256SUMS to a draft release; no macOS build). PCBWorld's D3 turned out to be a PCBench subset: 119 test boards run (97/99, 10/10, 9/10 clean), Freerouting 2.1.0 re-run with the paper's settings under this judge (73.7 %, 50 %, 30 % best of 3), one board lost to Freerouting's nightly run, no "better than" claim against the paper's own rows (other judge). --txn 1: +118 connections on the 33 failing tier B-D boards at eight variants and equal work, none completed; --relax: -509 overall, two boards completed (doc 10 section 11, bench/records/m17) |
| M18 | Session server and agent interface (stages A–B built 2026-10-15, doc 19: the session, MCP and JSON-lines transports, a scripted baseline agent and the evaluation; the stop rule is not met: the scripted agent routes 967 and a model-driven arm 968 of the control's 968 on 16 fresh boards, §9.3; the daemon and the KiCad assistant are not built) | A long-running board session (tracemakerd) holding the board and caches; a tool interface over transactions (list open connections, route a connection, rip a net, check, score, undo, save), each commit behind the exact check, with a replayable session log; the plugin routes selected nets through it |
Single-net route from the plugin within a stated latency on multichannel_mixer, one undo step; stop rule: an agent loop must route more than the plain run at the same compute on a held-out half, or the interface stays a library and nothing further is built |
| M19 | KiCad 11 readiness (planned, doc 18 §4 A4) | Scheduled job running DRC parity and round trip against the newest KiCad container and, when one exists, a KiCad 11 release candidate; reader and writer for the 11 file formats; plugin on the headless IPC (kicad-cli api-server) and its own interpreter |
DRC parity corpus and byte round trip pass on KiCad 11.0; plugin round trip in a running or headless KiCad 11 |
| M20 | Hobbyist wins (planned, doc 18 §4 C2, C3, C5, D3) | Pour generation and a layer-count advisor; route --report run report; pin-swap feasibility experiment, then a proposal-only pass if the gain is clear; classification of dense-package failures by cause |
Boards completed with a generated pour vs without (DRC clean); the advisor's layer count equals a brute-force run; the report's numbers each trace to a JSON field; swap experiment table on at least ten boards |
| M21 | High speed for the Kookabus boards (planned, doc 18 §4 A3, B1–B3, A5) | The Kookabus boards as a fixture set; KiCad 10 tuning profiles (per-layer width and gap, via and per-layer delay); time-domain length and skew matching; the return-path stitch pass inside --si-rules; five-seed settlement of #24's defaults |
Kookabus boards route with each layer's profile width, 0 errors added with tuning_profile_track_geometries enabled, groups within tolerance in delay by KiCad's DRC; options off byte-identical on the quick, mid and planes tiers |
Working rules for implementation sessions¶
- Read
PLAN.md, the docs for the milestone, andCLAUDE.mdfirst. - Every accelerated path (GPU, cache, index) lands with its reference path and an equivalence test.
- Every change runs the quick benchmark subset; a regression on any board blocks the change.
- Keep the viewer working: new stages emit events from day one.
- Update the doc when the design changes, in the same change, and record the decision in 12-decisions.md.