From df5fe8d13124c8f3fccb8e3ed08bba3a3d101efa Mon Sep 17 00:00:00 2001 From: CleverThis Date: Thu, 16 Apr 2026 06:15:26 +0000 Subject: [PATCH 1/2] spec(autonomy): add v3.5.0 Autonomy Hardening specification section [AUTO-ARCH-21] --- docs/specification.md | 433 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 433 insertions(+) diff --git a/docs/specification.md b/docs/specification.md index 914397026..13ecd6bfe 100644 --- a/docs/specification.md +++ b/docs/specification.md @@ -47381,6 +47381,439 @@ The pipeline produces an `AssembledContext` object delivered to the actor: --- +#### Detailed Specification [AUTO-ARCH-21] + +!!! info "Milestone Scope" + **v3.5.0 — M6: Autonomy Hardening** is the sixth milestone in the CleverAgents release series. Its goal is to enable the system to autonomously execute large-scale tasks (e.g., porting a substantial codebase) using hierarchical plan decomposition with 4+ levels of subplans, decision correction with selective subtree recomputation, parallel execution scaling to 10+ concurrent subplans, and validation-gated apply. + +!!! note "Scope Adjustments" + Server stubs previously scoped to this milestone have been moved to **M9 (v3.8.0)** following the ACP to A2A protocol adoption ([ADR-047](adr/ADR-047-acp-standard-adoption.md)) and server architecture redesign ([ADR-048](adr/ADR-048-server-application-architecture.md)). TUI features have been moved to **M8 (v3.7.0)**. + +##### Overview + +Autonomy Hardening is the capability milestone at which CleverAgents transitions from a system that can execute individual plans to one that can autonomously orchestrate large-scale, multi-level work with minimal human intervention. The key challenge is not merely running more plans in parallel — it is doing so safely, correctly, and with the ability to recover from errors without human guidance. + +The four pillars of Autonomy Hardening are: + +1. **Hierarchical Decomposition** — Breaking a large task into a tree of subplans with 4+ levels of depth, where each level represents a progressively finer-grained unit of work. +2. **Parallel Execution** — Running 10+ subplans concurrently, with resource management, result aggregation, and conflict resolution. +3. **Decision Correction** — When a decision proves wrong, recomputing only the affected subtree rather than restarting the entire plan. +4. **Validation-Gated Apply** — Ensuring that changes are only applied to real resources after a full validation pipeline passes. + +The A2A facade provides the unified interface through which all of these capabilities are accessed — both from the CLI and from any A2A-compatible client. + +###### Why Autonomy Hardening Is Needed + +Prior milestones established the core plan lifecycle (v3.1.0-v3.4.0) and the ACMS context pipeline (v3.4.0). These give CleverAgents the ability to execute a single plan against a single project. However, real-world large-scale tasks — porting a Firefox-scale codebase, migrating a large database schema, refactoring a monolith — cannot be expressed as a single plan. They require: + +- **Decomposition** into hundreds or thousands of independent work units +- **Parallelism** to complete in reasonable time +- **Error recovery** that does not require restarting from scratch +- **Safety** that prevents partial or incorrect changes from being applied + +Autonomy Hardening delivers all four. + +--- + +##### A2A Facade Module (v3.5.0) + +The **A2A Facade** (`cleveragents.a2a`) is the sole interface between the Presentation layer (CLI, TUI, IDE plugin, external clients) and the Application layer (plan lifecycle, registry services, context assembly). It implements the [Agent-to-Agent (A2A) Protocol](https://a2a-protocol.org) standard as defined in [ADR-047](adr/ADR-047-acp-standard-adoption.md). + +!!! adr "Architecture Decision" + The A2A facade design is governed by [ADR-047: A2A Standard Adoption](adr/ADR-047-acp-standard-adoption.md) and [ADR-048: Server Application Architecture](adr/ADR-048-server-application-architecture.md). All client-server communication uses A2A JSON-RPC 2.0. There is no REST API. + +###### Session Management + +Sessions are persistent conversation threads tied to an orchestrator actor. In v3.5.0, session lifecycle operations are fully functional via the A2A facade: + +| A2A Extension Method | CLI Command | Description | +|---------------------|-------------|-------------| +| `_cleveragents/registry/session/list` | `agents session list` | List all sessions | +| `_cleveragents/registry/session/show` | `agents session show SESSION_ID` | Get session details | +| `message/send` | `agents session tell` | Send a message to the session's orchestrator actor | +| `_cleveragents/registry/session/remove` | `agents session delete SESSION_ID` | Close and delete a session | + +When a session does not yet exist, `message/send` creates one implicitly. The session ID is returned in the Task metadata. Subsequent messages reference the session via the A2A `contextId` field. + +**Session Model Boundaries:** + +- Sessions are scoped to a single orchestrator actor +- Sessions persist message history across multiple plans +- Sessions are identified by ULID; namespaced as `[[server:]namespace/]session-id` +- In local mode, sessions are stored in SQLite; in server mode, in PostgreSQL + +###### Plan Lifecycle via A2A + +All plan lifecycle operations are exposed as A2A extension methods. In v3.5.0, the full plan lifecycle — create, execute, apply, diff — is functional: + +| A2A Extension Method | CLI Command | Application Service | +|---------------------|-------------|---------------------| +| `_cleveragents/plan/use` | `agents plan use` | `PlanLifecycleService.use_action()` | +| `_cleveragents/plan/execute` | `agents plan execute` | `PlanLifecycleService.execute_plan()` | +| `_cleveragents/plan/apply` | `agents plan apply` | `PlanLifecycleService.apply_plan()` | +| `_cleveragents/plan/diff` | `agents plan diff` | `PlanService.get_diff()` | +| `_cleveragents/plan/status` | `agents plan status` | `PlanService.get_status()` | +| `_cleveragents/plan/tree` | `agents plan tree` | `PlanService.get_tree()` | +| `_cleveragents/plan/correct` | `agents plan correct` | `CorrectionFlow.correct()` | +| `_cleveragents/plan/cancel` | `agents plan cancel` | `PlanService.cancel()` | + +###### Event Queue Publish/Subscribe + +The A2A facade exposes the domain event bus through A2A streaming. Clients subscribe to plan and session events via the standard A2A `tasks/subscribe` operation and receive `TaskStatusUpdateEvent` and `TaskArtifactUpdateEvent` messages as the plan progresses. + +**Event Categories Surfaced via A2A:** + +| Domain Event | A2A Event | When Emitted | +|-------------|-----------|--------------| +| `plan.created` | `TaskStatusUpdateEvent{state: submitted}` | Plan created via `plan use` | +| `plan.phase_changed` | `TaskStatusUpdateEvent{state: working}` | Phase transition | +| `plan.applied` | `TaskStatusUpdateEvent{state: completed}` | Plan successfully applied | +| `plan.errored` | `TaskStatusUpdateEvent{state: failed}` | Plan execution failed | +| `decision.created` | `TaskArtifactUpdateEvent` | Decision recorded in tree | +| `budget.warning` | `TaskArtifactUpdateEvent` | Budget threshold approaching | +| `budget.exceeded` | `TaskStatusUpdateEvent{state: input-required}` | Budget cap hit | + +In local mode, the `A2aEventQueue` delivers events in-process without network overhead. The `ReactiveEventBus` (RxPY-backed) serves as the backbone. In server mode, events flow as SSE (Server-Sent Events) over the A2A HTTP connection. + +###### Module Boundaries and Public Interfaces + +The A2A facade module (`cleveragents.a2a`) exposes the following public interfaces: + +| Class / Function | Role | +|-----------------|------| +| `A2aLocalFacade` | Extension method dispatch in local mode | +| `A2aClient` | Client-side A2A wrapper (wraps A2A Python SDK) | +| `A2aEventQueue` | In-process event delivery for local mode | +| `TransportSelector` | Selects stdio vs. HTTP transport based on config | +| `A2aRequest` / `A2aResponse` | Wire format models | + +**Module Invariants:** + +- All Presentation-layer code **must** route through the A2A facade. No direct calls to Application-layer services from CLI or TUI code. +- Extension methods use the `_cleveragents/{domain}/{operation}` naming convention. +- Standard A2A operations (`message/send`, `tasks/*`) are never modified. + +--- + +##### Guard System (v3.5.0) + +The Guard System enforces safety and budget constraints at runtime, operating independently of the phase-transition thresholds defined in Automation Profiles. Guards gate individual tool invocations and execution steps. + +Guards operate at the per-invocation level (tool calls, steps, cost). Safety Profiles operate at the plan level (sandbox requirements, checkpoint requirements, unsafe tool gating). Both may be active simultaneously; the tighter constraint wins. + +###### Guard Types + +**1. Denylist Guard** — Blocks specific tools from being called automatically. Tools on the denylist always require human approval regardless of confidence score. + +**2. Budget Cap Guard** — Blocks tool invocations when the cumulative cost exceeds the configured cap. When the cap is hit, the Task enters `input-required` state. + +**3. Tool Call Limit Guard** — Blocks further tool invocations when the per-step call count exceeds the limit. Prevents runaway loops. + +**4. Write Approval Guard** — Requires human approval before any write operation (tool with `writes=true`). + +**5. Apply Approval Guard** — Requires human approval before the Apply phase begins. + +###### Guard Enforcement Pipeline + +Guards are evaluated in a fixed order for every tool invocation: + +1. **Denylist check** — If the tool is on the denylist, it is blocked immediately (no approval possible). +2. **Allowlist check** — If an allowlist is set and the tool is not on it, it is blocked (no approval possible). +3. **Tool call limit** — If the call count has reached the limit, approval is required. +4. **Cost budget** — If the cumulative cost has reached the cap, approval is required. +5. **Write approval** — If the operation is a write and write approval is required. +6. **Apply approval** — If the tool name is `__apply__` and apply approval is required. + +**GuardResult Fields:** + +| Field | Type | Description | +|-------|------|-------------| +| `allowed` | `bool` | Whether the invocation may proceed | +| `reason` | `str or None` | Human-readable explanation when blocked | +| `requires_approval` | `bool` | Whether human approval can unblock the invocation | + +When `requires_approval=true`, the A2A Task enters `input-required` state. When `requires_approval=false` (denylist/allowlist), the invocation is permanently blocked. + +###### Automation Profile Resolution Precedence + +The automation profile determines which guards are active and what the phase-transition thresholds are. Resolution follows a strict precedence chain (highest to lowest priority): + +1. **Plan-level profile** — A profile specified directly on the plan via `agents plan use --automation-profile NAME`. +2. **Action-level profile** — The profile declared in the Action YAML definition. +3. **Global default profile** — The system-wide default configured via `agents config set default_automation_profile`. +4. **Built-in "review" profile** — The fallback when no profile is configured at any level. + +**Precedence Rules:** + +- **Plan > Action > Global**: A profile specified on the plan overrides the action's profile, which overrides the global default. +- **Non-overridable global invariants always win**: Global invariants marked `non_overridable` are enforced regardless of profile precedence. +- **Safety Profile composition**: The resolved automation profile's `safety` sub-model provides all hard safety constraints. + +--- + +##### Hierarchical Decomposition Engine (v3.5.0) + +The Hierarchical Decomposition Engine (`cleveragents.application.services.decomposition_service`) breaks large tasks into a tree of subplans with 4+ levels of depth. It is invoked during the Strategize phase and produces a decomposition tree that drives the Execute phase. + +###### Decomposition Strategy + +The engine uses three complementary clustering strategies applied recursively: + +| Strategy | Description | When Used | +|----------|-------------|-----------| +| **Directory** | Groups files by common directory prefix | Default; preserves code locality | +| **Language** | Groups files by file extension | Polyglot projects | +| **Size** | Groups files by cumulative estimated token count | Large files or uneven distributions | + +**Configuration:** + +| Parameter | Default | Description | +|-----------|---------|-------------| +| `planner_max_depth` | 4 | Maximum recursion depth (minimum for v3.5.0 acceptance) | +| `planner_max_files_per_subplan` | 500 | Upper file count per leaf subplan | +| `planner_max_tokens_per_subplan` | 100000 | Upper token count per leaf subplan | +| `planner_min_files_per_subplan` | 10 | Threshold below which decomposition is skipped | + +**Example: Firefox-Scale Decomposition (4 levels):** + +``` +Level 0: Root Plan (entire Firefox codebase) + Level 1: Component Plans (js/, dom/, layout/, gfx/, ...) + Level 2: Module Plans (js/src/vm/, js/src/jit/, ...) + Level 3: File Group Plans (vm/Interpreter.*, vm/Stack.*, ...) + Level 4: Leaf Plans (individual file sets, up to 500 files each) +``` + +###### Subplan Spawning and Tracking + +Each node in the decomposition tree corresponds to a subplan. The engine records two types of decisions during decomposition: + +1. **`strategy_choice`** — The overall decomposition strategy selected (directory/language/size). +2. **`subplan_spawn`** — One per leaf node, recording the files assigned to that subplan. + +**Subplan States:** + +| State | Description | +|-------|-------------| +| `PENDING` | Created but not yet executing | +| `EXECUTING` | Currently running | +| `COMPLETED` | Finished successfully | +| `ERRORED` | Failed; may be retried | +| `CANCELLED` | Cancelled (e.g., due to `fail_fast`) | + +###### Selective Subtree Recomputation for Decision Correction + +When a decision proves incorrect, the correction system recomputes only the affected subtree rather than restarting the entire plan. This is the key efficiency gain of Autonomy Hardening. + +The correction system uses breadth-first search (BFS) over the decision tree's adjacency list to find all decisions affected by a correction. Starting from the target decision, it traverses all child decisions recursively. + +**Correction Flow:** + +1. Operator identifies incorrect decision D_n +2. `CorrectionFlow.correct(decision_id=D_n, mode="revert", guidance="...")` +3. BFS computes affected subtree: all decisions reachable from D_n +4. Affected subplans are rolled back to their pre-D_n checkpoint +5. Strategize phase re-runs for the affected subtree only +6. Execute phase re-runs for the recomputed subtree +7. Unaffected subplans continue without interruption + +**Risk Classification:** + +| Affected Decisions | Risk Level | Action | +|-------------------|------------|--------| +| 3 or fewer | Low | Auto-proceed | +| 4 to 10 | Medium | Warn user, proceed | +| More than 10 | High | Require explicit confirmation | + +**Module Boundaries:** + +- `DecompositionService` — Orchestrates decomposition; records decisions +- `DependencyClosureComputer` — Computes transitive dependency closures for DAG ordering +- `CorrectionFlow` — Manages the correction lifecycle (request to analyze to execute) +- `CorrectionAttemptRepository` — Persists correction attempt records + +--- + +##### Parallel Execution Subsystem (v3.5.0) + +The Parallel Execution Subsystem (`cleveragents.application.services.subplan_service`) executes multiple subplans concurrently, scaling to 10+ concurrent subplans. + +###### Concurrency Model + +**Execution Modes:** + +| Mode | Description | Use Case | +|------|-------------|----------| +| `sequential` | One at a time, in order | Ordered migrations, sequential patches | +| `parallel` | Concurrent up to `max_parallel` | Independent file sets, maximum throughput | +| `dependency_ordered` | Topological sort; concurrent within waves | DAG-dependent work (e.g., build order) | + +The `max_parallel` setting (range: 1-50) controls the thread pool size. For v3.5.0 acceptance, the system must demonstrate stable execution at `max_parallel=10` or higher. The thread pool is backed by Python's `concurrent.futures.ThreadPoolExecutor`. + +For projects with inter-file dependencies, the `dependency_ordered` mode uses Kahn's algorithm for topological sorting. Independent subplans within the same topological wave execute concurrently; subsequent waves wait for the previous wave to complete. + +###### Resource Management + +- The thread pool is created fresh for each `execute_all()` call +- Threads are daemon threads; they do not block process exit +- On `fail_fast`, remaining futures are cancelled via `Future.cancel()` +- Cancelled futures are reported with `CANCELLED` status (not `ERRORED`) +- Each subplan has an optional wall-clock timeout (`timeout_per_subplan_seconds`); the timeout applies to the entire retry loop, not per attempt + +###### Result Aggregation + +After all subplans complete, the `SubplanMergeService` aggregates their outputs: + +| Merge Strategy | Description | When to Use | +|---------------|-------------|-------------| +| `git_three_way` | Three-way merge via `git merge-file` | Default; handles non-overlapping changes | +| `sequential_apply` | Apply in completion order | Ordered patches | +| `fail_on_conflict` | Raise `MergeConflictError` on conflict | Strict mode; manual resolution required | +| `last_wins` | Final subplan's output wins | Simple override scenarios | + +--- + +##### Validation-Gated Apply (v3.5.0) + +The Validation-Gated Apply subsystem ensures that changes are only applied to real resources after a full validation pipeline passes. This is the final safety gate before the Apply phase. + +###### Validation Pipeline + +The validation pipeline runs all attached validations against the sandbox changeset before allowing the Apply phase to proceed. An empty validation summary (no validations ran) is treated as a failed gate, because Apply must never proceed without validation evidence. + +- **Required validations** (`mode: required`) — If any fail, Apply is blocked and the plan enters `constrained` state. +- **Informational validations** (`mode: informational`) — Failures log a warning but do not block Apply. + +###### Gate Enforcement + +The Apply gate is enforced by `PlanLifecycleService.apply_plan()`. The method: + +1. Runs the validation pipeline against the sandbox changeset +2. If any required validation fails, transitions the plan to `constrained` state and raises `ValidationGateError` +3. If no validations ran, transitions the plan to `constrained` state and raises `ValidationGateError` +4. If all required validations pass, applies the sandbox changeset to real resources + +**Plan States After Validation:** + +| Validation Result | Plan State | Next Action | +|------------------|------------|-------------| +| All required passed | `applying` then `applied` | Done | +| No validations ran | `constrained` | Attach or run validations before Apply | +| Required validation failed | `constrained` | Fix issues, re-execute, or revert to Strategize | +| Informational validation failed | `applying` then `applied` | Warning logged; apply proceeds | + +The `require_approval_for_apply` guard adds a human approval gate before the validation pipeline runs. When set, the A2A Task enters `input-required` state and waits for user approval before proceeding to validation. + +--- + +##### Cross-Cutting Concerns for Autonomy (v3.5.0) + +###### Error Handling + +Autonomy Hardening introduces new error categories specific to large-scale autonomous execution: + +| Error Class | When Raised | Recovery | +|-------------|-------------|----------| +| `SubplanTimeoutError` | Subplan exceeds `timeout_per_subplan_seconds` | Retry or cancel subplan | +| `MergeConflictError` | Subplan outputs conflict and `fail_on_conflict` is set | Manual resolution or re-decompose | +| `CircularDependencyError` | Dependency graph has a cycle | Fix dependency graph | +| `ValidationGateError` | Required validation failed before Apply | Fix validation issues | +| `BudgetExceededError` | Cost cap hit during execution | Approve continuation or cancel | +| `DecompositionDepthError` | Max decomposition depth exceeded | Increase `planner_max_depth` | + +**Error Recovery Strategies:** + +1. **Retry** — For transient errors, the subsystem retries up to `max_retries` times. +2. **Selective Recomputation** — For decision errors, the correction system recomputes only the affected subtree. +3. **Checkpoint Rollback** — For catastrophic failures, the plan can be rolled back to the last checkpoint. +4. **Cancel and Restart** — For unrecoverable errors, the plan is cancelled and can be restarted from scratch. + +###### Observability + +All autonomy-related events are emitted to the domain event bus and surfaced via A2A streaming: + +| Observable | Event | Details | +|-----------|-------|---------| +| Decomposition | `decision.created{type: subplan_spawn}` | Files assigned to each subplan | +| Subplan start | `plan.phase_changed{subplan_id: ...}` | Subplan begins execution | +| Subplan complete | `plan.applied{subplan_id: ...}` | Subplan finishes | +| Guard triggered | `budget.warning` / `budget.exceeded` | Budget threshold events | +| Correction | `decision.superseded` | Decision invalidated by correction | +| Validation | `validation.passed` / `validation.started` | Validation pipeline events | + +Every guard enforcement event is recorded in a `GuardrailAuditTrail` persisted to plan metadata (max 10,000 entries; oldest evicted when full). All autonomy subsystems use `structlog` for structured logging, consistent with [ADR-025](adr/ADR-025-observability-and-logging.md). + +###### Configuration + +Autonomy Hardening introduces the following configuration keys: + +| Key | Default | Description | +|-----|---------|-------------| +| `autonomy.planner_max_depth` | `4` | Maximum decomposition depth | +| `autonomy.planner_max_files_per_subplan` | `500` | Max files per leaf subplan | +| `autonomy.planner_max_tokens_per_subplan` | `100000` | Max tokens per leaf subplan | +| `autonomy.planner_min_files_per_subplan` | `10` | Min files before decomposition is skipped | +| `autonomy.default_max_parallel` | `5` | Default parallel subplan count | +| `autonomy.default_merge_strategy` | `git_three_way` | Default merge strategy | +| `autonomy.default_timeout_per_subplan_seconds` | `null` | Default per-subplan timeout | +| `autonomy.guardrail_audit_max_entries` | `10000` | Max guardrail audit trail entries | + +--- + +##### Acceptance Criteria (v3.5.0) + +###### Functional Acceptance Criteria + +| Criterion | Verification Method | +|-----------|---------------------| +| A2A facade session and plan lifecycle operations functional via CLI | `agents session create`, `agents plan use/execute/apply` all succeed end-to-end | +| Event queue publish/subscribe operational | Subscribe to `plan.created` and `plan.phase_changed` events; verify delivery | +| Guard enforcement works (denylist, budget caps, tool call limits) | Configure guards; verify blocked invocations enter `input-required` state | +| Automation profile resolution precedence correct (plan > action > global) | Set conflicting profiles at each level; verify plan-level wins | +| Full autonomy acceptance flow with hierarchical decomposition (4+ levels) | Run a large-project plan; verify decomposition tree has depth >= 4 | +| Parallel execution scales to 10+ concurrent subplans | Configure `max_parallel=10`; verify 10 subplans execute concurrently | +| A realistic porting task completes autonomously | Port a Firefox-scale codebase without human intervention | +| nox passes with coverage >= 97% including large-project suites | `nox -s tests` passes; coverage report shows >= 97% | + +###### Technical Acceptance Criteria + +| Criterion | Verification Method | +|-----------|---------------------| +| Hierarchical decomposition creates 4+ levels of subplans | `agents plan tree PLAN_ID` shows depth >= 4 | +| Decision correction recomputes only affected subtree | Correct a mid-tree decision; verify unaffected subplans are not re-executed | +| Parallel execution scales to 10+ concurrent subplans | Load test with `max_parallel=10`; verify no deadlocks or race conditions | +| A realistic porting task (Firefox-scale) completes autonomously | End-to-end test with Firefox source tree | +| nox passes with coverage >= 97% including large-project suites | CI pipeline passes | + +--- + +##### ADR References (v3.5.0) + +The following Architecture Decision Records are directly relevant to v3.5.0 Autonomy Hardening: + +| ADR | Title | Relevance | +|-----|-------|-----------| +| [ADR-047](adr/ADR-047-acp-standard-adoption.md) | A2A Standard Adoption | Defines the A2A protocol as the sole client-server interface; governs the A2A facade design | +| [ADR-048](adr/ADR-048-server-application-architecture.md) | Server Application Architecture | Defines the server architecture; explains why server stubs moved to M9 | +| [ADR-006](adr/ADR-006-plan-lifecycle.md) | Plan Lifecycle | Defines the four-phase plan lifecycle | +| [ADR-007](adr/ADR-007-decision-tree-and-correction.md) | Decision Tree and Correction | Defines the decision tree model and correction semantics | +| [ADR-017](adr/ADR-017-automation-profiles.md) | Automation Profiles | Defines automation profiles, guards, and safety profiles | +| [ADR-025](adr/ADR-025-observability-and-logging.md) | Observability and Logging | Defines structured logging and event bus patterns | +| [ADR-033](adr/ADR-033-decision-recording-protocol.md) | Decision Recording Protocol | Defines how decisions are recorded and versioned | +| [ADR-035](adr/ADR-035-decision-tree-rollback-and-replay.md) | Decision Tree Rollback and Replay | Defines rollback semantics used by correction | +| [ADR-041](adr/ADR-041-safety-profile-extraction.md) | Safety Profile Extraction | Defines the Safety Profile as a composed sub-model of Automation Profile | + +**Key Scope Changes:** + +- **Server stubs moved to M9 (v3.8.0)**: The ACP to A2A protocol adoption (ADR-047) required a redesign of the server architecture (ADR-048). Server stubs previously scoped to v3.5.0 have been deferred to v3.8.0. +- **TUI features moved to M8 (v3.7.0)**: TUI features have been deferred to allow focus on the core autonomy capabilities in v3.5.0. + +--- + +*Section authored by [AUTO-ARCH-21] — Architecture Worker for milestone v3.5.0 Autonomy Hardening.* + +--- + ### v3.6.0 — Advanced Concepts & Deferred Features **Goal**: Advanced concepts not needed for basic MVP. Extends beyond core MVP but does not require TUI (v3.7.0) or Server (v3.8.0). Includes advanced context strategies, additional LLM backends, additional resource types, A2A module rename, container tool execution, pluggable scope chain extensions, cost/session budgets, and E2E workflow specification tests. -- 2.52.0 From bbfbcd8d6409c7a6240597e835f1f00239525eb1 Mon Sep 17 00:00:00 2001 From: drew Date: Tue, 16 Jun 2026 17:26:14 -0400 Subject: [PATCH 2/2] docs: align autonomy hardening session and apply gates --- docs/specification.md | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/docs/specification.md b/docs/specification.md index 13ecd6bfe..288329494 100644 --- a/docs/specification.md +++ b/docs/specification.md @@ -47424,14 +47424,14 @@ The **A2A Facade** (`cleveragents.a2a`) is the sole interface between the Presen ###### Session Management -Sessions are persistent conversation threads tied to an orchestrator actor. In v3.5.0, session lifecycle operations are fully functional via the A2A facade: +Sessions are persistent conversation threads tied to an orchestrator actor. In v3.5.0, session lifecycle operations remain part of the A2A/session workflow surface, not registry CRUD. Sessions are runtime conversation state, so they are not included in the `_cleveragents/registry/{entity}/*` entity set. -| A2A Extension Method | CLI Command | Description | +| A2A / Service Route | CLI Command | Description | |---------------------|-------------|-------------| -| `_cleveragents/registry/session/list` | `agents session list` | List all sessions | -| `_cleveragents/registry/session/show` | `agents session show SESSION_ID` | Get session details | -| `message/send` | `agents session tell` | Send a message to the session's orchestrator actor | -| `_cleveragents/registry/session/remove` | `agents session delete SESSION_ID` | Close and delete a session | +| `session/list` routes to `SessionWorkflow.list()` | `agents session list` | List all sessions | +| `session/load` routes to `SessionWorkflow.resume()` / `SessionService.get()` | `agents session show SESSION_ID` | Get session details | +| `message/send` routes to `SessionWorkflow.tell()` | `agents session tell` | Send a message to the session's orchestrator actor | +| `SessionService.delete()` via the session lifecycle command path | `agents session delete SESSION_ID` | Close and delete a session | When a session does not yet exist, `message/send` creates one implicitly. The session ID is returned in the Task metadata. Subsequent messages reference the session via the A2A `contextId` field. @@ -47679,7 +47679,7 @@ The Validation-Gated Apply subsystem ensures that changes are only applied to re ###### Validation Pipeline -The validation pipeline runs all attached validations against the sandbox changeset before allowing the Apply phase to proceed. An empty validation summary (no validations ran) is treated as a failed gate, because Apply must never proceed without validation evidence. +The validation pipeline runs during Execute, after sandbox changes are produced and before the plan can proceed to Apply. Apply checks the final validation summary/snapshot produced during Execute. An empty validation summary (no required validations ran) is treated as a failed gate, because Apply must never proceed without validation evidence. - **Required validations** (`mode: required`) — If any fail, Apply is blocked and the plan enters `constrained` state. - **Informational validations** (`mode: informational`) — Failures log a warning but do not block Apply. @@ -47688,10 +47688,10 @@ The validation pipeline runs all attached validations against the sandbox change The Apply gate is enforced by `PlanLifecycleService.apply_plan()`. The method: -1. Runs the validation pipeline against the sandbox changeset -2. If any required validation fails, transitions the plan to `constrained` state and raises `ValidationGateError` -3. If no validations ran, transitions the plan to `constrained` state and raises `ValidationGateError` -4. If all required validations pass, applies the sandbox changeset to real resources +1. Loads the final validation summary/snapshot recorded by the Execute phase +2. If any required validation failed, transitions the plan to `constrained` state and raises `ValidationGateError` +3. If no required validation ran, transitions the plan to `constrained` state and raises `ValidationGateError` +4. If all required validations passed, applies the sandbox changeset to real resources **Plan States After Validation:** @@ -47702,7 +47702,7 @@ The Apply gate is enforced by `PlanLifecycleService.apply_plan()`. The method: | Required validation failed | `constrained` | Fix issues, re-execute, or revert to Strategize | | Informational validation failed | `applying` then `applied` | Warning logged; apply proceeds | -The `require_approval_for_apply` guard adds a human approval gate before the validation pipeline runs. When set, the A2A Task enters `input-required` state and waits for user approval before proceeding to validation. +The `require_approval_for_apply` guard adds a human approval gate before Apply commits the sandbox changeset. When set, the A2A Task enters `input-required` state and waits for user approval before the apply gate checks the Execute-phase validation snapshot. --- -- 2.52.0