[Schema Consistency] Schema Consistency Check — 2026-04-14

[github-actions[bot]]

Summary

• Strategy used: Cross-Layer Field Diff (proven, day-of-year 104 → slot 4/9 → reuse)
• New findings: 3 new issues discovered (features schema gaps, action-mode enum mismatch, integrity-reactions reference docs gap)
• Persistent issues: 19 known gaps carried forward, all unresolved
• Recent commit analyzed: 0eb9816 — auto-enables cli-proxy when integrity-reactions is set (correctly documented in maintaining-repos.md)
• Workflow run: §24381073062

---

Critical Issues

⚠️ NEW — features Schema Has No Property Definitions (features.action-mode Enum Missing)

The features object in pkg/parser/schemas/main_workflow_schema.json uses additionalProperties: true but defines zero property schemas. In contrast, pkg/workflow/action_mode.go defines a strict Go enum with four valid values (dev, release, script, action) that is enforced at compile time — but the schema accepts any string (e.g., action-mode: "production" or action-mode: 42). This means IDE schema validation silently passes invalid action-mode values.

Additionally, the schema's features.examples array shows action-tag as the example feature flag — but action-tag is not documented in frontmatter.md (only in compilation-process.md), while action-mode is fully documented in frontmatter.md but absent from the schema examples. This creates a confusing disconnect for anyone relying on IDE autocomplete from the schema.

# What the schema examples show (misleading):
features:
  action-tag: "v1.0.0"

# What frontmatter.md documents (but schema doesn't define):
features:
  action-mode: "script"  # enum: dev | release | script | action

Impact: Schema-based tools (IDE plugins, linters) cannot warn about invalid action-mode values. The enum in Go (pkg/workflow/action_mode.go:35-37) is the only enforcement.

Fix: Add property definitions to features in the schema:

"features": {
  "properties": {
    "action-mode": {
      "type": "string",
      "enum": ["dev", "release", "script", "action"],
      "description": "..."
    },
    "cli-proxy": { "type": "boolean" },
    "copilot-requests": { "type": "boolean" },
    "mcp-gateway": { "type": "boolean" },
    "integrity-reactions": { "type": "boolean" },
    "copilot-integration-id": { "type": "boolean" },
    "disable-xpia-prompt": { "type": "boolean" }
  },
  "additionalProperties": true
}

---

⚠️ NEW — integrity-reactions and cli-proxy Features Not in Reference Docs

The integrity-reactions and cli-proxy feature flags are documented in docs/src/content/docs/guides/maintaining-repos.md (a guide) but not in frontmatter.md or frontmatter-full.md (the reference sections). The glossary entry for feature flags only mentions copilot-requests and mcp-gateway — both integrity-reactions and cli-proxy are absent. This is particularly important because integrity-reactions has significant behavior: it auto-enables cli-proxy (as of commit 0eb9816).

copilot-integration-id (added ~2026-04-11, pkg/constants/feature_constants.go) has no docs anywhere.

Files needing updates:

• docs/src/content/docs/reference/frontmatter.md — add integrity-reactions, cli-proxy, copilot-integration-id to the Feature Flags section
• docs/src/content/docs/reference/frontmatter-full.md — add these feature flags with examples
• docs/src/content/docs/reference/glossary.md:274 — update feature flags list

---

Persistent Issues (Ongoing)

Documentation Gaps (9 issues)

#	Field / Feature	Missing From	Notes
1	observability.otlp.* (endpoint, headers)	frontmatter-full.md	Schema has full sub-field definitions; docs only show observability: {}
2	sandbox.mcp.keepalive-interval	frontmatter-full.md	Defined in schema, undocumented
3	safe-outputs: report-incomplete tool	frontmatter-full.md	Only 2 tools missing: report-incomplete and upload-artifact
4	safe-outputs: upload-artifact tool	frontmatter-full.md	See above
5	12 top-level fields	frontmatter.md	check-for-updates, disable-model-invocation, import-schema, infer, inlined-imports, mcp-servers, observability, pre-steps, rate-limit, run-install-scripts, secret-masking, tracker-id
6	pre-steps, run-install-scripts	frontmatter-full.md	Both fields in schema but absent from full reference
7	Feature flags: copilot-requests, mcp-gateway, disable-xpia-prompt	frontmatter.md / frontmatter-full.md	Undocumented in reference; only in glossary or guides
8	mcp-scripts sub-fields	frontmatter-full.md	Only mcp-scripts: {} shown; no docs for description, inputs, script/run/py/go, env, timeout
9	aw.json repo-level config	All docs	Has full schema (repo_config_schema.json) and Go implementation but no user-facing documentation

Constraint Validation Gaps — Schema Says X, Go Doesn't Enforce It (6 issues)

Field	Schema Constraint	Go Validation	File
tracker-id	maxLength: 128	Only checks minLength: 8 and character pattern	pkg/workflow/frontmatter_extraction_metadata.go:91
rate-limit.max	maximum: 10	Only checks > 0	pkg/workflow/role_checks.go:175
rate-limit.window	minimum: 1, maximum: 180	Only checks > 0 (window:0 silently falls back)	pkg/workflow/role_checks.go:62
safe-outputs.max-patch-size	maximum: 10240	Only checks >= 1	pkg/workflow/safe_outputs_config.go:408
upload-artifact.max-uploads	maximum: 20	Only checks > 0	pkg/workflow/publish_artifacts.go:80
upload-artifact.defaults.if-no-files	enum: ["error", "ignore"]	Accepts any non-empty string	pkg/workflow/publish_artifacts.go:151

A user setting rate-limit: {max: 100, window: 999} or upload-artifact: {max-uploads: 99} will compile successfully but violate the schema's intent.

Dead Code — MCP Schema Never Used for Validation

pkg/parser/schemas/mcp_config_schema.json is compiled into Go as getCompiledMcpConfigSchema(), and there is a case mcpConfigSchema branch in validateWithSchema(). However, ValidateMCPConfigWithSchema() in schema_validation.go is a comment stub with no function body — it was never implemented. The compiled MCP schema is therefore never called for actual validation of MCP server configurations.

Impact: MCP server configs with structural errors (wrong types, missing fields) pass through without schema validation.

Stale Data — Renamed safe-inputs Still Present in Autocomplete Files (2026-04-13)

After the safe-inputs → mcp-scripts rename:

• docs/public/editor/autocomplete-data.json:1917 still contains "safe-inputs" alongside the correct "mcp-scripts" entry at line 1694
• docs/scripts/generate-autocomplete-data.js:40 still lists 'safe-inputs' in the frontmatter key list

IDE autocomplete will offer both the old and new key names.

---

Recommendations

1. Add property schemas to features in main_workflow_schema.json — especially action-mode as a typed enum. This is a low-effort, high-value change for IDE users.

2. Document integrity-reactions, cli-proxy, and copilot-integration-id in frontmatter.md Feature Flags section. The recent 0eb9816 commit makes integrity-reactions a user-facing feature; its reference docs should be discoverable without reading guides.

3. Remove stale safe-inputs from autocomplete-data.json:1917 and generate-autocomplete-data.js:40.

4. Add upper-bound constraint checks for rate-limit.max, rate-limit.window, upload-artifact.max-uploads, safe-outputs.max-patch-size, and tracker-id. The schema defines these limits; the compiler should enforce them with clear error messages rather than silently accepting out-of-range values.

5. Implement or remove ValidateMCPConfigWithSchema — either write the body of the function or remove the dead mcpConfigSchema case from validateWithSchema().

---

Strategy Performance

• Strategy: Cross-Layer Field Diff
• Run count: 13 (12 previous + this run)
• New findings this run: 3
• Effectiveness: High — consistently surfaces actionable gaps
• Should reuse: Yes

References: §24381073062

Generated by Schema Consistency Checker · ● 315.5K · ◷

• expires on Apr 15, 2026, 4:40 AM UTC