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