diff --git a/.claude/rules/25dae845-b52d-411e-a1c4-03e462e4587c.md b/.claude/rules/25dae845-b52d-411e-a1c4-03e462e4587c.md
new file mode 100644
index 0000000..940b429
--- /dev/null
+++ b/.claude/rules/25dae845-b52d-411e-a1c4-03e462e4587c.md
@@ -0,0 +1,86 @@
+<rule_activation id="25dae845-b52d-411e-a1c4-03e462e4587c" title="YAML Configuration Management for Application Settings" applies_to="**/*.py, **/*.yaml, **/*.yml">
+These rules are ALWAYS ACTIVE for all files matching `**/*.py, **/*.yaml, **/*.yml`.
+</rule_activation>
+
+### Rules
+
+- **R-YAML-001** MUST: Use YAML format for all application configuration files in Python projects (rate limiting, pricing, settings).
+- **R-YAML-002** MUST: Include pyyaml>=6.0 dependency for YAML parsing and python-dotenv>=1.0.0 for environment variable loading in requirements.txt.
+- **R-YAML-003** MUST: Load YAML configuration using yaml.safe_load() for security (prevents arbitrary code execution), never use yaml.load().
+- **R-YAML-004** MUST: Store configuration files in dedicated 'config' directory at project root level.
+- **R-YAML-005** SHOULD: Use Path(__file__).parent.parent / 'config' / 'filename.yaml' for cross-platform config file paths.
+- **R-YAML-006** MUST: Load environment variables using python-dotenv's load_dotenv() at application startup.
+- **R-YAML-007** SHOULD: Implement fallback values when configuration files or environment variables are missing.
+- **R-YAML-008** MUST: Create config directory at project root and place all YAML configuration files there.
+- **R-YAML-009** MUST: Import yaml module and load configuration with 'with open(config_path) as f: yaml.safe_load(f)'.
+- **R-YAML-010** MUST: Import dotenv and call load_dotenv() before accessing environment variables.
+- **R-YAML-011** SHOULD: Use os.getenv('KEY_NAME', 'default_value') for environment variable access with fallbacks.
+- **R-YAML-012** SHOULD: Structure YAML with nested dictionaries for logical grouping of related settings.
+- **R-YAML-013** SHOULD: Validate configuration after loading using conditional checks or Pydantic models.
+- **R-YAML-014** SHOULD: Generate YAML output using yaml.dump(data, default_flow_style=False) for readable formatting.
+
+### Verify
+
+```bash
+# Check for config directory at project root
+test -d config && echo "✓ config/ directory exists" || echo "✗ config/ directory missing"
+
+# Check for required dependencies in requirements.txt
+if [ -f requirements.txt ]; then
+  grep -q "pyyaml>=6.0" requirements.txt && echo "✓ pyyaml>=6.0 found" || echo "✗ pyyaml>=6.0 missing"
+  grep -q "python-dotenv>=1.0.0" requirements.txt && echo "✓ python-dotenv>=1.0.0 found" || echo "✗ python-dotenv>=1.0.0 missing"
+else
+  echo "⚠ requirements.txt not found"
+fi
+
+# Check for unsafe yaml.load() usage (should be zero)
+unsafe_yaml=$(grep -r "yaml\.load(" --include="*.py" . 2>/dev/null | grep -v "yaml.safe_load" | wc -l)
+if [ "$unsafe_yaml" -eq 0 ]; then
+  echo "✓ No unsafe yaml.load() usage found"
+else
+  echo "✗ Found $unsafe_yaml unsafe yaml.load() calls (use yaml.safe_load() instead)"
+  grep -rn "yaml\.load(" --include="*.py" . 2>/dev/null | grep -v "yaml.safe_load"
+fi
+
+# Check for yaml.safe_load() usage
+safe_yaml=$(grep -r "yaml\.safe_load" --include="*.py" . 2>/dev/null | wc -l)
+if [ "$safe_yaml" -gt 0 ]; then
+  echo "✓ Found $safe_yaml yaml.safe_load() usage(s)"
+else
+  echo "⚠ No yaml.safe_load() usage found"
+fi
+
+# Check for load_dotenv() usage
+load_dotenv=$(grep -r "load_dotenv()" --include="*.py" . 2>/dev/null | wc -l)
+if [ "$load_dotenv" -gt 0 ]; then
+  echo "✓ Found $load_dotenv load_dotenv() call(s)"
+else
+  echo "⚠ No load_dotenv() calls found"
+fi
+
+# Check for os.getenv usage with fallbacks
+getenv_with_fallback=$(grep -r "os\.getenv(.*," --include="*.py" . 2>/dev/null | wc -l)
+if [ "$getenv_with_fallback" -gt 0 ]; then
+  echo "✓ Found $getenv_with_fallback os.getenv() with fallback(s)"
+fi
+
+# List all YAML files in config directory
+if [ -d config ]; then
+  yaml_count=$(find config -name "*.yaml" -o -name "*.yml" 2>/dev/null | wc -l)
+  echo "✓ Found $yaml_count YAML file(s) in config/"
+  find config -name "*.yaml" -o -name "*.yml" 2>/dev/null | sed 's/^/  - /'
+fi
+```
+
+**Accept when:**
+- All Python files use yaml.safe_load() instead of yaml.load() for YAML parsing
+- Config directory exists at project root containing all YAML configuration files
+- requirements.txt includes pyyaml>=6.0 and python-dotenv>=1.0.0
+- Environment variables are loaded with load_dotenv() at application startup
+- os.getenv() calls include fallback values for critical settings
+- YAML files use nested dictionary structure for logical grouping
+- Configuration validation occurs after loading
+
+<enforcement>
+Claude Code MUST NOT skip or defer verification. Run all verification checks after creating or modifying YAML configuration files, Python configuration loading code, or requirements.txt.
+</enforcement>
\ No newline at end of file
diff --git a/.claude/rules/3bc34719-d377-4cb0-87ad-aea4726e4226.md b/.claude/rules/3bc34719-d377-4cb0-87ad-aea4726e4226.md
new file mode 100644
index 0000000..4034025
--- /dev/null
+++ b/.claude/rules/3bc34719-d377-4cb0-87ad-aea4726e4226.md
@@ -0,0 +1,36 @@
+<rule_activation id="3bc34719-d377-4cb0-87ad-aea4726e4226" title="Use Python For All Development Purposes" applies_to="**">
+These rules are ALWAYS ACTIVE for all development work in this project.
+</rule_activation>
+
+### Rules
+
+- **R-PY-001** MUST: Use Python 3+ for all development purposes. Python 2 is prohibited.
+- **R-PY-002** MUST: Default to Python as the primary language for all new development tasks unless explicitly specified otherwise.
+
+### Verify
+
+**Note:** The source ADR does not include an explicit verification section.
+
+Suggested verification commands:
+
+```bash
+# Check Python version in use
+python --version 2>&1 | grep -E "Python 3\."
+
+# Check for Python 2 shebang lines (should not exist)
+! find . -type f -name "*.py" -exec grep -l "^#!/usr/bin/env python$" {} \; 2>/dev/null
+! find . -type f -name "*.py" -exec grep -l "^#!/usr/bin/python$" {} \; 2>/dev/null
+
+# Verify Python 3 shebang or no version-specific shebang
+find . -type f -name "*.py" -exec grep -l "^#!" {} \; 2>/dev/null | xargs grep -E "(python3|python$)" || true
+```
+
+**Accept when:**
+- All Python scripts use Python 3+ syntax and features
+- Python 3 is specified in shebangs (#!/usr/bin/env python3) or environment configurations
+- No Python 2-specific code or dependencies are present
+- Python is chosen as the default language for new development tasks
+
+<enforcement>
+Claude Code MUST verify Python 3+ usage when working with Python files and MUST default to Python for development tasks.
+</enforcement>
\ No newline at end of file
diff --git a/.claude/rules/625f9120-cde0-48bf-8b08-acf4d18e94d6.md b/.claude/rules/625f9120-cde0-48bf-8b08-acf4d18e94d6.md
new file mode 100644
index 0000000..47da5e3
--- /dev/null
+++ b/.claude/rules/625f9120-cde0-48bf-8b08-acf4d18e94d6.md
@@ -0,0 +1,57 @@
+<rule_activation id="625f9120-cde0-48bf-8b08-acf4d18e94d6" title="Token Bucket Rate Limiting for API Call Management" applies_to="**/*.py">
+These rules are ALWAYS ACTIVE for all Python files implementing API rate limiting.
+</rule_activation>
+
+### Rules
+
+- **R-RL-001** MUST: Implement token bucket algorithm for all API rate limiting in Python applications.
+- **R-RL-002** MUST: Use RateLimiter class with configurable per-minute and per-day request limits for external API clients.
+- **R-RL-003** MUST: Load rate limit configuration from YAML files (rate_limiting.yaml) in config directory.
+- **R-RL-004** MUST: Implement async wait_if_needed() method that delays execution using asyncio.sleep() when limits are exceeded.
+- **R-RL-005** MUST: Track request timestamps using time.time() and maintain sliding window of recent requests.
+- **R-RL-006** SHOULD: Define RateLimitStrategy enum with ROLLING_WINDOW strategy for time-based rate limiting.
+- **R-RL-007** MUST: Provide get_status() method returning current usage statistics (requests made, remaining, reset time).
+- **R-RL-008** MUST: Create @dataclass RateLimitConfig with requests_per_minute and requests_per_day fields.
+- **R-RL-009** MUST: Implement RateLimiter class with __init__ accepting RateLimitConfig and storing request history.
+- **R-RL-010** SHOULD: Use collections.deque or list to track timestamps of recent API requests.
+- **R-RL-011** MUST: Implement async wait_if_needed() that calculates delay based on token replenishment rate.
+- **R-RL-012** MUST: Load configuration from YAML using yaml.safe_load() and create RateLimitConfig instance.
+- **R-RL-013** SHOULD: Wrap API calls with execute_with_rate_limiting() to automatically enforce limits.
+- **R-RL-014** MUST: Calculate time until next available slot by examining oldest request in sliding window.
+
+### Verify
+
+**Note:** The source ADR does not contain an explicit verify section with bash commands. Manual code review is recommended to ensure compliance with the rules above.
+
+Suggested verification approach:
+
+```bash
+# Check for RateLimiter class implementation
+grep -r "class RateLimiter" **/*.py
+
+# Check for RateLimitConfig dataclass
+grep -r "@dataclass" **/*.py | grep -i "RateLimitConfig"
+
+# Check for async wait_if_needed method
+grep -r "async.*wait_if_needed" **/*.py
+
+# Check for YAML configuration loading
+grep -r "yaml.safe_load" **/*.py
+
+# Check for get_status method
+grep -r "def get_status" **/*.py
+```
+
+**Accept when:**
+- RateLimiter class exists with token bucket algorithm implementation
+- RateLimitConfig dataclass defines requests_per_minute and requests_per_day fields
+- Configuration is loaded from YAML file (rate_limiting.yaml)
+- async wait_if_needed() method is implemented with asyncio.sleep() for delay handling
+- Request timestamps are tracked using time.time() in a sliding window data structure
+- get_status() method returns current usage statistics including requests made, remaining capacity, and reset time
+- Time calculations examine oldest request in sliding window to determine next available slot
+- API calls are wrapped with rate limiting enforcement mechanism
+
+<enforcement>
+Claude Code MUST NOT skip or defer verification when implementing or modifying rate limiting code.
+</enforcement>
\ No newline at end of file
diff --git a/.claude/rules/9ba96edd-ccd6-4170-8c18-433e72baae10.md b/.claude/rules/9ba96edd-ccd6-4170-8c18-433e72baae10.md
new file mode 100644
index 0000000..267909e
--- /dev/null
+++ b/.claude/rules/9ba96edd-ccd6-4170-8c18-433e72baae10.md
@@ -0,0 +1,60 @@
+<rule_activation id="9ba96edd-ccd6-4170-8c18-433e72baae10" title="Anthropic Claude AI Integration for Code Analysis" applies_to="**/*.py">
+These rules are ALWAYS ACTIVE for all Python files matching `**/*.py`.
+</rule_activation>
+
+### Rules
+
+- **R-CAI-001** MUST: Use Anthropic Claude API (via BAML client) for all AI-powered code analysis in Python files.
+- **R-CAI-002** MUST: Default to 'claude-sonnet-4-20250514' model for analysis tasks unless specific model requirements dictate otherwise.
+- **R-CAI-003** MUST: Store Anthropic API keys in environment variables (ANTHROPIC_API_KEY) and never hardcode credentials in Python source files.
+- **R-CAI-004** MUST: Validate BAML client initialization before performing any AI operations using check_baml_client() validation.
+- **R-CAI-005** MUST: Import AI functionality from baml_client.async_client module for all async AI operations.
+- **R-CAI-006** SHOULD: Track token usage for all Claude API calls to monitor costs and usage patterns.
+- **R-CAI-007** SHOULD: Set BAML_LOG environment variable to 'OFF' to disable verbose logging in production.
+- **R-CAI-008** MUST: Add baml-py>=0.202.1 dependency to requirements.txt for Claude AI integration.
+- **R-CAI-009** MUST: Initialize BAML client at application startup before any analysis operations.
+- **R-CAI-010** MUST: Load ANTHROPIC_API_KEY from environment using os.getenv() with fallback to credentials.json.
+- **R-CAI-011** SHOULD: Configure rate limiting and token tracking for all Claude API calls.
+- **R-CAI-012** MUST: Use async/await pattern with BAML client for concurrent AI operations.
+- **R-CAI-013** MUST: Import types from baml_client.types (e.g., StaticAnalysisRule, FileInfo) for type safety.
+- **R-CAI-014** MUST: Implement error handling for missing API keys with user-friendly error messages.
+
+### Verify
+
+```bash
+# Check for hardcoded API keys (R-CAI-003)
+grep -r "ANTHROPIC_API_KEY.*=.*sk-" --include="*.py" . && echo "FAIL: Hardcoded API keys found" || echo "PASS: No hardcoded API keys"
+
+# Verify baml-py dependency (R-CAI-008)
+grep -E "baml-py>=0\.202\.1" requirements.txt && echo "PASS: baml-py dependency present" || echo "FAIL: Missing baml-py>=0.202.1"
+
+# Check for BAML client imports (R-CAI-005, R-CAI-013)
+grep -r "from baml_client.async_client import" --include="*.py" . && echo "PASS: BAML async_client imports found" || echo "WARN: No BAML async_client imports"
+grep -r "from baml_client.types import" --include="*.py" . && echo "PASS: BAML types imports found" || echo "WARN: No BAML types imports"
+
+# Verify environment variable usage (R-CAI-010)
+grep -r "os\.getenv.*ANTHROPIC_API_KEY" --include="*.py" . && echo "PASS: Environment variable loading present" || echo "WARN: No environment variable loading found"
+
+# Check for BAML client validation (R-CAI-004)
+grep -r "check_baml_client" --include="*.py" . && echo "PASS: BAML client validation found" || echo "WARN: No check_baml_client() validation"
+
+# Verify async/await pattern usage (R-CAI-012)
+grep -r "async def.*:" --include="*.py" . | grep -q "baml" && echo "PASS: Async patterns with BAML found" || echo "INFO: Check async usage manually"
+
+# Check for claude-sonnet-4 model configuration (R-CAI-002)
+grep -r "claude-sonnet-4" --include="*.py" . && echo "PASS: Claude Sonnet 4 model configured" || echo "WARN: No Claude Sonnet 4 model configuration found"
+```
+
+**Accept when:**
+- No hardcoded ANTHROPIC_API_KEY credentials found in Python source files
+- baml-py>=0.202.1 dependency present in requirements.txt
+- BAML client imports from baml_client.async_client and baml_client.types are used
+- API keys loaded via os.getenv('ANTHROPIC_API_KEY') with appropriate fallbacks
+- BAML client validation (check_baml_client) implemented before AI operations
+- Async/await patterns used with BAML client for concurrent operations
+- Claude Sonnet 4 model configured as default for analysis tasks
+- Token tracking and error handling implemented for API calls
+
+<enforcement>
+Claude Code MUST NOT skip or defer verification. All rules must be validated before committing changes to Python files that integrate with Anthropic Claude API.
+</enforcement>
\ No newline at end of file
diff --git a/.claude/rules/a117ee09-e9ea-4860-bd61-9469cb3efb8e.md b/.claude/rules/a117ee09-e9ea-4860-bd61-9469cb3efb8e.md
new file mode 100644
index 0000000..d6b00fa
--- /dev/null
+++ b/.claude/rules/a117ee09-e9ea-4860-bd61-9469cb3efb8e.md
@@ -0,0 +1,37 @@
+<rule_activation id="a117ee09-e9ea-4860-bd61-9469cb3efb8e" title="Adopt External API Client Pattern for Third-Party Service Integration" applies_to="rulectl/**">
+These rules are ALWAYS ACTIVE for all files matching `rulectl/**` that integrate with external third-party services and APIs.
+</rule_activation>
+
+### Rules
+
+- **R-EXT-API-001** MUST: Implement dedicated external API client abstractions that encapsulate all interactions with third-party services.
+- **R-EXT-API-002** MUST: Provide a clean interface for external service operations within each client.
+- **R-EXT-API-003** MUST: Handle authentication and authorization within the API client abstraction.
+- **R-EXT-API-004** MUST: Implement retry logic and rate limiting for all external API calls.
+- **R-EXT-API-005** MUST: Provide consistent error handling across all external API interactions.
+- **R-EXT-API-006** MUST: Separate external API concerns from business logic to maintain modularity.
+- **R-EXT-API-007** MUST: Design clients with clear boundaries that isolate external dependencies.
+- **R-EXT-API-008** MUST: Provide mock-friendly interfaces for testing to ensure testability.
+- **R-EXT-API-009** SHOULD: Centralize authentication and rate limiting logic to reduce code duplication.
+- **R-EXT-API-010** SHOULD: Ensure external service integrations can be swapped or upgraded without affecting business logic.
+
+### Verify
+
+**Note:** The source ADR does not include explicit verification commands. Manual code review should verify:
+- External API clients are properly abstracted
+- Authentication, retry logic, and rate limiting are implemented
+- Error handling is consistent
+- Business logic is separated from API client concerns
+- Mock-friendly interfaces exist for testing
+
+**Accept when:**
+- Consistent error handling and retry logic is implemented across all external API interactions
+- Improved testability through clear abstraction boundaries and mock-friendly interfaces
+- Centralized authentication and rate limiting logic reduces code duplication
+- External service integrations can be swapped or upgraded without affecting business logic
+- Better observability and monitoring of external API calls through centralized client code
+- External API clients encapsulate all third-party service interactions
+
+<enforcement>
+Claude Code MUST apply these rules when working with external API integrations. Code review MUST verify compliance with the external API client pattern.
+</enforcement>
\ No newline at end of file
diff --git a/.claude/rules/b2b7e9e6-03c0-4345-b6d1-ed075188ffea.md b/.claude/rules/b2b7e9e6-03c0-4345-b6d1-ed075188ffea.md
new file mode 100644
index 0000000..f445bba
--- /dev/null
+++ b/.claude/rules/b2b7e9e6-03c0-4345-b6d1-ed075188ffea.md
@@ -0,0 +1,61 @@
+<rule_activation id="b2b7e9e6-03c0-4345-b6d1-ed075188ffea" title="Adopt External API Integration Pattern with Rate Limiting and Token Tracking" applies_to="**/{utils.py,token_tracker.py,rate_limiter.py,git_utils.py}">
+These rules are ALWAYS ACTIVE for all external API integration modules including rate limiting, token tracking, Git utilities, and shared utility functions.
+</rule_activation>
+
+### Rules
+
+- **R-API-001** MUST: Implement a centralized rate limiting mechanism to respect API quotas and prevent throttling across all external API interactions.
+- **R-API-002** MUST: Implement token tracking to monitor and manage API usage across requests, providing visibility into usage patterns.
+- **R-API-003** MUST: Create specialized utility modules for Git operations that abstract external service interactions from business logic.
+- **R-API-004** MUST: Provide shared utility functions with consistent error handling and retry logic for all external API calls.
+- **R-API-005** SHOULD: Implement exponential backoff mechanisms in retry logic to handle transient failures gracefully.
+- **R-API-006** MUST: Maintain rate limiting state and token tracking data structures to enable proactive quota management.
+- **R-API-007** MAY: Include configurable rate limit thresholds per API endpoint to accommodate different service tier limits.
+
+### Context
+
+The system integrates with external APIs (Git-based services and third-party APIs) that impose rate limits and require careful resource management. Without proper rate limiting and token tracking, the application risks hitting API quotas, experiencing service degradation, and failing to provide reliable external integrations.
+
+### Verify
+
+```bash
+# Check for rate limiting module
+test -f rate_limiter.py && echo "✓ Rate limiter module exists" || echo "✗ Missing rate_limiter.py"
+
+# Check for token tracking module
+test -f token_tracker.py && echo "✓ Token tracker module exists" || echo "✗ Missing token_tracker.py"
+
+# Check for Git utilities abstraction
+test -f git_utils.py && echo "✓ Git utilities module exists" || echo "✗ Missing git_utils.py"
+
+# Check for shared utilities with error handling
+test -f utils.py && echo "✓ Utils module exists" || echo "✗ Missing utils.py"
+
+# Verify rate limiting implementation (check for common patterns)
+if [ -f rate_limiter.py ]; then
+  grep -q "rate.*limit\|throttle\|quota" rate_limiter.py && echo "✓ Rate limiting logic present" || echo "✗ No rate limiting patterns found"
+fi
+
+# Verify token tracking implementation
+if [ -f token_tracker.py ]; then
+  grep -q "token\|usage\|track" token_tracker.py && echo "✓ Token tracking logic present" || echo "✗ No token tracking patterns found"
+fi
+
+# Verify retry logic with backoff
+if [ -f utils.py ]; then
+  grep -q "retry\|backoff\|sleep" utils.py && echo "✓ Retry logic present" || echo "✗ No retry patterns found"
+fi
+```
+
+**Accept when:**
+- All four core modules (utils.py, token_tracker.py, rate_limiter.py, git_utils.py) exist and contain relevant implementation
+- Rate limiting mechanisms are implemented to prevent API quota violations
+- Token tracking provides visibility into API usage patterns across requests
+- Git operations are abstracted through specialized utility modules
+- Consistent error handling and retry logic with backoff is implemented for external API calls
+- Rate limiting state and token tracking data structures are maintained
+- External API interactions follow the standardized pattern with built-in safeguards
+
+<enforcement>
+Claude Code MUST NOT skip or defer verification. Before completing any changes to external API integration modules, run the verification commands to ensure the rate limiting and token tracking pattern is properly implemented and all required modules are present.
+</enforcement>
\ No newline at end of file
diff --git a/.claude/rules/b4c009f0-92b6-4477-8d9f-ea56ca93893e.md b/.claude/rules/b4c009f0-92b6-4477-8d9f-ea56ca93893e.md
new file mode 100644
index 0000000..3bb93b2
--- /dev/null
+++ b/.claude/rules/b4c009f0-92b6-4477-8d9f-ea56ca93893e.md
@@ -0,0 +1,58 @@
+<rule_activation id="b4c009f0-92b6-4477-8d9f-ea56ca93893e" title="Token Usage Monitoring and Cost Tracking for AI Operations" applies_to="**/*.py">
+These rules are ALWAYS ACTIVE for all Python files using LLMs/AI APIs.
+</rule_activation>
+
+### Rules
+
+- **R-TKN-001** MUST: Implement TokenTracker class for monitoring AI API token usage and cost across all Python applications using LLMs.
+- **R-TKN-002** MUST: Track both input and output tokens separately (total_input_tokens, total_output_tokens) for accurate cost calculation and reporting.
+- **R-TKN-003** MUST: Load model pricing configuration from YAML files with per-model input/output token costs using yaml.safe_load().
+- **R-TKN-004** MUST: Record token usage per analysis phase using track_call_from_collector() method with phase identifiers.
+- **R-TKN-005** MUST: Calculate cumulative costs in real-time based on current token counts and model pricing.
+- **R-TKN-006** MUST: Set default model to 'claude-sonnet-4-20250514' from pricing configuration '_default' key.
+- **R-TKN-007** MUST: Provide get_total_tokens() method returning cumulative input/output token counts for reporting.
+- **R-TKN-008** MUST: Create TokenTracker class with __init__ initializing total_input_tokens and total_output_tokens to 0.
+- **R-TKN-009** MUST: Store pricing as nested dict with model names as keys and 'input'/'output' cost per 1M tokens.
+- **R-TKN-010** MUST: Calculate costs by multiplying token count by price per million tokens.
+- **R-TKN-011** MUST: Implement get_total_tokens() returning dictionary with 'input', 'output', and 'total' keys.
+- **R-TKN-012** MUST: Update token counters after each API call by extracting usage from API response metadata.
+
+### Verify
+
+```bash
+# Check for TokenTracker class implementation
+grep -r "class TokenTracker" --include="*.py" .
+
+# Verify track_call_from_collector method exists
+grep -r "def track_call_from_collector" --include="*.py" .
+
+# Verify get_total_tokens method exists
+grep -r "def get_total_tokens" --include="*.py" .
+
+# Check for token tracking attributes
+grep -r "total_input_tokens\|total_output_tokens" --include="*.py" .
+
+# Verify YAML pricing file loading
+grep -r "yaml.safe_load" --include="*.py" .
+
+# Check for model_pricing dictionary
+grep -r "model_pricing" --include="*.py" .
+
+# Verify default model configuration
+grep -r "claude-sonnet-4-20250514\|_default" --include="*.py" .
+```
+
+**Accept when:**
+- TokenTracker class is defined with __init__ method
+- total_input_tokens and total_output_tokens attributes are initialized to 0
+- track_call_from_collector(phase, model) method is implemented
+- get_total_tokens() method returns dictionary with 'input', 'output', and 'total' keys
+- Model pricing is loaded from YAML file using yaml.safe_load()
+- Pricing stored as nested dictionary with per-model input/output costs per 1M tokens
+- Default model set to 'claude-sonnet-4-20250514' from '_default' configuration key
+- Token counters updated after each API call from response metadata
+- Real-time cost calculation implemented by multiplying token counts by pricing
+
+<enforcement>
+Claude Code MUST NOT skip or defer verification. All token tracking implementations must be verified against these rules before acceptance.
+</enforcement>
\ No newline at end of file
diff --git a/.claude/rules/cceac33f-b2b2-426e-bf44-9b81cdfb29e8.md b/.claude/rules/cceac33f-b2b2-426e-bf44-9b81cdfb29e8.md
new file mode 100644
index 0000000..9326cb4
--- /dev/null
+++ b/.claude/rules/cceac33f-b2b2-426e-bf44-9b81cdfb29e8.md
@@ -0,0 +1,56 @@
+<rule_activation id="cceac33f-b2b2-426e-bf44-9b81cdfb29e8" title="Click Framework for CLI Application Architecture" applies_to="**/*.py">
+These rules are ALWAYS ACTIVE for all Python files matching `**/*.py` that implement CLI functionality.
+</rule_activation>
+
+### Rules
+
+- **R-CLICK-001** MUST: Use Click framework (click>=8.0.0) for all command-line interface implementation in Python applications.
+- **R-CLICK-002** MUST: Structure CLI with @click.group() decorator at the top level and @click.command() for subcommands.
+- **R-CLICK-003** MUST: Define command-line options using @click.option() with type hints, help text, and default values.
+- **R-CLICK-004** MUST: Use @click.argument() for required positional arguments with click.Choice() for enumerated values.
+- **R-CLICK-005** MUST: Include colorama>=0.4.6 for cross-platform colored terminal output in all CLI applications.
+- **R-CLICK-006** SHOULD: Implement --verbose/-v flag for debug output and --force/-f flag to skip confirmation prompts.
+- **R-CLICK-007** MUST: Provide clear help text for all commands and options using the help parameter.
+- **R-CLICK-008** MUST: Use click.echo() for all output instead of print() for better CLI compatibility.
+- **R-CLICK-009** SHOULD: Implement click.Choice() for restricted argument values (e.g., provider choices).
+- **R-CLICK-010** SHOULD: Add click.prompt() for interactive input when required values are not provided.
+
+### Verify
+
+```bash
+# Check for Click framework import and decorators
+grep -r "import click" **/*.py 2>/dev/null | head -5
+grep -r "@click.group\|@click.command\|@click.option\|@click.argument" **/*.py 2>/dev/null | head -10
+
+# Verify Click version in requirements
+grep "click>=8.0.0" requirements.txt 2>/dev/null || grep "click" requirements.txt 2>/dev/null
+
+# Check for colorama in requirements
+grep "colorama>=0.4.6" requirements.txt 2>/dev/null || grep "colorama" requirements.txt 2>/dev/null
+
+# Verify click.echo() usage instead of print() in CLI files
+if [ -n "$(find . -name '*cli*.py' -o -name '*command*.py' 2>/dev/null)" ]; then
+  grep -l "print(" *cli*.py *command*.py 2>/dev/null && echo "Warning: Found print() calls in CLI files, should use click.echo()" || echo "OK: Using click.echo() in CLI files"
+fi
+
+# Check for help text in options
+grep -r "@click.option.*help=" **/*.py 2>/dev/null | wc -l
+
+# Verify common CLI flags
+grep -r "\-\-verbose\|\-v.*help=" **/*.py 2>/dev/null | head -3
+grep -r "\-\-force\|\-f.*help=" **/*.py 2>/dev/null | head -3
+```
+
+**Accept when:**
+- Click framework is imported in CLI implementation files
+- CLI commands are structured using @click.group() and @click.command() decorators
+- Options are defined with @click.option() including help text
+- Arguments use @click.argument() with appropriate type constraints
+- click>=8.0.0 and colorama>=0.4.6 are listed in requirements.txt or pyproject.toml
+- Output uses click.echo() instead of print() in CLI files
+- Common flags (--verbose, --force) are implemented where appropriate
+- All commands and options include descriptive help text
+
+<enforcement>
+Claude Code MUST verify Click framework patterns when creating or modifying CLI implementations. Claude Code MUST NOT skip or defer verification of these patterns.
+</enforcement>
\ No newline at end of file
diff --git a/.claude/rules/e8f63640-71fd-4cba-911f-575be681b2cf.md b/.claude/rules/e8f63640-71fd-4cba-911f-575be681b2cf.md
new file mode 100644
index 0000000..fc1e1c7
--- /dev/null
+++ b/.claude/rules/e8f63640-71fd-4cba-911f-575be681b2cf.md
@@ -0,0 +1,62 @@
+<rule_activation id="e8f63640-71fd-4cba-911f-575be681b2cf" title="Git Repository Integration for Provenance Tracking" applies_to="**/*.py">
+These rules are ALWAYS ACTIVE for all files matching `**/*.py` that integrate with Git repositories.
+
+Evidence from rulectl/git_utils.py (1,643 lines) and rulectl/analyzer.py demonstrates deep Git integration implemented by Ethan (2025-09-02, commit b4a0531a). The GitAnalyzer class provides git blame analysis, branch detection, commit history tracking, and gitignore-based file filtering for provenance tracking.
+</rule_activation>
+
+### Rules
+
+- **R-GIT-001** MUST: Use subprocess module with git commands for all Git repository operations in Python applications.
+- **R-GIT-002** MUST: Validate Git repository existence before performing any git operations using subprocess.run(['git', 'rev-parse', '--git-dir']).
+- **R-GIT-003** MUST: Use subprocess.run() with git commands, capturing stdout with text=True and check=True parameters.
+- **R-GIT-004** MUST: Implement _validate_git_repo() method calling 'git rev-parse --git-dir' to verify repository.
+- **R-GIT-005** SHOULD: Integrate gitignore patterns for file filtering using pathspec module with 'gitwildmatch' pattern type.
+- **R-GIT-006** SHOULD: Implement git blame analysis to track file provenance including author, date, and commit metadata.
+- **R-GIT-007** SHOULD: Detect repository main branch dynamically by checking for 'main', 'master', or current branch.
+- **R-GIT-008** SHOULD: Use Path.resolve() for absolute path resolution when working with Git repository paths.
+- **R-GIT-009** SHOULD: Extract git metadata (commit hash, author, email, date) for all analyzed files to support provenance tracking.
+- **R-GIT-010** SHOULD: Create GitAnalyzer class with __init__ accepting repo_path and validating Git repository.
+- **R-GIT-011** SHOULD: Parse git blame output to extract line-by-line author and commit information.
+- **R-GIT-012** SHOULD: Load and parse .gitignore file using pathspec.PathSpec.from_lines('gitwildmatch', patterns).
+- **R-GIT-013** SHOULD: Implement get_file_statistics() to return commit count and author data per file.
+- **R-GIT-014** SHOULD: Use collections.defaultdict and collections.Counter for aggregating Git statistics.
+
+### Verify
+
+```bash
+# Check for subprocess usage with git commands (R-GIT-001, R-GIT-003)
+grep -r "subprocess\.run.*git" **/*.py || echo "WARNING: No subprocess git commands found"
+
+# Verify git repository validation (R-GIT-002, R-GIT-004)
+grep -r "git.*rev-parse.*--git-dir" **/*.py || echo "WARNING: No git repository validation found"
+
+# Check for GitAnalyzer class with proper initialization (R-GIT-010)
+grep -r "class GitAnalyzer" **/*.py || echo "WARNING: GitAnalyzer class not found"
+
+# Verify gitignore pattern integration (R-GIT-005, R-GIT-012)
+grep -r "pathspec.*gitwildmatch" **/*.py || echo "INFO: pathspec gitwildmatch not found (optional)"
+
+# Check for git blame implementation (R-GIT-006, R-GIT-011)
+grep -r "git.*blame" **/*.py || echo "INFO: git blame not found (optional)"
+
+# Verify Path.resolve() usage (R-GIT-008)
+grep -r "Path.*\.resolve\(\)" **/*.py || echo "INFO: Path.resolve() not found (optional)"
+
+# Check for collections usage in statistics (R-GIT-014)
+grep -r "collections\.\(defaultdict\|Counter\)" **/*.py || echo "INFO: collections defaultdict/Counter not found (optional)"
+```
+
+**Accept when:**
+- GitAnalyzer class exists with __init__ accepting repo_path parameter
+- Git repository validation is performed before any git operations
+- subprocess.run() is used with text=True and check=True for git commands
+- _validate_git_repo() method implements 'git rev-parse --git-dir' check
+- Error handling exists for invalid repositories or failed git operations
+- (Optional) pathspec module is used for gitignore pattern matching with 'gitwildmatch'
+- (Optional) git blame parsing extracts author, date, and commit metadata
+- (Optional) Main branch detection checks for 'main', 'master', or current branch
+- (Optional) collections.defaultdict and Counter are used for aggregating statistics
+
+<enforcement>
+Claude Code MUST NOT skip or defer verification. All MUST-level rules (R-GIT-001 through R-GIT-004) are mandatory for Git repository integration. SHOULD-level rules are strongly recommended for complete provenance tracking functionality.
+</enforcement>
\ No newline at end of file
diff --git a/.claude/rules/f039b8d8-cf8f-4c0a-bee1-dcae5c086c0c.md b/.claude/rules/f039b8d8-cf8f-4c0a-bee1-dcae5c086c0c.md
new file mode 100644
index 0000000..72b2442
--- /dev/null
+++ b/.claude/rules/f039b8d8-cf8f-4c0a-bee1-dcae5c086c0c.md
@@ -0,0 +1,76 @@
+<rule_activation id="f039b8d8-cf8f-4c0a-bee1-dcae5c086c0c" title="Asynchronous Programming with Asyncio for Concurrent Operations" applies_to="**/*.py">
+These rules are ALWAYS ACTIVE for all Python files matching `**/*.py`. Apply async/await patterns for I/O-bound operations including API calls and file processing.
+</rule_activation>
+
+### Rules
+
+- **R-ASYNCIO-001** MUST: Use async/await pattern for all I/O-bound operations including API calls and file processing in Python modules.
+- **R-ASYNCIO-002** MUST: Import asyncio module for event loop management and concurrency primitives.
+- **R-ASYNCIO-003** MUST: Define async functions with 'async def' for any operation that performs network requests or file I/O.
+- **R-ASYNCIO-004** MUST: Use 'await' keyword for all async function calls and use asyncio.sleep() instead of time.sleep() in async contexts.
+- **R-ASYNCIO-005** MUST: Implement async context managers for resource management in asynchronous code.
+- **R-ASYNCIO-006** SHOULD: Use asyncio.gather() or asyncio.create_task() for concurrent execution of multiple async operations.
+- **R-ASYNCIO-007** MUST: Call asyncio.run() at the entry point to execute async main functions from synchronous code.
+- **R-ASYNCIO-008** MUST: Add 'async' keyword before 'def' for functions that perform I/O operations.
+- **R-ASYNCIO-009** MUST: Add 'await' before calling async functions, API clients, or asyncio.sleep().
+- **R-ASYNCIO-010** MUST: Wrap synchronous entry points with asyncio.run(async_main_function()).
+- **R-ASYNCIO-011** MUST: Use 'async with' for async context managers (e.g., async API clients).
+- **R-ASYNCIO-012** SHOULD: Batch API requests and use asyncio.gather() for concurrent execution.
+- **R-ASYNCIO-013** SHOULD: Implement rate limiting with async delays using asyncio.sleep() between requests.
+- **R-ASYNCIO-014** MUST: Handle exceptions in async code with try/except around await statements.
+
+### Verify
+
+```bash
+# Check for async def usage in Python files
+grep -r "async def" --include="*.py" . || echo "No async functions found"
+
+# Check for asyncio imports
+grep -r "import asyncio" --include="*.py" . || echo "No asyncio imports found"
+
+# Check for await keyword usage
+grep -r "await " --include="*.py" . || echo "No await statements found"
+
+# Check for asyncio.run() at entry points
+grep -r "asyncio.run(" --include="*.py" . || echo "No asyncio.run() calls found"
+
+# Check for async context managers
+grep -r "async with" --include="*.py" . || echo "No async context managers found"
+
+# Check for asyncio.gather() usage
+grep -r "asyncio.gather(" --include="*.py" . || echo "No asyncio.gather() calls found"
+
+# Check for asyncio.sleep() usage (should be used instead of time.sleep in async contexts)
+grep -r "asyncio.sleep(" --include="*.py" . || echo "No asyncio.sleep() calls found"
+
+# Verify no time.sleep in async functions (anti-pattern)
+if grep -r "async def" --include="*.py" . > /dev/null; then
+  echo "Checking for time.sleep() anti-pattern in async functions..."
+  python3 -c "
+import re
+import sys
+from pathlib import Path
+
+for py_file in Path('.').rglob('*.py'):
+    content = py_file.read_text()
+    # Simple check: if file has 'async def' and 'time.sleep', flag it
+    if 'async def' in content and 'time.sleep(' in content:
+        print(f'WARNING: {py_file} contains both async def and time.sleep()')
+" || true
+fi
+```
+
+**Accept when:**
+- All I/O-bound functions are defined with `async def`
+- All async function calls use the `await` keyword
+- The asyncio module is imported in files using async/await
+- Entry points use `asyncio.run()` to execute async main functions
+- Async context managers are used with `async with` syntax
+- Multiple concurrent operations use `asyncio.gather()` or `asyncio.create_task()`
+- Async functions use `asyncio.sleep()` instead of `time.sleep()`
+- Exception handling wraps `await` statements with try/except blocks
+- Rate limiting is implemented using async delays when making API calls
+
+<enforcement>
+Claude Code MUST NOT skip or defer verification of async/await patterns. All I/O-bound operations MUST use async/await, and verification commands MUST be executed to ensure proper asyncio implementation.
+</enforcement>
\ No newline at end of file
diff --git a/.cursor/rules/adr-001.mdc b/.cursor/rules/adr-001.mdc
new file mode 100644
index 0000000..4236209
--- /dev/null
+++ b/.cursor/rules/adr-001.mdc
@@ -0,0 +1,10 @@
+---
+globs: ["rulectl/**"]
+alwaysApply: false
+---
+
+# Adopt External API Integration Pattern with Rate Limiting and Token Tracking
+
+## Policies
+
+1. Implement a centralized external API integration pattern that includes: (1) dedicated rate limiting mechanisms to respect API quotas and prevent throttling, (2) token tracking to monitor and manage API usage across requests, (3) specialized utility modules for Git operations that abstract external service interactions, and (4) shared utility functions that provide consistent error handling and retry logic for external API calls. This pattern ensures all external API interactions follow a standardized approach with built-in safeguards.
\ No newline at end of file
diff --git a/.cursor/rules/adr-002.mdc b/.cursor/rules/adr-002.mdc
new file mode 100644
index 0000000..abed99a
--- /dev/null
+++ b/.cursor/rules/adr-002.mdc
@@ -0,0 +1,10 @@
+---
+globs: ["rulectl/**"]
+alwaysApply: false
+---
+
+# Adopt External API Client Pattern for Third-Party Service Integration
+
+## Policies
+
+1. Implement dedicated external API client abstractions that encapsulate all interactions with third-party services. Each client provides a clean interface for external service operations, handles authentication and authorization, implements retry logic and rate limiting, and provides consistent error handling. The pattern separates external API concerns from business logic, making the codebase more modular and testable. Clients are designed with clear boundaries that isolate external dependencies and provide mock-friendly interfaces for testing.
\ No newline at end of file
diff --git a/.cursor/rules/adr-003.mdc b/.cursor/rules/adr-003.mdc
new file mode 100644
index 0000000..822b61e
--- /dev/null
+++ b/.cursor/rules/adr-003.mdc
@@ -0,0 +1,16 @@
+---
+globs: ["**/*.py","**/*.yaml","**/*.yml"]
+alwaysApply: false
+---
+
+# YAML Configuration Management for Application Settings
+
+## Policies
+
+1. Use YAML format for all application configuration files in Python projects (rate limiting, pricing, settings)
+2. Include pyyaml>=6.0 dependency for YAML parsing and python-dotenv>=1.0.0 for environment variable loading
+3. Load YAML configuration using yaml.safe_load() for security (prevents arbitrary code execution)
+4. Store configuration files in dedicated 'config' directory at project root level
+5. Use Path(__file__).parent.parent / 'config' / 'filename.yaml' for cross-platform config file paths
+6. Load environment variables using python-dotenv's load_dotenv() at application startup
+7. Implement fallback values when configuration files or environment variables are missing
\ No newline at end of file
diff --git a/.cursor/rules/adr-004.mdc b/.cursor/rules/adr-004.mdc
new file mode 100644
index 0000000..7715149
--- /dev/null
+++ b/.cursor/rules/adr-004.mdc
@@ -0,0 +1,16 @@
+---
+globs: ["**/*.py"]
+alwaysApply: false
+---
+
+# Token Usage Monitoring and Cost Tracking for AI Operations
+
+## Policies
+
+1. Implement TokenTracker class for monitoring AI API token usage and cost across all Python applications using LLMs
+2. Track both input and output tokens separately for accurate cost calculation and reporting
+3. Load model pricing configuration from YAML files with per-model input/output token costs
+4. Record token usage per analysis phase using track_call_from_collector() with phase identifiers
+5. Calculate cumulative costs in real-time based on current token counts and model pricing
+6. Set default model to 'claude-sonnet-4-20250514' from pricing configuration '_default' key
+7. Provide get_total_tokens() method returning cumulative input/output token counts for reporting
\ No newline at end of file
diff --git a/.cursor/rules/adr-005.mdc b/.cursor/rules/adr-005.mdc
new file mode 100644
index 0000000..b953a7f
--- /dev/null
+++ b/.cursor/rules/adr-005.mdc
@@ -0,0 +1,16 @@
+---
+globs: ["**/*.py"]
+alwaysApply: false
+---
+
+# Token Bucket Rate Limiting for API Call Management
+
+## Policies
+
+1. Implement token bucket algorithm for all API rate limiting in Python applications
+2. Use RateLimiter class with configurable per-minute and per-day request limits for external API clients
+3. Load rate limit configuration from YAML files (rate_limiting.yaml) in config directory
+4. Implement async wait_if_needed() method that delays execution using asyncio.sleep() when limits are exceeded
+5. Track request timestamps using time.time() and maintain sliding window of recent requests
+6. Define RateLimitStrategy enum with ROLLING_WINDOW strategy for time-based rate limiting
+7. Provide get_status() method returning current usage statistics (requests made, remaining, reset time)
\ No newline at end of file
diff --git a/.cursor/rules/adr-006.mdc b/.cursor/rules/adr-006.mdc
new file mode 100644
index 0000000..0eff4e5
--- /dev/null
+++ b/.cursor/rules/adr-006.mdc
@@ -0,0 +1,16 @@
+---
+globs: ["**/*.py"]
+alwaysApply: false
+---
+
+# Git Repository Integration for Provenance Tracking
+
+## Policies
+
+1. Use subprocess module with git commands for all Git repository operations in Python applications
+2. Validate Git repository existence before performing any git operations using subprocess.run(['git', 'rev-parse', '--git-dir'])
+3. Integrate gitignore patterns for file filtering using pathspec module with 'gitwildmatch' pattern type
+4. Implement git blame analysis to track file provenance including author, date, and commit metadata
+5. Detect repository main branch dynamically by checking for 'main', 'master', or current branch
+6. Use Path.resolve() for absolute path resolution when working with Git repository paths
+7. Extract git metadata (commit hash, author, email, date) for all analyzed files to support provenance tracking
\ No newline at end of file
diff --git a/.cursor/rules/adr-007.mdc b/.cursor/rules/adr-007.mdc
new file mode 100644
index 0000000..1f2d70f
--- /dev/null
+++ b/.cursor/rules/adr-007.mdc
@@ -0,0 +1,16 @@
+---
+globs: ["**/*.py"]
+alwaysApply: false
+---
+
+# Asynchronous Programming with Asyncio for Concurrent Operations
+
+## Policies
+
+1. Use async/await pattern for all I/O-bound operations including API calls and file processing in Python modules
+2. Import asyncio module for event loop management and concurrency primitives
+3. Define async functions with 'async def' for any operation that performs network requests or file I/O
+4. Use 'await' keyword for all async function calls and use asyncio.sleep() instead of time.sleep() in async contexts
+5. Implement async context managers for resource management in asynchronous code
+6. Use asyncio.gather() or asyncio.create_task() for concurrent execution of multiple async operations
+7. Call asyncio.run() at the entry point to execute async main functions from synchronous code
\ No newline at end of file
diff --git a/.cursor/rules/adr-008.mdc b/.cursor/rules/adr-008.mdc
new file mode 100644
index 0000000..a7b3453
--- /dev/null
+++ b/.cursor/rules/adr-008.mdc
@@ -0,0 +1,16 @@
+---
+globs: ["**/*.py"]
+alwaysApply: false
+---
+
+# Click Framework for CLI Application Architecture
+
+## Policies
+
+1. Use Click framework (click>=8.0.0) for all command-line interface implementation in Python applications
+2. Structure CLI with @click.group() decorator at the top level and @click.command() for subcommands
+3. Define command-line options using @click.option() with type hints, help text, and default values
+4. Use @click.argument() for required positional arguments with click.Choice() for enumerated values
+5. Include colorama>=0.4.6 for cross-platform colored terminal output in all CLI applications
+6. Implement --verbose/-v flag for debug output and --force/-f flag to skip confirmation prompts
+7. Provide clear help text for all commands and options using the help parameter
\ No newline at end of file
diff --git a/.cursor/rules/adr-009.mdc b/.cursor/rules/adr-009.mdc
new file mode 100644
index 0000000..9accd4f
--- /dev/null
+++ b/.cursor/rules/adr-009.mdc
@@ -0,0 +1,16 @@
+---
+globs: ["**/*.py"]
+alwaysApply: false
+---
+
+# Anthropic Claude AI Integration for Code Analysis
+
+## Policies
+
+1. Use Anthropic Claude API (via BAML client) for all AI-powered code analysis in Python files
+2. Default to 'claude-sonnet-4-20250514' model for analysis tasks unless specific model requirements dictate otherwise
+3. Store Anthropic API keys in environment variables (ANTHROPIC_API_KEY) and never hardcode credentials in Python source files
+4. Validate BAML client initialization before performing any AI operations using check_baml_client() validation
+5. Import AI functionality from baml_client.async_client module for all async AI operations
+6. Track token usage for all Claude API calls to monitor costs and usage patterns
+7. Set BAML_LOG environment variable to 'OFF' to disable verbose logging in production
\ No newline at end of file
diff --git a/.cursor/rules/adr-010.mdc b/.cursor/rules/adr-010.mdc
new file mode 100644
index 0000000..f920f8e
--- /dev/null
+++ b/.cursor/rules/adr-010.mdc
@@ -0,0 +1,10 @@
+---
+globs: ["**"]
+alwaysApply: false
+---
+
+# Use Python For All Development Purposes
+
+## Policies
+
+1. use python for everything, and use python 3+
\ No newline at end of file
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..891a4a4
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,127 @@
+---
+
+## Architecture Decision Records
+
+<adr_governance source="docs/adr/">
+ADRs govern validated architectural standards for this project.
+Full ADR documents: @docs/adr/
+</adr_governance>
+
+<activation>
+These directives are ALWAYS ACTIVE. All AI coding agents MUST apply all rules in this
+document to every code generation, modification, and review action within this
+project. No exceptions unless explicitly noted per-rule.
+</activation>
+
+---
+
+### Verification Protocol
+
+<verification_protocol>
+All rules in this document follow the **Verify → Fix → Repeat** loop.
+</verification_protocol>
+
+After generating or modifying code for any rule, the agent MUST:
+
+1. **RUN** the targeted verification command(s) in the rule's **Verify** block.
+2. **CAPTURE** the full command output (stdout + stderr).
+3. **EVALUATE** whether the **Accept when** criteria are satisfied.
+4. **IF FAILING:** diagnose the root cause, apply a fix, and re-run from step 1.
+5. **IF PASSING:** include the passing output as inline evidence before proposing further changes.
+6. **MAX ITERATIONS:** 5 attempts per rule. If still failing after 5 attempts, STOP and report the failure with all captured outputs.
+
+<enforcement>
+Compliance is not optional. Agents must not skip verification steps, assume
+correctness, or defer verification to a later task. Evidence of a passing
+verification run must accompany every code change that touches a governed area.
+</enforcement>
+
+---
+
+## YAML Configuration Management for Application Settings
+
+1. Use YAML format for all application configuration files in Python projects (rate limiting, pricing, settings)
+2. Include pyyaml>=6.0 dependency for YAML parsing and python-dotenv>=1.0.0 for environment variable loading
+3. Load YAML configuration using yaml.safe_load() for security (prevents arbitrary code execution)
+4. Store configuration files in dedicated 'config' directory at project root level
+5. Use Path(__file__).parent.parent / 'config' / 'filename.yaml' for cross-platform config file paths
+6. Load environment variables using python-dotenv's load_dotenv() at application startup
+7. Implement fallback values when configuration files or environment variables are missing
+
+---
+
+## Token Usage Monitoring and Cost Tracking for AI Operations
+
+1. Implement TokenTracker class for monitoring AI API token usage and cost across all Python applications using LLMs
+2. Track both input and output tokens separately for accurate cost calculation and reporting
+3. Load model pricing configuration from YAML files with per-model input/output token costs
+4. Record token usage per analysis phase using track_call_from_collector() with phase identifiers
+5. Calculate cumulative costs in real-time based on current token counts and model pricing
+6. Set default model to 'claude-sonnet-4-20250514' from pricing configuration '_default' key
+7. Provide get_total_tokens() method returning cumulative input/output token counts for reporting
+
+---
+
+## Token Bucket Rate Limiting for API Call Management
+
+1. Implement token bucket algorithm for all API rate limiting in Python applications
+2. Use RateLimiter class with configurable per-minute and per-day request limits for external API clients
+3. Load rate limit configuration from YAML files (rate_limiting.yaml) in config directory
+4. Implement async wait_if_needed() method that delays execution using asyncio.sleep() when limits are exceeded
+5. Track request timestamps using time.time() and maintain sliding window of recent requests
+6. Define RateLimitStrategy enum with ROLLING_WINDOW strategy for time-based rate limiting
+7. Provide get_status() method returning current usage statistics (requests made, remaining, reset time)
+
+---
+
+## Git Repository Integration for Provenance Tracking
+
+1. Use subprocess module with git commands for all Git repository operations in Python applications
+2. Validate Git repository existence before performing any git operations using subprocess.run(['git', 'rev-parse', '--git-dir'])
+3. Integrate gitignore patterns for file filtering using pathspec module with 'gitwildmatch' pattern type
+4. Implement git blame analysis to track file provenance including author, date, and commit metadata
+5. Detect repository main branch dynamically by checking for 'main', 'master', or current branch
+6. Use Path.resolve() for absolute path resolution when working with Git repository paths
+7. Extract git metadata (commit hash, author, email, date) for all analyzed files to support provenance tracking
+
+---
+
+## Asynchronous Programming with Asyncio for Concurrent Operations
+
+1. Use async/await pattern for all I/O-bound operations including API calls and file processing in Python modules
+2. Import asyncio module for event loop management and concurrency primitives
+3. Define async functions with 'async def' for any operation that performs network requests or file I/O
+4. Use 'await' keyword for all async function calls and use asyncio.sleep() instead of time.sleep() in async contexts
+5. Implement async context managers for resource management in asynchronous code
+6. Use asyncio.gather() or asyncio.create_task() for concurrent execution of multiple async operations
+7. Call asyncio.run() at the entry point to execute async main functions from synchronous code
+
+---
+
+## Click Framework for CLI Application Architecture
+
+1. Use Click framework (click>=8.0.0) for all command-line interface implementation in Python applications
+2. Structure CLI with @click.group() decorator at the top level and @click.command() for subcommands
+3. Define command-line options using @click.option() with type hints, help text, and default values
+4. Use @click.argument() for required positional arguments with click.Choice() for enumerated values
+5. Include colorama>=0.4.6 for cross-platform colored terminal output in all CLI applications
+6. Implement --verbose/-v flag for debug output and --force/-f flag to skip confirmation prompts
+7. Provide clear help text for all commands and options using the help parameter
+
+---
+
+## Anthropic Claude AI Integration for Code Analysis
+
+1. Use Anthropic Claude API (via BAML client) for all AI-powered code analysis in Python files
+2. Default to 'claude-sonnet-4-20250514' model for analysis tasks unless specific model requirements dictate otherwise
+3. Store Anthropic API keys in environment variables (ANTHROPIC_API_KEY) and never hardcode credentials in Python source files
+4. Validate BAML client initialization before performing any AI operations using check_baml_client() validation
+5. Import AI functionality from baml_client.async_client module for all async AI operations
+6. Track token usage for all Claude API calls to monitor costs and usage patterns
+7. Set BAML_LOG environment variable to 'OFF' to disable verbose logging in production
+
+---
+
+## Use Python For All Development Purposes
+
+1. use python for everything, and use python 3+
\ No newline at end of file
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..a11bb9f
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,127 @@
+---
+
+## Architecture Decision Records
+
+<adr_governance source="docs/adr/">
+ADRs govern validated architectural standards for this project.
+Full ADR documents: @docs/adr/
+</adr_governance>
+
+<activation>
+These directives are ALWAYS ACTIVE. Claude Code MUST apply all rules in this
+document to every code generation, modification, and review action within this
+project. No exceptions unless explicitly noted per-rule.
+</activation>
+
+---
+
+### Verification Protocol
+
+<verification_protocol>
+All rules in this document follow the **Verify → Fix → Repeat** loop.
+</verification_protocol>
+
+After generating or modifying code for any rule, Claude Code MUST:
+
+1. **RUN** the targeted verification command(s) in the rule's **Verify** block.
+2. **CAPTURE** the full command output (stdout + stderr).
+3. **EVALUATE** whether the **Accept when** criteria are satisfied.
+4. **IF FAILING:** diagnose the root cause, apply a fix, and re-run from step 1.
+5. **IF PASSING:** include the passing output as inline evidence before proposing further changes.
+6. **MAX ITERATIONS:** 5 attempts per rule. If still failing after 5 attempts, STOP and report the failure with all captured outputs.
+
+<enforcement>
+Compliance is not optional. Claude Code must not skip verification steps, assume
+correctness, or defer verification to a later task. Evidence of a passing
+verification run must accompany every code change that touches a governed area.
+</enforcement>
+
+---
+
+## ADR 1: YAML Configuration Management for Application Settings
+
+1. Use YAML format for all application configuration files in Python projects (rate limiting, pricing, settings)
+2. Include pyyaml>=6.0 dependency for YAML parsing and python-dotenv>=1.0.0 for environment variable loading
+3. Load YAML configuration using yaml.safe_load() for security (prevents arbitrary code execution)
+4. Store configuration files in dedicated 'config' directory at project root level
+5. Use Path(__file__).parent.parent / 'config' / 'filename.yaml' for cross-platform config file paths
+6. Load environment variables using python-dotenv's load_dotenv() at application startup
+7. Implement fallback values when configuration files or environment variables are missing
+
+---
+
+## ADR 2: Token Usage Monitoring and Cost Tracking for AI Operations
+
+1. Implement TokenTracker class for monitoring AI API token usage and cost across all Python applications using LLMs
+2. Track both input and output tokens separately for accurate cost calculation and reporting
+3. Load model pricing configuration from YAML files with per-model input/output token costs
+4. Record token usage per analysis phase using track_call_from_collector() with phase identifiers
+5. Calculate cumulative costs in real-time based on current token counts and model pricing
+6. Set default model to 'claude-sonnet-4-20250514' from pricing configuration '_default' key
+7. Provide get_total_tokens() method returning cumulative input/output token counts for reporting
+
+---
+
+## ADR 3: Token Bucket Rate Limiting for API Call Management
+
+1. Implement token bucket algorithm for all API rate limiting in Python applications
+2. Use RateLimiter class with configurable per-minute and per-day request limits for external API clients
+3. Load rate limit configuration from YAML files (rate_limiting.yaml) in config directory
+4. Implement async wait_if_needed() method that delays execution using asyncio.sleep() when limits are exceeded
+5. Track request timestamps using time.time() and maintain sliding window of recent requests
+6. Define RateLimitStrategy enum with ROLLING_WINDOW strategy for time-based rate limiting
+7. Provide get_status() method returning current usage statistics (requests made, remaining, reset time)
+
+---
+
+## ADR 4: Git Repository Integration for Provenance Tracking
+
+1. Use subprocess module with git commands for all Git repository operations in Python applications
+2. Validate Git repository existence before performing any git operations using subprocess.run(['git', 'rev-parse', '--git-dir'])
+3. Integrate gitignore patterns for file filtering using pathspec module with 'gitwildmatch' pattern type
+4. Implement git blame analysis to track file provenance including author, date, and commit metadata
+5. Detect repository main branch dynamically by checking for 'main', 'master', or current branch
+6. Use Path.resolve() for absolute path resolution when working with Git repository paths
+7. Extract git metadata (commit hash, author, email, date) for all analyzed files to support provenance tracking
+
+---
+
+## ADR 5: Asynchronous Programming with Asyncio for Concurrent Operations
+
+1. Use async/await pattern for all I/O-bound operations including API calls and file processing in Python modules
+2. Import asyncio module for event loop management and concurrency primitives
+3. Define async functions with 'async def' for any operation that performs network requests or file I/O
+4. Use 'await' keyword for all async function calls and use asyncio.sleep() instead of time.sleep() in async contexts
+5. Implement async context managers for resource management in asynchronous code
+6. Use asyncio.gather() or asyncio.create_task() for concurrent execution of multiple async operations
+7. Call asyncio.run() at the entry point to execute async main functions from synchronous code
+
+---
+
+## ADR 6: Click Framework for CLI Application Architecture
+
+1. Use Click framework (click>=8.0.0) for all command-line interface implementation in Python applications
+2. Structure CLI with @click.group() decorator at the top level and @click.command() for subcommands
+3. Define command-line options using @click.option() with type hints, help text, and default values
+4. Use @click.argument() for required positional arguments with click.Choice() for enumerated values
+5. Include colorama>=0.4.6 for cross-platform colored terminal output in all CLI applications
+6. Implement --verbose/-v flag for debug output and --force/-f flag to skip confirmation prompts
+7. Provide clear help text for all commands and options using the help parameter
+
+---
+
+## ADR 7: Anthropic Claude AI Integration for Code Analysis
+
+1. Use Anthropic Claude API (via BAML client) for all AI-powered code analysis in Python files
+2. Default to 'claude-sonnet-4-20250514' model for analysis tasks unless specific model requirements dictate otherwise
+3. Store Anthropic API keys in environment variables (ANTHROPIC_API_KEY) and never hardcode credentials in Python source files
+4. Validate BAML client initialization before performing any AI operations using check_baml_client() validation
+5. Import AI functionality from baml_client.async_client module for all async AI operations
+6. Track token usage for all Claude API calls to monitor costs and usage patterns
+7. Set BAML_LOG environment variable to 'OFF' to disable verbose logging in production
+
+---
+
+## ADR 8: Use Python For All Development Purposes
+
+1. use python for everything, and use python 3+
\ No newline at end of file
diff --git a/docs/adr/25dae845-b52d-411e-a1c4-03e462e4587c-yaml-configuration-management-for-application-settings.md b/docs/adr/25dae845-b52d-411e-a1c4-03e462e4587c-yaml-configuration-management-for-application-settings.md
new file mode 100644
index 0000000..6739dc9
--- /dev/null
+++ b/docs/adr/25dae845-b52d-411e-a1c4-03e462e4587c-yaml-configuration-management-for-application-settings.md
@@ -0,0 +1,19 @@
+Evidence from 5 files (rulectl/cli.py, rulectl/analyzer.py, rulectl/token_tracker.py, rulectl/utils.py, requirements.txt) totaling 1,984 lines shows comprehensive YAML-based configuration. Pattern implemented by Ethan (2025-09-02, commit b4a0531a) includes rate_limiting.yaml for API limits, model pricing configuration, and YAML frontmatter for rule output. PyYAML (pyyaml>=6.0) and python-dotenv (>=1.0.0) handle configuration loading with yaml.safe_load() and environment variable integration via os.getenv().
+
+## Policies
+- Use YAML format for all application configuration files in Python projects (rate limiting, pricing, settings)
+- Include pyyaml>=6.0 dependency for YAML parsing and python-dotenv>=1.0.0 for environment variable loading
+- Load YAML configuration using yaml.safe_load() for security (prevents arbitrary code execution)
+- Store configuration files in dedicated 'config' directory at project root level
+- Use Path(__file__).parent.parent / 'config' / 'filename.yaml' for cross-platform config file paths
+- Load environment variables using python-dotenv's load_dotenv() at application startup
+- Implement fallback values when configuration files or environment variables are missing
+
+## Instructions
+- Create config directory at project root and place all YAML configuration files there
+- Import yaml module and load configuration with 'with open(config_path) as f: yaml.safe_load(f)'
+- Import dotenv and call load_dotenv() before accessing environment variables
+- Use os.getenv('KEY_NAME', 'default_value') for environment variable access with fallbacks
+- Structure YAML with nested dictionaries for logical grouping of related settings
+- Validate configuration after loading using conditional checks or Pydantic models
+- Generate YAML output using yaml.dump(data, default_flow_style=False) for readable formatting
\ No newline at end of file
diff --git a/docs/adr/3bc34719-d377-4cb0-87ad-aea4726e4226-use-python-for-all-development-purposes.md b/docs/adr/3bc34719-d377-4cb0-87ad-aea4726e4226-use-python-for-all-development-purposes.md
new file mode 100644
index 0000000..b909a48
--- /dev/null
+++ b/docs/adr/3bc34719-d377-4cb0-87ad-aea4726e4226-use-python-for-all-development-purposes.md
@@ -0,0 +1,4 @@
+
+
+## Policies
+- use python for everything, and use python 3+
\ No newline at end of file
diff --git a/docs/adr/625f9120-cde0-48bf-8b08-acf4d18e94d6-token-bucket-rate-limiting-for-api-call-management.md b/docs/adr/625f9120-cde0-48bf-8b08-acf4d18e94d6-token-bucket-rate-limiting-for-api-call-management.md
new file mode 100644
index 0000000..5abdcd3
--- /dev/null
+++ b/docs/adr/625f9120-cde0-48bf-8b08-acf4d18e94d6-token-bucket-rate-limiting-for-api-call-management.md
@@ -0,0 +1,19 @@
+Evidence from rulectl/rate_limiter.py (219 lines) and rulectl/cli.py shows sophisticated rate limiting using token bucket algorithm. Implementation by Ethan (2025-09-02, commit b4a0531a) includes RateLimiter class with per-minute and per-day limits, async wait_if_needed() method, and execute_with_rate_limiting() wrapper. Configuration loaded from YAML file (rate_limiting.yaml) allows customizable limits. This pattern prevents API throttling and manages costs for Anthropic Claude API calls across concurrent async operations.
+
+## Policies
+- Implement token bucket algorithm for all API rate limiting in Python applications
+- Use RateLimiter class with configurable per-minute and per-day request limits for external API clients
+- Load rate limit configuration from YAML files (rate_limiting.yaml) in config directory
+- Implement async wait_if_needed() method that delays execution using asyncio.sleep() when limits are exceeded
+- Track request timestamps using time.time() and maintain sliding window of recent requests
+- Define RateLimitStrategy enum with ROLLING_WINDOW strategy for time-based rate limiting
+- Provide get_status() method returning current usage statistics (requests made, remaining, reset time)
+
+## Instructions
+- Create @dataclass RateLimitConfig with requests_per_minute and requests_per_day fields
+- Implement RateLimiter class with __init__ accepting RateLimitConfig and storing request history
+- Use collections.deque or list to track timestamps of recent API requests
+- Implement async wait_if_needed() that calculates delay based on token replenishment rate
+- Load configuration from YAML using yaml.safe_load() and create RateLimitConfig instance
+- Wrap API calls with execute_with_rate_limiting() to automatically enforce limits
+- Calculate time until next available slot by examining oldest request in sliding window
\ No newline at end of file
diff --git a/docs/adr/9ba96edd-ccd6-4170-8c18-433e72baae10-anthropic-claude-ai-integration-for-code-analysis.md b/docs/adr/9ba96edd-ccd6-4170-8c18-433e72baae10-anthropic-claude-ai-integration-for-code-analysis.md
new file mode 100644
index 0000000..5804f55
--- /dev/null
+++ b/docs/adr/9ba96edd-ccd6-4170-8c18-433e72baae10-anthropic-claude-ai-integration-for-code-analysis.md
@@ -0,0 +1,19 @@
+Evidence from 5 Python files (rulectl/cli.py, rulectl/analyzer.py, rulectl/token_tracker.py, fix_dependencies.py, requirements.txt) shows consistent integration with Anthropic's Claude AI API. Implementation committed by Ethan (2025-09-02, commit b4a0531a) includes BAML client setup, API key management via environment variables, and Claude Sonnet 4 model configuration. This pattern spans 2,573 lines across core analysis modules, indicating a fundamental architectural decision to use Claude AI for repository analysis and rule generation.
+
+## Policies
+- Use Anthropic Claude API (via BAML client) for all AI-powered code analysis in Python files
+- Default to 'claude-sonnet-4-20250514' model for analysis tasks unless specific model requirements dictate otherwise
+- Store Anthropic API keys in environment variables (ANTHROPIC_API_KEY) and never hardcode credentials in Python source files
+- Validate BAML client initialization before performing any AI operations using check_baml_client() validation
+- Import AI functionality from baml_client.async_client module for all async AI operations
+- Track token usage for all Claude API calls to monitor costs and usage patterns
+- Set BAML_LOG environment variable to 'OFF' to disable verbose logging in production
+
+## Instructions
+- Add baml-py>=0.202.1 dependency to requirements.txt for Claude AI integration
+- Initialize BAML client at application startup before any analysis operations
+- Load ANTHROPIC_API_KEY from environment using os.getenv() with fallback to credentials.json
+- Configure rate limiting and token tracking for all Claude API calls
+- Use async/await pattern with BAML client for concurrent AI operations
+- Import types from baml_client.types (e.g., StaticAnalysisRule, FileInfo) for type safety
+- Implement error handling for missing API keys with user-friendly error messages
\ No newline at end of file
diff --git a/docs/adr/a117ee09-e9ea-4860-bd61-9469cb3efb8e-adopt-external-api-client-pattern-for-third-party-service-integration.md b/docs/adr/a117ee09-e9ea-4860-bd61-9469cb3efb8e-adopt-external-api-client-pattern-for-third-party-service-integration.md
new file mode 100644
index 0000000..526af3a
--- /dev/null
+++ b/docs/adr/a117ee09-e9ea-4860-bd61-9469cb3efb8e-adopt-external-api-client-pattern-for-third-party-service-integration.md
@@ -0,0 +1,15 @@
+The codebase requires integration with external third-party services and APIs across multiple utility modules (utils.py, token_tracker.py, git_utils.py). These integrations need to handle authentication, rate limiting, error handling, and network failures consistently. Without a standardized approach, each module would implement its own client logic, leading to code duplication, inconsistent error handling, and maintenance challenges. The pattern emerged to address the need for reliable, maintainable, and testable external service interactions.
+
+## Policies
+- Implement dedicated external API client abstractions that encapsulate all interactions with third-party services. Each client provides a clean interface for external service operations, handles authentication and authorization, implements retry logic and rate limiting, and provides consistent error handling. The pattern separates external API concerns from business logic, making the codebase more modular and testable. Clients are designed with clear boundaries that isolate external dependencies and provide mock-friendly interfaces for testing.
+
+## Instructions
+- Positive: Consistent error handling and retry logic across all external API interactions
+- Positive: Improved testability through clear abstraction boundaries and mock-friendly interfaces
+- Positive: Centralized authentication and rate limiting logic reduces code duplication
+- Positive: Easier to swap or upgrade external service integrations without affecting business logic
+- Positive: Better observability and monitoring of external API calls through centralized client code
+- Negative: Additional abstraction layer adds initial development overhead
+- Negative: May introduce over-engineering for simple API calls
+- Negative: Requires developers to understand the client abstraction pattern
+- Trade-off: More code to maintain but significantly better separation of concerns
\ No newline at end of file
diff --git a/docs/adr/b2b7e9e6-03c0-4345-b6d1-ed075188ffea-adopt-external-api-integration-pattern-with-rate-limiting-and-token-tracking.md b/docs/adr/b2b7e9e6-03c0-4345-b6d1-ed075188ffea-adopt-external-api-integration-pattern-with-rate-limiting-and-token-tracking.md
new file mode 100644
index 0000000..d2f2917
--- /dev/null
+++ b/docs/adr/b2b7e9e6-03c0-4345-b6d1-ed075188ffea-adopt-external-api-integration-pattern-with-rate-limiting-and-token-tracking.md
@@ -0,0 +1,15 @@
+The system requires integration with external APIs (likely Git-based services and other third-party APIs) that impose rate limits and require careful resource management. The pattern emerged across utility modules (utils.py), token tracking (token_tracker.py), rate limiting (rate_limiter.py), and Git integration (git_utils.py), indicating a need for consistent handling of external API interactions. Without proper rate limiting and token tracking, the application risks hitting API quotas, experiencing service degradation, and failing to provide reliable external integrations.
+
+## Policies
+- Implement a centralized external API integration pattern that includes: (1) dedicated rate limiting mechanisms to respect API quotas and prevent throttling, (2) token tracking to monitor and manage API usage across requests, (3) specialized utility modules for Git operations that abstract external service interactions, and (4) shared utility functions that provide consistent error handling and retry logic for external API calls. This pattern ensures all external API interactions follow a standardized approach with built-in safeguards.
+
+## Instructions
+- Positive: Prevents API rate limit violations and service disruptions by proactively managing request rates
+- Positive: Provides visibility into API usage patterns through token tracking, enabling better capacity planning
+- Positive: Centralizes external API logic, making it easier to update authentication, error handling, and retry strategies
+- Positive: Improves reliability by implementing consistent retry and backoff mechanisms across all external integrations
+- Positive: Reduces coupling between business logic and external service implementations through abstraction layers
+- Negative: Adds complexity with additional layers of abstraction and monitoring infrastructure
+- Negative: Requires maintenance of rate limiting state and token tracking data structures
+- Negative: May introduce latency due to rate limiting delays and retry logic
+- Negative: Increases initial development time for implementing and testing the integration framework
\ No newline at end of file
diff --git a/docs/adr/b4c009f0-92b6-4477-8d9f-ea56ca93893e-token-usage-monitoring-and-cost-tracking-for-ai-operations.md b/docs/adr/b4c009f0-92b6-4477-8d9f-ea56ca93893e-token-usage-monitoring-and-cost-tracking-for-ai-operations.md
new file mode 100644
index 0000000..f15df2c
--- /dev/null
+++ b/docs/adr/b4c009f0-92b6-4477-8d9f-ea56ca93893e-token-usage-monitoring-and-cost-tracking-for-ai-operations.md
@@ -0,0 +1,19 @@
+Evidence from rulectl/token_tracker.py (235 lines) and rulectl/cli.py demonstrates real-time token tracking implemented by Ethan (2025-09-02, commit b4a0531a). TokenTracker class monitors input/output tokens (total_input_tokens, total_output_tokens), calculates costs using model pricing loaded from YAML, and provides cumulative statistics via get_total_tokens(). The track_call_from_collector() method records tokens per analysis phase, enabling cost monitoring across multi-phase analysis pipelines.
+
+## Policies
+- Implement TokenTracker class for monitoring AI API token usage and cost across all Python applications using LLMs
+- Track both input and output tokens separately for accurate cost calculation and reporting
+- Load model pricing configuration from YAML files with per-model input/output token costs
+- Record token usage per analysis phase using track_call_from_collector() with phase identifiers
+- Calculate cumulative costs in real-time based on current token counts and model pricing
+- Set default model to 'claude-sonnet-4-20250514' from pricing configuration '_default' key
+- Provide get_total_tokens() method returning cumulative input/output token counts for reporting
+
+## Instructions
+- Create TokenTracker class with __init__ initializing total_input_tokens and total_output_tokens to 0
+- Load pricing YAML file using yaml.safe_load() and store in self.model_pricing dictionary
+- Implement track_call_from_collector(phase, model) method to record token usage by phase
+- Store pricing as nested dict with model names as keys and 'input'/'output' cost per 1M tokens
+- Calculate costs by multiplying token count by price per million tokens
+- Implement get_total_tokens() returning dictionary with 'input', 'output', and 'total' keys
+- Update token counters after each API call by extracting usage from API response metadata
\ No newline at end of file
diff --git a/docs/adr/cceac33f-b2b2-426e-bf44-9b81cdfb29e8-click-framework-for-cli-application-architecture.md b/docs/adr/cceac33f-b2b2-426e-bf44-9b81cdfb29e8-click-framework-for-cli-application-architecture.md
new file mode 100644
index 0000000..cb4b44f
--- /dev/null
+++ b/docs/adr/cceac33f-b2b2-426e-bf44-9b81cdfb29e8-click-framework-for-cli-application-architecture.md
@@ -0,0 +1,19 @@
+Evidence from rulectl/cli.py (1,320 lines) and requirements.txt shows comprehensive CLI built with Click framework. Pattern emerged from initial commit by Ethan (2025-09-02, commit b4a0531a) with decorators (@click.group, @click.command, @click.option) defining commands for authentication setup, rate limiting configuration, and repository analysis. The CLI includes colorama for colored output, supporting multiple subcommands with extensive option parsing for API keys, verbosity flags, and force modes.
+
+## Policies
+- Use Click framework (click>=8.0.0) for all command-line interface implementation in Python applications
+- Structure CLI with @click.group() decorator at the top level and @click.command() for subcommands
+- Define command-line options using @click.option() with type hints, help text, and default values
+- Use @click.argument() for required positional arguments with click.Choice() for enumerated values
+- Include colorama>=0.4.6 for cross-platform colored terminal output in all CLI applications
+- Implement --verbose/-v flag for debug output and --force/-f flag to skip confirmation prompts
+- Provide clear help text for all commands and options using the help parameter
+
+## Instructions
+- Import click module and define main CLI group with @click.group() decorator
+- Create subcommands using @click.command() decorator and add to group with @cli.command()
+- Define options with @click.option() including name, type, default, and help parameters
+- Use click.echo() for all output instead of print() for better CLI compatibility
+- Implement click.Choice() for restricted argument values (e.g., provider choices)
+- Add click.prompt() for interactive input when required values are not provided
+- Test CLI commands using subprocess module to verify command-line behavior
\ No newline at end of file
diff --git a/docs/adr/e8f63640-71fd-4cba-911f-575be681b2cf-git-repository-integration-for-provenance-tracking.md b/docs/adr/e8f63640-71fd-4cba-911f-575be681b2cf-git-repository-integration-for-provenance-tracking.md
new file mode 100644
index 0000000..d17742b
--- /dev/null
+++ b/docs/adr/e8f63640-71fd-4cba-911f-575be681b2cf-git-repository-integration-for-provenance-tracking.md
@@ -0,0 +1,19 @@
+Evidence from rulectl/git_utils.py (1,643 lines) and rulectl/analyzer.py demonstrates deep Git integration implemented by Ethan (2025-09-02, commit b4a0531a). The GitAnalyzer class provides git blame analysis (get_file_statistics), branch detection (_find_main_branch), commit history tracking (get_recent_activity), and gitignore-based file filtering. This pattern enables provenance tracking by attributing code patterns to specific authors, dates, and commits, which is essential for understanding architectural decision origins.
+
+## Policies
+- Use subprocess module with git commands for all Git repository operations in Python applications
+- Validate Git repository existence before performing any git operations using subprocess.run(['git', 'rev-parse', '--git-dir'])
+- Integrate gitignore patterns for file filtering using pathspec module with 'gitwildmatch' pattern type
+- Implement git blame analysis to track file provenance including author, date, and commit metadata
+- Detect repository main branch dynamically by checking for 'main', 'master', or current branch
+- Use Path.resolve() for absolute path resolution when working with Git repository paths
+- Extract git metadata (commit hash, author, email, date) for all analyzed files to support provenance tracking
+
+## Instructions
+- Create GitAnalyzer class with __init__ accepting repo_path and validating Git repository
+- Use subprocess.run() with git commands, capturing stdout with text=True and check=True
+- Implement _validate_git_repo() method calling 'git rev-parse --git-dir' to verify repository
+- Parse git blame output to extract line-by-line author and commit information
+- Load and parse .gitignore file using pathspec.PathSpec.from_lines('gitwildmatch', patterns)
+- Implement get_file_statistics() to return commit count and author data per file
+- Use collections.defaultdict and collections.Counter for aggregating Git statistics
\ No newline at end of file
diff --git a/docs/adr/f039b8d8-cf8f-4c0a-bee1-dcae5c086c0c-asynchronous-programming-with-asyncio-for-concurrent-operations.md b/docs/adr/f039b8d8-cf8f-4c0a-bee1-dcae5c086c0c-asynchronous-programming-with-asyncio-for-concurrent-operations.md
new file mode 100644
index 0000000..f97f10a
--- /dev/null
+++ b/docs/adr/f039b8d8-cf8f-4c0a-bee1-dcae5c086c0c-asynchronous-programming-with-asyncio-for-concurrent-operations.md
@@ -0,0 +1,19 @@
+Evidence from 3 files (rulectl/cli.py, rulectl/analyzer.py, rulectl/rate_limiter.py) totaling 2,205 lines demonstrates comprehensive async/await implementation. Pattern introduced by Ethan (2025-09-02, commit b4a0531a) includes async functions for file analysis (async def analyze_file), rate limiting (async def wait_if_needed), and batch processing (async def execute_batch_with_rate_limiting). The asyncio pattern enables concurrent AI API calls while respecting rate limits, significantly improving performance for repository-wide analysis operations.
+
+## Policies
+- Use async/await pattern for all I/O-bound operations including API calls and file processing in Python modules
+- Import asyncio module for event loop management and concurrency primitives
+- Define async functions with 'async def' for any operation that performs network requests or file I/O
+- Use 'await' keyword for all async function calls and use asyncio.sleep() instead of time.sleep() in async contexts
+- Implement async context managers for resource management in asynchronous code
+- Use asyncio.gather() or asyncio.create_task() for concurrent execution of multiple async operations
+- Call asyncio.run() at the entry point to execute async main functions from synchronous code
+
+## Instructions
+- Add 'async' keyword before 'def' for functions that perform I/O operations
+- Add 'await' before calling async functions, API clients, or asyncio.sleep()
+- Wrap synchronous entry points with asyncio.run(async_main_function())
+- Use 'async with' for async context managers (e.g., async API clients)
+- Batch API requests and use asyncio.gather() for concurrent execution
+- Implement rate limiting with async delays using asyncio.sleep() between requests
+- Handle exceptions in async code with try/except around await statements
\ No newline at end of file
diff --git a/rulectl/AGENTS.md b/rulectl/AGENTS.md
new file mode 100644
index 0000000..e8c0e14
--- /dev/null
+++ b/rulectl/AGENTS.md
@@ -0,0 +1,49 @@
+---
+
+## Architecture Decision Records
+
+<adr_governance source="docs/adr/">
+ADRs govern validated architectural standards for this project.
+Full ADR documents: @docs/adr/
+</adr_governance>
+
+<activation>
+These directives are ALWAYS ACTIVE. All AI coding agents MUST apply all rules in this
+document to every code generation, modification, and review action within this
+project. No exceptions unless explicitly noted per-rule.
+</activation>
+
+---
+
+### Verification Protocol
+
+<verification_protocol>
+All rules in this document follow the **Verify → Fix → Repeat** loop.
+</verification_protocol>
+
+After generating or modifying code for any rule, the agent MUST:
+
+1. **RUN** the targeted verification command(s) in the rule's **Verify** block.
+2. **CAPTURE** the full command output (stdout + stderr).
+3. **EVALUATE** whether the **Accept when** criteria are satisfied.
+4. **IF FAILING:** diagnose the root cause, apply a fix, and re-run from step 1.
+5. **IF PASSING:** include the passing output as inline evidence before proposing further changes.
+6. **MAX ITERATIONS:** 5 attempts per rule. If still failing after 5 attempts, STOP and report the failure with all captured outputs.
+
+<enforcement>
+Compliance is not optional. Agents must not skip verification steps, assume
+correctness, or defer verification to a later task. Evidence of a passing
+verification run must accompany every code change that touches a governed area.
+</enforcement>
+
+---
+
+## Adopt External API Integration Pattern with Rate Limiting and Token Tracking
+
+1. Implement a centralized external API integration pattern that includes: (1) dedicated rate limiting mechanisms to respect API quotas and prevent throttling, (2) token tracking to monitor and manage API usage across requests, (3) specialized utility modules for Git operations that abstract external service interactions, and (4) shared utility functions that provide consistent error handling and retry logic for external API calls. This pattern ensures all external API interactions follow a standardized approach with built-in safeguards.
+
+---
+
+## Adopt External API Client Pattern for Third-Party Service Integration
+
+1. Implement dedicated external API client abstractions that encapsulate all interactions with third-party services. Each client provides a clean interface for external service operations, handles authentication and authorization, implements retry logic and rate limiting, and provides consistent error handling. The pattern separates external API concerns from business logic, making the codebase more modular and testable. Clients are designed with clear boundaries that isolate external dependencies and provide mock-friendly interfaces for testing.
\ No newline at end of file
diff --git a/rulectl/CLAUDE.md b/rulectl/CLAUDE.md
new file mode 100644
index 0000000..7b9709a
--- /dev/null
+++ b/rulectl/CLAUDE.md
@@ -0,0 +1,49 @@
+---
+
+## Architecture Decision Records
+
+<adr_governance source="docs/adr/">
+ADRs govern validated architectural standards for this project.
+Full ADR documents: @docs/adr/
+</adr_governance>
+
+<activation>
+These directives are ALWAYS ACTIVE. Claude Code MUST apply all rules in this
+document to every code generation, modification, and review action within this
+project. No exceptions unless explicitly noted per-rule.
+</activation>
+
+---
+
+### Verification Protocol
+
+<verification_protocol>
+All rules in this document follow the **Verify → Fix → Repeat** loop.
+</verification_protocol>
+
+After generating or modifying code for any rule, Claude Code MUST:
+
+1. **RUN** the targeted verification command(s) in the rule's **Verify** block.
+2. **CAPTURE** the full command output (stdout + stderr).
+3. **EVALUATE** whether the **Accept when** criteria are satisfied.
+4. **IF FAILING:** diagnose the root cause, apply a fix, and re-run from step 1.
+5. **IF PASSING:** include the passing output as inline evidence before proposing further changes.
+6. **MAX ITERATIONS:** 5 attempts per rule. If still failing after 5 attempts, STOP and report the failure with all captured outputs.
+
+<enforcement>
+Compliance is not optional. Claude Code must not skip verification steps, assume
+correctness, or defer verification to a later task. Evidence of a passing
+verification run must accompany every code change that touches a governed area.
+</enforcement>
+
+---
+
+## ADR 1: Adopt External API Integration Pattern with Rate Limiting and Token Tracking
+
+1. Implement a centralized external API integration pattern that includes: (1) dedicated rate limiting mechanisms to respect API quotas and prevent throttling, (2) token tracking to monitor and manage API usage across requests, (3) specialized utility modules for Git operations that abstract external service interactions, and (4) shared utility functions that provide consistent error handling and retry logic for external API calls. This pattern ensures all external API interactions follow a standardized approach with built-in safeguards.
+
+---
+
+## ADR 2: Adopt External API Client Pattern for Third-Party Service Integration
+
+1. Implement dedicated external API client abstractions that encapsulate all interactions with third-party services. Each client provides a clean interface for external service operations, handles authentication and authorization, implements retry logic and rate limiting, and provides consistent error handling. The pattern separates external API concerns from business logic, making the codebase more modular and testable. Clients are designed with clear boundaries that isolate external dependencies and provide mock-friendly interfaces for testing.
\ No newline at end of file