[Schema Consistency] 🔍 Schema Consistency Check - 2026-10-28

[github-actions[bot]]

Overview

Found 3 actionable documentation inconsistencies across schema, parser/compiler, documentation, and workflow analysis at commit e75f0a24487015b1c384f64498c05266559f39ed. No source files were changed.

• Strategy: Schema-def spot checks + targeted parser/doc/workflow verification (cached strategy-2).
• New strategy: No; day 301 modulo 10 = 1 selects a proven strategy. Previously cached findings were excluded.
• Workflow sample: 349 top-level workflow frontmatters checked; zero schema errors after excluding root required-field errors. This is structural validation, not a compilation or runtime guarantee.
• Priority: One security-related documentation gap and two broken authoring examples. No critical runtime bug established.

Key Issues

1. Security-related documentation gap: tools.github.refusal-labels is advertised but unsupported by the local authoring contract. docs/src/content/docs/reference/mcp-gateway.md:1617 describes label-based integrity demotion and gives examples at lines 1625 and 1636. The GitHub tool schema lists other guard fields around pkg/parser/schemas/main_workflow_schema.json:5131–5185, but contains no refusal-labels; neither does pkg/workflow contain that field. Guard parsing in pkg/workflow/tools_parser.go:306 and typed configuration in pkg/workflow/tools_types.go:435 implement trusted users and approval labels instead. A minimal example with min-integrity: approved plus refusal-labels: [review] fails schema validation; substituting approval-labels passes. Impact: Users cannot compile the documented configuration and may expect an unavailable exclusion control. Fix: Mark the feature as unavailable in current frontmatter docs, or implement and validate the schema/parser/serialization contract together before advertising support. This finding makes no claim about external gateway capabilities.

2. FAQ MCP example puts server configuration under an unsupported key. docs/src/content/docs/reference/faq.md:227 shows tools.mcp-servers.my-server.image with a nested network allowlist. The schema rejects tools.mcp-servers as an additional property. The compiler extracts the separate frontmatter MCP server map at pkg/workflow/compiler_orchestrator_tools.go:231, and the typed field is defined at pkg/workflow/frontmatter_types.go:382. Existing shared usage at .github/workflows/shared/mcp/ast-grep.md:2 also uses root mcp-servers. Fix: Rewrite the example using root mcp-servers, the supported container property, and explicit allowed tools; show network configuration at its supported location separately. A root mcp-servers example with container and allowed: ["*"] passes local validation. Merely moving the FAQ block without correcting its server properties is insufficient.

3. Rate-limiting example places stop-after at the workflow root instead of under on. docs/src/content/docs/reference/rate-limiting-controls.md:46–52 advertises root stop-after: +48h. That exact shape fails validation with an unexpected-property error. The schema defines the field under trigger properties at pkg/parser/schemas/main_workflow_schema.json:2282; the implementation explicitly records extraction from on.stop-after at pkg/workflow/frontmatter_types.go:394. Fix: Show on: {workflow_dispatch: {}, stop-after: +48h} or an equivalent multiline mapping preserving the intended trigger. The corrected mapping passes validation.

Validation scope, false positives, and limitations

Evidence and Method

Started from the supplied precomputed schema diff rather than repeating field enumeration. Both reported top-level type gaps are false positives: docker-image-pull-policy is read from RawFrontmatter in pkg/workflow/docker.go:294; work-queue-policy is processed by pkg/workflow/work_queue_policy.go and repository conflict/deprecation logic in pkg/workflow/work_queue_repo_config.go. No corrective change is recommended for these gaps.

Validated reference-document YAML snippets with the local Draft7 schema and YAML loading that preserves the on key. Removed non-frontmatter examples, incomplete fragments, and previously cached findings from report candidates. Reduced each reported mismatch to an inert data example and checked a passing control. No workflow code was executed.

Checked all 349 parsable top-level workflow frontmatters for errors other than root required-field errors; none were observed. Required-field errors were excluded to avoid classifying redirects and import-oriented documents as standalone workflows. Shared-component coverage was targeted, including the root MCP configuration example above; full import expansion and whole-repository compilation were not performed. Thus no workflow violation is claimed, and required-field consistency is not certified.

AWF Canonical-Source Warning — Non-authoritative

The supplied awf-config-drift.json has degraded: true: canonical-source retrieval failed for docs/awf-config-spec.md, docs/awf-config.schema.json, and src/awf-config-schema.json. AWF config-source drift could not be established. No required-check failure, corrective pull request, or drift issue is recommended from that incomplete comparison.

Strategy Performance

• Findings: 3 new actionable inconsistencies.
• Effectiveness: High; schema counterexamples plus compiler evidence eliminated false positives.
• Reuse: Yes. Updated strategies.json with this run and its findings.

Recommendations and Next Steps

• Correct the FAQ MCP configuration and rate-limiting example.
• Align the refusal-label documentation with the currently implemented authoring contract.
• If implementing refusal-label support, update schema, parser, validation, and serialization together and add meaningful acceptance coverage.
• Add documentation-example validation that distinguishes frontmatter, fragments, repository configuration, and unrelated YAML.
• Revisit AWF drift only after canonical sources are available.

References: §40637878127

Generated by ✅ Schema Consistency Checker · codex · gpt61 · ~16 AIC · ⌖ ~7 AIC · ⊞ 19.7K · ◷

• expires on Oct 28, 2026, 9:31 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 #72873.