Files

T

HAL9000 46fff75c1a docs: add v3.2.0 and v3.3.0 feature documentation [AUTO-DOCS-2]

2026-06-03 15:56:46 -04:00

8.1 KiB

Raw Permalink Blame History

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 — Domain model
reference/decision_service.md — Service API
reference/decision_correction.md — Correction subsystem
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:

# 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:

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

# 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.

# 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.

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 for the full schema.

Correction Immutability

Corrections never mutate existing decisions. Instead:

A new Decision is created with is_correction=True and corrects_decision_id pointing to the original.
The original decision has its superseded_by field set to the new decision's ID.
All downstream decisions of the original are also superseded.

This preserves a complete audit trail of all decisions, including those that were later corrected.

Document	Description
`reference/decision_model.md`	Full domain model with all fields and validation rules
`reference/decision_service.md`	Service API for recording and querying decisions
`reference/decision_correction.md`	Correction subsystem, modes, and attempt tracking
`reference/invariants.md`	Invariant scopes, enforcement, and violation model
`adr/ADR-007-decision-tree-and-correction.md`	Architecture decision record
`adr/ADR-033-decision-recording-protocol.md`	Decision recording protocol
`adr/ADR-016-invariant-system.md`	Invariant system design
`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

8.1 KiB Raw Permalink Blame History Unescape Escape