[Schema Consistency] Schema Consistency Check — 2026-10-21

[github-actions[bot]]

🔍 Schema Consistency Check — 2026-10-21

Three confirmed documentation inconsistencies affect configuration accepted by the schema/compiler. No critical runtime bug was established.

• Inconsistencies found: 3
• Categories analyzed: Schema, parser/compiler, documentation, workflows
• Strategy: Cached schema-definition spot checks plus targeted parser/doc/workflow verification; day 294 modulo 10 = 4 (proven strategy)
• New strategy: No; previously cached findings excluded
• Workflow validation: 346 root workflow frontmatters checked against the local Draft7 schema; zero schema errors. This does not establish successful compilation, import resolution, or runtime behavior.

Key Issues

1. High — tools.github.refusal-labels promises an unavailable authoring control. docs/src/content/docs/reference/mcp-gateway.md:1597 and :1608 show this configuration; the surrounding section promises label-based integrity demotion. An isolated configuration with min-integrity: approved and refusal-labels: [needs-security-review] fails schema validation with an unexpected-property error. The GitHub schema properties near pkg/parser/schemas/main_workflow_schema.json:5152 and compiler fields at pkg/workflow/tools_types.go:425 support approval labels but lack refusal labels; no compiler Go reference to refusal-labels was found. Impact: Authors cannot compile the documented suppression policy. Fix: Mark this as a proposed gateway capability unavailable in workflow frontmatter, or implement and test schema acceptance and end-to-end compiler forwarding together before advertising it. This finding concerns authoring support; gateway runtime enforcement was not tested.

2. Medium — OIDC frontmatter example puts custom MCP servers under the wrong parent. docs/src/content/docs/reference/mcp-gateway.md:1312 shows tools.mcp-servers.my-mcp-server. The schema rejects mcp-servers as an additional property of tools. Supported top-level mcp-servers is defined at pkg/parser/schemas/main_workflow_schema.json:4898, extracted at pkg/workflow/frontmatter_extraction_metadata.go:343, and merged with tools at pkg/workflow/tools.go:443. Impact: Copying the example fails schema validation before OIDC configuration can be used. Fix: Remove the tools wrapper and place mcp-servers at the frontmatter root; validate the corrected complete example.

3. Medium — PR review-comment example advertises unsupported footer. docs/src/content/docs/reference/safe-outputs-pull-requests.md:292 includes footer: if-body for create-pull-request-review-comment. The isolated option fails schema validation because footer is an additional property. The handler schema begins at pkg/parser/schemas/main_workflow_schema.json:9189 and closes with additionalProperties: false near :9273. pkg/workflow/create_pr_review_comment.go:10 and generated handler configuration at pkg/workflow/safe_outputs_handler_registry_pull_requests.go:190 contain no footer setting. Impact: The documented example cannot compile. Fix: Remove this option from the example, or add explicit schema/parser/handler support with behavior tests if footer control is intended.

Analysis details, exclusions, and limitations

Started from /tmp/gh-aw/agent/schema-diff.json and cached strategies. Both apparent schema-to-struct gaps were false positives: docker-image-pull-policy is consumed through RawFrontmatter in pkg/workflow/docker.go:294; work-queue-policy is consumed in pkg/workflow/work_queue_policy.go:184. The precomputed diff has no workflow keys missing from the schema.

Scanned reference-document YAML examples using a loader that preserves the YAML on key and recognizes true/false booleans; confirmed each reported rejection with a minimal inert JSON configuration and traced relevant compiler code. Excluded incomplete examples, other configuration formats, and findings recorded in prior strategy-cache results. No workflow scripts or runtime security controls were executed or probed. Root workflow validation covered .github/workflows/*.md; shared components were not independently certified as complete workflows.

Non-authoritative AWF warning: /tmp/gh-aw/agent/awf-config-drift.json reports degraded: true because canonical spec/schema retrieval failed. AWF drift cannot be concluded from this run. This warning is excluded from the inconsistency count and must not drive a required-check failure, corrective PR, or drift issue.

Schema improvements / parser updates: No standalone schema/compiler discrepancy was established by these three findings. If the documented features are intended, acceptance and implementation must change together. Otherwise documentation corrections suffice.

Strategy performance: 3 confirmed findings; high effectiveness; reuse recommended. Updated strategy-2 in the persistent strategy database. Repository source files were unchanged.

Recommendations and Next Steps

• Correct the OIDC MCP-server example placement.
• Remove unsupported review-comment footer configuration or implement it across schema and compiler.
• Clarify refusal-label availability; add schema/parser forwarding only with supported end-to-end behavior.
• Add documentation-example validation that distinguishes frontmatter, fragments, and other configuration formats.
• Repeat AWF comparison when canonical sources are available.

References: §39550062313

Generated by ✅ Schema Consistency Checker · codex · gpt61 · 16.9 AIC · ⌖ 6.93 AIC · ⊞ 19.6K · ◷

• expires on Oct 21, 2026, 9:37 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 #71050.