[Schema Consistency] Schema consistency check report

[github-actions[bot]]

🔍 Schema Consistency Check - 2026-09-28

Summary

• Inconsistencies Found: 4
• Categories Analyzed: Schema, Parser, Documentation, Workflows
• Strategy Used: Schema-def spot checks + targeted parser/doc/workflow verification
• New Strategy: NO

Critical Issues

1. ** appears in schema/frontmatter but is effectively absent from docs and workflows**

   • Schema/frontmatter define as a supported top-level field (, ).
   • No practical usage/examples found in and no clear section in frontmatter reference docs.
   • Impact: feature drift risk and unclear operator behavior for run-limiting.

2. ** precedence is only partially represented across references**

   • Schema explicitly states precedence: overrides ().
   • Reference docs mention default and scope but are fragmented across pages.
   • Impact: users can misconfigure generated-job runner routing.

Documentation Gaps

1. ** engine-gating is easy to miss in docs**

   • Schema marks it as supported only with and ().
   • Workflows use it broadly; docs should present gating prominently near the top-level field definition to prevent invalid assumptions under other engines.

2. ** shorthand vs object semantics are distributed across sections**

   • Schema allows or detailed object ().
   • Reference material covers this, but examples and caveats are spread across pages, making authoritative behavior harder to locate quickly.

Schema Improvements Needed

1. Add machine-readable cross-links (via or extension metadata) from top-level fields to the canonical doc anchors for high-risk fields (, , , ).
2. Add explicit note blocks in schema descriptions when field behavior is engine-conditional (already partly present for ; replicate pattern where applicable).

Parser Updates Required

1. Consider emitting compile-time warnings for low-visibility but schema-valid fields when no docs anchor is available in the local docs map (especially ).
2. Keep existing precedence behavior for runner fields, but add parser-level diagnostics when both and are set (informational warning showing effective value).

Workflow Violations

• No hard schema violations were confirmed in sampled workflow frontmatter.
• is empty in precomputed data ().
• AWF config-source drift source is degraded (), so any canonical-source drift findings are non-authoritative warnings only.

Recommendations

1. Add a dedicated section to with examples and interaction notes.
2. Consolidate runner precedence guidance (, , , threat-detection overrides) into a single table.
3. Promote engine-compatibility callouts for to a warning block in both short and full frontmatter references.
4. Add a docs consistency CI check that verifies every top-level schema field has at least one reference anchor.

Strategy Performance

• Strategy Used: Schema-def spot checks + targeted parser/doc/workflow verification
• Findings: 4
• Effectiveness: HIGH
• Should Reuse: YES

Next Steps

• Fix schema-to-doc anchor coverage for top-level fields
• Improve parser diagnostics for effective runner precedence
• Update frontmatter docs for and engine-gated fields
• Re-run consistency checker after docs/parser updates

Generated by ✅ Schema Consistency Checker · codex · gpt53codex · 12.8 AIC · ⌖ 3.52 AIC · ⊞ 21K · ◷

• expires on Sep 28, 2026, 9:38 PM UTC-08:00

[github-actions[bot]]

This discussion has been marked as outdated by Schema Consistency Checker.

A newer discussion is available at Discussion #64188.