execution-roadmap.md

Execution Roadmap

Purpose

This document translates the planning set into a phased implementation roadmap.

It does not replace the specialized planning documents. It defines build order, dependency ordering, and milestone intent so implementation can proceed without crossing subsystem boundaries too early.

Roadmap Principles

1. Build the graph authority and contracts before building advanced automation.
2. Prioritize non-destructive existing-graph support early, not as an afterthought.
3. Build deterministic retrieval before arbitration.
4. Build admission and reconciliation before scale-up.
5. Treat Obsidian projection as a first-class deliverable, but after graph truth exists.
6. Defer bounded self-improvement loops until lineage, validation, and promotion paths are stable.

Phase 0 — Foundations and Contracts

Goal

Lock the top-level architecture, entity boundaries, and decision records.

Deliverables

• integrated architecture document
• ADR set for major cross-cutting decisions
• canonical entity glossary and mutation boundary definitions
• agreement on terminology such as graph truth, projection, reuse/adapt/build, and relationship names

Why first

Without this phase, later implementation will drift across subsystem boundaries.

Exit criteria

• major subsystem ownership is explicit
• canonical graph vs projection boundary is explicit
• relationship naming standard is accepted
• reuse/adapt/build ordering is explicit

Phase 1 — Canonical Graph Core

Goal

Create the minimum viable canonical graph substrate and graph authority layer.

Scope

• canonical entities and IDs
• lineage and provenance fields
• graph mutation boundary
• admission record model
• alias and reference model

Dependencies

• Phase 0

Notes

This phase should define the internal truth model before any projection or automation takes control.

Exit criteria

• canonical graph entities are defined
• graph updates have one authoritative path
• aliasing and provenance can represent imported legacy material

Phase 2 — Existing-Graph Import and Reconciliation Backbone

Goal

Make the system safe for real existing graphs.

Scope

• import inventory and parsing
• schema mapping
• identity preservation and alias mapping
• conflict marking
• reconciliation outcomes and logs
• quarantine and review paths

Dependencies

• Phase 1

Why early

Existing-graph support is a core requirement, not a future enhancement.

Exit criteria

• existing graph material can be imported without destructive rewrite
• conflicts are explicit
• reconciliation decisions are reviewable
• stable IDs and paths are preserved where possible

Phase 3 — Research and Decomposition Spine

Goal

Implement the evidence-to-atomicity decision flow.

Scope

• Onyx research ingestion contract
• research bundle representation
• ROMA decision loop
• recursive child planning
• evidence refresh policy
• stop rules and recursion safety guards

Dependencies

• Phase 1
• Phase 2 for existing-graph-aware usage

Exit criteria

• nodes can be classified as ATOMIC, COMPOUND, AMBIGUOUS, or INSUFFICIENT
• evidence refresh and decomposition authority are separated cleanly
• recursive lineage is preserved

Phase 4 — Federated Retrieval and Deterministic Ranking

Goal

Create the reuse-first search backbone.

Scope

• source connector framework
• local cache/normalized candidate representation
• parallel retrieval channels
• dedupe rules
• rank fusion and shortlist generation
• weak-result / no-fit thresholding

Dependencies

• Phase 1
• Phase 2
• Phase 3 for atomic node handoff

Exit criteria

• top-K candidate shortlist is deterministic
• source trust, compatibility, metadata richness, freshness, and graph fit are represented in the score model
• raw search results are never passed directly into arbitration

Phase 5 — ADK Arbitration Layer

Goal

Add structured agentic arbitration on the shortlist.

Scope

• evaluator roles
• ADK ParallelAgent structured reviews
• ADK SequentialAgent arbiter
• constrained LoopAgent tie-breaks only where justified
• output contract for REUSE_EXISTING, ADAPT_EXISTING, NO_FIT_BUILD_REQUIRED

Dependencies

• Phase 4

Exit criteria

• arbitration consumes shortlist only
• arbitration outputs are structured and reviewable
• arbitration does not mutate graph state

Phase 6 — Isolated Skill Builder and Build Fallback

Goal

Enable bounded skill creation or adaptation only after upstream approval.

Scope

• Claude Code headless contract
• skill build job format
• adaptation flow for existing candidates
• fallback reason codes
• build report schema

Dependencies

• Phase 3
• Phase 5

Exit criteria

• builder runs only on approved atomic nodes
• builder can create, adapt, or version one skill at a time
• build fallback remains explicitly last resort

Phase 7 — Validation and Admission

Goal

Separate package generation from canonical admission and long-term trust.

Scope

• synchronous admission gates
• eventual validation workflows
• duplicate review hooks
• taxonomy fit checks
• validation state transitions

Dependencies

• Phase 1
• Phase 2
• Phase 6

Exit criteria

• a built artifact can fail admission cleanly
• admitted artifacts can remain under eventual validation
• trust accumulation is decoupled from generation success

Phase 8 — Graph Update, Promotion, and Projection

Goal

Make admitted graph state visible and navigable.

Scope

• canonical graph update workflows
• promotion decisions
• projection snapshot export
• Obsidian vault materialization
• incremental regeneration
• preservation of human notes blocks

Dependencies

• Phase 7

Exit criteria

• graph truth updates are reflected in the vault predictably
• the vault is directly readable in Obsidian
• projection remains derived and non-authoritative

Phase 9 — Bounded Optimization and Self-Improvement

Goal

Add safe improvement loops after the baseline system is stable.

Scope

• skill-level optimization experiments
• variant comparison
• promotion / rollback policy
• performance evidence capture
• bounded auto-training loops

Dependencies

• Phase 7
• Phase 8

Exit criteria

• improved variants preserve lineage
• optimization never bypasses validation or graph authority
• rollback and quarantine are available

Suggested Milestone Grouping

Milestone A — Planning Freeze

• Phase 0

Milestone B — Safe Graph Core

• Phase 1
• Phase 2

Milestone C — Reuse-First Decision Spine

• Phase 3
• Phase 4
• Phase 5

Milestone D — Build and Admit

• Phase 6
• Phase 7

Milestone E — Human-Facing Reference System

• Phase 8

Milestone F — Optimization Layer

• Phase 9

Recommended Early Risks to Watch

1. letting research ingestion leak into decomposition authority
2. letting arbitration replace deterministic ranking
3. letting builder success imply admission success
4. letting imported graph material silently rewrite canonical IDs or paths
5. letting the Obsidian vault become an unofficial source of truth
6. introducing self-improvement loops before lineage and rollback are stable

Recommended First Implementation Sequence

If implementation starts immediately after planning, the highest-leverage first sequence is:

1. canonical entity and graph authority contracts
2. import/normalization/reconciliation backbone
3. research bundle + ROMA control loop skeleton
4. federated retrieval + rank fusion
5. ADK arbitration
6. isolated skill builder contract
7. validation and admission
8. Obsidian projection
9. bounded optimization

Acceptance Criteria

This roadmap is complete when:

1. implementation phases are dependency-ordered
2. existing-graph support is first-class in the sequence
3. arbitration, building, validation, and projection are sequenced correctly
4. optimization is clearly deferred until safety boundaries exist