Rule Files Sync

.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>

.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>

.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>

.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>

.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>

.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>