UAT: agents validation attach does not enforce mutual exclusivity of --project and --plan scope flags #3823

New issue

Open

opened 2026-04-06 06:45:59 +00:00 by freemo · 0 comments

freemo commented

2026-04-06 06:45:59 +00:00

Owner

Metadata

Branch: fix/backlog-validation-attach-scope-flag-mutex
Commit Message: fix(cli): enforce mutual exclusivity of --project and --plan in validation attach
Milestone: (backlog — no milestone)
Parent Epic: #397

Background and Context

The agents validation attach command accepts both --project and --plan flags simultaneously without raising an error. The specification explicitly states "At most one scope flag may be provided per invocation."

Per docs/specification.md (agents validation attach section), the command synopsis is:

agents validation attach [--project <PROJECT>|--plan <PLAN_ID>] <RESOURCE> <VALIDATION> [<ARGS>...]

The | in the synopsis denotes mutual exclusivity — only one scope flag may be provided. If neither is provided, the validation is attached globally to the resource.

Current Behavior

The attach command in src/cleveragents/cli/commands/validation.py accepts both --project and --plan without validation:

@app.command("attach")
def attach(
    ...
    project: Annotated[str | None, typer.Option("--project", "-p", help="Project scope")] = None,
    plan_id: Annotated[str | None, typer.Option("--plan", help="Plan ID scope")] = None,
    ...
) -> None:
    # No check for mutual exclusivity of project and plan_id
    service = _get_tool_registry_service()
    attachment = service.attach_validation(
        validation_name=validation_name,
        resource_id=resource,
        project_name=project,
        plan_id=plan_id,  # Both project and plan_id can be non-None simultaneously
        args=extra_args,
    )

When both --project and --plan are provided, the ValidationAttachmentRepository.attach() method receives both values and stores them in the database, creating an attachment with both project_name and plan_id set. This is semantically undefined behavior per the spec.

Expected Behavior

Per docs/specification.md (agents validation attach section):

"At most one scope flag may be provided per invocation."

The command should reject invocations that provide both --project and --plan simultaneously, with a clear error message such as:

Error: --project and --plan are mutually exclusive; provide at most one scope flag

Steps to Reproduce

# This should fail with an error but currently succeeds
agents validation attach --project local/my-project --plan 01HXYZ1234567890ABCDEFGHIJ my-resource local/my-validation

Code Location

src/cleveragents/cli/commands/validation.py — attach() function (lines ~175–240)
Compare with add() function in the same file which correctly validates --required and --informational as mutually exclusive (lines ~100–115)

Subtasks

Add mutual exclusivity guard at the top of attach() in src/cleveragents/cli/commands/validation.py
Add error message matching the spec's expected output format
Tests (Behave): Add scenario for agents validation attach rejecting both --project and --plan simultaneously
Tests (Behave): Add scenario confirming --project alone and --plan alone are accepted
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 details.
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 stages pass.
Coverage >= 97%.

Backlog note: This issue was discovered during autonomous operation
on milestone v3.6.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**: `fix/backlog-validation-attach-scope-flag-mutex` - **Commit Message**: `fix(cli): enforce mutual exclusivity of --project and --plan in validation attach` - **Milestone**: *(backlog — no milestone)* - **Parent Epic**: #397 ## Background and Context The `agents validation attach` command accepts both `--project` and `--plan` flags simultaneously without raising an error. The specification explicitly states "At most one scope flag may be provided per invocation." Per `docs/specification.md` (agents validation attach section), the command synopsis is: ``` agents validation attach [--project <PROJECT>|--plan <PLAN_ID>] <RESOURCE> <VALIDATION> [<ARGS>...] ``` The `|` in the synopsis denotes mutual exclusivity — only one scope flag may be provided. If neither is provided, the validation is attached globally to the resource. ## Current Behavior The `attach` command in `src/cleveragents/cli/commands/validation.py` accepts both `--project` and `--plan` without validation: ```python @app.command("attach") def attach( ... project: Annotated[str | None, typer.Option("--project", "-p", help="Project scope")] = None, plan_id: Annotated[str | None, typer.Option("--plan", help="Plan ID scope")] = None, ... ) -> None: # No check for mutual exclusivity of project and plan_id service = _get_tool_registry_service() attachment = service.attach_validation( validation_name=validation_name, resource_id=resource, project_name=project, plan_id=plan_id, # Both project and plan_id can be non-None simultaneously args=extra_args, ) ``` When both `--project` and `--plan` are provided, the `ValidationAttachmentRepository.attach()` method receives both values and stores them in the database, creating an attachment with both `project_name` and `plan_id` set. This is semantically undefined behavior per the spec. ## Expected Behavior Per `docs/specification.md` (agents validation attach section): > "At most one scope flag may be provided per invocation." The command should reject invocations that provide both `--project` and `--plan` simultaneously, with a clear error message such as: ``` Error: --project and --plan are mutually exclusive; provide at most one scope flag ``` ## Steps to Reproduce ```bash # This should fail with an error but currently succeeds agents validation attach --project local/my-project --plan 01HXYZ1234567890ABCDEFGHIJ my-resource local/my-validation ``` ## Code Location - `src/cleveragents/cli/commands/validation.py` — `attach()` function (lines ~175–240) - Compare with `add()` function in the same file which correctly validates `--required` and `--informational` as mutually exclusive (lines ~100–115) ## Subtasks - [ ] Add mutual exclusivity guard at the top of `attach()` in `src/cleveragents/cli/commands/validation.py` - [ ] Add error message matching the spec's expected output format - [ ] Tests (Behave): Add scenario for `agents validation attach` rejecting both `--project` and `--plan` simultaneously - [ ] Tests (Behave): Add scenario confirming `--project` alone and `--plan` alone are accepted - [ ] 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 details. - 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 stages pass. - Coverage >= 97%. > **Backlog note:** This issue was discovered during autonomous operation > on milestone v3.6.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 a new dependency

2026-04-06 06:46:13 +00:00

#397 Epic: Server & Autonomy Infrastructure

freemo referenced this issue

2026-04-06 06:46:45 +00:00

[Automated] CleverAgents Build Session - 2026-04-06 #3775

freemo added the

Points

label

2026-04-06 06:50:02 +00:00

freemo referenced this issue

2026-04-06 06:51:25 +00:00