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

[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/workflows but omitted from user-facing engine docs and schema examples

   • Runtime comments explicitly list antigravity as a built-in engine 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 (id: antigravity).
   • But docs/src/content/docs/reference/engines.md:16-21 lists only Copilot, Claude, Codex, Gemini, OpenCode, and Pi.
   • The schema's engine object examples/descriptions also omit antigravity; see pkg/parser/schemas/main_workflow_schema.json:12540-12550 area, where built-in IDs/examples mention codex, claude, copilot, gemini, opencode, and pi only.
   • Impact: valid workflows appear undocumented; schema examples steer users away from a supported engine.

2. Top-level frontmatter docs still omit engine.extensions

   • Schema defines engine.extensions at pkg/parser/schemas/main_workflow_schema.json:12503.
   • Runtime implements it in pkg/workflow/pi_engine.go:211 and pkg/workflow/pi_engine.go:240 by emitting pi install <extension> steps.
   • Specialized docs describe it in docs/src/content/docs/reference/engines.md:435-447.
   • But the top-level reference page documents engine.driver in docs/src/content/docs/reference/frontmatter.md:151-161 and has no corresponding engine.extensions section nearby.
   • Impact: the concise frontmatter reference under-documents a supported field that users can discover only in deeper docs.

Documentation Gaps

1. Deprecated alias still surfaced in generated full reference

   • Parser accepts safe-outputs.dispatch_repository only as a compatibility alias and warns to rename it in pkg/workflow/dispatch_repository.go:36-41.
   • Yet docs/src/content/docs/reference/frontmatter-full.md:8464-8468 still includes the deprecated alias as a documented key:

     dispatch_repository: {}

   • Impact: users may keep authoring deprecated config that the parser already warns against.

2. dispatch-repository nested keys remain snake_case among kebab-case peers

   • Parser requires event_type and allowed_repositories in pkg/workflow/dispatch_repository.go:14-16 and pkg/workflow/dispatch_repository.go:73-82.
   • Schema documents the same snake_case keys and even calls out the inconsistency at pkg/parser/schemas/main_workflow_schema.json:9535-9560.
   • Full docs repeat that note at docs/src/content/docs/reference/frontmatter-full.md:8383-8409.
   • Impact: this is internally consistent today, but cross-surface naming differs from the broader kebab-case frontmatter style, making mistakes likely and making the API feel irregular.

Schema Improvements Needed

1. Add antigravity anywhere built-in engine IDs are enumerated in schema descriptions/examples for engine.
2. Consider constraining built-in engine IDs more explicitly instead of relying on descriptions/examples only.
3. Decide whether dispatch-repository nested keys should gain kebab-case aliases for consistency (event-type, allowed-repositories) or whether the docs should more aggressively flag the exception.

Parser Updates Required

1. If snake_case nested dispatch keys are kept, consider parser support for kebab-case aliases to match surrounding frontmatter conventions.
2. If deprecated dispatch_repository should be phased out soon, reduce its doc visibility or add stronger deprecation messaging in generated docs.

Workflow Violations

• No confirmed invalid workflow frontmatter was found in the sampled workflows.
• Instead, the strongest workflow-based finding is the opposite: .github/workflows/smoke-antigravity.md:37 proves real-world use of antigravity, which conflicts with current user-facing engine lists.

Recommendations

1. Update docs/src/content/docs/reference/engines.md to list antigravity alongside the other built-in engines.
2. Update schema descriptions/examples for engine.id / runtime IDs to include antigravity.
3. Add a short engine.extensions section to docs/src/content/docs/reference/frontmatter.md, parallel to engine.driver.
4. Remove or visually demote dispatch_repository from frontmatter-full.md so canonical dispatch-repository is the default authoring path.
5. Decide on a long-term naming policy for dispatch-repository nested keys and either add aliases or keep a prominent exception note.

Strategy Performance

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

Next Steps

• Fix schema built-in engine examples/descriptions
• Update engine reference docs
• Add engine.extensions to the concise frontmatter reference
• Reduce deprecated alias visibility in generated docs
• Decide on dispatch nested-key naming consistency

Verification notes

• Precomputed schema-diff.json was used as the starting point.
• Selection mode was proven strategy (day_mod=1).
• Follow-up verification was limited to targeted reads/greps across:
  • pkg/workflow/engine_definition.go
  • pkg/workflow/pi_engine.go
  • pkg/workflow/dispatch_repository.go
  • pkg/parser/schemas/main_workflow_schema.json
  • docs/src/content/docs/reference/frontmatter.md
  • docs/src/content/docs/reference/frontmatter-full.md
  • docs/src/content/docs/reference/engines.md
  • .github/workflows/smoke-antigravity.md

References:

• §29721657077

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 · 16.7 AIC · ⌖ 6.67 AIC · ⊞ 7.3K · ◷

• expires on Jul 20, 2026, 10:30 PM UTC-08:00

[github-actions[bot]]

This discussion was automatically closed because it expired on 2026-07-21T06:30:38.473Z.

Closed by Workflow

[github-actions[bot]]

Smoke test 29812420778 says hello.

📰 BREAKING: Report filed by Smoke Copilot · 55.5 AIC · ⌖ 5.71 AIC · ⊞ 19.3K · ◷
_{Comment /smoke-copilot to run again
Add label smoke to run again}