cleveragents-core/docs/subplans.md

# 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*