UAT: agents plan execute - undocumented --execution-environment flag not in spec #2935

New issue

Open

opened 2026-04-05 02:52:14 +00:00 by freemo · 1 comment

freemo commented

2026-04-05 02:52:14 +00:00

Owner

Metadata

Branch: fix/plan-execute-undocumented-execution-environment-flag
Commit Message: fix(cli): document --execution-environment flag in agents plan execute spec
Milestone: v3.7.0
Parent Epic: #397

Background

UAT testing of the agents plan execute CLI command revealed a spec-implementation gap: a flag accepted by the implementation is entirely absent from the specification reference documentation.

The spec (docs/reference/plan_cli.md) defines the synopsis for agents plan execute as:

agents plan execute [PLAN_ID] [--format FORMAT]

However, the implementation in src/cleveragents/cli/commands/plan.py (lines 1738–1752) also accepts an additional undocumented flag:

--execution-environment (e.g., "host" or "container")

This flag is not documented in the spec and users cannot discover it from the spec reference. Per CONTRIBUTING.md and the project's source-of-truth policy, the specification is authoritative — when there is a discrepancy between the codebase and the specification, the specification is considered correct and the code must be updated to match it. In this case, however, the flag appears to be intentional and useful functionality, so the resolution is to update the spec to document it.

Steps to Reproduce: Run agents plan execute --help and observe --execution-environment option that is absent from the spec.

Code Location: src/cleveragents/cli/commands/plan.py lines 1738–1752
Spec Location: docs/reference/plan_cli.md — Synopsis section for agents plan execute

Subtasks

Confirm the intended semantics of --execution-environment (valid values: host, container) with the spec owner
Update docs/reference/plan_cli.md to add --execution-environment to the synopsis and Options table for agents plan execute, including accepted values and descriptions
Update docs/specification.md if the execution environment concept is described there and the flag is missing from the CLI surface section
Add Behave unit test scenarios covering the flag (valid values, invalid values, default behaviour when omitted)
Verify agents plan execute --help output matches the updated spec exactly
Ensure all nox quality gates pass

Definition of Done

docs/reference/plan_cli.md synopsis and Options table for agents plan execute includes --execution-environment with full description and accepted values
docs/specification.md is consistent with the updated CLI reference (no remaining gap)
Behave scenarios cover the new flag
agents plan execute --help output matches the spec
All nox stages pass
Coverage >= 97%

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

## Metadata - **Branch**: `fix/plan-execute-undocumented-execution-environment-flag` - **Commit Message**: `fix(cli): document --execution-environment flag in agents plan execute spec` - **Milestone**: v3.7.0 - **Parent Epic**: #397 ## Background UAT testing of the `agents plan execute` CLI command revealed a spec-implementation gap: a flag accepted by the implementation is entirely absent from the specification reference documentation. The spec (`docs/reference/plan_cli.md`) defines the synopsis for `agents plan execute` as: ``` agents plan execute [PLAN_ID] [--format FORMAT] ``` However, the implementation in `src/cleveragents/cli/commands/plan.py` (lines 1738–1752) also accepts an additional undocumented flag: - `--execution-environment` (e.g., `"host"` or `"container"`) This flag is not documented in the spec and users cannot discover it from the spec reference. Per CONTRIBUTING.md and the project's source-of-truth policy, the specification is authoritative — when there is a discrepancy between the codebase and the specification, the specification is considered correct and the code must be updated to match it. In this case, however, the flag appears to be intentional and useful functionality, so the resolution is to update the spec to document it. **Steps to Reproduce**: Run `agents plan execute --help` and observe `--execution-environment` option that is absent from the spec. **Code Location**: `src/cleveragents/cli/commands/plan.py` lines 1738–1752 **Spec Location**: `docs/reference/plan_cli.md` — Synopsis section for `agents plan execute` ## Subtasks - [ ] Confirm the intended semantics of `--execution-environment` (valid values: `host`, `container`) with the spec owner - [ ] Update `docs/reference/plan_cli.md` to add `--execution-environment` to the synopsis and Options table for `agents plan execute`, including accepted values and descriptions - [ ] Update `docs/specification.md` if the execution environment concept is described there and the flag is missing from the CLI surface section - [ ] Add Behave unit test scenarios covering the flag (valid values, invalid values, default behaviour when omitted) - [ ] Verify `agents plan execute --help` output matches the updated spec exactly - [ ] Ensure all nox quality gates pass ## Definition of Done - [ ] `docs/reference/plan_cli.md` synopsis and Options table for `agents plan execute` includes `--execution-environment` with full description and accepted values - [ ] `docs/specification.md` is consistent with the updated CLI reference (no remaining gap) - [ ] Behave scenarios cover the new flag - [ ] `agents plan execute --help` output matches the spec - [ ] All nox stages pass - [ ] Coverage >= 97% --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-uat-tester

freemo added this to the v3.7.0 milestone

2026-04-05 02:52:58 +00:00

freemo added a new dependency

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

#397 Epic: Server & Autonomy Infrastructure

freemo commented

2026-04-05 03:01:15 +00:00

Author

Owner

Issue triaged by project owner:

State: Verified
Priority: Confirmed
MoSCoW: Should Have

Valid finding verified during batch triage.

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

Issue triaged by project owner: - **State**: Verified - **Priority**: Confirmed - **MoSCoW**: Should Have Valid finding verified during batch triage. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: ca-project-owner

freemo referenced this issue

2026-04-05 06:15:22 +00:00

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