1 changed files with 145 additions and 0 deletions
@@ -47095,3 +47095,148 @@ These architectural invariants must be maintained across all milestones:
 8. **BDD tests**: All unit-level tests expressed as Behave/Gherkin scenarios. No xUnit-style tests.
 9. **File size limit**: No source file exceeds 500 lines. Split into modules if approaching limit.
 10. **Atomic commits**: One logical change per commit. No mixed concerns.
+
+---
+
+## Checkpoint System (v3.3.0)
+
+### Overview
+
+The Checkpoint System enables rollback to previous plan states. Checkpoints are created automatically at key points during plan execution (before subplan spawning, after each phase transition) and can be created manually by users. Users can roll back a plan to any checkpoint using `agents plan rollback`.
+
+### Module Boundaries
+
+- **Module**: `cleveragents.checkpoints`
+- **Layer**: Domain
+- **Responsibilities**:
+  - Creating checkpoint snapshots of plan state
+  - Persisting checkpoint data to storage
+  - Restoring plan state from a checkpoint
+  - Managing checkpoint lifecycle (creation, listing, deletion)
+- **Public Interfaces**:
+  - `CheckpointRepository` — CRUD for checkpoint entities (domain repository interface)
+  - `CheckpointCreator` — creates checkpoint snapshots
+  - `CheckpointRestorer` — restores plan state from a checkpoint
+- **Forbidden Dependencies**: Must not import from `cleveragents.cli` or `cleveragents.tui`
+
+### Data Models
+
+#### Checkpoint Entity
+
+```python
+@dataclass
+class Checkpoint:
+    id: UUID
+    plan_id: UUID
+    alias: Optional[str]  # Human-readable name (e.g., "before-refactor")
+    trigger: Literal["automatic", "manual"]
+    trigger_event: str  # e.g., "before_subplan_spawn", "phase_transition", "user_request"
+    plan_state_snapshot: dict  # Full serialized plan state at checkpoint time
+    decision_tree_snapshot: list[dict]  # Decision tree at checkpoint time
+    subplan_states: list[dict]  # All subplan states at checkpoint time
+    created_at: datetime
+    metadata: dict
+```
+
+### Database Schema
+
+```sql
+CREATE TABLE checkpoints (
+    id UUID PRIMARY KEY,
+    plan_id UUID NOT NULL REFERENCES plans(id) ON DELETE CASCADE,
+    alias VARCHAR(255),
+    trigger VARCHAR(20) NOT NULL CHECK (trigger IN ('automatic', 'manual')),
+    trigger_event VARCHAR(100) NOT NULL,
+    plan_state_snapshot JSONB NOT NULL,
+    decision_tree_snapshot JSONB NOT NULL,
+    subplan_states JSONB NOT NULL DEFAULT '[]',
+    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    metadata JSONB NOT NULL DEFAULT '{}'
+);
+
+CREATE INDEX idx_checkpoints_plan_id ON checkpoints(plan_id);
+CREATE INDEX idx_checkpoints_created_at ON checkpoints(plan_id, created_at DESC);
+CREATE UNIQUE INDEX idx_checkpoints_alias ON checkpoints(plan_id, alias)
+    WHERE alias IS NOT NULL;
+```
+
+### Automatic Checkpoint Triggers
+
+Checkpoints are automatically created at these events:
+
+| Event | Trigger Name | Description |
+|---|---|---|
+| Before subplan spawn | `before_subplan_spawn` | Before a batch of subplans is spawned |
+| After Strategize phase | `after_strategize` | After the Strategize phase completes |
+| After Execute phase | `after_execute` | After the Execute phase completes |
+| Before Apply phase | `before_apply` | Before changes are applied to the workspace |
+| Subplan completion | `subplan_complete` | After each subplan completes |
+
+### CLI Interface Specification
+
+#### `agents plan rollback <plan-id> [--checkpoint <checkpoint-id>] [--alias <alias>]`
+
+- Rolls back a plan to a specific checkpoint
+- If no checkpoint specified, rolls back to the most recent automatic checkpoint
+- Required: `<plan-id>`
+- Optional: `--checkpoint <checkpoint-id>` or `--alias <alias>` (mutually exclusive)
+- Optional: `--dry-run` — shows what would be restored without executing
+- Optional: `--yes` — skip confirmation prompt
+- Output: Confirmation with checkpoint details and what was restored
+
+#### `agents plan checkpoint list <plan-id>`
+
+- Lists all checkpoints for a plan
+- Optional: `--format table|json`
+- Output: Table with columns: ID (short), Alias, Trigger, Event, Created
+
+#### `agents plan checkpoint create <plan-id> [--alias <alias>]`
+
+- Manually creates a checkpoint for a plan
+- Optional: `--alias <alias>` — human-readable name for the checkpoint
+- Output: Confirmation with checkpoint ID
+
+#### `agents plan checkpoint delete <checkpoint-id>`
+
+- Deletes a checkpoint
+- Requires confirmation unless `--yes` flag provided
+- Output: Confirmation message
+
+### Rollback Algorithm
+
+1. Retrieve the target checkpoint from `CheckpointRepository`
+2. Validate that the checkpoint belongs to the specified plan
+3. Restore `plan_state_snapshot` to the plan record
+4. Mark all decisions created after the checkpoint as `superseded`
+5. Restore subplan states from `subplan_states`
+6. Cancel any currently running subplans
+7. Update plan status to reflect the rolled-back state
+8. Create a new checkpoint marking the rollback event
+
+### Integration Points
+
+| Integration | Direction | Description |
+|---|---|---|
+| Plan Executor | Called by | Executor creates automatic checkpoints at trigger events |
+| Subplan System | Calls | Checkpoint includes all subplan states |
+| Decision Recording | Calls | Decisions after rollback point are marked superseded |
+| CLI | Called by | `agents plan rollback` and `agents plan checkpoint` commands |
+
+### Error Handling
+
+- `CheckpointNotFoundError(checkpoint_id)` — checkpoint does not exist
+- `CheckpointPlanMismatchError(checkpoint_id, plan_id)` — checkpoint belongs to different plan
+- `CheckpointRestoreError(checkpoint_id, reason)` — restore operation failed
+- `CheckpointAliasConflictError(plan_id, alias)` — alias already exists for this plan
+
+### Cross-Cutting Concerns
+
+- **Storage**: Checkpoint snapshots may be large; consider compression for `plan_state_snapshot`
+- **Retention**: Automatic checkpoints older than 30 days are pruned (configurable)
+- **Logging**: All checkpoint operations logged at INFO level
+- **Performance**: Checkpoint creation must complete within 200ms
+
+---
+**Automated by CleverAgents Bot**
+Supervisor: Architecture | Agent: architecture-pool-supervisor
+Worker: [AUTO-ARCH-7]