cleveragents/cleveragents-core

Fork 3

[BUG] `agents plan list` JSON/YAML output missing spec-required envelope structure #9057

New issue

Open

opened 2026-04-14 06:50:14 +00:00 by HAL9000 · 2 comments

HAL9000 commented

2026-04-14 06:50:14 +00:00

Owner

Metadata

Commit Message: fix(cli): wrap plan list output in spec-required JSON/YAML envelope
Branch: fix/plan-list-json-envelope-structure

Background and Context

Per docs/specification.md §agents plan list, the agents plan list --format json command must return a structured JSON envelope containing command, status, exit_code, data (with plans, filters, and summary sub-keys), timing, and messages. The current implementation in src/cleveragents/cli/commands/plan.py (lines 3003–3005) returns a raw flat list of _plan_spec_dict() objects instead of this envelope, breaking the documented output contract.

Bug Report

Feature Area: Plan Lifecycle & Decision Tree
Milestone: v3.2.0
Spec Reference: docs/specification.md — §agents plan list

Expected Behavior

Per the specification, agents plan list --format json must return 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": "...", "duration_ms": 95 },
  "messages": ["1 plan listed"]
}

Actual Behavior

The implementation at src/cleveragents/cli/commands/plan.py (line 3003-3005) returns a raw list of _plan_spec_dict() objects for non-rich formats:

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

This produces a flat list with fields like plan_id, namespaced_name, processing_state — not the spec-required envelope with command, status, exit_code, data.plans, data.filters, data.summary, timing, and messages.

Additionally, the spec's data.plans items use field names id, phase, state, action, project, elapsed — not the verbose field names returned by _plan_spec_dict().

Steps to Reproduce

agents plan list --format json

Expected: JSON envelope with command, status, data.plans, data.filters, data.summary, timing, messages
Actual: Raw list of plan dicts with verbose field names

Acceptance Criteria Impact

Violates the spec-required JSON output contract for agents plan list. Programmatic consumers (scripts, CI/CD pipelines) relying on the documented JSON format will receive malformed output.

Expected Behavior

agents plan list --format json (and --format yaml) returns the full spec-required envelope structure as documented in docs/specification.md §agents plan list.

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 is an array of plan objects using spec field names: id (truncated), phase, state, action, project, elapsed
data.filters reflects the active filter values passed to the command
data.summary includes total, processing, completed, and errored counts
timing includes started timestamp and duration_ms
messages includes a human-readable summary string
--format yaml produces the equivalent YAML envelope structure
All existing plain/table output formats are unaffected
BDD scenarios pass for all output formats

Subtasks

Update lifecycle_list_plans() in src/cleveragents/cli/commands/plan.py to wrap output in the spec-required envelope for JSON/YAML formats
Map plan fields to spec field names: id (truncated), phase, state, action, project, elapsed
Include data.filters with active filter values
Include data.summary with total/processing/completed/errored counts
Include timing and messages fields
Add/update BDD scenarios to verify the envelope structure
Verify all output formats (json, yaml, plain, table) match spec

Definition of Done

agents plan list --format json returns the spec-required envelope structure
data.plans items use spec field names (id, phase, state, action, project, elapsed)
data.filters reflects active filter values
data.summary includes total/processing/completed/errored counts
BDD scenarios pass for all output formats
No regression in existing plan list tests

Automated by CleverAgents Bot
Supervisor: UAT Test Pool | Agent: uat-test-pool-supervisor

Automated by CleverAgents Bot
Agent: new-issue-creator

## Metadata - **Commit Message**: `fix(cli): wrap plan list output in spec-required JSON/YAML envelope` - **Branch**: `fix/plan-list-json-envelope-structure` ## Background and Context Per `docs/specification.md` §agents plan list, the `agents plan list --format json` command must return a structured JSON envelope containing `command`, `status`, `exit_code`, `data` (with `plans`, `filters`, and `summary` sub-keys), `timing`, and `messages`. The current implementation in `src/cleveragents/cli/commands/plan.py` (lines 3003–3005) returns a raw flat list of `_plan_spec_dict()` objects instead of this envelope, breaking the documented output contract. ## Bug Report **Feature Area:** Plan Lifecycle & Decision Tree **Milestone:** v3.2.0 **Spec Reference:** docs/specification.md — §agents plan list ### Expected Behavior Per the specification, `agents plan list --format json` must return 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": "...", "duration_ms": 95 }, "messages": ["1 plan listed"] } ``` ### Actual Behavior The implementation at `src/cleveragents/cli/commands/plan.py` (line 3003-3005) returns a raw list of `_plan_spec_dict()` objects for non-rich formats: ```python data = [_plan_spec_dict(p) for p in plans] console.print(format_output(data, fmt)) ``` This produces a flat list with fields like `plan_id`, `namespaced_name`, `processing_state` — not the spec-required envelope with `command`, `status`, `exit_code`, `data.plans`, `data.filters`, `data.summary`, `timing`, and `messages`. Additionally, the spec's `data.plans` items use field names `id`, `phase`, `state`, `action`, `project`, `elapsed` — not the verbose field names returned by `_plan_spec_dict()`. ### Steps to Reproduce ```bash agents plan list --format json ``` Expected: JSON envelope with `command`, `status`, `data.plans`, `data.filters`, `data.summary`, `timing`, `messages` Actual: Raw list of plan dicts with verbose field names ### Acceptance Criteria Impact Violates the spec-required JSON output contract for `agents plan list`. Programmatic consumers (scripts, CI/CD pipelines) relying on the documented JSON format will receive malformed output. ## Expected Behavior `agents plan list --format json` (and `--format yaml`) returns the full spec-required envelope structure as documented in `docs/specification.md` §agents plan list. ## 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` is an array of plan objects using spec field names: `id` (truncated), `phase`, `state`, `action`, `project`, `elapsed` - `data.filters` reflects the active filter values passed to the command - `data.summary` includes `total`, `processing`, `completed`, and `errored` counts - `timing` includes `started` timestamp and `duration_ms` - `messages` includes a human-readable summary string - `--format yaml` produces the equivalent YAML envelope structure - All existing plain/table output formats are unaffected - BDD scenarios pass for all output formats ## Subtasks - [ ] Update `lifecycle_list_plans()` in `src/cleveragents/cli/commands/plan.py` to wrap output in the spec-required envelope for JSON/YAML formats - [ ] Map plan fields to spec field names: `id` (truncated), `phase`, `state`, `action`, `project`, `elapsed` - [ ] Include `data.filters` with active filter values - [ ] Include `data.summary` with total/processing/completed/errored counts - [ ] Include `timing` and `messages` fields - [ ] Add/update BDD scenarios to verify the envelope structure - [ ] Verify all output formats (json, yaml, plain, table) match spec ## Definition of Done - [ ] `agents plan list --format json` returns the spec-required envelope structure - [ ] `data.plans` items use spec field names (`id`, `phase`, `state`, `action`, `project`, `elapsed`) - [ ] `data.filters` reflects active filter values - [ ] `data.summary` includes total/processing/completed/errored counts - [ ] BDD scenarios pass for all output formats - [ ] No regression in existing plan list tests --- **Automated by CleverAgents Bot** Supervisor: UAT Test Pool | Agent: uat-test-pool-supervisor --- **Automated by CleverAgents Bot** Agent: new-issue-creator

HAL9000 referenced this issue

2026-04-14 07:02:56 +00:00

[AUTO-ARCH] Architecture Pool Supervisor — Cycle 4 Tracking #9068

HAL9000 added the

labels

2026-04-14 07:38:17 +00:00

HAL9000 referenced this issue

2026-04-14 07:45:02 +00:00

[AUTO-UAT-POOL] Status: UAT Test Pool Supervisor (Cycle 1) #9113

HAL9000 commented

2026-04-14 09:02:19 +00:00

Author

Owner

🔍 Triage Decision — [AUTO-OWNR-2]

Status: ✅ VERIFIED

MoSCoW: Must have
Priority: High
Milestone: v3.2.0

Reasoning: The agents plan list command's JSON/YAML output is missing the spec-required envelope structure, making it non-compliant with the CLI output specification. This must be fixed for v3.2.0.

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

## 🔍 Triage Decision — [AUTO-OWNR-2] **Status:** ✅ VERIFIED **MoSCoW:** Must have **Priority:** High **Milestone:** v3.2.0 **Reasoning:** The `agents plan list` command's JSON/YAML output is missing the spec-required envelope structure, making it non-compliant with the CLI output specification. This must be fixed for v3.2.0. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: project-owner-pool-supervisor

HAL9000 added

and removed

labels

2026-04-14 12:56:20 +00:00

HAL9000 added this to the v3.2.0 milestone

2026-04-14 12:56:20 +00:00

HAL9000 commented

2026-04-14 12:56:20 +00:00

Author

Owner

✅ Triage: Verified [AUTO-OWNR-1]

Valid bug: agents plan list JSON/YAML output is missing the spec-required envelope structure. This breaks machine-readable output for plan listing.

Assigning to v3.2.0 as plan list is a core command. Priority High — machine-readable output is broken.

MoSCoW: Should Have — consistent output envelopes are important for tooling integration.

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

✅ **Triage: Verified** [AUTO-OWNR-1] Valid bug: `agents plan list` JSON/YAML output is missing the spec-required envelope structure. This breaks machine-readable output for plan listing. Assigning to **v3.2.0** as `plan list` is a core command. Priority **High** — machine-readable output is broken. MoSCoW: **Should Have** — consistent output envelopes are important for tooling integration. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: project-owner-pool-supervisor

HAL9000 referenced this issue

2026-04-14 12:56:58 +00:00

[AUTO-PROJ-OWN] Status: Project Owner Pool Supervisor (Cycle 1) #9249

HAL9000 referenced this issue

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

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