UAT: Multiple implemented CLI command groups are absent from docs/specification.md CLI synopsis #3948

Open
opened 2026-04-06 07:42:49 +00:00 by freemo · 0 comments
Owner

Metadata

  • Branch: docs/spec-complete-cli-synopsis
  • Commit Message: docs(spec): document all implemented CLI command groups in synopsis
  • Milestone: Backlog
  • Parent Epic: #3374

Summary

The docs/specification.md CLI Command Synopsis section (lines 207–367) is the authoritative list of all supported CLI commands. However, the implementation registers several additional command groups that are not listed in the spec synopsis. This creates a discrepancy between the documented and actual CLI surface.

Per CONTRIBUTING.md: "Code should only be written to reflect what the specification describes — when there is a discrepancy between the current codebase and the specification, always assume the specification is correct and align the code accordingly."

What Was Tested

Compared the CLI command synopsis in docs/specification.md (lines 207–367) against all registered CLI commands in src/cleveragents/cli/main.py (lines 74–232).

Expected Behavior

The spec's CLI synopsis should be complete and accurate. All implemented CLI command groups must appear in the spec, or undocumented commands must be removed until the spec describes them.

Actual Behavior

The following command groups are registered in src/cleveragents/cli/main.py but are NOT listed in the spec's CLI synopsis:

  1. agents audit — View and manage the audit log (line 176–180 in main.py)
  2. agents cleanup — Garbage collection and cleanup for stale resources (line 171–175)
  3. agents db — Database migration management via Alembic (line 151–155)
  4. agents auto-debug — Auto-debug operations (line 150)
  5. agents repo — Repository indexing management (line 226–230)
  6. agents repl — Interactive REPL session (line 211–215)
  7. agents server — Server connection management (line 221–225) [also tracked in #3913]
  8. agents tui — Launch the Textual TUI (line 216–220)

Additionally, agents project clean is implemented in src/cleveragents/cli/commands/project.py (line 519) but is not in the spec's project command synopsis.

Code Locations

  • src/cleveragents/cli/main.py lines 74–232 (all registered commands)
  • docs/specification.md lines 207–367 (CLI synopsis — missing the above commands)

Steps to Reproduce

  1. Read docs/specification.md lines 207–367 (CLI synopsis)
  2. Read src/cleveragents/cli/main.py lines 74–232 (registered commands)
  3. Compare — the above 8 command groups are in the code but not in the spec

Impact

The spec is the source of truth. Either:

  1. The spec needs to be updated to document these command groups (preferred if they are intentional), or
  2. The undocumented commands need to be removed until the spec describes them

Note: Some of these commands (like agents db, agents auto-debug) may be internal/developer tools that intentionally don't appear in the user-facing spec. The spec should clarify this distinction.

Backlog note: This issue was discovered during autonomous operation
on milestone v3.6.0. It does not block milestone completion and has been
placed in the backlog for human review and future milestone assignment.

Subtasks

  • Audit all command groups registered in src/cleveragents/cli/main.py against docs/specification.md CLI synopsis
  • Determine for each undocumented command: intentional user-facing feature, internal/developer tool, or unintentional addition
  • For user-facing commands: add full synopsis entries to docs/specification.md (lines 207–367) covering usage, arguments, flags, and examples
  • For internal/developer tools: add a clearly marked "Internal Commands" section to the spec (or a separate developer reference doc) documenting them
  • For any commands that are neither spec-aligned nor intentional: remove them from src/cleveragents/cli/main.py
  • Add agents project clean to the spec's project command synopsis (or remove it from project.py line 519)
  • Verify agents server alignment with #3913 to avoid duplicate work
  • Update integration tests in robot/ to cover any newly documented commands
  • Ensure all nox stages pass after changes

Definition of Done

  • Every command group registered in src/cleveragents/cli/main.py is either documented in docs/specification.md or explicitly removed from the codebase
  • docs/specification.md CLI synopsis is complete and accurate with no undocumented commands
  • agents project clean is either documented in the spec or removed from project.py
  • Internal/developer-only commands (if any) are documented in a clearly marked section
  • All nox stages pass
  • Coverage >= 97%

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

## Metadata - **Branch**: `docs/spec-complete-cli-synopsis` - **Commit Message**: `docs(spec): document all implemented CLI command groups in synopsis` - **Milestone**: Backlog - **Parent Epic**: #3374 ## Summary The `docs/specification.md` CLI Command Synopsis section (lines 207–367) is the authoritative list of all supported CLI commands. However, the implementation registers several additional command groups that are not listed in the spec synopsis. This creates a discrepancy between the documented and actual CLI surface. Per CONTRIBUTING.md: *"Code should only be written to reflect what the specification describes — when there is a discrepancy between the current codebase and the specification, always assume the specification is correct and align the code accordingly."* ## What Was Tested Compared the CLI command synopsis in `docs/specification.md` (lines 207–367) against all registered CLI commands in `src/cleveragents/cli/main.py` (lines 74–232). ## Expected Behavior The spec's CLI synopsis should be complete and accurate. All implemented CLI command groups must appear in the spec, or undocumented commands must be removed until the spec describes them. ## Actual Behavior The following command groups are registered in `src/cleveragents/cli/main.py` but are **NOT** listed in the spec's CLI synopsis: 1. **`agents audit`** — View and manage the audit log (line 176–180 in main.py) 2. **`agents cleanup`** — Garbage collection and cleanup for stale resources (line 171–175) 3. **`agents db`** — Database migration management via Alembic (line 151–155) 4. **`agents auto-debug`** — Auto-debug operations (line 150) 5. **`agents repo`** — Repository indexing management (line 226–230) 6. **`agents repl`** — Interactive REPL session (line 211–215) 7. **`agents server`** — Server connection management (line 221–225) [also tracked in #3913] 8. **`agents tui`** — Launch the Textual TUI (line 216–220) Additionally, `agents project clean` is implemented in `src/cleveragents/cli/commands/project.py` (line 519) but is not in the spec's project command synopsis. ## Code Locations - `src/cleveragents/cli/main.py` lines 74–232 (all registered commands) - `docs/specification.md` lines 207–367 (CLI synopsis — missing the above commands) ## Steps to Reproduce 1. Read `docs/specification.md` lines 207–367 (CLI synopsis) 2. Read `src/cleveragents/cli/main.py` lines 74–232 (registered commands) 3. Compare — the above 8 command groups are in the code but not in the spec ## Impact The spec is the source of truth. Either: 1. The spec needs to be updated to document these command groups (preferred if they are intentional), or 2. The undocumented commands need to be removed until the spec describes them Note: Some of these commands (like `agents db`, `agents auto-debug`) may be internal/developer tools that intentionally don't appear in the user-facing spec. The spec should clarify this distinction. > **Backlog note:** This issue was discovered during autonomous operation > on milestone v3.6.0. It does not block milestone completion and has been > placed in the backlog for human review and future milestone assignment. ## Subtasks - [ ] Audit all command groups registered in `src/cleveragents/cli/main.py` against `docs/specification.md` CLI synopsis - [ ] Determine for each undocumented command: intentional user-facing feature, internal/developer tool, or unintentional addition - [ ] For user-facing commands: add full synopsis entries to `docs/specification.md` (lines 207–367) covering usage, arguments, flags, and examples - [ ] For internal/developer tools: add a clearly marked "Internal Commands" section to the spec (or a separate developer reference doc) documenting them - [ ] For any commands that are neither spec-aligned nor intentional: remove them from `src/cleveragents/cli/main.py` - [ ] Add `agents project clean` to the spec's project command synopsis (or remove it from `project.py` line 519) - [ ] Verify `agents server` alignment with #3913 to avoid duplicate work - [ ] Update integration tests in `robot/` to cover any newly documented commands - [ ] Ensure all nox stages pass after changes ## Definition of Done - [ ] Every command group registered in `src/cleveragents/cli/main.py` is either documented in `docs/specification.md` or explicitly removed from the codebase - [ ] `docs/specification.md` CLI synopsis is complete and accurate with no undocumented commands - [ ] `agents project clean` is either documented in the spec or removed from `project.py` - [ ] Internal/developer-only commands (if any) are documented in a clearly marked section - [ ] All nox stages pass - [ ] Coverage >= 97% --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-uat-tester
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.

Reference
cleveragents/cleveragents-core#3948
No description provided.