CHANGELOG.md

@@ -60,7 +60,7 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
   LLM-generated changes via `git merge` from an isolated worktree branch
   instead of flat `shutil.copy2`.  Displays spec-aligned Apply Summary
   (plan ID, artifacts, insertions/deletions, project, timestamp), Sandbox
-  Cleanup panel, and `✓ OK Changes applied` footer.  Non-git projects fall
+  Cleanup panel, and `OK Changes applied` footer.  Non-git projects fall
   back to the original flat file copy.
 
 - **Context Hydration Fix** (#4454): Fixed `ContextFragment` metadata types
@@ -89,10 +89,10 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
   `new-issue-creator`, and `issue-state-updater` now delegate all label operations to this
   subagent.
 
-- **PR–Issue Label Synchronization**: PRs now inherit `Priority/`, `MoSCoW/`, `Points/`,
+- **PR-Issue Label Synchronization**: PRs now inherit `Priority/`, `MoSCoW/`, `Points/`,
   and `State/` labels from their associated issues at creation time
   (`pr-api-creator`). The `backlog-groomer` adds a continuous Pass 19 for ongoing
-  PR–issue label synchronization. The `issue-state-updater` syncs PR state labels whenever
+  PR-issue label synchronization. The `issue-state-updater` syncs PR state labels whenever
   issue states change.
 
 - **Automation Tracking Announcements**: Extended `automation-tracking-manager` with
@@ -106,14 +106,14 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
   the `*-pool-supervisor` naming pattern. New agents added: `pr-editor` (safe PR editing
   with description preservation), `pr-manager` (unified PR interface), and
   `pr-merge-pool-supervisor` (automated PR merging supervisor). Renamed:
-  `pr-api-creator` → `pr-creator`, `pr-checker` → `pr-ci-test-fixer`,
-  `pr-status-checker` → `pr-status-analyzer`, `pr-self-reviewer` → `pr-reviewer`,
-  `pr-fix-orchestrator` → `pr-fix-pool-supervisor`.
+  `pr-api-creator` -> `pr-creator`, `pr-checker` -> `pr-ci-test-fixer`,
+  `pr-status-checker` -> `pr-status-analyzer`, `pr-self-reviewer` -> `pr-reviewer`,
+  `pr-fix-orchestrator` -> `pr-fix-pool-supervisor`.
 
 - **Automated PR Merging** (`pr-merge-pool-supervisor`): New supervisor continuously
   monitors for merge-ready PRs and merges them automatically when all criteria are met
   (approvals, CI passing, no conflicts). Supports both formal reviews and comment-based
-  approvals (LGTM, ✅, "ready to merge", etc.).
+  approvals (LGTM, ready to merge, etc.).
 
 - **Implementation Worker Workflow Completion**: `implementation-worker` now implements
   work claiming protocols with conflict detection, comprehensive review feedback handling
@@ -165,7 +165,7 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 - **PR Review Policy**: Reduced PR review requirement from 2 approvals to 1. Self-approval
   is now permitted including for automated bot PRs. Approval can be a formal review OR an
-  approval comment (LGTM, Approved, ✅, "ready to merge").
+  approval comment (LGTM, Approved, ready to merge).
 
 - **Label Delegation Enforcement**: `automation-tracking-manager` now enforces delegation
   to `forgejo-label-manager` for all label operations, preventing "invalid label ID" errors
@@ -234,7 +234,7 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 - **SubplanExecutionService fail_fast cancellation** (#7582): Fixed a race condition where
   already-running parallel subplans were not cancelled when `fail_fast` fired. Previously,
   `Future.cancel()` only prevented queued futures from starting but had no effect on
-  in-flight futures that completed after `stop_flag` was set — their `COMPLETE` results
+  in-flight futures that completed after `stop_flag` was set -- their `COMPLETE` results
   were incorrectly included in the merge output. The fix adds a post-completion guard that
   overrides any non-`ERRORED`/non-`CANCELLED` result to `CANCELLED` when `stop_flag` is
   active, and clears the associated output to prevent it from entering the merge. Also
@@ -275,6 +275,97 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ---
 
+## [3.3.0] — Unreleased (Milestone: Corrections + Subplans + Checkpoints)
+
+> **Status:** In progress. Features documented in [`docs/subplans.md`](docs/subplans.md)
+> and [`docs/cli.md`](docs/cli.md).
+
+### Added
+
+- **Decision Correction — Revert Mode** (`agents plan correct --mode=revert`):
+  Invalidates a targeted decision and all its descendants via BFS traversal.
+  Associated artifacts are archived and affected child plans are rolled back.
+  The plan re-executes from the corrected decision point. Dry-run support via
+  `--dry-run` shows full impact report (affected decisions, files, child plans,
+  risk level) without making changes.
+
+- **Decision Correction — Append Mode** (`agents plan correct --mode=append`):
+  Preserves the original decision and spawns a new child plan rooted at the
+  target node. The child plan carries operator guidance (`--guidance`) and
+  produces additional decisions without disturbing the existing tree.
+
+- **Correction Attempt Tracking** (`CorrectionAttemptRecord`): Each execution
+  of a correction is tracked as an attempt record with full state lifecycle
+  (`pending -> executing -> complete/failed`). Multiple attempts may exist per
+  correction. See [`docs/reference/decision_correction.md`](docs/reference/decision_correction.md).
+
+- **Subplan Execution Service** (`SubplanExecutionService`): Executes child plans
+  in `sequential`, `parallel`, or `dependency_ordered` mode. Supports `fail_fast`,
+  per-subplan timeouts, and configurable retry policies.
+
+- **Subplan Merge Service** (`SubplanMergeService`): Merges child plan sandbox
+  outputs using `git_three_way`, `sequential_apply`, `fail_on_conflict`, or
+  `last_wins` strategies.
+
+- **Checkpoint and Rollback** (`agents plan rollback <plan_id> <checkpoint_id>`):
+  Operators can restore sandbox state to any previously captured checkpoint.
+  Rollback is blocked for plans in the `applied` terminal state or with cleaned-up
+  sandboxes. See [`docs/reference/checkpointing.md`](docs/reference/checkpointing.md).
+
+- **Automatic Checkpoint Triggers**: The execution engine now creates checkpoints
+  automatically on `on_tool_write`, `on_tool_write_complete`, `on_subplan_spawn`,
+  and `on_error` triggers. Configurable via `core.checkpoints.auto_create_on`.
+
+- **Documentation**: Added [`docs/subplans.md`](docs/subplans.md) (subplans and
+  checkpoints guide) and extended [`docs/cli.md`](docs/cli.md) with all v3.3.0
+  CLI commands.
+
+---
+
+## [3.2.0] — Unreleased (Milestone: Decisions + Validations + Invariants)
+
+> **Status:** In progress. Features documented in [`docs/decisions.md`](docs/decisions.md)
+> and [`docs/cli.md`](docs/cli.md).
+
+### Added
+
+- **Decision Recording**: Every choice point in a plan's lifecycle is recorded as
+  a persistent `Decision` node in a tree. Decisions capture the question, chosen
+  option, alternatives considered, confidence score, rationale, actor reasoning,
+  and a context snapshot for replay. 11 decision types cover all phases of plan
+  execution. See [`docs/reference/decision_model.md`](docs/reference/decision_model.md).
+
+- **Decision Service** (`DecisionService`): Application-layer interface for
+  recording decisions, retrieving decision histories, managing context snapshots,
+  and performing tree operations (BFS traversal, path-to-root). Supports both
+  in-memory and persisted modes. See
+  [`docs/reference/decision_service.md`](docs/reference/decision_service.md).
+
+- **Decision Tree Visualization** (`agents plan tree <plan_id>`): Renders the
+  decision tree for a plan as a visual hierarchy. Supports `--show-superseded`
+  to include corrected decisions and `--depth` to limit tree depth.
+
+- **Decision Explain** (`agents plan explain <decision_id>`): Shows detailed
+  information about a single decision node including alternatives, context
+  snapshot, and actor reasoning. Supports `--show-context` and `--show-reasoning`.
+
+- **Invariant System** (`agents invariant add/list/remove`): Natural-language
+  constraints that govern plan execution. Invariants are scoped to `GLOBAL`,
+  `PROJECT`, `ACTION`, or `PLAN` level with a defined precedence hierarchy.
+  The Invariant Reconciliation Actor evaluates all invariants at the start of
+  the Strategize phase and records `invariant_enforced` decisions.
+  See [`docs/reference/invariants.md`](docs/reference/invariants.md).
+
+- **Invariant Violation Model**: When an invariant is violated, an
+  `InvariantViolation` is created with `error`, `warning`, or `info` severity.
+  Reconciliation failures block phase transitions with `ReconciliationBlockedError`.
+
+- **Documentation**: Added [`docs/decisions.md`](docs/decisions.md) (decision
+  system guide) and [`docs/cli.md`](docs/cli.md) (v3.2.0 and v3.3.0 CLI
+  command reference).
+
+---
+
 ## [3.8.0] — 2026-04-05
 
 ### Added
@@ -286,13 +377,16 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
   `INVARIANT_VIOLATED` events.  Post-correction reconciliation runs
   via `CORRECTION_APPLIED` event subscription (best-effort).  Added
   `InvariantService` Singleton provider in the DI container.
-- **TUI — Shell danger detection**: The TUI shell mode (`!` prefix) now detects
+
+- **TUI -- Shell danger detection**: The TUI shell mode (`!` prefix) now detects
   dangerous command patterns before execution. A configurable pattern registry
   classifies commands by danger level (warning, critical) and surfaces a user
   warning overlay before proceeding. Patterns cover destructive filesystem
   operations, privilege escalation, network exfiltration, and more. (#1003)
 
-- **TUI — Permission Question Widget**: A new inline `PermissionQuestionWidget`
+- **TUI -- Permission Question Widget**: A new inline `PermissionQuestionWidget`
   renders permission requests directly in the conversation stream for single-file
   operations. Users can allow/reject with single-key shortcuts (`a`/`A`/`r`/`R`),
   navigate with arrow keys, confirm with `Enter`, or press `v` to open the full
+  permission dialog. (#1003)
+

docs/cli.md

@@ -0,0 +1,343 @@
+# CLI Reference — v3.2.0 and v3.3.0 Features
+
+This page provides a consolidated reference for the CLI commands introduced in the
+**v3.2.0** (Decisions + Validations + Invariants) and **v3.3.0** (Corrections +
+Subplans + Checkpoints) milestones.
+
+For the full plan command reference see [`reference/plan_cli.md`](reference/plan_cli.md).
+For invariant management see [`reference/invariants.md`](reference/invariants.md).
+For checkpoint and rollback details see [`reference/checkpointing.md`](reference/checkpointing.md).
+
+---
+
+## Decision Tree Commands (v3.2.0)
+
+### `agents plan tree`
+
+Renders the decision tree for a plan as a visual hierarchy.
+
+```bash
+agents plan tree <PLAN_ID> [OPTIONS]
+```
+
+| Option | Description |
+|--------|-------------|
+| `--format`, `-f` | Output format: `json`, `yaml`, `plain`, `table`, `rich` (default: `rich`) |
+| `--show-superseded` | Include superseded (corrected) decisions in the tree |
+| `--depth` | Maximum tree depth to render (`0` = unlimited, default: `0`) |
+
+**Examples:**
+
+```bash
+# Render the full decision tree in rich format
+agents plan tree 01HXYZ1234567890ABCDEFGH
+
+# Include superseded decisions (useful for auditing corrections)
+agents plan tree 01HXYZ1234567890ABCDEFGH --show-superseded
+
+# Limit depth for large plans
+agents plan tree 01HXYZ1234567890ABCDEFGH --depth 3
+
+# JSON output for scripting
+agents plan tree 01HXYZ1234567890ABCDEFGH --format json
+```
+
+> **Note:** Decision IDs displayed in the tree are full 26-character ULIDs (v3.8.0+),
+> which can be copied directly and used in `plan explain` or `plan correct` commands.
+
+See also: [`reference/plan_cli.md#agents-plan-tree`](reference/plan_cli.md#agents-plan-tree)
+
+---
+
+### `agents plan explain`
+
+Shows detailed information about a single decision node, including the question
+posed, the chosen option, alternatives considered, and optional context/reasoning.
+
+```bash
+agents plan explain <DECISION_ID> [OPTIONS]
+```
+
+| Option | Description |
+|--------|-------------|
+| `--format`, `-f` | Output format: `json`, `yaml`, `plain`, `table`, `rich` |
+| `--show-context` | Include the context snapshot captured at decision time |
+| `--show-reasoning` | Include the actor's raw LLM reasoning trace |
+
+**Examples:**
+
+```bash
+# Default rich output
+agents plan explain 01HXYZ1234567890ABCDEFGH
+
+# Full detail with context and reasoning
+agents plan explain 01HXYZ1234567890ABCDEFGH --show-context --show-reasoning
+
+# JSON for programmatic use
+agents plan explain 01HXYZ1234567890ABCDEFGH --format json --show-context
+```
+
+See also: [`reference/plan_cli.md#agents-plan-explain`](reference/plan_cli.md#agents-plan-explain)
+
+---
+
+## Decision Correction Commands (v3.3.0)
+
+### `agents plan correct`
+
+Re-executes a plan from a specific decision point using one of two correction modes.
+
+```bash
+agents plan correct --mode=<MODE> <DECISION_ID> [OPTIONS]
+```
+
+| Option | Description |
+|--------|-------------|
+| `--mode` | Correction mode: `revert` or `append` (required) |
+| `--guidance` | Operator guidance text for `append` mode (required for `append`) |
+| `--dry-run` | Preview the impact without making changes |
+| `--yes`, `-y` | Skip the confirmation prompt |
+| `--format`, `-f` | Output format: `json`, `yaml`, `plain`, `table`, `rich` |
+
+#### `--mode=revert`
+
+Invalidates the targeted decision and all its descendants (BFS traversal), then
+re-executes the plan from that decision point. Associated artifacts are archived
+and affected child plans are rolled back.
+
+```bash
+# Revert a decision and re-execute from that point
+agents plan correct --mode=revert 01HXYZ1234567890ABCDEFGH
+
+# Preview impact without making changes
+agents plan correct --mode=revert 01HXYZ1234567890ABCDEFGH --dry-run
+
+# Skip confirmation prompt
+agents plan correct --mode=revert 01HXYZ1234567890ABCDEFGH --yes
+```
+
+**What happens:**
+
+```
+          D1 (target) <-- revert starts here
+                |
+           +----+----+
+           D2        D3     <- all invalidated
+                     |
+                     D4     <- also invalidated
+```
+
+#### `--mode=append`
+
+Preserves the original decision and spawns a new child plan rooted at the target
+node. The child plan carries the operator's guidance and produces additional
+decisions without disturbing the existing tree.
+
+```bash
+# Append a correction with guidance
+agents plan correct --mode=append 01HXYZ1234567890ABCDEFGH \
+  --guidance "Use a safer migration strategy that avoids table locks"
+
+# Append with dry-run to preview
+agents plan correct --mode=append 01HXYZ1234567890ABCDEFGH \
+  --guidance "Prefer read-only operations where possible" \
+  --dry-run
+```
+
+**What happens:**
+
+```
+          D1 (target)
+               |
+        +------+----------+
+        D2 (original)  CP-new   <- child plan appended
+```
+
+**Risk levels** (based on affected decision count):
+
+| Affected Decisions | Risk Level |
+|--------------------|------------|
+| <= 3 | `low` |
+| 4 - 10 | `medium` |
+| > 10 | `high` |
+
+See also: [`reference/decision_correction.md`](reference/decision_correction.md)
+
+---
+
+## Invariant Management Commands (v3.2.0)
+
+Invariants are natural-language constraints that govern plan execution. They are
+evaluated by the Invariant Reconciliation Actor at the start of the Strategize phase.
+
+### `agents invariant add`
+
+Creates a new invariant constraint.
+
+```bash
+agents invariant add <NAME> --description <TEXT> [OPTIONS]
+```
+
+| Option | Description |
+|--------|-------------|
+| `--description`, `-d` | Invariant constraint text (required) |
+| `--global` | Apply to every plan in the system (default scope) |
+| `--project <NAME>` | Scope to a specific project |
+| `--action <NAME>` | Scope to a specific action template |
+| `--format`, `-f` | Output format |
+
+**Examples:**
+
+```bash
+# Global invariant (applies to all plans)
+agents invariant add no-prod-deletes \
+  --description "Never delete production data"
+
+# Project-scoped invariant
+agents invariant add api-test-coverage \
+  --description "All API changes need tests" \
+  --project myapp
+
+# Action-scoped invariant
+agents invariant add min-coverage \
+  --description "Minimum 80% test coverage" \
+  --action local/code-coverage
+```
+
+**Scope hierarchy** (highest to lowest precedence):
+
+| Scope | Description |
+|-------|-------------|
+| `PLAN` | Attached directly to a specific plan (via `plan use --invariant`) |
+| `PROJECT` | Applies to all plans targeting a project |
+| `GLOBAL` | Applies to every plan in the system |
+| `ACTION` | Defined in an action template; promoted to plan scope on `plan use` |
+
+---
+
+### `agents invariant list`
+
+Lists all invariants, with optional scope filtering.
+
+```bash
+agents invariant list [REGEX] [OPTIONS]
+```
+
+| Option | Description |
+|--------|-------------|
+| `--global` | Show only global invariants |
+| `--project <NAME>` | Show invariants for a specific project |
+| `--effective --project <NAME>` | Show merged effective set for a project |
+| `--format`, `-f` | Output format |
+
+**Examples:**
+
+```bash
+# List all invariants
+agents invariant list
+
+# Filter by scope
+agents invariant list --global
+agents invariant list --project myapp
+
+# Show the merged effective set (with precedence applied)
+agents invariant list --effective --project myapp
+
+# Filter by regex pattern
+agents invariant list "data.*safe"
+
+# JSON output
+agents invariant list --format json
+```
+
+---
+
+### `agents invariant remove`
+
+Removes an invariant by its ULID.
+
+```bash
+agents invariant remove <INVARIANT_ID> [OPTIONS]
+```
+
+| Option | Description |
+|--------|-------------|
+| `--yes`, `-y` | Skip the confirmation prompt |
+| `--format`, `-f` | Output format |
+
+**Examples:**
+
+```bash
+# Remove with confirmation prompt
+agents invariant remove 01HXYZ1234567890ABCDEFGH
+
+# Remove without confirmation (for scripts)
+agents invariant remove 01HXYZ1234567890ABCDEFGH --yes
+```
+
+See also: [`reference/invariants.md`](reference/invariants.md)
+
+---
+
+## Checkpoint and Rollback Commands (v3.3.0)
+
+### `agents plan rollback`
+
+Restores sandbox state to a previously captured checkpoint.
+
+```bash
+agents plan rollback [--yes|-y] <PLAN_ID> <CHECKPOINT_ID> [OPTIONS]
+```
+
+| Option | Description |
+|--------|-------------|
+| `--yes`, `-y` | Skip the interactive confirmation prompt |
+| `--format`, `-f` | Output format: `json`, `yaml`, `plain`, `table`, `rich` |
+
+**Examples:**
+
+```bash
+# Rollback with confirmation prompt
+agents plan rollback 01HPLAN... 01HCHECKPOINT...
+
+# Rollback without confirmation (for scripts)
+agents plan rollback --yes 01HPLAN... 01HCHECKPOINT...
+
+# JSON output for scripting
+agents plan rollback --yes 01HPLAN... 01HCHECKPOINT... --format json
+```
+
+**Guards:** Rollback is blocked if:
+
+- The plan has already reached the `applied` terminal state.
+- The sandbox has been cleaned up.
+
+**Automatic checkpoint triggers** (v3.8.0+):
+
+| Trigger | When |
+|---------|------|
+| `on_tool_write` | Before each write-tool execution |
+| `on_tool_write_complete` | After each write-tool execution |
+| `on_subplan_spawn` | Before first subplan execution attempt |
+| `on_error` | When the Execute phase fails |
+
+See also: [`reference/checkpointing.md`](reference/checkpointing.md)
+
+---
+
+## Quick Reference
+
+| Command | Milestone | Description |
+|---------|-----------|-------------|
+| `agents plan tree <plan_id>` | v3.2.0 | Render decision tree |
+| `agents plan explain <decision_id>` | v3.2.0 | Show decision details |
+| `agents plan correct --mode=revert <decision_id>` | v3.3.0 | Re-execute from decision point |
+| `agents plan correct --mode=append <decision_id> --guidance <text>` | v3.3.0 | Append guidance as child plan |
+| `agents invariant add <name> --description <desc>` | v3.2.0 | Create invariant |
+| `agents invariant list` | v3.2.0 | List invariants |
+| `agents invariant remove <name>` | v3.2.0 | Remove invariant |
+| `agents plan rollback <plan_id> <checkpoint_id>` | v3.3.0 | Rollback to checkpoint |
+
+---
+
+*Automated by CleverAgents Bot — Supervisor: Documentation | Agent: documentation-pool-supervisor*

docs/decisions.md

@@ -0,0 +1,238 @@
+# Decision System
+
+The CleverAgents decision system records every choice point in a plan's lifecycle
+as a persistent **Decision** node in a tree structure. This enables full auditability,
+targeted correction, and replay of plan execution.
+
+This page provides a high-level guide to the decision system. For detailed API
+references see:
+
+- [`reference/decision_model.md`](reference/decision_model.md) — Domain model
+- [`reference/decision_service.md`](reference/decision_service.md) — Service API
+- [`reference/decision_correction.md`](reference/decision_correction.md) — Correction subsystem
+- [`reference/invariants.md`](reference/invariants.md) — Invariant constraints
+
+---
+
+## Overview
+
+Every time an agent makes a meaningful choice during plan execution — selecting a
+strategy, choosing which files to modify, deciding how to handle an error — that
+choice is recorded as a **Decision**. Decisions form a tree rooted at the initial
+`prompt_definition` decision.
+
+```
+prompt_definition (root)
+├── invariant_enforced       <- constraints applied at start of Strategize
+├── strategy_choice          <- high-level approach chosen
+│   ├── implementation_choice
+│   │   ├── resource_selection
+│   │   └── tool_invocation
+│   └── subplan_spawn        <- decision to create a child plan
+└── strategy_choice
+```
+
+---
+
+## Decision Recording (v3.2.0)
+
+### What Gets Recorded
+
+Each decision captures:
+
+| Field | Description |
+|-------|-------------|
+| `decision_id` | Unique ULID identifier |
+| `plan_id` | The plan this decision belongs to |
+| `decision_type` | One of 11 types (see below) |
+| `question` | What question was being answered |
+| `chosen_option` | The option that was selected |
+| `alternatives_considered` | Other options that were evaluated |
+| `confidence_score` | Confidence in the choice (0.0–1.0) |
+| `rationale` | Human-readable explanation |
+| `actor_reasoning` | Raw LLM reasoning trace |
+| `context_snapshot` | Hash + reference to the context window at decision time |
+| `parent_decision_id` | Parent in the tree (None for root) |
+| `created_at` | UTC timestamp |
+
+### Decision Types
+
+| Type | Phase | Description |
+|------|-------|-------------|
+| `prompt_definition` | Strategize | Root decision — the plan prompt |
+| `invariant_enforced` | Strategize | An invariant constraint was applied |
+| `strategy_choice` | Strategize | High-level approach chosen |
+| `implementation_choice` | Execute | How to implement a specific task |
+| `resource_selection` | Execute | Which resources to read/modify |
+| `subplan_spawn` | Strategize | Decision to create a child plan |
+| `subplan_parallel_spawn` | Strategize | Spawn a group of child plans in parallel |
+| `tool_invocation` | Execute | Which skill/tool to use |
+| `error_recovery` | Execute | How to handle a failure |
+| `validation_response` | Execute | Response to a validation failure |
+| `user_intervention` | Any | User-provided guidance/correction |
+
+---
+
+## Tree Visualization (v3.2.0)
+
+Use `agents plan tree` to render the decision tree for any plan:
+
+```bash
+# Rich tree view (default)
+agents plan tree 01HXYZ1234567890ABCDEFGH
+
+# Include superseded decisions
+agents plan tree 01HXYZ1234567890ABCDEFGH --show-superseded
+
+# Limit depth
+agents plan tree 01HXYZ1234567890ABCDEFGH --depth 2
+```
+
+The **current tree** consists of all decisions where `superseded_by IS NULL`.
+Superseded decisions are hidden by default but can be shown with `--show-superseded`
+for auditing corrections.
+
+To inspect a specific decision:
+
+```bash
+agents plan explain 01HDECISION...
+agents plan explain 01HDECISION... --show-context --show-reasoning
+```
+
+---
+
+## Invariants (v3.2.0)
+
+Invariants are natural-language constraints that are enforced at the start of the
+Strategize phase. The Invariant Reconciliation Actor evaluates each invariant and
+records an `invariant_enforced` decision for each one.
+
+### Scope Hierarchy
+
+| Scope | Precedence | Description |
+|-------|-----------|-------------|
+| `PLAN` | Highest | Attached directly to a specific plan |
+| `PROJECT` | Medium | Applies to all plans targeting a project |
+| `GLOBAL` | Lowest | Applies to every plan in the system |
+| `ACTION` | Promoted | Defined in action template; promoted to plan scope on `plan use` |
+
+### Managing Invariants
+
+```bash
+# Add a global invariant
+agents invariant add no-prod-deletes \
+  --description "Never delete production data"
+
+# Add a project-scoped invariant
+agents invariant add api-tests \
+  --description "All API changes need tests" \
+  --project myapp
+
+# List all invariants
+agents invariant list
+
+# Show effective set for a project (with precedence applied)
+agents invariant list --effective --project myapp
+
+# Remove an invariant
+agents invariant remove 01HINVARIANT...
+```
+
+### Violation Handling
+
+When an invariant is violated during execution, an `InvariantViolation` is created
+with a severity of `error`, `warning`, or `info`. Reconciliation failures block the
+phase transition with `ReconciliationBlockedError` and emit `INVARIANT_VIOLATED` events.
+
+---
+
+## Correction Modes (v3.3.0)
+
+The correction subsystem allows operators to modify a plan's decision tree after
+execution. Two modes are supported:
+
+### Revert Mode
+
+Invalidates the targeted decision and every descendant (BFS traversal). Associated
+artifacts are archived and affected child plans are rolled back. The plan then
+re-executes from the corrected decision point.
+
+```bash
+# Preview impact
+agents plan correct --mode=revert 01HDECISION... --dry-run
+
+# Apply correction
+agents plan correct --mode=revert 01HDECISION...
+```
+
+### Append Mode
+
+Preserves the original decision and spawns a new child plan rooted at the target
+node. The child plan carries operator guidance and produces additional decisions
+without disturbing the existing tree.
+
+```bash
+agents plan correct --mode=append 01HDECISION... \
+  --guidance "Use a safer migration strategy that avoids table locks"
+```
+
+### Correction Lifecycle
+
+```
+PENDING -> ANALYZING -> EXECUTING -> APPLIED
+                                   -> FAILED
+         PENDING -> CANCELLED
+         ANALYZING -> CANCELLED
+```
+
+### Impact Analysis
+
+Before executing a correction, the system performs BFS impact analysis:
+
+| Affected Decisions | Risk Level |
+|--------------------|------------|
+| <= 3 | `low` |
+| 4 - 10 | `medium` |
+| > 10 | `high` |
+
+Use `--dry-run` to see the full impact report before committing.
+
+### Correction Attempts
+
+Each execution of a correction is tracked as a `CorrectionAttemptRecord`. Multiple
+attempts may exist for a single correction (e.g., if a first attempt fails and the
+operator retries). See [`reference/decision_correction.md`](reference/decision_correction.md)
+for the full schema.
+
+---
+
+## Correction Immutability
+
+Corrections never mutate existing decisions. Instead:
+
+1. A new `Decision` is created with `is_correction=True` and `corrects_decision_id`
+   pointing to the original.
+2. The original decision has its `superseded_by` field set to the new decision's ID.
+3. All downstream decisions of the original are also superseded.
+
+This preserves a complete audit trail of all decisions, including those that were
+later corrected.
+
+---
+
+## Related References
+
+| Document | Description |
+|----------|-------------|
+| [`reference/decision_model.md`](reference/decision_model.md) | Full domain model with all fields and validation rules |
+| [`reference/decision_service.md`](reference/decision_service.md) | Service API for recording and querying decisions |
+| [`reference/decision_correction.md`](reference/decision_correction.md) | Correction subsystem, modes, and attempt tracking |
+| [`reference/invariants.md`](reference/invariants.md) | Invariant scopes, enforcement, and violation model |
+| [`adr/ADR-007-decision-tree-and-correction.md`](adr/ADR-007-decision-tree-and-correction.md) | Architecture decision record |
+| [`adr/ADR-033-decision-recording-protocol.md`](adr/ADR-033-decision-recording-protocol.md) | Decision recording protocol |
+| [`adr/ADR-016-invariant-system.md`](adr/ADR-016-invariant-system.md) | Invariant system design |
+| [`cli.md`](cli.md) | CLI quick reference for all v3.2.0 and v3.3.0 commands |
+
+---
+
+*Automated by CleverAgents Bot — Supervisor: Documentation | Agent: documentation-pool-supervisor*

docs/subplans.md

@@ -0,0 +1,229 @@
+# Subplans and Checkpoints
+
+CleverAgents supports decomposing complex plans into coordinated **subplans** and
+capturing **checkpoints** of sandbox state for rollback. These features are part of
+the **v3.3.0** (Corrections + Subplans + Checkpoints) milestone.
+
+For detailed API references see:
+
+- [`reference/subplans.md`](reference/subplans.md) — Execution modes and merge strategies
+- [`reference/subplan_service.md`](reference/subplan_service.md) — Spawn workflow and lifecycle
+- [`reference/checkpointing.md`](reference/checkpointing.md) — Checkpoint and rollback
+
+---
+
+## Subplans
+
+### Overview
+
+A **subplan** is a child plan spawned from a parent plan during the Strategize phase.
+Subplans allow a parent plan to decompose work into coordinated child plans, each
+running in its own sandbox. Results are merged back into the parent plan using a
+configurable merge strategy.
+
+Subplans are created when the Strategize actor records a `subplan_spawn` or
+`subplan_parallel_spawn` decision. The `SubplanService` then handles the spawn
+workflow: validating resource scopes, creating child plan statuses, and returning
+spawn metadata.
+
+### Execution Modes
+
+| Mode | Description |
+|------|-------------|
+| `sequential` | Execute one subplan at a time in order |
+| `parallel` | Execute concurrently (up to `max_parallel`, default 5) |
+| `dependency_ordered` | Respect DAG dependencies via topological sort |
+
+**Sequential mode** stops on the first failure (even without `fail_fast`).
+
+**Parallel mode** runs subplans concurrently. When `fail_fast` is enabled,
+remaining subplans are cancelled on first failure.
+
+**Dependency-ordered mode** sorts subplans topologically. Independent subplans
+within the same wave run concurrently. Circular dependencies raise a `ValueError`.
+
+### Merge Strategies
+
+After subplans complete, their sandbox outputs are merged:
+
+| Strategy | Description |
+|----------|-------------|
+| `git_three_way` | Three-way merge via `git merge-file` |
+| `sequential_apply` | Apply changes in completion order |
+| `fail_on_conflict` | Raise `MergeConflictError` on any conflict |
+| `last_wins` | Final subplan's output overwrites earlier ones |
+
+### Configuration
+
+```yaml
+subplan_config:
+  execution_mode: parallel        # sequential | parallel | dependency_ordered
+  merge_strategy: git_three_way   # git_three_way | sequential_apply | fail_on_conflict | last_wins
+  max_parallel: 5                 # 1-50, for parallel mode
+  fail_fast: false                # stop all on first failure
+  timeout_per_subplan_seconds: ~  # optional per-subplan timeout
+  retry_failed: true              # auto-retry failed subplans
+  max_retries: 2                  # 0-5, max retry attempts
+```
+
+### Failure Handling
+
+- **`fail_fast`**: Stop all subplans on first failure (any mode).
+- **Retry**: Retriable errors (`TimeoutError`, `ValidationError`,
+  `TemporaryResourceError`, `MergeConflictError`) are retried up to `max_retries`.
+- **Non-retriable**: `ConfigurationError`, `AuthenticationError`,
+  `MissingResourceError`, `CircularDependencyError` are never retried.
+
+### Spawn Validation
+
+Before any child plan is created, the `SubplanService` validates:
+
+1. All `target_resources` exist in the available resources set.
+2. A `merge_strategy` is defined on `SubplanConfig`.
+3. In `PARALLEL` mode, spawn count does not exceed `max_parallel`.
+4. Each entry has a non-empty `action_name`.
+5. Each entry's decision is `subplan_spawn` or `subplan_parallel_spawn`.
+
+---
+
+## Checkpoints
+
+### Overview
+
+A **checkpoint** is an immutable record of sandbox state at a point in time.
+Checkpoints allow operators to snapshot the sandbox during plan execution and
+restore it later — useful for recovering from mistakes, reverting tool side-effects,
+and supporting the decision-correction revert flow.
+
+### Checkpoint Types
+
+| Type | When Created |
+|------|-------------|
+| `pre_write` | Before a write-tool execution |
+| `post_step` | After a write-tool execution |
+| `manual` | Explicitly via `CheckpointService.create_checkpoint()` |
+
+### Automatic Checkpoint Triggers (v3.8.0+)
+
+The execution engine creates checkpoints automatically on four triggers:
+
+| Trigger | When | Component |
+|---------|------|-----------|
+| `on_tool_write` | Before each write-tool execution | `ToolRunner` |
+| `on_tool_write_complete` | After each write-tool execution | `ToolRunner` |
+| `on_subplan_spawn` | Before first subplan execution attempt | `SubplanExecutionService` |
+| `on_error` | When the Execute phase fails | `PlanExecutor` |
+
+Configure which triggers are active:
+
+```toml
+[core.checkpoints]
+auto_create_on = ["on_tool_write", "on_tool_write_complete", "on_subplan_spawn", "on_error"]
+```
+
+To disable all automatic checkpoints:
+
+```toml
+[core.checkpoints]
+auto_create_on = []
+```
+
+### Retention Policy
+
+By default, up to **50 checkpoints** are kept per plan. When `auto_prune` is
+enabled (default: `true`) and the limit is exceeded, the oldest interior checkpoints
+are removed. The first (earliest) and most recent checkpoints are always preserved.
+
+| Field | Default | Range |
+|-------|---------|-------|
+| `max_checkpoints` | 50 | 1–100 |
+| `auto_prune` | `true` | |
+
+### Rollback to a Checkpoint
+
+Use `agents plan rollback` to restore sandbox state to a previously captured checkpoint:
+
+```bash
+# Rollback with confirmation prompt
+agents plan rollback 01HPLAN... 01HCHECKPOINT...
+
+# Rollback without confirmation (for scripts)
+agents plan rollback --yes 01HPLAN... 01HCHECKPOINT...
+
+# JSON output
+agents plan rollback --yes 01HPLAN... 01HCHECKPOINT... --format json
+```
+
+**Guards:** Rollback is blocked if:
+
+- The plan has already reached the `applied` terminal state.
+- The sandbox has been cleaned up.
+
+**JSON output envelope:**
+
+```json
+{
+  "rollback_summary": {
+    "plan_id": "...",
+    "from_checkpoint_id": "...",
+    "restored_files_count": 3
+  },
+  "changes_reverted": ["path/to/file1.py", "path/to/file2.py"],
+  "impact": {
+    "files_affected": 3
+  },
+  "post_rollback_state": {
+    "active_checkpoint": "...",
+    "plan_id": "..."
+  },
+  "timing": {
+    "elapsed_seconds": 0.042
+  },
+  "messages": ["Rollback completed successfully."]
+}
+```
+
+### Checkpoint Metadata
+
+Each checkpoint stores structured metadata for auditability:
+
+| Field | Description |
+|-------|-------------|
+| `checkpoint_id` | Unique ULID |
+| `plan_id` | The plan that owns this checkpoint |
+| `sandbox_ref` | Reference to sandbox state (e.g., git commit hash) |
+| `decision_id` | Optional decision ULID this checkpoint is aligned to |
+| `checkpoint_type` | `pre_write`, `post_step`, or `manual` |
+| `created_at` | UTC timestamp |
+| `metadata` | Audit metadata: reason, source tool, phase |
+
+---
+
+## Relationship Between Subplans and Checkpoints
+
+Checkpoints and subplans work together in the execution engine:
+
+1. Before the first subplan execution attempt, an `on_subplan_spawn` checkpoint
+   is automatically created (if the trigger is enabled).
+2. This checkpoint can be used to roll back the entire parent plan's sandbox state
+   if subplan execution fails catastrophically.
+3. The `CorrectionService` accepts an optional `checkpoint_service` parameter as
+   an integration point: once wired, the correction revert flow will delegate
+   sandbox restoration to the checkpoint rollback mechanism.
+
+---
+
+## Related References
+
+| Document | Description |
+|----------|-------------|
+| [`reference/subplans.md`](reference/subplans.md) | Execution modes, merge strategies, and service API |
+| [`reference/subplan_service.md`](reference/subplan_service.md) | Spawn workflow, validation, and lifecycle |
+| [`reference/checkpointing.md`](reference/checkpointing.md) | Checkpoint model, rollback, and database schema |
+| [`reference/decision_correction.md`](reference/decision_correction.md) | Correction subsystem integration |
+| [`adr/ADR-015-sandbox-and-checkpoint.md`](adr/ADR-015-sandbox-and-checkpoint.md) | Architecture decision record |
+| [`cli.md`](cli.md) | CLI quick reference for all v3.2.0 and v3.3.0 commands |
+
+---
+
+*Automated by CleverAgents Bot — Supervisor: Documentation | Agent: documentation-pool-supervisor*

mkdocs.yml

@@ -11,6 +11,9 @@ site_dir: build/site
 nav:
   - Specification: specification.md
   - Architecture: architecture.md
+  - CLI Reference (v3.2.0/v3.3.0): cli.md
+  - Decision System: decisions.md
+  - Subplans & Checkpoints: subplans.md
   - API Reference:
     - Overview: api/index.md
     - Core Utilities: api/core.md