UAT: Deprecated legacy CLI commands (tell, build, new, current, cd, continue) lack a documented removal timeline and version policy #4109

New issue

Open

opened 2026-04-06 10:22:22 +00:00 by freemo · 0 comments

freemo commented

2026-04-06 10:22:22 +00:00

Owner

Metadata

Branch: fix/cli-deprecation-removal-timeline
Commit Message: fix(cli): document removal timeline and version policy for deprecated legacy CLI commands
Milestone: (backlog — see note below)
Parent Epic: #933

Bug Report

Feature Area: API Versioning and Backward Compatibility
Severity: Low
Found by: UAT Testing (automated)

Summary

Multiple legacy CLI commands are marked as deprecated in src/cleveragents/cli/commands/plan.py but have no documented removal timeline or version policy. Per CONTRIBUTING.md, breaking changes require a MAJOR version increment, but there is no clear statement of when these deprecated commands will be removed or what version will remove them.

Deprecated Commands Without Removal Timeline

The following commands in agents plan are marked .. deprecated:: in their docstrings but have no version or date for removal:

Command	Deprecated Since	Replacement	Removal Version
`agents tell`	Unknown	`agents plan use`	Not documented
`agents build`	Unknown	`agents plan execute`	Not documented
`agents new`	Unknown	`agents plan use`	Not documented
`agents current`	Unknown	`agents plan status`	Not documented
`agents cd`	Unknown	`agents plan status`	Not documented
`agents continue`	Unknown	`agents plan use`	Not documented
`agents apply` (legacy)	Unknown	`agents plan apply`	Not documented

Additionally, the agents context top-level command is marked as deprecated in src/cleveragents/cli/main.py without a removal timeline.

Expected Behavior

Per CONTRIBUTING.md's semantic versioning policy:

Breaking changes (removing commands) require a MAJOR version increment
Deprecated features should document:
1. The version they were deprecated in
2. The version they will be removed in
3. The migration path

Example of proper deprecation docstring:

.. deprecated:: 1.0.0
    Use ``agents plan use`` instead. Will be removed in v2.0.0.

Actual Behavior

Current deprecation docstrings in plan.py:

def tell_command(...):
    """...
    .. deprecated::
        Use ``PlanLifecycleService.use_action`` instead.
    """

No version numbers, no removal timeline.

Impact

Users cannot plan their migration timeline
The project cannot safely remove these commands without a documented policy
Semantic versioning guarantees cannot be upheld without knowing when breaking changes will occur
CI/CD pipelines using legacy commands have no warning of when they will break

Code Location

src/cleveragents/cli/commands/plan.py — deprecated command functions (lines ~271, 302, 338, 368, 395, 422, 450, 477, 669, 775, 944, 989, 1042, 1082)
src/cleveragents/cli/main.py — deprecated agents context alias (line ~121)

Subtasks

Audit all .. deprecated:: docstrings in src/cleveragents/cli/commands/plan.py and identify the version each command was deprecated in
Audit src/cleveragents/cli/main.py for the deprecated agents context alias
Determine the target MAJOR version for removal of each deprecated command (coordinate with project owner)
Update all deprecation docstrings to include .. deprecated:: <version> with the version deprecated and Will be removed in v<MAJOR>.0.0.
Add runtime deprecation warnings (e.g., warnings.warn(...)) to each deprecated command function so users see the warning at runtime
Update CHANGELOG or release notes to document the deprecation policy
Tests (pytest): verify that invoking each deprecated command emits a DeprecationWarning
Run nox (all default sessions), 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.
All nox stages pass
Coverage >= 97%

Backlog note: This issue was discovered during autonomous operation
on milestone v3.4.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: UAT Testing | Agent: ca-new-issue-creator

## Metadata - **Branch**: `fix/cli-deprecation-removal-timeline` - **Commit Message**: `fix(cli): document removal timeline and version policy for deprecated legacy CLI commands` - **Milestone**: *(backlog — see note below)* - **Parent Epic**: #933 ## Bug Report **Feature Area:** API Versioning and Backward Compatibility **Severity:** Low **Found by:** UAT Testing (automated) ### Summary Multiple legacy CLI commands are marked as deprecated in `src/cleveragents/cli/commands/plan.py` but have no documented removal timeline or version policy. Per CONTRIBUTING.md, breaking changes require a MAJOR version increment, but there is no clear statement of when these deprecated commands will be removed or what version will remove them. ### Deprecated Commands Without Removal Timeline The following commands in `agents plan` are marked `.. deprecated::` in their docstrings but have no version or date for removal: | Command | Deprecated Since | Replacement | Removal Version | |---------|-----------------|-------------|-----------------| | `agents tell` | Unknown | `agents plan use` | **Not documented** | | `agents build` | Unknown | `agents plan execute` | **Not documented** | | `agents new` | Unknown | `agents plan use` | **Not documented** | | `agents current` | Unknown | `agents plan status` | **Not documented** | | `agents cd` | Unknown | `agents plan status` | **Not documented** | | `agents continue` | Unknown | `agents plan use` | **Not documented** | | `agents apply` (legacy) | Unknown | `agents plan apply` | **Not documented** | Additionally, the `agents context` top-level command is marked as deprecated in `src/cleveragents/cli/main.py` without a removal timeline. ### Expected Behavior Per CONTRIBUTING.md's semantic versioning policy: - Breaking changes (removing commands) require a MAJOR version increment - Deprecated features should document: 1. The version they were deprecated in 2. The version they will be removed in 3. The migration path Example of proper deprecation docstring: ```python .. deprecated:: 1.0.0 Use ``agents plan use`` instead. Will be removed in v2.0.0. ``` ### Actual Behavior Current deprecation docstrings in `plan.py`: ```python def tell_command(...): """... .. deprecated:: Use ``PlanLifecycleService.use_action`` instead. """ ``` No version numbers, no removal timeline. ### Impact - Users cannot plan their migration timeline - The project cannot safely remove these commands without a documented policy - Semantic versioning guarantees cannot be upheld without knowing when breaking changes will occur - CI/CD pipelines using legacy commands have no warning of when they will break ### Code Location - `src/cleveragents/cli/commands/plan.py` — deprecated command functions (lines ~271, 302, 338, 368, 395, 422, 450, 477, 669, 775, 944, 989, 1042, 1082) - `src/cleveragents/cli/main.py` — deprecated `agents context` alias (line ~121) ## Subtasks - [ ] Audit all `.. deprecated::` docstrings in `src/cleveragents/cli/commands/plan.py` and identify the version each command was deprecated in - [ ] Audit `src/cleveragents/cli/main.py` for the deprecated `agents context` alias - [ ] Determine the target MAJOR version for removal of each deprecated command (coordinate with project owner) - [ ] Update all deprecation docstrings to include `.. deprecated:: <version>` with the version deprecated and `Will be removed in v<MAJOR>.0.0.` - [ ] Add runtime deprecation warnings (e.g., `warnings.warn(...)`) to each deprecated command function so users see the warning at runtime - [ ] Update `CHANGELOG` or release notes to document the deprecation policy - [ ] Tests (pytest): verify that invoking each deprecated command emits a `DeprecationWarning` - [ ] Run `nox` (all default sessions), 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. - All nox stages pass - Coverage >= 97% > **Backlog note:** This issue was discovered during autonomous operation > on milestone v3.4.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: UAT Testing | Agent: ca-new-issue-creator

freemo added a new dependency

2026-04-06 10:22:43 +00:00

#933 Epic: A2A Protocol Compliance — JSON-RPC 2.0 Framing, Standard Operations, and Extension Methods

freemo referenced this issue

2026-04-06 10:23:25 +00:00

[Automated] CleverAgents Build Session - 2026-04-06 #3775

freemo added the

Points

label

2026-04-06 10:26:46 +00:00

freemo referenced this issue

2026-04-06 10:35:53 +00:00