[Schema Consistency] 🔍 Schema Consistency Check - 2026-07-25

[github-actions[bot]]

Summary

• Inconsistencies Found: 4
• Categories Analyzed: Schema, Parser, Documentation, Workflows
• Strategy Used: Cross-surface antigravity/docs alias drift spot check
• New Strategy: No

Critical Issues

1. engine.id built-in engine list is stale in the schema/docs while runtime and workflows support antigravity.

   • Runtime catalog comments list antigravity as built-in in pkg/workflow/engine_definition.go:18 and pkg/workflow/engine_definition.go:285.
   • Real workflow usage exists in .github/workflows/smoke-antigravity.md:37.
   • But the schema still describes engine.id as codex, claude, copilot, gemini, opencode, pi only in pkg/parser/schemas/main_workflow_schema.json:12532-12533.
   • docs/src/content/docs/reference/engines.md also omits antigravity from the available engines table.
   • Impact: schema validation/docs understate supported engines; users may treat a valid engine as unsupported.

2. Schema is looser than the parser/runtime for engine.id.

   • pkg/parser/schemas/main_workflow_schema.json:12530-12533 leaves engine.id as an unconstrained string, even though the runtime resolves against a fixed built-in catalog and rejects unknown engines.
   • Impact: typos can pass schema validation but fail later during compile/runtime resolution.

Documentation Gaps

1. frontmatter-full.md still surfaces deprecated safe-outputs.dispatch_repository.

   • Parser accepts both names but logs a warning to rename underscore form in pkg/workflow/dispatch_repository.go:36-41.
   • Schema also marks dispatch_repository as deprecated alias in pkg/parser/schemas/main_workflow_schema.json:9637-9639.
   • Yet docs/src/content/docs/reference/frontmatter-full.md:8464-8468 still documents the deprecated alias as a normal config block instead of minimizing it as migration-only guidance.
   • Impact: docs keep steering users toward a name the parser explicitly warns against.

2. dispatch-repository nested key naming remains snake_case-only in a kebab-case surface.

   • frontmatter-full.md:8388+ explicitly documents nested keys such as event_type and allowed_repositories.
   • Parser logging/comments reinforce the same shape in pkg/workflow/dispatch_repository.go:10, :29, :112.
   • Impact: this is an inconsistent naming exception inside safe-outputs, increasing user confusion and making configs harder to predict.

Schema Improvements Needed

1. Update engine.id description/examples in pkg/parser/schemas/main_workflow_schema.json:12532-12533 to include antigravity.
2. Consider adding an enum (or generated enum) for known built-in engine.id values, or document clearly that arbitrary IDs are allowed only for custom runtimes if that is intentional.
3. Keep dispatch_repository in schema only as a deprecated compatibility alias and de-emphasize it in generated docs.

Parser Updates Required

1. No parser bug was found for dispatch-repository; parser behavior is actually ahead of docs because it warns on deprecated alias usage.
2. If engine.id should remain open-ended, parser/docs/schema should all state that explicitly; otherwise schema should align with runtime validation.

Workflow Violations

1. No invalid workflow usage was confirmed in repository workflows for these spot checks.
2. .github/workflows/smoke-antigravity.md:37 is valid against runtime behavior but demonstrates the schema/docs drift around antigravity.

Recommendations

1. Add antigravity everywhere the built-in engine catalog is enumerated, especially schema descriptions/examples and docs/src/content/docs/reference/engines.md.
2. Tighten engine.id schema validation or document the intentional runtime-vs-schema split.
3. Move dispatch_repository to a short deprecated migration note in frontmatter-full.md instead of a full surfaced block.
4. Decide whether dispatch-repository nested keys should keep snake_case forever; if yes, call out the exception consistently across docs/reference pages.

Strategy Performance

• Strategy Used: Cross-surface antigravity/docs alias drift spot check
• Findings: 4
• Effectiveness: High
• Should Reuse: Yes

Next Steps

• Fix schema descriptions/examples for engine.id
• Decide on engine.id enum vs open-ended contract
• Update engines.md engine table
• Reduce deprecated alias prominence in frontmatter-full.md
• Clarify dispatch-repository snake_case nested key exception

References:

• §30146951630

Generated by ✅ Schema Consistency Checker · gpt54 · 15.4 AIC · ⌖ 8.52 AIC · ⊞ 7.5K · ◷

• expires on Jul 25, 2026, 10:12 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 #48137.