[Schema Consistency] Schema consistency check - 2026-08-03

[github-actions[bot]]

🔍 Schema Consistency Check - 2026-08-03

Summary

• Inconsistencies Found: 4
• Categories Analyzed: Schema, Parser, Documentation, Workflows
• Strategy Used: Engine catalog + safe-output naming drift verification v2
• New Strategy: NO

Critical Issues

1. engine.id schema is looser than runtime validation and its built-in engine list is stale

   • Schema: pkg/parser/schemas/main_workflow_schema.json:12908 defines engine.extensions, but the engine.id branch remains a plain string with no enum/const guard, and a targeted search found no antigravity mention anywhere in the schema.
   • Runtime/compiler: pkg/workflow/engine_definition.go:18 and :286 state the built-in engine catalog includes antigravity (and pi).
   • Real workflows: .github/workflows/smoke-antigravity.md:37 uses engine.id: antigravity.
   • Impact: schema validation can accept typoed engine IDs that only fail later at compile/runtime, while schema-driven docs/examples omit a supported built-in engine.

2. docs/reference/engines.md omits a runtime-supported built-in engine

   • Docs: docs/src/content/docs/reference/engines.md available-engine table lists Copilot, Claude, Codex, Gemini, OpenCode, and Pi.
   • Runtime/workflows: pkg/workflow/engine_definition.go and .github/workflows/smoke-antigravity.md confirm antigravity is supported and exercised.
   • Impact: users consulting the main engine reference will not discover a supported engine that already works in code and workflows.

Documentation Gaps

1. frontmatter-full.md still surfaces deprecated dispatch_repository
   • Schema/docs: pkg/parser/schemas/main_workflow_schema.json:9956-9958 keeps dispatch_repository only as a deprecated alias of dispatch-repository.
   • Parser/compiler: pkg/workflow/dispatch_repository.go:37-42 accepts the underscore alias only for backward compatibility and logs a deprecation warning.
   • Generated full docs: docs/src/content/docs/reference/frontmatter-full.md (around the safe-outputs dispatch section near the provided offset) still surfaces the deprecated alias instead of steering readers to the canonical kebab-case key.
   • Impact: generated docs keep teaching the form the compiler warns against.

Schema Improvements Needed

1. Add machine-checkable constraints or generated built-in catalog coverage for engine.id

   • Current schema relies on descriptions instead of constraints.
   • Because runtime rejects unknown engines, the schema should either:
     • enumerate built-in IDs for the built-in branch, or
     • clearly model the distinction between named built-ins and inline/custom definitions.

2. Normalize naming within safe-outputs.dispatch-repository

   • Canonical parent key is kebab-case: dispatch-repository.
   • Nested properties remain snake_case in both schema and parser:
     • event_type at pkg/parser/schemas/main_workflow_schema.json:9869-9871 and pkg/workflow/dispatch_repository.go:74
     • allowed_repositories at pkg/parser/schemas/main_workflow_schema.json:9879 and pkg/workflow/dispatch_repository.go:82-89
   • Impact: the safe-outputs surface mixes naming conventions inside one feature, increasing author confusion and doc drift.

Parser Updates Required

1. Consider converging error/reporting strings on canonical names
   • Parser warning in pkg/workflow/dispatch_repository.go:42 correctly prefers dispatch-repository.
   • But much of the surrounding implementation and tests still use underscore-oriented names such as dispatch_repository (for handler/tool identifiers and test names), reinforcing mixed-surface terminology.
   • Impact: users see both spellings across validation, docs, and internal naming.

Workflow Violations

• No invalid workflow usage was required to prove the drift.
• Instead, actual workflows demonstrate supported-but-underdocumented behavior:
  • .github/workflows/smoke-antigravity.md:37 uses engine.id: antigravity
  • many workflows use engine.id: pi, matching docs and runtime
• This means the main workflow corpus validates the runtime support claim, while the schema/docs remain behind.

Recommendations

1. Update docs/src/content/docs/reference/engines.md to add antigravity anywhere engine choices are enumerated.
2. Update schema-generated descriptions/examples for engine.id so built-in engine lists include antigravity, and consider adding stronger constraints than a free-form string.
3. Regenerate or adjust docs/src/content/docs/reference/frontmatter-full.md so the canonical safe-output key shown to users is dispatch-repository, not deprecated dispatch_repository.
4. Choose one nested naming style for dispatch repository config; preferably add kebab-case aliases (or migrate fully) for event-type / allowed-repositories while preserving compatibility.

Strategy Performance

• Strategy Used: Engine catalog + safe-output naming drift verification v2
• Findings: 4
• Effectiveness: HIGH
• Should Reuse: YES

Next Steps

• Fix schema descriptions/constraints for engine IDs
• Update engine reference docs
• Update generated frontmatter docs to prefer canonical safe-output keys
• Normalize dispatch-repository nested field naming

References:

• .github/workflows/smoke-antigravity.md
• docs/src/content/docs/reference/engines.md
• pkg/workflow/dispatch_repository.go

Generated by ✅ Schema Consistency Checker · gpt54 · 17.7 AIC · ⌖ 5.96 AIC · ⊞ 8.3K · ◷

• expires on Aug 3, 2026, 10:36 PM UTC-08:00

[github-actions[bot]]

This discussion has been marked as outdated by Schema Consistency Checker.

A newer discussion is available at Discussion #50195.