[Schema Consistency] Schema consistency check report - 2026-08-27

[github-actions[bot]]

🔍 Schema Consistency Check - 2026-08-27

Summary

• Inconsistencies Found: 4
• Categories Analyzed: Schema, Parser, Documentation, Workflows
• Strategy Used: Doc-claim contradiction audit
• New Strategy: YES
• AWF Config Drift Note: Canonical-source retrieval is degraded, so AWF config-source drift is reported only as a non-authoritative warning if mentioned.

Critical Issues

1. max-daily-ai-credits docs contradict schema and parser defaults

• Schema: pkg/parser/schemas/main_workflow_schema.json defines max-daily-ai-credits via $defs.max_daily_ai_credits_limit and the compiler falls back to a default when the field is omitted.
• Parser/Compiler: pkg/workflow/daily_aic_workflow.go says:
  • resolveMaxDailyAIC() falls back to constants.DefaultMaxDailyAICredits when no frontmatter/import value exists.
  • hasMaxDailyAICGuardrail() returns enabled unless the workflow explicitly sets -1.
• Documentation mismatch:
  • docs/src/content/docs/reference/frontmatter.md says: “This guardrail is disabled by default when omitted”.
  • docs/src/content/docs/reference/rate-limiting-controls.md says the default threshold is 5000 AIC.
  • Schema description says: “Omit the field to leave the guardrail disabled.”
• Impact: Users reading frontmatter.md or the schema can believe omission disables the guardrail, while compiler/runtime behavior appears to enable a default threshold.

2. max-daily-ai-credits scope is documented as workflow-wide, but schema text says per triggering user

• Schema: $defs.max_daily_ai_credits_limit says “for runs of this workflow by the triggering user”.
• Documentation:
  • docs/src/content/docs/reference/frontmatter.md: “cap for a single workflow, aggregated across recent runs of the same workflow in the repository.”
  • docs/src/content/docs/reference/glossary.md: “aggregated across all recent runs of the same workflow in the repository.”
• Impact: This is a semantic mismatch on who is counted toward the budget. It changes operator expectations for shared workflows and incident response.

3. user-rate-limit.events fallback behavior is broader in docs/schema than in parser

• Schema: user-rate-limit.events says if omitted, rate limiting applies to all programmatically triggered events.
• Documentation:
  • docs/src/content/docs/reference/frontmatter.md: events are inferred from on: when omitted.
  • docs/src/content/docs/reference/frontmatter-full.md: same idea.
• Parser: pkg/workflow/role_checks.go only infers from a fixed allowlist of triggers present in on:. If on: is missing or contains no recognized programmatic triggers, config.Events can remain empty rather than “all programmatically triggered events”.
• Impact: Docs/schema imply broader automatic coverage than implementation guarantees.

4. user-rate-limit legacy aliases are implemented but not accepted by schema

• Parser: pkg/workflow/role_checks.go accepts legacy keys inside user-rate-limit:
  • max-runs-per-window
  • fallback max-runs
  • fallback max
• Documentation: docs/src/content/docs/reference/frontmatter.md states legacy max: and max-runs: are migrated automatically by gh aw fix.
• Schema: pkg/parser/schemas/main_workflow_schema.json requires max-runs-per-window and sets additionalProperties: false, so max and max-runs are invalid under the published schema.
• Impact: Real parser compatibility exceeds schema compatibility. Tooling that validates against schema alone will reject frontmatter the compiler still understands.

Documentation Gaps

• frontmatter.md and rate-limiting-controls.md disagree on whether max-daily-ai-credits is disabled by default or defaults to 5000 AIC.
• The schema and docs disagree on whether max-daily-ai-credits is aggregated per workflow or per triggering user.
• The schema says omitted user-rate-limit.events applies to all programmatic events, while parser behavior is trigger-inference-based.

Schema Improvements Needed

1. Align max-daily-ai-credits description with actual compiler behavior:
   • either document the default threshold explicitly,
   • or change runtime behavior so omission truly disables it.
2. Remove or correct “by the triggering user” wording if aggregation is workflow-wide.
3. Decide whether legacy user-rate-limit.max / max-runs should remain accepted:
   • if yes, schema should allow them (possibly deprecated),
   • if no, parser compatibility path should be narrowed or clearly documented as post-fix migration-only.
4. Clarify user-rate-limit.events fallback semantics in schema comments/descriptions.

Parser Updates Required

• Review pkg/workflow/daily_aic_workflow.go against docs/schema for omitted max-daily-ai-credits handling.
• Review pkg/workflow/role_checks.go fallback semantics for user-rate-limit.events and decide whether empty inference should mean “all applicable programmatic events” or “no explicit event filter”.
• Decide whether legacy max / max-runs aliases in user-rate-limit are intended long-term compatibility or temporary migration support.

Workflow Violations

• No top-level schema/workflow key drift was found from the precomputed diff.
• Current repository workflows actively use:
  • max-daily-ai-credits (e.g. .github/workflows/daily-yamllint-fixer.md)
  • user-rate-limit (e.g. .github/workflows/workflow-generator.md)
• These workflows therefore depend on the ambiguous behaviors above, especially for operator expectations and external schema validation.

Recommendations

1. Make one source of truth for max-daily-ai-credits default behavior and update schema, docs, and compiler comments together.
2. Standardize the aggregation scope text for max-daily-ai-credits across schema, docs, and code comments.
3. Either encode user-rate-limit legacy aliases in schema as deprecated forms or remove parser acceptance after migration tooling is confirmed sufficient.
4. Update docs/schema to match the actual user-rate-limit.events inference model, or change parser behavior to honor the broader documented promise.

Strategy Performance

• Strategy Used: Doc-claim contradiction audit
• Findings: 4
• Effectiveness: HIGH
• Should Reuse: YES

Next Steps

• Fix max-daily-ai-credits default-behavior wording across schema and docs
• Confirm intended aggregation scope for max-daily-ai-credits
• Align user-rate-limit legacy alias support between schema and parser
• Clarify user-rate-limit.events fallback semantics

Generated by ✅ Schema Consistency Checker · pi · gpt54 · 22.5 AIC · ⌖ 9.92 AIC · ⊞ 8.9K · ◷

• expires on Aug 28, 2026, 12:07 AM UTC-08:00