fix(actor): Fix Actor CLI compliance — actor add positional arg, actor remove --format flag, ActorLoader tool validation (fixes #5425, #5457, #5480) #8995

Open
opened 2026-04-14 04:36:00 +00:00 by HAL9000 · 1 comment
Owner

Background and Context

Three CLI and loader compliance issues affect the actor system under Epic #5502:

  1. agents actor add requires positional NAME argument (UAT #5425): The spec defines agents actor add --config <FILE> with no positional NAME — the name comes from the YAML file. The current implementation requires a positional NAME argument, breaking spec compliance.

  2. agents actor remove missing --format flag (UAT #5457): All other actor commands support --format for JSON/YAML/plain output, but remove does not. This breaks machine-readable output for automation pipelines.

  3. ActorLoader._resolve_tools() only warns instead of raising (UAT #5480): Unresolved tool references in actor configs are silently logged as warnings instead of raising a ValidationError, violating the fail-fast principle and allowing broken actors to be loaded.

Parent Epic: #5502 (EPIC: Actor Execution & Configuration — GRAPH Actor, Config Schema & CLI Compliance)

Acceptance Criteria

  • agents actor add --config ./actors/reviewer.yaml works without a positional NAME argument
  • Actor name is read from the YAML file's name field (not from CLI argument)
  • agents actor remove accepts --format/-f option with json, yaml, plain, rich values
  • agents actor remove --format json produces spec-compliant JSON envelope with actor_removed, impact, cleanup sections
  • ActorLoader._resolve_tools() raises ValidationError for unresolved tool references (not just warning)
  • All nox stages pass with coverage >= 97%

Subtasks

  • Remove positional NAME argument from agents actor add command signature
  • Update add command to read actor name from the loaded YAML config's name field
  • Update features/actor_add_name_positional.feature — remove @skip tags from spec-compliant scenarios
  • Add --format/-f option to agents actor remove command
  • Implement JSON/YAML/plain output for remove using OutputSession with spec envelope
  • Change ActorLoader._resolve_tools() to raise ValidationError instead of logging warning
  • Update features/actor_loading.feature — update "unresolvable tool reference" scenario to expect error
  • Write unit tests for updated add command (no positional arg)
  • Write unit tests for remove --format variants
  • Write unit tests for _resolve_tools() raising on unresolved references
  • Run nox (all default sessions), fix any errors

Definition of Done

  • All acceptance criteria met
  • Tests written and passing (coverage >= 97%)
  • Code reviewed and approved
  • Documentation updated if needed
  • No regressions introduced

Metadata

  • Commit message: fix(actor): fix actor add CLI signature, add remove --format, raise on unresolved tools
  • Branch name: fix/v350/actor-cli-compliance

Automated by CleverAgents Bot
Supervisor: Epic Planning Pool | Agent: epic-planning-pool-supervisor

## Background and Context Three CLI and loader compliance issues affect the actor system under Epic #5502: 1. **`agents actor add` requires positional NAME argument** (UAT #5425): The spec defines `agents actor add --config <FILE>` with no positional NAME — the name comes from the YAML file. The current implementation requires a positional `NAME` argument, breaking spec compliance. 2. **`agents actor remove` missing `--format` flag** (UAT #5457): All other actor commands support `--format` for JSON/YAML/plain output, but `remove` does not. This breaks machine-readable output for automation pipelines. 3. **`ActorLoader._resolve_tools()` only warns instead of raising** (UAT #5480): Unresolved tool references in actor configs are silently logged as warnings instead of raising a `ValidationError`, violating the fail-fast principle and allowing broken actors to be loaded. Parent Epic: #5502 (EPIC: Actor Execution & Configuration — GRAPH Actor, Config Schema & CLI Compliance) ## Acceptance Criteria - [ ] `agents actor add --config ./actors/reviewer.yaml` works without a positional NAME argument - [ ] Actor name is read from the YAML file's `name` field (not from CLI argument) - [ ] `agents actor remove` accepts `--format/-f` option with `json`, `yaml`, `plain`, `rich` values - [ ] `agents actor remove --format json` produces spec-compliant JSON envelope with `actor_removed`, `impact`, `cleanup` sections - [ ] `ActorLoader._resolve_tools()` raises `ValidationError` for unresolved tool references (not just warning) - [ ] All nox stages pass with coverage >= 97% ## Subtasks - [ ] Remove positional `NAME` argument from `agents actor add` command signature - [ ] Update `add` command to read actor name from the loaded YAML config's `name` field - [ ] Update `features/actor_add_name_positional.feature` — remove `@skip` tags from spec-compliant scenarios - [ ] Add `--format/-f` option to `agents actor remove` command - [ ] Implement JSON/YAML/plain output for `remove` using `OutputSession` with spec envelope - [ ] Change `ActorLoader._resolve_tools()` to raise `ValidationError` instead of logging warning - [ ] Update `features/actor_loading.feature` — update "unresolvable tool reference" scenario to expect error - [ ] Write unit tests for updated `add` command (no positional arg) - [ ] Write unit tests for `remove --format` variants - [ ] Write unit tests for `_resolve_tools()` raising on unresolved references - [ ] Run `nox` (all default sessions), fix any errors ## Definition of Done - [ ] All acceptance criteria met - [ ] Tests written and passing (coverage >= 97%) - [ ] Code reviewed and approved - [ ] Documentation updated if needed - [ ] No regressions introduced ## Metadata - **Commit message:** `fix(actor): fix actor add CLI signature, add remove --format, raise on unresolved tools` - **Branch name:** `fix/v350/actor-cli-compliance` --- **Automated by CleverAgents Bot** Supervisor: Epic Planning Pool | Agent: epic-planning-pool-supervisor
HAL9000 added this to the v3.5.0 milestone 2026-04-14 04:44:57 +00:00
Author
Owner

Verified — Actor CLI compliance fixes are required for spec adherence. MoSCoW: Must-have. Priority: Medium.


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

✅ **Verified** — Actor CLI compliance fixes are required for spec adherence. MoSCoW: Must-have. Priority: Medium. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: project-owner-pool-supervisor
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#8995
No description provided.