[Schema Consistency] Schema consistency check - 2026-08-16

[github-actions[bot]]

🔍 Schema Consistency Check - 2026-08-16

Summary

• Inconsistencies Found: 4
• Categories Analyzed: Schema, Parser, Documentation, Workflows
• Strategy Used: Precomputed gap + contradiction spot-check
• New Strategy: YES

Critical Issues

1. ambient-folders is implemented and documented, but missing from the typed frontmatter model

   • Schema: top-level ambient-folders exists in pkg/parser/schemas/main_workflow_schema.json:536.
   • Parser/compiler: runtime handling exists in pkg/workflow/ambient_folders.go:42-81.
   • Typed frontmatter model: pkg/workflow/frontmatter_types.go has no AmbientFolders field in FrontmatterConfig.
   • Docs/workflows: documented in docs/src/content/docs/reference/frontmatter.md:144-149, generated in docs/src/content/docs/reference/frontmatter-full.md:128, and used in .github/workflows/shared/squad.md:30.
   • Impact: any code path depending on FrontmatterConfig instead of the raw frontmatter map can silently miss a real supported feature.

2. Top-level github-app is in schema and docs, but missing from FrontmatterConfig

   • Schema: top-level github-app property exists in pkg/parser/schemas/main_workflow_schema.json:12309.
   • Docs: documented in docs/src/content/docs/reference/frontmatter.md:158-172 and generated in docs/src/content/docs/reference/frontmatter-full.md:20730-20769.
   • Typed frontmatter model: pkg/workflow/frontmatter_types.go includes many nested github-app mentions, but FrontmatterConfig itself has no top-level GitHubApp field.
   • Impact: typed consumers of frontmatter cannot see a documented top-level fallback auth feature even though the schema exposes it.

Documentation Gaps

1. max-turns documentation contradicts itself across docs and workflows

   • Schema: top-level max-turns is a first-class field in pkg/parser/schemas/main_workflow_schema.json:4043-4046.
   • Implementation: compiler and engine code apply it broadly (pkg/workflow/engine.go:241-248), and capability flags mark support across engines (for example pkg/workflow/copilot_engine.go:47, pkg/workflow/codex_engine.go:63, pkg/workflow/claude_engine.go:35).
   • Docs saying supported everywhere: docs/src/content/docs/reference/engines.md:51-63 says top-level max-turns is supported by Copilot, Claude, Codex, Gemini, and Pi.
   • Docs saying not supported for Copilot: the same file later says max-turns is unavailable for Copilot in docs/src/content/docs/reference/engines.md:534-549.
   • Workflow guidance also contradicts implementation:
     • .github/workflows/daily-community-attribution.md:588 says "This workflow uses the Copilot engine — max-turns is not available"
     • .github/workflows/agent-persona-explorer.md:37 says "max-turns not available for default Copilot engine"
   • Impact: authors may avoid a supported safety/cost-control feature or write misleading workflow instructions.

2. User-facing frontmatter guide omits top-level max-turns / deprecated max-runs sections despite schema support

   • Schema: both max-turns and deprecated max-runs exist (pkg/parser/schemas/main_workflow_schema.json:4043-4074).
   • Generated schema doc: includes max-turns examples in docs/src/content/docs/reference/frontmatter-full.md:3132-3141.
   • Glossary/other docs: explain both fields in docs/src/content/docs/reference/glossary.md:915-951 and docs/src/content/docs/reference/cost-management.md:211-231.
   • Main frontmatter guide: docs/src/content/docs/reference/frontmatter.md has no dedicated section for either top-level field.
   • Impact: the primary human-oriented frontmatter page is incomplete for an important execution guardrail.

Schema Improvements Needed

1. Remove or formally define stray typed-only fields
   • FrontmatterConfig includes version (pkg/workflow/frontmatter_types.go:327) and include (pkg/workflow/frontmatter_types.go:384) as top-level fields.
   • The main schema has no top-level version or include property.
   • version clearly appears elsewhere in nested schemas (engine/runtime/container), which increases ambiguity.
   • Impact: the typed model suggests unsupported top-level frontmatter keys.

Parser Updates Required

1. Add typed FrontmatterConfig coverage for top-level fields that already exist in schema and runtime logic, especially:

   • ambient-folders
   • github-app
   • max-turns
   • deprecated max-runs (if retained for compatibility)

2. Audit any features still read from raw map[string]any only, and either:

   • promote them into FrontmatterConfig, or
   • explicitly document that FrontmatterConfig is intentionally partial.

Workflow Violations

1. Workflow prose claims Copilot cannot use max-turns, but repository workflows already set top-level max-turns broadly
   • Examples of real usage: .github/workflows/daily-safe-output-optimizer.md:32, .github/workflows/spec-enforcer.md:35, .github/workflows/smoke-claude.md:26, plus many others.
   • The contradictory comments in .github/workflows/daily-community-attribution.md:588 and .github/workflows/agent-persona-explorer.md:37 should be corrected to match current behavior.

Non-Authoritative Warning

• AWF config-source drift could not be authoritatively checked.
• /tmp/gh-aw/agent/awf-config-drift.json reports degraded: true and warns that canonical source retrieval failed.
• Per task instructions, this should be treated only as a warning; no corrective action should be taken from this incomplete comparison.

Recommendations

1. Add missing top-level fields to pkg/workflow/frontmatter_types.go so the typed model matches the schema and docs.
2. Reconcile docs/src/content/docs/reference/engines.md so max-turns support is described consistently for Copilot/Codex/Gemini/Pi.
3. Add dedicated max-turns and deprecated max-runs sections to docs/src/content/docs/reference/frontmatter.md.
4. Correct misleading workflow prose in .github/workflows/daily-community-attribution.md and .github/workflows/agent-persona-explorer.md.
5. Decide whether top-level include and version are real frontmatter fields; if not, remove them from FrontmatterConfig or clearly mark them internal-only.

Strategy Performance

• Strategy Used: Precomputed gap + contradiction spot-check
• Findings: 4
• Effectiveness: HIGH
• Should Reuse: YES

Next Steps

• Fix typed frontmatter/schema drift
• Update inconsistent engine/frontmatter documentation
• Correct misleading workflow comments/instructions
• Re-run schema consistency audit after docs and type updates

Generated by ✅ Schema Consistency Checker · gpt54 · 15.3 AIC · ⌖ 6.4 AIC · ⊞ 8.8K · ◷

• expires on Aug 16, 2026, 9:35 PM UTC-08:00

[github-actions[bot]]

This discussion was automatically closed because it expired on 2026-08-17T05:35:53.114Z.

Closed by Workflow