UAT: `agents plan explain --format json` output missing spec-required envelope, `impact`, `correction_hint`, and `alternatives` schema #6807

New issue

Open

opened 2026-04-10 02:11:46 +00:00 by HAL9000 · 0 comments

HAL9000 commented

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

Owner

What Was Tested

agents plan explain <DECISION_ID> --format json JSON output schema (code analysis of src/cleveragents/cli/commands/plan.py, _build_explain_dict function lines 4150–4185, and explain_decision_cmd lines 4241–4243).

Expected Behavior (from Spec §agents plan explain JSON output, lines 14662–14703)

The JSON output must be the standard CLI envelope:

{
  "command": "plan explain",
  "status": "ok",
  "exit_code": 0,
  "data": {
    "decision_id": "...",
    "type": "strategy_choice",
    "question": "...",
    "chosen": "...",
    "confidence": 0.82,
    "plan_id": "...",
    "sequence": "2 of 5",
    "created": "2026-02-08T12:58:00Z",
    "alternatives": [
      { "index": 1, "description": "...", "chosen": true },
      ...
    ],
    "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 calls format_output(data, fmt) where data is the raw dict from _build_explain_dict() — not wrapped in the spec-required envelope. The raw dict has these schema violations:

No command, status, exit_code, timing, messages top-level envelope — data dict is output directly without wrapping
impact object is completely absent — downstream_decision_ids, downstream_plan_ids, artifacts_produced from the Decision model are never surfaced
correction_hint field is absent — no ready-to-use correction command is included
alternatives has wrong shape — it's a flat list[str] (alternatives_considered from the domain model) instead of the required list[{index, description, chosen}] objects
sequence is raw int — should be "N of M" string

Steps to Reproduce

Review src/cleveragents/cli/commands/plan.py _build_explain_dict() lines 4150–4185
Review the if fmt in (OutputFormat.JSON, ...) branch at lines 4241–4242
Compare to spec §agents plan explain JSON output example

Code Reference

# _build_explain_dict — missing impact, correction_hint, wrong alternatives shape
data: dict[str, object] = {
    "decision_id": decision.decision_id,
    ...
    "alternatives_considered": decision.alternatives_considered,  # flat list, wrong shape
    # missing: impact, correction_hint, proper sequence format
}

# explain_decision_cmd — raw dict passed to format_output, missing envelope
if fmt in (OutputFormat.JSON, OutputFormat.YAML, OutputFormat.TABLE):
    console.print(format_output(data, fmt))  # no command/status/exit_code/timing/messages

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

## What Was Tested `agents plan explain <DECISION_ID> --format json` JSON output schema (code analysis of `src/cleveragents/cli/commands/plan.py`, `_build_explain_dict` function lines 4150–4185, and `explain_decision_cmd` lines 4241–4243). ## Expected Behavior (from Spec §agents plan explain JSON output, lines 14662–14703) The JSON output must be the standard CLI envelope: ```json { "command": "plan explain", "status": "ok", "exit_code": 0, "data": { "decision_id": "...", "type": "strategy_choice", "question": "...", "chosen": "...", "confidence": 0.82, "plan_id": "...", "sequence": "2 of 5", "created": "2026-02-08T12:58:00Z", "alternatives": [ { "index": 1, "description": "...", "chosen": true }, ... ], "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 calls `format_output(data, fmt)` where `data` is the raw dict from `_build_explain_dict()` — **not** wrapped in the spec-required envelope. The raw dict has these schema violations: 1. **No `command`, `status`, `exit_code`, `timing`, `messages` top-level envelope** — `data` dict is output directly without wrapping 2. **`impact` object is completely absent** — `downstream_decision_ids`, `downstream_plan_ids`, `artifacts_produced` from the Decision model are never surfaced 3. **`correction_hint` field is absent** — no ready-to-use correction command is included 4. **`alternatives` has wrong shape** — it's a flat `list[str]` (`alternatives_considered` from the domain model) instead of the required `list[{index, description, chosen}]` objects 5. **`sequence` is raw int** — should be `"N of M"` string ## Steps to Reproduce 1. Review `src/cleveragents/cli/commands/plan.py` `_build_explain_dict()` lines 4150–4185 2. Review the `if fmt in (OutputFormat.JSON, ...)` branch at lines 4241–4242 3. Compare to spec §agents plan explain JSON output example ## Code Reference ```python # _build_explain_dict — missing impact, correction_hint, wrong alternatives shape data: dict[str, object] = { "decision_id": decision.decision_id, ... "alternatives_considered": decision.alternatives_considered, # flat list, wrong shape # missing: impact, correction_hint, proper sequence format } # explain_decision_cmd — raw dict passed to format_output, missing envelope if fmt in (OutputFormat.JSON, OutputFormat.YAML, OutputFormat.TABLE): console.print(format_output(data, fmt)) # no command/status/exit_code/timing/messages ``` --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: uat-tester

Rows
Columns

UAT: agents plan explain --format json output missing spec-required envelope, impact, correction_hint, and alternatives schema #6807