UAT: `agents plan explain` JSON/YAML output format deviates from spec — missing envelope, impact section, correction_hint, and alternatives format #4708

New issue

Open

opened 2026-04-08 18:04:24 +00:00 by HAL9000 · 0 comments

HAL9000 commented

2026-04-08 18:04:24 +00:00

Owner

Bug Report

Feature Area: Decision tree and correction model — agents plan explain CLI output
Severity: Medium — output is functional but does not match the spec-required format
Source: src/cleveragents/cli/commands/plan.py lines 3888–3910

What Was Tested

Code-level analysis of the explain_decision_cmd CLI command to verify that its JSON/YAML output format matches the specification.

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

The spec defines a structured 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", "chosen": false }
    ],
    "impact": {
      "downstream_decisions": 3,
      "downstream_child_plans": 2,
      "artifacts_produced": 5,
      "correction_impact": "medium"
    },
    "context_snapshot": { "items": [...], "hot_context_hash": "sha256:..." },
    "rationale": "...",
    "correction_hint": "agents plan correct <id> --mode revert --guidance \"...\""
  },
  "timing": { "started": "...", "duration_ms": 110 },
  "messages": ["Decision explained"]
}

Actual Behavior

The implementation (lines 3888–3910) outputs a flat dict without the spec-required envelope:

data = {
    "decision_id": ...,
    "plan_id": ...,
    "type": ...,
    "sequence": 2,                    # Integer, not "2 of 5"
    "question": ...,
    "chosen": ...,
    "confidence": ...,
    "parent": ...,
    "is_correction": ...,
    "superseded": ...,
    "created_at": ...,
    "alternatives_considered": [...],  # List of strings, not objects
    # No "impact" section
    # No "correction_hint" field
    # No envelope (command, status, exit_code, timing, messages)
}

Deviations:

Missing envelope: No command, status, exit_code, timing, messages wrapper
sequence format: Returns integer 2 instead of "2 of 5" (N of total)
alternatives format: Returns alternatives_considered: ["str1", "str2"] instead of alternatives: [{index, description, chosen}]
Missing impact section: No downstream_decisions, downstream_child_plans, artifacts_produced, correction_impact
Missing correction_hint: No agents plan correct <id> --mode revert --guidance "..." hint
Extra non-spec fields: parent, is_correction, superseded are not in the spec output
created_at vs created: Uses created_at (ISO datetime) instead of spec's created

Code Location

src/cleveragents/cli/commands/plan.py lines 3803–3838 — _build_explain_dict() function
src/cleveragents/cli/commands/plan.py lines 3888–3910 — explain_decision_cmd() output

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

## Bug Report **Feature Area:** Decision tree and correction model — `agents plan explain` CLI output **Severity:** Medium — output is functional but does not match the spec-required format **Source:** `src/cleveragents/cli/commands/plan.py` lines 3888–3910 --- ## What Was Tested Code-level analysis of the `explain_decision_cmd` CLI command to verify that its JSON/YAML output format matches the specification. ## Expected Behavior (from spec §agents plan explain, lines 14546–14703) The spec defines a structured 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", "chosen": false } ], "impact": { "downstream_decisions": 3, "downstream_child_plans": 2, "artifacts_produced": 5, "correction_impact": "medium" }, "context_snapshot": { "items": [...], "hot_context_hash": "sha256:..." }, "rationale": "...", "correction_hint": "agents plan correct <id> --mode revert --guidance \"...\"" }, "timing": { "started": "...", "duration_ms": 110 }, "messages": ["Decision explained"] } ``` ## Actual Behavior The implementation (lines 3888–3910) outputs a flat dict without the spec-required envelope: ```python data = { "decision_id": ..., "plan_id": ..., "type": ..., "sequence": 2, # Integer, not "2 of 5" "question": ..., "chosen": ..., "confidence": ..., "parent": ..., "is_correction": ..., "superseded": ..., "created_at": ..., "alternatives_considered": [...], # List of strings, not objects # No "impact" section # No "correction_hint" field # No envelope (command, status, exit_code, timing, messages) } ``` ### Deviations: 1. **Missing envelope**: No `command`, `status`, `exit_code`, `timing`, `messages` wrapper 2. **`sequence` format**: Returns integer `2` instead of `"2 of 5"` (N of total) 3. **`alternatives` format**: Returns `alternatives_considered: ["str1", "str2"]` instead of `alternatives: [{index, description, chosen}]` 4. **Missing `impact` section**: No `downstream_decisions`, `downstream_child_plans`, `artifacts_produced`, `correction_impact` 5. **Missing `correction_hint`**: No `agents plan correct <id> --mode revert --guidance "..."` hint 6. **Extra non-spec fields**: `parent`, `is_correction`, `superseded` are not in the spec output 7. **`created_at` vs `created`**: Uses `created_at` (ISO datetime) instead of spec's `created` ## Code Location - `src/cleveragents/cli/commands/plan.py` lines 3803–3838 — `_build_explain_dict()` function - `src/cleveragents/cli/commands/plan.py` lines 3888–3910 — `explain_decision_cmd()` output --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: uat-tester

Rows
Columns

UAT: agents plan explain JSON/YAML output format deviates from spec — missing envelope, impact section, correction_hint, and alternatives format #4708