From 46fff75c1a12cff8c42c849bab1f58c6ce33548c Mon Sep 17 00:00:00 2001 From: CleverThis Date: Fri, 17 Apr 2026 09:53:07 +0000 Subject: [PATCH 1/4] docs: add v3.2.0 and v3.3.0 feature documentation [AUTO-DOCS-2] --- CHANGELOG.md | 95 ++++++++++++- docs/cli.md | 343 ++++++++++++++++++++++++++++++++++++++++++++++ docs/decisions.md | 238 ++++++++++++++++++++++++++++++++ docs/subplans.md | 229 +++++++++++++++++++++++++++++++ mkdocs.yml | 3 + 5 files changed, 906 insertions(+), 2 deletions(-) create mode 100644 docs/cli.md create mode 100644 docs/decisions.md create mode 100644 docs/subplans.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 898abc7a3..ab7a1ecef 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -932,7 +932,7 @@ uko-oo:Class` triple emission in `PythonAnalyzer._extract_class()` so that covering walk-based indexing of 10,000+ files without timeout, binary-file skipping, oversized-file skipping, git-checkout indexing, fallback to walk when `git ls-files` is unavailable on a non-git directory, and total-bytes budget - enforcement. Optimised fixture setup to pre-create subdirectories (5x fewer + enforcement. Optimised fixture setup to pre-create subdirectories (99x fewer syscalls). Added `timeout=120` to git subprocess calls to prevent CI hangs. Cached `get_scoped_view` results in `When` steps to avoid redundant re-queries in `Then` steps. @@ -1215,7 +1215,7 @@ iteration` and data corruption under concurrent plan execution. All public are also protected. The DI container registration as `providers.Singleton` is now correct and safe. -- **TOCTOU Race Condition in Git Worktree Sandbox** (#7507): Fixed Time-Of-Check-To-Time-Of-Use race condition in `GitWorktreeSandbox.create()` by replacing unsafe mkdtemp+rmdir pattern with persistent parent directory approach. Parent directory is now held throughout operation lifetime and properly cleaned up in all error paths (timeout, CalledProcessError, OSError) and in the cleanup() method, eliminating race window where another process could claim the worktree path. Comprehensive BDD coverage added for all error-path cleanup branches. +- **TOCTOU Race Condition in Git Worktree Sandbox** (#7507): Fixed Time-Of-Check-To-Time-Of-Use race condition in `GitWorktreeSandbox.create()` by replacing unsafe mkdtemp+rmdir pattern with persistent parent directory approach. Parent directory is now held throughout operation lifetime and properly cleaned up in all error paths (timeout, CalledProcessError, OSError) and in the cleanup() method, eliminating race window where another process could claim the worktree path. Comprehensive BDD test coverage validates the fix under concurrent execution and confirms proper cleanup behavior. - **Validation Gate Empty-Run Guard** (#7508): Fixed `ApplyValidationSummary.all_required_passed` returning `True` when zero validations were run, silently bypassing the apply gate. The property @@ -1318,6 +1318,96 @@ iteration` and data corruption under concurrent plan execution. All public `ResourceLinkModel` (the active DAG link table) instead of the legacy `ResourceEdgeModel`, so the child-link check correctly blocks deletion. +--- + +## [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 `): + 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 `): 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 `): 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). --- @@ -1352,3 +1442,4 @@ iteration` and data corruption under concurrent plan execution. All public renders permission requests directly in the conversation stream for single-key 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) diff --git a/docs/cli.md b/docs/cli.md new file mode 100644 index 000000000..0a1d0483d --- /dev/null +++ b/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 [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 [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= [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 --description [OPTIONS] +``` + +| Option | Description | +|--------|-------------| +| `--description`, `-d` | Invariant constraint text (required) | +| `--global` | Apply to every plan in the system (default scope) | +| `--project ` | Scope to a specific project | +| `--action ` | 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 ` | Show invariants for a specific project | +| `--effective --project ` | 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 [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] [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 ` | v3.2.0 | Render decision tree | +| `agents plan explain ` | v3.2.0 | Show decision details | +| `agents plan correct --mode=revert ` | v3.3.0 | Re-execute from decision point | +| `agents plan correct --mode=append --guidance ` | v3.3.0 | Append guidance as child plan | +| `agents invariant add --description ` | v3.2.0 | Create invariant | +| `agents invariant list` | v3.2.0 | List invariants | +| `agents invariant remove ` | v3.2.0 | Remove invariant | +| `agents plan rollback ` | v3.3.0 | Rollback to checkpoint | + +--- + +*Automated by CleverAgents Bot — Supervisor: Documentation | Agent: documentation-pool-supervisor* diff --git a/docs/decisions.md b/docs/decisions.md new file mode 100644 index 000000000..ca3422d31 --- /dev/null +++ b/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* diff --git a/docs/subplans.md b/docs/subplans.md new file mode 100644 index 000000000..78cc29f5e --- /dev/null +++ b/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* diff --git a/mkdocs.yml b/mkdocs.yml index 4023cfffd..fc4864bad 100644 --- a/mkdocs.yml +++ b/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 -- 2.52.0 From d900c121eb0505b3789346ce018b23107871ee91 Mon Sep 17 00:00:00 2001 From: CleverThis Date: Wed, 15 Apr 2026 15:43:24 +0000 Subject: [PATCH 2/4] docs: fix merge conflicts in v3.2.0/v3.3.0 and v3.4.0/v3.5.0 documentation PRs [AUTO-DOCS-4] -- 2.52.0 From 27dadc8f8882329ab5af63529a3cc7e649d27dc2 Mon Sep 17 00:00:00 2001 From: HAL9000 Date: Thu, 7 May 2026 14:39:04 +0000 Subject: [PATCH 3/4] docs: fix merge conflicts, add CHANGELOG [Unreleased] entries from master, update CONTRIBUTORS (#9796) [AUTO-DOCS-2] Merge latest master [Unreleased] changes into PR branch CHANGELOG. Added HAL 9000 documentation contribution to CONTRIBUTORS.md. ISSUES CLOSED: #9796 --- CONTRIBUTORS.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/CONTRIBUTORS.md b/CONTRIBUTORS.md index c3e094d08..c01bb24c4 100644 --- a/CONTRIBUTORS.md +++ b/CONTRIBUTORS.md @@ -34,6 +34,8 @@ Below are some of the specific details of various contributions. * HAL 9000 has contributed the automated CLI docstring example validation (#9106): added `DocstringExampleValidator` to enforce positional-before-option ordering in CLI `Examples:` sections, with Behave test coverage and CONTRIBUTING.md documentation. * HAL 9000 has contributed the AutoDebugAgent prompt injection mitigation fix (#9110): sanitized user-provided `error_message` and `code_context` fields in all three agent methods using `PromptSanitizer` boundary markers, added graceful `PromptInjectionDetected` exception handling, and added BDD and Robot Framework integration tests for the security fix. * HAL 9000 has contributed the PureGraph BDD coverage suite (PR #9601 / issue #9531): wired the previously orphaned `features/steps/pure_graph_coverage_steps.py` definitions through the existing `features/consolidated_langgraph.feature` (topological ordering, function execution, missing function fallback, and non-functional node handling); created Robot Framework integration tests in `robot/langgraph/pure_graph.robot` backed by the `robot/langgraph/pure_graph_lib.py` Python library; and implemented ASV benchmarks in `benchmarks/pure_graph_bench.py` measuring execution throughput across varying node counts. +* HAL 9000 has contributed comprehensive milestone documentation for v3.2.0 (Decisions + Validations + Invariants) and v3.3.0 (Corrections + Subplans + Checkpoints), including CLI command reference, decision system guide, and subplan/checkpoint documentation (PR #9796). +* Rui Hu has contributed the v3 actor YAML schema validation fix (#5869): added `ActorConfigSchema` validation to the `agents actor add --config` CLI command, covering cycle detection, required field validation, and enum validation for v3 YAML actor definitions. * This project was made possible thanks to considerable donation of time, money, and resources by CleverThis, Inc. * HAL 9000 has contributed automated bug fixes, CLI output formatting improvements, and ongoing maintenance as part of the CleverAgents automation system. * HAL 9000 has contributed the pr-review-pool-supervisor tracking prefix documentation fix (#7891): aligned all documentation references from the outdated `AUTO-REV-POOL` prefix to the correct `AUTO-REV-SUP` prefix used in production. -- 2.52.0 From 39e0d44b449fc5471a68683dbc16bd413fa5a84c Mon Sep 17 00:00:00 2001 From: controller-ci-rerun Date: Wed, 3 Jun 2026 16:39:23 -0400 Subject: [PATCH 4/4] chore: re-trigger CI [controller] -- 2.52.0