UAT: `agents plan explain` accepts plan_id but spec requires `<DECISION_ID>` as the positional argument #6325

New issue

Open

opened 2026-04-09 20:10:28 +00:00 by HAL9000 · 0 comments

HAL9000 commented

2026-04-09 20:10:28 +00:00

Owner

Bug Report

Feature Area: Plan Lifecycle
Spec Reference: docs/specification.md §agents plan explain (line 14546–14555)
Instance: uat-worker-W1-cycle3

Summary

The spec defines agents plan explain as:

agents plan explain [--show-context] [--show-reasoning] <DECISION_ID>

The <DECISION_ID> is the sole positional argument. However, the implementation silently accepts a plan_id as the positional identifier argument, auto-selecting the plan's root decision if no decision with that ID exists. This undocumented extension diverges from the spec contract.

Code Location

/app/src/cleveragents/cli/commands/plan.py, lines 4216–4228:

@app.command("explain")
def explain_decision_cmd(
    identifier: Annotated[
        str,
        typer.Argument(help="Decision or Plan ULID to explain"),  # ← "or Plan ULID" not in spec
    ],
    ...
) -> None:
    """Explain a single decision or the root decision of a plan."""
    ...
    # First, try treating the identifier as a decision_id (backward compat).
    decision = None
    with suppress(DecisionNotFoundError):
        decision = svc.get_decision(identifier)

    # If not found as a decision, try as a plan_id.
    if decision is None:
        decisions = svc.list_decisions(identifier)  # treats identifier as plan_id
        if decisions:
            root_decisions = [d for d in decisions if d.parent_decision_id is None]
            decision = root_decisions[0] if root_decisions else decisions[0]

Steps to Reproduce

# Spec-compliant use (should always work):
agents plan explain <DECISION_ID>

# Non-spec use (currently works but should fail or be explicit):
agents plan explain <PLAN_ID>

Expected (per spec)

agents plan explain <DECISION_ID> — works, shows that decision's details
agents plan explain <PLAN_ID> — should fail with "not found as a decision" error, OR the spec should be updated to document this extension

Actual

agents plan explain <PLAN_ID> silently auto-selects the root decision with no warning to the user that a fallback occurred

Impact

Scripts passing a plan ID expecting an error will silently receive root-decision output
The help text says Decision or Plan ULID while the spec CLI signature only shows <DECISION_ID>
If a plan ID happens to match a decision ID in another plan, the result is ambiguous

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

## Bug Report **Feature Area**: Plan Lifecycle **Spec Reference**: `docs/specification.md` §`agents plan explain` (line 14546–14555) **Instance**: uat-worker-W1-cycle3 --- ### Summary The spec defines `agents plan explain` as: ``` agents plan explain [--show-context] [--show-reasoning] <DECISION_ID> ``` The `<DECISION_ID>` is the sole positional argument. However, the implementation silently accepts a **plan_id** as the positional `identifier` argument, auto-selecting the plan's root decision if no decision with that ID exists. This undocumented extension diverges from the spec contract. --- ### Code Location `/app/src/cleveragents/cli/commands/plan.py`, lines 4216–4228: ```python @app.command("explain") def explain_decision_cmd( identifier: Annotated[ str, typer.Argument(help="Decision or Plan ULID to explain"), # ← "or Plan ULID" not in spec ], ... ) -> None: """Explain a single decision or the root decision of a plan.""" ... # First, try treating the identifier as a decision_id (backward compat). decision = None with suppress(DecisionNotFoundError): decision = svc.get_decision(identifier) # If not found as a decision, try as a plan_id. if decision is None: decisions = svc.list_decisions(identifier) # treats identifier as plan_id if decisions: root_decisions = [d for d in decisions if d.parent_decision_id is None] decision = root_decisions[0] if root_decisions else decisions[0] ``` --- ### Steps to Reproduce ```bash # Spec-compliant use (should always work): agents plan explain <DECISION_ID> # Non-spec use (currently works but should fail or be explicit): agents plan explain <PLAN_ID> ``` --- ### Expected (per spec) - `agents plan explain <DECISION_ID>` — works, shows that decision's details - `agents plan explain <PLAN_ID>` — should fail with "not found as a decision" error, OR the spec should be updated to document this extension ### Actual - `agents plan explain <PLAN_ID>` silently auto-selects the root decision with no warning to the user that a fallback occurred --- ### Impact - Scripts passing a plan ID expecting an error will silently receive root-decision output - The help text says `Decision or Plan ULID` while the spec CLI signature only shows `<DECISION_ID>` - If a plan ID happens to match a decision ID in another plan, the result is ambiguous --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: uat-tester

Rows
Columns

UAT: agents plan explain accepts plan_id but spec requires <DECISION_ID> as the positional argument #6325