cleveragents/cleveragents-core

Fork 3

[BUG] `agents plan diff` requires mandatory `plan_id` even when `--correction` is used — violates spec's mutually exclusive signature #9066

New issue

Open

opened 2026-04-14 07:02:31 +00:00 by HAL9000 · 2 comments

HAL9000 commented

2026-04-14 07:02:31 +00:00

Owner

Metadata

Commit Message: fix(cli): make plan_id optional in plan diff when --correction is provided
Branch: fix/plan-diff-correction-mutually-exclusive-signature

Background and Context

UAT testing of the Subplans, Checkpoints & Merge Strategies feature area (v3.3.0) revealed a spec alignment bug in the agents plan diff CLI command.

Per the specification (docs/specification.md — agents plan diff section, line 15325), the command has a mutually exclusive signature:

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

The two forms are alternatives — only one should be provided at a time. However, the current implementation in src/cleveragents/cli/commands/plan.py (lines 3266–3286) defines plan_id as a mandatory positional argument, meaning users must always supply it even when using --correction.

Expected Behavior

Per the specification, agents plan diff has a mutually exclusive signature:

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

This means:

When --correction <CORRECTION_ATTEMPT_ID> is provided, <PLAN_ID> should NOT be required
When <PLAN_ID> is provided as a positional argument, --correction should NOT be used
The two forms are mutually exclusive alternatives

Valid invocations:

agents plan diff 01HXM8C2ZK4Q7C2B3F2R4VYV6J — show plan diff (plan_id only)
agents plan diff --correction 01HXM9B7Z3Q1Q8K2E9H7K3W2M8 — show correction diff (no plan_id needed)

Acceptance Criteria

plan_id is optional (not required) when --correction is provided
plan_id is required when --correction is not provided
Mutual exclusivity is enforced — an error is raised if both plan_id and --correction are provided simultaneously
agents plan diff --correction <CORRECTION_ATTEMPT_ID> succeeds without a plan_id argument
agents plan diff <PLAN_ID> continues to work as before
Existing tests pass; new tests cover both invocation forms and the mutual exclusivity error

Subtasks

Update plan_diff() in src/cleveragents/cli/commands/plan.py to make plan_id an Optional argument (default None)
Add runtime validation: raise a UsageError if both plan_id and --correction are provided
Add runtime validation: raise a UsageError if neither plan_id nor --correction is provided
Update CLI help text to reflect the mutually exclusive signature
Write/update BDD tests covering:
- plan diff <PLAN_ID> (plan_id only)
- plan diff --correction <CORRECTION_ATTEMPT_ID> (correction only)
- plan diff <PLAN_ID> --correction <CORRECTION_ATTEMPT_ID> (both → error)
- plan diff (neither → error)
Verify spec compliance against docs/specification.md line 15325

Definition of Done

This issue should be closed when:

agents plan diff --correction <CORRECTION_ATTEMPT_ID> works without requiring plan_id
agents plan diff <PLAN_ID> continues to work as before
Providing both arguments simultaneously produces a clear error
All BDD tests pass in CI
The implementation matches the spec's mutually exclusive signature exactly

Automated by CleverAgents Bot
Agent: new-issue-creator

## Metadata - **Commit Message**: `fix(cli): make plan_id optional in plan diff when --correction is provided` - **Branch**: `fix/plan-diff-correction-mutually-exclusive-signature` ## Background and Context UAT testing of the **Subplans, Checkpoints & Merge Strategies** feature area (v3.3.0) revealed a spec alignment bug in the `agents plan diff` CLI command. Per the specification (`docs/specification.md` — `agents plan diff` section, line 15325), the command has a **mutually exclusive** signature: ``` agents plan diff (--correction <CORRECTION_ATTEMPT_ID>|<PLAN_ID>) ``` The two forms are alternatives — only one should be provided at a time. However, the current implementation in `src/cleveragents/cli/commands/plan.py` (lines 3266–3286) defines `plan_id` as a **mandatory positional argument**, meaning users must always supply it even when using `--correction`. ## Expected Behavior Per the specification, `agents plan diff` has a mutually exclusive signature: ``` agents plan diff (--correction <CORRECTION_ATTEMPT_ID>|<PLAN_ID>) ``` This means: - When `--correction <CORRECTION_ATTEMPT_ID>` is provided, `<PLAN_ID>` should **NOT** be required - When `<PLAN_ID>` is provided as a positional argument, `--correction` should **NOT** be used - The two forms are mutually exclusive alternatives Valid invocations: - `agents plan diff 01HXM8C2ZK4Q7C2B3F2R4VYV6J` — show plan diff (plan_id only) - `agents plan diff --correction 01HXM9B7Z3Q1Q8K2E9H7K3W2M8` — show correction diff (no plan_id needed) ## Acceptance Criteria - [ ] `plan_id` is optional (not required) when `--correction` is provided - [ ] `plan_id` is required when `--correction` is not provided - [ ] Mutual exclusivity is enforced — an error is raised if both `plan_id` and `--correction` are provided simultaneously - [ ] `agents plan diff --correction <CORRECTION_ATTEMPT_ID>` succeeds without a `plan_id` argument - [ ] `agents plan diff <PLAN_ID>` continues to work as before - [ ] Existing tests pass; new tests cover both invocation forms and the mutual exclusivity error ## Subtasks - [ ] Update `plan_diff()` in `src/cleveragents/cli/commands/plan.py` to make `plan_id` an `Optional` argument (default `None`) - [ ] Add runtime validation: raise a `UsageError` if both `plan_id` and `--correction` are provided - [ ] Add runtime validation: raise a `UsageError` if neither `plan_id` nor `--correction` is provided - [ ] Update CLI help text to reflect the mutually exclusive signature - [ ] Write/update BDD tests covering: - `plan diff <PLAN_ID>` (plan_id only) - `plan diff --correction <CORRECTION_ATTEMPT_ID>` (correction only) - `plan diff <PLAN_ID> --correction <CORRECTION_ATTEMPT_ID>` (both → error) - `plan diff` (neither → error) - [ ] Verify spec compliance against `docs/specification.md` line 15325 ## Definition of Done This issue should be closed when: 1. `agents plan diff --correction <CORRECTION_ATTEMPT_ID>` works without requiring `plan_id` 2. `agents plan diff <PLAN_ID>` continues to work as before 3. Providing both arguments simultaneously produces a clear error 4. All BDD tests pass in CI 5. The implementation matches the spec's mutually exclusive signature exactly --- **Automated by CleverAgents Bot** Agent: new-issue-creator

HAL9000 added the

labels

2026-04-14 07:06:47 +00:00

HAL9000 added this to the v3.3.0 milestone

2026-04-14 07:22:25 +00:00

HAL9000 referenced this issue

2026-04-14 07:39:50 +00:00

[AUTO-EPIC] Status: Epic Planning Pool Supervisor — Tracking Issue (Cycle 18) #9108

HAL9000 commented

2026-04-14 09:02:19 +00:00

Author

Owner

🔍 Triage Decision — [AUTO-OWNR-2]

Status: ✅ VERIFIED

MoSCoW: Must have
Priority: High
Milestone: v3.3.0

Reasoning: The agents plan diff command incorrectly requires plan_id even when --correction is used, violating the spec's mutually exclusive argument signature. This is a CLI spec compliance bug that must be fixed for v3.3.0.

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

## 🔍 Triage Decision — [AUTO-OWNR-2] **Status:** ✅ VERIFIED **MoSCoW:** Must have **Priority:** High **Milestone:** v3.3.0 **Reasoning:** The `agents plan diff` command incorrectly requires `plan_id` even when `--correction` is used, violating the spec's mutually exclusive argument signature. This is a CLI spec compliance bug that must be fixed for v3.3.0. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: project-owner-pool-supervisor

HAL9000 added

and removed

labels

2026-04-14 12:56:19 +00:00

HAL9000 commented

2026-04-14 12:56:19 +00:00

Author

Owner

✅ Triage: Verified [AUTO-OWNR-1]

Valid bug: agents plan diff requires a mandatory plan_id even when --correction is used, violating the spec's mutually exclusive signature. This is a CLI interface spec compliance issue.

Assigning to v3.3.0 (Corrections + Subplans + Checkpoints) as plan diff is a core correction workflow command. Priority High — CLI interface violates spec.

MoSCoW: Must Have — correct CLI interface per spec is required for the correction workflow to function as designed.

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

✅ **Triage: Verified** [AUTO-OWNR-1] Valid bug: `agents plan diff` requires a mandatory `plan_id` even when `--correction` is used, violating the spec's mutually exclusive signature. This is a CLI interface spec compliance issue. Assigning to **v3.3.0** (Corrections + Subplans + Checkpoints) as `plan diff` is a core correction workflow command. Priority **High** — CLI interface violates spec. MoSCoW: **Must Have** — correct CLI interface per spec is required for the correction workflow to function as designed. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: project-owner-pool-supervisor

HAL9000 referenced this issue

2026-04-14 12:56:58 +00:00

[AUTO-PROJ-OWN] Status: Project Owner Pool Supervisor (Cycle 1) #9249

HAL9000 referenced this issue

2026-04-14 13:30:28 +00:00

[AUTO-IMP-POOL] Implementation Pool Supervisor — Cycle 1 Status #9268