# Milestone Plan — Reference

## Status Overview (as of 2026-04-11)

| Milestone | Status | Goal |
|-----------|--------|------|
| v3.0.0 | ✅ CLOSED | Minimal Local Source-Code Workflow |
| v3.1.0 | ✅ CLOSED | Actor Compiler + Full LLM Integration |
| v3.2.0 | 🔄 IN PROGRESS | Decisions + Validations + Invariants (571 open / 257 closed) |
| v3.3.0 | 🔄 IN PROGRESS | Corrections + Subplans + Checkpoints (122 open / 108 closed) |
| v3.4.0 | 🔄 IN PROGRESS | ACMS v1 + Context Scaling (200 open / 137 closed) |
| v3.5.0 | 🔄 IN PROGRESS | Autonomy Hardening (971 open / 201 closed) |
| v3.6.0 | 🔄 IN PROGRESS | Advanced Concepts & Deferred Features (282 open / 150 closed) |
| v3.7.0 | 🔄 IN PROGRESS | TUI Implementation (526 open / 427 closed) |
| v3.8.0 | 🔄 IN PROGRESS | Server Implementation (352 open / 132 closed) |

⚠️ **v3.8.0 has no deadline.** Focus on v3.2.0–v3.7.0 first. v3.8.0 may proceed in parallel but is not on the critical path.

---

## v3.2.0 — Decisions + Validations + Invariants

**Goal**: Decision recording, invariant enforcement, plan correction.

**Key deliverables:**
- `agents plan tree <plan_id>` renders decision tree
- `agents plan explain <decision_id>` shows alternatives, confidence, rationale
- `agents invariant add/list/remove` functional
- `agents plan correct --mode=revert` and `--mode=append` functional
- `agents plan correct --dry-run` shows warnings + estimated recompute time
- Validation runner executes required and informational validations

**Architectural constraints:**
- Decision persistence: ULIDs, `v3_decisions` table with `context_snapshot` JSONB
- Correction atomicity: `plan.attempt` incremented via `PlanLifecycleService` BEFORE recompute
- Dry-run: use `generate_dry_run_report()` (not `analyze_impact()`); preserves status at PENDING
- Invariant precedence: plan > action > project > global; non_overridable always wins
- Validation: always `writes=False`, `checkpointable=False`

---

## v3.3.0 — Corrections + Subplans + Checkpoints

**Goal**: Subplan spawning, parallel execution, three-way merge, rollback.

**Key deliverables:**
- Plans spawn child subplans via `subplan_spawn` decision type
- Sequential and parallel subplan execution with `max_parallel` enforcement
- Three-way merge for non-conflicting changes; conflict surfacing for conflicts
- Checkpoint creation during Execute; `agents plan rollback` functional
- Correction rejects decisions whose subtree includes applied child plans

**Architectural constraints:**
- Child plans: ULID identifiers only (no namespaced name)
- Each subplan: own isolated sandbox; parent merges via `MergeWorkflow`
- Checkpoint granularity: full plan state (decision tree + sandbox state hash + resource versions)
- `max_parallel` enforced by `PlanLifecycleService`
- Merge strategy selection per resource type

---

## v3.4.0 — ACMS v1 + Context Scaling

**Goal**: ACMS pipeline operational; 10,000+ file projects indexed and queried.

**Key deliverables:**
- Context policies configurable with view-specific settings (strategize/execute/apply/default)
- Budget enforcement: `max_file_size` and `max_total_size` constraints
- `agents project context show/inspect/simulate` functional
- Hot/warm/cold tier management
- 10,000+ file project indexes within 5 minutes
- UKO ontology indexing for Python (uko-py: URIs)
- Skeleton compression for child plan context

**Architectural constraints:**
- All 10 Context Assembly Pipeline slots overridable at plan > project > global scope
- UKO URI stability: file content changes do not change URI
- `ParallelStrategyExecutor` with circuit-breaker protection per strategy
- `GreedyKnapsackPacker` fills context up to token budget
- Hot tier evicts to warm on overflow; warm evicts to cold on age

---

## v3.5.0 — Autonomy Hardening

**Goal**: Autonomous execution with 4+ subplan levels, validation-gated apply, guard enforcement.

**Key deliverables:**
- A2A facade operations functional via CLI
- Guard enforcement: denylist, budget caps, tool call limits
- Automation profile precedence correct (plan > action > global)
- Safety profile enforcement: `require_sandbox`, `require_checkpoints`, `allow_unsafe_tools`
- 4+ levels of subplan hierarchy
- 10+ concurrent subplans without deadlock
- Validation-gated apply: required validations must pass
- `agents automation-profile add/list/show` functional

**Architectural constraints:**
- A2A local facade: in-process in local mode; no subprocess spawning for local operations
- Guard evaluation order: denylist → allowlist → tool call limits → budget caps
- Threshold: 0.0 = always auto; 1.0 = always manual
- Subtree recomputation: only decisions with `depends_on` edges to corrected decision
- Required validations block apply; informational log but don't block

---

## v3.6.0 — Advanced Concepts & Deferred Features

**Goal**: LSP integration, resource type inheritance, devcontainer, container execution.

**Key deliverables:**
- ACP → A2A module rename complete (no `acp` references in public API)
- `agents lsp add/list/show/remove` functional
- LSP bound to actor graph node; capabilities exposed as tools via LSPToolAdapter
- LSP diagnostics auto-injected into ACMS hot context
- Resource type inheritance with `inherits` field functional
- Polymorphic tool matching (parent type tools work with subtypes)
- Devcontainer auto-discovery from `.devcontainer/devcontainer.json`
- Devcontainer lazy activation (built only when first needed)
- Container tool execution via execution environment
- E2E workflow specification tests in Robot Framework

**Architectural constraints:**
- ACP module deprecated; all new code uses `a2a` namespace
- LSP server lifecycle: start on actor activate, stop on actor deactivate
- Max inheritance depth: 5 levels; circular inheritance rejected
- `devcontainer-instance` inherits `container-instance`; uses lazy activation
- Cloud resource stubs: validate config but raise `NotImplementedError` for sandbox

---

## v3.7.0 — TUI Implementation

**Goal**: Full Textual-based TUI with persona system, @ and / input modes, multi-session.

**Key deliverables:**
- `agents tui` launches Textual MainScreen
- 3 sidebar states: hidden / visible / fullscreen
- Persona system: YAML-based actor + args + scope + presets
- Reference input (`@` mode): resource/file completion popup
- Command input (`/` mode): command completion popup
- Shell execution (`!` mode)
- TuiMaterializer A2A integration functional
- Session persistence in `~/.local/state/cleveragents/tui.db`
- Dracula theme, block cursor navigation
- Notification system for async events (toast notifications)
- Multi-session tabs with independent A2A bindings
- `agents tui web` for Textual Web mode

**Architectural constraints:**
- Textual >= 1.0 required
- TUI/CLI parity: all CLI operations available in TUI via TuiMaterializer
- A2A routing: all TUI operations through A2aLocalFacade
- Session DB: `~/.local/state/cleveragents/tui.db` (separate from `data.db`)
- Persona scope: TUI only (not visible to CLI or server)

---

## v3.8.0 — Server Implementation

**Goal**: A2A server, multi-user, team RBAC, LangGraph Platform, PostgreSQL.

**Key deliverables:**
- A2A JSON-RPC 2.0 endpoint with standard operations
- `_cleveragents/` extension method routing
- A2A stdio transport (local) and HTTP transport (server)
- LangGraph Platform RemoteGraph integration
- FastAPI + A2A SDK server structure
- API token authentication
- Team RBAC: namespace-scoped permissions
- Entity sync via `_cleveragents/sync/*`
- Multi-device experience: shared namespaces
- PostgreSQL backend
- Docker + Helm deployment
- `agents server add/status` commands
- Multi-turn forwarding: `_cleveragents/fs/*`, `_cleveragents/terminal/*`

**Architectural constraints:**
- A2A exclusivity: NO REST API, NO GraphQL
- Shared domain/application layers: zero behavioral drift between local and server
- LangGraph Platform: actors deployed as separate RemoteGraphs; server does NOT run graphs in-process
- Authentication boundary: all A2A requests require valid API token
- Multi-turn forwarding: server-hosted agent requests client-local resources via input-required state

---

## Cross-Milestone Quality Gates

These apply to EVERY milestone:

| Gate | Requirement | Command |
|------|-------------|---------|
| Unit Tests | All BDD Behave scenarios pass | `nox -s unit_tests` |
| Integration Tests | All Robot Framework tests pass | `nox -s integration_tests` |
| Type Checking | Zero Pyright errors (strict mode) | `nox -s typecheck` |
| Linting | Zero Ruff violations | `nox -s lint` |
| Coverage | ≥ 97% line coverage | `nox -s coverage_report` |
| Security Scan | No high/critical Bandit findings | `nox -s security_scan` |
| Performance | No ASV regressions > 10% | `nox -s benchmarks` |
| Documentation | All public APIs documented | `nox -s docs` |

---

## Cross-Milestone Architectural Invariants

1. **Spec-first**: No feature implemented without spec coverage. Implementation better approach → update spec first via PR.
2. **Layer boundaries**: Presentation → Application → Domain → Infrastructure. No reverse dependencies.
3. **Type safety**: Full Pyright strict compliance. No `# type: ignore` suppressions.
4. **Fail-fast**: All argument validation at entry points. No silent failures.
5. **ULID identifiers**: Plans, decisions, resources, correction attempts, validation attachments use ULIDs.
6. **Namespace format**: `[[server:]namespace/]name`. `local/` reserved for local-only items.
7. **A2A exclusivity**: All client-server communication uses A2A. No REST API.
8. **BDD tests**: All unit-level tests as Behave/Gherkin scenarios. No xUnit-style tests.
9. **File size limit**: No source file exceeds 500 lines.
