[BUG] plan explain --format json output structure deviates from spec: missing fields and wrong field names #9276

New issue

Open

opened 2026-04-14 13:47:07 +00:00 by HAL9000 · 0 comments

HAL9000 commented

2026-04-14 13:47:07 +00:00

Owner

Metadata

Commit Message: fix(cli): align plan explain JSON output with spec — add impact, correction_hint, alternatives objects
Branch: fix/plan-explain-json-spec-alignment

Background and Context

The agents plan explain --format json command outputs a JSON structure that deviates from the specification in multiple ways. The spec (§CLI Commands — plan explain, line 14662–14703 of docs/specification.md) defines a precise JSON envelope structure for the plan explain command output.

This was discovered during UAT testing of the Decision Tree feature area (M3 milestone).

Current Behavior

The current _build_explain_dict() function in src/cleveragents/cli/commands/plan.py produces:

{
  "command": "",
  "status": "ok",
  "exit_code": 0,
  "data": {
    "decision_id": "...",
    "plan_id": "...",
    "type": "strategy_choice",
    "sequence": 2,
    "question": "...",
    "chosen": "...",
    "confidence": 0.82,
    "parent": "...",
    "is_correction": false,
    "superseded": false,
    "created_at": "2026-...",
    "alternatives_considered": ["Option A", "Option B"]
  },
  ...
}

Expected Behavior

Per the specification (docs/specification.md §agents plan explain), the JSON output should be:

{
  "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-...",
    "alternatives": [
      { "index": 1, "description": "Option A", "chosen": true },
      { "index": 2, "description": "Option B", "chosen": false }
    ],
    "impact": {
      "downstream_decisions": 3,
      "downstream_child_plans": 2,
      "artifacts_produced": 5,
      "correction_impact": "medium"
    },
    "context_snapshot": { ... },
    "rationale": "...",
    "correction_hint": "agents plan correct <decision_id> --mode revert --guidance ..."
  },
  "timing": { "started": "...", "duration_ms": 110 },
  "messages": ["Decision explained"]
}

Spec Deviations Found

Field	Current	Expected (Spec)
`alternatives_considered`	Flat list of strings	`alternatives` — list of objects with `index`, `description`, `chosen`
`impact`	Missing	Object with `downstream_decisions`, `downstream_child_plans`, `artifacts_produced`, `correction_impact`
`correction_hint`	Missing	String with correction command hint
`created_at`	ISO datetime string	`created` — ISO datetime string (field name differs)
`sequence`	Integer	String in "N of M" format
`command`	Empty string `""`	`"plan explain"`
`parent`	Present (not in spec)	Not in spec's data object
`is_correction`	Present (not in spec)	Not in spec's data object
`superseded`	Present (not in spec)	Not in spec's data object

Acceptance Criteria

agents plan explain <decision_id> --format json outputs "command": "plan explain" in the envelope
The data.alternatives field is a list of objects with index, description, and chosen keys
The data.impact field is present with downstream_decisions, downstream_child_plans, artifacts_produced, correction_impact
The data.correction_hint field is present with the correction command hint
The data.created field (not created_at) contains the ISO datetime
The data.sequence field is formatted as "N of M" string
BDD tests in features/plan_explain.feature pass for JSON format output

Supporting Information

Spec reference: docs/specification.md lines 14659–14703 (§agents plan explain — JSON tab)
Implementation: src/cleveragents/cli/commands/plan.py — _build_explain_dict() function (line ~4150) and explain_decision_cmd() (line ~4189)
Related known bug: @tdd_issue_4254 in features/plan_explain.feature (tree JSON format issue — separate but related)
UAT Test: Decision Tree feature area, M3 milestone acceptance criteria item 4: "agents plan explain <decision_id> shows decision details including alternatives"

Subtasks

Update _build_explain_dict() to use alternatives (list of objects) instead of alternatives_considered (flat list)
Add impact object to explain dict with downstream counts and correction impact
Add correction_hint field with formatted correction command
Rename created_at to created in explain dict
Format sequence as "N of M" string (requires total decision count)
Pass command="plan explain" to format_output() in explain_decision_cmd()
Update BDD scenarios in features/plan_explain.feature for JSON format
Run nox -s unit_tests -- features/plan_explain.feature and verify all pass
Run nox (all default sessions), fix any errors

Definition of Done

This issue is complete when:

All subtasks above are completed and checked off.
A Git commit is created where the first line of the commit message matches the Commit Message in Metadata exactly, followed by a blank line, then additional lines providing relevant details.
The commit is pushed to the remote on the branch matching the Branch in Metadata exactly.
The commit is submitted as a pull request to master, reviewed, and merged before this issue is marked done.

Automated by CleverAgents Bot
Supervisor: UAT Test Pool | Agent: uat-test-pool-supervisor

## Metadata - **Commit Message**: `fix(cli): align plan explain JSON output with spec — add impact, correction_hint, alternatives objects` - **Branch**: `fix/plan-explain-json-spec-alignment` ## Background and Context The `agents plan explain --format json` command outputs a JSON structure that deviates from the specification in multiple ways. The spec (§CLI Commands — plan explain, line 14662–14703 of docs/specification.md) defines a precise JSON envelope structure for the `plan explain` command output. This was discovered during UAT testing of the Decision Tree feature area (M3 milestone). ## Current Behavior The current `_build_explain_dict()` function in `src/cleveragents/cli/commands/plan.py` produces: ```json { "command": "", "status": "ok", "exit_code": 0, "data": { "decision_id": "...", "plan_id": "...", "type": "strategy_choice", "sequence": 2, "question": "...", "chosen": "...", "confidence": 0.82, "parent": "...", "is_correction": false, "superseded": false, "created_at": "2026-...", "alternatives_considered": ["Option A", "Option B"] }, ... } ``` ## Expected Behavior Per the specification (docs/specification.md §agents plan explain), the JSON output should be: ```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-...", "alternatives": [ { "index": 1, "description": "Option A", "chosen": true }, { "index": 2, "description": "Option B", "chosen": false } ], "impact": { "downstream_decisions": 3, "downstream_child_plans": 2, "artifacts_produced": 5, "correction_impact": "medium" }, "context_snapshot": { ... }, "rationale": "...", "correction_hint": "agents plan correct <decision_id> --mode revert --guidance ..." }, "timing": { "started": "...", "duration_ms": 110 }, "messages": ["Decision explained"] } ``` ## Spec Deviations Found | Field | Current | Expected (Spec) | |-------|---------|-----------------| | `alternatives_considered` | Flat list of strings | `alternatives` — list of objects with `index`, `description`, `chosen` | | `impact` | Missing | Object with `downstream_decisions`, `downstream_child_plans`, `artifacts_produced`, `correction_impact` | | `correction_hint` | Missing | String with correction command hint | | `created_at` | ISO datetime string | `created` — ISO datetime string (field name differs) | | `sequence` | Integer | String in "N of M" format | | `command` | Empty string `""` | `"plan explain"` | | `parent` | Present (not in spec) | Not in spec's data object | | `is_correction` | Present (not in spec) | Not in spec's data object | | `superseded` | Present (not in spec) | Not in spec's data object | ## Acceptance Criteria - [ ] `agents plan explain <decision_id> --format json` outputs `"command": "plan explain"` in the envelope - [ ] The `data.alternatives` field is a list of objects with `index`, `description`, and `chosen` keys - [ ] The `data.impact` field is present with `downstream_decisions`, `downstream_child_plans`, `artifacts_produced`, `correction_impact` - [ ] The `data.correction_hint` field is present with the correction command hint - [ ] The `data.created` field (not `created_at`) contains the ISO datetime - [ ] The `data.sequence` field is formatted as "N of M" string - [ ] BDD tests in `features/plan_explain.feature` pass for JSON format output ## Supporting Information - Spec reference: `docs/specification.md` lines 14659–14703 (§agents plan explain — JSON tab) - Implementation: `src/cleveragents/cli/commands/plan.py` — `_build_explain_dict()` function (line ~4150) and `explain_decision_cmd()` (line ~4189) - Related known bug: `@tdd_issue_4254` in `features/plan_explain.feature` (tree JSON format issue — separate but related) - UAT Test: Decision Tree feature area, M3 milestone acceptance criteria item 4: "`agents plan explain <decision_id>` shows decision details including alternatives" ## Subtasks - [ ] Update `_build_explain_dict()` to use `alternatives` (list of objects) instead of `alternatives_considered` (flat list) - [ ] Add `impact` object to explain dict with downstream counts and correction impact - [ ] Add `correction_hint` field with formatted correction command - [ ] Rename `created_at` to `created` in explain dict - [ ] Format `sequence` as "N of M" string (requires total decision count) - [ ] Pass `command="plan explain"` to `format_output()` in `explain_decision_cmd()` - [ ] Update BDD scenarios in `features/plan_explain.feature` for JSON format - [ ] Run `nox -s unit_tests -- features/plan_explain.feature` and verify all pass - [ ] Run `nox` (all default sessions), fix any errors ## Definition of Done This issue is complete when: - All subtasks above are completed and checked off. - A Git commit is created where the **first line** of the commit message matches the Commit Message in Metadata exactly, followed by a blank line, then additional lines providing relevant details. - The commit is pushed to the remote on the branch matching the **Branch** in Metadata exactly. - The commit is submitted as a **pull request** to `master`, reviewed, and **merged** before this issue is marked done. --- **Automated by CleverAgents Bot** Supervisor: UAT Test Pool | Agent: uat-test-pool-supervisor

HAL9000 added the

labels

2026-04-14 13:50:26 +00:00

HAL9000 referenced this issue

2026-04-14 14:18:18 +00:00

[AUTO-UAT-POOL] Status: UAT Test Pool Supervisor (Cycle 5) #9294