From bbbd39c6eec153ce80b90bda2c64ade2f73857d3 Mon Sep 17 00:00:00 2001 From: CleverThis Date: Thu, 9 Apr 2026 14:10:08 +0000 Subject: [PATCH] docs(spec): document ReconciliationBlockedError and invariant reconciliation failure behavior at phase transitions Adds documentation for the reconciliation failure behavior that was implemented in PR #5614 but not reflected in the specification: - ReconciliationBlockedError blocks phase transitions when invariants fail - INVARIANT_VIOLATED event emitted on reconciliation failure - Reconciliation runs at Strategize, Execute, and Apply phase starts - CORRECTION_APPLIED event triggers automatic re-reconciliation - builtin/invariant-reconciliation actor name documented ISSUES CLOSED: #5942 --- docs/specification.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/docs/specification.md b/docs/specification.md index 4accaad8b..f66dc71a3 100644 --- a/docs/specification.md +++ b/docs/specification.md @@ -19746,6 +19746,18 @@ The lookup order is: plan → project → global config. The first Invariant Rec Each effective invariant is then recorded as an `invariant_enforced` decision in the plan's decision tree. This makes invariants visible, auditable, and correctable through the standard decision correction mechanism. +**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: + +- **Strategize start** (`start_strategize()`) — reconciles all applicable invariants before strategy decisions are recorded +- **Execute start** (`execute_plan()`) — re-checks invariants before execution begins +- **Apply start** (`apply_plan()`) — re-checks invariants before changes are applied to the project + +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). This allows the plan to resume if the correction resolves the invariant violation. + +The built-in reconciliation actor is registered as `builtin/invariant-reconciliation`. It is used when no custom invariant actor is configured at the plan, project, or global level. + **Non-overridable global invariants**: A global invariant may be marked `non_overridable: true`. When set, this invariant takes precedence over all lower-scope invariants regardless of the normal precedence chain -- even plan-level invariants cannot override it. This is intended for system-wide safety constraints that must never be relaxed (e.g., "Never commit secrets to version control"). Non-overridable invariants are set via `agents invariant add --global --non-overridable ""`. The `non_overridable` flag is only meaningful on `GLOBAL`-scoped invariants; it is ignored on project, action, and plan invariants. **Child plan inheritance**: When a top-level plan spawns child plans, the parent's effective invariant view (already reconciled) is passed down to each child plan. Child plans do not re-run reconciliation — they inherit the parent's resolved view. -- 2.52.0