docs(roadmap): add phase-orchestration + phase-prompts (forward plan & prompts)

Mirror the audit system's structure for the forward pipeline: - phase-orchestration.md ← finding-orchestration.md: the roadmap DAG as a status board (phase × type port/research × status × prerequisites × role/model × chain × effort), the ready-set, the recommended waves (0 quick wins / A Phase 12 / B genus-g spine), and the per-item gates (spike go/no-go, validation battery, review). - phase-prompts.md ← session-prompts.md: ready-to-paste blocks for the ready-set (9g.1, 9h, 9d.3, Phase 12 two-step, 9b-analytic) plus reusable research-spike and math-review gate prompts, and the DAG-gated Chain B / G0-blocked notes. Cross-linked from feature-dev-agentic-system.md. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-06-01 00:26:22 +02:00
parent 3c2aad1596
commit 98819ec8c2
3 changed files with 363 additions and 0 deletions
--- a/doc/roadmap/feature-dev-agentic-system.md
+++ b/doc/roadmap/feature-dev-agentic-system.md
@@ -9,6 +9,10 @@ finishing the **Java port**, and extending into the **research questions** in
 The two systems **compose into a loop**: feature-dev lands new code → the audit
 system audits & hardens it → findings flow back. Build forward, audit back.

+> **Companion files (this system's plan + prompts, mirroring the audit system):**
+> - [`phase-orchestration.md`](phase-orchestration.md) — the DAG/status board (← `finding-orchestration.md`)
+> - [`phase-prompts.md`](phase-prompts.md) — ready-to-paste phase prompts (← `session-prompts.md`)
+
 ---

 ## 1. Why this needs a different shape than the audit system
--- a/doc/roadmap/phase-orchestration.md
+++ b/doc/roadmap/phase-orchestration.md
@@ -0,0 +1,132 @@
+# Phase Orchestration — DAG × Models × Gates (forward pipeline)
+
+**Forward counterpart** of [`../reviewer/finding-orchestration.md`](../reviewer/finding-orchestration.md).
+Where that file schedules *audit findings*, this one schedules the **roadmap phases**
+([`phases.md`](phases.md)) and **research questions** ([`research-track.md`](research-track.md))
+into model-assigned sessions with **spike → go/no-go**, **validation**, and **review** gates.
+
+System design: [`feature-dev-agentic-system.md`](feature-dev-agentic-system.md).
+Ready-to-paste prompts: [`phase-prompts.md`](phase-prompts.md).
+
+> **Two systems, one loop.** Feature-dev (this plan) lands new modules; the audit
+> system re-audits them. Every merge here appends an "audit module X" entry to the
+> audit backlog.
+
+---
+
+## How to use this
+
+1. Compute the **ready-set** = 🔲 phases whose prerequisites are **all ✅** (table below).
+2. Pick one; copy its block from [`phase-prompts.md`](phase-prompts.md); set the named model.
+3. **Port** items go straight to Porter→Validation. **Research** items go
+   Theorist→**Spike (go/no-go)**→Implement→Validation.
+4. Every item ends with a **review gate (Opus)** + the validation battery for its type,
+   then Integrate → CI → human merge → mark ✅ → unblock dependents.
+
+---
+
+## Model / role assignment (forward heuristic)
+
+| Work | Role · Model |
+|---|---|
+| Faithful Java→C++ translation (golden-oracle parity) | **Porter · Sonnet** (Haiku for trivial CLI/glue) |
+| Derive discrete formulas from papers, design validation, LaTeX note | **Theorist · Opus** |
+| Throwaway numeric proof-of-correctness before production | **Prototyper · Opus→Sonnet** |
+| Productionise validated research math | **Research Implementer · Opus→Sonnet** |
+| Test battery (oracle / invariant / convergence / cross-lib) | **Validation · Sonnet** |
+| Math-soundness + parity + correctness gate | **Reviewer · Opus** |
+| `references.md`, math-note polish, user/CLI docs | **Scholar · Haiku** |
+| Branch/PR/CI/rebase/merge | **Integrator · Sonnet** (shared with audit) |
+| Research direction · discretisation sign-off · precision substrate · G0 | **Human** |
+
+Routing rule: **port → cheapest faithful model; research → Opus owns the math, cheaper
+models productionise once the spike says GO.**
+
+---
+
+## Master phase table
+
+Type: 🔌 port (Java oracle) · 🔬 research (papers only) · 🧱 infra
+Status: ✅ done · 🔲 ready/planned · ⏸ planned-blocked-by-prereq · ⛔ blocked (G0)
+
+| Phase | Type | Status | Prerequisites | Role · Model | Chain | Effort |
+|---|---|---|---|---|---|---|
+| 1–7 (special fns → holonomy) | 🔌 | ✅ | — | — | — | done |
+| 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 |
+| **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 |
+| **9b-analytic HyperIdeal Hessian (Schläfli)** | 🔬 | 🔲 **ready** | 9b ✅ | Theorist · Opus | — | 10–14 d |
+| **9f polygon Laplacian** | 🔬 | 🔲 **ready** | none | Theorist · Opus | — | ~3 wk |
+| **Phase 12 decorated DCE + transition** | 🔬 | 🔲 **ready** | landed code only | Theorist · Opus | **A** | medium |
+| 9d.2 non-Euclidean cones | 🔬 | 🔲 ready | 9d.1 | Theorist · Opus | cones | medium |
+| 9g.2 period-matrix convergence study | 🔬 | 🔲 ready | period_matrix ✅ | Validation · Sonnet | — | ~3 d |
+| 9c 4g-gon fundamental domain | 🔌+🔬 | ⏸ | high-precision substrate | Theorist+Porter · Opus | **B** | ~5 wk |
+| holonomy-bug fix (+`cpp_dec_float_50`) | 🔬 | ⏸ | — (architecture call) | Opus + Human | **B** | ~1 wk |
+| 10a DEC layer + 1-forms | 🔌+🔬 | ⏸ | 9c | Porter+Theorist · Opus | **B** | ~6 wk |
+| 10b Siegel period matrix Ω | 🔬 | ⏸ | 10a | Theorist · Opus | **B** | ~1 wk |
+| 10c Fuchsian-group / H²/Γ | 🔬 | ⏸ | 10a+10b+9c | Theorist · Opus | **B** | large |
+| 13 canonical tessellations (capstone) | 🔬 | ⏸ | 9c+10a+10b+10c+holonomy(+12) | Theorist · Opus | **B** | very large |
+| Phase 8 CGAL packaging | 🧱 | ⛔ | **G0** (porting rights) | Opus+Human | — | large |
+| 11a/11b/11c, 10d–10g, GC-1/2/3 | 🔬 | ⏸/opt | various | Theorist · Opus | later | large |
+
+> **Ready-set right now** (no open prerequisites): **9g.1, 9h.1, 9h.2, 9d.3, 9d.4, 9e,
+> 9d.1, 9b-analytic, 9f, Phase 12, 9g.2.** The Chain-B spine and Phase 8 stay ⏸/⛔.
+
+---
+
+## Recommended sequence
+
+### Wave 0 — quick wins (Porter/Haiku, parallel, build confidence)
+**9g.1** (quality measures) · **9h.1+9h.2** (CLI) · **9d.3** (stereographic). All 🔌/🧱,
+no theory, golden-oracle or trivial validation. Land fast, exercise the forward pipeline
+cheaply, strengthen the genus-0/1 validation story.
+
+### Wave A — first research (Chain A, the spike gate's debut)
+**Phase 12 decorated DCE.** Theorist (Opus) derives the Penner-coordinate decoration as a
+*reparametrisation* of the shipped inversive-distance/hyper-ideal/spherical functionals →
+**spike**: round-trip `I_ij ↔ (r_i,r_j,ℓ)` + κ-transition invariant → Research Implementer
+→ invariant/GB battery. Builds on landed code only; **no genus-g dependency.**
+
+### Wave B — research on shipped modules (parallel with A)
+**9b-analytic** (Schläfli analytic HyperIdeal Hessian, with `doc/math/` LaTeX note,
+FD-vs-analytic cross-check against today's block-FD) · **9f** (polygon Laplacian) ·
+**9e / 9d.1 / 9d.4** (further Java ports).
+
+### Wave C — the genus-g≥2 spine (Chain B, strictly DAG-gated)
+**holonomy-bug fix + `cpp_dec_float_50`** → **9c** → **10a (+DEC layer)** → **10b** →
+**10c** → **Phase 13** capstone. The Orchestrator keeps each ⏸ until its prereqs are ✅;
+**13 never dispatches early.** Land **Phase 12** first so the Penner machinery exists.
+
+### Blocked
+**Phase 8 (CGAL packaging)** — ⛔ until **G0** (authors emailed, awaiting reply).
+
+---
+
+## Per-item gates (what "done" requires)
+
+- **Spike go/no-go** (research only): numeric correctness on a `spike/**` branch *before*
+  production code. A NO-GO is a recorded result, not a failure.
+- **Validation battery** (by type — see `feature-dev-agentic-system.md` §4):
+  - 🔌 port → Java golden values bit-for-bit + FD-gradient + Gauss–Bonnet.
+  - 🔬 with cross-impl → geometry-central agreement after normalisation.
+  - 🔬 no oracle → analytic-limit match + invariant conservation (GB, ∏[aᵢ,bᵢ]=Id) +
+    FD-vs-analytic + convergence-under-refinement.
+- **Review gate (Opus)**: math sound? parity intact (HardJava-style defaults)? public
+  surface intentional + documented? precision-prerequisite respected?
+- **Integrate**: PR with `/test-cgal` (+ `/quality-gates` where relevant); model
+  attribution in commits; mark ✅ here; append audit-backlog handoff.
+
+---
+
+## Status log
+
+- **2026-06-01:** plan created. Ready-set open (Wave 0/A/B). Chain B + Phase 8 gated.
+  Audit system delivered S1+S2 (`finding-orchestration.md`); its Integrator/CI/review
+  machinery is reused here.
--- a/doc/roadmap/phase-prompts.md
+++ b/doc/roadmap/phase-prompts.md
@@ -0,0 +1,227 @@
+# 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.
+```