UAT: `agents plan tree` JSON/YAML output missing spec-required envelope and summary fields #2048

New issue

Open

opened 2026-04-03 03:37:20 +00:00 by freemo · 1 comment

freemo commented

2026-04-03 03:37:20 +00:00

Owner

Metadata

Branch: fix/plan-tree-json-yaml-envelope
Commit Message: fix(cli): add spec-required envelope and summary fields to plan tree JSON/YAML output
Milestone: v3.7.0
Parent Epic: #394

Background

The agents plan tree command's JSON and YAML output formats do not match the specification (§14423–14543). The implementation outputs a raw array of tree nodes, but the spec requires a full structured envelope with additional metadata fields including command, status, exit_code, data (with plan_id, tree, summary, child_plans, decision_ids), timing, and messages.

Code location: src/cleveragents/cli/commands/plan.py, function tree_decisions_cmd (~line 3610–3737)

Expected behavior (from spec §14423–14543)

The JSON output should be:

{
  "command": "plan tree",
  "status": "ok",
  "exit_code": 0,
  "data": {
    "plan_id": "<PLAN_ID>",
    "tree": { "...nested tree structure..." },
    "summary": {
      "nodes": "<count>",
      "depth": "<depth>",
      "child_plans": "<count>",
      "invariants": "<count>",
      "superseded": "<count>"
    },
    "child_plans": ["..."],
    "decision_ids": {}
  },
  "timing": { "started": "...", "duration_ms": "..." },
  "messages": ["Decision tree rendered"]
}

Actual behavior

The implementation at tree_decisions_cmd (~line 3610) outputs only the raw tree array when --format json or --format yaml is used:

if fmt in (OutputFormat.JSON, OutputFormat.YAML):
    console.print(format_output(tree_data, fmt))

This produces just the raw list of tree nodes without:

The command, status, exit_code envelope fields
The data.plan_id field
The data.summary section (nodes count, depth, child_plans, invariants, superseded count)
The data.child_plans section (child plan IDs with phase/state)
The data.decision_ids section (named decision IDs for correction)
The timing section
The messages array

Additionally, the rich/plain output is missing the spec-required "Tree Summary" panel, "Child Plans" panel, and "Decision IDs (for correction)" panel.

Steps to Reproduce

Create a plan with decisions
Run agents plan tree <PLAN_ID> --format json
Observe the output is a raw array, not the spec-required envelope structure

Subtasks

Add spec-required envelope structure (command, status, exit_code, data, timing, messages) to JSON/YAML output in tree_decisions_cmd
Add data.summary section with node count, depth, child_plans count, invariants count, and superseded count
Add data.child_plans section with phase/state info for each child plan
Add data.decision_ids section for correction convenience
Add data.plan_id field to the data envelope
Add "Tree Summary" panel to rich/plain output
Add "Child Plans" panel to rich/plain output
Add "Decision IDs (for correction)" panel to rich/plain output
Write failing BDD (Behave) scenario capturing the missing envelope structure (TDD — commit before fix)
Implement the fix so all new BDD scenarios pass

Definition of Done

All subtasks above are checked off
agents plan tree <PLAN_ID> --format json outputs the full spec-required envelope structure
agents plan tree <PLAN_ID> --format yaml outputs the full spec-required envelope structure
agents plan tree <PLAN_ID> (rich output) shows "Tree Summary", "Child Plans", and "Decision IDs (for correction)" panels
Failing BDD scenario committed before fix (TDD workflow followed)
All existing tests continue to pass
New BDD tests cover the JSON/YAML envelope structure and all new rich panels
All nox stages pass (nox -e lint, nox -e typecheck, nox -e unit_tests, nox -e integration_tests)
Coverage >= 97%
Commit created with message: fix(cli): add spec-required envelope and summary fields to plan tree JSON/YAML output
Branch fix/plan-tree-json-yaml-envelope pushed and PR opened against main
PR merged and this issue closed

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

## Metadata - **Branch**: `fix/plan-tree-json-yaml-envelope` - **Commit Message**: `fix(cli): add spec-required envelope and summary fields to plan tree JSON/YAML output` - **Milestone**: v3.7.0 - **Parent Epic**: #394 ## Background The `agents plan tree` command's JSON and YAML output formats do not match the specification (§14423–14543). The implementation outputs a raw array of tree nodes, but the spec requires a full structured envelope with additional metadata fields including `command`, `status`, `exit_code`, `data` (with `plan_id`, `tree`, `summary`, `child_plans`, `decision_ids`), `timing`, and `messages`. **Code location**: `src/cleveragents/cli/commands/plan.py`, function `tree_decisions_cmd` (~line 3610–3737) ### Expected behavior (from spec §14423–14543) The JSON output should be: ```json { "command": "plan tree", "status": "ok", "exit_code": 0, "data": { "plan_id": "<PLAN_ID>", "tree": { "...nested tree structure..." }, "summary": { "nodes": "<count>", "depth": "<depth>", "child_plans": "<count>", "invariants": "<count>", "superseded": "<count>" }, "child_plans": ["..."], "decision_ids": {} }, "timing": { "started": "...", "duration_ms": "..." }, "messages": ["Decision tree rendered"] } ``` ### Actual behavior The implementation at `tree_decisions_cmd` (~line 3610) outputs only the raw tree array when `--format json` or `--format yaml` is used: ```python if fmt in (OutputFormat.JSON, OutputFormat.YAML): console.print(format_output(tree_data, fmt)) ``` This produces just the raw list of tree nodes without: - The `command`, `status`, `exit_code` envelope fields - The `data.plan_id` field - The `data.summary` section (nodes count, depth, child_plans, invariants, superseded count) - The `data.child_plans` section (child plan IDs with phase/state) - The `data.decision_ids` section (named decision IDs for correction) - The `timing` section - The `messages` array Additionally, the rich/plain output is missing the spec-required "Tree Summary" panel, "Child Plans" panel, and "Decision IDs (for correction)" panel. ### Steps to Reproduce 1. Create a plan with decisions 2. Run `agents plan tree <PLAN_ID> --format json` 3. Observe the output is a raw array, not the spec-required envelope structure ## Subtasks - [ ] Add spec-required envelope structure (`command`, `status`, `exit_code`, `data`, `timing`, `messages`) to JSON/YAML output in `tree_decisions_cmd` - [ ] Add `data.summary` section with node count, depth, child_plans count, invariants count, and superseded count - [ ] Add `data.child_plans` section with phase/state info for each child plan - [ ] Add `data.decision_ids` section for correction convenience - [ ] Add `data.plan_id` field to the `data` envelope - [ ] Add "Tree Summary" panel to rich/plain output - [ ] Add "Child Plans" panel to rich/plain output - [ ] Add "Decision IDs (for correction)" panel to rich/plain output - [ ] Write failing BDD (Behave) scenario capturing the missing envelope structure (TDD — commit before fix) - [ ] Implement the fix so all new BDD scenarios pass ## Definition of Done - [ ] All subtasks above are checked off - [ ] `agents plan tree <PLAN_ID> --format json` outputs the full spec-required envelope structure - [ ] `agents plan tree <PLAN_ID> --format yaml` outputs the full spec-required envelope structure - [ ] `agents plan tree <PLAN_ID>` (rich output) shows "Tree Summary", "Child Plans", and "Decision IDs (for correction)" panels - [ ] Failing BDD scenario committed before fix (TDD workflow followed) - [ ] All existing tests continue to pass - [ ] New BDD tests cover the JSON/YAML envelope structure and all new rich panels - [ ] All nox stages pass (`nox -e lint`, `nox -e typecheck`, `nox -e unit_tests`, `nox -e integration_tests`) - [ ] Coverage >= 97% - [ ] Commit created with message: `fix(cli): add spec-required envelope and summary fields to plan tree JSON/YAML output` - [ ] Branch `fix/plan-tree-json-yaml-envelope` pushed and PR opened against main - [ ] PR merged and this issue closed --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-new-issue-creator

freemo added this to the v3.7.0 milestone

2026-04-03 03:37:29 +00:00

freemo added a new dependency

2026-04-03 03:38:44 +00:00

#394 Epic: Decision Framework

freemo commented

2026-04-03 03:40:57 +00:00

Author

Owner

Issue triaged by project owner:

State: Verified
Priority: High (confirmed) — The agents plan tree JSON/YAML output is missing the entire spec-required envelope structure (§14423–14543). This is a significant spec-alignment gap affecting all programmatic consumers of the plan tree output.
Milestone: v3.7.0 (confirmed — part of the Plan Lifecycle Epic #394)
MoSCoW: Should Have — The spec defines a detailed envelope structure for JSON/YAML output including summary fields, child plans, decision IDs, and timing. The current raw array output is insufficient for programmatic use. Important for spec compliance and API consumers.
Parent Epic: #394 (confirmed correct)

Comprehensive issue with clear spec references and detailed subtask breakdown.

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

Issue triaged by project owner: - **State**: Verified - **Priority**: High (confirmed) — The `agents plan tree` JSON/YAML output is missing the entire spec-required envelope structure (§14423–14543). This is a significant spec-alignment gap affecting all programmatic consumers of the plan tree output. - **Milestone**: v3.7.0 (confirmed — part of the Plan Lifecycle Epic #394) - **MoSCoW**: Should Have — The spec defines a detailed envelope structure for JSON/YAML output including summary fields, child plans, decision IDs, and timing. The current raw array output is insufficient for programmatic use. Important for spec compliance and API consumers. - **Parent Epic**: #394 (confirmed correct) Comprehensive issue with clear spec references and detailed subtask breakdown. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: ca-project-owner

freemo referenced this issue

2026-04-03 03:41:08 +00:00

[UAT-SUPERVISOR] Progress Report — Cycle 681 — v3.7.0 #2049

freemo referenced this issue

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

[CA-AUTO] UAT Pool Supervisor — v3.7.0 — Session Tracker #2023

freemo referenced this issue

2026-04-03 03:57:57 +00:00

[CA-AUTO] UAT Pool Supervisor — v3.7.0 — Session Tracker #2023

freemo referenced this issue

2026-04-03 04:10:19 +00:00

[Milestone Review] v3.7.0 — Holistic Integration Review (2026-04-03) #2113