Merge pull request 'docs: feature-development agentic system (phases, port & research)' (#42) from docs/feature-dev-agentic-system into main

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)

doc/roadmap/feature-dev-agentic-system.md

@@ -0,0 +1,206 @@
+# 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.
+
+> **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
+
+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‖<tol`.
+- **A capstone is started prematurely** → DAG scheduler refuses blocked items (Phase 13).
+- **`double` silently fails the group relation** → Theorist's precision-prerequisite flag
+  forces the localised high-precision substrate.
+- **New code outruns review** → the audit-system handoff re-audits every merged module.
+
+---
+
+## 9. Worked first move (concrete, startable today)
+
+**Item:** Phase **9g.1** conformal-quality measures — Java port, no new theory, no deps,
+~3 days. **Why first:** lands fast, strengthens the validation story for the already-
+shipped genus-0/1 pipeline, and exercises the whole forward pipeline cheaply.
+
+- *Orchestrator* → classify **port**; prereqs none → ready.
+- *Porter (Sonnet)* → translate IsothermicityMeasure / DCE-measure / FlippedTriangles /
+  LengthCrossRatio + the ConvergenceUtility metrics into `conformal_quality.hpp`,
+  `// Ported from …` provenance.
+- *Validation (Sonnet)* → golden values from the Java outputs + a flipped-triangle unit
+  case; reuse on cathead/brezel.
+- *Reviewer (Opus)* → parity + the length-cross-ratio definition vs Springborn-Schröder-
+  Pinkall 2008.
+- *Scholar (Haiku)* → `references.md` row + a line in `validation.md`.
+- *Integrator* → PR, `/test-cgal` + `/quality-gates` run, merge → audit handoff.
+
+Then open **Chain A / Phase 12** in parallel as the first *research* exercise of the spike gate.

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.

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