[Schema Consistency] 🔍 Schema Consistency Check - 2026-06-28

[github-actions[bot]]

Summary

• Inconsistencies Found: 4
• Categories Analyzed: Schema, Parser, Documentation, Workflows
• Strategy Used: Cross-doc schema drift using non-frontmatter references
• New Strategy: YES

Critical Issues

1. engine.extensions is implemented and documented, but absent from the schema-generated reference

   • Parser/compiler reads engine.extensions in pkg/workflow/engine.go.
   • Specialized docs document it in docs/src/content/docs/reference/engines.md and docs/src/content/docs/reference/glossary.md.
   • docs/src/content/docs/reference/frontmatter-full.md has no engine.extensions entry because $defs.engine_config in pkg/parser/schemas/main_workflow_schema.json omits that property.

2. dispatch-repository alias is accepted by the parser but not declared in schema/docs

   • pkg/workflow/dispatch_repository.go accepts both dispatch_repository and dispatch-repository.
   • Schema/docs only declare dispatch_repository.

3. Engine catalog exposed in schema/docs is stale versus runtime support

   • Schema engine_config descriptions list built-in IDs as claude, codex, copilot, gemini, opencode, crush, pi.
   • Runtime supports antigravity (pkg/workflow/antigravity_engine.go).
   • Real workflow usage exists in .github/workflows/smoke-antigravity.md with engine.id: antigravity.

Documentation Gaps

• Generated frontmatter-full.md includes copilot-sdk-driver and dispatch_repository, but not engine.extensions.
• Top-level docs/src/content/docs/reference/frontmatter.md defers engine details to /reference/engines/, which masks drift in the generated schema reference.

Schema Improvements Needed

1. Add extensions to $defs.engine_config in pkg/parser/schemas/main_workflow_schema.json.
2. Decide whether dispatch-repository should be schema-documented or parser-removed.
3. Update engine ID descriptions/examples so antigravity is represented consistently.
4. Prefer explicit enum/generated catalog coverage for engine IDs over descriptive free text.

Parser Updates Required

• If underscore-only naming is intended, remove the undocumented dispatch-repository alias from pkg/workflow/dispatch_repository.go.
• Otherwise keep parser behavior and update schema/docs to match.

Workflow Violations

• .github/workflows/smoke-antigravity.md uses a runtime-supported engine that is not surfaced in schema engine descriptions/examples or generated frontmatter reference.

Recommendations

1. Fix schema for engine.extensions.
2. Align dispatch_repository naming across parser, schema, and docs.
3. Regenerate frontmatter-full.md after schema fixes.
4. Add regression tests diffing parser-read engine keys against schema-declared keys.
5. Add regression tests comparing runtime engine registry IDs against schema/docs examples.

Strategy Performance

• Strategy Used: Cross-doc schema drift using non-frontmatter references
• Findings: 4
• Effectiveness: HIGH
• Should Reuse: YES

Next Steps

• Fix schema definitions for engine.extensions
• Resolve dispatch_repository vs dispatch-repository alias policy
• Update engine ID descriptions/examples to include runtime-supported engines
• Regenerate generated reference docs and re-audit engine section consistency

Evidence

• pkg/workflow/engine.go: reads engineObj["extensions"].
• docs/src/content/docs/reference/engines.md: documents ### Pi Extensions (extensions).
• docs/src/content/docs/reference/frontmatter-full.md: no engine.extensions entry; has copilot-sdk-driver.
• pkg/workflow/dispatch_repository.go: accepts both spellings.
• .github/workflows/smoke-antigravity.md: uses engine.id: antigravity.

References:

• §28314125086

Generated by ✅ Schema Consistency Checker · 61.2 AIC · ⌖ 9.98 AIC · ⊞ 7.3K · ◷

• expires on Jun 28, 2026, 10:49 PM UTC-08:00