cleveragents/cleveragents-core

Fork 3

UAT: `agents actor add --config` is optional in CLI but spec requires it as a mandatory positional-style option #2580

New issue

Open

opened 2026-04-03 18:59:08 +00:00 by freemo · 1 comment

freemo commented

2026-04-03 18:59:08 +00:00

Owner

Metadata

Branch: fix/cli-actor-add-config-required
Commit Message: fix(cli): make actor add --config a required option per spec
Milestone: v3.7.0
Parent Epic: #868

Background and Context

The project specification (docs/specification.md, agents actor add section) defines the command signature as:

agents actor add --config|-c <FILE> [--update]

The --config|-c <FILE> argument appears without brackets, which in CLI convention means it is a required option. However, the current implementation in src/cleveragents/cli/commands/actor.py declares --config as optional with a None default, then validates it at runtime with a manual check.

This is a spec-compliance bug: the CLI's help text misrepresents --config as optional, and the error path uses a non-standard typer.BadParameter message rather than Typer's built-in required-option handling.

Current Behavior

In src/cleveragents/cli/commands/actor.py, the add() function declares:

config: Annotated[
    Path | None,
    typer.Option("--config", "-c", help="Path to JSON/YAML actor config"),
] = None,

The code then validates it at runtime:

if config_blob is None:
    raise typer.BadParameter("Config file is required for actor add")

This causes two problems:

The CLI help text shows --config as optional (displayed as [--config]), misleading users.
Running agents actor add without --config raises typer.BadParameter with a custom message instead of Typer's standard "Missing option '--config' / '-c'." error.

Steps to reproduce:

agents actor add
# Expected: "Error: Missing option '--config' / '-c'."
# Actual:   "Error: Invalid value for '--config' / '-c': Config file is required for actor add"

Expected Behavior

Per the specification:

--config must be declared as a required Typer option (no None default, no Optional type).
Running agents actor add without --config must produce Typer's standard "Missing option '--config' / '-c'." error.
The --help output must clearly indicate that --config is required (no [--config] bracket notation).
The manual if config_blob is None guard and typer.BadParameter call must be removed.

Acceptance Criteria

--config / -c is declared as a required typer.Option in the add() function (type Path, no = None default).
Running agents actor add without --config exits with Typer's standard "Missing option" error message.
agents actor add --help shows --config as a required option (not wrapped in [...]).
The manual if config_blob is None: raise typer.BadParameter(...) guard is removed.
All existing BDD scenarios for agents actor add continue to pass.
New BDD scenario added: agents actor add with no --config produces the standard Typer missing-option error.

Supporting Information

Code location: src/cleveragents/cli/commands/actor.py, add() function
Spec reference: docs/specification.md — agents actor add command signature
Discovered during: UAT testing of the CleverAgents CLI interface
Related Epic: #868 (Epic: TUI Interface, Modals and Persona System)

Subtasks

Update add() in src/cleveragents/cli/commands/actor.py: change config parameter type from Path | None to Path and remove the = None default
Remove the if config_blob is None: raise typer.BadParameter(...) runtime guard
Tests (Behave): Add scenario — agents actor add with no --config flag produces "Missing option '--config' / '-c'." error
Tests (Behave): Verify existing agents actor add --config <file> scenarios still pass
Tests (Robot): Add integration smoke test confirming --config is required at the CLI level
Verify agents actor add --help output no longer shows [--config] bracket notation
Verify coverage >= 97% via nox -s coverage_report
Run nox (all default sessions), fix any errors

Definition of Done

This issue is complete when:

All subtasks above are completed and checked off.
A Git commit is created where the first line of the commit message matches the Commit Message in Metadata exactly (fix(cli): make actor add --config a required option per spec), followed by a blank line, then additional lines providing relevant implementation details.
The commit is pushed to the remote on the branch matching the Branch in Metadata exactly (fix/cli-actor-add-config-required).
The commit is submitted as a pull request to master, reviewed, and merged before this issue is marked done.
All nox stages pass.
Coverage >= 97%.

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

## Metadata - **Branch**: `fix/cli-actor-add-config-required` - **Commit Message**: `fix(cli): make actor add --config a required option per spec` - **Milestone**: v3.7.0 - **Parent Epic**: #868 ## Background and Context The project specification (`docs/specification.md`, `agents actor add` section) defines the command signature as: ``` agents actor add --config|-c <FILE> [--update] ``` The `--config|-c <FILE>` argument appears **without brackets**, which in CLI convention means it is a **required** option. However, the current implementation in `src/cleveragents/cli/commands/actor.py` declares `--config` as optional with a `None` default, then validates it at runtime with a manual check. This is a spec-compliance bug: the CLI's help text misrepresents `--config` as optional, and the error path uses a non-standard `typer.BadParameter` message rather than Typer's built-in required-option handling. ## Current Behavior In `src/cleveragents/cli/commands/actor.py`, the `add()` function declares: ```python config: Annotated[ Path | None, typer.Option("--config", "-c", help="Path to JSON/YAML actor config"), ] = None, ``` The code then validates it at runtime: ```python if config_blob is None: raise typer.BadParameter("Config file is required for actor add") ``` This causes two problems: 1. The CLI help text shows `--config` as **optional** (displayed as `[--config]`), misleading users. 2. Running `agents actor add` without `--config` raises `typer.BadParameter` with a custom message instead of Typer's standard `"Missing option '--config' / '-c'."` error. **Steps to reproduce:** ```bash agents actor add # Expected: "Error: Missing option '--config' / '-c'." # Actual: "Error: Invalid value for '--config' / '-c': Config file is required for actor add" ``` ## Expected Behavior Per the specification: - `--config` must be declared as a **required** Typer option (no `None` default, no `Optional` type). - Running `agents actor add` without `--config` must produce Typer's standard `"Missing option '--config' / '-c'."` error. - The `--help` output must clearly indicate that `--config` is required (no `[--config]` bracket notation). - The manual `if config_blob is None` guard and `typer.BadParameter` call must be removed. ## Acceptance Criteria - [ ] `--config` / `-c` is declared as a required `typer.Option` in the `add()` function (type `Path`, no `= None` default). - [ ] Running `agents actor add` without `--config` exits with Typer's standard "Missing option" error message. - [ ] `agents actor add --help` shows `--config` as a required option (not wrapped in `[...]`). - [ ] The manual `if config_blob is None: raise typer.BadParameter(...)` guard is removed. - [ ] All existing BDD scenarios for `agents actor add` continue to pass. - [ ] New BDD scenario added: `agents actor add` with no `--config` produces the standard Typer missing-option error. ## Supporting Information - **Code location**: `src/cleveragents/cli/commands/actor.py`, `add()` function - **Spec reference**: `docs/specification.md` — `agents actor add` command signature - **Discovered during**: UAT testing of the CleverAgents CLI interface - **Related Epic**: #868 (Epic: TUI Interface, Modals and Persona System) ## Subtasks - [ ] Update `add()` in `src/cleveragents/cli/commands/actor.py`: change `config` parameter type from `Path | None` to `Path` and remove the `= None` default - [ ] Remove the `if config_blob is None: raise typer.BadParameter(...)` runtime guard - [ ] Tests (Behave): Add scenario — `agents actor add` with no `--config` flag produces `"Missing option '--config' / '-c'."` error - [ ] Tests (Behave): Verify existing `agents actor add --config <file>` scenarios still pass - [ ] Tests (Robot): Add integration smoke test confirming `--config` is required at the CLI level - [ ] Verify `agents actor add --help` output no longer shows `[--config]` bracket notation - [ ] Verify coverage >= 97% via `nox -s coverage_report` - [ ] Run `nox` (all default sessions), fix any errors ## Definition of Done This issue is complete when: - All subtasks above are completed and checked off. - A Git commit is created where the **first line** of the commit message matches the Commit Message in Metadata exactly (`fix(cli): make actor add --config a required option per spec`), followed by a blank line, then additional lines providing relevant implementation details. - The commit is pushed to the remote on the branch matching the **Branch** in Metadata exactly (`fix/cli-actor-add-config-required`). - The commit is submitted as a **pull request** to `master`, reviewed, and **merged** before this issue is marked done. - 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-03 18:59:23 +00:00

freemo referenced this issue

2026-04-03 19:00:56 +00:00

Task: Autonomous build progress report — v3.7.0 Production Push — 2026-04-03 #2436

freemo added a new dependency

2026-04-03 19:01:49 +00:00

#868 Epic: TUI Interface, Modals and Persona System

freemo referenced this issue

2026-04-03 19:03:52 +00:00

[UAT-SUPERVISOR] Progress Report — Cycle 1591 — v3.7.0 #2593

freemo added a new dependency

2026-04-03 19:08:55 +00:00

#2597 fix(ci): restore all CI quality gates to passing on master — no suppression, no bypasses

freemo referenced this issue

2026-04-03 19:14:03 +00:00

[UAT-SUPERVISOR] Progress Report — Cycle 1601 — v3.7.0 #2603

freemo referenced this issue

2026-04-03 19:24:12 +00:00

[UAT-SUPERVISOR] Progress Report — Cycle 1611 — v3.7.0 #2605

freemo commented

2026-04-03 19:34:05 +00:00

Author

Owner

Issue triaged by project owner:

State: Verified
MoSCoW: Should Have

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

Issue triaged by project owner: - **State**: Verified - **MoSCoW**: Should Have --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: ca-project-owner

freemo referenced this issue

2026-04-03 19:34:18 +00:00

[UAT-SUPERVISOR] Progress Report — Cycle 1621 — v3.7.0 #2607

freemo referenced this issue

2026-04-03 19:44:25 +00:00

[UAT-SUPERVISOR] Progress Report — Cycle 1631 — v3.7.0 #2613

freemo referenced this issue

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

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

freemo removed a dependency

2026-04-14 22:18:54 +00:00

#2597 fix(ci): restore all CI quality gates to passing on master — no suppression, no bypasses