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

[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 docs

   • Parser/compiler: pkg/workflow/engine.go:514-534 reads engineObj["extensions"] into EngineConfig.Extensions.
   • Runtime usage: pkg/workflow/pi_engine.go:198,225 emits pi install <extension> steps from engine.extensions.
   • Schema: pkg/parser/schemas/main_workflow_schema.json $defs.engine_config object branch (11713-11958) sets additionalProperties: false and has no extensions property.
   • Docs: docs/src/content/docs/reference/frontmatter.md:145-150 only documents engine: copilot; docs/src/content/docs/reference/frontmatter-full.md:2098-2155 lists engine object keys and also omits extensions.
   • Impact: Valid runtime config for the Pi engine is rejected by schema validation and undiscoverable in docs.

2. engine.id is described as a fixed built-in set, but schema does not enforce it while runtime does

   • Schema: $defs.engine_config.properties.id is only type: string at pkg/parser/schemas/main_workflow_schema.json:11714-11717.
   • Docs/schema prose: same block says built-ins are claude, codex, copilot, gemini, opencode, crush, pi.
   • Runtime validation: pkg/workflow/engine_definition.go:268-276 errors with invalid engine: ... Valid engines are: ... for unknown IDs.
   • Impact: Typos pass schema validation but fail later during compilation/runtime resolution, producing a later and less actionable failure mode.

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 underscore and dash spellings.
   • Schema: pkg/parser/schemas/main_workflow_schema.json:9142+ defines only dispatch_repository.
   • Docs: docs/src/content/docs/reference/frontmatter-full.md:7508 documents only dispatch_repository:.
   • Impact: Workflows using the parser-supported dash alias fail schema validation and are not documented, creating a parser-vs-schema/docs inconsistency.

Documentation Gaps

• frontmatter.md is too high-level for engine: and does not mention advanced object-only keys such as the implemented Pi-specific extensions field.
• frontmatter-full.md mirrors the schema omission, so users cannot discover engine.extensions even though the compiler supports it.
• dispatch_repository docs omit the accepted alias, so readers cannot predict which spellings validate versus merely parse.

Schema Improvements Needed

1. Add engine.extensions to $defs.engine_config.properties with type: array, items: {"type":"string"} and a Pi-engine-specific description.
2. Tighten engine.id / runtime IDs with an enum or a oneOf split between built-in IDs and named catalog references, or clearly document why arbitrary strings are intentionally allowed.
3. Decide whether dispatch-repository should be:
   • added as an explicit alias in schema/docs, or
   • removed from parser acceptance to restore one canonical key.

Parser Updates Required

• If the dash alias is intentional, align schema/docs with parser behavior.
• If it is accidental compatibility baggage, remove the alias path in pkg/workflow/dispatch_repository.go or warn when used.
• Consider validating built-in engine.id values earlier so schema and compiler fail at the same layer.

Workflow Violations

• No repository workflow examples surfaced these specific mismatches directly in .github/workflows/*.md during this run.
• The main workflow-facing risk is future authoring friction: authors can write configs accepted by compiler logic (engine.extensions, dispatch-repository) that fail schema-based tooling or docs-driven linting.

Recommendations

1. High priority: add engine.extensions to schema and both frontmatter references.
2. Medium priority: constrain or better model engine.id so schema catches invalid built-in engine names earlier.
3. Low priority: normalize dispatch_repository naming by either documenting/schema-allowing the dash alias or removing parser support.
4. Add regression tests that diff parser-read engine keys against schema properties for $defs.engine_config.

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
• Update parser/schema alignment for dispatch_repository alias handling
• Update documentation examples and field reference pages
• Add a regression check for engine key coverage

References:

• §28007183690

Generated by ✅ Schema Consistency Checker · 21.2 AIC · ⌖ 2.41 AIC · ⊞ 4.8K · ◷

• expires on Jun 23, 2026, 10:39 PM UTC-08:00

[github-actions[bot]]

This discussion was automatically closed because it expired on 2026-06-24T06:39:25.927Z.

Closed by Workflow