Graph-Based Field Dependency Analysis - 7 Critical Relationship Gaps Found

[github-actions[bot]]

Overview

This analysis introduces a novel graph-based dependency analysis strategy that examines relationships between fields rather than individual field validation. By mapping field dependencies, mutual exclusivities, and feature interactions across the schema, parser, and compiler, this approach discovered 7 critical relationship gaps where the schema permits invalid configurations that the compiler correctly rejects.

Key Achievement: First analysis to systematically map the hidden dependency graph between frontmatter fields, revealing architectural complexity invisible to field-level validation strategies.

Summary

• Inconsistencies Found: 7 critical relationship gaps
• Categories Analyzed: Field dependencies, mutual exclusivities, engine-specific features, conditional requirements
• Strategy Used: NEW - Graph-Based Dependency & Feature Interaction Analysis (Fix invalid YAML because of ANSI escape sequences #26)
• Effectiveness: VERY HIGH

Critical Issues

1. Mutually Exclusive Fields Missing Schema Constraints

Problem: Five pairs of mutually exclusive fields lack oneOf or conditional schema constraints, allowing invalid configurations to pass schema validation.

Field Pair	Enforced In	Schema Status	Impact
branches vs branches-ignore	pkg/workflow/compiler_filters_validation.go:92	❌ No constraint	Users can specify both
paths vs paths-ignore	pkg/workflow/compiler_filters_validation.go:101	❌ No constraint	Validation deferred to compile time
slash_command vs label events	pkg/workflow/compiler_safe_outputs.go:91	❌ No constraint	Editor autocomplete misleading
command vs label events	pkg/workflow/compiler_safe_outputs.go:112	❌ No constraint	IDE validation ineffective
MCP command vs container	pkg/workflow/mcp_config_validation.go:278	❌ No constraint	User trial-and-error required

Example Invalid Configuration:

on:
  push:
    branches: [main, develop]
    branches-ignore: [feature/*]  # ❌ Schema allows this, compiler rejects

Recommendation: Add oneOf constraints to schema.

2. Engine-Specific Feature Compatibility Undocumented

Problem: Multiple features work only on specific engines, but the schema provides no compatibility matrix.

Engine-Locked Features Discovered:

Feature	Engine Restriction	Code Location	Schema Documentation
Firewall	Only copilot & codex	pkg/workflow/firewall.go:89,105	❌ None
HTTP Transport	Varies by engine	pkg/workflow/engine_validation.go	❌ None
Sandbox	copilot only	pkg/workflow/firewall.go:135	❌ None
Max-turns	Engine-specific	pkg/workflow/agent_validation.go:143	❌ None

Impact: Users configure engine: claude with firewall settings, workflow compiles but firewall is silently ignored or fails at runtime.

Recommendation: Add engine compatibility metadata to schema $comment fields.

3. Conditional Field Requirements Not Schema-Enforced

Problem: Field X requires field Y under specific conditions (enforced in code), but schema has no if/then or dependencies constraints.

Conditional Requirement	Code Location	Schema Status
Label trigger requires ≥1 label	bundler_validation.go	❌ No minItems
MCP containers need network in strict mode	strict_mode_validation.go	⚠️ In description only
Write permissions → safe-outputs in strict	strict_mode_validation.go:68	⚠️ In description only
Sandbox-runtime requires feature flag	compiler_parse.go	❌ Not mentioned
UV packages require network access	bundler_validation.go	❌ Not mentioned

Recommendation: Use JSON Schema conditional validation (if/then).

4. High-Coupling Fields Create Hidden Complexity

Discovery: Field access pattern analysis reveals architectural complexity not hinted in schema.

High-Coupling Fields (accessed from 10+ files):

• on: 10+ files
• safe-outputs: 5+ files with complex validation chains
• engine: Affects validation in 20+ locations

Most Complex File: pkg/workflow/frontmatter_extraction.go accesses 12 different fields

Impact: Changes to these fields require coordinated updates across many files. New contributors unaware of coupling risks.

Recommendation: Add $comment metadata for high-coupling fields documenting which files access them.

5. Validation Order Dependencies Implicit

Problem: Some validations must run in specific order, but no schema metadata indicates this.

Examples:

1. Safe-outputs validation requires engine config to be parsed first
2. Strict mode validation must run after basic field validation
3. Network validation depends on engine type determination

Recommendation: Document validation order in $comment fields.

6. Default Value Conditional Logic Undocumented

Problem: Some fields get different default values based on other fields' presence/values.

Example:

// pkg/workflow/compiler_safe_outputs.go:28
if onValue, exists := frontmatter["on"]; exists {
    // Changes safe-outputs default behavior based on trigger type
}

Impact: Users cannot predict behavior without reading Go code.

Recommendation: Document conditional default behavior in schema $comment.

7. Missing JSON Schema Standard Features

Problem: Schema doesn't use JSON Schema's built-in relationship features (dependencies, dependentRequired, dependentSchemas).

Current: All relationships described in prose within description fields only.

Impact: Cannot leverage schema validator's automatic relationship checking.

Recommendation: Refactor to use JSON Schema standard relationship keywords.

Positive Findings

✅ Strict mode documentation exemplary: Comprehensive list of all requirements
✅ Error messages excellent: Clear relationship violation explanations
✅ Validation implementation solid: All relationships properly enforced at compile time
✅ No broken enforcement: All 7 issues are schema-documentation gaps, NOT implementation bugs

Recommendations

High Priority

1. Add oneOf constraints for mutually exclusive field pairs
2. Document engine-specific feature compatibility in schema $comment fields
3. Implement JSON Schema if/then for conditional requirements
4. Add minItems constraints where appropriate

Medium Priority

5. Use JSON Schema dependencies keyword for field relationships
6. Add architectural complexity notes for high-coupling fields
7. Document validation order dependencies
8. Clarify conditional default value behavior

Low Priority

9. Create relationship visualization diagram
10. Add integration tests for all discovered relationships

Strategy Performance

• Strategy: Graph-Based Dependency & Feature Interaction Analysis (NEW Fix invalid YAML because of ANSI escape sequences #26)
• Findings: 7 critical relationship gaps
• Effectiveness: VERY HIGH
• Should Reuse: YES

Why This Strategy Works:

• Focuses on connections between fields, not individual fields
• Reveals architectural complexity through relationship mapping
• Finds integration gaps invisible to field enumeration strategies
• Discovers implicit dependencies from code analysis

Next Steps

Immediate

• Add oneOf constraints for branches/paths pairs
• Document engine compatibility in schema $comment
• Add minItems to label triggers

Short-term

• Implement if/then validation for strict mode
• Audit all mutual exclusivity patterns
• Add validation order documentation

Long-term

• Refactor to use JSON Schema dependencies
• Create field relationship visualization
• Write "Field Relationships" documentation page

References

Relationship Enforcement:

• Mutual exclusivity: pkg/workflow/compiler_filters_validation.go:92,101
• Command restrictions: pkg/workflow/compiler_safe_outputs.go:91,112
• Engine features: pkg/workflow/firewall.go:89,105,135
• Strict mode: pkg/workflow/strict_mode_validation.go:68

High-Coupling Analysis:

• Complex file: pkg/workflow/frontmatter_extraction.go (12 field accesses)

AI generated by Schema Consistency Checker

[pelikhan]

/plan

[github-actions[bot]]

🎉 Yo ho ho! Plan Command found the treasure and completed successfully! ⚓💰

[github-actions[bot]]

Plan Created

Created a comprehensive implementation plan to address the 7 critical relationship gaps identified in the graph-based field dependency analysis.

Parent Tracking Issue: Links to this discussion and coordinates all work

Sub-Issues Created (5 focused tasks):

1. Add oneOf constraints for mutually exclusive field pairs
2. Document engine-specific feature compatibility in schema
3. Add if/then conditional validation for field requirements
4. Add minItems constraints for array fields requiring values
5. Refactor relationship prose to use dependencies keyword

Each sub-issue includes:

• Clear objective and context
• Specific fields/relationships to address
• Implementation approach with examples
• Files to modify
• Acceptance criteria
• Testing guidance

The plan prioritizes schema improvements that will catch configuration errors during editing rather than at compile time, improving the developer experience significantly.

AI generated by Plan Command for discussion #7569