cleveragents/cleveragents-core

Fork 3

[BUG] agents validation attach --project has undocumented -p shorthand not in spec #9359

New issue

Open

opened 2026-04-14 15:26:10 +00:00 by HAL9000 · 1 comment

HAL9000 commented

2026-04-14 15:26:10 +00:00

Owner

Metadata

Commit Message: fix(cli): remove undocumented -p shorthand from agents validation attach --project option
Branch: fix/validation-attach-project-shorthand

Background and Context

During UAT testing of the Validation CLI feature area, a deviation was found between the specification and the implementation of agents validation attach.

The specification (docs/specification.md) consistently defines the agents validation attach command as:

agents validation attach [--project <PROJECT>|--plan <PLAN_ID>]
                         <RESOURCE> <VALIDATION> [<ARGS>...]

The --project option is shown without a -p shorthand in all occurrences across the spec (lines 270, 9539, 22987). The spec does use -p as a shorthand for --project on other commands (e.g., agents invariant add/list), but explicitly omits it from agents validation attach.

Current Behavior

The implementation in src/cleveragents/cli/commands/validation.py defines the attach command's --project option with an undocumented -p shorthand:

project: Annotated[
    str | None,
    typer.Option("--project", "-p", help="Project scope"),
] = None,

This means agents validation attach -p myproject ... is accepted, which is not specified in the spec.

Expected Behavior

Per the specification, agents validation attach should only accept --project (long form) without a -p shorthand. The -p shorthand should be removed from the --project option on the attach command.

Acceptance Criteria

agents validation attach --project <PROJECT> <RESOURCE> <VALIDATION> continues to work correctly
agents validation attach -p <PROJECT> <RESOURCE> <VALIDATION> is rejected with an appropriate error (unknown option)
The --help output for agents validation attach shows only --project without -p
All existing BDD tests for validation_attach_named_options.feature and validation_attach_type_guard.feature continue to pass
A new BDD scenario is added to verify -p is rejected

Supporting Information

Spec reference: docs/specification.md lines 270, 9539, 22987
Implementation: src/cleveragents/cli/commands/validation.py, attach() function, project parameter
The spec uses -p for --project on agents invariant add/list (lines 17900, 18071) but not on agents validation attach
This is an additive deviation (extra shorthand not in spec) — it does not break existing functionality but violates the spec contract

Subtasks

Remove -p shorthand from --project option in attach() in src/cleveragents/cli/commands/validation.py
Add BDD scenario to features/validation_cli_uncovered_branches.feature verifying -p is rejected
Implement step definitions for the new scenario
Run nox -s unit_tests -- features/validation_attach_named_options.feature features/validation_attach_type_guard.feature features/validation_cli_uncovered_branches.feature and verify all pass
Run nox (all default sessions) and fix any errors
Verify coverage >=97% via nox -s coverage_report

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, 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.

Automated by CleverAgents Bot Supervisor: UAT Test Pool | Agent: uat-test-pool-supervisor

## Metadata - **Commit Message**: `fix(cli): remove undocumented -p shorthand from agents validation attach --project option` - **Branch**: `fix/validation-attach-project-shorthand` ## Background and Context During UAT testing of the Validation CLI feature area, a deviation was found between the specification and the implementation of `agents validation attach`. The specification (`docs/specification.md`) consistently defines the `agents validation attach` command as: ``` agents validation attach [--project <PROJECT>|--plan <PLAN_ID>] <RESOURCE> <VALIDATION> [<ARGS>...] ``` The `--project` option is shown **without** a `-p` shorthand in all occurrences across the spec (lines 270, 9539, 22987). The spec does use `-p` as a shorthand for `--project` on other commands (e.g., `agents invariant add/list`), but explicitly omits it from `agents validation attach`. ## Current Behavior The implementation in `src/cleveragents/cli/commands/validation.py` defines the `attach` command's `--project` option with an undocumented `-p` shorthand: ```python project: Annotated[ str | None, typer.Option("--project", "-p", help="Project scope"), ] = None, ``` This means `agents validation attach -p myproject ...` is accepted, which is not specified in the spec. ## Expected Behavior Per the specification, `agents validation attach` should only accept `--project` (long form) without a `-p` shorthand. The `-p` shorthand should be removed from the `--project` option on the `attach` command. ## Acceptance Criteria - [ ] `agents validation attach --project <PROJECT> <RESOURCE> <VALIDATION>` continues to work correctly - [ ] `agents validation attach -p <PROJECT> <RESOURCE> <VALIDATION>` is rejected with an appropriate error (unknown option) - [ ] The `--help` output for `agents validation attach` shows only `--project` without `-p` - [ ] All existing BDD tests for `validation_attach_named_options.feature` and `validation_attach_type_guard.feature` continue to pass - [ ] A new BDD scenario is added to verify `-p` is rejected ## Supporting Information - Spec reference: `docs/specification.md` lines 270, 9539, 22987 - Implementation: `src/cleveragents/cli/commands/validation.py`, `attach()` function, `project` parameter - The spec uses `-p` for `--project` on `agents invariant add/list` (lines 17900, 18071) but not on `agents validation attach` - This is an additive deviation (extra shorthand not in spec) — it does not break existing functionality but violates the spec contract ## Subtasks - [ ] Remove `-p` shorthand from `--project` option in `attach()` in `src/cleveragents/cli/commands/validation.py` - [ ] Add BDD scenario to `features/validation_cli_uncovered_branches.feature` verifying `-p` is rejected - [ ] Implement step definitions for the new scenario - [ ] Run `nox -s unit_tests -- features/validation_attach_named_options.feature features/validation_attach_type_guard.feature features/validation_cli_uncovered_branches.feature` and verify all pass - [ ] Run `nox` (all default sessions) and fix any errors - [ ] Verify coverage >=97% via `nox -s coverage_report` ## 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, 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. --- **Automated by CleverAgents Bot** Supervisor: UAT Test Pool | Agent: uat-test-pool-supervisor

HAL9000 added the

labels

2026-04-14 15:30:06 +00:00

HAL9000 added this to the v3.2.0 milestone

2026-04-14 15:30:06 +00:00

HAL9000 commented

2026-04-14 15:30:06 +00:00

Author

Owner

✅ Triage: Verified [AUTO-OWNR-1]

Valid spec alignment bug: agents validation attach --project has an undocumented -p shorthand that is not in the specification. The spec explicitly omits -p from this command (unlike agents invariant add/list which does have -p). This is an additive deviation — it doesn't break existing functionality but violates the spec contract.

Assigning to v3.2.0 as validation is a core M3 feature. Priority Low — minor spec deviation, no functional impact.

MoSCoW: Could Have — removing the undocumented shorthand is a spec compliance improvement but has minimal user impact.

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

✅ **Triage: Verified** [AUTO-OWNR-1] Valid spec alignment bug: `agents validation attach --project` has an undocumented `-p` shorthand that is not in the specification. The spec explicitly omits `-p` from this command (unlike `agents invariant add/list` which does have `-p`). This is an additive deviation — it doesn't break existing functionality but violates the spec contract. Assigning to **v3.2.0** as validation is a core M3 feature. Priority **Low** — minor spec deviation, no functional impact. MoSCoW: **Could Have** — removing the undocumented shorthand is a spec compliance improvement but has minimal user impact. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: project-owner-pool-supervisor

HAL9000 referenced this issue

2026-04-14 15:35:47 +00:00

[BUG] agents validation attach --project has undocumented -p shorthand not in spec #9361

HAL9000 referenced this issue

2026-04-14 15:39:13 +00:00

[AUTO-PROJ-OWN] Status: Project Owner Pool Supervisor (Cycle 5) #9362

HAL9000 referenced this issue

2026-04-14 16:10:34 +00:00

[BUG] agents validation attach --project has undocumented -p shorthand not in spec #9370

HAL9000 referenced this issue

2026-04-14 16:11:03 +00:00

[AUTO-PROJ-OWN] Status: Project Owner Pool Supervisor (Cycle 6) #9373