cleveragents-core/docs/adr/ADR-006-plan-lifecycle.md

---
adr_number: 6
title: Plan Lifecycle
status_history:
- - '2026-02-16'
  - Proposed
  - Jeffrey Phillips Freeman
- - '2026-02-16'
  - Accepted
  - Jeffrey Phillips Freeman
tier: 2
authors:
- Jeffrey Phillips Freeman
superseded_by: null
related_adrs:
- number: 7
  title: Decision Tree and Correction
  relationship: Decisions are recorded at each phase transition in the plan lifecycle
- number: 8
  title: Resource System
  relationship: Resources are bound to plans and sandboxed per the lifecycle phases
- number: 9
  title: Project Model
  relationship: Plans operate within project scope and inherit project-level configuration
- number: 10
  title: Actor and Agent Architecture
  relationship: Actors drive phase transitions and execute plan steps
- number: 15
  title: Sandbox and Checkpoint
  relationship: Sandboxes are created per-plan and checkpoints track execution progress
- number: 16
  title: Invariant System
  relationship: Invariants are reconciled at Strategize entry and enforced throughout the lifecycle
- number: 17
  title: Automation Profiles
  relationship: Profiles control which phase transitions require human approval
- number: 33
  title: Decision Recording Protocol
  relationship: Defines how decisions are recorded during Strategize and Execute phases of the plan lifecycle
- number: 34
  title: Decision Tree Versioning and History
  relationship: Specifies how decision trees are versioned across plan lifecycle transitions
- number: 35
  title: Decision Tree Rollback and Replay
  relationship: Governs rollback mechanics during mid-phase corrections within the plan lifecycle
acceptance:
  votes_for:
  - voter: Jeffrey Phillips Freeman <Jeffrey.Freeman@CleverThis.com>
    comment: The four-phase lifecycle with reversion rules gives us the right balance of structure and recovery
  votes_against: []
  abstentions: []
---
## Context

CleverAgents needs a structured workflow that takes a user's intent (e.g., "increase test coverage to 85%") and transforms it into verified, applied changes across project resources. This workflow must support human review gates, autonomous execution, hierarchical decomposition into child plans, sandboxed execution with rollback, and correction of decisions at any point. A linear "run and hope" approach is insufficient — the system needs distinct phases with clear inputs, outputs, transition rules, and failure handling.

## Decision Drivers

- User intent (e.g., "increase test coverage to 85%") must be transformed into verified, applied changes through a structured workflow
- Must support human review gates at any transition point, controlled by automation profiles
- Sandboxed execution must ensure incomplete or incorrect work never contaminates real project resources
- Need hierarchical decomposition for tasks of arbitrary scale while keeping each plan's context bounded
- Correction of decisions at any point requires phase reversion rather than plan abandonment
- A linear "run and hope" approach is insufficient — distinct phases with clear inputs, outputs, and failure handling are required

## Decision

Every unit of work in CleverAgents follows a **four-phase lifecycle**: **Action → Strategize → Execute → Apply**. Each phase has defined inputs, outputs, processing states, and transition rules. The lifecycle supports forward progression, phase reversion (Execute → Strategize, Apply → Strategize), hierarchical decomposition via child plans, and automation profile-controlled autonomy at each transition.

## Design

### Phase Definitions

**Action** — A reusable plan template that defines work to be done (description, definition of done, actors, arguments, invariants) without being bound to any project. No significant processing occurs. When used via `agents plan use`, it spawns a new plan entity that enters Strategize. Actions with `reusable: true` (default) remain available after use; `reusable: false` actions are deleted after first use.

**Strategize** — The first active processing phase. Read-only. The strategy actor gathers context from project resources, collects applicable invariants (reconciled via the Invariant Reconciliation Actor as `invariant_enforced` decisions), and produces a strategy: a decision tree of approach choices, resource selections, and child plan blueprints (`subplan_spawn` / `subplan_parallel_spawn` decisions). No resource modification occurs.

**Execute** — Work happens in a sandboxed environment. The execution actor follows the strategy, invokes tools to modify resources in the sandbox, spawns child plans from `subplan_spawn` decisions, and creates checkpoints for rollback. Produces a reviewable changeset. Additional decisions may be created during execution, constrained by Strategize-phase decisions.

**Apply** — The controlled commit step. Merges the sandboxed changeset into real project resources. Handles diff review gates, conflict resolution, and audit logging. Validation runs during Execute, not during Apply — by the time Apply runs, all required validations have passed.

### Phase Transition Verbs

| Current Phase | CLI Verb | Next Phase |
|---|---|---|
| (none) | `create` | Action |
| Action | `use` | Strategize |
| Strategize | `execute` | Execute |
| Execute | `apply` | Apply |

There is no `strategize` command. The `use` verb transitions from Action to Strategize by design — "use" describes the user's intent of applying an action template to a project.

### Processing States Per Phase

**Action**: `available`, `archived`.

**Strategize / Execute**: `queued`, `processing`, `errored`, `complete`, `cancelled`.

**Apply**: `queued`, `processing`, `errored`, `applied` (terminal success), `constrained` (terminal — strategy constraints prevent completion), `cancelled`.

### Phase Reversion

Both Execute and Apply may revert to Strategize (never to any other phase):

**Execute → Strategize**: Triggered when the execution actor discovers that Strategize-phase constraints are too restrictive to complete the work. Rather than violating those constraints, the plan reverts so the strategy actor can adjust the decision tree. Controlled by the `delete_content` automation profile flag.

**Apply → Strategize**: Triggered when the changeset cannot be applied within the current strategy's constraints (merge conflicts, validation failures at apply time, resource state drift). The plan enters the `constrained` terminal state, then may revert either automatically or after manual approval. Controlled by the `access_network` flag.

### Plan Identity

Every plan carries: `plan_id` (ULID), `parent_plan_id` (nullable), `root_plan_id`, `attempt` (integer, increments on phase re-runs), `created_at`, `updated_at`, `completed_at`, and `created_by`.

### Plan Hierarchy

Plans are hierarchical. Child plans are full plans with their own lifecycles, decision trees, and sandboxes. Decisions about child plans are made during Strategize (`subplan_spawn`, `subplan_parallel_spawn`); actual spawning occurs during Execute. Child plans run sequentially (individual `subplan_spawn`) or concurrently (grouped under `subplan_parallel_spawn`). The parent plan merges results.

Child plan result merging depends on resource type: git-style merge for source code, transaction coordination for databases, pluggable strategies for other types.

### Hierarchical Decomposition

For large tasks, the system uses hierarchical decomposition — root plan → subsystem plans → module plans → file-level plans. At each level, only relevant context is loaded. The persistent decision graph enables reconstruction of why any particular change was made and what constraints apply from higher levels.

### Action Data Model

Actions carry: `name` (namespaced), `short_description`, `long_description`, `definition_of_done` (required, must be explicit and testable), `actors` (strategy, execution, estimation, invariant), `reusable` (boolean), `read_only` (boolean), `inputs_schema`, and `automation_profile`.

## Constraints

- Every unit of work must pass through all four phases in order. No phase may be skipped.
- The Strategize phase is strictly read-only. No resource modification is permitted.
- Execute-phase decisions must be constrained by Strategize-phase decisions. If constraints cannot be honored, the correct response is reversion, not violation.
- Validation runs during Execute, not Apply. Apply assumes all validations have passed.
- Child plan maximum nesting depth is controlled by `plan.max-child-depth` (default: 5).
- Plan concurrency is controlled by `plan.concurrency` (default: 4). Child plans count toward the parent's allocation, not the global limit.
- `definition_of_done` is required on every action and must be explicit and testable.

## Consequences

### Positive
- The phase separation enables human review at any transition point, controlled by automation profiles.
- Sandboxed execution ensures that incomplete or incorrect work never contaminates real project resources.
- Hierarchical decomposition enables tackling tasks of arbitrary scale while keeping each plan's context bounded.
- Phase reversion provides a structured recovery mechanism instead of plan abandonment.
- The persistent decision tree enables selective correction and replay without re-executing the entire plan.

### Negative
- Four phases add ceremony for simple tasks that could be done in a single step.
- Phase reversion creates complex state management, especially when child plans are involved.
- Hierarchical decomposition increases the total number of plans and decisions that must be tracked.

### Risks
- Deep plan hierarchies could exhaust resources or create coordination bottlenecks during merging.
- Phase reversion loops (Execute → Strategize → Execute → Strategize ...) must be bounded to prevent infinite cycling.

## Alternatives Considered

None — specification-driven requirement. The four-phase lifecycle with reversion, hierarchy, and automation-controlled transitions is the core orchestration model prescribed by the specification.

## Plan Resume Behavior

Plans that are interrupted (e.g., process shutdown) or fail mid-execution can
be resumed from their last checkpoint using ``agents plan resume <plan_id>``.

### Resume Eligibility

Only non-terminal plans can be resumed. Terminal states that block resume:

| State | Reason |
|-------|--------|
| ``applied`` | Plan has already been committed successfully |
| ``cancelled`` | Plan was explicitly cancelled |
| ``constrained`` | Plan cannot proceed within constraints |

Plans in ``errored``, ``processing``, ``queued``, or ``complete`` state within
the Strategize, Execute, or Apply phases are eligible for resume.

### Resume Metadata

Each plan tracks two resume-related fields:

- ``last_completed_step`` -- zero-based index of the last step that completed successfully (-1 if none).
- ``last_checkpoint_id`` -- ULID of the most recent ``ResumeCheckpoint``.

Checkpoints are recorded at each completed execution step and are tied to:

- A decision ID (from the strategy decision tree)
- A sandbox reference (for filesystem state)

### Resume Flow

1. **Validate** -- ``PlanResumeService.validate_eligibility()`` checks that the plan is not in a terminal state.
2. **Summarize** -- ``build_resume_summary()`` returns the phase, next step index, decision ID, and sandbox reference.
3. **Dry-run** -- ``plan resume --dry-run`` shows the summary without changing state.
4. **Live resume** -- Resets ``processing_state`` to ``PROCESSING`` (clearing any error), then the caller re-drives execution from step ``last_completed_step + 1``.

### Graceful Shutdown

When the system detects a shutdown signal, ``record_shutdown()`` persists the
current step index and marks the resume metadata as ``interrupted``. This
ensures that the next ``plan resume`` picks up exactly where execution stopped.

### Example

```
$ agents plan resume 01HGZ6FE0AQDYTR4BXEXAMPLE --dry-run
Resume Summary
  Plan ID: 01HGZ6FE0AQDYTR4BXEXAMPLE
  Phase: execute
  State: errored
  Next Step: 3 / 5
  Decision ID: DEC-003
  Checkpoint: 01HGZ6FE0AQDYTR4BXCHKPT03
  No state changes made (dry-run mode).

$ agents plan resume 01HGZ6FE0AQDYTR4BXEXAMPLE
Resume Summary
  Plan ID: 01HGZ6FE0AQDYTR4BXEXAMPLE
  Phase: execute
  State: processing
  Next Step: 3 / 5
  Plan resumed. Execution will continue from step 3.
```

### Error Cases

| Scenario | Error |
|----------|-------|
| Resume applied plan | ``PlanError: Plan ... is in terminal state 'applied' and cannot be resumed.`` |
| Resume cancelled plan | ``PlanError: Plan ... is in terminal state 'cancelled' and cannot be resumed.`` |
| Empty plan ID | ``ValidationError: plan_id must not be empty`` |

## Compliance

- **Lifecycle state machine tests**: Unit tests verify all valid phase transitions and reject invalid ones (e.g., Action → Execute without passing through Strategize).
- **Reversion boundary tests**: Tests verify that Execute-phase code cannot modify resources outside the sandbox and that reversion correctly preserves and transmits findings to the strategy actor.
- **BDD scenarios**: Behave feature files describe end-to-end plan lifecycle scenarios including hierarchical decomposition, parallel child plan execution, and phase reversion.
- **Automation profile integration tests**: Tests verify that each automation profile correctly gates the appropriate phase transitions.