From b57528d92fad2aee8346d293f443082bfa5e9c9c Mon Sep 17 00:00:00 2001 From: Tarik Moussa Date: Mon, 1 Jun 2026 00:52:02 +0200 Subject: [PATCH] docs(roadmap): add phase orchestration system mirroring the reviewer audit workflow MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- CLAUDE.md | 9 +- doc/roadmap/phase-orchestration.md | 8 +- doc/roadmap/phases.md | 31 ++++- doc/roadmap/porting-status.md | 18 ++- doc/roadmap/research-track.md | 9 ++ doc/roadmap/session-prompts.md | 208 +++++++++++++++++++++++++++++ 6 files changed, 272 insertions(+), 11 deletions(-) create mode 100644 doc/roadmap/session-prompts.md diff --git a/CLAUDE.md b/CLAUDE.md index ad9906b..01eb4e5 100644 --- 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. diff --git a/doc/roadmap/phase-orchestration.md b/doc/roadmap/phase-orchestration.md index 27f7e33..a1d4e53 100644 --- 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 | diff --git a/doc/roadmap/phases.md b/doc/roadmap/phases.md index 7a70672..86fd5e6 100644 --- 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) diff --git a/doc/roadmap/porting-status.md b/doc/roadmap/porting-status.md index 0190c15..ba7736f 100644 --- 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 → `__`) | ✅ 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 | --- diff --git a/doc/roadmap/research-track.md b/doc/roadmap/research-track.md index d6152e5..71af0f4 100644 --- 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 diff --git a/doc/roadmap/session-prompts.md b/doc/roadmap/session-prompts.md new file mode 100644 index 0000000..d57fa62 --- /dev/null +++ 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 `. +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 `. +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 `. +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 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. +```