UAT: agents invariant add missing --non-overridable flag — no CLI way to set non_overridable field on global invariants #3146

Open
opened 2026-04-05 06:51:56 +00:00 by freemo · 3 comments
Owner

Metadata

  • Branch: fix/invariant-add-non-overridable-flag
  • Commit Message: fix(cli): add --non-overridable flag to agents invariant add command
  • Milestone: (none — backlog)
  • Parent Epic: #394

Background and Context

The Invariant domain model (src/cleveragents/domain/models/core/invariant.py) has a non_overridable: bool field (default False). The InvariantReconciliationActor in src/cleveragents/actor/reconciliation.py implements special handling for non-overridable global invariants — they always win in conflict resolution regardless of scope precedence. However, there is no CLI way to set this field when creating an invariant.

Issue #3064 (spec update proposal) documents that the specification should be updated to describe this feature. This issue tracks the corresponding CLI and service-layer implementation gap.

Current Behavior

The agents invariant add command only accepts:

  • --global / --project / --plan / --action (scope flags)
  • --format (output format)
  • The invariant text (positional argument)

There is no --non-overridable flag. The InvariantService.add_invariant() method also has no non_overridable parameter. As a result, the non_overridable feature is effectively dead code from a user perspective — it is implemented in the reconciliation actor but completely inaccessible via the CLI.

# This should work but currently does not:
agents invariant add --global --non-overridable "Never commit secrets to version control"

Expected Behavior

The agents invariant add command should support a --non-overridable flag for global invariants. When set, the created Invariant object should have non_overridable=True, causing the InvariantReconciliationActor to treat it as always-winning during conflict resolution.

Affected Code Locations

File Location Issue
src/cleveragents/cli/commands/invariant.py add() function Missing --non-overridable Click option
src/cleveragents/application/services/invariant_service.py add_invariant() Missing non_overridable: bool = False parameter
src/cleveragents/domain/models/core/invariant.py Invariant model Has non_overridable: bool = Field(default=False, ...) — correct, no change needed
src/cleveragents/actor/reconciliation.py _resolve_group() Consumes non_overridable correctly — no change needed

Impact

  • The non_overridable feature is implemented in the reconciliation actor but completely inaccessible via the CLI.
  • Users cannot create non-overridable global invariants without directly manipulating the service layer.
  • The feature is effectively dead code from a user perspective.

Subtasks

  • Add --non-overridable Click option to add() in src/cleveragents/cli/commands/invariant.py
  • Add validation: raise a UsageError if --non-overridable is used without --global
  • Update help text to document that --non-overridable is only meaningful for global invariants
  • Add non_overridable: bool = False parameter to InvariantService.add_invariant() in src/cleveragents/application/services/invariant_service.py
  • Pass non_overridable through to the Invariant constructor in add_invariant()
  • Tests (Behave): Add BDD scenario for agents invariant add --global --non-overridable "..."
  • Tests (Behave): Add BDD scenario verifying error when --non-overridable is used without --global
  • Verify coverage >=97% via nox -e coverage_report
  • Run nox (all default sessions), fix any errors

Definition of Done

This issue is complete when:

  • add CLI command updated with --non-overridable flag (only valid with --global)
  • Validation: error raised if --non-overridable is used without --global
  • InvariantService.add_invariant() updated to accept non_overridable: bool = False parameter
  • add_invariant() passes non_overridable to Invariant constructor
  • Help text documents that --non-overridable is only meaningful for global invariants
  • BDD scenario added for agents invariant add --global --non-overridable "..."
  • All nox stages pass
  • Coverage >= 97%
  • A Git commit is created where the first line of the commit message matches the Commit Message in Metadata exactly, followed by a blank line, then additional details about the implementation.
  • The commit is pushed to the remote on the branch matching the Branch in Metadata exactly.
  • The commit is submitted as a pull request to master, reviewed, and merged before this issue is marked done.

Backlog note: This issue was discovered during autonomous operation
on milestone v3.4.0. It does not block milestone completion and has been
placed in the backlog for human review and future milestone assignment.


Automated by CleverAgents Bot
Supervisor: UAT Testing | Agent: ca-uat-tester

## Metadata - **Branch**: `fix/invariant-add-non-overridable-flag` - **Commit Message**: `fix(cli): add --non-overridable flag to agents invariant add command` - **Milestone**: *(none — backlog)* - **Parent Epic**: #394 ## Background and Context The `Invariant` domain model (`src/cleveragents/domain/models/core/invariant.py`) has a `non_overridable: bool` field (default `False`). The `InvariantReconciliationActor` in `src/cleveragents/actor/reconciliation.py` implements special handling for non-overridable global invariants — they always win in conflict resolution regardless of scope precedence. However, there is no CLI way to set this field when creating an invariant. Issue #3064 (spec update proposal) documents that the specification should be updated to describe this feature. This issue tracks the corresponding CLI and service-layer implementation gap. ## Current Behavior The `agents invariant add` command only accepts: - `--global` / `--project` / `--plan` / `--action` (scope flags) - `--format` (output format) - The invariant text (positional argument) There is no `--non-overridable` flag. The `InvariantService.add_invariant()` method also has no `non_overridable` parameter. As a result, the `non_overridable` feature is effectively dead code from a user perspective — it is implemented in the reconciliation actor but completely inaccessible via the CLI. ```bash # This should work but currently does not: agents invariant add --global --non-overridable "Never commit secrets to version control" ``` ## Expected Behavior The `agents invariant add` command should support a `--non-overridable` flag for global invariants. When set, the created `Invariant` object should have `non_overridable=True`, causing the `InvariantReconciliationActor` to treat it as always-winning during conflict resolution. ## Affected Code Locations | File | Location | Issue | |------|----------|-------| | `src/cleveragents/cli/commands/invariant.py` | `add()` function | Missing `--non-overridable` Click option | | `src/cleveragents/application/services/invariant_service.py` | `add_invariant()` | Missing `non_overridable: bool = False` parameter | | `src/cleveragents/domain/models/core/invariant.py` | `Invariant` model | Has `non_overridable: bool = Field(default=False, ...)` — correct, no change needed | | `src/cleveragents/actor/reconciliation.py` | `_resolve_group()` | Consumes `non_overridable` correctly — no change needed | ## Impact - The `non_overridable` feature is implemented in the reconciliation actor but completely inaccessible via the CLI. - Users cannot create non-overridable global invariants without directly manipulating the service layer. - The feature is effectively dead code from a user perspective. ## Subtasks - [ ] Add `--non-overridable` Click option to `add()` in `src/cleveragents/cli/commands/invariant.py` - [ ] Add validation: raise a `UsageError` if `--non-overridable` is used without `--global` - [ ] Update help text to document that `--non-overridable` is only meaningful for global invariants - [ ] Add `non_overridable: bool = False` parameter to `InvariantService.add_invariant()` in `src/cleveragents/application/services/invariant_service.py` - [ ] Pass `non_overridable` through to the `Invariant` constructor in `add_invariant()` - [ ] Tests (Behave): Add BDD scenario for `agents invariant add --global --non-overridable "..."` - [ ] Tests (Behave): Add BDD scenario verifying error when `--non-overridable` is used without `--global` - [ ] Verify coverage >=97% via `nox -e coverage_report` - [ ] Run `nox` (all default sessions), fix any errors ## Definition of Done This issue is complete when: - [ ] `add` CLI command updated with `--non-overridable` flag (only valid with `--global`) - [ ] Validation: error raised if `--non-overridable` is used without `--global` - [ ] `InvariantService.add_invariant()` updated to accept `non_overridable: bool = False` parameter - [ ] `add_invariant()` passes `non_overridable` to `Invariant` constructor - [ ] Help text documents that `--non-overridable` is only meaningful for global invariants - [ ] BDD scenario added for `agents invariant add --global --non-overridable "..."` - [ ] All nox stages pass - [ ] Coverage >= 97% - [ ] A Git commit is created where the **first line** of the commit message matches the Commit Message in Metadata exactly, followed by a blank line, then additional details about the implementation. - [ ] The commit is pushed to the remote on the branch matching the **Branch** in Metadata exactly. - [ ] The commit is submitted as a **pull request** to `master`, reviewed, and **merged** before this issue is marked done. > **Backlog note:** This issue was discovered during autonomous operation > on milestone v3.4.0. It does not block milestone completion and has been > placed in the backlog for human review and future milestone assignment. --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-uat-tester
freemo added this to the v3.5.0 milestone 2026-04-05 06:57:52 +00:00
Author
Owner

Issue triaged by project owner:

  • State: Verified
  • Priority: Backlog — the non_overridable feature is implemented in the reconciliation actor but inaccessible via CLI. This is dead code from a user perspective.
  • Milestone: v3.5.0 (M6: Autonomy Hardening) — invariant enforcement is part of the guard enforcement acceptance criteria for M6
  • MoSCoW: Should Have — the spec (via ADR-016) defines the invariant system with non-overridable global invariants. The feature is partially implemented but the CLI gap makes it inaccessible. Important for completeness but not strictly blocking.
  • Parent Epic: #394

Related: #3064 (spec update proposal for non_overridable documentation)


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

Issue triaged by project owner: - **State**: Verified - **Priority**: Backlog — the non_overridable feature is implemented in the reconciliation actor but inaccessible via CLI. This is dead code from a user perspective. - **Milestone**: v3.5.0 (M6: Autonomy Hardening) — invariant enforcement is part of the guard enforcement acceptance criteria for M6 - **MoSCoW**: Should Have — the spec (via ADR-016) defines the invariant system with non-overridable global invariants. The feature is partially implemented but the CLI gap makes it inaccessible. Important for completeness but not strictly blocking. - **Parent Epic**: #394 Related: #3064 (spec update proposal for non_overridable documentation) --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: ca-project-owner
Author
Owner

Milestone Triage Decision: Moved to Backlog

This CLI feature enhancement has been moved out of v3.5.0 during aggressive milestone triage. While useful for advanced configurations, it does not block core autonomy hardening functionality.

Reasoning:

  • v3.5.0 focus: Essential autonomy hardening (guard enforcement, A2A facade, plan lifecycle)
  • This issue: Non-overridable invariant flag - advanced CLI feature
  • Impact: Advanced configuration option, not core functional capability

Will be addressed in a future milestone focused on CLI feature enhancements.

**Milestone Triage Decision: Moved to Backlog** This CLI feature enhancement has been moved out of v3.5.0 during aggressive milestone triage. While useful for advanced configurations, it does not block core autonomy hardening functionality. **Reasoning:** - v3.5.0 focus: Essential autonomy hardening (guard enforcement, A2A facade, plan lifecycle) - This issue: Non-overridable invariant flag - advanced CLI feature - Impact: Advanced configuration option, not core functional capability Will be addressed in a future milestone focused on CLI feature enhancements.
freemo removed this from the v3.5.0 milestone 2026-04-06 22:39:59 +00:00
Author
Owner

This issue has been moved to the backlog as part of an aggressive grooming of the v3.5.0 milestone. It has been deemed non-critical for the minimal viability of the milestone and will be addressed in a future release.

This issue has been moved to the backlog as part of an aggressive grooming of the v3.5.0 milestone. It has been deemed non-critical for the minimal viability of the milestone and will be addressed in a future release.
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.

Blocks
#394 Epic: Decision Framework
cleveragents/cleveragents-core
Reference
cleveragents/cleveragents-core#3146
No description provided.