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

# 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.