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

[github-actions[bot]]

🔍 Schema Consistency Check - 2026-07-15

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. Runtime-supported antigravity engine is missing from schema-facing built-in engine descriptions

   • Runtime/catalog registers antigravity as built-in in pkg/workflow/engine_definition.go:18 and pkg/workflow/engine_catalog_test.go:24.
   • Real workflow usage exists in .github/workflows/smoke-antigravity.md:36-37.
   • But docs/src/content/docs/reference/engines.md:14-21 omits antigravity from the available engine table.
   • The schema’s engine_config built-in engine description also omits antigravity (the serialized schema branch lists only claude, codex, copilot, gemini, opencode, pi).
   • Impact: schema/docs under-advertise a supported engine, so valid workflows can appear invalid or undiscoverable.

2. Documentation still surfaces deprecated safe-outputs.dispatch_repository alias alongside canonical dispatch-repository

   • Parser treats dispatch-repository as canonical and only keeps underscore form as backward-compatible alias in pkg/workflow/dispatch_repository.go:36-41, with a warning to rename.
   • docs/src/content/docs/reference/frontmatter-full.md:8464-8466 still documents dispatch_repository: as a full parallel section, not just a migration note.
   • Impact: users are encouraged to author deprecated config that runtime warns about.

Documentation Gaps

1. engines.md omits antigravity from the top-level engine catalog

   • docs/src/content/docs/reference/engines.md:14-21 lists Copilot, Claude, Codex, Gemini, OpenCode, and Pi only.
   • Runtime supports antigravity in pkg/workflow/antigravity_engine.go:22 and catalog comments in pkg/workflow/engine_definition.go:18.

2. Dispatch-repository docs preserve snake_case nested keys without clearly separating canonical vs legacy naming

   • docs/src/content/docs/reference/frontmatter-full.md:8398-8409 documents nested event_type and allowed_repositories under the canonical dashed parent key.
   • The same page also presents full deprecated dispatch_repository: examples at 8464-8466.
   • Impact: naming conventions across safe outputs remain inconsistent and easy to cargo-cult incorrectly.

Schema Improvements Needed

1. Add antigravity to built-in engine descriptions/examples in pkg/parser/schemas/main_workflow_schema.json

   • The engine_config definition includes driver and extensions, but its built-in engine description text is stale.
   • Suggested fix: update engine / $defs.engine_config descriptions and examples so built-in IDs match runtime catalog: claude, codex, copilot, gemini, opencode, pi, antigravity.

2. Consider reducing deprecated alias prominence in generated schema docs

   • Schema currently exposes both dispatch-repository and deprecated dispatch_repository properties, which is technically compatible but doc-generation makes the alias look first-class.
   • Suggested fix: keep alias in schema for compatibility, but mark it more strongly as deprecated in generator output or remove full example blocks for it from generated reference docs.

Parser Updates Required

1. No parser bug confirmed for engine.driver / engine.extensions

   • Spot-check confirmed parser handles both in pkg/workflow/engine.go:445-558.
   • This run’s actionable parser/doc drift is instead around deprecation messaging and engine catalog alignment.

2. Consider making deprecation handling stronger for dispatch_repository

   • Current behavior only logs a warning in pkg/workflow/dispatch_repository.go:41.
   • Optional improvement: emit a compile warning surfaced to users more prominently, matching docs cleanup.

Workflow Violations

1. No invalid workflow usage confirmed in sampled repo workflows
   • .github/workflows/smoke-antigravity.md:36-37 uses engine.id: antigravity, which is accepted by runtime but under-documented by schema/docs.
   • This is a workflow-valid / docs-schema-stale case rather than a workflow violation.

Recommendations

1. Update docs/src/content/docs/reference/engines.md to list antigravity wherever built-in engines are enumerated.
2. Update pkg/parser/schemas/main_workflow_schema.json built-in engine descriptions/examples to include antigravity.
3. Reduce dispatch_repository visibility in frontmatter-full.md so dispatch-repository is clearly canonical and underscore form is migration-only.
4. Add a regression check that diffs runtime engine IDs against schema/docs engine enumerations.

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 descriptions/examples
• Update engine reference docs
• Demote deprecated dispatch alias in generated docs
• Add regression coverage for runtime-vs-doc engine catalog drift

Evidence

• pkg/workflow/engine_definition.go:18 — built-in engines include antigravity.
• pkg/workflow/antigravity_engine.go:22 — runtime engine registration for antigravity.
• .github/workflows/smoke-antigravity.md:36-37 — real workflow uses engine.id: antigravity.
• docs/src/content/docs/reference/engines.md:14-21 — available engines table omits antigravity.
• pkg/workflow/dispatch_repository.go:36-41 — dashed key canonical; underscore alias deprecated with warning.
• docs/src/content/docs/reference/frontmatter-full.md:8388-8459 — canonical dispatch-repository block.
• docs/src/content/docs/reference/frontmatter-full.md:8464-8466 — deprecated dispatch_repository still shown as full section.

Generated by ✅ Schema Consistency Checker · 18 AIC · ⌖ 5.88 AIC · ⊞ 5.8K · ◷

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

[github-actions[bot]]

This discussion was automatically closed because it expired on 2026-07-16T06:11:27.057Z.

Closed by Workflow