crackerjack 0.37.9__py3-none-any.whl → 0.45.2__py3-none-any.whl

{crackerjack-0.37.9.dist-info → crackerjack-0.45.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: crackerjack
-Version: 0.37.9
+Version: 0.45.2
 Summary: Crackerjack Python project management tool
 Project-URL: documentation, https://github.com/lesleslie/crackerjack
 Project-URL: homepage, https://github.com/lesleslie/crackerjack
@@ -18,62 +18,76 @@ Classifier: Topic :: Software Development :: Testing
 Classifier: Topic :: Utilities
 Classifier: Typing :: Typed
 Requires-Python: >=3.13
-Requires-Dist: aiofiles>=24.1
-Requires-Dist: aiohttp>=3.12.14
-Requires-Dist: bandit>=1.8.6
+Requires-Dist: acb>=0.31.18
+Requires-Dist: aiofiles>=25.1.0
+Requires-Dist: aiohttp>=3.13.2
+Requires-Dist: bandit>=1.9.2
+Requires-Dist: bevy>=3.1.0b12
 Requires-Dist: codespell>=2.4.1
-Requires-Dist: complexipy>=3.3
-Requires-Dist: creosote>=4.0.3
-Requires-Dist: fastapi>=0.116.1
-Requires-Dist: fastmcp>=2.10.6
-Requires-Dist: hatchling>=1.25
-Requires-Dist: hypothesis>=6.100
-Requires-Dist: jinja2>=3.1
-Requires-Dist: keyring>=25.6
-Requires-Dist: mcp>=1.12.2
-Requires-Dist: pre-commit>=4.2
-Requires-Dist: psutil>=6.1.0
-Requires-Dist: pydantic>=2.11.7
+Requires-Dist: complexipy>=5.1.0
+Requires-Dist: creosote>=4.1.0
+Requires-Dist: fastapi>=0.124.0
+Requires-Dist: fastmcp>=2.13.2
+Requires-Dist: hatchling>=1.28.0
+Requires-Dist: hypothesis>=6.148.7
+Requires-Dist: jinja2>=3.1.6
+Requires-Dist: keyring>=25.7.0
+Requires-Dist: mcp-common>=0.3.3
+Requires-Dist: mcp>=1.23.3
+Requires-Dist: mdformat-ruff>=0.1.3
+Requires-Dist: mdformat>=1.0.0
+Requires-Dist: nltk>=3.9.2
+Requires-Dist: numpy>=2.3.5
+Requires-Dist: onnxruntime>=1.23.2
+Requires-Dist: pip-audit>=2.10.0
+Requires-Dist: psutil>=7.1.3
+Requires-Dist: pydantic>=2.12.5
 Requires-Dist: pyleak>=0.1.14
-Requires-Dist: pyright>=1.1.403
-Requires-Dist: pytest-asyncio>=1
-Requires-Dist: pytest-benchmark>=5.1
-Requires-Dist: pytest-cov>=6.2.1
-Requires-Dist: pytest-mock>=3.14.1
-Requires-Dist: pytest-timeout>=2.4
-Requires-Dist: pytest-xdist>=3.8
-Requires-Dist: pytest>=8.4.1
-Requires-Dist: pyyaml>=6.0.2
-Requires-Dist: refurb>=2.1
-Requires-Dist: rich>=14.1
-Requires-Dist: ruff>=0.12.9
-Requires-Dist: scipy>=1.14.0
-Requires-Dist: skylos>=2.1.2
-Requires-Dist: structlog>=24.4
-Requires-Dist: textual>=0.89
-Requires-Dist: tomli-w>=1.2
-Requires-Dist: tomli>=2.2.1
-Requires-Dist: typer>=0.16
-Requires-Dist: types-aiofiles>=24.1.0.20240626
-Requires-Dist: types-psutil>=6.0.0.12
-Requires-Dist: types-pyyaml>=6.0.12.12
-Requires-Dist: uv>=0.7.20
-Requires-Dist: uvicorn>=0.32.1
+Requires-Dist: pyright>=1.1.407
+Requires-Dist: pyscn>=1.5.0
+Requires-Dist: pytest-asyncio>=1.3.0
+Requires-Dist: pytest-benchmark>=5.2.3
+Requires-Dist: pytest-cov>=7.0.0
+Requires-Dist: pytest-mock>=3.15.1
+Requires-Dist: pytest-timeout>=2.4.0
+Requires-Dist: pytest-xdist>=3.8.0
+Requires-Dist: pytest>=9.0.2
+Requires-Dist: pyyaml>=6.0.3
+Requires-Dist: refurb>=2.2.0
+Requires-Dist: rich>=14.2.0
+Requires-Dist: ruff>=0.14.8
+Requires-Dist: scikit-learn>=1.7.2
+Requires-Dist: scipy-stubs>=1.16.3.3
+Requires-Dist: scipy>=1.16.3
+Requires-Dist: session-mgmt-mcp>=0.9.8
+Requires-Dist: skylos>=2.5.3
+Requires-Dist: structlog>=25.5.0
+Requires-Dist: textual>=6.8.0
+Requires-Dist: tomli-w>=1.2.0
+Requires-Dist: transformers>=4.57.3
+Requires-Dist: typer>=0.20.0
+Requires-Dist: types-aiofiles>=25.1.0.20251011
+Requires-Dist: types-psutil>=7.1.3.20251202
+Requires-Dist: types-pyyaml>=6.0.12.20250915
+Requires-Dist: uv-bump>=0.3.2
+Requires-Dist: uv>=0.9.16
+Requires-Dist: uvicorn>=0.38.0
 Requires-Dist: vulture>=2.14
-Requires-Dist: watchdog>=6
+Requires-Dist: watchdog>=6.0.0
 Requires-Dist: websockets>=15.0.1
-Requires-Dist: zuban>=0.0.22
+Requires-Dist: zuban>=0.3.0
 Description-Content-Type: text/markdown
 
 # Crackerjack: Advanced AI-Driven Python Development Platform
 
+[![Code style: crackerjack](https://img.shields.io/badge/code%20style-crackerjack-000042)](https://github.com/lesleslie/crackerjack)
 [![Python: 3.13+](https://img.shields.io/badge/python-3.13%2B-green)](https://www.python.org/downloads/)
 [![pytest](https://img.shields.io/badge/pytest-coverage%20ratchet-blue)](https://pytest.org)
 [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
 [![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
-[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit)](https://github.com/pre-commit/pre-commit)
+[![Quality Hooks](https://img.shields.io/badge/quality%20hooks-17%20tools-brightgreen)](https://github.com/lesleslie/crackerjack)
 [![License](https://img.shields.io/badge/License-BSD%203--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause)
-![Coverage](https://img.shields.io/badge/coverage-17.6%25-red)
+![Coverage](https://img.shields.io/badge/coverage-21.6%25-red)
 
 ## 🎯 Purpose
 
@@ -81,11 +95,11 @@ Description-Content-Type: text/markdown
 
 ### What is "Crackerjack"?
 
-**crackerjack** /ˈkrækərˌdʒæk/ (noun): *A person or thing of marked excellence or ability; first-rate; exceptional; outstanding quality or performance.*
+**crack·​er·​jack** ˈkra-kər-ˌjak (noun): *A person or thing of marked excellence or ability; first-rate; exceptional.*
 
 Just as the name suggests, Crackerjack makes your Python projects first-rate through:
 
-- **🧠 Proactive AI Architecture**: 10+ specialized AI agents prevent issues before they occur
+- **🧠 Proactive AI Architecture**: 12 specialized AI agents prevent issues before they occur
 - **⚡ Autonomous Quality**: Intelligent auto-fixing with architectural planning
 - **🛡️ Zero-Compromise Standards**: 100% test coverage, complexity ≤15, security-first patterns
 - **🔄 Learning System**: Gets smarter with every project, caching successful patterns
@@ -99,9 +113,9 @@ Just as the name suggests, Crackerjack makes your Python projects first-rate thr
 
 ```bash
 # Traditional workflow
-pip install black isort flake8 mypy pytest pre-commit
+pip install black isort flake8 mypy pytest
 # Configure each tool individually
-# Set up pre-commit hooks manually
+# Set up git hooks manually
 # Remember different commands for each tool
 ```
 
@@ -134,19 +148,130 @@ Crackerjack is built on the following core principles:
 - **Auto-Discovery:** Prefer intelligent auto-discovery of configurations and settings over manual configuration whenever possible, reducing setup friction and configuration errors
 - **Static Typing:** Static typing is essential for all development
 
+## Crackerjack vs Pre-commit: Architecture & Features
+
+Crackerjack and pre-commit solve related but different problems. While pre-commit is a language-agnostic git hook manager, Crackerjack is a comprehensive Python development platform with quality enforcement built-in.
+
+### Architectural Differences
+
+| Aspect | Pre-commit | Crackerjack |
+|--------|-----------|-------------|
+| **Execution Model** | Wrapper framework that spawns subprocesses for each hook | Direct tool invocation with ACB adapter architecture |
+| **Concurrency** | Synchronous sequential execution (one hook at a time) | **Async-first with 11 concurrent adapters** - true parallel execution |
+| **Performance** | Overhead from framework wrapper + subprocess spawning | Zero wrapper overhead, 70% cache hit rate, 50% faster workflows |
+| **Language Focus** | Language-agnostic (Python, Go, Rust, Docker, etc.) | Python-first with native tool implementations |
+| **Configuration** | YAML-based `.pre-commit-config.yaml` with repo URLs | Python-based configuration with intelligent defaults |
+| **Hook Management** | Clones repos, manages environments per hook | Native Python tools + direct UV invocation |
+
+### Feature Comparison
+
+#### Quality Hooks & Tools
+
+| Feature | Pre-commit | Crackerjack |
+|---------|-----------|-------------|
+| **Code Formatting** | ✅ Via hooks (black, ruff, etc.) | ✅ Native Ruff integration + mdformat |
+| **Linting** | ✅ Via hooks (flake8, pylint, etc.) | ✅ Native Ruff + codespell |
+| **Type Checking** | ✅ Via hooks (mypy, pyright) | ✅ **Zuban** (20-200x faster than pyright) |
+| **Security Scanning** | ✅ Via hooks (bandit, gitleaks) | ✅ Native bandit + gitleaks integration |
+| **Dead Code Detection** | ✅ Via vulture hook | ✅ **Skylos** (20x faster than vulture) |
+| **Complexity Analysis** | ❌ Not built-in | ✅ Native complexipy integration |
+| **Dependency Validation** | ❌ Not built-in | ✅ Native creosote unused dependency detection |
+| **Custom Python Tools** | ✅ Via `repo: local` hooks | ✅ 6 native tools in `crackerjack/tools/` |
+
+#### Development Workflow
+
+| Feature | Pre-commit | Crackerjack |
+|---------|-----------|-------------|
+| **Git Integration** | ✅ Pre-commit, pre-push, commit-msg hooks | ✅ Git hooks + intelligent commit messages |
+| **Testing Framework** | ❌ Not included | ✅ Built-in pytest with coverage ratchet |
+| **CI/CD Integration** | ✅ Via `pre-commit run --all-files` | ✅ Unified `--ci` mode with quality + tests |
+| **Version Management** | ❌ Not included | ✅ Intelligent version bumping + AI recommendations |
+| **Publishing** | ❌ Not included | ✅ PyPI publishing with UV authentication |
+| **Hook Stages** | ✅ Multiple stages (commit, push, merge, manual) | ✅ Fast (~5s) vs Comprehensive (~30s) strategies |
+| **Retry Logic** | ❌ No built-in retry | ✅ Automatic retry for formatting hooks |
+| **Parallel Execution** | ✅ Limited parallelism (sequential by default) | ✅ **Async-first architecture**: 11 concurrent adapters, 76% speedup |
+
+#### Advanced Features
+
+| Feature | Pre-commit | Crackerjack |
+|---------|-----------|-------------|
+| **AI Integration** | ❌ Not built-in | ✅ 12 specialized AI agents + auto-fixing |
+| **Dependency Injection** | ❌ Not applicable | ✅ ACB framework with protocol-based DI |
+| **Caching** | ✅ Per-file hash caching | ✅ Content-based caching (70% hit rate) |
+| **MCP Server** | ❌ Not included | ✅ Built-in MCP server for Claude integration |
+| **Monitoring Dashboard** | ❌ Not included | ✅ Real-time WebSocket dashboard |
+| **Configuration Management** | ✅ YAML + `--config` flag | ✅ ACB Settings with YAML + local overrides |
+| **Auto-Update** | ✅ `pre-commit autoupdate` | ⚠️ Manual UV dependency updates |
+| **Language Support** | ✅ 15+ languages (Python, Go, Rust, Docker, etc.) | ✅ Python + external tools (gitleaks, etc.) |
+
+#### Configuration & Ease of Use
+
+| Feature | Pre-commit | Crackerjack |
+|---------|-----------|-------------|
+| **Setup Complexity** | Medium (YAML config + `pre-commit install`) | Low (single `python -m crackerjack`) |
+| **Configuration Format** | YAML with repo URLs and hook IDs | Python settings with intelligent defaults |
+| **Hook Discovery** | Manual (add repos to `.pre-commit-config.yaml`) | Automatic (17 tools pre-configured) |
+| **Tool Installation** | Auto (pre-commit manages environments) | UV-based (one virtual environment) |
+| **Learning Curve** | Medium (understand repos, hooks, stages) | Low (unified Python commands) |
+
+### When to Use Each
+
+**Choose Pre-commit when:**
+
+- ✅ Working with multiple languages (Go, Rust, Docker, etc.)
+- ✅ Need language-agnostic hook framework
+- ✅ Want to use hooks from community repositories
+- ✅ Polyglot projects requiring diverse tooling
+- ✅ Simple YAML-based configuration preferred
+
+**Choose Crackerjack when:**
+
+- ✅ Python-focused development (Python 3.13+)
+- ✅ Want comprehensive development platform (testing, publishing, AI)
+- ✅ Need maximum performance (async architecture, Rust tools, caching, 11x parallelism)
+- ✅ Desire AI-powered auto-fixing and recommendations
+- ✅ Want unified workflow (quality + tests + publishing in one command)
+- ✅ Prefer Python-based configuration over YAML
+- ✅ Need advanced features (coverage ratchet, MCP integration, dashboards)
+
+### Migration from Pre-commit
+
+Crackerjack can **coexist** with pre-commit if needed, but most Python projects can fully migrate:
+
+```bash
+# Remove pre-commit (optional)
+pre-commit uninstall
+rm .pre-commit-config.yaml
+
+# Install crackerjack
+uv tool install crackerjack
+
+# Run quality checks (replaces pre-commit run --all-files)
+python -m crackerjack
+
+# With tests (comprehensive workflow)
+python -m crackerjack --run-tests
+```
+
+**Note**: Crackerjack Phase 8 successfully migrated from pre-commit framework to direct tool invocation, achieving 50% performance improvement while maintaining full compatibility with existing quality standards.
+
 ## Table of Contents
 
-- [Installation](#installation)
-- [Quick Start](#quick-start)
-- [AI Auto-Fix Features](#ai-auto-fix-features)
-- [Core Features](#core-features)
-- [MCP Server Configuration](#mcp-server-configuration)
-- [Pre-commit Hook Modes](#pre-commit-hook-modes)
-- [Testing Features](#testing-features)
-- [Command Reference](#command-reference)
-- [Style Guide](#style-guide)
-- [Publishing & Version Management](#publishing--version-management)
-- [Developer Experience](#developer-experience)
+- [Crackerjack vs Pre-commit](<#crackerjack-vs-pre-commit-architecture--features>)
+- [Installation](<#installation>)
+- [Quick Start](<#quick-start>)
+- [AI Auto-Fix Features](<#ai-auto-fix-features>)
+- [Core Workflow](<#core-workflow>)
+- [Core Features](<#core-features>)
+- [ACB Architecture & Performance](<#-acb-architecture--performance>)
+- [Adapters](<#adapters>)
+- [Configuration Management](<#-configuration-management-acb-settings--configuration-templates>)
+- [MCP Server Configuration](<#mcp-server-configuration>)
+- [Quality Hook Modes](<#quality-hook-modes>)
+- [Command Reference](<#command-reference>)
+- [Style Guide](<#style-guide>)
+- [Publishing & Version Management](<#publishing--version-management>)
+- [Troubleshooting](<#-troubleshooting>)
 
 ## Installation
 
@@ -158,14 +283,26 @@ Crackerjack is built on the following core principles:
 ### Install UV
 
 ```bash
+# Recommended: Official installer script
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# Alternative: Using pipx
 pipx install uv
+
+# Alternative: Using Homebrew (macOS)
+brew install uv
 ```
 
 ### Install Crackerjack
 
 ```bash
+# Recommended: Using UV (fastest)
+uv tool install crackerjack
+
+# Alternative: Using pip
 pip install crackerjack
-# or
+
+# For existing project: Add as dependency
 uv add crackerjack
 ```
 
@@ -214,7 +351,7 @@ Limited tool-specific auto-fixes for simple formatting issues:
 
 The AI agent intelligently fixes:
 
-- **Type Errors (pyright)**: Adds missing annotations, fixes type mismatches
+- **Type Errors (zuban)**: Adds missing annotations, fixes type mismatches
 - **🔒 Security Issues (bandit)**: Comprehensive security hardening including:
   - **Shell Injection Prevention**: Removes `shell=True` from subprocess calls
   - **Weak Cryptography**: Replaces MD5/SHA1 with SHA256
@@ -235,6 +372,12 @@ The AI agent intelligently fixes:
 # Standard AI agent mode (recommended)
 python -m crackerjack --ai-fix --run-tests --verbose
 
+# Preview fixes without applying (dry-run mode)
+python -m crackerjack --dry-run --run-tests --verbose
+
+# Custom iteration limit
+python -m crackerjack --ai-fix --max-iterations 15
+
 # MCP server with WebSocket support (localhost:8675)
 python -m crackerjack --start-mcp-server
 
@@ -242,6 +385,43 @@ python -m crackerjack --start-mcp-server
 python -m crackerjack.mcp.progress_monitor <job_id> ws://localhost:8675
 ```
 
+#### MCP Integration
+
+When using crackerjack via MCP tools (session-mgmt-mcp):
+
+```python
+# ✅ CORRECT - Use semantic command + ai_agent_mode parameter
+crackerjack_run(command="test", ai_agent_mode=True)
+
+# ✅ CORRECT - With additional arguments
+crackerjack_run(command="check", args="--verbose", ai_agent_mode=True, timeout=600)
+
+# ✅ CORRECT - Dry-run mode
+crackerjack_run(command="test", args="--dry-run", ai_agent_mode=True)
+
+# ❌ WRONG - Don't put flags in command parameter
+crackerjack_run(command="--ai-fix -t")  # This will error!
+
+# ❌ WRONG - Don't use --ai-fix in args
+crackerjack_run(command="test", args="--ai-fix")  # Use ai_agent_mode=True instead
+```
+
+#### Configuration
+
+Auto-fix requires:
+
+1. **Anthropic API key**: Set environment variable
+
+   ```bash
+   export ANTHROPIC_API_KEY=sk-ant-...
+   ```
+
+1. **Configuration file**: `settings/adapters.yml`
+
+   ```yaml
+   ai: claude
+   ```
+
 #### Key Benefits
 
 - **Zero Configuration**: No complex flag combinations needed
@@ -252,7 +432,7 @@ python -m crackerjack.mcp.progress_monitor <job_id> ws://localhost:8675
 
 #### 🤖 Specialized Agent Architecture
 
-**9 Domain-Specific Sub-Agents** for targeted code quality improvements:
+**12 Specialized AI Agents** for comprehensive code quality improvements:
 
 - **🔒 SecurityAgent**: Fixes shell injections, weak crypto, token exposure, unsafe library usage
 - **♻️ RefactoringAgent**: Reduces complexity ≤15, extracts helper methods, applies SOLID principles
@@ -263,6 +443,9 @@ python -m crackerjack.mcp.progress_monitor <job_id> ws://localhost:8675
 - **🧪 TestCreationAgent**: Fixes test failures, missing fixtures, dependency issues
 - **📦 ImportOptimizationAgent**: Removes unused imports, restructures import statements
 - **🔬 TestSpecialistAgent**: Advanced testing scenarios, fixture management
+- **🔍 SemanticAgent**: Advanced semantic analysis, code comprehension, intelligent refactoring suggestions based on business logic understanding
+- **🏗️ ArchitectAgent**: High-level architectural patterns, design recommendations, system-level optimization strategies
+- **🎯 EnhancedProactiveAgent**: Proactive issue prevention, predictive quality monitoring, optimization before problems occur
 
 **Agent Coordination Features**:
 
@@ -273,7 +456,7 @@ python -m crackerjack.mcp.progress_monitor <job_id> ws://localhost:8675
 #### Security & Safety Features
 
 - **Command Validation**: All AI modifications are validated for safety
-- **Enterprise-Grade Regex**: Centralized pattern system eliminates dangerous regex issues
+- **Advanced-Grade Regex**: Centralized pattern system eliminates dangerous regex issues
 - **No Shell Injection**: Uses secure subprocess execution with validated patterns
 - **Rollback Support**: All changes can be reverted via git
 - **Human Review**: Review AI-generated changes before commit
@@ -285,7 +468,7 @@ python -m crackerjack.mcp.progress_monitor <job_id> ws://localhost:8675
 - **🦅 Skylos** (Dead Code Detection): Replaces vulture with **20x performance improvement**
 
   - Rust-powered dead code detection and import analysis
-  - Seamlessly integrates with existing pre-commit workflows
+  - Seamlessly integrates with crackerjack's quality workflow
   - Zero configuration changes required
 
 - **🔍 Zuban** (Type Checking): Replaces pyright with **20-200x performance improvement**
@@ -296,7 +479,7 @@ python -m crackerjack.mcp.progress_monitor <job_id> ws://localhost:8675
 
 **Performance Benefits**:
 
-- **Faster Development Cycles**: Pre-commit hooks complete in seconds, not minutes
+- **Faster Development Cycles**: Quality hooks complete in seconds, not minutes
 - **Improved Developer Experience**: Near-instantaneous feedback during development
 - **Seamless Integration**: Works transparently with existing crackerjack workflows
 - **Zero Breaking Changes**: Same CLI interface, dramatically better performance
@@ -322,19 +505,19 @@ python -m crackerjack --ai-fix --run-tests # Complete workflow optimized
 
 **Optimal Execution Order**:
 
-- **Fast hooks first** → **retry once if any fail** (formatting fixes cascade to other issues)
-- **Code cleaning** → Remove TODO detection, apply standardized patterns
-- **Post-cleaning fast hooks sanity check** → Ensure cleaning didn't introduce issues
-- **Full test suite** → Collect ALL test failures (don't stop on first)
-- **Comprehensive hooks** → Collect ALL quality issues on clean codebase
-- **AI batch fixing** → Process all collected issues intelligently
+- **Fast hooks first** # → **retry once if any fail** (formatting fixes cascade to other issues)
+- **Code cleaning** # → Remove TODO detection, apply standardized patterns
+- **Post-cleaning fast hooks sanity check** # → Ensure cleaning didn't introduce issues
+- **Full test suite** # → Collect ALL test failures (don't stop on first)
+- **Comprehensive hooks** # → Collect ALL quality issues on clean codebase
+- **AI batch fixing** # → Process all collected issues intelligently
 
 **With AI integration:**
 
 - `--ai-fix` flag enables automatic error resolution with specialized sub-agents
 - MCP server allows AI agents to run crackerjack commands with real-time progress tracking
 - Structured error output for programmatic fixes with confidence scoring
-- Enterprise-grade regex pattern system ensures safe automated text transformations
+- Advanced-grade regex pattern system ensures safe automated text transformations
 
 ## Core Features
 
@@ -348,15 +531,15 @@ python -m crackerjack --ai-fix --run-tests # Complete workflow optimized
 
 - **Automated Code Cleaning:** Removes unnecessary docstrings, line comments, and trailing whitespace
 - **Consistent Code Formatting:** Enforces a unified style using [Ruff](https://github.com/astral-sh/ruff), the lightning-fast Python linter and formatter
-- **Comprehensive Pre-commit Hooks:** Installs and manages a robust suite of pre-commit hooks
-- **Interactive Checks:** Supports interactive pre-commit hooks (like `refurb`, `bandit`, and `pyright`) to fix issues in real-time
+- **Comprehensive Quality Hooks:** Direct tool invocation with no wrapper overhead - runs Python tools, Rust analyzers, and security scanners efficiently
+- **Interactive Checks:** Supports interactive quality checks (like `refurb`, `bandit`, and `pyright`) to fix issues in real-time
 - **Static Type Checking:** Enforces type safety with Pyright integration
 
 ### Testing & Coverage Ratchet System
 
 - **Built-in Testing:** Automatically runs tests using `pytest` with intelligent parallelization
 - **Coverage Ratchet:** Revolutionary coverage system that targets 100% - coverage can only increase, never decrease
-- **Milestone Celebrations:** Progress tracking with milestone achievements (15%, 20%, 25%... → 100%)
+- **Milestone Celebrations:** Progress tracking with milestone achievements (15%, 20%, 25%... # → 100%)
 - **No Arbitrary Limits:** Replaced traditional hard limits with continuous improvement toward perfection
 - **Visual Progress:** Rich terminal displays showing journey to 100% coverage
 - **Benchmark Testing:** Performance regression detection and monitoring
@@ -380,7 +563,7 @@ python -m crackerjack --run-tests
 # Example output:
 # 🎉 Coverage improved from 10.11% to 15.50%!
 # 🏆 Milestone achieved: 15% coverage!
-# 📈 Progress: [███░░░░░░░░░░░░░░░░░] 15.50% → 100%
+# 📈 Progress: [███░░░░░░░░░░░░░░░░░] 15.50% # → 100%
 # 🎯 Next milestone: 20% (+4.50% needed)
 ```
 
@@ -389,9 +572,324 @@ python -m crackerjack --run-tests
 - **Intelligent Commit Messages:** Analyzes git changes and suggests descriptive commit messages based on file types and modifications
 - **Commit and Push:** Commits and pushes your changes with standardized commit messages
 - **Pull Request Creation:** Creates pull requests to upstream repositories on GitHub or GitLab
-- **Pre-commit Integration:** Ensures code quality before commits
+- **Git Hook Integration:** Ensures code quality before commits with fast, direct tool execution
+
+## ⚡ ACB Architecture & Performance
+
+Crackerjack is built on the **ACB (Asynchronous Component Base)** framework, providing advanced-grade dependency injection, intelligent caching, and parallel execution.
+
+### What is ACB?
+
+[ACB](https://github.com/lesleslie/acb) is a lightweight dependency injection framework that enables:
+
+- **Module-level registration** via `depends.set()` for clean dependency management
+- **Runtime-checkable protocols** ensuring type safety across all components
+- **Async-first design** with lifecycle management and timeout strategies
+- **Clean separation of concerns** through adapters, orchestrators, and services
+
+### Architecture Overview
+
+**ACB Workflow Engine (Default since Phase 4.2)**
+
+```
+User Command # → BasicWorkflowEngine (ACB)
+    ↓
+Workflow Selection (Standard/Fast/Comprehensive/Test)
+    ↓
+Action Handlers (run_fast_hooks, run_code_cleaning, run_comprehensive_hooks, run_test_workflow)
+    ↓
+asyncio.to_thread() for non-blocking execution
+    ↓
+WorkflowPipeline (DI-injected via context)
+    ↓
+Phase Execution (_run_fast_hooks_phase, _run_comprehensive_hooks_phase, etc.)
+    ↓
+HookManager + TestManager (Manager Layer: 80% compliant)
+    ↓
+Direct adapter.check() calls (No subprocess overhead)
+    ↓
+ToolProxyCacheAdapter (Content-based caching, 70% hit rate)
+    ↓
+Parallel Execution (Up to 11 concurrent adapters)
+    ↓
+Results Aggregation with real-time console output
+```
+
+**Legacy Orchestrator Path** (opt-out with `--use-legacy-orchestrator`)
+
+```
+User Command # → WorkflowOrchestrator (Legacy)
+    ↓
+SessionCoordinator (@depends.inject + protocols)
+    ↓
+PhaseCoordinator (Orchestration Layer)
+    ↓
+HookManager + TestManager
+    ↓
+[Same execution path as ACB from here...]
+```
+
+**Architecture Compliance (Phase 2-4.2 Audit Results)**
+
+| Layer | Compliance | Status | Notes |
+|-------|-----------|--------|-------|
+| **ACB Workflows** | 95% | ✅ Production | **Default since Phase 4.2** - Real-time output, non-blocking |
+| **CLI Handlers** | 90% | ✅ Excellent | Gold standard: `@depends.inject` + `Inject[Protocol]` |
+| **Services** | 95% | ✅ Excellent | Phase 3 refactored, consistent constructors |
+| **Managers** | 80% | ✅ Good | Protocol-based injection, minor improvements needed |
+| **Legacy Orchestration** | 70% | ⚠️ Opt-out | Available with `--use-legacy-orchestrator` |
+| **Coordinators** | 70% | ⚠️ Mixed | Phase coordinators ✅, async needs standardization |
+| **Agent System** | 40% | 📋 Legacy | Uses `AgentContext` pattern (predates ACB) |
+
+**Key Architectural Patterns**
+
+```python
+# ✅ GOLD STANDARD Pattern (from CLI Handlers)
+from acb.depends import depends, Inject
+from crackerjack.models.protocols import Console
+
+
+@depends.inject
+def setup_environment(console: Inject[Console] = None, verbose: bool = False) -> None:
+    """Protocol-based injection with @depends.inject decorator."""
+    console.print("[green]Environment ready[/green]")
+
+
+# ❌ ANTI-PATTERN: Avoid manual fallbacks
+def setup_environment_wrong(console: Console | None = None):
+    self.console = console or Console()  # Bypasses DI container
+```
+
+### Performance Benefits
+
+| Metric | Legacy | ACB Workflows (Phase 4.2) | Improvement |
+|--------|--------|----------------------------|-------------|
+| **Fast Hooks** | ~45s | ~48s | Comparable |
+| **Full Workflow** | ~60s | ~90s | Real-time output |
+| **Console Output** | Buffered | **Real-time streaming** | UX improvement |
+| **Event Loop** | Sync (blocking) | **Async (non-blocking)** | Responsive |
+| **Cache Hit Rate** | 0% | **70%** | New capability |
+| **Concurrent Adapters** | 1 | **11** | 11x parallelism |
+| **DI Context** | Manual | **Protocol-based injection** | Type safety |
+
+### Core Components
+
+#### 1. Quality Assurance Adapters
+
+**Location:** `crackerjack/adapters/`
+
+ACB-registered adapters for all quality checks:
+
+- **Format:** Ruff formatting, mdformat
+- **Lint:** Codespell, complexity analysis
+- **Security:** Bandit security scanning, Gitleaks secret detection
+- **Type:** Zuban type checking (20-200x faster than Pyright)
+- **Refactor:** Creosote (unused dependencies), Refurb (Python idioms)
+- **Complexity:** Complexipy analysis
+- **Utility:** Various validation checks
+- **AI:** Claude integration for intelligent auto-fixing
+
+#### 2. Hook Orchestrator
+
+**Location:** `crackerjack/orchestration/hook_orchestrator.py`
+
+Features:
+
+- **Dual execution mode:** Legacy (pre-commit CLI) + ACB (direct adapters)
+- **Dependency resolution:** Intelligent hook ordering (e.g., format before lint)
+- **Adaptive strategies:** Fast, comprehensive, or dependency-aware execution
+- **Graceful degradation:** Timeout strategies prevent hanging
+
+#### 3. Cache Adapters
+
+**Location:** `crackerjack/orchestration/cache/`
+
+Two caching strategies:
+
+- **ToolProxyCache:** Content-based caching with file hash verification
+- **MemoryCache:** In-memory LRU cache for testing
+
+Benefits:
+
+- **70% cache hit rate** in typical workflows
+- **Content-aware invalidation:** Only re-runs when files actually change
+- **Configurable TTL:** Default 3600s (1 hour)
+
+#### 4. MCP Server Integration
+
+**Location:** `crackerjack/mcp/`
 
-## 🛡️ Enterprise-Grade Pattern Management System
+ACB-registered services:
+
+- **MCPServerService:** FastMCP server for AI agent integration
+- **ErrorCache:** Pattern tracking for AI fix recommendations
+- **JobManager:** WebSocket job tracking and progress streaming
+- **WebSocketSecurityConfig:** Security hardening (localhost-only, rate limiting)
+
+### Migration from Pre-commit
+
+Crackerjack has migrated from pre-commit subprocess calls to direct ACB adapter execution:
+
+**Old Approach (Pre-commit):**
+
+```bash
+pre-commit run ruff --all-files  # Subprocess overhead
+```
+
+**New Approach (ACB):**
+
+```bash
+python -m crackerjack --fast  # Direct Python API, 70% faster
+```
+
+**Migration Guide:** See `docs/README.md` (Migration Notes)
+
+### Configuration Management (ACB Settings & Configuration Templates)
+
+Crackerjack utilizes a **dual configuration system** to handle both runtime application settings and project configuration templates:
+
+#### 1. Runtime Configuration (ACB Settings)
+
+**ACB Settings** manages application runtime configuration:
+
+**Before (11 config files, ~1,808 LOC):**
+
+```python
+from crackerjack.models.config import WorkflowOptions, HookConfig
+from crackerjack.orchestration.config import OrchestrationConfig
+# ... multiple configuration imports
+```
+
+**After (1 settings file, ~300 LOC):**
+
+```python
+from acb.depends import depends
+from crackerjack.config import CrackerjackSettings
+
+settings = depends.get(CrackerjackSettings)
+# Auto-loads from: env vars (CRACKERJACK_*), .env file, defaults
+```
+
+**Benefits:**
+
+- **83% LOC reduction** in configuration code
+- **Automatic environment variable loading** (CRACKERJACK\_\* prefix)
+- **Type validation** via Pydantic
+- **Single source of truth** for all runtime settings
+- **Backward compatible** - Public API unchanged (`create_workflow_options()`)
+
+#### 2. Project Configuration Templates (ConfigTemplateService)
+
+**ConfigTemplateService** manages project-level configuration templates for files like `.pre-commit-config.yaml` and `pyproject.toml`:
+
+```bash
+# Check for available configuration updates
+python -m crackerjack --check-config-updates
+
+# Show diff for specific configuration type
+python -m crackerjack --diff-config pre-commit
+
+# Apply configuration updates interactively
+python -m crackerjack --apply-config-updates --config-interactive
+
+# Refresh configuration cache
+python -m crackerjack --refresh-cache
+```
+
+**ConfigTemplateService Benefits:**
+
+- **Version-based tracking** - Each configuration has version control
+- **User-controlled updates** - Explicit approval required for changes
+- **Diff visibility** - Shows changes before applying
+- **Cache management** - Automatic pre-commit cache invalidation
+- **Template management** - Centralized configuration templates as code
+
+**Config Merge Service (Initialization)**
+
+The ConfigMergeService handles intelligent configuration merging during project initialization:
+
+```python
+# Used by InitializationService for new project setup
+merge_result = config_merge_service.smart_merge_pyproject(
+    source_config, target_path, project_name
+)
+```
+
+**For Complete Configuration System Details:** See `docs/README.md` (Project Structure and Coding Standards).
+
+**Migration Details:** See `docs/README.md` (Migration Notes)
+
+### Using ACB Dependency Injection
+
+Example: Custom QA Adapter
+
+```python
+import uuid
+from contextlib import suppress
+from acb.depends import depends
+from crackerjack.adapters._qa_adapter_base import QAAdapterBase
+
+# Module-level registration (ACB pattern)
+MODULE_ID = uuid.UUID("01937d86-xxxx-xxxx-xxxx-xxxxxxxxxxxx")
+MODULE_STATUS = "stable"
+
+
+class CustomAdapter(QAAdapterBase):
+    @property
+    def adapter_name(self) -> str:
+        return "Custom Checker"
+
+    @property
+    def module_id(self) -> uuid.UUID:
+        return MODULE_ID
+
+    async def check(self, files, config):
+        # Your quality check logic here
+        return QAResult(passed=True, issues=[])
+
+
+# Register with DI container
+with suppress(Exception):
+    depends.set(CustomAdapter)
+```
+
+### Performance Optimization
+
+#### Intelligent Caching
+
+- **Content-based keys:** `{hook_name}:{config_hash}:{content_hash}`
+- **File hash verification:** Detects actual file changes, not just timestamps
+- **LRU eviction:** Automatic cleanup of old entries
+
+#### Parallel Execution
+
+- **Dependency-aware scheduling:** Runs independent hooks in parallel
+- **Semaphore control:** Prevents resource exhaustion
+- **Async I/O:** 76% faster for I/O-bound operations
+
+#### Timeout Strategies
+
+- **Graceful degradation:** Continues execution even if one hook times out
+- **Configurable limits:** Default 60s per hook, 300s overall
+- **Context managers:** Automatic cleanup on timeout
+
+### ACB Benefits
+
+1. **Type Safety:** Runtime-checkable protocols ensure correctness
+1. **Testability:** Easy mocking with `depends.get()`
+1. **Maintainability:** Clear separation between adapters and orchestration
+1. **Observability:** Structured logging with context fields
+1. **Security:** Input validation, timeout protection, origin validation
+1. **Performance:** 47% faster overall execution with intelligent caching
+
+### Documentation
+
+- See `docs/README.md` for consolidated documentation and references.
+- **Code Review Report:** Available from maintainers
+
+**Status:** ✅ Production Ready (as of 2025-10-09)
+
+## 🛡️ Advanced-Grade Pattern Management System
 
 ### Advanced Regex Pattern Validation
 
@@ -426,7 +924,7 @@ MAX_ITERATIONS = 10  # Iterative application limit
 
 # Iterative fixes for complex cases
 pattern.apply_iteratively("pytest - hypothesis - specialist")
-# → "pytest-hypothesis-specialist"
+# # → "pytest-hypothesis-specialist"
 
 # Performance monitoring capabilities
 pattern.get_performance_stats(text, iterations=100)
@@ -438,35 +936,35 @@ pattern.get_performance_stats(text, iterations=100)
 
 ```python
 # PyPI tokens (word boundaries prevent false matches)
-"pypi-AgEIcHlwaS5vcmcCJGE4M2Y3ZjI" → "pypi-****"
+"pypi-AgEIcHlwaS5vcmcCJGE4M2Y3ZjI"  # → "pypi-****"
 
 # GitHub personal access tokens (exactly 40 chars)
-"ghp_1234567890abcdef1234567890abcdef1234" → "ghp_****"
+"ghp_1234567890abcdef1234567890abcdef1234"  # → "ghp_****"
 
 # Generic long tokens (32+ chars with word boundaries)
-"secret_key=abcdef1234567890abcdef1234567890abcdef" → "secret_key=****"
+"secret_key=abcdef1234567890abcdef1234567890abcdef"  # → "secret_key=****"
 ```
 
 **Subprocess Security Fixes**:
 
 ```python
 # Automatic shell injection prevention
-subprocess.run(cmd, shell=True) → subprocess.run(cmd.split())
-subprocess.call(cmd, shell=True) → subprocess.call(cmd.split())
+subprocess.run(cmd, shell=True)  # → subprocess.run(cmd.split())
+subprocess.call(cmd, shell=True)  # → subprocess.call(cmd.split())
 ```
 
 **Unsafe Library Replacements**:
 
 ```python
-# Weak crypto → Strong crypto
-hashlib.md5(data) → hashlib.sha256(data)
-hashlib.sha1(data) → hashlib.sha256(data)
+# Weak crypto # → Strong crypto
+hashlib.md5(data)  # → hashlib.sha256(data)
+hashlib.sha1(data)  # → hashlib.sha256(data)
 
-# Insecure random → Cryptographic random
-random.choice(options) → secrets.choice(options)
+# Insecure random # → Cryptographic random
+random.choice(options)  # → secrets.choice(options)
 
-# Unsafe YAML → Safe YAML
-yaml.load(file) → yaml.safe_load(file)
+# Unsafe YAML # → Safe YAML
+yaml.load(file)  # → yaml.safe_load(file)
 ```
 
 #### Pattern Validation Requirements
@@ -495,7 +993,23 @@ yaml.load(file) → yaml.safe_load(file)
 python -m crackerjack.tools.validate_regex_usage
 ```
 
-This enterprise-grade pattern management system has **eliminated all regex-related spacing and security issues** that previously plagued the codebase, providing a robust foundation for safe text processing operations.
+This advanced-grade pattern management system has **eliminated all regex-related spacing and security issues** that previously plagued the codebase, providing a robust foundation for safe text processing operations.
+
+## Adapters
+
+Adapters connect Crackerjack to external tools and subsystems (e.g., Ruff, Zuban, Bandit) using ACB patterns. Each adapter exposes typed settings, async initialization, and standardized results.
+
+- AI — Claude-powered code fixes: [crackerjack/adapters/ai/README.md](<./crackerjack/adapters/ai/README.md>)
+- Complexity — Code complexity analysis (Complexipy): [crackerjack/adapters/complexity/README.md](<./crackerjack/adapters/complexity/README.md>)
+- Format — Python/Markdown formatting (Ruff, Mdformat): [crackerjack/adapters/format/README.md](<./crackerjack/adapters/format/README.md>)
+- Lint — Spelling and simple linters (Codespell): [crackerjack/adapters/lint/README.md](<./crackerjack/adapters/lint/README.md>)
+- LSP — Rust tools with LSP (Zuban, Skylos): [crackerjack/adapters/lsp/README.md](<./crackerjack/adapters/lsp/README.md>)
+- Refactor — Modernization, dead code, unused deps (Refurb, Skylos, Creosote): [crackerjack/adapters/refactor/README.md](<./crackerjack/adapters/refactor/README.md>)
+- Security — Static analysis and secrets (Bandit, Gitleaks, Pyscn): [crackerjack/adapters/security/README.md](<./crackerjack/adapters/security/README.md>)
+- Type — Static type checking (Zuban, Pyrefly, Ty): [crackerjack/adapters/type/README.md](<./crackerjack/adapters/type/README.md>)
+- Utility — Config-driven checks (EOF newline, regex, size, lock): [crackerjack/adapters/utility/README.md](<./crackerjack/adapters/utility/README.md>)
+
+Quick index: [crackerjack/adapters/README.md](<./crackerjack/adapters/README.md>).
 
 ## MCP Server Configuration
 
@@ -505,10 +1019,10 @@ Model Context Protocol (MCP) enables AI agents to interact directly with Cracker
 
 ### Setup MCP Server
 
-1. **Install MCP dependencies:**
+1. **Install development dependencies (includes MCP tools):**
 
    ```bash
-   uv sync --group mcp
+   uv sync --group dev
    ```
 
 1. **Start the MCP server:**
@@ -662,9 +1176,9 @@ keyring set https://upload.pypi.org/legacy/ __token__
 }
 ```
 
-## Pre-commit Hook Modes
+## Quality Hook Modes
 
-Crackerjack runs hooks in a two-stage process for optimal development workflow:
+Crackerjack runs quality checks in a two-stage process for optimal development workflow:
 
 ### Hook Details
 
@@ -678,7 +1192,7 @@ Crackerjack runs hooks in a two-stage process for optimal development workflow:
 
 **Comprehensive Hooks (~30 seconds):**
 
-- Pyright type checking
+- Zuban type checking
 - Bandit security analysis
 - Dead code detection (vulture)
 - Dependency analysis (creosote)
@@ -709,6 +1223,70 @@ python -m crackerjack --all patch
 python -m crackerjack --ai-fix
 ```
 
+## Quick Reference Index
+
+**📋 Command Index by Use Case**
+
+| Use Case | Command | Description |
+|----------|---------|-------------|
+| **Basic Quality Check** | `python -m crackerjack` | Run quality checks only |
+| **Quality + Tests** | `python -m crackerjack --run-tests` | Quality checks with test suite |
+| **AI Auto-Fix** | `python -m crackerjack --ai-fix --run-tests` | AI-powered fixing + tests (recommended) |
+| **Full Release** | `python -m crackerjack --all patch` | Version bump, quality checks, publish |
+| **Quick Publish** | `python -m crackerjack --publish patch` | Version bump + publish only |
+| **Start MCP Server** | `python -m crackerjack --start-mcp-server` | Launch MCP agent integration |
+| **Monitoring Dashboard** | `python -m crackerjack --dashboard` | Comprehensive monitoring view |
+| **AI Debugging** | `python -m crackerjack --ai-debug --run-tests` | Verbose AI debugging mode |
+| **Coverage Status** | `python -m crackerjack --coverage-status` | Show coverage ratchet progress |
+| **Clear Caches** | `python -m crackerjack --clear-cache` | Reset all cache data |
+| **Fast Iteration** | `python -m crackerjack --skip-hooks` | Skip quality checks during dev |
+| **Documentation** | `python -m crackerjack --generate-docs` | Generate API documentation |
+| **Advanced Features** | See `docs/README.md` | Advanced flags and workflows |
+
+**📑 Alphabetical Flag Reference**
+
+| Flag | Short | Description |
+|------|-------|-------------|
+| `--ai-debug` | - | Verbose debugging for AI auto-fixing |
+| `--ai-fix` | - | Enable AI-powered auto-fixing |
+| `--all` | `-a` | Full release workflow (bump, test, publish) |
+| `--benchmark` | - | Run tests in benchmark mode |
+| `--boost-coverage` | - | Auto-improve test coverage (default) |
+| `--bump` | `-b` | Bump version (patch/minor/major/auto) |
+| `--cache-stats` | - | Display cache statistics |
+| `--clear-cache` | - | Clear all caches and exit |
+| `--commit` | `-c` | Commit and push changes to Git |
+| `--comp` | - | Run only comprehensive hooks |
+| `--coverage-status` | - | Show coverage ratchet status |
+| `--dashboard` | - | Start comprehensive monitoring dashboard |
+| `--debug` | - | Enable debug output |
+| `--dev` | - | Enable development mode for monitors |
+| `--enhanced-monitor` | - | Advanced monitoring with patterns |
+| `--fast` | - | Run only fast hooks |
+| `--generate-docs` | - | Generate API documentation |
+| `--interactive` | `-i` | Use Rich UI interface |
+| `--monitor` | - | Multi-project progress monitor |
+| `--orchestrated` | - | Advanced orchestrated workflow mode |
+| `--publish` | `-p` | Bump version and publish to PyPI |
+| `--quick` | - | Quick mode (3 iterations, for CI/CD) |
+| `--restart-mcp-server` | - | Restart MCP server |
+| `--run-tests` | `-t` | Execute test suite |
+| `--skip-hooks` | `-s` | Skip pre-commit hooks |
+| `--start-mcp-server` | - | Start MCP server |
+| `--stop-mcp-server` | - | Stop MCP server |
+| `--strip-code` | `-x` | Remove docstrings/comments |
+| `--thorough` | - | Thorough mode (8 iterations) |
+| `--unified-dashboard` | - | Unified real-time dashboard |
+| `--verbose` | `-v` | Enable verbose output |
+| `--watchdog` | - | Service watchdog with auto-restart |
+
+**🔗 Related Documentation**
+
+- **Advanced Features**: See `docs/README.md` - consolidated advanced flags
+- **Developer Guide**: [CLAUDE.md](<./CLAUDE.md>) - AI assistant guidelines and developer commands
+
+______________________________________________________________________
+
 ## Command Reference
 
 **Core Workflow Commands:**
@@ -1082,7 +1660,7 @@ python -m crackerjack --start-mcp-server --verbose
 ## Contributing
 
 1. Fork and clone the repository
-1. Run `uv sync --all-groups` to install dependencies
+1. Run `uv sync --group dev` to install dependencies
 1. Ensure `python -m crackerjack` passes all checks
 1. Submit pull request
 
@@ -1096,3 +1674,5 @@ ______________________________________________________________________
 
 **Issues:** [GitHub Issues](https://github.com/lesleslie/crackerjack/issues)
 **Repository:** [GitHub](https://github.com/lesleslie/crackerjack)
+
+# Test