docs(roadmap): add phase orchestration system mirroring the reviewer audit workflow
All checks were successful
C++ Tests / test-fast (pull_request) Successful in 2m28s
C++ Tests / quality-gates (pull_request) Has been skipped
C++ Tests / test-cgal (pull_request) Has been skipped

Brings doc/roadmap/ to the same operational level as doc/reviewer/ by adding
the two missing structural files and updating existing docs to close the gap
identified in the system review.

New files:
- doc/roadmap/phase-orchestration.md  — master phase table (model assignments,
  session IDs, status, review-gate checklist); mirrors finding-orchestration.md
- doc/roadmap/session-prompts.md      — copy-paste-ready prompts for P1–P4
  (Haiku/Sonnet/Opus) + universal Opus review gate; mirrors reviewer/session-prompts.md

Updated files:
- CLAUDE.md: roadmap section now lists porting-status.md, phase-orchestration.md,
  session-prompts.md; reviewer section adds finding-orchestration.md and
  session-prompts.md; agentic-workflow section has direct "S3 is next / P1 is next"
  entry points so agents don't need to derive the next action from scratch
- doc/roadmap/phases.md: Current-focus table at the top (7 tracks, next session
  per track, gating); cross-links to geometry-central-comparison.md,
  software-landscape.md, complexity.md added in GC and 9b-analytic sections
- doc/roadmap/porting-status.md: snapshot date updated to 2026-05-31 (post S1+S2);
  test count replaced by reference to doc/api/tests.md; §4 gains four new solver
  rows (newton_core refactor, NewtonStatus enum, diagnostics, selectable clamp mode);
  §7 gains four new research-extension rows from S1/S2
- doc/roadmap/research-track.md: header companion-docs section links to
  novelty-statement.md, software-landscape.md, and phase-orchestration.md

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Tarik Moussa
2026-06-01 00:52:02 +02:00
parent 83a61b0228
commit fc77afc55f
6 changed files with 431 additions and 7 deletions

View File

@@ -1,6 +1,8 @@
# Porting status overview
> **Snapshot date:** 2026-05-22 (commit graph at v0.9.0 + 2 open PRs).
> **Snapshot date:** 2026-05-31 (post audit-sessions S1 + S2 on branch
> `fix/b1-v3-c1-quick-wins`; 9 commits; 301/301 CGAL tests green).
> For the authoritative live count see [`doc/api/tests.md`](../api/tests.md).
>
> **Audience.** External collaborators evaluating whether to use, extend,
> or contribute to conformallab++. This document is the **operational
@@ -55,8 +57,8 @@ legacy API (`code/include/*.hpp`) and the CGAL public API
| **CP-Euclidean** (BPS) | face circles | **face** | CPEuclidean 260 LoC | analytic 2×2-per-edge | ✅ | `discrete_circle_packing_euclidean` | ⛔ N/A |
| **Inversive Distance** | vertex circles| vertex | ❌ no Java (Luo 2004 + Glickenstein 2011 from literature) | FD (analytic planned) | ✅ | `discrete_inversive_distance_map` | ⛔ pending |
Total: 250+ tests covering all five models, 0 skipped. Per-suite
breakdown: [`doc/api/tests.md`](../api/tests.md).
Total test count: see [`doc/api/tests.md`](../api/tests.md) — single source
of truth (counts change as sessions land; do not hardcode them here).
### What "UV out" means
@@ -99,6 +101,10 @@ into `pmap` — no separate user code needed. See
| Newton with line search | ✅ | `newton_solver.hpp`, all five solvers |
| SimplicialLDLT + SparseQR fallback | ✅ | gauge-singular meshes handled automatically |
| Block-FD Hessian framework | ✅ | shipped for HyperIdeal (Phase 9b); 96× speed-up |
| `newton_core` refactor — single exit path | ✅ | shipped S1 (2026-05-31); prerequisite for clean diagnostic propagation |
| `NewtonStatus` enum (`Converged` / `MaxIterations` / `LinearSolverFailed` / `LineSearchStalled`) | ✅ | shipped S2 (2026-05-31); propagated into all three CGAL result types via `CGAL::Newton_status` alias |
| Solver diagnostics: `sparse_qr_fallback_used`, `min_ldlt_pivot` | ✅ | shipped S2 (2026-05-31); available on all public CGAL result types |
| Selectable Newton clamp mode (`HardJava` \| `SmoothBarrier`) | ✅ | shipped S1 (2026-05-31); `HardJava` is the default (Java-parity) |
| Analytic Hessian via Schläfli | 🔲 | Phase 9b-analytic; derivation in [`hyperideal-hessian-derivation.md`](../math/hyperideal-hessian-derivation.md) |
---
@@ -216,8 +222,12 @@ These are conformallab++ contributions beyond porting — the
| Genus-2 test mesh + brezel2.obj scalability | ✅ shipped |
| Memory-safe layout via `halfedge_uv` storage | ✅ shipped |
| `doc/release-policy.md` formal release policy | ✅ shipped (PR #13) |
| Analytic HyperIdeal Hessian via Schläfli | 🔲 derivation written (`hyperideal-hessian-derivation.md`); implementation Phase 9b-analytic |
| Output UV map integrated into wrappers | ✅ shipped (PR #14) for 3 of 5 models |
| `[[deprecated]]` aliases for pre-S1 API names (A1A3 rename → `<verb>_<geom>_<rest>`) | ✅ shipped S1 (2026-05-31) |
| Named numeric constants in `constants.hpp` (all thresholds / FD steps / guard values) | ✅ shipped S1 (2026-05-31) |
| Kahan-compensated triangle area in `enforce_gauss_bonnet` | ✅ shipped S1 (2026-05-31) |
| `NewtonStatus` enum + solver diagnostics on all public CGAL result types | ✅ shipped S2 (2026-05-31) |
| Analytic HyperIdeal Hessian via Schläfli | 🔲 derivation written (`hyperideal-hessian-derivation.md`); implementation Phase 9b-analytic (P4) |
| Full uniformisation for genus g ≥ 2 | 🔲 Phase 10c — fully new research |
---