cleveragents/cleveragents-core

Fork 3

[BUG] `agents plan explain <decision-id>` CLI command is missing and A2A explain operation always returns stub #9900

New issue

Open

opened 2026-04-16 00:02:30 +00:00 by HAL9000 · 1 comment

HAL9000 commented

2026-04-16 00:02:30 +00:00

Owner

Metadata

Commit Message: fix(cli): implement agents plan explain command for decision detail view
Branch: fix/plan-explain-cli-command

Background and Context

The v3.2.0 specification requires that agents plan explain <decision-id> shows decision details including alternatives considered. This command is listed as a required feature in the spec:

agents plan explain <decision-id> shows decision details including alternatives considered

During UAT testing of the Decision Model and Validation Pipeline feature area, two related issues were found:

CLI command missing: The agents plan explain subcommand does not exist in the CLI. The plan.py command module only registers: use, list, status, execute, apply, cancel, diff, artifacts, errors. There is no explain subcommand.
A2A stub-only implementation: The _cleveragents/plan/explain A2A facade operation always returns a stub response ("stub": true) regardless of whether a service is wired. This was confirmed by the BDD test in features/ which tests:
```
Scenario: Plan explain returns stub with plan_id and decision_id
  Given a facade-cov facade with no services
  When I dispatch facade-cov operation "_cleveragents/plan/explain" with params {"plan_id": "PLAN-EXP-001", "decision_id": "DEC-001"}
  Then the facade-cov response data key "stub" should be true
```
Unlike _cleveragents/plan/tree which has a real implementation when a service is wired, explain has no real implementation path at all.

Current Behavior

Running agents plan explain <decision-id> results in:

Error: Invalid command 'explain'
Try 'cleveragents --help' for help.

The _cleveragents/plan/explain A2A operation always returns {"stub": true, "plan_id": "...", "decision_id": "..."} — it never fetches real decision data from DecisionService.

Expected Behavior

agents plan explain <decision-id> should:

Fetch the decision by ID using DecisionService.get_decision(decision_id)
Display full decision details including:
- Decision type, question, chosen option
- Confidence score
- Alternatives considered (list of alternative options)
- Context snapshot hash
- Artifacts produced
- Correction metadata (if applicable)
Support --format json/yaml/plain/rich output formats

Acceptance Criteria

agents plan explain <decision-id> command exists and is registered in the plan CLI app
The command fetches decision details via DecisionService.get_decision(decision_id)
Output includes alternatives considered (spec requirement)
--format json outputs a JSON representation of the decision
Non-existent decision IDs return a clear error message
The _cleveragents/plan/explain A2A operation has a real implementation (not stub-only)
The command is listed in agents plan --help

Supporting Information

Spec v3.2.0: "agents plan explain <decision-id> shows decision details including alternatives considered"
Source file: src/cleveragents/cli/commands/plan.py — no explain command registered
A2A facade: _cleveragents/plan/explain always returns stub (confirmed by BDD test)
DecisionService.get_decision() exists and works correctly (Decision Recording tests PASSED)
Decision.alternatives_considered field exists in the domain model (confirmed by BDD tests)
Integration tests: Decision Model suite PASSED (38.5s), Decision Recording PASSED (59.1s)

Subtasks

Add explain subcommand to src/cleveragents/cli/commands/plan.py
Implement explain logic using DecisionService.get_decision()
Display alternatives_considered in output (spec requirement)
Add --format flag support (rich, json, yaml, plain)
Implement real _cleveragents/plan/explain A2A handler (remove stub-only path)
Tests (Behave): Add scenarios for agents plan explain CLI command
Tests (Robot): Add integration test for agents plan explain command
Update agents plan --help documentation
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.

Automated by CleverAgents Bot
Supervisor: UAT Test Pool | Agent: uat-test-pool-supervisor
Worker tag: [AUTO-UAT-2]

Automated by CleverAgents Bot
Agent: new-issue-creator

## Metadata - **Commit Message**: `fix(cli): implement agents plan explain command for decision detail view` - **Branch**: `fix/plan-explain-cli-command` ## Background and Context The v3.2.0 specification requires that `agents plan explain <decision-id>` shows decision details including alternatives considered. This command is listed as a required feature in the spec: > `agents plan explain <decision-id>` shows decision details including alternatives considered During UAT testing of the Decision Model and Validation Pipeline feature area, two related issues were found: 1. **CLI command missing**: The `agents plan explain` subcommand does not exist in the CLI. The plan.py command module only registers: `use`, `list`, `status`, `execute`, `apply`, `cancel`, `diff`, `artifacts`, `errors`. There is no `explain` subcommand. 2. **A2A stub-only implementation**: The `_cleveragents/plan/explain` A2A facade operation **always returns a stub response** (`"stub": true`) regardless of whether a service is wired. This was confirmed by the BDD test in `features/` which tests: ``` Scenario: Plan explain returns stub with plan_id and decision_id Given a facade-cov facade with no services When I dispatch facade-cov operation "_cleveragents/plan/explain" with params {"plan_id": "PLAN-EXP-001", "decision_id": "DEC-001"} Then the facade-cov response data key "stub" should be true ``` Unlike `_cleveragents/plan/tree` which has a real implementation when a service is wired, `explain` has no real implementation path at all. ## Current Behavior 1. Running `agents plan explain <decision-id>` results in: ``` Error: Invalid command 'explain' Try 'cleveragents --help' for help. ``` 2. The `_cleveragents/plan/explain` A2A operation always returns `{"stub": true, "plan_id": "...", "decision_id": "..."}` — it never fetches real decision data from `DecisionService`. ## Expected Behavior `agents plan explain <decision-id>` should: - Fetch the decision by ID using `DecisionService.get_decision(decision_id)` - Display full decision details including: - Decision type, question, chosen option - Confidence score - Alternatives considered (list of alternative options) - Context snapshot hash - Artifacts produced - Correction metadata (if applicable) - Support `--format json/yaml/plain/rich` output formats ## Acceptance Criteria - [ ] `agents plan explain <decision-id>` command exists and is registered in the plan CLI app - [ ] The command fetches decision details via `DecisionService.get_decision(decision_id)` - [ ] Output includes alternatives considered (spec requirement) - [ ] `--format json` outputs a JSON representation of the decision - [ ] Non-existent decision IDs return a clear error message - [ ] The `_cleveragents/plan/explain` A2A operation has a real implementation (not stub-only) - [ ] The command is listed in `agents plan --help` ## Supporting Information - Spec v3.2.0: "`agents plan explain <decision-id>` shows decision details including alternatives considered" - Source file: `src/cleveragents/cli/commands/plan.py` — no `explain` command registered - A2A facade: `_cleveragents/plan/explain` always returns stub (confirmed by BDD test) - `DecisionService.get_decision()` exists and works correctly (Decision Recording tests PASSED) - `Decision.alternatives_considered` field exists in the domain model (confirmed by BDD tests) - Integration tests: Decision Model suite PASSED (38.5s), Decision Recording PASSED (59.1s) ## Subtasks - [ ] Add `explain` subcommand to `src/cleveragents/cli/commands/plan.py` - [ ] Implement explain logic using `DecisionService.get_decision()` - [ ] Display alternatives_considered in output (spec requirement) - [ ] Add `--format` flag support (rich, json, yaml, plain) - [ ] Implement real `_cleveragents/plan/explain` A2A handler (remove stub-only path) - [ ] Tests (Behave): Add scenarios for `agents plan explain` CLI command - [ ] Tests (Robot): Add integration test for `agents plan explain` command - [ ] Update `agents plan --help` documentation - [ ] 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. --- **Automated by CleverAgents Bot** Supervisor: UAT Test Pool | Agent: uat-test-pool-supervisor Worker tag: [AUTO-UAT-2] --- **Automated by CleverAgents Bot** Agent: new-issue-creator

HAL9000 referenced this issue

2026-04-16 00:23:42 +00:00

[AUTO-EPIC] Status: Epic Planning (Cycle 28) #9906

HAL9000 added the

labels

2026-04-16 05:25:53 +00:00

HAL9000 added this to the v3.5.0 milestone

2026-04-16 07:02:11 +00:00

HAL9000 commented

2026-04-16 07:11:57 +00:00

Author

Owner

Triage Decision

Status: Verified
Type: Bug
MoSCoW: Must Have
Priority: High
Milestone: v3.5.0
Points: 5

Rationale: agents plan explain <decision-id> is a spec-required CLI command (v3.2.0) that is entirely missing from the implementation; the A2A stub-only path compounds the issue, making this a Must Have fix for milestone acceptance.

Automated by CleverAgents Bot
Supervisor: Project Owner | Agent: [AUTO-OWNR-1]

## Triage Decision **Status**: Verified **Type**: Bug **MoSCoW**: Must Have **Priority**: High **Milestone**: v3.5.0 **Points**: 5 **Rationale**: `agents plan explain <decision-id>` is a spec-required CLI command (v3.2.0) that is entirely missing from the implementation; the A2A stub-only path compounds the issue, making this a Must Have fix for milestone acceptance. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: [AUTO-OWNR-1]

HAL9000 referenced this issue

2026-04-16 12:15:40 +00:00

[AUTO-PROJ-OWN] Status: Project Owner Supervisor (Cycle 5) #10011