cleveragents/cleveragents-core

Fork 3

UAT: agents invariant add silently defaults to --global when no scope flag provided — spec requires at least one scope flag #3535

New issue

Open

opened 2026-04-05 19:02:21 +00:00 by freemo · 1 comment

freemo commented

2026-04-05 19:02:21 +00:00

Owner

Metadata

Branch: fix/invariant-add-require-scope-flag
Commit Message: fix(cli): raise error when no scope flag provided to agents invariant add
Milestone: Backlog
Parent Epic: #394

Summary

The agents invariant add command silently defaults to global scope when no scope flag is provided, but the spec states that at least one scope flag is required.

What Was Tested

Code analysis of src/cleveragents/cli/commands/invariant.py lines 70-97 (_resolve_scope function) compared against docs/specification.md §17808.

Expected Behavior (from spec)

The spec states:

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

Running agents invariant add "test invariant" with no scope flag should produce an error like:

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

Actual Behavior

The _resolve_scope function (lines 70-97) silently defaults to GLOBAL scope when no flags are set:

def _resolve_scope(is_global, project, plan, action):
    flags_set = sum([is_global, project is not None, plan is not None, action is not None])
    if flags_set > 1:
        raise typer.BadParameter("Specify at most one scope flag...")
    
    if project is not None:
        return InvariantScope.PROJECT, project
    if plan is not None:
        return InvariantScope.PLAN, plan
    if action is not None:
        return InvariantScope.ACTION, action
    
    # Default to global — THIS IS THE BUG
    return InvariantScope.GLOBAL, "system"

When a user runs agents invariant add "test invariant" without any scope flag, the invariant is silently created as a global invariant. This is surprising behavior — the user may not intend to create a global invariant.

The module docstring even says "If no scope flag is given, --global is assumed" — but this contradicts the spec.

Code Location

src/cleveragents/cli/commands/invariant.py lines 81-97 (_resolve_scope function)
src/cleveragents/cli/commands/invariant.py lines 23-24 (module docstring that documents the incorrect behavior)

Fix

Change _resolve_scope to raise an error when no scope flag is provided:

# After checking flags_set > 1:
if flags_set == 0:
    raise typer.BadParameter(
        "At least one scope flag (--global, --project, --plan, or --action) must be provided"
    )

Steps to Reproduce

Run agents invariant add "test invariant" (no scope flag)
Observe: invariant is silently created as global scope
Expected: error message requiring a scope flag

Subtasks

Update _resolve_scope in src/cleveragents/cli/commands/invariant.py to raise typer.BadParameter when flags_set == 0
Update module docstring (lines 23-24) to reflect the corrected behavior (no default scope assumed)
Add/update unit tests to assert the error is raised when no scope flag is provided
Add/update unit tests to assert all four scope flags still work correctly
Run nox (all default sessions), fix any errors
Verify coverage >= 97% via nox -s coverage_report

Definition of Done

_resolve_scope raises a clear error when called with no scope flags
Module docstring no longer states that --global is assumed as default
All new and existing tests pass
All nox stages pass
Coverage >= 97%

Backlog note: This issue was discovered during autonomous operation
on milestone . 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**: `fix/invariant-add-require-scope-flag` - **Commit Message**: `fix(cli): raise error when no scope flag provided to agents invariant add` - **Milestone**: Backlog - **Parent Epic**: #394 ## Summary The `agents invariant add` command silently defaults to global scope when no scope flag is provided, but the spec states that at least one scope flag is required. ## What Was Tested Code analysis of `src/cleveragents/cli/commands/invariant.py` lines 70-97 (`_resolve_scope` function) compared against `docs/specification.md` §17808. ## Expected Behavior (from spec) The spec states: > At least one scope flag (`--global`, `--project`, `--plan`, or `--action`) must be provided. Running `agents invariant add "test invariant"` with no scope flag should produce an error like: ``` Error: At least one scope flag (--global, --project, --plan, or --action) must be provided. ``` ## Actual Behavior The `_resolve_scope` function (lines 70-97) silently defaults to `GLOBAL` scope when no flags are set: ```python def _resolve_scope(is_global, project, plan, action): flags_set = sum([is_global, project is not None, plan is not None, action is not None]) if flags_set > 1: raise typer.BadParameter("Specify at most one scope flag...") if project is not None: return InvariantScope.PROJECT, project if plan is not None: return InvariantScope.PLAN, plan if action is not None: return InvariantScope.ACTION, action # Default to global — THIS IS THE BUG return InvariantScope.GLOBAL, "system" ``` When a user runs `agents invariant add "test invariant"` without any scope flag, the invariant is silently created as a global invariant. This is surprising behavior — the user may not intend to create a global invariant. The module docstring even says "If no scope flag is given, `--global` is assumed" — but this contradicts the spec. ## Code Location - `src/cleveragents/cli/commands/invariant.py` lines 81-97 (`_resolve_scope` function) - `src/cleveragents/cli/commands/invariant.py` lines 23-24 (module docstring that documents the incorrect behavior) ## Fix Change `_resolve_scope` to raise an error when no scope flag is provided: ```python # After checking flags_set > 1: if flags_set == 0: raise typer.BadParameter( "At least one scope flag (--global, --project, --plan, or --action) must be provided" ) ``` ## Steps to Reproduce 1. Run `agents invariant add "test invariant"` (no scope flag) 2. Observe: invariant is silently created as global scope 3. Expected: error message requiring a scope flag ## Subtasks - [ ] Update `_resolve_scope` in `src/cleveragents/cli/commands/invariant.py` to raise `typer.BadParameter` when `flags_set == 0` - [ ] Update module docstring (lines 23-24) to reflect the corrected behavior (no default scope assumed) - [ ] Add/update unit tests to assert the error is raised when no scope flag is provided - [ ] Add/update unit tests to assert all four scope flags still work correctly - [ ] Run `nox` (all default sessions), fix any errors - [ ] Verify coverage >= 97% via `nox -s coverage_report` ## Definition of Done - [ ] `_resolve_scope` raises a clear error when called with no scope flags - [ ] Module docstring no longer states that `--global` is assumed as default - [ ] All new and existing tests pass - [ ] All nox stages pass - [ ] Coverage >= 97% > **Backlog note:** This issue was discovered during autonomous operation > on milestone <M>. 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 a new dependency

2026-04-05 19:02:37 +00:00

#394 Epic: Decision Framework

freemo referenced this issue

2026-04-05 19:06:31 +00:00

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

freemo commented

2026-04-05 19:36:49 +00:00

Author

Owner

Issue triaged by project owner:

State: Verified
Priority: Low — The silent default to global scope is a UX issue, not a functional blocker. Users can still create correctly-scoped invariants by explicitly providing a scope flag.
Milestone: v3.3.0 — Invariant CLI is part of the Decision Framework (Epic #394).
Story Points: 1 — XS — Simple validation check: add if flags_set == 0: raise typer.BadParameter(...) and update the docstring. Trivial fix.
MoSCoW: Could Have — The spec says scope flags are required, but the current behavior (defaulting to global) is functional and documented in the module docstring. Low impact.
Parent Epic: #394 (Decision Framework)

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

Issue triaged by project owner: - **State**: Verified - **Priority**: Low — The silent default to global scope is a UX issue, not a functional blocker. Users can still create correctly-scoped invariants by explicitly providing a scope flag. - **Milestone**: v3.3.0 — Invariant CLI is part of the Decision Framework (Epic #394). - **Story Points**: 1 — XS — Simple validation check: add `if flags_set == 0: raise typer.BadParameter(...)` and update the docstring. Trivial fix. - **MoSCoW**: Could Have — The spec says scope flags are required, but the current behavior (defaulting to global) is functional and documented in the module docstring. Low impact. - **Parent Epic**: #394 (Decision Framework) --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: ca-project-owner

freemo added this to the v3.3.0 milestone

2026-04-05 19:37:43 +00:00

freemo referenced this issue

2026-04-05 19:38:18 +00:00

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

freemo referenced this issue

2026-04-05 19:44:18 +00:00

UAT: agents invariant add silently defaults to --global when no scope flag is provided — spec requires at least one scope flag #2094

freemo referenced this issue

2026-04-05 19:45:38 +00:00

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

freemo referenced this issue