UAT: `agents plan rollback` accepts missing CHECKPOINT_ID — spec requires it as a mandatory positional argument #4068

New issue

Open

opened 2026-04-06 09:52:59 +00:00 by freemo · 0 comments

freemo commented

2026-04-06 09:52:59 +00:00

Owner

Metadata

Branch: bugfix/m4-rollback-checkpoint-id-required
Commit Message: fix(cli): make checkpoint_id a required positional argument in plan rollback
Milestone: (none — backlog)
Parent Epic: #3374

Background and Context

The specification's CLI synopsis (docs/specification.md) defines:

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

<CHECKPOINT_ID> is a required positional argument per the spec. The agents plan rollback command is a key part of the project's safety and correction model — it reverts the state of a plan's sandbox to a previously captured checkpoint, enabling course correction before agents plan apply is run.

This bug was discovered during UAT testing of the plan rollback workflow.

Current Behavior

The implementation in src/cleveragents/cli/commands/plan.py at the rollback_plan function (around line 3446) makes checkpoint_id an optional positional argument and adds a non-spec --to-checkpoint option as an alternative:

@app.command("rollback")
def rollback_plan(
    plan_id: Annotated[str, typer.Argument(...)],
    checkpoint_id: Annotated[str | None, typer.Argument(...)] = None,  # OPTIONAL — should be required
    to_checkpoint: Annotated[str | None, typer.Option("--to-checkpoint", ...)] = None,  # NOT IN SPEC
    yes: Annotated[bool, typer.Option("--yes", "-y", ...)] = False,
) -> None:

Observed issues:

agents plan rollback <PLAN_ID> (without a checkpoint ID) is accepted by the CLI with no usage error, but fails at runtime with an error about a missing checkpoint ID.
The --to-checkpoint option exists but is not defined in the spec, creating an undocumented alternative interface.

Expected Behavior

Per docs/specification.md:

agents plan rollback <PLAN_ID> <CHECKPOINT_ID> — both arguments required
agents plan rollback --yes <PLAN_ID> <CHECKPOINT_ID> — with confirmation skip
Running agents plan rollback <PLAN_ID> (without checkpoint) must fail immediately with a CLI usage error (not a runtime error)
The --to-checkpoint option must not exist

Subtasks

TDD: Add a failing Behave scenario for agents plan rollback <PLAN_ID> (without checkpoint) asserting a CLI usage error is raised
Fix: Remove = None default from checkpoint_id in rollback_plan to make it a required positional argument
Fix: Remove the non-spec --to-checkpoint option from rollback_plan
Update any existing tests that relied on the optional checkpoint_id or --to-checkpoint behavior
Verify the TDD scenario now passes after the fix
Run nox (all default sessions), fix any errors
Verify coverage >= 97% via nox -s coverage_report

Definition of Done

checkpoint_id is a required positional argument in rollback_plan (no = None default)
--to-checkpoint option is removed from rollback_plan
agents plan rollback <PLAN_ID> (without checkpoint) produces a CLI usage error immediately
agents plan rollback <PLAN_ID> <CHECKPOINT_ID> works correctly end-to-end
Behave scenario added and passing for the corrected CLI behaviour
A Git commit is created where the first line of the commit message matches the Commit Message in Metadata exactly, followed by a blank line, then additional details
The commit is pushed to the remote on the branch matching the Branch in Metadata exactly
The commit is submitted as a pull request to master, reviewed, and merged before this issue is marked done
All nox stages pass
Coverage >= 97%

Supporting Information

Code location: src/cleveragents/cli/commands/plan.py, function rollback_plan (~line 3446)
Spec reference: docs/specification.md — CLI synopsis for agents plan rollback
Architectural context: The plan rollback command reverts a plan's sandbox to a checkpoint captured during the Execute phase. Checkpoints are snapshots of the sandbox state, enabling course correction before agents plan apply merges changes into live project resources.

Backlog note: This issue was discovered during autonomous operation
on milestone v3.3.0 (M4). It does not block milestone completion and has been
placed in the backlog for human review and future milestone assignment.

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

## Metadata - **Branch**: `bugfix/m4-rollback-checkpoint-id-required` - **Commit Message**: `fix(cli): make checkpoint_id a required positional argument in plan rollback` - **Milestone**: (none — backlog) - **Parent Epic**: #3374 ## Background and Context The specification's CLI synopsis (`docs/specification.md`) defines: ``` agents plan rollback [--yes|-y] <PLAN_ID> <CHECKPOINT_ID> ``` `<CHECKPOINT_ID>` is a **required** positional argument per the spec. The `agents plan rollback` command is a key part of the project's safety and correction model — it reverts the state of a plan's sandbox to a previously captured checkpoint, enabling course correction before `agents plan apply` is run. This bug was discovered during UAT testing of the plan rollback workflow. ## Current Behavior The implementation in `src/cleveragents/cli/commands/plan.py` at the `rollback_plan` function (around line 3446) makes `checkpoint_id` an **optional** positional argument and adds a non-spec `--to-checkpoint` option as an alternative: ```python @app.command("rollback") def rollback_plan( plan_id: Annotated[str, typer.Argument(...)], checkpoint_id: Annotated[str | None, typer.Argument(...)] = None, # OPTIONAL — should be required to_checkpoint: Annotated[str | None, typer.Option("--to-checkpoint", ...)] = None, # NOT IN SPEC yes: Annotated[bool, typer.Option("--yes", "-y", ...)] = False, ) -> None: ``` **Observed issues:** - `agents plan rollback <PLAN_ID>` (without a checkpoint ID) is **accepted** by the CLI with no usage error, but fails at runtime with an error about a missing checkpoint ID. - The `--to-checkpoint` option exists but is **not defined in the spec**, creating an undocumented alternative interface. ## Expected Behavior Per `docs/specification.md`: - `agents plan rollback <PLAN_ID> <CHECKPOINT_ID>` — both arguments required - `agents plan rollback --yes <PLAN_ID> <CHECKPOINT_ID>` — with confirmation skip - Running `agents plan rollback <PLAN_ID>` (without checkpoint) **must** fail immediately with a CLI usage error (not a runtime error) - The `--to-checkpoint` option must not exist ## Subtasks - [ ] TDD: Add a failing Behave scenario for `agents plan rollback <PLAN_ID>` (without checkpoint) asserting a CLI usage error is raised - [ ] Fix: Remove `= None` default from `checkpoint_id` in `rollback_plan` to make it a required positional argument - [ ] Fix: Remove the non-spec `--to-checkpoint` option from `rollback_plan` - [ ] Update any existing tests that relied on the optional `checkpoint_id` or `--to-checkpoint` behavior - [ ] Verify the TDD scenario now passes after the fix - [ ] Run `nox` (all default sessions), fix any errors - [ ] Verify coverage >= 97% via `nox -s coverage_report` ## Definition of Done - [ ] `checkpoint_id` is a required positional argument in `rollback_plan` (no `= None` default) - [ ] `--to-checkpoint` option is removed from `rollback_plan` - [ ] `agents plan rollback <PLAN_ID>` (without checkpoint) produces a CLI usage error immediately - [ ] `agents plan rollback <PLAN_ID> <CHECKPOINT_ID>` works correctly end-to-end - [ ] Behave scenario added and passing for the corrected CLI behaviour - [ ] A Git commit is created where the **first line** of the commit message matches the Commit Message in Metadata exactly, followed by a blank line, then additional details - [ ] The commit is pushed to the remote on the branch matching the **Branch** in Metadata exactly - [ ] The commit is submitted as a **pull request** to `master`, reviewed, and **merged** before this issue is marked done - [ ] All nox stages pass - [ ] Coverage >= 97% ## Supporting Information - **Code location**: `src/cleveragents/cli/commands/plan.py`, function `rollback_plan` (~line 3446) - **Spec reference**: `docs/specification.md` — CLI synopsis for `agents plan rollback` - **Architectural context**: The `plan rollback` command reverts a plan's sandbox to a checkpoint captured during the Execute phase. Checkpoints are snapshots of the sandbox state, enabling course correction before `agents plan apply` merges changes into live project resources. > **Backlog note:** This issue was discovered during autonomous operation > on milestone v3.3.0 (M4). It does not block milestone completion and has been > placed in the backlog for human review and future milestone assignment. --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-uat-tester

freemo added a new dependency

2026-04-06 09:53:11 +00:00

#3374 Epic: E2E Workflow Specification Tests & Code Review Tool Examples

freemo added the

Points

label

2026-04-06 09:53:52 +00:00

freemo referenced this issue

2026-04-06 09:56:31 +00:00

UAT: Specification Workflow Examples 1, 9, 10, 11, 13, and 15 have no Robot Framework integration tests #4072

freemo referenced this issue

2026-04-06 09:57:30 +00:00