[Code Quality] Add basic structure validation for pass-through YAML fields (concurrency, container, etc.)

[github-actions]

Description

Several frontmatter fields are extracted as raw YAML sections and passed through to GitHub Actions without validation: concurrency, container, environment, env, runs-on, services. While pass-through behavior is intentional, the lack of basic structure validation can lead to confusing runtime errors in GitHub Actions that could be caught earlier during compilation.

Problem

Current Behavior (in compiler_orchestrator_workflow.go:139-296):

workflowData.Concurrency = c.extractTopLevelYAMLSection(frontmatter, "concurrency")
workflowData.Container = c.extractTopLevelYAMLSection(frontmatter, "container")
workflowData.Environment = c.extractTopLevelYAMLSection(frontmatter, "environment")
// ... etc - no validation of structure

Impact:

• Invalid YAML structures accepted during compilation
• Errors only discovered during GitHub Actions execution
• Confusing error messages from GitHub Actions (not gh-aw)
• Harder to debug configuration issues

Example Scenarios

1. Invalid concurrency:

concurrency: "string"  # Should be object with 'group' field

→ Accepted by compiler, fails in GitHub Actions

2. Malformed container:

container: []  # Should be object, not array

→ Accepted by compiler, fails in GitHub Actions

Suggested Changes

Add basic structure validation for pass-through fields:

Implementation Approach:

1. Define expected structure for each pass-through field (in schema or code)
2. Add validation function: validatePassThroughField(fieldName, value, expectedType)
3. Check field structure matches expectations (object vs string vs array)
4. Provide clear error message if structure is invalid
5. Still pass-through valid structures unchanged

Validation Examples:

• concurrency: Must be object with group field (string)
• container: Must be object or string
• environment: Must be object or string
• runs-on: Must be string or array of strings
• env: Must be object with string values

Files Affected

• pkg/workflow/compiler_orchestrator_workflow.go - Add validation logic
• pkg/workflow/validation_passthrough.go (new) - Validation helpers
• pkg/parser/schemas/main_workflow_schema.json - Optionally enhance schema definitions

Success Criteria

• Basic structure validation for all pass-through fields
• Clear error messages indicating expected structure
• Errors caught during compilation, not at runtime
• Valid structures continue to pass-through unchanged
• Documentation marks fields as "pass-through with validation"
• Unit tests for valid and invalid structures

Alternative Approaches

Option 1 (Recommended): Basic structure validation

• Validates type/shape only (object vs string vs array)
• Still passes through to GitHub Actions for detailed validation
• Catches obvious errors early

Option 2: Full schema validation

• Validates against complete GitHub Actions schema
• More comprehensive but requires maintaining schema
• Potential for false positives if GitHub changes schema

Option 3: Document only

• Mark fields as pass-through in schema comments
• No validation added
• Simplest but provides least user benefit

Source

Extracted from Schema Consistency: Runtime Behavior vs Schema Contracts

Finding: Issue #3 - Pass-Through YAML Sections Without Validation (Medium Priority)

Priority

Medium - Improves user experience and catches errors earlier, but current pass-through behavior is intentional and working.

Estimated Effort

3-5 hours (validation logic + comprehensive testing)

AI generated by Discussion Task Miner - Code Quality Improvement Agent

• expires on Feb 13, 2026, 5:22 AM UTC

[github-actions]

🍪 Issue Monster has assigned this to Copilot!

I've identified this issue as a good candidate for automated resolution and assigned it to the Copilot agent.

The Copilot agent will analyze the issue and create a pull request with the fix.

Om nom nom! 🍪

AI generated by Issue Monster