[Schema Consistency] Schema Consistency Check - February 9, 2026

[github-actions[bot]]

Summary

Automated schema consistency analysis using Hybrid Semantic Field Coverage Analysis strategy. This run analyzed alignment between the JSON schema, compiler implementation, documentation, and actual workflows.

• Inconsistencies Found: 5 (1 high, 2 medium, 2 low priority)
• Categories Analyzed: Schema ✓ Parser ✓ Documentation ✓ Workflows ✓
• Strategy Performance: High effectiveness (proven strategy, 2nd successful use)

---

Critical Issues

🔴 HIGH: Missing 'labels' Field in FrontmatterConfig

Location: pkg/workflow/frontmatter_types.go

Issue: The schema defines labels as an array of strings for categorizing workflows (line 36-48 in main_workflow_schema.json), and documentation describes it (frontmatter.md:57-65), but the FrontmatterConfig struct lacks a Labels field.

Evidence:

• Schema: "labels": { "type": "array", "items": { "type": "string", "minLength": 1 } }
• FrontmatterConfig struct: No Labels field present
• Documentation: "Optional array of labels to categorize and organize workflows"

Impact: Labels defined in workflow frontmatter are not parsed into the typed config struct. While they may pass through as raw frontmatter data, they lack compile-time validation and type safety.

Recommendation: Add Labels []string \json:"labels,omitempty"`` to FrontmatterConfig and ensure serialization in ToMap() method.

🟡 MEDIUM: Duplicate timeout Field Names

Location: pkg/parser/schemas/main_workflow_schema.json

Issue: Schema defines both timeout-minutes and timeout_minutes as top-level properties, creating naming ambiguity.

Evidence:

• Both field names appear in schema properties
• FrontmatterConfig only has one TimeoutMinutes field
• No clear deprecation notice for either variant

Impact: Users may be confused about which field name to use. Could cause validation issues if both are present.

Recommendation:

1. Deprecate timeout_minutes (underscore version)
2. Document timeout-minutes (hyphen version) as canonical
3. Add deprecation notice to schema

🟡 MEDIUM: Unprocessed 'post-steps' Field

Location: pkg/parser/schemas/main_workflow_schema.json

Issue: Schema defines post-steps field but no compiler code accesses frontmatter["post-steps"].

Evidence:

• Schema includes post-steps in properties
• No frontmatter["post-steps"] access in pkg/workflow/*.go
• No PostSteps field in FrontmatterConfig

Impact: If users define post-steps in workflows, the field is silently ignored without error or warning.

Recommendation: Either implement post-steps processing or remove from schema and document rationale.

---

Low Priority Issues

⚪ LOW: Top-Level 'command' Field Not Used

Location: pkg/parser/schemas/main_workflow_schema.json

Issue: Schema defines top-level command field, but compiler only uses engine.command (nested within engine config).

Evidence:

• Schema has command in top-level properties
• Compiler accesses engine.command but not frontmatter["command"]
• No documentation mentions top-level command usage

Impact: Unclear whether this is deprecated or unimplemented. Could confuse users reading schema.

Recommendation: Clarify intent - either remove if deprecated or document usage if intentional.

⚪ LOW: Weak Type Safety for 'imports' Field

Location: pkg/workflow/frontmatter_types.go

Issue: Schema defines complex oneOf validation for imports (string OR object with path/inputs), but FrontmatterConfig uses loose any type.

Evidence:

• Schema: "oneOf": [{"type": "string"}, {"type": "object", "properties": {"path": ..., "inputs": ...}}]
• FrontmatterConfig: Imports any \json:"imports,omitempty"``

Impact: No compile-time type safety for imports. Malformed import structures may not produce clear error messages.

Recommendation: Consider creating ImportItem type union for better validation and error reporting.

---

Validation Confirmed ✅

The following fields were verified to have proper schema-compiler-documentation alignment:

• ✅ strict: Properly implemented in compiler_orchestrator_engine.go
• ✅ cache: Correctly handled as GitHub Actions passthrough
• ✅ engine: Matches $defs/engine_config definition
• ✅ network: Properly typed with NetworkPermissions struct
• ✅ metadata: Included in FrontmatterConfig with correct type
• ✅ tracker-id: Validated and used throughout compiler

---

Recommendations

1. Add Labels field to FrontmatterConfig (high priority for type safety)
2. Deprecate timeout_minutes in favor of timeout-minutes (reduce ambiguity)
3. Clarify post-steps intent - implement or remove from schema
4. Review command field - document or remove top-level usage
5. Consider ImportItem type for stronger imports validation

---

Strategy Performance

Strategy: Hybrid Semantic Field Coverage Analysis (proven from cache)
Approach: Field enumeration + type analysis + cross-referencing
Effectiveness: HIGH (5 issues found)
Should Reuse: YES ✅

This strategy successfully identified:

• Missing struct fields (labels)
• Naming inconsistencies (timeout variants)
• Unused schema definitions (command, post-steps)
• Type safety gaps (imports any type)

Next Run Recommendation: Use this strategy again (70% probability selection) or try Strategy 2 (Deep Type Constraint Validation) for complementary analysis.

---

References:

• §21815157682

AI generated by Schema Consistency Checker

• expires on Feb 16, 2026, 6:52 AM UTC

[github-actions[bot]]

This discussion was automatically closed because it expired on 2026-02-16T06:52:54.090Z.

Closed by Workflow