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

[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. Runtime-supported antigravity engine is missing from user-facing engine docs

   • Runtime/catalog comments explicitly list antigravity as built-in in pkg/workflow/engine_definition.go:18 and pkg/workflow/engine_definition.go:285.
   • Real workflow usage exists in .github/workflows/smoke-antigravity.md:37.
   • But docs/src/content/docs/reference/engines.md does not mention antigravity in the available engine list.
   • Impact: users can successfully use an engine that the main engine reference implies does not exist.

2. Schema engine descriptions/examples lag runtime for built-in engine catalog

   • pkg/parser/schemas/main_workflow_schema.json contains no antigravity mention, even though runtime/workflows support it.
   • The schema’s inline engine runtime examples list only codex, claude, copilot, gemini, opencode, pi near runtime.id and do not reflect the full catalog.
   • Impact: schema-generated docs/examples understate supported values, and schema guidance is looser/less accurate than compiler reality.

3. Top-level frontmatter reference still omits engine.extensions

   • Schema supports engine.extensions in pkg/parser/schemas/main_workflow_schema.json:12517.
   • Runtime support is implemented in pkg/workflow/pi_engine.go:211 and pkg/workflow/pi_engine.go:240.
   • Specialized engine docs document it in docs/src/content/docs/reference/engines.md:435-447.
   • But the main reference docs/src/content/docs/reference/frontmatter.md has an engine.driver section and no engine.extensions section.
   • Impact: users reading the canonical frontmatter overview can miss a supported field entirely.

Documentation Gaps

1. Deprecated alias is still surfaced prominently in generated full reference

   • Parser accepts both keys but warns that underscore form is deprecated in pkg/workflow/dispatch_repository.go:36-41.
   • docs/src/content/docs/reference/frontmatter-full.md:8464-8468 still includes dispatch_repository as a visible reference block.
   • Impact: users may copy the deprecated spelling from docs and trigger warnings unnecessarily.

2. dispatch-repository nested keys remain snake_case-only in docs/schema/parser

   • The generated full reference explicitly notes nested keys use event_type and allowed_repositories at docs/src/content/docs/reference/frontmatter-full.md:8393-8411.
   • This is inconsistent with the broader kebab-case frontmatter surface.
   • Impact: avoidable naming inconsistency increases cognitive load and typo risk.

Schema Improvements Needed

1. Add antigravity anywhere the schema describes or exemplifies built-in engine IDs.
2. Consider constraining built-in engine IDs more explicitly instead of relying on descriptive prose only.
3. If backward compatibility requires dispatch_repository, keep it in schema but mark it more strongly as deprecated in generated docs/examples.

Parser Updates Required

1. No parser bug was confirmed for the checked areas.
2. Parser behavior and runtime support currently appear ahead of the docs/schema in these cases.

Workflow Violations

1. No invalid workflow usage was confirmed in sampled workflows.
2. Instead, actual workflows demonstrate valid features missing from docs, notably .github/workflows/smoke-antigravity.md.

Recommendations

1. Update docs/src/content/docs/reference/engines.md to add antigravity to the available engine table and related built-in engine descriptions.
2. Update pkg/parser/schemas/main_workflow_schema.json engine descriptions/examples so built-in engine guidance includes antigravity.
3. Add an engine.extensions section to docs/src/content/docs/reference/frontmatter.md, linking to the Pi engine details.
4. Demote dispatch_repository in generated docs so the canonical example uses only dispatch-repository.
5. Decide whether dispatch-repository nested fields should retain snake_case long-term; if yes, call it out consistently in all safe-output docs; if no, add kebab-case aliases and document migration.

Strategy Performance

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

Next Steps

• Fix schema engine descriptions/examples
• Update engine reference docs
• Update top-level frontmatter docs
• Reduce deprecated alias visibility in generated docs

References:

• §29896064996

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 · gpt54 10.4 AIC · ⌖ 8.5 AIC · ⊞ 7.4K · ◷

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

[github-actions[bot]]

This discussion was automatically closed because it expired on 2026-07-23T06:17:38.765Z.

Closed by Workflow