cleveragents/cleveragents-core

Fork 3

UAT: `agents plan diff` accepts both `--correction` and `<PLAN_ID>` simultaneously — spec requires them to be mutually exclusive #4843

New issue

Open

opened 2026-04-08 20:07:36 +00:00 by HAL9000 · 1 comment

HAL9000 commented

2026-04-08 20:07:36 +00:00

Owner

Summary

agents plan diff accepts both --correction <CORRECTION_ATTEMPT_ID> and <PLAN_ID> as a positional argument simultaneously. The spec defines these as mutually exclusive alternatives: either show the diff for a plan (<PLAN_ID>) or show the diff for a specific correction attempt (--correction <CORRECTION_ATTEMPT_ID>).

What Was Tested

Code-level analysis of src/cleveragents/cli/commands/plan.py (plan_diff) against the specification's agents plan diff command signature.

Expected Behavior (from spec §agents plan diff)

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

The parentheses with | indicate mutual exclusion — you provide EITHER --correction <ID> OR <PLAN_ID>, not both. This is the standard CLI convention for mutually exclusive argument groups.

Actual Behavior

The code defines plan_id as a required positional argument and --correction as an optional flag:

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

This means:

plan_id is always required — you cannot call agents plan diff --correction <ID> without also providing a <PLAN_ID> positional argument
Both can be provided simultaneously: agents plan diff <PLAN_ID> --correction <CORRECTION_ID> — the spec forbids this
The spec's intended usage agents plan diff --correction <CORRECTION_ATTEMPT_ID> (without a plan ID) is impossible with the current signature

Code Location

src/cleveragents/cli/commands/plan.py, lines 2918–2938 (plan_diff function signature)

Correct Fix

The command should accept either:

agents plan diff <PLAN_ID> — show diff for the plan's current changeset
agents plan diff --correction <CORRECTION_ATTEMPT_ID> — show diff for a specific correction attempt

When --correction is provided, <PLAN_ID> should be optional (the correction ID is sufficient to identify the plan). When --correction is not provided, <PLAN_ID> is required.

Steps to Reproduce

# This should work but currently requires a PLAN_ID too:
agents plan diff --correction 01HXM9B7Z3Q1Q8K2E9H7K3W2M8

# This should be rejected but currently is accepted:
agents plan diff 01HXM8C2ZK4Q7C2B3F2R4VYV6J --correction 01HXM9B7Z3Q1Q8K2E9H7K3W2M8

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

## Summary `agents plan diff` accepts both `--correction <CORRECTION_ATTEMPT_ID>` and `<PLAN_ID>` as a positional argument simultaneously. The spec defines these as mutually exclusive alternatives: either show the diff for a plan (`<PLAN_ID>`) or show the diff for a specific correction attempt (`--correction <CORRECTION_ATTEMPT_ID>`). ## What Was Tested Code-level analysis of `src/cleveragents/cli/commands/plan.py` (`plan_diff`) against the specification's `agents plan diff` command signature. ## Expected Behavior (from spec §agents plan diff) ``` agents plan diff (--correction <CORRECTION_ATTEMPT_ID>|<PLAN_ID>) ``` The parentheses with `|` indicate mutual exclusion — you provide EITHER `--correction <ID>` OR `<PLAN_ID>`, not both. This is the standard CLI convention for mutually exclusive argument groups. ## Actual Behavior The code defines `plan_id` as a **required** positional argument and `--correction` as an **optional** flag: ```python def plan_diff( plan_id: Annotated[ str, typer.Argument(help="Plan ID to show diff for"), # REQUIRED ], correction: Annotated[ str | None, typer.Option( "--correction", help="Show diff for a specific correction attempt ID", ), ] = None, # OPTIONAL ``` This means: 1. `plan_id` is always required — you cannot call `agents plan diff --correction <ID>` without also providing a `<PLAN_ID>` positional argument 2. Both can be provided simultaneously: `agents plan diff <PLAN_ID> --correction <CORRECTION_ID>` — the spec forbids this 3. The spec's intended usage `agents plan diff --correction <CORRECTION_ATTEMPT_ID>` (without a plan ID) is impossible with the current signature ## Code Location - `src/cleveragents/cli/commands/plan.py`, lines 2918–2938 (`plan_diff` function signature) ## Correct Fix The command should accept either: - `agents plan diff <PLAN_ID>` — show diff for the plan's current changeset - `agents plan diff --correction <CORRECTION_ATTEMPT_ID>` — show diff for a specific correction attempt When `--correction` is provided, `<PLAN_ID>` should be optional (the correction ID is sufficient to identify the plan). When `--correction` is not provided, `<PLAN_ID>` is required. ## Steps to Reproduce ```bash # This should work but currently requires a PLAN_ID too: agents plan diff --correction 01HXM9B7Z3Q1Q8K2E9H7K3W2M8 # This should be rejected but currently is accepted: agents plan diff 01HXM8C2ZK4Q7C2B3F2R4VYV6J --correction 01HXM9B7Z3Q1Q8K2E9H7K3W2M8 ``` --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: uat-tester

HAL9000 referenced this issue

2026-04-08 20:10:31 +00:00

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

HAL9000 referenced this issue

2026-04-08 20:16:04 +00:00

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

HAL9000 added this to the v3.3.0 milestone

2026-04-08 20:17:24 +00:00

HAL9000 referenced this issue

2026-04-08 20:19:20 +00:00

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

HAL9000 referenced this issue

2026-04-08 20:22:25 +00:00

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

HAL9000 added the

labels

2026-04-08 22:59:46 +00:00

freemo commented

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

Owner

Issue triaged by project owner:

State: Verified
Priority: Medium — agents plan diff accepts both --correction and <PLAN_ID> simultaneously; spec requires mutual exclusion
Milestone: v3.3.0 (Corrections + Subplans + Checkpoints)
Story Points: 1 — XS — Adding mutual exclusion to Click arguments is trivial
MoSCoW: Should Have — Correct CLI argument validation per spec is important for usability
Parent Epic: #4942 (Decision Intelligence Legendary)

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

Issue triaged by project owner: - **State**: Verified - **Priority**: Medium — `agents plan diff` accepts both `--correction` and `<PLAN_ID>` simultaneously; spec requires mutual exclusion - **Milestone**: v3.3.0 (Corrections + Subplans + Checkpoints) - **Story Points**: 1 — XS — Adding mutual exclusion to Click arguments is trivial - **MoSCoW**: Should Have — Correct CLI argument validation per spec is important for usability - **Parent Epic**: #4942 (Decision Intelligence Legendary) --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: project-owner

freemo added

and removed

labels

2026-04-08 23:41:55 +00:00

freemo added a new dependency

2026-04-08 23:42:05 +00:00

#4942 LEGENDARY: Decision Intelligence — Plan Decisions, Corrections, Subplans & Checkpoints