From 6175e37ca389fe64aa73081e9a971dd030dacffd Mon Sep 17 00:00:00 2001 From: CleverThis Date: Mon, 13 Apr 2026 20:12:44 +0000 Subject: [PATCH] docs: add milestone overview documentation [AUTO-DOCS-1] --- docs/milestones/README.md | 481 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 481 insertions(+) create mode 100644 docs/milestones/README.md diff --git a/docs/milestones/README.md b/docs/milestones/README.md new file mode 100644 index 000000000..cf3b26c4d --- /dev/null +++ b/docs/milestones/README.md @@ -0,0 +1,481 @@ +# CleverAgents Milestone History & Status + +> **Last updated**: 2026-04-13 +> **Maintained by**: Documentation automation ([AUTO-DOCS-1]) +> **Source of truth**: [Forgejo Milestones](https://git.cleverthis.com/cleveragents/cleveragents-core/milestones) + +This document provides a comprehensive overview of the CleverAgents project milestone history, current status, and planned roadmap. Each milestone corresponds to a tagged release in the `cleveragents-core` repository and represents a coherent set of capabilities delivered together. + +--- + +## Quick Reference โ€” Version History Table + +| Milestone | Version | Status | Closed | Key Theme | +|-----------|---------|--------|--------|-----------| +| [M1: Minimal Local Source-Code Workflow](#m1-minimal-local-source-code-workflow) | v3.0.0 | โœ… Completed | 2026-03-16 | Local-mode foundation | +| [M2: Actor Compiler + Full LLM Integration](#m2-actor-compiler--full-llm-integration) | v3.1.0 | โœ… Completed | 2026-03-16 | LLM integration & MCP | +| [M3: Decisions + Validations + Invariants](#m3-decisions--validations--invariants) | v3.2.0 | ๐Ÿ”„ Active | โ€” | Plan correctness | +| [M4: Corrections + Subplans + Checkpoints](#m4-corrections--subplans--checkpoints) | v3.3.0 | ๐Ÿ”„ Active | โ€” | Resilience & recovery | +| [M5: ACMS v1 + Context Scaling](#m5-acms-v1--context-scaling) | v3.4.0 | ๐Ÿ”„ Active | โ€” | Context at scale | +| [M6: Autonomy Hardening](#m6-autonomy-hardening) | v3.5.0 | ๐Ÿ”„ Active | โ€” | Production autonomy | +| [M7: Advanced Concepts](#m7-advanced-concepts) | v3.6.0 | ๐Ÿ”„ Active | โ€” | Extensibility | +| [M8: TUI Implementation](#m8-tui-implementation) | v3.7.0 | ๐Ÿ”„ Active | โ€” | Interactive interface | +| [M9: Server Implementation](#m9-server-implementation) | v3.8.0 | ๐Ÿ”„ Active | โ€” | Distributed deployment | + +**Status legend**: โœ… Completed ยท ๐Ÿ”„ Active (open) ยท โณ Planned + +--- + +## Completed Milestones + +### M1: Minimal Local Source-Code Workflow + +| Field | Value | +|-------|-------| +| **Version** | v3.0.0 | +| **Status** | โœ… Completed | +| **Closed** | 2026-03-16 | +| **Changelog** | [v3.0.0](../../CHANGELOG.md#300--2025-12-06) | + +#### Overview + +M1 established the foundational local-mode workflow for CleverAgents. It delivered the minimal viable set of capabilities required for an agent to autonomously read, plan, and apply source-code changes on a developer's local machine โ€” entirely without a remote server or cloud dependency. + +#### Delivered Capabilities + +| Capability | Description | +|------------|-------------| +| **Action Registration** | Declarative registration of agent actions with typed inputs/outputs | +| **Git Checkout Resource** | First-class resource type for git repository checkouts | +| **Plan Lifecycle** | Full `use โ†’ execute โ†’ diff โ†’ apply` plan lifecycle with state machine | +| **Git Worktree Sandbox** | Isolated git worktree for safe LLM-generated change staging | +| **SQLite Persistence** | Lightweight local persistence for plans, decisions, and state | +| **Pydantic v2 Domain Models** | Type-safe domain models with full validation throughout | +| **Test Coverage** | 97%+ test coverage across unit, integration, and BDD suites | + +#### Acceptance Criteria (Met) + +- [x] `agents plan use ` initiates a new plan session +- [x] `agents plan execute` runs the LLM actor and produces file changes +- [x] `agents plan diff` shows a human-readable diff of proposed changes +- [x] `agents plan apply` merges changes from the worktree sandbox into the working tree +- [x] All plan state persisted to SQLite; survives process restart +- [x] Pydantic v2 models enforce invariants at domain boundaries +- [x] 97%+ test coverage gate enforced in CI + +#### Related ADRs + +- [ADR-001 Layered Architecture](../adr/ADR-001-layered-architecture.md) +- [ADR-003 Dependency Injection](../adr/ADR-003-dependency-injection.md) +- [ADR-006 Plan Lifecycle](../adr/ADR-006-plan-lifecycle.md) +- [ADR-008 Resource System](../adr/ADR-008-resource-system.md) +- [ADR-015 Sandbox & Checkpoint](../adr/ADR-015-sandbox-and-checkpoint.md) +- [ADR-019 Storage & Persistence](../adr/ADR-019-storage-and-persistence.md) + +--- + +### M2: Actor Compiler + Full LLM Integration + +| Field | Value | +|-------|-------| +| **Version** | v3.1.0 | +| **Status** | โœ… Completed | +| **Closed** | 2026-03-16 | +| **Changelog** | [v3.1.0](../../CHANGELOG.md#310--2025-12-20) | + +#### Overview + +M2 elevated CleverAgents from a local scripting tool to a fully LLM-integrated agent platform. The Actor Compiler translates declarative YAML actor definitions into executable LangGraph `StateGraph` objects, enabling arbitrary agent topologies to be described in configuration rather than code. The MCP adapter opened the door to tool ecosystems beyond the built-in tool library. + +#### Delivered Capabilities + +| Capability | Description | +|------------|-------------| +| **Actor YAML Compiler** | Compiles YAML actor definitions to LangGraph `StateGraph` objects | +| **MCP Adapter** | Model Context Protocol client for external tool server integration | +| **Validation Runner** | Automated validation pipeline for actor graph correctness | +| **Multi-File Generation** | LLM actors can generate and modify multiple files per plan | +| **Tool Router** | Dynamic tool dispatch based on actor graph node configuration | +| **LSP Integration** | Language Server Protocol client for IDE-grade code intelligence | +| **Agent Skills Standard** | AgentSkills.io standard support for portable skill definitions | + +#### Acceptance Criteria (Met) + +- [x] YAML actor definitions compile to runnable LangGraph graphs without manual Python +- [x] MCP server connections established and tools surfaced to LLM actors +- [x] Validation runner catches malformed actor graphs at compile time +- [x] Multi-file generation produces coherent, syntactically valid output +- [x] Tool router correctly dispatches to built-in and MCP-provided tools +- [x] LSP client provides symbol resolution and diagnostics to actor context + +#### Related ADRs + +- [ADR-010 Actor & Agent Architecture](../adr/ADR-010-actor-and-agent-architecture.md) +- [ADR-011 Tool System](../adr/ADR-011-tool-system.md) +- [ADR-012 Skill System](../adr/ADR-012-skill-system.md) +- [ADR-022 LangChain/LangGraph Integration](../adr/ADR-022-langchain-langgraph-integration.md) +- [ADR-027 Language Server Protocol](../adr/ADR-027-language-server-protocol.md) +- [ADR-028 Agent Skills Standard](../adr/ADR-028-agent-skills-standard.md) +- [ADR-029 Model Context Protocol](../adr/ADR-029-model-context-protocol.md) +- [ADR-030 Skill Abstraction Definition](../adr/ADR-030-skill-abstraction-definition.md) +- [ADR-031 Actor Abstraction Definition](../adr/ADR-031-actor-abstraction-definition.md) +- [ADR-032 Jinja2 YAML Template Preprocessing](../adr/ADR-032-jinja2-yaml-template-preprocessing.md) + +--- + +## Active Milestones + +### M3: Decisions + Validations + Invariants + +| Field | Value | +|-------|-------| +| **Version** | v3.2.0 | +| **Status** | ๐Ÿ”„ Active | +| **Target** | TBD | +| **Changelog** | [v3.2.0](../../CHANGELOG.md#320--2026-01-03) | + +#### Overview + +M3 introduces the correctness layer for plan execution. Decisions are first-class domain objects that record *why* an agent made a choice, enabling auditability and correction. Validations provide a pluggable gate system that blocks plan application when quality criteria are not met. Invariants express system-wide constraints that must hold across all plan phases. + +#### Planned Capabilities + +| Capability | Description | +|------------|-------------| +| **Decision Recording** | Structured recording of agent decisions with rationale and context | +| **`plan tree` Command** | Visual tree display of plan decisions and their relationships | +| **`plan explain` Command** | Human-readable explanation of why a decision was made | +| **Invariant Management** | Define, register, and enforce system-wide invariants | +| **Plan Correction โ€” Revert Mode** | Roll back a specific decision and re-execute from that point | +| **Plan Correction โ€” Append Mode** | Append corrective instructions to an existing plan | + +#### Key Acceptance Criteria + +- [ ] Every LLM decision recorded with ULID, rationale, and context snapshot +- [ ] `agents plan tree` renders a navigable decision tree +- [ ] `agents plan explain ` outputs human-readable rationale +- [ ] Invariants evaluated at every plan phase transition +- [ ] Invariant violations block plan progression with actionable error messages +- [ ] `agents plan correct --mode revert ` replays from rollback point +- [ ] `agents plan correct --mode append` appends corrective context and re-executes + +#### Related ADRs + +- [ADR-007 Decision Tree & Correction](../adr/ADR-007-decision-tree-and-correction.md) +- [ADR-013 Validation Abstraction](../adr/ADR-013-validation-abstraction.md) +- [ADR-016 Invariant System](../adr/ADR-016-invariant-system.md) +- [ADR-017 Automation Profiles](../adr/ADR-017-automation-profiles.md) +- [ADR-018 Semantic Error Prevention](../adr/ADR-018-semantic-error-prevention.md) +- [ADR-033 Decision Recording Protocol](../adr/ADR-033-decision-recording-protocol.md) + +--- + +### M4: Corrections + Subplans + Checkpoints + +| Field | Value | +|-------|-------| +| **Version** | v3.3.0 | +| **Status** | ๐Ÿ”„ Active | +| **Target** | TBD | +| **Changelog** | [v3.3.0](../../CHANGELOG.md#330--2026-01-17) | + +#### Overview + +M4 extends the plan model with hierarchical composition (subplans), robust recovery (checkpoints and rollback), and parallel execution. Child subplans allow complex tasks to be decomposed into independently executable units. Three-way merge resolves conflicts when parallel subplans modify overlapping files. + +#### Planned Capabilities + +| Capability | Description | +|------------|-------------| +| **Child Subplans** | Decompose a parent plan into independently executable child plans | +| **Parallel Execution** | Execute independent subplans concurrently | +| **Three-Way Merge** | Resolve conflicts between parallel subplan outputs | +| **Checkpoint System** | Snapshot plan state at any phase for safe rollback | +| **Rollback** | Restore plan to any prior checkpoint on failure or user request | + +#### Key Acceptance Criteria + +- [ ] Parent plan can spawn child subplans with scoped context +- [ ] Independent subplans execute in parallel without race conditions +- [ ] Three-way merge resolves non-conflicting parallel changes automatically +- [ ] Conflicting parallel changes surface as structured merge conflicts +- [ ] Checkpoints created automatically at each phase transition +- [ ] `agents plan rollback ` restores to any prior checkpoint + +#### Related ADRs + +- [ADR-007 Decision Tree & Correction](../adr/ADR-007-decision-tree-and-correction.md) +- [ADR-015 Sandbox & Checkpoint](../adr/ADR-015-sandbox-and-checkpoint.md) +- [ADR-034 Decision Tree Versioning & History](../adr/ADR-034-decision-tree-versioning-and-history.md) +- [ADR-035 Decision Tree Rollback & Replay](../adr/ADR-035-decision-tree-rollback-and-replay.md) +- [ADR-038 Cross-Mechanism Sandbox Coordination](../adr/ADR-038-cross-mechanism-sandbox-coordination.md) + +--- + +### M5: ACMS v1 + Context Scaling + +| Field | Value | +|-------|-------| +| **Version** | v3.4.0 | +| **Status** | ๐Ÿ”„ Active | +| **Target** | TBD | +| **Changelog** | [v3.4.0](../../CHANGELOG.md#340--2026-01-31) | + +#### Overview + +M5 delivers the Advanced Context Management System (ACMS) v1, enabling CleverAgents to operate effectively on large codebases with 10,000+ files. A three-tier storage model (hot/warm/cold) manages context budget allocation, ensuring the most relevant context is always within the LLM's token window. + +#### Planned Capabilities + +| Capability | Description | +|------------|-------------| +| **ACMS v1** | Advanced Context Management System with tiered context strategies | +| **10,000+ File Indexing** | Efficient indexing and retrieval across large repositories | +| **Hot/Warm/Cold Storage Tiers** | Tiered context storage with automatic promotion/demotion | +| **Resource Type Inheritance** | Hierarchical resource type system with multiple inheritance | +| **Safety Profile Extraction** | Automated extraction of safety constraints from resource definitions | + +#### Key Acceptance Criteria + +- [ ] ACMS indexes repositories with 10,000+ files within acceptable startup time +- [ ] Hot tier holds actively referenced context within LLM token budget +- [ ] Warm tier caches recently accessed context for fast promotion +- [ ] Cold tier stores full index for on-demand retrieval +- [ ] Context relevance scoring drives automatic tier promotion/demotion +- [ ] Resource type inheritance resolves capabilities through type hierarchy + +#### Related ADRs + +- [ADR-014 Context Management (ACMS)](../adr/ADR-014-context-management-acms.md) +- [ADR-036 Resource DAG Operational Semantics](../adr/ADR-036-resource-dag-operational-semantics.md) +- [ADR-037 Tool Reachability & Access Projection](../adr/ADR-037-tool-reachability-and-access-projection.md) +- [ADR-041 Safety Profile Extraction](../adr/ADR-041-safety-profile-extraction.md) +- [ADR-042 Resource Type Inheritance](../adr/ADR-042-resource-type-inheritance.md) + +--- + +### M6: Autonomy Hardening + +| Field | Value | +|-------|-------| +| **Version** | v3.5.0 | +| **Status** | ๐Ÿ”„ Active | +| **Target** | TBD | +| **Changelog** | [v3.5.0](../../CHANGELOG.md#350--2026-02-14) | + +#### Overview + +M6 hardens CleverAgents for production autonomous operation. The A2A (Agent-to-Agent) facade enables multi-agent coordination. An event queue decouples agent communication. Guard enforcement prevents agents from violating architectural constraints. Hierarchical decomposition supports 4+ levels of nested subplans, and parallel execution scales to 10+ concurrent agents. + +#### Planned Capabilities + +| Capability | Description | +|------------|-------------| +| **A2A Facade** | Agent-to-Agent protocol facade for multi-agent coordination | +| **Event Queue** | Asynchronous event queue for decoupled agent communication | +| **Guard Enforcement** | Runtime enforcement of architectural and safety guards | +| **Hierarchical Decomposition** | 4+ levels of nested subplan decomposition | +| **Parallel Execution (10+)** | Concurrent execution of 10+ independent agent tasks | +| **Advisory Locking** | Distributed advisory locks preventing concurrent resource conflicts | +| **Validation Pipeline** | Multi-stage validation pipeline with configurable gates | +| **Definition-of-Done Gating** | Automated DoD checks before plan application | + +#### Key Acceptance Criteria + +- [ ] A2A facade routes messages between agents with delivery guarantees +- [ ] Event queue handles agent communication without blocking +- [ ] Guards block non-compliant operations at runtime with actionable errors +- [ ] Hierarchical plans decompose to 4+ levels without performance degradation +- [ ] 10+ concurrent agent tasks execute without deadlock or resource starvation +- [ ] Advisory locks prevent concurrent modification of shared resources + +#### Related ADRs + +- [ADR-026 Agent-to-Agent Protocol (A2A)](../adr/ADR-026-agent-client-protocol.md) +- [ADR-036 Resource DAG Operational Semantics](../adr/ADR-036-resource-dag-operational-semantics.md) +- [ADR-039 Container Resource Types](../adr/ADR-039-container-resource-types.md) +- [ADR-040 LSP Resource Types](../adr/ADR-040-lsp-resource-types.md) + +--- + +### M7: Advanced Concepts + +| Field | Value | +|-------|-------| +| **Version** | v3.6.0 | +| **Status** | ๐Ÿ”„ Active | +| **Target** | TBD | +| **Changelog** | [v3.6.0](../../CHANGELOG.md#360--2026-02-28) | + +#### Overview + +M7 introduces advanced extensibility features: sophisticated context strategies powered by the Universal Knowledge Ontology (UKO), additional LLM backends beyond the initial provider set, container-based tool execution for sandboxed operations, and a plugin architecture enabling third-party extensions. + +#### Planned Capabilities + +| Capability | Description | +|------------|-------------| +| **Advanced Context Strategies** | UKO-powered context strategies with semantic reasoning | +| **UKO Runtime** | Universal Knowledge Ontology with graph persistence and inference | +| **Additional LLM Backends** | Extended provider support beyond the initial eight | +| **Container Tool Execution** | Run tools inside isolated containers for security and reproducibility | +| **Plugin Architecture** | Third-party extension points for tools, actors, and resources | + +#### Key Acceptance Criteria + +- [ ] UKO runtime indexes project ontology and answers semantic queries +- [ ] Context strategies leverage UKO inference for relevance scoring +- [ ] At least two additional LLM backends integrated and tested +- [ ] Container tool execution runs tools in Docker/Podman with resource limits +- [ ] Plugin API documented and at least one reference plugin implemented + +#### Related ADRs + +- [ADR-014 Context Management (ACMS)](../adr/ADR-014-context-management-acms.md) +- [ADR-039 Container Resource Types](../adr/ADR-039-container-resource-types.md) +- [ADR-043 Devcontainer Integration](../adr/ADR-043-devcontainer-integration.md) + +--- + +### M8: TUI Implementation + +| Field | Value | +|-------|-------| +| **Version** | v3.7.0 | +| **Status** | ๐Ÿ”„ Active | +| **Target** | TBD | +| **Changelog** | [v3.7.0](../../CHANGELOG.md#370--2026-03-15) | + +#### Overview + +M8 delivers a full-featured terminal user interface (TUI) built on the [Textual](https://textual.textualize.io/) framework. The TUI provides an interactive, keyboard-driven interface for all CleverAgents operations, with a persona system for customized agent identities, reference/command input for structured context injection, and session persistence for long-running work. + +#### Planned Capabilities + +| Capability | Description | +|------------|-------------| +| **Textual-Based TUI** | Full-screen terminal UI with multi-session tabs and rich rendering | +| **Persona System** | YAML-backed personas binding actors, presets, and scope references | +| **Reference Input (`@`)** | File/resource reference picker for structured context injection | +| **Command Input (`/`)** | Slash command system with 67+ commands across 14 groups | +| **Shell Mode (`!`)** | Inline shell execution with danger detection and user confirmation | +| **Session Persistence** | Full JSON export/import and Markdown transcript export | +| **Actor Thought Blocks** | Expandable reasoning trace widgets rendered inline | +| **Permission Questions** | Inline permission request widgets with single-key shortcuts | + +#### Key Acceptance Criteria + +- [ ] `agents tui` launches a full-screen Textual application +- [ ] Multi-session tabs allow parallel plan sessions in a single terminal +- [ ] Persona system loads from `~/.config/cleveragents/personas/` +- [ ] `@` reference picker inserts file/resource references into input +- [ ] `/` command overlay provides searchable access to all 67+ commands +- [ ] `!` shell mode detects dangerous patterns before execution +- [ ] Sessions export to JSON and Markdown formats +- [ ] Actor thought blocks render inline and collapse by default + +#### Related ADRs + +- [ADR-044 TUI Architecture and Framework](../adr/ADR-044-tui-architecture-and-framework.md) +- [ADR-045 TUI Persona System](../adr/ADR-045-tui-persona-system.md) +- [ADR-046 TUI Reference and Command System](../adr/ADR-046-tui-reference-and-command-system.md) + +--- + +### M9: Server Implementation + +| Field | Value | +|-------|-------| +| **Version** | v3.8.0 | +| **Status** | ๐Ÿ”„ Active | +| **Target** | TBD | +| **Changelog** | [v3.8.0](../../CHANGELOG.md#380--2026-04-05) | + +#### Overview + +M9 transforms CleverAgents from a local CLI tool into a distributed server platform. A JSON-RPC 2.0 A2A wire format enables standardized agent-to-agent communication over HTTP. A FastAPI server exposes the full CleverAgents API, backed by PostgreSQL for production-grade persistence. Kubernetes deployment manifests and a Helm chart enable cloud-native operation. + +#### Planned Capabilities + +| Capability | Description | +|------------|-------------| +| **A2A JSON-RPC 2.0** | Standard JSON-RPC 2.0 wire format for agent-to-agent communication | +| **HTTP Transport** | HTTP/HTTPS transport layer for remote agent connections | +| **FastAPI Server** | Production-grade FastAPI application exposing the CleverAgents API | +| **PostgreSQL Backend** | PostgreSQL persistence replacing SQLite for multi-user deployments | +| **Kubernetes Deployment** | Helm chart and manifests for Kubernetes production deployment | +| **`agents server connect`** | CLI command to configure and connect to a remote server | +| **Database Resource Handler** | Full CRUD and checkpoint/rollback for SQL database resources | + +#### Key Acceptance Criteria + +- [ ] `agents server connect ` configures remote server connection +- [ ] JSON-RPC 2.0 messages route correctly between client and server +- [ ] FastAPI server handles concurrent requests without data races +- [ ] PostgreSQL backend supports all plan lifecycle operations +- [ ] Kubernetes Helm chart deploys successfully to a standard cluster +- [ ] Database resource handler supports SQLite, PostgreSQL, MySQL, and DuckDB + +#### Related ADRs + +- [ADR-023 Server Mode](../adr/ADR-023-server-mode.md) +- [ADR-026 Agent-to-Agent Protocol (A2A)](../adr/ADR-026-agent-client-protocol.md) +- [ADR-047 A2A Standard Adoption](../adr/ADR-047-acp-standard-adoption.md) +- [ADR-048 Server Application Architecture](../adr/ADR-048-server-application-architecture.md) + +--- + +## Milestone Progression Overview + +The CleverAgents v3.x series follows a deliberate capability-layering strategy: + +``` +M1 (Foundation) + โ””โ”€ M2 (LLM Integration) + โ””โ”€ M3 (Correctness) + โ””โ”€ M4 (Resilience) + โ””โ”€ M5 (Scale) + โ””โ”€ M6 (Autonomy) + โ”œโ”€ M7 (Extensibility) + โ”œโ”€ M8 (Interactive UX) + โ””โ”€ M9 (Distribution) +``` + +Each milestone builds on the guarantees established by its predecessors: + +- **M1โ€“M2** establish the core execution model (plan lifecycle + LLM actors) +- **M3โ€“M4** add correctness and resilience (decisions, validations, checkpoints) +- **M5โ€“M6** scale the system (context management, autonomy hardening) +- **M7โ€“M9** extend the platform (advanced concepts, TUI, server mode) + +--- + +## Contributing to Milestone Tracking + +Milestone status is tracked in the [Forgejo Milestones](https://git.cleverthis.com/cleveragents/cleveragents-core/milestones) page. To associate an issue or PR with a milestone: + +1. Open the issue or PR in Forgejo +2. In the sidebar, select the appropriate milestone from the **Milestone** dropdown +3. Issues are automatically counted toward milestone completion percentage + +For questions about milestone scope or acceptance criteria, open an issue with the `Type/Question` label and reference the milestone. + +--- + +## Related Documentation + +- [Architecture Overview](../architecture.md) โ€” System architecture and layered design +- [Architecture Decision Records](../adr/index.md) โ€” All ADRs indexed by tier +- [Implementation Timeline](../timeline.md) โ€” Detailed implementation timeline +- [CHANGELOG](../../CHANGELOG.md) โ€” Full version-by-version change history +- [Development: Automation Tracking](../development/automation-tracking.md) โ€” Automation agent tracking system +- [Development: CI/CD Pipeline](../development/ci-cd.md) โ€” Continuous integration and delivery + +--- + +*This document is automatically maintained by the CleverAgents documentation automation system.* + +--- +**Automated by CleverAgents Bot** +Supervisor: Documentation | Agent: documentation-pool-supervisor +Worker: [AUTO-DOCS-1]