cleveragents/cleveragents-core

Fork 3

UAT: `agents plan` missing spec-required subcommands: `tree`, `explain`, `correct`, `prompt`, `rollback` #3769

New issue

Open

opened 2026-04-05 22:34:56 +00:00 by freemo · 2 comments

freemo commented

2026-04-05 22:34:56 +00:00

Owner

Metadata

Branch: fix/plan-cli-missing-subcommands-tree-explain-correct-prompt-rollback
Commit Message: feat(cli): implement missing agents plan subcommands tree, explain, correct, prompt, rollback
Milestone: None (Backlog)
Parent Epic: #362

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

Background

During UAT testing of src/cleveragents/cli/commands/plan.py, the module docstring lists only 9 plan subcommands, but the specification requires 14 subcommands. Five spec-required subcommands are absent from the module docstring and appear to be missing from the implementation.

Expected Behavior (from spec)

Per docs/specification.md CLI Command Synopsis, the following agents plan subcommands are required:

agents plan list [--phase <PHASE>] [--state <STATE>] [--project <PROJECT>] [--action <ACTION>] [<REGEX>]
agents plan use [...] <ACTION> <PROJECT>...
agents plan execute <PLAN_ID>
agents plan apply [--yes|-y] <PLAN_ID>
agents plan status <PLAN_ID>
agents plan cancel [(--reason|-r) <REASON>] <PLAN_ID>
agents plan tree [--show-superseded] <PLAN_ID>          ← MISSING
agents plan explain [--show-context] [--show-reasoning] <DECISION_ID>  ← MISSING
agents plan correct --mode (revert|append) (--guidance|-g) <GUIDANCE> [--dry-run] [--yes|-y] <DECISION_ID>  ← MISSING
agents plan diff (--correction <CORRECTION_ATTEMPT_ID>|<PLAN_ID>)
agents plan artifacts <PLAN_ID>
agents plan prompt <PLAN_ID> <GUIDANCE>                 ← MISSING
agents plan rollback [--yes|-y] <PLAN_ID> <CHECKPOINT_ID>  ← MISSING
agents plan errors <PLAN_ID>

Actual Behavior (from code)

The src/cleveragents/cli/commands/plan.py module docstring lists only these commands:

plan use
plan list
plan status
plan execute
plan apply
plan cancel
plan diff
plan artifacts
plan errors

The following 5 spec-required commands are NOT listed in the module docstring and appear to be missing:

agents plan tree [--show-superseded] <PLAN_ID> — Render the decision tree for a plan
agents plan explain [--show-context] [--show-reasoning] <DECISION_ID> — Explain a specific decision
agents plan correct --mode (revert|append) (--guidance|-g) <GUIDANCE> [--dry-run] [--yes|-y] <DECISION_ID> — Correct a decision
agents plan prompt <PLAN_ID> <GUIDANCE> — Send guidance to an active plan
agents plan rollback [--yes|-y] <PLAN_ID> <CHECKPOINT_ID> — Rollback to a checkpoint

Code Location

src/cleveragents/cli/commands/plan.py — module docstring and command definitions

Impact

Users cannot inspect the decision tree of a plan (plan tree)
Users cannot understand why a specific decision was made (plan explain)
Users cannot correct a bad decision during plan execution (plan correct)
Users cannot send mid-execution guidance to a running plan (plan prompt)
Users cannot rollback a plan to a previous checkpoint (plan rollback)

These are core plan lifecycle management features that are critical for the v3 plan workflow.

Subtasks

Implement agents plan tree [--show-superseded] <PLAN_ID> command
Implement agents plan explain [--show-context] [--show-reasoning] <DECISION_ID> command
Implement agents plan correct --mode (revert|append) (--guidance|-g) <GUIDANCE> [--dry-run] [--yes|-y] <DECISION_ID> command
Implement agents plan prompt <PLAN_ID> <GUIDANCE> command
Implement agents plan rollback [--yes|-y] <PLAN_ID> <CHECKPOINT_ID> command
Add unit tests (Behave) for each new command
Verify all commands appear in agents plan --help

Definition of Done

All 5 missing plan subcommands are implemented and accessible via agents plan --help
Each command matches the spec's argument/option signature
Unit test coverage >= 97% maintained
Associated PR is merged
All nox stages pass
Coverage >= 97%

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

## Metadata - **Branch**: `fix/plan-cli-missing-subcommands-tree-explain-correct-prompt-rollback` - **Commit Message**: `feat(cli): implement missing agents plan subcommands tree, explain, correct, prompt, rollback` - **Milestone**: None (Backlog) - **Parent Epic**: #362 > **Backlog note:** This issue was discovered during autonomous operation > on milestone v3.3.0. It does not block milestone completion and has been > placed in the backlog for human review and future milestone assignment. ## Background During UAT testing of `src/cleveragents/cli/commands/plan.py`, the module docstring lists only 9 plan subcommands, but the specification requires 14 subcommands. Five spec-required subcommands are absent from the module docstring and appear to be missing from the implementation. ## Expected Behavior (from spec) Per `docs/specification.md` CLI Command Synopsis, the following `agents plan` subcommands are required: ``` agents plan list [--phase <PHASE>] [--state <STATE>] [--project <PROJECT>] [--action <ACTION>] [<REGEX>] agents plan use [...] <ACTION> <PROJECT>... agents plan execute <PLAN_ID> agents plan apply [--yes|-y] <PLAN_ID> agents plan status <PLAN_ID> agents plan cancel [(--reason|-r) <REASON>] <PLAN_ID> agents plan tree [--show-superseded] <PLAN_ID> ← MISSING agents plan explain [--show-context] [--show-reasoning] <DECISION_ID> ← MISSING agents plan correct --mode (revert|append) (--guidance|-g) <GUIDANCE> [--dry-run] [--yes|-y] <DECISION_ID> ← MISSING agents plan diff (--correction <CORRECTION_ATTEMPT_ID>|<PLAN_ID>) agents plan artifacts <PLAN_ID> agents plan prompt <PLAN_ID> <GUIDANCE> ← MISSING agents plan rollback [--yes|-y] <PLAN_ID> <CHECKPOINT_ID> ← MISSING agents plan errors <PLAN_ID> ``` ## Actual Behavior (from code) The `src/cleveragents/cli/commands/plan.py` module docstring lists only these commands: - `plan use` - `plan list` - `plan status` - `plan execute` - `plan apply` - `plan cancel` - `plan diff` - `plan artifacts` - `plan errors` The following 5 spec-required commands are NOT listed in the module docstring and appear to be missing: 1. `agents plan tree [--show-superseded] <PLAN_ID>` — Render the decision tree for a plan 2. `agents plan explain [--show-context] [--show-reasoning] <DECISION_ID>` — Explain a specific decision 3. `agents plan correct --mode (revert|append) (--guidance|-g) <GUIDANCE> [--dry-run] [--yes|-y] <DECISION_ID>` — Correct a decision 4. `agents plan prompt <PLAN_ID> <GUIDANCE>` — Send guidance to an active plan 5. `agents plan rollback [--yes|-y] <PLAN_ID> <CHECKPOINT_ID>` — Rollback to a checkpoint ## Code Location `src/cleveragents/cli/commands/plan.py` — module docstring and command definitions ## Impact - Users cannot inspect the decision tree of a plan (`plan tree`) - Users cannot understand why a specific decision was made (`plan explain`) - Users cannot correct a bad decision during plan execution (`plan correct`) - Users cannot send mid-execution guidance to a running plan (`plan prompt`) - Users cannot rollback a plan to a previous checkpoint (`plan rollback`) These are core plan lifecycle management features that are critical for the v3 plan workflow. ## Subtasks - [ ] Implement `agents plan tree [--show-superseded] <PLAN_ID>` command - [ ] Implement `agents plan explain [--show-context] [--show-reasoning] <DECISION_ID>` command - [ ] Implement `agents plan correct --mode (revert|append) (--guidance|-g) <GUIDANCE> [--dry-run] [--yes|-y] <DECISION_ID>` command - [ ] Implement `agents plan prompt <PLAN_ID> <GUIDANCE>` command - [ ] Implement `agents plan rollback [--yes|-y] <PLAN_ID> <CHECKPOINT_ID>` command - [ ] Add unit tests (Behave) for each new command - [ ] Verify all commands appear in `agents plan --help` ## Definition of Done - [ ] All 5 missing plan subcommands are implemented and accessible via `agents plan --help` - [ ] Each command matches the spec's argument/option signature - [ ] Unit test coverage >= 97% maintained - [ ] Associated PR is merged - All nox stages pass - Coverage >= 97% --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-new-issue-creator

freemo added a new dependency

2026-04-05 22:35:08 +00:00

#362 Epic: Security & Safety Hardening

freemo referenced this issue

2026-04-05 22:35:43 +00:00

[Automated] CleverAgents Build Session - 2026-04-05 (Resumed) #3654

freemo commented

2026-04-06 06:15:16 +00:00

Author

Owner

Label compliance fix applied:

Removed conflicting label: State/Unverified
Reason: Issue already has State/In Progress — two conflicting State/* labels were present. Keeping the more advanced state (State/In Progress).

Note: Type/Automation label appears to be incorrectly applied to this bug issue. This issue is a genuine UAT bug, not an automation tracking issue. Please review and remove Type/Automation if appropriate.

Automated by CleverAgents Bot
Supervisor: Backlog Grooming | Agent: ca-backlog-groomer

Label compliance fix applied: - Removed conflicting label: `State/Unverified` - Reason: Issue already has `State/In Progress` — two conflicting State/* labels were present. Keeping the more advanced state (`State/In Progress`). Note: `Type/Automation` label appears to be incorrectly applied to this bug issue. This issue is a genuine UAT bug, not an automation tracking issue. Please review and remove `Type/Automation` if appropriate. --- **Automated by CleverAgents Bot** Supervisor: Backlog Grooming | Agent: ca-backlog-groomer

freemo referenced this issue

2026-04-06 06:17:24 +00:00

[Automated] CleverAgents Build Session - 2026-04-06 #3775

freemo commented

2026-04-06 06:18:27 +00:00

Author

Owner

Issue triaged by project owner:

State: In Progress (was: conflicting Unverified + In Progress — removed Unverified)
Priority: Medium (confirmed) — These are spec-required plan subcommands but were deferred to backlog during v3.3.0 work. They are important but not blocking the current milestone.
Milestone: Recommend v3.7.0 — The tree, explain, correct, prompt, and rollback subcommands are core plan lifecycle features. They belong in the CLI completeness milestone.
Story Points: 13 — XXL — Implementing 5 full CLI subcommands with spec-compliant argument signatures, rich output, and Behave tests is a substantial effort.
MoSCoW: Should Have — These are spec-required commands (the spec uses imperative language for the CLI synopsis), but the core plan workflow functions without them. They significantly improve the user experience for plan management.
Parent Epic: #362 (Epic: Security & Safety Hardening) — Note: the issue references #362 as parent, but #362 is about security hardening, not CLI commands. This may need re-linking to a more appropriate CLI Epic. Keeping the existing link for now.

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

Issue triaged by project owner: - **State**: In Progress (was: conflicting Unverified + In Progress — removed Unverified) - **Priority**: Medium (confirmed) — These are spec-required plan subcommands but were deferred to backlog during v3.3.0 work. They are important but not blocking the current milestone. - **Milestone**: Recommend v3.7.0 — The `tree`, `explain`, `correct`, `prompt`, and `rollback` subcommands are core plan lifecycle features. They belong in the CLI completeness milestone. - **Story Points**: 13 — XXL — Implementing 5 full CLI subcommands with spec-compliant argument signatures, rich output, and Behave tests is a substantial effort. - **MoSCoW**: Should Have — These are spec-required commands (the spec uses imperative language for the CLI synopsis), but the core plan workflow functions without them. They significantly improve the user experience for plan management. - **Parent Epic**: #362 (Epic: Security & Safety Hardening) — Note: the issue references #362 as parent, but #362 is about security hardening, not CLI commands. This may need re-linking to a more appropriate CLI Epic. Keeping the existing link for now. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: ca-project-owner

freemo added the

Points

label

2026-04-06 06:18:31 +00:00

freemo referenced this issue

2026-04-06 06:20:16 +00:00

[Automated] CleverAgents Build Session - 2026-04-06 #3775

freemo referenced this issue

2026-04-06 06:22:50 +00:00

[Automated] CleverAgents Build Session - 2026-04-06 #3775

freemo referenced this issue

2026-04-06 06:41:50 +00:00