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

[github-actions[bot]]

Caution

agentic threat detected
Threat detection flagged this output in warn mode. Manual review is REQUIRED before any follow-up automation.

Details

Potential security threats were detected in the agent output.

Review the workflow run logs for details.

🔍 Schema Consistency Check - 2026-08-14

🔍 Schema Consistency Check - 2026-08-14

Summary

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

Critical Issues

1. max-runs still exists in schema and parser implementation, but is absent from the main frontmatter reference docs

   • Schema: pkg/parser/schemas/main_workflow_schema.json:4044
   • Parser/Compiler: pkg/workflow/engine.go:242-249 still parses top-level max-runs as a legacy alias.
   • Docs: docs/src/content/docs/reference/frontmatter.md has no max-runs section/hit.
   • Impact: Users relying on the schema or autocomplete can discover max-runs, but readers of the main reference cannot. This creates migration ambiguity for a still-supported deprecated field.

2. Top-level github-app docs describe inherited fields that are not visible in the frontmatter reference section itself

   • Docs say owner/repositories/ignore-if-missing are supported in docs/src/content/docs/reference/frontmatter.md:158-172.
   • Schema source of truth: top-level github-app references $defs.github_app, which includes owner, repositories, and permissions.
   • Risk: the short frontmatter reference example only shows client-id and private-key, while the behavioral note says extra fields are supported. This is not a hard contradiction, but it is an under-specified reference section relative to the schema and implementation.

Documentation Gaps

1. observability.otlp.github-app and workload-identity are implemented in schema/compiler, but only partially surfaced in the main frontmatter reference

   • Schema: pkg/parser/schemas/main_workflow_schema.json:11669+
   • Implementation: pkg/workflow/observability_otlp.go, pkg/workflow/compiler_validators.go:498-504, typed fields in pkg/workflow/frontmatter_types.go:267-303
   • Docs: docs/src/content/docs/reference/frontmatter.md:447-460 documents endpoint/headers/if-missing/attributes/resource-attributes, but does not mention github-app or workload-identity in that main section.
   • Impact: important auth/configuration branches are discoverable in schema and code but easy to miss in the primary reference.

2. frontmatter-full.md appears to omit a concrete top-level max-runs entry despite the field being in schema

   • grep '^max-runs:' docs/src/content/docs/reference/frontmatter-full.md returned no entry.
   • The glossary and engines docs mention the deprecation, but the exhaustive full reference file appears not to show the field directly.
   • Impact: generated “full” reference is not fully aligned with schema coverage for deprecated-but-supported keys.

Schema Improvements Needed

1. Clarify deprecation visibility for max-runs

   • If it remains accepted, ensure generated/full docs explicitly include it as deprecated.
   • If removal is imminent, consider stronger schema deprecation metadata or validation warnings that point users to max-turns.

2. Promote observability auth branches in schema-linked docs

   • observability.otlp.github-app
   • observability.otlp.workload-identity
   • mutual-exclusion rule with GitHub App credentials

Parser Updates Required

1. No clear parser bug found for the sampled fields, but documentation should catch up with implemented behavior:

   • pkg/workflow/engine.go correctly honors max-runs as a legacy alias.
   • pkg/workflow/workflow_github_app.go correctly applies top-level fallback behavior.
   • pkg/workflow/observability_otlp.go and validators clearly implement advanced OTLP auth behavior.

2. Potential cleanup opportunity

   • The precomputed schema-diff.json reported parser_yaml_fields: [], which is misleading for this repo because the frontmatter model lives primarily in pkg/workflow/frontmatter_types.go using JSON tags, not parser YAML tags.
   • This is a tooling/reporting inconsistency rather than a product schema inconsistency, but it can send future audits in the wrong direction.

Workflow Violations

1. No confirmed top-level schema violations from sampled workflow files for the targeted fields.
   • Apparent “used in workflows but not in schema” entries like create-pull-request and noop are mostly nested under safe-outputs, not true top-level frontmatter keys.
   • This suggests the precomputed workflow-key extraction is flattening nested keys and can produce false positives.

Recommendations

1. Add a deprecated max-runs subsection to docs/src/content/docs/reference/frontmatter.md and ensure frontmatter-full.md renders it too.
2. Expand the observability: section in frontmatter.md to mention github-app and workload-identity explicitly, with a pointer to the deeper OTLP/auth docs.
3. Enrich the top-level github-app: reference example with owner / repositories (and note permissions caveats) so it matches the schema’s effective surface area.
4. Fix the schema-diff precomputation logic to understand JSON-tagged workflow frontmatter structs and nested workflow keys, reducing false positives in future audits.

Strategy Performance

• Strategy Used: Field gap triage + targeted parser/doc verification
• Findings: 4
• Effectiveness: High
• Should Reuse: Yes

Next Steps

• Fix deprecated-field coverage in docs (max-runs)
• Update frontmatter observability docs for OTLP auth variants
• Improve top-level github-app examples/docs
• Correct the precomputed schema-diff extraction logic for future runs

Generated by ✅ Schema Consistency Checker · gpt54 · 19.7 AIC · ⌖ 5.21 AIC · ⊞ 8.5K · ◷

• expires on Aug 14, 2026, 9:54 PM UTC-08:00