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

[github-actions[bot]]

Summary

• Inconsistencies Found: 3
• 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 missing from the main frontmatter schema and frontmatter-full.md.

   • Parser/compiler: pkg/workflow/engine.go:521 reads engine.extensions; pkg/workflow/pi_engine.go:210 and :237 generate install steps from it.
   • Docs: docs/src/content/docs/reference/engines.md:424 and glossary document engine.extensions with examples.
   • Schema/frontmatter reference: pkg/parser/schemas/main_workflow_schema.json engine object (around line 11729 onward) has no extensions property, and docs/src/content/docs/reference/frontmatter-full.md engine section similarly omits it.
   • Impact: valid Pi workflows using engine.extensions will fail schema-based validation/editor assistance despite being supported at compile/runtime.

2. Engine catalog/runtime supports antigravity, but schema/docs still describe the built-in engine set as excluding it.

   • Runtime: pkg/workflow/antigravity_engine.go:20-24 registers engine id antigravity.
   • Actual workflow usage: .github/workflows/smoke-antigravity.md:36-37 uses engine.id: antigravity.
   • Schema/docs mismatch: pkg/parser/schemas/main_workflow_schema.json engine descriptions list built-ins as claude, codex, copilot, gemini, opencode, crush, pi; docs/src/content/docs/reference/frontmatter-full.md:2093-2100, 2421-2422, and docs/src/content/docs/reference/engines.md engine comments use the same list. pkg/workflow/engine_definition.go:18 stale comment also omits both pi and antigravity.
   • Impact: users are told antigravity is not a built-in option even though repo workflows and runtime support it; schema remains too lax (type: string) yet its descriptive guidance is outdated.

3. Parser accepts safe-outputs.dispatch-repository, but schema/docs only allow dispatch_repository.

   • Parser: pkg/workflow/dispatch_repository.go:30-39 explicitly accepts both dispatch_repository and dispatch-repository.
   • Schema/docs: pkg/parser/schemas/main_workflow_schema.json:9157, docs/src/content/docs/reference/safe-outputs.md:1343+, and frontmatter-full.md:7508 document only dispatch_repository.
   • Impact: one accepted spelling is parser-only. Users can write working workflows that fail schema validation or appear undocumented.

Documentation Gaps

• frontmatter-full.md is missing engine.extensions even though the dedicated engines reference documents it.
• Built-in engine lists in multiple references have drifted from runtime reality (antigravity missing; one code comment also misses pi).
• Safe-output key alias support for repository dispatch is undocumented.

Schema Improvements Needed

1. Add engine.extensions to the engine object branch in pkg/parser/schemas/main_workflow_schema.json with type: array, items: {"type":"string"}, and Pi-specific description.
2. Update engine descriptions/examples anywhere built-in IDs are enumerated so they include antigravity (and keep pi).
3. Decide whether dispatch-repository is a supported alias:
   • if yes, add it to schema/docs (or model aliases explicitly),
   • if no, remove parser support and emit a validation error instead.

Parser Updates Required

• No parser bug was required to confirm finding rejig docs #1; runtime already supports engine.extensions.
• For finding Add workflow: githubnext/agentics/weekly-research #3, parser and schema should be aligned by either deprecating/removing the dash alias or documenting/schema-encoding it.
• Refresh stale comments in pkg/workflow/engine_definition.go so code comments match runtime registration.

Workflow Violations

• .github/workflows/smoke-antigravity.md uses a real runtime-supported engine id that current schema/docs do not list as built-in guidance. This is not a runtime failure today, but it is a documentation/schema drift signal inside the repository itself.

Recommendations

1. Add engine.extensions to both schema and frontmatter-full.md, reusing the wording already present in docs/src/content/docs/reference/engines.md.
2. Centralize the built-in engine ID list (schema/docs/comments) from one authoritative source to avoid future drift like antigravity/pi.
3. Resolve the dispatch_repository vs dispatch-repository naming split with a single supported public spelling and a clear deprecation path if needed.

Strategy Performance

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

Next Steps

• Fix schema definitions for engine.extensions
• Update frontmatter reference docs and engine built-in lists
• Align parser/schema/docs for repository dispatch naming
• Refresh stale code comments around built-in engines

References:

• Runtime/workflow context: .github/workflows/smoke-antigravity.md, pkg/workflow/antigravity_engine.go, pkg/workflow/engine.go
• Schema: pkg/parser/schemas/main_workflow_schema.json
• Docs: docs/src/content/docs/reference/frontmatter-full.md, docs/src/content/docs/reference/engines.md, docs/src/content/docs/reference/safe-outputs.md

Generated by ✅ Schema Consistency Checker · 17.2 AIC · ⌖ 17.5 AIC · ⊞ 7.3K · ◷

• expires on Jun 26, 2026, 10:44 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 #41857.