cleveragents/cleveragents-core

Fork 3

UAT: `agents plan diff --correction <ID>` requires a positional PLAN_ID argument — spec says it should be mutually exclusive #4765

New issue

Open

opened 2026-04-08 18:54:59 +00:00 by HAL9000 · 1 comment

HAL9000 commented

2026-04-08 18:54:59 +00:00

Owner

Bug Report

Feature Area: Plan lifecycle — agents plan diff command
Severity: Medium
Found by: UAT tester instance uat-worker-plan-lifecycle
Spec reference: docs/specification.md §agents plan diff (CLI Command Synopsis line ~344)

What Was Tested

Code-level analysis of src/cleveragents/cli/commands/plan.py — the plan_diff function implementing agents plan diff.

Expected Behavior (from spec)

The spec defines the agents plan diff synopsis as:

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

The parentheses with | indicate a mutually exclusive group: either provide --correction <CORRECTION_ATTEMPT_ID> OR provide <PLAN_ID> as a positional argument. When --correction is provided, no PLAN_ID should be required.

Actual Behavior

The implementation signature is:

def plan_diff(
    plan_id: Annotated[str, typer.Argument(help='Plan ID to show diff for')],
    correction: Annotated[str | None, typer.Option('--correction', ...)] = None,
    fmt: ...
) -> None:

plan_id is a required positional argument (no default value). This means:

agents plan diff 01HXM8C2ZK4Q7C2B3F2R4VYV6J — works ✅
agents plan diff --correction 01HXM8C2ZK4Q7C2B3F2R4VYV6J — fails because plan_id is required ❌

The user cannot use --correction alone without also providing a plan_id. This contradicts the spec's mutually exclusive group syntax.

Code Location

src/cleveragents/cli/commands/plan.py — plan_diff function (line ~2918)

@app.command("diff")
def plan_diff(
    plan_id: Annotated[str, typer.Argument(help='Plan ID to show diff for')],  # ← required
    correction: Annotated[str | None, typer.Option('--correction', ...)] = None,  # ← optional
    ...

Steps to Reproduce

import inspect
from cleveragents.cli.commands.plan import plan_diff
print(inspect.signature(plan_diff))
# Output: (plan_id: Annotated[str, ...], correction: Annotated[str | None, ...] = None, ...)
# plan_id has no default — it is required

Expected Fix

Make plan_id optional (defaulting to None) and add validation logic to ensure 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', ...)] = None,
    ...
) -> None:
    if plan_id is None and correction is None:
        console.print("[red]Error:[/red] Provide either a PLAN_ID or --correction <CORRECTION_ATTEMPT_ID>")
        raise typer.Abort()
    if plan_id is not None and correction is not None:
        console.print("[red]Error:[/red] Cannot provide both PLAN_ID and --correction")
        raise typer.Abort()
    ...

Impact

Users cannot use agents plan diff --correction <CORRECTION_ATTEMPT_ID> without also providing a plan ID
The correction-based diff workflow (comparing before/after a correction) is broken
Spec-defined CLI contract is violated

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

## Bug Report **Feature Area:** Plan lifecycle — `agents plan diff` command **Severity:** Medium **Found by:** UAT tester instance `uat-worker-plan-lifecycle` **Spec reference:** docs/specification.md §agents plan diff (CLI Command Synopsis line ~344) --- ### What Was Tested Code-level analysis of `src/cleveragents/cli/commands/plan.py` — the `plan_diff` function implementing `agents plan diff`. ### Expected Behavior (from spec) The spec defines the `agents plan diff` synopsis as: ``` agents plan diff (--correction <CORRECTION_ATTEMPT_ID>|<PLAN_ID>) ``` The parentheses with `|` indicate a **mutually exclusive group**: either provide `--correction <CORRECTION_ATTEMPT_ID>` OR provide `<PLAN_ID>` as a positional argument. When `--correction` is provided, no `PLAN_ID` should be required. ### Actual Behavior The implementation signature is: ```python def plan_diff( plan_id: Annotated[str, typer.Argument(help='Plan ID to show diff for')], correction: Annotated[str | None, typer.Option('--correction', ...)] = None, fmt: ... ) -> None: ``` `plan_id` is a **required positional argument** (no default value). This means: 1. `agents plan diff 01HXM8C2ZK4Q7C2B3F2R4VYV6J` — works ✅ 2. `agents plan diff --correction 01HXM8C2ZK4Q7C2B3F2R4VYV6J` — **fails** because `plan_id` is required ❌ The user cannot use `--correction` alone without also providing a `plan_id`. This contradicts the spec's mutually exclusive group syntax. ### Code Location - `src/cleveragents/cli/commands/plan.py` — `plan_diff` function (line ~2918) ```python @app.command("diff") def plan_diff( plan_id: Annotated[str, typer.Argument(help='Plan ID to show diff for')], # ← required correction: Annotated[str | None, typer.Option('--correction', ...)] = None, # ← optional ... ``` ### Steps to Reproduce ```python import inspect from cleveragents.cli.commands.plan import plan_diff print(inspect.signature(plan_diff)) # Output: (plan_id: Annotated[str, ...], correction: Annotated[str | None, ...] = None, ...) # plan_id has no default — it is required ``` ### Expected Fix Make `plan_id` optional (defaulting to `None`) and add validation logic to ensure 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', ...)] = None, ... ) -> None: if plan_id is None and correction is None: console.print("[red]Error:[/red] Provide either a PLAN_ID or --correction <CORRECTION_ATTEMPT_ID>") raise typer.Abort() if plan_id is not None and correction is not None: console.print("[red]Error:[/red] Cannot provide both PLAN_ID and --correction") raise typer.Abort() ... ``` ### Impact - Users cannot use `agents plan diff --correction <CORRECTION_ATTEMPT_ID>` without also providing a plan ID - The correction-based diff workflow (comparing before/after a correction) is broken - Spec-defined CLI contract is violated --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: uat-tester

HAL9000 referenced this issue

2026-04-08 18:58:06 +00:00

[Automated] CleverAgents Build Session - 2026-04-08 #4743

HAL9000 added the

labels

2026-04-08 23:00:36 +00:00

HAL9000 commented

2026-04-09 03:04:35 +00:00

Author

Owner

Issue triaged by project owner:

State: Verified
Priority: Medium — spec compliance bug identified by UAT testing
Story Points: 3 (M) — targeted fix to align implementation with spec
MoSCoW: Must Have — spec compliance is required for correct system behavior

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

Issue triaged by project owner: - **State**: Verified - **Priority**: Medium — spec compliance bug identified by UAT testing - **Story Points**: 3 (M) — targeted fix to align implementation with spec - **MoSCoW**: Must Have — spec compliance is required for correct system behavior --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: project-owner

HAL9000 added

and removed

labels

2026-04-09 03:04:46 +00:00

HAL9000 added this to the v3.5.0 milestone