[BUG] agents plan diff --format json output does not wrap in spec-required envelope (missing command/status/exit_code/data/timing/messages) #9339

New issue

Open

opened 2026-04-14 15:11:35 +00:00 by HAL9000 · 0 comments

HAL9000 commented

2026-04-14 15:11:35 +00:00

Owner

Metadata

Commit Message: fix(cli): wrap plan diff JSON output in spec-required envelope with diff_summary, files, patch_preview, risk_assessment
Branch: fix/plan-diff-json-envelope-spec-alignment

Background and Context

The agents plan diff --format json command outputs raw changeset data that deviates from the specification. The spec (§CLI Commands — agents plan diff, docs/specification.md line 15423–15474) defines a precise JSON envelope structure.

This was discovered during UAT testing of the Plan Diff and Artifacts CLI feature area.

Current Behavior

The current PlanApplyService.diff() method in src/cleveragents/application/services/plan_apply_service.py calls _render_diff_json() which returns raw changeset data:

{
  "changeset_id": "...",
  "plan_id": "...",
  "total_changes": 3,
  "summary": { "total": 3, "creates": 1, "modifies": 1, "deletes": 1 },
  "entries": [...]
}

The CLI command plan_diff() in src/cleveragents/cli/commands/plan.py (line 3265) calls service.diff(plan_id, fmt=fmt) and prints the result directly — no envelope wrapping is applied.

Expected Behavior

Per docs/specification.md §agents plan diff (lines 15423–15474), the JSON output must be:

{
  "command": "plan diff",
  "status": "ok",
  "exit_code": 0,
  "data": {
    "diff_summary": {
      "plan": "<PLAN_ID>",
      "project": "<project>",
      "files_changed": 2,
      "insertions": 12,
      "deletions": 4,
      "net_change": "+8 lines"
    },
    "files": [
      { "path": "src/auth/session.py", "change": "+8 -2", "status": "modified" }
    ],
    "patch_preview": [...],
    "risk_assessment": {
      "api_compatibility": "preserved",
      "test_coverage": "maintained",
      "breaking_changes": "none detected"
    }
  },
  "timing": { "started": "...", "duration_ms": 750 },
  "messages": ["Diff generated"]
}

Acceptance Criteria

agents plan diff <PLAN_ID> --format json outputs a JSON object with top-level keys: command, status, exit_code, data, timing, messages
data contains diff_summary (with plan, files_changed, insertions, deletions, net_change), files list, patch_preview list, and risk_assessment object
timing contains started (ISO timestamp) and duration_ms
messages contains ["Diff generated"]
command is "plan diff", status is "ok", exit_code is 0
The plan_diff_artifacts.feature scenario "Plan diff shows file changes in JSON format" passes without @tdd_expected_fail

Supporting Information

Spec reference: docs/specification.md lines 15423–15474
Implementation: src/cleveragents/application/services/plan_apply_service.py — _render_diff_json() and diff()
CLI command: src/cleveragents/cli/commands/plan.py — plan_diff() (line 3265)
Feature file: features/plan_diff_artifacts.feature — "Plan diff shows file changes in JSON format"
The plan_diff_artifacts.feature step step_diff_valid_json checks for entries key, but the spec requires data.files and data.diff_summary structure

Subtasks

Update _render_diff_json() in plan_apply_service.py to return spec-compliant structure with diff_summary, files, patch_preview, risk_assessment
Update plan_diff() CLI command to wrap output in the spec envelope (command, status, exit_code, data, timing, messages)
Add timing.started ISO timestamp to the envelope
Update plan_diff_artifacts.feature step assertions to match spec envelope structure
Tests (Behave): Update/add scenarios for JSON format spec compliance
Run nox -s unit_tests -- features/plan_diff_artifacts.feature, fix any errors
Verify coverage ≥97% via nox -s coverage_report

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 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): wrap plan diff JSON output in spec-required envelope with diff_summary, files, patch_preview, risk_assessment` - **Branch**: `fix/plan-diff-json-envelope-spec-alignment` ## Background and Context The `agents plan diff --format json` command outputs raw changeset data that deviates from the specification. The spec (§CLI Commands — agents plan diff, `docs/specification.md` line 15423–15474) defines a precise JSON envelope structure. This was discovered during UAT testing of the Plan Diff and Artifacts CLI feature area. ## Current Behavior The current `PlanApplyService.diff()` method in `src/cleveragents/application/services/plan_apply_service.py` calls `_render_diff_json()` which returns raw changeset data: ```json { "changeset_id": "...", "plan_id": "...", "total_changes": 3, "summary": { "total": 3, "creates": 1, "modifies": 1, "deletes": 1 }, "entries": [...] } ``` The CLI command `plan_diff()` in `src/cleveragents/cli/commands/plan.py` (line 3265) calls `service.diff(plan_id, fmt=fmt)` and prints the result directly — no envelope wrapping is applied. ## Expected Behavior Per `docs/specification.md` §agents plan diff (lines 15423–15474), the JSON output must be: ```json { "command": "plan diff", "status": "ok", "exit_code": 0, "data": { "diff_summary": { "plan": "<PLAN_ID>", "project": "<project>", "files_changed": 2, "insertions": 12, "deletions": 4, "net_change": "+8 lines" }, "files": [ { "path": "src/auth/session.py", "change": "+8 -2", "status": "modified" } ], "patch_preview": [...], "risk_assessment": { "api_compatibility": "preserved", "test_coverage": "maintained", "breaking_changes": "none detected" } }, "timing": { "started": "...", "duration_ms": 750 }, "messages": ["Diff generated"] } ``` ## Acceptance Criteria - `agents plan diff <PLAN_ID> --format json` outputs a JSON object with top-level keys: `command`, `status`, `exit_code`, `data`, `timing`, `messages` - `data` contains `diff_summary` (with `plan`, `files_changed`, `insertions`, `deletions`, `net_change`), `files` list, `patch_preview` list, and `risk_assessment` object - `timing` contains `started` (ISO timestamp) and `duration_ms` - `messages` contains `["Diff generated"]` - `command` is `"plan diff"`, `status` is `"ok"`, `exit_code` is `0` - The `plan_diff_artifacts.feature` scenario "Plan diff shows file changes in JSON format" passes without `@tdd_expected_fail` ## Supporting Information - Spec reference: `docs/specification.md` lines 15423–15474 - Implementation: `src/cleveragents/application/services/plan_apply_service.py` — `_render_diff_json()` and `diff()` - CLI command: `src/cleveragents/cli/commands/plan.py` — `plan_diff()` (line 3265) - Feature file: `features/plan_diff_artifacts.feature` — "Plan diff shows file changes in JSON format" - The `plan_diff_artifacts.feature` step `step_diff_valid_json` checks for `entries` key, but the spec requires `data.files` and `data.diff_summary` structure ## Subtasks - [ ] Update `_render_diff_json()` in `plan_apply_service.py` to return spec-compliant structure with `diff_summary`, `files`, `patch_preview`, `risk_assessment` - [ ] Update `plan_diff()` CLI command to wrap output in the spec envelope (`command`, `status`, `exit_code`, `data`, `timing`, `messages`) - [ ] Add `timing.started` ISO timestamp to the envelope - [ ] Update `plan_diff_artifacts.feature` step assertions to match spec envelope structure - [ ] Tests (Behave): Update/add scenarios for JSON format spec compliance - [ ] Run `nox -s unit_tests -- features/plan_diff_artifacts.feature`, fix any errors - [ ] Verify coverage ≥97% via `nox -s coverage_report` ## 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 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 15:13:48 +00:00

HAL9000 referenced this issue

2026-04-14 15:41:04 +00:00

[AUTO-UAT-POOL] Status: UAT Test Pool Supervisor (Cycle 1) #9364