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

[github-actions[bot]]

Summary

• Inconsistencies Found: 4
• Categories Analyzed: Schema, Parser/Compiler, Documentation, Workflows
• Strategy Used: Cross-surface naming and engine-catalog drift spot check
• New Strategy: No

Critical Issues

1. engine.id built-in engine catalog is stale in schema/docs

   • Schema $defs.engine_config says built-ins are claude, codex, copilot, gemini, opencode, crush, pi.
   • Runtime/workflows also support antigravity (.github/workflows/smoke-antigravity.md uses engine.id: antigravity).
   • Impact: users can write a valid in-repo workflow that works at runtime but appears undocumented/invalid from schema-generated docs.

2. Built-in engine list in code comments lags implementation

   • pkg/workflow/engine_definition.go comments say built-ins are claude, codex, copilot, gemini, opencode, crush.
   • Runtime loader and workflows clearly include pi and antigravity.
   • Impact: maintainers reading code comments get a wrong mental model; future generated docs/tests can drift further.

Documentation Gaps

1. docs/reference/engines.md omits Antigravity entirely

   • Available-engine table includes Copilot/Claude/Codex/Gemini/Crush/OpenCode/Pi, but not antigravity.
   • Yet .github/workflows/smoke-antigravity.md is a first-party workflow proving runtime support.
   • Impact: feature appears unsupported even though the repo ships a smoke test for it.

2. dispatch-repository is canonical, but nested keys remain snake_case-only across schema/docs/parser

   • Canonical top-level key is kebab-case: dispatch-repository.
   • Nested keys are still snake_case in schema, parser, and docs: event_type, allowed_repositories.
   • This conflicts with the surrounding safe-output naming convention (allowed-repos, target-repo, github-token, etc.).
   • Impact: high typo risk and discoverability problems; users will naturally try allowed-repos / event-type and fail schema validation.

Schema Improvements Needed

1. Add antigravity wherever built-in engine IDs are enumerated/described

   • pkg/parser/schemas/main_workflow_schema.json $defs.engine_config.oneOf[1].properties.id.description
   • pkg/parser/schemas/main_workflow_schema.json $defs.engine_config.oneOf[3].properties.id.description
   • Any generated frontmatter docs derived from those descriptions.

2. Consider a naming-alias migration path for dispatch-repository nested fields

   • Current schema only accepts event_type and allowed_repositories.
   • Parser also only reads those spellings in pkg/workflow/dispatch_repository.go.
   • Recommendation: either document the exception much more prominently or add kebab-case aliases (event-type, allowed-repos) and deprecate snake_case over time.

Parser Updates Required

1. dispatch-repository parser only reads snake_case nested keys

   • pkg/workflow/dispatch_repository.go reads event_type and allowed_repositories only.
   • No kebab-case alias support exists for these nested keys, despite the parent object being canonicalized to dispatch-repository.

2. Deprecated alias remains prominently surfaced in generated docs

   • docs/reference/frontmatter-full.md still includes a full dispatch_repository: block immediately after the canonical dispatch-repository: block.
   • Impact: users may copy the deprecated spelling instead of the canonical one.

Workflow Violations

1. Real workflow uses runtime-supported engine missing from engine docs/schema descriptions
   • .github/workflows/smoke-antigravity.md uses:

     engine:
       id: antigravity

   • This validates the drift is not hypothetical; the repository itself depends on the undocumented engine ID.

Recommendations

1. Update schema engine-ID descriptions and generated docs to include antigravity everywhere built-in engines are listed.
2. Fix pkg/workflow/engine_definition.go comments to match the actual built-in engine catalog (pi and antigravity).
3. Decide on a long-term naming policy for dispatch-repository nested fields:
   • either support kebab-case aliases in parser/schema, or
   • clearly mark snake_case as a deliberate exception in safe-outputs.md and frontmatter docs.
4. Reduce prominence of deprecated dispatch_repository in generated docs (move to a short deprecation note instead of a full mirrored block).

Strategy Performance

• Strategy Used: Cross-surface naming and engine-catalog drift spot check
• Findings: 4
• Effectiveness: High
• Should Reuse: Yes

Next Steps

• Fix schema descriptions for built-in engine IDs
• Update engines.md available-engine table to include Antigravity
• Correct stale engine catalog comments in Go source
• Decide whether to add kebab-case aliases for dispatch-repository nested keys
• Trim deprecated alias exposure in generated frontmatter docs

Evidence

• pkg/workflow/engine_definition.go: comments list built-ins as claude, codex, copilot, gemini, opencode, crush.
• docs/src/content/docs/reference/engines.md: engine table lists Copilot/Claude/Codex/Gemini/Crush/OpenCode/Pi, but no Antigravity.
• .github/workflows/smoke-antigravity.md: first-party workflow uses engine.id: antigravity.
• pkg/workflow/dispatch_repository.go: parser accepts top-level dispatch-repository and deprecated alias dispatch_repository, but nested keys read are event_type and allowed_repositories only.
• pkg/parser/schemas/main_workflow_schema.json: dispatch-repository schema requires event_type; allowlist field is allowed_repositories; engine-id descriptions omit Antigravity.
• docs/src/content/docs/reference/safe-outputs.md and docs/src/content/docs/reference/frontmatter-full.md: canonical docs still teach snake_case nested keys and still expose full deprecated dispatch_repository examples.

References:

• §28998844019

Generated by ✅ Schema Consistency Checker · 14 AIC · ⌖ 5.39 AIC · ⊞ 7.3K · ◷

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

[github-actions[bot]]

This discussion was automatically closed because it expired on 2026-07-10T06:38:35.155Z.

Closed by Workflow