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`](../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 <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.