UAT: agents plan execute, agents plan apply, and agents plan status make PLAN_ID optional — spec requires it as a mandatory argument #2934

Open
opened 2026-04-05 02:52:10 +00:00 by freemo · 3 comments
Owner

Background and Context

The spec defines these commands with PLAN_ID as a required positional argument:

  • agents plan execute <PLAN_ID> — "Plan ID (required)"
  • agents plan apply [--yes|-y] <PLAN_ID> — "Plan ID"
  • agents plan status <PLAN_ID> — "Plan ID (required)"

However, the implementation makes PLAN_ID optional in all three commands, auto-discovering the plan when omitted. While auto-discovery is a useful UX enhancement, it deviates from the spec's explicit requirement that PLAN_ID is mandatory. This deviation needs to be tracked and resolved — either by updating the spec to formally allow optional PLAN_ID with auto-discovery, or by updating the implementation to require PLAN_ID.

Current Behavior

All three commands accept no PLAN_ID argument and auto-discover the eligible plan:

  • agents plan execute — auto-selects the single eligible plan when no ID is given
  • agents plan apply — auto-selects the single eligible plan when no ID is given
  • agents plan status — lists all plans when no ID is given

Code locations (src/cleveragents/cli/commands/plan.py):

  • execute_plan() function (line 1732): plan_id: str | None = None
  • lifecycle_apply_plan() function (line 1942): plan_id: str | None = None
  • plan_status() function (line 2093): plan_id: str | None = None

Expected Behavior

Per the spec, PLAN_ID should be a required positional argument for all three commands. Running without it should produce a usage error directing the user to supply a PLAN_ID.

Note: The auto-discovery behavior is a useful UX enhancement. Resolution options are:

  1. Update the spec to formally allow optional PLAN_ID with auto-discovery semantics, OR
  2. Update the implementation to require PLAN_ID as a mandatory positional argument

Acceptance Criteria

  • A decision is made and documented: either the spec is updated to allow optional PLAN_ID, or the implementation is updated to require it
  • If spec is updated: docs/specification.md reflects the optional PLAN_ID with auto-discovery semantics for all three commands
  • If implementation is updated: running agents plan execute, agents plan apply, or agents plan status without a PLAN_ID produces a clear usage error
  • All existing tests pass; new tests cover the chosen behavior
  • The chosen behavior is consistent across all three commands

Supporting Information

  • Code locations: src/cleveragents/cli/commands/plan.pyexecute_plan() line 1732, lifecycle_apply_plan() line 1942, plan_status() line 2093
  • Spec reference: docs/specification.md §agents plan execute, §agents plan apply, §agents plan status
  • Parent Epic: #397

Metadata

  • Branch: fix/m6-plan-lifecycle-plan-id-required
  • Commit Message: fix(cli): enforce PLAN_ID as required argument for plan execute, apply, and status
  • Milestone: v3.5.0
  • Parent Epic: #397

Subtasks

  • Review spec and implementation to determine the correct resolution (require PLAN_ID vs. update spec)
  • If updating implementation: make plan_id a required positional argument in execute_plan(), lifecycle_apply_plan(), and plan_status()
  • If updating spec: update docs/specification.md to document optional PLAN_ID with auto-discovery semantics
  • Add or update unit tests to cover the resolved behavior for all three commands
  • Tests (Behave): Add/update scenarios for missing PLAN_ID in plan execute, plan apply, plan status
  • Tests (Robot): Add integration tests for the resolved PLAN_ID behavior
  • Verify coverage >= 97% via nox -s coverage_report
  • 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, followed by a blank line, then additional lines providing relevant details about the implementation.
  • 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%

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

## Background and Context The spec defines these commands with PLAN_ID as a required positional argument: - `agents plan execute <PLAN_ID>` — "Plan ID (required)" - `agents plan apply [--yes|-y] <PLAN_ID>` — "Plan ID" - `agents plan status <PLAN_ID>` — "Plan ID (required)" However, the implementation makes PLAN_ID optional in all three commands, auto-discovering the plan when omitted. While auto-discovery is a useful UX enhancement, it deviates from the spec's explicit requirement that PLAN_ID is mandatory. This deviation needs to be tracked and resolved — either by updating the spec to formally allow optional PLAN_ID with auto-discovery, or by updating the implementation to require PLAN_ID. ## Current Behavior All three commands accept no PLAN_ID argument and auto-discover the eligible plan: - `agents plan execute` — auto-selects the single eligible plan when no ID is given - `agents plan apply` — auto-selects the single eligible plan when no ID is given - `agents plan status` — lists all plans when no ID is given **Code locations** (`src/cleveragents/cli/commands/plan.py`): - `execute_plan()` function (line 1732): `plan_id: str | None = None` - `lifecycle_apply_plan()` function (line 1942): `plan_id: str | None = None` - `plan_status()` function (line 2093): `plan_id: str | None = None` ## Expected Behavior Per the spec, PLAN_ID should be a required positional argument for all three commands. Running without it should produce a usage error directing the user to supply a PLAN_ID. **Note**: The auto-discovery behavior is a useful UX enhancement. Resolution options are: 1. Update the spec to formally allow optional PLAN_ID with auto-discovery semantics, OR 2. Update the implementation to require PLAN_ID as a mandatory positional argument ## Acceptance Criteria - [ ] A decision is made and documented: either the spec is updated to allow optional PLAN_ID, or the implementation is updated to require it - [ ] If spec is updated: `docs/specification.md` reflects the optional PLAN_ID with auto-discovery semantics for all three commands - [ ] If implementation is updated: running `agents plan execute`, `agents plan apply`, or `agents plan status` without a PLAN_ID produces a clear usage error - [ ] All existing tests pass; new tests cover the chosen behavior - [ ] The chosen behavior is consistent across all three commands ## Supporting Information - **Code locations**: `src/cleveragents/cli/commands/plan.py` — `execute_plan()` line 1732, `lifecycle_apply_plan()` line 1942, `plan_status()` line 2093 - **Spec reference**: `docs/specification.md` §agents plan execute, §agents plan apply, §agents plan status - **Parent Epic**: #397 ## Metadata - **Branch**: `fix/m6-plan-lifecycle-plan-id-required` - **Commit Message**: `fix(cli): enforce PLAN_ID as required argument for plan execute, apply, and status` - **Milestone**: v3.5.0 - **Parent Epic**: #397 ## Subtasks - [ ] Review spec and implementation to determine the correct resolution (require PLAN_ID vs. update spec) - [ ] If updating implementation: make `plan_id` a required positional argument in `execute_plan()`, `lifecycle_apply_plan()`, and `plan_status()` - [ ] If updating spec: update `docs/specification.md` to document optional PLAN_ID with auto-discovery semantics - [ ] Add or update unit tests to cover the resolved behavior for all three commands - [ ] Tests (Behave): Add/update scenarios for missing PLAN_ID in `plan execute`, `plan apply`, `plan status` - [ ] Tests (Robot): Add integration tests for the resolved PLAN_ID behavior - [ ] Verify coverage >= 97% via `nox -s coverage_report` - [ ] 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, followed by a blank line, then additional lines providing relevant details about the implementation. - 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% --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-uat-tester
freemo added this to the v3.5.0 milestone 2026-04-05 02:52:58 +00:00
Author
Owner

Issue triaged by project owner:

  • State: Verified
  • Priority: Low (confirmed)
  • MoSCoW: Could Have — PlanContext usage is 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 — PlanContext usage is low impact Valid finding verified during batch triage. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: ca-project-owner
Author
Owner

Milestone Triage Decision: Moved to Backlog

This CLI specification issue has been moved out of v3.5.0 during aggressive milestone triage. While important for spec compliance, it does not block core autonomy hardening functionality.

Reasoning:

  • v3.5.0 focus: Essential autonomy hardening (guard enforcement, A2A facade, plan lifecycle)
  • This issue: CLI argument validation (optional vs required PLAN_ID) - spec compliance
  • Impact: UX consistency, not functional capability

Will be addressed in a future milestone focused on CLI polish and spec compliance.

**Milestone Triage Decision: Moved to Backlog** This CLI specification issue has been moved out of v3.5.0 during aggressive milestone triage. While important for spec compliance, it does not block core autonomy hardening functionality. **Reasoning:** - v3.5.0 focus: Essential autonomy hardening (guard enforcement, A2A facade, plan lifecycle) - This issue: CLI argument validation (optional vs required PLAN_ID) - spec compliance - Impact: UX consistency, not functional capability Will be addressed in a future milestone focused on CLI polish and spec compliance.
Author
Owner

This issue has been moved to the backlog as part of an aggressive grooming of the v3.5.0 milestone. It has been deemed non-critical for the minimal viability of the milestone and will be addressed in a future release.

This issue has been moved to the backlog as part of an aggressive grooming of the v3.5.0 milestone. It has been deemed non-critical for the minimal viability of the milestone and will be addressed in a future release.
Sign in to join this conversation.
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Blocks
#397 Epic: Server & Autonomy Infrastructure
cleveragents/cleveragents-core
Reference
cleveragents/cleveragents-core#2934
No description provided.