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

[github-actions[bot]]

Summary

• Inconsistencies Found: 4
• 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 schema-facing engine catalogs

   • Runtime/docs evidence: pkg/workflow/README.md lists antigravity as an engine; .github/workflows/smoke-antigravity.md:36-37 uses engine.id: antigravity.
   • Schema drift: pkg/parser/schemas/main_workflow_schema.json:11920, :11928, and :12193 still describe built-in engine IDs/examples as claude, codex, copilot, gemini, opencode, crush, pi only.
   • Impact: schema-guided tooling and generated docs under-advertise a valid runtime, so users can be told a supported engine is invalid or unavailable.

2. Docs still advertise engine.copilot-sdk-driver, while parser/schema canonicalize to engine.driver

   • Docs: docs/src/content/docs/reference/engines.md:325-336, :380; docs/src/content/docs/reference/frontmatter-full.md:2323-2329; glossary also references engine.copilot-sdk-driver.
   • Implementation: parser reads engineObj["driver"] in pkg/workflow/engine.go:408-412; validation comments in pkg/workflow/engine_validation.go:115-117 say engine.copilot-sdk-driver is only a backward-compatible alias.
   • Schema: engine object exposes driver, not copilot-sdk-driver, in pkg/parser/schemas/main_workflow_schema.json:12161-12167.
   • Impact: a user following docs may author a key that is legacy/alias-only, while schema-based validation and docs disagree on the preferred contract.

3. Generated frontmatter reference still surfaces deprecated safe-outputs.dispatch_repository instead of canonical dispatch-repository

   • Docs: docs/src/content/docs/reference/frontmatter-full.md:7493-7498 shows dispatch_repository: as the visible example.
   • Schema: pkg/parser/schemas/main_workflow_schema.json:9346-9446 defines canonical dispatch-repository and marks dispatch_repository as a deprecated alias.
   • Parser: pkg/workflow/dispatch_repository.go:36-41 prefers dispatch-repository and warns when underscore form is used.
   • Impact: documentation nudges authors toward a deprecated spelling that the compiler warns about.

Documentation Gaps

1. engine.extensions is implemented and documented in specialized docs, but underrepresented in generated frontmatter reference examples
   • Parser reads engineObj["extensions"] in pkg/workflow/engine.go:509-529.
   • Schema defines extensions in engine config at pkg/parser/schemas/main_workflow_schema.json:12168-12174.
   • Specialized docs explain it in docs/src/content/docs/reference/engines.md:428-440.
   • But nearby generated frontmatter examples around the named engine format focus on copilot-sdk-driver and do not surface extensions, reducing discoverability for Pi users.

Schema Improvements Needed

1. Update engine ID descriptions/examples in main_workflow_schema.json so built-in engine catalogs match runtime reality, including antigravity.
2. Decide on one public key for custom Copilot drivers:
   • either document engine.driver everywhere and mark copilot-sdk-driver clearly as deprecated alias, or
   • add explicit alias handling in schema/docs generation if the legacy key must remain first-class.
3. Ensure generated frontmatter reference prefers canonical safe-output keys over deprecated aliases.

Parser Updates Required

1. If engine.copilot-sdk-driver remains supported, make alias handling discoverable in user-facing docs/error text instead of leaving it mostly in validation comments.
2. Consider emitting a stronger migration hint when deprecated dispatch_repository appears, since docs currently reinforce the deprecated form.

Workflow Violations

• No repository workflows were found using deprecated dispatch_repository; this is currently a docs/schema presentation drift rather than an in-repo usage violation.
• .github/workflows/smoke-antigravity.md is valid runtime usage that exposes the engine catalog drift described above.

Recommendations

1. Regenerate or patch frontmatter reference output so deprecated aliases are not the primary examples.
2. Align all engine driver docs on engine.driver as the canonical field, with engine.copilot-sdk-driver clearly labeled deprecated/compat-only if retained.
3. Add antigravity to schema descriptions/examples for engine IDs wherever built-in engines are enumerated.
4. Add at least one frontmatter reference example showing engine.extensions for the Pi engine.

Strategy Performance

• Strategy Used: Engine sub-object key coverage (engineObj vs engine_config branches)
• Findings: 4
• Effectiveness: HIGH
• Should Reuse: YES

Next Steps

• Fix schema engine ID descriptions/examples
• Update engine driver documentation to the canonical key
• Regenerate frontmatter reference examples for canonical safe-output names
• Improve frontmatter reference coverage for engine.extensions

References:

• §28570249641

Generated by ✅ Schema Consistency Checker · 16.4 AIC · ⌖ 21.3 AIC · ⊞ 7.4K · ◷

• expires on Jul 2, 2026, 10:36 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 #43136.