[framework] bench2 preview emits preview_hard_zoom (three-view+iso) + CI gate (warns first)

[BenchCAD]

Makes the heldout three-view+iso a standard, reproducible output of bench2 preview, and starts gating on it.

Why

The four benchmark views (preview_views.png) are all diagonal isometric octants, so axis-aligned features (a hole pattern on a flat plate, a shaft crossing a duct) are hard to reconstruct. Heldout ships a preview_hard_zoom.png for exactly this — but it was generated by an ad-hoc script.

Changes

• render.py: render_three_view() — front / side / top / iso. render_iso hard-codes up=(0,0,1), so a pure top front=(0,0,1) collapses the camera basis (blank panel); the top view uses a small forward tilt (near-plan) instead.
• cli.py: bench2 preview also writes preview_hard_zoom.png for a deterministic hard example (hard, seed 0). Label column is 390 px (not the 300 px default) — a 2-params-per-line caption overran it and was clipped by the first panel.
• family-pr-checks.yml: preview_hard_zoom.png is added to the package whitelist, and a new step 3b warns when it is missing.
• DESIGN_SPEC / PR template / CONTRIBUTING: documented as the four-render set.

Warn, not require (changed from the first revision)

The first revision made the file a hard requirement. That is wrong to merge as-is:

• every open family PR is branched off pre-[framework] bench2 preview emits preview_hard_zoom (three-view+iso) + CI gate (warns first) #18 main, so it cannot generate the file — merging a hard gate would turn 11 open community PRs red at once, through no fault of their authors (5 of 16 have it: [family] articulating_monitor_arm_vesa_plate: VESA FDMI adapter plate #11/[family] round_duct_butterfly_damper: round HVAC balancing damper #12/[family] drum_tension_lug: drum-shell tension lug #15/[family] guitar_tuning_machine_head: sealed geared tuning machine #22/[family] tilting_speaker_wall_bracket: tilt-adjustable speaker wall mount #23);
• the two families already merged to main (slotted_din_rail, speaker_pole_mount_socket) also lack it, so main itself would be non-conformant and any later fix PR to those families would be blocked.

So step 3b emits a ::warning:: with the exact command instead. Flipping it into the hard-required list (and backfilling main) is tracked in the follow-up issue.

Merge conflict resolved (this is why the PR was dirty)

main meanwhile rewrote family-pr-checks.yml, the PR template and CONTRIBUTING. Resolution keeps both sides, plus one real bug the auto-merge would have shipped:

main's new step 4 (package whitelist) did not list preview_hard_zoom.png. Combined with this branch's step 3, CI would have required the file and then rejected it as a stray file — every family PR that shipped it would fail. Whitelisted.

Verified

uv run bench2 preview re-run on both merged families on the merged tree: four panels, no blank/collapsed views, captions no longer clipped. speaker_pole_mount_socket is the case in point — the top plan shows the 4-hole pattern + bore that all four diagonal isos hide.

Pairs with adding family-pr-checks to the branch ruleset's required checks (separate, admin-side).

[github-actions]

bench2 validate

slotted_din_rail

  ✓ family.json: keys + base_plane valid
  ✓ pieces: build(10 params) + PARAM_SPEC + check present
  ✓ PARAM_SPEC: 11 params, all entries complete
  ✓ easy: 4/4 seeds sample+check+build+execute clean
  ✓ medium: 4/4 seeds sample+check+build+execute clean
  ✓ hard: 4/4 seeds sample+check+build+execute clean
  ✓ difficulty separation: difficulties produce distinct programs
  ✓ geometry novelty: 6/12 unique shapes (50% duplicate)
  ✓ solids: every instance non-degenerate, 1 solid(s) each
PASS — designs/slotted_din_rail

speaker_pole_mount_socket

  ✓ family.json: keys + base_plane valid
  ✓ pieces: build(8 params) + PARAM_SPEC + check present
  ✓ PARAM_SPEC: 8 params, all entries complete
  ✓ easy: 4/4 seeds sample+check+build+execute clean
  ✓ medium: 4/4 seeds sample+check+build+execute clean
  ✓ hard: 4/4 seeds sample+check+build+execute clean
  ✓ coverage: bore_d reaches all 2 declared values (standard table fully covered)
  ✓ coverage: flange_od reaches all 2 declared values (standard table fully covered)
  ✓ coverage: flange_t reaches all 2 declared values (standard table fully covered)
  ✓ coverage: depth reaches all 6 declared values (standard table fully covered)
  ✓ difficulty separation: difficulties produce distinct programs
  ✓ geometry novelty: 9/12 unique shapes (25% duplicate)
  ✓ solids: every instance non-degenerate, 1 solid(s) each
PASS — designs/speaker_pole_mount_socket

Previews: the previews artifact on this run.