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