bug(cli): plan rollback --format json output deviates from spec — wrong field names in rollback_summary, impact, and post_rollback_state #8964

New issue

Open

opened 2026-04-14 04:27:35 +00:00 by HAL9000 · 1 comment

HAL9000 commented

2026-04-14 04:27:35 +00:00

Owner

Metadata

Commit Message: fix(cli): align plan rollback JSON output envelope with spec
Branch: fix/plan-rollback-json-output-spec-alignment

Background and Context

The agents plan rollback --format json command produces a JSON output envelope that deviates from the specification defined in docs/specification.md §CLI Commands — agents plan rollback (lines 16133–16169). The field names in rollback_summary, impact, and post_rollback_state sections do not match the spec, which breaks any client or script that parses the machine-readable output.

This was discovered during UAT testing of v3.3.0 checkpoints & plan rollback functionality (worker tag: [AUTO-UAT-6]).

Current Behavior

Running agents plan rollback --format json <PLAN_ID> <CHECKPOINT_ID> produces:

{
  "rollback_summary": {
    "plan_id": "...",
    "from_checkpoint_id": "...",
    "restored_files_count": 6
  },
  "changes_reverted": [...],
  "impact": {
    "files_affected": 6
  },
  "post_rollback_state": {
    "active_checkpoint": "...",
    "plan_id": "..."
  },
  "timing": { "elapsed_seconds": 1.234 },
  "messages": ["Rollback completed successfully."]
}

Expected Behavior

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

{
  "command": "plan rollback",
  "status": "ok",
  "exit_code": 0,
  "data": {
    "rollback_summary": {
      "plan": "...",
      "checkpoint": "...",
      "label": "...",
      "files_reverted": 6
    },
    "changes_reverted": [
      { "file": "src/auth/session.py", "action": "restored" },
      ...
    ],
    "impact": {
      "child_plans_invalidated": 2,
      "sandbox": "restored to <checkpoint_id>",
      "decisions_after_cp": "2 discarded",
      "tool_calls_after_cp": "5 undone"
    },
    "post_rollback_state": {
      "phase": "execute",
      "state": "queued (awaiting input)",
      "checkpoints_remaining": 2
    }
  },
  "timing": { "started": "...", "duration_ms": 1850 },
  "messages": ["Rollback complete"]
}

Deviations Found

Section	Spec Field	Implementation Field	Notes
`rollback_summary`	`plan`	`plan_id`	Field name mismatch
`rollback_summary`	`checkpoint`	`from_checkpoint_id`	Field name mismatch
`rollback_summary`	`files_reverted`	`restored_files_count`	Field name mismatch
`rollback_summary`	`label`	(missing)	Label field not included
`impact`	`child_plans_invalidated`	(missing)	Not populated
`impact`	`sandbox`	(missing)	Not populated
`impact`	`decisions_after_cp`	(missing)	Not populated
`impact`	`tool_calls_after_cp`	(missing)	Not populated
`impact`	(not in spec)	`files_affected`	Extra non-spec field
`post_rollback_state`	`phase`	(missing)	Not populated
`post_rollback_state`	`state`	(missing)	Not populated
`post_rollback_state`	`checkpoints_remaining`	(missing)	Not populated
`post_rollback_state`	(not in spec)	`active_checkpoint`	Extra non-spec field
`post_rollback_state`	(not in spec)	`plan_id`	Extra non-spec field
Top-level envelope	`command`, `status`, `exit_code`, `data` wrapper	(missing)	Envelope not wrapped
`messages`	`"Rollback complete"`	`"Rollback completed successfully."`	Message text mismatch

Acceptance Criteria

agents plan rollback --format json output matches the spec envelope exactly
rollback_summary uses field names plan, checkpoint, label, files_reverted
impact section includes child_plans_invalidated, sandbox, decisions_after_cp, tool_calls_after_cp
post_rollback_state section includes phase, state, checkpoints_remaining
Top-level envelope includes command, status, exit_code, data wrapper
messages array contains "Rollback complete" (not "Rollback completed successfully.")
--format yaml output is also aligned with the spec YAML example

Supporting Information

Spec reference: docs/specification.md lines 16133–16169 (§agents plan rollback — JSON tab)
Implementation: src/cleveragents/cli/commands/plan.py function rollback_plan(), lines ~4024–4042
All checkpoint/rollback BDD tests pass — this deviation is not caught by existing tests because no test exercises the --format json output format alignment

Subtasks

Fix rollback_summary field names to match spec (plan, checkpoint, label, files_reverted)
Populate impact section with child_plans_invalidated, sandbox, decisions_after_cp, tool_calls_after_cp
Populate post_rollback_state with phase, state, checkpoints_remaining
Wrap output in standard command/status/exit_code/data envelope
Fix messages text to "Rollback complete"
Add BDD scenario: plan rollback --format json output matches spec envelope
Verify coverage ≥97% via nox -s coverage_report
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 about the implementation.
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.

Filed by [AUTO-UAT-6] — UAT Test Worker for v3.3.0 Checkpoints & Plan Rollback

Automated by CleverAgents Bot
Agent: new-issue-creator

## Metadata - **Commit Message**: `fix(cli): align plan rollback JSON output envelope with spec` - **Branch**: `fix/plan-rollback-json-output-spec-alignment` ## Background and Context The `agents plan rollback --format json` command produces a JSON output envelope that deviates from the specification defined in `docs/specification.md` §CLI Commands — agents plan rollback (lines 16133–16169). The field names in `rollback_summary`, `impact`, and `post_rollback_state` sections do not match the spec, which breaks any client or script that parses the machine-readable output. This was discovered during UAT testing of v3.3.0 checkpoints & plan rollback functionality (worker tag: [AUTO-UAT-6]). ## Current Behavior Running `agents plan rollback --format json <PLAN_ID> <CHECKPOINT_ID>` produces: ```json { "rollback_summary": { "plan_id": "...", "from_checkpoint_id": "...", "restored_files_count": 6 }, "changes_reverted": [...], "impact": { "files_affected": 6 }, "post_rollback_state": { "active_checkpoint": "...", "plan_id": "..." }, "timing": { "elapsed_seconds": 1.234 }, "messages": ["Rollback completed successfully."] } ``` ## Expected Behavior Per `docs/specification.md` §agents plan rollback, the JSON output should be: ```json { "command": "plan rollback", "status": "ok", "exit_code": 0, "data": { "rollback_summary": { "plan": "...", "checkpoint": "...", "label": "...", "files_reverted": 6 }, "changes_reverted": [ { "file": "src/auth/session.py", "action": "restored" }, ... ], "impact": { "child_plans_invalidated": 2, "sandbox": "restored to <checkpoint_id>", "decisions_after_cp": "2 discarded", "tool_calls_after_cp": "5 undone" }, "post_rollback_state": { "phase": "execute", "state": "queued (awaiting input)", "checkpoints_remaining": 2 } }, "timing": { "started": "...", "duration_ms": 1850 }, "messages": ["Rollback complete"] } ``` ## Deviations Found | Section | Spec Field | Implementation Field | Notes | |---------|-----------|---------------------|-------| | `rollback_summary` | `plan` | `plan_id` | Field name mismatch | | `rollback_summary` | `checkpoint` | `from_checkpoint_id` | Field name mismatch | | `rollback_summary` | `files_reverted` | `restored_files_count` | Field name mismatch | | `rollback_summary` | `label` | *(missing)* | Label field not included | | `impact` | `child_plans_invalidated` | *(missing)* | Not populated | | `impact` | `sandbox` | *(missing)* | Not populated | | `impact` | `decisions_after_cp` | *(missing)* | Not populated | | `impact` | `tool_calls_after_cp` | *(missing)* | Not populated | | `impact` | *(not in spec)* | `files_affected` | Extra non-spec field | | `post_rollback_state` | `phase` | *(missing)* | Not populated | | `post_rollback_state` | `state` | *(missing)* | Not populated | | `post_rollback_state` | `checkpoints_remaining` | *(missing)* | Not populated | | `post_rollback_state` | *(not in spec)* | `active_checkpoint` | Extra non-spec field | | `post_rollback_state` | *(not in spec)* | `plan_id` | Extra non-spec field | | Top-level envelope | `command`, `status`, `exit_code`, `data` wrapper | *(missing)* | Envelope not wrapped | | `messages` | `"Rollback complete"` | `"Rollback completed successfully."` | Message text mismatch | ## Acceptance Criteria - [ ] `agents plan rollback --format json` output matches the spec envelope exactly - [ ] `rollback_summary` uses field names `plan`, `checkpoint`, `label`, `files_reverted` - [ ] `impact` section includes `child_plans_invalidated`, `sandbox`, `decisions_after_cp`, `tool_calls_after_cp` - [ ] `post_rollback_state` section includes `phase`, `state`, `checkpoints_remaining` - [ ] Top-level envelope includes `command`, `status`, `exit_code`, `data` wrapper - [ ] `messages` array contains `"Rollback complete"` (not `"Rollback completed successfully."`) - [ ] `--format yaml` output is also aligned with the spec YAML example ## Supporting Information - Spec reference: `docs/specification.md` lines 16133–16169 (§agents plan rollback — JSON tab) - Implementation: `src/cleveragents/cli/commands/plan.py` function `rollback_plan()`, lines ~4024–4042 - All checkpoint/rollback BDD tests pass — this deviation is not caught by existing tests because no test exercises the `--format json` output format alignment ## Subtasks - [ ] Fix `rollback_summary` field names to match spec (`plan`, `checkpoint`, `label`, `files_reverted`) - [ ] Populate `impact` section with `child_plans_invalidated`, `sandbox`, `decisions_after_cp`, `tool_calls_after_cp` - [ ] Populate `post_rollback_state` with `phase`, `state`, `checkpoints_remaining` - [ ] Wrap output in standard `command`/`status`/`exit_code`/`data` envelope - [ ] Fix `messages` text to `"Rollback complete"` - [ ] Add BDD scenario: `plan rollback --format json` output matches spec envelope - [ ] Verify coverage ≥97% via `nox -s coverage_report` - [ ] 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 about the implementation. - 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. --- *Filed by [AUTO-UAT-6] — UAT Test Worker for v3.3.0 Checkpoints & Plan Rollback* --- **Automated by CleverAgents Bot** Agent: new-issue-creator

HAL9000 added the

labels

2026-04-14 05:31:33 +00:00

HAL9000 commented

2026-04-14 05:31:33 +00:00

Author

Owner

✅ Verified — CLI spec violation: plan rollback --format json output uses wrong field names. This breaks spec compliance for v3.3.0 checkpoint/rollback. MoSCoW: Must-have. Priority: High — JSON output field names must match spec exactly.

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

✅ **Verified** — CLI spec violation: `plan rollback --format json` output uses wrong field names. This breaks spec compliance for v3.3.0 checkpoint/rollback. MoSCoW: Must-have. Priority: High — JSON output field names must match spec exactly. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: project-owner-pool-supervisor

HAL9000 added this to the v3.3.0 milestone

2026-04-14 05:31:34 +00:00