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

[github-actions[bot]]

Overview

This run used Strategy 13: Documentation Completeness Audit + Schema Structural Defects (day 55, proven strategy path). Analysis covered all four consistency dimensions: schema ↔ parser/compiler, schema ↔ documentation, schema ↔ real workflows, and parser ↔ documentation. Two parallel sub-agents ran full cross-references of FrontmatterConfig, WorkflowData, JSON schema definitions, and primary documentation. 9 new findings were identified — including two structural schema bugs that would actively reject valid user configurations.

Run reference: §22345778423

---

Summary

Severity	Count	Areas
Critical	3	Schema/implementation mismatch, type mismatch, schema structural defect
Medium	5	Primary docs missing fields, undocumented feature flags
Low	3	Overly permissive schema, struct-less field, dual-write side effect

---

Critical Issues

1. bots Schema/Implementation Path Mismatch

The JSON schema defines bots as a top-level property (properties.bots). The implementation in pkg/workflow/role_checks.go:141 extracts it exclusively from on.bots (nested inside the trigger block). The primary documentation (docs/src/content/docs/reference/frontmatter.md:263) correctly shows on.bots — and even includes a migration note referencing gh aw fix to migrate from the old top-level form.

Impact: The schema is stale — it still documents the old top-level position that was migrated away from. Any schema validator will accept bots: [...] at the root but the compiler will silently ignore it; on.bots: [...] is the correct form but the schema will not validate it as a bots field.

Fix: Remove properties.bots from the top-level schema and instead add bots as a property inside the on: field definition.

pkg/parser/schemas/main_workflow_schema.json — move bots from top-level to on.properties.bots

---

2. environment Type Mismatch Between Schema and Go Struct

The schema defines environment using oneOf — accepting either a plain string ("production") or an object ({ name: "production", url: "..." }). However, FrontmatterConfig.Environment in pkg/workflow/frontmatter_types.go is typed as map[string]any, which cannot deserialize a plain string. A user writing environment: production will trigger a silent deserialization failure.

Impact: Any workflow using the GitHub Actions shorthand environment: (name) will silently fail to have the environment configured in the compiled output. No error is surfaced.

Relevant files:

• pkg/workflow/frontmatter_types.go — Environment map[string]any
• pkg/parser/schemas/main_workflow_schema.json — properties.environment (oneOf string/object)
• docs/src/content/docs/reference/frontmatter.md:528 — documents string shorthand as valid

Fix: Change FrontmatterConfig.Environment to any (like Plugins any) and add deserialization handling for the string case, or extract it as a raw YAML section like Container and Services.

---

3. jobs.(job).strategy Schema Blocks All Matrix Configurations

In the jobs schema definition, the strategy property for job objects is defined with "additionalProperties": false but no properties defined. This means every key inside strategy: — including the standard matrix:, fail-fast:, and max-parallel: — is rejected by the schema validator.

Impact: Any user (or CI tool) running schema validation against a workflow file that uses jobs.(job).strategy.matrix: will receive a validation error, even though the implementation fully supports it.

Fix: Add the standard GitHub Actions strategy properties to the schema:

"strategy": {
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "matrix": { "type": "object", "additionalProperties": true },
    "fail-fast": { "type": "boolean" },
    "max-parallel": { "type": "integer", "minimum": 1 }
  }
}

---

Documentation Gaps

Fields Missing from Primary Reference (frontmatter.md)

The following fields have full schema definitions, typed Go structs, and active compiler implementations — but are entirely absent from docs/src/content/docs/reference/frontmatter.md, the primary user-facing reference:

Field	Schema	Struct	Implementation	In frontmatter-full.md
secret-masking	Defined (steps array, additionalProperties: false)	*SecretMaskingConfig	redact_secrets.go, compiler_orchestrator_tools.go	Yes (line 4209)
disable-model-invocation	Defined (boolean)	Parser allowlisted	No compiler implementation found	Yes (line 887)
inlined-imports	Defined (boolean)	InlinedImports bool	compiler_orchestrator_workflow.go, compiler_yaml.go	Not verified
rate-limit	Fully defined (max, window, events, ignored-roles)	*RateLimitConfig	compiler_activation_jobs.go	Not verified

secret-masking is particularly notable: it supports import merging (import_processor.go line 831), is included in frontmatter hashes (frontmatter_hash.go line 132), and has a dedicated redact_secrets.go implementation — yet is completely invisible to users reading the main reference.

rate-limit is marked experimental in compiler.go:222 but has a well-defined schema with four sub-fields and is actively used in the compilation pipeline.

Feature Flags Undocumented in Primary Reference

The features: field uses additionalProperties: true with no enumeration of valid keys. The following feature flag constants are defined and actively used in the compiler/workflow code but have no documentation in frontmatter.md (and limited/no coverage in other reference docs):

Feature Flag	Constant	Used In
copilot-requests	CopilotRequestsFeatureFlag	tools.go, copilot_engine_execution.go, copilot_engine_installation.go, threat_detection.go
dangerous-permissions-write	DangerousPermissionsWriteFeatureFlag	dangerous_permissions_validation.go
disable-xpia-prompt	DisableXPIAPromptFeatureFlag	unified_prompt_step.go
safe-inputs	SafeInputsFeatureFlag	claude_engine.go, codex_engine.go
mcp-gateway	MCPGatewayFeatureFlag	Has a dedicated mcp-gateway.md page but not cross-referenced from frontmatter.md

Only action-mode is documented. action-tag appears in frontmatter-full.md only. Users have no discoverable list of valid feature flags.

---

Schema Improvements Needed

Minor Schema Issues

steps / post-steps overly permissive: Both fields use oneOf[object, array] at the top level. The object alternative would allow a single bare step object instead of an array — which is not how the implementation processes them. In practice steps are always arrays; the object alternative is a permissive artifact that could confuse schema-aware editors.

infer deprecated field still present: The infer boolean is marked DEPRECATED in its schema description (pointing to disable-model-invocation). The field is allowlisted in include_processor.go but no Go code reads its value. The schema should either be removed or use deprecated: true and mark it as a no-op clearly.

---

Parser/Compiler Issues

MCP Config: `network` Field is Struct-Less

The network property in mcp_config_schema.json is parsed from the raw map in pkg/parser/mcp.go:735 but never stored on MCPServerConfig or BaseMCPServerConfig. The proxy-args value nested inside network is extracted and stored on MCPServerConfig.ProxyArgs, but the network object itself is discarded after extraction.

Any consumer that receives a parsed MCPServerConfig struct cannot inspect network configuration beyond ProxyArgs — it would need the original raw map. This creates a data loss risk if network.allowed is inspected post-parse.

MCP Config: `entrypoint` Dual-Write Side Effect

In pkg/parser/mcp.go:666-669, the entrypoint field value is both:

1. Stored on config.Entrypoint
2. Appended to config.Args as --entrypoint (value)

If any downstream consumer reconstructs a command from both config.Entrypoint and config.Args, the entrypoint would be applied twice.

---

Confirmed Still-Present Issues (From Prior Runs)

The following critical bugs identified in earlier strategy runs were confirmed not yet fixed:

Issue	First Found	Status
hasSafeOutputType() missing 11 operations — silent import conflict pass-through	Strategy 11 (2026-02-22)	Still present
tools.serena.languages schema restricts to 6 languages; code supports 30+	Strategy 11 (2026-02-22)	Still present
Schema network.firewall description incorrectly says Copilot-only	Strategy 12 (2026-02-23)	Not verified this run
cleanup_script parsed from engine.firewall but absent from schema	Strategy 12 (2026-02-23)	Not verified this run
permissions schema missing repository-projects and organization-projects scopes	Strategy 12 (2026-02-23)	Not verified this run

---

Recommendations

1. Fix bots schema placement — move bots from properties.bots (top-level) to inside on: definition to match both the implementation and the documentation.
2. Fix environment type handling — change FrontmatterConfig.Environment from map[string]any to any and add deserialization for the string shorthand case.
3. Fix jobs.(job).strategy schema — add matrix, fail-fast, and max-parallel as explicitly allowed properties so schema validation does not reject standard GitHub Actions matrix strategies.
4. Add secret-masking to frontmatter.md — document this fully-implemented field in the primary reference alongside its import merging behavior.
5. Add feature flag enumeration to docs — either add a dedicated feature flags reference page or add a table of supported flags to the features: section in frontmatter.md.
6. Add inlined-imports and rate-limit to frontmatter.md — both are active compiler features with full schema coverage.

---

Strategy Performance

• Strategy used: Strategy 13 — Documentation Completeness Audit + Schema Structural Defects
• Findings: 9 new + 3 confirmed carry-overs
• Effectiveness: High — structural schema bugs (critical 2 and 3) directly affect schema validators and user-facing tooling
• Should reuse: Yes (high yield for structural + documentation gaps); consider combining with Schema Constraint Validation in future runs

---

References:

• §22345778423

AI generated by Schema Consistency Checker

• expires on Feb 25, 2026, 10:13 AM UTC