[Schema Consistency] Schema Consistency Check - 2026-09-27

[github-actions[bot]]

🔍 Schema Consistency Check - 2026-09-27

Summary

• Inconsistencies Found: 4
• Categories Analyzed: Schema, Parser, Documentation, Workflows
• Strategy Used: Schema-def spot checks + targeted parser/doc/workflow verification
• New Strategy: NO (day-of-year modulo favored proven strategy)

Critical Issues

1. Documented deprecated alias engine.max-turns is not represented in schema/parser frontmatter types

   • Evidence in docs: docs/src/content/docs/reference/cost-management.md:238 documents engine.max-turns as deprecated alias.
   • Frontmatter type only exposes top-level field: pkg/workflow/frontmatter_types.go:362 (MaxTurns top-level).
   • Schema surface is top-level only: pkg/parser/schemas/main_workflow_schema.json:4355 ("max-turns"), with no corresponding engine.max-turns property in top-level frontmatter contract.
   • Impact: Users following docs can author invalid frontmatter that fails validation or behaves unexpectedly.

2. Generated schema-diff reports many in_schema_not_workflow keys that are likely false positives due to extraction method mismatch

   • Evidence: /tmp/gh-aw/agent/schema-diff.json lists numerous top-level keys (safe-outputs, runs-on-slim, strict, etc.) in field_gaps.in_schema_not_workflow.
   • But workflows actively use these keys, e.g. .github/workflows/agentic-token-audit.md:17 (safe-outputs:), .github/workflows/daily-fact.md:39 (runs-on:).
   • Frontmatter struct defines them: pkg/workflow/frontmatter_types.go:385 (safe-outputs), pkg/workflow/frontmatter_types.go:409 (runs-on), pkg/workflow/frontmatter_types.go:410 (runs-on-slim).
   • Impact: Automated drift conclusions based on this gap list are unreliable unless the extractor clearly scopes to top-level frontmatter tags.

Documentation Gaps

1. Defaults in docs are not tied to schema-visible defaults for key operational fields
   • Docs describe defaults/guardrails (e.g., timeouts and credits): docs/src/content/docs/reference/cost-management.md:188.
   • The schema locations for these fields exist (timeout-minutes at pkg/parser/schemas/main_workflow_schema.json:2936, max-turns at pkg/parser/schemas/main_workflow_schema.json:4355) but the contract and docs are not obviously cross-linked in a way that lets readers verify which layer owns defaults.
   • Impact: Confusion about whether defaults are schema-level, compiler env-level, or runtime-level.

Schema Improvements Needed

1. Make alias behavior explicit in schema (or remove from docs)

   • Either add explicit deprecated alias handling for engine.max-turns in schema, or remove/clarify the alias statement from docs.

2. Clarify ownership of defaults in schema descriptions

   • For fields like timeout-minutes, max-turns, and max-runs, embed explicit notes indicating whether defaults are schema defaults vs compiler/runtime defaults.

Parser Updates Required

1. Align parser/validation behavior with documented alias story
   • If engine.max-turns is truly supported as a deprecated alias, parser extraction/normalization should expose that path clearly in frontmatter parsing and validation code, not only in prose docs.

Workflow Violations

• No direct workflow schema violations found from sampled high-signal keys (max-turns, runs-on, safe-outputs, cache) in .github/workflows/*.md.
• Existing workflows appear to use currently declared top-level fields.

AWF Config-Source Drift Context

• /tmp/gh-aw/agent/awf-config-drift.json reports degraded: true with canonical source retrieval failure.
• Per policy, this run treats AWF canonical-source availability as a non-authoritative warning only and does not recommend destructive correction actions from that comparison.

Recommendations

1. Reconcile engine.max-turns documentation with actual schema/parser behavior in one change set.
2. Improve schema-diff extractor to distinguish top-level frontmatter tags from nested job/action YAML tags to reduce false-positive in_schema_not_workflow gaps.
3. Add a CI assertion that every documented deprecated alias is represented in either schema (explicitly deprecated) or parser normalization tests.
4. Add doc callouts for default-resolution precedence: frontmatter value > env override > runtime fallback.

Strategy Performance

• Strategy Used: Schema-def spot checks + targeted parser/doc/workflow verification
• Findings: 4
• Effectiveness: HIGH
• Should Reuse: YES

Next Steps

• Fix alias consistency (engine.max-turns) across schema/parser/docs
• Tighten schema-diff extraction heuristics
• Add regression tests for deprecated alias handling
• Add docs clarifying default source-of-truth precedence

Generated by ✅ Schema Consistency Checker · codex · gpt53codex · 11.7 AIC · ⌖ 3.56 AIC · ⊞ 21K · ◷

• expires on Sep 27, 2026, 9:34 PM UTC-08:00

[github-actions[bot]]

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

A newer discussion is available at Discussion #63937.