[Schema Consistency] Schema Consistency Check — 2026-06-03

[github-actions[bot]]

Summary

• Inconsistencies confirmed: 7 (across all 4 areas)
• Categories analyzed: Schema ↔ Parser/Compiler, Schema ↔ Documentation, Schema ↔ Workflows, Parser ↔ Documentation
• Selection mode: PROVEN (day-of-year 154 mod 10 = 4 ≤ 6)
• Strategies used: S7, S10, S12, S16, S17, S19 (all cached, all re-confirmed today)
• New strategy this run: No — all findings re-verified against current source

All findings below were re-confirmed against the live tree on 2026-06-03 (HEAD 97aef66). These are persistent divergences carried from prior audits — none have regressed, but none are yet fixed.

Critical Issues

No correctness-breaking (would-cause-runtime-bug) issues found this run. All 7 findings are consistency/maintainability divergences. The highest-impact items are the two missing deprecation flags (users get no machine-readable deprecation signal) and the three fully-undocumented fields.

Schema ↔ Parser/Compiler Mismatches

1. Deprecation described in prose but not flagged (deprecated: true missing)

   • inline-sub-agents — description begins "Deprecated switch for inline sub-agent support..." yet .deprecated is null and there is no x-deprecation-message.
   • rate-limit — description begins "Legacy alias for 'user-rate-limit'..." yet .deprecated is null and there is no x-deprecation-message.
   • The schema already carries 14 elements with deprecated: true, so these two are genuine omissions, not a convention the project avoids.
   • Impact: tooling/editors that surface JSON-Schema deprecated give no warning for these fields.

2. create-code-scanning-alert — singular schema/parser key vs plural Go struct tag

   • Schema safe-outputs property key: create-code-scanning-alert (singular).
   • Parse handler reads outputMap["create-code-scanning-alert"] (singular) at pkg/workflow/create_code_scanning_alert.go:24,29.
   • Go struct yaml tag is plural: pkg/workflow/compiler_types.go:647 → yaml:"create-code-scanning-alerts,omitempty".
   • Impact: the plural yaml tag is effectively dead code (parsing is manual map access), and the mismatch is a trap for the next maintainer who relies on the struct tag.

3. Dead allowlist entries in SharedWorkflowForbiddenFields

   • pkg/constants/constants.go:334 (command) and :342 (roles) forbid fields that are not top-level schema properties (top-level schema is additionalProperties: false, and neither key exists in .properties).
   • Impact: low — defensive-only entries that can never match a schema-valid field; candidates for removal or a clarifying comment.

Schema ↔ Documentation Mismatches

4. Three schema fields have ZERO curated documentation (only appear in the auto-generated frontmatter-full.md):

   • check-for-updates
   • disable-model-invocation
   • run-install-scripts
   • Impact: users discovering these fields have no hand-written guidance on semantics or when to set them.

5. Broken in-schema doc anchor for check-for-updates

   • Schema description (~line 9862) links to .../reference/frontmatter/#check-for-updates, but frontmatter.md contains 0 occurrences of check-for-updates — no such heading/anchor exists.
   • Impact: the documentation link in the schema resolves to a non-existent anchor (404-on-page).

Schema ↔ Workflows / Naming-Convention Mismatches

6. dispatch_repository uses snake_case among kebab-case siblings
   • pkg/parser/schemas/main_workflow_schema.json:8329 defines dispatch_repository while every sibling safe-output (dispatch-workflow, create-issue, create-discussion, ...) uses kebab-case.
   • Impact: inconsistent authoring ergonomics; easy to mistype by analogy with neighbors.

Parser ↔ Documentation Mismatches

7. IgnoredFrontmatterFields is undocumented
   • pkg/constants/constants.go:315 → IgnoredFrontmatterFields = ["user-invokable"] — silently dropped during validation, but user-invokable appears in 0 files under docs/.
   • Impact: a field the parser intentionally accepts-and-ignores is invisible to users reading the docs.

Recommendations

1. Add "deprecated": true (and ideally x-deprecation-message) to inline-sub-agents and rate-limit in the schema.
2. Align the code-scanning alert key: change the Go struct yaml tag at compiler_types.go:647 to singular create-code-scanning-alert, matching schema + parse handler.
3. Rename dispatch_repository → dispatch-repository in the schema (with a back-compat alias if any workflows already use the snake_case form).
4. Add curated docs for check-for-updates, disable-model-invocation, and run-install-scripts; add the missing #check-for-updates heading so the schema link resolves.
5. Document user-invokable (the lone IgnoredFrontmatterFields entry) or remove it if obsolete.
6. Remove or comment the dead command / roles entries in SharedWorkflowForbiddenFields.

Strategy performance (this run)

Strategy	Findings	Effectiveness	Reuse
S7 Documentation coverage audit	3	high	yes
S10 Deprecation flag consistency	2	high	yes
S12 Schema doc-link anchor verification	1	high	yes
S16 SharedWorkflowForbiddenFields cross-check	2	high	yes
S17 IgnoredFrontmatterFields doc audit	1	medium	yes
S19 Safe-output key naming convention	2	high	yes

Noise note (not findings): field_gaps.in_schema_not_parser and in_used_not_schema from the pre-computed diff remain low-signal — top-level fields are handled via map[string]any access (no yaml tags), and used_in_workflows flattens nested expression keys (authors, model, title, repo, task, try, else, date, https). These were excluded.

Next Steps

• Add deprecated: true flags to inline-sub-agents and rate-limit
• Fix create-code-scanning-alert plural struct tag
• Normalize dispatch_repository to kebab-case
• Document check-for-updates, disable-model-invocation, run-install-scripts + add missing anchor
• Document or remove user-invokable
• Clean up dead command/roles forbidden-field entries

References: §26868884519

Generated by ✅ Schema Consistency Checker · opus48 4.8M · ◷

• expires on Jun 4, 2026, 7:03 AM UTC

[github-actions[bot]]

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

A newer discussion is available at Discussion #36862.