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

[github-actions[bot]]

Schema consistency analysis run on 2026-05-02. Workflow run: §25245322929

Summary

• Inconsistencies Found: 6 distinct categories
• Areas Analyzed: Schema (main_workflow_schema.json), Parser/Compiler (pkg/parser/*.go, pkg/workflow/*.go), Documentation (docs/src/content/docs/reference/), Workflows (.github/workflows/*.md)
• Strategy Used: Deprecated field consistency check + experimental feature marker audit + frontmatter.md coverage scan
• New Strategy: Yes (first run — no prior cache)

---

Critical Issues

1. deprecated: true Missing from Schema for Compiler-Deprecated Fields

The strict-mode validator (validateStrictDeprecatedFields in pkg/workflow/strict_mode_permissions_validation.go:44) reads the list of deprecated fields from the schema using parser.GetMainWorkflowDeprecatedFields(). That function only detects fields with "deprecated": true as a JSON property.

Currently, only two fields have "deprecated": true in the schema:

• tools.grep
• tools.serena

But these fields are treated as deprecated by the compiler yet lack "deprecated": true in the schema:

Field	Evidence of Deprecation	Schema deprecated: true?
dependencies	compiler_orchestrator_tools.go:166 warns "deprecated and no longer supported"	❌ No
infer	Schema description says "DEPRECATED: Use 'disable-model-invocation' instead"; include_processor.go:202 comment marks it deprecated	❌ No

Impact: In strict mode, workflows using dependencies: or infer: will compile without a deprecated field error. The schema's description for infer correctly says "DEPRECATED" but without "deprecated": true, the automated check cannot enforce it.

Fix: Add "deprecated": true to properties.dependencies and properties.infer in main_workflow_schema.json.

---

2. Experimental Features Not Flagged in Schema

The compiler (pkg/workflow/compiler_validators.go:264-278) emits runtime warnings for three features:

Using experimental feature: rate-limit
Using experimental feature: dispatch_repository
Using experimental feature: merge-pull-request

None of these have an "experimental", "x-status", or equivalent marker in the JSON schema. The schema descriptions for all three read as stable features:

• rate-limit: "Rate limiting configuration to restrict how frequently users can trigger the workflow."
• safe-outputs.dispatch_repository: "Dispatch repository_dispatch events to external repositories."
• safe-outputs.merge-pull-request: "Enable AI agents to merge pull requests under configured policy gates."

Impact: IDE schema validation and documentation generators show no indication these features are experimental. Users discover the experimental status only at compile time via stderr warnings. The documentation correctly calls dispatch_repository and merge-pull-request experimental, but the schema itself is silent.

Fix: Add "x-stability": "experimental" (or similar) to these three schema nodes, and add a note to rate-limit's description referencing its experimental status.

---

Documentation Gaps

3. features Sub-Keys Not Enumerated in Schema

The features field uses "additionalProperties": true with only action-tag shown in examples. However, the compiler actively validates several specific sub-keys:

Feature Key	Implemented In	Documented In
action-tag	features_validation.go	frontmatter.md ✅
action-mode	compiler_validators.go:52	frontmatter.md ✅
copilot-requests	constants/feature_constants.go	glossary.md only
awf-diagnostic-logs	awf_helpers.go:308	glossary.md only
integrity-reactions	compiler_difc_proxy.go:164	frontmatter.md ✅
cli-proxy	compiler_difc_proxy.go:415	frontmatter.md ✅
mcp-gateway	mcp_gateway.go	glossary.md only
byok-copilot	Mentioned as deprecated	glossary.md only

The features.copilot-requests flag is used in 15+ production workflow files in .github/workflows/ (private preview, per glossary.md), yet the schema provides no guidance, and IDEs cannot validate or auto-complete it.

Fix: Add a "properties" object to features in the schema enumerating known sub-keys with descriptions. Keep "additionalProperties": true for forward compatibility. Add features.copilot-requests and other used keys to frontmatter.md.

---

4. Schema Fields Missing from frontmatter.md

The following top-level schema fields have full, valid schema definitions and working implementations but are absent from the main docs/src/content/docs/reference/frontmatter.md reference page:

Field	Where Documented Instead
check-for-updates	frontmatter-full.md only
run-install-scripts	frontmatter-full.md only
experiments	Per-feature docs (github-tools.md, artifacts.md) but no frontmatter section
mcp-servers	tools.md (not cross-linked from frontmatter.md)
secret-masking	architecture.mdx and frontmatter-hash-specification.md but no frontmatter section
tracker-id	footers.md and frontmatter-hash-specification.md
rate-limit	rate-limiting-controls.md (not cross-linked from frontmatter.md)

The experiments field is particularly notable: the schema defines a comprehensive A/B testing system (variants, weights, hypotheses, metrics, guardrail metrics), but frontmatter.md has no section for it. Users relying on frontmatter.md as the primary reference won't discover this capability.

Fix: Add stub sections to frontmatter.md for each missing field with cross-links to the dedicated documentation pages.

---

5. infer Field: Description Says Deprecated, Schema Property Does Not

The infer field's description in the schema reads:

"DEPRECATED: Use 'disable-model-invocation' instead."

But there is no "deprecated": true JSON property. This is inconsistent with the pattern used for tools.grep and tools.serena (which have both the description text and the boolean property). Because extractDeprecatedFields() in pkg/parser/schema_deprecation.go:73 checks only the boolean property, infer escapes strict-mode detection.

This is a subset of finding #1, highlighted separately because it is an internal schema inconsistency (description contradicts structure).

---

6. dependencies Field: Compiler Warning vs Schema Description Mismatch

The dependencies field's schema description reads:

"APM package references to install."

The compiler emits:

"The 'dependencies' field is deprecated and no longer supported. Migrate to 'imports: - uses: shared/apm.md'"

The main frontmatter.md correctly documents this as deprecated:

"dependencies: frontmatter field is deprecated and no longer supported"

But the schema itself provides no deprecation signal, creating a three-way inconsistency: schema says "supported," docs say "deprecated," compiler warns "not supported."

---

Schema Improvements Needed

Recommended schema changes

1. Add "deprecated": true to properties.dependencies and update its description to reference the imports: - uses: shared/apm.md migration path.

2. Add "deprecated": true to properties.infer (the description already says DEPRECATED — just needs the boolean property to match).

3. Add "x-stability": "experimental" (or a $comment) to:

   • properties.rate-limit
   • properties.safe-outputs.properties.dispatch_repository
   • properties.safe-outputs.properties.merge-pull-request

4. Enumerate features sub-keys by adding "properties" to properties.features for: action-tag, action-mode, copilot-requests, awf-diagnostic-logs, integrity-reactions, cli-proxy, mcp-gateway, byok-copilot (deprecated).

---

Recommendations

1. [Highest priority] Add "deprecated": true to properties.dependencies and properties.infer in main_workflow_schema.json so strict mode correctly rejects these fields.
2. [High] Add an experimental status marker to rate-limit, safe-outputs.dispatch_repository, and safe-outputs.merge-pull-request in the schema.
3. [Medium] Enumerate features sub-keys in the schema with descriptions; promote copilot-requests, awf-diagnostic-logs, cli-proxy, mcp-gateway, and byok-copilot from glossary-only to frontmatter.md sections.
4. [Medium] Add stub sections with cross-links to frontmatter.md for: check-for-updates, run-install-scripts, experiments, mcp-servers, secret-masking, tracker-id, rate-limit.
5. [Low] Update properties.dependencies description to match compiler warning and frontmatter.md ("deprecated and no longer supported; migrate to imports: - uses: shared/apm.md").

---

Strategy Performance

• Strategy Used: Deprecated field consistency check (new — first run)
• Findings: 6 distinct categories, 2 critical (strict mode bypass risk)
• Effectiveness: HIGH
• Should Reuse: YES — checking deprecated: true against compiler warnings is a high-signal, low-noise approach

---

Next Steps

• Add "deprecated": true to properties.dependencies in main_workflow_schema.json
• Add "deprecated": true to properties.infer in main_workflow_schema.json
• Add experimental status signal to rate-limit, dispatch_repository, merge-pull-request in schema
• Add features sub-key enumeration to schema
• Add missing field stubs to frontmatter.md

References:

• §25245322929

Generated by Schema Consistency Checker · ● 435.2K · ◷

• expires on May 3, 2026, 6:10 AM UTC

[github-actions[bot]]

This discussion was automatically closed because it expired on 2026-05-03T06:10:17.726Z.

Closed by Workflow