cleveragents/cleveragents-core

Fork 3

UAT: `agents plan list` command synopsis in spec missing `--namespace` flag — synopsis and examples are inconsistent #2903

New issue

Open

opened 2026-04-05 02:46:21 +00:00 by freemo · 3 comments

freemo commented

2026-04-05 02:46:21 +00:00

Owner

Metadata

Branch: fix/m5-plan-list-synopsis-namespace-flag
Commit Message: fix(docs): add missing --namespace flag to agents plan list synopsis
Milestone: v3.5.0
Parent Epic: #397

Background and Context

The spec command synopsis (docs/specification.md lines 12111–12112) shows:

agents plan list [--phase <PHASE>] [--state <STATE>] [--project <PROJECT>]
                 [--action <ACTION>] [<REGEX>]

However, the spec examples (lines 41938, 41971) use agents plan list --namespace myteam. The implementation correctly supports --namespace/-n but the synopsis omits it entirely. This is a spec documentation inconsistency — the implementation is correct per the examples, but the synopsis is misleading to readers and future contributors.

Current Behavior

The synopsis in docs/specification.md (lines 12111–12112) is missing [--namespace/-n <NS>], creating an inconsistency with the usage examples later in the same document.

Expected Behavior

The spec synopsis should include [--namespace/-n <NS>] to match the examples and the actual implementation:

agents plan list [--phase <PHASE>] [--state <STATE>] [--project <PROJECT>]
                 [--action <ACTION>] [--namespace/-n <NS>] [<REGEX>]

No code changes are required — this is a documentation-only fix to docs/specification.md.

Acceptance Criteria

docs/specification.md synopsis for agents plan list (lines ~12111–12112) includes [--namespace/-n <NS>]
The updated synopsis is consistent with the usage examples at lines ~41938 and ~41971
No implementation changes are made (the CLI already supports --namespace correctly)
All nox stages pass (no regressions)

Subtasks

Locate the agents plan list synopsis in docs/specification.md (lines ~12111–12112)
Add [--namespace/-n <NS>] to the synopsis line
Verify consistency with all agents plan list --namespace examples in the spec
Run nox to confirm no regressions

Definition of Done

All subtasks above are checked
docs/specification.md synopsis for agents plan list includes --namespace/-n <NS>
Synopsis is consistent with all usage examples in the spec
Commit pushed to fix/m5-plan-list-synopsis-namespace-flag with message fix(docs): add missing --namespace flag to agents plan list synopsis
PR merged and issue closed
All nox stages pass
Coverage >= 97%

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

## Metadata - **Branch**: `fix/m5-plan-list-synopsis-namespace-flag` - **Commit Message**: `fix(docs): add missing --namespace flag to agents plan list synopsis` - **Milestone**: v3.5.0 - **Parent Epic**: #397 ## Background and Context The spec command synopsis (`docs/specification.md` lines 12111–12112) shows: ``` agents plan list [--phase <PHASE>] [--state <STATE>] [--project <PROJECT>] [--action <ACTION>] [<REGEX>] ``` However, the spec examples (lines 41938, 41971) use `agents plan list --namespace myteam`. The implementation correctly supports `--namespace/-n` but the synopsis omits it entirely. This is a spec documentation inconsistency — the implementation is correct per the examples, but the synopsis is misleading to readers and future contributors. ## Current Behavior The synopsis in `docs/specification.md` (lines 12111–12112) is missing `[--namespace/-n <NS>]`, creating an inconsistency with the usage examples later in the same document. ## Expected Behavior The spec synopsis should include `[--namespace/-n <NS>]` to match the examples and the actual implementation: ``` agents plan list [--phase <PHASE>] [--state <STATE>] [--project <PROJECT>] [--action <ACTION>] [--namespace/-n <NS>] [<REGEX>] ``` No code changes are required — this is a documentation-only fix to `docs/specification.md`. ## Acceptance Criteria - [ ] `docs/specification.md` synopsis for `agents plan list` (lines ~12111–12112) includes `[--namespace/-n <NS>]` - [ ] The updated synopsis is consistent with the usage examples at lines ~41938 and ~41971 - [ ] No implementation changes are made (the CLI already supports `--namespace` correctly) - [ ] All nox stages pass (no regressions) ## Subtasks - [ ] Locate the `agents plan list` synopsis in `docs/specification.md` (lines ~12111–12112) - [ ] Add `[--namespace/-n <NS>]` to the synopsis line - [ ] Verify consistency with all `agents plan list --namespace` examples in the spec - [ ] Run `nox` to confirm no regressions ## Definition of Done - [ ] All subtasks above are checked - [ ] `docs/specification.md` synopsis for `agents plan list` includes `--namespace/-n <NS>` - [ ] Synopsis is consistent with all usage examples in the spec - [ ] Commit pushed to `fix/m5-plan-list-synopsis-namespace-flag` with message `fix(docs): add missing --namespace flag to agents plan list synopsis` - [ ] PR merged and issue closed - [ ] All nox stages pass - [ ] Coverage >= 97% --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-new-issue-creator

freemo added this to the v3.5.0 milestone

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

freemo added a new dependency

2026-04-05 02:47:01 +00:00

#397 Epic: Server & Autonomy Infrastructure

freemo commented

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

Author

Owner

Issue triaged by project owner:

State: Verified
Priority: Low (confirmed)
MoSCoW: Could Have — spec documentation gap, not a code bug

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**: Low (confirmed) - **MoSCoW**: Could Have — spec documentation gap, not a code bug Valid UAT finding verified during batch triage. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: ca-project-owner

freemo added the

MoSCoW

Could have

label

2026-04-05 02:54:03 +00:00

freemo referenced this issue

2026-04-05 02:54:19 +00:00

[CA-AUTO] Project Owner — project-owner-1 — Session Tracker #2793

freemo commented

2026-04-06 18:45:50 +00:00

Author

Owner

Milestone Triage Decision: Moved to Backlog

This CLI documentation issue has been moved out of v3.5.0 during aggressive milestone triage. While important for spec compliance, it does not block core autonomy hardening functionality.

Reasoning:

v3.5.0 focus: Essential autonomy hardening (guard enforcement, A2A facade, plan lifecycle)
This issue: CLI help text (plan list synopsis) - documentation consistency
Impact: UX consistency, not functional capability

Will be addressed in a future milestone focused on CLI polish and spec compliance.

**Milestone Triage Decision: Moved to Backlog** This CLI documentation issue has been moved out of v3.5.0 during aggressive milestone triage. While important for spec compliance, it does not block core autonomy hardening functionality. **Reasoning:** - v3.5.0 focus: Essential autonomy hardening (guard enforcement, A2A facade, plan lifecycle) - This issue: CLI help text (`plan list` synopsis) - documentation consistency - Impact: UX consistency, not functional capability Will be addressed in a future milestone focused on CLI polish and spec compliance.

freemo commented

2026-04-06 22:45:17 +00:00

Author

Owner

This issue has been moved to the backlog as part of an aggressive grooming of the v3.5.0 milestone. It has been deemed non-critical for the minimal viability of the milestone and will be addressed in a future release.