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

[github-actions[bot]]

Summary

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

Critical Issues

1. engine.extensions is implemented but missing from schema and frontmatter references

   • Parser/compiler reads engine.extensions in pkg/workflow/engine.go:514-534.
   • Pi engine uses it in pkg/workflow/pi_engine.go:225.
   • User docs describe it in docs/src/content/docs/reference/engines.md:422-434.
   • But the generated schema reference and main frontmatter reference do not expose it, and the schema grep around $defs.engine_config shows no extensions property.
   • Impact: valid Pi workflows can fail schema validation or be absent from generated reference docs even though the compiler supports them.

2. engine.id is described like an enum but schema does not enforce one

   • Schema says built-in values in description only: pkg/parser/schemas/main_workflow_schema.json around $defs.engine_config.id.
   • Runtime rejects unknown ids in pkg/workflow/engine_definition.go:268-274 with invalid engine: ... Valid engines are: ....
   • Workflows in this repo actively use id: pi and id: antigravity (for example .github/workflows/schema-consistency-checker.md:14, .github/workflows/smoke-antigravity.md:37).
   • Impact: typos like copiilot can pass schema-level validation and fail later at compile/runtime, so the schema is laxer than the implementation.

Documentation Gaps

1. Main frontmatter docs omit engine.extensions while engine-specific docs document it

   • Present in docs/src/content/docs/reference/engines.md:422-434.
   • Missing from docs/src/content/docs/reference/frontmatter.md engine section and from generated frontmatter-full.md engine object excerpt near lines 2099/2421.
   • Impact: users following the main frontmatter references miss a real feature unless they also read the engine-specific page.

2. Safe-outputs dispatch repository alias is parser-only

   • Parser accepts both dispatch_repository and dispatch-repository in pkg/workflow/dispatch_repository.go:30-39.
   • Schema exposes only dispatch_repository (pkg/parser/schemas/main_workflow_schema.json:9146).
   • Docs also only mention underscore form (docs/src/content/docs/reference/safe-outputs.md:1342-1353, glossary entry).
   • Impact: workflows using the dash alias compile, but schema validation/doc-guided authoring say it is invalid.

Schema Improvements Needed

1. Add engine.extensions to $defs.engine_config with array-of-string semantics, ideally documented as Pi-only.
2. Tighten engine.id validation so schema and compiler agree. If dynamic catalog entries must remain allowed, document that explicitly and consider a pattern/anyOf split for built-ins vs named catalog entries.
3. Decide whether safe-outputs.dispatch-repository is a supported alias: either add it to schema/docs or remove parser support.

Parser Updates Required

1. If dispatch-repository is not intended to be public, remove the alias branch from parseDispatchRepositoryConfig.
2. Update stale built-in engine comments in pkg/workflow/engine_definition.go:
   • file comment says built-ins are claude, codex, copilot, gemini, opencode, crush
   • repo docs and workflows clearly include pi, and repo workflows also use antigravity as a valid engine id
   • Impact: low-severity but misleading for maintainers reading code comments.

Workflow Violations

• No confirmed repo workflow schema violation was found from the targeted checks.
• Instead, workflows demonstrate reality that the schema/docs lag behind implementation: multiple workflows use id: pi, and .github/workflows/smoke-antigravity.md uses id: antigravity, which underscores the importance of clarifying whether engine.id is an open catalog field or a constrained built-in enum.

Recommendations

1. Add engine.extensions to the schema first, then regenerate frontmatter-full.md.
2. Make an explicit product decision on engine.id: strict enum for built-ins, or documented open catalog contract.
3. Normalize dispatch_repository naming across parser/schema/docs; avoid dual spellings unless both are officially supported.
4. Refresh code comments in pkg/workflow/engine_definition.go so maintainer-facing docs match current engine catalog reality.

Strategy Performance

• Strategy Used: strategy-25 + strategy-29, with strategy-24 and strategy-30 verification
• Findings: 4
• Effectiveness: High
• Should Reuse: Yes

Next Steps

• Fix schema definitions for engine.extensions
• Align engine.id schema validation with compiler behavior
• Update frontmatter docs/generated reference
• Resolve dispatch_repository alias inconsistency
• Refresh stale engine catalog comments

References:

• §28079920974

Generated by ✅ Schema Consistency Checker · 22.4 AIC · ⊞ 7.3K · ◷

• expires on Jun 24, 2026, 10:36 PM UTC-08:00

[github-actions[bot]]

This discussion was automatically closed because it expired on 2026-06-25T06:36:52.189Z.

Closed by Workflow