UAT: `agents plan list` JSON/YAML output missing spec-required envelope — `plans`, `filters`, and `summary` keys absent #2902

New issue

Open

opened 2026-04-05 02:46:10 +00:00 by freemo · 3 comments

freemo commented

2026-04-05 02:46:10 +00:00

Owner

Metadata

Branch: fix/m5-plan-list-json-envelope
Commit Message: fix(cli): wrap agents plan list JSON/YAML output in spec-required envelope
Milestone: v3.5.0
Parent Epic: #397

Background and Context

The spec (docs/specification.md §agents plan list) requires the JSON output to be a structured envelope with command, status, exit_code, data (containing plans, filters, summary), timing, and messages keys. The current implementation in src/cleveragents/cli/commands/plan.py outputs a bare list of plan dicts ([_plan_spec_dict(p) for p in plans]) without the required envelope structure.

Current Behavior

agents plan list --format json outputs a raw JSON array of plan objects:

[
  { "id": "...", "phase": "...", ... },
  ...
]

Code location: src/cleveragents/cli/commands/plan.py, lifecycle_list_plans() function (around line 2306), lines 2449–2453.

Expected Behavior

Per the spec, agents plan list --format json must output a structured envelope:

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

The same envelope structure must be used for --format yaml output.

Acceptance Criteria

agents plan list --format json outputs a JSON object (not array) with top-level keys: command, status, exit_code, data, timing, messages
data.plans contains the array of plan objects (same schema as before)
data.filters reflects the active filter flags (--phase, --state, --project, --action), with null for unset filters
data.summary contains total, processing, completed, and errored counts derived from the returned plans
timing.duration_ms contains the command execution duration in milliseconds
messages contains a human-readable summary string (e.g., "3 plans listed")
agents plan list --format yaml outputs the same envelope structure in YAML
Rich (default) output is unaffected
All nox stages pass with coverage >= 97%

Subtasks

Audit lifecycle_list_plans() in plan.py and locate the JSON/YAML serialisation path (lines ~2449–2453)
Implement _build_plan_list_envelope(plans, filters, duration_ms) helper that constructs the spec-required envelope dict
Replace the bare list serialisation with the envelope helper for both JSON and YAML format paths
Update any existing Behave unit tests that assert on the raw-list JSON shape
Write new Behave unit tests covering the envelope structure, filters, and summary counts
Write Robot Framework integration test asserting the envelope keys are present in JSON output
Run nox and confirm all stages pass with coverage >= 97%

Definition of Done

All subtasks above are checked
agents plan list --format json output matches the spec envelope structure
agents plan list --format yaml output matches the spec envelope structure
Behave unit tests cover envelope keys, filters, and summary
Robot Framework integration test passes
Commit pushed to fix/m5-plan-list-json-envelope with message fix(cli): wrap agents plan list JSON/YAML output in spec-required envelope
PR merged and issue closed
All nox stages pass
Coverage >= 97%

Automated by CleverAgents Bot
Supervisor: UAT Testing | Agent: ca-new-issue-creator

## Metadata - **Branch**: `fix/m5-plan-list-json-envelope` - **Commit Message**: `fix(cli): wrap agents plan list JSON/YAML output in spec-required envelope` - **Milestone**: v3.5.0 - **Parent Epic**: #397 ## Background and Context The spec (`docs/specification.md` §agents plan list) requires the JSON output to be a structured envelope with `command`, `status`, `exit_code`, `data` (containing `plans`, `filters`, `summary`), `timing`, and `messages` keys. The current implementation in `src/cleveragents/cli/commands/plan.py` outputs a bare list of plan dicts (`[_plan_spec_dict(p) for p in plans]`) without the required envelope structure. ## Current Behavior `agents plan list --format json` outputs a raw JSON array of plan objects: ```json [ { "id": "...", "phase": "...", ... }, ... ] ``` **Code location**: `src/cleveragents/cli/commands/plan.py`, `lifecycle_list_plans()` function (around line 2306), lines 2449–2453. ## Expected Behavior Per the spec, `agents plan list --format json` must output a structured envelope: ```json { "command": "plan list", "status": "ok", "exit_code": 0, "data": { "plans": [ { "id": "...", "phase": "...", ... } ], "filters": { "phase": "execute", "state": null, "project": null, "action": null }, "summary": { "total": 1, "processing": 1, "completed": 0, "errored": 0 } }, "timing": { "duration_ms": 42 }, "messages": ["1 plan listed"] } ``` The same envelope structure must be used for `--format yaml` output. ## Acceptance Criteria - [ ] `agents plan list --format json` outputs a JSON object (not array) with top-level keys: `command`, `status`, `exit_code`, `data`, `timing`, `messages` - [ ] `data.plans` contains the array of plan objects (same schema as before) - [ ] `data.filters` reflects the active filter flags (`--phase`, `--state`, `--project`, `--action`), with `null` for unset filters - [ ] `data.summary` contains `total`, `processing`, `completed`, and `errored` counts derived from the returned plans - [ ] `timing.duration_ms` contains the command execution duration in milliseconds - [ ] `messages` contains a human-readable summary string (e.g., `"3 plans listed"`) - [ ] `agents plan list --format yaml` outputs the same envelope structure in YAML - [ ] Rich (default) output is unaffected - [ ] All nox stages pass with coverage >= 97% ## Subtasks - [ ] Audit `lifecycle_list_plans()` in `plan.py` and locate the JSON/YAML serialisation path (lines ~2449–2453) - [ ] Implement `_build_plan_list_envelope(plans, filters, duration_ms)` helper that constructs the spec-required envelope dict - [ ] Replace the bare list serialisation with the envelope helper for both JSON and YAML format paths - [ ] Update any existing Behave unit tests that assert on the raw-list JSON shape - [ ] Write new Behave unit tests covering the envelope structure, filters, and summary counts - [ ] Write Robot Framework integration test asserting the envelope keys are present in JSON output - [ ] Run `nox` and confirm all stages pass with coverage >= 97% ## Definition of Done - [ ] All subtasks above are checked - [ ] `agents plan list --format json` output matches the spec envelope structure - [ ] `agents plan list --format yaml` output matches the spec envelope structure - [ ] Behave unit tests cover envelope keys, filters, and summary - [ ] Robot Framework integration test passes - [ ] Commit pushed to `fix/m5-plan-list-json-envelope` with message `fix(cli): wrap agents plan list JSON/YAML output in spec-required envelope` - [ ] PR merged and issue closed - [ ] All nox stages pass - [ ] Coverage >= 97% --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-new-issue-creator

freemo added this to the v3.5.0 milestone

2026-04-05 02:46:52 +00:00

freemo added a new dependency

2026-04-05 02:47:01 +00:00

#397 Epic: Server & Autonomy Infrastructure

freemo commented

2026-04-05 02:52:59 +00:00

Author

Owner

Issue triaged by project owner:

State: Verified
Priority: Medium (confirmed)
MoSCoW: Should Have — JSON output envelope missing per spec

Valid UAT finding verified during batch triage.

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

Issue triaged by project owner: - **State**: Verified - **Priority**: Medium (confirmed) - **MoSCoW**: Should Have — JSON output envelope missing per spec Valid UAT finding verified during batch triage. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: ca-project-owner

freemo commented

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

Author

Owner

Milestone Triage Decision: Moved to Backlog

This CLI output formatting issue has been moved out of v3.5.0 during aggressive milestone triage. While important for spec compliance, it does not block core autonomy hardening functionality.

Reasoning:

v3.5.0 focus: Essential autonomy hardening (guard enforcement, A2A facade, plan lifecycle)
This issue: CLI output formatting (plan list envelope) - spec compliance
Impact: UX consistency, not functional capability

Will be addressed in a future milestone focused on CLI polish and spec compliance.

**Milestone Triage Decision: Moved to Backlog** This CLI output formatting issue has been moved out of v3.5.0 during aggressive milestone triage. While important for spec compliance, it does not block core autonomy hardening functionality. **Reasoning:** - v3.5.0 focus: Essential autonomy hardening (guard enforcement, A2A facade, plan lifecycle) - This issue: CLI output formatting (`plan list` envelope) - spec compliance - Impact: UX consistency, not functional capability Will be addressed in a future milestone focused on CLI polish and spec compliance.

freemo commented

2026-04-06 22:45:20 +00:00

Author

Owner

This issue has been moved to the backlog as part of an aggressive grooming of the v3.5.0 milestone. It has been deemed non-critical for the minimal viability of the milestone and will be addressed in a future release.