docs: add v3.2.0 and v3.3.0 feature documentation [AUTO-DOCS-2]
This commit is contained in:
cleveragents-auto
+343
@@ -0,0 +1,343 @@
|
||||
# CLI Reference — v3.2.0 and v3.3.0 Features
|
||||
|
||||
This page provides a consolidated reference for the CLI commands introduced in the
|
||||
**v3.2.0** (Decisions + Validations + Invariants) and **v3.3.0** (Corrections +
|
||||
Subplans + Checkpoints) milestones.
|
||||
|
||||
For the full plan command reference see [`reference/plan_cli.md`](reference/plan_cli.md).
|
||||
For invariant management see [`reference/invariants.md`](reference/invariants.md).
|
||||
For checkpoint and rollback details see [`reference/checkpointing.md`](reference/checkpointing.md).
|
||||
|
||||
---
|
||||
|
||||
## Decision Tree Commands (v3.2.0)
|
||||
|
||||
### `agents plan tree`
|
||||
|
||||
Renders the decision tree for a plan as a visual hierarchy.
|
||||
|
||||
```bash
|
||||
agents plan tree <PLAN_ID> [OPTIONS]
|
||||
```
|
||||
|
||||
| Option | Description |
|
||||
|--------|-------------|
|
||||
| `--format`, `-f` | Output format: `json`, `yaml`, `plain`, `table`, `rich` (default: `rich`) |
|
||||
| `--show-superseded` | Include superseded (corrected) decisions in the tree |
|
||||
| `--depth` | Maximum tree depth to render (`0` = unlimited, default: `0`) |
|
||||
|
||||
**Examples:**
|
||||
|
||||
```bash
|
||||
# Render the full decision tree in rich format
|
||||
agents plan tree 01HXYZ1234567890ABCDEFGH
|
||||
|
||||
# Include superseded decisions (useful for auditing corrections)
|
||||
agents plan tree 01HXYZ1234567890ABCDEFGH --show-superseded
|
||||
|
||||
# Limit depth for large plans
|
||||
agents plan tree 01HXYZ1234567890ABCDEFGH --depth 3
|
||||
|
||||
# JSON output for scripting
|
||||
agents plan tree 01HXYZ1234567890ABCDEFGH --format json
|
||||
```
|
||||
|
||||
> **Note:** Decision IDs displayed in the tree are full 26-character ULIDs (v3.8.0+),
|
||||
> which can be copied directly and used in `plan explain` or `plan correct` commands.
|
||||
|
||||
See also: [`reference/plan_cli.md#agents-plan-tree`](reference/plan_cli.md#agents-plan-tree)
|
||||
|
||||
---
|
||||
|
||||
### `agents plan explain`
|
||||
|
||||
Shows detailed information about a single decision node, including the question
|
||||
posed, the chosen option, alternatives considered, and optional context/reasoning.
|
||||
|
||||
```bash
|
||||
agents plan explain <DECISION_ID> [OPTIONS]
|
||||
```
|
||||
|
||||
| Option | Description |
|
||||
|--------|-------------|
|
||||
| `--format`, `-f` | Output format: `json`, `yaml`, `plain`, `table`, `rich` |
|
||||
| `--show-context` | Include the context snapshot captured at decision time |
|
||||
| `--show-reasoning` | Include the actor's raw LLM reasoning trace |
|
||||
|
||||
**Examples:**
|
||||
|
||||
```bash
|
||||
# Default rich output
|
||||
agents plan explain 01HXYZ1234567890ABCDEFGH
|
||||
|
||||
# Full detail with context and reasoning
|
||||
agents plan explain 01HXYZ1234567890ABCDEFGH --show-context --show-reasoning
|
||||
|
||||
# JSON for programmatic use
|
||||
agents plan explain 01HXYZ1234567890ABCDEFGH --format json --show-context
|
||||
```
|
||||
|
||||
See also: [`reference/plan_cli.md#agents-plan-explain`](reference/plan_cli.md#agents-plan-explain)
|
||||
|
||||
---
|
||||
|
||||
## Decision Correction Commands (v3.3.0)
|
||||
|
||||
### `agents plan correct`
|
||||
|
||||
Re-executes a plan from a specific decision point using one of two correction modes.
|
||||
|
||||
```bash
|
||||
agents plan correct --mode=<MODE> <DECISION_ID> [OPTIONS]
|
||||
```
|
||||
|
||||
| Option | Description |
|
||||
|--------|-------------|
|
||||
| `--mode` | Correction mode: `revert` or `append` (required) |
|
||||
| `--guidance` | Operator guidance text for `append` mode (required for `append`) |
|
||||
| `--dry-run` | Preview the impact without making changes |
|
||||
| `--yes`, `-y` | Skip the confirmation prompt |
|
||||
| `--format`, `-f` | Output format: `json`, `yaml`, `plain`, `table`, `rich` |
|
||||
|
||||
#### `--mode=revert`
|
||||
|
||||
Invalidates the targeted decision and all its descendants (BFS traversal), then
|
||||
re-executes the plan from that decision point. Associated artifacts are archived
|
||||
and affected child plans are rolled back.
|
||||
|
||||
```bash
|
||||
# Revert a decision and re-execute from that point
|
||||
agents plan correct --mode=revert 01HXYZ1234567890ABCDEFGH
|
||||
|
||||
# Preview impact without making changes
|
||||
agents plan correct --mode=revert 01HXYZ1234567890ABCDEFGH --dry-run
|
||||
|
||||
# Skip confirmation prompt
|
||||
agents plan correct --mode=revert 01HXYZ1234567890ABCDEFGH --yes
|
||||
```
|
||||
|
||||
**What happens:**
|
||||
|
||||
```
|
||||
D1 (target) <-- revert starts here
|
||||
|
|
||||
+----+----+
|
||||
D2 D3 <- all invalidated
|
||||
|
|
||||
D4 <- also invalidated
|
||||
```
|
||||
|
||||
#### `--mode=append`
|
||||
|
||||
Preserves the original decision and spawns a new child plan rooted at the target
|
||||
node. The child plan carries the operator's guidance and produces additional
|
||||
decisions without disturbing the existing tree.
|
||||
|
||||
```bash
|
||||
# Append a correction with guidance
|
||||
agents plan correct --mode=append 01HXYZ1234567890ABCDEFGH \
|
||||
--guidance "Use a safer migration strategy that avoids table locks"
|
||||
|
||||
# Append with dry-run to preview
|
||||
agents plan correct --mode=append 01HXYZ1234567890ABCDEFGH \
|
||||
--guidance "Prefer read-only operations where possible" \
|
||||
--dry-run
|
||||
```
|
||||
|
||||
**What happens:**
|
||||
|
||||
```
|
||||
D1 (target)
|
||||
|
|
||||
+------+----------+
|
||||
D2 (original) CP-new <- child plan appended
|
||||
```
|
||||
|
||||
**Risk levels** (based on affected decision count):
|
||||
|
||||
| Affected Decisions | Risk Level |
|
||||
|--------------------|------------|
|
||||
| <= 3 | `low` |
|
||||
| 4 - 10 | `medium` |
|
||||
| > 10 | `high` |
|
||||
|
||||
See also: [`reference/decision_correction.md`](reference/decision_correction.md)
|
||||
|
||||
---
|
||||
|
||||
## Invariant Management Commands (v3.2.0)
|
||||
|
||||
Invariants are natural-language constraints that govern plan execution. They are
|
||||
evaluated by the Invariant Reconciliation Actor at the start of the Strategize phase.
|
||||
|
||||
### `agents invariant add`
|
||||
|
||||
Creates a new invariant constraint.
|
||||
|
||||
```bash
|
||||
agents invariant add <NAME> --description <TEXT> [OPTIONS]
|
||||
```
|
||||
|
||||
| Option | Description |
|
||||
|--------|-------------|
|
||||
| `--description`, `-d` | Invariant constraint text (required) |
|
||||
| `--global` | Apply to every plan in the system (default scope) |
|
||||
| `--project <NAME>` | Scope to a specific project |
|
||||
| `--action <NAME>` | Scope to a specific action template |
|
||||
| `--format`, `-f` | Output format |
|
||||
|
||||
**Examples:**
|
||||
|
||||
```bash
|
||||
# Global invariant (applies to all plans)
|
||||
agents invariant add no-prod-deletes \
|
||||
--description "Never delete production data"
|
||||
|
||||
# Project-scoped invariant
|
||||
agents invariant add api-test-coverage \
|
||||
--description "All API changes need tests" \
|
||||
--project myapp
|
||||
|
||||
# Action-scoped invariant
|
||||
agents invariant add min-coverage \
|
||||
--description "Minimum 80% test coverage" \
|
||||
--action local/code-coverage
|
||||
```
|
||||
|
||||
**Scope hierarchy** (highest to lowest precedence):
|
||||
|
||||
| Scope | Description |
|
||||
|-------|-------------|
|
||||
| `PLAN` | Attached directly to a specific plan (via `plan use --invariant`) |
|
||||
| `PROJECT` | Applies to all plans targeting a project |
|
||||
| `GLOBAL` | Applies to every plan in the system |
|
||||
| `ACTION` | Defined in an action template; promoted to plan scope on `plan use` |
|
||||
|
||||
---
|
||||
|
||||
### `agents invariant list`
|
||||
|
||||
Lists all invariants, with optional scope filtering.
|
||||
|
||||
```bash
|
||||
agents invariant list [REGEX] [OPTIONS]
|
||||
```
|
||||
|
||||
| Option | Description |
|
||||
|--------|-------------|
|
||||
| `--global` | Show only global invariants |
|
||||
| `--project <NAME>` | Show invariants for a specific project |
|
||||
| `--effective --project <NAME>` | Show merged effective set for a project |
|
||||
| `--format`, `-f` | Output format |
|
||||
|
||||
**Examples:**
|
||||
|
||||
```bash
|
||||
# List all invariants
|
||||
agents invariant list
|
||||
|
||||
# Filter by scope
|
||||
agents invariant list --global
|
||||
agents invariant list --project myapp
|
||||
|
||||
# Show the merged effective set (with precedence applied)
|
||||
agents invariant list --effective --project myapp
|
||||
|
||||
# Filter by regex pattern
|
||||
agents invariant list "data.*safe"
|
||||
|
||||
# JSON output
|
||||
agents invariant list --format json
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `agents invariant remove`
|
||||
|
||||
Removes an invariant by its ULID.
|
||||
|
||||
```bash
|
||||
agents invariant remove <INVARIANT_ID> [OPTIONS]
|
||||
```
|
||||
|
||||
| Option | Description |
|
||||
|--------|-------------|
|
||||
| `--yes`, `-y` | Skip the confirmation prompt |
|
||||
| `--format`, `-f` | Output format |
|
||||
|
||||
**Examples:**
|
||||
|
||||
```bash
|
||||
# Remove with confirmation prompt
|
||||
agents invariant remove 01HXYZ1234567890ABCDEFGH
|
||||
|
||||
# Remove without confirmation (for scripts)
|
||||
agents invariant remove 01HXYZ1234567890ABCDEFGH --yes
|
||||
```
|
||||
|
||||
See also: [`reference/invariants.md`](reference/invariants.md)
|
||||
|
||||
---
|
||||
|
||||
## Checkpoint and Rollback Commands (v3.3.0)
|
||||
|
||||
### `agents plan rollback`
|
||||
|
||||
Restores sandbox state to a previously captured checkpoint.
|
||||
|
||||
```bash
|
||||
agents plan rollback [--yes|-y] <PLAN_ID> <CHECKPOINT_ID> [OPTIONS]
|
||||
```
|
||||
|
||||
| Option | Description |
|
||||
|--------|-------------|
|
||||
| `--yes`, `-y` | Skip the interactive confirmation prompt |
|
||||
| `--format`, `-f` | Output format: `json`, `yaml`, `plain`, `table`, `rich` |
|
||||
|
||||
**Examples:**
|
||||
|
||||
```bash
|
||||
# Rollback with confirmation prompt
|
||||
agents plan rollback 01HPLAN... 01HCHECKPOINT...
|
||||
|
||||
# Rollback without confirmation (for scripts)
|
||||
agents plan rollback --yes 01HPLAN... 01HCHECKPOINT...
|
||||
|
||||
# JSON output for scripting
|
||||
agents plan rollback --yes 01HPLAN... 01HCHECKPOINT... --format json
|
||||
```
|
||||
|
||||
**Guards:** Rollback is blocked if:
|
||||
|
||||
- The plan has already reached the `applied` terminal state.
|
||||
- The sandbox has been cleaned up.
|
||||
|
||||
**Automatic checkpoint triggers** (v3.8.0+):
|
||||
|
||||
| Trigger | When |
|
||||
|---------|------|
|
||||
| `on_tool_write` | Before each write-tool execution |
|
||||
| `on_tool_write_complete` | After each write-tool execution |
|
||||
| `on_subplan_spawn` | Before first subplan execution attempt |
|
||||
| `on_error` | When the Execute phase fails |
|
||||
|
||||
See also: [`reference/checkpointing.md`](reference/checkpointing.md)
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Command | Milestone | Description |
|
||||
|---------|-----------|-------------|
|
||||
| `agents plan tree <plan_id>` | v3.2.0 | Render decision tree |
|
||||
| `agents plan explain <decision_id>` | v3.2.0 | Show decision details |
|
||||
| `agents plan correct --mode=revert <decision_id>` | v3.3.0 | Re-execute from decision point |
|
||||
| `agents plan correct --mode=append <decision_id> --guidance <text>` | v3.3.0 | Append guidance as child plan |
|
||||
| `agents invariant add <name> --description <desc>` | v3.2.0 | Create invariant |
|
||||
| `agents invariant list` | v3.2.0 | List invariants |
|
||||
| `agents invariant remove <name>` | v3.2.0 | Remove invariant |
|
||||
| `agents plan rollback <plan_id> <checkpoint_id>` | v3.3.0 | Rollback to checkpoint |
|
||||
|
||||
---
|
||||
|
||||
*Automated by CleverAgents Bot — Supervisor: Documentation | Agent: documentation-pool-supervisor*
|
||||
@@ -0,0 +1,238 @@
|
||||
# Decision System
|
||||
|
||||
The CleverAgents decision system records every choice point in a plan's lifecycle
|
||||
as a persistent **Decision** node in a tree structure. This enables full auditability,
|
||||
targeted correction, and replay of plan execution.
|
||||
|
||||
This page provides a high-level guide to the decision system. For detailed API
|
||||
references see:
|
||||
|
||||
- [`reference/decision_model.md`](reference/decision_model.md) — Domain model
|
||||
- [`reference/decision_service.md`](reference/decision_service.md) — Service API
|
||||
- [`reference/decision_correction.md`](reference/decision_correction.md) — Correction subsystem
|
||||
- [`reference/invariants.md`](reference/invariants.md) — Invariant constraints
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
Every time an agent makes a meaningful choice during plan execution — selecting a
|
||||
strategy, choosing which files to modify, deciding how to handle an error — that
|
||||
choice is recorded as a **Decision**. Decisions form a tree rooted at the initial
|
||||
`prompt_definition` decision.
|
||||
|
||||
```
|
||||
prompt_definition (root)
|
||||
├── invariant_enforced <- constraints applied at start of Strategize
|
||||
├── strategy_choice <- high-level approach chosen
|
||||
│ ├── implementation_choice
|
||||
│ │ ├── resource_selection
|
||||
│ │ └── tool_invocation
|
||||
│ └── subplan_spawn <- decision to create a child plan
|
||||
└── strategy_choice
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Decision Recording (v3.2.0)
|
||||
|
||||
### What Gets Recorded
|
||||
|
||||
Each decision captures:
|
||||
|
||||
| Field | Description |
|
||||
|-------|-------------|
|
||||
| `decision_id` | Unique ULID identifier |
|
||||
| `plan_id` | The plan this decision belongs to |
|
||||
| `decision_type` | One of 11 types (see below) |
|
||||
| `question` | What question was being answered |
|
||||
| `chosen_option` | The option that was selected |
|
||||
| `alternatives_considered` | Other options that were evaluated |
|
||||
| `confidence_score` | Confidence in the choice (0.0–1.0) |
|
||||
| `rationale` | Human-readable explanation |
|
||||
| `actor_reasoning` | Raw LLM reasoning trace |
|
||||
| `context_snapshot` | Hash + reference to the context window at decision time |
|
||||
| `parent_decision_id` | Parent in the tree (None for root) |
|
||||
| `created_at` | UTC timestamp |
|
||||
|
||||
### Decision Types
|
||||
|
||||
| Type | Phase | Description |
|
||||
|------|-------|-------------|
|
||||
| `prompt_definition` | Strategize | Root decision — the plan prompt |
|
||||
| `invariant_enforced` | Strategize | An invariant constraint was applied |
|
||||
| `strategy_choice` | Strategize | High-level approach chosen |
|
||||
| `implementation_choice` | Execute | How to implement a specific task |
|
||||
| `resource_selection` | Execute | Which resources to read/modify |
|
||||
| `subplan_spawn` | Strategize | Decision to create a child plan |
|
||||
| `subplan_parallel_spawn` | Strategize | Spawn a group of child plans in parallel |
|
||||
| `tool_invocation` | Execute | Which skill/tool to use |
|
||||
| `error_recovery` | Execute | How to handle a failure |
|
||||
| `validation_response` | Execute | Response to a validation failure |
|
||||
| `user_intervention` | Any | User-provided guidance/correction |
|
||||
|
||||
---
|
||||
|
||||
## Tree Visualization (v3.2.0)
|
||||
|
||||
Use `agents plan tree` to render the decision tree for any plan:
|
||||
|
||||
```bash
|
||||
# Rich tree view (default)
|
||||
agents plan tree 01HXYZ1234567890ABCDEFGH
|
||||
|
||||
# Include superseded decisions
|
||||
agents plan tree 01HXYZ1234567890ABCDEFGH --show-superseded
|
||||
|
||||
# Limit depth
|
||||
agents plan tree 01HXYZ1234567890ABCDEFGH --depth 2
|
||||
```
|
||||
|
||||
The **current tree** consists of all decisions where `superseded_by IS NULL`.
|
||||
Superseded decisions are hidden by default but can be shown with `--show-superseded`
|
||||
for auditing corrections.
|
||||
|
||||
To inspect a specific decision:
|
||||
|
||||
```bash
|
||||
agents plan explain 01HDECISION...
|
||||
agents plan explain 01HDECISION... --show-context --show-reasoning
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Invariants (v3.2.0)
|
||||
|
||||
Invariants are natural-language constraints that are enforced at the start of the
|
||||
Strategize phase. The Invariant Reconciliation Actor evaluates each invariant and
|
||||
records an `invariant_enforced` decision for each one.
|
||||
|
||||
### Scope Hierarchy
|
||||
|
||||
| Scope | Precedence | Description |
|
||||
|-------|-----------|-------------|
|
||||
| `PLAN` | Highest | Attached directly to a specific plan |
|
||||
| `PROJECT` | Medium | Applies to all plans targeting a project |
|
||||
| `GLOBAL` | Lowest | Applies to every plan in the system |
|
||||
| `ACTION` | Promoted | Defined in action template; promoted to plan scope on `plan use` |
|
||||
|
||||
### Managing Invariants
|
||||
|
||||
```bash
|
||||
# Add a global invariant
|
||||
agents invariant add no-prod-deletes \
|
||||
--description "Never delete production data"
|
||||
|
||||
# Add a project-scoped invariant
|
||||
agents invariant add api-tests \
|
||||
--description "All API changes need tests" \
|
||||
--project myapp
|
||||
|
||||
# List all invariants
|
||||
agents invariant list
|
||||
|
||||
# Show effective set for a project (with precedence applied)
|
||||
agents invariant list --effective --project myapp
|
||||
|
||||
# Remove an invariant
|
||||
agents invariant remove 01HINVARIANT...
|
||||
```
|
||||
|
||||
### Violation Handling
|
||||
|
||||
When an invariant is violated during execution, an `InvariantViolation` is created
|
||||
with a severity of `error`, `warning`, or `info`. Reconciliation failures block the
|
||||
phase transition with `ReconciliationBlockedError` and emit `INVARIANT_VIOLATED` events.
|
||||
|
||||
---
|
||||
|
||||
## Correction Modes (v3.3.0)
|
||||
|
||||
The correction subsystem allows operators to modify a plan's decision tree after
|
||||
execution. Two modes are supported:
|
||||
|
||||
### Revert Mode
|
||||
|
||||
Invalidates the targeted decision and every descendant (BFS traversal). Associated
|
||||
artifacts are archived and affected child plans are rolled back. The plan then
|
||||
re-executes from the corrected decision point.
|
||||
|
||||
```bash
|
||||
# Preview impact
|
||||
agents plan correct --mode=revert 01HDECISION... --dry-run
|
||||
|
||||
# Apply correction
|
||||
agents plan correct --mode=revert 01HDECISION...
|
||||
```
|
||||
|
||||
### Append Mode
|
||||
|
||||
Preserves the original decision and spawns a new child plan rooted at the target
|
||||
node. The child plan carries operator guidance and produces additional decisions
|
||||
without disturbing the existing tree.
|
||||
|
||||
```bash
|
||||
agents plan correct --mode=append 01HDECISION... \
|
||||
--guidance "Use a safer migration strategy that avoids table locks"
|
||||
```
|
||||
|
||||
### Correction Lifecycle
|
||||
|
||||
```
|
||||
PENDING -> ANALYZING -> EXECUTING -> APPLIED
|
||||
-> FAILED
|
||||
PENDING -> CANCELLED
|
||||
ANALYZING -> CANCELLED
|
||||
```
|
||||
|
||||
### Impact Analysis
|
||||
|
||||
Before executing a correction, the system performs BFS impact analysis:
|
||||
|
||||
| Affected Decisions | Risk Level |
|
||||
|--------------------|------------|
|
||||
| <= 3 | `low` |
|
||||
| 4 - 10 | `medium` |
|
||||
| > 10 | `high` |
|
||||
|
||||
Use `--dry-run` to see the full impact report before committing.
|
||||
|
||||
### Correction Attempts
|
||||
|
||||
Each execution of a correction is tracked as a `CorrectionAttemptRecord`. Multiple
|
||||
attempts may exist for a single correction (e.g., if a first attempt fails and the
|
||||
operator retries). See [`reference/decision_correction.md`](reference/decision_correction.md)
|
||||
for the full schema.
|
||||
|
||||
---
|
||||
|
||||
## Correction Immutability
|
||||
|
||||
Corrections never mutate existing decisions. Instead:
|
||||
|
||||
1. A new `Decision` is created with `is_correction=True` and `corrects_decision_id`
|
||||
pointing to the original.
|
||||
2. The original decision has its `superseded_by` field set to the new decision's ID.
|
||||
3. All downstream decisions of the original are also superseded.
|
||||
|
||||
This preserves a complete audit trail of all decisions, including those that were
|
||||
later corrected.
|
||||
|
||||
---
|
||||
|
||||
## Related References
|
||||
|
||||
| Document | Description |
|
||||
|----------|-------------|
|
||||
| [`reference/decision_model.md`](reference/decision_model.md) | Full domain model with all fields and validation rules |
|
||||
| [`reference/decision_service.md`](reference/decision_service.md) | Service API for recording and querying decisions |
|
||||
| [`reference/decision_correction.md`](reference/decision_correction.md) | Correction subsystem, modes, and attempt tracking |
|
||||
| [`reference/invariants.md`](reference/invariants.md) | Invariant scopes, enforcement, and violation model |
|
||||
| [`adr/ADR-007-decision-tree-and-correction.md`](adr/ADR-007-decision-tree-and-correction.md) | Architecture decision record |
|
||||
| [`adr/ADR-033-decision-recording-protocol.md`](adr/ADR-033-decision-recording-protocol.md) | Decision recording protocol |
|
||||
| [`adr/ADR-016-invariant-system.md`](adr/ADR-016-invariant-system.md) | Invariant system design |
|
||||
| [`cli.md`](cli.md) | CLI quick reference for all v3.2.0 and v3.3.0 commands |
|
||||
|
||||
---
|
||||
|
||||
*Automated by CleverAgents Bot — Supervisor: Documentation | Agent: documentation-pool-supervisor*
|
||||
@@ -0,0 +1,229 @@
|
||||
# Subplans and Checkpoints
|
||||
|
||||
CleverAgents supports decomposing complex plans into coordinated **subplans** and
|
||||
capturing **checkpoints** of sandbox state for rollback. These features are part of
|
||||
the **v3.3.0** (Corrections + Subplans + Checkpoints) milestone.
|
||||
|
||||
For detailed API references see:
|
||||
|
||||
- [`reference/subplans.md`](reference/subplans.md) — Execution modes and merge strategies
|
||||
- [`reference/subplan_service.md`](reference/subplan_service.md) — Spawn workflow and lifecycle
|
||||
- [`reference/checkpointing.md`](reference/checkpointing.md) — Checkpoint and rollback
|
||||
|
||||
---
|
||||
|
||||
## Subplans
|
||||
|
||||
### Overview
|
||||
|
||||
A **subplan** is a child plan spawned from a parent plan during the Strategize phase.
|
||||
Subplans allow a parent plan to decompose work into coordinated child plans, each
|
||||
running in its own sandbox. Results are merged back into the parent plan using a
|
||||
configurable merge strategy.
|
||||
|
||||
Subplans are created when the Strategize actor records a `subplan_spawn` or
|
||||
`subplan_parallel_spawn` decision. The `SubplanService` then handles the spawn
|
||||
workflow: validating resource scopes, creating child plan statuses, and returning
|
||||
spawn metadata.
|
||||
|
||||
### Execution Modes
|
||||
|
||||
| Mode | Description |
|
||||
|------|-------------|
|
||||
| `sequential` | Execute one subplan at a time in order |
|
||||
| `parallel` | Execute concurrently (up to `max_parallel`, default 5) |
|
||||
| `dependency_ordered` | Respect DAG dependencies via topological sort |
|
||||
|
||||
**Sequential mode** stops on the first failure (even without `fail_fast`).
|
||||
|
||||
**Parallel mode** runs subplans concurrently. When `fail_fast` is enabled,
|
||||
remaining subplans are cancelled on first failure.
|
||||
|
||||
**Dependency-ordered mode** sorts subplans topologically. Independent subplans
|
||||
within the same wave run concurrently. Circular dependencies raise a `ValueError`.
|
||||
|
||||
### Merge Strategies
|
||||
|
||||
After subplans complete, their sandbox outputs are merged:
|
||||
|
||||
| Strategy | Description |
|
||||
|----------|-------------|
|
||||
| `git_three_way` | Three-way merge via `git merge-file` |
|
||||
| `sequential_apply` | Apply changes in completion order |
|
||||
| `fail_on_conflict` | Raise `MergeConflictError` on any conflict |
|
||||
| `last_wins` | Final subplan's output overwrites earlier ones |
|
||||
|
||||
### Configuration
|
||||
|
||||
```yaml
|
||||
subplan_config:
|
||||
execution_mode: parallel # sequential | parallel | dependency_ordered
|
||||
merge_strategy: git_three_way # git_three_way | sequential_apply | fail_on_conflict | last_wins
|
||||
max_parallel: 5 # 1-50, for parallel mode
|
||||
fail_fast: false # stop all on first failure
|
||||
timeout_per_subplan_seconds: ~ # optional per-subplan timeout
|
||||
retry_failed: true # auto-retry failed subplans
|
||||
max_retries: 2 # 0-5, max retry attempts
|
||||
```
|
||||
|
||||
### Failure Handling
|
||||
|
||||
- **`fail_fast`**: Stop all subplans on first failure (any mode).
|
||||
- **Retry**: Retriable errors (`TimeoutError`, `ValidationError`,
|
||||
`TemporaryResourceError`, `MergeConflictError`) are retried up to `max_retries`.
|
||||
- **Non-retriable**: `ConfigurationError`, `AuthenticationError`,
|
||||
`MissingResourceError`, `CircularDependencyError` are never retried.
|
||||
|
||||
### Spawn Validation
|
||||
|
||||
Before any child plan is created, the `SubplanService` validates:
|
||||
|
||||
1. All `target_resources` exist in the available resources set.
|
||||
2. A `merge_strategy` is defined on `SubplanConfig`.
|
||||
3. In `PARALLEL` mode, spawn count does not exceed `max_parallel`.
|
||||
4. Each entry has a non-empty `action_name`.
|
||||
5. Each entry's decision is `subplan_spawn` or `subplan_parallel_spawn`.
|
||||
|
||||
---
|
||||
|
||||
## Checkpoints
|
||||
|
||||
### Overview
|
||||
|
||||
A **checkpoint** is an immutable record of sandbox state at a point in time.
|
||||
Checkpoints allow operators to snapshot the sandbox during plan execution and
|
||||
restore it later — useful for recovering from mistakes, reverting tool side-effects,
|
||||
and supporting the decision-correction revert flow.
|
||||
|
||||
### Checkpoint Types
|
||||
|
||||
| Type | When Created |
|
||||
|------|-------------|
|
||||
| `pre_write` | Before a write-tool execution |
|
||||
| `post_step` | After a write-tool execution |
|
||||
| `manual` | Explicitly via `CheckpointService.create_checkpoint()` |
|
||||
|
||||
### Automatic Checkpoint Triggers (v3.8.0+)
|
||||
|
||||
The execution engine creates checkpoints automatically on four triggers:
|
||||
|
||||
| Trigger | When | Component |
|
||||
|---------|------|-----------|
|
||||
| `on_tool_write` | Before each write-tool execution | `ToolRunner` |
|
||||
| `on_tool_write_complete` | After each write-tool execution | `ToolRunner` |
|
||||
| `on_subplan_spawn` | Before first subplan execution attempt | `SubplanExecutionService` |
|
||||
| `on_error` | When the Execute phase fails | `PlanExecutor` |
|
||||
|
||||
Configure which triggers are active:
|
||||
|
||||
```toml
|
||||
[core.checkpoints]
|
||||
auto_create_on = ["on_tool_write", "on_tool_write_complete", "on_subplan_spawn", "on_error"]
|
||||
```
|
||||
|
||||
To disable all automatic checkpoints:
|
||||
|
||||
```toml
|
||||
[core.checkpoints]
|
||||
auto_create_on = []
|
||||
```
|
||||
|
||||
### Retention Policy
|
||||
|
||||
By default, up to **50 checkpoints** are kept per plan. When `auto_prune` is
|
||||
enabled (default: `true`) and the limit is exceeded, the oldest interior checkpoints
|
||||
are removed. The first (earliest) and most recent checkpoints are always preserved.
|
||||
|
||||
| Field | Default | Range |
|
||||
|-------|---------|-------|
|
||||
| `max_checkpoints` | 50 | 1–100 |
|
||||
| `auto_prune` | `true` | |
|
||||
|
||||
### Rollback to a Checkpoint
|
||||
|
||||
Use `agents plan rollback` to restore sandbox state to a previously captured checkpoint:
|
||||
|
||||
```bash
|
||||
# Rollback with confirmation prompt
|
||||
agents plan rollback 01HPLAN... 01HCHECKPOINT...
|
||||
|
||||
# Rollback without confirmation (for scripts)
|
||||
agents plan rollback --yes 01HPLAN... 01HCHECKPOINT...
|
||||
|
||||
# JSON output
|
||||
agents plan rollback --yes 01HPLAN... 01HCHECKPOINT... --format json
|
||||
```
|
||||
|
||||
**Guards:** Rollback is blocked if:
|
||||
|
||||
- The plan has already reached the `applied` terminal state.
|
||||
- The sandbox has been cleaned up.
|
||||
|
||||
**JSON output envelope:**
|
||||
|
||||
```json
|
||||
{
|
||||
"rollback_summary": {
|
||||
"plan_id": "...",
|
||||
"from_checkpoint_id": "...",
|
||||
"restored_files_count": 3
|
||||
},
|
||||
"changes_reverted": ["path/to/file1.py", "path/to/file2.py"],
|
||||
"impact": {
|
||||
"files_affected": 3
|
||||
},
|
||||
"post_rollback_state": {
|
||||
"active_checkpoint": "...",
|
||||
"plan_id": "..."
|
||||
},
|
||||
"timing": {
|
||||
"elapsed_seconds": 0.042
|
||||
},
|
||||
"messages": ["Rollback completed successfully."]
|
||||
}
|
||||
```
|
||||
|
||||
### Checkpoint Metadata
|
||||
|
||||
Each checkpoint stores structured metadata for auditability:
|
||||
|
||||
| Field | Description |
|
||||
|-------|-------------|
|
||||
| `checkpoint_id` | Unique ULID |
|
||||
| `plan_id` | The plan that owns this checkpoint |
|
||||
| `sandbox_ref` | Reference to sandbox state (e.g., git commit hash) |
|
||||
| `decision_id` | Optional decision ULID this checkpoint is aligned to |
|
||||
| `checkpoint_type` | `pre_write`, `post_step`, or `manual` |
|
||||
| `created_at` | UTC timestamp |
|
||||
| `metadata` | Audit metadata: reason, source tool, phase |
|
||||
|
||||
---
|
||||
|
||||
## Relationship Between Subplans and Checkpoints
|
||||
|
||||
Checkpoints and subplans work together in the execution engine:
|
||||
|
||||
1. Before the first subplan execution attempt, an `on_subplan_spawn` checkpoint
|
||||
is automatically created (if the trigger is enabled).
|
||||
2. This checkpoint can be used to roll back the entire parent plan's sandbox state
|
||||
if subplan execution fails catastrophically.
|
||||
3. The `CorrectionService` accepts an optional `checkpoint_service` parameter as
|
||||
an integration point: once wired, the correction revert flow will delegate
|
||||
sandbox restoration to the checkpoint rollback mechanism.
|
||||
|
||||
---
|
||||
|
||||
## Related References
|
||||
|
||||
| Document | Description |
|
||||
|----------|-------------|
|
||||
| [`reference/subplans.md`](reference/subplans.md) | Execution modes, merge strategies, and service API |
|
||||
| [`reference/subplan_service.md`](reference/subplan_service.md) | Spawn workflow, validation, and lifecycle |
|
||||
| [`reference/checkpointing.md`](reference/checkpointing.md) | Checkpoint model, rollback, and database schema |
|
||||
| [`reference/decision_correction.md`](reference/decision_correction.md) | Correction subsystem integration |
|
||||
| [`adr/ADR-015-sandbox-and-checkpoint.md`](adr/ADR-015-sandbox-and-checkpoint.md) | Architecture decision record |
|
||||
| [`cli.md`](cli.md) | CLI quick reference for all v3.2.0 and v3.3.0 commands |
|
||||
|
||||
---
|
||||
|
||||
*Automated by CleverAgents Bot — Supervisor: Documentation | Agent: documentation-pool-supervisor*
|
||||
Reference in New Issue
Block a user