Repository navigation
Description
Deferred follow-up from code-health epic #1939. Evidence pinned to main @ 71b8c94. The maintainer deferred hole/feature leader convergence until after #1939 so that this goal remains limited to refactors that preserve successful drawing output. This issue remains open but is not an exit criterion for #1939.
Question
There are two leader-placement engines:
- Hole callouts go through
holes._place_queue, a strip-candidate queue built on_common.place_strip_candidatesand PAVA. - Other machined-feature leaders go through
leaders.place_feature_leader_jobs, a search plus a 407-linegreedy, reached fromfrom_model.py:3196.
holes.py never calls the leaders engine. ADR 2 says to extend a shared pass rather than add a copy.
Task
Investigate whether the split is justified, for example by something hole-specific such as tabulation or bolt circles, or whether it is historical.
- If historical, propose a convergence plan.
- If justified, write the reason in
docs/architecture.md.
This is a maintainer decision before any code moves, because it may touch ADR 2.
Investigation and agreed direction (2026-09-28)
A fresh read-only agent found no hole-specific drafting rule that requires a permanent second leader engine. Sparse ordinary and pattern holes already use the late FeatureLeaderJob inventory. The remaining split preserves plan/side PAVA row order, binding authored side, physical rim tips, pre-staged bolt-circle furniture, and dense-hole table escalation/rollback. Those are producer and transaction contracts to carry into the shared solve. The maintainer has already authorised convergence in small verified PRs if no hole-specific reason exists; no ADR text change is authorised without sign-off on exact wording.
Progress: #1974 added the candidate-stream adapter. #1989 moved front/rear hole leader rim-tip, elbow and Leader construction into FrontHoleLeaderCandidateAdapter with exact live corpus parity and CI; row selection and strip commit still use the existing engine. Dense/profiled migration and final convergence remain open. ADR 2 text is unchanged.
Migration worklist:
- Extract a reusable hole candidate adapter for row, side, rim-tip and fallback candidates without changing commit behavior.
- Migrate front/rear and profiled holes separately; retain PAVA row seeds and physical-tip constraints.
- Migrate dense scattered holes last, preserving table escalation, grouped balloon and furniture rollback after the final leader outcome.
- Remove the duplicate commit engine only after placed/dropped measurement IDs, labels, owners, furniture, tables, authored-side refusal, lint and live corpus signatures match. Include forced budget/failure cases and no benchmark regression.
2026-09-30 next-seam audit on unpublished 0f9534c9
No small direct reroute of remaining hole paths through place_feature_leader_jobs was found that preserves successful drawings. Sparse plan/side jobs already share a HoleStripPlan and late candidate inventory. Dense/profiled _place_immediate_queue commits only final PAVA survivors, assigns hc_* names after drops in natural-Y order, and adds furniture after placement; the shared path reserves names and stages furniture before a late solve that can choose alternate rows/sides. Front callouts use a distinct below-view strip, approved-X-witness text side, and front_hole_callouts trace. producer_floor=True still applies different validation/drop rules, so a direct route can change identity, furniture, trace, or placement.
The next staged step is an exact, preconditioned behavior guard across immediate/front, dense/profiled, authored-side and deferred-replay cases, including name, owner/measurement, geometry, issue/drop, furniture and trace signatures. Only then should an ordered preselected-PAVA survivor transaction be considered for the shared rank-4 commit owner, without rerunning joint assignment. The intended deletion target is the 104-line immediate emitter, but a net reduction is a design target, not a proved patch. No production code or ADR text changed in this audit; full convergence and no-behavior-change acceptance remain open.
2026-09-30 local pre-convergence guard
The test-only slice b5badaf9 in /private/tmp/dw1937-hole-outcome-guard records existing immediate dense hole callout name/order, owner and measurement identities, profiled bore routing, front below-view placement and trace linkage, and pattern furniture rollback on an immediate drop. It stays in behavior-owned test modules and does not change production or ADRs. Fourteen focused/shape/clone cases passed; an immediate emitter-order mutation and a front producer-order mutation each failed named assertions after substitution was confirmed, and a provenance mutation failed the dense owner guard. Fresh independent review found no P0–P3 issue after fixed front Y coordinates were replaced with legal-bounds and trace-to-rendered-elbow checks. This guard is local and not merged; it does not by itself prove parity for a future engine migration. It will accompany the next actual #1937 convergence slice rather than trigger a separate CI cycle.
2026-09-30 preselected-commit design check
A local production prototype on the reviewed guard branch preserved byte-identical 14 CAD plus three STEP drawing/lint/decision/trace signatures against 0f9534c9; four focused dense forced-text/Policy-B, profiled Double-D, and front-trace cases passed. It was discarded before commit: removing the 104-line immediate emitter required a 46-line generic coordinator and 68 new lines in the hole queue, added eight callback parameters, and saved only ten net production lines while enlarging _place_queue. This moved complexity rather than materially converging the engines. No benchmark was run for the rejected design. The clean local branch 6568df7a retains only the reviewed test guards; no production PR, CI, or ADR change followed. #1937 remains open for a simpler typed survivor transaction that preserves exact PAVA outcomes, identity, rollback, and trace.
2026-09-30 local architecture-map correction
Reviewed docs-only local commit 1d19f9c8 (after unpublished 636a34d4) records the current three placement paths in docs/architecture.md: sparse plan/side PAVA seeds followed by late joint inventory; front/rear below-view strip survivor commit; dense/profiled queue-wide immediate PAVA survivor commit. It names shared physical construction and the immediate/late commit_feature_leader seam, plus the ownership, furniture, indexing, authored-side, and trace contracts future convergence must preserve. Fresh review caught and fixed an incorrect front/rear shared-commit claim and an overstatement that would have treated the split as permanent; final review found no P0–P3 finding and static/docs gate passed. The document changes no ADR wording or production behavior. This is migration documentation, not acceptance of a permanent exception to ADR 2; #1937 remains open. No PR/CI or merge under the current branch-write approval block.
2026-09-30 dependent documentation integration
The corrected architecture note from isolated 1d19f9c8 is now incorporated unchanged as fb1a74d9 in the dependent /private/tmp/dw1939-fourth-local unit alongside a #1935 duration-data refresh. Exact-head static/docs gate and a fresh independent combined-head review passed with no P0–P3 finding. It describes the existing migration state; the engine convergence work and #1937 remain open. No PR/CI or merge under the current GitHub branch-write approval block.
2026-09-30 maintainer deferral
The maintainer chose to postpone this convergence until after epic #1939 and keep the current goal on output-preserving refactors. The existing architecture map documents the split; that does not waive ADR 2 or close this issue. A future solution needs either a simpler exact-parity convergence or maintainer sign-off on specific ADR 2 wording for a justified exception. No production code or ADR text changes under this decision.
Activity
Extract hole leader candidate streams (#1937) (#1974)
pzfreo commentedon Sep 28, 2026
First convergence slice merged in #1974 (
321c95cc). Ordered physical candidate streams for sparse plan/side hole leaders now live in a rank-4 adapter feeding the existing shared late leader assignment. The hole pass still owns strip solve, table eligibility, furniture/coverage transaction, and immediate commit. Dense/profiled paths are unchanged.Independent review checked row order, authored side, physical tip ownership, fallback floors, and transaction behavior; its architecture-map finding was fixed. Focused tests, exact three-hole leader/lint parity, static checks, and all CI jobs passed. No ADR text changed. Remaining engine convergence stays open under this issue.
Extract front and rear hole leader candidate geometry (#1937)
Extract front and rear hole leader candidate geometry (#1937) (#1989)
pzfreo commentedon Sep 29, 2026
Fresh read-only investigation after #1974/#1989 found no safe small additional convergence slice that preserves exact drawing and solve-trace behavior. Sparse plan/side holes already enter
FeatureLeaderJob. Front/rear holes still commit ranked PAVA rows throughplace_strip_candidateswith thefront_hole_calloutstrace; moving that commit to the feature-leader search would change selection and event identity. Dense scattered and profiled holes keep an immediate_place_queuepath whose final names and coverage govern table escalation and staged furniture rollback. #1989 already shares front physical leader construction.No source or ADR text was changed. #1937 remains open. A next migration needs explicit parity gates for PAVA survivors, trace events, measurement coverage, table escalation, and furniture rollback, including forced failure/budget cases. The active #2027/#2036 leader refactors should settle before attempting that transaction change.
Extract sparse shared hole leader build into candidate adapter (#1937)
Extract sparse shared hole leader build into candidate adapter (#1937)
Extract sparse shared hole leader build into candidate adapter (#1937)
Extract sparse shared hole leader build into candidate adapter (#1937)
pzfreo commentedon Sep 29, 2026
Next convergence slice: #2098 is open against the reviewed #2084 stack tip. It shares physical hole-callout leader construction across direct, front-strip, sparse-shared, and immediate dense/profiled paths while preserving each path's selection, solve, rollback, and commit rules. A fresh independent review approved it; static/focused checks, a load-bearing mutation, exact 14 CAD + 3 STEP drawing/lint/decision/trace parity, and paired timings passed with no measured regression. Required GitHub CI is pending. The separate commit-engine convergence acceptance remains open.
Integrate reviewed code-health slices with one CI gate (#1939) (#2102)