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

[github-actions[bot]]

Summary

• Inconsistencies Found: 15 active (2 new today, 13 persistent)
• Categories Analyzed: Schema ↔ Parser, Schema ↔ Documentation, Parser ↔ Documentation, Workflow Files
• Strategy Used: Cross-Layer Field Diff (run codex naming #14, success_count=14)
• New Issues Today: 2
• Resolved Since Last Run: 0

Analysis covered 455 workflow files, pkg/parser/schemas/main_workflow_schema.json, pkg/workflow/*.go, pkg/constants/feature_constants.go, docs/src/content/docs/reference/frontmatter.md, and docs/src/content/docs/reference/frontmatter-full.md.

Workflow run: §24436529841

---

🔴 Critical Issues

NEW: engine.bare is undocumented in both reference docs

The engine.bare field was added by changeset patch-add-engine-bare-frontmatter-field and is:

• ✅ Defined in schema ($defs.engine_config, both extended-object and inline-engine branches)
• ✅ Implemented in Go (pkg/workflow/engine.go:158-160 and :298-300)
• ✅ Used in actual workflows: .github/workflows/smoke-claude.md:21 and .github/workflows/smoke-copilot.md:21
• ❌ Zero occurrences in docs/src/content/docs/reference/frontmatter.md
• ❌ Zero occurrences in docs/src/content/docs/reference/frontmatter-full.md

# Used in production workflows (smoke-claude.md, smoke-copilot.md) but not documented:
engine:
  id: claude
  bare: true   # disables CLAUDE.md / AGENTS.md / system-prompt loading

PERSISTENT: create-code-scanning-alert naming inconsistency

The YAML struct tag in pkg/workflow/compiler_types.go:511 uses the plural form (create-code-scanning-alerts) while the schema, implementation files, map accessors, and MCP parser all use the singular form (create-code-scanning-alert):

Location	Form used
pkg/parser/schemas/main_workflow_schema.json	create-code-scanning-alert ✅
pkg/workflow/create_code_scanning_alert.go:24,29	create-code-scanning-alert ✅
pkg/workflow/safe_outputs_config.go:162	create-code-scanning-alert ✅
pkg/workflow/compiler_types.go:511 (yaml tag)	create-code-scanning-alerts ❌
cli/workflows/test-copilot-create-code-scanning-alerts.md:9	create-code-scanning-alerts ❌

---

📚 Documentation Gaps

NEW: Feature flags inconsistency across reference documents

The following feature flags are defined in pkg/constants/feature_constants.go but have inconsistent coverage across the three reference locations:

Feature Flag	frontmatter.md	frontmatter-full.md	glossary.md
action-mode	✅	❌	✅
action-tag	❌	✅	❌
mcp-gateway	❌	✅	✅
mcp-scripts	✅	✅	❌
integrity-reactions	✅	❌	✅
cli-proxy	❌	❌	✅
copilot-requests	❌	❌	✅
disable-xpia-prompt	❌	❌	❌
copilot-integration-id	❌	❌	❌
difc-proxy (deprecated)	✅	❌	❌

disable-xpia-prompt and copilot-integration-id are entirely absent from all user-facing documentation.

View other persistent documentation gaps

Schema fields missing from frontmatter.md (12 fields)

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

Schema fields missing from frontmatter-full.md (2 fields)

pre-steps, run-install-scripts

Safe-outputs tools missing from frontmatter-full.md (2 tools)

upload-artifact and report-incomplete are defined in the schema and implemented in Go (pkg/workflow/publish_artifacts.go:54, pkg/workflow/report_incomplete.go:26) but absent from the reference full spec. 67 tools total in schema; 65 documented.

observability.otlp sub-fields undocumented

The observability field only appears as observability: {} in frontmatter-full.md. The nested fields otlp.endpoint and otlp.headers (now correctly typed as string after the OTLP headers migration) are not shown.

mcp-scripts in frontmatter-full.md shows no sub-fields

frontmatter-full.md shows mcp-scripts: {} only — the sub-field structure is not documented.

aw.json repo-level config is undocumented

No documentation exists anywhere in docs/ for .github/workflows/aw.json.

---

⚠️ Schema Improvements Needed

features object has no property schemas

"features": {
  "type": "object",
  "additionalProperties": true,
  "properties": {}   // ← empty!
}

action-mode accepts only dev | release | script | action (enforced in pkg/workflow/action_mode.go) but these enum values are not defined in the schema. IDE autocomplete shows action-tag from schema examples but not action-mode. Invalid values like features: { action-mode: "invalid" } pass JSON Schema validation silently.

Schema features.examples shows action-tag (the action SHA/tag reference), while frontmatter.md documents action-mode as the primary feature. These are different features and the schema examples are misleading.

View constraint validation gaps

These schema constraints are defined but not enforced in Go:

Field	Schema Constraint	Go validation
tracker-id	maxLength: 128	Missing (minLength/charset only)
rate-limit.max	maximum: 10	Missing
rate-limit.window	minimum: 1, maximum: 180	Missing
safe-outputs.max-patch-size	maximum: 10240	Missing
upload-artifact.defaults.if-no-files	enum: warn|error|ignore	Missing

---

🗂️ Stale Data

Autocomplete data still references safe-inputs (renamed to mcp-scripts)

• docs/public/editor/autocomplete-data.json:1917 — still lists "safe-inputs"
• docs/scripts/generate-autocomplete-data.js:40 — still lists 'safe-inputs'

The rename from safe-inputs → mcp-scripts was done (changeset minor-rename-safe-inputs-to-mcp-scripts) but the autocomplete data was not regenerated/updated.

mcp_config_schema.json — dead validation code

pkg/parser/schemas/mcp_config_schema.json is compiled into Go but ValidateMCPConfigWithSchema is a stub comment — never actually called. MCP config is accepted without schema validation.

---

Recommendations

1. [High] Document engine.bare in frontmatter.md (under Engine section) and frontmatter-full.md. The field is already deployed in production smoke workflows.
2. [High] Fix compiler_types.go:511 yaml tag from create-code-scanning-alerts to create-code-scanning-alert (singular) to match the schema and all other code.
3. [Medium] Regenerate docs/public/editor/autocomplete-data.json and update docs/scripts/generate-autocomplete-data.js to replace safe-inputs with mcp-scripts.
4. [Medium] Add property schemas to features in main_workflow_schema.json — at minimum define action-mode with its enum values and fix the features.examples to show action-mode instead of action-tag.
5. [Medium] Create a unified feature flags table in frontmatter.md covering all 9 active flags (action-mode, action-tag, mcp-gateway, mcp-scripts, integrity-reactions, cli-proxy, copilot-requests, disable-xpia-prompt, copilot-integration-id).
6. [Medium] Add report-incomplete and upload-artifact to the safe-outputs section of frontmatter-full.md.
7. [Low] Add maxLength: 128 enforcement to extractTrackerID in pkg/workflow/frontmatter_extraction_metadata.go.
8. [Low] Add rate-limit.max (≤10) and rate-limit.window (1–180) bounds validation in pkg/workflow/role_checks.go.

Strategy Performance

• Strategy Used: Cross-Layer Field Diff
• Findings: 15 active (2 new, 13 persistent)
• Effectiveness: HIGH
• Should Reuse: YES

References:

• §24436529841

Generated by Schema Consistency Checker · ● 281.1K · ◷

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