Repository navigation
v0.22.0
Summary
Three new kct check rules — via_under_body and pin1_marker (both on
by default) and the opt-in width_consistency audit — plus native
emission of the different-net SMD-pad clearance floor and a single
clearance resolver for kct route (Epic #5509 Phase 2/3). Read the
upgrade notes: kct check --strict and native kicad-cli DRC can
newly fail on boards that passed before, and kct route now routes at
the clearance the board's project declares (for example KiCad's stock
0.20 mm Default netclass) instead of letting --mfr or its own target
override it. Also: routing-plan capacity gating (--plan-gate,
net-status --why sidecar), the coupled diff-pair search moved onto the
exact-geometry clearance kernel, pre-release correctness fixes to the
three new rules, and router performance work.
Upgrade notes / behaviour changes
-
kct check --strictcan newly fail on boards that passed before.
Two new categories are on by default:via_under_body(Issue #5736) and
pin1_marker(Issue #5737). Their findings are warnings, and plain
kct checkexit codes don't change. But--strict, and any CI or ship
gate that counts warnings, will now fail on:- a via under a QFN/DFN/SON/LGA package body (
via_under_body) - an orientation-sensitive part with no visible silkscreen pin-1 mark
(pin1_marker_missing/pin1_marker_obscured)
The repo's own board-04 gate hit this and needed waivers (#5745). To keep
a gate green without fixing the board, either skip both categories with
kct check --strict --skip via_under_body,pin1_marker, or add
per-reference / per-item entries to.kct_waivers.json. Waivers are
narrower and keep the check active for new parts. - a via under a QFN/DFN/SON/LGA package body (
-
kct routenow routes at the clearance the board's project
declares (Issues #5645, #5654). The router reads the.kicad_proand
.kicad_drubeside the.kicad_pcb— the same setkicad-cli pcb drc
checks — and treats each declared value as a floor that only ever
raises the router's 0.15 mm target, never lowers it:- an unconditional
.kicad_druclearance rule, - the
.kicad_prominimum clearance (min_clearance/
clearance_min), and - the
.kicad_proDefaultnetclass clearance. A project still
carrying KiCad's stock 0.20 mmDefaultis now routed at 0.20 mm.
Projects kct itself creates now writeDefaultat 0.15 mm, so they are
unaffected.
In addition,
--manufacturer/--mfrno longer overrides a clearance
the board declares; it only selects which fab floor applies. The
clearance banner names the layer that won. To keep the previous spacing,
lower the declared value in the project, or pass--clearance, which
remains the one deliberate waiver and now warns when it undercuts a
declared rule (#5656). - an unconditional
-
kicad-cli pcb drccan newly fail boards whose.kicad_drukct
regenerates (Issue #5059). Generated DRU files (and the shipped JLCPCB
templates) now carry a nativeSMD Pad Clearancerule for SMD pads of
different footprints whenever the profile sets
min_smd_pad_clearance_mm, so native DRC reports different-net SMD pad
pairs closer than that floor that it previously passed. KiCad
10.0.0/10.0.1 never fire the rule, and kct warns when it detects one of
those versions (#5724).
Fixed
-
Board 04 now silkscreens pin 1 / polarity on U1, U2, D1 and J1
(Issue #5745).boards/04-stm32-devboard/generate_design.pyemitted all
four of those footprints with no footprint silkscreen graphics at all —
only the reference text — sopin1_marker_missingfired on every one and
the four findings had to be waived inoutput/.kct_waivers.jsonwhen
#5737 landed the rule. Each generator function now emits its stock KiCad
library artwork: the body outline plus the filled pin-1 triangle for
SOT-223-3_TabPin2(Y-mirrored — this board's pad 1 sits aty=+2.3,
the opposite of the library footprint, so copying the library triangle
verbatim would have marked pad 3) and forLQFP-48_7x7mm_P0.5mm(four
corner brackets, transferred as-is — the pad coordinates already match the
library), the open-sided polarity bracket forLED_0805_2012Metric, and
the L-shaped pin-1 corner plus body rectangle for
PinHeader_1x06_P2.54mm_Vertical(shifted from the library's pin-1 origin
onto this footprint's centered origin). Strokes are 0.15mm, the
jlcpcb-tier1silkscreen floor, rather than the library's 0.12mm, and the
U1/D1/J1 reference designators move clear of the new outlines so
silk_overlapstays at zero. The four waivers are deleted and the board
passes the reviewed paid-drill gate (#5009) at strict-0 without them —
kct checkreports 0 errors / 0 warnings / 0 waived, andkicad-cli pcb drcindependently reports no silk finding of any kind. -
The coupled diff-pair search now sees the copper it was routing
through (Issue #5662, Phase 3c of Epic #5509). #4507 summarised the
defect as "the copper this board fails on is invisible to both by
construction", and both halves of that are closed here by moving the
coupled path onto the shared exact-geometry clearance kernel:- C++ (
CoupledPathfinder::rail_clear, consumer group 7). The gate
was a lambda insideroute(), wrapped inif (grid_.has_fixed_fills())and consulting fixed fills alone — so on a
board with no copper pour it ran no rail check at all, and a route
committed throughadd_stored_segment/add_stored_viaafter the
last blocked-plane re-sync was invisible to it. It is now a named,
bound method that always runs and measures the candidate rail against
the grid's stored route geometry with the clearance kernel, through
the same 2 mm bin index the single-ended refinement path uses. Its two
rejection reasons also join the #4459 rejection histogram instead of
pruning the frontier silently. - Python (
DiffPairRouter's gates, consumer group 8).
_segment_cells_clear,_span_pad_clear,_segment_pad_clear,
_span_via_clear,_route_via_clear,_pair_has_physical_overlap,
_copper_conflictsandfind_intra_pair_clearance_violationsnow
read the kernel through one shared translation
(router/clearance_shapes.py) instead of six private predicates.
_segment_cells_cleargains the missing quadrant — a candidate span
is screened against the constructor's own unmarked shadow copper —
and the raster's over-block is re-decided by exact geometry when
every blocking cell is attributable to copper the grid can name, the
same authorisationPathfinder._trace_halo_clearhas used since
#5240.roundrect/ovalpads are now measured as the copper they
are rather than as their enclosing rectangle. - The oracle rows harden. Groups 7 and 8 stop being report-only in
the over-rejection direction: refusing a candidatekicad-clicalls
clean is a test failure
(test_migrated_consumer_never_over_rejects). Group 7 was the epic's
one unexposed consumer; bindingrail_clearretires
NOT_MEASURED_REASONSentirely, so all nineteen groups are measured. - No rule value,
.kicad_dru, or A* heuristic term is touched (Epic
#5509 scope guards #1 and #2); rule resolution stays with each
consumer, the kernel answers only gaps.
- C++ (
-
Coupled differential-pair search now refines dynamic route-halo rejection
with physical clearance (part of Issue #5410). A dynamic route halo is a
conservative acceleration structure: committed copper is dilated to whole
grid cells, so a foreign route's halo covers candidates whose actual copper
and drill gaps satisfy the effective rules. PR #5425 taught the per-net A*
(both backends) to measure that geometry before rejecting such a candidate;
the coupled joint-state search — the engine that routes every
differential pair — still answered on the raster alone, so every pair after
the first refused legal steps beside already-committed copper. Both coupled
backends now apply the identical check, over the swept trace step (not just
its endpoint) and the through-via envelope. Hard or unverifiable blockage —
pad metal, static halos, keepouts, reservations, hidden overlapping owners,
missing geometry — still rejects, and the refinement is fail-closed:
dormant without the net-name map it needs to resolve pairwise
(HV-isolation) requirements, and, on the C++ side, dormant unless that
grid's own cross-domain widening was installed and the refiner is armed.
The refinement re-measures with the candidate's net-class trace width,
clearance and via size on both backends — re-measuring with the global
DesignRulesscalar would have waived clearance the raster halo (dilated
with the net-class value) had enforced, which is the #5673 under-blocking
direction. Native ABI 42 → 44. -
Qualify KiCad 10.0.6 for the native mask-to-copper gate (Issue #5678).
The CI runner's floatingkicad/kicad:10.0tag moved from 10.0.5 to 10.0.6,
and both hard-coded10.0.5version pins —scripts/ci/check_mask_copper_native.py's
gate andvalidate/mask_copper_geometry.py's native-attribution check —
rejected it, failing theTestjob's mask step (which also skipped every
later step in that job, includingRun tests). The two pins are now one
sharedQUALIFIED_NATIVE_VERSIONS = ("10.0.5", "10.0.6")in
validate/mask_copper_geometry.py, imported by the CI gate so the pair can
no longer drift apart; an unqualified build still fails loudly, now naming
the versions it did see.
10.0.6 was measured, not assumed, before being admitted: the full native
suite was run in bothkicad/kicad@sha256:182c8005…(10.0.5) and
kicad/kicad@sha256:18693567…(10.0.6), each reporting32 passed, no skips, and the resulting mask/copper geometry was compared across the two —
every exported layer polygon and every per-UUID attributed object polygon
came back byte-identical in WKT (0.000e+00 mm² symmetric difference). -
The new
kct checkrules shipped in this release got three
correctness fixes before release.pin1_marker's bent-component
tie-break no longer lets a nearby board-level silk shape stand in for a
footprint's own pin-1 mark (Issue #5748).via_under_body's default
footprint pattern is now case-insensitive (lower/mixed-caseqfn,
Wson,lgaids are checked) with theSONtoken anchored so
Resonator/Panasonic/Epson/Degsonfootprints are not
swept in — it selects exactly the same 964 KiCad 10 stock footprints as
before — and an exposed pad split into several same-net pads is now
recognised as the thermal pad (Issue #5749).width_consistencyjoins
track endpoints withinnode_tolerance_mmeven when rounding puts them
in different buckets, so chains no longer end early and hide
width_island/width_transitionfindings (Issue #5750; six
previously missed transitions on board 05). -
The route optimizer's grid collision checker no longer rejects legal
copper near the clearance threshold (Issue #5625). It dilated
already-dilated committed copper a second time, so two envelopes merely
touching read as a violation at roughly twice the real clearance; it now
runs an exact narrow phase and agrees with the vector checker and
kicad-clion the conformance corpus's routed-copper (segment-segment)
probes. -
A routing-cache hit now writes the
<stem>.routing_plan.json
sidecar too (Issue #5651) — the plan stage previously ran only on a
cache miss, so identical runs produced different artifact sets. -
--clearancebelow a declared rule now warns (Issue #5656). The
explicit-clearance path skipped reading the board's declared rules, so
the undercut advisory could never fire from the CLI; the resolved value
is unchanged. -
The native mask-geometry export check no longer reports a
successfulkicad-cliexport as unsupported because of KiCad's
single-instanceWarning: Invalid lock fileline (Issue #5707). A
narrow, anchored allowlist of geometry-neutral stderr lines is ignored
only when the process exited 0. -
Writing a
.kicad_drunow warns when itsSMD Pad Clearancerule
is inert on the installed KiCad
(Issue #5724). KiCad 10.0.0/10.0.1 silently never fire it (pads there
don't inherit their footprint's reference), which gave a clean DRC on
boards violating the 0.15 mm different-net SMD floor. -
--deterministic-budget's help text and warning now state the
--timeoutinteraction accurately (Issue #5765). Under--auto-layers
escalation each attempt gets only a fair slice of--timeout, which can
bind on a slow host; the flag no longer claims an unconditional safety
backstop, and a run whose stage deadline actually fired is logged as
having lost determinism. -
Board 03's saved-plan replay no longer deletes footprint silkscreen
(Issue #5744). The demo recipe's routed artifact had lost all 139 silk
graphics because the plan replay removed every silk child and restored
only reference text; it now replays text only.
Added
-
Via-under-package-body rule in
kct check: a new default-on
via_under_bodycategory (selectable via--only/--skip, no new flags)
with a warning-severityvia_under_bodyrule. It flags vias whose copper
overlaps the body outline of a bottom-terminated package (QFN / DFN / SON /
LGA by default). The outline is the footprint'sF.Fab/B.Faboutline,
falling back to the courtyard. Clearance and via-in-pad both pass these vias
because they miss every pad, yet they can't be probed or inspected once the
part is assembled. Thermal vias inside the footprint's own exposed pad on
its net are allowed by default.ViaUnderBodyRuleexposes
footprint_pattern,include_references/exclude_references,
allow_thermal_pad_vias,fallback_to_courtyardandseverity. Findings
are waivable via.kct_waivers.json, and the rule id is classified
advisory, so plain exit codes don't change. All committed fleet boards
produce zero findings.kct check --strict, and any gate that counts
warnings, will now fail on a board with a via under a QFN/DFN/SON/LGA
body, even if that board passed before the upgrade. To opt out, run
kct check --skip via_under_body, or waive the via or reference in
.kct_waivers.json. See "Upgrade notes" above. -
Pin-1 / polarity silkscreen-marker rule in
kct check: a new
default-onpin1_markercategory (selectable via--only/--skip, no new
flags) with two warning-severity rules.pin1_marker_missingfires when an
orientation-sensitive footprint has no silkscreen element within 2.5 mm of
pad 1 that points at it (closer to pad 1 than to any other pad; a
multi-segment corner mark such as the L on KiCad's stock crystal
footprints counts when its centroid is closer to pad 1). Covered
footprints are those with 3+ copper pads including1/A1, plus
Diode_*/LED_*/CP_*/ tantalum parts.pin1_marker_obscuredfires
when the only such marks are under the Fab package-body outline or on pad
copper. Every other gate passes a board with no visible pin-1 marks, yet
the parts can then be assembled or reworked backwards. Passives, test
points, mounting holes, switches and keyed USB-C / coax connectors are
excluded.Pin1MarkerRuleexposes the selection patterns,min_pads,
include/exclude references,search_radius_mm,require_asymmetry,
include_board_silkandseverity. Findings are waivable per reference
via.kct_waivers.json, and both rule ids are classified advisory, so
plain exit codes don't change.kct check --strict, and any gate that
counts warnings, will now fail on a board with an orientation-sensitive
part that has no visible pin-1 mark, even if that board passed before the
upgrade. To opt out, runkct check --skip pin1_marker, or waive the
reference in.kct_waivers.json. See "Upgrade notes" above. Marker
generation is out of scope; it remains a listed follow-up of
kicad_tools.silkscreen.generator. -
Trace width-consistency audit (
width_consistency). A new
heuristic, geometric (not ampacity) advisory rule. It walks each
net/layer's tracks as chains between pads, vias and branches and reports
width_island(a short constant-width run with narrower copper on both
sides) andwidth_transition(a neck-down on a two-terminal chain that
no other-net clearance or pad escape explains, reported with the nearest
obstacle and the gap before and after widening). Warning severity,
advisory-quality category, waivable. Opt-in via
kct check --only width_consistencyor
DRCChecker.check_width_consistency(), so it does not change existing
verdicts. It can be configured throughWidthConsistencyRule
(max_island_length_mm,clearance_mm,report_justified,severity,
...). -
Native emission of the different-net SMD-pad clearance floor
(Issue #5059). TheSMD Pad Clearancerule is now emitted into the
generated.kicad_dru(and the shipped JLCPCB templates) whenever a
profile setsmin_smd_pad_clearance_mm, scoped to SMD pads of
different footprints viaA.Reference != B.Reference— KiCad's
custom-rule docs state that footprint children (pads) carry their parent
footprint's reference designator, so package-internal pairs compare equal
and stay exempt (the fine-pitch QFP/QFN wall that kept this floor
Python-only). Measured againstkicad-cli pcb drc10.0.6 (CI's
kicad/kicad:10.0container exercises the same suite):
a 0.12 mm gap between two referenced footprints fires
rule 'SMD Pad Clearance' ... actual 0.1200 mm; the same gap inside one
footprint stays silent. Known boundary, pinned by test: the native scope
is the reference string, so blank or duplicated reference designators
are not discriminated —kct check's identity-scoped floor remains
authoritative for that shape. Thedru_generatorlegacy-sidecar
rule-family list learned the new rule name. -
Measured effective-native-DRC coverage for silkscreen clearance
(Issue #5059). A manufacturer profile can emit a constraint that looks
correct in the generated.kicad_pro/.kicad_druand still be applied to
nothing; asserting emitted values cannot detect that.
tests/test_effective_silk_clearance_5059.pyasserts only what
kicad-cli pcb drcactually reports for geometry placed a known distance
below (0.085 mm) or above (0.16 mm) the 0.15 mm JLCPCB silkscreen-to-pad
floor:- the project key
board.design_settings.rules.min_silk_clearancealone
reports no finding for that gap — measured on KiCad CLI 10.0.1, both
at the factory floor and with the key raised to 2.0 mm — while a
positive-control test proves the same project block is loaded
(min_clearanceraised to 0.5 mm reportsboard minimum clearance 0.5000 mm; actual 0.1200 mm); - the explicit
(constraint silk_clearance …)rule emitted by
generate_drureports the gap numerically on byte-identical geometry; - the shipped JLCPCB profile gates it end to end through
write_drc_constraints, stays silent above the floor, and does not fire
for back-side silk against a front-side pad.
If a future KiCad honours the built-in minimum for this pair, the first
test fails and says so rather than silently leaving a redundant rule in
place. The behaviour is characterised, not explained: the upstream cause
is a lead, not a conclusion this repository has established. - the project key
-
docs/guides/drc-and-validation.md: "Three gates, not one" — native
DRC,kct check --mfrand factory DFM are separate gates, and a clean
kicad-cli pcb drcrun is not supplier approval. Includes the measured
silk-clearance evidence above and the standing warning that a blanket
same-netphysical_clearanceover every copper object is not how to get
net-independent gap checks (499 warnings on a real board, including
intentional track joins). -
Make the routing plan's overflow report consumable and measured
(Issue #5521, Phase 1c of Epic #5510). Phases 1a/1b produced a sidecar
listing over-subscribed tile boundaries; this slice says what they mean
and what would fix them:RoutingPlan.format_overflow_report()prints one block per
overflowed edge — the two regions' bounds, the nearest component ref
on each side, the overflowed layer indices, demand, capacity,
overflow, and the nets crossing. It reads only the plan object, so a
sidecar loaded withfrom_dictformats identically to a plan built
in-process. New per-edgerefs_a/refs_b(populated on overflowed
edges only) carry the ref ranking.- Computed relief (
relief, empty since 1a, plus a new
relief_meta). Each candidate is measured, not guessed: the same
global pass is re-run under one hypothetical change and the resulting
board-wideexpected_overflowrecorded, keeping only candidates that
beat the baseline.move_componentshifts one adjacent component by
a 2.0 mm step against a copy of the pads — the router, the grid
and the PCB are never touched, so routed copper stays byte-identical;
add_signal_layerre-plans with one plane index treated as signal
(advice about capacity, not a claim the plane is removable);
swap_pinsis a deferred stub for #5511 and evaluates nothing. The
search is bounded by a deterministic cap (3 edges x 3 refs x 4 steps)
and a 5 s wall-clock budget, and runs only when the board actually
overflows, so a feasible board pays 0 s. kct route --plan-gate(off by default): when the plan reports
feasible: false, print the report and exit 9 before any
detailed routing, on both the negotiated and the dense two-phase
paths. Exit 9 is shared with--census-advisory-gate(#4799) and the
stderr prefix ([plan-gate]/[crosstail-gate]) says which fired.
The override is the existing--force, not a second flag — note
it also disables grid/DRC validation, so to simply not gate, omit
--plan-gate.kct net-status --whyreads the sidecar. No new flag:--why
auto-discovers<pcb_stem>.routing_plan.jsonbeside the board and,
for each stuck net crossing an overflowed corridor, names that
corridor and its measured relief immediately before the
recommendation:line — a pre-route capacity measurement printed
alongside the classifier's inference from finished copper, never
replacing it. In--format jsonthis adds exactly two keys, and only
when a sidecar was loaded: a top-levelrouting_planblock and an
overflow_edgeper crossing diagnosis (injected inoutput_why;
StuckNetDiagnosis.to_dict()is untouched). Without a sidecar the
output is byte-identical to before, pinned by golden fixtures in
tests/fixtures/net_status_why_golden/. A sidecar built for another
board, or older than the PCB, is reported on stderr and ignored.- Fleet precision/recall table in
docs/reference/routing-plan.md,
printed byscripts/routing_plan_fleet_table.py(which reads
sidecars andkct net-status --format jsondumps — it never routes).
This replaces Epic #5510 Phase 1's two unmeasurable acceptance lines
with two falsifiable ones: recall (of the nets that really ended
unrouted, how many cross an overflowed corridor) and precision (of
the overflowed corridors, how many are crossed by an unrouted net).
Changed
- One clearance resolver for
kct route(Issue #5645, Epic #5509
Phase 2).router/clearance_resolver.pynow owns the required
clearance for every copper pair in one deterministic precedence:
explicit--clearance> legacy.kicad_pcbnet classes > project
floors (.kicad_druunconditional clearance,.kicad_prominimum
clearance and — new — theDefaultnetclass clearance, #5654) >
fab-tier floor > the router target, then per-net-class overrides and
the #4431 net-pair matrix. The clearance banner names which layer won.
See the upgrade note on routing clearance.
Performance
-
The pure-Python A* fallback stops re-deriving four things that do not
vary with what they were being re-derived for (Issue #5617). A py-spy
profile of the Diff-Pair regression job's re-route step now attributes
67.6 % of phase 4 ("Routing nets") to the GIL-released native C++ A*
and 20.1 % to the Python fallback; this takes about a third of that
Python remainder:ComponentHoleIndex.clearis a physical drill floor, so a
predicate of the candidate cell alone — yet it ran once in
_check_via_placement_cachedand again per non-plane layer inside
_is_via_blocked, 3–5 identical evaluations per via candidate.- The #5240 non-through-hole pad-drill sweep is likewise cell-only,
but ran on every_check_via_placement_cachedcall because the
sibling_via_cacheis bypassed wheneverallow_sharingis set —
exactly the negotiated mode the fallback runs in. _is_trace_blocked's #3229 Euclidean-disc kernel is a pure
function of the radius and the region offsets relative to the
centre, rebuilt fromnp.arangeon every neighbour expansion.RouteHaloGeometry.cell_knownreached the four occupancy planes
through a freshly allocated_CellViewand four bound-property calls;
it now indexes the same arrays directly, with the operand order and
short-circuit points unchanged.
The two via-site memos are tokened against the state they read — the
hole memo on(index object, len(index.holes), index.known), the
pad-drill memo on the identity of the arrays tuple
_non_th_pad_geometryreturns — becauseRoutingGrid.add_component_hole
andadd_padmutate the live index in place, mid-route, with no
router-side hook. Measured locally onboards/06-diffpair-test --seed 42
across six alternating arms, normalised against the native search to
cancel host load (which moved 5× over the 95 minutes they took): phase 4
−4.4 % (floor −2.0 % on the most conservative pairing),
_check_via_placement_cached−34.1 %,cell_known−35.6 %, the whole
fallback −20.9 %.diffpair_test_routed.kicad_pcbis byte-identical
across every arm. Method, the full line-level attribution and the six-run
table are retained in
docs/diagnostics/issue-5617/phase4-native-split.md. -
Faster exact-geometry clearance checks in the router. The lattice
engine's three pair kinds take a type-exact fast path through
clearance_kernel.copper_gap(Issue #5672, recovering most of the ~6 %
route-CPU cost the kernel migration added on board 02); the coupled
diff-pair halo's via refinement memoises its geometric half (Issue
#5696); and the coupled via predicate's three per-cell Python raster
sweeps become occupancy-plane slices (Issue #5720). Routed copper is
unchanged.