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

[github-actions[bot]]

Summary

• Inconsistencies Found: 4
• Categories Analyzed: Schema, Parser, Documentation, Workflows
• Strategy Used: Cross-surface naming and engine-catalog drift spot check
• New Strategy: YES

Critical Issues

1. safe-outputs.dispatch-repository nested keys are documented/schema-exposed in snake_case, while adjacent safe-output surfaces are kebab-case-heavy

   • Schema defines event_type and allowed_repositories under dispatch-repository in pkg/parser/schemas/main_workflow_schema.json:9450-9467.
   • Parser also only reads those snake_case keys in pkg/workflow/dispatch_repository.go:73-88.
   • This is inconsistent with the canonical outer key rename to dispatch-repository and with nearby safe-output fields like allowed-repos, which makes authoring error-prone.
   • Impact: users can reasonably write event-type / allowed-repos and fail validation/runtime despite surrounding docs favoring kebab-case.

2. frontmatter-full under-documents dispatch-repository

   • The generated reference only shows dispatch-repository: {} at docs/src/content/docs/reference/frontmatter-full.md:7494-7499; it does not expand the nested object shape there.
   • Meanwhile schema/parser require specific nested keys (workflow, event_type, optionally repository, allowed_repositories, inputs, max, etc.).
   • Impact: the canonical docs do not give users enough information to write a valid config without consulting schema internals.

3. engine.driver schema/docs are narrower than the implementation and specialized docs

   • Main schema says engine.driver is for engines “(e.g. pi)” and only allows workspace-relative path syntax matching filenames/bare basenames, with description limited to .js/.cjs/.mjs (main_workflow_schema.json:12415-12420).
   • frontmatter-full repeats the same Pi-oriented, JS-only description at docs/src/content/docs/reference/frontmatter-full.md:2323-2329.
   • Runtime implementation supports much more for Copilot: .js, .cjs, .mjs, .py, .ts, .mts, .rb, or a bare command name (pkg/workflow/engine.go:61, parsing at pkg/workflow/engine.go:437-441).
   • docs/src/content/docs/reference/engines.md:345-365,399 also documents Copilot SDK driver usage and TS examples.
   • Impact: schema validation/docs can reject or discourage configurations the runtime and engine docs explicitly support.

4. Runtime/workflows support antigravity, but engine reference docs still omit it

   • The repo ships an Antigravity engine implementation and embedded definition (pkg/workflow/antigravity_engine.go, pkg/workflow/data/engines/antigravity.md).
   • A real workflow uses engine: id: antigravity in .github/workflows/smoke-antigravity.md:1-34.
   • But docs/src/content/docs/reference/engines.md sections inspected around the engine catalog/driver guidance do not mention antigravity.
   • Also pkg/workflow/engine_definition.go still says built-ins are only claude, codex, copilot, gemini, opencode, crush in both top comments and NewEngineCatalog comment, omitting pi and antigravity.
   • Impact: users reading docs/comments get an outdated supported-engine set.

Documentation Gaps

• Expand dispatch-repository in frontmatter-full.md with its nested fields and examples, not just {}.
• Add explicit note on canonical naming for nested dispatch fields, or migrate them to kebab-case aliases consistently.
• Add antigravity to docs/reference/engines.md supported-engine listings/examples.

Schema Improvements Needed

1. Revisit dispatch-repository nested naming: either add kebab-case aliases (event-type, allowed-repos) or clearly document snake_case as intentional.
2. Broaden engine.driver schema description/pattern/examples so they match Copilot SDK support and non-JS drivers.
3. Consider stronger schema/example coverage for runtime-supported engine IDs such as antigravity.

Parser Updates Required

1. If kebab-case is meant to be canonical everywhere, pkg/workflow/dispatch_repository.go should accept aliases for event-type / allowed-repos.
2. Update stale built-in engine comments in pkg/workflow/engine_definition.go to match the actual catalog.

Workflow Violations

• No invalid dispatch-repository usage was found in checked workflow files.
• .github/workflows/smoke-antigravity.md demonstrates that antigravity is a real supported engine, which increases the severity of the docs drift.

Recommendations

1. Make dispatch-repository naming internally consistent: canonical kebab-case or fully documented snake_case, but not a mixed surface.
2. Regenerate/update frontmatter docs so dispatch-repository shows the real object schema and example.
3. Align engine.driver schema text and validation with the runtime’s Copilot SDK driver support.
4. Update engine reference docs and code comments to include antigravity (and pi where omitted).

Strategy Performance

• Strategy Used: Cross-surface naming and engine-catalog drift spot check
• Findings: 4
• Effectiveness: HIGH
• Should Reuse: YES

Next Steps

• Fix dispatch-repository naming/docs drift
• Update engine.driver schema/docs
• Update engine catalog docs/comments for antigravity and pi
• Re-run schema/doc generation checks after fixes

References:

• §28921700394

Generated by ✅ Schema Consistency Checker · 9.21 AIC · ⌖ 9.48 AIC · ⊞ 7.3K · ◷

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

[github-actions[bot]]

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

Closed by Workflow