# Roadmap ## Milestone 0 — Bootstrap Implemented: Java 25, Spring Boot 4, non-web Picocli entry point, one Gradle Kotlin DSL project with Wrapper, Modulith boundaries, help/version smoke tests, Spring AOT, Native Image configuration and native archive tasks. Acceptance: clean tests and JAR build pass, CLI terminates and errors are meaningful. Native results are tracked in the experiment log, separately from configuration claims. ## Milestone 1 — Portable engineering protocol Implemented: project discovery/init, schema 1 configuration, linked Git/submodule registry and default read-only policy, stable Work IDs, local artifact workspaces, discussion history, draft DECs, evidence integrity, structural validation and stable Markdown/JSON context. Temporary-fixture tests cover continuity, independent Works, multiple repositories and malformed/missing/unsafe state. Simple projects are supported directly: initialize in an existing source folder without Git, or register a single existing Git repository using `repo add app --path .`. No enclosing workspace or additional repositories are required. Regression coverage includes fresh processes without Git on PATH and single-repository root discovery. Pilot usability improvements include explicit `work update` refinement and UTF-8 `discussion add --text-file` input. Scope fields can now be maintained through the CLI, and long proposals can be authored as ordinary Markdown files before persistence. Acceptance demonstration: initialize a project with two independent Git repositories, create a Work referencing both, append discussion, persist a draft decision and evidence, export context, then reconstruct the same context in independent processes using only files. No framework state or model history may be required. Platform release targets: Linux x86_64, macOS ARM64, macOS x86_64 and Windows x86_64. The workflow builds the three available GraalVM 25 platforms. **macOS x86_64 is blocked by upstream GraalVM 25 support removal**, documented in the [official release notes](https://www.graalvm.org/release-notes/JDK_25/). Do not substitute an older Java target or label an ARM binary as Intel. A future distribution experiment must identify and validate a maintained compatible toolchain before enabling that native release target. CI configuration is not evidence that CI has run; see actual local results in experiments. ## Operational replacement baseline — expanded scope Implemented after the initial milestones at the user's request: provider-neutral discovery instructions and manifest, root `AGENTS.md` integration, explicit DEC approval/rejection/revision with history, lightweight plans and dependent steps, status/next-actions, mechanical completion checks, criterion evidence mappings, canonical knowledge integration snapshots, retained archives and reversible reopening. No old Agenda/Lesson entity or automatic housekeeping deletion is introduced. Acceptance: a fresh process reads the entry contract and reconstructs an approved, planned, evidenced, completed and archived Work; another execution reopens it with prior conclusions and delivery history intact. Invalid approval, dependency, evidence and revision-history states are diagnosed. No agent/provider service is required. The test suite verifies mechanics, not an arbitrary external AI's compliance. Continue piloting the installed entry files and CLI in an existing real project, with an external agent continuing a Work through human-reviewed closure. The first Discussion refinement slice is described below. The separate DF importer now previews and imports DSCs with open agendas, preserving originals, source identity and targets across independent projects under an umbrella. Reimport is deterministic and does not overwrite refinement. See [the import contract](discussion-import.md). Legacy Lessons still require deliberate integration into canonical docs. ## Milestone 2 — Discussion refinement (first contract slice) PLN-0001 implements the explicitly approved first slice: topics, surveys with options and free text, append-only answer revisions, reversible proposal dispositions, a small AgentAdapter API, general fallback/specialized routing and two deterministic fixtures. Run provenance, idempotent completed requests and source-staleness diagnostics remain portable. The framework applies validated proposals; human approval stays explicit. Acceptance experiment: one fake organizes two topics and a survey; fixture answers are revised, evidence attached, and another fake continues from a fresh process with an investigation, reversible archive and DEC draft. Unchanged context matches across executions. This verifies the contract, not real semantic intelligence. Actual build and native outcomes are recorded in [experiments](experiments.md). The subsequent local CLI slice below implements the selected real transports; fixtures remain the default acceptance-test baseline without external accounts. ## EPIC coordination — second approved slice PLN-0002 implements DEC-0003: Works can coordinate derived Works through versioned EPIC policies. Children are important by default, with explicit optional subsets, decomposition-only delivery, cycle/multiple-parent rejection and nested coordination. Important cancellation remains pending until scope/importance review. Automatic completion requires explicit policy delegation, local readiness and valid important deliveries; receipts distinguish system results from human delivery approvals. Lifecycle commands propagate outcomes/reopenings and return a deterministic report. Reconciliation recovers missed propagation from files without an LLM. Acceptance covers independent processes, repeated notification, policy/scope changes, history, important/optional/cancelled children and native standalone execution. Actual observed results are recorded in [experiments](experiments.md). The EPIC slice itself does not choose providers or execute child repository changes. Agent-generated decomposition and Lesson integration remain separate work. The open-agenda importer is delivered independently of EPIC coordination. ## Local Codex/Claude adapters — third approved slice PLN-0003 follows SVY-0001: both installed CLIs, for Discussion/synthesis proposals validated by AIE. Implements fixed process arguments, private workspaces, schemas, timeout/output/cleanup limits, safe diagnostics, general classification/routing, RUN provenance, local doctor and guided init for general/activity executors. Credentials remain with the provider. No provider is activated automatically in the AIE source project. Native distribution and ordinary protocol use still need no JVM, Node or model service; optional real runs require the chosen CLI/authentication. Acceptance uses deterministic JDK subprocess fixtures, including failure, invalid output, ownership, timeout/descendants, cleanup and fresh-process reconstruction. Bounded real-provider checks and native outcomes are reported separately in [experiments](experiments.md). Provider-native config profiles, direct APIs, source editing/execution and a generic orchestration engine are outside this slice. ## Plan consolidation — approved execution-state slice WRK-0002/DEC-0001 adds a separately approved execution-state slice before further OODA work: deterministic Step → Plan → Work consolidation, reviewed cancellation scope, pending commitments, system receipts, idempotent recovery and EPIC propagation. Acceptance requires offline multi-Plan/no-model tests, legacy/fresh-process continuity, Modulith and actual local native/distribution verification. This is protocol state management, not an autonomous OODA engine. Results are recorded in experiments.md. ## Milestone 3 — Adaptive OODA Contract 3 implements Work conduct and human DEC authority plus optional Plan experiments, prior criteria, evidence-backed results and recorded reconsideration. See [the implemented contract](work-guidance.md). Richer cross-repository Attempts and autonomous orchestration remain future work. Add observations, orientation, operational decisions and Attempts using the conceptual contracts in protocol.md. Acceptance: experiment evidence changes the next action; history prevents repeating an invalidated attempt without a stated new hypothesis. The optional experiment records do not impose a rigid Observe→Orient→Decide→Act pipeline or provide an autonomous repository engine. ## Milestone 4 — Coordinated repositories (design only) Add per-Work permissions, independent worktrees, exact source revisions, coordinated validation and separate commit outcomes. Acceptance: partial success in one repository remains visible; destructive actions, push and merge require explicit authorization. Never assume atomic commit across repositories. ## Milestone 5 — Extended knowledge integration and conformance (design only) Extend the operational baseline's explicit human-reviewed mappings with richer checks against evidence; identify impacted canonical specs, tests, code and documentation; expose conformance checks to agents and CI. Acceptance: a Work can demonstrate its outcome and preserve actionable knowledge without a mandatory Lesson model or redundant documentation trail.