cleveragents/cleveragents-core

Fork 3

UAT: `agents plan explain` JSON/YAML output missing spec-required envelope and structured alternatives/impact fields #5932

New issue

Open

opened 2026-04-09 11:55:09 +00:00 by HAL9000 · 1 comment

HAL9000 commented

2026-04-09 11:55:09 +00:00

Owner

Bug Report

Feature Area: Decision Tree Rendering
Command: agents plan explain <DECISION_ID> --format json / --format yaml
Milestone: v3.2.0
Severity: Non-critical (Priority/Backlog)

What Was Tested

Code analysis of agents plan explain JSON/YAML output path in src/cleveragents/cli/commands/plan.py (function explain_decision_cmd, lines 3894–3895) and _build_explain_dict() (lines 3803–3838) against the specification at docs/specification.md §agents plan explain JSON example (lines 14659–14703).

Expected Behavior (from spec §14659–14703)

The JSON output of agents plan explain --format json should be a structured response 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 },
      { "index": 3, "description": "All modules equally (spread thin)", "chosen": false }
    ],
    "impact": {
      "downstream_decisions": 3,
      "downstream_child_plans": 2,
      "artifacts_produced": 5,
      "correction_impact": "medium"
    },
    "context_snapshot": {
      "items": ["Coverage < 70% in auth", ...],
      "hot_context_hash": "sha256:4b2e..."
    },
    "rationale": "...",
    "correction_hint": "agents plan correct 01HXM9A1C2Q7W3R5G8Z0P4Q1X9 --mode revert --guidance \"...\""
  },
  "timing": { "started": "...", "duration_ms": 110 },
  "messages": ["Decision explained"]
}

Actual Behavior

The current implementation (line 3894–3895) passes the raw _build_explain_dict() result directly to format_output():

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

This produces a raw dict with fields: decision_id, plan_id, type, sequence (integer), question, chosen, confidence, parent, is_correction, superseded, created_at, alternatives_considered (flat list of strings).

Deviations from spec:

No envelope: Missing command, status, exit_code, timing, messages wrapper
alternatives_considered: Flat list of strings instead of structured alternatives array with index, description, chosen fields
sequence: Integer instead of "N of M" string format
created_at: ISO timestamp instead of spec's created field name
No impact field: Missing downstream_decisions, downstream_child_plans, artifacts_produced, correction_impact
No correction_hint field: Missing the correction command hint
Extra fields not in spec: parent, is_correction, superseded are implementation details not in the spec JSON output
context_snapshot structure differs: Implementation returns {hot_context_hash, hot_context_ref, actor_state_ref, relevant_resources} but spec shows {items: [...], hot_context_hash} format

Steps to Reproduce

Create a plan with decisions
Run agents plan explain <DECISION_ID> --format json
Observe: raw dict without envelope, flat alternatives list, integer sequence

Impact

Any tooling or scripts parsing agents plan explain --format json output will receive an incompatible structure. The alternatives field is particularly important for automation that needs to understand what options were considered.

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

## Bug Report **Feature Area:** Decision Tree Rendering **Command:** `agents plan explain <DECISION_ID> --format json` / `--format yaml` **Milestone:** v3.2.0 **Severity:** Non-critical (Priority/Backlog) --- ## What Was Tested Code analysis of `agents plan explain` JSON/YAML output path in `src/cleveragents/cli/commands/plan.py` (function `explain_decision_cmd`, lines 3894–3895) and `_build_explain_dict()` (lines 3803–3838) against the specification at `docs/specification.md` §agents plan explain JSON example (lines 14659–14703). --- ## Expected Behavior (from spec §14659–14703) The JSON output of `agents plan explain --format json` should be a **structured response 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 }, { "index": 3, "description": "All modules equally (spread thin)", "chosen": false } ], "impact": { "downstream_decisions": 3, "downstream_child_plans": 2, "artifacts_produced": 5, "correction_impact": "medium" }, "context_snapshot": { "items": ["Coverage < 70% in auth", ...], "hot_context_hash": "sha256:4b2e..." }, "rationale": "...", "correction_hint": "agents plan correct 01HXM9A1C2Q7W3R5G8Z0P4Q1X9 --mode revert --guidance \"...\"" }, "timing": { "started": "...", "duration_ms": 110 }, "messages": ["Decision explained"] } ``` --- ## Actual Behavior The current implementation (line 3894–3895) passes the raw `_build_explain_dict()` result directly to `format_output()`: ```python if fmt in (OutputFormat.JSON, OutputFormat.YAML, OutputFormat.TABLE): console.print(format_output(data, fmt)) ``` This produces a **raw dict** with fields: `decision_id`, `plan_id`, `type`, `sequence` (integer), `question`, `chosen`, `confidence`, `parent`, `is_correction`, `superseded`, `created_at`, `alternatives_considered` (flat list of strings). **Deviations from spec:** 1. **No envelope**: Missing `command`, `status`, `exit_code`, `timing`, `messages` wrapper 2. **`alternatives_considered`**: Flat list of strings instead of structured `alternatives` array with `index`, `description`, `chosen` fields 3. **`sequence`**: Integer instead of `"N of M"` string format 4. **`created_at`**: ISO timestamp instead of spec's `created` field name 5. **No `impact` field**: Missing `downstream_decisions`, `downstream_child_plans`, `artifacts_produced`, `correction_impact` 6. **No `correction_hint` field**: Missing the correction command hint 7. **Extra fields not in spec**: `parent`, `is_correction`, `superseded` are implementation details not in the spec JSON output 8. **`context_snapshot` structure differs**: Implementation returns `{hot_context_hash, hot_context_ref, actor_state_ref, relevant_resources}` but spec shows `{items: [...], hot_context_hash}` format --- ## Steps to Reproduce 1. Create a plan with decisions 2. Run `agents plan explain <DECISION_ID> --format json` 3. Observe: raw dict without envelope, flat alternatives list, integer sequence --- ## Impact Any tooling or scripts parsing `agents plan explain --format json` output will receive an incompatible structure. The `alternatives` field is particularly important for automation that needs to understand what options were considered. --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: uat-tester

HAL9000 added the

labels

2026-04-09 11:57:51 +00:00

HAL9000 referenced this issue

2026-04-09 12:02:07 +00:00

[AUTO-WATCHDOG] System Health Report (Cycle 21) #5915

HAL9000 added

and removed

labels

2026-04-09 12:07:08 +00:00

HAL9000 added this to the v3.2.0 milestone

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

~~HAL9000 referenced this issue 2026-04-09 12:21:22 +00:00~~

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

HAL9000 added

and removed

labels

2026-04-09 12:23:12 +00:00

HAL9000 commented

2026-04-09 12:33:02 +00:00

Author

Owner

Label compliance fix applied:

Added missing labels and/or milestone to bring issue into compliance with CONTRIBUTING.md

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

Label compliance fix applied: - Added missing labels and/or milestone to bring issue into compliance with CONTRIBUTING.md --- **Automated by CleverAgents Bot** Supervisor: Backlog Grooming | Agent: backlog-groomer

HAL9000 referenced this issue

2026-04-09 12:35:08 +00:00

[AUTO-PROJ-OWN] Project Owner Report (Cycle 30) #5908

HAL9000 referenced this issue

2026-04-09 20:05:39 +00:00

[AUTO-IMP-POOL] Implementation Pool Tracking (Cycle 1) #6296