kerfmaster pin list · UI / workflow decisions
rulingmixedd11A decision by Aristide or Jordan. True because it was decided; it can be superseded, but it cannot be stale.
Content last changed 2026-08-03 — computed from the item itself, not typed.
Contract — Cross-cutting stage
This contract states a decision, not an implementation.
takes —
makes —
fails if A stage that runs without an accept gate; a result with no provenance; the engine reachable only through the UI; a customer file leaving the box.
Contract last changed 2026-08-06 — computed, not typed. Dated separately from the text above, so neither date can speak for the other.
⚠ Known defects
This item's subject has a known defect in the code. Recorded and deliberately NOT fixed — recording a defect is not a licence to fix it. Source: cadmaster/defects.json → cadmaster/KNOWN_DEFECTS.md, not this page — the text below is generated from the register so the two can never disagree.
How the app is built and how it feels to use. Decided with Aristide 2026-07-26; two decisions are locked now because retrofitting either one later is a rewrite.
Heal / QC / tabs / leads / nest / post live in a core with no UI dependency, behind a thin API. The same core then drives the CLI, a local desktop install, and a hosted version. Separating this at the start is free; doing it after a UI is built is not.
⚑ Half honoured, 2026-08-03. The engine modules really are UI-free — heal.py, emit.py, qc.py, bridges.py and dxf_io.py emit no HTML and print nothing outside their __main__ self-tests. But there is no API and no CLI. The only two things that run a pipeline end to end are build_board.py and build_vec_board.py, both of which read sys.argv at module level and execute at import (which is why they must never be imported). They share no orchestration code: the front halves differ on purpose (a DXF is HEALED, an .ai is FITTED) but the tail — qc.analyze → emit.write_dxf / write_gcode / write_gcode_macrob → board HTML — is written twice. The audit called that "duplicating the orchestration wholesale", which overstates it; the duplication is real but it is the tail only.
Every stage records why it did each thing, not just the resulting geometry.
e.g. 47 segments spanning 91.3° → one R0.375 arc, max deviation 0.4 thou
(tol 10); reason: repeated equal turns at equal spacing = coarse arc, not a corner.
This single mechanism pays for three separate goals: the educational tool (click any entity and it explains itself, on the operator's own part — beats any tutorial), the audit trail, and our own debugging. Cheap if designed in, a rewrite if bolted on.
⚑ Not honoured anywhere, 2026-08-03 — and this pin says why that is expensive. No stage records a reason. heal.heal() returns (prims, meta) where meta carries counts and coordinates only (native_arcs, corners, borderline, splines, corner_pts, micro_pts, gate, fit_target) — no per-decision explanation, nothing that could render the example above. The decision is locked; the mechanism does not exist yet.
Many shops sign NDAs, so "upload your parts to our cloud" dies in the customer's compliance questionnaire regardless of how good our security is. That is a sales blocker, not a technical one.
Answer: a local web app. The UI is HTML/JS in a browser, but the server runs on the shop's own machine bound to localhost — files never leave the building. Same codebase ships two ways: local install for NDA shops, hosted for shops that don't care. Selling line: your files never leave your building.
Cost note: coding difficulty is about the same either way. The real cost of local is distribution — per-OS installers, code signing, auto-update, antivirus false positives on bundled Python, and harder support.
Adopt the Adobe philosophy — a Window menu listing every panel, so the app's full power is discoverable in one place while the screen stays quiet. But take the whole pattern: what actually rescues Adobe from sprawl is workspaces (curated default layouts + a Reset command), not the floating itself. Panels alone would just relocate the mess.
What actually makes it feel easy is not the window system: it's one obvious primary action per stage, and panels used only for inspecting and overriding. If you must open a panel to do the job, the design failed. Ties to item 11 — defaults do the work, and a panel is simply the override surface, hidden until wanted.
Make the pipeline visible, not a hidden sequence: a stage rail
Load → Heal → QC → Tabs → Leads/Order → Nest → Post,
each stage showing its state (not run / running / clean / flagged / accepted-by-whom).
Why this beats Metacam: Metacam gives you output. We give you output plus the reasoning, signed off by name.
Per-user logins (local accounts in the local install), so every accept is attributable. Wanted explicitly for workflows where specialists own different stages.
⚑ Needs Jordan: (1) how many screens do shop stations really have, and is a second screen for the canvas realistic? (2) Who accepts which gate in a real shop — is the specialist split real, or does one operator run the whole job? (3) Would per-user login be accepted on the shop floor, or is it friction they'd bypass? (4) What does he want the educational layer to explain first?
⚑ Still open: the target-user density question — Aristide wants it learnable by a fresh operator and powerful for a Jordan. Default workspace presets are how we serve both; which preset is the default is undecided.
src — Aristide, design discussion 2026-07-26 (Adobe-philosophy windows, NDA constraint, educational goal, audit trail for specialists). Jordan's round pending.