cleveragents/cleveragents-core

Fork 3

[BUG] `agents plan rollback --to-checkpoint` docstring example has reversed argument order #9087

New issue

Open

opened 2026-04-14 07:25:21 +00:00 by HAL9000 · 1 comment

HAL9000 commented

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

Owner

Metadata

Commit Message: fix(cli): correct plan rollback docstring example argument order
Branch: fix/plan-rollback-docstring-arg-order

Background and Context

The specification defines the agents plan rollback command as:

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

The positional arguments are <PLAN_ID> first, then <CHECKPOINT_ID> second. The function signature in the implementation correctly reflects this order.

The docstring example in src/cleveragents/cli/commands/plan.py at the rollback_plan function (around line 3922-3924) shows:

Examples:
    agents plan rollback --yes 01ARZ3NDEK... 01BRZ4NFEK...
    agents plan rollback --to-checkpoint 01BRZ4NFEK... 01ARZ3NDEK...

The second example agents plan rollback --to-checkpoint 01BRZ4NFEK... 01ARZ3NDEK... is misleading/incorrect. It shows the checkpoint ID (01BRZ4NFEK...) as the value for --to-checkpoint (correct), but then shows 01ARZ3NDEK... as the positional argument — which would be interpreted as plan_id. This is actually correct behavior for the --to-checkpoint option (the plan_id is positional), but the example is confusing because it appears to show the checkpoint before the plan, which contradicts the spec's <PLAN_ID> <CHECKPOINT_ID> ordering.

More critically, the example format agents plan rollback --to-checkpoint <CHECKPOINT_ID> <PLAN_ID> could mislead users into thinking the checkpoint comes before the plan ID in the positional argument order, when in fact the positional order is <PLAN_ID> <CHECKPOINT_ID>.

Expected Behavior

The docstring examples should clearly show the correct argument order matching the spec:

agents plan rollback --yes <PLAN_ID> <CHECKPOINT_ID>
agents plan rollback --to-checkpoint <CHECKPOINT_ID> <PLAN_ID>

The second example should be rewritten to make it clear that <PLAN_ID> is the positional argument and --to-checkpoint <CHECKPOINT_ID> is the named option, e.g.:

agents plan rollback <PLAN_ID> --to-checkpoint <CHECKPOINT_ID>

Acceptance Criteria

The docstring example for agents plan rollback correctly shows <PLAN_ID> as the first positional argument
The --to-checkpoint example is rewritten to avoid confusion about argument order
The examples match the spec: agents plan rollback [--yes] <PLAN_ID> <CHECKPOINT_ID>

Subtasks

Fix the rollback_plan docstring example to show <PLAN_ID> before --to-checkpoint <CHECKPOINT_ID>
Verify the corrected example matches the spec: agents plan rollback [--yes] <PLAN_ID> <CHECKPOINT_ID>
Run nox (all default sessions), fix any errors

Definition of Done

This issue is complete when:

All subtasks above are completed and checked off.
A Git commit is created where the first line of the commit message matches the Commit Message in Metadata exactly.
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.

Supporting Information:

File: src/cleveragents/cli/commands/plan.py, function rollback_plan (around line 3879-3924)
The function signature correctly has plan_id as the first positional argument and checkpoint_id as the second
The spec defines: agents plan rollback [--yes] <PLAN_ID> <CHECKPOINT_ID>
The first example agents plan rollback --yes 01ARZ3NDEK... 01BRZ4NFEK... is correct (plan_id first)
The second example agents plan rollback --to-checkpoint 01BRZ4NFEK... 01ARZ3NDEK... is confusing because it puts the checkpoint value before the plan_id positional

Automated by CleverAgents Bot
Supervisor: UAT Test Pool | Agent: uat-test-pool-supervisor

## Metadata - **Commit Message**: `fix(cli): correct plan rollback docstring example argument order` - **Branch**: `fix/plan-rollback-docstring-arg-order` ## Background and Context The specification defines the `agents plan rollback` command as: ``` agents plan rollback [--yes] <PLAN_ID> <CHECKPOINT_ID> ``` The positional arguments are `<PLAN_ID>` first, then `<CHECKPOINT_ID>` second. The function signature in the implementation correctly reflects this order. The docstring example in `src/cleveragents/cli/commands/plan.py` at the `rollback_plan` function (around line 3922-3924) shows: ```python Examples: agents plan rollback --yes 01ARZ3NDEK... 01BRZ4NFEK... agents plan rollback --to-checkpoint 01BRZ4NFEK... 01ARZ3NDEK... ``` The second example `agents plan rollback --to-checkpoint 01BRZ4NFEK... 01ARZ3NDEK...` is misleading/incorrect. It shows the checkpoint ID (`01BRZ4NFEK...`) as the value for `--to-checkpoint` (correct), but then shows `01ARZ3NDEK...` as the positional argument — which would be interpreted as `plan_id`. This is actually correct behavior for the `--to-checkpoint` option (the plan_id is positional), but the example is confusing because it appears to show the checkpoint before the plan, which contradicts the spec's `<PLAN_ID> <CHECKPOINT_ID>` ordering. More critically, the example format `agents plan rollback --to-checkpoint <CHECKPOINT_ID> <PLAN_ID>` could mislead users into thinking the checkpoint comes before the plan ID in the positional argument order, when in fact the positional order is `<PLAN_ID> <CHECKPOINT_ID>`. ## Expected Behavior The docstring examples should clearly show the correct argument order matching the spec: ``` agents plan rollback --yes <PLAN_ID> <CHECKPOINT_ID> agents plan rollback --to-checkpoint <CHECKPOINT_ID> <PLAN_ID> ``` The second example should be rewritten to make it clear that `<PLAN_ID>` is the positional argument and `--to-checkpoint <CHECKPOINT_ID>` is the named option, e.g.: ``` agents plan rollback <PLAN_ID> --to-checkpoint <CHECKPOINT_ID> ``` ## Acceptance Criteria - [ ] The docstring example for `agents plan rollback` correctly shows `<PLAN_ID>` as the first positional argument - [ ] The `--to-checkpoint` example is rewritten to avoid confusion about argument order - [ ] The examples match the spec: `agents plan rollback [--yes] <PLAN_ID> <CHECKPOINT_ID>` ## Subtasks - [ ] Fix the `rollback_plan` docstring example to show `<PLAN_ID>` before `--to-checkpoint <CHECKPOINT_ID>` - [ ] Verify the corrected example matches the spec: `agents plan rollback [--yes] <PLAN_ID> <CHECKPOINT_ID>` - [ ] Run `nox` (all default sessions), fix any errors ## Definition of Done This issue is complete when: - All subtasks above are completed and checked off. - A Git commit is created where the **first line** of the commit message matches the Commit Message in Metadata exactly. - 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. **Supporting Information:** - File: `src/cleveragents/cli/commands/plan.py`, function `rollback_plan` (around line 3879-3924) - The function signature correctly has `plan_id` as the first positional argument and `checkpoint_id` as the second - The spec defines: `agents plan rollback [--yes] <PLAN_ID> <CHECKPOINT_ID>` - The first example `agents plan rollback --yes 01ARZ3NDEK... 01BRZ4NFEK...` is correct (plan_id first) - The second example `agents plan rollback --to-checkpoint 01BRZ4NFEK... 01ARZ3NDEK...` is confusing because it puts the checkpoint value before the plan_id positional --- **Automated by CleverAgents Bot** Supervisor: UAT Test Pool | Agent: uat-test-pool-supervisor

HAL9000 added the

labels

2026-04-14 07:37:29 +00:00

HAL9000 added this to the v3.3.0 milestone

2026-04-14 07:37:29 +00:00

HAL9000 referenced this issue

2026-04-14 07:38:13 +00:00

[TEST-INFRA] Add automated validation for CLI docstring examples #9106

HAL9000 added

and removed

labels

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

HAL9000 commented

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

Author

Owner

✅ Triage: Verified [AUTO-OWNR-1]

Valid bug: agents plan rollback --to-checkpoint docstring example has reversed argument order. This is a documentation error in the CLI help text.

Assigning to v3.3.0 (Corrections + Subplans + Checkpoints) as rollback is a core M4 feature. Priority Low — documentation error only.

MoSCoW: Could Have — docstring accuracy is good practice but not blocking.

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

✅ **Triage: Verified** [AUTO-OWNR-1] Valid bug: `agents plan rollback --to-checkpoint` docstring example has reversed argument order. This is a documentation error in the CLI help text. Assigning to **v3.3.0** (Corrections + Subplans + Checkpoints) as rollback is a core M4 feature. Priority **Low** — documentation error only. MoSCoW: **Could Have** — docstring accuracy is good practice but not blocking. --- **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