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

New issue

Open

opened 2026-04-05 07:17:32 +00:00 by freemo · 0 comments

freemo commented

2026-04-05 07:17:32 +00:00

Owner

Metadata

Branch: bugfix/plan-tree-json-output-spec-compliance
Commit Message: fix(cli): add spec-required envelope and data fields to plan tree JSON/YAML output
Milestone: v3.2.0
Parent Epic: #357

Bug Report

Feature Area: plan tree and plan explain CLI Commands (v3.2.0)

What was tested

Code analysis of src/cleveragents/cli/commands/plan.py:

Lines 3681–3682: JSON/YAML output in tree_decisions_cmd
Lines 3570–3643: build_decision_tree helper function

Spec Reference

docs/specification.md lines 14423–14543 (JSON and YAML output for agents plan tree)

Expected behavior (from spec)

The agents plan tree JSON output must be a full envelope:

{
  "command": "plan tree",
  "status": "ok",
  "exit_code": 0,
  "data": {
    "plan_id": "<PLAN_ID>",
    "tree": { "type": "...", "description": "...", "children": [...] },
    "summary": { "nodes": 9, "depth": 3, "child_plans": "2+", "invariants": 2, "superseded": 0 },
    "child_plans": [{ "id": "...", "phase": "...", "state": "..." }],
    "decision_ids": { "root": "...", "strategy": "...", "..." : "..." }
  },
  "timing": { "started": "...", "duration_ms": 85 },
  "messages": ["Decision tree rendered"]
}

The tree node structure must use type and description fields (not decision_id, question, chosen, sequence, superseded).

Actual behavior (from code analysis)

The current implementation (lines 3681–3682):

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

This outputs the raw tree_data list directly with NO envelope. The output is:

A bare list of tree node dicts (not wrapped in command/status/exit_code/data/timing/messages)
Each node uses wrong field names: decision_id, question, chosen, sequence, superseded instead of spec's type, description, confidence, children
Missing data.plan_id, data.summary, data.child_plans, data.decision_ids entirely

Code location

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

Lines 3681–3682: JSON/YAML output — bare format_output(tree_data, fmt) with no envelope
Lines 3609–3619: _node_dict function — uses wrong field names

Steps to reproduce

Create a plan with decisions recorded
Run: agents plan tree <PLAN_ID> --format json
Observe: A bare list of node dicts with wrong field names, no envelope

Impact

This directly blocks the v3.2.0 milestone acceptance criterion:

agents plan tree renders the decision tree correctly

Scripting and visualization tools that consume the JSON output will fail because the envelope structure is missing.

Subtasks

Wrap JSON/YAML output in the spec-required envelope (command, status, exit_code, data, timing, messages)
Fix tree node field names to use type and description (not decision_id, question, chosen)
Add data.plan_id, data.summary, data.child_plans, data.decision_ids to the data object
Add timing measurement
Add Behave unit tests for the new JSON/YAML structure
Verify nox passes

Definition of Done

JSON/YAML output matches the envelope structure in docs/specification.md lines 14423–14543
Tree node fields use type, description, confidence, children
All required data fields present: plan_id, tree, summary, child_plans, decision_ids
Tests pass and coverage ≥ 97%
All nox stages pass
Coverage >= 97%

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

## Metadata - **Branch**: `bugfix/plan-tree-json-output-spec-compliance` - **Commit Message**: `fix(cli): add spec-required envelope and data fields to plan tree JSON/YAML output` - **Milestone**: v3.2.0 - **Parent Epic**: #357 ## Bug Report **Feature Area**: plan tree and plan explain CLI Commands (v3.2.0) ### What was tested Code analysis of `src/cleveragents/cli/commands/plan.py`: - Lines 3681–3682: JSON/YAML output in `tree_decisions_cmd` - Lines 3570–3643: `build_decision_tree` helper function ### Spec Reference `docs/specification.md` lines 14423–14543 (JSON and YAML output for `agents plan tree`) ### Expected behavior (from spec) The `agents plan tree` JSON output must be a full envelope: ```json { "command": "plan tree", "status": "ok", "exit_code": 0, "data": { "plan_id": "<PLAN_ID>", "tree": { "type": "...", "description": "...", "children": [...] }, "summary": { "nodes": 9, "depth": 3, "child_plans": "2+", "invariants": 2, "superseded": 0 }, "child_plans": [{ "id": "...", "phase": "...", "state": "..." }], "decision_ids": { "root": "...", "strategy": "...", "..." : "..." } }, "timing": { "started": "...", "duration_ms": 85 }, "messages": ["Decision tree rendered"] } ``` The tree node structure must use `type` and `description` fields (not `decision_id`, `question`, `chosen`, `sequence`, `superseded`). ### Actual behavior (from code analysis) The current implementation (lines 3681–3682): ```python if fmt in (OutputFormat.JSON, OutputFormat.YAML): console.print(format_output(tree_data, fmt)) ``` This outputs the raw `tree_data` list directly with NO envelope. The output is: - A bare list of tree node dicts (not wrapped in `command`/`status`/`exit_code`/`data`/`timing`/`messages`) - Each node uses wrong field names: `decision_id`, `question`, `chosen`, `sequence`, `superseded` instead of spec's `type`, `description`, `confidence`, `children` - Missing `data.plan_id`, `data.summary`, `data.child_plans`, `data.decision_ids` entirely ### Code location `src/cleveragents/cli/commands/plan.py`: - Lines 3681–3682: JSON/YAML output — bare `format_output(tree_data, fmt)` with no envelope - Lines 3609–3619: `_node_dict` function — uses wrong field names ### Steps to reproduce 1. Create a plan with decisions recorded 2. Run: `agents plan tree <PLAN_ID> --format json` 3. Observe: A bare list of node dicts with wrong field names, no envelope ### Impact This directly blocks the v3.2.0 milestone acceptance criterion: > `agents plan tree` renders the decision tree correctly Scripting and visualization tools that consume the JSON output will fail because the envelope structure is missing. ## Subtasks - [ ] Wrap JSON/YAML output in the spec-required envelope (`command`, `status`, `exit_code`, `data`, `timing`, `messages`) - [ ] Fix tree node field names to use `type` and `description` (not `decision_id`, `question`, `chosen`) - [ ] Add `data.plan_id`, `data.summary`, `data.child_plans`, `data.decision_ids` to the data object - [ ] Add timing measurement - [ ] Add Behave unit tests for the new JSON/YAML structure - [ ] Verify `nox` passes ## Definition of Done - [ ] JSON/YAML output matches the envelope structure in `docs/specification.md` lines 14423–14543 - [ ] Tree node fields use `type`, `description`, `confidence`, `children` - [ ] All required data fields present: `plan_id`, `tree`, `summary`, `child_plans`, `decision_ids` - [ ] Tests pass and coverage ≥ 97% - [ ] All nox stages pass - [ ] Coverage >= 97% --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-new-issue-creator

freemo added this to the v3.2.0 milestone

2026-04-05 07:19:17 +00:00

freemo added a new dependency

2026-04-05 07:20:08 +00:00

#357 Epic: Decisions + Validations + Invariants (M3)

freemo added the