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

[github-actions[bot]]

Summary

• Inconsistencies Found: 4
• Categories Analyzed: Schema, Parser, Documentation, Workflows
• Strategy Used: Cross-doc schema drift using non-frontmatter references
• New Strategy: No

Critical Issues

1. antigravity engine is implemented and used, but omitted from the public engine catalog docs

   • Runtime implementation exists in pkg/workflow/antigravity_engine.go (id: "antigravity").
   • Real workflow usage exists in .github/workflows/smoke-antigravity.md (engine.id: antigravity).
   • But docs/src/content/docs/reference/engines.md available-engine table lists Copilot, Claude, Codex, Gemini, Crush, OpenCode, and Pi — not antigravity.
   • Impact: users reading the main engine reference will conclude the engine is unsupported even though the compiler/runtime already support it.

2. Built-in engine catalog comments in code are stale

   • pkg/workflow/engine_definition.go:18 says: claude, codex, copilot, gemini, opencode, crush.
   • pkg/workflow/engine_definition.go:180 repeats the same stale list.
   • But runtime now includes at least pi and antigravity as built-ins.
   • Impact: misleading maintenance signal for contributors; future schema/doc generation or reviews may anchor on incorrect comments.

Documentation Gaps

1. Top-level frontmatter reference omits engine.driver

   • pkg/parser/schemas/main_workflow_schema.json defines engine.driver with a detailed description.
   • Parser/runtime reads it in pkg/workflow/engine.go:432-436.
   • Specialized docs cover it in docs/src/content/docs/reference/engines.md:345-365 and generated examples in frontmatter-full.md:2471-2479.
   • But docs/src/content/docs/reference/frontmatter.md only gives a minimal engine: copilot section and does not mention driver.
   • Impact: users consulting the primary frontmatter reference miss a real supported field.

2. Top-level frontmatter reference omits engine.extensions

   • Schema defines engine.extensions and describes it as Pi plugin installation.
   • Parser/runtime reads it in pkg/workflow/engine.go:525-545.
   • docs/src/content/docs/reference/engines.md:427-439 documents Pi extensions and frontmatter-full.md:2482-2484 includes it.
   • But docs/src/content/docs/reference/frontmatter.md does not mention it in the engine: section.
   • Impact: incomplete top-level reference; users have to discover the field indirectly.

Schema Improvements Needed

1. Engine catalog descriptions/examples still appear looser or older than runtime reality

   • The schema contains engine.driver and engine.extensions, so the core structure is correct.
   • However, the runtime-supported built-in engine set has moved faster than the human-facing engine catalog docs.
   • Recommendation: ensure schema descriptions/examples for engine IDs are generated or audited against the runtime catalog to prevent more antigravity-style drift.

2. Deprecated alias still has high visibility

   • Schema includes both safe-outputs.dispatch-repository and deprecated alias dispatch_repository.
   • Parser warns in pkg/workflow/dispatch_repository.go:36-41 that dispatch_repository is deprecated and should be renamed.
   • But docs/src/content/docs/reference/frontmatter-full.md:8362-8364 still surfaces the deprecated alias as an example block immediately after the canonical key.
   • Impact: generated reference still nudges users toward the deprecated spelling.

Parser Updates Required

• No hard parser/schema break was confirmed in this run.
• The main parser-side inconsistency is messaging vs docs:
  • parser deprecates dispatch_repository
  • docs still prominently show it.
• Recommendation: either remove/reduce deprecated alias exposure in docs, or keep the parser warning but mark the alias much more aggressively in generated docs.

Workflow Violations

• No invalid workflow frontmatter was confirmed.
• Instead, workflows highlighted documentation drift:
  • .github/workflows/smoke-antigravity.md proves real-world antigravity usage that the public engine catalog page does not list.

Recommendations

1. Add antigravity to docs/src/content/docs/reference/engines.md available-engine table and any engine catalog summaries.
2. Update pkg/workflow/engine_definition.go comments so built-in engine lists match the real catalog (pi, antigravity, and any other currently registered built-ins).
3. Expand docs/src/content/docs/reference/frontmatter.md engine: section to mention or link to engine.driver and engine.extensions explicitly.
4. Demote or remove the deprecated dispatch_repository example from docs/src/content/docs/reference/frontmatter-full.md, leaving dispatch-repository as the clear canonical form.
5. Consider generating engine catalog lists from the runtime registry or shared metadata to reduce manual drift.

Strategy Performance

• Strategy Used: Cross-doc schema drift using non-frontmatter references
• Findings: 4
• Effectiveness: HIGH
• Should Reuse: YES

Next Steps

• Fix engine catalog docs to include antigravity
• Update stale built-in engine comments in Go code
• Update top-level frontmatter docs for engine.driver and engine.extensions
• Reduce deprecated dispatch_repository visibility in generated docs

Generated by ✅ Schema Consistency Checker · 14.8 AIC · ⌖ 10.5 AIC · ⊞ 7.3K · ◷

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

[github-actions[bot]]

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

Closed by Workflow