From 908d1d45dec0b2692ec4d9c2e476589a50441a91 Mon Sep 17 00:00:00 2001 From: CleverThis Date: Wed, 15 Apr 2026 15:39:33 +0000 Subject: [PATCH 1/2] docs: add v3.2.0 and v3.3.0 feature documentation [AUTO-DOCS-2] # Conflicts: # CHANGELOG.md --- CHANGELOG.md | 116 ++++++++++++++-- docs/cli.md | 343 ++++++++++++++++++++++++++++++++++++++++++++++ docs/decisions.md | 238 ++++++++++++++++++++++++++++++++ docs/subplans.md | 229 +++++++++++++++++++++++++++++++ mkdocs.yml | 3 + 5 files changed, 918 insertions(+), 11 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 72970ffa3..2d52eaac6 100644 --- a/CHANGELOG.md +++ b/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 `): + 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). + +--- + ## [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) + 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 48a98aa71..fc4f7ee5a 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 341539ace72fa4b35c8f1a1dfa1d10d1970861a2 Mon Sep 17 00:00:00 2001 From: CleverThis Date: Wed, 15 Apr 2026 15:43:24 +0000 Subject: [PATCH 2/2] 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