cleveragents/cleveragents-core

Fork 3

[BUG] agents plan prompt --format json envelope missing timing.started field (spec requires ISO timestamp) #9353

New issue

Open

opened 2026-04-14 15:21:44 +00:00 by HAL9000 · 1 comment

HAL9000 commented

2026-04-14 15:21:44 +00:00

Owner

Metadata

Commit Message: fix(cli): add timing.started ISO timestamp to plan prompt JSON envelope
Branch: fix/plan-prompt-json-timing-started

Background and Context

The agents plan prompt --format json command outputs a JSON envelope that is missing the timing.started field. The spec (§CLI Commands — agents plan prompt, docs/specification.md lines 15983–16011) defines a precise JSON envelope structure that includes timing.started as an ISO 8601 timestamp.

This was discovered during UAT testing of the Plan Diff and Artifacts CLI feature area. The plan_prompt_command.feature scenario "Plan prompt delivers guidance and returns spec envelope in json" is tagged @tdd_expected_fail @tdd_issue @tdd_issue_4255, indicating this is a known tracked deviation.

Current Behavior

In src/cleveragents/cli/commands/plan.py, the prompt_plan_cmd() command (line 3359) builds the envelope:

envelope: dict[str, object] = {
    "command": "plan prompt",
    "status": "ok",
    "exit_code": 0,
    "data": prompt_data,
    "timing": {"duration_ms": elapsed_ms},  # Missing "started" field
    "messages": ["Guidance queued"],
}

The timing dict only contains duration_ms but is missing started (ISO 8601 timestamp of when the command began).

Expected Behavior

Per docs/specification.md §agents plan prompt (lines 15983–16011), the JSON output must be:

{
  "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"]
}

The timing object must include started as an ISO 8601 UTC timestamp.

Acceptance Criteria

agents plan prompt <PLAN_ID> <GUIDANCE> --format json outputs a JSON object where timing contains both started (ISO 8601 UTC timestamp) and duration_ms
started is the ISO 8601 UTC timestamp of when the command began execution
The plan_prompt_command.feature scenario "Plan prompt delivers guidance and returns spec envelope in json" passes without @tdd_expected_fail
The @tdd_expected_fail @tdd_issue @tdd_issue_4255 tags are removed from the scenario once fixed

Supporting Information

Spec reference: docs/specification.md lines 15983–16011
Implementation: src/cleveragents/cli/commands/plan.py — prompt_plan_cmd() (line 3359), envelope construction at lines 3396–3403
Feature file: features/plan_prompt_command.feature — scenario "Plan prompt delivers guidance and returns spec envelope in json" (tagged @tdd_expected_fail @tdd_issue @tdd_issue_4255)
Step definition: features/steps/plan_prompt_command_steps.py — step_prompt_envelope_command(), step_prompt_envelope_status(), step_prompt_envelope_data()
The fix is minimal: capture datetime.now(UTC) before calling service.prompt_plan() and include it as timing["started"]

Subtasks

Capture started_at = datetime.now(UTC) before calling service.prompt_plan() in prompt_plan_cmd()
Add "started": started_at.isoformat() to the timing dict in the envelope
Remove @tdd_expected_fail @tdd_issue @tdd_issue_4255 tags from the scenario in plan_prompt_command.feature once fixed
Update step assertions in plan_prompt_command_steps.py to verify timing.started is present and is a valid ISO timestamp
Tests (Behave): Verify the scenario passes without @tdd_expected_fail
Run nox -s unit_tests -- features/plan_prompt_command.feature, fix any errors
Verify coverage ≥97% via nox -s coverage_report

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 details.
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): add timing.started ISO timestamp to plan prompt JSON envelope` - **Branch**: `fix/plan-prompt-json-timing-started` ## Background and Context The `agents plan prompt --format json` command outputs a JSON envelope that is missing the `timing.started` field. The spec (§CLI Commands — agents plan prompt, `docs/specification.md` lines 15983–16011) defines a precise JSON envelope structure that includes `timing.started` as an ISO 8601 timestamp. This was discovered during UAT testing of the Plan Diff and Artifacts CLI feature area. The `plan_prompt_command.feature` scenario "Plan prompt delivers guidance and returns spec envelope in json" is tagged `@tdd_expected_fail @tdd_issue @tdd_issue_4255`, indicating this is a known tracked deviation. ## Current Behavior In `src/cleveragents/cli/commands/plan.py`, the `prompt_plan_cmd()` command (line 3359) builds the envelope: ```python envelope: dict[str, object] = { "command": "plan prompt", "status": "ok", "exit_code": 0, "data": prompt_data, "timing": {"duration_ms": elapsed_ms}, # Missing "started" field "messages": ["Guidance queued"], } ``` The `timing` dict only contains `duration_ms` but is missing `started` (ISO 8601 timestamp of when the command began). ## Expected Behavior Per `docs/specification.md` §agents plan prompt (lines 15983–16011), the JSON output must be: ```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"] } ``` The `timing` object must include `started` as an ISO 8601 UTC timestamp. ## Acceptance Criteria - `agents plan prompt <PLAN_ID> <GUIDANCE> --format json` outputs a JSON object where `timing` contains both `started` (ISO 8601 UTC timestamp) and `duration_ms` - `started` is the ISO 8601 UTC timestamp of when the command began execution - The `plan_prompt_command.feature` scenario "Plan prompt delivers guidance and returns spec envelope in json" passes without `@tdd_expected_fail` - The `@tdd_expected_fail @tdd_issue @tdd_issue_4255` tags are removed from the scenario once fixed ## Supporting Information - Spec reference: `docs/specification.md` lines 15983–16011 - Implementation: `src/cleveragents/cli/commands/plan.py` — `prompt_plan_cmd()` (line 3359), envelope construction at lines 3396–3403 - Feature file: `features/plan_prompt_command.feature` — scenario "Plan prompt delivers guidance and returns spec envelope in json" (tagged `@tdd_expected_fail @tdd_issue @tdd_issue_4255`) - Step definition: `features/steps/plan_prompt_command_steps.py` — `step_prompt_envelope_command()`, `step_prompt_envelope_status()`, `step_prompt_envelope_data()` - The fix is minimal: capture `datetime.now(UTC)` before calling `service.prompt_plan()` and include it as `timing["started"]` ## Subtasks - [ ] Capture `started_at = datetime.now(UTC)` before calling `service.prompt_plan()` in `prompt_plan_cmd()` - [ ] Add `"started": started_at.isoformat()` to the `timing` dict in the envelope - [ ] Remove `@tdd_expected_fail @tdd_issue @tdd_issue_4255` tags from the scenario in `plan_prompt_command.feature` once fixed - [ ] Update step assertions in `plan_prompt_command_steps.py` to verify `timing.started` is present and is a valid ISO timestamp - [ ] Tests (Behave): Verify the scenario passes without `@tdd_expected_fail` - [ ] Run `nox -s unit_tests -- features/plan_prompt_command.feature`, fix any errors - [ ] Verify coverage ≥97% via `nox -s coverage_report` ## 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 details. - 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 15:24:13 +00:00

HAL9000 added this to the v3.2.0 milestone

2026-04-14 15:24:13 +00:00

HAL9000 commented

2026-04-14 15:24:13 +00:00

Author

Owner

✅ Triage: Verified [AUTO-OWNR-1]

Valid bug: agents plan prompt --format json is missing the timing.started ISO timestamp field in the output envelope. The spec requires both started and duration_ms in the timing object. This is a known tracked deviation (tagged @tdd_expected_fail @tdd_issue @tdd_issue_4255 in the feature file).

Assigning to v3.2.0 as plan prompt is a core command. Priority Medium — missing field in machine-readable output.

MoSCoW: Should Have — the timing.started field is important for programmatic consumers tracking command execution timing.

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

✅ **Triage: Verified** [AUTO-OWNR-1] Valid bug: `agents plan prompt --format json` is missing the `timing.started` ISO timestamp field in the output envelope. The spec requires both `started` and `duration_ms` in the `timing` object. This is a known tracked deviation (tagged `@tdd_expected_fail @tdd_issue @tdd_issue_4255` in the feature file). Assigning to **v3.2.0** as plan prompt is a core command. Priority **Medium** — missing field in machine-readable output. MoSCoW: **Should Have** — the `timing.started` field is important for programmatic consumers tracking command execution timing. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: project-owner-pool-supervisor

HAL9000 referenced this issue from a commit

2026-04-14 17:57:56 +00:00

fix(cli): add timing.started ISO timestamp to plan prompt JSON envelope

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

2026-04-14 17:58:32 +00:00

fix(cli): add timing.started ISO timestamp to plan prompt JSON envelope #9447

HAL9000 added

and removed