@bobmatnyc/ai-trackdown-tools/CHANGELOG.md

Professional CLI tool for ai-trackdown functionality with comprehensive PR management system

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [1.1.7] - 2025-07-14

### Fixed
- **CLI Index Corruption Fix**: Resolved "No items found" errors in status and backlog commands
- **Index Auto-Repair System**: Automatic detection and repair of corrupted index files
- **Enhanced CLI Reliability**: Improved index validation and error recovery mechanisms

### Added
- **index-health Command**: New diagnostic command for CLI index validation and repair
- **Automatic Index Validation**: Built-in health checks for index integrity
- **Enhanced Error Recovery**: Graceful handling of index corruption scenarios

### Enhanced
- **CLI Performance**: Improved reliability and consistency of core CLI operations
- **Error Handling**: Better user feedback for index-related issues
- **Index Management**: Robust index file validation and maintenance

## [1.1.6] - 2025-07-13

## [1.1.5] - 2025-07-13

### Fixed
- **ISS-0092**: Epic ID parser now correctly handles tickets without epic_id field (optional parsing)

### Enhanced
- Resolution of ISS-0029: Fixed directory structure initialization bug
- E2E test suite enhancements and comprehensive validation
- Version synchronization system implementation
- Performance optimizations for large-scale operations
- Enhanced memory management and test isolation
- Improved CLI argument validation and error handling

### Technical
- ES module __dirname compatibility fixes
- Universal ticketing interface integration
- Enhanced test coverage with automated cleanup
- Strengthened build verification processes
- Version consistency across all project files

## [1.0.1] - 2025-07-09

### Fixed
- Enhanced epic display with improved formatting and color coding
- Fixed issue list sorting and filtering functionality
- Improved type system for better TypeScript compatibility
- Added GitHub sync integration capabilities
- Enhanced color utilities for better terminal output

### Added
- GitHub sync integration modules
- Enhanced sync commands with bidirectional support
- Improved test coverage for GitHub integration
- Better error handling and validation

## [3.0.0] - 2025-07-08

### Major Release - Performance Revolution and Anywhere-Submit Functionality

**MAJOR ENHANCEMENTS**: Comprehensive performance improvements, anywhere-submit capability, and enhanced template system

### Added

#### **Anywhere-Submit Functionality**
- **`--project-dir` Global Option**: Execute commands from any location by specifying target project directory
- **CI/CD Integration**: Perfect for automated workflows and build systems
- **Multi-Project Management**: Manage multiple projects from a single location
- **Path Resolution**: Automatic working directory change to target project

#### **Performance Revolution - Intelligent Indexing System**
- **90%+ Performance Improvement**: Operations that took 2-5 seconds now complete in <10ms
- **Automatic Index Management**: `.ai-trackdown-index` file provides instant lookups for all operations
- **Memory Efficient**: <5MB memory usage even for large projects (1000+ items)
- **Real-time Updates**: Index automatically updates when files change
- **Hash-based Lookups**: Instant search operations replace expensive directory scans

#### **Enhanced Template System**
- **Bundled Templates**: Default templates included with CLI installation in `dist/templates/`
- **Robust Fallback Mechanisms**: Automatic fallback to bundled templates when project templates missing
- **Multiple Path Resolution**: Works across different build structures and deployment methods
- **Zero Configuration**: Works out-of-the-box without requiring project template setup

#### **Directory Structure Improvements**
- **Unified Path Resolution**: Consistent path handling across all commands with `UnifiedPathResolver`
- **Configurable Root Directory**: Use `--root-dir` or `--tasks-dir` for custom directory layouts
- **Legacy Compatibility**: Seamless migration from older directory structures
- **Environment Variable Support**: `CLI_PROJECT_DIR` and `CLI_TASKS_DIR` environment variables

### Changed

#### **Performance Benchmarks**
- **Status Command**: <10ms (was 2-5 seconds) - >95% improvement
- **Epic List**: <50ms (was 3-8 seconds) - >90% improvement
- **PR Operations**: <100ms average response time
- **Search Operations**: Instant hash-based lookups (was linear scan)
- **Memory Usage**: <5MB for large projects (was high due to repeated file operations)

#### **Template System Redesign**
- **Fallback Priority**: Project templates → bundled templates → error
- **Path Resolution**: Multiple path attempts for robust template loading
- **Build Compatibility**: Works with development, compiled, and distributed builds
- **Error Handling**: Graceful fallbacks with informative error messages

#### **Command Execution**
- **Working Directory Management**: Automatic directory change with `--project-dir`
- **Global Options**: All commands support `--project-dir` for remote execution
- **Environment Integration**: Support for environment variable overrides
- **Verbose Output**: Enhanced debugging output for path resolution

### Fixed

#### **Template Loading Issues**
- **Deployment Scenarios**: Fixed template loading in different deployment environments
- **Path Resolution**: Resolved conflicts in distributed environments
- **Build Structures**: Compatible with various build and packaging methods
- **Error Handling**: Improved error messages for template issues

#### **Directory Structure Issues**
- **Path Consistency**: Unified path resolution across all commands
- **Configuration Conflicts**: Resolved conflicts between CLI options and configuration
- **Legacy Migration**: Smooth migration from older directory structures
- **Permission Handling**: Better error handling for directory access issues

#### **CLI Option Parsing**
- **Option Consistency**: Fixed inconsistencies in command option parsing
- **Help System**: Improved help text accuracy and completeness
- **Error Messages**: More informative error messages for invalid options
- **Validation**: Better input validation and error handling

### Technical Improvements

#### **Architecture Enhancements**
- **Index File System**: High-performance indexing with `.ai-trackdown-index`
- **Path Resolver**: Unified path resolution system for consistent behavior
- **Template Manager**: Enhanced template management with fallback mechanisms
- **Performance Monitoring**: Built-in performance benchmarking and monitoring

#### **Quality Assurance**
- **Test Coverage**: Comprehensive test suite for new functionality
- **Performance Testing**: Automated performance benchmarking
- **Integration Testing**: Cross-platform compatibility testing
- **Error Handling**: Robust error handling and recovery mechanisms

### Migration Notes

#### **Automatic Upgrades**
- **Zero Breaking Changes**: All existing projects continue to work without modifications
- **Performance Benefits**: Existing projects immediately benefit from performance improvements
- **Template Compatibility**: Existing project templates continue to work with fallback support
- **Configuration Preservation**: All existing configurations remain valid

#### **New Features Available**
- **Anywhere-Submit**: Use `--project-dir` with any command for remote execution
- **Performance Boost**: Automatic indexing system provides immediate speed improvements
- **Enhanced Templates**: Bundled templates available as fallbacks
- **Improved Help**: Enhanced help system with accurate command documentation

### Performance Metrics

#### **Response Times**
- **Status Command**: <10ms (was 2-5 seconds)
- **Epic/Issue/Task Lists**: <50ms (was 3-8 seconds)
- **PR Operations**: <100ms average
- **Search Operations**: Instant (<1ms)
- **Project Initialization**: <200ms

#### **Scalability**
- **Large Projects**: Tested with 1000+ items
- **Memory Usage**: <5MB for large projects
- **Index File Size**: <1MB for 1000+ items
- **Concurrent Operations**: Safe multi-user access

## [2.0.0] - 2025-07-08

### Major Release - Complete Internal PR Management System

**BREAKING CHANGES**: Major version bump introducing comprehensive Pull Request management capabilities

### Added

#### **Complete PR Management System - 12 New Commands**
- **`aitrackdown pr create`** - Create new PR from templates with auto-linking to tasks/issues
- **`aitrackdown pr list`** - List PRs with advanced filtering and status-based views
- **`aitrackdown pr show <id>`** - Display comprehensive PR details with relationships
- **`aitrackdown pr update <id>`** - Update PR properties, assignees, and metadata
- **`aitrackdown pr review <id>`** - Create structured PR reviews with approval tracking
- **`aitrackdown pr approve <id>`** - Formally approve PRs with optional auto-merge
- **`aitrackdown pr merge <id>`** - Merge PRs with multiple strategies (merge/squash/rebase)
- **`aitrackdown pr close <id>`** - Close PRs without merging with reason tracking
- **`aitrackdown pr batch`** - Perform bulk operations on multiple PRs
- **`aitrackdown pr dependencies`** - Manage PR dependencies and relationship chains
- **`aitrackdown pr sync`** - Synchronize PRs with external systems (GitHub integration)
- **`aitrackdown pr archive`** - Archive old PRs with compression and external storage

#### **GitHub-Independent PR System**
- **File-based PR Storage**: Complete PR lifecycle management using local files
- **Status-based Organization**: Automatic file movement based on PR status (draft → open → review → approved → merged/closed)
- **Template Integration**: Full and quick PR templates with variable substitution
- **Relationship Management**: Link PRs to tasks, issues, and other PRs
- **Review System**: Structured review process with approval tracking

#### **Agent-Optimized Workflows**
- **Batch PR Creation**: Create multiple PRs from completed tasks with smart grouping
- **Auto-linking**: Intelligent task-PR associations based on completion status
- **Template Population**: Pre-fill PR templates with task/issue metadata
- **Token Usage Tracking**: Monitor AI token consumption for PR operations
- **Memory-efficient Operations**: Optimized for large-scale PR management

#### **Advanced PR Features**
- **Dependency Management**: Track PR dependencies and validate dependency chains
- **Multiple Merge Strategies**: Support for merge, squash, and rebase operations
- **Conditional Approvals**: Approval with conditions for minor fixes
- **Review Templates**: Security, performance, and general review templates
- **Batch Operations**: Efficient bulk approve, merge, and close operations
- **Archive System**: Compress and store old PRs with configurable retention

#### **Performance Optimizations**
- **Fast Command Response**: PR operations complete in 60-70ms average
- **Efficient File Operations**: Optimized directory scanning and file management
- **Memory Management**: <50MB memory usage for large PR repositories
- **Batch Processing**: <1s per 10 PRs for bulk operations
- **Intelligent Caching**: Reduce redundant file system operations

#### **New Directory Structure**
```
project/
├── prs/
│   ├── draft/           # Draft PRs
│   ├── active/
│   │   ├── open/        # Open PRs ready for review
│   │   ├── review/      # PRs under review
│   │   └── approved/    # Approved PRs ready to merge
│   ├── merged/          # Successfully merged PRs
│   ├── closed/          # Closed/rejected PRs
│   ├── reviews/         # PR review files
│   └── logs/            # Operation logs
└── templates/
    ├── pr-review-default.yaml
    ├── pr-review-quick.yaml
    └── pr-review-security.yaml
```

### Changed

#### **Enhanced CLI Interface**
- **New Command Namespace**: Complete `aitrackdown pr` command suite
- **Rich Terminal Output**: Enhanced formatting for PR status and information
- **Advanced Filtering**: Support for complex PR filtering by status, assignee, priority, dates
- **Multiple Output Formats**: Table, JSON, CSV, and Markdown output options
- **Progress Indicators**: Real-time feedback for long-running operations

#### **Configuration Extensions**
- **PR Directory Configuration**: Configurable PR storage location via `prs_dir` setting
- **Template Configuration**: Customizable PR template locations and naming
- **Merge Strategy Defaults**: Configurable default merge strategies per project
- **Review Requirements**: Configurable approval requirements and review processes

#### **Integration Enhancements**
- **Task-PR Synchronization**: Automatic status synchronization between tasks and PRs
- **Issue Linking**: Enhanced issue-PR relationship management
- **Epic Integration**: Connect PRs to epics through issue relationships
- **GitHub Sync**: Optional GitHub integration for external synchronization

### Technical Improvements

#### **Architecture Enhancements**
- **Modular Command Structure**: Clean separation of PR command implementations
- **File Management System**: Robust PR file manager with atomic operations
- **Status Management**: State machine-based PR status transitions
- **Relationship Engine**: Advanced relationship tracking and validation
- **Template Engine**: Flexible template system with variable substitution

#### **Quality Assurance**
- **Comprehensive Test Suite**: 170+ automated test cases for PR functionality
- **90%+ Test Coverage**: High test coverage for PR management code
- **Performance Benchmarks**: Automated performance testing and monitoring
- **Error Handling**: Graceful error handling for all edge cases
- **Input Validation**: Robust validation for all PR operations

#### **Documentation**
- **Complete PR Commands Guide**: Comprehensive documentation for all PR commands
- **Workflow Examples**: Real-world usage patterns and best practices
- **API Reference**: Complete command reference with examples
- **Migration Guide**: Instructions for upgrading from previous versions

### Performance Metrics

#### **Response Times**
- **PR Creation**: < 200ms (template-based)
- **PR Listing**: < 100ms (up to 100 PRs)
- **PR Details**: < 50ms (individual PR)
- **Batch Operations**: < 1s per 10 PRs
- **Status Updates**: < 100ms (with file movement)

#### **Scalability**
- **Large Repositories**: Tested with 1000+ PRs
- **Memory Efficiency**: < 50MB for PR operations
- **Concurrent Operations**: Safe multi-agent PR management
- **File System**: Efficient directory organization and scanning

### Migration Notes

#### **New Dependencies**
- No new external dependencies required
- All PR functionality built on existing foundation
- Backward compatible with existing projects

#### **Configuration Changes**
- New optional `prs_dir` configuration setting
- Enhanced project initialization to create PR directories
- Existing configurations remain fully compatible

#### **Breaking Changes**
- None - This is a major version bump for significant new functionality
- All existing commands and functionality remain unchanged
- PR commands are additive to existing feature set

### Developer Experience

#### **CLI Enhancements**
- **Intuitive Command Structure**: Follow GitHub CLI patterns for familiarity
- **Rich Help System**: Comprehensive help text with examples
- **Interactive Prompts**: Guided PR creation and management
- **Dry Run Mode**: Preview operations before execution
- **Verbose Output**: Detailed operation feedback when needed

#### **Agent Integration**
- **Batch Workflows**: Efficient bulk operations for agent-driven development
- **Smart Defaults**: Intelligent default values based on context
- **Token Optimization**: Minimize AI token usage for PR operations
- **Memory Management**: Efficient memory usage for large-scale operations
- **Progress Tracking**: Real-time feedback for long-running operations

## [1.0.1] - 2025-07-08

### ATT-004: Fix Task Directory Structure - Single Root Directory Implementation

### Added
- **Unified Directory Structure**: All task types now organized under single configurable root directory (default: `tasks/`)
- **Configurable Tasks Directory**: New `tasks_directory` configuration option in config.yaml
- **CLI Directory Options**: Added `--tasks-dir` and `--root-dir` CLI options for runtime override
- **Migration Utility**: New `migrate-structure` command to migrate legacy projects
- **Priority Resolution**: CLI > ENV > CONFIG > DEFAULT priority for directory configuration
- **Pull Request Support**: Added PR directory and prefix support in configuration

### Changed
- **Directory Structure**: Changed from separate root directories (epics/, issues/, tasks/) to unified structure (tasks/epics/, tasks/issues/, tasks/tasks/)
- **Path Resolution**: Implemented UnifiedPathResolver for consistent path handling
- **Configuration Schema**: Updated ProjectConfig interface with tasks_directory and prs_dir fields

### Fixed
- **Legacy Compatibility**: Existing projects continue to work with automatic structure detection
- **Command Integration**: All create commands now use unified directory structure
- **Template Loading**: Templates now load from unified structure paths

## [1.0.0] - 2025-07-08

### Major Release - Complete Redesign for ai-trackdown Compliance

**BREAKING CHANGES**: Complete architectural redesign for ai-trackdown framework compliance

### Added
- **AI-First Architecture**: Complete YAML frontmatter support for Epic/Issue/Task hierarchy
- **Token Tracking System**: Comprehensive token usage monitoring and budget management
- **AI Context Generation**: Automatic llms.txt generation for AI workflows
- **Template System**: Configurable project templates and initialization
- **Hierarchical Relationships**: Epic → Issue → Task relationship management
- **Migration Tools**: Convert legacy projects to ai-trackdown format
- **Professional CLI Interface**: Complete command structure with help system
- **Configuration System**: `.ai-trackdown/config.yaml` project configuration

### Removed
- **Legacy Commands**: Simplified to focus on ai-trackdown core functionality
- **External Dependencies**: Now operates with zero external API requirements

### Changed
- **Project Structure**: New `epics/issues/tasks/` directory structure (BREAKING)
- **Data Format**: YAML frontmatter replaces JSON data files (BREAKING)
- **Command Interface**: Complete redesign of all CLI commands (BREAKING)
- **Configuration**: `.ai-trackdown/config.yaml` replaces `.trackdownrc.json` (BREAKING)

### Technical Improvements
- **Git-Native Storage**: Local file operations with version control integration
- **Type Safety**: Complete TypeScript implementation
- **Performance**: Fast CLI startup and efficient file operations
- **Build System**: Clean build configuration with proper module bundling
- **Testing**: Comprehensive verification and quality assurance

## [0.3.0] - 2025-07-07

### Changed - CLI Rename and Alias Update
- **BREAKING CHANGE**: Renamed main CLI command from `trackdown` to `aitrackdown`
- **BREAKING CHANGE**: Renamed short alias from `td` to `atd` 
- Updated all command examples and help text throughout the codebase
- Updated package.json bin configuration for new command names
- Enhanced README with migration instructions and quick start guide

### Migration
- Replace `trackdown` commands with `aitrackdown` 
- Replace `td` alias with `atd`
- All functionality remains identical, only command names changed
- Example: `trackdown issue list` → `aitrackdown issue list` or `atd issue list`

### Technical Changes
- Updated Commander.js program name configuration
- Updated all help text and error messages
- Updated validation rules for reserved command names
- Maintained backward compatibility in configuration file formats

### Documentation
- Added comprehensive migration guide in README
- Updated installation and usage instructions
- Added quick start examples with new command syntax
- Documented both full (`aitrackdown`) and short (`atd`) command aliases

## [0.2.0] - 2025-07-07

### Added - GitHub Issues API Complete Parity (Phase 1)
- **Complete Issue Management System**
  - Full CRUD operations: create, list, show, update, close, reopen, delete
  - Advanced filtering and sorting with GitHub-compatible syntax
  - GitHub-compatible search with complex query parsing
  - State management with state_reason tracking (completed, not_planned, reopened)
  - Bulk operations and batch processing capabilities

- **Professional Label Management**
  - Complete label CRUD operations with color and description support
  - Label application and removal from issues
  - Interactive label creation with preset color schemes
  - Usage statistics and impact analysis
  - Label validation and conflict resolution

- **Advanced Search and Filtering**
  - GitHub-compatible search query parser supporting complex syntax
  - Date range filtering with relative and absolute dates
  - Multi-field search (title, body, comments)
  - Number-based filtering (comments, reactions, interactions)
  - Boolean and negation operators

- **GitHub API Integration**
  - Complete GitHub REST API v4 compatibility
  - Authentication with GitHub tokens
  - Rate limiting management and optimization
  - Error handling with actionable suggestions
  - Repository auto-detection and configuration

- **Professional CLI Interface**
  - Rich terminal output with colored formatting
  - Multiple output formats: table, JSON, YAML, CSV
  - Progress indicators and real-time feedback
  - Interactive prompts for complex operations
  - Comprehensive help system with examples

- **Type Safety and Validation**
  - Complete TypeScript type definitions for GitHub API
  - Input validation with helpful error messages
  - Schema validation for complex operations
  - Type-safe command options and parameters

### Technical Implementation
- Comprehensive GitHub API client with rate limiting
- Advanced search query parser for GitHub-compatible syntax
- Professional output formatters with multiple format support
- Robust error handling with contextual suggestions
- Modular command architecture for extensibility

### Performance Optimizations
- Efficient API request batching
- Intelligent caching strategies
- Optimized pagination handling
- Memory-efficient large dataset processing

## [0.1.1] - 2025-07-07

## [0.1.0] - 2025-07-07

### Added
- Initial CLI foundation with core commands
- Project initialization and configuration (`trackdown init`)
- Status reporting and task tracking (`trackdown status`)
- Export functionality for issues and tasks (`trackdown export`)
- Task tracking functionality (`trackdown track`)
- Complete semantic versioning system with automated management
- Version management commands (`trackdown version`)
- Automated changelog generation following Keep a Changelog format
- Git integration with tagging and commit automation
- Cross-file version synchronization
- Conventional commit parsing for changelog entries
- Professional CLI interface with colored output and help system

### Changed
- N/A (Initial release)

### Fixed
- N/A (Initial release)

[0.1.0]: https://github.com/user/ai-trackdown-tools/releases/tag/v0.1.0