crackerjack 0.39.5__tar.gz → 0.39.7__tar.gz

{crackerjack-0.39.5 → crackerjack-0.39.7}/AGENTS.md

@@ -1,3 +1,7 @@
+______________________________________________________________________
+
+## id: 01K6K1ATWK012TB0ND8A2YZD8F
+
 # Repository Guidelines
 
 ## Project Structure & Module Organization

{crackerjack-0.39.5 → crackerjack-0.39.7}/CHANGELOG.md

@@ -1,3 +1,82 @@
+______________________________________________________________________
+
+## [0.39.7] - 2025-10-03
+
+### Changed
+
+- Crackerjack (quality: 69/100) - 2025-10-03 10:30:07
+- Crackerjack (quality: 69/100) - 2025-10-03 11:48:05
+- Crackerjack (quality: 69/100) - 2025-10-03 12:08:12
+
+### Documentation
+
+- Complete Phase 1 & 2 documentation audit and updates
+- Complete Phase 3 optimization - 100% CLI coverage achieved
+
+### Testing
+
+- test: Update 6 files
+
+## [Unreleased] - 2025-10-03
+
+### Added
+- feat: add new feature
+
+### Fixed
+- fix: resolve bug in parser
+
+
+## [Unreleased] - 2025-10-03
+
+### Added
+
+- feat: add new feature
+
+### Fixed
+
+- fix: resolve bug in parser
+
+## [Unreleased] - 2025-10-03
+
+### Added
+
+- docs: Add documentation for 3 new AI agents (SemanticAgent, ArchitectAgent, EnhancedProactiveAgent)
+- docs: Comprehensive documentation audit report with 73-file inventory
+
+### Changed
+
+- docs: Update agent count from 9 to 12 across README.md and CLAUDE.md
+- docs: Enhanced agent descriptions with capabilities and use cases
+
+## [0.39.6] - 2025-10-03
+
+### Changed
+
+- Crackerjack (quality: 64/100) - 2025-10-02 13:40:49
+- Crackerjack (quality: 64/100) - 2025-10-02 20:06:38
+- Crackerjack (quality: 64/100) - 2025-10-02 20:47:06
+- Crackerjack (quality: 64/100) - 2025-10-02 20:54:53
+- Crackerjack (quality: 64/100) - 2025-10-02 21:20:59
+- Crackerjack (quality: 64/100) - 2025-10-02 22:04:12
+- Crackerjack (quality: 64/100) - 2025-10-02 22:16:32
+- Crackerjack (quality: 68/100) - 2025-10-02 22:58:03
+
+### Testing
+
+- tests: Update 4 files
+
+## [Unreleased] - 2025-10-02
+
+### Added
+
+- feat: add new feature
+
+### Fixed
+
+- fix: resolve bug in parser
+
+## id: 01K6K1AYFVG7DAPYM597FJRPA8
+
 # Changelog
 
 All notable changes to this project will be documented in this file.
@@ -14,11 +93,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased] - 2025-10-02
 
 ### Added
+
 - feat: add new feature
 
 ### Fixed
-- fix: resolve bug in parser
 
+- fix: resolve bug in parser
 
 ## [0.39.4] - 2025-10-01
 

{crackerjack-0.39.5 → crackerjack-0.39.7}/CLAUDE.md

@@ -94,27 +94,27 @@ Crackerjack is an opinionated Python project management tool unifying UV, Ruff,
 
 ## RESPONSE PROTOCOLS
 
-### When Uncertain:
+### When Uncertain
 
 - State: "I need clarification on [specific point] before proceeding."
 - **NEVER** guess or make assumptions.
 - Ask specific questions to get the information needed.
 
-### When Asked "Are You Sure?":
+### When Asked "Are You Sure?"
 
 - Re-examine the code thoroughly.
 - Provide specific evidence for your answer.
 - If uncertain after re-examination, state: "After reviewing, I'm not certain about [specific aspect]. Let me check [specific file/code section]."
 - **MAINTAIN CONSISTENCY** - don't change answers without new evidence.
 
-### Error Handling:
+### Error Handling
 
 - **ANALYZE** the actual error message/response.
 - **NEVER** assume error causes (like rate limits) without evidence.
 - Ask the user to share error details if needed.
 - Provide specific debugging steps.
 
-### Code Cleanup:
+### Code Cleanup
 
 - **ALWAYS** remove unused code when making changes.
 - **NEVER** leave orphaned functions, imports, or variables.
@@ -158,8 +158,8 @@ Remember: It's better to ask for clarification than to make assumptions that cou
 ## AI Documentation References
 
 - **[AI-REFERENCE.md](docs/ai/AI-REFERENCE.md)** - Command reference with decision trees
-- **[AGENT-CAPABILITIES.json](AGENT-CAPABILITIES.json)** - Structured agent data
-- **[ERROR-PATTERNS.yaml](ERROR-PATTERNS.yaml)** - Automated issue resolution patterns
+- **\[[AGENT-CAPABILITIES.json]\]** - Structured agent data
+- **\[[ERROR-PATTERNS.yaml]\]** - Automated issue resolution patterns
 
 ## Essential Commands
 
@@ -188,12 +188,80 @@ python -m crackerjack --restart-mcp-server   # Restart MCP server
 python -m crackerjack --watchdog             # Monitor/restart services
 
 # Release
-python -m crackerjack --full-release patch  # Full release workflow
+python -m crackerjack --all patch  # Full release workflow
 ```
 
+## Developer Command Index
+
+**🔧 Daily Development Workflow**
+
+| Workflow Stage | Command | When to Use |
+|---------------|---------|-------------|
+| **Quick Check** | `python -m crackerjack` | Before committing changes |
+| **Full Validation** | `python -m crackerjack --run-tests` | After feature completion |
+| **AI-Assisted Fix** | `python -m crackerjack --ai-fix --run-tests` | When tests fail or quality issues found |
+| **Fast Iteration** | `python -m crackerjack --skip-hooks` | During active development/debugging |
+| **Debug AI Issues** | `python -m crackerjack --ai-debug --run-tests` | When AI agents behave unexpectedly |
+
+**🐛 Debugging & Troubleshooting**
+
+| Issue | Command | Description |
+|-------|---------|-------------|
+| **AI Agent Issues** | `python -m crackerjack --ai-debug` | Verbose AI debugging output |
+| **Slow Tests** | `python -m crackerjack --test-workers 2` | Reduce parallelization |
+| **Hook Failures** | `python -m crackerjack --skip-hooks` | Bypass pre-commit during dev |
+| **Cache Problems** | `python -m crackerjack --clear-cache` | Reset all caches |
+| **Coverage Issues** | `python -m crackerjack --coverage-status` | Check ratchet status |
+
+**🚀 Release & Publishing**
+
+| Task | Command | Notes |
+|------|---------|-------|
+| **Quick Publish** | `python -m crackerjack --publish patch` | Version bump + publish |
+| **Full Release** | `python -m crackerjack --all patch` | Complete release workflow |
+| **Version Bump Only** | `python -m crackerjack --bump minor` | Update version without publishing |
+| **Interactive Release** | `python -m crackerjack --all interactive` | Choose version interactively |
+
+**🤖 AI Agent Invocation**
+
+| Agent Task | Command Pattern | Confidence Threshold |
+|-----------|----------------|---------------------|
+| **Refactoring** | `--ai-fix` (complexity ≤15) | 0.9 |
+| **Performance** | `--ai-fix` (O(n²) detection) | 0.85 |
+| **Security** | `--ai-fix` (unsafe patterns) | 0.8 |
+| **Testing** | `--ai-fix` (test failures) | 0.8 |
+| **All Agents** | `--ai-fix --run-tests` | ≥0.7 |
+
+**⚡ Performance Optimization**
+
+| Optimization | Command | Impact |
+|--------------|---------|--------|
+| **Benchmark Mode** | `python -m crackerjack --benchmark` | Disable parallelization for accurate timing |
+| **Cache Stats** | `python -m crackerjack --cache-stats` | View hit rates and sizes |
+| **Fast Hooks Only** | `python -m crackerjack --fast` | ~5s execution (formatting only) |
+| **Comprehensive Hooks** | `python -m crackerjack --comp` | ~30s execution (full analysis) |
+| **Quick Mode (CI/CD)** | `python -m crackerjack --quick` | Max 3 iterations |
+
+**📊 Monitoring Commands**
+
+| Monitor Type | Command | Access |
+|-------------|---------|--------|
+| **Comprehensive Dashboard** | `python -m crackerjack --dashboard` | Terminal UI |
+| **Unified Dashboard** | `python -m crackerjack --unified-dashboard` | http://localhost:8675 |
+| **Multi-Project** | `python -m crackerjack --monitor` | Terminal UI |
+| **Enhanced Monitor** | `python -m crackerjack --enhanced-monitor` | Advanced patterns |
+
+**🔗 Quick Links**
+
+- **Advanced Features**: See `docs/ADVANCED-FEATURES.md` for 82 enterprise/power user flags
+- **User Reference**: See `README.md` for comprehensive command reference
+- **Error Patterns**: See `docs/ai/ERROR-PATTERNS.yaml` for automated fixes
+
+______________________________________________________________________
+
 ## AI Agent System
 
-**9 Specialized Agents** handle domain-specific issues:
+**12 Specialized Agents** handle domain-specific issues:
 
 - **RefactoringAgent** (0.9): Complexity ≤15, dead code removal
 - **PerformanceAgent** (0.85): O(n²) detection, optimization
@@ -204,6 +272,9 @@ python -m crackerjack --full-release patch  # Full release workflow
 - **FormattingAgent** (0.8): Style violations, imports
 - **ImportOptimizationAgent**: Import cleanup, reorganization
 - **TestSpecialistAgent** (0.8): Advanced testing scenarios
+- **SemanticAgent** (0.85): Semantic analysis, code comprehension, intelligent refactoring
+- **ArchitectAgent** (0.85): Architecture patterns, design recommendations, system optimization
+- **EnhancedProactiveAgent** (0.9): Proactive prevention, predictive monitoring, preemptive optimization
 
 **Usage**: `--ai-fix` enables batch fixing; confidence ≥0.7 uses specific agents
 
@@ -448,7 +519,7 @@ python -m crackerjack --experimental-hooks  # (when experimental hooks are avail
 
 - **No Active Experimental Hooks**: Previous experimental candidates (pyrefly, ty) failed availability testing and were removed
 - **Framework Ready**: System prepared for future experimental tool evaluation
-- **Documentation**: Complete evaluation criteria in [EXPERIMENTAL-EVALUATION.md](EXPERIMENTAL-EVALUATION.md)
+- **Documentation**: Complete evaluation criteria in \[[EXPERIMENTAL-EVALUATION|EXPERIMENTAL-EVALUATION.md]\]
 
 ## Critical Reminders
 
@@ -492,5 +563,3 @@ from ..models.protocols import TestManagerProtocol
 - make sure to run `python -m crackerjack` after every editing/debugging cycle for quality checking
 - always put implementation plans in a md doc for review and reference
 - think when you need to think, think harder when you need to think harder
-
-# Test debug logging

{crackerjack-0.39.5 → crackerjack-0.39.7}/GEMINI.md

@@ -1,3 +1,7 @@
+______________________________________________________________________
+
+## id: 01K6K1AYRBPF8CGY95H0RMV9C4
+
 # Crackerjack: AI-Powered Python Development Platform
 
 ## Project Overview

{crackerjack-0.39.5 → crackerjack-0.39.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: crackerjack
-Version: 0.39.5
+Version: 0.39.7
 Summary: Crackerjack Python project management tool
 Project-URL: documentation, https://github.com/lesleslie/crackerjack
 Project-URL: homepage, https://github.com/lesleslie/crackerjack
@@ -79,7 +79,7 @@ Description-Content-Type: text/markdown
 [![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)
 [![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-18.4%25-red)
+![Coverage](https://img.shields.io/badge/coverage-18.0%25-red)
 
 ## 🎯 Purpose
 
@@ -142,17 +142,17 @@ Crackerjack is built on the following core principles:
 
 ## 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)
+- \[[#installation|Installation]\]
+- \[[#quick-start|Quick Start]\]
+- \[[#ai-auto-fix-features|AI Auto-Fix Features]\]
+- \[[#core-workflow|Core Workflow]\]
+- \[[#core-features|Core Features]\]
+- \[[#mcp-server-configuration|MCP Server Configuration]\]
+- \[[#pre-commit-hook-modes|Pre-commit Hook Modes]\]
+- \[[#command-reference|Command Reference]\]
+- \[[#style-guide|Style Guide]\]
+- \[[#publishing--version-management|Publishing & Version Management]\]
+- \[[#-troubleshooting|Troubleshooting]\]
 
 ## Installation
 
@@ -258,7 +258,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
@@ -269,6 +269,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**:
 
@@ -715,6 +718,71 @@ 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 \[[ADVANCED-FEATURES|ADVANCED-FEATURES.md]\] | 82 enterprise/power user flags |
+
+**📑 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**: \[[ADVANCED-FEATURES|ADVANCED-FEATURES.md]\] - 82 enterprise/power user flags
+- **Developer Guide**: \[[CLAUDE|CLAUDE.md]\] - AI assistant guidelines and developer commands
+- **Phase 2 Analysis**: \[[PHASE2-CROSS-REFERENCE-ANALYSIS|docs/PHASE2-CROSS-REFERENCE-ANALYSIS.md]\] - CLI flag audit
+
+______________________________________________________________________
+
 ## Command Reference
 
 **Core Workflow Commands:**

{crackerjack-0.39.5 → crackerjack-0.39.7}/README.md

@@ -7,7 +7,7 @@
 [![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)
 [![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-18.4%25-red)
+![Coverage](https://img.shields.io/badge/coverage-18.0%25-red)
 
 ## 🎯 Purpose
 
@@ -70,17 +70,17 @@ Crackerjack is built on the following core principles:
 
 ## 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)
+- \[[#installation|Installation]\]
+- \[[#quick-start|Quick Start]\]
+- \[[#ai-auto-fix-features|AI Auto-Fix Features]\]
+- \[[#core-workflow|Core Workflow]\]
+- \[[#core-features|Core Features]\]
+- \[[#mcp-server-configuration|MCP Server Configuration]\]
+- \[[#pre-commit-hook-modes|Pre-commit Hook Modes]\]
+- \[[#command-reference|Command Reference]\]
+- \[[#style-guide|Style Guide]\]
+- \[[#publishing--version-management|Publishing & Version Management]\]
+- \[[#-troubleshooting|Troubleshooting]\]
 
 ## Installation
 
@@ -186,7 +186,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
@@ -197,6 +197,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**:
 
@@ -643,6 +646,71 @@ 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 \[[ADVANCED-FEATURES|ADVANCED-FEATURES.md]\] | 82 enterprise/power user flags |
+
+**📑 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**: \[[ADVANCED-FEATURES|ADVANCED-FEATURES.md]\] - 82 enterprise/power user flags
+- **Developer Guide**: \[[CLAUDE|CLAUDE.md]\] - AI assistant guidelines and developer commands
+- **Phase 2 Analysis**: \[[PHASE2-CROSS-REFERENCE-ANALYSIS|docs/PHASE2-CROSS-REFERENCE-ANALYSIS.md]\] - CLI flag audit
+
+______________________________________________________________________
+
 ## Command Reference
 
 **Core Workflow Commands:**

{crackerjack-0.39.5 → crackerjack-0.39.7}/crackerjack/mcp/tools/execution_tools.py

@@ -17,37 +17,91 @@ def register_execution_tools(mcp_app: t.Any) -> None:
 def _register_execute_crackerjack_tool(mcp_app: t.Any) -> None:
     @mcp_app.tool()  # type: ignore[misc]
     async def execute_crackerjack(args: str, kwargs: str) -> str:
-        context = get_context()
-
-        validation_error = await _validate_context_and_rate_limit(context)
-        if validation_error:
-            return validation_error
-
-        kwargs_result = _parse_kwargs(kwargs)
-        if "error" in kwargs_result:
-            return json.dumps(kwargs_result)
-
-        extra_kwargs = kwargs_result["kwargs"]
+        try:
+            context = get_context()
+            validation_error = await _handle_context_validation(context)
+            if validation_error:
+                return validation_error
 
-        if "execution_timeout" not in extra_kwargs:
-            if extra_kwargs.get("test", False) or extra_kwargs.get("testing", False):
-                extra_kwargs["execution_timeout"] = 1200
-            else:
-                extra_kwargs["execution_timeout"] = 900
+            kwargs_result = _parse_kwargs(kwargs)
+            if "error" in kwargs_result:
+                return json.dumps(kwargs_result)
 
-        try:
+            extra_kwargs = _prepare_execution_kwargs(kwargs_result["kwargs"])
             result = await execute_crackerjack_workflow(args, extra_kwargs)
             return json.dumps(result, indent=2)
+        except TypeError as e:
+            return _handle_type_error(e)
         except Exception as e:
+            return _handle_general_error(e)
+
+
+async def _handle_context_validation(context: t.Any) -> str | None:
+    """Handle context validation with proper error handling."""
+    from datetime import datetime
+
+    try:
+        validation_error = await _validate_context_and_rate_limit(context)
+        if validation_error:
+            return validation_error
+        return None
+    except TypeError as e:
+        if "NoneType" in str(e) and "await" in str(e):
             return json.dumps(
                 {
                     "status": "failed",
-                    "error": f"Execution failed: {e}",
-                    "timestamp": context.get_current_time()
-                    if hasattr(context, "get_current_time")
-                    else None,
+                    "error": "Context validation failed: rate limiter returned None. "
+                    "MCP server may not be properly initialized.",
+                    "timestamp": datetime.now().isoformat(),
+                    "details": str(e),
                 }
             )
+        raise
+
+
+def _prepare_execution_kwargs(kwargs: dict[str, t.Any]) -> dict[str, t.Any]:
+    """Prepare execution kwargs with appropriate timeout defaults."""
+    if "execution_timeout" not in kwargs:
+        if kwargs.get("test", False) or kwargs.get("testing", False):
+            kwargs["execution_timeout"] = 1200
+        else:
+            kwargs["execution_timeout"] = 900
+    return kwargs
+
+
+def _handle_type_error(error: TypeError) -> str:
+    """Handle TypeError with specific async execution error details."""
+    import traceback
+    from datetime import datetime
+
+    if "NoneType" in str(error) and "await" in str(error):
+        return json.dumps(
+            {
+                "status": "failed",
+                "error": f"Async execution error: A function returned None instead of an awaitable. {error}",
+                "traceback": traceback.format_exc(),
+                "timestamp": datetime.now().isoformat(),
+            }
+        )
+    raise error
+
+
+def _handle_general_error(error: Exception) -> str:
+    """Handle general execution errors with traceback."""
+    import traceback
+    from datetime import datetime
+
+    context = get_context()
+    return json.dumps(
+        {
+            "status": "failed",
+            "error": f"Execution failed: {error}",
+            "traceback": traceback.format_exc(),
+            "timestamp": context.get_current_time()
+            if context and hasattr(context, "get_current_time")
+            else datetime.now().isoformat(),
+        }
+    )
 
 
 def _register_smart_error_analysis_tool(mcp_app: t.Any) -> None: