cleveragents/cleveragents-core

Fork 3

Proposal: update specification — invariant reconciliation auto-invocation at all phase transitions #3123

New issue

Closed

opened 2026-04-05 06:34:59 +00:00 by freemo · 1 comment

freemo commented

2026-04-05 06:34:59 +00:00

Owner

Spec Update Proposal

What Changed in the Implementation

Merged PR: #1205 — feat(plan): wire invariant reconciliation actor auto-invocation
Commit: a0c7f5188e75e93714b1319d9da4d28717c5dfa4

PR #1205 wired the InvariantReconciliationActor into PlanLifecycleService so that invariant reconciliation runs automatically at every phase transition, not just at the start of Strategize. Specifically:

start_strategize() — after preflight guardrails, before PROCESSING state
execute_plan() — after estimation/error patterns, before Execute phase
apply_plan() — after state validation, before Apply transition
Post-correction — subscribes to CORRECTION_APPLIED events and re-runs reconciliation (best-effort, failures logged but not re-raised)

A new exception class ReconciliationBlockedError was introduced. Unlike estimation (which is informational-only), a reconciliation failure blocks the phase transition and raises this error, surfacing invariant violations immediately.

The InvariantService is now an optional dependency on PlanLifecycleService (injected via DI container as a Singleton). Reconciliation is skipped when plan.invariant_actor is None or "__optional__".

What Spec Sections Need Updating

1. Glossary — Invariant definition (line 92)

Current text:

Reconciled by the Invariant Reconciliation Actor at the start of Strategize; recorded as invariant_enforced decisions that propagate to child plans.

Proposed text:

Reconciled by the Invariant Reconciliation Actor automatically at each phase transition (Strategize, Execute, and Apply); recorded as invariant_enforced decisions that propagate to child plans. Reconciliation failure blocks the phase transition (ReconciliationBlockedError). Post-correction reconciliation is re-run as a best-effort operation after CORRECTION_APPLIED events.

2. Plan Actors section (line 18892)

Current text:

invariant_actor (Invariant Reconciliation Actor) — optional; resolves invariant conflicts when the plan enters Strategize. Lookup falls back to project, then global config.

Proposed text:

invariant_actor (Invariant Reconciliation Actor) — optional; resolves invariant conflicts automatically at each phase transition (Strategize, Execute, Apply). A reconciliation failure blocks the transition (ReconciliationBlockedError). Post-correction reconciliation is re-run best-effort after CORRECTION_APPLIED events. Lookup falls back to project, then global config.

3. Invariant view calculation section (line 19614)

Current text:

Invariant view calculation: When an action is used and a plan enters the Strategize phase, the Invariant Reconciliation Actor computes the effective invariant view by:

Proposed text:

Invariant view calculation: The Invariant Reconciliation Actor computes the effective invariant view automatically at each phase transition (Strategize, Execute, and Apply). A reconciliation failure raises ReconciliationBlockedError and blocks the transition. Post-correction reconciliation is re-run as a best-effort operation after CORRECTION_APPLIED events (failures are logged but do not reverse the correction). The actor computes the effective invariant view by:

4. `agents plan use` flow (line 18980)

Current text:

The Invariant Reconciliation Actor computes the effective invariant view (resolving conflicts using plan > project > global precedence)

Proposed text:

The Invariant Reconciliation Actor computes the effective invariant view (resolving conflicts using plan > project > global precedence) — this reconciliation also runs automatically before Execute and Apply phase transitions

5. `PlanLifecycleService` exceptions — add `ReconciliationBlockedError`

The spec should document ReconciliationBlockedError alongside the other PlanLifecycleService exceptions (InvalidPhaseTransitionError, ActionNotAvailableError, PlanNotReadyError).

Rationale

The implementation discovered that running reconciliation only at Strategize was insufficient — invariants can be violated by changes that occur between phases (e.g., new invariants added after Strategize but before Execute). Running reconciliation at every phase transition ensures invariants are always enforced before any processing begins. This is a genuine improvement over the spec's original design.

The post-correction reconciliation (via CORRECTION_APPLIED event subscription) is also an improvement: corrections can introduce new invariant violations, and re-checking after correction catches these immediately.

Scope

Sections affected:

Glossary → Invariant definition (line 92)
Plan Actors section (line 18892)
Invariant view calculation section (line 19614)
agents plan use flow (line 18980)
PlanLifecycleService exceptions documentation (new entry for ReconciliationBlockedError)

Automated by CleverAgents Bot
Supervisor: Spec Evolution | Agent: ca-spec-updater

## Spec Update Proposal ### What Changed in the Implementation **Merged PR**: #1205 — `feat(plan): wire invariant reconciliation actor auto-invocation` **Commit**: `a0c7f5188e75e93714b1319d9da4d28717c5dfa4` PR #1205 wired the `InvariantReconciliationActor` into `PlanLifecycleService` so that invariant reconciliation runs **automatically at every phase transition**, not just at the start of Strategize. Specifically: 1. **`start_strategize()`** — after preflight guardrails, before PROCESSING state 2. **`execute_plan()`** — after estimation/error patterns, before Execute phase 3. **`apply_plan()`** — after state validation, before Apply transition 4. **Post-correction** — subscribes to `CORRECTION_APPLIED` events and re-runs reconciliation (best-effort, failures logged but not re-raised) A new exception class `ReconciliationBlockedError` was introduced. Unlike estimation (which is informational-only), a reconciliation failure **blocks** the phase transition and raises this error, surfacing invariant violations immediately. The `InvariantService` is now an optional dependency on `PlanLifecycleService` (injected via DI container as a Singleton). Reconciliation is skipped when `plan.invariant_actor` is `None` or `"__optional__"`. ### What Spec Sections Need Updating #### 1. Glossary — Invariant definition (line 92) **Current text**: > Reconciled by the Invariant Reconciliation Actor at the start of Strategize; recorded as `invariant_enforced` decisions that propagate to child plans. **Proposed text**: > Reconciled by the Invariant Reconciliation Actor automatically at each phase transition (Strategize, Execute, and Apply); recorded as `invariant_enforced` decisions that propagate to child plans. Reconciliation failure blocks the phase transition (`ReconciliationBlockedError`). Post-correction reconciliation is re-run as a best-effort operation after `CORRECTION_APPLIED` events. #### 2. Plan Actors section (line 18892) **Current text**: > * **invariant_actor** (Invariant Reconciliation Actor) — optional; resolves invariant conflicts when the plan enters Strategize. Lookup falls back to project, then global config. **Proposed text**: > * **invariant_actor** (Invariant Reconciliation Actor) — optional; resolves invariant conflicts automatically at each phase transition (Strategize, Execute, Apply). A reconciliation failure blocks the transition (`ReconciliationBlockedError`). Post-correction reconciliation is re-run best-effort after `CORRECTION_APPLIED` events. Lookup falls back to project, then global config. #### 3. Invariant view calculation section (line 19614) **Current text**: > **Invariant view calculation**: When an action is used and a plan enters the Strategize phase, the Invariant Reconciliation Actor computes the effective invariant view by: **Proposed text**: > **Invariant view calculation**: The Invariant Reconciliation Actor computes the effective invariant view automatically at each phase transition (Strategize, Execute, and Apply). A reconciliation failure raises `ReconciliationBlockedError` and blocks the transition. Post-correction reconciliation is re-run as a best-effort operation after `CORRECTION_APPLIED` events (failures are logged but do not reverse the correction). The actor computes the effective invariant view by: #### 4. `agents plan use` flow (line 18980) **Current text**: > 5. The **Invariant Reconciliation Actor** computes the effective invariant view (resolving conflicts using plan > project > global precedence) **Proposed text**: > 5. The **Invariant Reconciliation Actor** computes the effective invariant view (resolving conflicts using plan > project > global precedence) — this reconciliation also runs automatically before Execute and Apply phase transitions #### 5. `PlanLifecycleService` exceptions — add `ReconciliationBlockedError` The spec should document `ReconciliationBlockedError` alongside the other `PlanLifecycleService` exceptions (`InvalidPhaseTransitionError`, `ActionNotAvailableError`, `PlanNotReadyError`). ### Rationale The implementation discovered that running reconciliation only at Strategize was insufficient — invariants can be violated by changes that occur between phases (e.g., new invariants added after Strategize but before Execute). Running reconciliation at every phase transition ensures invariants are always enforced before any processing begins. This is a genuine improvement over the spec's original design. The post-correction reconciliation (via `CORRECTION_APPLIED` event subscription) is also an improvement: corrections can introduce new invariant violations, and re-checking after correction catches these immediately. ### Scope Sections affected: - Glossary → Invariant definition (line 92) - Plan Actors section (line 18892) - Invariant view calculation section (line 19614) - `agents plan use` flow (line 18980) - `PlanLifecycleService` exceptions documentation (new entry for `ReconciliationBlockedError`) --- **Automated by CleverAgents Bot** Supervisor: Spec Evolution | Agent: ca-spec-updater

freemo referenced this issue

2026-04-05 06:35:58 +00:00

Task: Spec Updater session state — 2026-04-05 #3110

freemo referenced this issue

2026-04-05 06:38:04 +00:00

[CA-AUTO] Spec Updater — Session Tracker — 2026-04-05 #3129

freemo commented

2026-04-05 06:38:57 +00:00

Author

Owner

Closing as duplicate of #3121 — both proposals cover the same spec change (invariant reconciliation auto-invocation at all phase transitions triggered by PR #1205). Issue #3121 is the canonical proposal and will be tracked going forward.

Automated by CleverAgents Bot
Supervisor: Spec Evolution | Agent: ca-spec-updater

freemo closed this issue

2026-04-05 06:39:18 +00:00

freemo referenced this issue

2026-04-05 06:39:49 +00:00

[CA-AUTO] Spec Updater — Session Tracker — 2026-04-05 #3129

freemo referenced this issue

2026-04-05 06:56:06 +00:00

Task: Spec Updater session state — 2026-04-05 #3110

freemo referenced this issue

2026-04-05 10:07:21 +00:00

[CA-AUTO] Backlog Groomer — Session Tracker — groomer-1 — 2026-04-05 #3182