docs: architecture corrections cycle 2 — plan revert/resume commands, correction_attempts DDL alignment
CI / benchmark-publish (pull_request) Has been skipped
CI / lint (pull_request) Failing after 39s
CI / helm (pull_request) Successful in 28s
CI / push-validation (pull_request) Successful in 29s
CI / build (pull_request) Successful in 3m20s
CI / quality (pull_request) Successful in 3m43s
CI / typecheck (pull_request) Successful in 4m2s
CI / security (pull_request) Successful in 4m9s
CI / coverage (pull_request) Has been skipped
CI / benchmark-regression (pull_request) Has been skipped
CI / integration_tests (pull_request) Failing after 4m11s
CI / e2e_tests (pull_request) Successful in 7m15s
CI / unit_tests (pull_request) Successful in 8m35s
CI / docker (pull_request) Has been skipped
CI / status-check (pull_request) Failing after 1s
CI / benchmark-publish (pull_request) Has been skipped
CI / lint (pull_request) Failing after 39s
CI / helm (pull_request) Successful in 28s
CI / push-validation (pull_request) Successful in 29s
CI / build (pull_request) Successful in 3m20s
CI / quality (pull_request) Successful in 3m43s
CI / typecheck (pull_request) Successful in 4m2s
CI / security (pull_request) Successful in 4m9s
CI / coverage (pull_request) Has been skipped
CI / benchmark-regression (pull_request) Has been skipped
CI / integration_tests (pull_request) Failing after 4m11s
CI / e2e_tests (pull_request) Successful in 7m15s
CI / unit_tests (pull_request) Successful in 8m35s
CI / docker (pull_request) Has been skipped
CI / status-check (pull_request) Failing after 1s
Add agents plan revert and agents plan resume to spec command reference (issue #4596) - Both commands exist in implementation but were absent from spec - agents plan revert: reverts plan to previous phase (strategize|execute) - agents plan resume: resumes plan from last checkpoint - Added to command synopsis and full documentation sections - Added comparison table distinguishing revert/resume/rollback/correct Align correction_attempts DDL between early and late spec sections (issue #4911) - Early DDL: updated PK from attempt_id to correction_attempt_id (matches implementation) - Early DDL: added mode and guidance fields (matches later DDL and implementation) - Both DDLs: added original_subtree_snapshot field for correction diff workflow - Implementation needs Alembic migration to add original_subtree_snapshot column
This commit is contained in:
+56
-4
@@ -344,6 +344,8 @@ The following standards are integrated into the architecture:
|
||||
<span style="color: cyan; font-weight: 600;">agents</span> plan artifacts <span style="color: #66cc66;"><PLAN_ID></span>
|
||||
<span style="color: cyan; font-weight: 600;">agents</span> plan prompt <span style="color: #66cc66;"><PLAN_ID></span> <span style="color: #66cc66;"><GUIDANCE></span>
|
||||
<span style="color: cyan; font-weight: 600;">agents</span> plan rollback [<span style="color: cyan;">--yes</span>|<span style="color: yellow;">-y</span>] <span style="color: #66cc66;"><PLAN_ID></span> <span style="color: #66cc66;"><CHECKPOINT_ID></span>
|
||||
<span style="color: cyan; font-weight: 600;">agents</span> plan revert [<span style="color: cyan;">--to-phase</span> (<span style="color: magenta;">strategize|execute</span>)] [<span style="color: cyan;">--reason</span> <span style="color: #66cc66;"><REASON></span>] [<span style="color: cyan;">--yes</span>|<span style="color: yellow;">-y</span>] <span style="color: #66cc66;"><PLAN_ID></span>
|
||||
<span style="color: cyan; font-weight: 600;">agents</span> plan resume [<span style="color: cyan;">--dry-run</span>] <span style="color: #66cc66;"><PLAN_ID></span>
|
||||
<span style="color: cyan; font-weight: 600;">agents</span> plan errors <span style="color: #66cc66;"><PLAN_ID></span>
|
||||
|
||||
<span style="color: cyan; font-weight: 600;">agents</span> action create <span style="color: cyan;">--config</span>|<span style="color: yellow;">-c</span> <span style="color: #66cc66;"><CFG_FILE></span>
|
||||
@@ -16210,6 +16212,53 @@ Provide additional guidance to a plan, typically when it is errored or awaiting
|
||||
- "Rollback complete"
|
||||
```
|
||||
|
||||
##### agents plan revert
|
||||
|
||||
<div class="highlight"><pre><code><span style="color: cyan; font-weight: 600;">agents</span> plan revert [<span style="color: cyan;">--to-phase</span> (<span style="color: magenta;">strategize|execute</span>)] [<span style="color: cyan;">--reason</span> <span style="color: #66cc66;"><REASON></span>] [<span style="color: cyan;">--yes</span>|<span style="color: yellow;">-y</span>] <span style="color: #66cc66;"><PLAN_ID></span></code></pre></div>
|
||||
|
||||
!!! 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>`: 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
|
||||
|
||||
<div class="highlight"><pre><code><span style="color: cyan; font-weight: 600;">agents</span> plan resume [<span style="color: cyan;">--dry-run</span>] <span style="color: #66cc66;"><PLAN_ID></span></code></pre></div>
|
||||
|
||||
**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>`: 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
|
||||
|
||||
<span style="opacity: 0.7;">-- Correction history</span>
|
||||
<span style="color: #5599ff; font-weight: 600;">CREATE</span> <span style="color: #5599ff; font-weight: 600;">TABLE</span> correction_attempts (
|
||||
attempt_id <span style="color: #5599ff; font-weight: 600;">TEXT</span> <span style="color: #5599ff; font-weight: 600;">PRIMARY</span> <span style="color: #5599ff; font-weight: 600;">KEY</span>, -- ULID
|
||||
correction_attempt_id <span style="color: #5599ff; font-weight: 600;">TEXT</span> <span style="color: #5599ff; font-weight: 600;">PRIMARY</span> <span style="color: #5599ff; font-weight: 600;">KEY</span>, -- ULID
|
||||
plan_id <span style="color: #5599ff; font-weight: 600;">TEXT</span> <span style="color: #5599ff; font-weight: 600;">NOT</span> <span style="color: #5599ff; font-weight: 600;">NULL</span>,
|
||||
original_decision_id <span style="color: #5599ff; font-weight: 600;">TEXT</span> <span style="color: #5599ff; font-weight: 600;">NOT</span> <span style="color: #5599ff; font-weight: 600;">NULL</span>,
|
||||
new_decision_id <span style="color: #5599ff; font-weight: 600;">TEXT</span>,
|
||||
original_subtree_snapshot <span style="color: #5599ff; font-weight: 600;">TEXT</span>, -- Reference to archived state
|
||||
correction_reason <span style="color: #5599ff; font-weight: 600;">TEXT</span>,
|
||||
status <span style="color: #5599ff; font-weight: 600;">TEXT</span> <span style="color: #5599ff; font-weight: 600;">NOT</span> <span style="color: #5599ff; font-weight: 600;">NULL</span>, -- <span style="color: #66cc66;">'pending'</span>, <span style="color: #66cc66;">'executing'</span>, <span style="color: #66cc66;">'completed'</span>, <span style="color: #66cc66;">'failed'</span>
|
||||
mode <span style="color: #5599ff; font-weight: 600;">TEXT</span> <span style="color: #5599ff; font-weight: 600;">NOT</span> <span style="color: #5599ff; font-weight: 600;">NULL</span>, -- revert|append
|
||||
guidance <span style="color: #5599ff; font-weight: 600;">TEXT</span> <span style="color: #5599ff; font-weight: 600;">NOT</span> <span style="color: #5599ff; font-weight: 600;">NULL</span>,
|
||||
original_subtree_snapshot <span style="color: #5599ff; font-weight: 600;">TEXT</span>, -- JSON reference to archived subtree state before correction
|
||||
archived_artifacts_path <span style="color: #5599ff; font-weight: 600;">TEXT</span>, -- filesystem path to archived originals
|
||||
state <span style="color: #5599ff; font-weight: 600;">TEXT</span> <span style="color: #5599ff; font-weight: 600;">NOT</span> <span style="color: #5599ff; font-weight: 600;">NULL</span>, -- <span style="color: #66cc66;">'pending'</span>, <span style="color: #66cc66;">'executing'</span>, <span style="color: #66cc66;">'complete'</span>, <span style="color: #66cc66;">'failed'</span>
|
||||
created_at <span style="color: #5599ff; font-weight: 600;">TEXT</span> <span style="color: #5599ff; font-weight: 600;">NOT</span> <span style="color: #5599ff; font-weight: 600;">NULL</span>,
|
||||
completed_at <span style="color: #5599ff; font-weight: 600;">TEXT</span>,
|
||||
|
||||
@@ -45835,6 +45886,7 @@ The relational database follows a normalized design with foreign key constraints
|
||||
new_decision_id <span style="color: #5599ff; font-weight: 600;">TEXT</span> <span style="color: #5599ff; font-weight: 600;">REFERENCES</span> decisions(decision_id),
|
||||
mode <span style="color: #5599ff; font-weight: 600;">TEXT</span> <span style="color: #5599ff; font-weight: 600;">NOT NULL</span>, <span style="opacity: 0.7;">-- revert|append</span>
|
||||
guidance <span style="color: #5599ff; font-weight: 600;">TEXT</span> <span style="color: #5599ff; font-weight: 600;">NOT NULL</span>,
|
||||
original_subtree_snapshot <span style="color: #5599ff; font-weight: 600;">TEXT</span>, <span style="opacity: 0.7;">-- JSON reference to archived subtree state before correction</span>
|
||||
archived_artifacts_path <span style="color: #5599ff; font-weight: 600;">TEXT</span>, <span style="opacity: 0.7;">-- filesystem path to archived originals</span>
|
||||
state <span style="color: #5599ff; font-weight: 600;">TEXT</span> <span style="color: #5599ff; font-weight: 600;">NOT NULL</span> <span style="color: #5599ff; font-weight: 600;">DEFAULT</span> 'pending', <span style="opacity: 0.7;">-- pending|executing|complete|failed</span>
|
||||
created_at <span style="color: #5599ff; font-weight: 600;">TEXT</span> <span style="color: #5599ff; font-weight: 600;">NOT NULL</span> <span style="color: #5599ff; font-weight: 600;">DEFAULT</span> (strftime('%Y-%m-%dT%H:%M:%f', 'now')),
|
||||
|
||||
Reference in New Issue
Block a user