[Code Quality] Extract Magic Numbers to Named Constants with Policy Documentation

[github-actions]

Description

Critical validation thresholds (12 months, 52 weeks, 365 days, 8760 hours, 525600 minutes) and port numbers (80, 3000, 3001) are hardcoded inline. This obscures business rules and makes policy changes require coordinated updates across multiple locations.

Current Problem

// pkg/workflow/time_delta.go:142-156
if delta.Months > 12 {
    return nil, fmt.Errorf("time delta too large: %d months exceeds maximum of 12 months", delta.Months)
}
if delta.Hours > 8760 { // 365 * 24
    return nil, fmt.Errorf("time delta too large: %d hours exceeds maximum of 8760 hours", delta.Hours)
}

// pkg/workflow/mcp_setup_generator.go:262,383
yaml.WriteString("          PORT=3001\\n")
yaml.WriteString("          PORT=3000\\n")

Suggested Solution

Extract to named constants with clear policy documentation:

// pkg/workflow/time_delta_constants.go (new file)
// Time delta validation limits
// Policy: Maximum stop-after time is 1 year to prevent scheduling too far in the future
const (
    MaxTimeDeltaMonths  = 12      // 1 year
    MaxTimeDeltaDays    = 365     // 1 year
    MaxTimeDeltaHours   = 8760    // 1 year (365 * 24)
)

// pkg/constants/constants.go - Network constants
const (
    DefaultMCPGatewayPort      = 80    // Gateway exposed on standard HTTP port
    DefaultMCPServerPort       = 3000  // Internal MCP server default port
    DefaultMCPInspectorPort    = 3001  // MCP inspector tool port
)

Files Affected

• pkg/workflow/time_delta.go:142-156 - Five magic number comparisons
• pkg/workflow/mcp_setup_generator.go:262,383 - Hardcoded ports 3000, 3001
• pkg/workflow/mcp_gateway_constants.go:37 - Port 80
• pkg/workflow/sandbox_validation.go:158 - Port range 1-65535

Success Criteria

• Create pkg/workflow/time_delta_constants.go with time limit constants
• Add MCP port constants to pkg/constants/constants.go
• Update all hardcoded magic numbers to use named constants
• Add policy documentation comments explaining business rules
• All existing tests pass
• No behavior changes

Impact

Severity: High
Risk: Business rules obscured, inconsistent documentation, difficult policy adjustments
Benefit: Improved code clarity, centralized policy documentation, easier maintenance

Source

Extracted from Sergo Report: Magic Numbers Analysis #13058

Priority

High - Affects maintainability and makes it hard to understand validation policies

Estimated Effort

Small (1 day)

AI generated by Discussion Task Miner - Code Quality Improvement Agent

• expires on Feb 15, 2026, 1:20 PM UTC