cleveragents/cleveragents-core

Fork 3

UAT: `agents plan rollback` makes CHECKPOINT_ID optional but spec requires it as a positional argument #4772

New issue

Open

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

HAL9000 commented

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

Owner

Bug Report

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

What Was Tested

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

Expected Behavior (from spec)

The spec defines the agents plan rollback synopsis as:

agents plan rollback [--yes|-y] <PLAN_ID> <CHECKPOINT_ID>

Both <PLAN_ID> and <CHECKPOINT_ID> are required positional arguments. The command should fail with a clear error if CHECKPOINT_ID is not provided.

Actual Behavior

The implementation signature is:

def rollback_plan(
    plan_id: Annotated[str, typer.Argument(help='Plan ID to rollback')],
    checkpoint_id: Annotated[str | None, typer.Argument(help='Checkpoint ID to restore (positional)')] = None,
    to_checkpoint: Annotated[str | None, typer.Option('--to-checkpoint', ...)] = None,
    yes: Annotated[bool, typer.Option('--yes', '-y', ...)] = False,
    fmt: ...
) -> None:

checkpoint_id is an optional positional argument (defaults to None). The implementation also adds a --to-checkpoint named option as an alternative way to specify the checkpoint. This means:

agents plan rollback <PLAN_ID> <CHECKPOINT_ID> — works ✅
agents plan rollback <PLAN_ID> — accepted without error ❌ (spec requires CHECKPOINT_ID)
agents plan rollback <PLAN_ID> --to-checkpoint <CHECKPOINT_ID> — works (extension, not in spec)

The spec requires CHECKPOINT_ID as a mandatory positional argument. The implementation makes it optional, which means users can invoke the command without specifying which checkpoint to restore to, leading to ambiguous behavior.

Code Location

src/cleveragents/cli/commands/plan.py — rollback_plan function (line ~3532)

@app.command("rollback")
def rollback_plan(
    plan_id: Annotated[str, typer.Argument(...)],
    checkpoint_id: Annotated[str | None, typer.Argument(...)] = None,  # ← should be required
    to_checkpoint: Annotated[str | None, typer.Option('--to-checkpoint', ...)] = None,  # ← extension
    ...

Steps to Reproduce

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

Expected Fix

Make checkpoint_id a required positional argument per the spec:

@app.command("rollback")
def rollback_plan(
    plan_id: Annotated[str, typer.Argument(help='Plan ID to rollback')],
    checkpoint_id: Annotated[str, typer.Argument(help='Checkpoint ID to restore')],  # required
    yes: Annotated[bool, typer.Option('--yes', '-y', ...)] = False,
    fmt: ...
) -> None:

The --to-checkpoint named option extension is acceptable as an additional convenience, but checkpoint_id as a positional arg should remain required.

Impact

Users can invoke agents plan rollback <PLAN_ID> without specifying a checkpoint, leading to undefined behavior
The spec-defined CLI contract is violated
Rollback without a target checkpoint is ambiguous — should the system roll back to the latest checkpoint? The spec doesn't define this behavior.

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

## Bug Report **Feature Area:** Plan lifecycle — `agents plan rollback` command **Severity:** Medium **Found by:** UAT tester instance `uat-worker-plan-lifecycle` **Spec reference:** docs/specification.md §agents plan rollback (CLI Command Synopsis line ~346) --- ### What Was Tested Code-level analysis of `src/cleveragents/cli/commands/plan.py` — the `rollback_plan` function implementing `agents plan rollback`. ### Expected Behavior (from spec) The spec defines the `agents plan rollback` synopsis as: ``` agents plan rollback [--yes|-y] <PLAN_ID> <CHECKPOINT_ID> ``` Both `<PLAN_ID>` and `<CHECKPOINT_ID>` are **required positional arguments**. The command should fail with a clear error if `CHECKPOINT_ID` is not provided. ### Actual Behavior The implementation signature is: ```python def rollback_plan( plan_id: Annotated[str, typer.Argument(help='Plan ID to rollback')], checkpoint_id: Annotated[str | None, typer.Argument(help='Checkpoint ID to restore (positional)')] = None, to_checkpoint: Annotated[str | None, typer.Option('--to-checkpoint', ...)] = None, yes: Annotated[bool, typer.Option('--yes', '-y', ...)] = False, fmt: ... ) -> None: ``` `checkpoint_id` is an **optional positional argument** (defaults to `None`). The implementation also adds a `--to-checkpoint` named option as an alternative way to specify the checkpoint. This means: 1. `agents plan rollback <PLAN_ID> <CHECKPOINT_ID>` — works ✅ 2. `agents plan rollback <PLAN_ID>` — **accepted without error** ❌ (spec requires CHECKPOINT_ID) 3. `agents plan rollback <PLAN_ID> --to-checkpoint <CHECKPOINT_ID>` — works (extension, not in spec) The spec requires `CHECKPOINT_ID` as a mandatory positional argument. The implementation makes it optional, which means users can invoke the command without specifying which checkpoint to restore to, leading to ambiguous behavior. ### Code Location - `src/cleveragents/cli/commands/plan.py` — `rollback_plan` function (line ~3532) ```python @app.command("rollback") def rollback_plan( plan_id: Annotated[str, typer.Argument(...)], checkpoint_id: Annotated[str | None, typer.Argument(...)] = None, # ← should be required to_checkpoint: Annotated[str | None, typer.Option('--to-checkpoint', ...)] = None, # ← extension ... ``` ### Steps to Reproduce ```python import inspect from cleveragents.cli.commands.plan import rollback_plan print(inspect.signature(rollback_plan)) # Output: (plan_id: ..., checkpoint_id: Annotated[str | None, ...] = None, ...) # checkpoint_id has default None — it is optional ``` ### Expected Fix Make `checkpoint_id` a required positional argument per the spec: ```python @app.command("rollback") def rollback_plan( plan_id: Annotated[str, typer.Argument(help='Plan ID to rollback')], checkpoint_id: Annotated[str, typer.Argument(help='Checkpoint ID to restore')], # required yes: Annotated[bool, typer.Option('--yes', '-y', ...)] = False, fmt: ... ) -> None: ``` The `--to-checkpoint` named option extension is acceptable as an additional convenience, but `checkpoint_id` as a positional arg should remain required. ### Impact - Users can invoke `agents plan rollback <PLAN_ID>` without specifying a checkpoint, leading to undefined behavior - The spec-defined CLI contract is violated - Rollback without a target checkpoint is ambiguous — should the system roll back to the latest checkpoint? The spec doesn't define this behavior. --- **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 referenced this issue

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

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

HAL9000 added the

labels

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

HAL9000 commented

2026-04-09 03:04:10 +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:23 +00:00

HAL9000 added this to the v3.5.0 milestone