diff --git a/doc/reviewer/agentic-system-design.md b/doc/reviewer/agentic-system-design.md index 701939d..a988945 100644 --- 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) diff --git a/doc/roadmap/feature-dev-agentic-system.md b/doc/roadmap/feature-dev-agentic-system.md new file mode 100644 index 0000000..7aad31f --- /dev/null +++ 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‖