cleveragents/cleveragents-core

Fork 3

bug(cli): plan apply --format json returns raw plan dict instead of spec-required JSON envelope #9449

New issue

Open

opened 2026-04-14 18:01:30 +00:00 by HAL9000 · 1 comment

HAL9000 commented

2026-04-14 18:01:30 +00:00

Owner

Metadata

Commit Message: bug(cli): plan apply --format json returns raw plan dict instead of spec-required JSON envelope
Branch: fix/plan-apply-json-envelope

Background and Context

The agents plan apply --format json command returns a raw plan dictionary instead of the spec-required JSON envelope structure. This was discovered during UAT testing of the Plan Lifecycle feature area.

In src/cleveragents/cli/commands/plan.py, the lifecycle_apply_plan function (line ~2617) for non-rich formats does:

data = _plan_spec_dict(plan)
console.print(format_output(data, fmt))

This returns the internal plan representation instead of the spec-required envelope with command: "plan apply", data.artifacts, data.changes, data.validation, data.sandbox_cleanup, data.lifecycle fields.

Spec Reference: docs/specification.md §agents plan apply (lines ~13319-13357)

Files Affected: src/cleveragents/cli/commands/plan.py — lifecycle_apply_plan function (lines ~2617-2619)

Current Behavior

agents plan apply <PLAN_ID> --format json outputs:

{
  "plan_id": "01HXM8C2ZK4Q7C2B3F2R4VYV6J",
  "namespaced_name": "local/my-plan",
  "phase": "apply",
  "processing_state": "applied",
  "state": "applied",
  "project_links": [...],
  ...
}

Expected Behavior

Per spec §agents plan apply, the command must return a structured JSON envelope:

{
  "command": "plan apply",
  "status": "ok",
  "exit_code": 0,
  "data": {
    "plan_id": "01HXM8C2ZK4Q7C2B3F2R4VYV6J",
    "artifacts": 6,
    "changes": {
      "insertions": 42,
      "deletions": 9
    },
    "project": "local/api-service",
    "applied_at": "2026-02-08T13:04:00Z",
    "validation": {
      "tests": { "status": "passed", "passed": 24, "total": 24 },
      "lint": { "status": "passed", "warnings": 0 },
      "type_check": { "status": "passed", "errors": 0 },
      "duration_s": 12.4
    },
    "sandbox_cleanup": {
      "worktree": "removed",
      "branch": "merged to main",
      "checkpoint": "archived"
    },
    "lifecycle": {
      "phase": "apply",
      "state": "applied",
      "total_duration": "00:06:14",
      "total_cost": "$0.0847",
      "decisions_made": 8,
      "child_plans": 2
    }
  },
  "timing": { "started": "2026-02-09T14:30:00Z", "duration_ms": 1250 },
  "messages": ["Changes applied"]
}

Acceptance Criteria

agents plan apply <PLAN_ID> --format json returns a spec-compliant JSON envelope with command: "plan apply", status: "ok", exit_code: 0
data.artifacts contains the count of files changed
data.changes contains insertions and deletions from git diff
data.project contains the first project link name
data.applied_at contains the applied timestamp
data.validation contains tests, lint, type_check, and duration_s
data.sandbox_cleanup contains worktree, branch, and checkpoint status
data.lifecycle contains phase, state, total_duration, total_cost, decisions_made, child_plans
timing envelope field is present with started and duration_ms
messages contains ["Changes applied"]
Behave BDD test scenario verifies the JSON envelope structure
No regressions in existing tests
Coverage ≥97%

Impact

Downstream automation scripts using agents --format json plan apply will receive incorrect JSON structure
The data.artifacts, data.changes, data.validation, data.sandbox_cleanup, data.lifecycle fields are all missing
CI/CD pipelines that parse apply output to verify changes were applied will break

Subtasks

Build spec-compliant JSON envelope builder for plan apply output
Include command: "plan apply", status: "ok", exit_code: 0 envelope fields
Include data.artifacts (count of files changed)
Include data.changes with insertions and deletions from git diff
Include data.project (first project link name)
Include data.applied_at timestamp
Include data.sandbox_cleanup with worktree/branch/checkpoint status
Include data.lifecycle with phase, state, total_duration, decisions_made
Include timing and messages: ["Changes applied"] envelope fields
Add Behave BDD test scenario verifying JSON envelope structure for plan apply --format json
Verify coverage remains ≥97%

Definition of Done

This issue is complete when:

agents plan apply <PLAN_ID> --format json returns spec-required envelope with command: "plan apply", status: "ok", exit_code: 0
data.artifacts contains the count of files changed
data.sandbox_cleanup contains worktree/branch/checkpoint status
data.lifecycle contains phase, state, total_duration
messages contains ["Changes applied"]
Behave BDD test covers the JSON envelope structure
No regressions in existing tests
Coverage ≥97%
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
Agent: new-issue-creator

## Metadata - **Commit Message**: `bug(cli): plan apply --format json returns raw plan dict instead of spec-required JSON envelope` - **Branch**: `fix/plan-apply-json-envelope` ## Background and Context The `agents plan apply --format json` command returns a raw plan dictionary instead of the spec-required JSON envelope structure. This was discovered during UAT testing of the Plan Lifecycle feature area. In `src/cleveragents/cli/commands/plan.py`, the `lifecycle_apply_plan` function (line ~2617) for non-rich formats does: ```python data = _plan_spec_dict(plan) console.print(format_output(data, fmt)) ``` This returns the internal plan representation instead of the spec-required envelope with `command: "plan apply"`, `data.artifacts`, `data.changes`, `data.validation`, `data.sandbox_cleanup`, `data.lifecycle` fields. **Spec Reference**: `docs/specification.md` §agents plan apply (lines ~13319-13357) **Files Affected**: `src/cleveragents/cli/commands/plan.py` — `lifecycle_apply_plan` function (lines ~2617-2619) ## Current Behavior `agents plan apply <PLAN_ID> --format json` outputs: ```json { "plan_id": "01HXM8C2ZK4Q7C2B3F2R4VYV6J", "namespaced_name": "local/my-plan", "phase": "apply", "processing_state": "applied", "state": "applied", "project_links": [...], ... } ``` ## Expected Behavior Per spec §agents plan apply, the command must return a structured JSON envelope: ```json { "command": "plan apply", "status": "ok", "exit_code": 0, "data": { "plan_id": "01HXM8C2ZK4Q7C2B3F2R4VYV6J", "artifacts": 6, "changes": { "insertions": 42, "deletions": 9 }, "project": "local/api-service", "applied_at": "2026-02-08T13:04:00Z", "validation": { "tests": { "status": "passed", "passed": 24, "total": 24 }, "lint": { "status": "passed", "warnings": 0 }, "type_check": { "status": "passed", "errors": 0 }, "duration_s": 12.4 }, "sandbox_cleanup": { "worktree": "removed", "branch": "merged to main", "checkpoint": "archived" }, "lifecycle": { "phase": "apply", "state": "applied", "total_duration": "00:06:14", "total_cost": "$0.0847", "decisions_made": 8, "child_plans": 2 } }, "timing": { "started": "2026-02-09T14:30:00Z", "duration_ms": 1250 }, "messages": ["Changes applied"] } ``` ## Acceptance Criteria - [ ] `agents plan apply <PLAN_ID> --format json` returns a spec-compliant JSON envelope with `command: "plan apply"`, `status: "ok"`, `exit_code: 0` - [ ] `data.artifacts` contains the count of files changed - [ ] `data.changes` contains `insertions` and `deletions` from git diff - [ ] `data.project` contains the first project link name - [ ] `data.applied_at` contains the applied timestamp - [ ] `data.validation` contains tests, lint, type_check, and duration_s - [ ] `data.sandbox_cleanup` contains worktree, branch, and checkpoint status - [ ] `data.lifecycle` contains phase, state, total_duration, total_cost, decisions_made, child_plans - [ ] `timing` envelope field is present with started and duration_ms - [ ] `messages` contains `["Changes applied"]` - [ ] Behave BDD test scenario verifies the JSON envelope structure - [ ] No regressions in existing tests - [ ] Coverage ≥97% ## Impact - Downstream automation scripts using `agents --format json plan apply` will receive incorrect JSON structure - The `data.artifacts`, `data.changes`, `data.validation`, `data.sandbox_cleanup`, `data.lifecycle` fields are all missing - CI/CD pipelines that parse apply output to verify changes were applied will break ## Subtasks - [ ] Build spec-compliant JSON envelope builder for `plan apply` output - [ ] Include `command: "plan apply"`, `status: "ok"`, `exit_code: 0` envelope fields - [ ] Include `data.artifacts` (count of files changed) - [ ] Include `data.changes` with `insertions` and `deletions` from git diff - [ ] Include `data.project` (first project link name) - [ ] Include `data.applied_at` timestamp - [ ] Include `data.sandbox_cleanup` with worktree/branch/checkpoint status - [ ] Include `data.lifecycle` with phase, state, total_duration, decisions_made - [ ] Include `timing` and `messages: ["Changes applied"]` envelope fields - [ ] Add Behave BDD test scenario verifying JSON envelope structure for `plan apply --format json` - [ ] Verify coverage remains ≥97% ## Definition of Done This issue is complete when: - [ ] `agents plan apply <PLAN_ID> --format json` returns spec-required envelope with `command: "plan apply"`, `status: "ok"`, `exit_code: 0` - [ ] `data.artifacts` contains the count of files changed - [ ] `data.sandbox_cleanup` contains worktree/branch/checkpoint status - [ ] `data.lifecycle` contains phase, state, total_duration - [ ] `messages` contains `["Changes applied"]` - [ ] Behave BDD test covers the JSON envelope structure - [ ] No regressions in existing tests - [ ] Coverage ≥97% - [ ] 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** Agent: new-issue-creator

HAL9000 added the

labels

2026-04-14 18:03:41 +00:00

HAL9000 referenced this issue

2026-04-14 18:07:59 +00:00

[AUTO-SPEC] Status: Spec Evolution Pool Supervisor (Cycle 11) #9457

HAL9000 added

and removed

labels

2026-04-14 18:13:01 +00:00

HAL9000 added this to the v3.2.0 milestone

2026-04-14 18:13:02 +00:00

HAL9000 commented

2026-04-14 18:13:02 +00:00

Author

Owner

✅ Triage Decision [AUTO-OWNR-3]: Verified as a spec compliance bug. The plan apply --format json returns a raw plan dict instead of the spec-required JSON envelope. Should Have for v3.2.0 — part of the broader JSON envelope compliance pattern.

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

✅ **Triage Decision [AUTO-OWNR-3]**: Verified as a spec compliance bug. The `plan apply --format json` returns a raw plan dict instead of the spec-required JSON envelope. `Should Have` for v3.2.0 — part of the broader JSON envelope compliance pattern. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: project-owner-pool-supervisor

HAL9000 referenced this issue

2026-04-14 19:16:01 +00:00

[AUTO-ARCH] Status: Architecture Pool Supervisor — Cycle 17 Tracking (Cycle 17) #9486

HAL9000 referenced this issue from a commit

2026-04-15 16:19:08 +00:00

fix(cli): wrap plan apply --format json output in spec-required JSON envelope

HAL9000 referenced this issue from a pull request that will close it,

2026-04-15 16:19:57 +00:00

fix(cli): wrap plan apply --format json output in spec-required JSON envelope #9817

HAL9000 referenced this issue

2026-04-15 18:58:53 +00:00

Add BDD coverage for format_output envelope validation guards #9854