[Schema Consistency] Schema Consistency Check - 2026-05-28

[github-actions[bot]]

Summary

• Inconsistencies Found: 5 (2 new from strategy-15/16/17, 3 re-confirmed from prior runs)
• Categories Analyzed: Schema ↔ Parser, Schema ↔ Compiler defaults, Schema ↔ Docs, Constants ↔ Schema
• Strategies Used: strategy-15 (default-value consistency), strategy-16 (forbidden-fields cross-check), strategy-17 (ignored-fields docs audit) — all new strategies
• Day-mod: 8 (new-approach mode)

Today's run used three brand-new detection strategies rather than re-running the cached set. Two of them uncovered net-new findings — most notably dead entries in SharedWorkflowForbiddenFields and an undocumented Copilot interop escape hatch in IgnoredFrontmatterFields. Most schema defaults were verified to match the compiler.

Critical Issues

None. All discovered issues are documentation or dead-code cleanups, not behavioral bugs.

New Findings (this run)

1. Dead entries in SharedWorkflowForbiddenFields (pkg/constants/constants.go:325-343)

SharedWorkflowForbiddenFields lists fields that are forbidden at the top level of shared/included workflows. Two entries name fields that do not exist in the main schema and have no yaml: tag anywhere in pkg/parser/ or pkg/workflow/ as top-level keys:

Entry	In schema?	Top-level yaml tag?
"roles"	❌ no	❌ no
"command"	❌ no	❌ no (only a sub-key of MCP tool configs, events.workflows, etc.)

The top-level schema has additionalProperties: false (verified via jq '.additionalProperties' → false), so any author writing roles: or command: at the top of a main workflow would already be rejected by schema validation. The SharedWorkflowForbiddenFields entry never fires.

Fix: Drop the "roles" and "command" entries from SharedWorkflowForbiddenFields (or, if roles was an intentional placeholder for a future feature, add a tracking comment). Note: timeout_minutes (underscore variant) should remain — it is the migration target of pkg/cli/codemod_timeout_minutes.go.

2. Undocumented user-invokable escape hatch (pkg/constants/constants.go:309)

IgnoredFrontmatterFields = []string{"user-invokable"} silently drops user-invokable from schema validation. The comment on line 308 explains:

user-invokable is a GitHub Copilot custom agent field that is not part of the gh-aw schema

But a grep -r "user-invokable" docs/ returns zero hits. Authors who want to ship a workflow that doubles as a Copilot custom agent have no way to discover this interop affordance without reading constants.go.

Fix: Add a short interoperability note under docs/src/content/docs/reference/frontmatter.md listing the ignored fields and why each is tolerated.

3. Asymmetric expires default declaration (schema-only)

• safe-outputs.create-discussion.expires declares "default": 7 in the schema (integer-days form) and the compiler installs a 168-hour (7-day) fallback at pkg/workflow/create_discussion.go:55-57.
• safe-outputs.create-issue.expires has no default in the schema and the compiler installs no default at runtime.

The two fields share the exact same oneOf shape (integer/relative-time string/false). The asymmetry is intentional behaviorally (issues do not auto-expire by default; discussions do), but the schema-level default annotation surfaces only on the discussion path. IDEs and downstream tooling that read JSON-Schema defaults see one but not the other.

Fix: Either drop the default: 7 from create-discussion.expires (since the runtime fallback is what actually matters and the prose description already says "Defaults to 7 days") or add a matching default annotation with a description that explains the contrast on create-issue.expires. Documentation in docs/src/content/docs/reference/safe-outputs.md:1057 already shows the divergent intent.

Defaults that were verified consistent

Schema default	Constant / runtime	Status
properties.engine.default = copilot	constants.DefaultEngine = CopilotEngine (pkg/constants/engine_constants.go:34)	✅ match
properties.max-effective-tokens.default = 25000000	constants.DefaultMaxEffectiveTokens = 25000000 (pkg/constants/constants.go:267)	✅ match
properties.max-runs.default = 500	constants.DefaultMaxRuns = 500 (pkg/constants/constants.go:270)	✅ match
properties.sandbox.oneOf.1.properties.mcp.properties.port.default = 8080	constants.DefaultMCPGatewayPort = 8080 (pkg/constants/constants.go:105)	✅ match
safe-outputs.close-issue.state-reason.default = completed	enum-only field, no runtime fallback needed	✅ match
safe-outputs.upload-artifact.max-size-bytes.default = 104857600	runtime AddDefault("max-size-bytes", ...) (pkg/workflow/safe_outputs_config.go:1537)	✅ match
safe-outputs.max-patch-size.default = 1024	config.MaximumPatchSize = 1024 (pkg/workflow/safe_outputs_config.go:465)	✅ match

Re-confirmed Findings (no progress since prior runs)

Strategy	Finding	Location	Last confirmed
7	check-for-updates, disable-model-invocation, run-install-scripts have zero mentions in curated docs (only in auto-generated frontmatter-full.md)	docs/src/content/docs/reference/	2026-05-28
9	applyTo still in parser validFields map; schema_utilities.go:14 comment still falsely claims applyTo is validated by the schema	pkg/parser/include_processor.go:267, pkg/parser/schema_utilities.go:14	2026-05-28
10	inline-sub-agents and rate-limit describe themselves as deprecated in prose but lack the JSON Schema deprecated: true flag → invisible to IDE tooling	pkg/parser/schemas/main_workflow_schema.json	2026-05-27
12	Schema descriptions for check-for-updates and run-install-scripts link to frontmatter/#<field> anchors that do not exist in frontmatter.md	pkg/parser/schemas/main_workflow_schema.json	2026-05-27
13	$defs.templatable_integer is defined but never $refd; sibling templatable_boolean is referenced. 62 inline `integer	string` duplicates exist.	pkg/parser/schemas/main_workflow_schema.json
14	engine.id schema declares type: string and enumerates valid values in prose only (no JSON Schema enum); compiler also handles a "custom" id not listed in the prose	pkg/parser/schemas/main_workflow_schema.json, pkg/workflow/compiler_yaml.go:772	2026-05-27

Documentation Gaps

• Three top-level schema fields documented only by auto-generated reference (strategy-7).
• user-invokable Copilot interop is invisible to authors (new finding 2).
• Schema description anchors for check-for-updates and run-install-scripts point to non-existent doc headings (strategy-12).

Schema Improvements Needed

• Add enum: ["claude", "codex", "copilot", "gemini", "opencode", "crush", "pi", "custom"] to properties.engine.oneOf.1.properties.id so IDE validation catches engine typos at edit time (the test corpus already contains a copiliot typo).
• Refactor 62 inline integer|string duplicates to $ref: "#/$defs/templatable_integer" (already defined, currently unreferenced).
• Add deprecated: true (and ideally x-deprecation-message) to inline-sub-agents and rate-limit top-level properties.
• Either remove default: 7 from create-discussion.expires or add a matching default annotation to create-issue.expires with an explanatory description.

Parser / Compiler Updates Required

• Remove the "applyTo" entry from validFields in pkg/parser/include_processor.go:267 and the stale claim in pkg/parser/schema_utilities.go:14.
• Remove dead entries "roles" and "command" from pkg/constants/constants.go SharedWorkflowForbiddenFields.
• Promote the legacy rate-limit debug log to a user-facing deprecation warning (or drop the field — it has no schema deprecation flag either).

Workflow Violations

None observed at top level. The field_gaps.in_used_not_schema entries in the pre-computed diff (e.g. affected_sections, independence, verdict) are all nested keys inside experiments.* or tools.serena.* — not top-level frontmatter — and are expected.

Recommendations

1. Drop dead allowlist entries (roles, command in SharedWorkflowForbiddenFields; applyTo in validFields). These are the cheapest cleanups and remove confusing code paths that never fire.
2. Document the user-invokable Copilot interop affordance in docs/src/content/docs/reference/frontmatter.md — currently invisible to anyone who has not read constants.go.
3. Add the engine.id schema enum — single highest-leverage edit; converts a class of runtime errors into IDE squiggles at edit time.
4. Resolve the broken schema anchors for check-for-updates and run-install-scripts and write the missing curated doc sections (strategies-7 and -12 share the same root cause — fix together).
5. Add JSON Schema deprecated: true to inline-sub-agents and rate-limit so IDEs surface the deprecation.
6. Refactor the 62 inline integer|string duplicates to $ref the existing-but-unused templatable_integer def.

Strategy Performance

Strategy	Findings	Effectiveness	Reuse?
strategy-15 (default-value consistency)	1 new	medium	yes — every quarter or when a new safe-output is added
strategy-16 (forbidden-fields cross-check)	2 new	high	yes — cheap one-pass jq + grep
strategy-17 (ignored-fields docs audit)	1 new	medium	yes — re-run whenever IgnoredFrontmatterFields grows

All three new strategies have been added to /tmp/gh-aw/cache-memory/strategies.json. Strategy-15 is the most extensible: as new safe-output entities accumulate default annotations, this one will keep paying off.

Next Steps

• Drop "roles" and "command" from SharedWorkflowForbiddenFields (pkg/constants/constants.go)
• Drop "applyTo" from validFields (pkg/parser/include_processor.go:267) and update the misleading comment at pkg/parser/schema_utilities.go:14
• Add enum: [...] to engine.id in main schema
• Add deprecated: true to inline-sub-agents and rate-limit
• Document user-invokable interop in docs/src/content/docs/reference/frontmatter.md
• Fix or add anchors for check-for-updates and run-install-scripts in frontmatter.md
• Refactor inline integer|string patterns to $ref templatable_integer
• Decide whether to align create-issue.expires and create-discussion.expires default annotations

References:

• Workflow run: §26559029378

Generated by ✅ Schema Consistency Checker · opus47 15.2M · ◷

• expires on May 29, 2026, 6:48 AM UTC

[github-actions[bot]]

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

A newer discussion is available at Discussion #35656.