[Schema Consistency] Schema Consistency Check - 2026-08-17

[github-actions[bot]]

🔍 Schema Consistency Check - 2026-08-17

Summary

• Inconsistencies Found: 5
• Categories Analyzed: Schema, Parser, Documentation, Workflows
• Strategy Used: Precomputed field-gap triage + targeted parser/doc verification
• New Strategy: YES

Critical Issues

1. Top-level github-app is implemented and documented but missing from the main schema

   • Schema: pkg/parser/schemas/main_workflow_schema.json has no top-level github-app property.
   • Parser/compiler: pkg/workflow/frontmatter_types.go includes GitHubApp *GitHubAppConfig \json:"github-app,omitempty"`andpkg/workflow/workflow_github_app.goresolves it as a top-level fallback for activation, safe-outputs, checkout, andtools.github`.
   • Docs: docs/src/content/docs/reference/frontmatter.md contains a dedicated ### GitHub App (\github-app:`)` section.
   • Impact: schema-based validation and generated schema docs can reject or omit a real supported feature.

2. max-runs and max-turns exist in schema but are absent from typed frontmatter config

   • Schema diff: field_gaps.in_schema_not_frontmatter = ["max-runs", "max-turns"].
   • Parser/compiler: engine extraction still applies top-level overrides in pkg/workflow/engine.go (applyEngineTopLevelOverrides, buildTopLevelOnlyEngineConfig), so the feature exists behaviorally.
   • Typed config: pkg/workflow/frontmatter_types.go includes MaxAICredits, MaxTurnCacheMisses, MaxDailyAICredits, MaxToolDenials, but no top-level MaxRuns or MaxTurns fields on FrontmatterConfig.
   • Impact: typed parsing/introspection paths can silently diverge from schema and actual compiler behavior.

3. Undocumented parser aliases under user-rate-limit are accepted in code and used by workflows

   • Schema/frontmatter type: RateLimitConfig uses max-runs-per-window in pkg/workflow/frontmatter_types.go.
   • Parser: pkg/workflow/role_checks.go accepts max-runs-per-window, plus aliases max-runs, and legacy max.
   • Workflows: .github/workflows/ai-moderator.md and .github/workflows/auto-triage-issues.md use user-rate-limit.max:.
   • Impact: repo workflows rely on compatibility behavior that is not represented in the schema, so strict schema consumers would flag valid in-repo usage as invalid.

Documentation Gaps

1. User-facing frontmatter guide omits user-rate-limit entirely

   • docs/src/content/docs/reference/frontmatter.md: no matches for user-rate-limit or ignored-roles.
   • Parser/compiler support exists in pkg/workflow/frontmatter_types.go and pkg/workflow/role_checks.go.
   • Impact: a supported top-level control is effectively undiscoverable in the primary human-oriented reference.

2. Generated full frontmatter reference omits engine.extensions despite parser support and user-facing docs

   • Parser/compiler: pkg/workflow/engine.go parses engine.extensions; pkg/workflow/pi_engine.go uses it for Pi extension installation.
   • User docs: docs/src/content/docs/reference/frontmatter.md has ### Engine Extensions (\engine.extensions:`)`.
   • Generated schema reference: docs/src/content/docs/reference/frontmatter-full.md has no engine.extensions mention.
   • Impact: generated schema docs under-report a documented and implemented nested engine field, suggesting schema/doc generation drift.

Schema Improvements Needed

1. Add top-level github-app to pkg/parser/schemas/main_workflow_schema.json, aligned with the existing parser and docs.
2. Decide whether max-runs and max-turns should be first-class typed frontmatter fields or removed from the schema if they are intentionally engine-only legacy shims.
3. Either formalize user-rate-limit.max / user-rate-limit.max-runs aliases in schema/docs or migrate workflows off aliases and deprecate them explicitly.

Parser Updates Required

1. Add typed FrontmatterConfig fields for top-level max-runs and max-turns, or centralize these fields exclusively in engine config and stop advertising them at top level.
2. If alias support for user-rate-limit.max and max-runs is intentional, emit a deprecation warning during parse so users can migrate toward the canonical schema form.

Workflow Violations

1. .github/workflows/ai-moderator.md uses user-rate-limit.max: 5, which is parser-compatible but not schema-canonical.
2. .github/workflows/auto-triage-issues.md uses user-rate-limit.max: aliases, also parser-compatible but not schema-canonical.

AWF Config-Source Drift Note

• /tmp/gh-aw/agent/awf-config-drift.json reports degraded: true.
• Canonical AWF source retrieval was unavailable, so any AWF drift observations should be treated as non-authoritative warnings only.
• No corrective drift action is recommended from this run.

Recommendations

1. Make the main schema the source of truth again by adding top-level github-app and reconciling top-level max-runs / max-turns.
2. Document user-rate-limit in docs/src/content/docs/reference/frontmatter.md, including canonical keys and any deprecated aliases.
3. Align repository workflows with canonical schema names (max-runs-per-window) if alias support is meant to remain backward-compatible only.
4. Regenerate or fix schema-derived docs so frontmatter-full.md includes nested fields like engine.extensions.
5. Add regression tests that diff schema fields against typed FrontmatterConfig and selected parser aliases.

Strategy Performance

• Strategy Used: Precomputed field-gap triage + targeted parser/doc verification
• Findings: 5
• Effectiveness: HIGH
• Should Reuse: YES

Next Steps

• Fix schema definitions
• Update parser validation/typed config
• Update documentation
• Fix workflow files using non-canonical aliases

Generated by ✅ Schema Consistency Checker · gpt54 · 12.7 AIC · ⌖ 6.23 AIC · ⊞ 8.8K · ◷

• expires on Aug 17, 2026, 9:36 PM UTC-08:00

[github-actions[bot]]

This discussion was automatically closed because it expired on 2026-08-18T05:36:53.419Z.

Closed by Workflow