[Schema Consistency] Schema Consistency Check - 2026-07-31

[github-actions[bot]]

🔍 Schema Consistency Check - 2026-07-31

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 is looser than runtime validation and omits a real built-in engine

   • Schema: pkg/parser/schemas/main_workflow_schema.json:12672 defines engine.id as an unconstrained string.
   • Runtime: pkg/workflow/engine_definition.go:18 and pkg/workflow/engine_definition.go:285 list built-ins including antigravity.
   • Real workflow: .github/workflows/smoke-antigravity.md:37 uses id: antigravity.
   • Impact: schema validation cannot catch typos early, and generated docs/examples understate the supported engine catalog.

2. Engine reference docs omit the runtime-supported antigravity engine

   • docs/src/content/docs/reference/engines.md lists Copilot/Claude/Codex/Gemini/OpenCode/Pi in the engine table but has no antigravity section or mention.
   • Runtime and workflow evidence above confirm antigravity is supported in practice.
   • Impact: users cannot discover a supported engine from docs alone.

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

   • Parser accepts both keys, but warns on underscore form: pkg/workflow/dispatch_repository.go:36-41.
   • Docs still include a full deprecated alias block at docs/src/content/docs/reference/frontmatter-full.md:9117 onward.
   • Schema also carries the deprecated alias at pkg/parser/schemas/main_workflow_schema.json:9733.
   • Impact: generated docs continue teaching a name the parser explicitly asks users to rename.

Documentation Gaps

1. Mixed naming conventions in dispatch-repository nested keys
   • Schema uses event_type and allowed_repositories: pkg/parser/schemas/main_workflow_schema.json:9635-9729.
   • Parser also reads only those snake_case nested keys: pkg/workflow/dispatch_repository.go:73-88.
   • Generated docs repeat that caveat: docs/src/content/docs/reference/frontmatter-full.md:9036-9062.
   • Impact: this safe-output subtree diverges from the surrounding kebab-case frontmatter surface and increases authoring mistakes.

Schema Improvements Needed

1. Add an explicit enum or generated catalog-backed validation surface for engine.id, or at minimum keep schema descriptions/examples synchronized with the runtime engine catalog.
2. If dispatch_repository must remain for compatibility, reduce its visibility in generated docs and mark it as migration-only.
3. Consider adding kebab-case aliases for nested dispatch-repository keys (event-type, allowed-repositories) or documenting the exception more prominently in the concise docs.

Parser Updates Required

1. The parser/runtime currently supports antigravity, but the schema/docs surface does not advertise it consistently.
2. The parser warning on dispatch_repository is correct; the docs/schema generation should align with that canonicalization policy.

Workflow Violations

• No invalid workflow usage confirmed in the sampled check.
• Instead, .github/workflows/smoke-antigravity.md demonstrates a valid runtime feature (engine.id: antigravity) that documentation does not reflect.

Recommendations

1. Update the engine schema descriptions/examples and docs/reference/engines.md to include antigravity anywhere built-in engines are enumerated.
2. Hide or collapse the deprecated dispatch_repository alias from frontmatter-full.md examples so dispatch-repository is the only prominently shown form.
3. Decide whether dispatch-repository nested snake_case keys are intentional long-term API design; if not, add kebab-case aliases before the surface spreads further.
4. Add a regression test that compares runtime engine IDs against schema/docs enumerations or generated examples.

Strategy Performance

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

Next Steps

• Fix schema descriptions/examples for built-in engines
• Update engine reference docs to include antigravity
• Reduce deprecated alias prominence in generated docs
• Decide and document long-term naming policy for dispatch-repository nested keys

References:

• §30609542721

Generated by ✅ Schema Consistency Checker · gpt54 · 12.3 AIC · ⌖ 8.56 AIC · ⊞ 8.2K · ◷

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

[github-actions[bot]]

This discussion has been marked as outdated by Schema Consistency Checker.

A newer discussion is available at Discussion #49484.