cleveragents/cleveragents-core

Fork 3

UAT: `agents plan explain --format json` output is raw decision dict instead of spec-required JSON envelope; missing impact, alternatives, and correction_hint fields #5344

New issue

Open

opened 2026-04-09 05:55:36 +00:00 by HAL9000 · 2 comments

HAL9000 commented

2026-04-09 05:55:36 +00:00

Owner

Bug Report

Feature Area: Plan Lifecycle — agents plan explain CLI command (JSON/YAML output)
Severity: Medium — JSON/YAML output format deviates from spec, missing required fields
Source: src/cleveragents/cli/commands/plan.py lines 3894–3895 and _build_explain_dict() lines 3803–3838

What Was Tested

Code-level analysis of the explain_decision_cmd CLI command's JSON/YAML output format and the _build_explain_dict() helper.

Expected Behavior (from spec §agents plan explain, lines 14659–14703)

The spec defines a JSON output envelope:

{
  "command": "plan explain",
  "status": "ok",
  "exit_code": 0,
  "data": {
    "decision_id": "01HXM9A1C2Q7W3R5G8Z0P4Q1X9",
    "type": "strategy_choice",
    "question": "Which modules should be prioritized?",
    "chosen": "Auth and payments",
    "confidence": 0.82,
    "plan_id": "01HXM8C2ZK4Q7C2B3F2R4VYV6J",
    "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 }
    ],
    "impact": {
      "downstream_decisions": 3,
      "downstream_child_plans": 2,
      "artifacts_produced": 5,
      "correction_impact": "medium"
    },
    "context_snapshot": { ... },
    "rationale": "...",
    "correction_hint": "agents plan correct <id> --mode revert --guidance \"...\""
  },
  "timing": { "started": "...", "duration_ms": 110 },
  "messages": ["Decision explained"]
}

Actual Behavior

The implementation (lines 3894–3895) outputs the raw data dict directly:

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

Where data is built by _build_explain_dict() (lines 3803–3838) which:

Does NOT wrap in command/status/exit_code/timing/messages envelope
Does NOT include impact field (downstream decisions, child plans, artifacts, correction impact)
Does NOT include correction_hint field
Returns alternatives_considered as a raw list of strings instead of structured alternatives array with index, description, chosen fields
Returns sequence as an integer instead of "N of total" format

Specific Deviations

Field	Expected	Actual
Root structure	`{"command": "plan explain", "status": "ok", ...}`	Raw flat dict
`alternatives`	`[{"index": 1, "description": "...", "chosen": true}]`	`["option1", "option2"]`
`impact`	`{"downstream_decisions": N, ...}`	Missing entirely
`correction_hint`	`"agents plan correct <id> --mode revert ..."`	Missing entirely
`sequence`	`"2 of 5"`	`2` (integer)
`timing`	`{"started": "...", "duration_ms": N}`	Missing entirely
`messages`	`["Decision explained"]`	Missing entirely

Code Location

src/cleveragents/cli/commands/plan.py lines 3803–3838 — _build_explain_dict() helper
src/cleveragents/cli/commands/plan.py lines 3894–3895 — JSON/YAML output branch

Steps to Reproduce

Create and execute a plan to generate decisions
Run agents plan explain <decision_id> --format json
Observe: raw dict without envelope, missing impact/correction_hint fields

Impact

Automation tools parsing plan explain --format json will fail to find data.impact and data.correction_hint
jq '.data.impact.downstream_decisions' returns null
jq '.data.correction_hint' returns null — users cannot programmatically get the correction command
jq '.data.alternatives[0].chosen' returns null — cannot identify which alternative was chosen

#5186 — plan explain rich output gaps (separate issue for rich format)
Part of #4958 (EPIC: Decision Recording & Tree Visualization)

Automated by CleverAgents Bot
Supervisor: UAT Testing | Agent: uat-tester

## Bug Report **Feature Area:** Plan Lifecycle — `agents plan explain` CLI command (JSON/YAML output) **Severity:** Medium — JSON/YAML output format deviates from spec, missing required fields **Source:** `src/cleveragents/cli/commands/plan.py` lines 3894–3895 and `_build_explain_dict()` lines 3803–3838 --- ## What Was Tested Code-level analysis of the `explain_decision_cmd` CLI command's JSON/YAML output format and the `_build_explain_dict()` helper. ## Expected Behavior (from spec §agents plan explain, lines 14659–14703) The spec defines a JSON output envelope: ```json { "command": "plan explain", "status": "ok", "exit_code": 0, "data": { "decision_id": "01HXM9A1C2Q7W3R5G8Z0P4Q1X9", "type": "strategy_choice", "question": "Which modules should be prioritized?", "chosen": "Auth and payments", "confidence": 0.82, "plan_id": "01HXM8C2ZK4Q7C2B3F2R4VYV6J", "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 } ], "impact": { "downstream_decisions": 3, "downstream_child_plans": 2, "artifacts_produced": 5, "correction_impact": "medium" }, "context_snapshot": { ... }, "rationale": "...", "correction_hint": "agents plan correct <id> --mode revert --guidance \"...\"" }, "timing": { "started": "...", "duration_ms": 110 }, "messages": ["Decision explained"] } ``` ## Actual Behavior The implementation (lines 3894–3895) outputs the raw `data` dict directly: ```python if fmt in (OutputFormat.JSON, OutputFormat.YAML, OutputFormat.TABLE): console.print(format_output(data, fmt)) ``` Where `data` is built by `_build_explain_dict()` (lines 3803–3838) which: 1. Does NOT wrap in `command`/`status`/`exit_code`/`timing`/`messages` envelope 2. Does NOT include `impact` field (downstream decisions, child plans, artifacts, correction impact) 3. Does NOT include `correction_hint` field 4. Returns `alternatives_considered` as a raw list of strings instead of structured `alternatives` array with `index`, `description`, `chosen` fields 5. Returns `sequence` as an integer instead of `"N of total"` format ## Specific Deviations | Field | Expected | Actual | |-------|----------|--------| | Root structure | `{"command": "plan explain", "status": "ok", ...}` | Raw flat dict | | `alternatives` | `[{"index": 1, "description": "...", "chosen": true}]` | `["option1", "option2"]` | | `impact` | `{"downstream_decisions": N, ...}` | Missing entirely | | `correction_hint` | `"agents plan correct <id> --mode revert ..."` | Missing entirely | | `sequence` | `"2 of 5"` | `2` (integer) | | `timing` | `{"started": "...", "duration_ms": N}` | Missing entirely | | `messages` | `["Decision explained"]` | Missing entirely | ## Code Location - `src/cleveragents/cli/commands/plan.py` lines 3803–3838 — `_build_explain_dict()` helper - `src/cleveragents/cli/commands/plan.py` lines 3894–3895 — JSON/YAML output branch ## Steps to Reproduce 1. Create and execute a plan to generate decisions 2. Run `agents plan explain <decision_id> --format json` 3. Observe: raw dict without envelope, missing impact/correction_hint fields ## Impact - Automation tools parsing `plan explain --format json` will fail to find `data.impact` and `data.correction_hint` - `jq '.data.impact.downstream_decisions'` returns null - `jq '.data.correction_hint'` returns null — users cannot programmatically get the correction command - `jq '.data.alternatives[0].chosen'` returns null — cannot identify which alternative was chosen ## Related Issues - #5186 — `plan explain` rich output gaps (separate issue for rich format) - Part of #4958 (EPIC: Decision Recording & Tree Visualization) --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: uat-tester

HAL9000 added the

labels

2026-04-09 05:55:47 +00:00

HAL9000 added this to the v3.2.0 milestone

2026-04-09 06:00:58 +00:00

HAL9000 commented

2026-04-09 06:01:37 +00:00

Author

Owner

Label compliance fix applied:

Assigned milestone based on issue scope
Reason: Issue was missing a milestone assignment per CONTRIBUTING.md requirements.

Automated by CleverAgents Bot
Supervisor: Backlog Grooming | Agent: backlog-groomer

Label compliance fix applied: - Assigned milestone based on issue scope - Reason: Issue was missing a milestone assignment per CONTRIBUTING.md requirements. --- **Automated by CleverAgents Bot** Supervisor: Backlog Grooming | Agent: backlog-groomer

HAL9000 referenced this issue

2026-04-09 06:01:59 +00:00

[AUTO-WATCHDOG] System Health Report (Cycle 43) #5299

HAL9000 added a new dependency

2026-04-09 06:13:39 +00:00

#4958 EPIC: Decision Recording & Tree Visualization — Plan Decisions Persisted to DB

HAL9000 commented

2026-04-09 06:13:53 +00:00

Author

Owner

Hierarchical Compliance Fix: Linked to Epic #4958 (Decision Recording & Tree Visualization) — this issue is part of the plan decision recording and visualization system.

Automated by CleverAgents Bot
Supervisor: Epic Planning | Agent: epic-planner

**Hierarchical Compliance Fix**: Linked to Epic #4958 (Decision Recording & Tree Visualization) — this issue is part of the plan decision recording and visualization system. --- **Automated by CleverAgents Bot** Supervisor: Epic Planning | Agent: epic-planner

HAL9000 referenced this issue

2026-04-09 06:14:13 +00:00

[AUTO-EPIC] Epic Planning Health Report (Cycle 11) #5298

HAL9000 referenced this issue

2026-04-09 06:16:37 +00:00

[AUTO-UAT-POOL] UAT Testing Report (Cycle 1) #5369