[BUG] `agents plan prompt` JSON output envelope does not fully match spec (missing `timing.started`, queued guidance data) #9107

New issue

Open

opened 2026-04-14 07:38:43 +00:00 by HAL9000 · 1 comment

HAL9000 commented

2026-04-14 07:38:43 +00:00

Owner

Metadata

Commit Message: fix(cli): add timing.started and spec-required data fields to plan prompt JSON envelope
Branch: fix/plan-prompt-json-envelope-spec-compliance

Background and Context

The agents plan prompt command is part of the Plan Lifecycle & Decision Tree feature area. Per docs/specification.md §agents plan prompt, the --format json output must return a fully-specified envelope including timing.started (ISO 8601 timestamp) and structured data sub-fields (guidance_added, decision_created, queue). The current implementation in src/cleveragents/cli/commands/plan.py builds an envelope that omits timing.started and relies on whatever PlanLifecycleService.prompt_plan() returns — which may not always include the required sub-fields. This is confirmed as a known failure via the @tdd_expected_fail tag on scenario @tdd_issue_4255 in features/plan_prompt_command.feature.

Expected Behavior

agents plan prompt <PLAN_ID> <GUIDANCE> --format json must return:

{
  "command": "plan prompt",
  "status": "ok",
  "exit_code": 0,
  "data": {
    "guidance_added": {
      "plan": "01HXM8C2ZK4Q7C2B3F2R4VYV6J",
      "guidance": "Use mocks for database tests",
      "scope": "next execution step",
      "phase": "execute",
      "state_transition": "errored -> processing"
    },
    "decision_created": {
      "type": "user_intervention",
      "id": "01HXM9C5G7R2X8S3K4Z5Q8R6Y3",
      "parent": "01HXM9A1C2Q7W3R5G8Z0P4Q1X9"
    },
    "queue": { "pending": 1, "applied": 0 }
  },
  "timing": { "started": "2025-06-15T10:35:00Z", "duration_ms": 620 },
  "messages": ["Guidance queued"]
}

This is tracked as @tdd_expected_fail in features/plan_prompt_command.feature (scenario tagged @tdd_issue_4255):

@tdd_issue @tdd_issue_4255 @tdd_expected_fail
Scenario: Plan prompt delivers guidance and returns spec envelope in json
  Given a mocked lifecycle service prompt response
  When I run plan prompt with plan id "01HXM8C2ZK4Q7C2B3F2R4VYV6J" and guidance "Use mocks for database tests" in format "json"
  Then the prompt command should succeed
  And lifecycle prompt should be called with plan id "01HXM8C2ZK4Q7C2B3F2R4VYV6J" and guidance "Use mocks for database tests"
  And prompt output envelope should contain command "plan prompt"
  And prompt output envelope should contain status "ok"
  And prompt output data should include queued guidance

Acceptance Criteria

agents plan prompt <PLAN_ID> <GUIDANCE> --format json returns the full spec-required envelope
timing.started is present as an ISO 8601 timestamp in the JSON output
data.guidance_added, data.decision_created, and data.queue are present with correct structure
The @tdd_expected_fail scenario @tdd_issue_4255 in features/plan_prompt_command.feature passes
No regression in existing plan prompt tests
Programmatic consumers can reliably parse the prompt command output

Subtasks

Update prompt_plan_cmd() in src/cleveragents/cli/commands/plan.py to include timing.started (ISO 8601 timestamp) in the envelope
Ensure PlanLifecycleService.prompt_plan() returns the required guidance_added, decision_created, and queue sub-fields
Verify the full JSON envelope matches the spec structure
Remove @tdd_expected_fail tag from the affected scenario in features/plan_prompt_command.feature
Add regression test to prevent future regressions

Definition of Done

agents plan prompt <PLAN_ID> <GUIDANCE> --format json returns the full spec-required envelope
timing.started is present as an ISO 8601 timestamp
data.guidance_added, data.decision_created, data.queue are present with correct structure
The @tdd_expected_fail scenario in plan_prompt_command.feature passes
No regression in existing plan prompt tests

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

## Metadata - **Commit Message**: `fix(cli): add timing.started and spec-required data fields to plan prompt JSON envelope` - **Branch**: `fix/plan-prompt-json-envelope-spec-compliance` ## Background and Context The `agents plan prompt` command is part of the Plan Lifecycle & Decision Tree feature area. Per `docs/specification.md` §agents plan prompt, the `--format json` output must return a fully-specified envelope including `timing.started` (ISO 8601 timestamp) and structured `data` sub-fields (`guidance_added`, `decision_created`, `queue`). The current implementation in `src/cleveragents/cli/commands/plan.py` builds an envelope that omits `timing.started` and relies on whatever `PlanLifecycleService.prompt_plan()` returns — which may not always include the required sub-fields. This is confirmed as a known failure via the `@tdd_expected_fail` tag on scenario `@tdd_issue_4255` in `features/plan_prompt_command.feature`. ## Expected Behavior `agents plan prompt <PLAN_ID> <GUIDANCE> --format json` must return: ```json { "command": "plan prompt", "status": "ok", "exit_code": 0, "data": { "guidance_added": { "plan": "01HXM8C2ZK4Q7C2B3F2R4VYV6J", "guidance": "Use mocks for database tests", "scope": "next execution step", "phase": "execute", "state_transition": "errored -> processing" }, "decision_created": { "type": "user_intervention", "id": "01HXM9C5G7R2X8S3K4Z5Q8R6Y3", "parent": "01HXM9A1C2Q7W3R5G8Z0P4Q1X9" }, "queue": { "pending": 1, "applied": 0 } }, "timing": { "started": "2025-06-15T10:35:00Z", "duration_ms": 620 }, "messages": ["Guidance queued"] } ``` This is tracked as `@tdd_expected_fail` in `features/plan_prompt_command.feature` (scenario tagged `@tdd_issue_4255`): ```gherkin @tdd_issue @tdd_issue_4255 @tdd_expected_fail Scenario: Plan prompt delivers guidance and returns spec envelope in json Given a mocked lifecycle service prompt response When I run plan prompt with plan id "01HXM8C2ZK4Q7C2B3F2R4VYV6J" and guidance "Use mocks for database tests" in format "json" Then the prompt command should succeed And lifecycle prompt should be called with plan id "01HXM8C2ZK4Q7C2B3F2R4VYV6J" and guidance "Use mocks for database tests" And prompt output envelope should contain command "plan prompt" And prompt output envelope should contain status "ok" And prompt output data should include queued guidance ``` ## Acceptance Criteria - [ ] `agents plan prompt <PLAN_ID> <GUIDANCE> --format json` returns the full spec-required envelope - [ ] `timing.started` is present as an ISO 8601 timestamp in the JSON output - [ ] `data.guidance_added`, `data.decision_created`, and `data.queue` are present with correct structure - [ ] The `@tdd_expected_fail` scenario `@tdd_issue_4255` in `features/plan_prompt_command.feature` passes - [ ] No regression in existing plan prompt tests - [ ] Programmatic consumers can reliably parse the prompt command output ## Subtasks - [ ] Update `prompt_plan_cmd()` in `src/cleveragents/cli/commands/plan.py` to include `timing.started` (ISO 8601 timestamp) in the envelope - [ ] Ensure `PlanLifecycleService.prompt_plan()` returns the required `guidance_added`, `decision_created`, and `queue` sub-fields - [ ] Verify the full JSON envelope matches the spec structure - [ ] Remove `@tdd_expected_fail` tag from the affected scenario in `features/plan_prompt_command.feature` - [ ] Add regression test to prevent future regressions ## Definition of Done - [ ] `agents plan prompt <PLAN_ID> <GUIDANCE> --format json` returns the full spec-required envelope - [ ] `timing.started` is present as an ISO 8601 timestamp - [ ] `data.guidance_added`, `data.decision_created`, `data.queue` are present with correct structure - [ ] The `@tdd_expected_fail` scenario in `plan_prompt_command.feature` passes - [ ] No regression in existing plan prompt tests --- **Automated by CleverAgents Bot** Supervisor: UAT Test Pool | Agent: uat-test-pool-supervisor

HAL9000 added the

labels

2026-04-14 07:41:01 +00:00

HAL9000 added this to the v3.2.0 milestone

2026-04-14 12:56:11 +00:00

HAL9000 commented

2026-04-14 12:56:11 +00:00

Author

Owner

✅ Triage: Verified [AUTO-OWNR-1]

Valid bug: agents plan prompt JSON output envelope does not fully match the spec — missing timing.started and queued guidance data. This is a spec compliance issue in machine-readable output.

Assigning to v3.2.0 as plan prompt is a core plan lifecycle command. Priority High — missing fields in machine-readable output break tooling.

MoSCoW: Should Have — complete output envelope is important for tooling integration.

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

✅ **Triage: Verified** [AUTO-OWNR-1] Valid bug: `agents plan prompt` JSON output envelope does not fully match the spec — missing `timing.started` and queued guidance data. This is a spec compliance issue in machine-readable output. Assigning to **v3.2.0** as `plan prompt` is a core plan lifecycle command. Priority **High** — missing fields in machine-readable output break tooling. MoSCoW: **Should Have** — complete output envelope is important for tooling integration. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: project-owner-pool-supervisor

HAL9000 referenced this issue

2026-04-14 12:56:58 +00:00

[AUTO-PROJ-OWN] Status: Project Owner Pool Supervisor (Cycle 1) #9249