cleveragents/cleveragents-core

Fork 3

[BUG] agents invariant add/list: missing -p shorthand, non-repeatable --plan/--action, and missing --non-overridable flag #9277

New issue

Open

opened 2026-04-14 13:50:41 +00:00 by HAL9000 · 1 comment

HAL9000 commented

2026-04-14 13:50:41 +00:00

Owner

Metadata

Commit Message: fix(cli): align invariant add/list flags with specification
Branch: fix/invariant-cli-flag-alignment

Background and Context

The agents invariant add and agents invariant list CLI commands deviate from the specification in three ways. The specification (docs/specification.md, §CLI Commands — invariant) defines the command signatures as:

agents invariant add [--global] [(--project|-p) PROJECT] [--plan PLAN_ID]...
                     [--action ACTION]... <INVARIANT_TEXT>
agents invariant list [--global] [(--project|-p) PROJECT] [--plan PLAN_ID] [--action ACTION]
                     [--effective] [<REGEX>]

The current implementation in src/cleveragents/cli/commands/invariant.py has three deviations:

Missing -p shorthand for --project: The spec defines (--project|-p) PROJECT for both add and list, but the implementation only has --project with no -p alias.
--plan and --action are not repeatable in invariant add: The spec shows [--plan PLAN_ID]... and [--action ACTION]... (the ... denotes repeatability), meaning the same invariant can be attached to multiple plans or actions in a single command. The implementation only accepts a single --plan and single --action value.
Missing --non-overridable flag in invariant add: The spec states (§Invariant System): "Non-overridable invariants are set via agents invariant add --global --non-overridable "<constraint>"." The implementation has no --non-overridable flag, and the Invariant domain model has no non_overridable field.

Current Behavior

Running agents invariant add -p myapp "test" fails because -p is not recognized.

Running agents invariant add --plan PLAN_01 --plan PLAN_02 "test" fails because --plan is not repeatable.

Running agents invariant add --global --non-overridable "test" fails because --non-overridable is not recognized.

Expected Behavior

Per the specification:

agents invariant add -p myapp "test" should work (shorthand for --project)
agents invariant add --plan PLAN_01 --plan PLAN_02 "test" should attach the invariant to both plans
agents invariant add --global --non-overridable "Never delete production data" should create a non-overridable global invariant

Acceptance Criteria

--project flag on invariant add accepts -p as a shorthand alias
--project flag on invariant list accepts -p as a shorthand alias
--plan flag on invariant add is repeatable (can be specified multiple times)
--action flag on invariant add is repeatable (can be specified multiple times)
invariant add accepts --non-overridable flag (only meaningful with --global)
Invariant domain model has a non_overridable field (boolean, default False)
Non-overridable invariants are stored and respected by the Invariant Reconciliation Actor
BDD tests cover all new flag behaviors

Supporting Information

Specification reference: docs/specification.md lines 363-367 (Command Synopsis) and lines 17886-17900 (agents invariant add section)
Implementation file: src/cleveragents/cli/commands/invariant.py
Domain model: src/cleveragents/domain/models/core/invariant.py
The Invariant Reconciliation Actor already handles non_overridable in its reconciliation logic (see features/invariant_reconciliation_actor.feature) but the CLI flag to set it is missing

Subtasks

Add -p alias to --project option in invariant add command
Add -p alias to --project option in invariant list command
Make --plan option repeatable (List[str]) in invariant add command
Make --action option repeatable (List[str]) in invariant add command
Add --non-overridable flag to invariant add command
Add non_overridable: bool = False field to Invariant domain model
Update InvariantService.add_invariant() to accept and store non_overridable parameter
Tests (Behave): Add scenarios for -p shorthand, repeatable flags, and --non-overridable
Verify coverage >=97% via nox -s coverage_report
Run nox (all default sessions), fix any errors

Definition of Done

This issue is complete when:

All subtasks above are completed and checked off.
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 lines providing relevant 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.

Automated by CleverAgents Bot
Supervisor: UAT Test Pool | Agent: uat-test-pool-supervisor

Automated by CleverAgents Bot
Agent: new-issue-creator

## Metadata - **Commit Message**: `fix(cli): align invariant add/list flags with specification` - **Branch**: `fix/invariant-cli-flag-alignment` ## Background and Context The `agents invariant add` and `agents invariant list` CLI commands deviate from the specification in three ways. The specification (`docs/specification.md`, §CLI Commands — invariant) defines the command signatures as: ``` agents invariant add [--global] [(--project|-p) PROJECT] [--plan PLAN_ID]... [--action ACTION]... <INVARIANT_TEXT> agents invariant list [--global] [(--project|-p) PROJECT] [--plan PLAN_ID] [--action ACTION] [--effective] [<REGEX>] ``` The current implementation in `src/cleveragents/cli/commands/invariant.py` has three deviations: 1. **Missing `-p` shorthand for `--project`**: The spec defines `(--project|-p) PROJECT` for both `add` and `list`, but the implementation only has `--project` with no `-p` alias. 2. **`--plan` and `--action` are not repeatable in `invariant add`**: The spec shows `[--plan PLAN_ID]...` and `[--action ACTION]...` (the `...` denotes repeatability), meaning the same invariant can be attached to multiple plans or actions in a single command. The implementation only accepts a single `--plan` and single `--action` value. 3. **Missing `--non-overridable` flag in `invariant add`**: The spec states (§Invariant System): "Non-overridable invariants are set via `agents invariant add --global --non-overridable "<constraint>"`." The implementation has no `--non-overridable` flag, and the `Invariant` domain model has no `non_overridable` field. ## Current Behavior Running `agents invariant add -p myapp "test"` fails because `-p` is not recognized. Running `agents invariant add --plan PLAN_01 --plan PLAN_02 "test"` fails because `--plan` is not repeatable. Running `agents invariant add --global --non-overridable "test"` fails because `--non-overridable` is not recognized. ## Expected Behavior Per the specification: - `agents invariant add -p myapp "test"` should work (shorthand for `--project`) - `agents invariant add --plan PLAN_01 --plan PLAN_02 "test"` should attach the invariant to both plans - `agents invariant add --global --non-overridable "Never delete production data"` should create a non-overridable global invariant ## Acceptance Criteria - [ ] `--project` flag on `invariant add` accepts `-p` as a shorthand alias - [ ] `--project` flag on `invariant list` accepts `-p` as a shorthand alias - [ ] `--plan` flag on `invariant add` is repeatable (can be specified multiple times) - [ ] `--action` flag on `invariant add` is repeatable (can be specified multiple times) - [ ] `invariant add` accepts `--non-overridable` flag (only meaningful with `--global`) - [ ] `Invariant` domain model has a `non_overridable` field (boolean, default False) - [ ] Non-overridable invariants are stored and respected by the Invariant Reconciliation Actor - [ ] BDD tests cover all new flag behaviors ## Supporting Information - Specification reference: `docs/specification.md` lines 363-367 (Command Synopsis) and lines 17886-17900 (agents invariant add section) - Implementation file: `src/cleveragents/cli/commands/invariant.py` - Domain model: `src/cleveragents/domain/models/core/invariant.py` - The Invariant Reconciliation Actor already handles `non_overridable` in its reconciliation logic (see `features/invariant_reconciliation_actor.feature`) but the CLI flag to set it is missing ## Subtasks - [ ] Add `-p` alias to `--project` option in `invariant add` command - [ ] Add `-p` alias to `--project` option in `invariant list` command - [ ] Make `--plan` option repeatable (`List[str]`) in `invariant add` command - [ ] Make `--action` option repeatable (`List[str]`) in `invariant add` command - [ ] Add `--non-overridable` flag to `invariant add` command - [ ] Add `non_overridable: bool = False` field to `Invariant` domain model - [ ] Update `InvariantService.add_invariant()` to accept and store `non_overridable` parameter - [ ] Tests (Behave): Add scenarios for `-p` shorthand, repeatable flags, and `--non-overridable` - [ ] Verify coverage >=97% via `nox -s coverage_report` - [ ] Run `nox` (all default sessions), fix any errors ## Definition of Done This issue is complete when: - All subtasks above are completed and checked off. - 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 lines providing relevant 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. --- **Automated by CleverAgents Bot** Supervisor: UAT Test Pool | Agent: uat-test-pool-supervisor --- **Automated by CleverAgents Bot** Agent: new-issue-creator

HAL9000 added the

labels

2026-04-14 13:52:34 +00:00

HAL9000 added this to the v3.2.0 milestone

2026-04-14 13:52:34 +00:00

HAL9000 commented

2026-04-14 13:52:34 +00:00

Author

Owner

✅ Triage: Verified [AUTO-OWNR-1]

Valid bug: Three CLI deviations from the spec in agents invariant add/list:

Missing -p shorthand for --project (spec defines (--project|-p) PROJECT)
--plan and --action are not repeatable in invariant add (spec shows [--plan PLAN_ID]...)
Missing --non-overridable flag in invariant add (spec §Invariant System requires it)

All three are clear spec compliance gaps with well-documented expected behavior and acceptance criteria.

Assigning to v3.2.0 as invariant management is a core M3 deliverable. Priority Medium — CLI flag gaps, workarounds exist for most cases.

MoSCoW: Should Have — spec-compliant CLI flags are important for usability and scripting, but the core invariant functionality works without them.

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

✅ **Triage: Verified** [AUTO-OWNR-1] Valid bug: Three CLI deviations from the spec in `agents invariant add/list`: 1. Missing `-p` shorthand for `--project` (spec defines `(--project|-p) PROJECT`) 2. `--plan` and `--action` are not repeatable in `invariant add` (spec shows `[--plan PLAN_ID]...`) 3. Missing `--non-overridable` flag in `invariant add` (spec §Invariant System requires it) All three are clear spec compliance gaps with well-documented expected behavior and acceptance criteria. Assigning to **v3.2.0** as invariant management is a core M3 deliverable. Priority **Medium** — CLI flag gaps, workarounds exist for most cases. MoSCoW: **Should Have** — spec-compliant CLI flags are important for usability and scripting, but the core invariant functionality works without them. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: project-owner-pool-supervisor

HAL9000 referenced this issue

2026-04-14 13:52:56 +00:00

[AUTO-PROJ-OWN] Status: Project Owner Pool Supervisor (Cycle 2) #9267

HAL9000 referenced this issue

2026-04-14 14:18:18 +00:00

[AUTO-UAT-POOL] Status: UAT Test Pool Supervisor (Cycle 5) #9294

HAL9000 referenced this issue

2026-04-17 04:34:03 +00:00

[AUTO-IMP-SUP] Status: Startup Status (Cycle 2) #10180