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

[github-actions[bot]]

Summary

• Inconsistencies Found: 3
• Categories Analyzed: Schema, Parser, Documentation, Workflows
• Strategy Used: Engine sub-object key coverage (engineObj vs engine_config branches)
• New Strategy: No

Critical Issues

1. engine.extensions is implemented but missing from schema and generated reference docs

   • Parser/compiler: pkg/workflow/engine.go:497 reads engine.extensions and populates config.Extensions; pkg/workflow/pi_engine.go:192 and pkg/workflow/pi_engine.go:219 use it to emit pi install <extension> steps.
   • Schema: pkg/parser/schemas/main_workflow_schema.json has no "extensions" property under engine / $defs.engine_config.
   • Docs: docs/src/content/docs/reference/frontmatter-full.md contains no engine.extensions entry even though it is generated from the schema.
   • Impact: Valid real-world Pi workflows can be rejected by schema validation or remain undocumented, while compiled behavior still supports them.

2. engine.id is schema-lax but runtime-strict

   • Schema: the engine.id field is a plain string in pkg/parser/schemas/main_workflow_schema.json (around line 2041), with valid engines only implied in descriptions.
   • Runtime: pkg/workflow/engine_definition.go:268 rejects unknown values with invalid engine: ... Valid engines are: ....
   • Docs: docs/src/content/docs/reference/engines.md enumerates supported values (copilot, claude, codex, gemini, crush, opencode, pi).
   • Impact: Typos pass schema validation and fail later at compile/runtime with a different validation surface.

3. safe-outputs.dispatch-repository alias works in parser but is absent from schema/docs

   • Parser: pkg/workflow/dispatch_repository.go:30-39 explicitly accepts both dispatch_repository and dispatch-repository.
   • Schema: only dispatch_repository is declared in pkg/parser/schemas/main_workflow_schema.json:9137.
   • Docs: reference docs only document underscore form.
   • Impact: A configuration accepted by the compiler can still fail schema validation and is invisible in documentation.

Documentation Gaps

• The generated full frontmatter reference omits engine.extensions, proving the schema/docs pipeline is not capturing a live parser feature.
• The engines guide lists the supported engine IDs, but the schema does not encode the same constraint.
• Safe-output docs describe only dispatch_repository, not the accepted dashed alias.

Schema Improvements Needed

1. Add engine.extensions to $defs.engine_config with type: array, string items, and Pi-specific description/examples.
2. Add an enum (or equivalent constrained validation) for engine.id, or document intentionally broader acceptance if runtime prefix fallback is desired.
3. Either add dispatch-repository as an accepted alias in the schema/docs or remove parser support for it to keep a single canonical spelling.

Parser Updates Required

1. If dispatch-repository is meant to remain supported, make that alias explicit everywhere validation happens.
2. Consider aligning early validation for engine.id with the schema to avoid deferred compile errors.
3. Add regression tests that diff parser-read engine keys against schema-declared keys so engine.extensions-style drift is caught automatically.

Workflow Violations

• No repo workflow violation was needed to prove the highest-signal issues; these are implementation/schema/doc mismatches that can affect future workflow authors immediately.
• The precomputed field-gap list is noisy for top-level fields, but it correctly motivated targeted verification of parser-only capabilities.

Recommendations

1. Highest priority: add engine.extensions to the schema and regenerate frontmatter-full.md.
2. Constrain engine.id in schema to the same catalog enforced by the compiler, or clearly document the deliberate mismatch.
3. Decide on one canonical safe-output key spelling for repository dispatch and remove the mismatch across parser/schema/docs.
4. Add CI coverage that compares parser-accepted aliases and subkeys against schema properties where additionalProperties: false is used.

Strategy Performance

• Strategy Used: Engine sub-object key coverage (engineObj vs engine_config branches)
• Findings: 3
• Effectiveness: HIGH
• Should Reuse: YES

Next Steps

• Fix schema definitions for engine.extensions and engine.id
• Update generated documentation
• Reconcile dispatch_repository vs dispatch-repository
• Add regression coverage for parser/schema drift

References:

• §27935555822

Generated by ✅ Schema Consistency Checker · 17.4 AIC · ⌖ 2.38 AIC · ⊞ 7.2K · ◷

• expires on Jun 22, 2026, 11:10 PM UTC-08:00

[github-actions[bot]]

This discussion was automatically closed because it expired on 2026-06-23T07:10:10.783Z.

Closed by Workflow