[Schema Consistency] Schema Consistency Check — 2026-05-31

[github-actions[bot]]

Summary

• Inconsistencies confirmed: 8 (all re-verified against current main this run)
• Categories analyzed: Schema ↔ Parser ↔ Documentation ↔ Workflows
• Strategy mode: Proven (day-of-year 151 mod 10 = 1 → cached strategies)
• Strategies applied: S7, S8, S9, S10, S12, S13, S15, S16, S17
• Status: ⚠️ Multiple low-severity-but-persistent consistency gaps; none block compilation, all are paper-cuts for users and maintainers.

No critical (bug-causing) inconsistencies were found this run. All findings are documentation gaps, dead/defensive code, or schema-metadata omissions. They have been stable across several prior audits and remain unaddressed.

Critical Issues

None this run. No type mismatches or field-handling gaps that would let invalid frontmatter silently compile.

Documentation Gaps

1. Three schema fields have ZERO curated documentation (S7)

check-for-updates, disable-model-invocation, and run-install-scripts (nested under runtimes) appear only in the auto-generated frontmatter-full.md. No curated page in docs/src/content/docs/ mentions them.

• run-install-scripts is defined at main_workflow_schema.json:11472 and carries a supply-chain security warning — it deserves a real doc entry given its security relevance.
• Impact: Users cannot discover or understand these fields from the human-written docs.

2. Schema doc-link anchors point to non-existent headings (S12)

The schema descriptions for check-for-updates and run-install-scripts link to reference/frontmatter/#check-for-updates and .../#run-install-scripts, but no matching heading exists in docs/src/content/docs/reference/frontmatter.md. These are dead deep-links shipped in the schema itself.

3. `user-invokable` silently ignored but undocumented (S17)

pkg/constants/constants.go:315 lists user-invokable in IgnoredFrontmatterFields (a Copilot custom-agent field that is silently dropped). The field name appears nowhere in docs/, so users get no explanation of why it is accepted-but-ignored.

4. `applyTo` accepted by parser, absent from schema & docs (S9)

pkg/parser/include_processor.go:267 keeps applyTo in its validFields allowlist, but applyTo is not a property in main_workflow_schema.json and has zero curated-doc mentions. The parser accepts a field the schema does not know about and nobody documents.

Schema Improvements Needed

5. Deprecated/legacy fields lack JSON-Schema deprecation metadata (S10)

Field	Description starts with	deprecated flag	x-deprecation-message
inline-sub-agents	"Deprecated switch for inline sub-agent..."	null	null
rate-limit	"Legacy alias for 'user-rate-limit'..."	null	null

Both describe themselves as deprecated/legacy in prose but carry no deprecated: true flag, so editors/tooling cannot surface the deprecation.

False-positive watch: strict matches a naive grep because its description lists "(5) Deprecated Fields" as a strict-mode FEATURE — it is not deprecated; exclude it.

6. Dead `$defs` entry: `templatable_integer` (S13)

templatable_integer is defined in $defs but never $ref'd (1 occurrence total = the definition itself). Its sibling templatable_boolean has 10 occurrences. Either wire it up where integer templating is allowed, or remove the dead def.

7. Inconsistent `expires` default across safe-outputs (S15)

create-discussion.expires declares default: 7 in the schema, but create-issue.expires declares no default (null). If both are meant to expire after 7 days the schema is misleading; if not, the asymmetry should be documented.

Parser Updates Required

8. Legacy `rate-limit` deprecation is debug-only, not user-visible (S8)

pkg/workflow/role_checks.go:301 handles the legacy rate-limit alias with roleLog.Print("Extracted legacy rate-limit configuration") — a debug-level log. There is no user-facing deprecation warning steering users toward user-rate-limit. (For contrast, user-rate-limit itself emits an EXPERIMENTAL warning at compile time.)

Workflow Violations

None. No .github/workflows/*.md file uses a field rejected by the schema. The field_gaps.in_used_not_schema entries are all flattened nested keys / template variables (e.g. score, verdict, run_dir), not real top-level violations.

Dead/defensive allowlist entries (S16) — code hygiene, not a violation

SharedWorkflowForbiddenFields in pkg/constants/constants.go lists command (line 334) and roles (line 342), neither of which is a top-level schema property. Since the top-level schema is additionalProperties: false, these can never appear, making the entries dead/defensive. Harmless but worth a cleanup comment.

Recommendations

1. Add curated doc sections (with matching #anchor headings) for check-for-updates, disable-model-invocation, and run-install-scripts — the latter is security-relevant and most urgent.
2. Add "deprecated": true (and an x-deprecation-message) to the inline-sub-agents and rate-limit schema entries.
3. Promote the legacy rate-limit debug log to a user-visible deprecation warning pointing at user-rate-limit.
4. Reconcile create-issue.expires default with create-discussion.expires (default: 7), or document the difference.
5. Either reference or remove the dead templatable_integer $def.
6. Document or remove applyTo and user-invokable handling so accepted-but-undocumented fields stop surprising users.
7. Add a brief comment marking command/roles as defensive entries in SharedWorkflowForbiddenFields.

Strategy Performance

• Mode: Proven (mod-10 = 1).
• Strategies used: S7, S8, S9, S10, S12, S13, S15, S16, S17.
• Findings: 8 confirmed, 0 regressions, 0 newly-fixed.
• Effectiveness: HIGH — every cached high-signal strategy still reproduces; cache success counts incremented.
• Should reuse: YES.

Next Steps

• Add deprecation metadata to inline-sub-agents and rate-limit in the schema
• Promote legacy rate-limit log to a user-facing warning
• Document check-for-updates, disable-model-invocation, run-install-scripts and fix their doc anchors
• Reconcile expires defaults across safe-outputs
• Remove/wire-up dead templatable_integer def; tidy SharedWorkflowForbiddenFields

References: §26705611078

Generated by ✅ Schema Consistency Checker · opus48 906.5K · ◷

• expires on Jun 1, 2026, 6:46 AM UTC