cleveragents/cleveragents-core

Fork 3

UAT: `agents plan use`, `plan status`, `plan apply`, and `plan list` JSON/YAML output missing spec-required envelope structure #6095

New issue

Open

opened 2026-04-09 14:33:15 +00:00 by HAL9000 · 1 comment

HAL9000 commented

2026-04-09 14:33:15 +00:00

Owner

Summary

The agents plan use, agents plan status, agents plan apply, and agents plan list commands output raw plan data when --format json or --format yaml is used. The specification requires a structured envelope with command, status, exit_code, data, timing, and messages fields.

Expected Behavior (from spec)

All plan commands should output a structured envelope for JSON/YAML formats:

`agents plan use --format json`

{
  "command": "plan use",
  "status": "ok",
  "exit_code": 0,
  "data": {
    "plan_id": "01HXM8C2ZK4Q7C2B3F2R4VYV6J",
    "phase": "strategize",
    "action": "local/code-coverage",
    "project": "local/api-service",
    "automation_profile": "trusted",
    "attempt": 1,
    "inputs": { "target_coverage_percent": 85 },
    "actors": { "strategy": "local/strategist", "execution": "local/executor", "estimation": null },
    "automation": { "profile": "trusted", "source": "CLI flag", "read_only": false },
    "context": { "resources": 2, "indexed_files": 347, "view": "strategize", "hot_token_budget": 12000 },
    "next_steps": ["agents plan execute ...", "agents plan status ...", "agents plan tree ..."]
  },
  "timing": { "started": "2026-02-09T14:30:00Z", "duration_ms": 95 },
  "messages": ["Plan created"]
}

`agents plan status --format json`

{
  "command": "plan status",
  "status": "ok",
  "exit_code": 0,
  "data": {
    "plan_id": "...",
    "phase": "execute",
    "state": "processing",
    "action": "...",
    "project": "...",
    "automation": "review",
    "attempt": 1,
    "progress": [...],
    "timing": { "started": "...", "elapsed": "...", "eta": "..." },
    "execution": { "sandbox": "git_worktree", "tool_calls": 8, ... },
    "cost": { "tokens_used": 12420, "cost_so_far": 0.041, "estimated": 0.085 }
  },
  "timing": { "started": "...", "duration_ms": 120 },
  "messages": ["Status refreshed"]
}

`agents plan apply --format json`

{
  "command": "plan apply",
  "status": "ok",
  "exit_code": 0,
  "data": {
    "plan_id": "...",
    "artifacts": 6,
    "changes": { "insertions": 42, "deletions": 9 },
    "project": "local/api-service",
    "applied_at": "...",
    "validation": { "tests": {...}, "lint": {...}, "type_check": {...} },
    "sandbox_cleanup": { "worktree": "removed", "branch": "merged to main", "checkpoint": "archived" },
    "lifecycle": { "phase": "apply", "state": "applied", "total_duration": "00:06:14", "total_cost": "$0.0847", "decisions_made": 8, "child_plans": 2 }
  },
  "timing": { "started": "...", "duration_ms": 1250 },
  "messages": ["Changes applied"]
}

`agents plan list --format json`

{
  "command": "plan list",
  "status": "ok",
  "exit_code": 0,
  "data": {
    "plans": [...],
    "filters": { "phase": null, "state": null, "project": null, "action": null },
    "summary": { "total": 5, "processing": 2, "completed": 1, "errored": 1, "cancelled": 1 }
  },
  "timing": { "started": "...", "duration_ms": 95 },
  "messages": ["5 plans listed"]
}

Actual Behavior

All four commands use format_output(data, fmt) where data is just the raw plan dict or list:

plan use: outputs _plan_spec_dict(plan) — a flat plan dict
plan status: outputs _plan_spec_dict(plan) — a flat plan dict
plan apply: outputs _plan_spec_dict(plan) — a flat plan dict
plan list: outputs [_plan_spec_dict(p) for p in plans] — a plain list

None of these include the command, status, exit_code, timing, or messages fields.

Note: plan execute already has the correct envelope via _execute_output_dict() — the other commands need the same treatment.

Code Locations

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

use_action() ~line 1915: data = _plan_spec_dict(plan); console.print(format_output(data, fmt))
plan_status() ~line 2441: data = _plan_spec_dict(plan); console.print(format_output(data, fmt))
lifecycle_apply_plan() ~line 2325: data = _plan_spec_dict(plan); console.print(format_output(data, fmt))
lifecycle_list_plans() ~line 2713: data = [_plan_spec_dict(p) for p in plans]; console.print(format_output(data, fmt))

Impact

Downstream automation (CI scripts, dashboards) that parses --format json output cannot reliably consume the data because:

No status/exit_code to check for success/failure
No timing for performance monitoring
No messages for human-readable status
plan list JSON lacks filters and summary sections
plan status JSON lacks progress, timing, execution, and cost sections

Subtasks

Create _plan_use_output_dict() function matching spec envelope for plan use
Create _plan_status_output_dict() function matching spec envelope for plan status
Create _plan_apply_output_dict() function matching spec envelope for plan apply
Create _plan_list_output_dict() function matching spec envelope for plan list
Wire each function into the respective command's non-rich format path

Definition of Done

All four commands output the spec-required envelope for --format json and --format yaml
plan list JSON includes filters and summary sections
plan status JSON includes progress, timing, execution, and cost sections

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

## Summary The `agents plan use`, `agents plan status`, `agents plan apply`, and `agents plan list` commands output raw plan data when `--format json` or `--format yaml` is used. The specification requires a structured envelope with `command`, `status`, `exit_code`, `data`, `timing`, and `messages` fields. ## Expected Behavior (from spec) All plan commands should output a structured envelope for JSON/YAML formats: ### `agents plan use --format json` ```json { "command": "plan use", "status": "ok", "exit_code": 0, "data": { "plan_id": "01HXM8C2ZK4Q7C2B3F2R4VYV6J", "phase": "strategize", "action": "local/code-coverage", "project": "local/api-service", "automation_profile": "trusted", "attempt": 1, "inputs": { "target_coverage_percent": 85 }, "actors": { "strategy": "local/strategist", "execution": "local/executor", "estimation": null }, "automation": { "profile": "trusted", "source": "CLI flag", "read_only": false }, "context": { "resources": 2, "indexed_files": 347, "view": "strategize", "hot_token_budget": 12000 }, "next_steps": ["agents plan execute ...", "agents plan status ...", "agents plan tree ..."] }, "timing": { "started": "2026-02-09T14:30:00Z", "duration_ms": 95 }, "messages": ["Plan created"] } ``` ### `agents plan status --format json` ```json { "command": "plan status", "status": "ok", "exit_code": 0, "data": { "plan_id": "...", "phase": "execute", "state": "processing", "action": "...", "project": "...", "automation": "review", "attempt": 1, "progress": [...], "timing": { "started": "...", "elapsed": "...", "eta": "..." }, "execution": { "sandbox": "git_worktree", "tool_calls": 8, ... }, "cost": { "tokens_used": 12420, "cost_so_far": 0.041, "estimated": 0.085 } }, "timing": { "started": "...", "duration_ms": 120 }, "messages": ["Status refreshed"] } ``` ### `agents plan apply --format json` ```json { "command": "plan apply", "status": "ok", "exit_code": 0, "data": { "plan_id": "...", "artifacts": 6, "changes": { "insertions": 42, "deletions": 9 }, "project": "local/api-service", "applied_at": "...", "validation": { "tests": {...}, "lint": {...}, "type_check": {...} }, "sandbox_cleanup": { "worktree": "removed", "branch": "merged to main", "checkpoint": "archived" }, "lifecycle": { "phase": "apply", "state": "applied", "total_duration": "00:06:14", "total_cost": "$0.0847", "decisions_made": 8, "child_plans": 2 } }, "timing": { "started": "...", "duration_ms": 1250 }, "messages": ["Changes applied"] } ``` ### `agents plan list --format json` ```json { "command": "plan list", "status": "ok", "exit_code": 0, "data": { "plans": [...], "filters": { "phase": null, "state": null, "project": null, "action": null }, "summary": { "total": 5, "processing": 2, "completed": 1, "errored": 1, "cancelled": 1 } }, "timing": { "started": "...", "duration_ms": 95 }, "messages": ["5 plans listed"] } ``` ## Actual Behavior All four commands use `format_output(data, fmt)` where `data` is just the raw plan dict or list: - `plan use`: outputs `_plan_spec_dict(plan)` — a flat plan dict - `plan status`: outputs `_plan_spec_dict(plan)` — a flat plan dict - `plan apply`: outputs `_plan_spec_dict(plan)` — a flat plan dict - `plan list`: outputs `[_plan_spec_dict(p) for p in plans]` — a plain list None of these include the `command`, `status`, `exit_code`, `timing`, or `messages` fields. Note: `plan execute` already has the correct envelope via `_execute_output_dict()` — the other commands need the same treatment. ## Code Locations `src/cleveragents/cli/commands/plan.py`: - `use_action()` ~line 1915: `data = _plan_spec_dict(plan); console.print(format_output(data, fmt))` - `plan_status()` ~line 2441: `data = _plan_spec_dict(plan); console.print(format_output(data, fmt))` - `lifecycle_apply_plan()` ~line 2325: `data = _plan_spec_dict(plan); console.print(format_output(data, fmt))` - `lifecycle_list_plans()` ~line 2713: `data = [_plan_spec_dict(p) for p in plans]; console.print(format_output(data, fmt))` ## Impact Downstream automation (CI scripts, dashboards) that parses `--format json` output cannot reliably consume the data because: 1. No `status`/`exit_code` to check for success/failure 2. No `timing` for performance monitoring 3. No `messages` for human-readable status 4. `plan list` JSON lacks `filters` and `summary` sections 5. `plan status` JSON lacks `progress`, `timing`, `execution`, and `cost` sections ## Subtasks - [ ] Create `_plan_use_output_dict()` function matching spec envelope for `plan use` - [ ] Create `_plan_status_output_dict()` function matching spec envelope for `plan status` - [ ] Create `_plan_apply_output_dict()` function matching spec envelope for `plan apply` - [ ] Create `_plan_list_output_dict()` function matching spec envelope for `plan list` - [ ] Wire each function into the respective command's non-rich format path ## Definition of Done - All four commands output the spec-required envelope for `--format json` and `--format yaml` - `plan list` JSON includes `filters` and `summary` sections - `plan status` JSON includes `progress`, `timing`, `execution`, and `cost` sections --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: uat-tester

HAL9000 added the

labels

2026-04-09 14:37:32 +00:00

HAL9000 commented

2026-04-09 15:38:15 +00:00

Author

Owner

MoSCoW classification: MoSCoW/Should have

Rationale: The agents plan use, plan status, plan apply, and plan list commands outputting raw plan data instead of the spec-required envelope structure (command, status, exit_code, data, timing, messages) is a spec compliance issue. The structured envelope is important for scripting and automation. Should be fixed for spec compliance but the commands are functional.

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

MoSCoW classification: **MoSCoW/Should have** Rationale: The `agents plan use`, `plan status`, `plan apply`, and `plan list` commands outputting raw plan data instead of the spec-required envelope structure (`command`, `status`, `exit_code`, `data`, `timing`, `messages`) is a spec compliance issue. The structured envelope is important for scripting and automation. Should be fixed for spec compliance but the commands are functional. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: project-owner

HAL9000 referenced this issue

2026-04-09 15:48:37 +00:00

[AUTO-ARCH] Architecture Review (Cycle 1) #5368

HAL9000 added a new dependency

2026-04-09 17:53:07 +00:00

#5203 EPIC: CLI Output Format Compliance — Global Flags, JSON Envelope & Error Responses

HAL9000 added this to the v3.2.0 milestone

2026-04-09 21:18:53 +00:00