[Schema Consistency] Schema Consistency Check — 2026-11-02: three documentation contract mismatches

[github-actions[bot]]

🔍 Schema Consistency Check — 2026-11-02

Three actionable inconsistencies found across documentation examples and accepted configuration. No critical runtime bug established. Analysis covered schema, parser/compiler, reference documentation, and repository workflow/shared frontmatter.

• Strategy: Schema-def spot checks + targeted parser/doc/workflow verification (reused; day-of-year modulo 10 = 6).
• Validation: Three inert JSON counterexamples rejected by local Draft7 validation; all three corrected controls accepted. Root required fields were excluded to validate fragments.
• Workflow scope: 472 frontmatter blocks scanned for these three patterns; zero matches. This is a targeted check, not a full compilation or all-field consistency certification.

Key Findings

1. Retired GitHub repository alias remains documented (medium). cross-repository.md:70–88 advertises tools.github.allowed-repos: current and claims normalization to the current repository expression. The schema accepts only all, public, ${{ github.repository }}, or arrays. The migration codemod explicitly replaces the legacy alias with the accepted expression. Impact: copying the documented example fails validation. Fix: replace the alias and remove the normalization claim; link the migration guidance.

2. Dispatch examples omit the required workflow allowlist (medium). faq.md:185 shows only max: 1; rate-limiting-controls.md:104 shows only environment: production. Both fragments fail schema validation. dispatch_workflow_validation.go:29 explicitly rejects an empty workflow list. Impact: users cannot compile either example as presented. Fix: add workflows: [worker-name] to both examples and explain that the named worker must exist. Preserve the allowlist requirement.

3. Reusable-worker example promises unsupported choice inputs (medium). safe-outputs.md:1543 declares on.workflow_call.inputs.environment.type: choice with options and lists choice as supported. The workflow_call schema permits only string, number, and boolean, and disallows the options property. The generic input schema builder handles choice, but that does not make it valid in a workflow_call trigger. Impact: the documented Markdown worker fails schema validation. Fix: use type: string, remove options, and describe validation in the worker. Any proposed choice extension needs explicit lowering to valid reusable-workflow inputs and tests.

Evidence, exclusions, and analysis limits

Schema ↔ Parser

The precomputed top-level gaps are false positives: docker-image-pull-policy is consumed through RawFrontmatter in pkg/workflow/docker.go:294, and work-queue-policy is consumed in pkg/workflow/work_queue_policy.go:184. No corrective parser change is justified by those gaps.

Validation Controls

• GitHub allowed-repos: current rejected; ${{ github.repository }} accepted.
• Dispatch: {max: 1} rejected; {max: 1, workflows: [worker]} accepted.
• workflow_call environment input: {type: choice, options: [dev, production]} rejected; {type: string} accepted.

Only static repository analysis and inert schema validation were performed. No workflow code was executed or dispatched. Existing cached findings were excluded from the new finding count. Source files were unchanged. References use main links and may move after this run.

AWF Canonical-Source Warning — Non-Authoritative

The supplied awf-config-drift.json reports degraded canonical-source retrieval. AWF config-source drift is therefore not established. This incomplete comparison must not drive a required-check failure, corrective PR, or drift issue.

Recommendations and Next Steps

• Correct the repository alias prose and example.
• Add explicit worker allowlists to both dispatch examples.
• Change the reusable-worker example to a string input and narrow the supported-type claim.
• Consider validating complete documentation examples against the appropriate schema branch, distinguishing fragments and non-workflow YAML.

Schema improvements / parser updates: none required for the conservative documentation fixes above. Workflow violations: none found for the selected patterns.

Strategy performance: 3 findings; high effectiveness; reuse recommended. Strategy cache updated with evidence and exclusions.

References: §41393769760

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

• expires on Nov 2, 2026, 9:29 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 #74403.