Description
Two top-level frontmatter fields are declared in the JSON schema and used in real workflows, but missing from the typed FrontmatterConfig struct in pkg/workflow/frontmatter_types.go:
ambient-folders — schema: main_workflow_schema.json:536; runtime handling exists in pkg/workflow/ambient_folders.go (reads straight from the raw frontmatter map[string]any, e.g. line 42 frontmatter["ambient-folders"]); documented in docs/src/content/docs/reference/frontmatter.md:144-149; used in .github/workflows/shared/squad.md:30. No AmbientFolders field exists on FrontmatterConfig.github-app (top-level auth fallback) — schema: main_workflow_schema.json:12309, described as "Top-level GitHub App configuration used as a fallback for all nested github-app token minting operations"; documented in docs/src/content/docs/reference/frontmatter.md:158-172. FrontmatterConfig only has a GitHubApp *OTLPGitHubAppConfig field nested inside OTLPConfig (frontmatter_types.go:299, a different github-app key scoped to OTLP auth) — there is no top-level GitHubApp field on FrontmatterConfig itself.
Both gaps were surfaced by this week's Schema Consistency Checker (discussion #53057) and verified directly against current source for this report.
Expected Impact
Any code path that consumes the typed FrontmatterConfig (instead of the raw frontmatter map) currently cannot see these two real, documented, schema-valid features — silently dropping them for typed consumers. Adding the fields closes the type/schema/doc drift and prevents a future typed-consumer feature from silently no-op'ing on these keys.
Suggested Agent
New Agent (Go struct + schema alignment)
Estimated Effort
Quick (< 1 hour)
Data Source
DeepReport analysis, 2026-08-16 cycle, sourced from discussion #53057 (Schema Consistency Checker) and verified directly against pkg/workflow/frontmatter_types.go and pkg/parser/schemas/main_workflow_schema.json.
Generated by 🔬 Deep Report · agent · 257.9 AIC · ⌖ 11 AIC · ⊞ 11.8K · ◷
Description
Two top-level frontmatter fields are declared in the JSON schema and used in real workflows, but missing from the typed
FrontmatterConfigstruct inpkg/workflow/frontmatter_types.go:ambient-folders— schema:main_workflow_schema.json:536; runtime handling exists inpkg/workflow/ambient_folders.go(reads straight from the rawfrontmatter map[string]any, e.g. line 42frontmatter["ambient-folders"]); documented indocs/src/content/docs/reference/frontmatter.md:144-149; used in.github/workflows/shared/squad.md:30. NoAmbientFoldersfield exists onFrontmatterConfig.github-app(top-level auth fallback) — schema:main_workflow_schema.json:12309, described as "Top-level GitHub App configuration used as a fallback for all nested github-app token minting operations"; documented indocs/src/content/docs/reference/frontmatter.md:158-172.FrontmatterConfigonly has aGitHubApp *OTLPGitHubAppConfigfield nested insideOTLPConfig(frontmatter_types.go:299, a differentgithub-appkey scoped to OTLP auth) — there is no top-levelGitHubAppfield onFrontmatterConfigitself.Both gaps were surfaced by this week's Schema Consistency Checker (discussion #53057) and verified directly against current source for this report.
Expected Impact
Any code path that consumes the typed
FrontmatterConfig(instead of the raw frontmatter map) currently cannot see these two real, documented, schema-valid features — silently dropping them for typed consumers. Adding the fields closes the type/schema/doc drift and prevents a future typed-consumer feature from silently no-op'ing on these keys.Suggested Agent
New Agent (Go struct + schema alignment)
Estimated Effort
Quick (< 1 hour)
Data Source
DeepReport analysis, 2026-08-16 cycle, sourced from discussion #53057 (Schema Consistency Checker) and verified directly against
pkg/workflow/frontmatter_types.goandpkg/parser/schemas/main_workflow_schema.json.