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

[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: YES

Critical Issues

1. Built-in engine catalog drift for antigravity

   • Runtime supports antigravity: pkg/workflow/engine_definition.go:18, pkg/workflow/engine_definition.go:285, and invalid-engine errors enumerate the registry-derived engine list at pkg/workflow/engine_definition.go:360-370.
   • Real workflow usage exists: .github/workflows/smoke-antigravity.md:33-35 sets engine.id: antigravity.
   • But generated docs still omit it from the built-in engine list: docs/src/content/docs/reference/engines.md:14-21 lists only copilot, claude, codex, gemini, opencode, and pi; docs/src/content/docs/reference/frontmatter-full.md:2287-2295 also omits antigravity.
   • The schema/examples are therefore looser in implementation than in docs, creating false negatives for users who rely on documentation to discover valid engine IDs.

2. Deprecated alias still prominently surfaced in docs

   • Parser treats safe-outputs.dispatch-repository as canonical and logs a deprecation warning for safe-outputs.dispatch_repository: pkg/workflow/dispatch_repository.go:36-41.
   • frontmatter-full still documents the full deprecated alias block as a first-class surface: docs/src/content/docs/reference/frontmatter-full.md:9088-9092.
   • This keeps steering users toward a deprecated key that the parser explicitly asks them to rename.

Documentation Gaps

1. engines.md is incomplete for available engines

   • docs/src/content/docs/reference/engines.md:14-21 has no Antigravity row, despite runtime support and a checked-in workflow using it.

2. frontmatter-full.md built-in engine comments lag runtime reality

   • docs/src/content/docs/reference/frontmatter-full.md:2287-2295 says built-ins are claude, codex, copilot, gemini, opencode, pi, omitting antigravity.

Schema Improvements Needed

1. Engine schema descriptions/examples should include antigravity

   • In pkg/parser/schemas/main_workflow_schema.json, the engine object includes examples/descriptions for built-in IDs around 12488-12544, but antigravity is absent.
   • The inline runtime branch examples around 12542-12568 also omit it.
   • Since parser/runtime reject unknown engine IDs based on the registered catalog, the schema description/examples should reflect the actual built-in set.

2. Safe-output naming remains internally inconsistent

   • pkg/parser/schemas/main_workflow_schema.json:9537-9639 and docs/src/content/docs/reference/frontmatter-full.md:9010-9092 explicitly preserve snake_case nested keys (event_type, allowed_repositories) inside dispatch-repository, while neighboring safe-output surfaces are predominantly kebab-case.
   • This may be intentional for compatibility, but it remains a cross-surface inconsistency worth either documenting more prominently or normalizing with aliases.

Parser Updates Required

1. No functional parser bug found for these items, but docs/schema should align with parser behavior
   • pkg/workflow/dispatch_repository.go:36-41 already encodes the desired direction: canonical kebab-case key, underscore alias only for backward compatibility.
   • pkg/workflow/engine_definition.go:18, :285, and :360-370 already reflect the actual built-in engine catalog including antigravity.

Workflow Violations

1. No invalid checked-in workflow found in the targeted spot check
   • Instead, workflows exposed the opposite problem: .github/workflows/smoke-antigravity.md:33-35 uses a runtime-supported engine that the docs do not advertise.

Recommendations

1. Add antigravity anywhere built-in engine IDs are enumerated in docs and schema-generated comments/examples.
2. Reduce prominence of dispatch_repository in frontmatter-full.md by marking it as legacy-only or removing the expanded deprecated example block.
3. Decide whether dispatch-repository nested snake_case keys are intentional long-term API surface; if not, add kebab-case aliases and document the migration path.
4. Add a regression check that compares registered engine IDs from runtime against the generated docs/schema examples to catch future catalog drift.

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 built-in engine IDs
• Update docs/src/content/docs/reference/engines.md
• Update docs/src/content/docs/reference/frontmatter-full.md
• Decide and document the long-term naming plan for dispatch-repository nested keys

References:

• §30190847215

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

• expires on Jul 26, 2026, 10:23 PM UTC-08:00