[Schema Consistency] Schema Consistency Check — 2026-06-18

[github-actions[bot]]

Summary

• Inconsistencies Found: 2 (1 HIGH re-confirmed, 1 MEDIUM new) + 2 LOW still-open
• Categories Analyzed: Schema ↔ Parser ↔ Docs ↔ Workflows
• Strategy Used: strategy-29 Enum-constraint presence check (NEW, day_mod=9 → new-approach mode)
• New Strategy: YES

Critical Issues

🔴 HIGH — engine.extensions valid usage is rejected by the schema (re-confirmed)

The parser reads engine.extensions and the Pi engine consumes it, but no engine_config schema branch declares the field — and every branch is additionalProperties: false. A perfectly valid Pi workflow therefore fails schema validation.

• Parser: pkg/workflow/engine.go:484-503 extracts engine.extensions (accepts []string and []any), stored in config.Extensions.
• Consumer: pkg/workflow/pi_engine.go:204-218 generates Pi extension install steps from EngineConfig.Extensions.
• Schema: engine.extensions is declared in 0 of 6 engine_config.oneOf branches; branch 1 (the rich object form) is additionalProperties: false (verified).
• Docs: not present in docs/src/content/docs/reference/ engine docs.
• Impact: Triple gap. Any workflow that uses engine: { id: pi, extensions: [...] } is rejected at schema-validation time even though the compiler fully supports it. Authors cannot discover the field.

Repro / evidence

// engine_config.oneOf[1]
{ "additionalProperties": false, "properties": { "id": {...}, /* no "extensions" */ } }

pkg/workflow/engine.go:484    if extVal, hasExt := engineObj["extensions"]; hasExt {
pkg/workflow/pi_engine.go:204  if workflowData.EngineConfig != nil && len(workflowData.EngineConfig.Extensions) > 0 {

Fix: Add an extensions property (array of string) to the engine_config object branch (oneOf[1]) and document it under the engine reference. This finding has now survived multiple runs unresolved.

Schema Improvements Needed

🟡 MEDIUM — engine.id has no enum, so the schema is laxer than the parser (NEW, strategy-29)

engine_config.oneOf[1].properties.id is { "type": "string" } with no enum, even though its own description spells out a closed catalog and the parser enforces exactly that catalog.

• Schema description: "built-in ('claude', 'codex', 'copilot', 'gemini', 'opencode', 'crush', 'pi') or a named catalog entry" — but enum is absent (NONE).
• Parser: pkg/workflow/engine_definition.go:18,185 registers a fixed built-in catalog and rejects unknown ids at compile time.
• Impact: A typo like engine: { id: claud } passes JSON-schema validation and only fails later during compilation, producing a worse error experience than a schema enum would. (Note: a free-form catalog-entry escape hatch exists, so a strict enum may need an accompanying pattern/anyOf to preserve named catalog entries — worth a maintainer decision rather than a blind enum.)

Documentation Gaps

• engine.extensions (above) is undocumented in the engine reference.

Workflow Violations

• None found. field_gaps.in_used_not_schema from the pre-computed diff is entirely false positives — model, title, task, try, else, https, repo, date, authors, serena-*, *_path, min_samples, etc. are nested keys / prompt-body tokens / MCP tool names, not top-level frontmatter keys.

Still-Open Low-Priority (carried from cache, re-confirmed)

Finding	Strategy	Severity
dispatch_repository is the lone snake_case key among kebab-case safe-output siblings	strategy-19	LOW
Parser accepts a dispatch-repository (dash) alias not declared in the schema (dispatch_repository.go:30,38)	strategy-24	LOW

Recommendations

1. Add extensions: { type: array, items: { type: string } } to engine_config.oneOf[1] and document it in the engine reference (resolves the HIGH triple-gap).
2. Constrain engine.id with an enum (or anyOf: [enum, pattern] to keep named catalog entries) so typos fail at schema-validation time with a clear message.
3. Decide on the dispatch_repository naming / dash-alias items (rename to kebab-case or declare the alias) — low priority but trivial.

Strategy Performance

• Strategy Used: strategy-29 Enum-constraint presence check (NEW)
• Findings: 1 new (engine.id) + 1 re-confirmed HIGH (engine.extensions, strategy-25)
• Effectiveness: MEDIUM — productive new angle; should reuse against other fixed-catalog string fields (runtime ids, mcp registry refs).
• Should Reuse: YES
• jq lesson recorded: x // "default" returns the default for x == false (jq treats false like null), which initially masked the additionalProperties: false on engine branches. Use has("additionalProperties") when the value may be false.

Next Steps

• Add engine.extensions to schema + docs (HIGH)
• Add enum/pattern constraint to engine.id (MEDIUM)
• Resolve dispatch_repository naming + dash alias (LOW)

Generated by ✅ Schema Consistency Checker · ◷

• expires on Jun 18, 2026, 11:04 PM UTC-08:00