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

[github-actions[bot]]

Summary

• Inconsistencies Found: 4 issues across 3 categories
• Categories Analyzed: Schema, Parser, Documentation, Workflows
• Strategies Used: doc-link anchor verification (Weekly Research Report: AI Workflow Automation Landscape and Strategic Opportunities - August 2025 #12), deprecation flag consistency (Remove ai-inference, opencode, genaiscript agentic engines for now #10), parser-allowlist cross-check (Weekly Research Report: AI Workflow Automation Landscape and Strategic Opportunities - August 2025 #9), documentation coverage audit (Weekly Research Report: AI Workflow Automation Landscape and Market Opportunities - August 2025 #7)
• Selection Mode: proven (day-of-year 146 % 10 = 6)
• New Strategy Tried: No (proven strategies still surfacing valid findings)

This cycle reconfirms three high-impact gaps from prior runs and confirms tracker-id is now documented — a previously-flagged top finding has been resolved. All four findings below are independently verifiable from the schema and source files.

Critical Issues

1. Schema See: links point to anchors that do not exist

Both check-for-updates and run-install-scripts schema descriptions end with a See: https://github.github.com/gh-aw/reference/frontmatter/#<field> link. Neither anchor resolves to a heading in docs/src/content/docs/reference/frontmatter.md. Users following the schema-suggested doc link land on a page with no matching section.

Field	Link in schema	Heading exists?
check-for-updates	frontmatter/#check-for-updates	❌ no heading slugifies to this
run-install-scripts	frontmatter/#run-install-scripts	❌ no heading slugifies to this
strict	frontmatter/#strict-mode-strict	✅ ### Strict Mode (\strict:`)`

This is a customer-visible breakage in IDE hover-doc and schema preview tooling.

2. Top-level deprecation prose has no deprecated: true flag

Two top-level fields explicitly call themselves Deprecated/Legacy in their schema description but lack the JSON-Schema deprecated: true flag:

# pkg/parser/schemas/main_workflow_schema.json — inline-sub-agents
type: boolean
description: "Deprecated switch for inline sub-agent support. ... Setting this to false is not supported and causes a compilation error."
examples: [true]
# (no deprecated flag)

# pkg/parser/schemas/main_workflow_schema.json — rate-limit
description: "Legacy alias for 'user-rate-limit'. Prefer 'user-rate-limit' with 'max-runs-per-window'."
deprecated: null      # ← explicitly null, never true
type: object

Consequences:

• IDE/JSON-schema tooling does not mark these fields as deprecated (no strikethrough, no warning chip).
• pkg/workflow/compiler_orchestrator_tools.go:436-460 (warnDeprecatedFrontmatterFields) consumes schema.deprecated:true to emit user-visible warnings via GetMainWorkflowDeprecatedFieldsDeep(). Because the flag is missing, no compile-time warning ever fires for these two fields. For rate-limit the only signal is a debug log at pkg/workflow/role_checks.go:301 (roleLog.Print("Extracted legacy rate-limit configuration")), which is invisible to end users.

The schema has 14 nested fields correctly tagged deprecated: true (e.g. tools.github.oneOf.3.repos, tools.grep, tools.serena, several safe-outputs.*.title-prefix, etc.) — so the convention is established; these two top-level fields are simply missing it.

3. Parser allowlist contains applyTo, but it is dead code

pkg/parser/include_processor.go:250-271 defines a validFields allowlist for shared-workflow frontmatter validation:

validFields := map[string]bool{
  "tools": true, "engine": true, ..., 
  "applyTo": true,                          // ← orphan
  "inputs": true,
  "import-schema": true,
  "disable-model-invocation": true,
  "features": true,
}

Reality check on applyTo:

• ❌ Not in main_workflow_schema.json at any level.

• ❌ Not referenced by any production code (only include_processor.go:267 and a test in schema_utilities_test.go).

• ❌ Not used in any .github/workflows/**/*.md file in the repo.

• ❌ Not documented anywhere in docs/.

• ⚠️ The comment at pkg/parser/schema_utilities.go:14 actively misleads:

  // as all previously ignored fields (description, applyTo) are now validated by the schema

  applyTo is not validated by the schema — it is only allowed because this map permits it.

This looks like a leftover from a past refactor. Either restore validation (add applyTo to the schema with a description and document it) or remove the allowlist entry and update the test/comment. (inputs in the same map is legitimate — it is a nested field on imports[].inputs.)

Documentation Gaps

Three schema-defined top-level fields have zero mentions anywhere in the curated docs tree (docs/src/content/docs/, excluding the auto-generated frontmatter-full.md):

Field	Schema default	Compile-time impact	Curated docs?
check-for-updates	true	Strict mode error if set to false; warning otherwise (strict_mode_update_check_validation.go)	❌ none
disable-model-invocation	—	Listed only in include_processor.go:270 allowlist; no compiler code path	❌ none
run-install-scripts	false	Supply-chain security warning at compile; strict-mode error (compiler_orchestrator_workflow.go:96)	❌ none

run-install-scripts is particularly concerning — it disables --ignore-scripts for all npm installs, which is a meaningful supply-chain trade-off, but a user opting in has no documentation to consult.

Fields documented elsewhere but missing from the curated frontmatter index

These have a real implementation but their only doc lives outside frontmatter.md:

Field	Where it shows up
experiments	docs/src/content/docs/reference/gh-aw-as-mcp-server.md
user-rate-limit	docs/src/content/docs/reference/rate-limiting-controls.md (dedicated page)
secret-masking	docs/src/content/docs/reference/imports.md
import-schema	docs/src/content/docs/reference/imports.md
inlined-imports	docs/src/content/docs/reference/faq.md (one-line mention)
inline-sub-agents	nowhere user-facing (deprecated, see issue #2)
rate-limit	nowhere user-facing (deprecated, see issue #2)

The curated reference/frontmatter.md is the index users land on first; missing entries here mean discoverability suffers even when a dedicated page exists.

Schema Improvements Needed

1. Add deprecated: true to properties["inline-sub-agents"] and properties["rate-limit"] so the warnDeprecatedFrontmatterFields runtime warning fires and IDE tooling renders strikethrough.
2. Either drop the See: link from the descriptions of check-for-updates and run-install-scripts, or add ### Check for Updates (\check-for-updates:`)and### Run Install Scripts (`run-install-scripts:`)headings todocs/src/content/docs/reference/frontmatter.md` so the anchors resolve.

Parser Updates Required

1. Decide the fate of applyTo in pkg/parser/include_processor.go:267:
   • Option A (likely correct): remove "applyTo": true from the validFields map, remove the matching case in pkg/parser/schema_utilities_test.go, and update the stale comment at pkg/parser/schema_utilities.go:14.
   • Option B: if applyTo is intended as a real shared-workflow field, add it to main_workflow_schema.json, give it a description, and document it.
2. (Lower priority) After fixing the schema deprecated: flags above, no parser code changes are needed — GetMainWorkflowDeprecatedFieldsDeep() will pick them up automatically.

Workflow Violations

No new workflow-frontmatter violations detected this cycle. The previously-noisy field_gaps.in_used_not_schema entries (e.g. affected_sections, judge_path, serena-find_symbol) remain false positives caused by the diff tool flattening nested keys.

Recommendations

1. Quick win: add deprecated: true to inline-sub-agents and rate-limit schema entries. Two-line change, immediate user-facing benefit (IDE + compile warning).
2. Quick win: remove the dead applyTo allowlist entry and update its misleading comment. ~5 lines deleted across 3 files.
3. Docs: add curated frontmatter.md sections for check-for-updates, run-install-scripts, and disable-model-invocation. The supply-chain implications of run-install-scripts deserve a security note. This also fixes the broken anchors flagged in issue rejig docs #1.
4. Index hygiene: cross-link to experiments, user-rate-limit, secret-masking, and import-schema from the curated frontmatter.md so the index reflects the full top-level surface even when details live on dedicated pages.

Strategy Performance

Strategy	Findings this run	Effectiveness	Reuse next cycle?
#7 documentation coverage audit	3 confirmed (+ 7 secondary)	high	yes
#8 deprecation enforcement check	1 confirmed	high	yes
#9 parser validFields vs schema	1 confirmed	high	yes
#10 deprecation flag consistency	2 confirmed	high	yes
#12 schema doc-link anchor verification	2 confirmed	high	yes (anchors evolve)

Strategy cache (/tmp/gh-aw/cache-memory/strategies.json) updated with these results. Notable: strategy-7 saw a prior-cycle finding resolved (tracker-id now documented), confirming the audit loop is closing real gaps over time.

Next Steps

• Fix schema definitions: add deprecated: true to inline-sub-agents and rate-limit in pkg/parser/schemas/main_workflow_schema.json
• Update parser: remove or implement applyTo in pkg/parser/include_processor.go:267 and update comment at pkg/parser/schema_utilities.go:14
• Update documentation: add headings to docs/src/content/docs/reference/frontmatter.md for check-for-updates, run-install-scripts, disable-model-invocation
• Verify schema See: links resolve — drop the link or add the heading

References:

• §26436389600

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

• expires on May 27, 2026, 6:41 AM UTC