forked from cleveragents/cleveragents-core
79 lines
2.7 KiB
Markdown
79 lines
2.7 KiB
Markdown
# 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:
|
|
|
|
```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.
|