solarwindpy 0.0.1.dev0__py3-none-any.whl → 0.1.1__py3-none-any.whl

plans/completed/pr-review-remediation/2-Smart-Timeouts-Validation.md

@@ -0,0 +1,399 @@
+# Phase 2: Smart Timeouts and Validation
+
+## Overview
+- **Phase**: 2 of 3  
+- **Duration**: 2.0 hours
+- **Priority**: HIGH (ROI 8-9/10)
+- **Dependencies**: Phase 1 (depth limits enable better timeout calculation)
+- **Affects**: `.claude/hooks/*`, `.claude/settings.local.json`, new validation utilities
+
+## Objective
+Implement adaptive timeout system and input validation to eliminate false timeout failures and prevent malformed operations, while maintaining the simplicity appropriate for SolarWindPy's scale.
+
+## Context
+Current fixed timeouts (120s) cause either:
+1. **False failures** when complex physics tests need more time
+2. **Unnecessary waits** when simple changes complete in 5-10s
+
+Additionally, lack of input validation allows malformed commands to reach tools, causing cryptic errors.
+
+**ROI Analysis:**
+- Adaptive timeouts: ROI 9/10 (saves 30-60 min/day developer time)
+- Input validation: ROI 8/10 (prevents system failures, clear errors)
+
+## Tasks
+
+### Task 2.1: Adaptive Timeout System (1 hour)
+**Priority**: HIGH (Massive time savings on every code edit)
+
+**Problem**: Fixed 120s timeouts for all operations regardless of complexity.
+
+**Solution**: Scale timeouts based on operation type and changed files.
+
+#### Subtask 2.1.1: Create Timeout Configuration (15 minutes)
+
+**New File**: `.claude/config/timeouts.json`
+```json
+{
+  "adaptive_timeouts": {
+    "enabled": true,
+    "base_timeouts": {
+      "physics_validation": 180,
+      "test_execution": 120, 
+      "coverage_analysis": 60,
+      "file_analysis": 30,
+      "git_operations": 15
+    },
+    "scaling": {
+      "per_file_factor": 15,
+      "max_timeout": 300,
+      "min_timeout": 10
+    },
+    "operation_patterns": {
+      "solarwindpy/instabilities/*.py": "physics_validation",
+      "solarwindpy/core/*.py": "physics_validation",
+      "solarwindpy/plotting/*.py": "test_execution",
+      "tests/*.py": "test_execution",
+      "*.md": "file_analysis"
+    }
+  }
+}
+```
+
+**Rationale**:
+- Physics calculations (instabilities) take longest: 180s base
+- Core physics validation: 180s base  
+- General tests: 120s base
+- Documentation: 30s base
+- Scale by 15s per changed file (reasonable for SolarWindPy size)
+
+#### Subtask 2.1.2: Update Test Runner Hook (30 minutes)
+
+**File**: `.claude/hooks/test-runner.sh`
+
+**Current Problem** (line 8):
+```bash
+MAX_TEST_TIME=120  # Fixed timeout
+```
+
+**Enhanced Implementation**:
+```bash
+#!/bin/bash
+# Calculate adaptive timeout based on changed files and types
+
+calculate_timeout() {
+    local changed_files="$1"
+    local file_count=$(echo "$changed_files" | wc -l)
+    local base_timeout=120
+    
+    # Check for physics files (need more time)
+    if echo "$changed_files" | grep -q "solarwindpy/instabilities/\|solarwindpy/core/"; then
+        base_timeout=180
+    elif echo "$changed_files" | grep -q "solarwindpy/plotting/"; then
+        base_timeout=120
+    elif echo "$changed_files" | grep -q "tests/"; then
+        base_timeout=120
+    else
+        base_timeout=60
+    fi
+    
+    # Scale by file count (15s per file)
+    local scaled_timeout=$((base_timeout + file_count * 15))
+    
+    # Clamp to reasonable bounds for SolarWindPy
+    if [ $scaled_timeout -gt 300 ]; then
+        scaled_timeout=300
+    elif [ $scaled_timeout -lt 10 ]; then
+        scaled_timeout=10
+    fi
+    
+    echo $scaled_timeout
+}
+
+# Get changed files for timeout calculation
+CHANGED_FILES=$(git diff --name-only HEAD~1..HEAD 2>/dev/null || echo "unknown")
+MAX_TEST_TIME=$(calculate_timeout "$CHANGED_FILES")
+
+echo "Adaptive timeout: ${MAX_TEST_TIME}s for $(echo "$CHANGED_FILES" | wc -l) changed files"
+```
+
+#### Subtask 2.1.3: Update Hook Configurations (15 minutes)
+
+**Files**: `.claude/settings.local.json` (hooks section around lines 127-249)
+
+**Update Timeout Values**:
+```json
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": ".claude/hooks/test-runner.sh --changed",
+            "timeout": "adaptive"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+**Implementation Note**: The actual timeout will be calculated by the hook itself, with "adaptive" signaling to use the new system.
+
+### Task 2.2: Basic Input Validation (1 hour)
+**Priority**: HIGH (Prevents system failures with clear errors)
+
+**Problem**: Malformed inputs cause cryptic tool failures.
+
+**Solution**: Validate inputs before they reach tools.
+
+#### Subtask 2.2.1: Create Input Validator (45 minutes)
+
+**New File**: `.claude/utils/input-validator.py`
+```python
+#!/usr/bin/env python3
+"""
+Basic input validation for SolarWindPy Claude operations
+Focused on preventing common errors and security issues
+"""
+
+import re
+import os
+from pathlib import Path
+
+class SolarWindPyValidator:
+    """Simple validator for SolarWindPy-specific operations."""
+    
+    # Safe path patterns for SolarWindPy
+    SAFE_PATHS = [
+        r'^solarwindpy/',
+        r'^tests/',
+        r'^\.claude/',
+        r'^docs/',
+        r'^scripts/',
+        r'^\w+\.py$',
+        r'^\w+\.md$'
+    ]
+    
+    # Dangerous patterns to block
+    DANGEROUS_PATTERNS = [
+        r'\.\./',           # Directory traversal
+        r'~/',              # Home directory access
+        r'/etc/',           # System directories
+        r'rm\s+-rf',        # Dangerous removal
+        r';\s*\w+',         # Command chaining
+        r'\|\s*\w+',        # Piping
+        r'`[^`]*`',         # Command substitution
+        r'\$\(',            # Command substitution
+    ]
+    
+    def validate_file_path(self, path: str) -> tuple[bool, str]:
+        """Validate file path is safe for SolarWindPy operations."""
+        if not path:
+            return False, "Empty path not allowed"
+        
+        # Check for dangerous patterns
+        for pattern in self.DANGEROUS_PATTERNS:
+            if re.search(pattern, path):
+                return False, f"Dangerous pattern detected: {pattern}"
+        
+        # Check against safe paths
+        for pattern in self.SAFE_PATHS:
+            if re.match(pattern, path):
+                return True, "Path validated"
+        
+        return False, f"Path not in allowed locations: {path}"
+    
+    def validate_branch_name(self, branch: str) -> tuple[bool, str]:
+        """Validate git branch name follows SolarWindPy conventions."""
+        if not branch:
+            return False, "Empty branch name"
+        
+        # SolarWindPy branch patterns
+        valid_patterns = [
+            r'^master$',
+            r'^plan/[\w\-]+$',
+            r'^feature/[\w\-]+$',  
+            r'^update-\d{4}$',
+            r'^codex/\d{4}-\d{2}-\d{2}',
+        ]
+        
+        for pattern in valid_patterns:
+            if re.match(pattern, branch):
+                return True, "Branch name validated"
+        
+        return False, f"Branch name doesn't match SolarWindPy conventions: {branch}"
+    
+    def validate_test_pattern(self, pattern: str) -> tuple[bool, str]:
+        """Validate test execution pattern is safe."""
+        if not pattern:
+            return False, "Empty test pattern"
+        
+        # Safe test patterns for SolarWindPy
+        safe_patterns = [
+            r'^tests/[\w/]*\.py$',
+            r'^solarwindpy/[\w/]*\.py$',
+            r'^tests/$',
+            r'^--\w+$',  # pytest flags
+            r'^\w+$',    # simple module names
+        ]
+        
+        for safe in safe_patterns:
+            if re.match(safe, pattern):
+                return True, "Test pattern validated"
+        
+        return False, f"Test pattern not safe: {pattern}"
+
+def validate_operation(operation_type: str, **kwargs) -> tuple[bool, str]:
+    """Main validation entry point."""
+    validator = SolarWindPyValidator()
+    
+    if operation_type == "file_path":
+        return validator.validate_file_path(kwargs.get('path', ''))
+    elif operation_type == "branch_name":
+        return validator.validate_branch_name(kwargs.get('branch', ''))
+    elif operation_type == "test_pattern":
+        return validator.validate_test_pattern(kwargs.get('pattern', ''))
+    else:
+        return False, f"Unknown operation type: {operation_type}"
+
+if __name__ == "__main__":
+    # CLI interface for validation
+    import sys
+    
+    if len(sys.argv) < 3:
+        print("Usage: input-validator.py <operation_type> <value>")
+        sys.exit(1)
+    
+    operation = sys.argv[1]
+    value = sys.argv[2]
+    
+    if operation == "file_path":
+        is_valid, message = validate_operation("file_path", path=value)
+    elif operation == "branch_name":
+        is_valid, message = validate_operation("branch_name", branch=value)
+    elif operation == "test_pattern":
+        is_valid, message = validate_operation("test_pattern", pattern=value)
+    else:
+        is_valid, message = False, f"Unknown operation: {operation}"
+    
+    print(message)
+    sys.exit(0 if is_valid else 1)
+```
+
+#### Subtask 2.2.2: Integrate Validation into Session Hook (15 minutes)
+
+**File**: `.claude/hooks/validate-session-state.sh`
+
+**Current Enhancement** (add before existing validation):
+```bash
+#!/bin/bash
+# Enhanced session validation with input checking
+
+echo "🔍 Validating session state..."
+
+# Get current branch
+CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "unknown")
+
+# Validate branch name
+if ! python .claude/utils/input-validator.py branch_name "$CURRENT_BRANCH"; then
+    echo "⚠️  Warning: Branch name doesn't follow SolarWindPy conventions"
+    echo "   Current: $CURRENT_BRANCH"
+    echo "   Expected: plan/*, feature/*, master, update-YYYY"
+fi
+
+# Check for safe working directory
+if [ ! -f "solarwindpy/__init__.py" ]; then
+    echo "❌ Not in SolarWindPy root directory"
+    exit 1
+fi
+
+# Validate recent file changes are safe
+RECENT_FILES=$(git diff --name-only HEAD~1..HEAD 2>/dev/null | head -10)
+if [ -n "$RECENT_FILES" ]; then
+    echo "📋 Validating recent file changes:"
+    while IFS= read -r file; do
+        if [ -n "$file" ]; then
+            if python .claude/utils/input-validator.py file_path "$file"; then
+                echo "   ✓ $file"
+            else
+                echo "   ⚠️  $file (outside safe paths)"
+            fi
+        fi
+    done <<< "$RECENT_FILES"
+fi
+
+# Continue with existing validation...
+echo "✅ Session state validation complete"
+```
+
+## Validation Steps
+
+### Timeout Validation
+1. **Small Change Test**:
+   ```bash
+   # Edit single plotting file
+   touch solarwindpy/plotting/test.py
+   git add solarwindpy/plotting/test.py
+   # Should get ~120s timeout (base) + 15s (1 file) = 135s
+   ```
+
+2. **Physics Change Test**:
+   ```bash
+   # Edit core physics file
+   touch solarwindpy/core/plasma.py
+   git add solarwindpy/core/plasma.py
+   # Should get ~180s timeout (physics base) + 15s (1 file) = 195s
+   ```
+
+3. **Multiple Files Test**:
+   ```bash
+   # Edit 5 files
+   # Should get base + (5 * 15s) = base + 75s, capped at 300s
+   ```
+
+### Input Validation Testing
+1. **Safe Paths**:
+   ```bash
+   python .claude/utils/input-validator.py file_path "solarwindpy/core/plasma.py"
+   # Should return: Path validated
+   ```
+
+2. **Dangerous Paths**:
+   ```bash
+   python .claude/utils/input-validator.py file_path "../../../etc/passwd"
+   # Should return: Dangerous pattern detected
+   ```
+
+3. **Branch Names**:
+   ```bash
+   python .claude/utils/input-validator.py branch_name "feature/pr-review-remediation"
+   # Should return: Branch name validated
+   ```
+
+## Dependencies
+- **Phase 1**: Depth limits must be working for timeout calculations
+- **Next Phase**: Validated inputs enable better GitHub integration
+
+## Rollback Procedures
+1. **Timeouts**: Revert to fixed 120s values
+2. **Validation**: Remove validation calls from hooks
+3. **Files**: Remove new `.claude/config/` and `.claude/utils/` files
+
+## Success Metrics
+- **Performance**: No false timeout failures, 30-60 min/day saved
+- **Reliability**: Clear error messages for invalid inputs
+- **User Experience**: Appropriate timeouts for operation complexity
+- **Security**: Malformed inputs blocked before reaching tools
+
+## Implementation Notes
+- **SolarWindPy Specific**: Timeout values calibrated for physics calculations
+- **Simple Validation**: Whitelist approach, no complex parsing
+- **Backward Compatible**: Falls back to fixed timeouts if adaptive fails
+- **Low Maintenance**: Simple patterns, no complex dependencies
+
+---
+*Phase 2 eliminates the major workflow friction points (timeouts, cryptic errors) while maintaining the simplicity appropriate for SolarWindPy's development scale.*

plans/completed/pr-review-remediation/3-Enhanced-GitHub-Integration.md

@@ -0,0 +1,258 @@
+# Phase 3: Enhanced GitHub Integration
+
+## Overview
+- **Phase**: 3 of 3
+- **Duration**: 0.5 hours (30 minutes)
+- **Priority**: MEDIUM (ROI 7/10)
+- **Dependencies**: Phases 1-2 (validated inputs, reliable routing)
+- **Affects**: `.github/workflows/claude-code-review.yml`, documentation
+
+## Objective
+Optimize Claude Code's automated PR review workflow to provide more relevant, physics-aware feedback that leverages SolarWindPy's sophisticated agent routing system and domain expertise.
+
+## Context
+Current GitHub integration uses generic review prompts. With the improved agent routing and validation from Phases 1-2, we can now provide more targeted, SolarWindPy-specific review guidance that focuses on:
+- Physics validation and unit consistency
+- Solar wind domain expertise  
+- Appropriate use of the 8-agent system
+- Scientific code review standards
+
+**ROI**: 7/10 - Improves review quality and reduces manual review time.
+
+## Tasks
+
+### Task 3.1: Enhance Claude Code Review Workflow (30 minutes)
+**Priority**: MEDIUM (Better reviews save manual review time)
+
+**File**: `.github/workflows/claude-code-review.yml`
+
+#### Current Configuration Analysis
+**Current Direct Prompt** (lines 19-26):
+```yaml
+direct_prompt: Please review this pull request and provide feedback on:
+- Code quality and best practices
+- Potential bugs or issues
+- Performance considerations
+- Security concerns
+- Test coverage
+
+Be constructive and helpful in your feedback.
+```
+
+#### Enhanced SolarWindPy-Specific Prompt
+
+**Updated Configuration**:
+```yaml
+direct_prompt: |
+  Please review this pull request for SolarWindPy, a solar wind physics analysis library.
+  
+  Focus your review on these SolarWindPy-specific areas:
+  
+  **Physics & Scientific Accuracy:**
+  - Unit consistency (SI units internally, conversion for display only)
+  - Thermal speed convention: mw² = 2kT
+  - Alfvén speed calculations: V_A = B/√(μ₀ρ) with proper ion composition
+  - Missing data handling (NaN, never 0 or -999)
+  - Time series chronological order preservation
+  
+  **Code Quality & Architecture:**
+  - MultiIndex DataFrame patterns (M/C/S structure: Measurement/Component/Species)
+  - Use of .xs() for DataFrame views, not copies
+  - DateTime indices named "Epoch"
+  - Proper inheritance from Base class for logging/units/constants
+  
+  **Agent Routing Optimization:**
+  - Physics calculations → PhysicsValidator
+  - DataFrame operations → DataFrameArchitect  
+  - Plotting code → PlottingEngineer
+  - Test files → TestEngineer
+  - Complex tasks → UnifiedPlanCoordinator
+  
+  **Performance & Security:**
+  - No unbounded operations (add -maxdepth to find commands)
+  - Appropriate timeout values for physics calculations
+  - Memory efficiency for large datasets
+  - Input validation for file paths and commands
+  
+  **Testing Standards:**
+  - Coverage ≥95% (enforced by hooks)
+  - Physics constraint validation in tests
+  - Numerical stability testing for edge cases
+  - Integration with existing .claude/hooks system
+  
+  When suggesting improvements, consider:
+  - SolarWindPy has ~50 files, 1-2 developers, 5-10 PRs/month
+  - Favor simple, maintainable solutions over complex engineering
+  - Leverage existing sophisticated .claude agent/hook ecosystem
+  - Maintain scientific accuracy and numerical precision
+  
+  Be constructive and provide specific, actionable feedback with line references.
+```
+
+#### Additional Configuration Enhancements
+
+**File Pattern Targeting** (add after line 30):
+```yaml
+# Only run detailed review for significant changes
+- name: Check if substantial changes
+  id: check_changes
+  run: |
+    FILES_CHANGED=$(git diff --name-only ${{ github.event.pull_request.base.sha }} ${{ github.sha }} | wc -l)
+    LINES_CHANGED=$(git diff --stat ${{ github.event.pull_request.base.sha }} ${{ github.sha }} | tail -1 | awk '{print $4+$6}')
+    echo "files_changed=$FILES_CHANGED" >> $GITHUB_OUTPUT
+    echo "lines_changed=$LINES_CHANGED" >> $GITHUB_OUTPUT
+    
+    # Skip review for trivial changes
+    if [ $FILES_CHANGED -lt 2 ] && [ $LINES_CHANGED -lt 20 ]; then
+      echo "skip_review=true" >> $GITHUB_OUTPUT
+    else
+      echo "skip_review=false" >> $GITHUB_OUTPUT
+    fi
+
+# Conditional review execution
+- name: Run Claude Code Review
+  if: steps.check_changes.outputs.skip_review == 'false'
+  uses: anthropics/claude-code-action@beta
+  # ... rest of configuration
+```
+
+#### Physics-Specific Review Triggers
+
+**Enhanced File-Based Triggering**:
+```yaml
+# Add physics-specific review intensity
+- name: Determine Review Focus  
+  id: review_focus
+  run: |
+    PHYSICS_FILES=$(git diff --name-only ${{ github.event.pull_request.base.sha }} ${{ github.sha }} | grep -E "(instabilities|core)" | wc -l)
+    PLOTTING_FILES=$(git diff --name-only ${{ github.event.pull_request.base.sha }} ${{ github.sha }} | grep "plotting" | wc -l)
+    TEST_FILES=$(git diff --name-only ${{ github.event.pull_request.base.sha }} ${{ github.sha }} | grep "tests/" | wc -l)
+    
+    if [ $PHYSICS_FILES -gt 0 ]; then
+      echo "Extra focus on physics validation, unit consistency, and numerical accuracy." >> physics_focus.txt
+    fi
+    if [ $PLOTTING_FILES -gt 0 ]; then
+      echo "Extra focus on matplotlib best practices and publication-quality output." >> plotting_focus.txt  
+    fi
+    if [ $TEST_FILES -gt 0 ]; then
+      echo "Extra focus on test coverage ≥95% and physics constraint validation." >> testing_focus.txt
+    fi
+```
+
+### Task 3.2: Create Quick Reference Documentation (Optional)
+**Priority**: LOW (Nice-to-have for context)
+
+**New File**: `.claude/docs/review-guidelines.md` (if time permits)
+
+```markdown
+# SolarWindPy PR Review Guidelines
+
+## Quick Reference for Claude Code Reviews
+
+### Physics Review Checklist
+- [ ] Units: SI internally, display conversion only
+- [ ] Thermal speed: mw² = 2kT convention
+- [ ] Alfvén speed: V_A = B/√(μ₀ρ) 
+- [ ] Missing data: NaN (never 0 or -999)
+- [ ] Time series: Chronological order maintained
+
+### Code Structure Review
+- [ ] MultiIndex: M/C/S structure (Measurement/Component/Species)
+- [ ] DataFrame: Use .xs() for views, not copies
+- [ ] DateTime: Indices named "Epoch" 
+- [ ] Inheritance: Base class for logging/units/constants
+
+### Performance Review
+- [ ] Operations: No unbounded find/grep commands
+- [ ] Timeouts: Appropriate for operation complexity
+- [ ] Memory: Efficient for large solar wind datasets
+
+### Agent Routing Optimization
+- Physics calculations → PhysicsValidator
+- DataFrame operations → DataFrameArchitect
+- Plotting code → PlottingEngineer
+- Test files → TestEngineer
+- Complex tasks → UnifiedPlanCoordinator
+
+### SolarWindPy Scale Context
+- ~50 Python files (focused scientific library)
+- 1-2 active developers
+- 5-10 PRs/month
+- Sophisticated .claude agent/hook ecosystem
+- Favor simplicity over complex engineering
+```
+
+## Validation Steps
+
+### GitHub Workflow Validation
+1. **Workflow Syntax**:
+   ```bash
+   # Validate YAML syntax
+   yamllint .github/workflows/claude-code-review.yml
+   ```
+
+2. **Test Review Trigger**:
+   - Create test PR with physics file changes
+   - Verify physics-specific prompts are included
+   - Confirm agent routing suggestions appear
+
+3. **Change Detection**:
+   - Test with trivial changes (skip review)
+   - Test with substantial changes (full review)
+   - Test with physics-specific changes (enhanced prompts)
+
+### Review Quality Assessment
+1. **Physics Focus**:
+   - Submit PR with unit inconsistency
+   - Verify review catches physics issues
+   - Confirm domain-specific feedback
+
+2. **Agent Routing**:
+   - Submit PR affecting multiple domains
+   - Verify appropriate agent suggestions
+   - Confirm routing conflicts are resolved
+
+## Dependencies
+- **Phase 1**: Agent routing conflicts must be resolved
+- **Phase 2**: Input validation enables better workflow triggers
+- **GitHub Actions**: Must support enhanced YAML configuration
+
+## Rollback Procedures
+1. **Workflow**: Revert to original direct_prompt
+2. **Documentation**: Remove new review guidelines
+3. **Triggers**: Remove file-based review intensity logic
+
+## Success Metrics
+- **Review Quality**: More physics-specific, actionable feedback
+- **Efficiency**: Skip trivial changes, focus on substantial ones
+- **Agent Utilization**: Better suggestions for domain-specific work
+- **Developer Experience**: Faster, more relevant review cycles
+
+## Implementation Notes
+- **SolarWindPy Specific**: Prompts tailored to solar wind physics domain
+- **Leverage Existing**: Uses sophisticated agent routing system
+- **Scale Appropriate**: Review intensity matches change significance
+- **Maintainable**: Simple workflow enhancements, no complex logic
+
+## Expected Outcomes
+
+### Before Enhancement
+- Generic code review feedback
+- No physics domain awareness
+- Manual agent selection required
+- Same review intensity for all changes
+
+### After Enhancement  
+- Physics-aware review feedback with unit/constraint checking
+- Automatic agent routing suggestions based on file types
+- Review intensity scaled to change significance
+- Domain expertise leveraged through targeted prompts
+
+### ROI Analysis
+- **Time Investment**: 30 minutes
+- **Value**: 2-4 hours/month saved on manual review
+- **Payback**: 2-3 review cycles
+- **Annual Value**: $1,200-2,400 in developer time
+
+---
+*Phase 3 completes the PR review enhancement by optimizing the GitHub integration to leverage SolarWindPy's domain expertise and sophisticated agent ecosystem, delivering more valuable automated reviews.*