[Schema Consistency] 🔍 Schema Consistency Check - 2026-09-26

[github-actions[bot]]

Summary

• Inconsistencies Found: 4
• Categories Analyzed: Schema, Parser, Documentation, Workflows
• Strategy Used: Doc-claim contradiction audit (new-approach mode) + targeted schema/parser spot checks
• New Strategy: YES
• AWF Config Drift Source Status: Degraded canonical-source retrieval (degraded: true in /tmp/gh-aw/agent/awf-config-drift.json), so AWF drift observations are non-authoritative only.

Critical Issues

1. Potential schema type invalidity for nullable numeric-like limits

   • Evidence: schema-diff.json shows blank top-level type entries for max-runs, max-daily-ai-credits, max-ai-credits, max-tool-denials, timeout-minutes, runs-on, and runs-on-slim in field_types.
   • Parser expectation: strong typed fields exist in frontmatter (pkg/workflow/frontmatter_types.go:363, pkg/workflow/frontmatter_types.go:366, pkg/workflow/frontmatter_types.go:367, pkg/workflow/frontmatter_types.go:410).
   • Impact: if schema typing is expressed in a way tooling cannot reliably introspect, downstream validators/editors can under-validate these high-impact controls.

2. Permissions shape mismatch risk between docs and parser compatibility behavior

   • Parser keeps both typed and deprecated forms: PermissionsTyped any and legacy Permissions map[string]any (pkg/workflow/frontmatter_types.go:393, pkg/workflow/frontmatter_types.go:394).
   • Schema permits string or object for permissions (pkg/parser/schemas/main_workflow_schema.json:2530 onward).
   • Risk: docs can imply a single canonical format while parser still accepts dual forms for backward compatibility, making migration state unclear for users.

Documentation Gaps

1. Top-level legacy aliases are under-signaled in reference docs

   • Parser comment explicitly marks max-runs as deprecated alias for max-turns (pkg/workflow/frontmatter_types.go:363).
   • Workflows still use these fields broadly (sample usage appears in .github/workflows/api-consumption-report.md:7 for max-daily-ai-credits).
   • Gap: docs should clearly and centrally mark legacy aliases and migration behavior to avoid mixed usage persistence.

2. Import-schema value-shape constraints are buried and easy to miss

   • Schema repeatedly documents only one-level-deep object allowance in import parameter objects (pkg/parser/schemas/main_workflow_schema.json:223, pkg/parser/schemas/main_workflow_schema.json:286, pkg/parser/schemas/main_workflow_schema.json:388).
   • Gap: if frontmatter.md/frontmatter-full.md do not present this prominently with failing examples, users can author nested values that parse mentally but fail validation.

Schema Improvements Needed

1. Ensure machine-readable type metadata for all top-level fields appears consistently in tooling outputs (especially limit and runner fields).
2. Add explicit deprecated/migration annotations for known aliases (e.g., max-runs) where supported by schema conventions.
3. Tighten and centralize permissions examples to mirror both accepted forms and preferred modern form.

Parser Updates Required

1. Emit explicit compile-time warnings when legacy permissions or max-runs alias paths are used, if not already surfaced.
2. Add/confirm tests that protect intended behavior for inlined-imports, import-schema object-depth constraints, and legacy alias normalization.

Workflow Violations

• No outright top-level unknown-key violations found from precomputed field_gaps.in_used_not_schema (empty in /tmp/gh-aw/agent/schema-diff.json).
• Observed mixed-era config usage persists in real workflows (e.g., limit aliases), which is valid but contributes to documentation/consistency drift.

Recommendations

1. Publish a concise “legacy frontmatter aliases” table in docs with replacement fields and deprecation timelines.
2. Add schema-level metadata or lints for soft-deprecated keys to guide authors before compile time.
3. Add a docs section with explicit import-schema nested-object invalid examples and corresponding validator errors.
4. Add a CI check that flags when field_types extraction yields blank type markers for top-level keys.

Strategy Performance

• Strategy Used: Doc-claim contradiction audit + targeted spot checks
• Findings: 4
• Effectiveness: MEDIUM-HIGH
• Should Reuse: YES (especially when precomputed diff already shows zero obvious field-name gaps)

Next Steps

• Fix schema type exposure/consistency for nullable/union top-level fields
• Clarify and document permissions compatibility and preferred format
• Document deprecations (max-runs alias) in frontmatter references
• Expand import-schema docs with invalid nested examples

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

• expires on Sep 26, 2026, 9:33 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 #63784.