[Schema Consistency] Conditional Logic & Feature Interaction Consistency Check - 2026-01-23

[github-actions[bot]]

Summary

• Inconsistencies Found: 3
• Strategy Used: Conditional Logic & Feature Flag Analysis (Strategy 005)
• Focus: Relationships between fields, feature interactions, mutual exclusivity patterns
• Overall Assessment: Good consistency with one critical documentation gap

Quick Stats

• ✅ Critical Finding: 1 (label-only exception undocumented)
• ⚠️ Moderate Findings: 2 (incomplete filter validation, schema gaps)
• 🎉 Positive Findings: 3 (excellent filter validation implementation)

---

Critical Issues

1. Label-Only Exception for Command Triggers NOT DOCUMENTED

Severity: HIGH - Undocumented feature behavior

What We Found:

• The compiler implements a sophisticated exception that allows slash_command to coexist with issues/pull_request events when those events are configured for label-only triggers (only labeled or unlabeled types)
• This is implemented via parser.IsLabelOnlyEvent() function in pkg/parser/schema_triggers.go:65
• The function checks if an event configuration only contains labeled/unlabeled types

Code Evidence (pkg/workflow/compiler_safe_outputs.go:98):

// Special case: allow issues/pull_request if they only have labeled/unlabeled types
if (eventName == "issues" || eventName == "pull_request") && parser.IsLabelOnlyEvent(eventValue) {
    continue // Allow this - it doesn't conflict with command triggers
}
return fmt.Errorf("cannot use 'slash_command' with '%s' in the same workflow", eventName)

Documentation Says (docs/src/content/docs/reference/command-triggers.md:79):

Note: You cannot combine slash_command with issues, issue_comment, or pull_request as they would conflict.

The Gap: The documentation states an absolute prohibition but the code implements a nuanced exception. Users are unaware that label-only configurations are actually allowed.

Impact:

• Users avoid valid patterns thinking they're forbidden
• Lack of examples showing this legitimate use case
• Implementation quality is excellent but hidden from users

Recommendation:

1. Update command-triggers.md to document the label-only exception
2. Add example workflow showing slash_command + label-only issues pattern
3. Add similar example for pull_request with labeled/unlabeled types

---

Moderate Issues

2. Filter Validation Only Covers push/pull_request Events

Severity: MODERATE - Incomplete validation coverage

What We Found:
The filter validation in pkg/workflow/compiler_filters_validation.go only validates mutual exclusivity for:

• ✅ push event (line 58-64)
• ✅ pull_request event (line 67-72)

However, GitHub Actions also supports filters for:

• ❌ workflow_run - supports branches and paths filters
• ❌ pull_request_target - supports same filters as pull_request
• ❌ merge_group - supports filters

Code Evidence:

// Check push event
if pushVal, exists := onMap["push"]; exists {
    filterValidationLog.Print("Validating push event filters")
    if err := validateFilterExclusivity(pushVal, "push"); err != nil {
        return err
    }
}

// Check pull_request event
if prVal, exists := onMap["pull_request"]; exists {
    filterValidationLog.Print("Validating pull_request event filters")
    if err := validateFilterExclusivity(prVal, "pull_request"); err != nil {
        return err
    }
}

// Missing: workflow_run, pull_request_target, merge_group

Impact: Users could accidentally specify both branches and branches-ignore for workflow_run events and wouldn't get a validation error until GitHub Actions runtime.

Recommendation: Extend ValidateEventFilters() to include validation for all filter-supporting events.

3. Sandbox/Firewall Mutual Exclusivity Not in Schema

Severity: MODERATE - Schema documentation gap

What We Found:

• Runtime validation EXISTS in pkg/workflow/sandbox_validation.go:133-140
• Schema: No oneOf/not constraint expressing this mutual exclusivity
• Users can create invalid frontmatter that passes schema validation but fails at compile time

Code Evidence (sandbox_validation.go:133-140):

// Check for mutual exclusivity with AWF
if workflowData.NetworkPermissions != nil && 
   workflowData.NetworkPermissions.Firewall != nil && 
   workflowData.NetworkPermissions.Firewall.Enabled {
    return NewConfigurationError(
        "sandbox",
        "sandbox-runtime with network.firewall",
        "sandbox-runtime and AWF firewall cannot be used together",
        "Choose one sandbox approach:\n\nOption 1 (sandbox-runtime):\nsandbox: sandbox-runtime\n\nOption 2 (AWF firewall):\nnetwork:\n  firewall: true",
    )
}

Schema Status: The schema defines both sandbox and network.firewall fields independently without expressing their mutual exclusivity relationship.

Impact:

• IDE schema validation doesn't catch this conflict
• Users only discover the issue at compile time
• Error message is excellent but prevention would be better

Recommendation:

• Add schema-level oneOf constraint or
• Add prominent $comment in schema explaining the mutual exclusivity or
• Document this constraint in field descriptions

---

Positive Findings

✅ 1. branches/branches-ignore Mutual Exclusivity - EXCELLENT

Perfect alignment across all layers:

Schema (main_workflow_schema.json:330-355): Uses sophisticated oneOf with not constraints

"oneOf": [
  {
    "required": ["branches"],
    "not": { "required": ["branches-ignore"] }
  },
  {
    "required": ["branches-ignore"],
    "not": { "required": ["branches"] }
  },
  {
    "not": {
      "anyOf": [
        { "required": ["branches"] },
        { "required": ["branches-ignore"] }
      ]
    }
  }
]

Runtime Validation (compiler_filters_validation.go:86-93): Matches schema perfectly

_, hasBranches := eventMap["branches"]
_, hasBranchesIgnore := eventMap["branches-ignore"]

if hasBranches && hasBranchesIgnore {
    return fmt.Errorf("%s event cannot specify both 'branches' and 'branches-ignore' - they are mutually exclusive per GitHub Actions requirements...")
}

Documentation: Clear error messages reference GitHub Actions requirements

Gold Standard: This is exemplary implementation showing perfect schema-code-docs alignment!

✅ 2. paths/paths-ignore Mutual Exclusivity - EXCELLENT

Same perfect pattern as branches/branches-ignore:

• Schema uses oneOf with not constraints (lines 356-385)
• Runtime validation in validateFilterExclusivity() (lines 95-102)
• Clear, actionable error messages

✅ 3. IsLabelOnlyEvent Function - WELL IMPLEMENTED

The label-only detection logic is clean and thorough:

func IsLabelOnlyEvent(eventValue any) bool {
    eventMap, isMap := eventValue.(map[string]any)
    if !isMap {
        return false
    }

    typesValue, hasTypes := eventMap["types"]
    if !hasTypes {
        return false
    }

    typesArray, isArray := typesValue.([]any)
    if !isArray {
        // Handle single type edge case
    }

    // Check all types are labeled/unlabeled
    for _, t := range typesArray {
        typeStr, ok := t.(string)
        if !ok || (typeStr != "labeled" && typeStr != "unlabeled") {
            return false
        }
    }
    return len(typesArray) > 0
}

Quality observations:

• Defensive type checking
• Handles both array and single-value cases
• Clear boolean logic
• Good function documentation
• Properly exported for compiler use

---

Recommendations

Priority 1: Document Label-Only Exception

Timeline: Next documentation update

1. Update docs/src/content/docs/reference/command-triggers.md:

   • Add section explaining label-only exception
   • Include example workflow
   • Explain the use case (e.g., slash command that also needs to react to label changes)

2. Add to schema description for slash_command field

Priority 2: Extend Filter Validation

Timeline: Next development cycle

Add validation for workflow_run, pull_request_target, and merge_group events:

// Add to ValidateEventFilters function
if workflowRunVal, exists := onMap["workflow_run"]; exists {
    if err := validateFilterExclusivity(workflowRunVal, "workflow_run"); err != nil {
        return err
    }
}

if prTargetVal, exists := onMap["pull_request_target"]; exists {
    if err := validateFilterExclusivity(prTargetVal, "pull_request_target"); err != nil {
        return err
    }
}

Priority 3: Schema Mutual Exclusivity Documentation

Timeline: Next schema update

Add to sandbox field description:

Note: sandbox-runtime (SRT) and network.firewall (AWF) are mutually exclusive. Choose one sandbox approach for your workflow.

---

Strategy Performance

Strategy Details

• Name: Conditional Logic & Feature Flag Analysis
• ID: strategy-005
• Run: 10th execution
• Last Used: 2026-01-23

Findings

• Critical: 1 (label-only exception)
• Moderate: 2 (filter validation coverage, schema gaps)
• Positive: 3 (excellent implementations)
• Total: 6 findings

Effectiveness

• Rating: VERY HIGH ⭐⭐⭐⭐⭐
• Unique Value: Focuses on feature interactions and conditional requirements rather than individual field validation
• Key Strength: Discovers implementation nuances and edge cases in complex conditional logic

Key Insights from This Run

1. Label-only exception is sophisticated edge case handling - validates that label-only issues/PRs can coexist with slash_command, but this intelligence is hidden from users
2. Documentation explicitly prohibits what code allows - creates user confusion and missed opportunities
3. Filter validation infrastructure excellent but incomplete - easy to extend to other events
4. branches/branches-ignore pattern is gold standard - perfect schema-code-docs alignment, should be template for other mutual exclusivity constraints

Should Reuse This Strategy?

YES - Strategy continues to find valuable conditional logic gaps. Recommended for use every 4-5 analyses to validate feature interaction documentation.

---

Next Steps

• Document label-only exception in command-triggers.md
• Add example workflow showing slash_command + label-only pattern
• Extend filter validation to workflow_run, pull_request_target, merge_group
• Add sandbox/firewall mutual exclusivity note to schema descriptions
• Consider creating "conditional requirements" section in documentation

---

Analysis Date: 2026-01-23
Strategy: Conditional Logic & Feature Flag Analysis (005)
Run Number: 10
Files Analyzed:

• pkg/parser/schemas/main_workflow_schema.json
• pkg/workflow/compiler_filters_validation.go
• pkg/workflow/compiler_safe_outputs.go
• pkg/workflow/sandbox_validation.go
• pkg/parser/schema_triggers.go
• docs/src/content/docs/reference/command-triggers.md

Workflow Run: §21304988485

AI generated by Schema Consistency Checker

• expires on Jan 30, 2026, 11:57 PM UTC

[github-actions[bot]]

This discussion was automatically closed because it expired on 2026-01-30T23:57:14.787Z.