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

[github-actions[bot]]

Caution

agentic threat detected
Threat detection flagged this output in warn mode. Manual review is REQUIRED before any follow-up automation.

Details

Potential security threats were detected in the agent output.

Review the workflow run logs for details.

Summary

• Inconsistencies Found: 4
• Categories Analyzed: Schema, Parser/Compiler, Documentation, Workflows
• Strategy Used: Example-validation + high-signal field verification
• New Strategy: YES

Critical Issues

1. max-turn-cache-misses is in schema and implementation, but missing from the primary frontmatter reference page

   • Schema: pkg/parser/schemas/main_workflow_schema.json defines max-turn-cache-misses as an integer with default 5.
   • Implementation: pkg/workflow/engine.go parses frontmatter["max-turn-cache-misses"] and applies it to EngineConfig.MaxTurnCacheMisses.
   • Docs gap: docs/src/content/docs/reference/frontmatter.md has no mention of max-turn-cache-misses, while frontmatter-full.md does.
   • Impact: users reading the main reference page will not discover the feature and may assume it is unsupported.

2. Workflow examples use create-pull-request: as a top-level frontmatter key, but schema requires it under safe-outputs:

   • Schema: top-level properties do not include create-pull-request; it appears under safe-outputs.
   • Workflow examples: .github/workflows/dictation-prompt.md:43, .github/workflows/code-scanning-fixer.md:168, .github/workflows/unbloat-docs.md:75 contain create-pull-request: lines.
   • Impact: readers or automated scanners can misinterpret these examples as top-level frontmatter syntax even though they are nested configuration blocks.
   • Note: these appear to be nested body examples rather than real top-level frontmatter, so the inconsistency is documentation/example clarity rather than compiler behavior.

Documentation Gaps

1. Primary doc coverage is uneven between frontmatter.md and frontmatter-full.md

   • check-for-updates and runs-on-slim are documented in both places.
   • max-turn-cache-misses appears only in docs/src/content/docs/reference/frontmatter-full.md:3110 and is absent from docs/src/content/docs/reference/frontmatter.md.
   • Recommendation: add a short section or at least a cross-link in the primary page.

2. safe-outputs overview page does not expose key nested operations in the main frontmatter reference

   • docs/src/content/docs/reference/frontmatter.md mentions safe-outputs: only briefly and does not surface common nested operations such as noop or create-pull-request.
   • Meanwhile, real workflows use those nested operations frequently.
   • Impact: users may search the main frontmatter reference for those keys and conclude they are undocumented.

Schema Improvements Needed

1. Pre-computed field-gap data produces false positives for parser coverage
   • /tmp/gh-aw/agent/schema-diff.json reports every schema field under in_schema_not_parser because pkg/parser/frontmatter.go has no yaml-tagged structs.
   • Actual parsing/typing happens in workflow-layer structs such as pkg/workflow/frontmatter_types.go and map-based extraction code.
   • Impact: the current diff can mislead analysis by flagging healthy fields as missing.
   • Recommendation: compute parser/compiler coverage from JSON tags and extraction sites, not only YAML tags in pkg/parser/*.go.

Parser Updates Required

1. Reference comments point to a doc URL that differs from the schema/doc anchor style
   • Code comment: pkg/workflow/strict_mode_update_check_validation.go:11 points to https://github.github.com/gh-aw/reference/check-for-updates/.
   • Schema/docs use the frontmatter anchor style (/reference/frontmatter/#check-for-updates).
   • Impact: maintainers may update one canonical location while comments continue to point elsewhere.
   • Recommendation: standardize comments on the frontmatter anchor URL used by the schema description.

Workflow Violations

1. used_in_workflows contains many non-frontmatter keys because it scans whole markdown files, not just frontmatter
   • Examples from /tmp/gh-aw/agent/schema-diff.json: authors, date, task, try, else, title, repo.
   • These are present in workflow bodies and examples (for instance generated JSON/YAML snippets), not as top-level frontmatter.
   • Impact: the current workflow-vs-schema analysis over-reports violations and hides real mismatches.
   • Recommendation: restrict extraction to the YAML frontmatter block only.

Recommendations

1. Add max-turn-cache-misses to docs/src/content/docs/reference/frontmatter.md with a short explanation and link to the full reference.
2. Improve example extraction/validation so nested safe-outputs operations are not treated as top-level workflow keys.
3. Rework the pre-computed schema diff generator to inspect frontmatter blocks only and use workflow/compiler structs plus extraction code for coverage.
4. Standardize documentation links in code comments to the same canonical frontmatter anchors used in schema descriptions.

Strategy Performance

• Strategy Used: Example-validation + high-signal field verification
• Findings: 4
• Effectiveness: HIGH
• Should Reuse: YES

Next Steps

• Fix primary frontmatter docs to include omitted high-impact fields
• Tighten schema-diff generation to avoid parser/workflow false positives
• Clarify nested safe-outputs examples in workflow markdown
• Normalize code-comment documentation URLs

References:

• §30980502101

Generated by ✅ Schema Consistency Checker · gpt54 · 22.8 AIC · ⌖ 7.17 AIC · ⊞ 8.4K · ◷

• expires on Aug 5, 2026, 10:16 PM UTC-08:00

[github-actions[bot]]

This discussion was automatically closed because it expired on 2026-08-06T06:16:28.558Z.

Closed by Workflow