fix: try the scale step on the selected page before spending the ISO and the sheet (#1338)

[pzfreo]

Fixes #1338. Two commits: the fixture the tests need, then the fix.

The defect

The automatic ladder's only recovery order was drop the optional ISO, then escalate the
page, so an incomplete plan could settle on a candidate strictly worse than one it never
reached. GRM-03 (28.7 × 10 × 10 mm) settled on 5:1/A3 without its ISO while
5:1/A4 is clean with it — same scale, smaller sheet, pictorial view retained.

Raising the drawing scale is how the ladder buys annotation room, and text height is fixed
in page mm — so every step up it shrinks the text relative to the part. Spending a sheet
size and an optional view before trying the cheaper move on the sheet already chosen was
the wrong order.

The fix

The bounded larger-scale trial on the already-selected page — the one #1155 added for a
conservative recovery detail — now also runs when the plan is incomplete, and runs first.
Both callers share one helper (_try_larger_scales_on_selected_page) instead of a second
copy of the loop.

Unchanged from #1155's contract: the hard two-candidate budget, confinement to the settled
page and arrangement, compilation through the ordinary pipeline, and a win only by passing
the same structural, required-outcome and (when the failure was axial) axial-coverage gates
the larger sheet would have had to pass. Every attempt, rejection and winner is still
recorded in the structured scale decision.

Measured

pmi="off", on the fixtures:

	before	after
plain grm03 fixture	5:1/A4, no ISO	5:1/A4, with ISO, no error/warning issues at all
grm03 AP242+PMI	5:1/A3, no ISO	5:1/A4, with ISO, same one code either way
five-step synthetic (#1299)	5:1/A3, no ISO	5:1/A4, with ISO, all five step lengths
explicit page="A4"	incomplete 2:1 (2 shoulders unlocated)	5:1/A4, axial_length_missing gone

"Same one code either way" is the honest form, and CI is why this line reads as it does — see
below. The AP242 fixture and the five-step profile each carry one pre-existing
annotation_ink_overlap ('2' draws 2.2 mm of line-work through the label '0.5'), and it is
identical on the A3 fallback this change avoids. The recovery neither causes nor cures it —
it is the step-chain collision class tracked by #1331 / #1333. No candidate carries an error,
a dropped outcome, or a missing axial length.

An explicit page pins the sheet, not the scale, so the trial applies there too: it fills
the sheet the caller chose instead of returning an incomplete layout on it.

GRM-03 with pmi="annotate" is deliberately unchanged at 10:1/A1. The same-page trial is
attempted and rejected (recovery_detail_retained, then structural_error), so this does not
paper over #1336 — that issue is about what a single dropped callout may buy, and stays open.

Test expectations that moved

Ten tests failed on the first full run. Each new outcome was verified as the better drawing
before the expectation was rewritten — none was adjusted to whatever the code now prints:

• needs repro: turned step-length chain phantom sub-mm step (GRM-03 #298 secondary) #443 (2 tests) — its actual requirement is the truthful step lengths, and they still
  hold; what the replan spends to get them changed, so "iso" not in views became "iso" in.
• Automatic axial-coverage recovery cannot escalate the sheet after same-page replan fails #1299 (6 tests) — the real-part ones now assert same-page recovery; the two fakes gain
  the two rejected same-page trials, and one needed a (297, 210) page mapping. Page
  escalation itself stays covered by the fake bounded-recovery test and by Lower AP242 thread, tapped-hole and knurl requirements into typed drawing intent #1298's GRM-03
  pmi="annotate" acceptance.
• The machined-feature leader pass builds throwaway OCC geometry for every candidate it measures #1308 — golden bbox dict gains note_iso_nts; the other 16 boxes are byte-identical.
• docs/multi-feature-object-reference-workflow.md — no longer quotes the four
  authored_views lines: with the automatic plan intact the emitter authors no view block.

New tests assert the precondition (2:1/A4 genuinely is axially incomplete, so the recovery
is exercised) and that relaxing the named mechanism changes the outcome — with
_AUTOMATIC_UPSCALE_TRIAL_LIMIT monkeypatched to 0 the same part falls back to the pre-#1338
A3-without-ISO result.

The first CI run failed — what it was

The first push failed one test on all five Linux legs: my own
test_automatic_recovers_on_a4_at_a_larger_scale_instead_of_escalating_the_sheet, on an
annotation_ink_overlap warning that does not exist in this repo at the commit I branched
from. It was not platform divergence, and not a defect in the fix.

main had advanced by two commits — #1322 (Lint the line-work drawn through a label…) and
#1335 — and GitHub tests the merge, so CI was running a lint rule my base didn't have. The
branch is now rebased onto those commits, and the drawing was measured against the new rule
both ways: the A4 recovery and the A3 fallback report the same single code, so the
overlap is pre-existing and sheet-independent.

The test asserted "no warnings at all", which was never what #1338 is about. It now asserts
the requirement — no errors, nothing dropped, no missing axial length — plus a direct
comparison of the recovered drawing's lint codes against the avoided sheet's, which is the
assertion that would actually catch the recovery making a drawing worse.

Gates

• Full fast tier on the rebase: 4872 passed, 5 skipped, 2 xfailed, 99.06 s
  (-n auto --dist worksteal).
• scripts/pr-check --static exits 0 (exit code read, not output grepped).

Architecture

ADR 0004 owns outer scale/page selection, so it carries a new amendment (2026-08-25) recording
the order and its constraints, alongside the 2026-08-23 amendment this generalises. The
amendment also records what it does not settle: scale remains the ladder's only lever for a
placement shortage, and bounding what one dropped annotation may buy is #1336.

The fixture commit

GRM03 in test_issue_1296 / _1298 / _1299 pointed at an absolute path on one developer's
disk, so four tests — including the one pinning #1336's 841×594/10:1 outcome — skipped in CI
and for every other contributor. The file is now
tests/fixtures/grm03_thumbwheel_drive_screw_ap242_pmi.step (identical sha256, so the existing
SHA guards still hold) and the skipif markers are gone. A new module asserts the fixture's own
preconditions — 18 PMI records, the #2004 internal thread behind #1336's escalating callout,
and that this is a different solid from the plain grm03 fixture (28.7 mm / 16 faces vs
23.5 mm / 14 faces), so the pair is never mistaken for a pmi on/off comparison of one part. All
four checks were mutated and all four fail. The four un-skipped tests cost 5.34 s, 5.23 s,
2.13 s and 0.51 s.

Known limits, stated rather than hidden

• The recovery branch is still gated on the plan having an optional ISO, so a plan without one
  gets no replan at all. Pre-existing; widening it is a separate decision with no evidence in
  hand.
• Each accepted upscale is built through the explicit scale+page path, whose conservative
  _fits predictor logs Requested scale 5 on (297.0, 210.0) page may not fit the 4-view layout at WARNING on a drawing lint then measures clean. Pre-existing for GRM-04 auto layout leaves most of A4 unused while dropping the Ø2.4 callout #1155's trials
  (that path also ships candidates built this way), but more common now. Demoting a predictor
  that the measurement contradicts would mean threading a flag through builder → analysis →
  compose and changing a documented contract — maintainer's call.

🤖 Generated with Claude Code

https://claude.ai/code/session_015Lp1DcM175cph7KE2fm5HF

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 93.67%. Comparing base (062d152) to head (fec7297).
⚠️ Report is 4 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1340      +/-   ##
==========================================
+ Coverage   93.59%   93.67%   +0.08%     
==========================================
  Files          61       62       +1     
  Lines       20803    21274     +471     
  Branches     3972     4083     +111     
==========================================
+ Hits        19470    19928     +458     
+ Misses        774      767       -7     
- Partials      559      579      +20     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.