feat: Auto-Healing System for Python Code Quality

.claude/commands/heal.md

@@ -0,0 +1,11 @@
+---
+allowed-tools: Bash(python .claude/slash_commands/heal.py:*)
+description: Check or heal unhealthy Python modules using the auto-healer
+argument-hint: [--check-only] [--max N] [--threshold N] [--yes]
+---
+
+# /heal — Auto-heal unhealthy Python modules
+
+This command shells out to `.claude/slash_commands/heal.py`, which delegates to the amplifier CLI heal command. See `@.claude/slash_commands/heal.md` for detailed usage examples.
+
+!`python .claude/slash_commands/heal.py $ARGUMENTS`

.claude/settings.json

@@ -14,7 +14,7 @@
       ".vscode",
       ".claude",
       ".ai",
-      "~/amplifier"
+      "~/dev/amplifier"
     ]
   },
   "enableAllProjectMcpServers": false,

.claude/slash_commands/heal.md

@@ -0,0 +1,71 @@
+---
+name: heal
+description: Auto-heal unhealthy Python modules by analyzing and improving code quality
+---
+
+# /heal - Auto-heal unhealthy Python modules
+
+Analyzes Python modules for complexity, lines of code, and type errors, then uses Claude to refactor and improve the code.
+
+## Usage
+
+```bash
+/heal                      # Check health and heal up to 3 modules
+/heal --check-only         # Only check health status, don't heal
+/heal --max 5              # Heal up to 5 modules
+/heal --threshold 80       # Heal modules below 80% health
+/heal --yes                # Skip confirmation prompt
+```
+
+## What it does
+
+The healing system:
+1. Analyzes Python modules for complexity, LOC, and type errors
+2. Identifies modules that fall below the health threshold (default: 70)
+3. Uses Claude to refactor and improve the code
+4. Validates improvements before committing changes
+5. Creates git branches and commits for each healing operation
+
+## Examples
+
+Check module health without healing:
+```bash
+/heal --check-only
+```
+
+Heal up to 5 modules automatically:
+```bash
+/heal --max 5 --yes
+```
+
+Heal modules below 80% health:
+```bash
+/heal --threshold 80
+```
+
+## Health Score
+
+Health score is calculated based on:
+- **Complexity**: Cyclomatic complexity (penalized if > 10)
+- **Lines of Code**: Module length (penalized if > 200 lines)
+- **Type Errors**: Number of type errors from pyright
+
+Score ranges from 0-100, with 100 being perfect health.
+
+## Options
+
+- `--max N`: Maximum number of modules to heal (default: 3)
+- `--threshold N`: Health threshold percentage (default: 70)
+- `--check-only`: Only display health status, don't perform healing
+- `--yes`: Skip confirmation prompt, heal automatically
+- `--project-root PATH`: Override project root directory
+
+## Limitations
+
+- **File size limit**: Modules larger than 400 lines are skipped to prevent timeouts
+- **Critical files**: Files with patterns like `__init__`, `setup`, `config`, `settings`, or `test_` are skipped for safety
+- When a file is skipped, you'll see: `⏭️ filename.py: File too large (692 lines, limit: 400)`
+
+## Implementation
+
+This command delegates to the amplifier CLI: `python -m amplifier.cli heal`

.claude/slash_commands/heal.py

@@ -0,0 +1,25 @@
+#!/usr/bin/env python3
+"""Simplified slash command that delegates to the amplifier CLI heal command."""
+
+import subprocess
+import sys
+from pathlib import Path
+
+
+def main():
+    """Run amplifier heal command with provided arguments."""
+    # Get the project root (2 levels up from this script)
+    project_root = Path(__file__).resolve().parents[2]
+
+    # Build the command: python -m amplifier.cli heal [args]
+    cmd = [sys.executable, "-m", "amplifier.cli", "heal"] + sys.argv[1:]
+
+    # Run the command in the project root directory
+    result = subprocess.run(cmd, cwd=project_root)
+
+    # Exit with the same code as the subprocess
+    sys.exit(result.returncode)
+
+
+if __name__ == "__main__":
+    main()

.env.example

@@ -24,7 +24,7 @@ AMPLIFIER_CONTENT_DIRS=.data/content
 AMPLIFIER_MODEL_FAST=claude-3-5-haiku-20241022
 
 # Default model for standard operations
-AMPLIFIER_MODEL_DEFAULT=claude-sonnet-4-20250514
+AMPLIFIER_MODEL_DEFAULT=claude-sonnet-4-5-20250929
 
 # Thinking model for complex reasoning tasks
 AMPLIFIER_MODEL_THINKING=claude-opus-4-1-20250805
@@ -34,7 +34,7 @@ AMPLIFIER_MODEL_THINKING=claude-opus-4-1-20250805
 KNOWLEDGE_MINING_MODEL=claude-3-5-haiku-20241022
 
 # Powerful model for knowledge extraction (Sonnet for depth)
-KNOWLEDGE_MINING_EXTRACTION_MODEL=claude-sonnet-4-20250514
+KNOWLEDGE_MINING_EXTRACTION_MODEL=claude-sonnet-4-5-20250929
 
 # ========================
 # CONTENT PROCESSING

.gitignore

@@ -17,7 +17,8 @@ __pycache__
 .ruff_cache
 .cache
 *.egg-info
-bin
+# bin directory for build artifacts (but allow our global command)
+# bin
 obj
 dist
 build
@@ -54,6 +55,7 @@ ai_working/tmp
 
 # Default data directory
 .data/
+.amplifier/
 
 # .claude-trace Logs
 .claude-trace

CLAUDE.md

@@ -9,6 +9,7 @@ This file is reserved for Claude Code-specific instructions.
 # import the following files (using the `@` syntax):
 
 - @AGENTS.md
+- @REPOSITORY_GUIDELINES.md
 - @DISCOVERIES.md
 - @ai_context/IMPLEMENTATION_PHILOSOPHY.md
 - @ai_context/MODULAR_DESIGN_PHILOSOPHY.md

Makefile

@@ -21,6 +21,7 @@ default: ## Show essential commands
 	@echo ""
 	@echo "Quick Start:"
 	@echo "  make install         Install all dependencies"
+	@echo "  make install-global  Install global 'amplifier' command"
 	@echo ""
 	@echo "Knowledge Base:"
 	@echo "  make knowledge-update        Full pipeline: extract & synthesize"
@@ -54,6 +55,7 @@ help: ## Show ALL available commands
 	@echo ""
 	@echo "QUICK START:"
 	@echo "  make install         Install all dependencies"
+	@echo "  make install-global  Install global 'amplifier' command"
 	@echo ""
 	@echo "KNOWLEDGE BASE:"
 	@echo "  make knowledge-update        Full pipeline: extract & synthesize"
@@ -140,6 +142,9 @@ install: ## Install all dependencies
 	@echo ""
 	@echo "✅ All dependencies installed!"
 	@echo ""
+	@echo "💡 To use auto-healing globally from any directory:"
+	@echo "   make install-global"
+	@echo ""
 	@if [ -n "$$VIRTUAL_ENV" ]; then \
 		echo "✓ Virtual environment already active"; \
 	elif [ -f .venv/bin/activate ]; then \
@@ -148,6 +153,67 @@ install: ## Install all dependencies
 		echo "✗ No virtual environment found. Run 'make install' first."; \
 	fi
 
+# Global installation
+install-global: ## Install global 'amplifier' command for system-wide access
+	@echo "Installing global amplifier CLI command..."
+	@if [ ! -f .venv/bin/activate ]; then \
+		echo "❌ Please run 'make install' first to create the virtual environment"; \
+		exit 1; \
+	fi
+	@mkdir -p ~/bin
+	@cp bin/amplifier ~/bin/amplifier
+	@chmod +x ~/bin/amplifier
+	@echo "✅ Global 'amplifier' command installed to ~/bin/amplifier"
+	@echo ""
+	@if echo "$$PATH" | grep -q "$$HOME/bin"; then \
+		echo "✓ ~/bin is already in your PATH"; \
+	else \
+		echo "💡 Add ~/bin to your PATH for global access:"; \
+		if [ -n "$$ZSH_VERSION" ] || [ "$$SHELL" = "/bin/zsh" ] || [ -f ~/.zshrc ]; then \
+			echo '   echo "export PATH="\$$HOME/bin:\$$PATH"" >> ~/.zshrc'; \
+			echo "   source ~/.zshrc"; \
+		else \
+			echo '   echo "export PATH="\$$HOME/bin:\$$PATH"" >> ~/.bashrc'; \
+			echo "   source ~/.bashrc"; \
+		fi; \
+	fi
+	@echo ""
+	@echo "Usage: amplifier [project-dir] [claude-options]"
+	@echo "Example: amplifier ~/my-project --model sonnet"
+
+install-global-system: ## Install global 'amplifier' command system-wide (requires sudo)
+	@echo "Installing system-wide Amplifier command..."
+	@if [ ! -f .venv/bin/activate ]; then \
+		echo "❌ Please run 'make install' first to create the virtual environment"; \
+		exit 1; \
+	fi
+	@echo "This will install to /usr/local/bin and requires sudo privileges."
+	@read -p "Continue? [y/N] " -n 1 -r; echo; \
+	if [[ $$REPLY =~ ^[Yy]$$ ]]; then \
+		sudo cp bin/amplifier /usr/local/bin/amplifier; \
+		sudo chmod +x /usr/local/bin/amplifier; \
+		echo "✅ Global 'amplifier' command installed to /usr/local/bin/amplifier"; \
+	else \
+		echo "Installation cancelled."; \
+	fi
+
+uninstall-global: ## Remove global 'amplifier' command
+	@echo "Removing global Amplifier command..."
+	@if [ -f ~/bin/amplifier ]; then \
+		rm ~/bin/amplifier; \
+		echo "✅ Removed ~/bin/amplifier"; \
+	else \
+		echo "✓ ~/bin/amplifier not found"; \
+	fi
+	@if [ -f /usr/local/bin/amplifier ]; then \
+		echo "System-wide installation found at /usr/local/bin/amplifier"; \
+		read -p "Remove it? (requires sudo) [y/N] " -n 1 -r; echo; \
+		if [[ $$REPLY =~ ^[Yy]$$ ]]; then \
+			sudo rm /usr/local/bin/amplifier; \
+			echo "✅ Removed /usr/local/bin/amplifier"; \
+		fi; \
+	fi
+
 # Code quality
 check: ## Format, lint, and type-check all code
 	@# Handle worktree virtual environment issues by unsetting mismatched VIRTUAL_ENV