Description
Schema Consistency Checker (discussion #54161) found two related doc gaps in docs/src/content/docs/reference/frontmatter.md:
- It states
gh aw compile emits an informational message "when a redirect is configured," but the compiler (pkg/workflow/compiler_orchestrator_frontmatter.go) only treats a file as redirect-only when it has redirect and no on field — ordinary workflows combining both redirect: and on: (e.g. .github/workflows/ai-moderator.md:3) aren't obviously covered the same way. Docs should distinguish the redirect-only-placeholder case from the general case.
- Several implemented top-level frontmatter fields —
max-turn-cache-misses, excluded-env, import-schema — have no coverage in frontmatter.md at all (or the page should be explicitly marked partial).
Expected Impact
Removes two documented-but-inaccurate/incomplete claims from the primary frontmatter reference page, reducing confusion for anyone relying on it to understand redirect: behavior or discover these existing fields.
Suggested Agent
Documentation-focused agent — update docs/src/content/docs/reference/frontmatter.md to (a) clarify redirect:-only vs redirect: + on: compile behavior against the actual code in pkg/workflow/compiler_orchestrator_frontmatter.go / compiler_orchestrator_workflow.go, and (b) add entries for max-turn-cache-misses, excluded-env, import-schema.
Estimated Effort
Quick (< 1 hour)
Data Source
DeepReport Intelligence analysis, 2026-08-20 cycle, based on Schema Consistency Checker discussion #54161.
Generated by 🔬 Deep Report · agent · 175.8 AIC · ⌖ 9.08 AIC · ⊞ 11.9K · ◷
Description
Schema Consistency Checker (discussion #54161) found two related doc gaps in
docs/src/content/docs/reference/frontmatter.md:gh aw compileemits an informational message "when aredirectis configured," but the compiler (pkg/workflow/compiler_orchestrator_frontmatter.go) only treats a file as redirect-only when it hasredirectand noonfield — ordinary workflows combining bothredirect:andon:(e.g..github/workflows/ai-moderator.md:3) aren't obviously covered the same way. Docs should distinguish the redirect-only-placeholder case from the general case.max-turn-cache-misses,excluded-env,import-schema— have no coverage infrontmatter.mdat all (or the page should be explicitly marked partial).Expected Impact
Removes two documented-but-inaccurate/incomplete claims from the primary frontmatter reference page, reducing confusion for anyone relying on it to understand
redirect:behavior or discover these existing fields.Suggested Agent
Documentation-focused agent — update
docs/src/content/docs/reference/frontmatter.mdto (a) clarifyredirect:-only vsredirect:+on:compile behavior against the actual code inpkg/workflow/compiler_orchestrator_frontmatter.go/compiler_orchestrator_workflow.go, and (b) add entries formax-turn-cache-misses,excluded-env,import-schema.Estimated Effort
Quick (< 1 hour)
Data Source
DeepReport Intelligence analysis, 2026-08-20 cycle, based on Schema Consistency Checker discussion #54161.