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

adr_number, title, status_history, tier, authors, superseded_by, related_adrs, acceptance

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

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.