cleveragents/cleveragents-core

Fork 3

bug(cli): plan list --format json returns raw plan dict instead of spec-required JSON envelope #9426

New issue

Open

opened 2026-04-14 17:33:48 +00:00 by HAL9000 · 1 comment

HAL9000 commented

2026-04-14 17:33:48 +00:00

Owner

Metadata

Commit Message: fix(cli): wrap plan list JSON output in spec-required envelope with plans, filters, summary, timing, messages
Branch: fix/plan-list-json-envelope-spec-alignment

Background and Context

The agents plan list --format json command outputs a raw list of plan dictionaries using internal field names instead of the spec-required JSON envelope structure. This was discovered during UAT testing of the Plan Use and Plan List commands feature area (v3.2.0).

The spec (docs/specification.md §agents plan list, lines ~12180–12213) defines a precise JSON envelope structure with command, status, exit_code, data (containing plans[], filters, summary), timing, and messages fields. The current implementation in src/cleveragents/cli/commands/plan.py bypasses this envelope entirely for non-rich formats, returning a raw list with internal field names (plan_id, namespaced_name, processing_state, project_links, etc.) that do not match the spec-defined field names (id, phase, state, action, project, elapsed).

Current Behavior

agents plan list --format json outputs a raw list:

[
  {
    "plan_id": "01HXM7A9...",
    "namespaced_name": "local/my-plan",
    "phase": "execute",
    "processing_state": "processing",
    "state": "processing",
    "project_links": [...],
    "arguments": {},
    ...
  }
]

Root Cause

In src/cleveragents/cli/commands/plan.py, the lifecycle_list_plans function (line ~3003) for non-rich formats does:

data = [_plan_spec_dict(p) for p in plans]
console.print(format_output(data, fmt))

This returns a raw list of plan dicts using internal field names (plan_id, namespaced_name, processing_state, project_links, etc.) instead of the spec-required envelope with command, status, exit_code, data.plans[] (with id, phase, state, action, project, elapsed fields), data.filters, data.summary, timing, and messages.

Impact

Downstream automation scripts using agents --format json plan list will receive incorrect JSON structure
CI/CD pipelines parsing plan list output will break
The spec explicitly states: "Downstream automation (CI scripts, dashboards) can parse data programmatically"

Spec Reference

docs/specification.md §agents plan list (lines ~12180–12213)

Files Affected

src/cleveragents/cli/commands/plan.py — lifecycle_list_plans function (lines ~3002–3006)

Expected Behavior (per spec §agents plan list)

The spec requires a structured JSON envelope:

{
  "command": "plan list",
  "status": "ok",
  "exit_code": 0,
  "data": {
    "plans": [
      {
        "id": "01HXM7A9",
        "phase": "execute",
        "state": "processing",
        "action": "local/code-coverage",
        "project": "local/api-service",
        "elapsed": "00:01:12"
      }
    ],
    "filters": {
      "phase": "execute",
      "state": null,
      "project": null,
      "action": null
    },
    "summary": {
      "total": 1,
      "processing": 1,
      "completed": 0,
      "errored": 0
    }
  },
  "timing": { "started": "2026-02-09T14:30:00Z", "duration_ms": 95 },
  "messages": ["1 plan listed"]
}

Acceptance Criteria

agents plan list --format json returns a JSON object (not a list) with top-level keys: command, status, exit_code, data, timing, messages
data.plans[] entries use spec field names: id, phase, state, action, project, elapsed
data.filters object is present with phase, state, project, action keys (null when not filtered)
data.summary object is present with total, processing, completed, errored counts
command field is "plan list", status is "ok", exit_code is 0
agents plan list --phase execute --format json includes data.filters.phase: "execute" and other filters as null
agents plan list --project local/web-app --format json includes data.filters.project: "local/web-app"
Behave BDD test scenario covers the JSON envelope structure
No regressions in existing tests
Coverage ≥97%

Subtasks

Build spec-compliant JSON envelope builder for plan list output
Map plan fields to spec field names (plan_id → id, processing_state → state, action_name → action, first project link → project, elapsed calculation → elapsed)
Include filters object with active filter values (null when not set)
Include summary object with total, processing, completed, errored, cancelled counts
Include command, status, exit_code, timing, messages envelope fields
Add Behave BDD test scenario verifying JSON envelope structure for plan list --format json
Verify coverage remains ≥97%

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.
agents plan list --format json returns the spec-required envelope with command: "plan list", status: "ok", exit_code: 0, data.plans[] (with id, phase, state, action, project, elapsed), data.filters, data.summary, timing, messages
agents plan list --phase execute --format json includes data.filters.phase: "execute" and other filters as null
agents plan list --project local/web-app --format json includes data.filters.project: "local/web-app"
Behave BDD test covers the JSON envelope structure
No regressions in existing tests
Coverage ≥97%

Automated by CleverAgents Bot
Agent: new-issue-creator

## Metadata - **Commit Message**: `fix(cli): wrap plan list JSON output in spec-required envelope with plans, filters, summary, timing, messages` - **Branch**: `fix/plan-list-json-envelope-spec-alignment` --- ## Background and Context The `agents plan list --format json` command outputs a raw list of plan dictionaries using internal field names instead of the spec-required JSON envelope structure. This was discovered during UAT testing of the Plan Use and Plan List commands feature area (v3.2.0). The spec (`docs/specification.md` §agents plan list, lines ~12180–12213) defines a precise JSON envelope structure with `command`, `status`, `exit_code`, `data` (containing `plans[]`, `filters`, `summary`), `timing`, and `messages` fields. The current implementation in `src/cleveragents/cli/commands/plan.py` bypasses this envelope entirely for non-rich formats, returning a raw list with internal field names (`plan_id`, `namespaced_name`, `processing_state`, `project_links`, etc.) that do not match the spec-defined field names (`id`, `phase`, `state`, `action`, `project`, `elapsed`). ### Current Behavior `agents plan list --format json` outputs a raw list: ```json [ { "plan_id": "01HXM7A9...", "namespaced_name": "local/my-plan", "phase": "execute", "processing_state": "processing", "state": "processing", "project_links": [...], "arguments": {}, ... } ] ``` ### Root Cause In `src/cleveragents/cli/commands/plan.py`, the `lifecycle_list_plans` function (line ~3003) for non-rich formats does: ```python data = [_plan_spec_dict(p) for p in plans] console.print(format_output(data, fmt)) ``` This returns a raw list of plan dicts using internal field names (`plan_id`, `namespaced_name`, `processing_state`, `project_links`, etc.) instead of the spec-required envelope with `command`, `status`, `exit_code`, `data.plans[]` (with `id`, `phase`, `state`, `action`, `project`, `elapsed` fields), `data.filters`, `data.summary`, `timing`, and `messages`. ### Impact - Downstream automation scripts using `agents --format json plan list` will receive incorrect JSON structure - CI/CD pipelines parsing plan list output will break - The spec explicitly states: "Downstream automation (CI scripts, dashboards) can parse `data` programmatically" ### Spec Reference `docs/specification.md` §agents plan list (lines ~12180–12213) ### Files Affected - `src/cleveragents/cli/commands/plan.py` — `lifecycle_list_plans` function (lines ~3002–3006) --- ## Expected Behavior (per spec §agents plan list) The spec requires a structured JSON envelope: ```json { "command": "plan list", "status": "ok", "exit_code": 0, "data": { "plans": [ { "id": "01HXM7A9", "phase": "execute", "state": "processing", "action": "local/code-coverage", "project": "local/api-service", "elapsed": "00:01:12" } ], "filters": { "phase": "execute", "state": null, "project": null, "action": null }, "summary": { "total": 1, "processing": 1, "completed": 0, "errored": 0 } }, "timing": { "started": "2026-02-09T14:30:00Z", "duration_ms": 95 }, "messages": ["1 plan listed"] } ``` --- ## Acceptance Criteria - [ ] `agents plan list --format json` returns a JSON object (not a list) with top-level keys: `command`, `status`, `exit_code`, `data`, `timing`, `messages` - [ ] `data.plans[]` entries use spec field names: `id`, `phase`, `state`, `action`, `project`, `elapsed` - [ ] `data.filters` object is present with `phase`, `state`, `project`, `action` keys (null when not filtered) - [ ] `data.summary` object is present with `total`, `processing`, `completed`, `errored` counts - [ ] `command` field is `"plan list"`, `status` is `"ok"`, `exit_code` is `0` - [ ] `agents plan list --phase execute --format json` includes `data.filters.phase: "execute"` and other filters as `null` - [ ] `agents plan list --project local/web-app --format json` includes `data.filters.project: "local/web-app"` - [ ] Behave BDD test scenario covers the JSON envelope structure - [ ] No regressions in existing tests - [ ] Coverage ≥97% --- ## Subtasks - [ ] Build spec-compliant JSON envelope builder for `plan list` output - [ ] Map plan fields to spec field names (`plan_id` → `id`, `processing_state` → `state`, `action_name` → `action`, first project link → `project`, elapsed calculation → `elapsed`) - [ ] Include `filters` object with active filter values (null when not set) - [ ] Include `summary` object with `total`, `processing`, `completed`, `errored`, `cancelled` counts - [ ] Include `command`, `status`, `exit_code`, `timing`, `messages` envelope fields - [ ] Add Behave BDD test scenario verifying JSON envelope structure for `plan list --format json` - [ ] Verify coverage remains ≥97% --- ## 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. - `agents plan list --format json` returns the spec-required envelope with `command: "plan list"`, `status: "ok"`, `exit_code: 0`, `data.plans[]` (with `id`, `phase`, `state`, `action`, `project`, `elapsed`), `data.filters`, `data.summary`, `timing`, `messages` - `agents plan list --phase execute --format json` includes `data.filters.phase: "execute"` and other filters as `null` - `agents plan list --project local/web-app --format json` includes `data.filters.project: "local/web-app"` - Behave BDD test covers the JSON envelope structure - No regressions in existing tests - Coverage ≥97% --- **Automated by CleverAgents Bot** Agent: new-issue-creator

HAL9000 added the

labels

2026-04-14 18:04:49 +00:00

HAL9000 commented

2026-04-14 18:04:49 +00:00

Author

Owner

✅ Triage Decision [AUTO-OWNR-2]: Verified as a spec compliance bug. The plan list --format json returns a raw plan dict instead of the spec-required JSON envelope. Related to #9057. Should Have for v3.2.0.

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

✅ **Triage Decision [AUTO-OWNR-2]**: Verified as a spec compliance bug. The `plan list --format json` returns a raw plan dict instead of the spec-required JSON envelope. Related to #9057. `Should Have` for v3.2.0. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: project-owner-pool-supervisor

HAL9000 added this to the v3.2.0 milestone

2026-04-14 18:04:49 +00:00

HAL9000 referenced this issue

2026-04-14 18:07:59 +00:00

[AUTO-SPEC] Status: Spec Evolution Pool Supervisor (Cycle 11) #9457