From 3c2aad15967adf31b36089c55c8edda164c143b9 Mon Sep 17 00:00:00 2001 From: Tarik Moussa Date: Mon, 1 Jun 2026 00:19:07 +0200 Subject: [PATCH 1/2] docs(roadmap): add feature-development agentic system + cross-link MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Forward counterpart to the audit/remediation system: a DAG-scheduled pipeline that works the planned phases (phases.md) and research questions (research-track.md), with a port-vs-research router, a Theorist/Spec-author (Opus) that derives discrete formulas + designs validation, a research spike→go/no-go gate, an item-type-specific validation strategy (golden oracle / invariant / convergence / cross-library), DAG prerequisite gating (chains A/B), and reuse of the audit system's Integrator/CI/review machinery. The two systems compose into a loop (build forward, audit back). Reciprocal cross-link added to agentic-system-design.md. Co-Authored-By: Claude Opus 4.8 --- doc/reviewer/agentic-system-design.md | 3 + doc/roadmap/feature-dev-agentic-system.md | 202 ++++++++++++++++++++++ 2 files changed, 205 insertions(+) create mode 100644 doc/roadmap/feature-dev-agentic-system.md diff --git a/doc/reviewer/agentic-system-design.md b/doc/reviewer/agentic-system-design.md index 701939d..a988945 100644 --- a/doc/reviewer/agentic-system-design.md +++ b/doc/reviewer/agentic-system-design.md @@ -10,6 +10,9 @@ Sonnet did validation/error-handling, **Opus** did the numerics + the **review g that validated the cheaper models' work, then diagnosed a CI OOM and sequenced the #36→#39 rebase. The system below generalises exactly that flow. +> **Companion:** the *forward* pipeline that builds the library (phases, port, research) is [`../roadmap/feature-dev-agentic-system.md`](../roadmap/feature-dev-agentic-system.md). Feature-dev lands code; this audit system hardens it — they compose into a loop. + + --- ## 1. Design principles (the lessons that shape the architecture) diff --git a/doc/roadmap/feature-dev-agentic-system.md b/doc/roadmap/feature-dev-agentic-system.md new file mode 100644 index 0000000..7aad31f --- /dev/null +++ b/doc/roadmap/feature-dev-agentic-system.md @@ -0,0 +1,202 @@ +# Feature-development agentic system — phases, port & research + +**Companion to** [`../reviewer/agentic-system-design.md`](../reviewer/agentic-system-design.md) +(the *audit / remediation* system). This one is the **forward** pipeline: it +*produces* the library — working the planned phases in [`phases.md`](phases.md), +finishing the **Java port**, and extending into the **research questions** in +[`research-track.md`](research-track.md). + +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. + +--- + +## 1. Why this needs a different shape than the audit system + +The audit pipeline consumes **closed, fully-specified** findings (`file:line`, fix, +acceptance). Feature work is the opposite — it is **open-ended and gated by truth +sources that differ per item**. Three properties of `phases.md` drive the design: + +1. **Port vs. Research is a hard, explicit fork.** + - *Port* items have a **Java golden oracle** (e.g. `CPEuclideanFunctional.java`, + `ConesUtility.java`) → faithful translation, bit-for-bit parity testing. + - *Research* items have **NONE** (e.g. inversive-distance, 9b-analytic, Phase 12/13) + → derive from papers, *design* the validation (no oracle exists). +2. **Phases form a dependency DAG with hard prerequisites.** 10b needs 10a; Phase 13 + needs 9c+10a+10b+10c **and** the holonomy-bug fix. Parallel "chains" exist + (Chain A = Phase 12, near-term; Chain B = Phase 13 capstone). +3. **The hard part is mathematical correctness, not typing.** A research item can be + *numerically wrong while compiling and "converging"*. Validation must be invented + (invariants, convergence studies, cross-library), and a domain expert may need to + sign off the discretization. + +So this system adds, over the audit one: a **DAG-aware scheduler**, a **port/research +router**, a **spike→go/no-go gate** (research may fail), and a **validation-strategy +designer**. It **reuses** the audit system's Integrator / CI / Review-gate machinery. + +--- + +## 2. Roles + +| Role | Model | Owns | Output | +|---|---|---|---| +| **Roadmap Orchestrator** | Sonnet | the phase DAG; picks next *unblocked* item; runs chains A/B in parallel; classifies port vs research | next-item spec + launch prompt | +| **Theorist / Spec-author** | **Opus** | turn a phase into a precise spec: port → extract algorithm + golden values from Java/dissertation; research → read papers, **derive the discrete formulas**, write the LaTeX note, **design the validation** | phase-spec doc + `doc/math/*-derivation.md` | +| **Prototyper (Spike)** | Opus→Sonnet | a throwaway reference impl (scratch branch) that **numerically confirms the math before productionising** — the research de-risk | go/no-go + a validated numerical recipe | +| **Porter** | **Sonnet** | faithful Java→C++ translation for *port* items; `// Ported from …` provenance | impl + golden-oracle parity tests | +| **Research Implementer** | Opus→Sonnet | productionise the prototyped research math into the library | impl + tests | +| **Validation Engineer** | **Sonnet** | build the test battery appropriate to the item (see §4) | golden / invariant / convergence / cross-lib tests | +| **Reviewer (Gatekeeper)** | **Opus** | math-soundness + parity + correctness gate (per item) | APPROVE / CHANGES-REQUESTED | +| **Integrator / Release** | Sonnet | branch/PR/CI/rebase/merge | merged PR *(shared with the audit system)* | +| **Scholar / Doc** | **Haiku** | `references.md` rows, math-note polish, user-manual/CLI docs | docs | +| **Human (Domain expert / Owner)** | — | research direction; **sign off the discretisation**; precision-substrate architecture; G0/legal | recorded decision | + +> The **Theorist** is the forward mirror of the audit system's **Auditor**: the Auditor +> finds *problems* in existing code; the Theorist produces *specs* for new code. Both are +> Opus, because both are "decide what is true / what should be built" work. + +--- + +## 3. Workflow (DAG-scheduled, with a research spike gate) + +``` + ROADMAP DAG (phases.md + research-track.md; ✅/🔲/⛔/prereqs) + │ Orchestrator picks next item whose prerequisites are ALL ✅ + ▼ + ┌── CLASSIFY ──┐ + │ port │ research│ + └──┬───┴────┬────┘ + │ │ + │ ▼ + │ THEORIST (Opus): derive formulas + LaTeX note + design validation + │ ▼ + │ SPIKE (Prototyper): numeric proof-of-correctness on a scratch branch + │ ▼ + │ ┌─ GO/NO-GO gate ─┐ NO-GO → record negative result, back to DAG + │ └────────┬────────┘ (research is allowed to fail) + │ │ GO + ▼ ▼ + PORTER RESEARCH IMPLEMENTER (productionise into the library) + └─────┬──────┘ + ▼ + VALIDATION ENGINEER (battery per §4: oracle / invariant / convergence / cross-lib) + ▼ + REVIEW GATE (Opus): math-sound? parity intact? public surface intentional? + ▼ ── CHANGES-REQUESTED ─► back to implement + INTEGRATE → CI → HUMAN MERGE GATE → MERGE → Orchestrator marks ✅, unblocks dependents + ▼ + HANDOFF → the AUDIT system re-audits the new module (close the loop) +``` + +The **spike→go/no-go** gate is the key addition: research math is proven *cheaply on a +throwaway branch* before any production code or tests are written. A NO-GO is a +*successful* outcome (a recorded dead end), not a failure — unlike the audit system, +where every dispatched finding is expected to land. + +--- + +## 4. Validation strategy — chosen by item type + +The Theorist picks the battery; the Validation Engineer builds it: + +| Item type | Primary oracle | Mandatory checks | +|---|---|---| +| **Java port** (9a.1, 9c, 9d.1/.3/.4, 9e, 9g, 10a utils) | Java golden values (`@golden` vectors) | bit-for-bit parity at the documented tol; FD-gradient check; Gauss–Bonnet | +| **Research, has a cross-impl** (10a forms ↔ geometry-central; GC-1 cross-check) | another library's output on the same mesh | agreement to tol after normalisation alignment | +| **Research, no oracle** (inversive-distance, 9b-analytic, 12, 13) | **invariants + analytic limits** | analytic-limit match (e.g. κ=0 ↔ euclidean path bit-for-bit); invariant conservation (GB, holonomy closure ∏[aᵢ,bᵢ]=Id); FD vs analytic; convergence-under-refinement study | +| **Numerical/architecture** (high-precision substrate, Hessian speed) | self-consistency | value-identity vs the slow reference; speed-up measured; conditioning diagnostics (the N7 `min_ldlt_pivot` we just added) | + +Two project-specific truths the battery must respect: +- **Parity is sacred** for ports (the same discipline that kept HardJava the default). +- **Precision prerequisite**: genus-g composes exponentially-growing isometry products; + `double` cannot verify ∏gᵢ=Id. The Theorist must flag when a *localised* + high-precision substrate (`cpp_dec_float_50`/MPFR) is required (Phase 9c/10c/13), + scoped to the uniformisation module only — never the Eigen core. + +--- + +## 5. Scheduling the actual roadmap + +**Chains run in parallel; the Orchestrator never dispatches a blocked item.** + +- **Quick wins first (cheap, unblock confidence):** 9g.1 quality measures (Java port, + ~3 days, no deps), 9h.1/9h.2 CLI (~hours), 9d.3 stereographic (small). → Porter + Haiku. +- **Chain A (near-term research, builds only on landed code):** **Phase 12** decorated + DCE. → Theorist (decoration reparametrisation) → spike (round-trip `I_ij↔(r,ℓ)` + + κ-transition invariant) → Research Implementer → invariant/GB battery. **No genus-g deps.** +- **Research math on shipped modules:** 9b-analytic HyperIdeal Hessian (Schläfli chain + rule) → Theorist + LaTeX note + FD-vs-analytic cross-check against today's block-FD. +- **Chain B (gated capstone):** the genus-g≥2 spine **9c → 10a(+DEC layer) → 10b → 10c + → Phase 13**, plus the **holonomy-bug fix** (Opus + high-precision substrate). The + Orchestrator keeps 13 ⛔ until every prerequisite is ✅. +- **Blocked by G0 (legal, shared with audit system):** Phase 8 CGAL packaging stays ⛔ + until porting rights clear — exactly as in the audit plan. + +> Prerequisite edges are enforced as data: each phase lists its prereqs; the +> Orchestrator computes the ready-set = {🔲 items whose prereqs are all ✅} each cycle. + +--- + +## 6. Composition with the audit system (the loop) + +``` + feature-dev: Theorist → spike → implement → validate → review → merge ─┐ + │ new module + audit: Auditor → plan → (implement → review) → integrate → merge ┘ hardened + ▲ │ + └────────────────── re-audit the new module ◄────────────────────┘ +``` + +- Shared infrastructure: **Integrator, CI/Infra-Diagnostician, Review-gate discipline, + the blackboard (markdown + git), commit-attribution by model**. +- Distinct front-ends: **Auditor** (finds problems) vs **Theorist** (specs features). +- The handoff: every feature merge triggers an audit-backlog entry "audit module X", + so growth never outruns scrutiny. + +--- + +## 7. Run options (same ladder as the audit system) + +1. **Manual sessions** — Orchestrator emits a launch prompt per item (a forward analog + of `session-prompts.md`), set to the named model; spike + review are separate Opus + sessions. +2. **Claude Code subagents** — roles as subagents with pinned models and scoped tools + (Prototyper works only on `spike/**` branches; Porter cannot touch `doc/math` proofs; + Reviewer is read-only on `main`). +3. **Claude Agent SDK** — a supervisor loops the DAG: computes the ready-set, spawns the + role-agents, runs gates as code (build/test/CI + invariant checks), and **stops at the + go/no-go and human-sign-off gates**. + +--- + +## 8. Failure modes this design absorbs + +- **Research math is wrong** → caught at the cheap **spike gate** before production code. +- **A port drifts from Java** → golden-oracle parity tests (Porter's mandatory battery). +- **"Converges" but is geometrically false** → invariant checks (GB, holonomy closure) + and convergence-under-refinement, not just `‖G‖ Date: Mon, 1 Jun 2026 00:26:22 +0200 Subject: [PATCH 2/2] docs(roadmap): add phase-orchestration + phase-prompts (forward plan & prompts) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- doc/roadmap/feature-dev-agentic-system.md | 4 + doc/roadmap/phase-orchestration.md | 132 +++++++++++++ doc/roadmap/phase-prompts.md | 227 ++++++++++++++++++++++ 3 files changed, 363 insertions(+) create mode 100644 doc/roadmap/phase-orchestration.md create mode 100644 doc/roadmap/phase-prompts.md 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. +```