[Schema Consistency] Schema consistency check - 2026-09-02

[github-actions[bot]]

🔍 Schema Consistency Check - 2026-09-02

Summary

• Inconsistencies Found: 4
• Categories Analyzed: Schema, Parser, Documentation, Workflows
• Strategy Used: Schema-def spot checks + targeted parser/doc/workflow verification
• New Strategy: No
• AWF config-source drift: Canonical source unavailable (degraded: true in /tmp/gh-aw/agent/awf-config-drift.json), so no AWF drift findings below should be treated as authoritative.

Critical Issues

1. max-daily-ai-credits default behavior disagrees between schema, parser, and docs

• Schema/docs claim: pkg/parser/schemas/main_workflow_schema.json describes max-daily-ai-credits as omitted = disabled, and docs/src/content/docs/reference/frontmatter.md plus docs/src/content/docs/reference/cost-management.md repeat that claim.
• Parser/compiler behavior: pkg/workflow/daily_aic_workflow.go enables the guardrail by default unless the workflow explicitly sets -1.
  • resolveMaxDailyAIC() falls back to BuildDefaultMaxDailyAICreditsExpression(constants.DefaultMaxDailyAICredits) when the field is omitted.
  • hasMaxDailyAICGuardrail() returns !hasWorkflowExplicitMaxDailyAICDisable(data), so omission still enables the guardrail.
• Workflow reality: many workflows set max-daily-ai-credits, but the current implementation still means omission does not disable the feature.
• Impact: users relying on docs/schema can accidentally get a live API-expensive guardrail they thought was off.

2. max-daily-ai-credits aggregation scope is documented as per-workflow or per-user depending on file

• Frontmatter docs: docs/src/content/docs/reference/frontmatter.md says the limit is "for a single workflow, aggregated across recent runs of the same workflow in the repository."
• Generated full reference: docs/src/content/docs/reference/frontmatter-full.md says "24-hour AI Credits guardrail for runs triggered by the same user."
• Implementation/docs elsewhere: docs/src/content/docs/reference/cost-management.md agrees with the per-workflow aggregation model, not the per-user model.
• Impact: operators may mis-estimate enforcement and API cost, especially for shared workflows run by multiple actors.

Documentation Gaps

3. secret-masking is present in schema and implementation but missing from the human frontmatter reference

• Schema: pkg/parser/schemas/main_workflow_schema.json defines top-level secret-masking.steps.
• Parser/compiler: pkg/workflow/secret_masking.go extracts and merges secret-masking; pkg/workflow/frontmatter_types.go has SecretMasking *SecretMaskingConfig.
• Docs gap: docs/src/content/docs/reference/frontmatter.md does not have a secret-masking section, while frontmatter-full.md and imports.md do mention it.
• Impact: the primary hand-written frontmatter reference is incomplete for a supported top-level field.

Schema Improvements Needed

4. max-tool-denials schema accepts templated expressions, but parser silently treats expression values as unset

• Schema/docs claim: pkg/parser/schemas/main_workflow_schema.json and docs/src/content/docs/reference/frontmatter.md/frontmatter-full.md say max-tool-denials supports GitHub Actions expressions.
• Parser behavior:
  • pkg/workflow/engine_config_parser.go routes max-tool-denials through parseIntOrExpressionValue, which preserves expressions.
  • But FrontmatterConfig.MaxToolDenials is *TemplatableInt32, while other runtime paths consume strings; this split is easy to misuse.
  • More importantly, analogous integer-only handling for max-turn-cache-misses explicitly rejects expressions by treating them as unset, so the docs need to call out where expressions are runtime-supported vs compile-time-only and keep that distinction consistent.
• Impact: this is a lower-confidence but still actionable consistency risk: the family of budget/limit fields is documented inconsistently, and neighboring fields behave differently enough that users can easily misconfigure them.

Parser Updates Required

1. Decide the intended omitted behavior for max-daily-ai-credits, then make all three agree:
   • schema description,
   • frontmatter/cost docs,
   • pkg/workflow/daily_aic_workflow.go fallback logic.
2. Regenerate frontmatter-full.md after fixing the source schema comments/descriptions for max-daily-ai-credits.
3. Add explicit frontmatter reference coverage for secret-masking in docs/src/content/docs/reference/frontmatter.md.
4. Audit all numeric guardrail fields for consistent expression support language, especially max-tool-denials vs max-turn-cache-misses.

Workflow Violations

• No top-level workflow keys were found outside the schema (field_gaps.in_used_not_schema was empty).
• Representative workflows use max-daily-ai-credits heavily, which increases the risk of the documentation drift above because users will copy those patterns.

Recommendations

1. Fix the max-daily-ai-credits contract first — it is the most user-visible mismatch and changes runtime behavior.
2. Regenerate and diff frontmatter-full.md after any schema comment updates; the generated file currently preserves stale wording about "same user" aggregation.
3. Add a concise secret-masking section to frontmatter.md with one example and a link to the fuller reference.
4. Create a guardrail-field consistency test that compares documented default/aggregation wording for max-ai-credits, max-daily-ai-credits, max-tool-denials, and max-turn-cache-misses against the implementation.

Strategy Performance

• Strategy Used: Schema-def spot checks + targeted parser/doc/workflow verification
• Findings: 4
• Effectiveness: High
• Should Reuse: Yes

Next Steps

• Fix max-daily-ai-credits default semantics in either code or docs/schema
• Align frontmatter-full.md wording with actual aggregation scope
• Document secret-masking in frontmatter.md
• Review neighboring guardrail fields for expression-support consistency

Generated by ✅ Schema Consistency Checker · pi · gpt54 · 48.8 AIC · ⌖ 9.82 AIC · ⊞ 8.8K · ◷

• expires on Sep 2, 2026, 9:39 PM UTC-08:00