[Schema Consistency] 🔍 Schema Consistency Check - 2026-08-12

[github-actions[bot]]

Summary

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

Critical Issues

1. pkg/parser/frontmatter.go no longer represents frontmatter parsing behavior, but the task-facing parser file list still points to it

   • pkg/parser/frontmatter.go now only contains a logger declaration.
   • Actual frontmatter field extraction/parsing is implemented under pkg/workflow/, including frontmatter_extraction_yaml.go, frontmatter_types.go, and trigger_parser.go.
   • Impact: anyone auditing pkg/parser/frontmatter.go for schema consistency will miss the real implementation surface, and automated field-diff approaches that only inspect pkg/parser/*.go produce false negatives.

2. Auto-generated schema reference omits important schema fields from narrative visibility

   • docs/src/content/docs/reference/frontmatter-full.md contains allow-bot-authored-trigger-comment and check-for-updates, but does not include run-install-scripts or report-failed-jobs as searchable field names.
   • Meanwhile the schema defines both fields, and the user-facing docs document them in frontmatter.md.
   • Impact: the supposed complete JSON-Schema-derived reference is incomplete for real fields users need.

Documentation Gaps

1. frontmatter-full.md misses run-install-scripts as an actual field path

   • Schema: runtimes.<runtime>.run-install-scripts exists.
   • Implementation: pkg/workflow/frontmatter_types.go defines RunInstallScripts *bool with JSON tag run-install-scripts, and validation exists in the workflow layer.
   • Docs: frontmatter.md explains it, but frontmatter-full.md contains no run-install-scripts token at all.
   • Impact: the generated reference cannot be relied on for nested runtime fields.

2. frontmatter-full.md misses report-failed-jobs as an actual field path

   • Schema: safe-outputs.report-failed-jobs exists.
   • Implementation: pkg/workflow/safe_outputs_config_global.go parses report-failed-jobs.
   • Docs: frontmatter.md and glossary mention it, but frontmatter-full.md does not contain the field name.
   • Impact: the “complete reference” is not actually complete for safe-output global controls.

Schema Improvements Needed

1. Clarify canonical field naming for label-command removal

   • Schema uses remove_label under on.label_command.
   • Most top-level/frontmatter naming is hyphenated.
   • Recommendation: explicitly document in schema descriptions and reference docs that remove_label intentionally uses underscore naming and is not remove-label.

2. Expose nested field coverage better in generated docs

   • The schema contains nested fields like run-install-scripts and report-failed-jobs, but the generated reference does not surface them as searchable headings/anchors.
   • Recommendation: improve doc generation so nested property names are emitted in a stable, grep-friendly way.

Parser Updates Required

1. Parser ownership/docs need to be updated to reflect reality

   • pkg/parser/frontmatter.go is effectively a stub.
   • Real parsing is in workflow-layer files such as pkg/workflow/frontmatter_extraction_yaml.go and pkg/workflow/trigger_parser.go.
   • Recommendation: either move/restore frontmatter parsing entrypoints under pkg/parser, or update docs/tasks/tests that claim parser logic lives there.

2. Field-diff tooling should inspect pkg/workflow/frontmatter_types.go, not yaml tags in pkg/parser/*.go

   • Precomputed data showed parser_yaml_fields was empty, which is misleading rather than actionable.
   • frontmatter_types.go uses JSON tags for frontmatter keys, e.g. max-daily-ai-credits, runs-on-slim, and check-for-updates.
   • Recommendation: adapt consistency tooling to the current implementation model.

Workflow Violations

1. Precomputed used_in_workflows includes many non-schema keys that are probably body YAML/examples rather than true top-level frontmatter
   • Examples include noop, create-pull-request, repo, title, task, try, else.
   • This does not look like a real schema violation in source workflows; it looks like extraction overreach.
   • Impact: schema-vs-workflow reports can overstate invalid workflow usage.
   • Recommendation: restrict workflow usage extraction to the actual frontmatter block only.

Recommendations

1. Update schema-consistency tooling to inspect the current frontmatter implementation in pkg/workflow/ instead of pkg/parser/frontmatter.go.
2. Fix generation of docs/src/content/docs/reference/frontmatter-full.md so nested schema fields like run-install-scripts and report-failed-jobs are emitted explicitly.
3. Tighten workflow key extraction to parse only YAML frontmatter, avoiding markdown body examples and embedded YAML snippets.
4. Add a regression check that asserts every schema property name is searchable in frontmatter-full.md or intentionally excluded.

Strategy Performance

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

Next Steps

• Fix schema-reference doc generation for nested fields
• Update parser ownership/docs and analysis tooling
• Tighten workflow frontmatter extraction for consistency audits
• Add regression coverage for generated reference completeness

Generated by ✅ Schema Consistency Checker · gpt54 · 24.1 AIC · ⌖ 5.97 AIC · ⊞ 8.5K · ◷

• expires on Aug 12, 2026, 9:55 PM UTC-08:00

[github-actions[bot]]

This discussion was automatically closed because it expired on 2026-08-13T05:55:22.005Z.

Closed by Workflow