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

[github-actions[bot]]

Summary

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

Critical Issues

1. Antigravity is implemented and used, but omitted from the engines reference list

   • Runtime/catalog comments include antigravity: pkg/workflow/engine_definition.go:18
   • Real workflow uses it: .github/workflows/smoke-antigravity.md:37
   • But docs/src/content/docs/reference/engines.md available-engine table lists Pi at line 21 and has no Antigravity entry.
   • Impact: users consulting the main engine reference may conclude engine: antigravity is unsupported even though it works.

2. Top-level frontmatter docs omit engine.extensions, but runtime and engine docs support it

   • Runtime installs Pi extensions from engine.extensions: pkg/workflow/pi_engine.go:211,240-251
   • Detailed engine docs document it: docs/src/content/docs/reference/engines.md:435-447
   • Top-level frontmatter reference documents engine.driver (docs/src/content/docs/reference/frontmatter.md:154) but does not mention engine.extensions.
   • Impact: the quick reference is incomplete for a real supported frontmatter key, especially for Pi users.

3. frontmatter-full.md still surfaces deprecated safe-outputs.dispatch_repository alias

   • Canonical key is dispatch-repository in schema: pkg/parser/schemas/main_workflow_schema.json:9533
   • Deprecated alias remains documented in full reference: docs/src/content/docs/reference/frontmatter-full.md:8468
   • Parser warns to rename the underscore form: pkg/workflow/dispatch_repository.go:41
   • Impact: generated docs encourage a deprecated spelling that the parser immediately warns about, increasing churn and avoidable warnings.

Documentation Gaps

• docs/src/content/docs/reference/engines.md should add Antigravity to the “Available Coding Agents” table.
• docs/src/content/docs/reference/frontmatter.md should add a short engine.extensions subsection or explicitly link to the Pi-specific extension support in engines docs.
• docs/src/content/docs/reference/frontmatter-full.md should demote or clearly mark dispatch_repository as deprecated instead of surfacing it like a normal peer key.

Schema Improvements Needed

• The schema currently preserves both dispatch-repository and dispatch_repository, which is fine for compatibility, but the alias should be explicitly marked deprecated in surfaced docs the same way parser behavior already does.
• Consider tightening engine-id surfacing so generated docs and schema-derived examples stay aligned with the actual runtime engine catalog, including Antigravity.

Parser Updates Required

• No parser bug was required to explain these findings; parser/runtime behavior appears intentional.
• The main parser/docs inconsistency is the deprecation warning for dispatch_repository without equivalent prominence in the generated full reference.

Workflow Violations

• No invalid workflow usage found in the sampled area.
• Instead, workflow reality exposed a docs gap: .github/workflows/smoke-antigravity.md is valid evidence that Antigravity is a real supported engine.

Recommendations

1. Add an Antigravity row to docs/src/content/docs/reference/engines.md.
2. Add engine.extensions to docs/src/content/docs/reference/frontmatter.md near engine.driver.
3. Mark dispatch_repository as deprecated in frontmatter-full.md or hide it from primary examples in favor of dispatch-repository.
4. Add a regression check that compares runtime engine catalog entries against the engines reference table.

Strategy Performance

• Strategy Used: Cross-surface antigravity/docs alias drift spot check
• Findings: 3
• Effectiveness: HIGH
• Should Reuse: YES

Next Steps

• Fix engines reference list
• Update top-level frontmatter docs
• Reduce deprecated alias surfacing in full reference
• Add doc/runtime consistency guard for engine catalog

Generated by ✅ Schema Consistency Checker · 22.3 AIC · ⌖ 9.54 AIC · ⊞ 7.3K · ◷

• expires on Jul 19, 2026, 10:21 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 #46731.