[Schema Consistency] 🔍 Schema Consistency Check - Conditional Logic & Feature Interactions (2025-10-25)

[github-actions[bot]]

🔍 Schema Consistency Check - 2025-10-25

Summary

• Inconsistencies Found: 11
• Categories Analyzed: Schema, Parser, Documentation, Workflows
• Strategy Used: Conditional Logic & Feature Flag Analysis (NEW)
• New Strategy: YES
• Workflows Analyzed: 56 total, 26 using strict mode (46% adoption)

Executive Summary

This analysis used a NEW strategy focusing on conditional logic, feature interactions, and feature flag validation. Unlike previous strategies that focused on field enumeration and type matching, this strategy examines:

1. Conditional requirements (if X is set, then Y must be set)
2. Feature conflicts (X and Y cannot be used together)
3. Feature flag validation (strict mode enforcement)
4. Schema conditional logic (JSON Schema if/then/else, dependencies, anyOf)

Key Finding: The codebase has extensive conditional validation logic but the main schema lacks JSON Schema conditional constructs (if/then/else, dependencies) to encode these rules declaratively. However, MCP tool schemas DO use sophisticated conditionals (anyOf, not, allOf) - providing an excellent gold standard example.

---

Critical Issues

1. Missing Top-Level JSON Schema Conditionals

Location: pkg/parser/schemas/main_workflow_schema.json

Issue: The main workflow schema has NO if/then/else or dependencies fields despite extensive conditional validation in the code.

Code Reality:

• Command cannot be used with issues, issue_comment, pull_request, pull_request_review_comment
• Strict mode enforces 6+ conditional requirements
• Network restrictions require firewall-capable engines
• MCP tools have mutually exclusive properties

Impact: HIGH - Schema validation cannot catch invalid configurations that the compiler will reject later.

2. Strict Mode Conditional Requirements Not in Schema

Location: pkg/workflow/strict_mode.go vs pkg/parser/schemas/main_workflow_schema.json

Issue: Strict mode enforces 6 conditional requirements but schema doesn't encode them with JSON Schema conditionals.

Requirements Enforced by Code:

1. No write permissions for contents/issues/pull-requests
2. Network configuration REQUIRED
3. No wildcard * in network.allowed
4. Custom MCP servers with containers MUST have network config
5. No bash wildcards (*, :*)
6. Timeout validation (not enforced currently)

Impact: HIGH - Users won't get schema validation errors until runtime compilation.

3. Command Event Conflicts Not Documented with Examples

Issue: Code enforces that command cannot be used with 4 specific events, but docs don't show this restriction with clear anti-examples.

Impact: MEDIUM - Users might try invalid combinations and get compile errors without understanding why.

Recommendation: Add anti-examples to triggers documentation showing what NOT to do.

---

Schema Architecture Strengths

✅ Excellent: MCP Tool Schema Conditionals

Location: pkg/parser/schemas/main_workflow_schema.json → $defs.stdio_mcp_tool

MCP tool schemas USE sophisticated JSON Schema conditionals correctly:

{
  "anyOf": [
    { "required": ["command"] },
    { "required": ["container"] }
  ],
  "not": {
    "allOf": [
      { "required": ["command"] },
      { "required": ["container"] }
    ]
  },
  "allOf": [
    {
      "if": { "required": ["network"] },
      "then": { "required": ["container"] }
    }
  ]
}

This correctly encodes:

• ✅ Must have EITHER command OR container (not neither)
• ✅ Cannot have BOTH command AND container
• ✅ If network config exists, container is required

This is the GOLD STANDARD - the same approach should be used for top-level conditional requirements.

---

Documentation Gaps

4. Strict Mode Side Effects Not Fully Documented

Current Docs: List 4 requirements
Missing: Bash wildcard restrictions, CLI precedence rules, isolation behavior, non-strict mode behavior

5. Network Configuration Conditional Not Documented

MCP schema has conditional: "If you specify network config for an MCP server, you MUST use container (not command)"

This is encoded in schema but not explained in documentation.

---

Workflow Usage Analysis

Findings from 56 Production Workflows:

• Strict Mode: 26/56 (46%) use strict: true - significant adoption
• Network Config: 14 workflows have network configuration
• Command Conflicts: 0 violations ✅ - all workflows respect rules
• Validation: Production workflows respect all conditional requirements ✅

---

Recommendations

Immediate Actions (High Priority)

1. Add JSON Schema conditionals to main schema for:

   • Command event conflicts
   • Engine conflicts
   • Consider: Strict mode requirements (or document why they're runtime-only)

2. Document command event restrictions with clear anti-examples in triggers.md

3. Expand strict mode documentation to cover all 6 requirements + precedence rules

Medium Priority

4. Document network/container dependency for MCP servers in mcps.md
5. Add validation timing section explaining schema vs compile vs runtime validation
6. Create troubleshooting guide for common conditional requirement errors

---

Strategy Performance

• Strategy Used: Conditional Logic & Feature Flag Analysis
• Findings: 11 inconsistencies/gaps
• Effectiveness: VERY HIGH
• Should Reuse: YES

What Made This Effective:

• Focused on relationships between fields (not just individual fields)
• Analyzed feature interactions and conflicts
• Examined JSON Schema conditional constructs
• Compared schema conditionals vs code conditionals

Complementary Strategies: Use with enum validation, required fields, and cross-schema consistency strategies for comprehensive coverage.

---

Key Patterns Discovered

1. Schema Conditional Gap: Main schema lacks JSON Schema conditionals despite extensive code logic
2. MCP Schema Excellence: MCP tool schemas are gold standard examples of proper conditional encoding
3. Validation Timing: Three stages (schema parse, compile time, runtime) - users need clarity
4. Field Relationships: Many rules are about field combinations, not individual fields
5. Strict Mode Significance: 46% adoption shows this is a major production feature

---

Next Steps

• Add JSON Schema conditionals to main schema
• Update triggers.md with command restrictions and anti-examples
• Expand strict mode documentation
• Add MCP network/container docs
• Create validation timing section in reference docs
• Consider troubleshooting guide for conditional errors

---

Full Analysis Report: Available in /tmp/gh-aw/cache-memory/analysis-report-2025-10-25.md
Strategy Database: Updated in /tmp/gh-aw/cache-memory/strategies.json

AI generated by Schema Consistency Checker

[github-actions[bot]]

This discussion was automatically closed because it was created by an agentic workflow more than 1 month ago.