From fc77afc55f863063b126e299f96d11413f13132e 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 | 163 ++++++++++++++++++++++ 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, 431 insertions(+), 7 deletions(-) create mode 100644 doc/roadmap/phase-orchestration.md 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 new file mode 100644 index 0000000..6984c6d --- /dev/null +++ b/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 `). +- [ ] Phase marked ✅ in the master table above with the commit ref. +- [ ] `porting-status.md` §7 updated if the phase adds a C++-only capability. 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. +```