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>

CLAUDE.md

@@ -375,9 +375,12 @@ Full line-by-line audit of all math-critical headers against `de.varylab.discret
 
 | Question | Document |
 |---|---|
-| Phases 1–10 with status and sub-tasks | `doc/roadmap/phases.md` |
+| Phases 1–13 with status, effort, and sub-tasks | `doc/roadmap/phases.md` |
+| Operational truth of which Java maths is in C++ today | `doc/roadmap/porting-status.md` |
 | Which Java classes are ported, which are planned, which are skipped? | `doc/roadmap/java-parity.md` |
 | New research items (beyond Java) — citations, acceptance criteria | `doc/roadmap/research-track.md` |
+| Phase orchestration — model assignments, priority, phase-session mapping | `doc/roadmap/phase-orchestration.md` |
+| Ready-to-paste session prompts for upcoming phases (P1–P4) | `doc/roadmap/session-prompts.md` |
 
 ### Tutorials & onboarding
 
@@ -397,6 +400,8 @@ Full line-by-line audit of all math-critical headers against `de.varylab.discret
 | Internal meeting agenda | `doc/reviewer/agenda.md` |
 | Reviewer landing index | `doc/reviewer/README.md` |
 | Hand-curated reviewer landing page (HTML, source-of-truth for codeberg pages) | `doc/reviewer/hub.html` |
+| Audit orchestration — model assignments, session sequence, status tracker | `doc/reviewer/finding-orchestration.md` |
+| Ready-to-paste session prompts for pending audit sessions (S3–S6) | `doc/reviewer/session-prompts.md` |
 
 The published hub lives at https://tmoussa.codeberg.page/ConformalLabpp/ (Doxygen index at `/doxygen.html`).  See the "Codeberg pages" quirk below for how it is republished.
 
@@ -419,6 +424,8 @@ Recommended loops when working in this repo. Prefer the cheapest gate that catch
 - **Before any commit**: run the four required gates locally — they mirror CI exactly and are seconds-cheap: `bash scripts/quality/license-headers.sh`, `python3 scripts/quality/cgal-conventions.py`, `bash scripts/quality/codespell.sh`, `bash scripts/quality/shellcheck.sh --strict`.
 - **Before tagging a release**: also run the two now-un-gated structural gates (test-cgal is disabled in CI): `BUILD_DIR=build bash scripts/check-test-counts.sh` and `bash scripts/try_it.sh`.  Update `CHANGELOG.md`, `CITATION.cff`, and the `doc/api/tests.md` counts (single source of truth).
 - **Touching public-API headers**: rebuild Doxygen (`cmake --build build --target doc`) and re-check coverage (`bash scripts/doxygen-coverage.sh --threshold 100`); regenerate `doc/api/headers.md` via `python3 scripts/gen-headers-md.py` (or `bash scripts/regen-docs.sh`).
+- **Starting work on an audit finding**: open `doc/reviewer/finding-orchestration.md`, pick the next ⬜ pending session, copy its prompt from `doc/reviewer/session-prompts.md`, set the named model, and go. **S3 is next** (H3/H4/H5/V5/V6, Sonnet → Opus review).
+- **Starting work on a roadmap phase**: open `doc/roadmap/phase-orchestration.md`, pick the next ⬜ pending phase-session, copy its prompt from `doc/roadmap/session-prompts.md`, set the named model, and go. **P1 is next** (9g.1 + 9h.1 + 9h.2 + 9d.3, Haiku → Opus review).
 - **Landing to `main`** (origin is protected): branch → push to `origin` → open PR via `gh`/Gitea API → merge via API → also push `codeberg/main` directly → keep both remotes in sync.
 - **Republishing the reviewer hub**: see the Codeberg `pages` quirk below — manual force-push of an orphan branch; verify the live URL with a cache-bust query.
 - **Delegation**: this repo's heavy builds are slow on the ARM64 runner — when a task is genuinely parallelisable and independent, consider a background agent; otherwise handle inline.  Always verify an agent's actual diff, not just its summary.

doc/roadmap/phase-orchestration.md

@@ -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.

doc/roadmap/phases.md

@@ -10,6 +10,26 @@
 
 ---
 
+## ◼ Current focus (as of 2026-06-01)
+
+> **Agent entry point.** Read this box first. For model assignments, priority
+> order, and ready-to-paste prompts, see
+> [`phase-orchestration.md`](phase-orchestration.md) and
+> [`session-prompts.md`](session-prompts.md).
+> Audit-finding sessions run in parallel from `doc/reviewer/`.
+
+| Track | Next session | Gating |
+|---|---|---|
+| **Audit findings** | S3: H3/H4/H5/V5/V6 — Sonnet → Opus review | None — start now |
+| **Phase quick-wins** | P1: 9g.1 + 9h.1 + 9h.2 + 9d.3 — Haiku → Opus review | None — start now |
+| **Research: Decorated DCE** | P2: Phase 12 — Sonnet → Opus review | None — start now |
+| **Circle pattern + convergence** | P3: 9e + 9d.4 + 9g.2 — Sonnet → Opus review | None — start now |
+| **Research: Analytic Hessian** | P4: Phase 9b-analytic — Opus | ⏸ awaiting reviewer Q3 |
+| **Java port: genus > 1** | P5: Phase 9c — Opus | ⏸ awaiting reviewer Q4 + G0 |
+| **CGAL packaging** | S6 (audit system) — Opus | ⛔ blocked on G0 (author reply pending) |
+
+---
+
 ## ◼ Porting complete — Phases 1–7
 
 ```
@@ -107,14 +127,16 @@ mesh type.
          Status: 🟡 PR #9 open, 7 tests passing, ~96× speed-up measured.
 
 9b-analytic   Full analytic HyperIdeal Hessian via Schläfli identity
-         → planned, see research-track.md
+         → planned, see research-track.md + session-prompts.md §P4
          Mathematical source: Springborn 2020 §4 + Schläfli 1858/60
                               + Rivin, Schlenker 1999 "The Schläfli formula in
                                 Einstein manifolds with boundary" (ERA-AMS 5, 18–23)
                               + Cho-Kim 1999 + Glickenstein 2011 §4
          Algorithm: explicit chain rule through (bᵢ,aₑ) → ℓᵢⱼ → ζ₁₃/ζ₁₄/ζ₁₅ → αᵢⱼ/βᵢ
-         Includes: short LaTeX correctness note in doc/math/.
+         Includes: 805-line LaTeX derivation in doc/math/hyperideal-hessian-derivation.md.
          Effort: 10–14 days net.  Trigger: profiling on V > 5000.
+         Complexity / scaling context: doc/math/complexity.md.
+         ⏸ GATED: awaiting reviewer Q3 answer ("worth ~2 weeks at your mesh sizes?").
 
 9c — Genus g > 1 fundamental domain  (Java port + research extensions)
 ──────────────────────────────────────────────────────────────────────
@@ -414,6 +436,11 @@ poor input triangulations. Both share the same
 mathematical core (discrete conformal equivalence, Gauss–Bonnet,
 variational principle of Bobenko–Springborn 2004).
 
+Full architecture-level comparison (overlap analysis, adoption rationale,
+scientific value): [`doc/architecture/geometry-central-comparison.md`](../architecture/geometry-central-comparison.md).
+Software landscape (libigl, CGAL, pmp-library, geometry-central):
+[`doc/math/software-landscape.md`](../math/software-landscape.md).
+
 ---
 
 ## ◼ Phase 10 — Genus g ≥ 2 (research with partial Java support)

doc/roadmap/porting-status.md

@@ -1,6 +1,8 @@
 # Porting status overview
 
-> **Snapshot date:** 2026-05-22 (commit graph at v0.9.0 + 2 open PRs).
+> **Snapshot date:** 2026-05-31 (post audit-sessions S1 + S2 on branch
+> `fix/b1-v3-c1-quick-wins`; 9 commits; 301/301 CGAL tests green).
+> For the authoritative live count see [`doc/api/tests.md`](../api/tests.md).
 >
 > **Audience.** External collaborators evaluating whether to use, extend,
 > or contribute to conformallab++.  This document is the **operational
@@ -55,8 +57,8 @@ legacy API (`code/include/*.hpp`) and the CGAL public API
 | **CP-Euclidean** (BPS) | face circles  | **face**     | CPEuclidean 260 LoC | analytic 2×2-per-edge  | ✅        | `discrete_circle_packing_euclidean`         | ⛔ N/A     |
 | **Inversive Distance** | vertex circles| vertex       | ❌ no Java (Luo 2004 + Glickenstein 2011 from literature) | FD (analytic planned) | ✅ | `discrete_inversive_distance_map`           | ⛔ pending |
 
-Total: 250+ tests covering all five models, 0 skipped.  Per-suite
+Total test count: see [`doc/api/tests.md`](../api/tests.md) — single source
-breakdown: [`doc/api/tests.md`](../api/tests.md).
+of truth (counts change as sessions land; do not hardcode them here).
 
 ### What "UV out" means
 
@@ -99,6 +101,10 @@ into `pmap` — no separate user code needed.  See
 | Newton with line search                         | ✅     | `newton_solver.hpp`, all five solvers |
 | SimplicialLDLT + SparseQR fallback              | ✅     | gauge-singular meshes handled automatically |
 | Block-FD Hessian framework                      | ✅     | shipped for HyperIdeal (Phase 9b); 96× speed-up |
+| `newton_core` refactor — single exit path       | ✅     | shipped S1 (2026-05-31); prerequisite for clean diagnostic propagation |
+| `NewtonStatus` enum (`Converged` / `MaxIterations` / `LinearSolverFailed` / `LineSearchStalled`) | ✅ | shipped S2 (2026-05-31); propagated into all three CGAL result types via `CGAL::Newton_status` alias |
+| Solver diagnostics: `sparse_qr_fallback_used`, `min_ldlt_pivot` | ✅ | shipped S2 (2026-05-31); available on all public CGAL result types |
+| Selectable Newton clamp mode (`HardJava` \| `SmoothBarrier`) | ✅ | shipped S1 (2026-05-31); `HardJava` is the default (Java-parity) |
 | Analytic Hessian via Schläfli                   | 🔲    | Phase 9b-analytic; derivation in [`hyperideal-hessian-derivation.md`](../math/hyperideal-hessian-derivation.md) |
 
 ---
@@ -216,8 +222,12 @@ These are conformallab++ contributions beyond porting — the
 | Genus-2 test mesh + brezel2.obj scalability  | ✅ shipped |
 | Memory-safe layout via `halfedge_uv` storage | ✅ shipped |
 | `doc/release-policy.md` formal release policy | ✅ shipped (PR #13) |
-| Analytic HyperIdeal Hessian via Schläfli     | 🔲 derivation written (`hyperideal-hessian-derivation.md`); implementation Phase 9b-analytic |
 | Output UV map integrated into wrappers       | ✅ shipped (PR #14) for 3 of 5 models |
+| `[[deprecated]]` aliases for pre-S1 API names (A1–A3 rename → `<verb>_<geom>_<rest>`) | ✅ shipped S1 (2026-05-31) |
+| Named numeric constants in `constants.hpp` (all thresholds / FD steps / guard values) | ✅ shipped S1 (2026-05-31) |
+| Kahan-compensated triangle area in `enforce_gauss_bonnet` | ✅ shipped S1 (2026-05-31) |
+| `NewtonStatus` enum + solver diagnostics on all public CGAL result types | ✅ shipped S2 (2026-05-31) |
+| Analytic HyperIdeal Hessian via Schläfli     | 🔲 derivation written (`hyperideal-hessian-derivation.md`); implementation Phase 9b-analytic (P4) |
 | Full uniformisation for genus g ≥ 2           | 🔲 Phase 10c — fully new research |
 
 ---

doc/roadmap/research-track.md

@@ -7,6 +7,15 @@
 > port-tracking sheet `doc/roadmap/java-parity.md` so that the porting
 > work and the research work can be planned independently.
 >
+> **Companion documents:**
+> - [`doc/math/novelty-statement.md`](../math/novelty-statement.md) — why these
+>   contributions are novel and who the target audience is.
+> - [`doc/math/software-landscape.md`](../math/software-landscape.md) — how
+>   conformallab++ relates to libigl, geometry-central, and CGAL (relevant for
+>   deciding research vs. duplication at the boundary cases).
+> - [`phase-orchestration.md`](phase-orchestration.md) — model assignments and
+>   session prompts for implementing items in this document.
+>
 > **Created:** 2026-05-21, after a full doc audit that identified four
 > items previously mislabelled as "ports".  This document corrects the
 > record and extends it with the explicit research plan for Phase

doc/roadmap/session-prompts.md

@@ -0,0 +1,208 @@
+# Ready-to-paste session prompts (P1–P4 + review gate)
+
+Copy one block into a fresh session, set the **model named in the prompt**, and go.
+Each prompt is self-contained: it names the phase(s), the detail doc to follow,
+the build/test commands, and the branch/push/PR + review-gate workflow.
+
+Shared conventions (baked into each prompt):
+- Repo root: `/Users/tarikmoussa/Desktop/ConformalLabpp`, base branch `main`.
+- Branch + push to the **eulernest fork** = remote `origin`; open the PR via the
+  Gitea API (`https://git.eulernest.eu/api/v1/repos/conformallab/ConformalLabpp/pulls`,
+  basic-auth with the token embedded in the `origin` URL), base `main`.
+- Build/test command (CGAL suite):
+  `cmake -S code -B build-cgal -DWITH_CGAL_TESTS=ON && cmake --build build-cgal --target conformallab_cgal_tests -j8 && ctest --test-dir build-cgal -R '^cgal\.'`
+- Phase details: `doc/roadmap/phases.md` (per-phase plan);
+  `doc/roadmap/research-track.md` (research items with acceptance criteria).
+- Build flags reference: `CLAUDE.md` §Build commands (canonical source; use
+  `-DCONFORMALLAB_LOW_MEMORY_BUILD=ON -j1` if on the Raspberry Pi runner).
+- After each implementation session, run the **Review gate** prompt (Opus).
+
+---
+
+## P1 — Quick wins  (model: **Haiku**)
+
+```
+Use the Haiku model. Work in /Users/tarikmoussa/Desktop/ConformalLabpp on a new
+branch off main called `feat/p1-quick-wins`.
+
+Implement four independent additions — full details (Java references, math
+references, acceptance criteria) in doc/roadmap/phases.md at the sections
+labelled 9h.1, 9h.2, 9g.1, 9d.3:
+
+- 9h.1  Add --tol and --max-iter CLI options in code/src/conformallab_cli.cpp.
+  Thread both through run_euclidean / run_spherical / run_hyper_ideal.
+  Update doc/getting-started.md CLI parameter table.
+
+- 9h.2  Add -g cp_euclidean and -g inversive_distance routes in the CLI,
+  following the existing run_euclidean() pattern (~60 lines each).
+  Add both geometry strings to the CLI::IsMember validator.
+  Update README + doc/getting-started.md.
+
+- 9g.1  Create code/include/conformal_quality.hpp implementing:
+    IsothermicityMeasure, DiscreteConformalEquivalenceMeasure,
+    FlippedTriangles, LengthCrossRatio, ConvergenceUtility measures.
+  Java source classes are listed in phases.md §9g.1.
+  Each function must have at least one sanity test in code/tests/cgal/
+  (e.g. FlippedTriangles returns 0 on a valid layout; LengthCrossRatio
+  is 1.0 on an equilateral triangle). Register in code/tests/cgal/CMakeLists.txt.
+
+- 9d.3  Create code/include/stereographic_layout.hpp porting
+  StereographicUnwrapper.java (266 LoC). See phases.md §9d.3 for the math
+  (stereographic projection S²→ℂ∪{∞} + Möbius centring for genus-0 surfaces).
+  Add at least one round-trip test (north pole → ∞; a unit-sphere point →
+  expected complex value).
+
+Run the full CGAL suite after all four are implemented:
+cmake -S code -B build-cgal -DWITH_CGAL_TESTS=ON && cmake --build build-cgal \
+  --target conformallab_cgal_tests -j8 && ctest --test-dir build-cgal -R '^cgal\.'
+It must stay green with your new tests added.
+
+Commit per phase (or in two logical commits) with trailer
+`Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>`.
+Push to origin and open a PR (base main) via the Gitea API using the token
+in the origin remote URL. Update doc/roadmap/phase-orchestration.md (mark each
+completed phase ✅ with the commit ref). Report the PR URL and test count.
+```
+
+---
+
+## P2 — Decorated DCE transition  (model: **Sonnet**)
+
+```
+Use the Sonnet model. Work in /Users/tarikmoussa/Desktop/ConformalLabpp on a new
+branch off main called `feat/p2-decorated-dce`.
+
+Implement Phase 12 — Decorated DCE & geometric transition.
+Full details and acceptance criteria in:
+  doc/roadmap/phases.md §Phase 12
+  doc/roadmap/research-track.md §Phase 12
+
+Mathematical reference: Bobenko, Lutz 2025 "Decorated Discrete Conformal
+Equivalence in Non-Euclidean Geometries" (Discrete & Comput. Geom.;
+arXiv:2310.17529) §3 — Penner-coordinate decoration unifying the three
+background geometries.
+
+Scope (from phases.md):
+1. Decoration layer — per-vertex circle/horocycle radius as Penner coordinate;
+   implement the map ↔ existing inversive distance I_ij via
+   ℓ² = r_i² + r_j² + 2 r_i r_j η.
+   → Create code/include/decorated_dce.hpp.
+2. Transition driver — deform background curvature κ ∈ {+,0,−} while holding
+   the discrete conformal invariant fixed; call the three existing solvers
+   (euclidean, spherical, hyper_ideal).
+3. Validation harness — code/tests/cgal/test_decorated_dce.cpp.
+
+All four acceptance criteria from phases.md must be met:
+- 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 across the κ-transition.
+- Invariant (I_ij) is constant across the three-geometry transition to tol.
+
+Run the full CGAL suite (must stay green with new tests).
+Commit with trailer `Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>`.
+Push to origin, open a PR (base main) via the Gitea API. Update
+doc/roadmap/phase-orchestration.md (Phase 12 → ✅, session P2 + commit ref).
+Report the PR URL.
+```
+
+---
+
+## P3 — Circle pattern embedding + Möbius centring + convergence study  (model: **Sonnet**)
+
+```
+Use the Sonnet model. Work in /Users/tarikmoussa/Desktop/ConformalLabpp on a new
+branch off main called `feat/p3-circle-pattern-convergence`.
+
+Three items — full details in doc/roadmap/phases.md:
+
+- 9e  Create code/include/circle_pattern_layout.hpp porting
+  CirclePatternLayout + CirclePatternUtility. Phase 9a.1 (the CP-Euclidean
+  energy + solver) is a prerequisite and is already landed on main.
+  Java references: unwrapper/circlepattern/{CirclePatternLayout,
+  CirclePatternUtility,CPEuclideanRotation}.java (phases.md §9e).
+  Required test: given ρ values from a solved CP-Euclidean system, verify
+  that the embedded vertex positions are self-consistent (each face's three
+  circle-intersection points form the correct intersection angles to tol).
+
+- 9d.4  Upgrade normalise_hyperbolic() in code/include/layout.hpp to use the
+  variational MobiusCenteringFunctional (Lorentz energy
+  E = Σ log(-⟨x,p⟩/√(-⟨x,x⟩)), gradient + Hessian).
+  Java reference: functional/MobiusCenteringFunctional.java (289 LoC).
+  Retain the existing Fréchet mean as a fallback if Newton fails.
+  Required test: compare old vs new centring output on brezel.obj; both
+  must place the centroid within tol of the origin.
+
+- 9g.2  Add code/tests/cgal/test_period_matrix_convergence.cpp (experiment,
+  not a library feature — see phases.md §9g.2):
+  Generate a genus-1 elliptic mesh with a known analytic τ; subdivide via
+  igl::loop; add per-vertex Gaussian noise; compute |τ_discrete − τ_analytic|
+  after each step. Assert that the residual decreases monotonically with
+  refinement (the discrete period matrix converges).
+
+Run the full CGAL suite (must stay green).
+Commit with trailer `Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>`.
+Push to origin, open a PR (base main) via the Gitea API. Update
+doc/roadmap/phase-orchestration.md (9e/9d.4/9g.2 → ✅, P3 + commit ref).
+Report the PR URL and the convergence-study output.
+```
+
+---
+
+## P4 — Analytic HyperIdeal Hessian  (model: **Opus**) — ⏸ GATED on reviewer Q3
+
+```
+PRECONDITION: do NOT start this session until the reviewer has answered Q3
+("Is the ~6× speedup over block-FD worth ~2 weeks at your typical mesh sizes?").
+  If the answer is "no" or "not a priority", stop — Phase 9b-analytic stays ⏸.
+  If the answer is "yes" or "above V > X", proceed.
+
+Use the Opus model. Work in /Users/tarikmoussa/Desktop/ConformalLabpp on a new
+branch off main called `feat/p4-analytic-hessian`.
+
+Implement Phase 9b-analytic — the full analytic HyperIdeal Hessian via the
+Schläfli identity. The complete chain-rule derivation (805-line LaTeX note) and
+the implementation plan are in:
+  doc/math/hyperideal-hessian-derivation.md
+  doc/roadmap/phases.md §9b-analytic
+  doc/roadmap/research-track.md §Phase 9b-analytic
+
+Chain: (bᵢ, aₑ) → ℓᵢⱼ → ζ₁₃/ζ₁₄/ζ₁₅ → αᵢⱼ/βᵢ → ∂²E/∂u².
+Replace the block-FD path in code/include/hyper_ideal_hessian.hpp with the
+analytic Hessian. Retain the block-FD path available as a compile-time flag
+(-DCONFORMALLAB_HYPER_IDEAL_FD_CHECK or runtime enum) for cross-validation.
+
+Acceptance criteria:
+- All existing HyperIdeal golden-value tests pass bit-for-bit (HardJava clamp).
+- New test: analytic and block-FD Hessians agree to 1e-6 on the tetrahedron.
+- Benchmark: measure the analytic vs block-FD wall-time on the largest test
+  mesh; report the ratio. Analytic must be faster for V > 500.
+
+Run the full CGAL suite (must stay green). Commit; push; open PR via Gitea API.
+Update doc/roadmap/phase-orchestration.md (9b-analytic → ✅, P4 + commit ref).
+Report PR URL and the measured speed ratio.
+```
+
+---
+
+## Review gate (run after P1 / P2 / P3)  (model: **Opus**)
+
+```
+Use the Opus model. Work in /Users/tarikmoussa/Desktop/ConformalLabpp. Review
+the open PR <PR_URL / branch name> as an independent reviewer. Check, and report
+a pass/fail per item:
+
+- Builds clean; full CGAL suite green with no count regression
+  (ctest --test-dir build-cgal -R '^cgal\.'); count matches doc/api/tests.md.
+- Any new functional has a gradient-check test (pattern in CLAUDE.md §Test design patterns).
+- No Java golden-vector / parity test perturbed; HardJava clamp default intact.
+- Numeric changes are value-identical where claimed, or justified + covered by a test.
+- New public surface (result types, enums, CGAL headers) is intentional and
+  documented in doc/api/headers.md and doc/api/contracts.md.
+- Commit messages attribute the implementing model (Co-Authored-By trailer).
+- Phase(s) marked ✅ in doc/roadmap/phase-orchestration.md with the commit ref.
+
+Read the actual diff (git diff main...HEAD -- code/include/ code/tests/ doc/)
+and the phases.md entry for the phase(s) involved. If you find a real problem,
+fix it directly (small) or list precise required changes (larger), then re-run
+the suite. Conclude with an explicit APPROVE / CHANGES-REQUESTED.
+```