crackerjack 0.31.10__py3-none-any.whl → 0.31.12__py3-none-any.whl

crackerjack/CLAUDE.md

@@ -6,18 +6,95 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 **EVERY LINE OF CODE IS A LIABILITY. The best code is no code.**
 
-- **DRY (Don't Repeat Yourself)**: If you write it twice, you're doing it wrong
-- **YAGNI (You Ain't Gonna Need It)**: Build only what's needed NOW
-- **KISS (Keep It Simple, Stupid)**: Complexity is the enemy of maintainability
-- **Less is More**: Prefer 10 lines that are clear over 100 that are clever
+- **DRY**: If you write it twice, you're doing it wrong
+- **YAGNI**: Build only what's needed NOW
+- **KISS**: Complexity is the enemy of maintainability
+- **Less is More**: Prefer 10 clear lines over 100 clever ones
 - **Code is Read 10x More Than Written**: Optimize for readability
-- **Self-Documenting Code**: Code should explain itself; comments only for "why", not "what". Variable names should **ALWAYS** be clear and descriptive, even in inline map/filter functions.
+- **Self-Documenting Code**: Variable names must be clear and descriptive, even in inline functions
+
+## Design Philosophy
+
+- **Auto-Discovery**: Prefer intelligent auto-discovery of configurations and settings over manual configuration whenever possible, reducing setup friction and configuration errors
 
 ## Project Overview
 
-Crackerjack is an opinionated Python project management tool that unifies UV, Ruff, pytest, and pre-commit into a single workflow. It enforces consistent code quality from setup to deployment and includes AI agent integration via MCP (Model Context Protocol).
+Crackerjack is an opinionated Python project management tool unifying UV, Ruff, pytest, and pre-commit into a single workflow. Enforces consistent code quality with AI agent integration via MCP.
+
+**Key Dependencies**: Python 3.13+, UV, pre-commit, pytest
+
+## AI-Optimized Documentation
+
+**For AI assistants, refer to these structured documentation files:**
 
-**Key Dependencies**: Python 3.13+, UV package manager, pre-commit hooks, pytest
+- **[AI-REFERENCE.md](AI-REFERENCE.md)** - Complete AI command reference with decision trees and lookup tables
+- **[AGENT-CAPABILITIES.json](AGENT-CAPABILITIES.json)** - Structured agent data for automated selection
+- **[ERROR-PATTERNS.yaml](ERROR-PATTERNS.yaml)** - Pattern matching rules for automated issue resolution
+
+These files provide parseable formats, decision trees, and structured data optimized for AI understanding and autonomous operation.
+
+## Quick Reference
+
+### Most Used Commands
+
+```bash
+# Daily development workflow
+python -m crackerjack                      # Quality checks only
+python -m crackerjack -t                   # With tests
+python -m crackerjack --ai-agent -t        # AI auto-fixing (recommended)
+
+# Debugging and monitoring
+python -m crackerjack --ai-debug -t        # AI debug mode with verbose output
+python -m crackerjack --enhanced-monitor   # Progress monitor with advanced UI
+python -m crackerjack --watchdog           # Auto-restart services monitor
+
+# Server management
+python -m crackerjack --start-mcp-server      # Start MCP server
+python -m crackerjack --start-websocket-server # Start WebSocket server
+python -m crackerjack --restart-mcp-server    # Restart MCP server
+
+# Release workflow
+python -m crackerjack --bump patch         # Version bump only
+python -m crackerjack -a patch              # Full release with publishing
+```
+
+### Common Flags
+
+| Flag | Purpose | When to Use |
+|------|---------|-------------|
+| `-t` | Include tests | Always for comprehensive validation |
+| `--ai-agent` | Enable AI auto-fixing | Standard process for quality compliance |
+| `--ai-debug` | Verbose AI debugging | When troubleshooting AI agent issues |
+| `-x` | Code cleaning mode | When ready to resolve all TODOs |
+| `-i` | Interactive mode | For step-by-step workflow control |
+| `--skip-hooks` | Skip pre-commit hooks | During rapid development iterations |
+| `--quick` | Quick mode (3 iterations) | CI/CD pipelines or rapid testing |
+| `--thorough` | Thorough mode (8 iterations) | Complex refactoring or difficult issues |
+| `--verbose` | Extra output | When diagnosing issues |
+
+### Agent Selection Guide
+
+**When to Use Which Specialist Agent:**
+
+| Issue Type | Best Agent | Confidence | Use Case |
+|------------|------------|------------|----------|
+| **Documentation inconsistencies** | DocumentationAgent | 0.8 | Changelog updates, .md file consistency |
+| **Cognitive complexity >15** | RefactoringAgent | 0.9 | Breaking down complex functions |
+| **Unused imports/dead code** | RefactoringAgent | 0.8 | AST-based cleanup |
+| **Performance bottlenecks** | PerformanceAgent | 0.85 | O(n²) loops, string concatenation |
+| **Code duplication** | DRYAgent | 0.8 | Extract common patterns |
+| **Import/formatting issues** | FormattingAgent | 0.8 | Code style violations |
+| **Security vulnerabilities** | SecurityAgent | 0.8 | Hardcoded paths, unsafe operations |
+| **Test failures** | TestCreationAgent | 0.8 | Missing fixtures, assertion issues |
+| **Complex test scenarios** | TestSpecialistAgent | 0.8 | Advanced test frameworks |
+
+**Decision Tree:**
+
+1. **Type errors?** → Use AI agent auto-fixing (handles all types)
+1. **Single issue type?** → Use specific agent with confidence ≥0.7
+1. **Multiple issue types?** → Use AI agent batch fixing
+1. **Documentation issues?** → Always use DocumentationAgent
+1. **Performance issues?** → Always use PerformanceAgent (real code transformation)
 
 ## Core Development Commands
 
@@ -31,6 +108,7 @@ python -m crackerjack
 python -m crackerjack -t
 
 # Code cleaning with TODO detection (blocks if TODOs found)
+# Note: Automatically creates backups in temp directory for safety
 python -m crackerjack -x
 
 # Full release workflow with version bump and publishing
@@ -48,6 +126,12 @@ python -m crackerjack --ai-agent -t
 # AI Agent mode with full debugging and verbose output
 python -m crackerjack --ai-debug -t
 
+# Quick mode (3 iterations) - ideal for CI/CD
+python -m crackerjack --quick --ai-agent -t
+
+# Thorough mode (8 iterations) - for complex refactoring
+python -m crackerjack --thorough --ai-agent -t
+
 # Start MCP server for AI agent integration
 python -m crackerjack --start-mcp-server
 
@@ -101,200 +185,50 @@ reset
 
 ### AI Agent Auto-Fixing Process
 
-**The AI agent provides intelligent, autonomous code fixing that goes far beyond basic tool auto-fixes:**
-
-#### Two Types of Auto-Fixing
-
-**1. Hook Auto-Fix Modes (Limited Scope)**
-
-- Basic formatting tools like `ruff --fix`, `trailing-whitespace --fix`
-- Only handle simple style issues (whitespace, import order, basic formatting)
-- Cannot fix logic errors, type issues, security problems, or test failures
+**Two Types of Auto-Fixing:**
 
-**2. AI Agent Auto-Fixing (Comprehensive Intelligence)**
+**1. Hook Auto-Fix (Limited)**: Basic formatting (`ruff --fix`, whitespace). Cannot fix logic/security/test issues.
 
-- Analyzes ALL error types: hooks, tests, type checking, security, complexity
-- Reads source code, understands context, and makes intelligent modifications
-- Fixes actual bugs, adds missing type annotations, resolves test failures
-- Handles complex issues that require code understanding and logic changes
+**2. AI Agent (Comprehensive)**: Analyzes ALL error types, reads source code, makes intelligent modifications.
 
-#### Standard AI Agent Iterative Process
-
-**This is the recommended standard process for achieving code quality compliance:**
+#### Standard Process
 
 ```bash
-# AI Agent mode with automatic fixing between iterations
+# Recommended workflow
 python -m crackerjack --ai-agent -t
 
-# The AI agent follows this optimal workflow order in each iteration:
-# 1. Fast Hooks (formatting) → Retry once if any fail (fixes often cascade)
-# 2. Full Test Suite → Collect ALL test failures (don't stop on first)
-# 3. Comprehensive Hooks → Collect ALL quality issues (don't stop on first)
-# 4. AI Analysis & Batch Fixing → Fix ALL collected issues in one pass
-# 5. Repeat entire cycle until all checks pass (up to 10 iterations)
-
-# CRITICAL: The AI agent only moves to the next iteration AFTER applying fixes
-# This ensures that each iteration validates the fixes from the previous iteration
+# AI workflow per iteration:
+# 1. Fast Hooks → Retry once if fail
+# 2. Full Test Suite → Collect ALL failures
+# 3. Comprehensive Hooks → Collect ALL issues
+# 4. AI Batch Fixing → Fix ALL collected issues
+# 5. Repeat until perfect (up to 5 iterations)
 ```
 
-**What the AI Agent Auto-Fixes:**
-
-- **Type Errors**: Adds missing type annotations, fixes type mismatches
-- **Security Issues**: Removes hardcoded paths, fixes subprocess vulnerabilities
-- **Dead Code**: Removes unused imports, variables, and functions
-- **Test Failures**: Fixes missing fixtures, import errors, assertion issues
-- **Code Quality**: Applies refactoring suggestions, reduces complexity
-- **Dependency Issues**: Removes unused dependencies from pyproject.toml
-- **Hook Failures**: All formatting, linting, and style issues
+**AI Auto-Fixes**: Type errors, security issues, dead code, test failures, complexity, dependencies, hooks
 
-**Benefits of AI Agent Auto-Fixing:**
-
-- **Autonomous Operation**: Requires no manual intervention
-- **Intelligent Analysis**: Understands code context and intent
-- **Comprehensive Coverage**: Fixes all error types, not just formatting
-- **Iterative Improvement**: Continues until perfect code quality achieved
-- **Learning Capability**: Adapts fixing strategies based on codebase patterns
+**Benefits**: Autonomous, intelligent, comprehensive, iterative, adaptive
 
 #### Sub-Agent Architecture
 
-**Crackerjack uses specialized sub-agents for domain-specific code quality issues:**
-
-**Available Sub-Agents:**
-
-- **DocumentationAgent**: Documentation consistency and changelog management
-
-  - **Primary Expertise**: `IssueType.DOCUMENTATION` (documentation consistency, changelog updates)
-  - **Capabilities**:
-    - Auto-generates changelog entries from git commits during version bumps
-    - Maintains consistency across all .md files (agent counts, references)
-    - Updates README examples when APIs change
-    - Adds newly discovered error patterns to CLAUDE.md
-    - Cross-validates documentation references
-    - Integrates with publish workflow for automatic changelog updates
-  - **Philosophy Alignment**: Reduces manual documentation maintenance (YAGNI principle)
-  - **Confidence**: 0.8 for documentation issues
-
-- **RefactoringAgent**: Structural code improvements and complexity reduction
-
-  - **Primary Expertise**: `IssueType.COMPLEXITY` (cognitive complexity ≤13)
-  - **Secondary Expertise**: `IssueType.DEAD_CODE` (unused imports, variables, functions)
-  - **Capabilities**:
-    - Breaks down complex functions into helper methods
-    - Removes unused imports, variables, and functions using AST analysis
-    - Extracts common patterns into reusable utilities
-    - Applies dependency injection and Protocol patterns
-  - **Philosophy Alignment**: Perfect fit with DRY, YAGNI, KISS principles
-
-- **PerformanceAgent**: Performance optimization and algorithmic improvements
-
-  - **Primary Expertise**: `IssueType.PERFORMANCE` (performance anti-patterns and bottlenecks)
-  - **Capabilities**:
-    - Detects and fixes nested loops with O(n²) complexity
-    - Transforms inefficient list concatenation (`list += [item]` → `list.append(item)`)
-    - Optimizes string building (concatenation → list.append + join pattern)
-    - Identifies repeated expensive operations in loops (file I/O, function calls)
-    - Applies AST-based pattern recognition for accurate detection
-    - **Real Code Transformation**: Actually modifies code, not just comments
-  - **Philosophy Alignment**: KISS principle through algorithmic efficiency
-
-- **DRYAgent**: Don't Repeat Yourself violation detection and fixing
-
-  - **Primary Expertise**: `IssueType.DRY_VIOLATION` (code duplication and repetition)
-  - **Capabilities**:
-    - Detects duplicate code patterns and repeated functionality
-    - Suggests extracting common patterns to utility functions
-    - Recommends creating base classes or mixins for repeated functionality
-    - Identifies opportunities for code consolidation and refactoring
-  - **Philosophy Alignment**: Core DRY principle enforcement
-
-- **FormattingAgent**: Code style and formatting issues
-
-  - **Primary Expertise**: `IssueType.FORMATTING`, `IssueType.IMPORT_ERROR`
-  - **Capabilities**:
-    - Handles code style and formatting violations
-    - Fixes import-related formatting issues
-    - Ensures consistent code formatting standards
-
-- **SecurityAgent**: Security vulnerabilities and best practices
-
-  - **Primary Expertise**: `IssueType.SECURITY`
-  - **Capabilities**:
-    - Detects and fixes security vulnerabilities (hardcoded paths, unsafe operations)
-    - Applies security best practices
-    - Identifies potential security risks in code patterns
-
-- **ImportOptimizationAgent**: Import statement optimization and cleanup
-
-  - **Primary Expertise**: `IssueType.IMPORT_ERROR`, `IssueType.DEAD_CODE`
-  - **Capabilities**:
-    - Optimizes import statements and organization
-    - Removes unused imports and dead code
-    - Consolidates and reorganizes import patterns
-    - **Real Code Transformation**: Restructures import statements
-
-- **TestCreationAgent**: Test coverage and quality improvements
-
-  - **Primary Expertise**: `IssueType.TEST_FAILURE`, `IssueType.DEPENDENCY`
-  - **Capabilities**:
-    - Fixes test failures and missing test dependencies
-    - Improves test coverage and quality
-    - Handles dependency-related testing issues
-
-- **TestSpecialistAgent**: Advanced testing scenarios and fixtures
-
-  - **Primary Expertise**: `IssueType.IMPORT_ERROR`, `IssueType.TEST_FAILURE`
-  - **Capabilities**:
-    - Handles complex testing scenarios and fixture management
-    - Fixes advanced test failures and import issues in test files
-    - Specializes in testing framework integration
-
-**Agent Coordination:**
-
-- **AgentCoordinator** routes issues to appropriate agents based on confidence scoring
-- **Single-agent mode**: High confidence (≥0.7) issues handled by best-match agent
-- **Collaborative mode**: Lower confidence issues processed by multiple agents
-- **Batch processing**: Issues grouped by type for efficient parallel processing
-
-**Agent Integration:**
+**9 specialized agents handle domain-specific issues:**
 
-```python
-# Automatic integration - all agents are registered and coordinated
-# 9 total agents: DocumentationAgent, RefactoringAgent, PerformanceAgent, FormattingAgent,
-#                SecurityAgent, TestCreationAgent, TestSpecialistAgent, ImportOptimizationAgent, DRYAgent
-
-# Agent confidence scoring examples:
-# DocumentationAgent:
-# - 0.8 confidence for documentation issues (primary expertise)
-# RefactoringAgent:
-# - 0.9 confidence for complexity issues (primary expertise)
-# - 0.8 confidence for dead code issues (secondary expertise)
-# PerformanceAgent:
-# - 0.85 confidence for performance issues (primary expertise)
-# - Real code transformations with AST-based detection
-
-# Works with all agents for comprehensive code quality fixes
-```
-
-### Temporary File Management
+- **DocumentationAgent** (0.8): Changelog generation, .md consistency, README updates
+- **RefactoringAgent** (0.9): Complexity reduction ≤15, dead code removal, AST analysis
+- **PerformanceAgent** (0.85): O(n²) detection, string optimization, real code transformation
+- **DRYAgent** (0.8): Code duplication detection, pattern extraction, utility creation
+- **FormattingAgent** (0.8): Style violations, import formatting, consistency
+- **SecurityAgent** (0.8): Hardcoded paths, subprocess vulnerabilities, best practices
+- **ImportOptimizationAgent**: Import cleanup, dead code removal, reorganization
+- **TestCreationAgent** (0.8): Test failures, fixture management, dependencies
+- **TestSpecialistAgent** (0.8): Advanced testing, framework integration
 
-**Crackerjack automatically manages temporary files created during execution:**
+**Coordination**: AgentCoordinator routes by confidence (≥0.7 single-agent, \<0.7 collaborative), batch processing
 
-```bash
-# Default behavior (recommended)
-python -m crackerjack  # Auto-cleanup: keeps 5 debug logs, 10 coverage files
-
-# Customize cleanup behavior
-python -m crackerjack --no-cleanup  # Disable automatic cleanup
-python -m crackerjack --keep-debug-logs 10  # Keep more debug files
-python -m crackerjack --keep-coverage-files 20  # Keep more coverage files
-```
-
-**Files managed:**
-
-- `crackerjack-debug-*.log` - Debug logs from each run (default: keep 5 most recent)
-- `.coverage.*` - Coverage data files from pytest-cov (default: keep 10 most recent)
+### Temporary File Management
 
-**Configuration**: Cleanup behavior can be controlled via CLI options or disabled entirely for debugging purposes.
+**Auto-cleanup**: Keeps 5 debug logs, 10 coverage files by default
+**Options**: `--no-cleanup`, `--keep-debug-logs N`, `--keep-coverage-files N`
 
 ### Testing & Development
 
@@ -345,661 +279,310 @@ python -m crackerjack -p patch
 
 ### UVX Integration
 
-**Crackerjack can be executed via uvx for isolated environments:**
-
-```bash
-# For installed crackerjack (from PyPI)
-uvx crackerjack --help
-uvx crackerjack -t
-uvx crackerjack --start-mcp-server
-
-# For local development version
-uvx --from /Users/les/Projects/crackerjack crackerjack --help
-uvx --from /Users/les/Projects/crackerjack crackerjack -t
-uvx --from /Users/les/Projects/crackerjack crackerjack --start-mcp-server
-```
-
-**Benefits**: Isolated execution, no dependency conflicts, consistent environment across systems.
+**Isolated execution**: `uvx crackerjack -t` (PyPI) or `uvx --from /path crackerjack -t` (local)
 
 ## Architecture Overview
 
-**Recently refactored from monolithic `crackerjack.py` to modular architecture:**
-
-### Core Orchestration Layer
-
-- **`core/workflow_orchestrator.py`**: Main entry point with `WorkflowOrchestrator` and `WorkflowPipeline` classes
-- **`core/container.py`**: Basic dependency injection container using protocols for loose coupling
-- **`core/enhanced_container.py`**: Advanced DI container with lifecycle management
-  - **ServiceLifetime** enum: `SINGLETON`, `TRANSIENT`, `SCOPED` service lifetimes
-  - **ServiceDescriptor** dataclass: Comprehensive service registration with factory support
-  - **Thread-safe**: Singleton instances with thread-local scoping
-  - **Dependency resolution**: Automatic dependency injection with circular dependency detection
-- **`__main__.py`**: Simplified CLI entry point (reduced from 601 to 122 lines via modularization)
+**Modular architecture with dependency injection:**
 
-### Coordinator Layer (Workflow Management)
+### Core Layers
 
-- **`core/session_coordinator.py`**: Session tracking, cleanup handlers, progress management
-- **`core/phase_coordinator.py`**: Individual workflow phases (cleaning, config, hooks, testing, publishing, commit)
-- **`core/async_workflow_orchestrator.py`**: Async workflow coordination with parallel execution
-  - **Async/await patterns**: Non-blocking workflow execution
-  - **Parallel hook execution**: Concurrent pre-commit hook processing
-  - **Progress streaming**: Real-time progress updates via WebSocket
-  - **Error aggregation**: Collects all errors before batch processing by AI agents
+- **Orchestration**: `WorkflowOrchestrator`, DI containers with lifecycle management
+- **Coordinators**: Session/phase coordination, async workflows with parallel execution
+- **Managers**: Hook execution (fast→comprehensive), test management, publishing
+- **Services**: Filesystem, git, config, security, health monitoring
 
-### Domain Managers (Business Logic)
+### Key Patterns
 
-- **`managers/hook_manager.py`**: Pre-commit hook execution with fast→comprehensive two-stage system
-- **`managers/test_manager.py`**: Test execution, coverage analysis, environment validation
-- **`managers/publish_manager.py`**: Version bumping, git tagging, PyPI publishing with authentication
+**Dependency Flow**: `__main__.py` → `WorkflowOrchestrator` → Coordinators → Managers → Services
 
-### Component Interaction Patterns
+**Critical**: Always import protocols from `models/protocols.py`, never concrete classes
 
-**Dependency Flow:**
+- ❌ `from ..managers.test_manager import TestManager`
+- ✅ `from ..models.protocols import TestManagerProtocol`
 
-```
-WorkflowOrchestrator → SessionCoordinator → PhaseCoordinator → Managers
-                   ↓
-Container (DI) → Protocols → Concrete Implementations
-```
+### MCP Integration
 
-**Critical Interfaces in `models/protocols.py`:**
-
-- `HookManagerProtocol`, `TestManagerProtocol`, `PublishManagerProtocol`
-- Always import protocols, never concrete classes for dependency injection
-- **Common Error**: `from ..managers.test_manager import TestManager` ❌
-- **Correct**: `from ..models.protocols import TestManagerProtocol` ✅
-
-**Enhanced Dependency Injection Patterns** (using `EnhancedContainer`):
-
-```python
-from crackerjack.core.enhanced_container import EnhancedContainer, ServiceLifetime
-
-# Service registration with lifecycle management
-container.register_service(
-    interface=HookManagerProtocol,
-    implementation=AsyncHookManager,
-    lifetime=ServiceLifetime.SINGLETON,  # Shared instance
-)
-
-# Factory-based registration for complex initialization
-container.register_factory(
-    interface=TestManagerProtocol,
-    factory=lambda: create_test_manager_with_config(),
-    lifetime=ServiceLifetime.SCOPED,  # Per-session instance
-)
-
-# Automatic dependency resolution
-hook_manager = container.resolve(HookManagerProtocol)  # Returns singleton
-test_manager = container.resolve(TestManagerProtocol)  # Creates scoped instance
-```
-
-### Infrastructure Services
-
-- **`services/filesystem.py`**: Basic file operations with caching, batching, and security validation
-- **`services/enhanced_filesystem.py`**: Advanced filesystem operations
-  - **Atomic Operations**: Ensures file consistency during concurrent operations
-  - **XDG Compliance**: Follows XDG Base Directory Specification for config/cache/data
-  - **Backup Management**: Automatic backup creation with rotation policies
-  - **Performance Monitoring**: File operation timing and performance metrics
-  - **Security Validation**: Path traversal prevention and secure temp file handling
-- **`services/git.py`**: Git operations (commit, push, file tracking) with intelligent commit messages
-- **`services/config.py`**: Configuration management for pyproject.toml and .pre-commit-config.yaml
-- **`services/unified_config.py`**: Centralized configuration management across all components
-- **`services/security.py`**: Token handling, command validation, secure temp file creation
-- **`services/health_metrics.py`**: System health monitoring and performance benchmarking
-- **`services/contextual_ai_assistant.py`**: AI-powered code analysis and suggestions
-
-### MCP Integration (AI Agent Support)
-
-**Refactored from monolithic 3,116-line server to modular architecture (70% line reduction):**
-
-- **`mcp/server.py`**: Backward compatibility wrapper (32 lines, imports from modular implementation)
-- **`mcp/server_core.py`**: Core MCP server configuration and setup (194 lines)
-- **`mcp/tools/`**: Modular tool implementations:
-  - `core_tools.py`: Basic execution and stage tools
-  - `monitoring_tools.py`: Status monitoring and health checks
-  - `progress_tools.py`: Progress tracking and job management
-  - `execution_tools.py`: Auto-fixing and workflow execution
-- **`mcp/context.py`**: Context manager for dependency injection and state management
-- **`mcp/state.py`**: Thread-safe session state management with async locks
-- **`mcp/cache.py`**: Thread-safe error pattern caching and fix result tracking
-- **`mcp/rate_limiter.py`**: Rate limiting, resource management, and DoS protection
-- **`mcp/file_monitor.py`**: Event-based file monitoring with watchdog
-- **Entry point**: `python -m crackerjack --start-mcp-server`
-
-**WebSocket Server (refactored from 1,479 lines to modular architecture - 35% reduction):**
-
-- **`mcp/websocket_server.py`**: Backward compatibility wrapper (imports from modular implementation)
-- **`mcp/websocket/server.py`**: Main WebSocket server class (101 lines)
-- **`mcp/websocket/app.py`**: FastAPI application setup (26 lines)
-- **`mcp/websocket/jobs.py`**: Job lifecycle and progress management (197 lines)
-- **`mcp/websocket/endpoints.py`**: HTTP endpoint definitions (545 lines)
-- **`mcp/websocket/websocket_handler.py`**: WebSocket connection handling (75 lines)
-- **Entry point**: `python -m crackerjack --start-websocket-server`
-
-### CLI Interface (Modular Command Handling)
-
-- **`cli/options.py`**: CLI option definitions and models (213 lines)
-- **`cli/handlers.py`**: Mode handlers for different execution types (124 lines)
-- **`cli/utils.py`**: CLI utility functions (17 lines)
-
-### Advanced Orchestration
-
-- **`orchestration/advanced_orchestrator.py`**: Advanced workflow orchestration with parallel execution strategies
-- **`orchestration/execution_strategies.py`**: Pluggable execution strategies for different workflow types
-- **`orchestration/test_progress_streamer.py`**: Real-time test progress streaming with Rich UI
-
-### Plugin System
-
-- **`plugins/base.py`**: Base plugin interface and lifecycle management
-- **`plugins/loader.py`**: Dynamic plugin loading with dependency resolution
-- **`plugins/hooks.py`**: Pre-commit hook plugins with custom validation rules
-- **`plugins/managers.py`**: Plugin-specific manager implementations
-
-### Legacy Components (Stable, Integrated)
-
-- **`code_cleaner.py`**: Modernized code cleaning with AST parsing and protocol-based architecture
-- **`dynamic_config.py`**: Configuration generation and management
-- **`interactive.py`**: Rich UI interactive mode with clean architecture
-- **`api.py`**: Public API with TODO detection for code cleaning operations
+**70% reduction**: 3,116 lines → modular architecture with tools, state management, rate limiting, monitoring
+**WebSocket Server**: 35% reduction with FastAPI, job management, progress streaming
+**Entry points**: `--start-mcp-server`, `--start-websocket-server`
 
 ## Quality Process
 
-### Optimal AI Agent Workflow Order
-
-**Proper execution order for maximum efficiency (used by `/crackerjack:run`):**
-
-1. **Fast Hooks First** (~5 seconds): `trailing-whitespace`, `end-of-file-fixer`, `ruff-format`, `ruff-check`, `gitleaks`
-
-   - **Package-focused**: `ruff-check` now runs only on `crackerjack/` package code, excludes `tests/`
-   - **Repository-wide**: Other fast hooks (formatting) still run on entire repository
-   - If any formatting hooks fail → **Retry fast hooks once** (formatting fixes often resolve downstream issues)
-   - Only proceed when fast hooks pass or have been retried
-
-1. **Full Test Suite** (~variable): Run ALL tests, collect ALL failures
-
-   - **Don't stop on first failure** - gather complete list of test issues
-   - Tests are more critical than lint issues, so run before comprehensive hooks
-
-1. **Comprehensive Hooks** (~30 seconds): `pyright`, `bandit`, `vulture`, `refurb`, `creosote`, `complexipy`
+### Workflow Order
 
-   - **Package-focused by default**: Only run on `crackerjack/` package code, excludes `tests/`, `examples/`
-   - **Don't stop on first failure** - gather complete list of quality issues
-   - Use `--with-tests` flag (future) to include tests in comprehensive quality checks
+1. **Fast Hooks** (~5s): formatting, basic checks → retry once if fail
+1. **Full Test Suite**: collect ALL failures, don't stop on first
+1. **Comprehensive Hooks** (~30s): type checking, security, complexity → collect ALL issues
+1. **AI Batch Fixing**: process all collected failures together
 
-1. **AI Analysis & Batch Fixing**: Process ALL collected failures together
+### Testing
 
-   - More efficient than fixing one issue at a time
-   - AI can consider dependencies between fixes
-
-### Testing Configuration
-
-- **Framework**: pytest with asyncio auto mode
-- **Coverage**: Incremental ratchet system targeting 100% coverage
-- **Timeout**: 300 seconds per test (configurable with --test-timeout)
-- **Workers**: Auto-detected based on CPU count (override with --test-workers)
-- **Config file**: `pyproject.toml` contains pytest configuration
+**Framework**: pytest with asyncio, 300s timeout, auto-detected workers
+**Coverage**: Ratchet system targeting 100%, never decrease
 
 ## Code Standards
 
-### Clean Code Principles (Applied)
-
-Following our philosophy that **EVERY LINE OF CODE IS A LIABILITY**:
-
-- **DRY**: Extract common patterns into reusable functions/classes
-- **YAGNI**: Implement only current requirements, not future "what-ifs"
-- **KISS**: Choose simple solutions over clever ones
-- **Readability First**: Code should be self-explanatory
-- **Descriptive Names**: `user_count` not `uc`, even in map/filter functions
+### Principles
 
-### Python 3.13+ Requirements
+- **DRY/YAGNI/KISS**: Extract patterns, build only what's needed, choose simple solutions
+- **Python 3.13+**: `|` unions, protocols, pathlib, `import typing as t`, Pydantic
 
-- Modern type hints with `|` unions instead of `Union`
-- Protocol-based interfaces in `models/protocols.py`
-- Pathlib over os.path
-- `import typing as t` convention
-- Pydantic BaseModel for configuration with validation
+### Quality Rules
 
-### Quality Rules (Enforced by Tools)
+- **Complexity ≤15** per function
+- **No hardcoded paths** (use `tempfile`)
+- **No shell=True** in subprocess
+- **Type annotations required**
+- **Protocol-based DI**
+- **TODO resolution** required for cleaning mode
 
-- **Cognitive complexity ≤15** per function (Complexipy) - KISS principle in action
-- **No hardcoded temp paths** (Security: Bandit B108) - use `tempfile` module
-- **UV tool execution**: Always use `uv run` for external tools
-- **No shell=True** in subprocess calls
-- **Type annotations required**: All functions must have return type hints
-- **Protocol compliance**: Use protocols for dependency injection interfaces
-- **TODO detection**: Code cleaning (`-x`) requires resolving all TODO comments first
-
-### Refactoring Patterns for Complexity Reduction
+### Refactoring Pattern
 
 ```python
-# GOOD: Break complex methods into smaller helper methods
+# Break complex methods into helper methods
 def complex_method(self, data: dict) -> bool:
     if not self._validate_input(data):
         return self._handle_invalid_input()
-
     processed = self._process_data(data)
     return self._save_results(processed)
-
-
-def _validate_input(self, data: dict) -> bool:
-    # Single responsibility validation logic
-    pass
-
-
-def _handle_invalid_input(self) -> bool:
-    # Focused error handling
-    pass
 ```
 
-### Error Prevention Patterns
+### Error Prevention Examples
 
 ```python
-# AVOID: Hardcoded temp paths (Security issue)
-config_path = "/tmp/test-config.yaml"  # BAD
-
-# USE: Proper temp file handling
-import tempfile
-
+# Use tempfile, not hardcoded paths
 with tempfile.NamedTemporaryFile(suffix=".yaml") as f:
     config_path = f.name
 
-# AVOID: try/except pass (Refurb FURB107)
-try:
-    risky_operation()
-except Exception:
-    pass  # BAD
-
-# USE: contextlib.suppress
+# Use contextlib.suppress, not try/except pass
 from contextlib import suppress
 
 with suppress(Exception):
     risky_operation()
 
-# AVOID: Lists in membership tests (Refurb FURB109)
-if status in ["error", "failed", "timeout"]:  # BAD
-    handle_error()
-
-# USE: Tuples for immutable membership tests
-if status in ("error", "failed", "timeout"):  # GOOD
+# Use tuples for membership tests
+if status in ("error", "failed", "timeout"):
     handle_error()
 
-# AVOID: Manual list building (FURB138)
-issues = []
-for item in data:
-    if condition(item):
-        issues.append(process(item))
-
-# USE: List comprehensions
+# Use comprehensions, not manual building
 issues = [process(item) for item in data if condition(item)]
 
-# AVOID: Dictionary get with if/else (FURB184)
-emoji = AGENT_EMOJIS.get(agent_type)
-if emoji:
-    return emoji
-return "🤖"
-
-# USE: Dictionary get with default
+# Use dict.get with default
 return AGENT_EMOJIS.get(agent_type, "🤖")
 
-# AVOID: Lambda for simple attribute access (FURB118)
-sorted_items = sorted(items, key=lambda x: x["priority"])
-
-# USE: operator.itemgetter
+# Use operator functions, not lambdas
 from operator import itemgetter
 
 sorted_items = sorted(items, key=itemgetter("priority"))
 ```
 
-## Development Workflow
-
-### Making Changes
+### Regex Best Practices (CRITICAL)
 
-1. **Run quality checks**: `python -m crackerjack`
-1. **Run with tests**: `python -m crackerjack -t` (for comprehensive validation)
-1. **Address remaining issues**: Manual fixes for any issues that tools cannot resolve
-1. **Get AI code review**: When gemini-cli MCP server is connected, have Gemini review your completed work with `mcp__gemini-cli__ask-gemini` for a second opinion on code quality
-1. **Commit changes**: Use `python -m crackerjack -c` for auto-commit with intelligent messages
+**⚠️ WARNING: Bad regex caused security vulnerabilities. Always use centralized patterns.**
 
-### Testing Individual Components
+**NEVER write raw regex. Use centralized registry:**
 
-```bash
-# Test specific manager
-python -m pytest tests/test_managers.py -v
-
-# Test core orchestration
-python -m pytest tests/test_coordinator_integration.py -v
+```python
+# ❌ DANGEROUS
+text = re.sub(r"(\w+) - (\w+)", r"\g < 1 >-\g < 2 >", text)
 
-# Test MCP integration
-python -m pytest tests/test_mcp_server.py -v
+# ✅ SAFE
+from crackerjack.services.regex_patterns import SAFE_PATTERNS
 
-# Run failing test in isolation
-python -m pytest tests/test_crackerjack.py::TestClass::test_method -v -s
+text = SAFE_PATTERNS["fix_hyphenated_names"].apply(text)
 ```
 
-### Common Development Issues
+**Available patterns**: command spacing, token masking, hyphenation, security fixes (18+ validated patterns)
 
-- **Import errors**: Check `models/protocols.py` for interface definitions
-- **Type errors**: Use `t.cast()` for complex type scenarios, ensure proper type annotations
-- **Complexity violations**: Break large methods into focused helper methods
-- **Test failures**: Check mock paths for new architecture
+**FORBIDDEN patterns that cause vulnerabilities:**
 
-## MCP Server Integration
+- `r"\g < 1 >"` (spaces in replacement - SECURITY ISSUE)
+- `r"\g< 1>"` or `r"\g<1 >"` (spacing bugs)
+- `r".*"` (overly broad)
+- Raw token masking
 
-**WebSocket-based MCP server with real-time progress streaming:**
+**Security token masking**: Use word boundaries, comprehensive tests, consistent application
+**Emergency fix**: Find with `rg "pattern"`, replace with `SAFE_PATTERNS["pattern_name"].apply(text)`
 
-### Server Features
+## Common Issues & Solutions
 
-- **🌐 Dual Protocol Support**: MCP protocol tools + WebSocket server on localhost:8675
-- **🎨 Real-time Progress**: Live progress updates with Rich formatting
-- **🔄 Auto-Fallback**: Graceful fallback from WebSocket to polling
-- **📊 Job Tracking**: Comprehensive job progress and iteration monitoring
-- **🛑 Signal Handling**: Graceful shutdown with Ctrl+C support
+### Terminal Issues
 
-### MCP Server Usage
+- **Unresponsive terminal**: `./fix_terminal.sh` or `stty sane; reset; exec $SHELL -l`
+- **No progress updates**: Start WebSocket server, verify at http://localhost:8675/
 
-**For live progress monitoring with `/crackerjack:run`:**
+### Development Issues
 
-```bash
-# Step 1: Start the dedicated WebSocket server (in a separate terminal)
-python -m crackerjack --start-websocket-server
-
-# Step 2: Use /crackerjack:run in Claude - progress will be available at:
-# - WebSocket: ws://localhost:8675/ws/progress/{job_id}
-# - Test page: http://localhost:8675/test
-# - Status: http://localhost:8675/
-```
+- **AI agent ineffective**: Use `--ai-debug -t` for analysis
+- **Import errors**: Always import protocols from `models/protocols.py`
+- **Test hangs**: Avoid complex async tests, use simple synchronous config tests
 
-**Alternative - Start MCP server with WebSocket support:**
+### Quality Issues
 
-```bash
-# Starts server on localhost:8675 with WebSocket + MCP protocol support
-python -m crackerjack --start-mcp-server --websocket-port 8675
-```
+- **Coverage failing**: Never reduce below baseline, add tests incrementally
+- **Complexity >15**: Break into helper methods using RefactoringAgent approach
+- **Security violations**: Use `SAFE_PATTERNS` for token masking
+- **Regex issues**: Never use raw regex, use centralized patterns
 
-**Progress monitoring:**
+### Server Issues
 
-```bash
-# Monitor specific job by ID via WebSocket
-python -m crackerjack.mcp.progress_monitor abc123-def456
+- **MCP not starting**: `--restart-mcp-server` or `--watchdog`
+- **WebSocket failures**: Restart with `--websocket-port 8675`
 
-# Monitor with custom WebSocket URL
-python -m crackerjack.mcp.progress_monitor abc123-def456 ws://localhost:8675
-```
+### Performance Issues
 
-**Enhanced API integration:**
+- **Slow tests**: Customize `--test-workers N` or `--benchmark`
+- **Memory issues**: PerformanceAgent detects O(n²) patterns
+- **Slow hooks**: Use `--skip-hooks` during rapid iteration
 
-```python
-from crackerjack.mcp.progress_monitor import (
-    run_crackerjack_with_enhanced_progress,
-)
+## Development Workflow
 
-# Uses WebSocket monitoring with Rich display
-await run_crackerjack_with_enhanced_progress(client, "/crackerjack:run")
-```
+### Standard Process
 
-### Server Architecture
+1. Run quality checks: `python -m crackerjack`
+1. Run with tests: `python -m crackerjack -t`
+1. Address remaining issues manually
+1. Optional AI review: `mcp__gemini-cli__ask-gemini`
+1. Commit: `python -m crackerjack -c`
 
-- **WebSocket Server**: Runs on localhost:8675 for progress streaming
-- **MCP Protocol**: FastMCP-based tools for AI agent integration
-- **Progress Queue**: `asyncio.Queue` for real-time job updates
-- **Rich Components**: Formatted progress panels and status displays
-- **Job Management**: Background task execution with progress tracking
+### Testing Components
 
-### Available MCP Tools
+- **Specific**: `python -m pytest tests/test_managers.py -v`
+- **Isolated**: `python -m pytest tests/test_file.py::TestClass::test_method -v -s`
 
-- `execute_crackerjack`: Start iterative auto-fixing workflow
-- `get_job_progress`: Get current progress for running jobs
-- `get_comprehensive_status`: Get complete system status (servers, jobs, health)
-- `run_crackerjack_stage`: Execute specific workflow stages
-- `analyze_errors`: Intelligent error pattern analysis
-- `session_management`: Track iteration state and checkpoints
-- `get_stage_status`: Get workflow stage completion status
-- `get_server_stats`: Get MCP server resource usage and statistics
+### Common Issues
 
-### Dependencies
+- **Import errors**: Check `models/protocols.py` for interfaces
+- **Type errors**: Use `t.cast()`, ensure annotations
+- **Complexity**: Break into helper methods
 
-- `fastmcp>=2.10.6`: MCP server framework
-- `uvicorn>=0.32.1`: WebSocket server support
-- `websockets>=15.0.1`: WebSocket client connections
-- `fastapi>=0.116.1`: HTTP/WebSocket endpoint framework
-- `rich>=14`: Terminal formatting and progress displays
+## MCP Server Integration
 
-### Slash Commands
+### Features
 
-**Location**: Available in `crackerjack.slash_commands` module for other packages to use
+- **Dual Protocol**: MCP tools + WebSocket server on localhost:8675
+- **Real-time Progress**: Live updates with Rich formatting
+- **Job Tracking**: Comprehensive progress monitoring
 
-**`/crackerjack:run`**: Run full iterative auto-fixing with AI agent, tests, progress tracking, and verbose output
+### Usage
 
-**`/crackerjack:status`**: Get comprehensive system status including MCP server health, WebSocket server status, active jobs, progress tracking, and resource usage
+```bash
+# Start WebSocket server
+python -m crackerjack --start-websocket-server
 
-**`/crackerjack:init`**: Initialize or update project configuration with intelligent smart merge (preserves existing configurations, never overwrites project identity)
+# Use /crackerjack:run in Claude
+# Progress at: http://localhost:8675/
 
-**Programmatic Access**:
+# Monitor job
+python -m crackerjack.mcp.progress_monitor <job_id>
+```
 
-```python
-from crackerjack.slash_commands import list_available_commands, get_slash_command_path
+### Available Tools
 
-# List all available commands
-commands = list_available_commands()  # ['run', 'init']
+- `execute_crackerjack`: Start auto-fixing workflow
+- `get_job_progress`: Get current job progress
+- `get_comprehensive_status`: Complete system status
+- `analyze_errors`: Error pattern analysis
+- `session_management`: Track iterations
 
-# Get path to specific command
-command_path = get_slash_command_path("run")
-command_content = command_path.read_text()
-```
+### Slash Commands
 
-## Configuration Details
+- **`/crackerjack:run`**: Full auto-fixing with progress tracking
+- **`/crackerjack:status`**: System status and health
+- **`/crackerjack:init`**: Initialize project configuration
 
-**Tool Configuration** (from `pyproject.toml`):
+## Configuration
 
-- **Coverage requirement**: Ratchet system - never decrease, always improve toward 100%
-- **Cognitive complexity**: ≤13 per function (complexipy)
-- **Python version**: 3.13+ required
-- **Test timeout**: 300 seconds per test
-- **Type checking**: Strict mode with Pyright
-- **Security scanning**: Bandit with custom exclusions
+- **Coverage**: Ratchet system targeting 100%
+- **Complexity**: ≤15 per function
+- **Python**: 3.13+ required
+- **Test timeout**: 300s
+- **Type checking**: Strict Pyright
+- **Security**: Bandit scanning
 
 ## Service Watchdog
 
-**Automatic monitoring and restart system for MCP and WebSocket servers.**
-
-### Overview
-
-The Service Watchdog provides enterprise-grade monitoring and automatic recovery for Crackerjack's server components. It ensures continuous availability by detecting failures and restarting services automatically.
+**Auto-restart system for servers**
 
 ### Usage
 
 ```bash
-# Start watchdog to monitor both MCP and WebSocket servers
 python -m crackerjack --watchdog
 ```
 
-### Monitored Services
-
-1. **MCP Server** (`--start-mcp-server`)
-
-   - Process monitoring (detects crashes)
-   - No HTTP health checks (stdio-based protocol)
-   - Auto-restart on process termination
-
-1. **WebSocket Server** (`--start-websocket-server`)
-
-   - Process monitoring (detects crashes)
-   - HTTP health checks (`http://localhost:8675/`)
-   - Auto-restart on process or health check failures
-
 ### Features
 
-- **Real-time Monitoring**: Continuous process and health monitoring
-- **Intelligent Restart**: Rate-limited restarts with exponential backoff
-- **Rich Dashboard**: Live status display with service health, restart counts, and errors
-- **Rate Limiting**: Maximum 10 restarts per 5-minute window to prevent restart loops
-- **Health Checks**: HTTP endpoint monitoring for WebSocket server
-- **Error Tracking**: Logs and displays last error for each service
-- **Graceful Shutdown**: Proper cleanup on Ctrl+C
-
-### Dashboard Display
-
-The watchdog shows a real-time table with:
-
-- **Service**: Service name (MCP Server, WebSocket Server)
-- **Status**: ✅ Running / ❌ Stopped
-- **Health**: 🟢 Healthy / 🔴 Unhealthy / N/A
-- **Restarts**: Total restart count for the session
-- **Last Error**: Most recent error message (truncated)
-
-### Configuration
-
-Default configuration monitors:
-
-- **Health Check Interval**: 30 seconds
-- **Restart Delay**: 5 seconds between restart attempts
-- **Max Restarts**: 10 per 5-minute window
-- **Health Timeout**: 10 seconds for HTTP checks
-
-### Use Cases
-
-- **Development**: Automatic recovery during active development sessions
-- **CI/CD**: Ensure services stay running during automated testing
-- **Production**: High-availability deployment with automatic failover
-- **Debugging**: Monitor service stability and identify recurring issues
-
-### Dependencies
-
-- `aiohttp`: HTTP health check client
-- `rich`: Dashboard display and formatting
-- `asyncio`: Concurrent monitoring and restart management
-
-## Architecture Migration Notes
-
-**Key changes from monolithic to modular:**
-
-- `Crackerjack` class methods → `WorkflowOrchestrator` + coordinator delegation
-- Direct tool execution → Manager pattern with dependency injection
-- Hardcoded workflows → Configurable phase execution with retry logic
-- Manual error handling → Automatic fixing with intelligent retry
+- **Real-time monitoring**: Process/health checks
+- **Auto-restart**: Rate-limited with backoff (max 10/5min)
+- **Dashboard**: Live status display
+- **Health checks**: HTTP monitoring for WebSocket server
+- **Graceful shutdown**: Ctrl+C cleanup
 
-**Modular Architecture Notes:**
+**Monitors**: MCP server (process), WebSocket server (process + HTTP health)
 
-- **Clean Architecture**: Direct use of modern class names (`InteractiveCLI`, `WorkflowManager`, `CodeCleaner`)
-- **Modular CLI**: Options and handlers moved to dedicated modules (`cli/options.py`, `cli/handlers.py`)
-- **Protocol-based Design**: Dependency injection through protocols for better testability
+## Recent Achievements (January 2025)
 
-**Refactoring Achievements (January 2025):**
+**Refactoring Results:**
 
-- **70% line reduction** in MCP server (3,116 lines → 921 lines across 6 focused modules)
-- **35% line reduction** in WebSocket server (1,479 lines → 944 lines across 5 modules)
-- **80% line reduction** in CLI entry point (601 lines → 122 lines via delegation)
-- **Code Quality Improvements**:
-  - Fixed all 31+ refurb violations in agents directory (FURB107, FURB109, FURB118, FURB135, FURB138, FURB184)
-  - Reduced complex functions from 32 to 29 total, with major reductions:
-    - `_execute_crackerjack_sync`: complexity 34 → 3 (91% reduction)
-    - `TestManagementImpl::run_tests`: complexity 33 → 2 (94% reduction)
-    - All 5 fast hooks now passing consistently
-- **Improved maintainability** through single responsibility principle
-- **Better testability** with focused, isolated modules
-- **Enhanced security** with modular validation and error handling
-- **Protocol-based interfaces** for better dependency injection and testing
-- **Performance Improvements**: Enhanced async/await patterns, parallel execution, and caching strategies
-- **Plugin Architecture**: Extensible plugin system for custom hooks and workflow extensions
-- **Health Monitoring**: Comprehensive system health metrics and performance benchmarking
+- **70% line reduction**: MCP server (3,116 → 921 lines)
+- **35% line reduction**: WebSocket server (1,479 → 944 lines)
+- **80% line reduction**: CLI entry point (601 → 122 lines)
 
-## Test Coverage Requirements
+**Quality Improvements:**
 
-**CRITICAL**: The coverage ratchet system prevents regression and targets 100% coverage.
+- Fixed all 31+ refurb violations
+- Major complexity reductions: 34→3 (91%), 33→2 (94%)
+- All 5 fast hooks passing consistently
+- Protocol-based interfaces throughout
 
-- **Never reduce coverage below current baseline** - coverage can only improve
-- **Add tests to increase coverage** incrementally toward 100%
-- **Current Status**: Test coverage at 10.11% baseline, targeting 100%
-- Existing test files cover various modules including core components, managers, and async workflows
-- Focus testing on modules with 0% coverage: plugins, MCP server, enhanced filesystem, unified config
+## Test Coverage Status
 
-## Current Quality Status (January 2025)
+**Current**: 10.11% baseline targeting 100%
+**Strategy**: Import-only tests, protocol compliance, async validation, integration testing
+**Priority**: Fix existing failures first, then add tests incrementally
 
-**✅ COMPLETED:**
+**Ratchet System**: 2% tolerance, never reduce coverage
 
-- All 31+ refurb violations fixed in agents directory
-- Fast hooks: All 5 passing consistently
-- Major complexity reductions (34→3, 33→2)
-- Import errors and protocol compliance fixed
+## Critical Reminders
 
-**🔄 IN PROGRESS:**
+### Core Instructions
 
-- Complexipy violations: Some functions still > 15 complexity
-- Test coverage: Working toward 100% via incremental improvements
+- Do only what's asked, nothing more
+- NEVER create files unless absolutely necessary
+- ALWAYS prefer editing existing files
+- NEVER proactively create documentation
+- MAINTAIN coverage ratchet
 
-**⚠️ CRITICAL PRIORITIES:**
+### Quality Standards
 
-1. **Fix existing test failures first** (before adding new tests)
-1. Add tests strategically to reach next milestone toward 100% coverage
-1. Complete remaining complexity reductions
-1. Final integration and release preparation
+- **Test Quality**: Avoid async tests that hang, use synchronous config tests
+- **Honest Reporting**: Report actual percentages (10.17%, not "approaching 15%")
+- **Import Compliance**: Use protocols from `models/protocols.py`
+- **Fix failures FIRST** before creating new tests
+- Use IDE diagnostics after implementation
+- Be critical/comprehensive in reviews
+- Use crackerjack-architect agent for compliant code
 
-**Key User Directive**: Always prioritize fixing failures of existing tests over creating new tests, especially when coverage issues are being addressed.
-
-### Current Test Strategy (Post-Architectural Refactoring)
-
-**Strategic Testing Approach**:
-
-- **Import-only tests**: Fast, reliable coverage for basic module loading and interface compliance
-- **Protocol compliance tests**: Ensure all implementations properly follow interface contracts
-- **Async pattern testing**: Comprehensive validation of async/await workflows without hanging tests
-- **Integration testing**: End-to-end validation of dependency injection and workflow orchestration
-- **Performance regression testing**: Automated detection of performance degradation in async workflows
-
-## Important Instruction Reminders
-
-- Do what has been asked; nothing more, nothing less
-- NEVER create files unless absolutely necessary for achieving your goal
-- ALWAYS prefer editing an existing file to creating a new one
-- NEVER proactively create documentation files (\*.md) or README files unless explicitly requested
-- MAINTAIN coverage ratchet - never decrease coverage, always improve toward 100%
-
-## Coding Standards Memories
-
-- Do not reduce coverage below current baseline. Instead add tests to increase coverage toward 100% target.
-- **Debugging Approach Memory**: Focus on test errors first then move on to failures when debugging tests
-
-## Critical Quality Standards
-
-- **Test Quality**: Never create async tests that hang indefinitely. When testing async components like `BatchedStateSaver`, prefer simple synchronous tests that verify configuration and basic state rather than complex async workflows that can cause test suite timeouts.
-- **Honest Progress Reporting**: Always report actual coverage percentages and test results accurately. If coverage is 10.17%, report it as 10.17%, not "approaching 15%" or other optimistic estimates.
-- **Import Error Prevention**: Common import error pattern: `TestManager` vs `TestManagerProtocol` in `async_workflow_orchestrator.py`. Always use protocol interfaces from `models/protocols.py`.
-
-## Development Standards
-
-- be honest when describing the things you have accomplished. if tasks have not been completed to their full extent we need to know so sugarcoating your accomplishments for your, and especially our, benefit helps nobody.
-
-- be very critical and comprehensive when performing code or documentation reviews/audits. pride ourselves on our attention to detail and take the time to do things right the first time. always still assume failure on the first try, when making edits, so our work is double checked and bulletproof.
-
-## Common Failure Patterns to Avoid
-
-### Async Test Hangs
+### Failure Patterns to Avoid
 
 ```python
-# AVOID: Complex async tests that can hang
+# ❌ Async tests that hang
 @pytest.mark.asyncio
 async def test_batch_processing(self, batched_saver):
-    await batched_saver.start()
-    # Complex async workflow that might hang
+    await batched_saver.start()  # Can hang
 
 
-# PREFER: Simple synchronous config tests
+# ✅ Simple synchronous tests
 def test_batch_configuration(self, batched_saver):
     assert batched_saver.max_batch_size == expected_size
-    assert not batched_saver._running
-```
 
-### Import Error Prevention
 
-```python
-# WRONG: Importing concrete classes instead of protocols
+# ❌ Import concrete classes
 from ..managers.test_manager import TestManager
 
-# CORRECT: Use protocol interfaces for dependency injection
+# ✅ Import protocols
 from ..models.protocols import TestManagerProtocol
 ```
 
-- DO NOT CREATE ANY NEW TESTS UNTIL CURRENTLY FAILING OR ERRORING TESTS HAVE EITHER BEEN FIXED OR REMOVED!
-- always be honest with your answers. do not embelish on progress.
-- always clean up after yourself
+- make as few edits as possible by batching related changes together in a single operation.