[Schema Consistency] Schema consistency check - 2026-07-23

[github-actions[bot]]

🔍 Schema Consistency Check - 2026-07-23

Summary

• Inconsistencies Found: 4
• Categories Analyzed: Schema, Parser, Documentation, Workflows
• Strategy Used: Cross-surface antigravity/docs alias drift spot check
• New Strategy: No

Critical Issues

1. Runtime/workflow support for antigravity is missing from user-facing engine docs

   • Runtime supports antigravity in pkg/workflow/antigravity_engine.go:24.
   • Real workflow usage exists in .github/workflows/smoke-antigravity.md:37 (id: antigravity).
   • But docs/src/content/docs/reference/engines.md available-engine table does not list Antigravity.
   • Impact: valid production configuration appears undocumented.

2. Schema/docs engine catalog drift around built-in engine IDs

   • pkg/workflow/engine_definition.go says built-in engines include ... pi, antigravity.
   • pkg/parser/schemas/main_workflow_schema.json documents engine.extensions, but its surrounding built-in engine descriptions/examples still lag the runtime catalog and do not surface Antigravity where users would expect built-in engine coverage.
   • Impact: schema-guided tooling and generated docs under-describe supported engine IDs.

Documentation Gaps

1. frontmatter.md omits engine.extensions

   • Supported in schema: pkg/parser/schemas/main_workflow_schema.json:12528.
   • Documented in engines reference: docs/src/content/docs/reference/engines.md:442.
   • Missing from top-level frontmatter reference: docs/src/content/docs/reference/frontmatter.md has engine.driver but no matching engine.extensions entry.
   • Impact: users consulting the main frontmatter reference will miss a real engine field.

2. frontmatter-full.md still surfaces deprecated dispatch_repository

   • Schema still includes the alias at pkg/parser/schemas/main_workflow_schema.json:9658-9660.
   • Parser comment says underscore alias remains supported via parsing compatibility: pkg/workflow/safe_outputs_config_types.go:82 and extraction comment pkg/workflow/safe_outputs_config_extraction.go:303.
   • But docs/src/content/docs/reference/frontmatter-full.md:8464-8468 still gives the deprecated alias its own visible section immediately after the canonical dispatch-repository block.
   • Impact: generated docs continue to encourage a deprecated spelling instead of gently hiding it.

Schema Improvements Needed

1. Make built-in engine support easier to validate mechanically

   • Current schema uses descriptions/examples rather than a stricter engine ID catalog for the common built-in engine path.
   • Consider adding an enum or generated catalog fragment for built-in IDs where practical, or ensuring generated descriptions/examples stay synchronized with runtime registration.

2. Consider de-emphasizing deprecated alias docs in generated schema output

   • dispatch_repository remains valid for compatibility, but the current generated full reference makes it highly visible.
   • Consider marking it as deprecated more aggressively in generated docs or moving deprecated aliases to a dedicated compatibility appendix.

Parser Updates Required

No parser/runtime breakage was found in this pass; the main drift is schema/docs surfacing rather than implementation correctness.

Workflow Violations

No invalid workflow usage found in sampled workflows.

However, workflows demonstrate support that docs understate:

• .github/workflows/smoke-antigravity.md:37 uses engine.id: antigravity successfully as a first-class workflow example.

Recommendations

1. Add Antigravity to docs/src/content/docs/reference/engines.md available-engine tables and related examples.
2. Update schema-generated descriptions/examples for built-in engine coverage so Antigravity is surfaced consistently with runtime support.
3. Add an engine.extensions subsection to docs/src/content/docs/reference/frontmatter.md near engine.driver / engine.
4. Reduce prominence of deprecated dispatch_repository in frontmatter-full.md while keeping compatibility noted.

Strategy Performance

• Strategy Used: Cross-surface antigravity/docs alias drift spot check
• Findings: 4
• Effectiveness: High
• Should Reuse: Yes

Next Steps

• Fix engine reference docs to include Antigravity
• Update schema/doc generation for built-in engine catalog examples
• Add engine.extensions to the concise frontmatter reference
• Move or de-emphasize deprecated alias documentation for dispatch_repository

References:

• §29984534346

Generated by ✅ Schema Consistency Checker · gpt54 18.9 AIC · ⌖ 6.32 AIC · ⊞ 7.4K · ◷

• expires on Jul 23, 2026, 10:22 PM UTC-08:00

[github-actions[bot]]

This discussion was automatically closed because it expired on 2026-07-24T06:22:28.050Z.

Closed by Workflow