---
adr_number: 16
title: Invariant System
status_history:
- - '2026-02-16'
  - Proposed
  - Jeffrey Phillips Freeman
- - '2026-02-16'
  - Accepted
  - Jeffrey Phillips Freeman
tier: 3
authors:
- Jeffrey Phillips Freeman
superseded_by: null
related_adrs:
- number: 6
  title: Plan Lifecycle
  relationship: Invariants are reconciled at Strategize entry and enforced throughout the lifecycle
- number: 7
  title: Decision Tree and Correction
  relationship: Enforced invariants are recorded as `invariant_enforced` decision nodes
- number: 9
  title: Project Model
  relationship: Projects define project-scoped invariants that constrain all child plans
- number: 17
  title: Automation Profiles
  relationship: Invariant violations interact with automation profile thresholds for escalation
- number: 33
  title: Decision Recording Protocol
  relationship: Invariant Reconciliation Actor creates `invariant_enforced` decisions via the `record_decision` tool
acceptance:
  votes_for:
  - voter: Jeffrey Phillips Freeman <Jeffrey.Freeman@CleverThis.com>
    comment: Four-scope invariants with precedence and reconciliation give us layered constraint enforcement
  votes_against: []
  abstentions: []
---
## Context

When AI systems make autonomous decisions, they must operate within defined boundaries. A strategy actor choosing an implementation approach must respect project-wide coding standards. An execution actor modifying files must respect API compatibility requirements. These constraints — invariants — may be defined at different scopes (global, project, action, plan) and may conflict with each other. The system needs a structured mechanism for declaring, scoping, resolving conflicts, and enforcing invariants across the plan lifecycle.

## Decision Drivers

- Autonomous AI decisions must operate within declared boundaries (coding standards, API compatibility, etc.)
- Constraints originate at different scopes — system-wide standards vs. project-specific rules vs. plan-specific overrides
- Conflicting invariants across scopes need a deterministic, predictable resolution mechanism
- Invariants must be visible in the decision tree so they can be corrected, audited, and visualized like any other decision
- Child plans must inherit parent constraints without manual propagation

## Decision

CleverAgents implements an **invariant system** with four scopes (global, project, action, plan), a precedence-based resolution chain, an **Invariant Reconciliation Actor** that resolves conflicts, and explicit recording of enforced invariants as `invariant_enforced` decision nodes in the plan's decision tree. Invariants flow through the hierarchy — child plans inherit the effective invariant set of their parent.

## Design

### Four Scopes

**Global invariants**: Apply to all plans in the system. Set via `agents invariant add --global`. Example: "All code must pass Ruff linting."

**Project invariants**: Apply to all plans targeting a specific project. Set via `agents invariant add --project <PROJECT>`. Example: "Maintain API compatibility with v2 callers."

**Action invariants**: Attached to an action template and carried forward to every plan spawned from that action. Set in the action YAML or via `agents invariant add --action <ACTION>`. Example: "Do not modify the public interface of module X."

**Plan invariants**: Apply to a specific plan instance. Set via `--invariant` flag at `plan use` time or via `agents invariant add --plan <PLAN>`. Example: "Use only async patterns in this refactoring."

### Precedence Rules

When invariants conflict, the more specific scope wins:

```
plan > action > project > global
```

If an invariant at a lower scope contradicts one at a higher scope, the lower (more specific) scope takes precedence. This enables plans to override project-level constraints when justified.

### Invariant Reconciliation Actor

At the entry to the Strategize phase, the **Invariant Reconciliation Actor** computes the effective invariant view:

1. Collects invariants from all four scopes.
2. Identifies conflicts (contradictory invariants across scopes).
3. Resolves conflicts using the precedence rules.
4. Records each enforced invariant as an `invariant_enforced` decision in the plan's decision tree.

The Invariant Reconciliation Actor is itself an actor, configurable at the plan, action, project, or global level (lookup chain: plan → action → project → `actor.default.invariant`).

### Decision Tree Integration

Enforced invariants appear as `invariant_enforced` decision nodes in the plan's decision tree. This means:

- Invariants are visible in the decision tree visualization.
- Invariants constrain downstream decisions (strategy choices, resource selections, child plan blueprints).
- Invariants can be corrected using the standard `agents plan correct` command (e.g., removing an inappropriate invariant).
- Child plans inherit the effective invariant set of their parent.

### Child Plan Inheritance

When a parent plan spawns child plans, the child inherits the parent's effective invariant set. Additional invariants can be added at the child plan level. The child's Invariant Reconciliation Actor reconciles the inherited set with any child-specific additions.

### Correction Mechanism

Invariants are correctable like any other decision:

- To remove an inappropriate invariant: correct the `invariant_enforced` decision.
- To add a missing invariant: use `agents invariant add --plan <PLAN>` and re-enter Strategize.
- Correcting an invariant invalidates all downstream decisions that were constrained by it.

## Constraints

- Every plan must have its effective invariant view computed at Strategize entry. Plans must not enter Strategize without invariant reconciliation.
- Invariant precedence (plan > action > project > global) is fixed and cannot be overridden.
- Invariants are recorded as decision tree nodes. They must not exist as side-channel metadata invisible to the decision tree.
- Child plans must inherit the parent's effective invariant set. Dropping inherited invariants requires explicit correction.
- The Invariant Reconciliation Actor must be deterministic for a given set of inputs — same invariants, same conflict resolution, same output.

## Consequences

### Positive
- Four scopes provide fine-grained control — from system-wide standards to plan-specific constraints.
- Recording invariants as decision tree nodes enables unified correction, visualization, and auditability.
- Precedence-based resolution provides a clear, predictable conflict resolution mechanism.
- Child plan inheritance ensures that constraints flow through the entire plan hierarchy without manual propagation.

### Negative
- Four scopes create complexity in understanding which invariants are effective for a given plan.
- The Invariant Reconciliation Actor adds a processing step at Strategize entry.
- Invariant conflicts may be subtle and difficult for users to diagnose without good visualization tooling.

### Risks
- Overly restrictive invariants (especially global ones) could prevent plans from completing, requiring manual intervention to relax constraints.
- The precedence chain may produce surprising results when plan-level invariants override well-intentioned project-level safety constraints.
- Stale invariants (referencing deprecated APIs, removed modules, etc.) could cause unnecessary failures.

## Alternatives Considered

**Single-scope invariants (global only)** — Too coarse. Different projects have different requirements, and individual plans may need to temporarily override project standards (e.g., a migration plan that deliberately breaks API compatibility).

**Invariants as metadata outside the decision tree** — Would create a parallel constraint system invisible to the correction mechanism. Recording invariants as decision nodes ensures they are subject to the same correction, visualization, and auditing as all other decisions.

## Compliance

- **Scope precedence tests**: Unit tests verify that invariant resolution correctly applies plan > action > project > global precedence in all conflict scenarios.
- **Decision tree integration tests**: Tests verify that enforced invariants appear as `invariant_enforced` nodes and correctly constrain downstream decisions.
- **Inheritance tests**: Tests verify that child plans inherit the parent's effective invariant set and that child-level additions are correctly reconciled.
- **Correction tests**: BDD scenarios verify that correcting an invariant invalidates downstream decisions and that adding/removing invariants triggers re-strategization.
- **Reconciliation determinism**: Tests verify that the Invariant Reconciliation Actor produces identical output for identical inputs.
