cleveragents-core/docs/reference/phase_reversion.md

Phase Reversion State Machine

Phase reversion allows plans to return to an earlier lifecycle phase when the current strategy proves unworkable. This enables adaptive re-planning without discarding accumulated context.

Reversion Paths

Source Phase	Target Phase	Trigger
Execute	Strategize	Validation failures block apply; constraints too restrictive
Apply (constrained)	Strategize	Cannot proceed within current strategy constraints

Automation Profile Thresholds

Automatic reversion is gated by the plan's resolved AutomationProfile:

Threshold	Controls
auto_reversion_from_apply	Auto-revert when Apply is constrained. < 1.0 = automatic, 1.0 = manual only
auto_strategy_revision	Auto-revert from Execute to Strategize. < 1.0 = automatic, 1.0 = manual only

Built-in profile defaults:

Profile	auto_reversion_from_apply	auto_strategy_revision
manual	1.0 (never auto)	1.0
review	1.0	1.0
trusted	1.0	1.0
auto	1.0	0.0
ci	0.0 (always auto)	0.0
full-auto	0.0	0.0

Loop Guard

Every plan tracks a reversion_count field. Each reversion increments this counter. The maximum number of reversions per plan execution is 3 (Plan.MAX_REVERSIONS). Once this limit is reached, both automatic and manual reversions are blocked.

This prevents infinite strategize-execute-revert cycles when the underlying problem cannot be resolved through re-planning alone.

Decision Recording

Each reversion is recorded as a reversion decision in the plan's decisions list with the following fields:

Field	Type	Description
type	str	Always "reversion"
source_phase	str	Phase the plan was in before reversion
target_phase	str	Phase the plan reverted to
reason	str	Human-readable reason for the reversion
timestamp	str	ISO 8601 timestamp
reversion_number	int	1-based reversion counter

Manual Reversion

Plans can be manually reverted via the CLI:

agents plan revert <plan_id> --to-phase strategize --reason "constraints too strict"

Manual reversion is subject to the same loop guard (max 3 reversions) but ignores automation profile thresholds.

State Reset on Reversion

When a plan is reverted:

1. The phase is set to the target phase.
2. The processing_state is reset to QUEUED.
3. The error_message is cleared.
4. The reversion_count is incremented.
5. The updated_at timestamp is refreshed.
6. Context and sandbox state are preserved.