UAT: `agents plan explain` JSON/YAML output missing envelope, structured alternatives, and impact fields #3174

New issue

Open

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

freemo commented

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

Owner

Metadata

Branch: bugfix/plan-explain-json-output-spec-compliance
Commit Message: fix(cli): add spec-required envelope and structured fields to plan explain 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 3493–3562: explain_decision_cmd command
Lines 3455–3490: _build_explain_dict helper function
Lines 3546–3547: JSON/YAML output rendering

Spec Reference

docs/specification.md lines 14658–14755 (JSON and YAML output for agents plan explain)

Expected behavior (from spec)

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

{
  "command": "plan explain",
  "status": "ok",
  "exit_code": 0,
  "data": {
    "decision_id": "...",
    "type": "strategy_choice",
    "question": "Which modules should be prioritized?",
    "chosen": "Auth and payments",
    "confidence": 0.82,
    "plan_id": "...",
    "sequence": "2 of 5",
    "created": "2026-02-08T12:58:00Z",
    "alternatives": [
      { "index": 1, "description": "Auth and payments", "chosen": true },
      { "index": 2, "description": "User module first (coverage 71%, med risk)", "chosen": false },
      { "index": 3, "description": "All modules equally (spread thin)", "chosen": false }
    ],
    "impact": {
      "downstream_decisions": 3,
      "downstream_child_plans": 2,
      "artifacts_produced": 5,
      "correction_impact": "medium"
    },
    "rationale": "...",
    "correction_hint": "agents plan correct <DECISION_ID> --mode revert --guidance ..."
  },
  "timing": { "started": "...", "duration_ms": 110 },
  "messages": ["Decision explained"]
}

Actual behavior (from code analysis)

The current implementation (lines 3546–3547):

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

This outputs the raw data dict with NO envelope. Multiple fields are wrong or missing:

No envelope: Missing command, status, exit_code, timing, messages wrapper
alternatives_considered is a raw list of strings (e.g., ["Option A", "Option B"]) — spec requires structured objects with index, description, chosen fields
sequence is a bare number (e.g., 3) — spec requires "N of M" format (e.g., "3 of 7")
No impact field — downstream_decisions, downstream_child_plans, artifacts_produced, correction_impact are completely absent
No correction_hint field — the correction command hint is absent
Extra non-spec fields: parent, is_correction, superseded, actor_reasoning are included but not in the spec's JSON output

Code location

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

Lines 3546–3547: JSON/YAML output — bare format_output(data, fmt) with no envelope
Lines 3455–3490: _build_explain_dict — missing impact, correction_hint; alternatives_considered is raw strings; sequence is a number

Steps to reproduce

Create a plan with decisions recorded
Run: agents plan explain <DECISION_ID> --format json
Observe: A bare dict with wrong field names, no envelope, no impact, no correction hint, raw string alternatives

Impact

This directly blocks the v3.2.0 milestone acceptance criterion:

agents plan explain shows decision details including alternatives considered

The alternatives field is present but in the wrong format (raw strings vs. structured objects with index/description/chosen).

Subtasks

Wrap JSON/YAML output in the spec-required envelope (command, status, exit_code, data, timing, messages)
Convert alternatives_considered to structured list: [{"index": N, "description": "...", "chosen": bool}]
Fix sequence to "N of M" format
Add impact field (requires downstream decision/child plan count from decision service)
Add correction_hint field with the correction command string
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 14658–14755
alternatives is a structured list with index, description, chosen fields
sequence is in "N of M" format
impact field is present with all required sub-fields
correction_hint field is present
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-explain-json-output-spec-compliance` - **Commit Message**: `fix(cli): add spec-required envelope and structured fields to plan explain 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 3493–3562: `explain_decision_cmd` command - Lines 3455–3490: `_build_explain_dict` helper function - Lines 3546–3547: JSON/YAML output rendering ### Spec Reference `docs/specification.md` lines 14658–14755 (JSON and YAML output for `agents plan explain`) ### Expected behavior (from spec) The `agents plan explain` JSON output must be a full envelope: ```json { "command": "plan explain", "status": "ok", "exit_code": 0, "data": { "decision_id": "...", "type": "strategy_choice", "question": "Which modules should be prioritized?", "chosen": "Auth and payments", "confidence": 0.82, "plan_id": "...", "sequence": "2 of 5", "created": "2026-02-08T12:58:00Z", "alternatives": [ { "index": 1, "description": "Auth and payments", "chosen": true }, { "index": 2, "description": "User module first (coverage 71%, med risk)", "chosen": false }, { "index": 3, "description": "All modules equally (spread thin)", "chosen": false } ], "impact": { "downstream_decisions": 3, "downstream_child_plans": 2, "artifacts_produced": 5, "correction_impact": "medium" }, "rationale": "...", "correction_hint": "agents plan correct <DECISION_ID> --mode revert --guidance ..." }, "timing": { "started": "...", "duration_ms": 110 }, "messages": ["Decision explained"] } ``` ### Actual behavior (from code analysis) The current implementation (lines 3546–3547): ```python if fmt in (OutputFormat.JSON, OutputFormat.YAML, OutputFormat.TABLE): console.print(format_output(data, fmt)) ``` This outputs the raw `data` dict with NO envelope. Multiple fields are wrong or missing: 1. **No envelope**: Missing `command`, `status`, `exit_code`, `timing`, `messages` wrapper 2. **`alternatives_considered` is a raw list of strings** (e.g., `["Option A", "Option B"]`) — spec requires structured objects with `index`, `description`, `chosen` fields 3. **`sequence` is a bare number** (e.g., `3`) — spec requires "N of M" format (e.g., `"3 of 7"`) 4. **No `impact` field** — `downstream_decisions`, `downstream_child_plans`, `artifacts_produced`, `correction_impact` are completely absent 5. **No `correction_hint` field** — the correction command hint is absent 6. **Extra non-spec fields**: `parent`, `is_correction`, `superseded`, `actor_reasoning` are included but not in the spec's JSON output ### Code location `src/cleveragents/cli/commands/plan.py`: - Lines 3546–3547: JSON/YAML output — bare `format_output(data, fmt)` with no envelope - Lines 3455–3490: `_build_explain_dict` — missing `impact`, `correction_hint`; `alternatives_considered` is raw strings; `sequence` is a number ### Steps to reproduce 1. Create a plan with decisions recorded 2. Run: `agents plan explain <DECISION_ID> --format json` 3. Observe: A bare dict with wrong field names, no envelope, no impact, no correction hint, raw string alternatives ### Impact This directly blocks the v3.2.0 milestone acceptance criterion: > `agents plan explain` shows decision details including alternatives considered The `alternatives` field is present but in the wrong format (raw strings vs. structured objects with `index`/`description`/`chosen`). ## Subtasks - [ ] Wrap JSON/YAML output in the spec-required envelope (`command`, `status`, `exit_code`, `data`, `timing`, `messages`) - [ ] Convert `alternatives_considered` to structured list: `[{"index": N, "description": "...", "chosen": bool}]` - [ ] Fix `sequence` to "N of M" format - [ ] Add `impact` field (requires downstream decision/child plan count from decision service) - [ ] Add `correction_hint` field with the correction command string - [ ] 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 14658–14755 - `alternatives` is a structured list with `index`, `description`, `chosen` fields - `sequence` is in "N of M" format - `impact` field is present with all required sub-fields - `correction_hint` field is present - 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:40 +00:00

freemo added the

labels

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

freemo added a new dependency