roadmap

name	roadmap
description	Use at the start of an autonomous or unsupervised session to pick what to work on, when deciding whether a geometry case is worth chasing, when a task looks like something a past session already tried, or before claiming a case is closed. The sanctioned work-selection doctrine: what is open and ready, what is terminal, the chase filters, and the acceptance bar.

Roadmap: choosing what to work on

This is the sanctioned work-selection doctrine for autonomous sessions. It says what is open and ready, what is TERMINAL (do not re-attempt without new tooling), which work to chase and which to skip, and the bar a case must clear to be called closed.

This is a LIVING document: maintenance is mandatory

When a session closes, defers, or discovers a work item, it MUST update this skill in the same PR. A stale roadmap is worse than none: past sessions burned large budgets rediscovering dead ends this file was supposed to name. Keep every entry to ONE line with a pointer (a test path, a git-history PR number, a memory-free source file) that carries the detail. Never duplicate the detailed truth here; point at the repro. Closed-campaign narrative is rot: when a case closes, collapse its entry to one line plus its fixture/PR pointer in the Closed section, and delete the dig log.

The #[ignore] inventory is the load-bearing artifact. Before quoting any "deferred" claim, regenerate and reconcile it:

rg -n -A2 '#\[ignore' crates/    # filter the doc-comment false hits by hand

Inventory status (2026-08-15): ZERO deferred-defect pins — kumiko_diagonal_strut_fuse_is_exact is ACTIVE (the corner-window frontier closed). Every remaining #[ignore] is an explicit diagnostic or a slow-test marker. Known stale-but-harmless: the profile_intersect.rs box-sphere probes (box-sphere shipped analytic in #1006), staircase_fuse_with_cylinders (~2 min perf run), the two #696 dovetail entries and diverge_first_cut (print-only).

When to use

• Starting a session with no assigned task and needing to pick high-value work.
• A task resembles something that may already be tried, closed, or proven impossible.
• Deciding whether an analytic-recovery or parity case is worth the budget.
• Before writing "this case is closed" anywhere.

The north star

Replace the incumbent kernel in the gridfinity layout tool (~/Git/gridfinity-layout-tool) at full parity, across all its generator scenarios: 100% triangle correctness, volume correctness, manifold correctness, AND generation performance at least as good. Parity first, then beating it, is the acceptance bar. See parity-benchmarking for the harness.

Where that stands: REACHED AND SHIPPED (2026-08-13) — the tool pins brepkit-wasm 3.2.38, its full generator suite is green on every bump (issue #1517 closed at 0/2790 on 3.2.36; see the Closed entries). The 3.2.38 parity matrix reads 0.45x aggregate with brepkit faster on 25 of 26 rows (the last is a 1.04x noise-band watch) and 0 non-manifold scenarios vs the reference's 5; all four primitive-boolean fallbacks are exact analytic. Per-PR history and per-row numbers live in git, MEMORY.md, and the bench harness — do not re-record them here. Native criterion CAVEAT: the cad_operations "mesh sphere" case runs a bench-local PER-FACE shim ~40x lighter than the solid-level path — never compare it to solid-level numbers (perf_probe has the matching native figure).

The lesson that most reshapes triage: not every scenario failure is a boolean fallback, and many are not geometry at all. The honeycomb triangle blow-up and the compartment non-manifold family both replayed with ZERO mesh fallbacks (roots were tessellation density, shared-rim meshing, face orientation), and 18 of the 21 divider/floor failures were a missing brepjs ADAPTER method that threw before any geometry ran. So: measure where the failure actually is before assuming GFA — capture the real boolean traffic and replay it natively (recipe under "Tool-side measurement recipes"). A family that fails in seconds is failing pre-geometry.

The priority filters (rules with reasons)

1. Chase operations that RE-CREATE an existing analytic surface type. Do NOT chase ops that INVENT a blend or approximation surface. A boolean or revolve result face is a trimmed patch of an input surface, so it is always closable with the right split. Fillet and chamfer walls, general sweep and loft side faces, and offsets of NURBS input introduce a NEW surface with no closed form; they are fundamentally approximate. See analytic-preservation.
2. Solve the NARROW case (coaxial, perpendicular, equal-radius), not the general problem. Every primitive-boolean win was gated to one specific configuration and defers to the generic marcher otherwise. Sessions that reached for a general solver burned budget and shipped nothing.
3. Prefer work with a stable primitive repro over work that needs tooling first. The four primitive-boolean cases (stable repros in crates/operations/examples/approx_census.rs) were picked over the tooling-blocked scoop case for exactly this reason.
4. After ANY GFA or boolean change, re-probe scenario face counts before claiming anything. Scorecards rot silently; a stale one once hid a regression through a whole release. This is mandatory, not optional (see parity-benchmarking).

TERMINAL cases: do not re-attempt without the named missing primitive

Several past sessions burned large budgets rediscovering these. Each needs a component that does not exist yet; without it, stop.

• Equal-radius perpendicular cylinder-union RENDER. The exact seam is a self-touching figure-eight (a genuine non-manifold singularity, odd Euler). The shipped artifact (#1008: analytic B-Rep whose marched-NURBS seam dodges the touch, plus exact closed-form volume) STANDS. Needs a face-split-at-pinch primitive on a periodic wall, or a periodic-aware crossing-holes mesher. There is no exact_cylinder_cylinder symbol; do not go looking for one.
• Plane-by-sphere splitting across the chord-discretized equator. The general capability behind box-sphere; a section circle's crossings miss a polygon-approximated equator by the sagitta. Box-sphere was closed (#1006) with a case-specific seam-plane fit (rg -n 'seam_plane' crates/). The general fix is a UV-space arrangement splitter, a dedicated multi-day component not yet built. The boundary-plane crossing technique is proven and reusable.
• Gridfinity scoop fuse (3x3 scoop+label+lip). Root: a lip-foot cone must be split with a coordinated staircase cone-split plus bracket-cap re-trim sharing the new edge; every one-sided attempt regresses. Many sequential autonomous passes exhausted. Parity is already MET via a correct-but-slow mesh fallback (this is perf-only). In-memory repros exist (crates/io/tests/scoop*_inmem.rs); the blocker is the coordinated split, not tooling.
• A universal smarter merge-key for duplicate edges. PROVEN UNBUILDABLE. The gridfinity lip corner (chord + arc, same endpoints) MUST merge; the torus-box in-tube lens (line + co-endpoint arc) MUST stay distinct. No merge-key discriminant separates them; the distinction is global. Sanctioned pattern: splitter-side midpoint splits, per case, so no two edges share both endpoints, and leave merge_duplicate_edges (in crates/algo/src/builder/builder_solid.rs) alone. Control the geometry you emit; do not make the shared merge smarter.
• Pinch-shim double-cover mesh residuals (groupedScoop case2 nm=75). Two coincident face meshes span the same region by construction, so shared rim edges carry 3 triangles; inherent to the shim encoding — the alternative is the face-split-at-pinch primitive above. Sub-export-tolerance (tool suites 7/7); parked in this row on purpose.

OPEN: ready or gated work

Item	Status / next step
4x4 mag no-lip noise-band watch (1.04x on the 3.2.38 matrix)	The only row the reference leads; has oscillated 1.00x-1.06x across 3.2.36-3.2.38 with no kernel change targeting it. Watch, do not chase, unless a fresh same-day matrix shows a real drift
Mesh-boolean fallback emits OPEN meshes that are CONSUMED	A product call, not just a fix: rejecting means the op fails outright. Mitigation shipped: boolean::mesh_fallback_count() + wasm meshFallbackCount() let pipelines snapshot-and-refuse
Export angular default (5°) vs the reference's coarser effective default	Tolerance-parity product choice, not mesher waste: 5° forces 18 segments/quarter-arc on r=0.6 slot corners, ~1.7x triangles vs reference at fine deflection. Revisit only as a product decision
Marched FF sections carry pave_block_id=None	Architectural note without a live repro (the snapClip op-cut-3 case replays clean, fixture snapclip_export_corner_inmem.rs ACTIVE). If a new leak lands here, the canonical altitude is pave-block attachment at phase-FF/make_blocks — every face-splitter-level attempt broke calibrated chains
v1 fillet deprecations entangled with the public wasm API	try_fillet still reaches deprecated fillet/fillet_rolling_ball; migrating changes public behavior — a product decision, not safe cleanup. See fillet-blend, wasm-bindings
crates.io / GTM items	Andy-only. Publishing infrastructure works (see MEMORY.md for the release-please continue-on-error masking gotcha)

Closed: root cause + where the detail lives

One line each; the fixture/PR carries the story. Newest first.

• Kumiko corner-window strut fuse (CLOSED 2026-08-15, ten roots, #1599-#1616; pin kumiko_diagonal_strut_fuse_is_exact ACTIVE) — exact watertight fuse (70 faces, free=0 over=0); every root was marched-geometry ~1e-6..1e-5 drift meeting an exact-tol gate (endpoints, vertices, tangents) — fixed by weld-scale bands with 10x ambiguity guards or shared-anchor adoption at each altitude. Fixtures and instrument census: crates/io/tests/kumiko_strut_fuse_inmem.rs + replay_pair. Tool-side verified same-day on 3.3.7: generator suite 2883/2883 (292 files) vs a 2883/2883 control on 3.3.0, wall 221s vs 229s; head-to-head matrix 0.49x aggregate (10476ms vs 5155ms), nm 0 vs 5, only the three known scoop-family reference double-cover volume flags.

• bp 6x4 magnets residual + every baseplate row (CLOSED 2026-08-13 on released 3.2.38; row 775 vs 1383ms = 0.56x, was 1.10x; aggregate 0.45x, faster 25/26) — the #1488-era "no dominant stage" reading had rotted: pocketsCut owned the deficit (825 vs 466ms wasm). The 24 pitch-aligned pockets touch rim-to-rim (38 grid adjacencies), fuse_n's welded union is genuinely non-manifold so the by-edge-id gate rejects it, and fuse_cluster fell back to 23 pairwise accumulator fuses: ~24 wasted GFA runs, 501ms native for a 31ms cut. Fix #1590: contact-thin compound-cut shortcut (every pairwise tool-AABB intersection at most 100·tol thick in some axis → combine tool shells verbatim, cut once; interpenetrating pairs like the coaxial magnet+screw drill take the fuse ladder; fallback taint falls through unchanged). Lifted bp 2x2 plain to 0.18x and bp 4x4 plain to 0.16x as collateral. Fixture bp64_pocket_compound_cut_inmem.rs; instrument BK_GFA_TIME (native-only per-stage wall clock, the tool that separated merge waste from arrangement cost). lightweightFloorCut's 253ms native is the genuine big-base cut, not merge waste — the remaining lever on this row if ever needed.

• 2x2 label bracket scenario-first row (CLOSED 2026-08-13 on released 3.2.37; matrix row 34 vs 66ms = 0.52x, was 2.3x slower) — the tool's redesigned bracket (finger strips in the cavity-wall plane, changed since the Aug 9 #1510 capture) made its wall cuts ride collinearly on the top ring's inner boundary; the hole weave's whole-window midpoint sat exactly ON the hole polygon and the on-boundary ray-cast verdict flipped between the mirrored walls, so the +x corner lune never split out of the ring: exact fuse open (3 free edges) → 121-face mesh fallback → paid TWICE (brepjs fuseAllBisect: fuseAll bail discarded 95ms, pairwise redo kept 99ms — 195 of the row's 240ms). Fix #1587: collinear-overlap window splitting + explicit riding-piece drop in integrate_holes_plane, and 2-solid fuse_all groups take the pairwise contract (a pair has no batch to protect; the bail only double-billed degraded pair fuses). Fixture . Same-day 3.2.37 matrix: aggregate 0.63x, faster 24/26, nm 0 vs 5; the three volume-FAIL rows remain the reference's own double-cover over-count. Durable: only scenario-first numbers are kernel comparisons in the labelBracketPerf harness (warm repeats are parameter-cache hits on both sides).

Refuted: do not re-try

• Clip-level inner-wire trimming in clip_line_to_face_boundary — even endpoint-only single-window trimming regressed three foils (groove_chain, dovetail a1corner holecut, exact_coincident_lip_fuse); the holed-face weave requires untouched sections (#1563). Do not retry any clip-level variant.
• Vote-layer rules for on-plane samples in the ray-cast classifier — the honeycomb and circleinsert flip points are formally inseparable at that resolution; four rule variants each broke one side. #1567 fixed the real root with analytic circular holes instead.
• A universal smarter merge-key for duplicate edges — see TERMINAL; unbuildable.
• Placing the thick-wall collapsed corner EXACTLY (nᵢ·(x−C) = radius − thickness) — geometrically right, measured WORSE (20 → 318/544); moot with the chamfer strip shipped.
• Ungated pendant-chain bridging in the face splitter — fires at healthy corners and over-connects (use-3); the shipped version's three gates (section-free target, mutual nearest, isolation) are each load-bearing.
• Cluster-canonical vertex adoption in JunctionRegistry::resolve — net-negative; consumers that bypass endpoint resolution keep their own anchors.
• Narrowing the DCEL-rescue gate by kumiko loop signature — loop shape does not separate the corner wall from goma's bands (goma byte-identical under it).
• "The constraint is the SPLIT ITSELF disturbing reconciliation" — the newly-admitted splits were straight axis-aligned runs stored as NurbsCurve; a span-local sagitta gate fixes it.
• shell_is_outward_oriented / signed_volume_of_shell being inverted — both exact on a known-good cube (flux_orientation_probe.rs); the operand really was inward.
• The goma odd bands as a GFA defect — they were brepkit's own mesh-fallback output.
• Ellipse aliasing at FF filter 2 on the goma lump — a genuine 2× separation, not aliasing.
• Also refuted, each once: coincident coaxial cylinders as the corner-cut root; a classification error there (independent oracle agreed with GFA); plane-gated seed correction; arc-cornered wires as the nested-hole trigger; helix sweep as the goma cause (helical_sweep_is_watertight_across_turns_and_segments); upstreaming the brepjs intersectCurves eager-release (brepjs pins the cache-alive contract).

Recurring traps (the distilled, expensive lessons)

• A circular edge has ONE canonical span and it is not the short one. EdgeCurve::domain_with_endpoints is the CCW range from start vertex to end vertex, routinely a major arc. Any new "which part of the circle does this edge cover" test must call it or reproduce it exactly (#1540). Taking the short way does not merely lose crossings, it invents them on the complement.
• Validation-clean is not winding-clean. A globally mirrored solid (every wire wound against its face flags) passes validate_solid WITH orientation checking, positive oriented volume, and a clean directed mesh — pairwise opposition and surface-derived normals all survive the mirror. The only symptom is a downstream boolean minting same-direction shared edges from "clean" operands. When that happens, audit the operand CONSTRUCTOR's winding emission first (extrude shipped mirrored CW-profile prisms for a long time), and remember the trimmer/splitter Left/Right frames follow wire traversal — never predict them from geometry alone.
• A whole-solid volume cannot tell a MISSING cavity from a COLLAPSED one — both read high by the same amount. Print per-shell signed volume against each shell's own bbox (cargo run --release --example cavity_probe -p brepkit-io) before blaming either the boolean or the measurement (#1536).
• A hole can only be carried by a region larger than itself; a shared-corner probe fakes containment. The splitter's first-vertex hole matching + first-match order handed a 6577-area mouth loop to a 1.26-area notch because the traced loop STARTED at a shared corner and the strict ray-cast read it inside (#1536). When auditing hole attachment, check area dominance before trusting any point probe. Per-face signed-volume census (shell_face_census) is the cheap way to spot the resulting same-sense doubled cover: one face's contribution has the wrong sign for its shell.
• Measurement and tessellation walk different face sets. Tessellation uses explorer::solid_faces (outer + inner shells) so the MESH is complete, while several volume/area/CoM paths walked outer_shell() alone — closed, manifold and correctly bounded, with the cavity silently absent from the number. Fixed for volume, area and centre of mass; when adding a solid-scoped measurement, use solid_faces.
• Never compare closed-curve directions through their parameter frames. A closed circle's domain_with_endpoints anchors at the curve's own reference direction, so evaluating two coincident circles at matching parameters compares unrelated angles (a quarter-point test read opposing circles as same-direction). Compare TANGENTS at a shared 3D point ( in fill_images_faces).

Tool-side measurement recipes and traps

• Scenario numbers rot. Always run the control on the SAME DAY and SAME catalog; a stale baseline has twice nearly produced a false conclusion. Confirmed again 2026-08-10: the issue's "137 failed on 3.2.18" re-measured as 154 on the same kernel, because the catalog had grown. Quote a delta between two runs you did yourself, never against a recorded number.
• The reference kernel's volume is NOT an oracle where its own mesh is non-manifold. Three of four volume "failures" in the head-to-head matrix were against reference meshes carrying 970-1809 non-manifold edges (Euler 1230-2375) reading HIGHER than brepkit's clean ones — the double-cover over-count. Check nonManifoldEdges on BOTH sides before believing a volume delta.
• A per-kernel .brepkit.snap triangle count is not a defect signal. Any correct change to how a face splits moves it. 11 of 16 apparent regressions in the 3.2.22 run were stale baselines; separate them out before counting, or refresh them first.
• Measurement worktree recipe (2026-08-10, worked end to end): git worktree add .worktrees/<name> origin/main --detach inside the TOOL repo, pnpm install, edit the brepkit-wasm pin in its package.json, pnpm install --no-frozen-lockfile. Verify with require.resolve('brepkit-wasm', {paths:[require.resolve('brepjs')]}) plus a sha256 of the .wasm — resolution THROUGH brepjs is the part that catches a nested copy. Drive ./node_modules/.bin/vitest directly. --reporter=basic is not a vitest 4 reporter and fails as a missing custom module. A full generator run is ~45 min at --maxWorkers=4.
• Current baseline (2026-08-07, released 2.129.13 era, stock pins): the ENTIRE tool generator suite is GREEN — 272 files, 2720 passed, 0 failures. Compare against a fresh same-day run, not old counts (the catalog grows continuously).
• Overlay verification is mandatory and non-obvious. Hash the file that require.resolve('brepkit-wasm', {paths:[require.resolve('brepjs')]}) returns, run FROM the directory vitest will use. The foils worktree has its OWN node_modules. For a brepjs-side change, npx vite build then copy dist/*; methods live in content-hashed shapeTypes-*.cjs chunks, so grepping brepjs.cjs reads as "fix missing". The vitest resolve.alias does NOT reach the CJS require path — overlay node_modules and hash-verify, or you silently bench the installed kernel.

Subsystem trap notes (crates without their own skill)

• validate_solid mis-reports a multi-component shell as an Euler error. A 2x2 socket assembly is 4 disjoint feet in ONE shell (V-E+F = 8, correct at 2 per component); the validator expects 2+L. The ops boolean gates handle this (euler_multi_ok), the standalone validator does not — never "fix" a fixture to satisfy that report, and never gate a multi-foot operand on is_valid().

• The free/over edge census cannot see winding damage. A result can read free=0 over=0 with same-direction shared edges the validator counts (the #1538 pocket cuts mint 8-9). validate_solid's orientation check or the halfedge oracle (audit_bin) are the instruments; replay_wire_audit prints unclosed chains and same-direction positional pairs directly.

• heal fix_duplicate_faces IS implemented (solid-scoped, crates/heal/src/fix/solid.rs, returns Status::DONE2), not a no-op stub. It compares only centroid, normal, and edge count, so it can miss true-but-differently- wound duplicates. Verify current state before quoting either way.

• heal, offset, and sketch have no distilled campaign knowledge. They follow the same debugging-doctrine, but no skill covers their internals. Treat any diagnosis there as first-of-kind and write findings down.

Acceptance bar for a geometry campaign case

Every box before "closed":

• Exact analytic result where the inputs are analytic (typed faces, single to low-tens face count, not hundreds).
• Watertight tessellation (zero boundary edges).
• Manifold B-Rep (every edge used by exactly two faces, Euler balanced).
• Full workspace suites green, INCLUDING cargo test -p brepkit-wasm --lib gridfinity (running only algo/io/operations has shipped a gridfinity regression before).
• Regression fixture shipped with the fix (STEP or arena .bin; see testing).
• Census clean or improved: the row flips FALLBACK to analytic (cargo run --release --example approx_census -p brepkit-operations).
• Head-to-head timing at least parity (the brepjs wasm bench; see parity-benchmarking).
• Release published when user-facing (see release-flow).

Anti-patterns

• Do NOT re-attempt a TERMINAL case hoping this time is different; it needs the named missing primitive, not another pass.
• Do NOT reach for the general solver when the narrow case is what parity needs.
• Do NOT call a case closed on an "exact analytic" census row alone; the census does not check correctness (see analytic-preservation).
• Do NOT quote a "deferred" or face-count claim without regenerating the inventory and re-probing scenarios; both rot silently.
• Do NOT close, defer, or discover an item and leave this skill unchanged — and when closing, DELETE the dig log rather than appending to it.

Related skills

analytic-preservation (the chase filters in depth), parity-benchmarking (the scenario re-probe and head-to-head), debugging-doctrine (before any multi-pass dig), solid-verification (the acceptance oracles), testing (fixtures and ready-repros), fillet-blend (the blend traps), release-flow (shipping a user-facing close).