diff --git a/doc/roadmap/feature-dev-agentic-system.md b/doc/roadmap/feature-dev-agentic-system.md index 7aad31f..d30e1cd 100644 --- 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 diff --git a/doc/roadmap/phase-orchestration.md b/doc/roadmap/phase-orchestration.md new file mode 100644 index 0000000..27f7e33 --- /dev/null +++ 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. diff --git a/doc/roadmap/phase-prompts.md b/doc/roadmap/phase-prompts.md new file mode 100644 index 0000000..3f9f7b2 --- /dev/null +++ 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 ` 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 `. +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/`. +Goal: cheaply PROVE OR DISPROVE the math of 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 for as an independent reviewer: +- Math: does the implementation match the derivation in doc/math/-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. +```