docs(roadmap): add phase orchestration system mirroring the reviewer audit workflow
Brings doc/roadmap/ to the same operational level as doc/reviewer/ by adding the two missing structural files and updating existing docs to close the gap identified in the system review. New files: - doc/roadmap/phase-orchestration.md — master phase table (model assignments, session IDs, status, review-gate checklist); mirrors finding-orchestration.md - doc/roadmap/session-prompts.md — copy-paste-ready prompts for P1–P4 (Haiku/Sonnet/Opus) + universal Opus review gate; mirrors reviewer/session-prompts.md Updated files: - CLAUDE.md: roadmap section now lists porting-status.md, phase-orchestration.md, session-prompts.md; reviewer section adds finding-orchestration.md and session-prompts.md; agentic-workflow section has direct "S3 is next / P1 is next" entry points so agents don't need to derive the next action from scratch - doc/roadmap/phases.md: Current-focus table at the top (7 tracks, next session per track, gating); cross-links to geometry-central-comparison.md, software-landscape.md, complexity.md added in GC and 9b-analytic sections - doc/roadmap/porting-status.md: snapshot date updated to 2026-05-31 (post S1+S2); test count replaced by reference to doc/api/tests.md; §4 gains four new solver rows (newton_core refactor, NewtonStatus enum, diagnostics, selectable clamp mode); §7 gains four new research-extension rows from S1/S2 - doc/roadmap/research-track.md: header companion-docs section links to novelty-statement.md, software-landscape.md, and phase-orchestration.md Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Tarik Moussa
163
doc/roadmap/phase-orchestration.md
Normal file
163
doc/roadmap/phase-orchestration.md
Normal file
@@ -0,0 +1,163 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user