ConformalLabpp/doc/roadmap/phase-prompts.md

# Ready-to-paste phase prompts (forward pipeline)

Forward counterpart of [`../reviewer/session-prompts.md`](../reviewer/session-prompts.md).
Copy one block into a fresh session, set the **model named in the prompt**, go.
Plan + DAG: [`phase-orchestration.md`](phase-orchestration.md). Design:
[`feature-dev-agentic-system.md`](feature-dev-agentic-system.md).

Shared conventions (baked into each prompt):
- Repo `/Users/tarikmoussa/Desktop/ConformalLabpp`, base `main`; push to the **eulernest
  fork** = remote `origin`; open the PR via the Gitea API
  (`/api/v1/repos/conformallab/ConformalLabpp/pulls`, basic-auth from the `origin` URL).
- Build/test: `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\.'`.
  Add `/test-cgal` (and `/quality-gates` where relevant) to the PR-head commit message so
  CI runs the full suites (they are keyword-triggered).
- **Port items:** add `// Ported from <Java file>` provenance + Java golden-oracle parity
  tests. **Research items:** run the **spike** first (separate Opus session) and only
  productionise on GO.
- Finish: **review gate** (Opus), then update status in `phase-orchestration.md` (phase → ✅).

---

## W0·9g.1 — Conformal-quality measures (port)  ·  model: **Sonnet**

```
Use Sonnet. Repo /Users/tarikmoussa/Desktop/ConformalLabpp, new branch off main
`feat/9g1-conformal-quality`. This is a Java PORT, no new theory (phases.md §9g.1).

Create code/include/conformal_quality.hpp porting these Java measures (math is
GUI-independent — lift only the math):
  - IsothermicityMeasure (plugin/visualizer/IsothermicityMeasure.java) — pointwise
    deviation from conformality (anisotropy of the induced metric).
  - DiscreteConformalEquivalencemMeasure (…/DiscreteConformalEquivalencemMeasure.java)
    — per-edge length-cross-ratio residual vs the conformal-equivalence condition.
  - FlippedTriangles (…/FlippedTriangles.java) — detect inverted/degenerate triangles
    in a 2-D layout (embedding-validity).
  - LengthCrossRatio (heds/adapter/types/LengthCrossRatio.java) — the discrete conformal
    invariant per edge (shared input for the two measures).
  - ConvergenceUtility metrics (convergence/ConvergenceUtility.java, math/float only):
    getMaxMeanSumCrossRatio (q=(a·c)/(b·d), qfun=(q+1/q)/2−1),
    getMaxMeanSumMultiRatio (per-face product, =1 iff conformal),
    getMaxMeanSumScaleInvariantCircumRadius (R/√A).
Math reference: Springborn-Schröder-Pinkall 2008 (length cross-ratio = discrete
conformal invariant). Java reference path: /Users/tarikmoussa/Desktop/conformallab/src/...

Validation (port battery): golden values read from the Java outputs on a small mesh;
a unit flipped-triangle case; run the measures on the converged cathead/brezel layouts
from the existing euclidean pipeline and assert near-conformality.

Per-finding commits, trailer `Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>`.
Build + full CGAL suite green. Push, open PR (base main, head commit message contains
`/test-cgal /quality-gates`). Update phase-orchestration.md (9g.1 → ✅) + a row in
doc/math/validation.md and references.md. Report PR URL + test count.
Then hand off to the audit system: note "audit module conformal_quality.hpp" in
doc/reviewer/finding-orchestration.md backlog.
```

---

## W0·9h — CLI extensions (infra)  ·  model: **Sonnet** (or Haiku for 9h.1)

```
Use Sonnet. Repo as above, new branch off main `feat/9h-cli`. Two independent CLI tasks
(phases.md §9h), no new theory.

9h.1 (~30 min): expose Newton tuning in code/src/apps/v0/conformallab_cli.cpp —
  app.add_option("--tol", tol, "Newton gradient tolerance [1e-8]");
  app.add_option("--max-iter", max_iter, "Newton iteration limit [200]");
  thread both through run_euclidean / run_spherical / run_hyper_ideal. Update the CLI
  parameter table in doc/getting-started.md.

9h.2 (~2–4 h): expose the Phase-9a models (already in the library + CGAL API) to the CLI:
  -g cp_euclidean       → run_cp_euclidean()
  -g inversive_distance → run_inversive_distance()
  following the existing run_euclidean() pattern (~60 lines each); add both strings to the
  CLI::IsMember validator. Update README + getting-started.md.

Validation: CLI smoke runs on a small mesh for each new flag/model; assert non-zero exit
on bad input. Build + full CGAL suite green. Commit (Sonnet trailer), push, PR (base main,
`/test-cgal` in head commit). Update phase-orchestration.md (9h.1, 9h.2 → ✅). Report PR.
```

---

## W0·9d.3 — Stereographic layout S²→ℂ (port)  ·  model: **Sonnet**

```
Use Sonnet. Repo as above, new branch off main `feat/9d3-stereographic`. Java PORT
(phases.md §9d.3) closing the spherical-visualisation gap.

Create code/include/stereographic_layout.hpp: stereographic projection S²→ℂ∪{∞} plus a
Möbius-centering step, turning discrete_conformal_map_spherical()'s Point_3-on-S² output
into a flat 2-D atlas. Java reference: unwrapper/StereographicUnwrapper.java (266 lines).
Do NOT port math/CP1 or ComplexUtility.stereographic (redundant with std::complex + the
existing MobiusMap — see porting-status.md).

Validation: round-trip (project then inverse-project) to machine precision on sampled S²
points; pole-handling unit case; run on the spherical pipeline output of a small genus-0
mesh and assert no flipped triangles (reuse 9g.1 FlippedTriangles if landed). Build + full
CGAL suite green. Commit (Sonnet trailer), push, PR (`/test-cgal`). Update
phase-orchestration.md (9d.3 → ✅). Report PR. Audit handoff note.
```

---

## WA·Phase 12 — Decorated DCE & transition (RESEARCH, Chain A)  ·  **two-step**

### Step 1 — Theorist + Spike  ·  model: **Opus**

```
Use Opus. Repo as above. This is RESEARCH (no Java parent), Chain A — it reparametrises
ALREADY-LANDED functionals, no genus-g dependency (phases.md §12).

THEORIST: read Bobenko-Lutz 2025 "Decorated Discrete Conformal Equivalence in
Non-Euclidean Geometries" (arXiv:2310.17529) §3 + Lutz 2024 thesis. Derive, on paper, the
Penner-coordinate DECORATION layer: per-vertex circle/horocycle radius as a Penner
coordinate, and its map to the existing inversive distance I_ij via the classical
ℓ² = r_i² + r_j² + 2 r_i r_j η. Write the derivation to doc/math/decorated-dce-derivation.md
(short LaTeX-style note). Define the validation strategy + acceptance criteria (below).

SPIKE (branch `spike/phase12-decoration`, throwaway): a minimal numeric proof BEFORE any
production code —
  (a) decoration round-trip I_ij ↔ (r_i, r_j, ℓ) at machine precision;
  (b) at background curvature κ=0, bit-for-bit match with the existing euclidean/inversive
      path;
  (c) the κ∈{+,0,−} transition driver holds the discrete conformal invariant fixed (GB per
      geometry; invariant constant across the transition to tol) — the numerical witness of
      the Bobenko-Lutz master theorem.
Conclude GO or NO-GO with the evidence. If NO-GO, record it in research-track.md and stop.
On GO, write the productionisation spec (files, public surface, test list) for Step 2.
```

### Step 2 — Research Implementer + Validation  ·  model: **Sonnet** (Opus review)

```
Use Sonnet. Repo as above, new branch off main `feat/phase12-decorated-dce`. Productionise
the GO spike from Step 1 per its spec (doc/math/decorated-dce-derivation.md).

Scope: (1) decoration layer (Penner coord ↔ I_ij); (2) transition driver (deform κ at fixed
invariant, solve per geometry); (3) validation harness + example gallery. Reuse the shipped
inversive-distance / hyper-ideal / spherical functionals — the decoration is a
RE-PARAMETRISATION, not a new solver.

Validation (research, no oracle — acceptance criteria from §12): round-trip machine
precision; κ=0 bit-for-bit vs euclidean/inversive; GB per geometry; invariant constant
across the κ-transition; one surface solved in all three backgrounds shares the invariant.
Build + full CGAL suite green. Commit (Sonnet trailer), push, PR (`/test-cgal`).
THEN run the review gate (Opus) below. Update phase-orchestration.md (Phase 12 → ✅) +
references.md. Audit handoff note.
```

---

## WB·9b-analytic — Analytic HyperIdeal Hessian via Schläfli (RESEARCH)  ·  model: **Opus**

```
Use Opus. Repo as above, new branch off main `feat/9b-analytic-hessian`. RESEARCH
(phases.md §9b-analytic) — replace the FD HyperIdeal Hessian with the closed form.

THEORIST + IMPLEMENT: derive the analytic Hessian by explicit chain rule through
(b_i, a_e) → ℓ_ij → ζ13/ζ14/ζ15 → α_ij / β_i. Sources: Springborn 2020 §4 +
Schläfli 1858/60 + Rivin-Schlenker 1999 + Cho-Kim 1999 + Glickenstein 2011 §4. Write a
short LaTeX correctness note to doc/math/hyperideal-hessian-derivation.md (extend the
existing one). Implement as a new `hyper_ideal_hessian_analytic_sym(...)` next to the
block-FD variant.

Validation (research, FD cross-check): assert the analytic Hessian matches today's
hyper_ideal_hessian_block_fd_sym entry-wise to FD tolerance on tetrahedron + the Lawson
genus-2 mesh (off-equilibrium); PSD check; convergence parity with the existing solver;
measured speed-up. Keep the block-FD as the cross-validation reference. Default solver
path unchanged until parity is proven, then switch newton_hyper_ideal to the analytic
Hessian behind the same interface.
Build + full CGAL suite green (incl. all Lawson Java golden-vector tests — parity sacred).
Commit (Opus trailer), push, PR (`/test-cgal`). Update phase-orchestration.md (9b-analytic
→ ✅) + references.md. Audit handoff note.
```

---

## Reusable — Research spike go/no-go gate  ·  model: **Opus**

```
Use Opus. Repo /Users/tarikmoussa/Desktop/ConformalLabpp, throwaway branch `spike/<item>`.
Goal: cheaply PROVE OR DISPROVE the math of <item> BEFORE any production code.
- Implement the smallest possible reference computation (scratch .cpp or a test-only TU).
- Run the item's designed checks: analytic-limit match, invariant conservation
  (Gauss-Bonnet; holonomy closure ∏[a_i,b_i]=Id where relevant), FD-vs-analytic, and a
  small convergence-under-refinement probe.
- If precision is suspect (genus-g isometry products), test with cpp_dec_float_50 too.
Conclude with an explicit GO or NO-GO + the numeric evidence. On GO, output the
productionisation spec (files, public surface, test list). On NO-GO, record the dead end in
research-track.md. Do NOT touch library production code in this session.
```

## Reusable — Math-review / validation gate  ·  model: **Opus**

```
Use Opus. Review the open PR <url/branch> for <item> as an independent reviewer:
- Math: does the implementation match the derivation in doc/math/<item>-derivation.md?
  Spot-check the chain rule / formula against the cited paper.
- Validation: is the battery correct for the item TYPE (port→golden oracle;
  research→analytic-limit + invariant + convergence)? Are the tolerances honest?
- Parity: no Java golden-vector test perturbed; defaults intact.
- Precision: localized high-precision substrate where required, never in the Eigen core.
- Public surface intentional + documented; commits attribute the model.
Read `git diff main...HEAD` + the derivation note. Fix small issues inline; list precise
required changes otherwise. Re-run the suite. Conclude APPROVE / CHANGES-REQUESTED, and
mark the phase ✅ in phase-orchestration.md on approve.
```

---

## ⏸ Chain B (genus g ≥ 2) — DAG-gated, do not start early

Strict order, each ⏸ until its prereq is ✅:
**holonomy-bug fix (+`cpp_dec_float_50`)** → **9c** (4g-gon fundamental domain) →
**10a** (DEC layer + 1-forms) → **10b** (Siegel Ω) → **10c** (Fuchsian / H²/Γ) →
**Phase 13** (canonical tessellations capstone). Land **Phase 12** first (Penner machinery
reused). Each is a Theorist(Opus)→spike→implement→validate→review item; full literature in
`phases.md` §9c/10/13 + `research-track.md`. The Orchestrator must refuse any item whose
prerequisites are not all ✅.

## ⛔ Phase 8 (CGAL packaging) — blocked by G0

Do not start until the original authors grant porting/relicensing rights (G0; authors
emailed, awaiting reply). Shared with the audit system's S6.
```