ConformalLabpp/doc/roadmap/phase-orchestration.md

Phase Orchestration — Sessions × Models × Review Gates

Updated: 2026-06-01 Purpose: structured plan to work through roadmap phases across multiple short sessions, each run by the model best suited to the work, with an external Opus reviewer session after every implementation session. Mirrors the audit workflow in doc/reviewer/finding-orchestration.md.

Ready-to-paste prompts for every pending session (P1–P4 + review gate) live in session-prompts.md — copy one block, set the named model, go.

---

How to use this

1. Pick the next ⬜ pending session from the sequence.
2. Start a session with the assigned model, point it at the phase details in phases.md and (for research items) research-track.md. Each phase entry has a Java reference, a mathematical source, and acceptance criteria.
3. When it finishes, start the paired 🔍 Opus review session — it validates the diff (correctness, gradient checks, no parity regression) and only then is the batch "done".
4. Mark the session ✅ here and move on.

Rationale: same as the audit system — Haiku/Sonnet for well-specified work, Opus reserved for math/architecture work and the review gate.

---

Model-assignment heuristic

Model	Take phases that are…	Examples
Haiku	mechanical Java ports, local CLI additions, doc-only, no new math	9g.1 (quality measures), 9h.1/9h.2 (CLI), 9d.3 (Stereographic port)
Sonnet	medium Java ports or research with explicit acceptance criteria	9e (CirclePatternLayout), Phase 12 (Decorated DCE)
Opus	math derivations, architecture decisions, all 🔍 review gates	9b-analytic (Schläfli Hessian), 9c (genus > 1), all reviews

Decision rule isn't "how large" but "how much must be understood to get it right." A mechanical 600-line Java port can be Haiku; a 200-line numerical reformulation needs Opus.

---

Master phase table

Status: ✅ done · ⬜ open (actionable) · ⏸ deferred/gated · ⛔ blocked · 👤 needs reviewer input

Phase	Focus	Effort	Sev	Status	Model	Session
9h.1	Newton CLI params (--tol, --max-iter)	30 min	🔵	⬜	Haiku→🔍Opus	P1
9h.2	Phase 9a models in CLI (-g cp_euclidean, -g inversive_distance)	2–4 h	🔵	⬜	Haiku→🔍Opus	P1
9g.1	Conformal quality measures (conformal_quality.hpp)	~3 days	🟡	⬜	Haiku→🔍Opus	P1
9d.3	StereographicUnwrapper port	~3 days	🟡	⬜	Haiku→🔍Opus	P1
12	Decorated DCE & geometric transition	medium	🔴	⬜	Sonnet→🔍Opus	P2
9e	CirclePatternLayout + CirclePatternUtility	medium	🟡	⬜	Sonnet→🔍Opus	P3
9d.4	MobiusCenteringFunctional (variational Möbius centring)	medium	🟡	⬜	Sonnet→🔍Opus	P3
9g.2	Period-matrix convergence study (experiment test)	~3 days	🔵	⬜	Sonnet→🔍Opus	P3
GC-1	geometry-central cross-validation	small	🔵	⏸	Sonnet→🔍Opus	(after reviewer Q5)
9d.1	ConesUtility port (Euclidean cone singularities)	medium	🟡	⏸	Sonnet→🔍Opus	(after reviewer Q1)
9d.2	Non-Euclidean cone extensions (RESEARCH)	large	🟡	⏸	Opus	(after reviewer Q1)
9f	Polygon Laplacian (RESEARCH, no Java parent)	medium	🟡	⏸	Sonnet/Opus	(after reviewer Q1)
9b-analytic	Analytic HyperIdeal Hessian via Schläfli	10–14 days	🔴	⏸	Opus	P4 (after reviewer Q3)
9c	4g-polygon fundamental domain (genus g > 1)	~5 weeks	🔴	⏸	Opus	P5 (after reviewer Q4 + G0)
10a	Holomorphic/harmonic 1-forms + DEC layer	~6 weeks	🔴	⏸	Opus	P6 (after 9c)
10b	Siegel period matrix Ω ∈ H_g	~1 week	🟡	⏸	Opus	P6 (after 10a)
10c	Full genus-g≥2 uniformization	large	🔴	⏸	Opus	P7 (after 10b)
13	Canonical tessellations + polyhedral realisation (Chain B capstone)	very large	🔴	⏸	Opus	P8 (after 10c)
A4, A5 (public naming)	CGAL entry-point renames + Circle_packing_result unification	🟡	⏸	Opus	S6 in audit system (after G0)

---

Session sequence

⬜ P1 — Quick wins (Haiku → 🔍 Opus)

Four independent items, all with well-specified acceptance criteria and no new math. Can run in one batch or as two sub-sessions (9h.1+9h.2 first as a ~half-day warmup, then 9g.1+9d.3 as a ~1-week batch).

• 9h.1 — --tol and --max-iter CLI options in conformallab_cli.cpp; thread through the three run_*() helpers; update doc/getting-started.md.
• 9h.2 — -g cp_euclidean and -g inversive_distance routes in the CLI; add both to the CLI::IsMember validator; update README + getting-started.
• 9g.1 — code/include/conformal_quality.hpp with IsothermicityMeasure, DiscreteConformalEquivalenceMeasure, FlippedTriangles, LengthCrossRatio, ConvergenceUtility measures; one test each in code/tests/cgal/.
• 9d.3 — code/include/stereographic_layout.hpp porting StereographicUnwrapper.java (266 LoC); round-trip test required.
• 🔍 Opus review: gradient-check test for quality measures, CLI smoke test on a real mesh, no count regression.

⬜ P2 — Decorated DCE transition (Sonnet → 🔍 Opus)

• Phase 12 — Penner-coordinate decoration layer + geometric transition driver
  • validation harness. Mathematical reference: Bobenko–Lutz 2025 §3. Acceptance criteria (all four must pass — from phases.md):
  • Decoration round-trip I_ij ↔ (r_i, r_j, ℓ) at machine precision.
  • At κ=0: bit-for-bit match with existing euclidean/inversive path.
  • Gauss–Bonnet holds per geometry; invariant constant across κ-transition.
• 🔍 Opus review: validate the three acceptance criteria numerically; verify the cross-geometry invariant test; confirm no parity regression.

⬜ P3 — Circle pattern embedding + Möbius centring + convergence study (Sonnet → 🔍 Opus)

• 9e — code/include/circle_pattern_layout.hpp porting CirclePatternLayout + CirclePatternUtility (Phase 9a.1 prerequisite ✅). Test: given ρ values from a solved CP-Euclidean system, embedded vertex positions are self-consistent (intersection angles match the input).
• 9d.4 — upgrade normalise_hyperbolic() in layout.hpp via MobiusCenteringFunctional (Lorentz energy; Java: 289 LoC). Retain Fréchet mean as fallback. Test: compare old vs new centering on brezel.obj.
• 9g.2 — code/tests/cgal/test_period_matrix_convergence.cpp (experiment): genus-1 mesh with known analytic τ, igl::loop subdivision, noise, assert |τ_computed − τ_expected| decreases with refinement.
• 🔍 Opus review: cross-validate circle pattern positions against solver output; verify convergence-study direction; confirm no count regression.

⏸ P4 — Analytic HyperIdeal Hessian (Opus) — awaiting reviewer Q3

Precondition: reviewer Q3 answer must confirm the ~6× speedup over block-FD is worth ~2 weeks at their typical mesh sizes. If Q3 is "no" or "later", phase stays ⏸. If "yes" or "above V > X", proceed.

• Phase 9b-analytic — full analytic Hessian via Schläfli identity. Derivation: doc/math/hyperideal-hessian-derivation.md. Chain: (bᵢ, aₑ) → ℓᵢⱼ → ζ₁₃/ζ₁₄/ζ₁₅ → αᵢⱼ/βᵢ → ∂²E/∂u². Block-FD path must be retained as a compile-time cross-check. Acceptance: analytic and block-FD agree to 1e-6; golden-value tests pass bit-for-bit; benchmark: analytic faster on V > 500.
• No separate review gate (Opus implements + self-reviews; block-FD is the independent cross-check).

⏸ P5 — Genus > 1 fundamental domain (Opus) — awaiting reviewer Q4 + G0

Preconditions: (a) reviewer Q4 answer (port-literal vs. re-derive from Springborn 2020 §5); (b) G0 porting rights confirmed in writing.

• Phase 9c — 4g-polygon boundary walk; high-precision substrate (boost::multiprecision::cpp_dec_float_50, local to uniformization module). See phases.md §9c for the full Java source list and the precision prerequisite note.

⏸ P6–P8 — Higher-genus research chain (Opus, sequential)

Phases 10a → 10b → 10c → 13. Each gates the next. Start only after P5 (9c) is complete. Full scope in phases.md and research-track.md.

---

Review-gate checklist (every 🔍 Opus session checks)

• Builds clean; full CGAL suite green; count matches doc/api/tests.md.
• Any new functional has a gradient-check test (see CLAUDE.md §Test design patterns).
• No Java golden-vector / parity test perturbed (HardJava clamp defaults intact).
• Numeric changes are value-identical where claimed, or justified + covered by a test.
• New public surface (result types, enums, CGAL headers) is intentional; documented in doc/api/headers.md and doc/api/contracts.md.
• Commit message attributes the implementing model (Co-Authored-By: Claude <Model> <noreply@anthropic.com>).
• Phase marked ✅ in the master table above with the commit ref.
• porting-status.md §7 updated if the phase adds a C++-only capability.