164 lines
9.3 KiB
Markdown
164 lines
9.3 KiB
Markdown
# 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 | 🔵 | ✅ 1375878 | Haiku→🔍Opus | **P1** |
|
||
| 9h.2 | Phase 9a models in CLI (`-g cp_euclidean`, `-g inversive_distance`) | 2–4 h | 🔵 | ✅ 1375878 | Haiku→🔍Opus | **P1** |
|
||
| 9g.1 | Conformal quality measures (`conformal_quality.hpp`) | ~3 days | 🟡 | ✅ 1375878 | Haiku→🔍Opus | **P1** |
|
||
| 9d.3 | StereographicUnwrapper port | ~3 days | 🟡 | ✅ 1375878 | 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.
|