# 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 (see spec § Automatable Tasks for field naming) |
|-----------|----------|
| `access_network` | Auto-revert when Apply is constrained. `< 1.0` = automatic, `1.0` = manual only |
| `delete_content` | Auto-revert from Execute to Strategize. `< 1.0` = automatic, `1.0` = manual only |

Built-in profile defaults:

| Profile | `access_network` | `delete_content` |
|---------|---------------------------|------------------------|
| `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:

```bash
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.