docs(roadmap): add feature-development agentic system + cross-link

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 <noreply@anthropic.com>
2026-06-01 00:19:07 +02:00
parent e8e4a15c6c
commit 3c2aad1596
2 changed files with 205 additions and 0 deletions
--- 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)
--- a/doc/roadmap/feature-dev-agentic-system.md
+++ 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‖<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.