cleveragents/cleveragents-core
4
0
Fork 3
Code Issues 6.0k Pull Requests 115 Actions Packages Projects Releases Wiki Activity

docs(spec): document ReconciliationBlockedError and invariant reconciliation failure behavior #6004

Closed
HAL9000 wants to merge 1 commits from spec/document-reconciliation-blocked-error-5942 into master
pull from: spec/document-reconciliation-blocked-error-5942
merge into: cleveragents:master
Conversation 1 Commits 1 Files Changed 1
+18 -2
1 changed files with 18 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/specification.md
+18 -2
View File
@@ -19798,8 +19798,8 @@ The system collects, reconciles, and checks invariants:
<span style="color: magenta; font-weight: 600;">or</span> self.get_global_invariant_actor()
)
<span style="opacity: 0.7;"># 3. Reconcile: apply precedence (plan &gt; project &gt; global), resolve conflicts</span>
effective = reconciler.reconcile(raw, precedence=[<span style="color: #66cc66;">&#x27;plan&#x27;</span>, <span style="color: #66cc66;">&#x27;project&#x27;</span>, <span style="color: #66cc66;">&#x27;global&#x27;</span>])
<span style="opacity: 0.7;"># 3. Reconcile: apply precedence (plan &gt; action &gt; project &gt; global), resolve conflicts</span>
effective = reconciler.reconcile(raw, precedence=[<span style="color: #66cc66;">&#x27;plan&#x27;</span>, <span style="color: #66cc66;">&#x27;action&#x27;</span>, <span style="color: #66cc66;">&#x27;project&#x27;</span>, <span style="color: #66cc66;">&#x27;global&#x27;</span>])
<span style="color: magenta; font-weight: 600;">return</span> effective
<span style="color: magenta; font-weight: 600;">def</span> <span style="color: cyan; font-weight: 600;">collect_all_invariants</span>(self, plan):
@@ -19820,6 +19820,22 @@ The system collects, reconciles, and checks invariants:
<span style="color: magenta; font-weight: 600;">return</span> Success()
</code></pre></div>
#### Reconciliation Failure Behavior
When invariant reconciliation fails at a phase transition, the transition is **blocked** — the plan cannot proceed to the next phase until the invariants are corrected. The system raises a `ReconciliationBlockedError` and emits an `INVARIANT_VIOLATED` event on the event bus.
Reconciliation runs at the start of three phase transitions:
| Phase Transition | Method | Behavior on Failure |
|---|---|---|
| Strategize start | `start_strategize()` | Raises `ReconciliationBlockedError`; plan stays in `PENDING` state |
| Execute start | `execute_plan()` | Raises `ReconciliationBlockedError`; plan stays in `STRATEGIZED` state |
| Apply start | `apply_plan()` | Raises `ReconciliationBlockedError`; plan stays in `EXECUTED` state |
After a correction is applied (`agents plan correct`), reconciliation automatically re-runs via a `CORRECTION_APPLIED` event subscription (best-effort; does not block correction completion).
The built-in reconciliation actor is registered as `builtin/invariant-reconciliation`.
#### Layer 4: Predictive Error Prevention
The system learns from past failures: