Description
user-rate-limit has two verified schema/parser/docs mismatches:
- Legacy aliases accepted by parser but rejected by schema.
pkg/workflow/role_checks.go:230-236 accepts max-runs-per-window, falling back to max-runs, falling back to max ("legacy compatibility"). But pkg/parser/schemas/main_workflow_schema.json:12337-12377 marks user-rate-limit with "required": ["max-runs-per-window"] and "additionalProperties": false — so max/max-runs are schema-invalid even though the parser still honors them and frontmatter.md claims gh aw fix auto-migrates them. Tooling that validates against the published schema will reject frontmatter the compiler actually accepts.
events fallback semantics diverge. The schema (main_workflow_schema.json:12360-12367) and frontmatter.md/frontmatter-full.md all say omitting events applies rate limiting to "all programmatically triggered events." But pkg/workflow/role_checks.go only infers events from a fixed allowlist actually present in the workflow's on: block — if on: has no recognized programmatic triggers, the effective event set can end up empty rather than "all," which is narrower than what docs/schema promise.
Expected Impact
Prevents external schema-validation tooling from flagging valid, parser-accepted frontmatter as invalid, and closes a behavior gap where the documented "applies to all programmatic events" fallback can silently under-apply.
Suggested Fix
- Decide whether
max/max-runs are permanent aliases or migration-only; if permanent, add them to the schema (as deprecated) so schema-validating tools don't reject compiler-accepted frontmatter — otherwise update frontmatter.md to say gh aw fix migration is required, not automatic-and-silent.
- Either broaden
role_checks.go's event inference to genuinely cover "all programmatic events" when on: lacks a recognized trigger, or narrow the schema/docs wording to describe the actual allowlist-based inference.
Suggested Agent
Repository Quality / deep-report doc-drift fixer.
Estimated Effort
Medium (1-4 hours) — item 1 is a schema-only fix; item 2 requires a parser-behavior decision.
Data Source
DeepReport Intelligence Briefing analysis, 2026-08-27 cycle (window since discussion #56215). Source: Schema Consistency Checker report #56291, findings 3-4.
Generated by 🔬 Deep Report · claude · agent · 153.6 AIC · ⌖ 8.47 AIC · ⊞ 12.4K · ◷
Description
user-rate-limithas two verified schema/parser/docs mismatches:pkg/workflow/role_checks.go:230-236acceptsmax-runs-per-window, falling back tomax-runs, falling back tomax("legacy compatibility"). Butpkg/parser/schemas/main_workflow_schema.json:12337-12377marksuser-rate-limitwith"required": ["max-runs-per-window"]and"additionalProperties": false— somax/max-runsare schema-invalid even though the parser still honors them andfrontmatter.mdclaimsgh aw fixauto-migrates them. Tooling that validates against the published schema will reject frontmatter the compiler actually accepts.eventsfallback semantics diverge. The schema (main_workflow_schema.json:12360-12367) andfrontmatter.md/frontmatter-full.mdall say omittingeventsapplies rate limiting to "all programmatically triggered events." Butpkg/workflow/role_checks.goonly infers events from a fixed allowlist actually present in the workflow'son:block — ifon:has no recognized programmatic triggers, the effective event set can end up empty rather than "all," which is narrower than what docs/schema promise.Expected Impact
Prevents external schema-validation tooling from flagging valid, parser-accepted frontmatter as invalid, and closes a behavior gap where the documented "applies to all programmatic events" fallback can silently under-apply.
Suggested Fix
max/max-runsare permanent aliases or migration-only; if permanent, add them to the schema (as deprecated) so schema-validating tools don't reject compiler-accepted frontmatter — otherwise updatefrontmatter.mdto saygh aw fixmigration is required, not automatic-and-silent.role_checks.go's event inference to genuinely cover "all programmatic events" whenon:lacks a recognized trigger, or narrow the schema/docs wording to describe the actual allowlist-based inference.Suggested Agent
Repository Quality / deep-report doc-drift fixer.
Estimated Effort
Medium (1-4 hours) — item 1 is a schema-only fix; item 2 requires a parser-behavior decision.
Data Source
DeepReport Intelligence Briefing analysis, 2026-08-27 cycle (window since discussion #56215). Source: Schema Consistency Checker report #56291, findings 3-4.