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

Feature-development agentic system — phases, port & research

Companion to ../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, finishing the Java port, and extending into the research questions in 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.