[Schema Consistency] Schema Consistency Check - 2026-04-09

[github-actions[bot]]

Summary

• Inconsistencies Found: 4 new (2 schema/implementation gaps, 2 documentation gaps)
• Strategy Used: MCP Config Schema Deep Dive + Default Value Analysis (new strategy, day 099 % 10 = 9)
• Categories Analyzed: Schema, Parser/Compiler, Documentation, Workflows
• Workflow Run: §24172367990

All 187 workflow files in .github/workflows/ use only schema-valid frontmatter fields. Default values are consistent between schema and Go code for the fields checked (rate-limit.window=60, max-patch-size=1024, upload-asset branch, mcp-scripts timeout=60).

Critical Issues

1. mcp_config_schema.json validation is dead code

pkg/parser/schema_validation.go:102 ends with a comment stub that was never implemented:

// ValidateMCPConfigWithSchema validates MCP configuration using JSON schema
```

No function body follows. As a result, `getCompiledMcpConfigSchema()` (compiled and cached in `pkg/parser/schema_compiler.go:67`) is never called for actual runtime validation. The `validateWithSchema()` switch has a `case mcpConfigSchema:` branch (`schema_compiler.go:203`) that is dead code — no caller passes `mcpConfigSchema` to it.

**Impact**: `mcp_config_schema.json` is maintained (14 properties defined, with `network` field marked deprecated) but its compiled form is never used to enforce constraints on MCP server configurations. Users can set invalid MCP server configs that would fail the schema but are not caught.

**Files**: `pkg/parser/schema_validation.go:102`, `pkg/parser/schema_compiler.go:67,192-210`

---

#### 2. `proxy-args` missing from `$defs.stdio_mcp_tool` in main workflow schema

`pkg/parser/schemas/main_workflow_schema.json` defines `$defs.stdio_mcp_tool` with `"additionalProperties": false`. The properties list does **not** include `proxy-args`:

```
allowed, args, command, container, entrypoint, entrypointArgs, env, mounts, network, registry, type, version

However, Go code fully supports proxy-args as a top-level MCP server field:

• pkg/workflow/mcp_config_validation.go:190 — "proxy-args": true in knownToolFields
• pkg/workflow/mcp_config_custom.go:90,95 — included in propertyOrder for both stdio variants
• pkg/workflow/mcp_config_custom.go:499-511,690 — rendering and extraction logic

proxy-args only appears in the schema inside the deprecated network.properties["proxy-args"] sub-object of stdio_mcp_tool.

Impact: A workflow using proxy-args at the top level of an mcp-servers: entry would pass Go's custom ValidateMCPConfigs validation but fail JSON schema validation (stdio_mcp_tool.additionalProperties: false). The two validation layers disagree on whether this field is valid.

Fix: Add proxy-args to $defs.stdio_mcp_tool.properties in main_workflow_schema.json (and remove or retain the deprecated network.proxy-args with a deprecation notice).

View schema diff needed

In main_workflow_schema.json, $defs.stdio_mcp_tool.properties should add:

"proxy-args": {
  "type": "array",
  "items": { "type": "string" },
  "description": "Custom proxy arguments for container-based MCP servers",
  "examples": [["--proxy", "(proxy.example.com/redacted)
}

Documentation Gaps

3. .github/workflows/aw.json — repository-level config is undocumented

The repository-level configuration file (.github/workflows/aw.json) has:

• A full JSON schema: pkg/parser/schemas/repo_config_schema.json
• A complete Go implementation: pkg/workflow/repo_config.go
• Schema validation at load time (validateRepoConfigJSON)
• Usage in maintenance workflow generation

But zero documentation in docs/src/content/docs/. Users cannot discover that this file exists or what it does.

Supported configuration (from repo_config_schema.json):

{ "maintenance": false }

or

{
  "maintenance": {
    "runs_on": "ubuntu-slim"
  }
}

Note: The runs_on field uses underscore (JSON file format) rather than the hyphen convention used in .md frontmatter — this is intentional but potentially confusing.

Impact: Users cannot customize the maintenance workflow runner or disable maintenance entirely without reading the source code.

---

4. pre-steps field has no frontmatter reference entry

pre-steps is defined in main_workflow_schema.json with a detailed description including step output access patterns and token minting use cases. It is not present in:

• docs/src/content/docs/reference/frontmatter.md (0 occurrences)
• docs/src/content/docs/reference/frontmatter-full.md (0 occurrences)

It is only mentioned incidentally in imports.md and dependencies.md in the context of other features.

post-steps by contrast appears in frontmatter.md (2 occurrences) and frontmatter-full.md (3 occurrences), creating an asymmetry.

Impact: Users seeking to mint short-lived tokens before checkout (the schema's stated use case) cannot find this feature in the reference documentation.

Schema Improvements Needed

Field	Location	Issue
proxy-args	$defs.stdio_mcp_tool.properties	Missing; causes schema/Go validation mismatch
proxy-args	$defs.stdio_mcp_tool.properties.network	Marked deprecated but is the only schema location

Parser/Compiler Updates Required

Location	Issue
pkg/parser/schema_validation.go:102	Implement ValidateMCPConfigWithSchema or remove dead comment
pkg/parser/schema_compiler.go:203	case mcpConfigSchema: is dead code in validateWithSchema

Workflow Violations

No workflow files in .github/workflows/ use invalid or undocumented frontmatter fields. All 187 scanned workflows use only schema-valid top-level keys.

Recommendations

1. Add proxy-args to $defs.stdio_mcp_tool.properties in main_workflow_schema.json — resolves the schema/Go validation disagreement immediately
2. Implement or remove ValidateMCPConfigWithSchema — either complete the function body (calling validateWithSchema(mcpConfig, mcpConfigSchema, ...)) or remove the dead comment and the dead case mcpConfigSchema: branch in validateWithSchema
3. Document .github/workflows/aw.json — add a reference page or section covering the repository-level configuration, its schema, and use cases (custom runner for maintenance, disabling maintenance)
4. Add pre-steps to frontmatter reference docs — create a section parallel to post-steps covering token minting and pre-checkout setup

Strategy Performance

• Strategy Used: MCP Config Schema Deep Dive + Default Value Analysis (NEW)
• Findings: 4 new issues
• Effectiveness: HIGH — new angles (dead code detection, schema-vs-validation-layer comparison) surfaced issues not found by previous strategies
• Should Reuse: YES — particularly the dead code / unused compiled schema check

Persistent Issues (from Previous Runs, Not Yet Fixed)

View persistent issues (4 categories, 14 total items)

Constraint Gaps (from 2026-04-08):

• tracker-id maxLength (128) not validated in Go
• rate-limit.max maximum (10) not validated in Go
• rate-limit.window min/max bounds (1–180) not validated in Go
• safe-outputs.max-patch-size maximum (10240) not validated in Go

Naming Inconsistency (from 2026-04-07):

• create-code-scanning-alerts (plural) yaml tag in compiler_types.go:462 vs singular in schema and map keys

Docs Gaps (from 2026-04-07):

• observability.otlp sub-fields not in frontmatter-full.md
• sandbox.mcp.keepalive-interval not in frontmatter-full.md
• 29 safe-outputs tools missing from frontmatter-full.md
• Feature flags (copilot-requests, mcp-gateway, etc.) not documented in frontmatter reference

References:

• §24172367990

Generated by Schema Consistency Checker · ● 657.4K · ◷

• expires on Apr 10, 2026, 4:39 AM UTC