[Schema Consistency] Schema Consistency Check - 2026-08-01

[github-actions[bot]]

🔍 Schema Consistency Check - 2026-08-01

Summary

• Inconsistencies Found: 4
• Categories Analyzed: Schema, Parser, Documentation, Workflows
• Strategy Used: Engine catalog + safe-output naming drift verification v2
• New Strategy: NO

Critical Issues

1. Antigravity is runtime-supported and used by a real workflow, but key schema/docs surfaces omit it.

   • Runtime/code: pkg/workflow/engine_definition.go:18 and :285 list built-in engines including antigravity.
   • Real workflow: .github/workflows/smoke-antigravity.md:37 uses engine.id: antigravity.
   • Schema/docs drift:
     • pkg/parser/schemas/main_workflow_schema.json describes engine built-ins as claude, codex, copilot, gemini, opencode, pi but omits antigravity in both engine_config string and id descriptions.
     • docs/src/content/docs/reference/engines.md:13-22 omits Antigravity from the "Available Coding Agents" table.
   • Impact: valid runtime/workflow configuration looks undocumented or invalid to users and downstream tooling.

2. Schema is laxer than runtime for built-in engine IDs.

   • pkg/parser/schemas/main_workflow_schema.json uses plain type: string for engine.id / engine string forms and only mentions built-ins in descriptions.
   • Runtime resolves against a registered catalog and rejects unknown engines.
   • Impact: typos pass schema validation and fail later at compile/runtime; the omission is especially visible for antigravity because the descriptions are also stale.

Documentation Gaps

1. frontmatter-full.md still prominently documents deprecated safe-outputs.dispatch_repository.

   • Docs: docs/src/content/docs/reference/frontmatter-full.md:9133 includes a full deprecated alias block.
   • Parser: pkg/workflow/dispatch_repository.go:37-42 accepts it only as a backward-compatible alias and logs: rename to dispatch-repository or run gh aw fix.
   • Impact: generated reference keeps steering authors toward a deprecated key.

2. engines.md omits Antigravity despite dedicated runtime support files.

   • Runtime support is visible across pkg/workflow/antigravity_installer.go, pkg/workflow/antigravity_tools.go, and engine catalog registration.
   • docs/src/content/docs/reference/engines.md still lists only Copilot, Claude, Codex, Gemini, OpenCode, and Pi.
   • Impact: feature discovery/documentation is incomplete.

Schema Improvements Needed

1. Add antigravity to engine built-in lists/descriptions across all engine schema branches.

   • Affected spots include engine_config string description, engine.id description, and runtime.id examples in pkg/parser/schemas/main_workflow_schema.json.

2. Consider constraining built-in engine IDs with an explicit enum/oneOf branch.

   • Today the schema describes a fixed set but does not enforce it.
   • If named catalog entries must remain allowed, use a pattern/oneOf approach rather than a description-only contract.

3. Normalize dispatch-repository nested field naming.

   • Canonical parent key is kebab-case (dispatch-repository) but required nested keys remain snake_case (event_type, allowed_repositories) in schema, docs, and parser.
   • This mixed convention is explicitly called out in schema/docs and increases authoring mistakes.

Parser Updates Required

1. Reduce mixed-surface naming drift for dispatch repository diagnostics.
   • pkg/workflow/dispatch_repository_validation.go errors and examples still use underscore-form labels like dispatch_repository / allowed_repositories even though the canonical top-level key is dispatch-repository.
   • Consider emitting canonical-key examples while still mentioning accepted deprecated aliases where needed.

Workflow Violations

• No invalid workflow usage confirmed in sampled repo workflows.
• Instead, .github/workflows/smoke-antigravity.md demonstrates that repo workflows already depend on a capability (antigravity) that some schema/docs surfaces still omit.

Recommendations

1. Update main_workflow_schema.json engine descriptions/examples to include antigravity everywhere runtime supports it.
2. Add stronger schema validation for engine IDs so schema and compiler fail at the same layer.
3. Remove or sharply de-emphasize the full dispatch_repository block from frontmatter-full.md; keep only a short deprecated note pointing to dispatch-repository.
4. Decide on a single naming convention for dispatch-repository nested keys and align schema, parser messages, and docs.
5. Add a doc/reference test that diffs runtime built-in engine IDs against schema descriptions and engines.md tables.

Strategy Performance

• Strategy Used: Engine catalog + safe-output naming drift verification v2
• Findings: 4
• Effectiveness: HIGH
• Should Reuse: YES

Next Steps

• Fix schema engine built-in descriptions/examples
• Tighten schema validation for engine IDs
• Update engines.md to list Antigravity
• De-emphasize deprecated dispatch_repository docs
• Align dispatch-repository nested naming across schema/docs/parser

Generated by ✅ Schema Consistency Checker · gpt54 · 16.5 AIC · ⌖ 5.93 AIC · ⊞ 8.2K · ◷

• expires on Aug 1, 2026, 10:20 PM UTC-08:00

[github-actions[bot]]

This discussion was automatically closed because it expired on 2026-08-02T06:20:32.966Z.

Closed by Workflow