[Schema Consistency] 🔍 Schema Consistency Check - 2026-07-10

[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: NO

Critical Issues

1. antigravity is implemented but omitted from user-facing engine docs/schema examples

   • Runtime support exists in pkg/workflow/antigravity_engine.go, pkg/workflow/engine_catalog_test.go, and pkg/workflow/README.md.
   • However docs/src/content/docs/reference/engines.md omits antigravity from the Available Coding Agents table, and the schema text search shows no antigravity mention in pkg/parser/schemas/main_workflow_schema.json.
   • Impact: valid workflow configurations can appear unsupported to users, and schema/docs examples lag runtime reality.

2. Built-in engine catalog comments are stale

   • pkg/workflow/engine_definition.go header comments and NewEngineCatalog comments say built-ins are claude, codex, copilot, gemini, opencode, crush.
   • Runtime tests and registration include pi and antigravity as built-ins (pkg/workflow/engine_catalog_test.go, pkg/workflow/README.md).
   • Impact: maintainers reading code comments get an incorrect authoritative list.

3. dispatch-repository nested keys still use snake_case in parser/schema/docs despite kebab-case conventions elsewhere

   • Parser canonical parent key is dashed: safe-outputs.dispatch-repository in pkg/workflow/dispatch_repository.go:36-41, with underscore alias only for backward compatibility.
   • Yet nested fields remain event_type and allowed_repositories in parser (pkg/workflow/dispatch_repository.go) and frontmatter-full.md examples (dispatch-repository: section around lines 8315-8336).
   • Impact: naming is inconsistent within the same feature and increases user error risk when switching between canonical dashed keys elsewhere in frontmatter.

Documentation Gaps

1. Top-level Frontmatter guide is missing implemented engine subfeatures

   • pkg/workflow/engine.go parses engine.token-weights and engine.extensions.
   • docs/src/content/docs/reference/frontmatter-full.md documents both (token-weights around line 2427; extensions exists in schema and runtime), but docs/src/content/docs/reference/frontmatter.md does not mention either in the engine: summary section.
   • Impact: users reading the shorter frontmatter reference miss supported engine capabilities.

2. Deprecated alias remains prominently documented

   • frontmatter-full.md documents both dispatch-repository: and deprecated dispatch_repository: blocks.
   • Parser logs a warning that dispatch_repository is deprecated and users should rename it or run gh aw fix (pkg/workflow/dispatch_repository.go:41).
   • Impact: docs continue to normalize deprecated syntax instead of steering users to the canonical form.

Schema Improvements Needed

1. Add explicit antigravity mentions/examples to engine schema descriptions if it is a supported built-in engine.
2. Consider whether dispatch-repository nested fields should gain kebab-case aliases (event-type, allowed-repositories) or whether docs should explicitly call out the snake_case exception.
3. Ensure summary docs track schema-supported engine.extensions and engine.token-weights.

Parser Updates Required

1. If naming cleanup is desired, add backward-compatible kebab-case aliases for event-type and allowed-repositories in pkg/workflow/dispatch_repository.go.
2. Update stale built-in engine comments in pkg/workflow/engine_definition.go so code comments match registration/tests.

Workflow Violations

• No high-confidence invalid workflow usage was required to establish drift this run.
• Repository workflows are not the main source of the findings above; the stronger drifts are runtime-vs-docs and schema/docs naming inconsistencies.

Recommendations

1. Update docs/src/content/docs/reference/engines.md to include antigravity wherever built-in engines are enumerated.
2. Fix stale built-in engine comments in pkg/workflow/engine_definition.go.
3. In frontmatter-full.md, demote or clearly mark dispatch_repository as deprecated and prefer dispatch-repository.
4. Decide on a canonical naming policy for nested dispatch-repository fields and align parser/schema/docs accordingly.
5. Add engine.extensions and engine.token-weights to docs/src/content/docs/reference/frontmatter.md summary coverage.

Strategy Performance

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

Next Steps

• Fix schema descriptions/examples for built-in engine coverage
• Update parser/runtime comments for built-in engines
• Update documentation for canonical dispatch-repository naming
• Expand summary frontmatter docs for implemented engine subfeatures

References:

• pkg/workflow/engine_definition.go
• docs/src/content/docs/reference/engines.md
• pkg/workflow/dispatch_repository.go
• docs/src/content/docs/reference/frontmatter.md
• docs/src/content/docs/reference/frontmatter-full.md

Generated by ✅ Schema Consistency Checker · 11.4 AIC · ⌖ 14.4 AIC · ⊞ 5.8K · ◷

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

[github-actions[bot]]

This discussion was automatically closed because it expired on 2026-07-11T06:36:55.483Z.

Closed by Workflow