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

[github-actions[bot]]

Summary

• Inconsistencies Found: 4
• Categories Analyzed: Schema, Parser, Documentation, Workflows
• Strategy Used: Cross-surface engine catalog + docs/alias drift verification
• New Strategy: No

Critical Issues

1. Runtime-supported antigravity engine is missing from the main engine docs

   • Runtime/compiler: pkg/workflow/engine_definition.go states built-ins include antigravity; runtime files such as pkg/workflow/antigravity_installer.go and tests also reference it.
   • Real workflow usage: .github/workflows/smoke-antigravity.md uses engine.id: antigravity.
   • Docs mismatch: docs/src/content/docs/reference/engines.md lists Copilot, Claude, Codex, Gemini, OpenCode, and Pi, but not antigravity.
   • Impact: Users can successfully use a supported engine that the canonical engine reference does not advertise, making the docs incomplete and misleading.

2. frontmatter-full.md still prominently surfaces the deprecated safe-outputs.dispatch_repository alias

   • Parser/compiler behavior: pkg/workflow/dispatch_repository.go treats dispatch-repository as canonical and logs a deprecation warning when dispatch_repository is used.
   • Schema: pkg/parser/schemas/main_workflow_schema.json includes both keys and labels dispatch_repository as a deprecated alias.
   • Docs mismatch: docs/src/content/docs/reference/frontmatter-full.md:9101 still renders a full top-level example block for dispatch_repository, directly after the canonical block.
   • Impact: Generated reference docs still encourage a deprecated spelling even though the parser explicitly warns against it.

Documentation Gaps

1. Engine catalog drift between docs and implementation

   • docs/src/content/docs/reference/engines.md omits antigravity, while code and workflows support it.
   • This is a schema ↔ docs ↔ workflows inconsistency because real workflows rely on the runtime surface that the docs do not fully describe.

2. Naming-style inconsistency is documented rather than normalized

   • Canonical top-level key: safe-outputs.dispatch-repository uses kebab-case.
   • Nested keys: schema/parser/docs all use snake_case: event_type, allowed_repositories.
   • Evidence: pkg/workflow/dispatch_repository.go parses event_type and allowed_repositories; schema description at pkg/parser/schemas/main_workflow_schema.json:9559 explicitly notes the snake_case exception; docs in docs/src/content/docs/reference/frontmatter-full.md and docs/src/content/docs/reference/safe-outputs.md repeat it.
   • Impact: This is internally consistent, but inconsistent with surrounding safe-output naming conventions; it is a recurring usability/documentation footgun.

Schema Improvements Needed

1. Reduce deprecated alias visibility in generated reference output

   • Keep dispatch_repository accepted in schema for compatibility, but demote it in generated docs to a short deprecated note instead of a full example block.

2. Clarify engine catalog source of truth

   • The schema/docs surface should be generated or validated against the runtime engine catalog so supported built-ins such as antigravity cannot fall out of documentation.

Parser Updates Required

1. Mixed canonical/deprecated naming still leaks through validation and internal labels
   • Validation/error surfaces continue to use underscore-form names such as dispatch_repository in files like pkg/workflow/dispatch_repository_validation.go, pkg/workflow/safe_outputs_max_validation.go, and pkg/workflow/compiler_validators.go.
   • The parser also emits a warning telling users to rename to dispatch-repository.
   • Impact: Users see canonical dashed names in some places and deprecated underscore names in others, which makes diagnostics harder to follow.

Workflow Violations

• No clear invalid workflow frontmatter usage was confirmed in sampled repository workflows.
• Instead, the main workflow finding is documentation lag behind actual valid workflow usage: .github/workflows/smoke-antigravity.md uses a supported engine not documented in engines.md.

Recommendations

1. Add antigravity to docs/src/content/docs/reference/engines.md and any engine summary tables generated from the same source.
2. Change frontmatter-full.md generation so deprecated aliases like dispatch_repository appear only in a compact deprecated note, not as a peer example to the canonical key.
3. Standardize user-facing validation/error strings on dispatch-repository, optionally mentioning dispatch_repository only as a deprecated alias.
4. Consider adding a consistency test that diffs the documented engine list against the built-in engine catalog in pkg/workflow/engine_definition.go.
5. Consider whether dispatch-repository nested snake_case keys should gain kebab-case aliases for long-term consistency, or at minimum add stronger migration notes in docs.

Strategy Performance

• Strategy Used: Cross-surface engine catalog + docs/alias drift verification
• Findings: 4
• Effectiveness: HIGH
• Should Reuse: YES

Next Steps

• Fix engine reference docs to include all supported built-ins
• Reduce deprecated alias prominence in generated frontmatter reference docs
• Normalize validation/error messaging around dispatch-repository
• Add regression tests for doc/runtime engine catalog parity

Evidence

• pkg/workflow/engine_definition.go — built-in engine list includes antigravity
• .github/workflows/smoke-antigravity.md — real workflow usage of engine.id: antigravity
• docs/src/content/docs/reference/engines.md — engine list omits antigravity
• pkg/workflow/dispatch_repository.go — canonical key is dispatch-repository, underscore alias is deprecated
• docs/src/content/docs/reference/frontmatter-full.md:9101 — deprecated dispatch_repository still fully rendered
• pkg/parser/schemas/main_workflow_schema.json:9559 — nested snake_case exception explicitly documented

References:

• §30427575616

Generated by ✅ Schema Consistency Checker · gpt54 · 11.6 AIC · ⌖ 9.53 AIC · ⊞ 7.6K · ◷

• expires on Jul 29, 2026, 10:20 PM UTC-08:00

[github-actions[bot]]

This discussion was automatically closed because it expired on 2026-07-30T06:20:22.923Z.

Closed by Workflow