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

[github-actions[bot]]

Summary

• Inconsistencies Found: 4
• Categories Analyzed: Schema, Parser, Documentation, Workflows
• Strategy Used: Engine catalog + deprecated safe-output alias targeted verification
• New Strategy: YES

Critical Issues

1. Runtime-supported antigravity is missing from engine reference docs

   • Runtime comments explicitly list antigravity as a built-in engine in pkg/workflow/engine_definition.go:16-18.
   • Real workflow usage exists in .github/workflows/smoke-antigravity.md:37.
   • But docs/src/content/docs/reference/engines.md frontmatter/overview only lists Copilot, Claude, Codex, Gemini, OpenCode, and Pi (engines.md:3,16-21).
   • Impact: users can successfully use an engine that the primary engine docs do not advertise.

2. Schema/docs surface a deprecated alias alongside the canonical safe-output key

   • Parser treats safe-outputs.dispatch-repository as canonical and warns when dispatch_repository is used in pkg/workflow/dispatch_repository.go:35-41.
   • Schema still exposes both dispatch-repository and deprecated alias dispatch_repository at pkg/parser/schemas/main_workflow_schema.json:9557-9659.
   • docs/src/content/docs/reference/frontmatter-full.md:9088-9111 still renders the deprecated alias as a full top-level example block.
   • Impact: docs continue teaching a spelling that compiler logs explicitly ask users to rename.

Documentation Gaps

1. engines.md omits antigravity despite parser/runtime support

   • Evidence above; this is the clearest doc drift across parser/runtime/workflow surfaces.

2. frontmatter-full.md presents deprecated dispatch_repository as if it were a normal supported key

   • Because it is fully expanded with examples, users are likely to copy it instead of the canonical kebab-case key.

Schema Improvements Needed

1. Deprecated alias should be downgraded in generated schema/docs output

   • Keep dispatch_repository for compatibility if needed, but mark it more aggressively as deprecated and avoid presenting it as a first-class example block.

2. Safe-output naming remains internally inconsistent

   • dispatch-repository description in schema explicitly says nested keys use snake_case (event_type, allowed_repositories) at main_workflow_schema.json:9559,9574,9584.
   • Surrounding safe-output surface is predominantly kebab-case.
   • Impact: high typo risk and harder memorability.

Parser Updates Required

1. Consider normalizing nested dispatch-repository keys
   • Parser currently reads only snake_case nested keys in pkg/workflow/dispatch_repository.go:68-81.
   • If kebab-case nested aliases are intentionally unsupported, docs/schema should emphasize that more strongly.
   • Otherwise, parser could accept both spellings for consistency with the broader frontmatter style.

Workflow Violations

1. No immediate invalid workflow usage found in the targeted check
   • The main workflow-side inconsistency is the opposite direction: .github/workflows/smoke-antigravity.md:37 proves real usage of antigravity, while reference docs omit it.

Recommendations

1. Add antigravity to docs/src/content/docs/reference/engines.md engine lists and examples.
2. Stop rendering a full example section for deprecated safe-outputs.dispatch_repository; keep only a brief compatibility note pointing to dispatch-repository.
3. Decide whether nested dispatch keys should remain snake_case only; if not, add kebab-case aliases in parser and schema.
4. If schema must retain deprecated aliases, ensure generated reference docs visually demote them compared with canonical keys.

Strategy Performance

• Strategy Used: Engine catalog + deprecated safe-output alias targeted verification
• Findings: 4
• Effectiveness: HIGH
• Should Reuse: YES

Next Steps

• Fix engine reference docs to include antigravity
• Reduce deprecated alias prominence in frontmatter-full output
• Decide on snake_case vs kebab-case normalization for dispatch-repository nested keys
• Re-run schema/doc generation checks after updates

Generated by ✅ Schema Consistency Checker · gpt54 · 12.9 AIC · ⌖ 6.5 AIC · ⊞ 7.6K · ◷

• expires on Jul 28, 2026, 10:17 PM UTC-08:00