[Schema Consistency] Audit 2026-05-27 — Schema enum gaps, unused $def, plus re-confirmed doc/deprecation issues

[github-actions[bot]]

Summary

• Inconsistencies surfaced: 7 (2 new + 5 re-confirmed)
• Categories analyzed: Schema ↔ Parser, Schema ↔ Docs, Schema ↔ Workflows, Parser ↔ Docs
• Strategy mode: New approach (day-of-year mod 10 = 7 → exploratory)
• New strategies introduced: strategy-13 ($defs reference integrity), strategy-14 (enum vs prose-only enumeration)
• Status: ⚠️ Several long-standing gaps remain. Two are new high-signal findings worth fixing in a single PR.

Critical Issues

🆕 1. engine.id has no enum constraint — typos pass schema validation

engine.id in pkg/parser/schemas/main_workflow_schema.json (engine_config def) is declared {"type": "string"} with the valid values listed only in the description prose:

"AI engine identifier: built-in ('claude', 'codex', 'copilot', 'gemini', 'opencode', 'crush', 'pi') or a named catalog entry"

The existing error-formatting test at pkg/workflow/compiler_error_formatting_test.go:246 uses a literal "copiliot" typo because the only validation today happens at compile time, not in the editor / schema validator. Adding an enum: [...] constraint (with the named catalog entry carve-out handled via oneOf if needed) would catch these at edit time in any JSON-schema-aware IDE.

Additionally, the engine model-env switch at pkg/workflow/compiler_yaml.go:772 includes:

case "custom":
    modelEnvVar = constants.EnvVarModelAgentCustom

"custom" is not listed in the schema description's enumeration of valid engine ids, but the compiler explicitly handles it — pick one truth.

🆕 2. Unused templatable_integer $def, 62 inline duplicates

$defs.templatable_integer is defined in the schema (with a good description) but is referenced from zero places:

# from strategy-13
jq -r '."$defs" | keys[]' main_workflow_schema.json > defs.txt
jq -r '[.. | objects | select(has("$ref")) | ."$ref"] | unique | .[] | sub("#/\\$defs/"; "")' main_workflow_schema.json > refs.txt
comm -23 defs.txt refs.txt   # → templatable_integer

Its sibling $defs.templatable_boolean is referenced 5+ times and works exactly the way you'd expect. Meanwhile the schema contains 62 inline copies of the same oneOf: [{type: integer}, {type: string, pattern: ^\$\{\{...\}\}$}] shape — e.g. rate-limit.max-runs, rate-limit.max, plus dozens of similar locations.

Folding those duplicates into $ref: "#/$defs/templatable_integer" would (a) shrink the schema, (b) make GitHub Actions expression support universally consistent (some inline copies omit minimum: 0, others omit the templating string variant), and (c) put the unused $def to work.

Documentation Gaps

3. Three fields entirely undocumented in curated docs (re-confirmed)

The following top-level fields have zero mentions anywhere in docs/src/content/docs/ outside the auto-generated frontmatter-full.md:

• check-for-updates
• disable-model-invocation
• run-install-scripts

These are reachable via the schema and surfaced in tooling, but a user reading the curated reference will never learn what they do.

4. Broken reference/frontmatter/#anchor links in schema descriptions

The schema descriptions for check-for-updates and run-install-scripts both link to frontmatter/#<field> anchors that do not resolve to any heading in docs/src/content/docs/reference/frontmatter.md. Fixing #3 and #4 together is a single PR.

Schema Improvements Needed

5. Prose-only deprecation flags (re-confirmed)

Two top-level fields are described as deprecated/legacy but lack the JSON Schema deprecated: true flag, so IDE deprecation strikethrough never fires and the compiler's warnDeprecatedFrontmatterFields() infrastructure can't see them either:

Field	Schema description excerpt	deprecated: flag
rate-limit	"Legacy alias for 'user-rate-limit'..."	missing
inline-sub-agents	"Deprecated switch for inline sub-agent support..."	missing

For rate-limit, pkg/workflow/role_checks.go:301 only logs "Extracted legacy rate-limit configuration" via the debug-only roleLog.Print — not a user-visible warning. Adding "deprecated": true to both schema entries hooks them into the existing warning machinery at pkg/workflow/compiler_orchestrator_tools.go:436-460.

Parser Updates Required

6. applyTo is a dead validFields allowlist entry (re-confirmed)

pkg/parser/include_processor.go:267 still lists "applyTo": true in the valid-fields allowlist for shared workflows, and the comment at pkg/parser/schema_utilities.go:14 claims:

as all previously ignored fields (description, applyTo) are now validated by the schema

This is false: applyTo does not appear as a top-level property in main_workflow_schema.json and isn't used by any workflow file or referenced anywhere in implementation logic. Either restore real schema/implementation support or remove the entry and the misleading comment.

Workflow Violations

No new workflow-side violations beyond those already covered by field_gaps.in_used_not_schema (which is dominated by nested keys flattened by the diff script — none of the remaining names appear to be real new top-level violations).

Recommendations

1. Schema PR — enum + dead def cleanup (new, high impact)

   • Add an enum (or oneOf with a named-catalog-entry escape hatch) on engine_config.oneOf[1].properties.id and on the bare-string variant; align with pkg/workflow/compiler_yaml.go:764-776.
   • Decide whether "custom" is officially supported. If yes, document and add to the enum / description. If no, treat it as the default: arm and remove the case "custom" branch.
   • Refactor inline integer | $\{\{ ... \}\} patterns to $ref: "#/$defs/templatable_integer" (≈62 sites).

2. Deprecation PR

   • Add "deprecated": true to the rate-limit and inline-sub-agents schema entries.
   • Verify warnDeprecatedFrontmatterFields() then surfaces a user-visible warning when either is used.

3. Docs PR

   • Add curated sections for check-for-updates, disable-model-invocation, and run-install-scripts in docs/src/content/docs/reference/frontmatter.md, with heading slugs that match the existing schema links.

4. Parser cleanup PR

   • Remove "applyTo" from pkg/parser/include_processor.go:267 or restore real support.
   • Fix the misleading comment at pkg/parser/schema_utilities.go:14.

Strategy Performance

Strategy	Used	Findings	Effectiveness
strategy-13 ($defs reference integrity) — new	1	1 (high impact, 62-site refactor)	high
strategy-14 (enum vs prose-only enumeration) — new	1	2 (engine.id enum + custom mismatch)	high
strategy-7 (doc coverage)	8	3 (re-confirmed)	high
strategy-8 (deprecation enforcement)	8	1 (re-confirmed)	high
strategy-9 (validFields cross-check)	8	1 (re-confirmed)	high
strategy-10 (deprecation flag consistency)	7	2 (re-confirmed)	high
strategy-12 (doc-link anchor verification)	3	2 (re-confirmed)	high

Cache updated at /tmp/gh-aw/cache-memory/strategies.json with two new strategies (strategy-13, strategy-14). Both should be reused in future cycles — they target schema-internal hygiene, which is independent of code/doc churn.

Next Steps

• Add engine.id enum constraint (and decide the fate of "custom")
• Refactor 62 inline integer | string patterns to use $defs/templatable_integer
• Add "deprecated": true to rate-limit and inline-sub-agents schema entries
• Add curated docs sections for check-for-updates, disable-model-invocation, run-install-scripts
• Remove dead applyTo allowlist entry and fix the stale comment

References:

• §26495406662

Generated by ✅ Schema Consistency Checker · opus47 6.6M · ◷

• expires on May 28, 2026, 6:50 AM UTC

[github-actions[bot]]

This discussion has been marked as outdated by Schema Consistency Checker.

A newer discussion is available at Discussion #35425.