markitect-main/.clinerules

# MarkiTect Project - Claude Code Rules
# =====================================
# Guidelines for Claude Code when working with the MarkiTect project
# This project follows TDD8 methodology with Clean Architecture

## Project Overview
This is a high-performance markdown processing engine with database integration,
AST-based parsing, and sophisticated caching. The project follows Clean Architecture
principles with strict separation of concerns.

## Directory Structure & Clean Architecture
```
markitect-main/
├── domain/          # Business logic (innermost layer)
├── application/     # Use cases and workflows
├── infrastructure/ # External interfaces (database, file system)
├── cli/            # Presentation layer (CLI interface)
├── markitect/      # Core markdown processing engine
├── tests/          # Comprehensive test suite (TDD8 methodology)
├── docs/           # Architecture and user documentation
└── tddai/          # TDD workflow tools and utilities
```

## Core Principles

### 1. TDD8 Methodology - ALWAYS FOLLOW
1. **ISSUE**: Analyze GitHub issue and extract requirements
2. **TEST**: Write comprehensive tests BEFORE implementation
3. **RED**: Ensure tests fail initially (validate test correctness)
4. **GREEN**: Implement minimum viable solution to pass tests
5. **REFACTOR**: Improve code quality and design
6. **DOCUMENT**: Update documentation and examples
7. **REFINE**: Performance optimization and edge cases
8. **PUBLISH**: Integration validation and delivery

### 2. Clean Architecture Dependency Rules
- **NEVER violate dependency inversion**: Outer layers depend on inner layers, never reverse
- **Domain layer**: Pure business logic, no external dependencies
- **Application layer**: Use cases, may depend only on domain
- **Infrastructure layer**: External concerns (database, CLI, API)
- **Presentation layer**: User interfaces (CLI commands)

### 3. Testing Requirements
- **Minimum 80% test coverage** - Use `pytest --cov=markitect --cov-report=html`
- **Test naming**: `test_issue_{issue_num}_{scenario}.py` pattern
- **Architectural testing**: Run tests by layer (`make test-domain`, `make test-infrastructure`)
- **Performance validation**: All cache operations must be <50% of parsing time
- **TDD workspace**: Use `.tddai_workspace/` for issue-specific development

## Development Workflow

### Starting Work on an Issue
```bash
# Always start with TDD workspace
make tdd-start NUM=<issue_number>

# Analyze requirements first
make validate-requirements

# Create tests before implementation
make tdd-add-test
```

### Code Quality Gates
```bash
# Run before any commit
make test                    # All tests must pass
make lint                   # Code style compliance
make test-coverage NUM=X    # Verify coverage targets
make validate-mocks         # Mock compatibility
```

### Performance Requirements
- **Cache operations**: <50% of initial parsing time (enforced by tests)
- **Memory usage**: <50MB baseline for normal operations
- **Database queries**: Sub-millisecond metadata retrieval
- **Bulk operations**: Linear scaling with document count

## Technology Stack & Dependencies

### Core Technologies
- **Python 3.8+** with type hints (gradual mypy adoption)
- **SQLite** for database operations (ACID compliance required)
- **markdown-it-py** for AST processing
- **pytest** for testing with comprehensive fixtures
- **Click** for CLI framework

### Key Libraries
- `PyYAML` - Front matter processing
- `jsonpath-ng` - AST querying
- `tabulate` - Output formatting
- `aiohttp` - Async HTTP operations

## Coding Standards

### Python Code Style
- **Type hints**: Use where possible (gradual mypy adoption)
- **Docstrings**: Required for all public methods
- **Error handling**: Comprehensive exception handling and validation
- **Security**: Never log secrets, validate all inputs, prevent SQL injection

### File Organization
- **One concept per file**: Clear separation of responsibilities
- **Interface segregation**: Clean interfaces between layers
- **Plugin architecture**: Support modular extensions

### Database Operations
- **Read-only queries**: Default to safe operations
- **Transaction safety**: Use ACID compliance for batch operations
- **Performance optimization**: Leverage SQLite capabilities
- **Migration support**: Schema versioning and updates

## Common Patterns

### CLI Command Structure
```python
@click.command()
@click.option('--format', type=click.Choice(['table', 'json', 'yaml']))
def command_name(format):
    """Command description with clear purpose."""
    try:
        # Implementation with proper error handling
        pass
    except SpecificException as e:
        # Provide helpful error messages
        pass
```

### Test Structure (TDD8 Pattern)
```python
class TestIssue{N}_{Description}:
    """Test suite for issue #{N}: {description}"""

    def test_{scenario}_success(self):
        """Test successful operation scenario."""
        # Arrange
        # Act
        # Assert

    def test_{scenario}_error_handling(self):
        """Test error handling scenario."""
        # Test edge cases and error conditions
```

### Domain Model Pattern
```python
from dataclasses import dataclass
from typing import Optional

@dataclass
class DomainEntity:
    """Domain entity with business logic."""
    id: str
    name: str

    def business_method(self) -> bool:
        """Business logic belongs in domain layer."""
        return True
```

## Performance Guidelines

### AST Caching System
- **Cache validation**: Automatic timestamp-based invalidation
- **Serialization**: Optimized JSON format for AST storage
- **Memory management**: Careful resource cleanup
- **Performance contracts**: <50% of parsing time (tested)

### Database Optimization
- **Query optimization**: Use appropriate indexes
- **Batch operations**: Minimize database round trips
- **Connection management**: Proper connection lifecycle
- **Read-only defaults**: Safety-first approach

## Security Requirements

### Input Validation
- **SQL injection prevention**: Use parameterized queries
- **Path traversal protection**: Validate file paths
- **Command injection**: Sanitize shell command inputs
- **YAML safety**: Safe loading of front matter

### Secrets Management
- **Never log secrets**: Authentication tokens, passwords
- **Environment variables**: Use for sensitive configuration
- **Git repository**: Never commit credentials
- **Error messages**: Don't expose sensitive information

## Documentation Standards

### Code Documentation
- **API documentation**: Clear method signatures and purposes
- **Architecture decisions**: Document in docs/architecture/
- **Usage examples**: Include practical examples
- **Performance notes**: Document performance characteristics

### User Documentation
- **CLI help**: Comprehensive command documentation
- **Configuration**: Clear setup instructions
- **Troubleshooting**: Common issues and solutions
- **Performance**: Usage optimization guidelines

## Integration Points

### Git Platform Integration
- **Gitea API**: Primary integration for issue management
- **GitHub compatibility**: Support multiple platforms
- **Authentication**: Token-based with multiple sources
- **Error handling**: Robust network failure handling

### Development Tools
- **Makefile integration**: Standard development commands
- **pytest integration**: Comprehensive test framework
- **mypy integration**: Gradual type checking adoption
- **CLI tools**: Complete command-line interface

## Common Mistakes to Avoid

### Architecture Violations
- ❌ **Domain depending on infrastructure**: Never import database in domain
- ❌ **Skipping tests**: Never implement without tests first (TDD8)
- ❌ **Performance assumptions**: Always validate cache performance
- ❌ **Direct database access**: Use repository pattern

### Security Issues
- ❌ **SQL injection**: Always use parameterized queries
- ❌ **Logging secrets**: Never log authentication tokens
- ❌ **Unsafe YAML**: Use yaml.safe_load() not yaml.load()
- ❌ **Path injection**: Validate and sanitize file paths

### Testing Issues
- ❌ **Insufficient coverage**: Maintain >80% test coverage
- ❌ **Missing edge cases**: Test error conditions thoroughly
- ❌ **Test dependencies**: Tests must be independent
- ❌ **Performance tests**: Validate cache performance contracts

## When Making Changes

### Before Implementation
1. **Read the issue**: Understand requirements completely
2. **TDD workspace**: Use `make tdd-start NUM=X`
3. **Write tests first**: Follow TDD8 methodology strictly
4. **Validate architecture**: Ensure clean dependency flow

### During Implementation
1. **Red-Green-Refactor**: Follow TDD cycle religiously
2. **Performance validation**: Test cache performance contracts
3. **Security review**: Validate input handling and safety
4. **Documentation updates**: Keep docs current with changes

### Before Completion
1. **Full test suite**: `make test` must pass completely
2. **Performance benchmarks**: Validate performance requirements
3. **Code quality**: `make lint` and type checking
4. **Integration tests**: Verify end-to-end functionality

## Emergency Procedures

### If Tests Fail
1. **Don't ignore**: Never commit with failing tests
2. **Isolate issue**: Use `make test-module MODULE=name`
3. **Check dependencies**: Verify layer boundary violations
4. **Performance regression**: Check cache performance contracts

### If Performance Degrades
1. **Run benchmarks**: Use performance test suite
2. **Cache validation**: Verify cache hit rates and timing
3. **Memory profiling**: Check for memory leaks
4. **Database optimization**: Review query performance

### If Security Issues Found
1. **Immediate assessment**: Evaluate impact and scope
2. **Input validation**: Review all user input handling
3. **Secrets audit**: Check for credential exposure
4. **Dependency updates**: Update vulnerable dependencies

Remember: This project's success depends on maintaining architectural discipline,
comprehensive testing, and performance contracts. When in doubt, ask for clarification
and always prioritize correctness over speed of implementation.