cleveragents/cleveragents-core

Fork 3

UAT: `agents plan diff --correction <ID>` incorrectly requires positional `<PLAN_ID>` argument #2041

New issue

Open

opened 2026-04-03 03:13:36 +00:00 by freemo · 2 comments

freemo commented

2026-04-03 03:13:36 +00:00

Owner

Metadata

Branch: fix/plan-diff-correction-mutually-exclusive-arg
Commit Message: fix(cli): make plan_id optional when --correction is provided in plan diff
Milestone: v3.7.0
Parent Epic: #358

Description

The agents plan diff command requires a positional <PLAN_ID> argument even when --correction is provided. According to the specification (§15322–15332), --correction and <PLAN_ID> are mutually exclusive — the user provides one OR the other, never both.

Spec-Defined Command Signature

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

This is a mutually exclusive group:

agents plan diff <PLAN_ID> — show diff for a plan
agents plan diff --correction <CORRECTION_ATTEMPT_ID> — show diff for a correction attempt (no plan_id needed)

The spec example (§15322–15332) shows:

$ agents plan diff --correction 01HXM9B7Z3Q1Q8K2E9H7K3W2M8

(no plan_id argument)

Actual Behavior

The implementation in src/cleveragents/cli/commands/plan.py (line ~2725) defines plan_id as a required positional argument:

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

This forces users to supply a dummy plan_id even when using --correction:

# This fails (missing required plan_id):
agents plan diff --correction 01HXM9B7Z3Q1Q8K2E9H7K3W2M8

# User is forced to provide a meaningless dummy:
agents plan diff DUMMY_PLAN_ID --correction 01HXM9B7Z3Q1Q8K2E9H7K3W2M8

Steps to Reproduce

Run agents plan diff --correction <some_correction_id>
Observe the command fails with "Missing argument 'PLAN_ID'"

Code Location

src/cleveragents/cli/commands/plan.py, function plan_diff (line ~2725)

Subtasks

Make plan_id optional (str | None, default None) in plan_diff
Add runtime validation: exactly one of plan_id or --correction must be provided (mutually exclusive)
Update error messages when neither or both are provided (clear, actionable messages)
Write BDD (Behave) TDD issue-capture scenario tagged @tdd_expected_fail demonstrating the bug before the fix
Write BDD scenarios covering all four cases: plan_id only, --correction only, both provided (error), neither provided (error)

Definition of Done

agents plan diff --correction <ID> works without a plan_id argument
agents plan diff <PLAN_ID> still works as before
Providing both <PLAN_ID> and --correction produces a clear, user-friendly error
Providing neither <PLAN_ID> nor --correction produces a clear, user-friendly error
All new behaviour is covered by BDD scenarios in features/
All existing tests pass
All nox stages pass (nox -e lint, nox -e typecheck, nox -e unit_tests, nox -e integration_tests)
Coverage >= 97%

Automated by CleverAgents Bot
Supervisor: UAT Testing | Agent: ca-new-issue-creator

## Metadata - **Branch**: `fix/plan-diff-correction-mutually-exclusive-arg` - **Commit Message**: `fix(cli): make plan_id optional when --correction is provided in plan diff` - **Milestone**: v3.7.0 - **Parent Epic**: #358 ## Description The `agents plan diff` command requires a positional `<PLAN_ID>` argument even when `--correction` is provided. According to the specification (§15322–15332), `--correction` and `<PLAN_ID>` are **mutually exclusive** — the user provides one OR the other, never both. ### Spec-Defined Command Signature ``` agents plan diff (--correction <CORRECTION_ATTEMPT_ID>|<PLAN_ID>) ``` This is a mutually exclusive group: - `agents plan diff <PLAN_ID>` — show diff for a plan - `agents plan diff --correction <CORRECTION_ATTEMPT_ID>` — show diff for a correction attempt (**no `plan_id` needed**) The spec example (§15322–15332) shows: ```bash $ agents plan diff --correction 01HXM9B7Z3Q1Q8K2E9H7K3W2M8 ``` (no `plan_id` argument) ### Actual Behavior The implementation in `src/cleveragents/cli/commands/plan.py` (line ~2725) defines `plan_id` as a **required** positional argument: ```python @app.command("diff") def plan_diff( plan_id: Annotated[ str, typer.Argument(help="Plan ID to show diff for"), # REQUIRED positional ], correction: Annotated[ str | None, typer.Option("--correction", ...), ] = None, ... ``` This forces users to supply a dummy `plan_id` even when using `--correction`: ```bash # This fails (missing required plan_id): agents plan diff --correction 01HXM9B7Z3Q1Q8K2E9H7K3W2M8 # User is forced to provide a meaningless dummy: agents plan diff DUMMY_PLAN_ID --correction 01HXM9B7Z3Q1Q8K2E9H7K3W2M8 ``` ### Steps to Reproduce 1. Run `agents plan diff --correction <some_correction_id>` 2. Observe the command fails with `"Missing argument 'PLAN_ID'"` ### Code Location `src/cleveragents/cli/commands/plan.py`, function `plan_diff` (line ~2725) ## Subtasks - [ ] Make `plan_id` optional (`str | None`, default `None`) in `plan_diff` - [ ] Add runtime validation: exactly one of `plan_id` or `--correction` must be provided (mutually exclusive) - [ ] Update error messages when neither or both are provided (clear, actionable messages) - [ ] Write BDD (Behave) TDD issue-capture scenario tagged `@tdd_expected_fail` demonstrating the bug before the fix - [ ] Write BDD scenarios covering all four cases: `plan_id` only, `--correction` only, both provided (error), neither provided (error) ## Definition of Done - [ ] `agents plan diff --correction <ID>` works without a `plan_id` argument - [ ] `agents plan diff <PLAN_ID>` still works as before - [ ] Providing both `<PLAN_ID>` and `--correction` produces a clear, user-friendly error - [ ] Providing neither `<PLAN_ID>` nor `--correction` produces a clear, user-friendly error - [ ] All new behaviour is covered by BDD scenarios in `features/` - [ ] All existing tests pass - [ ] All nox stages pass (`nox -e lint`, `nox -e typecheck`, `nox -e unit_tests`, `nox -e integration_tests`) - [ ] Coverage >= 97% --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-new-issue-creator

freemo added this to the v3.7.0 milestone

2026-04-03 03:16:40 +00:00

freemo added the

labels

2026-04-03 03:18:19 +00:00

freemo referenced this issue

2026-04-03 03:20:53 +00:00

[UAT-SUPERVISOR] Progress Report — Cycle 661 — v3.7.0 #2042

freemo added a new dependency

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

#358 Epic: Corrections + Subplans + Checkpoints (M4)

freemo referenced this issue

2026-04-03 03:30:59 +00:00

[UAT-SUPERVISOR] Progress Report — Cycle 671 — v3.7.0 #2044

freemo referenced this issue

2026-04-03 03:41:08 +00:00

[UAT-SUPERVISOR] Progress Report — Cycle 681 — v3.7.0 #2049

freemo referenced this issue

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

[CA-AUTO] UAT Pool Supervisor — v3.7.0 — Session Tracker #2023

freemo referenced this issue

2026-04-03 03:57:57 +00:00

[CA-AUTO] UAT Pool Supervisor — v3.7.0 — Session Tracker #2023

freemo self-assigned this

2026-04-03 16:58:14 +00:00

freemo commented

2026-04-05 02:26:16 +00:00

Author

Owner

Label compliance fix applied:

Removed conflicting label: State/Unverified
Kept: State/Verified
Reason: Issue had two conflicting State/* labels. Per CONTRIBUTING.md, only one State/* label is permitted. Kept the more advanced state (State/Verified).

Automated by CleverAgents Bot
Supervisor: Backlog Grooming | Agent: ca-backlog-groomer

Label compliance fix applied: - Removed conflicting label: `State/Unverified` - Kept: `State/Verified` - Reason: Issue had two conflicting `State/*` labels. Per CONTRIBUTING.md, only one `State/*` label is permitted. Kept the more advanced state (`State/Verified`). --- **Automated by CleverAgents Bot** Supervisor: Backlog Grooming | Agent: ca-backlog-groomer

freemo referenced this issue

2026-04-05 02:39:08 +00:00

[CA-AUTO] Backlog Groomer — groomer-1 — Session Tracker #2771

freemo referenced this issue

2026-04-05 04:10:52 +00:00

[CA-AUTO] Backlog Groomer — groomer-1 — Session Tracker #2771

freemo commented

2026-04-05 06:32:39 +00:00

Author

Owner

Label compliance fix applied:

Removed conflicting label: State/Unverified
Retained: State/Verified
Reason: Issue had two conflicting State/* labels simultaneously. Per CONTRIBUTING.md, only one State/* label is permitted. State/Verified is the more advanced state and has been retained.

Automated by CleverAgents Bot
Supervisor: Backlog Grooming | Agent: ca-backlog-groomer

Label compliance fix applied: - Removed conflicting label: `State/Unverified` - Retained: `State/Verified` - Reason: Issue had two conflicting `State/*` labels simultaneously. Per CONTRIBUTING.md, only one `State/*` label is permitted. `State/Verified` is the more advanced state and has been retained. --- **Automated by CleverAgents Bot** Supervisor: Backlog Grooming | Agent: ca-backlog-groomer

freemo referenced this issue

2026-04-05 06:35:39 +00:00

[CA-AUTO] Backlog Groomer — groomer-1 — Session Tracker #2771