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

[github-actions[bot]]

Overview

• Inconsistencies Found: 4
• Categories Analyzed: Schema, Parser, Documentation, Workflows
• Strategy Used: Cross-surface engine/docs and deprecated alias drift spot check v2
• New Strategy: YES

Key Issues

1. Runtime engine catalog exceeds documented built-ins

   • pkg/workflow/engine_definition.go documents built-in engines as claude, codex, copilot, gemini, opencode, pi, antigravity.
   • docs/src/content/docs/reference/engines.md lists Copilot, Claude, Codex, Gemini, OpenCode, and Pi, but omits antigravity entirely.
   • Real generated workflows reference .antigravity agent folders and firewall model groups containing antigravity, confirming live runtime support.
   • Impact: users can rely on a supported engine that the main engine reference does not mention.

2. Deprecated dispatch_repository alias is still prominently surfaced in generated docs

   • Parser accepts both safe-outputs.dispatch-repository and deprecated safe-outputs.dispatch_repository, but warns to rename the underscore form in pkg/workflow/dispatch_repository.go.
   • docs/src/content/docs/reference/frontmatter-full.md still contains a dedicated deprecated alias block for dispatch_repository, which makes the old form easy to copy forward.
   • Impact: users keep authoring deprecated config even though the compiler asks them to migrate.

3. Engine-related docs remain inconsistent across surfaces

   • frontmatter.md now mentions engine.driver and engine.extensions, but its main engine: summary still routes users to engines.md.
   • engines.md omits antigravity, so the doc set still disagrees on what engine capabilities and choices exist.

4. dispatch-repository nested naming remains a convention outlier

   • Parser fields use snake_case nested names like event_type and allowed_repositories in pkg/workflow/dispatch_repository.go.
   • Docs repeat those snake_case keys in safe-outputs.md and glossary entries, while sibling safe-output top-level keys predominantly use kebab-case.
   • Impact: parser/schema/docs agree on acceptance, but naming inconsistency increases author confusion.

Details and Recommendations

Schema Improvements Needed

1. Constrain engine built-in IDs more explicitly or generate docs from the runtime registry to avoid engine catalog drift.
2. Mark deprecated aliases more aggressively in generated schema/docs output so canonical keys are favored.
3. Consider documenting naming-convention exceptions for dispatch-repository nested fields, or add canonical kebab-case aliases if backward compatibility permits.

Parser Updates Required

1. No parser bug was confirmed in this run for antigravity; the issue is cross-surface drift.
2. pkg/workflow/dispatch_repository.go already warns on deprecated alias usage; the main needed follow-up is doc/schema surfacing, not parser behavior.

Workflow Violations

1. No source .github/workflows/*.md violation requiring edit was confirmed.
2. Real compiled workflows (*.lock.yml) clearly show active antigravity runtime support, reinforcing the documentation drift finding.

Recommendations

1. Add antigravity to docs/src/content/docs/reference/engines.md wherever built-in engine choices are enumerated.
2. In frontmatter-full.md, keep the deprecated alias only in a migration note and move canonical dispatch-repository examples first.
3. Decide whether dispatch-repository nested keys should stay snake_case permanently; if yes, call out that exception explicitly in schema descriptions and docs.
4. Add a regression test or doc-generation check that diffs the runtime engine catalog against engines.md.

Strategy Performance

• Strategy Used: Cross-surface engine/docs and deprecated alias drift spot check v2
• Findings: 4
• Effectiveness: HIGH
• Should Reuse: YES

Next Actions

• Fix engine reference docs for antigravity
• Reduce deprecated alias prominence in generated frontmatter docs
• Clarify or normalize dispatch-repository nested naming
• Add guardrails to prevent future runtime/docs drift

Generated by ✅ Schema Consistency Checker · gpt54 · 11.4 AIC · ⌖ 9.42 AIC · ⊞ 7.5K · ◷

• expires on Jul 27, 2026, 10:37 PM UTC-08:00

[github-actions[bot]]

This discussion was automatically closed because it expired on 2026-07-28T06:37:03.191Z.

Closed by Workflow