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

[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: YES

Critical Issues

1. Runtime/workflow support engine: antigravity, but reference docs omit it from the available engine list.

   • Workflow usage: .github/workflows/smoke-antigravity.md:37 uses id: antigravity.
   • Runtime/catalog comments: pkg/workflow/engine_definition.go:18 and :285 list built-in engines including antigravity.
   • Docs gap: docs/src/content/docs/reference/engines.md:16-21 lists Copilot, Claude, Codex, Gemini, OpenCode, and Pi, but no Antigravity row.
   • Impact: users consulting the main engine reference can conclude Antigravity is unsupported even though the compiler/runtime and first-party workflow usage support it.

2. Top-level frontmatter reference documents engine.driver but omits engine.extensions.

   • Present in top-level docs: docs/src/content/docs/reference/frontmatter.md:154-160 documents engine.driver.
   • Missing there: no engine.extensions section in frontmatter.md.
   • Documented elsewhere: docs/src/content/docs/reference/engines.md:437 documents Pi engine.extensions.
   • Impact: the concise frontmatter reference is incomplete for engine subfields, so users relying on it miss a supported frontmatter field.

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

   • Canonical key in schema: pkg/parser/schemas/main_workflow_schema.json:9521 defines dispatch-repository.
   • Deprecated alias retained in schema: pkg/parser/schemas/main_workflow_schema.json:9621-9623 defines dispatch_repository as a deprecated alias.
   • Parser warning: pkg/workflow/dispatch_repository.go:36-41 accepts the alias but logs safe-outputs.dispatch_repository is deprecated; rename to dispatch-repository.
   • Docs still show alias block: docs/src/content/docs/reference/frontmatter-full.md:8464-8468.
   • Impact: generated docs continue to encourage a deprecated spelling, increasing drift and delaying migrations to the canonical kebab-case key.

Documentation Gaps

• docs/src/content/docs/reference/engines.md should include Antigravity in the available engines table or explicitly mark it unsupported if that is the intent.
• docs/src/content/docs/reference/frontmatter.md should add an engine.extensions subsection or link to it from the engine summary section.
• docs/src/content/docs/reference/frontmatter-full.md should demote or remove the deprecated alias example so the canonical key is the only prominent example.

Schema Improvements Needed

• No blocking schema parser mismatch was required to prove the issues above, but the schema currently preserves both dispatch-repository and deprecated dispatch_repository. Consider whether the deprecated alias should remain accepted indefinitely or be hidden from generated reference output.

Parser Updates Required

• No parser behavior bug found in this pass. Parser behavior and runtime support were consistent with the confirmed findings.

Workflow Violations

• No invalid workflow usage found for the confirmed issues. Instead, real workflow usage (smoke-antigravity.md) demonstrates that the documentation is lagging behind supported behavior.

Recommendations

1. Add an Antigravity row to docs/src/content/docs/reference/engines.md with its engine ID, status, and auth requirements.
2. Add engine.extensions to docs/src/content/docs/reference/frontmatter.md near engine.driver, with a short Pi-specific note and link to the engines reference.
3. Update the docs generator or source doc content so deprecated aliases like dispatch_repository are not shown as normal examples in frontmatter-full.md.
4. Optionally annotate deprecated alias fields in generated docs as hidden/collapsed to reduce copy-paste drift.

Strategy Performance

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

Next Steps

• Fix engine reference docs to include Antigravity
• Update frontmatter reference coverage for engine.extensions
• Reduce deprecated alias prominence in full frontmatter docs

References:

• §29633317082

Generated by ✅ Schema Consistency Checker · 8.22 AIC · ⌖ 6.11 AIC · ⊞ 7.3K · ◷

• expires on Jul 18, 2026, 10:09 PM UTC-08:00

[github-actions[bot]]

This discussion was automatically closed because it expired on 2026-07-19T06:09:50.664Z.

Closed by Workflow