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

[github-actions[bot]]

Summary

• Inconsistencies Found: 4
• Categories Analyzed: Schema, Parser, Documentation, Workflows
• Strategy Used: Engine sub-object key coverage + parser alias coverage
• New Strategy: NO

Critical Issues

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

   • Parser/compiler: pkg/workflow/engine.go:521-541 parses engine.extensions
   • Docs: docs/src/content/docs/reference/engines.md has a dedicated Pi Extensions (extensions) section
   • Schema/generated docs: $defs.engine_config in pkg/parser/schemas/main_workflow_schema.json has no extensions property, so docs/src/content/docs/reference/frontmatter-full.md cannot show it
   • Impact: valid Pi workflows can fail schema validation or appear unsupported in generated reference docs

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

   • Parser/compiler: pkg/workflow/dispatch_repository.go:30-39 explicitly accepts both dispatch_repository and dispatch-repository
   • Schema: pkg/parser/schemas/main_workflow_schema.json contains dispatch_repository only (around line 9197)
   • Docs: no dispatch-repository alias appears in the generated references
   • Impact: a config spelling accepted by runtime is rejected by schema validation and undocumented

3. Parser still accepts engine.copilot-sdk-driver, but schema exposes only engine.driver

   • Parser/compiler: pkg/workflow/engine.go:413-424 maps both driver and deprecated copilot-sdk-driver into the same field
   • Schema: $defs.engine_config contains driver, but no copilot-sdk-driver
   • Docs: docs/src/content/docs/reference/engines.md still documents engine.copilot-sdk-driver; pkg/workflow/README.md also references it
   • Impact: existing workflows following docs can be rejected by schema validators even though compilation still supports the alias

Documentation Gaps

1. Antigravity is implemented and used, but omitted from schema-driven engine descriptions/examples
   • Runtime: pkg/workflow/antigravity_engine.go registers/implements the engine
   • Workflows: .github/workflows/smoke-antigravity.md uses engine.id: antigravity
   • Other docs: docs/src/content/docs/reference/engines.md currently lists Copilot, Claude, Codex, Gemini, Crush, OpenCode, and Pi — not Antigravity
   • Schema: $defs.engine_config descriptions/examples list built-ins like 'claude', 'codex', 'copilot', 'gemini', 'opencode', 'crush', 'pi' but not antigravity
   • Impact: generated docs and schema guidance understate the supported engine set, causing false negatives for users and tooling

Schema Improvements Needed

1. Add engine.extensions to $defs.engine_config.properties with array-of-string validation and Pi-specific description.
2. Decide whether deprecated aliases should remain schema-valid:
   • if yes, add engine.copilot-sdk-driver
   • if no, remove it from docs and emit a dedicated migration note
3. Add either dispatch-repository as an accepted alias in schema/docs or remove parser support for the alias.
4. Update engine descriptions/examples in schema so built-in engine lists include antigravity wherever runtime supports it.

Parser Updates Required

1. If alias support is intentional, keep parser behavior but align schema/docs for:
   • safe-outputs.dispatch-repository
   • engine.copilot-sdk-driver
2. If aliases are no longer desired, parser should emit deprecation warnings or stop accepting them after docs are updated.

Workflow Violations

• No invalid in-repo workflow usage was confirmed in this pass.
• Instead, the main workflow-side signal is that .github/workflows/smoke-antigravity.md demonstrates a real supported engine (antigravity) that the schema and schema-generated references still omit.

Recommendations

1. Treat $defs.engine_config as the source of truth for engine option coverage and diff it against ExtractEngineConfig() in CI.
2. Add a schema-vs-parser alias test for every parser-supported fallback key.
3. Regenerate frontmatter-full.md after fixing schema gaps and confirm engine.extensions appears.
4. Reconcile engines.md with the actual engine registry so Antigravity is either documented as supported or explicitly marked experimental/hidden everywhere consistently.

Strategy Performance

• Strategy Used: Engine sub-object key coverage (schema ↔ parser ↔ docs) plus parser alias coverage
• Findings: 4
• Effectiveness: HIGH
• Should Reuse: YES

Next Steps

• Add missing engine keys to the main schema (extensions, possibly deprecated aliases)
• Align alias handling between parser, schema, and docs
• Update engine lists/examples to include antigravity consistently
• Regenerate schema-derived reference docs and verify output

References:

• §28354267032

Generated by ✅ Schema Consistency Checker · 47.6 AIC · ⌖ 19.7 AIC · ⊞ 7.4K · ◷

• expires on Jun 29, 2026, 11:03 PM UTC-08:00