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

[github-actions[bot]]

Summary

• Inconsistencies Found: 5
• Categories Analyzed: Schema, Parser, Documentation, Workflows
• Strategy Used: Engine sub-object key coverage (engineObj vs engine_config branches)
• New Strategy: No

Critical Issues

1. antigravity is implemented and used, but omitted from user-facing engine catalogs

   • Runtime/tests include antigravity as a supported engine: pkg/constants/spec_test.go:59, pkg/constants/constants_test.go:57, pkg/workflow/README.md:13.
   • A real workflow uses it: .github/workflows/smoke-antigravity.md:37.
   • But docs omit it from the main engine list: docs/src/content/docs/reference/engines.md:16-22.
   • Impact: valid workflows look undocumented, and users may assume the engine is unsupported.

2. Schema engine descriptions are looser and stale vs runtime support

   • Schema engine descriptions list built-ins as claude, codex, copilot, gemini, opencode, crush, pi: pkg/parser/schemas/main_workflow_schema.json:12149, :12157, :12434, :12556.
   • Runtime/tests additionally support antigravity: pkg/constants/spec_test.go:59, .github/workflows/smoke-antigravity.md:37.
   • Impact: schema-generated docs and completions advertise an incomplete engine set.

3. Top-level frontmatter docs under-document engine: capabilities

   • frontmatter.md reduces engine: to a single-line pointer: docs/src/content/docs/reference/frontmatter.md:146-148.
   • Yet engine.driver and engine.extensions are implemented/documented elsewhere: pkg/workflow/README.md:153-164, docs/src/content/docs/reference/engines.md:345-356, :429-436, and docs/src/content/docs/reference/frontmatter-full.md:2472-2482.
   • Impact: readers of the compact frontmatter reference miss important supported fields unless they already know to search deeper docs.

Documentation Gaps

1. engines.md omits antigravity completely despite runtime/workflow support.
2. frontmatter.md omits mention of advanced engine: subfields, especially driver and extensions, while fuller references document them.
3. frontmatter-full.md still publishes deprecated dispatch_repository as a full example block: docs/src/content/docs/reference/frontmatter-full.md:8362-8364. Parser treats it as deprecated and logs a rename warning: pkg/workflow/dispatch_repository.go:36-41.

Schema Improvements Needed

1. Update all engine built-in descriptions/examples in pkg/parser/schemas/main_workflow_schema.json to include antigravity wherever built-ins are enumerated in prose.
2. Consider adding tighter machine-readable validation for engine IDs when feasible; currently key built-in sets live only in descriptions, which is prone to drift.

Parser Updates Required

1. No parser/runtime bug was found for antigravity; the drift is mostly schema/docs.
2. Code comments in pkg/workflow/engine_definition.go:13-20 and :184-185 remain stale, listing built-ins as claude, codex, copilot, gemini, opencode, crush and omitting both pi and antigravity.
   • Impact: maintainers reading code comments get an inaccurate catalog summary.

Workflow Violations

1. No invalid workflow frontmatter was confirmed in sampled built-in workflows.
2. Instead, the repo contains the inverse inconsistency: .github/workflows/smoke-antigravity.md:37 uses a valid engine that the schema/docs under-advertise.

Recommendations

1. Add antigravity to docs/src/content/docs/reference/engines.md engine tables and examples where built-in engines are enumerated.
2. Normalize all built-in engine lists across schema descriptions, frontmatter-full.md, and code comments from one shared source if possible.
3. Expand docs/src/content/docs/reference/frontmatter.md so the engine: section explicitly links or briefly lists high-value subfields such as id, model, driver, extensions, env, and api-target.
4. Remove or strongly demote the deprecated dispatch_repository alias from frontmatter-full.md examples so canonical dispatch-repository is the only surfaced form.
5. Add a regression check that compares documented built-in engine names against runtime-supported engine IDs.

Strategy Performance

• Strategy Used: Engine sub-object key coverage (engineObj vs engine_config branches)
• Findings: 5
• Effectiveness: High
• Should Reuse: Yes

Next Steps

• Fix schema prose for built-in engine IDs
• Update engines.md to include antigravity
• Expand compact frontmatter.md coverage for engine: subfields
• Update stale built-in-engine comments in pkg/workflow/engine_definition.go
• Stop surfacing deprecated dispatch_repository in generated full-reference examples

Evidence

• Runtime/tests engine catalog includes antigravity and pi: pkg/constants/spec_test.go:59, pkg/constants/constants_test.go:57, pkg/workflow/README.md:13.
• Workflow usage: .github/workflows/smoke-antigravity.md:37.
• engines.md public engine list includes Copilot, Claude, Codex, Gemini, Crush, OpenCode, Pi — but not antigravity: docs/src/content/docs/reference/engines.md:16-22.
• Compact frontmatter engine section is minimal: docs/src/content/docs/reference/frontmatter.md:146-148.
• Advanced engine fields are documented elsewhere: docs/src/content/docs/reference/engines.md:345-356, :429-436; docs/src/content/docs/reference/frontmatter-full.md:2472-2482; pkg/workflow/README.md:153-164.
• Deprecated alias still documented: docs/src/content/docs/reference/frontmatter-full.md:8362-8364; parser deprecation warning: pkg/workflow/dispatch_repository.go:36-41.

References:

• §29310263796

Generated by ✅ Schema Consistency Checker · 20.2 AIC · ⌖ 6.35 AIC · ⊞ 7.3K · ◷

• expires on Jul 14, 2026, 10:11 PM UTC-08:00