diff --git a/docs/specification.md b/docs/specification.md index ee078196a..591d09d43 100644 --- a/docs/specification.md +++ b/docs/specification.md @@ -344,6 +344,8 @@ The following standards are integrated into the architecture: agents plan artifacts <PLAN_ID> agents plan prompt <PLAN_ID> <GUIDANCE> agents plan rollback [--yes|-y] <PLAN_ID> <CHECKPOINT_ID> +agents plan revert [--to-phase (strategize|execute)] [--reason <REASON>] [--yes|-y] <PLAN_ID> +agents plan resume [--dry-run] <PLAN_ID> agents plan errors <PLAN_ID> agents action create --config|-c <CFG_FILE> @@ -16210,6 +16212,53 @@ Provide additional guidance to a plan, typically when it is errored or awaiting - "Rollback complete" ``` +##### agents plan revert + +
agents plan revert [--to-phase (strategize|execute)] [--reason <REASON>] [--yes|-y] <PLAN_ID>
+ +!!! danger "Destructive Operation" + Revert a plan to a previous phase. All work done in phases after the target phase is discarded — decisions, tool calls, and sandbox changes are rolled back. This is a coarser-grained operation than `agents plan correct` (which targets a specific decision) or `agents plan rollback` (which restores a checkpoint). + +**Purpose** +Revert a plan back to a previous phase so it can re-run from that phase. Use when you want to re-run the entire strategy or execution phase, not just correct a specific decision. The plan returns to the `queued` state in the target phase, ready to re-execute. + +**Arguments** + +- ``: Plan ID to revert. +- `--to-phase PHASE`: Target phase to revert to. Accepted values: `strategize` (default), `execute`. Reverting to `strategize` discards all Execute-phase work and re-runs strategy. Reverting to `execute` discards Execute-phase work but preserves the Strategize decision tree. +- `--reason REASON`: Optional reason for the reversion (stored in the plan's audit log). +- `--yes`: Skip confirmation prompt. + +**Relationship to other recovery commands** + +| Command | Scope | Use When | +|---------|-------|----------| +| `agents plan correct` | Single decision | You want to change a specific decision and recompute its subtree | +| `agents plan revert` | Entire phase | You want to re-run an entire phase from scratch | +| `agents plan rollback` | Checkpoint | You want to restore the sandbox to a specific saved state | +| `agents plan resume` | Last checkpoint | You want to continue a paused/errored plan from where it left off | + +--- + +##### agents plan resume + +
agents plan resume [--dry-run] <PLAN_ID>
+ +**Purpose** +Resume a plan from its last checkpoint. Use when a plan has errored or been paused and you want to continue execution from the most recent saved state. Unlike `agents plan prompt` (which provides guidance to the actor for the next step), `agents plan resume` performs checkpoint-based resumption — it restores the sandbox to the last checkpoint and re-queues the plan for execution. + +**Arguments** + +- ``: Plan ID to resume. +- `--dry-run`: Show what would be resumed without actually resuming. Displays the last checkpoint, the plan state, and the estimated work remaining. + +**When to use `agents plan resume` vs `agents plan prompt`** + +- Use `agents plan resume` when the plan errored or was paused and you want to continue from the last checkpoint without providing new guidance. +- Use `agents plan prompt` when you want to provide new guidance or instructions to the actor for the next step, without restoring a checkpoint. + +--- + #### agents action !!! info "Purpose" @@ -18892,13 +18941,15 @@ The `record_decision` tool accepts the decision type, question, chosen option, a -- Correction history CREATE TABLE correction_attempts ( - attempt_id TEXT PRIMARY KEY, -- ULID + correction_attempt_id TEXT PRIMARY KEY, -- ULID plan_id TEXT NOT NULL, original_decision_id TEXT NOT NULL, new_decision_id TEXT, - original_subtree_snapshot TEXT, -- Reference to archived state - correction_reason TEXT, - status TEXT NOT NULL, -- 'pending', 'executing', 'completed', 'failed' + mode TEXT NOT NULL, -- revert|append + guidance TEXT NOT NULL, + original_subtree_snapshot TEXT, -- JSON reference to archived subtree state before correction + archived_artifacts_path TEXT, -- filesystem path to archived originals + state TEXT NOT NULL, -- 'pending', 'executing', 'complete', 'failed' created_at TEXT NOT NULL, completed_at TEXT, @@ -45835,6 +45886,7 @@ The relational database follows a normalized design with foreign key constraints new_decision_id TEXT REFERENCES decisions(decision_id), mode TEXT NOT NULL, -- revert|append guidance TEXT NOT NULL, + original_subtree_snapshot TEXT, -- JSON reference to archived subtree state before correction archived_artifacts_path TEXT, -- filesystem path to archived originals state TEXT NOT NULL DEFAULT 'pending', -- pending|executing|complete|failed created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%f', 'now')),