Revise the phase-1 design after a simplicity review

[troldal]

Why

Before building phase 1, the new simplicity-reviewer (PR #12) reviewed the core design approved on 2026-10-04 (§12.20):

• Six passes: five on single items (B7+B4+A1–A4, B1, B2/B3, B6, B5) and one across the whole design.
• Four verification lenses then checked every one of the 22 proposals: numerics, C++, caller and phase scope. They corrected eight proposals and refuted one claim. No change weakens a rule-5 guarantee.

On 2026-10-06 the maintainer accepted every recommendation. This PR writes them into DESIGN and PLAN. Nothing is built yet. Changed items keep the mark [phase 1, approved 2026-10-04; not built] and say what changed on 2026-10-06. The new §12.21 records which §12.20 decision or choice each item amends.

What (docs only)

#	Change	DESIGN
1	Combinators: one "cannot take", one "results" and, for then/warm_fallback, one "stage 2 cannot start" state per class. 8 reasoned siblings instead of 18, 11 states instead of 21. A nested chain takes the inner chain's state.	§3.6, §6.10
2	Validated tolerances passed to a solver constructor: the bare-number deletion that each solver already has now also covers tolerance<T> and its parts. No new deletions; decision 12's remedy goes into the existing text.	§6.6, §7.2
3	with_stop given a non-criterion: one sibling, !is_criterion_v<C>. The text says that only width_tol bounds the error in x, that x_tol bounds only the last step and that f_tol bounds only |f(x)|. It also fixes today's false reason for with_stop(1e-10).	§6.6
4	make(abs, rel_tolerance) is accepted as the run-time mirror of the mixed literal, so a run-time mixed tolerance needs two checks, not three	§6.2
5	A part alone in a literal: the deletion is keyed on is_tolerance_part_v (is_any_rel_v goes)	§6.2
6–7	Diagnostics: no reasoned deletion for best_x on a search result, and none on nxx::better_than. best deduces its argument type directly.	§6.3, §6.6
8	R3 ranks by width: the halves are used only when both widths overflow, and a NaN |fx| ranks last. This drops sign_bracket::half_width() and the subnormal inversion.	§6.7, §7.2
9–10	value_fits_v moves to phase 3. The run-time overflow and underflow check stays, guarded inline, and to_scalar is one static_cast. The phase-3 sketch uses two requires-expressions instead of the param_of family.	§6.4
11	A1 for cpp_bin_float_50: a run-time check against the library's own thresholds	§3.5
12	Build plan: three build PRs; phase 1 is re-estimated at 5–7.5 developer-days [est]	§10.3, PLAN

Design flaws this fixes (each reproduced by a lens):

• the false "call it alone" hint on first_of(a, b, c) when the inner pair is at fault;
• a GCC 16 hard error in the approved states_accepts_v;
• A1's integer check, which was off by one and accepted 2·eps;
• a possible library warning in to_scalar;
• Appendix D's claim that an overflowing width breaks the order.

Counted from the design text: 17 new deleted declarations instead of 39–40, and 17 new compile-fail cases instead of 29.

Verification

• docs-auditor, phase-scope-checker, cpp-reviewer (design-note mode) and numerics-reviewer reviewed the write-up.
• cpp-reviewer probed every C++ sketch on GCC 16.1, Clang 22.1.8, cl 19.51 and clang-cl 22.1.3. The floor compilers and em++ were not probed. The sketches add no language or library feature beyond the floor.
• numerics-reviewer measured the width order: no axiom violation on 220 estimates, and no strictly wider enclosure ranked first over 29,584 pairs. It also measured the x_tol error ratio on multiple roots, 1.3–6.0.
• After one fix round, the same reviewers re-checked. I applied the last two findings and checked them against the probe outputs.
• No code changed, so no presets were run. The nightly on master (a417eec) is green.

Next

The build follows in three PRs:

1. B7 + B4 + B6 (results and order);
2. B1 + the tolerance siblings + A1;
3. B2/B3 + B5 + A2, then the nightly floor dispatch (asking first) and the tag v2.0.0-alpha.1.

Each one is reviewed and run through all 12 presets.

🤖 Generated with Claude Code

[Copilot]

Copilot review overview

🟡 Changes recommended

Three proposed combinator diagnostics incorrectly require matching success and failure estimate types, contradicting valid search-result compositions.

Review effort: Balanced
Findings: 1

Open (1)

• Diagnostic incorrectly requires one estimate type for all alternatives · New

What changed in this PR

Revises the approved phase-1 design following the simplicity review; no implementation changes are included.

Changes:

• Simplifies diagnostics, traits, and combinator states.
• Revises tolerance, result ordering, and callback designs.
• Replans phase 1 as three implementation PRs.

File	Description
docs/​redesign/​PLAN.md	Updates phase estimates and build sequence.
docs/​redesign/​DESIGN.md	Records the revised phase-1 design and decisions.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.