[Schema Consistency] 🔍 Schema Consistency Check - 2026-08-20

[github-actions[bot]]

Summary

• Inconsistencies Found: 4
• Categories Analyzed: Schema, Parser, Documentation, Workflows
• Strategy Used: Precomputed field-gap + targeted validation check
• New Strategy: NO
• AWF config drift note: Canonical-source retrieval was degraded (/tmp/gh-aw/agent/awf-config-drift.json), so any AWF config-source observations are non-authoritative warnings only. No corrective action is recommended from drift data in this run.

Critical Issues

1. strict: default is described correctly in docs/schema, but the CLI compile path appears to default to non-strict unless the caller sets the flag

• Schema: pkg/parser/schemas/main_workflow_schema.json defines strict as a boolean with default true.
• Docs: docs/src/content/docs/reference/frontmatter.md says strict: default is true and that workflows run in strict mode unless set to false.
• CLI/MCP setup:
  • pkg/cli/compile_compiler_setup.go unconditionally applies compiler.SetStrictMode(config.Strict).
  • The MCP compile tool explicitly injects a default of strict=true in pkg/cli/mcp_tools_readonly.go.
  • But the ordinary CLI flag path does not show the same explicit default in the inspected setup code; the comment in pkg/cli/compile_compiler_setup.go says flags are set from config.Strict directly.
• Why this matters: If config.Strict is false by default in the normal CLI command path, that contradicts both schema/docs and the MCP compile tool behavior. This could silently weaken validation for gh aw compile while docs promise strict-by-default behavior.
• Files:
  • pkg/parser/schemas/main_workflow_schema.json
  • docs/src/content/docs/reference/frontmatter.md
  • pkg/cli/compile_compiler_setup.go
  • pkg/cli/mcp_tools_readonly.go
• Action: Audit the regular CLI compile flag defaults and ensure they match the documented/schema default (true), or update docs/schema if the product decision is actually different.

2. redirect: behavior in docs overstates what gh aw compile does compared with parser/compiler implementation

• Docs: docs/src/content/docs/reference/frontmatter.md says: "gh aw compile emits an informational message when a redirect is configured."
• Compiler behavior: pkg/workflow/compiler_orchestrator_frontmatter.go treats a file as redirect-only only when it has redirect and no on field. In that case, compilation returns a redirect-only workflow error via pkg/workflow/compiler_orchestrator_workflow.go.
• Observed workflow usage: .github/workflows/ai-moderator.md contains redirect: at line 3.
• Why this matters: The docs read like any workflow with redirect: gets an informational compile message. The implementation is narrower: redirect-only placeholders are a special case, while ordinary workflows with both on: and redirect: are not obviously handled the same way in the inspected code path.
• Action: Clarify docs to distinguish:
  1. redirect-only placeholder files (redirect without on), and
  2. normal workflows that happen to carry redirect metadata.

Documentation Gaps

3. Valid top-level fields implemented in schema/parser are missing from frontmatter.md

The main frontmatter reference appears incomplete for some valid top-level fields that exist in both the schema and parser:

• max-turn-cache-misses
  • Parser: pkg/workflow/frontmatter_types.go, pkg/workflow/engine.go, pkg/workflow/engine_config_parser.go
  • Docs elsewhere: docs/src/content/docs/reference/glossary.md, docs/src/content/docs/reference/compiler-enterprise-environment-controls.md
  • Missing from: docs/src/content/docs/reference/frontmatter.md
• excluded-env
  • Parser: pkg/workflow/frontmatter_types.go
  • Schema: top-level field exists in main_workflow_schema.json
  • Missing from: docs/src/content/docs/reference/frontmatter.md
• import-schema
  • Supported and documented in docs/src/content/docs/reference/imports.md, but not surfaced in the main frontmatter reference.

Why this matters: frontmatter.md reads like the authoritative frontmatter index. Users consulting only that page can miss valid supported fields.

Action: Either:

• add sections for these fields to frontmatter.md, or
• explicitly scope frontmatter.md as a partial guide and link a canonical complete field index.

Schema Improvements Needed

4. Precomputed workflow field-gap data over-reports "schema violations" because it treats nested keys as top-level keys

• Precomputed data: /tmp/gh-aw/agent/schema-diff.json lists field_gaps.in_used_not_schema values such as title, repo, noop, try, else, create-pull-request, and capabilities.
• Repository evidence:
  • .github/workflows/code-scanning-fixer.md:169 has create-pull-request: as a nested safe-outputs handler, not a top-level field.
  • .github/workflows/daily-safeoutputs-git-simulator.md:304 has noop: inside safe-output config/content, not as a top-level frontmatter key.
  • .github/workflows/dataflow-pr-discussion-dataset.md:587 and several others use try: / else: in markdown body structures, not as top-level frontmatter schema keys.
  • .github/workflows/daily-agent-of-the-day-blog-writer.md contains title: / authors: in a discussion payload block, not top-level frontmatter.
• Why this matters: A naive workflow-vs-schema report can create false positives and waste review time.
• Action: Tighten the extractor that populates used_in_workflows so it only captures top-level frontmatter keys from the YAML header, not nested config blocks or markdown-body YAML-like content.

Parser Updates Required

No parser bug was proven in this run for the inspected fields (ambient-folders, runs-on-slim, check-for-updates, threat-detection-suppress, import-schema). Those looked internally consistent across schema and implementation.

The main code-level follow-up is to verify the strict-mode default in the regular CLI compile path.

Workflow Violations

No confirmed real workflow schema violations were established from repository workflows in this run.

The strongest workflow-related observation was that the precomputed used_in_workflows / in_used_not_schema set contains many false positives caused by nested keys and body content.

Recommendations

1. Audit strict-mode defaulting in the regular CLI compile path and align it with schema/docs/MCP behavior.
2. Clarify redirect: docs to describe redirect-only placeholder compilation behavior precisely.
3. Expand frontmatter.md coverage for implemented top-level fields such as max-turn-cache-misses, excluded-env, and import-schema (or clearly mark the page as partial).
4. Fix the workflow key extractor used to generate schema-diff reports so it only records top-level frontmatter keys.
5. Keep AWF drift findings informational only while canonical-source retrieval remains degraded.

Strategy Performance

• Strategy Used: Precomputed field-gap + targeted validation check
• Findings: 4
• Effectiveness: HIGH
• Should Reuse: YES

Why it worked:

• Starting from /tmp/gh-aw/agent/schema-diff.json quickly eliminated low-value enumeration work.
• Targeted follow-up on a few fields (strict, redirect, max-turn-cache-misses, import-schema) was enough to produce actionable findings.
• It also exposed quality issues in the precomputed diff itself.

Next Steps

• Verify and, if needed, fix strict-mode defaulting for normal CLI compilation
• Update redirect: documentation to match compile behavior
• Add missing field coverage to docs/src/content/docs/reference/frontmatter.md
• Refine schema-diff workflow key extraction to avoid nested/body false positives

Generated by ✅ Schema Consistency Checker · gpt54 · 29.6 AIC · ⌖ 11.7 AIC · ⊞ 8.9K · ◷

• expires on Aug 20, 2026, 9:37 PM UTC-08:00