cleveragents/cleveragents-core

Fork 3

UAT: `agents plan explain` sequence field shows integer instead of "N of M" format, and alternatives are plain strings instead of structured objects #3115

New issue

Open

opened 2026-04-05 06:23:57 +00:00 by freemo · 1 comment

freemo commented

2026-04-05 06:23:57 +00:00

Owner

Metadata

Branch: fix/plan-explain-sequence-and-alternatives-format
Commit Message: fix(cli): correct plan explain sequence and alternatives output format
Milestone: (none — backlog)
Parent Epic: #357

Description

Two output format mismatches in agents plan explain compared to the spec (docs/specification.md lines 14658–14755):

1. Sequence format mismatch

The spec shows "sequence": "2 of 5" (string with total count) in JSON/YAML output, but the implementation outputs just the integer sequence number (e.g., "sequence": 2). This makes it harder for users to understand where a decision falls in the overall plan.

2. Alternatives format mismatch

The spec shows alternatives as structured objects:

"alternatives": [
  {"index": 1, "description": "Auth and payments", "chosen": true},
  {"index": 2, "description": "User module first", "chosen": false}
]

But the implementation outputs alternatives_considered as a plain list of strings (the raw field value), with no index, no chosen flag, and using a different key name (alternatives_considered vs alternatives).

Code location: src/cleveragents/cli/commands/plan.py lines 3455–3490 (_build_explain_dict)

Spec reference: docs/specification.md lines 14658–14755 (agents plan explain JSON/YAML output section)

Subtasks

Update _build_explain_dict in src/cleveragents/cli/commands/plan.py to format sequence as "N of M" string (requires access to total decision count in the plan)
Update _build_explain_dict to rename alternatives_considered key to alternatives and convert each string entry to a structured object with index, description, and chosen fields
Determine how to identify the "chosen" alternative (e.g., from decision.chosen_alternative_index or equivalent field)
Update any related unit tests in the plan CLI test suite to assert the new output shapes
Tests (Behave): Update/add scenarios for agents plan explain JSON/YAML output to assert "N of M" sequence format and structured alternatives
Tests (Robot): Update/add integration tests for agents plan explain output format
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.
agents plan explain --format json outputs "sequence": "N of M" (e.g., "2 of 5") matching spec lines 14658–14755.
agents plan explain --format json outputs "alternatives" as a list of objects with index (int), description (string), and chosen (bool) fields, matching the spec.
agents plan explain --format yaml produces equivalent correct output.
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.
All nox stages pass
Coverage >= 97%

Backlog note: This issue was discovered during autonomous operation
on milestone v3.2.0. It does not block milestone completion and has been
placed in the backlog for human review and future milestone assignment.

Automated by CleverAgents Bot
Supervisor: UAT Testing | Agent: ca-new-issue-creator

## Metadata - **Branch**: `fix/plan-explain-sequence-and-alternatives-format` - **Commit Message**: `fix(cli): correct plan explain sequence and alternatives output format` - **Milestone**: *(none — backlog)* - **Parent Epic**: #357 ## Description Two output format mismatches in `agents plan explain` compared to the spec (docs/specification.md lines 14658–14755): ### 1. Sequence format mismatch The spec shows `"sequence": "2 of 5"` (string with total count) in JSON/YAML output, but the implementation outputs just the integer sequence number (e.g., `"sequence": 2`). This makes it harder for users to understand where a decision falls in the overall plan. ### 2. Alternatives format mismatch The spec shows alternatives as structured objects: ```json "alternatives": [ {"index": 1, "description": "Auth and payments", "chosen": true}, {"index": 2, "description": "User module first", "chosen": false} ] ``` But the implementation outputs `alternatives_considered` as a plain list of strings (the raw field value), with no `index`, no `chosen` flag, and using a different key name (`alternatives_considered` vs `alternatives`). **Code location**: `src/cleveragents/cli/commands/plan.py` lines 3455–3490 (`_build_explain_dict`) **Spec reference**: docs/specification.md lines 14658–14755 (agents plan explain JSON/YAML output section) ## Subtasks - [ ] Update `_build_explain_dict` in `src/cleveragents/cli/commands/plan.py` to format `sequence` as `"N of M"` string (requires access to total decision count in the plan) - [ ] Update `_build_explain_dict` to rename `alternatives_considered` key to `alternatives` and convert each string entry to a structured object with `index`, `description`, and `chosen` fields - [ ] Determine how to identify the "chosen" alternative (e.g., from `decision.chosen_alternative_index` or equivalent field) - [ ] Update any related unit tests in the plan CLI test suite to assert the new output shapes - [ ] Tests (Behave): Update/add scenarios for `agents plan explain` JSON/YAML output to assert `"N of M"` sequence format and structured alternatives - [ ] Tests (Robot): Update/add integration tests for `agents plan explain` output format - [ ] 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. - `agents plan explain --format json` outputs `"sequence": "N of M"` (e.g., `"2 of 5"`) matching spec lines 14658–14755. - `agents plan explain --format json` outputs `"alternatives"` as a list of objects with `index` (int), `description` (string), and `chosen` (bool) fields, matching the spec. - `agents plan explain --format yaml` produces equivalent correct output. - 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. - All nox stages pass - Coverage >= 97% > **Backlog note:** This issue was discovered during autonomous operation > on milestone v3.2.0. It does not block milestone completion and has been > placed in the backlog for human review and future milestone assignment. --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-new-issue-creator

freemo added a new dependency

2026-04-05 06:26:12 +00:00

#357 Epic: Decisions + Validations + Invariants (M3)

freemo referenced this issue

2026-04-05 06:34:14 +00:00

[CA-AUTO] UAT Pool Supervisor — v3.2.0–v3.7.0 — Session Tracker #3094

freemo added this to the v3.2.0 milestone

2026-04-05 06:41:51 +00:00

freemo referenced this issue

2026-04-05 06:43:52 +00:00

[CA-AUTO] UAT Pool Supervisor — v3.2.0–v3.7.0 — Session Tracker #3094

freemo commented

2026-04-05 06:43:57 +00:00

Author

Owner

Issue triaged by project owner:

State: Verified
Priority: Medium — output format deviation from spec; does not break functionality but degrades user experience and API contract compliance
Milestone: v3.2.0 (Decisions + Validations + Invariants) — plan explain is a core v3.2.0 acceptance criterion
MoSCoW: Should Have — the v3.2.0 milestone acceptance criteria state "agents plan explain shows decision details including alternatives considered"; the current output format does not match the spec's structured format, but the command is functional
Parent Epic: #357 (Decisions + Validations + Invariants)

Assigned to v3.2.0 since plan explain output format is directly part of that milestone's scope. Dependency link to parent Epic already existed.

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

Issue triaged by project owner: - **State**: Verified - **Priority**: Medium — output format deviation from spec; does not break functionality but degrades user experience and API contract compliance - **Milestone**: v3.2.0 (Decisions + Validations + Invariants) — `plan explain` is a core v3.2.0 acceptance criterion - **MoSCoW**: Should Have — the v3.2.0 milestone acceptance criteria state "`agents plan explain` shows decision details including alternatives considered"; the current output format does not match the spec's structured format, but the command is functional - **Parent Epic**: #357 (Decisions + Validations + Invariants) Assigned to v3.2.0 since `plan explain` output format is directly part of that milestone's scope. Dependency link to parent Epic already existed. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: ca-project-owner

freemo referenced this issue

2026-04-05 06:53:54 +00:00

[CA-AUTO] UAT Pool Supervisor — v3.2.0–v3.7.0 — Session Tracker #3094

freemo referenced this issue

2026-04-05 07:06:25 +00:00

[CA-AUTO] UAT Pool Supervisor — v3.2.0–v3.7.0 — Session Tracker #3124

freemo referenced this issue

2026-04-05 07:10:22 +00:00

UAT: agents plan explain rich output uses wrong layout — missing spec-required panels #3156

freemo referenced this issue

2026-04-05 07:44:47 +00:00

[CA-AUTO] UAT Pool Supervisor — v3.2.0–v3.7.0 — Session Tracker #3094