UAT: `agents actor update` is an undocumented command — spec only defines `agents actor add --update` for updating actors #3602

New issue

Open

opened 2026-04-05 20:18:18 +00:00 by freemo · 0 comments

freemo commented

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

Owner

Metadata

Branch: fix/backlog-actor-update-undocumented-command
Commit Message: fix(cli): remove or document undocumented agents actor update command
Milestone: Backlog
Parent Epic: #392

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

Background and Context

The specification defines the following actor CLI commands:

agents actor add --config|-c <FILE> [--update]
agents actor remove <NAME>
agents actor list
agents actor show <NAME>
agents actor context ...

The --update flag on agents actor add is the spec-defined mechanism for updating an existing actor.

Current Behavior

The codebase implements an additional agents actor update <NAME> command (in src/cleveragents/cli/commands/actor.py, the update() function at line 600) that is not defined in the specification. This command:

Takes a <NAME> positional argument
Accepts --config, --unsafe, --safe, --set-default, --option, --format flags
Updates an existing actor by name

This creates two parallel update paths:

agents actor add --config <FILE> --update (spec-defined)
agents actor update <NAME> [--config <FILE>] (undocumented, not in spec)

The undocumented actor update command has different semantics — it can update an actor without providing a new config file (using the existing config), and it supports a --safe flag to mark an actor as safe. These behaviours are not documented in the spec.

Expected Behavior

Per the specification, actor updates should be performed exclusively via agents actor add --config <FILE> --update. The separate agents actor update command should either:

Be removed and its functionality merged into agents actor add --update, OR
Be documented in the specification if it provides genuinely useful functionality not covered by actor add --update

Code Location

src/cleveragents/cli/commands/actor.py — update() function (~line 600–720): the undocumented command

Subtasks

Audit agents actor update vs agents actor add --update to determine whether actor update provides functionality not covered by the spec-defined path (e.g. --safe, --set-default, config-less re-validation)
Decision: remove actor update and fold unique functionality into actor add --update, OR update the specification to formally document actor update
If removing: delete the update() function from src/cleveragents/cli/commands/actor.py and update CLI registration
If removing: migrate any unique flags (--safe, --set-default, --option) to agents actor add --update where appropriate
If documenting in spec: add full command signature, flag descriptions, and output format to docs/specification.md
Update or remove all tests that exercise agents actor update to use the correct path
Verify coverage >= 97% via nox -s coverage_report
Run nox (all default sessions), fix any errors

Definition of Done

This issue is complete when:

There is exactly one spec-defined mechanism for updating an actor — either agents actor add --config <FILE> --update exclusively, or both paths are formally documented in the specification
The agents actor update command either no longer exists in the codebase or is fully documented in docs/specification.md with its complete argument set and output format
If removed, all tests previously relying on actor update have been updated to use actor add --update
A Git commit is created where the first line of the commit message matches the Commit Message in Metadata exactly, followed by a blank line, then additional lines providing relevant details about the implementation
The commit is pushed to the remote on the branch matching the Branch in Metadata exactly
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-new-issue-creator

## Metadata - **Branch**: `fix/backlog-actor-update-undocumented-command` - **Commit Message**: `fix(cli): remove or document undocumented agents actor update command` - **Milestone**: Backlog - **Parent Epic**: #392 > **Backlog note:** This issue was discovered during autonomous operation > on milestone v3.2.0. It does not block milestone completion and has been > placed in the backlog for human review and future milestone assignment. ## Background and Context The specification defines the following actor CLI commands: ``` agents actor add --config|-c <FILE> [--update] agents actor remove <NAME> agents actor list agents actor show <NAME> agents actor context ... ``` The `--update` flag on `agents actor add` is the spec-defined mechanism for updating an existing actor. ## Current Behavior The codebase implements an additional `agents actor update <NAME>` command (in `src/cleveragents/cli/commands/actor.py`, the `update()` function at line 600) that is **not defined in the specification**. This command: - Takes a `<NAME>` positional argument - Accepts `--config`, `--unsafe`, `--safe`, `--set-default`, `--option`, `--format` flags - Updates an existing actor by name This creates two parallel update paths: 1. `agents actor add --config <FILE> --update` (spec-defined) 2. `agents actor update <NAME> [--config <FILE>]` (undocumented, not in spec) The undocumented `actor update` command has different semantics — it can update an actor without providing a new config file (using the existing config), and it supports a `--safe` flag to mark an actor as safe. These behaviours are not documented in the spec. ## Expected Behavior Per the specification, actor updates should be performed exclusively via `agents actor add --config <FILE> --update`. The separate `agents actor update` command should either: 1. Be removed and its functionality merged into `agents actor add --update`, OR 2. Be documented in the specification if it provides genuinely useful functionality not covered by `actor add --update` ## Code Location - `src/cleveragents/cli/commands/actor.py` — `update()` function (~line 600–720): the undocumented command ## Subtasks - [ ] Audit `agents actor update` vs `agents actor add --update` to determine whether `actor update` provides functionality not covered by the spec-defined path (e.g. `--safe`, `--set-default`, config-less re-validation) - [ ] Decision: remove `actor update` and fold unique functionality into `actor add --update`, OR update the specification to formally document `actor update` - [ ] If removing: delete the `update()` function from `src/cleveragents/cli/commands/actor.py` and update CLI registration - [ ] If removing: migrate any unique flags (`--safe`, `--set-default`, `--option`) to `agents actor add --update` where appropriate - [ ] If documenting in spec: add full command signature, flag descriptions, and output format to `docs/specification.md` - [ ] Update or remove all tests that exercise `agents actor update` to use the correct path - [ ] Verify coverage >= 97% via `nox -s coverage_report` - [ ] Run `nox` (all default sessions), fix any errors ## Definition of Done This issue is complete when: - [ ] There is exactly one spec-defined mechanism for updating an actor — either `agents actor add --config <FILE> --update` exclusively, or both paths are formally documented in the specification - [ ] The `agents actor update` command either no longer exists in the codebase or is fully documented in `docs/specification.md` with its complete argument set and output format - [ ] If removed, all tests previously relying on `actor update` have been updated to use `actor add --update` - [ ] A Git commit is created where the **first line** of the commit message matches the Commit Message in Metadata exactly, followed by a blank line, then additional lines providing relevant details about the implementation - [ ] The commit is pushed to the remote on the branch matching the **Branch** in Metadata exactly - [ ] 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-new-issue-creator

freemo added a new dependency

2026-04-05 20:18:23 +00:00

#392 Epic: Actor YAML & Compiler

freemo added this to the v3.7.0 milestone

2026-04-05 20:23:30 +00:00

freemo referenced this issue

2026-04-05 20:29:17 +00:00

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

freemo referenced this issue

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

UAT: agents actor update is an undocumented separate command; spec only defines agents actor add --update #3617

freemo referenced this issue