[Schema Consistency] 🔍 Schema Consistency Check - 2026-08-15 #52849

Summary

• Inconsistencies Found: 4
• Categories Analyzed: Schema, Parser, Documentation, Workflows
• Strategy Used: Targeted gap verification + top-level semantic checks
• New Strategy: YES

Critical Issues

1. max-turns is missing from FrontmatterConfig despite being a first-class top-level schema field

   • Schema: pkg/parser/schemas/main_workflow_schema.json defines top-level max-turns with examples and description.
   • Parser type: pkg/workflow/frontmatter_types.go does not include a json:"max-turns" field in FrontmatterConfig.
   • Implementation still uses it via raw-map parsing in pkg/workflow/engine.go:241.
   • Impact: the typed frontmatter model is incomplete, so any code that relies on FrontmatterConfig for introspection, serialization, docs tooling, or validation can silently miss max-turns even though runtime compilation honors it.

2. Top-level github-app is also missing from FrontmatterConfig, even though runtime/compiler support exists and docs advertise it

   • Schema: top-level github-app exists and is documented as workflow-wide fallback config.
   • Docs: docs/src/content/docs/reference/frontmatter.md:158 documents github-app: as a top-level field.
   • Implementation: pkg/workflow/workflow_github_app.go:15-45 extracts frontmatter["github-app"] and applies fallback behavior; pkg/workflow/workflow_data.go:127 stores TopLevelGitHubApp.
   • Parser type: pkg/workflow/frontmatter_types.go has no top-level github-app field on FrontmatterConfig.
   • Impact: another mismatch between the canonical typed frontmatter model and actual supported workflow semantics.

Documentation Gaps

3. max-runs is in schema and implementation, but not surfaced in the user-facing frontmatter docs
   • Schema: max-runs exists, marked deprecated, with migration text to max-turns.
   • Implementation: pkg/workflow/engine.go:245-248 still parses max-runs; pkg/workflow/engine_config_parser.go:27-30 validates it; pkg/workflow/README.md describes it as engine.max-runs / AWF apiProxy.maxRuns.
   • User docs: no visible top-level max-runs section in docs/src/content/docs/reference/frontmatter.md; the generated frontmatter-full.md also does not expose a top-level max-runs: example near the main top-level field list.
   • Impact: users can still write a deprecated-but-supported field that is effectively undocumented in the main reference.

Schema Improvements Needed

4. Schema-diff workflow over-reports fake inconsistencies because it treats nested keys as top-level frontmatter fields
   • Precomputed diff reported include and version under in_frontmatter_not_schema.
   • Verification shows those are nested fields, not top-level frontmatter:
     • pkg/workflow/frontmatter_types.go:383 → Include belongs to imported-step / stop-after-related config, not top-level frontmatter.
     • pkg/workflow/frontmatter_types.go:24 and nearby matches show version is used in runtime configs and other nested structs.
     • Actual workflow usage examples such as .github/workflows/smoke-test-tools.md use version: inside runtimes: blocks, not as a top-level frontmatter key.
   • Impact: the current checker can create noisy or misleading reports unless it scopes extraction to type FrontmatterConfig struct instead of all tagged fields in frontmatter_types.go.

Parser Updates Required

• Add top-level typed fields for schema-backed frontmatter that are currently parsed only from raw maps:
  • max-turns
  • github-app
  • likely ambient-folders as well, since it is schema-backed and compiler-supported through pkg/workflow/ambient_folders.go but absent from FrontmatterConfig.
• Keep raw-map parsing where needed, but make the typed model match the supported contract.

Workflow Violations

• No confirmed repository workflow was found using an actually invalid top-level field from the main schema.
• Several entries from used_in_workflows / in_used_not_schema are false positives caused by naive regex extraction over nested YAML blocks in markdown workflows rather than true top-level frontmatter keys.

Recommendations

1. Add max-turns, github-app, and ambient-folders to pkg/workflow/frontmatter_types.go's FrontmatterConfig.
2. Add a deprecated max-runs note to docs/src/content/docs/reference/frontmatter.md, pointing users to max-turns.
3. Tighten the schema-consistency precomputation so it only enumerates fields from type FrontmatterConfig struct for frontmatter comparisons.
4. Split findings into real contract mismatches vs checker false positives to keep future reports actionable.

Strategy Performance

• Strategy Used: Targeted gap verification + top-level semantic checks
• Findings: 4
• Effectiveness: HIGH
• Should Reuse: YES

Next Steps

• Fix typed frontmatter coverage for supported top-level fields
• Update documentation for deprecated-but-supported fields
• Reduce false positives in the schema diff precompute job
• Re-run the checker after narrowing frontmatter field extraction

Generated by ✅ Schema Consistency Checker · gpt54 · 36.1 AIC · ⌖ 4.89 AIC · ⊞ 8.7K · ◷

• expires on Aug 15, 2026, 9:36 PM UTC-08:00