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

[github-actions[bot]]

🔍 Schema Consistency Check - 2026-07-30

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 omit a runtime-supported built-in engine (antigravity)

   • Runtime/catalog code explicitly lists antigravity as built-in in pkg/workflow/engine_definition.go:18 and pkg/workflow/engine_definition.go:285.
   • Real workflow usage exists in .github/workflows/smoke-antigravity.md:37 (id: antigravity).
   • But the main schema still describes built-ins as only claude, codex, copilot, gemini, opencode, pi in $defs.engine_config.oneOf[1].properties.id.description, and antigravity does not appear anywhere in pkg/parser/schemas/main_workflow_schema.json.
   • Impact: schema-guided tooling and users get a false negative picture of supported engines.

2. Schema is looser than runtime for engine.id

   • In the schema, engine.id is a plain string with no enum in both engine config branches.
   • Runtime resolution rejects unknown engine IDs via the engine catalog/registry.
   • Impact: invalid values can pass schema validation and only fail later at compile/runtime, producing avoidable delayed errors.

Documentation Gaps

1. docs/src/content/docs/reference/engines.md still has no Antigravity engine coverage

   • The docs cover driver support and Pi extensions (for example around engines.md:353 and engines.md:453), but there is no Antigravity section even though runtime code, tests, and a repository workflow support it.
   • Impact: users cannot discover or correctly configure a shipped engine from the primary engine reference.

2. Deprecated alias safe-outputs.dispatch_repository is still surfaced in generated reference docs

   • Parser warns that safe-outputs.dispatch_repository is deprecated and should be renamed to dispatch-repository in pkg/workflow/dispatch_repository.go:36-41.
   • Yet docs/src/content/docs/reference/frontmatter-full.md:9099-9122 still documents dispatch_repository: as a full reference block, not just a migration note.
   • Impact: documentation encourages continued use of a deprecated spelling.

Schema Improvements Needed

1. Tighten engine.id constraints

   • Add antigravity to built-in engine descriptions/examples immediately.
   • Consider an explicit enum (or a generated enum for built-ins plus documented custom-engine escape hatch) so schema validation matches runtime behavior more closely.

2. Reduce naming drift in dispatch-repository nested keys

   • Schema currently defines nested keys only as snake_case: event_type and allowed_repositories under safe-outputs.dispatch-repository.
   • This is called out directly in docs at frontmatter-full.md:9018-9020.
   • Impact: the top-level surface is predominantly kebab-case, but this subtree switches style unexpectedly.

Parser Updates Required

1. Unify deprecated-name messaging around dispatch repository
   • Parser canonical key is dispatch-repository, but several validator/handler/test surfaces still emit underscore-form names such as:
     • pkg/workflow/compiler_validators.go:399
     • pkg/workflow/safe_outputs_max_validation.go:314
     • tests asserting underscore-form error text in pkg/workflow/safe_outputs_max_validation_test.go:111
   • Impact: users see mixed canonical/deprecated names depending on which validation path they hit.

Workflow Violations

• No clear invalid workflow frontmatter was confirmed in this run.
• Instead, the workflow corpus demonstrates the opposite inconsistency: .github/workflows/smoke-antigravity.md legitimately uses engine.id: antigravity, proving runtime/workflow support that the schema/docs still under-document.

Recommendations

1. Update main_workflow_schema.json engine descriptions/examples to include antigravity wherever built-in engine IDs are enumerated.
2. Decide whether engine.id should gain a stronger schema constraint (enum/pattern/oneOf`) to catch unknown built-ins earlier.
3. Change frontmatter-full.md so dispatch_repository appears only as a deprecated alias note, with dispatch-repository as the sole primary example.
4. Standardize user-facing validation/error text on dispatch-repository while keeping the underscore alias accepted for backward compatibility.
5. Consider whether dispatch-repository nested keys should grow kebab-case aliases (or at minimum a stronger migration note) to match the rest of the frontmatter style.

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 built-in IDs
• Update parser/user-facing validation messages for dispatch-repository naming
• Update engine reference docs to cover Antigravity
• Demote deprecated dispatch_repository docs to migration-only guidance

Generated by ✅ Schema Consistency Checker · gpt54 · 20 AIC · ⌖ 7.04 AIC · ⊞ 8.2K · ◷

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

[github-actions[bot]]

This discussion was automatically closed because it expired on 2026-07-31T06:17:31.486Z.

Closed by Workflow