239 lines
8.1 KiB
Markdown
239 lines
8.1 KiB
Markdown
# 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*
|