markitect-main/guides/LEGACY_COMPATIBILITY_SYSTEM_GUIDE.md

# Legacy Compatibility System for MarkiTect CLI

## Overview

The Legacy Compatibility System provides comprehensive management of deprecated CLI interfaces through versioned switches, automated lifecycle management, and seamless migration assistance. This system enables gradual deprecation of features while maintaining backward compatibility and providing clear migration paths.

## Architecture Overview

```mermaid
graph TB
    CLI[CLI Commands] --> LS[Legacy Switches]
    LS --> LR[Legacy Registry]
    LR --> LA[Legacy Agent]
    LA --> GT[Git State Tracker]
    LA --> DM[Deprecation Manager]
    LA --> CL[Compatibility Layer]

    GT --> Git[Git Repository]
    DM --> Warnings[Deprecation Warnings]
    CL --> Adapters[Parameter Adapters]

    LA --> Automation[Automated Management]
    Automation --> Progression[Lifecycle Progression]
    Automation --> Cleanup[Legacy Cleanup]
    Automation --> Migration[Migration Assistance]
```

## Key Components

### 1. Legacy Registry
**Central management of legacy interfaces and versions**

- **Purpose**: Maintains authoritative database of all legacy interfaces
- **Features**:
  - Version tracking with git commit bindings
  - Status lifecycle management (current → deprecated → legacy → sunset → removed)
  - Usage analytics and migration guidance
  - Import/export capabilities for backup and sharing

**Core API**:
```python
from markitect.legacy import LegacyRegistry, LegacyStatus

registry = LegacyRegistry()

# Register a legacy interface
interface = registry.register_legacy_interface(
    command='query',
    version='v1.0',
    git_commit='abc123',
    status=LegacyStatus.DEPRECATED,
    migration_guide='Use new --format parameter',
    breaking_changes=['Parameter renamed', 'Output format changed']
)

# Execute legacy implementation
result = registry.execute_legacy('query', 'v1.0', *args, **kwargs)
```

### 2. Legacy Switch System
**CLI switches for version-controlled legacy behavior**

- **Purpose**: Provides `--legacy-v1`, `--legacy-v2` style switches
- **Features**:
  - Automatic switch generation from registry
  - Deprecation warnings on usage
  - Parameter adaptation for compatibility
  - Graceful fallback to modern implementations

**Usage Patterns**:
```python
from markitect.legacy import legacy_option, with_legacy_support

# Method 1: Decorators for new commands
@legacy_option('v1.0', 'Use v1.0 legacy behavior')
@click.command()
def my_command(legacy_v1_0=False):
    if legacy_v1_0:
        # Handle legacy behavior
        pass

# Method 2: Automatic legacy support
@with_legacy_support('query')
@click.command()
def query_command(*args, **kwargs):
    # Modern implementation - legacy routing handled automatically
    pass
```

### 3. Git State Tracker
**Binding legacy versions to specific git commits**

- **Purpose**: Enable precise version restoration and validation
- **Features**:
  - Current git state capture
  - Version-to-commit binding
  - File validation for legacy versions
  - Snapshot creation for testing

**Example**:
```python
from markitect.legacy import GitStateTracker

tracker = GitStateTracker()

# Bind current state to legacy version
binding = tracker.bind_version_to_commit(
    command='query',
    version='v1.0',
    description='Query v1.0 with old parameters',
    validation_files=['markitect/cli.py', 'markitect/database.py']
)

# Get commit for legacy version
commit_hash = tracker.get_commit_for_version('query', 'v1.0')
```

### 4. Deprecation Manager
**Graduated deprecation warnings and lifecycle management**

- **Purpose**: Structured deprecation process with appropriate warnings
- **Features**:
  - Four-level warning system (INFO → WARNING → CRITICAL → ERROR)
  - Timeline-based progression
  - Migration report generation
  - Usage analytics and recommendations

**Deprecation Levels**:
- **INFO**: Initial deprecation notice (90 days)
- **WARNING**: Standard deprecation warning (60 days)
- **CRITICAL**: Final warning before removal (30 days)
- **ERROR**: Blocks execution (post-removal)

### 5. Compatibility Layer
**Bridge between legacy and modern interfaces**

- **Purpose**: Translate legacy parameters to modern equivalents
- **Features**:
  - Parameter name mapping
  - Value transformation
  - Return format adaptation
  - Fallback behavior for missing functionality

**Parameter Mapping Example**:
```python
from markitect.legacy.compatibility import InterfaceAdapter, ParameterMapping

adapter = InterfaceAdapter(
    legacy_version='v1.0',
    parameter_mappings=[
        ParameterMapping(
            legacy_name='sql_query',    # Old parameter
            modern_name='sql',          # New parameter
            required=True
        ),
        ParameterMapping(
            legacy_name='output_format',
            modern_name='format',
            transformer=lambda x: {'pretty': 'table', 'raw': 'simple'}.get(x, x)
        )
    ]
)
```

### 6. Legacy Agent
**Automated legacy interface lifecycle management**

- **Purpose**: Intelligent automation of legacy management tasks
- **Features**:
  - Automatic deprecation progression
  - Cleanup scheduling and execution
  - Migration assistance coordination
  - Usage monitoring and analytics

**Agent Operations**:
```python
from markitect.legacy import LegacyAgent

agent = LegacyAgent()

# Run maintenance cycle
summary = agent.run_maintenance()

# Force cleanup of specific version
success = agent.force_cleanup('old_command', 'v1.0')

# Schedule migration assistance
agent.schedule_migration_assistance('query', 'v1.0', target_date='2024-12-31')
```

## Implementation Guide

### Step 1: Setup Legacy Registry

```python
# Initialize registry and register legacy interfaces
from markitect.legacy import LegacyRegistry, LegacyStatus
from datetime import datetime, timedelta

registry = LegacyRegistry()

# Register deprecated version
registry.register_legacy_interface(
    command='query',
    version='v1.0',
    git_commit='a1b2c3d4',  # Commit where v1.0 was current
    status=LegacyStatus.DEPRECATED,
    deprecated_date=(datetime.now() - timedelta(days=90)).isoformat(),
    removal_date=(datetime.now() + timedelta(days=60)).isoformat(),
    description='Legacy query with sql_query parameter',
    breaking_changes=[
        'Parameter sql_query renamed to sql',
        'Output format changed'
    ],
    migration_guide='''
    Migration steps:
    1. Change --sql_query to positional sql argument
    2. Update --output_format values (pretty→table, raw→simple)
    3. Adapt result parsing for new format
    ''',
    implementation=legacy_v1_implementation
)
```

### Step 2: Add Legacy Switches to CLI Commands

```python
# Option 1: Manual legacy option addition
@click.command()
@click.argument('sql', type=str)
@click.option('--format', '-f', default='simple')
@legacy_option('v1.0', 'Use v1.0 legacy behavior (deprecated)')
def query_command(sql, format, legacy_v1_0=False):
    if legacy_v1_0:
        # Use legacy registry
        registry = LegacyRegistry()
        return registry.execute_legacy('query', 'v1.0', sql=sql, format=format)
    else:
        # Modern implementation
        return execute_modern_query(sql, format)

# Option 2: Automatic legacy support
@with_legacy_support('query')
@click.command()
def query_command(sql, format):
    # Modern implementation only - legacy handled automatically
    return execute_modern_query(sql, format)
```

### Step 3: Setup Compatibility Adapters

```python
from markitect.legacy.compatibility import CompatibilityLayer, InterfaceAdapter, ParameterMapping

compatibility = CompatibilityLayer()

# Create adapter for parameter changes
adapter = InterfaceAdapter(
    legacy_version='v1.0',
    parameter_mappings=[
        ParameterMapping(
            legacy_name='sql_query',
            modern_name='sql'
        ),
        ParameterMapping(
            legacy_name='output_format',
            modern_name='format',
            transformer=lambda x: {'pretty': 'table', 'raw': 'simple'}.get(x, x)
        )
    ],
    return_transformer=lambda result: {
        'status': 'success',
        'data': result,
        'version': 'v1.0'
    }
)

compatibility.register_adapter('query', adapter)
```

### Step 4: Configure Automated Management

```python
from markitect.legacy import LegacyAgent
from markitect.legacy.agent import AgentConfig

# Configure agent
config = AgentConfig(
    auto_progression=True,
    cleanup_unused_days=180,
    migration_guide_auto_generation=True,
    notification_threshold_days=30
)

agent = LegacyAgent(config=config)

# Setup scheduled maintenance (via cron, systemd, etc.)
# 0 2 * * * /usr/local/bin/markitect legacy agent-maintenance
```

### Step 5: Add Legacy Management Commands

```python
@click.group('legacy')
def legacy_commands():
    """Legacy interface management."""
    pass

@legacy_commands.command('status')
def legacy_status():
    """Show all legacy interfaces."""
    registry = LegacyRegistry()
    # Display legacy interface status

@legacy_commands.command('migrate')
@click.argument('command')
@click.argument('version')
def legacy_migrate(command, version):
    """Get migration guidance."""
    registry = LegacyRegistry()
    migration = registry.get_migration_path(command, version)
    # Display migration guide
```

## Lifecycle Management

### Deprecation Progression

1. **Current** → **Deprecated** (Manual)
   - Developer marks feature as deprecated
   - INFO level warnings begin
   - Feature still works normally

2. **Deprecated** → **Legacy** (90 days)
   - WARNING level warnings
   - `--legacy-vX` flag required
   - Compatibility layer handles differences

3. **Legacy** → **Sunset** (60 days)
   - CRITICAL level warnings
   - Final warning phase
   - Migration assistance activated

4. **Sunset** → **Removed** (30 days)
   - Feature no longer available
   - ERROR level blocking
   - Cleanup and removal

### Automated Tasks

The Legacy Agent performs these automated tasks:

- **Daily**: Check for progression opportunities
- **Weekly**: Generate usage reports and migration recommendations
- **Monthly**: Clean up unused legacy interfaces
- **On-demand**: Force cleanup, migration assistance, compatibility testing

## Usage Examples

### Basic Legacy Support

```bash
# Modern usage
markitect query "SELECT * FROM files" --format=table

# Legacy v1.0 usage (with warning)
markitect query --legacy-v1.0 --sql_query "SELECT * FROM files" --output_format=pretty

# Legacy v2.0 usage
markitect query --legacy-v2.0 --database_query "SELECT * FROM files"
```

### Legacy Management

```bash
# Show all legacy interfaces
markitect legacy status

# Get migration guidance
markitect legacy migrate query v1.0

# Force cleanup of legacy version
markitect legacy cleanup query v1.0 --force

# Show agent status
markitect legacy agent-status

# Run maintenance manually
markitect legacy agent-maintenance
```

### Compatibility Testing

```bash
# Test parameter adaptation
markitect legacy test-compatibility query v1.0 \
  --test-params '{"sql_query": "SELECT 1", "output_format": "pretty"}'

# Generate compatibility report
markitect legacy compatibility-report query v1.0
```

## Testing Strategy

### Dual Interface Testing

The system supports testing both modern and legacy interfaces simultaneously:

```python
def test_query_modern_and_legacy():
    """Test both modern and legacy query interfaces."""

    # Test modern interface
    result_modern = execute_modern_query("SELECT 1", "table")

    # Test legacy interface
    registry = LegacyRegistry()
    result_legacy = registry.execute_legacy("query", "v1.0",
                                          sql_query="SELECT 1",
                                          output_format="pretty")

    # Verify compatibility
    assert extract_data(result_modern) == extract_data(result_legacy)
```

### Automated Test Generation

```python
# Generate tests for legacy versions
def generate_legacy_tests():
    registry = LegacyRegistry()
    for command in registry._interfaces:
        for version in registry.get_available_versions(command):
            create_compatibility_test(command, version)
```

## Migration Assistance

### Automated Migration Reports

```python
# Generate migration report
report = deprecation_manager.generate_migration_report('query', 'v1.0')

# Report includes:
# - Breaking changes
# - Step-by-step migration guide
# - Code examples
# - Timeline and urgency
# - Support resources
```

### Interactive Migration Assistant

```bash
# Interactive migration guidance
markitect legacy migrate-assistant query v1.0

# Output:
# 🔄 Migration Assistant for query v1.0
#
# Current usage detected:
# ✓ Found 15 scripts using --sql_query parameter
# ✓ Found 8 scripts using --output_format=pretty
#
# Migration steps:
# 1. Update parameter names...
# 2. Change format values...
# 3. Test with new interface...
#
# Generate migration script? [y/N]
```

## Configuration

### Environment Variables

```bash
# Legacy system configuration
export MARKITECT_LEGACY_AUTO_PROGRESSION=true
export MARKITECT_LEGACY_CLEANUP_DAYS=180
export MARKITECT_LEGACY_NOTIFICATION_DAYS=30
export MARKITECT_LEGACY_QUIET_MODE=false

# Database locations
export MARKITECT_LEGACY_DB_PATH="~/.markitect/legacy_registry.db"
export MARKITECT_LEGACY_AGENT_DATA="~/.markitect/legacy_agent"
```

### Configuration File

```yaml
# .markitect/legacy_config.yml
legacy:
  auto_progression: true
  cleanup_unused_days: 180
  migration_guide_auto_generation: true
  notification_threshold_days: 30
  max_concurrent_migrations: 3
  backup_before_cleanup: true

  deprecation:
    info_duration_days: 90
    warning_duration_days: 60
    critical_duration_days: 30
    show_migration_guide: true
    block_on_error: true

  compatibility:
    default_mode: adaptive
    strict_validation: false
    fallback_behavior: warn
```

## Best Practices

### 1. Registration Strategy

- **Register early**: Add legacy interfaces as soon as deprecation begins
- **Comprehensive metadata**: Include detailed breaking changes and migration guides
- **Git binding**: Always bind to specific commits for precise restoration
- **Validation files**: Specify key files that define the legacy behavior

### 2. Deprecation Timeline

- **Generous timelines**: Allow sufficient time for migration (6+ months total)
- **Clear communication**: Provide detailed warnings and migration guidance
- **Usage monitoring**: Track legacy usage to inform timeline decisions
- **Gradual progression**: Use the four-phase progression systematically

### 3. Compatibility Layer

- **Parameter mapping**: Handle all parameter name and format changes
- **Return transformation**: Maintain expected output formats
- **Error handling**: Provide graceful fallbacks for edge cases
- **Performance**: Minimize overhead of compatibility translations

### 4. Testing Approach

- **Dual testing**: Test both legacy and modern interfaces
- **Compatibility validation**: Ensure legacy interfaces produce equivalent results
- **Migration testing**: Validate migration guides work correctly
- **Agent testing**: Test automated lifecycle management

### 5. Migration Assistance

- **Proactive guidance**: Generate migration reports before removal
- **Code examples**: Provide concrete before/after examples
- **Tool support**: Offer automated migration scripts where possible
- **Documentation**: Maintain comprehensive migration documentation

## Troubleshooting

### Common Issues

#### Legacy Version Not Found
```
LegacyVersionNotFoundError: Legacy version 'v1.0' not found for command 'query'
```
**Solution**: Register the legacy interface or check version identifier

#### Parameter Adaptation Failed
```
CompatibilityError: Legacy compatibility failed: unmapped parameter 'old_param'
```
**Solution**: Add parameter mapping to compatibility adapter

#### Git State Error
```
GitStateError: Git command failed: invalid commit hash
```
**Solution**: Verify git repository state and commit hash validity

#### Agent Task Failed
```
AgentTask execution failed: generate_migration_guide
```
**Solution**: Check agent configuration and ensure interfaces are properly registered

### Debugging Tools

```bash
# Debug legacy registry
markitect legacy debug registry --command=query

# Debug compatibility layer
markitect legacy debug compatibility --command=query --version=v1.0

# Debug agent state
markitect legacy debug agent --show-tasks --show-bindings

# Validate git bindings
markitect legacy debug git-bindings --validate
```

## Integration with Existing Systems

### CI/CD Integration

```yaml
# .github/workflows/legacy-management.yml
name: Legacy Management
on:
  schedule:
    - cron: '0 2 * * *'  # Daily at 2 AM

jobs:
  legacy-maintenance:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Run Legacy Agent
        run: |
          markitect legacy agent-maintenance
          markitect legacy generate-reports
```

### Monitoring Integration

```python
# Integration with monitoring systems
def setup_legacy_monitoring():
    agent = LegacyAgent()

    # Collect metrics
    stats = agent.get_agent_status()

    # Send to monitoring system
    send_metric('legacy.interfaces.total', stats['registry_stats']['total_interfaces'])
    send_metric('legacy.tasks.pending', stats['tasks']['pending'])
    send_metric('legacy.usage.warnings', get_warning_count())
```

## Future Enhancements

### Planned Features

1. **Web Dashboard**: Visual interface for legacy management
2. **API Integration**: REST API for programmatic access
3. **Advanced Analytics**: Usage patterns and migration success tracking
4. **Custom Workflows**: User-defined deprecation workflows
5. **Plugin System**: Extensible compatibility adapters
6. **Integration Tools**: IDE plugins for migration assistance

### Extension Points

The system is designed for extension:

- **Custom Adapters**: Implement specialized compatibility logic
- **Agent Tasks**: Add custom automated tasks
- **Transformers**: Create parameter and return value transformers
- **Notification Systems**: Integrate with external notification platforms
- **Migration Tools**: Build domain-specific migration assistants

## Conclusion

The Legacy Compatibility System provides a comprehensive solution for managing CLI evolution while maintaining backward compatibility. By combining automated lifecycle management, precise version tracking, and intelligent compatibility adaptation, it enables smooth transitions between interface versions while providing users with clear migration paths and adequate time for adaptation.

The system's modular architecture allows for customization and extension while providing sensible defaults for common deprecation scenarios. With proper setup and configuration, it can significantly reduce the maintenance burden of supporting legacy interfaces while improving the user experience during transitions.