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

[github-actions[bot]]

Summary

• 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

Critical Issues

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

   • Runtime/catalog comments list built-in engines including antigravity in pkg/workflow/engine_definition.go:18,285.
   • A real workflow uses it in .github/workflows/smoke-antigravity.md:37.
   • docs/src/content/docs/reference/engines.md lists Copilot, Claude, Codex, Gemini, OpenCode, and Pi, but no antigravity.
   • Impact: users can successfully use an engine that the primary engine reference does not advertise.

2. Top-level frontmatter docs omit engine.extensions

   • frontmatter.md has engine: and engine.driver: sections at docs/src/content/docs/reference/frontmatter.md:146,154, but no engine.extensions section.
   • The field is supported by schema at pkg/parser/schemas/main_workflow_schema.json:12474 and documented in the specialized engine reference at docs/src/content/docs/reference/engines.md:437-445.
   • Impact: the concise frontmatter reference is incomplete for a real supported field, especially for Pi workflows.

Documentation Gaps

1. dispatch_repository deprecated alias is still surfaced prominently in generated full docs

   • Parser accepts alias only for backward compatibility and emits a warning in pkg/workflow/dispatch_repository.go:36-41.
   • Schema also marks dispatch_repository as a deprecated alias at pkg/parser/schemas/main_workflow_schema.json:9621-9623.
   • But docs/src/content/docs/reference/frontmatter-full.md:8464-8468 still shows a standalone example block for dispatch_repository: {}.
   • Impact: generated docs still encourage a key the compiler actively asks users to rename.

2. dispatch-repository nested keys remain snake_case-only in an otherwise kebab-case surface

   • Schema/docs/parser all require event_type and allowed_repositories under safe-outputs.dispatch-repository (main_workflow_schema.json:9523-9548, frontmatter-full.md:8383-8409, pkg/workflow/dispatch_repository.go:14-16,73,82).
   • The parent feature uses kebab-case (dispatch-repository), making the nested naming convention inconsistent with nearby frontmatter and safe-output fields.
   • Impact: avoidable usability/documentation friction and higher typo risk (event-type, allowed-repositories look natural but are invalid).

Schema Improvements Needed

1. Consider constraining or at least clearly documenting built-in engine IDs in the schema/descriptions so runtime-supported IDs like antigravity are not omitted from user-facing references.
2. For safe-outputs.dispatch-repository, consider adding kebab-case aliases for nested keys (or fully standardizing on one convention) to reduce naming drift.
3. If deprecated aliases must remain in schema, annotate them more aggressively in generated docs so canonical keys are clearly preferred.

Parser Updates Required

1. No parser bug was confirmed in this run, but the deprecation warning path in dispatch_repository.go and the generated docs are out of sync; either reduce alias visibility in docs or plan eventual alias removal.
2. If nested kebab-case aliases are added, parser support would need to expand beyond event_type / allowed_repositories.

Workflow Violations

1. No invalid workflow field usage was confirmed from the repository sample checked.
2. Instead, .github/workflows/smoke-antigravity.md:37 demonstrates a supported engine (antigravity) whose support is not reflected in the primary engine docs.

Recommendations

1. Add antigravity to docs/src/content/docs/reference/engines.md wherever the built-in engine list/table appears.
2. Add an engine.extensions subsection to docs/src/content/docs/reference/frontmatter.md, linking to the Pi extensions details in engines.md.
3. Remove or demote the dispatch_repository example from frontmatter-full.md, keeping only the canonical dispatch-repository form plus a deprecation note.
4. Decide whether dispatch-repository nested keys should gain kebab-case aliases; if not, explicitly call out the exception in concise docs too, not only in the generated full reference.

Strategy Performance

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

Next Steps

• Fix engine reference docs to include all runtime-supported built-in engines
• Update concise frontmatter docs for engine.extensions
• Reduce deprecated alias visibility in generated docs
• Decide and document naming policy for dispatch-repository nested keys

References:

• §29559113506

Generated by ✅ Schema Consistency Checker · 14.6 AIC · ⌖ 9.06 AIC · ⊞ 7.3K · ◷

• expires on Jul 17, 2026, 10:14 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 #46352.