v3.0 Breaking Change: Remove hidden backward-compatibility commands

[itdove]

Problem

In issue #283, we simplified the CLI from 49 → 37 visible commands by hiding 10 commands for backward compatibility. These hidden commands still work but clutter the codebase and should be removed in a future major version.

Hidden Commands to Remove in v3.0

The following commands were hidden in v2.x and should be completely removed in v3.0:

1. Deprecated Aliases (3 commands)

• daf sessions list → Remove (use daf list)
• daf config tui → Remove (use daf config edit)
• daf completion → Remove (integrated into daf init)

2. Merged Commands (2 commands)

• daf edit → Remove (use daf open --edit)
• daf check → Remove (use daf init --check)

3. Hidden Maintenance Commands (5 commands)

Keep these but remove direct access (only via daf maintenance group):

• daf cleanup-conversation → Remove direct access
• daf cleanup-sessions → Remove direct access
• daf discover → Remove direct access
• daf rebuild-index → Remove direct access
• daf repair-conversation → Remove direct access

4. Developer Utilities (1 command)

• daf purge-mock-data → Keep hidden (developer-only)

Implementation Plan

Phase 1: Prepare Users (v2.x releases)

• ✅ Hidden commands show migration messages
• ✅ Documentation updated with new syntax
• Add deprecation warnings to hidden commands
• Release notes highlight upcoming removal
• Give users 2-3 releases (6+ months) to migrate

Phase 2: Remove Commands (v3.0)

• Delete daf sessions command group code
• Delete daf config tui alias code
• Delete daf completion command code
• Delete daf edit command code
• Delete daf check command code
• Delete direct access to 5 maintenance commands
• Update tests to remove references
• Update all documentation

Phase 3: Cleanup (v3.0)

• Remove backward compatibility code
• Simplify command structure
• Update CLI tests
• Create v3.0 migration guide

Expected Impact

Metric	v2.x	v3.0	Change
Visible Commands	37	37	No change (already hidden)
Hidden Commands	10	1	-9
Total Commands	47	38	-9 (-19%)
Backward Compatibility	Yes	No (breaking)	⚠️

Breaking Changes

This is a BREAKING CHANGE release (v3.0) requiring:

• Major version bump
• Clear migration guide
• Release notes highlighting removals
• Minimum 6 months deprecation period

User Migration Path

Users will need to update their scripts/workflows:

# v2.x (deprecated, still works)
daf sessions list
daf config tui
daf edit PROJ-123
daf check
daf cleanup-sessions

# v3.0+ (required)
daf list
daf config edit
daf open PROJ-123 --edit
daf init --check
daf maintenance cleanup-sessions

Files to Modify

Delete:

• devflow/cli/commands/sessions_list_command.py (already unused in v2.x)
• Hidden command decorators from devflow/cli/main.py

Update:

• devflow/cli/main.py - Remove hidden command definitions
• tests/ - Update/remove tests for hidden commands
• docs/ - Remove migration notes (no longer needed)

Acceptance Criteria

• All 10 hidden backward-compatibility commands removed
• Only daf purge-mock-data remains hidden (developer utility)
• All tests updated and passing
• v3.0 migration guide created
• Release notes document all breaking changes
• Code simplified (no backward compatibility shims)

Timeline

Proposed:

• v2.1: Add deprecation warnings (released)
• v2.2-2.3: Continue showing warnings (6 months)
• v3.0: Remove hidden commands (breaking change)

Dependencies

• Blocked by: User adoption of v2.x with new command syntax
• Requires: Sufficient deprecation period (6+ months)
• Related: Simplify CLI: Reduce 73 commands to ~50 by removing deprecated/redundant commands #283 (CLI simplification implementation)

References

• Original simplification: Simplify CLI: Reduce 73 commands to ~50 by removing deprecated/redundant commands #283
• Branch with implementation: 283
• Commits: 31d3c2c (Phase 1), ddbf53a (Phase 2), 7995e2b (Completion), e4f70c7 (Phase 3)