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>
2026-06-01 00:52:02 +02:00
parent fc234c69b5
commit b57528d92f
6 changed files with 272 additions and 11 deletions
--- a/CLAUDE.md
+++ b/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.
--- a/doc/roadmap/phase-orchestration.md
+++ b/doc/roadmap/phase-orchestration.md
@@ -55,10 +55,10 @@ Status: ✅ done · 🔲 ready/planned · ⏸ planned-blocked-by-prereq · ⛔ b
 | 9a.1 CP-Euclidean | 🔌 | ✅ | — | — | — | done |
 | 9a.2 inversive-distance | 🔬 | ✅ | — | — | — | done |
 | 9b block-FD HyperIdeal Hessian | 🔬 | ✅ | — | — | — | done |
-| **9g.1 conformal-quality measures** | 🔌 | 🔲 **ready** | none | Porter · Sonnet | quick | ~3 d |
-| **9h.1 CLI --tol/--max-iter** | 🧱 | 🔲 **ready** | none | Haiku/Sonnet | quick | ~30 m |
-| **9h.2 CLI cp/inv-dist models** | 🧱 | 🔲 **ready** | 9a ✅ | Sonnet | quick | 2–4 h |
-| **9d.3 stereographic layout (S²→ℂ)** | 🔌 | 🔲 **ready** | none | Porter · Sonnet | sphere | ~3 d |
+| **9g.1 conformal-quality measures** | 🔌 | ✅ 1375878 | none | Porter · Sonnet | quick | ~3 d |
+| **9h.1 CLI --tol/--max-iter** | 🧱 | ✅ 1375878 | none | Haiku/Sonnet | quick | ~30 m |
+| **9h.2 CLI cp/inv-dist models** | 🧱 | ✅ 1375878 | 9a ✅ | Sonnet | quick | 2–4 h |
+| **9d.3 stereographic layout (S²→ℂ)** | 🔌 | ✅ 1375878 | none | Porter · Sonnet | sphere | ~3 d |
 | **9d.4 Möbius-centering functional** | 🔌 | 🔲 **ready** | Phase 7 ✅ | Porter · Sonnet | sphere | ~3 d |
 | **9e circle-pattern layout** | 🔌 | 🔲 **ready** | 9a.1 ✅ | Porter · Sonnet | — | ~1 wk |
 | **9d.1 ConesUtility (Euclidean)** | 🔌 | 🔲 **ready** | none | Porter · Sonnet | cones | ~1 wk |
--- a/doc/roadmap/phases.md
+++ b/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)
--- a/doc/roadmap/porting-status.md
+++ b/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
-breakdown: [`doc/api/tests.md`](../api/tests.md).
+Total test count: see [`doc/api/tests.md`](../api/tests.md) — single source
+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 |

 ---
--- a/doc/roadmap/research-track.md
+++ b/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
--- a/doc/roadmap/session-prompts.md
+++ b/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.
+```