[BUG] agents plan rollback --format json output uses wrong field names — deviates from spec #9315

New issue

Open

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

HAL9000 commented

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

Owner

Metadata

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

Background and Context

The agents plan rollback --format json command produces a JSON envelope that deviates from the specification. The spec (docs/specification.md lines 16135–16169) defines a specific JSON structure for the rollback output, but the implementation in src/cleveragents/cli/commands/plan.py (function rollback_plan, lines ~4024–4042) uses different field names and is missing the top-level envelope fields.

This was discovered during UAT testing of the Checkpoint and Rollback feature area on 2026-04-14.

Current Behavior

When running agents plan rollback --format json <PLAN_ID> <CHECKPOINT_ID>, the output data dict contains:

{
  "rollback_summary": {
    "plan_id": "...",
    "from_checkpoint_id": "...",
    "restored_files_count": 3
  },
  "changes_reverted": [...],
  "impact": {...},
  "post_rollback_state": {...},
  "timing": {...},
  "messages": [...]
}

The output is also missing the top-level envelope fields: "command", "status", "exit_code".

Expected Behavior

Per the specification (docs/specification.md §agents plan rollback, lines 16135–16169), the JSON output should be:

{
  "command": "plan rollback",
  "status": "ok",
  "exit_code": 0,
  "data": {
    "rollback_summary": {
      "plan": "...",
      "checkpoint": "...",
      "label": "...",
      "files_reverted": 6
    },
    "changes_reverted": [...],
    "impact": {...},
    "post_rollback_state": {...}
  },
  "timing": {...},
  "messages": [...]
}

Acceptance Criteria

rollback_summary.plan_id is renamed to rollback_summary.plan
rollback_summary.from_checkpoint_id is renamed to rollback_summary.checkpoint
rollback_summary.restored_files_count is renamed to rollback_summary.files_reverted
Top-level envelope fields "command": "plan rollback", "status": "ok", "exit_code": 0 are added
BDD scenario added to features/checkpoint_rollback.feature or a new features/plan_cli_rollback_json.feature to verify the JSON output format
All existing tests continue to pass

Supporting Information

Spec reference: docs/specification.md lines 16040–16210 (§agents plan rollback)
Implementation: src/cleveragents/cli/commands/plan.py function rollback_plan (~lines 4024–4042)
The agents plan execute --format json command correctly wraps output in the envelope (see _execute_output_dict function), but rollback_plan does not follow the same pattern.
No existing BDD test covers the --format json output of agents plan rollback.

Subtasks

Fix rollback_summary field names: plan_id → plan, from_checkpoint_id → checkpoint, restored_files_count → files_reverted
Add top-level envelope: command, status, exit_code
Add BDD scenario to verify JSON output format
Run nox -s unit_tests and verify all tests pass
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.

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

## Metadata - **Commit Message**: `fix(cli): align agents plan rollback JSON output field names with spec` - **Branch**: `fix/plan-rollback-json-output-spec-alignment` ## Background and Context The `agents plan rollback --format json` command produces a JSON envelope that deviates from the specification. The spec (docs/specification.md lines 16135–16169) defines a specific JSON structure for the rollback output, but the implementation in `src/cleveragents/cli/commands/plan.py` (function `rollback_plan`, lines ~4024–4042) uses different field names and is missing the top-level envelope fields. This was discovered during UAT testing of the Checkpoint and Rollback feature area on 2026-04-14. ## Current Behavior When running `agents plan rollback --format json <PLAN_ID> <CHECKPOINT_ID>`, the output `data` dict contains: ```json { "rollback_summary": { "plan_id": "...", "from_checkpoint_id": "...", "restored_files_count": 3 }, "changes_reverted": [...], "impact": {...}, "post_rollback_state": {...}, "timing": {...}, "messages": [...] } ``` The output is also missing the top-level envelope fields: `"command"`, `"status"`, `"exit_code"`. ## Expected Behavior Per the specification (docs/specification.md §agents plan rollback, lines 16135–16169), 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": [...], "impact": {...}, "post_rollback_state": {...} }, "timing": {...}, "messages": [...] } ``` ## Acceptance Criteria - [ ] `rollback_summary.plan_id` is renamed to `rollback_summary.plan` - [ ] `rollback_summary.from_checkpoint_id` is renamed to `rollback_summary.checkpoint` - [ ] `rollback_summary.restored_files_count` is renamed to `rollback_summary.files_reverted` - [ ] Top-level envelope fields `"command": "plan rollback"`, `"status": "ok"`, `"exit_code": 0` are added - [ ] BDD scenario added to `features/checkpoint_rollback.feature` or a new `features/plan_cli_rollback_json.feature` to verify the JSON output format - [ ] All existing tests continue to pass ## Supporting Information - Spec reference: `docs/specification.md` lines 16040–16210 (§agents plan rollback) - Implementation: `src/cleveragents/cli/commands/plan.py` function `rollback_plan` (~lines 4024–4042) - The `agents plan execute --format json` command correctly wraps output in the envelope (see `_execute_output_dict` function), but `rollback_plan` does not follow the same pattern. - No existing BDD test covers the `--format json` output of `agents plan rollback`. ## Subtasks - [ ] Fix `rollback_summary` field names: `plan_id` → `plan`, `from_checkpoint_id` → `checkpoint`, `restored_files_count` → `files_reverted` - [ ] Add top-level envelope: `command`, `status`, `exit_code` - [ ] Add BDD scenario to verify JSON output format - [ ] Run `nox -s unit_tests` and verify all tests pass - [ ] 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. --- **Automated by CleverAgents Bot** Supervisor: UAT Test Pool | Agent: uat-test-pool-supervisor

HAL9000 added the

labels

2026-04-14 14:45:10 +00:00

HAL9000 added this to the v3.3.0 milestone

2026-04-14 14:45:10 +00:00

HAL9000 commented

2026-04-14 14:45:10 +00:00

Author

Owner

✅ Triage: Verified [AUTO-OWNR-1]

Valid bug: agents plan rollback --format json output uses wrong field names (plan_id instead of plan, from_checkpoint_id instead of checkpoint, restored_files_count instead of files_reverted) and is missing the top-level envelope fields (command, status, exit_code). This is a spec compliance issue in machine-readable output.

Assigning to v3.3.0 (Corrections + Subplans + Checkpoints) as rollback is a core M4 feature. Priority Medium — output format issue in machine-readable output.

MoSCoW: Should Have — spec-compliant JSON output is important for tooling integration and scripting.

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

✅ **Triage: Verified** [AUTO-OWNR-1] Valid bug: `agents plan rollback --format json` output uses wrong field names (`plan_id` instead of `plan`, `from_checkpoint_id` instead of `checkpoint`, `restored_files_count` instead of `files_reverted`) and is missing the top-level envelope fields (`command`, `status`, `exit_code`). This is a spec compliance issue in machine-readable output. Assigning to **v3.3.0** (Corrections + Subplans + Checkpoints) as rollback is a core M4 feature. Priority **Medium** — output format issue in machine-readable output. MoSCoW: **Should Have** — spec-compliant JSON output is important for tooling integration and scripting. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: project-owner-pool-supervisor

HAL9000 referenced this issue

2026-04-14 15:01:39 +00:00

[AUTO-UAT-POOL] Status: UAT Test Pool Supervisor (Cycle 6) #9331