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

New issue

Open

opened 2026-04-05 02:58:20 +00:00 by freemo · 1 comment

freemo commented

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

Owner

Metadata

Branch: fix/plan-rollback-undocumented-to-checkpoint-option
Commit Message: fix(cli): remove undocumented --to-checkpoint option from plan rollback command
Milestone: v3.3.0
Parent Epic: #362

Background

The agents plan rollback command implementation adds an undocumented --to-checkpoint named option that is not present in the specification. The spec defines the command signature as:

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

Only --yes (or -y) is a valid option. The implementation adds --to-checkpoint as an alternative way to specify the checkpoint ID, which is not in the spec.

Expected behavior (from spec, line 15950):

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

Only --yes option is allowed. <CHECKPOINT_ID> must be a mandatory positional argument.

Actual behavior:
In src/cleveragents/cli/commands/plan.py lines 3332–3338:

to_checkpoint: Annotated[
    str | None,
    typer.Option(
        "--to-checkpoint",
        help="Checkpoint ID to restore (named option)",
    ),
] = None,

The --to-checkpoint option is not documented in the spec and creates an inconsistency with the spec-defined interface. Additionally, the checkpoint_id positional argument is made optional (defaulting to None) when either checkpoint_id or to_checkpoint is provided, which is a separate deviation from the spec (see also issue #2511).

Code location:

src/cleveragents/cli/commands/plan.py lines 3328–3338

Steps to reproduce:

Run agents plan rollback --help
Observe --to-checkpoint option listed (not in spec)
Run agents plan rollback <PLAN_ID> --to-checkpoint <CHECKPOINT_ID> — this works but is not spec-compliant

Subtasks

Write a failing Behave scenario that asserts agents plan rollback --help does NOT list --to-checkpoint
Write a failing Behave scenario that asserts agents plan rollback <PLAN_ID> --to-checkpoint <ID> raises an error (unrecognised option)
Remove the to_checkpoint parameter (lines 3332–3338) from the plan rollback command in src/cleveragents/cli/commands/plan.py
Ensure checkpoint_id positional argument is mandatory (not optional) per spec
Update any internal logic that references to_checkpoint to use only checkpoint_id
Verify agents plan rollback --help output matches spec exactly
Run nox to confirm all quality gates pass

Definition of Done

All subtasks are checked off
A failing test reproducing the bug is merged before the fix (TDD workflow)
agents plan rollback --help no longer lists --to-checkpoint
agents plan rollback <PLAN_ID> --to-checkpoint <ID> is rejected as an unrecognised option
checkpoint_id is a mandatory positional argument matching the spec signature
Work is committed using the exact commit message and branch name from the Metadata section
A pull request has been created, reviewed (≥2 approvals), and merged
All nox stages pass
Coverage >= 97%

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

## Metadata - **Branch**: `fix/plan-rollback-undocumented-to-checkpoint-option` - **Commit Message**: `fix(cli): remove undocumented --to-checkpoint option from plan rollback command` - **Milestone**: v3.3.0 - **Parent Epic**: #362 ## Background The `agents plan rollback` command implementation adds an undocumented `--to-checkpoint` named option that is not present in the specification. The spec defines the command signature as: ``` agents plan rollback [--yes|-y] <PLAN_ID> <CHECKPOINT_ID> ``` Only `--yes` (or `-y`) is a valid option. The implementation adds `--to-checkpoint` as an alternative way to specify the checkpoint ID, which is not in the spec. **Expected behavior** (from spec, line 15950): ``` agents plan rollback [--yes|-y] <PLAN_ID> <CHECKPOINT_ID> ``` Only `--yes` option is allowed. `<CHECKPOINT_ID>` must be a mandatory positional argument. **Actual behavior:** In `src/cleveragents/cli/commands/plan.py` lines 3332–3338: ```python to_checkpoint: Annotated[ str | None, typer.Option( "--to-checkpoint", help="Checkpoint ID to restore (named option)", ), ] = None, ``` The `--to-checkpoint` option is not documented in the spec and creates an inconsistency with the spec-defined interface. Additionally, the `checkpoint_id` positional argument is made optional (defaulting to `None`) when either `checkpoint_id` or `to_checkpoint` is provided, which is a separate deviation from the spec (see also issue #2511). **Code location:** - `src/cleveragents/cli/commands/plan.py` lines 3328–3338 **Steps to reproduce:** 1. Run `agents plan rollback --help` 2. Observe `--to-checkpoint` option listed (not in spec) 3. Run `agents plan rollback <PLAN_ID> --to-checkpoint <CHECKPOINT_ID>` — this works but is not spec-compliant ## Subtasks - [ ] Write a failing Behave scenario that asserts `agents plan rollback --help` does NOT list `--to-checkpoint` - [ ] Write a failing Behave scenario that asserts `agents plan rollback <PLAN_ID> --to-checkpoint <ID>` raises an error (unrecognised option) - [ ] Remove the `to_checkpoint` parameter (lines 3332–3338) from the `plan rollback` command in `src/cleveragents/cli/commands/plan.py` - [ ] Ensure `checkpoint_id` positional argument is mandatory (not optional) per spec - [ ] Update any internal logic that references `to_checkpoint` to use only `checkpoint_id` - [ ] Verify `agents plan rollback --help` output matches spec exactly - [ ] Run `nox` to confirm all quality gates pass ## Definition of Done - [ ] All subtasks are checked off - [ ] A failing test reproducing the bug is merged before the fix (TDD workflow) - [ ] `agents plan rollback --help` no longer lists `--to-checkpoint` - [ ] `agents plan rollback <PLAN_ID> --to-checkpoint <ID>` is rejected as an unrecognised option - [ ] `checkpoint_id` is a mandatory positional argument matching the spec signature - [ ] Work is committed using the exact commit message and branch name from the Metadata section - [ ] A pull request has been created, reviewed (≥2 approvals), and merged - [ ] All nox stages pass - [ ] Coverage >= 97% --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-new-issue-creator

freemo added this to the v3.3.0 milestone

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

freemo added a new dependency

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

#362 Epic: Security & Safety Hardening

freemo commented

2026-04-05 03:00:24 +00:00

Author

Owner

Issue triaged by project owner:

State: Verified
Priority: Low (confirmed)
MoSCoW: Could Have — undocumented option, low impact

Valid finding verified during batch triage.

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

Issue triaged by project owner: - **State**: Verified - **Priority**: Low (confirmed) - **MoSCoW**: Could Have — undocumented option, low impact Valid finding verified during batch triage. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: ca-project-owner

freemo added the

MoSCoW

Could have

label

2026-04-05 03:02:24 +00:00

freemo referenced this issue

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

[CA-AUTO] Project Owner — project-owner-1 — Session Tracker #2793

freemo referenced this issue

2026-04-05 06:15:22 +00:00

[CA-AUTO] UAT Pool Supervisor — v3.2.0–v3.7.0 — Session Tracker #3094

freemo removed this from the v3.3.0 milestone