forked from HAL9000/cleveragents-core
freemo
33a5adcfee
Adds CorrectionRequest, CorrectionResult, CorrectionMode, CorrectionPatch, CorrectionDryRunReport, CorrectionNotFoundError, and CorrectionConflictError domain models. Implements CorrectionService with BFS-based revert (marks decisions as rolled back and restores via inverse changes) and append mode (spawns a child correction plan). Includes request_correction() with dry-run support and dispatch_correction() convenience method. 33 Behave scenarios, 8 Robot smoke tests, ASV benchmark suite, and reference documentation. Ref: Day-14 Rebaseline – M4.2 Decision-correction flows [Jeff]
100 lines
3.3 KiB
Markdown
100 lines
3.3 KiB
Markdown
# Decision Correction Reference
|
||
|
||
## Overview
|
||
|
||
The correction subsystem allows operators to modify a plan's decision tree
|
||
after execution by either **reverting** a subtree of decisions or
|
||
**appending** new decisions as a child plan.
|
||
|
||
## Correction Modes
|
||
|
||
### Revert
|
||
|
||
Invalidates the targeted decision and every descendant reachable via
|
||
BFS traversal. Associated artifacts are archived and affected child
|
||
plans are rolled back.
|
||
|
||
```text
|
||
┌─── D1 (target) ◄── revert starts here
|
||
│ │
|
||
│ ┌──┴──┐
|
||
│ D2 D3 ← all invalidated
|
||
│ │
|
||
│ D4 ← also invalidated
|
||
```
|
||
|
||
### 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.
|
||
|
||
```text
|
||
D1 (target)
|
||
│
|
||
┌──┴──────────┐
|
||
D2 (original) CP-new ← child plan appended
|
||
```
|
||
|
||
## Impact Analysis — BFS Algorithm
|
||
|
||
Impact analysis uses breadth-first search over the decision tree's
|
||
adjacency list (parent → children mapping):
|
||
|
||
```python
|
||
from collections import deque
|
||
|
||
def compute_affected_subtree(target_id, tree):
|
||
affected = []
|
||
queue = deque([target_id])
|
||
while queue:
|
||
node = queue.popleft()
|
||
affected.append(node)
|
||
queue.extend(tree.get(node, []))
|
||
return affected
|
||
```
|
||
|
||
### Risk Classification
|
||
|
||
| Affected Count | Risk Level |
|
||
|----------------|------------|
|
||
| ≤ 3 | low |
|
||
| 4 – 10 | medium |
|
||
| > 10 | high |
|
||
|
||
## Dry-Run Output
|
||
|
||
A dry-run report contains:
|
||
|
||
- **impact** — Full `CorrectionImpact` with affected decisions, files,
|
||
child plans, estimated cost, and risk level.
|
||
- **decisions_to_invalidate** — Decision IDs that *would* be marked
|
||
invalid (revert mode only).
|
||
- **child_plans_to_rollback** — Child plans that *would* be rolled back.
|
||
- **estimated_recompute_time_seconds** — Wall-clock estimate.
|
||
- **warnings** — Human-readable cautions (e.g. high risk).
|
||
|
||
## Status Lifecycle
|
||
|
||
```text
|
||
PENDING → ANALYZING → EXECUTING → APPLIED
|
||
→ FAILED
|
||
PENDING → CANCELLED
|
||
ANALYZING → CANCELLED
|
||
```
|
||
|
||
## Service API
|
||
|
||
| Method | Description |
|
||
|-----------------------------|-----------------------------------------------|
|
||
| `request_correction()` | Create a new correction request |
|
||
| `analyze_impact()` | BFS impact analysis on the decision tree |
|
||
| `generate_dry_run_report()` | Full report without side effects |
|
||
| `execute_revert()` | Invalidate subtree + archive artifacts |
|
||
| `execute_append()` | Spawn child plan preserving original decision |
|
||
| `execute_correction()` | Dispatch to revert or append based on mode |
|
||
| `get_correction()` | Retrieve a correction by ID |
|
||
| `list_corrections()` | List corrections (optional plan_id filter) |
|
||
| `list_attempts()` | List execution attempts for a correction |
|
||
| `cancel_correction()` | Cancel a pending/analyzing correction |
|