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

[github-actions[bot]]

🔍 Schema Consistency Check - 2026-08-19

Summary

• Inconsistencies Found: 4
• Categories Analyzed: Schema, Parser, Documentation, Workflows
• Strategy Used: Field-gap follow-up with targeted parser/doc verification
• New Strategy: NO
• AWF config drift note: Canonical-source comparison was unavailable (awf-config-drift.json has degraded: true), so no AWF drift findings are treated as authoritative.

Critical Issues

1. safe-outputs.runs-on type mismatch: schema allows full runner forms, parser stores string only

• Schema: pkg/parser/schemas/main_workflow_schema.json defines safe-outputs.runs-on via #/$defs/github_actions_runs_on, which supports string, array, and runner-group object forms.
• Parser: pkg/workflow/safe_outputs_config_types.go defines SafeOutputsConfig.RunsOn string \yaml:"runs-on,omitempty"``.
• Documentation:
  • docs/src/content/docs/reference/frontmatter.md says safe-outputs.runs-on accepts the same forms as runs-on.
  • docs/src/content/docs/reference/safe-outputs.md shows an array example: runs-on: [self-hosted, linux, x64].
• Impact: valid schema/doc configurations may be misparsed, dropped, or narrowed at compile time when users provide array/object runner specs.
• Recommended fix: change parser/storage for safe-outputs.runs-on to the same flexible type used for top-level runs-on / runs-on-slim, then add a regression test for array and object forms.

2. threat-detection-suppress is implemented and schema-validated but effectively undocumented in the user-facing frontmatter guide

• Schema: top-level field exists with strict shape (rule, reason, optional expires).
• Parser: pkg/workflow/threat_detection_suppression.go validates:
  • rule must match CTR-###
  • reason must be non-empty
  • expires must be YYYY-MM-DD
• Docs gap:
  • docs/src/content/docs/reference/frontmatter.md does not describe the field.
  • docs/src/content/docs/reference/frontmatter-full.md only includes generated skeleton lines near the top, without practical semantics or usage guidance.
• Impact: users can discover the field in schema/generated reference, but not when or how to use it safely.
• Recommended fix: add a dedicated section in frontmatter.md describing intent, required fields, expiry behavior, and the audit expectations around suppressions.

Documentation Gaps

3. Deprecated top-level max-runs exists in schema/parser/docs glossary, but is missing from the main frontmatter guide

• Schema: max-runs is still accepted, marked deprecated, default 500.
• Parser: pkg/workflow/frontmatter_types.go still accepts max-runs; pkg/workflow/engine.go reads it as a fallback alias.
• Docs:
  • docs/src/content/docs/reference/glossary.md documents max-runs as deprecated.
  • docs/src/content/docs/reference/frontmatter.md documents max-turns and rate-limit max-runs-per-window, but does not clearly call out top-level max-runs as a deprecated alias in the main frontmatter reference.
• Impact: users reading only the main frontmatter page may not realize old workflows still compile or should be migrated.
• Recommended fix: add one sentence in the max-turns/credits area of frontmatter.md noting that top-level max-runs remains accepted as a deprecated alias and should be migrated with gh aw fix.

4. check-for-updates strict-mode behavior is documented, but the linked dedicated page appears missing from the docs corpus scanned here

• Schema: description points to https://github.github.com/gh-aw/reference/frontmatter/#check-for-updates.
• Parser: pkg/workflow/strict_mode_update_check_validation.go enforces:
  • false is rejected in strict mode
  • false emits only a warning in non-strict mode
• Docs:
  • docs/src/content/docs/reference/frontmatter.md has a section for check-for-updates.
  • Source comments reference https://github.github.com/gh-aw/reference/check-for-updates/, but no corresponding reference doc was surfaced in the scanned docs set.
• Impact: the code comments imply a standalone explainer/reference page that may not exist or may have moved, which can lead to stale maintenance breadcrumbs.
• Recommended fix: either add the dedicated page or update code comments to reference the canonical existing frontmatter section.

Schema Improvements Needed

1. Align safe-outputs.runs-on schema and parser contract with a shared runner type across all runner-bearing fields.
2. Consider adding stronger generated descriptions/examples for threat-detection-suppress in schema if the main prose docs remain intentionally brief.
3. Keep deprecated fields like max-runs visible in the main reference path, not only in glossary/generated pages.

Parser Updates Required

1. Update pkg/workflow/safe_outputs_config_types.go and downstream consumers so safe-outputs.runs-on can accept string, array, and object forms.
2. Add tests covering parity between:
   • runs-on
   • runs-on-slim
   • safe-outputs.runs-on
3. Keep comment/documentation references in strict_mode_update_check_validation.go synchronized with the real docs location.

Workflow Violations

No confirmed repository workflow violations against the main schema were established from the targeted checks. The precomputed used_in_workflows list includes many markdown-body/tool payload keys (for example repo, title, task, noop) that are not reliable frontmatter drift signals by themselves.

Recommendations

1. Treat safe-outputs.runs-on as the highest-priority fix because it is a true schema ↔ parser ↔ docs contract mismatch.
2. Add a user-facing threat-detection-suppress section to docs/src/content/docs/reference/frontmatter.md with one minimal example.
3. Add a short deprecation note for top-level max-runs in the main frontmatter guide.
4. Normalize stale doc links in code comments so maintainers follow the actual canonical page.

Strategy Performance

• Strategy Used: Field-gap follow-up with targeted parser/doc verification
• Findings: 4
• Effectiveness: HIGH
• Should Reuse: YES

Next Steps

• Fix safe-outputs.runs-on parser typing
• Add regression tests for array/object runner forms in safe outputs
• Update frontmatter docs for threat-detection-suppress
• Add deprecated max-runs note to the main frontmatter guide
• Reconcile check-for-updates code comment links with current docs

Generated by ✅ Schema Consistency Checker · gpt54 · 22.7 AIC · ⌖ 5.02 AIC · ⊞ 8.9K · ◷

• expires on Aug 19, 2026, 9:36 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 #54161.