UAT: `agents invariant add` silently defaults to `--global` scope when no scope flag provided — spec requires exactly one scope flag #3571

New issue

Open

opened 2026-04-05 19:50:16 +00:00 by freemo · 1 comment

freemo commented

2026-04-05 19:50:16 +00:00

Owner

Metadata

Branch: bugfix/invariant-add-require-scope-flag
Commit Message: fix(cli): raise error when no scope flag provided to invariant add
Milestone: (none — backlog)
Parent Epic: #374

Background and context

The agents invariant add CLI command silently defaults to --global scope when no scope flag is provided. The specification (docs/specification.md line 17781) explicitly states:

"Exactly one scope flag is required for add and list."

And (line 17808):

"At least one scope flag (--global, --project, --plan, or --action) must be provided."

This was discovered during UAT testing via code analysis of src/cleveragents/cli/commands/invariant.py.

Current behavior

agents invariant add "some constraint" (no scope flag) silently creates a global-scoped invariant.
The CLI docstring even documents this non-compliant behavior: "If no scope flag is given, --global is assumed."
The _resolve_scope() function (lines 73–82) contains the comment # Default to global on line 80, which documents the spec-violating default.

def _resolve_scope(...) -> tuple[InvariantScope, str]:
    ...
    # Default to global  ← This should be an error, not a default
    return InvariantScope.GLOBAL, "system"

This can lead to unintended global invariants being created when the user forgot to specify a scope.

Steps to reproduce:

agents invariant add "Never delete production data"
# Current output: Invariant added: 01HXYZ... (scope: global)
# Expected output: Error: Exactly one scope flag is required: --global, --project, --plan, or --action

Expected behavior

agents invariant add "some constraint" (no scope flag) should fail with a clear error message requiring the user to specify a scope.
The error should read: "Error: Exactly one scope flag is required: --global, --project, --plan, or --action"

Subtasks

Update _resolve_scope() in src/cleveragents/cli/commands/invariant.py to raise typer.BadParameter when no scope flag is provided
Update CLI docstring and module docstring to remove "If no scope flag is given, --global is assumed"
Update feature tests in features/invariant_cli_new_coverage.feature to reflect required scope behavior
Run nox (all default sessions), fix any errors

Definition of Done

This issue is complete when:

agents invariant add "text" (no scope flag) returns a non-zero exit code with a clear error message
Error message clearly states which scope flags are available (--global, --project, --plan, --action)
All tests updated and passing
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
All nox default sessions pass
Coverage >= 97%

Backlog note: This issue was discovered during autonomous operation
on milestone v3.2.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-new-issue-creator

## Metadata - **Branch**: `bugfix/invariant-add-require-scope-flag` - **Commit Message**: `fix(cli): raise error when no scope flag provided to invariant add` - **Milestone**: *(none — backlog)* - **Parent Epic**: #374 ## Background and context The `agents invariant add` CLI command silently defaults to `--global` scope when no scope flag is provided. The specification (`docs/specification.md` line 17781) explicitly states: > "Exactly one scope flag is required for `add` and `list`." And (line 17808): > "At least one scope flag (`--global`, `--project`, `--plan`, or `--action`) must be provided." This was discovered during UAT testing via code analysis of `src/cleveragents/cli/commands/invariant.py`. ## Current behavior - `agents invariant add "some constraint"` (no scope flag) silently creates a global-scoped invariant. - The CLI docstring even documents this non-compliant behavior: *"If no scope flag is given, `--global` is assumed."* - The `_resolve_scope()` function (lines 73–82) contains the comment `# Default to global` on line 80, which documents the spec-violating default. ```python def _resolve_scope(...) -> tuple[InvariantScope, str]: ... # Default to global ← This should be an error, not a default return InvariantScope.GLOBAL, "system" ``` This can lead to unintended global invariants being created when the user forgot to specify a scope. **Steps to reproduce:** ```bash agents invariant add "Never delete production data" # Current output: Invariant added: 01HXYZ... (scope: global) # Expected output: Error: Exactly one scope flag is required: --global, --project, --plan, or --action ``` ## Expected behavior - `agents invariant add "some constraint"` (no scope flag) should **fail** with a clear error message requiring the user to specify a scope. - The error should read: `"Error: Exactly one scope flag is required: --global, --project, --plan, or --action"` ## Subtasks - [ ] Update `_resolve_scope()` in `src/cleveragents/cli/commands/invariant.py` to raise `typer.BadParameter` when no scope flag is provided - [ ] Update CLI docstring and module docstring to remove *"If no scope flag is given, --global is assumed"* - [ ] Update feature tests in `features/invariant_cli_new_coverage.feature` to reflect required scope behavior - [ ] Run `nox` (all default sessions), fix any errors ## Definition of Done This issue is complete when: - [ ] `agents invariant add "text"` (no scope flag) returns a non-zero exit code with a clear error message - [ ] Error message clearly states which scope flags are available (`--global`, `--project`, `--plan`, `--action`) - [ ] All tests updated and passing - [ ] 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 - [ ] All `nox` default sessions pass - [ ] Coverage >= 97% > **Backlog note:** This issue was discovered during autonomous operation > on milestone v3.2.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-new-issue-creator

freemo added this to the v3.3.0 milestone

2026-04-05 20:14:45 +00:00

freemo commented

2026-04-05 20:15:07 +00:00

Author

Owner

Issue triaged by project owner:

State: Verified
Priority: Medium — agents invariant add silently defaults to --global scope when no scope flag is provided. The spec explicitly states "Exactly one scope flag is required for add and list." This can lead to unintended global invariants.
Milestone: v3.3.0
Story Points: 1 — XS — Update _resolve_scope() to raise typer.BadParameter instead of defaulting to global. Simple validation fix.
MoSCoW: Should Have — Input validation per spec is important. Silent defaults that contradict the spec lead to user confusion and unintended behavior.
Parent Epic: #374 (dependency link already exists)

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

Issue triaged by project owner: - **State**: Verified - **Priority**: Medium — `agents invariant add` silently defaults to `--global` scope when no scope flag is provided. The spec explicitly states "Exactly one scope flag is required for `add` and `list`." This can lead to unintended global invariants. - **Milestone**: v3.3.0 - **Story Points**: 1 — XS — Update `_resolve_scope()` to raise `typer.BadParameter` instead of defaulting to global. Simple validation fix. - **MoSCoW**: Should Have — Input validation per spec is important. Silent defaults that contradict the spec lead to user confusion and unintended behavior. - **Parent Epic**: #374 (dependency link already exists) --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: ca-project-owner

freemo referenced this issue

2026-04-05 20:17:01 +00:00

[Automated] CleverAgents Build Session - 2026-04-05 #3572

freemo removed this from the v3.3.0 milestone

2026-04-06 20:48:04 +00:00