b57528d92f
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>
133 lines
7.6 KiB
Markdown
133 lines
7.6 KiB
Markdown
# 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** | 🔌 | ✅ 1375878 | none | Porter · Sonnet | quick | ~3 d |
|
||
| **9h.1 CLI --tol/--max-iter** | 🧱 | ✅ 1375878 | none | Haiku/Sonnet | quick | ~30 m |
|
||
| **9h.2 CLI cp/inv-dist models** | 🧱 | ✅ 1375878 | 9a ✅ | Sonnet | quick | 2–4 h |
|
||
| **9d.3 stereographic layout (S²→ℂ)** | 🔌 | ✅ 1375878 | 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.
|