UAT: agents plan use - undocumented --execution-environment and --execution-env-priority flags not in spec #2906

Open
opened 2026-04-05 02:46:39 +00:00 by freemo · 1 comment
Owner

Metadata

  • Branch: fix/plan-use-undocumented-execution-env-flags
  • Commit Message: fix(cli): document --execution-environment and --execution-env-priority flags in agents plan use spec
  • Milestone: v3.7.0
  • Parent Epic: #397

Background

UAT testing of the agents plan use CLI command revealed a spec-implementation gap: two flags accepted by the implementation are entirely absent from the specification reference documentation.

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

  • --project / -p
  • --arg / -a
  • --automation-profile
  • --invariant
  • --strategy-actor
  • --execution-actor
  • --estimation-actor
  • --invariant-actor
  • --format / -f

However, the implementation in src/cleveragents/cli/commands/plan.py (lines 1463–1476) also accepts two additional undocumented flags:

  • --execution-environment (e.g., "host" or "container")
  • --execution-env-priority (e.g., "fallback" or "override")

These flags are not documented in the spec and users cannot discover them 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 flags appear to be intentional and useful functionality, so the resolution is to update the spec to document them.

Steps to Reproduce: Run agents plan use --help and observe --execution-environment and --execution-env-priority options that are absent from the spec.

Code Location: src/cleveragents/cli/commands/plan.py lines 1463–1476
Spec Location: docs/reference/plan_cli.md — Options table for agents plan use

Subtasks

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

Definition of Done

  • docs/reference/plan_cli.md Options table for agents plan use includes --execution-environment and --execution-env-priority with full descriptions and accepted values
  • docs/specification.md is consistent with the updated CLI reference (no remaining gap)
  • Behave scenarios cover both new flags
  • agents plan use --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-use-undocumented-execution-env-flags` - **Commit Message**: `fix(cli): document --execution-environment and --execution-env-priority flags in agents plan use spec` - **Milestone**: v3.7.0 - **Parent Epic**: #397 ## Background UAT testing of the `agents plan use` CLI command revealed a spec-implementation gap: two flags accepted by the implementation are entirely absent from the specification reference documentation. The spec (`docs/reference/plan_cli.md`) defines the options for `agents plan use` as: - `--project` / `-p` - `--arg` / `-a` - `--automation-profile` - `--invariant` - `--strategy-actor` - `--execution-actor` - `--estimation-actor` - `--invariant-actor` - `--format` / `-f` However, the implementation in `src/cleveragents/cli/commands/plan.py` (lines 1463–1476) also accepts two additional undocumented flags: - `--execution-environment` (e.g., `"host"` or `"container"`) - `--execution-env-priority` (e.g., `"fallback"` or `"override"`) These flags are not documented in the spec and users cannot discover them 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 flags appear to be intentional and useful functionality, so the resolution is to update the spec to document them. **Steps to Reproduce**: Run `agents plan use --help` and observe `--execution-environment` and `--execution-env-priority` options that are absent from the spec. **Code Location**: `src/cleveragents/cli/commands/plan.py` lines 1463–1476 **Spec Location**: `docs/reference/plan_cli.md` — Options table for `agents plan use` ## Subtasks - [ ] Confirm the intended semantics of `--execution-environment` (valid values: `host`, `container`) and `--execution-env-priority` (valid values: `fallback`, `override`) with the spec owner - [ ] Update `docs/reference/plan_cli.md` to add both flags to the Options table for `agents plan use`, including accepted values and descriptions - [ ] Update `docs/specification.md` if the execution environment concept is described there and the flags are missing from the CLI surface section - [ ] Add Behave unit test scenarios covering both flags (valid values, invalid values, default behaviour when omitted) - [ ] Verify `agents plan use --help` output matches the updated spec exactly - [ ] Ensure all nox quality gates pass ## Definition of Done - [ ] `docs/reference/plan_cli.md` Options table for `agents plan use` includes `--execution-environment` and `--execution-env-priority` with full descriptions and accepted values - [ ] `docs/specification.md` is consistent with the updated CLI reference (no remaining gap) - [ ] Behave scenarios cover both new flags - [ ] `agents plan use --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:46:44 +00:00
Author
Owner

Issue triaged by project owner:

  • State: Verified
  • Priority: Medium (confirmed)
  • MoSCoW: Should Have — undocumented flags not in spec

Valid UAT finding verified during batch triage.


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

Issue triaged by project owner: - **State**: Verified - **Priority**: Medium (confirmed) - **MoSCoW**: Should Have — undocumented flags not in spec Valid UAT finding verified during batch triage. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: ca-project-owner
Sign in to join this conversation.
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Blocks
#397 Epic: Server & Autonomy Infrastructure
cleveragents/cleveragents-core
Reference
cleveragents/cleveragents-core#2906
No description provided.