fix(cli): align agents plan rollback JSON output field names with spec #3556

New issue

Open

opened 2026-04-05 19:35:01 +00:00 by freemo · 1 comment

freemo commented

2026-04-05 19:35:01 +00:00

Owner

Summary

The agents plan rollback command's JSON output uses different field names than those defined in the specification. This breaks the API contract for any client consuming the JSON output.

Discrepancy Details

Spec section: docs/specification.md — ##### agents plan rollback (line ~16041)

`rollback_summary` fields

Field	Spec defines	Implementation uses
Plan ID	`"plan"`	`"plan_id"`
Checkpoint ID	`"checkpoint"`	`"from_checkpoint_id"`
Files count	`"files_reverted"`	`"restored_files_count"`

`impact` fields

Field	Spec defines	Implementation uses
Child plans	`"child_plans_invalidated"`	missing (only `"files_affected"`)
Sandbox state	`"sandbox"`	missing
Decisions	`"decisions_after_cp"`	missing
Tool calls	`"tool_calls_after_cp"`	missing

`post_rollback_state` fields

Field	Spec defines	Implementation uses
Phase	`"phase"`	missing
State	`"state"`	missing
Checkpoints remaining	`"checkpoints_remaining"`	missing
Active checkpoint	not in spec	`"active_checkpoint"` (extra)
Plan ID	not in spec	`"plan_id"` (extra)

Spec-defined JSON output (correct)

{
  "command": "plan rollback",
  "status": "ok",
  "exit_code": 0,
  "data": {
    "rollback_summary": {
      "plan": "01HXM8C2ZK4Q7C2B3F2R4VYV6J",
      "checkpoint": "cp_01HXM8C2",
      "label": "before auth refactor",
      "files_reverted": 6
    },
    "changes_reverted": [...],
    "impact": {
      "child_plans_invalidated": 2,
      "sandbox": "restored to cp_01HXM8C2",
      "decisions_after_cp": "2 discarded",
      "tool_calls_after_cp": "5 undone"
    },
    "post_rollback_state": {
      "phase": "execute",
      "state": "queued (awaiting input)",
      "checkpoints_remaining": 2
    }
  }
}

Implementation (incorrect — `src/cleveragents/cli/commands/plan.py` lines 3402-3420)

data = {
    "rollback_summary": {
        "plan_id": plan_id,                          # should be "plan"
        "from_checkpoint_id": result.from_checkpoint_id,  # should be "checkpoint"
        "restored_files_count": result.restored_files_count,  # should be "files_reverted"
    },
    "changes_reverted": result.changed_paths,
    "impact": {
        "files_affected": result.restored_files_count,  # wrong structure
    },
    "post_rollback_state": {
        "active_checkpoint": result.from_checkpoint_id,  # wrong fields
        "plan_id": plan_id,
    },
    ...
}

Fix Required

Update src/cleveragents/cli/commands/plan.py in the rollback_plan function to use the spec-defined field names:

rollback_summary.plan_id → rollback_summary.plan
rollback_summary.from_checkpoint_id → rollback_summary.checkpoint
rollback_summary.restored_files_count → rollback_summary.files_reverted
impact block: add child_plans_invalidated, sandbox, decisions_after_cp, tool_calls_after_cp (using getattr with defaults, as the rich output already does)
post_rollback_state block: use phase, state, checkpoints_remaining (using getattr with defaults, as the rich output already does)

Note: The rich output panels are already correct (added by PR #3279). Only the JSON/non-rich output envelope needs fixing.

Triggered By

Discovered during spec-updater analysis of merged PR #3279 (fix(cli): render spec-required panels in agents plan rollback).

Automated by CleverAgents Bot
Supervisor: Spec Evolution | Agent: ca-spec-updater

## Summary The `agents plan rollback` command's JSON output uses different field names than those defined in the specification. This breaks the API contract for any client consuming the JSON output. ## Discrepancy Details **Spec section:** `docs/specification.md` — `##### agents plan rollback` (line ~16041) ### `rollback_summary` fields | Field | Spec defines | Implementation uses | |-------|-------------|---------------------| | Plan ID | `"plan"` | `"plan_id"` | | Checkpoint ID | `"checkpoint"` | `"from_checkpoint_id"` | | Files count | `"files_reverted"` | `"restored_files_count"` | ### `impact` fields | Field | Spec defines | Implementation uses | |-------|-------------|---------------------| | Child plans | `"child_plans_invalidated"` | missing (only `"files_affected"`) | | Sandbox state | `"sandbox"` | missing | | Decisions | `"decisions_after_cp"` | missing | | Tool calls | `"tool_calls_after_cp"` | missing | ### `post_rollback_state` fields | Field | Spec defines | Implementation uses | |-------|-------------|---------------------| | Phase | `"phase"` | missing | | State | `"state"` | missing | | Checkpoints remaining | `"checkpoints_remaining"` | missing | | Active checkpoint | not in spec | `"active_checkpoint"` (extra) | | Plan ID | not in spec | `"plan_id"` (extra) | ## Spec-defined JSON output (correct) ```json { "command": "plan rollback", "status": "ok", "exit_code": 0, "data": { "rollback_summary": { "plan": "01HXM8C2ZK4Q7C2B3F2R4VYV6J", "checkpoint": "cp_01HXM8C2", "label": "before auth refactor", "files_reverted": 6 }, "changes_reverted": [...], "impact": { "child_plans_invalidated": 2, "sandbox": "restored to cp_01HXM8C2", "decisions_after_cp": "2 discarded", "tool_calls_after_cp": "5 undone" }, "post_rollback_state": { "phase": "execute", "state": "queued (awaiting input)", "checkpoints_remaining": 2 } } } ``` ## Implementation (incorrect — `src/cleveragents/cli/commands/plan.py` lines 3402-3420) ```python data = { "rollback_summary": { "plan_id": plan_id, # should be "plan" "from_checkpoint_id": result.from_checkpoint_id, # should be "checkpoint" "restored_files_count": result.restored_files_count, # should be "files_reverted" }, "changes_reverted": result.changed_paths, "impact": { "files_affected": result.restored_files_count, # wrong structure }, "post_rollback_state": { "active_checkpoint": result.from_checkpoint_id, # wrong fields "plan_id": plan_id, }, ... } ``` ## Fix Required Update `src/cleveragents/cli/commands/plan.py` in the `rollback_plan` function to use the spec-defined field names: 1. `rollback_summary.plan_id` → `rollback_summary.plan` 2. `rollback_summary.from_checkpoint_id` → `rollback_summary.checkpoint` 3. `rollback_summary.restored_files_count` → `rollback_summary.files_reverted` 4. `impact` block: add `child_plans_invalidated`, `sandbox`, `decisions_after_cp`, `tool_calls_after_cp` (using `getattr` with defaults, as the rich output already does) 5. `post_rollback_state` block: use `phase`, `state`, `checkpoints_remaining` (using `getattr` with defaults, as the rich output already does) Note: The **rich output** panels are already correct (added by PR #3279). Only the JSON/non-rich output envelope needs fixing. ## Triggered By Discovered during spec-updater analysis of merged PR #3279 (`fix(cli): render spec-required panels in agents plan rollback`). --- **Automated by CleverAgents Bot** Supervisor: Spec Evolution | Agent: ca-spec-updater

freemo added this to the v3.2.0 milestone

2026-04-05 19:35:14 +00:00

freemo referenced this issue

2026-04-05 19:35:55 +00:00

[Automated] CleverAgents Build Session - 2026-04-05 #3377

freemo commented

2026-04-06 18:51:36 +00:00

Author

Owner

Milestone Triage Decision: Moved to Backlog

This issue has been moved out of v3.3.0 during aggressive milestone triage. While important for completeness, it does not directly relate to the core focus of Corrections + Subplans + Checkpoints.

Reasoning:

v3.3.0 focus: Essential corrections, subplan management, and checkpoint functionality
This issue: Infrastructure improvement not directly blocking core milestone functionality
Impact: System enhancement, not core corrections/subplans/checkpoints functionality

Will be addressed in a future milestone after core corrections, subplans, and checkpoints are stable.

**Milestone Triage Decision: Moved to Backlog** This issue has been moved out of v3.3.0 during aggressive milestone triage. While important for completeness, it does not directly relate to the core focus of Corrections + Subplans + Checkpoints. **Reasoning:** - v3.3.0 focus: Essential corrections, subplan management, and checkpoint functionality - This issue: Infrastructure improvement not directly blocking core milestone functionality - Impact: System enhancement, not core corrections/subplans/checkpoints functionality Will be addressed in a future milestone after core corrections, subplans, and checkpoints are stable.

freemo removed this from the v3.2.0 milestone

2026-04-06 20:50:18 +00:00