[Schema Consistency] Schema Consistency Check - 2026-08-28

[github-actions[bot]]

🔍 Schema Consistency Check - 2026-08-28

🔍 Schema Consistency Check - 2026-08-28

Summary

• Inconsistencies Found: 4
• Categories Analyzed: Schema, Parser, Documentation, Workflows
• Strategy Used: Schema-def spot checks + targeted parser/doc/workflow verification
• New Strategy: No
• AWF config-source drift: Canonical-source retrieval was degraded in /tmp/gh-aw/agent/awf-config-drift.json; any drift conclusions would be non-authoritative, so none are asserted here.

Critical Issues

1. max-runs schema accepts 0, parser silently treats 0 as unset

• Schema: pkg/parser/schemas/main_workflow_schema.json defines max-runs via templatable_integer, whose integer branch allows minimum: 0.
• Parser/compiler: pkg/workflow/engine_config_parser.go routes max-runs through parsePositiveIntValue(raw, "max-runs"), which requires values >= 1; 0 becomes 0/unset.
• Docs: docs/src/content/docs/reference/frontmatter.md documents max-runs only as a deprecated alias for max-turns, and max-turns is described as a positive cap.
• Impact: A workflow can validate against schema with max-runs: 0 but the compiler will ignore it and fall back to defaults, creating schema/runtime disagreement.

References

• pkg/parser/schemas/main_workflow_schema.json (max-runs, $defs.templatable_integer)
• pkg/workflow/engine_config_parser.go:31-46
• pkg/workflow/engine.go:233-245
• docs/src/content/docs/reference/frontmatter.md:447-452

Documentation Gaps

2. User-facing frontmatter guide does not document max-tool-denials

• Schema: Top-level max-tool-denials is defined with default 5 and engine restrictions.
• Parser/compiler: Implemented in pkg/workflow/frontmatter_types.go, pkg/workflow/engine.go, and validated in pkg/workflow/agent_validation.go.
• Docs:
  • Present in generated schema reference: docs/src/content/docs/reference/frontmatter-full.md:3299-3308
  • Missing from user guide: docs/src/content/docs/reference/frontmatter.md has no max-tool-denials section.
• Impact: A real frontmatter field exists and is validated, but users reading the main guide will not discover it or its Copilot SDK-only constraint.

References

• pkg/workflow/frontmatter_types.go:362-365
• pkg/workflow/engine.go:238-245
• pkg/workflow/agent_validation.go:156-179
• docs/src/content/docs/reference/frontmatter-full.md:3299-3308

3. github-app docs claim fallback applies to dependencies, but frontmatter/schema surface does not expose a top-level dependencies field

• Docs: docs/src/content/docs/reference/frontmatter.md says the top-level github-app fallback applies to on, safe-outputs, checkout, tools.github, and dependencies.
• Schema/frontmatter: No top-level dependencies field exists in pkg/parser/schemas/main_workflow_schema.json or pkg/workflow/frontmatter_types.go.
• Impact: The guide suggests a frontmatter surface area that users cannot actually configure at top level, which is likely stale wording from an internal/runtime concept.

References

• docs/src/content/docs/reference/frontmatter.md:187-200
• pkg/parser/schemas/main_workflow_schema.json top-level properties
• pkg/workflow/frontmatter_types.go:345-467

Schema Improvements Needed

4. runs-on-slim schema/examples inherit generic GitHub Actions runner wording that still lists macOS-shaped examples, while compiler rejects macOS for agentic workflows

• Schema: runs-on-slim references the generic github_actions_runs_on definition; its dereferenced description includes examples like macos-latest in the generic prose for runner strings.
• Parser/compiler: pkg/workflow/runs_on_validation.go explicitly rejects macos / macos-* on both runs-on and runs-on-slim.
• Docs: The user guide correctly says macos-* is unsupported, but the schema-derived reference inherits more permissive generic runner text.
• Impact: Generated reference material can imply compatibility that the compiler forbids.

References

• pkg/parser/schemas/main_workflow_schema.json (runs-on-slim → $defs.github_actions_runs_on)
• pkg/workflow/runs_on_validation.go:35-82
• docs/src/content/docs/reference/frontmatter.md:389-409
• docs/src/content/docs/reference/frontmatter-full.md:1739-1758

Workflow Violations

• No .github/workflows/*.md examples in this repository currently use runs-on-slim, github-app, or check-for-updates at top level, so repository workflows do not presently demonstrate these mismatches.
• No workflow usage outside schema was found in the precomputed field_gaps.in_used_not_schema set.

Recommendations

1. Tighten schema/runtime parity for max-runs by changing its integer minimum to 1, or explicitly supporting 0 in parser semantics with documentation explaining the meaning.
2. Add a dedicated max-tool-denials section to docs/src/content/docs/reference/frontmatter.md, including the default (5) and the requirement for engine: copilot with engine.copilot-sdk: true.
3. Remove or clarify the dependencies claim in the top-level github-app docs unless a real frontmatter field or documented nested path exists for users.
4. Specialize the schema description/examples for runs-on-slim (or post-process the generated docs) so agentic-workflow restrictions do not inherit generic GitHub Actions/macOS-friendly wording.

Strategy Performance

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

Next Steps

• Fix schema definitions for max-runs or align parser behavior
• Update frontmatter.md to cover max-tool-denials
• Correct stale github-app fallback wording
• Align runs-on-slim schema-derived docs with compiler validation

Generated by ✅ Schema Consistency Checker · pi · gpt54 · 23 AIC · ⌖ 8.57 AIC · ⊞ 8.9K · ◷

• expires on Aug 29, 2026, 12:10 AM UTC-08:00