[Schema Consistency] Schema consistency check report - 2026-07-03

[github-actions[bot]]

🔍 Schema Consistency Check - 2026-07-03

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. Engine catalog drift: antigravity is implemented and used, but omitted from schema-facing built-in engine lists

   • Schema descriptions for engine and engine.id list built-ins as claude, codex, copilot, gemini, opencode, crush, pi only (pkg/parser/schemas/main_workflow_schema.json:11920, :11928).
   • Runtime/tests treat antigravity as a built-in engine (pkg/workflow/engine_catalog_test.go:24, pkg/workflow/engine_auth_test.go:400, pkg/workflow/engine_api_targets.go:232).
   • A real workflow uses it today (.github/workflows/smoke-antigravity.md:37).
   • Impact: users reading generated schema/docs get an incomplete engine catalog and may assume a supported engine is invalid.

2. Schema for engine.driver is narrower than parser/docs behavior

   • Schema says engine.driver accepts a string matching a path pattern and its description only mentions .js/.cjs/.mjs or a bare filename (pkg/parser/schemas/main_workflow_schema.json:12163-12166).
   • Parser validation allows broader forms for the copilot engine, including .py, .ts, .mts, .rb, and bare command names (pkg/workflow/engine_validation.go:171; tests at pkg/workflow/engine_validation_test.go:549-579).
   • Documentation advertises those broader driver forms (docs/src/content/docs/reference/engines.md:325-379).
   • Impact: valid documented configurations can fail schema validation or editor linting before they reach the compiler.

Documentation Gaps

1. frontmatter.md under-documents implemented engine fields

   • The main frontmatter guide only says engine: specifies which AI engine interprets the markdown and sends readers elsewhere (docs/src/content/docs/reference/frontmatter.md, AI Engine section).
   • Implemented/documented engine subfields such as engine.driver and engine.extensions are only discoverable in engines.md and the generated full reference.
   • Impact: the concise reference is incomplete for common engine customization paths.

2. Deprecated alias handling is implemented in parser but easy to miss in reference docs

   • Parser still accepts safe-outputs.dispatch_repository as a deprecated alias and logs a warning to rename it (pkg/workflow/dispatch_repository.go:36-41).
   • Schema keeps both keys, with the underscore form deprecated (pkg/parser/schemas/main_workflow_schema.json:9346, :9444-9446).
   • frontmatter-full.md currently surfaces the canonical dispatch-repository block (docs/src/content/docs/reference/frontmatter-full.md:7497), but the deprecation/alias behavior is not obvious in the higher-level docs.
   • Impact: users migrating older workflows may not realize underscore syntax still works but is deprecated.

Schema Improvements Needed

1. Add antigravity to every built-in engine list/description derived from schema, including engine string and engine.id object branches.
2. Reconcile engine.driver schema with runtime validation:
   • either broaden the schema to match per-engine accepted extensions/command names, or
   • narrow docs/parser behavior intentionally and document the restriction clearly.
3. Consider adding explicit alias/deprecation notes in top-level safe-outputs docs for dispatch_repository.

Parser Updates Required

1. If current runtime behavior is intended, expose the broader engine.driver acceptance in schema so editor validation matches compiler validation.
2. If dispatch_repository is nearing removal, consider surfacing a stronger user-facing deprecation path beyond log-only warning.

Workflow Violations

• No concrete first-party workflow violation was found in sampled files.
• Instead, a first-party workflow (.github/workflows/smoke-antigravity.md) demonstrates that docs/schema metadata lag runtime support.

Recommendations

1. Regenerate the engine schema descriptions/examples from the authoritative runtime engine registry to avoid built-in catalog drift.
2. Align engine.driver schema constraints with validateEngineDriver and its tests.
3. Expand frontmatter.md with a short advanced engine: subsection covering driver, extensions, and provider-specific caveats.
4. Add a deprecation note/example for safe-outputs.dispatch_repository in user-facing docs until the alias is removed.

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 built-in lists to include antigravity
• Align engine.driver schema with parser behavior
• Update frontmatter docs for advanced engine fields
• Clarify deprecated dispatch_repository alias behavior in docs

Generated by ✅ Schema Consistency Checker · 12.3 AIC · ⌖ 8.37 AIC · ⊞ 7.4K · ◷

• expires on Jul 3, 2026, 10:34 PM UTC-08:00

[github-actions[bot]]

This discussion was automatically closed because it expired on 2026-07-04T06:34:08.924Z.

Closed by Workflow