UAT: `agents plan diff --correction` requires a positional `<PLAN_ID>` — spec defines `--correction` and `<PLAN_ID>` as mutually exclusive alternatives #2508

New issue

Open

opened 2026-04-03 18:41:21 +00:00 by freemo · 1 comment

freemo commented

2026-04-03 18:41:21 +00:00

Owner

Metadata

Branch: fix/plan-diff-signature
Commit Message: fix(cli): make plan diff --correction and <PLAN_ID> mutually exclusive per spec
Milestone: v3.7.0
Parent Epic: #397

Description

The specification defines agents plan diff with mutually exclusive alternatives:

agents plan diff (--correction <CORRECTION_ATTEMPT_ID>|<PLAN_ID>)

This means the user provides either --correction <CORRECTION_ATTEMPT_ID> or <PLAN_ID> as a positional argument — not both.

Expected Behavior

Both of these should work:

# Show diff for a plan by plan ID
agents plan diff 01HXM8C2ZK4Q7C2B3F2R4VYV6J

# Show diff for a specific correction attempt
agents plan diff --correction 01HXM9B7Z3Q1Q8K2E9H7K3W2M8

When --correction is provided, <PLAN_ID> should not be required.

Actual Behavior

In src/cleveragents/cli/commands/plan.py (lines 2673–2694), plan_id is defined as a mandatory positional argument:

@app.command("diff")
def plan_diff(
    plan_id: Annotated[
        str,
        typer.Argument(help="Plan ID to show diff for"),
    ],
    correction: Annotated[
        str | None,
        typer.Option(
            "--correction",
            help="Show diff for a specific correction attempt ID",
        ),
    ] = None,
    ...

This means:

agents plan diff 01HXM8C2ZK works ✓
agents plan diff --correction 01HXM9B7Z3 fails with a missing argument error because plan_id is required ✗

Users cannot use --correction alone without also providing a plan_id, which contradicts the spec.

Code Location

src/cleveragents/cli/commands/plan.py — plan_diff() function (lines 2673–2727)

Proposed Fix

Make plan_id optional and validate that exactly one of plan_id or --correction is provided:

@app.command("diff")
def plan_diff(
    plan_id: Annotated[
        str | None,
        typer.Argument(help="Plan ID to show diff for"),
    ] = None,
    correction: Annotated[
        str | None,
        typer.Option("--correction", help="Show diff for a specific correction attempt ID"),
    ] = None,
    ...
) -> None:
    if plan_id is None and correction is None:
        console.print("[red]Error:[/red] Provide either <PLAN_ID> or --correction <ID>")
        raise typer.Exit(1)
    if plan_id is not None and correction is not None:
        console.print("[red]Error:[/red] --correction and <PLAN_ID> are mutually exclusive")
        raise typer.Exit(1)
    ...

Subtasks

Write a TDD Behave scenario demonstrating agents plan diff --correction <ID> works without a positional plan_id (red test)
Update plan_diff() in src/cleveragents/cli/commands/plan.py to make plan_id optional
Add mutual exclusivity validation
Verify the TDD scenario passes (green test)
Run nox -e typecheck to confirm no type errors
Run nox -e unit_tests to confirm all scenarios pass
Run nox -e coverage_report to confirm coverage ≥ 97%

Definition of Done

agents plan diff --correction 01HXM9B7Z3 works without requiring a positional plan_id
agents plan diff 01HXM8C2ZK still works
Providing both --correction and <PLAN_ID> produces a clear error
Providing neither produces a clear error
All nox stages pass
Coverage ≥ 97%

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

## Metadata - **Branch**: `fix/plan-diff-signature` - **Commit Message**: `fix(cli): make plan diff --correction and <PLAN_ID> mutually exclusive per spec` - **Milestone**: v3.7.0 - **Parent Epic**: #397 ## Description The specification defines `agents plan diff` with mutually exclusive alternatives: ``` agents plan diff (--correction <CORRECTION_ATTEMPT_ID>|<PLAN_ID>) ``` This means the user provides **either** `--correction <CORRECTION_ATTEMPT_ID>` **or** `<PLAN_ID>` as a positional argument — not both. ### Expected Behavior Both of these should work: ```bash # Show diff for a plan by plan ID agents plan diff 01HXM8C2ZK4Q7C2B3F2R4VYV6J # Show diff for a specific correction attempt agents plan diff --correction 01HXM9B7Z3Q1Q8K2E9H7K3W2M8 ``` When `--correction` is provided, `<PLAN_ID>` should not be required. ### Actual Behavior In `src/cleveragents/cli/commands/plan.py` (lines 2673–2694), `plan_id` is defined as a **mandatory positional argument**: ```python @app.command("diff") def plan_diff( plan_id: Annotated[ str, typer.Argument(help="Plan ID to show diff for"), ], correction: Annotated[ str | None, typer.Option( "--correction", help="Show diff for a specific correction attempt ID", ), ] = None, ... ``` This means: - `agents plan diff 01HXM8C2ZK` works ✓ - `agents plan diff --correction 01HXM9B7Z3` **fails** with a missing argument error because `plan_id` is required ✗ Users cannot use `--correction` alone without also providing a `plan_id`, which contradicts the spec. ### Code Location - `src/cleveragents/cli/commands/plan.py` — `plan_diff()` function (lines 2673–2727) ### Proposed Fix Make `plan_id` optional and validate that exactly one of `plan_id` or `--correction` is provided: ```python @app.command("diff") def plan_diff( plan_id: Annotated[ str | None, typer.Argument(help="Plan ID to show diff for"), ] = None, correction: Annotated[ str | None, typer.Option("--correction", help="Show diff for a specific correction attempt ID"), ] = None, ... ) -> None: if plan_id is None and correction is None: console.print("[red]Error:[/red] Provide either <PLAN_ID> or --correction <ID>") raise typer.Exit(1) if plan_id is not None and correction is not None: console.print("[red]Error:[/red] --correction and <PLAN_ID> are mutually exclusive") raise typer.Exit(1) ... ``` ## Subtasks - [ ] Write a TDD Behave scenario demonstrating `agents plan diff --correction <ID>` works without a positional plan_id (red test) - [ ] Update `plan_diff()` in `src/cleveragents/cli/commands/plan.py` to make `plan_id` optional - [ ] Add mutual exclusivity validation - [ ] Verify the TDD scenario passes (green test) - [ ] Run `nox -e typecheck` to confirm no type errors - [ ] Run `nox -e unit_tests` to confirm all scenarios pass - [ ] Run `nox -e coverage_report` to confirm coverage ≥ 97% ## Definition of Done - [ ] `agents plan diff --correction 01HXM9B7Z3` works without requiring a positional plan_id - [ ] `agents plan diff 01HXM8C2ZK` still works - [ ] Providing both `--correction` and `<PLAN_ID>` produces a clear error - [ ] Providing neither produces a clear error - [ ] All nox stages pass - [ ] Coverage ≥ 97% --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-uat-tester

freemo referenced this issue

2026-04-03 18:43:28 +00:00

[UAT-SUPERVISOR] Progress Report — Cycle 1571 — v3.7.0 #2516

freemo commented

2026-04-03 18:46:48 +00:00

Author

Owner

Issue triaged by project owner:

State: Verified
MoSCoW: Should Have — Spec compliance or quality improvement that should be included in the milestone.

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

Issue triaged by project owner: - **State**: Verified - **MoSCoW**: Should Have — Spec compliance or quality improvement that should be included in the milestone. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: ca-project-owner

freemo referenced this issue

2026-04-03 18:54:29 +00:00

[CA-AUTO] UAT Pool Supervisor — v3.x — Session Tracker #2435

freemo added this to the v3.5.0 milestone

2026-04-05 05:06:36 +00:00