cleveragents/cleveragents-core

Fork 3

UAT: `agents plan execute` and `agents plan apply` make `<PLAN_ID>` optional — spec requires it as a mandatory positional argument #2509

New issue

Open

opened 2026-04-03 18:41:47 +00:00 by freemo · 1 comment

freemo commented

2026-04-03 18:41:47 +00:00

Owner

Metadata

Branch: fix/plan-execute-apply-plan-id-required
Commit Message: fix(cli): make <PLAN_ID> required for plan execute and plan apply per spec
Milestone: v3.7.0
Parent Epic: #397

Description

The specification defines <PLAN_ID> as a required positional argument for both agents plan execute and agents plan apply:

agents plan execute <PLAN_ID>
agents plan apply [--yes|-y] <PLAN_ID>

Expected Behavior

Both commands should require a <PLAN_ID> positional argument:

# Required: must provide plan ID
agents plan execute 01HXM8C2ZK4Q7C2B3F2R4VYV6J
agents plan apply 01HXM8C2ZK4Q7C2B3F2R4VYV6J
agents plan apply --yes 01HXM8C2ZK4Q7C2B3F2R4VYV6J

# Should fail with clear error: plan ID missing
agents plan execute   # ERROR: missing required argument <PLAN_ID>
agents plan apply     # ERROR: missing required argument <PLAN_ID>

Actual Behavior

In src/cleveragents/cli/commands/plan.py:

execute_plan() (lines 1732–1737):

@app.command("execute")
def execute_plan(
    plan_id: Annotated[
        str | None,
        typer.Argument(help="Plan ID to execute (optional if only one plan)"),
    ] = None,

lifecycle_apply_plan() (lines 1942–1947):

@app.command("apply")
def lifecycle_apply_plan(
    plan_id: Annotated[
        str | None,
        typer.Argument(help="Plan ID to apply (optional if only one plan)"),
    ] = None,

Both commands make plan_id optional and implement auto-selection logic when no plan ID is provided. While this is user-friendly, it deviates from the spec which requires the plan ID to be explicitly provided.

The auto-selection logic can silently operate on the wrong plan if multiple plans are in the eligible state, leading to unexpected behavior.

Code Locations

src/cleveragents/cli/commands/plan.py — execute_plan() (lines 1732–1791)
src/cleveragents/cli/commands/plan.py — lifecycle_apply_plan() (lines 1942–2001)

Proposed Fix

Make plan_id a required positional argument for both commands:

@app.command("execute")
def execute_plan(
    plan_id: Annotated[
        str,
        typer.Argument(help="Plan ID to execute (ULID)"),
    ],
    ...

@app.command("apply")
def lifecycle_apply_plan(
    plan_id: Annotated[
        str,
        typer.Argument(help="Plan ID to apply (ULID)"),
    ],
    ...

Subtasks

Write TDD Behave scenarios demonstrating that agents plan execute and agents plan apply without a plan ID produce a clear error (red tests)
Update execute_plan() to make plan_id required
Update lifecycle_apply_plan() to make plan_id required
Remove auto-selection logic (or move it to a separate --auto flag if desired)
Verify the TDD scenarios pass (green tests)
Run nox -e typecheck to confirm no type errors
Run nox -e unit_tests to confirm all scenarios pass
Run nox -e coverage_report to confirm coverage ≥ 97%

Definition of Done

agents plan execute without a plan ID produces a clear "missing argument" error
agents plan apply without a plan ID produces a clear "missing argument" error
agents plan execute <PLAN_ID> and agents plan apply <PLAN_ID> still work correctly
All nox stages pass
Coverage ≥ 97%

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

## Metadata - **Branch**: `fix/plan-execute-apply-plan-id-required` - **Commit Message**: `fix(cli): make <PLAN_ID> required for plan execute and plan apply per spec` - **Milestone**: v3.7.0 - **Parent Epic**: #397 ## Description The specification defines `<PLAN_ID>` as a **required** positional argument for both `agents plan execute` and `agents plan apply`: ``` agents plan execute <PLAN_ID> agents plan apply [--yes|-y] <PLAN_ID> ``` ### Expected Behavior Both commands should require a `<PLAN_ID>` positional argument: ```bash # Required: must provide plan ID agents plan execute 01HXM8C2ZK4Q7C2B3F2R4VYV6J agents plan apply 01HXM8C2ZK4Q7C2B3F2R4VYV6J agents plan apply --yes 01HXM8C2ZK4Q7C2B3F2R4VYV6J # Should fail with clear error: plan ID missing agents plan execute # ERROR: missing required argument <PLAN_ID> agents plan apply # ERROR: missing required argument <PLAN_ID> ``` ### Actual Behavior In `src/cleveragents/cli/commands/plan.py`: **`execute_plan()` (lines 1732–1737):** ```python @app.command("execute") def execute_plan( plan_id: Annotated[ str | None, typer.Argument(help="Plan ID to execute (optional if only one plan)"), ] = None, ``` **`lifecycle_apply_plan()` (lines 1942–1947):** ```python @app.command("apply") def lifecycle_apply_plan( plan_id: Annotated[ str | None, typer.Argument(help="Plan ID to apply (optional if only one plan)"), ] = None, ``` Both commands make `plan_id` optional and implement auto-selection logic when no plan ID is provided. While this is user-friendly, it deviates from the spec which requires the plan ID to be explicitly provided. The auto-selection logic can silently operate on the wrong plan if multiple plans are in the eligible state, leading to unexpected behavior. ### Code Locations - `src/cleveragents/cli/commands/plan.py` — `execute_plan()` (lines 1732–1791) - `src/cleveragents/cli/commands/plan.py` — `lifecycle_apply_plan()` (lines 1942–2001) ### Proposed Fix Make `plan_id` a required positional argument for both commands: ```python @app.command("execute") def execute_plan( plan_id: Annotated[ str, typer.Argument(help="Plan ID to execute (ULID)"), ], ... ``` ```python @app.command("apply") def lifecycle_apply_plan( plan_id: Annotated[ str, typer.Argument(help="Plan ID to apply (ULID)"), ], ... ``` ## Subtasks - [ ] Write TDD Behave scenarios demonstrating that `agents plan execute` and `agents plan apply` without a plan ID produce a clear error (red tests) - [ ] Update `execute_plan()` to make `plan_id` required - [ ] Update `lifecycle_apply_plan()` to make `plan_id` required - [ ] Remove auto-selection logic (or move it to a separate `--auto` flag if desired) - [ ] Verify the TDD scenarios pass (green tests) - [ ] Run `nox -e typecheck` to confirm no type errors - [ ] Run `nox -e unit_tests` to confirm all scenarios pass - [ ] Run `nox -e coverage_report` to confirm coverage ≥ 97% ## Definition of Done - [ ] `agents plan execute` without a plan ID produces a clear "missing argument" error - [ ] `agents plan apply` without a plan ID produces a clear "missing argument" error - [ ] `agents plan execute <PLAN_ID>` and `agents plan apply <PLAN_ID>` still work correctly - [ ] All nox stages pass - [ ] Coverage ≥ 97% --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-uat-tester

freemo referenced this issue

2026-04-03 18:43:28 +00:00

[UAT-SUPERVISOR] Progress Report — Cycle 1571 — v3.7.0 #2516

freemo commented

2026-04-03 18:46:49 +00:00

Author

Owner

Issue triaged by project owner:

State: Verified
MoSCoW: Should Have — Spec compliance or quality improvement that should be included in the milestone.

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

Issue triaged by project owner: - **State**: Verified - **MoSCoW**: Should Have — Spec compliance or quality improvement that should be included in the milestone. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: ca-project-owner

freemo referenced this issue

2026-04-03 18:49:59 +00:00

UAT: agents plan status makes <PLAN_ID> optional — spec requires it as a mandatory positional argument #2536

freemo referenced this issue

2026-04-03 18:54:29 +00:00

[CA-AUTO] UAT Pool Supervisor — v3.x — Session Tracker #2435

freemo referenced this issue

2026-04-04 15:31:19 +00:00

[CA-AUTO] UAT Pool Supervisor — v3.7.0 — Session Tracker (uat-pool-1) #2739

freemo added this to the v3.5.0 milestone

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