cleveragents/cleveragents-core

Fork 3

UAT: Missing global `-v` repeatable verbosity flag on CLI entry point #3616

New issue

Open

opened 2026-04-05 20:37:48 +00:00 by freemo · 1 comment

freemo commented

2026-04-05 20:37:48 +00:00

Owner

Metadata

Branch: fix/uat-global-verbosity-flag
Commit Message: fix(cli): add repeatable -v verbosity flag to main_callback global options
Milestone: (none — backlog, see note below)
Parent Epic: #3370

Background

The specification (docs/specification.md, "Global Options" section) requires a repeatable -v flag for log verbosity on the CLI entry point:

-v: Increase log verbosity for a single invocation (repeatable). By default (no -v), only normal command output is shown on stdout; logging output is suppressed except on fatal errors. Each additional -v raises the verbosity one level: -v = ERROR, -vv = WARN, -vvv = INFO, -vvvv = DEBUG, -vvvvv = TRACE.

Expected behavior (from spec):

agents -vvv plan list       # INFO level logging
agents -vvvv actor show local/my-actor  # DEBUG level logging

Actual behavior:
The main_callback in src/cleveragents/cli/main.py (lines 292–316) has no -v verbosity flag. The only verbosity-related option is --verbose/-v on the build subcommand (line 517–518), which is a boolean flag scoped to that specific command — not the global repeatable verbosity flag required by the spec.

Code location: src/cleveragents/cli/main.py, main_callback function (lines 292–316)

Impact: Users cannot control log verbosity from the CLI. This prevents debugging issues with CLI commands and is a spec-required feature that is completely absent from the global CLI entry point.

Subtasks

Add a repeatable Annotated[int, typer.Option("-v", count=True)] (or equivalent) verbosity parameter to main_callback in src/cleveragents/cli/main.py
Map verbosity count to log levels: 0 → suppress (fatal only), 1 → ERROR, 2 → WARN, 3 → INFO, 4 → DEBUG, 5 → TRACE
Wire the verbosity level into the logging configuration (e.g., call logging.basicConfig or the project's log-setup utility) at the start of main_callback
Ensure the global -v flag does not conflict with the existing --verbose/-v boolean on the build subcommand (rename or scope appropriately)
Write Behave BDD unit test scenarios in features/ covering each verbosity level (0–5)
Write Robot Framework integration test in robot/ verifying that agents -vvv <cmd> produces INFO-level log output
Update CLI help text / docstring to document the repeatable -v flag
Ensure all nox stages pass (lint, typecheck, unit_tests, integration_tests, coverage_report)

Definition of Done

main_callback accepts a repeatable -v flag matching the spec's verbosity table
Verbosity levels 0–5 correctly map to suppress/ERROR/WARN/INFO/DEBUG/TRACE
Global -v does not conflict with any subcommand-level flags
Behave unit test scenarios written and passing for all verbosity levels
Robot Framework integration test written and passing
CLI --help output documents the -v flag
All nox stages pass
Coverage >= 97%

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.

Automated by CleverAgents Bot
Supervisor: Acting on behalf of: UAT Testing | Agent: ca-new-issue-creator

## Metadata - **Branch**: `fix/uat-global-verbosity-flag` - **Commit Message**: `fix(cli): add repeatable -v verbosity flag to main_callback global options` - **Milestone**: _(none — backlog, see note below)_ - **Parent Epic**: #3370 ## Background The specification (`docs/specification.md`, "Global Options" section) requires a repeatable `-v` flag for log verbosity on the CLI entry point: > `-v`: Increase log verbosity for a single invocation (repeatable). By default (no `-v`), only normal command output is shown on stdout; logging output is suppressed except on fatal errors. Each additional `-v` raises the verbosity one level: `-v` = ERROR, `-vv` = WARN, `-vvv` = INFO, `-vvvv` = DEBUG, `-vvvvv` = TRACE. **Expected behavior** (from spec): ``` agents -vvv plan list # INFO level logging agents -vvvv actor show local/my-actor # DEBUG level logging ``` **Actual behavior**: The `main_callback` in `src/cleveragents/cli/main.py` (lines 292–316) has **no** `-v` verbosity flag. The only verbosity-related option is `--verbose/-v` on the `build` subcommand (line 517–518), which is a boolean flag scoped to that specific command — not the global repeatable verbosity flag required by the spec. **Code location**: `src/cleveragents/cli/main.py`, `main_callback` function (lines 292–316) **Impact**: Users cannot control log verbosity from the CLI. This prevents debugging issues with CLI commands and is a spec-required feature that is completely absent from the global CLI entry point. ## Subtasks - [ ] Add a repeatable `Annotated[int, typer.Option("-v", count=True)]` (or equivalent) `verbosity` parameter to `main_callback` in `src/cleveragents/cli/main.py` - [ ] Map verbosity count to log levels: 0 → suppress (fatal only), 1 → ERROR, 2 → WARN, 3 → INFO, 4 → DEBUG, 5 → TRACE - [ ] Wire the verbosity level into the logging configuration (e.g., call `logging.basicConfig` or the project's log-setup utility) at the start of `main_callback` - [ ] Ensure the global `-v` flag does not conflict with the existing `--verbose/-v` boolean on the `build` subcommand (rename or scope appropriately) - [ ] Write Behave BDD unit test scenarios in `features/` covering each verbosity level (0–5) - [ ] Write Robot Framework integration test in `robot/` verifying that `agents -vvv <cmd>` produces INFO-level log output - [ ] Update CLI help text / docstring to document the repeatable `-v` flag - [ ] Ensure all nox stages pass (`lint`, `typecheck`, `unit_tests`, `integration_tests`, `coverage_report`) ## Definition of Done - [ ] `main_callback` accepts a repeatable `-v` flag matching the spec's verbosity table - [ ] Verbosity levels 0–5 correctly map to suppress/ERROR/WARN/INFO/DEBUG/TRACE - [ ] Global `-v` does not conflict with any subcommand-level flags - [ ] Behave unit test scenarios written and passing for all verbosity levels - [ ] Robot Framework integration test written and passing - [ ] CLI `--help` output documents the `-v` flag - [ ] All nox stages pass - [ ] Coverage >= 97% > **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. --- **Automated by CleverAgents Bot** Supervisor: Acting on behalf of: UAT Testing | Agent: ca-new-issue-creator

freemo added a new dependency

2026-04-05 20:38:02 +00:00

#3370 Epic: Automation Profile & Safety Profile CLI — Cost Budgets, Guard Enforcement, and Profile Management

freemo referenced this issue

2026-04-05 20:39:39 +00:00

[Automated] CleverAgents Build Session - 2026-04-05 #3572

freemo added this to the v3.7.0 milestone

2026-04-05 20:42:22 +00:00

freemo referenced this issue

2026-04-05 20:42:47 +00:00

[Automated] CleverAgents Build Session - 2026-04-05 #3572

freemo referenced this issue

2026-04-05 20:43:01 +00:00

[Automated] CleverAgents Build Session - 2026-04-05 #3572

freemo referenced this issue

2026-04-05 20:51:04 +00:00

[Automated] CleverAgents Build Session - 2026-04-05 #3377

freemo referenced this issue

2026-04-05 21:13:33 +00:00

[Automated] CleverAgents Build Session - 2026-04-05 #3377

freemo commented

2026-04-05 22:27:20 +00:00

Author

Owner

Duplicate UAT Finding — Additional Context

This issue was independently re-discovered during a separate UAT testing session of src/cleveragents/cli/main.py on 2026-04-05. The finding is identical to what is tracked here and in the older issue #2415.

Additional context from the new UAT session:

The verbosity level mapping specified in docs/specification.md is:

Flag	Level	Description
(none)	0	Default — only stdout output; logging suppressed except fatal errors
`-v`	1	ERROR — non-fatal, recoverable errors
`-vv`	2	WARN — warnings indicating degraded system
`-vvv`	3	INFO — routine informative messages
`-vvvv`	4	DEBUG — coarse debugging output
`-vvvvv`	5	TRACE — most granular logging level

The spec also specifies: "Increased verbosity writes to both the log file and stderr by default, keeping log output separate from normal program output on stdout. This flag does not persist — it only affects the current invocation."

Related issues also open:

#2415 — older tracking of the same bug (Priority/High, milestone v3.6.0)
#3644 — configure_structlog() raises ValueError for TRACE log level (the -vvvvv level is broken even if the flag were added)
#2863 — configure_structlog() rejects 'TRACE' log level

Note: Issue #3644 and #2863 must also be resolved as part of the full fix, since adding the -v flag without fixing configure_structlog() TRACE support would leave -vvvvv broken.

Duplicate note: A new issue creation was requested by UAT tester ca-uat-tester (Supervisor: UAT Testing). Rather than creating a third duplicate, this comment has been added to the most recent existing tracking issue. No new issue was created.

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

## Duplicate UAT Finding — Additional Context This issue was independently re-discovered during a separate UAT testing session of `src/cleveragents/cli/main.py` on 2026-04-05. The finding is identical to what is tracked here and in the older issue #2415. **Additional context from the new UAT session:** The verbosity level mapping specified in `docs/specification.md` is: | Flag | Level | Description | |------|-------|-------------| | _(none)_ | 0 | Default — only stdout output; logging suppressed except fatal errors | | `-v` | 1 | ERROR — non-fatal, recoverable errors | | `-vv` | 2 | WARN — warnings indicating degraded system | | `-vvv` | 3 | INFO — routine informative messages | | `-vvvv` | 4 | DEBUG — coarse debugging output | | `-vvvvv` | 5 | TRACE — most granular logging level | The spec also specifies: *"Increased verbosity writes to both the log file and stderr by default, keeping log output separate from normal program output on stdout. This flag does not persist — it only affects the current invocation."* **Related issues also open:** - #2415 — older tracking of the same bug (Priority/High, milestone v3.6.0) - #3644 — `configure_structlog()` raises `ValueError` for `TRACE` log level (the `-vvvvv` level is broken even if the flag were added) - #2863 — `configure_structlog()` rejects `'TRACE'` log level **Note:** Issue #3644 and #2863 must also be resolved as part of the full fix, since adding the `-v` flag without fixing `configure_structlog()` TRACE support would leave `-vvvvv` broken. > **Duplicate note:** A new issue creation was requested by UAT tester `ca-uat-tester` (Supervisor: UAT Testing). Rather than creating a third duplicate, this comment has been added to the most recent existing tracking issue. No new issue was created. --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-new-issue-creator

freemo referenced this issue

2026-04-05 22:35:43 +00:00

[Automated] CleverAgents Build Session - 2026-04-05 (Resumed) #3654