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

[github-actions[bot]]

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. antigravity is supported in runtime and real workflows but omitted from schema-facing engine examples/lists and the main engines reference.

   • Runtime registers antigravity as built-in in pkg/workflow/engine_definition.go:18 and :285.
   • A real workflow uses it in .github/workflows/smoke-antigravity.md:37.
   • But the top-level engine schema examples in pkg/parser/schemas/main_workflow_schema.json:3863-3874 only show copilot and claude, and docs/src/content/docs/reference/engines.md has Pi examples (:441) but no antigravity coverage.
   • Impact: users can write valid workflows that appear undocumented or unsupported.

2. frontmatter.md documents engine.driver but still omits engine.extensions.

   • docs/src/content/docs/reference/frontmatter.md:146-161 covers engine and engine.driver.
   • docs/src/content/docs/reference/engines.md:435-447 documents engine.extensions.
   • docs/src/content/docs/reference/frontmatter-full.md:2478-2485 includes extensions, and runtime implements it in pkg/workflow/pi_engine.go:211, :240.
   • Impact: the concise frontmatter reference is incomplete for a shipped frontmatter key.

3. frontmatter-full.md still prominently publishes deprecated safe-outputs.dispatch_repository.

   • Full docs include the deprecated alias at docs/src/content/docs/reference/frontmatter-full.md:8464-8468.
   • Parser accepts it only as a backward-compatible alias and logs a warning in pkg/workflow/dispatch_repository.go:36-41.
   • Impact: users are nudged toward a spelling that the compiler itself asks them to rename.

Documentation Gaps

1. Dispatch repository nested keys remain snake_case-only in schema/docs/parser while neighboring safe-output surfaces are kebab-case.
   • Schema notes this explicitly at pkg/parser/schemas/main_workflow_schema.json:9533-9561.
   • Full docs repeat it at docs/src/content/docs/reference/frontmatter-full.md:8383-8409.
   • Parser struct tags require event_type / allowed_repositories in pkg/workflow/dispatch_repository.go:14-16.
   • Impact: this is easy to mistype because it breaks the dominant frontmatter naming convention.

Schema Improvements Needed

1. Expand the top-level engine examples/description in pkg/parser/schemas/main_workflow_schema.json to include all built-in IDs actually registered at runtime, including antigravity.
2. Consider surfacing canonical-key guidance more strongly for dispatch-repository, or eventually normalizing nested names to kebab-case with alias support if backward compatibility permits.

Parser Updates Required

1. No parser/runtime bug was found for antigravity or engine.extensions; the drift is primarily schema/docs-facing.
2. For dispatch_repository, the parser already warns correctly; the docs should stop surfacing the deprecated alias as a normal example.

Workflow Violations

1. No invalid workflow was confirmed in this pass. Instead, .github/workflows/smoke-antigravity.md:37 demonstrates a valid real-world configuration that documentation/schema examples underrepresent.

Recommendations

1. Update docs/src/content/docs/reference/engines.md to add an antigravity section or include it in the built-in engine catalog.
2. Update docs/src/content/docs/reference/frontmatter.md to add a short engine.extensions subsection alongside engine.driver.
3. Remove or demote the deprecated dispatch_repository alias from docs/src/content/docs/reference/frontmatter-full.md; keep only a short migration note.
4. Add a canonical example for dispatch-repository that calls out the snake_case nested keys as an exception, or add parser aliases for kebab-case nested keys if that is an intended long-term UX improvement.

Strategy Performance

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

Next Steps

• Fix schema engine examples/descriptions to reflect the full built-in engine catalog
• Update engines.md for antigravity
• Update frontmatter.md for engine.extensions
• Reduce deprecated alias visibility in frontmatter-full.md

References:

• §29806384829

Warning

Firewall blocked 1 domain

The following domain was blocked by the firewall during workflow execution:

• pi.dev

To allow these domains, add them to the network.allowed list in your workflow frontmatter:

network:
  allowed:
    - defaults
    - "pi.dev"

See Network Configuration for more information.

Generated by ✅ Schema Consistency Checker · 7.67 AIC · ⌖ 8.32 AIC · ⊞ 7.4K · ◷

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