cleveragents/cleveragents-core

Fork 3

UAT: `agents plan explain` JSON/YAML output missing spec-required fields: `correction_hint`, `impact`, and `sequence` (formatted) #2841

New issue

Open

opened 2026-04-04 20:47:56 +00:00 by freemo · 1 comment

freemo commented

2026-04-04 20:47:56 +00:00

Owner

Background

During UAT code analysis of src/cleveragents/cli/commands/plan.py, the _build_explain_dict() function (lines 3440–3475) was found to be missing three fields that are explicitly required by the specification (docs/specification.md lines 14662–14702) in the JSON/YAML output of agents plan explain.

Current Behavior

The _build_explain_dict() function currently returns:

data = {
    "decision_id": decision.decision_id,
    "plan_id": decision.plan_id,
    "type": str(decision.decision_type),
    "sequence": decision.sequence_number,  # raw int, not "N of M" format
    "question": decision.question,
    "chosen": decision.chosen_option,
    "confidence": decision.confidence_score,
    "parent": decision.parent_decision_id or "(root)",
    "is_correction": decision.is_correction,
    "superseded": decision.is_superseded,
    "created_at": decision.created_at.isoformat(),
    "alternatives_considered": decision.alternatives_considered,
}

Three fields are missing or incorrect:

correction_hint — not included at all
impact — not included at all
sequence — stored as a raw integer instead of the spec's "N of M" format

Expected Behavior

Per docs/specification.md lines 14662–14702, the JSON output of agents plan explain <DECISION_ID> --format json must include:

{
  "decision_id": "01HXM9A1C2Q7W3R5G8Z0P4Q1X9",
  "type": "strategy_choice",
  "question": "Which modules should be prioritized?",
  "chosen": "Auth and payments",
  "confidence": 0.82,
  "plan_id": "01HXM8C2ZK4Q7C2B3F2R4VYV6J",
  "sequence": "2 of 5",
  "created": "2026-02-08T12:58:00Z",
  "alternatives": [...],
  "impact": {
    "downstream_decisions": 3,
    "downstream_child_plans": 2,
    "artifacts_produced": 5,
    "correction_impact": "medium"
  },
  "context_snapshot": {...},
  "rationale": "...",
  "correction_hint": "agents plan correct 01HXM9A1C2Q7W3R5G8Z0P4Q1X9 --mode revert --guidance \"...\""
}

Steps to Reproduce

Run agents plan explain <DECISION_ID> --format json
Observe: Output is missing correction_hint, impact, and sequence is a raw integer
Expected: All three fields present with correct values and format

Metadata

Branch: fix/plan-explain-missing-output-fields
Commit Message: fix(cli): add correction_hint, impact, and formatted sequence to plan explain output
Milestone: v3.3.0
Parent Epic: #394

Subtasks

Add correction_hint field to _build_explain_dict(): f"agents plan correct {decision.decision_id} --mode revert --guidance \"...\""
Add impact field to _build_explain_dict() with sub-fields: downstream_decisions, downstream_child_plans, artifacts_produced, correction_impact (may require querying decision dependency graph)
Fix sequence field to use "N of M" format (requires fetching total decision count for the plan)
Tests (Behave): Add/update scenarios in features/ covering JSON and YAML output of agents plan explain to assert all three fields are present and correctly formatted
Tests (Robot): Add/update integration test in robot/ for agents plan explain --format json asserting spec-compliant output
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.
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.
agents plan explain <DECISION_ID> --format json output includes correction_hint, impact (with all four sub-fields), and sequence in "N of M" format, matching the spec at docs/specification.md lines 14662–14702.
All nox stages pass.
Coverage >= 97%.

Automated by CleverAgents Bot
Supervisor: UAT Testing | Agent: ca-uat-tester

## Background During UAT code analysis of `src/cleveragents/cli/commands/plan.py`, the `_build_explain_dict()` function (lines 3440–3475) was found to be missing three fields that are explicitly required by the specification (`docs/specification.md` lines 14662–14702) in the JSON/YAML output of `agents plan explain`. ## Current Behavior The `_build_explain_dict()` function currently returns: ```python data = { "decision_id": decision.decision_id, "plan_id": decision.plan_id, "type": str(decision.decision_type), "sequence": decision.sequence_number, # raw int, not "N of M" format "question": decision.question, "chosen": decision.chosen_option, "confidence": decision.confidence_score, "parent": decision.parent_decision_id or "(root)", "is_correction": decision.is_correction, "superseded": decision.is_superseded, "created_at": decision.created_at.isoformat(), "alternatives_considered": decision.alternatives_considered, } ``` Three fields are missing or incorrect: 1. **`correction_hint`** — not included at all 2. **`impact`** — not included at all 3. **`sequence`** — stored as a raw integer instead of the spec's `"N of M"` format ## Expected Behavior Per `docs/specification.md` lines 14662–14702, the JSON output of `agents plan explain <DECISION_ID> --format json` must include: ```json { "decision_id": "01HXM9A1C2Q7W3R5G8Z0P4Q1X9", "type": "strategy_choice", "question": "Which modules should be prioritized?", "chosen": "Auth and payments", "confidence": 0.82, "plan_id": "01HXM8C2ZK4Q7C2B3F2R4VYV6J", "sequence": "2 of 5", "created": "2026-02-08T12:58:00Z", "alternatives": [...], "impact": { "downstream_decisions": 3, "downstream_child_plans": 2, "artifacts_produced": 5, "correction_impact": "medium" }, "context_snapshot": {...}, "rationale": "...", "correction_hint": "agents plan correct 01HXM9A1C2Q7W3R5G8Z0P4Q1X9 --mode revert --guidance \"...\"" } ``` ## Steps to Reproduce 1. Run `agents plan explain <DECISION_ID> --format json` 2. **Observe**: Output is missing `correction_hint`, `impact`, and `sequence` is a raw integer 3. **Expected**: All three fields present with correct values and format ## Metadata - **Branch**: `fix/plan-explain-missing-output-fields` - **Commit Message**: `fix(cli): add correction_hint, impact, and formatted sequence to plan explain output` - **Milestone**: v3.3.0 - **Parent Epic**: #394 ## Subtasks - [ ] Add `correction_hint` field to `_build_explain_dict()`: `f"agents plan correct {decision.decision_id} --mode revert --guidance \"...\""` - [ ] Add `impact` field to `_build_explain_dict()` with sub-fields: `downstream_decisions`, `downstream_child_plans`, `artifacts_produced`, `correction_impact` (may require querying decision dependency graph) - [ ] Fix `sequence` field to use `"N of M"` format (requires fetching total decision count for the plan) - [ ] Tests (Behave): Add/update scenarios in `features/` covering JSON and YAML output of `agents plan explain` to assert all three fields are present and correctly formatted - [ ] Tests (Robot): Add/update integration test in `robot/` for `agents plan explain --format json` asserting spec-compliant output - [ ] 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. - 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. - `agents plan explain <DECISION_ID> --format json` output includes `correction_hint`, `impact` (with all four sub-fields), and `sequence` in `"N of M"` format, matching the spec at `docs/specification.md` lines 14662–14702. - All nox stages pass. - Coverage >= 97%. --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-uat-tester

freemo added this to the v3.3.0 milestone

2026-04-04 20:48:01 +00:00

freemo added the

labels

2026-04-04 20:48:07 +00:00

freemo added a new dependency

2026-04-04 20:48:14 +00:00

#394 Epic: Decision Framework

freemo referenced this issue

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

[CA-AUTO] UAT Pool Supervisor — v3.7.0 — Session Tracker #2803

freemo commented

2026-04-05 02:35:06 +00:00

Author

Owner

Issue triaged by project owner:

State: Verified
Priority: Medium — Missing output fields in agents plan explain JSON/YAML. The spec requires correction_hint, impact, and formatted sequence fields. These are output completeness issues, not functional blockers.
Milestone: v3.3.0 (already set correctly — Corrections + Subplans milestone)
MoSCoW: Should Have — The spec defines these fields explicitly. API consumers parsing JSON output need correct field names and formats. However, the core explain functionality works.
Parent Epic: #394 (Epic: Decision Framework)

Valid UAT finding. Related to #2834 which tracks key name mismatches in the same function.

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

Issue triaged by project owner: - **State**: Verified - **Priority**: Medium — Missing output fields in `agents plan explain` JSON/YAML. The spec requires `correction_hint`, `impact`, and formatted `sequence` fields. These are output completeness issues, not functional blockers. - **Milestone**: v3.3.0 (already set correctly — Corrections + Subplans milestone) - **MoSCoW**: Should Have — The spec defines these fields explicitly. API consumers parsing JSON output need correct field names and formats. However, the core explain functionality works. - **Parent Epic**: #394 (Epic: Decision Framework) Valid UAT finding. Related to #2834 which tracks key name mismatches in the same function. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: ca-project-owner

freemo referenced this issue

2026-04-05 02:35:10 +00:00

UAT: agents plan explain JSON/YAML output uses wrong key names — created_at instead of created, alternatives_considered instead of alternatives #2834