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

[github-actions[bot]]

🔍 Schema Consistency Check - 2026-08-21

🔍 Schema Consistency Check - 2026-08-21

Summary

• Inconsistencies Found: 4
• Categories Analyzed: Schema, Parser, Documentation, Workflows
• Strategy Used: Schema diff + targeted parser/doc verification
• New Strategy: No

Critical Issues

1. max-turn-cache-misses rejects expression values in the parser, but the schema/documentation position it as a configurable guardrail with frontmatter precedence.

   • Schema: pkg/parser/schemas/main_workflow_schema.json defines max-turn-cache-misses as integer only with default 5.
   • Parser type: pkg/workflow/frontmatter_types.go:331 stores it as *int32, unlike neighboring templatable numeric fields.
   • Parser runtime: pkg/workflow/engine_config_parser.go:33-53 explicitly treats GitHub Actions expression strings as 0 / unset for integer-only fields.
   • Docs: docs/src/content/docs/reference/glossary.md:956 says imported/frontmatter precedence applies, but does not warn that expressions are unsupported while nearby fields do support them.
   • Impact: users may assume parity with nearby limit fields such as max-tool-denials / max-turns; expression inputs silently degrade to default behavior instead of applying the intended value.

2. tracker-id validation rules live in parser code but are only partially represented in schema/docs.

   • Parser enforcement: pkg/workflow/frontmatter_extraction_metadata.go:97-124 requires a string, trims whitespace, enforces length 8..128, and restricts characters to [A-Za-z0-9_-].
   • Frontmatter struct: pkg/workflow/frontmatter_types.go:325 is a plain string field.
   • Docs: docs/src/content/docs/reference/frontmatter.md:616 documents the allowed charset and length.
   • Schema diff signal: the top-level field list alone does not capture those constraints, so schema-level validation is weaker than compile-time validation.
   • Impact: schema-based editors and external validators can accept values that compilation later rejects.

Documentation Gaps

1. secret-masking is present in schema/parser but missing from the concise frontmatter reference.

   • Parser type: pkg/workflow/frontmatter_types.go:393.
   • Runtime support: pkg/workflow/secret_masking.go and pkg/workflow/redact_secrets.go process it.
   • Config shape: pkg/workflow/safe_outputs_config_types.go:177-180 exposes secret-masking.steps.
   • The short reference docs/src/content/docs/reference/frontmatter.md has no dedicated secret-masking section, while the generated full reference does mention it (frontmatter-full.md:20275).
   • Impact: discoverability gap for a security-relevant feature.

2. excluded-env is documented outside the main frontmatter reference but omitted from the concise frontmatter page.

   • Parser type: pkg/workflow/frontmatter_types.go:448.
   • Runtime use: pkg/workflow/awf_env.go:167-170 always excludes listed names from the agent container.
   • Full docs/glossary: docs/src/content/docs/reference/frontmatter-full.md:20483-20489 and docs/src/content/docs/reference/glossary.md:1513-1523 describe it.
   • Short frontmatter page: no dedicated excluded-env section despite covering nearby top-level config fields like check-for-updates, strict, and tracker-id.
   • Impact: users reading only the primary frontmatter guide can miss a useful hardening control.

Schema Improvements Needed

1. Add explicit schema constraints for tracker-id to match compiler validation:

   • type: string
   • minLength: 8
   • maxLength: 128
   • pattern: ^[A-Za-z0-9_-]+$

2. Clarify max-turn-cache-misses support boundaries:

   • either keep it integer-only and explicitly state "no GitHub Actions expressions supported"
   • or align it with adjacent templatable limits by moving to the same templatable integer schema/parser path.

Parser Updates Required

1. Consider making max-turn-cache-misses use the same templatable integer pathway as max-tool-denials, max-turns, and timeout-minutes if runtime expression support is intended.
2. If expression support is intentionally forbidden, emit a hard validation error instead of silently collapsing invalid string input to unset/default behavior.

Workflow Violations

1. The precomputed used_in_workflows diff includes several non-schema keys such as capabilities, repo, https, and title, but targeted verification shows at least some are false positives from workflow body content rather than real frontmatter keys:
   • .github/workflows/smoke-aider.md contains capabilities: in body text, not frontmatter.
   • .github/workflows/shared/copilot-agent-analysis-history.md contains repo: in a query example, not frontmatter.
   • .github/workflows/shared/mcp/grafana.md and sentry.md contain https: lines from example URLs, not top-level frontmatter.
   • Impact: the precomputed workflow-usage extractor is useful for triage but should not be treated as authoritative without frontmatter boundary detection.

Non-Authoritative Warning

• AWF config-source drift data at /tmp/gh-aw/agent/awf-config-drift.json is marked degraded: true.
• Canonical source retrieval failed, so no authoritative AWF config drift claim is included in this report.
• Per instructions, this should not trigger destructive follow-up or corrective action by itself.

Recommendations

1. Tighten JSON schema validation for tracker-id so editors catch invalid values before compilation.
2. Resolve the max-turn-cache-misses UX mismatch by either supporting templated expressions or documenting/rejecting them clearly.
3. Add short-reference sections for secret-masking and excluded-env in docs/src/content/docs/reference/frontmatter.md.
4. Improve workflow-frontmatter extraction used for schema-diff.json so body YAML/examples are excluded from used_in_workflows.

Strategy Performance

• Strategy Used: Schema diff + targeted parser/doc verification
• Findings: 4
• Effectiveness: High
• Should Reuse: Yes

Next Steps

• Fix schema definitions for tracker-id
• Decide and document max-turn-cache-misses expression support
• Update concise frontmatter docs for secret-masking and excluded-env
• Harden workflow usage extraction against markdown body false positives

Generated by ✅ Schema Consistency Checker · gpt54 · 20.4 AIC · ⌖ 9.97 AIC · ⊞ 8.9K · ◷

• expires on Aug 21, 2026, 9:37 PM UTC-08:00

[github-actions[bot]]

This discussion was automatically closed because it expired on 2026-08-22T05:37:30.066Z.

Closed by Workflow