Proposal: update specification — fix invariant precedence chain and document non_overridable flag #3064

Closed
opened 2026-04-05 04:50:50 +00:00 by freemo · 5 comments
Owner

Proposal: Specification Update — Invariant Precedence Chain and non_overridable Flag

What Changed in the Implementation

This proposal was triggered by a proactive spec scan (cycle 1, 2026-04-05) comparing the implementation against the specification for milestones v3.2.0–v3.7.0. No single merged PR triggered this — it is a pre-existing inconsistency between the spec glossary and the ADR/implementation.

What Spec Sections Need Updating

Issue 1: Invariant Precedence Chain — Glossary Inconsistency

Current text (spec line 92, Glossary → "Invariant"):

A natural-language constraint on plan execution scoped to global, project, action, or plan level. Action invariants are promoted to plan-level when the action is used, so the runtime precedence chain is three-tier: ==plan > project > global==.

Proposed text:

A natural-language constraint on plan execution scoped to global, project, action, or plan level. The runtime precedence chain is four-tier: ==plan > action > project > global==. Exception: global invariants marked non_overridable always win regardless of scope. Reconciled by the Invariant Reconciliation Actor at the start of Strategize; recorded as invariant_enforced decisions that propagate to child plans.

Rationale: The glossary says "action invariants are promoted to plan-level" and describes a 3-tier chain, but:

  1. ADR-016 (the authoritative decision record, line 71) explicitly defines plan > action > project > global as a 4-tier chain and states "Invariant precedence (plan > action > project > global) is fixed and cannot be overridden."
  2. The implementation (actor/reconciliation.py _SCOPE_PRECEDENCE dict, application/services/plan_lifecycle_service.py line 810, application/services/automation_profile_service.py line 48) all use the 4-tier chain.
  3. Other spec sections (lines 18977, 18980, 18991) correctly state plan > action > project > global.
  4. The InvariantScope enum in domain/models/core/invariant.py includes ACTION = "action" as a distinct scope — it is NOT promoted to plan-level.

The glossary entry is the only place that says 3-tier. It is incorrect and contradicts the ADR, the implementation, and the rest of the spec.

Also fix the InvariantScope docstring in domain/models/core/invariant.py (lines 40–44) which repeats the incorrect 3-tier claim:

Precedence (highest to lowest): PLAN > PROJECT > GLOBAL. ACTION invariants are promoted to PLAN scope at plan use time.

And the InvariantSet.merge method docstring (lines 137, 165) which only accepts 3 parameters (plan, project, global) and omits the action tier — this is a separate implementation gap that should be tracked as a bug issue.

Issue 2: non_overridable Global Invariants — Missing from Spec

Current text: The spec has no mention of non_overridable anywhere.

Proposed addition (in the Invariant System section, after the precedence rules table):

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.

Rationale: The Invariant domain model (domain/models/core/invariant.py line 86) has a non_overridable: bool field. The InvariantReconciliationActor (actor/reconciliation.py lines 138–157) implements special handling: non-overridable global invariants are checked first and always win. This behavior is implemented but completely undocumented in the spec.

Scope — Spec Sections Affected

  1. Glossary → "Invariant" (line 92): Fix 3-tier → 4-tier precedence description
  2. Invariant System section (around line 19440–19600): Add non_overridable flag documentation
  3. ADR-016 (already correct — no changes needed)

Rationale Summary

  • The glossary inconsistency is a documentation error — the implementation correctly follows ADR-016's 4-tier model.
  • The non_overridable feature is a genuine implementation addition that improves the invariant system (allows system administrators to set unbreakable safety constraints). It is better than the spec (which had no mechanism for this), so the spec should be updated to document it.

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

## Proposal: Specification Update — Invariant Precedence Chain and `non_overridable` Flag ### What Changed in the Implementation This proposal was triggered by a proactive spec scan (cycle 1, 2026-04-05) comparing the implementation against the specification for milestones v3.2.0–v3.7.0. No single merged PR triggered this — it is a pre-existing inconsistency between the spec glossary and the ADR/implementation. ### What Spec Sections Need Updating #### Issue 1: Invariant Precedence Chain — Glossary Inconsistency **Current text** (spec line 92, Glossary → "Invariant"): > A natural-language constraint on plan execution scoped to global, project, action, or plan level. Action invariants are promoted to plan-level when the action is used, so the runtime precedence chain is three-tier: ==plan > project > global==. **Proposed text**: > A natural-language constraint on plan execution scoped to global, project, action, or plan level. The runtime precedence chain is four-tier: ==plan > action > project > global==. Exception: global invariants marked `non_overridable` always win regardless of scope. Reconciled by the Invariant Reconciliation Actor at the start of Strategize; recorded as `invariant_enforced` decisions that propagate to child plans. **Rationale**: The glossary says "action invariants are promoted to plan-level" and describes a 3-tier chain, but: 1. **ADR-016** (the authoritative decision record, line 71) explicitly defines `plan > action > project > global` as a 4-tier chain and states "Invariant precedence (plan > action > project > global) is fixed and cannot be overridden." 2. **The implementation** (`actor/reconciliation.py` `_SCOPE_PRECEDENCE` dict, `application/services/plan_lifecycle_service.py` line 810, `application/services/automation_profile_service.py` line 48) all use the 4-tier chain. 3. **Other spec sections** (lines 18977, 18980, 18991) correctly state `plan > action > project > global`. 4. The `InvariantScope` enum in `domain/models/core/invariant.py` includes `ACTION = "action"` as a distinct scope — it is NOT promoted to plan-level. The glossary entry is the only place that says 3-tier. It is incorrect and contradicts the ADR, the implementation, and the rest of the spec. **Also fix** the `InvariantScope` docstring in `domain/models/core/invariant.py` (lines 40–44) which repeats the incorrect 3-tier claim: > Precedence (highest to lowest): PLAN > PROJECT > GLOBAL. ACTION invariants are promoted to PLAN scope at ``plan use`` time. And the `InvariantSet.merge` method docstring (lines 137, 165) which only accepts 3 parameters (plan, project, global) and omits the action tier — this is a separate implementation gap that should be tracked as a bug issue. #### Issue 2: `non_overridable` Global Invariants — Missing from Spec **Current text**: The spec has no mention of `non_overridable` anywhere. **Proposed addition** (in the Invariant System section, after the precedence rules table): > **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. **Rationale**: The `Invariant` domain model (`domain/models/core/invariant.py` line 86) has a `non_overridable: bool` field. The `InvariantReconciliationActor` (`actor/reconciliation.py` lines 138–157) implements special handling: non-overridable global invariants are checked first and always win. This behavior is implemented but completely undocumented in the spec. ### Scope — Spec Sections Affected 1. **Glossary → "Invariant"** (line 92): Fix 3-tier → 4-tier precedence description 2. **Invariant System section** (around line 19440–19600): Add `non_overridable` flag documentation 3. **ADR-016** (already correct — no changes needed) ### Rationale Summary - The glossary inconsistency is a documentation error — the implementation correctly follows ADR-016's 4-tier model. - The `non_overridable` feature is a genuine implementation addition that improves the invariant system (allows system administrators to set unbreakable safety constraints). It is better than the spec (which had no mechanism for this), so the spec should be updated to document it. --- **Automated by CleverAgents Bot** Supervisor: Spec Evolution | Agent: ca-spec-updater
Author
Owner

approved

approved
freemo added this to the v3.5.0 milestone 2026-04-05 06:21:36 +00:00
Author
Owner

Issue triaged by project owner:

  • State: Verified
  • Priority: Backlog (keeping existing)
  • Milestone: v3.5.0 (Autonomy Hardening — invariant system correctness is in scope)
  • MoSCoW: Should Have — the spec glossary has an incorrect 3-tier description that contradicts ADR-016 and the implementation. Fixing this inconsistency is important for spec integrity. The non_overridable flag documentation is also valuable as it documents an existing safety feature.
  • Parent Epic: #394 (Decision Framework)

Dependency note: This spec update should be done AFTER #3066 (the code fix for InvariantSet.merge()) lands, since the spec update documents the correct 4-tier behavior that #3066 will fully implement.


Automated by CleverAgents Bot
Supervisor: Project Owner | Agent: ca-project-owner

Issue triaged by project owner: - **State**: Verified - **Priority**: Backlog (keeping existing) - **Milestone**: v3.5.0 (Autonomy Hardening — invariant system correctness is in scope) - **MoSCoW**: Should Have — the spec glossary has an incorrect 3-tier description that contradicts ADR-016 and the implementation. Fixing this inconsistency is important for spec integrity. The `non_overridable` flag documentation is also valuable as it documents an existing safety feature. - **Parent Epic**: #394 (Decision Framework) **Dependency note:** This spec update should be done AFTER #3066 (the code fix for `InvariantSet.merge()`) lands, since the spec update documents the correct 4-tier behavior that #3066 will fully implement. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: ca-project-owner
Author
Owner

Spec update proposal #3064 approved. PR created: #3268

Label: needs feedback (awaiting human review before merge)

All 6 changes from this proposal have been applied to docs/specification.md on branch spec/update-m4-invariant-precedence-non-overridable.


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

Spec update proposal #3064 approved. PR created: [#3268](https://git.cleverthis.com/cleveragents/cleveragents-core/pulls/3268) Label: `needs feedback` (awaiting human review before merge) All 6 changes from this proposal have been applied to `docs/specification.md` on branch `spec/update-m4-invariant-precedence-non-overridable`. --- **Automated by CleverAgents Bot** Supervisor: Spec Evolution | Agent: ca-spec-updater
Author
Owner

PR #3268 has been reviewed. All 6 specification changes were verified against the implementation (actor/reconciliation.py, domain/models/core/invariant.py) and confirmed correct. The PR accurately fixes the 3-tier → 4-tier precedence chain inconsistency and documents the non_overridable global invariant feature.

Status: PR has the needs feedback label — awaiting human review and human-initiated merge. No blocking issues found in the code review.


Automated by CleverAgents Bot
Supervisor: PR Review | Agent: ca-pr-self-reviewer

PR #3268 has been reviewed. All 6 specification changes were verified against the implementation (`actor/reconciliation.py`, `domain/models/core/invariant.py`) and confirmed correct. The PR accurately fixes the 3-tier → 4-tier precedence chain inconsistency and documents the `non_overridable` global invariant feature. **Status**: PR has the `needs feedback` label — awaiting human review and human-initiated merge. No blocking issues found in the code review. --- **Automated by CleverAgents Bot** Supervisor: PR Review | Agent: ca-pr-self-reviewer
Author
Owner

Label compliance fix applied:

  • Removed 3x duplicate State/In Progress labels (IDs: 1343, 843, 1336)
  • Removed conflicting State/Verified label
  • Added State/In Review — PR #3268 has been submitted implementing this proposal
  • Reason: Issue had 4 conflicting State labels. Per CONTRIBUTING.md, exactly one State/* label is required. Since PR #3268 implements this proposal and is open for review, State/In Review is the correct state.

Automated by CleverAgents Bot
Supervisor: Backlog Grooming | Agent: ca-backlog-groomer

Label compliance fix applied: - Removed 3x duplicate `State/In Progress` labels (IDs: 1343, 843, 1336) - Removed conflicting `State/Verified` label - Added `State/In Review` — PR #3268 has been submitted implementing this proposal - Reason: Issue had 4 conflicting State labels. Per CONTRIBUTING.md, exactly one `State/*` label is required. Since PR #3268 implements this proposal and is open for review, `State/In Review` is the correct state. --- **Automated by CleverAgents Bot** Supervisor: Backlog Grooming | Agent: ca-backlog-groomer
Sign in to join this conversation.
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Reference
cleveragents/cleveragents-core#3064
No description provided.