# 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`](../reviewer/finding-orchestration.md). > **Ready-to-paste prompts** for every pending session (P1–P4 + review gate) > live in [`session-prompts.md`](session-prompts.md) — copy one block, set the > named model, go. --- ## How to use this 1. Pick the next **⬜ pending** session from the [sequence](#session-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 `). - [ ] Phase marked ✅ in the master table above with the commit ref. - [ ] `porting-status.md` §7 updated if the phase adds a C++-only capability.