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

[github-actions[bot]]

🔍 Schema Consistency Check - 2026-08-02

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. engine.id schema/docs lag runtime support for antigravity

   • Schema: pkg/parser/schemas/main_workflow_schema.json describes built-in engine IDs as claude, codex, copilot, gemini, opencode, pi.
   • Parser/compiler/runtime: pkg/workflow/engine_definition.go says built-in engines include antigravity.
   • Actual workflows: .github/workflows/smoke-antigravity.md uses engine.id: antigravity.
   • Impact: schema-driven tooling and docs understate a valid engine ID that is already used in-repo.

2. Schema is looser than runtime for engine.id

   • Schema: engine.id is just type: string with no enum/const constraint.
   • Runtime: engine catalog resolves a fixed built-in set plus named catalog entries and rejects unknown IDs.
   • Impact: typos can pass schema validation and fail later at compile/runtime, producing worse UX.

Documentation Gaps

1. docs/src/content/docs/reference/engines.md omits Antigravity from the available engine table

   • The table lists Copilot, Claude, Codex, Gemini, OpenCode, and Pi.
   • Runtime and repo workflows support antigravity.
   • Impact: users reading the engine reference will miss a supported engine.

2. frontmatter-full.md still surfaces deprecated safe-outputs.dispatch_repository

   • pkg/workflow/dispatch_repository.go treats dispatch-repository as canonical and logs a deprecation warning for dispatch_repository.
   • docs/src/content/docs/reference/frontmatter-full.md still emits a full deprecated alias block, not just a brief compatibility note.
   • Impact: users may keep copying the deprecated form, prolonging migration drift.

Schema Improvements Needed

1. Tighten engine.id validation:
   • add an enum for built-ins, or
   • use oneOf/pattern rules that distinguish built-ins from named catalog references.
2. Update engine.id description to include antigravity anywhere built-ins are enumerated.
3. Revisit safe-outputs.dispatch-repository nested naming consistency:
   • parent key is kebab-case,
   • nested required keys remain snake_case (event_type, allowed_repositories).
   • If intentional, document the exception more prominently; otherwise consider kebab-case aliases.

Parser Updates Required

1. Consider normalizing dispatch-repository nested keys with kebab-case aliases:
   • current parser reads event_type and allowed_repositories only.
   • this is inconsistent with surrounding safe-output surfaces that prefer kebab-case.
2. If alias support is not desired, keep parser as-is but reduce doc prominence of deprecated underscore aliases.

Workflow Violations

• No confirmed invalid workflow frontmatter was found in the sampled repo workflows.
• Instead, the repo demonstrates the opposite inconsistency: .github/workflows/smoke-antigravity.md uses a valid runtime feature (engine.id: antigravity) that is not fully reflected in schema/docs.

Recommendations

1. Update main_workflow_schema.json engine.id description and constraints to reflect antigravity.
2. Add Antigravity to docs/src/content/docs/reference/engines.md engine availability tables/examples.
3. Demote dispatch_repository in frontmatter-full.md to a short deprecated note instead of a full mirrored example block.
4. Decide whether dispatch-repository nested keys should stay snake_case; if yes, document the exception in the main safe-outputs docs with rationale.

Strategy Performance

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

Next Steps

• Fix schema definitions for engine.id
• Update engine reference docs to include Antigravity
• Reduce deprecated alias prominence in generated frontmatter docs
• Decide on long-term naming policy for dispatch-repository nested fields

Generated by ✅ Schema Consistency Checker · gpt54 · 21.1 AIC · ⌖ 6.63 AIC · ⊞ 8.2K · ◷

• expires on Aug 2, 2026, 10:22 PM UTC-08:00