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

[github-actions[bot]]

Summary

• Inconsistencies Found: 4
• 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 absent from the schema-generated frontmatter reference

   • Parser/compiler reads engineObj["extensions"] in pkg/workflow/engine.go and stores it in config.Extensions.
   • Pi runtime documentation describes engine.extensions in docs/src/content/docs/reference/engines.md and docs/src/content/docs/reference/glossary.md.
   • docs/src/content/docs/reference/frontmatter-full.md is generated from schema, but the schema's engine reference does not expose concrete properties in generated output, so users consulting the canonical frontmatter reference will not discover extensions there.
   • Impact: a real supported field is effectively invisible in the schema-based reference, and schema validation tooling cannot reliably communicate support for it.

2. Schema is looser than runtime for valid engine IDs

   • Runtime rejects unknown engines in pkg/workflow/engine_definition.go with invalid engine: ... Valid engines are: ....
   • Repository workflows use engine.id: antigravity in .github/workflows/smoke-antigravity.md.
   • Docs list antigravity/experimental engine support outside the generated frontmatter reference, but schema-generated engine examples shown in frontmatter-full.md/schema excerpts do not surface the full accepted engine catalog.
   • Impact: invalid engine IDs can appear schema-valid yet fail later at compile time; supported IDs are not fully visible from the primary schema-derived reference.

Documentation Gaps

1. Primary reference drift for engine fields

   • Specialized docs (reference/engines.md) explain engine.extensions, but reference/frontmatter-full.md does not surface it.
   • This creates a split-brain docs experience: advanced engine fields only appear if the user already knows to read the engine-specific page.

2. dispatch-repository alias is parser-only

   • Parser accepts both dispatch_repository and dispatch-repository in pkg/workflow/dispatch_repository.go.
   • Schema and docs document only dispatch_repository (docs/src/content/docs/reference/safe-outputs.md, frontmatter-full.md, glossary).
   • Impact: a workflow using the dash form compiles, but schema validation and docs say it is invalid/unsupported.

Schema Improvements Needed

1. Add explicit schema coverage for engine subfields surfaced in runtime, especially engine.extensions.
2. Constrain or otherwise machine-surface valid engine.id values so schema validation aligns better with runtime validation.
3. Decide whether dispatch-repository is a supported alias:
   • if yes, add it to schema/docs;
   • if no, remove the parser alias and keep underscore-only behavior.

Parser Updates Required

1. Either remove the undocumented dispatch-repository alias or formally support it everywhere.
2. Consider validating/normalizing engine.extensions more strictly if non-Pi engines should reject rather than silently ignore it.

Workflow Violations

1. .github/workflows/smoke-antigravity.md demonstrates a valid runtime engine ID (antigravity) that is not clearly surfaced by the schema-derived frontmatter reference.
   • This is not a broken workflow; it is evidence that workflows can use supported runtime values the schema/reference layer does not present clearly.

Recommendations

1. Make $defs.engine_config enumerate/document its supported properties so generated docs include real engine fields.
2. Add a schema enum (or generated catalog hook) for built-in engine.id values, with a documented extension path for custom engines if needed.
3. Resolve the dispatch_repository vs dispatch-repository contract mismatch in one direction only.
4. Add a regression test that compares parser-read engineObj[...] keys against schema-visible engine properties and generated docs.

Strategy Performance

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

Next Steps

• Fix schema definitions for engine subfields
• Align runtime engine catalog visibility with schema/docs
• Update documentation to eliminate alias ambiguity
• Add regression checks for parser/schema/doc drift

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

• expires on Jun 27, 2026, 10:35 PM UTC-08:00

[github-actions[bot]]

This discussion was automatically closed because it expired on 2026-06-28T06:35:15.959Z.

Closed by Workflow