[Schema Consistency] Schema Consistency Check - Default Values & Required Fields Analysis (2026-02-13)

[github-actions[bot]]

Comprehensive analysis of default value consistency between JSON schema, Go parser/compiler implementation, documentation, and real workflow usage.

Summary

• Analysis Strategy: Default Values & Required Fields Consistency (New Strategy)
• Inconsistencies Found: 5 critical issues + 3 documentation gaps
• Categories Analyzed: Schema defaults, compiler implementation, documentation accuracy, real workflow usage
• Key Focus: How schema defaults are actually applied in code vs. documented behavior

Critical Issues

1. 🚨 MCP Port Default Value Mismatch (CRITICAL BUG)

Severity: HIGH - Data inconsistency across all layers

• Schema: sandbox.mcp.port default = 8080 (line 2425)
• Go Constant: DefaultMCPGatewayPort = 80 (pkg/constants/constants.go:284)
• Documentation: States "default: 8080" (frontmatter-full.md:1087, sandbox.md:279)
• Impact: Runtime uses port 80, but users expect 8080 based on schema/docs

Evidence:

• Schema defines: "default": 8080 at line 2425
• Code applies: Port: int(DefaultMCPGatewayPort) where constant = 80
• All 13 documentation examples show port 8080

Recommendation: Decide on correct port (likely 8080 for non-privileged) and update either constant or schema + docs to match.

---

2. ⚠️ Strict Mode Default Documentation Inconsistency

Severity: MEDIUM - Confusing user experience

• Schema: "default": true (implicit from strict: true at line 3684)
• Compiler: Explicitly defaults to true when unset (compiler_orchestrator_engine.go:66)
• Documentation: Contradictory statements
  • Line 225: "Non-strict mode (default)" ❌
  • Line 266: "Enabled by default" ✅

Evidence:

• 93 of 147 workflows (63%) explicitly set strict: true
• Only 3 workflows set strict: false
• 54 workflows rely on implicit default (37%)

Recommendation: Update frontmatter.md line 225 to say "Non-strict mode (optional)" instead of "default".

---

3. ⚠️ Reaction Emoji Default Not Documented

Severity: MEDIUM - Undocumented behavior

• Schema: on.reaction default = "eyes"
• Compiler: Auto-applies "eyes" for command triggers (compiler_safe_outputs.go:140-141)
• Documentation: Says "defaults to 'eyes'" but doesn't mention it's automatic for commands

Code:

// Auto-enable "eyes" reaction for command triggers if no explicit reaction was specified
if hasCommand && !hasReaction && workflowData.AIReaction == "" {
    workflowData.AIReaction = "eyes"
}

Recommendation: Document that command triggers automatically use "eyes" reaction unless overridden.

---

4. ℹ️ Engine Default Documentation Clarity

Severity: LOW - Could be clearer

• Schema: engine default = "copilot"
• Compiler: Explicitly applies via GetDefaultEngine() returning "copilot"
• Documentation: States "default AI engine" correctly but not consistently

Evidence:

• 125 of 147 workflows (85%) explicitly specify engine
• Only 22 workflows (15%) rely on default
• Default correctly documented in engines.md:12

Recommendation: Add explicit note in frontmatter.md that omitting engine field defaults to GitHub Copilot CLI.

---

5. ℹ️ Safe-Outputs Footer Default Uses Implicit Nil Handling

Severity: LOW - Architectural observation

• Schema: All footer fields default to true
• Compiler: Uses *bool (pointer) with nil meaning "use default"
• JavaScript Runtime: Nil values omitted from JSON, JS applies true default

Pattern:

func getEffectiveFooter(localFooter *bool, globalFooter *bool) *bool {
    if localFooter != nil {
        return localFooter
    }
    return globalFooter  // nil = use JS-side default (true)
}

Observation: This is intentional architecture (dual-layer defaulting) but not documented. Consider adding comment explaining this pattern.

---

Documentation Gaps

View All Documentation Gaps

Gap 1: Sandbox Agent Default Clarity

• Schema: sandbox.agent default = "awf"
• Docs: Correctly mentions "Defaults to 'awf'" (frontmatter-full.md:930)
• Improvement: Add note that omitting entire sandbox: field also defaults to awf

Gap 2: Cache Memory Scope Default

• Schema: cache-memory.scope default = "workflow"
• Compiler: Explicitly applies empty string check (cache.go:112)
• Docs: Mentions default in text but no explicit YAML example showing omission

Gap 3: Serena Mode Default

• Schema: tools.serena.mode default = "docker"
• Compiler: String literal default (mcp_config_serena_renderer.go:106)
• Docs: States "(default, runs in container)" but not in structured format

---

Default Value Application Patterns

Analysis of how the 52 schema defaults are applied in Go code:

Pattern	Count	Examples
Explicit Runtime Assignment	6	engine, strict, sandbox.agent, cache-memory.scope, on.reaction, serena.mode
Explicit Constant + Zero-Value Check	1	sandbox.mcp.port (uses constant)
Implicit Nil Pointer Handling	28+	safe-outputs footer fields
JSON Schema Only	~17	Various nested safe-outputs config fields

Key Finding: Most critical defaults (engine, strict, sandbox.agent) are explicitly applied in code with dedicated logic, not relying on JSON unmarshaling defaults. This ensures consistent behavior but requires keeping schema + code synchronized.

---

Real Workflow Usage Statistics

Based on 147 workflow files in .github/workflows/:

Field	Explicit Usage	Implicit Default	Explicit False/Off
strict:	93 (63%) set to true	54 (37%) use default	3 (<2%) set false
engine:	125 (85%) explicit	22 (15%) use default	0
sandbox:	18 (12%) explicit	129 (88%) use default	0

Observation: High explicit strict: true usage (63%) suggests users are unsure of the default or following cargo-cult patterns from examples.

---

Recommendations

High Priority

1. Fix MCP Port Mismatch 🚨

   • Option A: Change DefaultMCPGatewayPort constant to 8080
   • Option B: Change schema/docs to 80 (requires explanation for privileged port)
   • Recommended: Option A (8080 is non-privileged, more portable)

2. Clarify Strict Mode Documentation ⚠️

   • Update frontmatter.md:225 to remove "(default)" from "Non-strict mode"
   • Emphasize that strict mode is ON by default
   • Add visual indicator (✅/❌) to examples

3. Document Command Reaction Auto-Enable ⚠️

   • Add note in command-triggers.md about automatic "eyes" reaction
   • Explain users can override with reaction: none or custom emoji

Medium Priority

4. Add Default Value Reference Table

   • Create a quick reference table in frontmatter.md showing all defaults
   • Format: Field → Default Value → Can Omit? → Notes

5. Document Default Application Architecture

   • Add developer note explaining dual-layer defaulting (Go runtime + JSON schema)
   • Explain when each layer applies defaults

6. Reduce Explicit strict: true Cargo-Culting

   • Update examples to omit strict: true since it's default
   • Show strict: false only when intentionally needed

---

Strategy Performance

Strategy Used: Default Values & Required Fields Consistency Analysis (NEW)

Components:

• Schema default value extraction (52 fields with defaults)
• Go code tracing for default application logic
• Documentation cross-reference for default mentions
• Real workflow usage statistics (147 workflows analyzed)

Effectiveness: HIGH

Findings: 5 critical issues + 3 documentation gaps

Should Reuse: YES - This strategy revealed a critical bug (MCP port mismatch) and architectural insights about dual-layer defaulting that previous strategies missed.

Key Insight: Focusing on the gap between declared defaults and applied defaults exposed mismatches that field enumeration strategies wouldn't catch. The MCP port discrepancy existed in plain sight but required comparing schema → constant → runtime application to detect.

---

Next Steps

• Fix DefaultMCPGatewayPort constant (change 80 → 8080)
• Update strict mode documentation to remove contradictions
• Document automatic "eyes" reaction for command triggers
• Create default values reference table
• Add developer documentation for default application patterns
• Update workflow examples to avoid explicit strict: true cargo-culting
• Validate that schema default values match test expectations

---

Analysis Date: 2026-02-13
Strategy: New - Default Values & Required Fields Consistency
Workflows Analyzed: 147
Schema Defaults Found: 52
Code Files Examined: 25+ compiler/parser files
Documentation Files: 8 reference docs

🤖 Generated with gh-aw Schema Consistency Checker

AI generated by Schema Consistency Checker

• expires on Feb 20, 2026, 6:50 AM UTC

[github-actions[bot]]

✨ Smoke Test Agent was here! ✨

Just passing through on my smoke test journey. Everything looks great in this discussion! 🚀

All systems nominal. Carry on! 🤖

---

This was an automated comment from smoke test run §21977573895

AI generated by Smoke Copilot

[github-actions[bot]]

💥 WHOOSH! 💥

🦸 The Smoke Test Agent has CRASH LANDED into this discussion! 🦸

KAPOW! Just completed a full diagnostic sweep through the gh-aw universe! All systems are GO and firing on all cylinders! 🚀

ZZZAP! - GitHub MCP: Connected! ✅
BOOM! - Serena Powers: Activated! ✅
WHAM! - Build Systems: Online! ✅
POW! - Playwright Vision: Crystal Clear! ✅
SLAM! - Tavily Search: Super Charged! ✅

With great power comes great testing! The smoke test has vanquished all bugs in its path! 💪

🎯 Mission accomplished at 07:19 UTC on 2026-02-13

The Smoke Test Agent will return... 🦇

---

Transmitted from the Smoke Test Batcave 🦇 | §21978182216

AI generated by Smoke Claude