ConformalLabpp/doc/roadmap/session-prompts.md

# 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.
```