SuperClaude/Framework-Hooks/docs/Modules/framework_logic.py.md

framework_logic.py - Core SuperClaude Framework Decision Engine

Overview

The framework_logic.py module implements the core decision-making algorithms from the SuperClaude framework, translating RULES.md, PRINCIPLES.md, and ORCHESTRATOR.md patterns into executable intelligence. This module serves as the central nervous system for all hook operations, providing evidence-based decision making, complexity assessment, risk evaluation, and quality validation.

Purpose and Responsibilities

Primary Functions

• Decision Algorithm Implementation: Executable versions of SuperClaude framework rules
• Complexity Assessment: Multi-factor scoring system for operation routing decisions
• Risk Evaluation: Context-aware risk assessment with mitigation strategies
• Quality Validation: Multi-step validation cycles with measurable quality scores
• Performance Estimation: Resource impact prediction and optimization recommendations

Framework Pattern Implementation

• RULES.md Compliance: Read-before-write validation, systematic codebase changes, session lifecycle rules
• PRINCIPLES.md Integration: Evidence-based decisions, quality standards, error handling patterns
• ORCHESTRATOR.md Logic: Intelligent routing, resource management, quality gate enforcement

Core Classes and Data Structures

Enumerations

OperationType

class OperationType(Enum):
    READ = "read"           # File reading operations
    WRITE = "write"         # File creation operations
    EDIT = "edit"           # File modification operations
    ANALYZE = "analyze"     # Code analysis operations
    BUILD = "build"         # Build/compilation operations
    TEST = "test"           # Testing operations
    DEPLOY = "deploy"       # Deployment operations
    REFACTOR = "refactor"   # Code restructuring operations

RiskLevel

class RiskLevel(Enum):
    LOW = "low"           # Minimal impact, safe operations
    MEDIUM = "medium"     # Moderate impact, requires validation
    HIGH = "high"         # Significant impact, requires approval
    CRITICAL = "critical" # System-wide impact, maximum validation

Data Classes

OperationContext

@dataclass
class OperationContext:
    operation_type: OperationType        # Type of operation being performed
    file_count: int                     # Number of files involved
    directory_count: int                # Number of directories involved
    has_tests: bool                     # Whether tests are available
    is_production: bool                 # Production environment flag
    user_expertise: str                 # beginner|intermediate|expert
    project_type: str                   # web|api|cli|library|etc
    complexity_score: float             # 0.0 to 1.0 complexity rating
    risk_level: RiskLevel              # Assessed risk level

ValidationResult

@dataclass
class ValidationResult:
    is_valid: bool                      # Overall validation status
    issues: List[str]                   # Critical issues found
    warnings: List[str]                 # Non-critical warnings
    suggestions: List[str]              # Improvement recommendations
    quality_score: float                # 0.0 to 1.0 quality rating

Core Methods and Algorithms

Framework Rule Implementation

should_use_read_before_write()

def should_use_read_before_write(self, context: OperationContext) -> bool:
    """RULES.md: Always use Read tool before Write or Edit operations."""
    return context.operation_type in [OperationType.WRITE, OperationType.EDIT]

Implementation Details:

• Direct mapping from RULES.md operational security requirements
• Returns True for any operation that modifies existing files
• Used by hooks to enforce read-before-write validation

should_enable_validation()

def should_enable_validation(self, context: OperationContext) -> bool:
    """ORCHESTRATOR.md: Enable validation for production code or high-risk operations."""
    return (
        context.is_production or 
        context.risk_level in [RiskLevel.HIGH, RiskLevel.CRITICAL] or
        context.operation_type in [OperationType.DEPLOY, OperationType.REFACTOR]
    )

Complexity Assessment Algorithm

calculate_complexity_score()

Multi-factor complexity scoring with weighted components:

File Count Factor (0.0 to 0.3):

• 1 file: 0.0
• 2-3 files: 0.1
• 4-10 files: 0.2
• 10+ files: 0.3

Directory Factor (0.0 to 0.2):

• 1 directory: 0.0
• 2 directories: 0.1
• 3+ directories: 0.2

Operation Type Factor (0.0 to 0.3):

• Refactor/Architecture: 0.3
• Build/Implement/Migrate: 0.2
• Fix/Update/Improve: 0.1
• Read/Analyze: 0.0

Language/Framework Factor (0.0 to 0.2):

• Multi-language projects: 0.2
• Framework changes: 0.1
• Single language/no framework: 0.0

Total Score: Sum of all factors, capped at 1.0

Risk Assessment Algorithm

assess_risk_level()

Context-based risk evaluation with escalation rules:

1. Production Environment: Automatic HIGH risk
2. Complexity > 0.7: HIGH risk
3. Complexity > 0.4: MEDIUM risk
4. File Count > 10: MEDIUM risk
5. Default: LOW risk

Quality Validation Framework

validate_operation()

Multi-criteria validation with quality scoring:

Evidence-Based Validation:

• Evidence provided: Quality maintained
• No evidence: -0.1 quality score, warning generated

Error Handling Validation:

• Write/Edit/Deploy operations require error handling
• Missing error handling: -0.2 quality score, issue generated

Test Coverage Validation:

• Logic changes should have tests
• Missing tests: -0.1 quality score, suggestion generated

Documentation Validation:

• Public APIs require documentation
• Missing docs: -0.1 quality score, suggestion generated

Security Validation:

• User input handling requires validation
• Missing input validation: -0.3 quality score, critical issue

Quality Thresholds:

• Valid operation: No issues AND quality_score ≥ 0.7
• Final quality_score: max(calculated_score, 0.0)

Thinking Mode Selection

determine_thinking_mode()

Complexity-based thinking mode selection:

• Complexity ≥ 0.8: --ultrathink (32K token analysis)
• Complexity ≥ 0.6: --think-hard (10K token analysis)
• Complexity ≥ 0.3: --think (4K token analysis)
• Complexity < 0.3: No thinking mode required

Delegation Decision Logic

should_enable_delegation()

Multi-factor delegation assessment:

def should_enable_delegation(self, context: OperationContext) -> Tuple[bool, str]:
    if context.file_count > 3:
        return True, "files"          # File-based delegation
    elif context.directory_count > 2:
        return True, "folders"        # Folder-based delegation
    elif context.complexity_score > 0.4:
        return True, "auto"           # Automatic strategy selection
    else:
        return False, "none"          # No delegation needed

Performance Target Management

Configuration Integration

def __init__(self):
    # Load performance targets from SuperClaude configuration
    self.performance_targets = {}
    
    # Hook-specific targets
    self.performance_targets['session_start_ms'] = config_loader.get_hook_config(
        'session_start', 'performance_target_ms', 50
    )
    self.performance_targets['tool_routing_ms'] = config_loader.get_hook_config(
        'pre_tool_use', 'performance_target_ms', 200
    )
    # ... additional targets

Performance Impact Estimation

def estimate_performance_impact(self, context: OperationContext) -> Dict[str, Any]:
    base_time = 100  # ms
    estimated_time = base_time * (1 + context.complexity_score * 3)
    
    # Factor in file count impact
    if context.file_count > 5:
        estimated_time *= 1.5
    
    # Generate optimization suggestions
    optimizations = []
    if context.file_count > 3:
        optimizations.append("Consider parallel processing")
    if context.complexity_score > 0.6:
        optimizations.append("Enable delegation mode")
    
    return {
        'estimated_time_ms': int(estimated_time),
        'performance_risk': 'high' if estimated_time > 1000 else 'low',
        'suggested_optimizations': optimizations,
        'efficiency_gains_possible': len(optimizations) > 0
    }

Quality Gates Integration

get_quality_gates()

Dynamic quality gate selection based on operation context:

Base Gates (All Operations):

• syntax_validation: Language-specific syntax checking

Write/Edit Operations:

• type_analysis: Type compatibility validation
• code_quality: Linting and style checking

High-Risk Operations:

• security_assessment: Vulnerability scanning
• performance_analysis: Performance impact analysis

Test-Available Operations:

• test_validation: Test execution and coverage

Deployment Operations:

• integration_testing: End-to-end validation
• deployment_validation: Environment compatibility

SuperClaude Principles Application

apply_superclaude_principles()

Automatic principle enforcement with recommendations:

Evidence > Assumptions:

if 'assumptions' in enhanced_data and not enhanced_data.get('evidence'):
    enhanced_data['recommendations'].append(
        "Gather evidence to validate assumptions"
    )

Code > Documentation:

if enhanced_data.get('operation_type') == 'document' and not enhanced_data.get('has_working_code'):
    enhanced_data['warnings'].append(
        "Ensure working code exists before extensive documentation"
    )

Efficiency > Verbosity:

if enhanced_data.get('output_length', 0) > 1000 and not enhanced_data.get('justification_for_length'):
    enhanced_data['efficiency_suggestions'].append(
        "Consider token efficiency techniques for long outputs"
    )

Integration with Hooks

Hook Implementation Pattern

# Hook initialization
framework_logic = FrameworkLogic()

# Operation context creation
context = OperationContext(
    operation_type=OperationType.EDIT,
    file_count=file_count,
    directory_count=dir_count,
    has_tests=has_tests,
    is_production=is_production,
    user_expertise="intermediate",
    project_type="web",
    complexity_score=0.0,  # Will be calculated
    risk_level=RiskLevel.LOW  # Will be assessed
)

# Calculate complexity and assess risk
context.complexity_score = framework_logic.calculate_complexity_score(operation_data)
context.risk_level = framework_logic.assess_risk_level(context)

# Make framework-compliant decisions
should_validate = framework_logic.should_enable_validation(context)
should_delegate, delegation_strategy = framework_logic.should_enable_delegation(context)
thinking_mode = framework_logic.determine_thinking_mode(context)

# Validate operation
validation_result = framework_logic.validate_operation(operation_data)
if not validation_result.is_valid:
    # Handle validation issues
    handle_validation_issues(validation_result)

Error Handling Strategies

Graceful Degradation

• Configuration Errors: Use default performance targets
• Calculation Errors: Return safe default values
• Validation Failures: Provide detailed error context

Fallback Mechanisms

• Complexity Calculation: Default to 0.5 if calculation fails
• Risk Assessment: Default to MEDIUM risk if assessment fails
• Quality Validation: Default to valid with warnings if validation fails

Performance Characteristics

Operation Timings

• Complexity Calculation: <5ms for typical operations
• Risk Assessment: <3ms for context evaluation
• Quality Validation: <10ms for comprehensive validation
• Performance Estimation: <2ms for impact calculation

Memory Efficiency

• Context Objects: ~200-400 bytes per context
• Validation Results: ~500-1000 bytes with full details
• Configuration Cache: ~1-2KB for performance targets

Configuration Requirements

Required Configuration Sections

# Performance targets for each hook
hook_configurations:
  session_start:
    performance_target_ms: 50
  pre_tool_use:
    performance_target_ms: 200
  post_tool_use:
    performance_target_ms: 100
  pre_compact:
    performance_target_ms: 150

# Global performance settings
global_configuration:
  performance_monitoring:
    enabled: true
    target_percentile: 95
    alert_threshold_ms: 500

Usage Examples

Basic Decision Making

framework_logic = FrameworkLogic()

# Create operation context
context = OperationContext(
    operation_type=OperationType.REFACTOR,
    file_count=15,
    directory_count=3,
    has_tests=True,
    is_production=False,
    user_expertise="expert",
    project_type="web",
    complexity_score=0.0,
    risk_level=RiskLevel.LOW
)

# Calculate complexity and assess risk
context.complexity_score = framework_logic.calculate_complexity_score({
    'file_count': 15,
    'directory_count': 3,
    'operation_type': 'refactor',
    'multi_language': False,
    'framework_changes': True
})

context.risk_level = framework_logic.assess_risk_level(context)

# Make decisions
should_read_first = framework_logic.should_use_read_before_write(context)  # False (refactor)
should_validate = framework_logic.should_enable_validation(context)        # True (refactor)
should_delegate, strategy = framework_logic.should_enable_delegation(context)  # True, "files"
thinking_mode = framework_logic.determine_thinking_mode(context)           # "--think-hard"

Quality Validation

operation_data = {
    'operation_type': 'write',
    'affects_logic': True,
    'has_tests': False,
    'is_public_api': True,
    'has_documentation': False,
    'handles_user_input': True,
    'has_input_validation': False,
    'has_error_handling': True
}

validation_result = framework_logic.validate_operation(operation_data)

print(f"Valid: {validation_result.is_valid}")                    # False
print(f"Quality Score: {validation_result.quality_score}")       # 0.4
print(f"Issues: {validation_result.issues}")                     # ['User input handling without validation']
print(f"Warnings: {validation_result.warnings}")                # ['No tests found for logic changes', 'Public API lacks documentation']
print(f"Suggestions: {validation_result.suggestions}")          # ['Add unit tests for new logic', 'Add API documentation']

Dependencies and Relationships

Internal Dependencies

• yaml_loader: Configuration loading and management
• Standard Libraries: json, time, dataclasses, enum, typing

Framework Integration

• RULES.md: Direct implementation of operational rules
• PRINCIPLES.md: Quality standards and decision-making principles
• ORCHESTRATOR.md: Intelligent routing and resource management patterns

Hook Coordination

• Used by all 7 hooks for consistent decision-making
• Provides standardized context and validation interfaces
• Enables cross-hook performance monitoring and optimization

---

This module serves as the foundational intelligence layer for the entire SuperClaude framework, ensuring that all hook operations are evidence-based, quality-validated, and optimally routed according to established patterns and principles.