cleveragents/cleveragents-core

Fork 3

feat(actor): implement built-in invariant reconciliation actor #549

New issue

Closed

opened 2026-03-04 01:02:40 +00:00 by freemo · 1 comment

freemo commented

2026-03-04 01:02:40 +00:00

Owner

Metadata

Field	Value
Type	Feature
Priority	High
MoSCoW	Should Have
Points	5
Milestone	v3.5.0
Assignee	freemo
Parent Epic	#374 (Legendary: Actors, Skills & Tool Execution)
Depends On	None (invariant infrastructure exists)

Background

The specification (§ Core Concepts > Invariants, line 92; § Strategize Phase, lines 18421+) describes a built-in Invariant Reconciliation Actor that runs at the start of the Strategize phase to reconcile invariants from multiple scopes:

Global invariants — project-wide constraints (e.g., "never delete production data")
Project invariants — from project configuration
Action invariants — from the user's action definition
Plan invariants — inherited from parent plans

The reconciliation actor:

Collects invariants from all 4 scopes
Detects conflicts between scopes (e.g., action invariant contradicts global invariant)
Records invariant_enforced decisions for each active invariant
Produces a reconciled invariant set that subsequent actors must respect

Current state: No code reference to InvariantReconciliation or reconciliation_actor found in codebase. Invariant models exist but no actor performs the reconciliation step.

Acceptance Criteria

InvariantReconciliationActor exists as a built-in actor (YAML or code-defined).
Actor runs automatically at the start of Strategize phase.
Collects invariants from global, project, action, and plan scopes.
Detects and reports scope conflicts with clear diagnostic messages.
Records invariant_enforced decision for each active invariant.
Produces a reconciled InvariantSet available to subsequent actors.
Conflict resolution strategy: higher specificity wins (plan > action > project > global) unless global invariant is marked non_overridable.

Subtasks

1. Design

Design invariant scope collection flow
Design conflict detection and resolution algorithm
Design invariant_enforced decision format

2. Implementation

Create InvariantReconciliationActor class
Implement multi-scope invariant collection
Implement conflict detection
Implement conflict resolution with specificity rules
Implement invariant_enforced decision recording
Register as built-in actor that auto-runs in Strategize

3. Testing

Unit test: single-scope invariants (no conflicts)
Unit test: multi-scope with compatible invariants
Unit test: conflicting invariants resolved by specificity
Unit test: non_overridable global invariant blocks override
Integration test: reconciliation → subsequent actor respects invariants

4. Documentation

Actor behavior documentation
Invariant scope priority documentation

5. Integration

Wire into Strategize phase execution order
Verify compatibility with existing invariant models

6. Observability

Log reconciliation results (invariant count per scope, conflicts detected)
Log invariant_enforced decisions

7. Security

non_overridable invariants cannot be bypassed by lower scopes

Definition of Done

All acceptance criteria met
All subtask checkboxes checked
Tests pass in CI
Code reviewed and approved

## Metadata | Field | Value | |-------|-------| | **Type** | Feature | | **Priority** | High | | **MoSCoW** | Should Have | | **Points** | 5 | | **Milestone** | v3.5.0 | | **Assignee** | freemo | | **Parent Epic** | #374 (Legendary: Actors, Skills & Tool Execution) | | **Depends On** | None (invariant infrastructure exists) | ## Background The specification (§ Core Concepts > Invariants, line 92; § Strategize Phase, lines 18421+) describes a **built-in Invariant Reconciliation Actor** that runs at the start of the Strategize phase to reconcile invariants from multiple scopes: 1. **Global invariants** — project-wide constraints (e.g., "never delete production data") 2. **Project invariants** — from project configuration 3. **Action invariants** — from the user's action definition 4. **Plan invariants** — inherited from parent plans The reconciliation actor: - Collects invariants from all 4 scopes - Detects conflicts between scopes (e.g., action invariant contradicts global invariant) - Records `invariant_enforced` decisions for each active invariant - Produces a reconciled invariant set that subsequent actors must respect **Current state:** No code reference to `InvariantReconciliation` or `reconciliation_actor` found in codebase. Invariant models exist but no actor performs the reconciliation step. ## Acceptance Criteria 1. `InvariantReconciliationActor` exists as a built-in actor (YAML or code-defined). 2. Actor runs automatically at the start of Strategize phase. 3. Collects invariants from global, project, action, and plan scopes. 4. Detects and reports scope conflicts with clear diagnostic messages. 5. Records `invariant_enforced` decision for each active invariant. 6. Produces a reconciled `InvariantSet` available to subsequent actors. 7. Conflict resolution strategy: higher specificity wins (plan > action > project > global) unless global invariant is marked `non_overridable`. ## Subtasks ### 1. Design - [x] Design invariant scope collection flow - [x] Design conflict detection and resolution algorithm - [x] Design `invariant_enforced` decision format ### 2. Implementation - [x] Create `InvariantReconciliationActor` class - [x] Implement multi-scope invariant collection - [x] Implement conflict detection - [x] Implement conflict resolution with specificity rules - [x] Implement `invariant_enforced` decision recording - [ ] Register as built-in actor that auto-runs in Strategize ### 3. Testing - [x] Unit test: single-scope invariants (no conflicts) - [x] Unit test: multi-scope with compatible invariants - [x] Unit test: conflicting invariants resolved by specificity - [x] Unit test: non_overridable global invariant blocks override - [x] Integration test: reconciliation → subsequent actor respects invariants ### 4. Documentation - [ ] Actor behavior documentation - [ ] Invariant scope priority documentation ### 5. Integration - [ ] Wire into Strategize phase execution order - [x] Verify compatibility with existing invariant models ### 6. Observability - [x] Log reconciliation results (invariant count per scope, conflicts detected) - [x] Log invariant_enforced decisions ### 7. Security - [x] non_overridable invariants cannot be bypassed by lower scopes ## Definition of Done - [x] All acceptance criteria met - [ ] All subtask checkboxes checked - [x] Tests pass in CI - [ ] Code reviewed and approved

freemo added the

Rows
Columns