[WIP] Refactor validation architecture for better consolidation

[Copilot]

Thanks for assigning this issue to me. I'm starting to work on it and will keep this PR's description up to date as I form a plan and make progress.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[refactor] Semantic Function Clustering Analysis: Validation Architecture Consolidation Opportunity</issue_title>
<issue_description>Analysis of repository: githubnext/gh-aw

A comprehensive semantic analysis of 470 Go source files in the pkg/ directory has identified refactoring opportunities through function clustering and duplicate detection.

Executive Summary

The codebase demonstrates excellent organization with strong helper file conventions and domain-driven design. The primary opportunity for improvement is completing the validation architecture consolidation already in progress.

Key Metrics:

• Files Analyzed: 470 Go source files (excluding tests)
• Packages Analyzed: 11 major packages
• High-Priority Issues: 1 (validation consolidation)
• Medium-Priority Issues: 1 (string processing cross-references)
• Well-Organized Areas: 6 (no changes needed)

---

Critical Finding: Validation Architecture Consolidation

Issue: The pkg/workflow/ package contains 28 separate validation files with duplicated validation patterns, though consolidation is already underway.

Current State

Validation Files (28 files, ~4,000+ total lines):

• sandbox_validation.go (188 lines)
• safe_outputs_domains_validation.go (215 lines)
• permissions_validation.go (60+ lines)
• docker_validation.go (130 lines)
• bundler_script_validation.go (148 lines)
• bundler_runtime_validation.go, bundler_safety_validation.go
• firewall_validation.go, npm_validation.go, pip_validation.go
• dispatch_workflow_validation.go, engine_validation.go
• features_validation.go, mcp_config_validation.go
• repository_features_validation.go, runtime_validation.go
• secrets_validation.go, step_order_validation.go
• strict_mode_validation.go, template_injection_validation.go
• template_validation.go, agent_validation.go
• compiler_filters_validation.go, dangerous_permissions_validation.go
• github_toolset_validation_error.go, mcp_gateway_schema_validation.go
• safe_output_validation_config.go, safe_outputs_target_validation.go

Helper Files (already consolidated):

• validation_helpers.go (190 lines) - Consolidates reusable validation patterns
• error_helpers.go (200 lines) - Error type definitions and constructors

Duplicated Patterns Across 28 Files

1. Repeated NewValidationError() Calls
Every validation file contains multiple calls with identical structure:

return NewValidationError(
    "field_name",           // field
    actualValue,            // value
    "reason for error",     // reason
    "suggested fix",        // suggestion
)

2. Common Field Validation Patterns

• Empty string checks: if field == "" { return NewValidationError(...) }
• Array element validation: iterating arrays and validating each element
• Range validation: if value < min || value > max { ... }
• Nil/empty checks: if field == nil || len(field) == 0 { ... }

3. Consistent Logging Pattern
Each file initializes: logger := logger.New("workflow:*_validation")

Example: Duplicated Empty String Validation

In sandbox_validation.go:

if value == "" {
    return NewValidationError(
        "sandbox",
        value,
        "sandbox field cannot be empty",
        "Provide a valid sandbox type (e.g., 'docker', 'none')",
    )
}

In docker_validation.go:

if image == "" {
    return NewValidationError(
        "image",
        image,
        "docker image cannot be empty",
        "Provide a valid Docker image name",
    )
}

In npm_validation.go:

if packageName == "" {
    return NewValidationError(
        "package",
        packageName,
        "npm package name cannot be empty",
        "Provide a valid npm package name",
    )
}

Recommendation: Create helper function:

// In validation_helpers.go
func ValidateNotEmpty(fieldName string, value string, suggestion string) error {
    if value == "" {
        return NewValidationError(
            fieldName,
            value,
            fmt.Sprintf("%s cannot be empty", fieldName),
            suggestion,
        )
    }
    return nil
}

Example: Duplicated Range Validation

In runtime_validation.go:

if timeout < 0 || timeout > 360 {
    return NewValidationError(
        "timeout-minutes",
        timeout,
        "timeout must be between 0 and 360 minutes",
        "Set a timeout between 0 and 360 minutes",
    )
}

In bundler_runtime_validation.go:

if maxJobs < 1 || maxJobs > 256 {
    return NewValidationError(
        "max-parallel-jobs",
        maxJobs,
        "max-parallel-jobs must be between 1 and 256",
        "Set max-parallel-jobs to a value between 1 and 256",
    )...

</details>



<!-- START COPILOT CODING AGENT SUFFIX -->

- Fixes githubnext/gh-aw#11888

<!-- START COPILOT CODING AGENT TIPS -->
---

✨ Let Copilot coding agent [set things up for you](https://github.com/githubnext/gh-aw/issues/new?title=✨+Set+up+Copilot+instructions&body=Configure%20instructions%20for%20this%20repository%20as%20documented%20in%20%5BBest%20practices%20for%20Copilot%20coding%20agent%20in%20your%20repository%5D%28https://gh.io/copilot-coding-agent-tips%29%2E%0A%0A%3COnboard%20this%20repo%3E&assignees=copilot) — coding agent works faster and does higher quality work when set up for your repo.