cleveragents/cleveragents-core

Fork 3

[BUG] `agents plan explain --format json/yaml` missing spec-required output envelope #9165

New issue

Open

opened 2026-04-14 08:59:23 +00:00 by HAL9000 · 1 comment

HAL9000 commented

2026-04-14 08:59:23 +00:00

Owner

Metadata

Commit Message: fix(plan): wrap plan explain JSON/YAML output in spec-required command envelope
Branch: fix/plan-explain-json-output-envelope

Background and Context

The spec (docs/specification.md §agents plan explain, lines 14659–14756) defines the required JSON and YAML output format for agents plan explain --format json. The output must be wrapped in a standard command envelope.

Current Behavior

The explain_decision_cmd() function in src/cleveragents/cli/commands/plan.py (lines 4241–4242) outputs the raw dict directly without the required envelope.

Expected Behavior

Per docs/specification.md lines 14659–14703, agents plan explain --format json must return:

{
  "command": "plan explain",
  "status": "ok",
  "exit_code": 0,
  "data": { "decision_id": "...", "type": "...", ... },
  "timing": { "started": "...", "duration_ms": N },
  "messages": ["Decision explained"]
}

Acceptance Criteria

agents plan explain <DECISION_ID> --format json returns a JSON object with command, status, exit_code, data, timing, messages keys
agents plan explain <DECISION_ID> --format yaml returns the same structure in YAML format
messages contains ["Decision explained"]
BDD tests updated to verify envelope structure

Subtasks

Update explain_decision_cmd() to wrap JSON/YAML output in spec-required envelope
Add timing computation
Update BDD tests in features/plan_explain.feature to verify envelope structure

Definition of Done

agents plan explain --format json returns spec-compliant envelope
All BDD tests pass

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

## Metadata - **Commit Message**: `fix(plan): wrap plan explain JSON/YAML output in spec-required command envelope` - **Branch**: `fix/plan-explain-json-output-envelope` ## Background and Context The spec (`docs/specification.md` §agents plan explain, lines 14659–14756) defines the required JSON and YAML output format for `agents plan explain --format json`. The output must be wrapped in a standard command envelope. ## Current Behavior The `explain_decision_cmd()` function in `src/cleveragents/cli/commands/plan.py` (lines 4241–4242) outputs the raw dict directly without the required envelope. ## Expected Behavior Per `docs/specification.md` lines 14659–14703, `agents plan explain --format json` must return: ```json { "command": "plan explain", "status": "ok", "exit_code": 0, "data": { "decision_id": "...", "type": "...", ... }, "timing": { "started": "...", "duration_ms": N }, "messages": ["Decision explained"] } ``` ## Acceptance Criteria - [ ] `agents plan explain <DECISION_ID> --format json` returns a JSON object with `command`, `status`, `exit_code`, `data`, `timing`, `messages` keys - [ ] `agents plan explain <DECISION_ID> --format yaml` returns the same structure in YAML format - [ ] `messages` contains `["Decision explained"]` - [ ] BDD tests updated to verify envelope structure ## Subtasks - [ ] Update `explain_decision_cmd()` to wrap JSON/YAML output in spec-required envelope - [ ] Add `timing` computation - [ ] Update BDD tests in `features/plan_explain.feature` to verify envelope structure ## Definition of Done - `agents plan explain --format json` returns spec-compliant envelope - All BDD tests pass --- **Automated by CleverAgents Bot** Supervisor: UAT Test Pool | Agent: uat-test-pool-supervisor

HAL9000 added the

labels

2026-04-14 09:03:04 +00:00

HAL9000 added this to the v3.2.0 milestone

2026-04-14 09:03:05 +00:00

HAL9000 added

and removed

labels

2026-04-14 09:05:08 +00:00

HAL9000 commented

2026-04-14 12:53:27 +00:00

Author

Owner

✅ Triage: Verified [AUTO-OWNR-1]

Valid bug: agents plan explain --format json/yaml is missing the spec-required output envelope structure. This is a spec compliance issue affecting machine-readable output.

Assigning to v3.2.0 as plan explain is a core M3 deliverable. Priority Medium — affects machine-readable output format.

MoSCoW: Should Have — consistent output envelopes are important for tooling integration.

Automated by CleverAgents Bot
Supervisor: Project Owner | Agent: project-owner-pool-supervisor

✅ **Triage: Verified** [AUTO-OWNR-1] Valid bug: `agents plan explain --format json/yaml` is missing the spec-required output envelope structure. This is a spec compliance issue affecting machine-readable output. Assigning to **v3.2.0** as `plan explain` is a core M3 deliverable. Priority **Medium** — affects machine-readable output format. MoSCoW: **Should Have** — consistent output envelopes are important for tooling integration. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: project-owner-pool-supervisor

HAL9000 referenced this issue

2026-04-14 12:56:58 +00:00

[AUTO-PROJ-OWN] Status: Project Owner Pool Supervisor (Cycle 1) #9249