UAT: `agents plan rollback` makes `<CHECKPOINT_ID>` optional — spec requires it as a mandatory positional argument #2511

New issue

Open

opened 2026-04-03 18:42:15 +00:00 by freemo · 1 comment

freemo commented

2026-04-03 18:42:15 +00:00

Owner

Metadata

Branch: fix/plan-rollback-checkpoint-id-required
Commit Message: fix(cli): make <CHECKPOINT_ID> required for plan rollback per spec
Milestone: v3.7.0
Parent Epic: #397

Description

The specification defines <CHECKPOINT_ID> as a required positional argument for agents plan rollback:

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

Both <PLAN_ID> and <CHECKPOINT_ID> are required positional arguments.

Expected Behavior

# Required: must provide both plan ID and checkpoint ID
agents plan rollback 01HXM8C2ZK4Q7C2B3F2R4VYV6J 01HXM9B7Z3Q1Q8K2E9H7K3W2M8
agents plan rollback --yes 01HXM8C2ZK4Q7C2B3F2R4VYV6J 01HXM9B7Z3Q1Q8K2E9H7K3W2M8

# Should fail with clear error: checkpoint ID missing
agents plan rollback 01HXM8C2ZK4Q7C2B3F2R4VYV6J  # ERROR: missing required argument <CHECKPOINT_ID>

Actual Behavior

In src/cleveragents/cli/commands/plan.py (lines 3286–3318), checkpoint_id is defined as an optional positional argument:

@app.command("rollback")
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",
            help="Checkpoint ID to restore (named option)",
        ),
    ] = None,
    ...

The implementation accepts checkpoint_id as optional (can be None) and also adds a --to-checkpoint named option as an alternative. This deviates from the spec which requires <CHECKPOINT_ID> as a mandatory positional argument.

When neither checkpoint_id nor --to-checkpoint is provided, the command fails with a runtime error rather than a clear CLI validation error.

Code Location

src/cleveragents/cli/commands/plan.py — rollback_plan() (lines 3286–3455)

Proposed Fix

Make checkpoint_id a required positional argument:

@app.command("rollback")
def rollback_plan(
    plan_id: Annotated[
        str,
        typer.Argument(help="Plan ID to rollback (ULID)"),
    ],
    checkpoint_id: Annotated[
        str,
        typer.Argument(help="Checkpoint ID to restore (ULID)"),
    ],
    yes: Annotated[
        bool,
        typer.Option("--yes", "-y", help="Skip confirmation prompt"),
    ] = False,
    ...

The --to-checkpoint named option can be removed or kept as a deprecated alias.

Subtasks

Write a TDD Behave scenario demonstrating that agents plan rollback <PLAN_ID> without a checkpoint ID produces a clear error (red test)
Update rollback_plan() in src/cleveragents/cli/commands/plan.py to make checkpoint_id required
Remove or deprecate the --to-checkpoint named option
Verify the TDD scenario passes (green test)
Run nox -e typecheck to confirm no type errors
Run nox -e unit_tests to confirm all scenarios pass
Run nox -e coverage_report to confirm coverage ≥ 97%

Definition of Done

agents plan rollback <PLAN_ID> without a checkpoint ID produces a clear "missing argument" error
agents plan rollback <PLAN_ID> <CHECKPOINT_ID> still works correctly
All nox stages pass
Coverage ≥ 97%

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

## Metadata - **Branch**: `fix/plan-rollback-checkpoint-id-required` - **Commit Message**: `fix(cli): make <CHECKPOINT_ID> required for plan rollback per spec` - **Milestone**: v3.7.0 - **Parent Epic**: #397 ## Description The specification defines `<CHECKPOINT_ID>` as a **required** positional argument for `agents plan rollback`: ``` agents plan rollback [--yes|-y] <PLAN_ID> <CHECKPOINT_ID> ``` Both `<PLAN_ID>` and `<CHECKPOINT_ID>` are required positional arguments. ### Expected Behavior ```bash # Required: must provide both plan ID and checkpoint ID agents plan rollback 01HXM8C2ZK4Q7C2B3F2R4VYV6J 01HXM9B7Z3Q1Q8K2E9H7K3W2M8 agents plan rollback --yes 01HXM8C2ZK4Q7C2B3F2R4VYV6J 01HXM9B7Z3Q1Q8K2E9H7K3W2M8 # Should fail with clear error: checkpoint ID missing agents plan rollback 01HXM8C2ZK4Q7C2B3F2R4VYV6J # ERROR: missing required argument <CHECKPOINT_ID> ``` ### Actual Behavior In `src/cleveragents/cli/commands/plan.py` (lines 3286–3318), `checkpoint_id` is defined as an **optional** positional argument: ```python @app.command("rollback") 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", help="Checkpoint ID to restore (named option)", ), ] = None, ... ``` The implementation accepts `checkpoint_id` as optional (can be None) and also adds a `--to-checkpoint` named option as an alternative. This deviates from the spec which requires `<CHECKPOINT_ID>` as a mandatory positional argument. When neither `checkpoint_id` nor `--to-checkpoint` is provided, the command fails with a runtime error rather than a clear CLI validation error. ### Code Location - `src/cleveragents/cli/commands/plan.py` — `rollback_plan()` (lines 3286–3455) ### Proposed Fix Make `checkpoint_id` a required positional argument: ```python @app.command("rollback") def rollback_plan( plan_id: Annotated[ str, typer.Argument(help="Plan ID to rollback (ULID)"), ], checkpoint_id: Annotated[ str, typer.Argument(help="Checkpoint ID to restore (ULID)"), ], yes: Annotated[ bool, typer.Option("--yes", "-y", help="Skip confirmation prompt"), ] = False, ... ``` The `--to-checkpoint` named option can be removed or kept as a deprecated alias. ## Subtasks - [ ] Write a TDD Behave scenario demonstrating that `agents plan rollback <PLAN_ID>` without a checkpoint ID produces a clear error (red test) - [ ] Update `rollback_plan()` in `src/cleveragents/cli/commands/plan.py` to make `checkpoint_id` required - [ ] Remove or deprecate the `--to-checkpoint` named option - [ ] Verify the TDD scenario passes (green test) - [ ] Run `nox -e typecheck` to confirm no type errors - [ ] Run `nox -e unit_tests` to confirm all scenarios pass - [ ] Run `nox -e coverage_report` to confirm coverage ≥ 97% ## Definition of Done - [ ] `agents plan rollback <PLAN_ID>` without a checkpoint ID produces a clear "missing argument" error - [ ] `agents plan rollback <PLAN_ID> <CHECKPOINT_ID>` still works correctly - [ ] All nox stages pass - [ ] Coverage ≥ 97% --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-uat-tester

freemo referenced this issue

2026-04-03 18:43:28 +00:00

[UAT-SUPERVISOR] Progress Report — Cycle 1571 — v3.7.0 #2516

freemo commented

2026-04-03 18:46:49 +00:00

Author

Owner

Issue triaged by project owner:

State: Verified
MoSCoW: Should Have — Spec compliance or quality improvement that should be included in the milestone.

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

Issue triaged by project owner: - **State**: Verified - **MoSCoW**: Should Have — Spec compliance or quality improvement that should be included in the milestone. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: ca-project-owner

freemo referenced this issue

2026-04-03 18:54:29 +00:00

[CA-AUTO] UAT Pool Supervisor — v3.x — Session Tracker #2435

freemo referenced this issue

2026-04-05 02:58:20 +00:00

UAT: agents plan rollback has undocumented --to-checkpoint option not in spec — spec only defines <PLAN_ID> <CHECKPOINT_ID> positional arguments #2964

freemo added this to the v3.5.0 milestone

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