[Schema Consistency] Schema Consistency Audit - 2026-04-19

[github-actions[bot]]

Schema consistency analysis across main_workflow_schema.json, parser/compiler code, documentation, and .github/workflows/ files. Used new Cross-Reference Map strategy (4-way intersection).

Summary

Category	Count
Inconsistencies Found	7
Critical (potential user-facing bugs)	1
Medium (code quality / misleading)	3
Low (documentation gaps)	3
Strategy	Cross-Reference Map (new)
Schema additionalProperties	false ✓
Workflow files using non-schema fields	0 ✓

---

Critical Issues

1. disable-model-invocation — Schema Field With No Compiler Implementation

Severity: ⚠️ Medium-High

• Schema (main_workflow_schema.json): defines disable-model-invocation as a top-level boolean field
• Code: only appears in pkg/parser/include_processor.go as an entry in a "known fields" whitelist — the compiler never reads this value and never changes behaviour based on it
• Documentation: mentioned only in frontmatter-full.md (no explanatory section)

If a user sets disable-model-invocation: true expecting the agent to skip model calls, nothing will happen — the field is silently ignored by the compiler.

Recommendation: Either implement the field in the compiler (propagate to engine config) or add a deprecation notice/warning when the field is present.

---

Medium Issues

2. create-code-scanning-alert vs create-code-scanning-alerts — Plural/Singular Naming Split

Severity: ⚠️ Medium

The field name is inconsistent across layers:

Layer	Value
Schema	create-code-scanning-alert (singular)
Docs (safe-outputs.md, frontmatter-full.md)	create-code-scanning-alert (singular)
Code — map access in create_code_scanning_alert.go:24	outputMap["create-code-scanning-alert"] (singular)
Code — SafeOutputsConfig struct yaml tag	yaml:"create-code-scanning-alerts,omitempty" (plural)
daily-safe-output-integrator.md markdown content	create-code-scanning-alerts (plural)

The struct's yaml tag is plural but all external-facing surfaces use singular. Since extractSafeOutputsConfig() processes safe-outputs via direct map access (not YAML struct deserialization), this doesn't cause a runtime bug — but it misleads developers reading the struct and is propagated into the daily-safe-output-integrator.md workflow which documents the plural form to users.

Recommendation: Rename the struct field yaml tag to yaml:"create-code-scanning-alert,omitempty" (singular) and update daily-safe-output-integrator.md references.

Relevant code locations

• pkg/workflow/compiler_types.go — SafeOutputsConfig.CreateCodeScanningAlerts yaml tag
• pkg/workflow/create_code_scanning_alert.go:24 — correct singular map access
• .github/workflows/daily-safe-output-integrator.md lines 100, 154, 412, 423, 641

3. SafeOutputsConfig Uses yaml: Tags But Is Parsed Via JSON

Severity: ⚠️ Medium (latent / architectural)

ParseFrontmatterConfig() (pkg/workflow/frontmatter_parsing.go) converts the raw frontmatter map[string]any → JSON → FrontmatterConfig via json.Marshal/json.Unmarshal. This means json: tags are used for field mapping, yaml: tags are ignored.

SafeOutputsConfig (stored in FrontmatterConfig.SafeOutputs) uses only yaml: tags. When JSON-unmarshaling the safe-outputs block into SafeOutputsConfig, all hyphenated keys like create-issue, add-comment, etc. will not be matched (JSON unmarshal falls back to exported field name, case-insensitive — CreateIssues ≠ create-issue).

FrontmatterConfig.SafeOutputs is therefore always nil/empty after ParseFrontmatterConfig. Actual processing uses extractSafeOutputsConfig() (direct map access), so there is no runtime bug today. But this is a trap for future callers who access parsedFrontmatter.SafeOutputs expecting it to be populated.

Recommendation: Either add json: tags to SafeOutputsConfig matching the hyphenated keys, or add a code comment on FrontmatterConfig.SafeOutputs warning that it is never populated via ParseFrontmatterConfig (intentional — use extractSafeOutputsConfig() instead).

Relevant code locations

• pkg/workflow/frontmatter_parsing.go:12-32 — JSON marshal/unmarshal path
• pkg/workflow/compiler_types.go:526 — SafeOutputsConfig struct (yaml tags only)
• pkg/workflow/safe_outputs_config.go:54 — extractSafeOutputsConfig() (correct path)
• pkg/workflow/frontmatter_types.go:207 — FrontmatterConfig.SafeOutputs

4. FrontmatterConfig Has Fields Not In Schema (version, include)

Severity: ⚠️ Low-Medium

The schema has "additionalProperties": false. Two fields exist in FrontmatterConfig that are absent from the schema:

• Version string \json:"version,omitempty"`— serialized back to map infrontmatter_serialization.go:81`
• Include any \json:"include,omitempty"`— serialized back to map infrontmatter_serialization.go:212`

No workflows in .github/workflows/ currently use these fields at the top level, so schema validation doesn't fail. However:

• If code sets fc.Version and then round-trips back to a map that is re-validated, schema validation would fail.
• Developers may be confused about what these fields are for.

version may be used for Copilot custom-agent files (which aren't validated against the main schema); include appears to be an internal/legacy import alias for imports.

Recommendation: Add version and include to the schema (with deprecation notes if appropriate) or document in code comments that these fields bypass schema validation.

---

Documentation Gaps

5. Fields in Schema With No Dedicated Documentation Section

The following schema-defined fields are missing from the main frontmatter.md reference and only appear (if at all) in frontmatter-full.md or scattered docs:

Field	Status	Notes
tracker-id	⚠️ Only in footers.md	No frontmatter.md section
check-for-updates	❌ Only in frontmatter-full.md	No dedicated doc
run-install-scripts	❌ Only in frontmatter-full.md	No dedicated doc
secret-masking	⚠️ Only briefly in imports.md	No dedicated section
observability	⚠️ Scattered across compilation-process.md, artifacts.md	No frontmatter section
disable-model-invocation	❌ Only in frontmatter-full.md	See Critical Issue #1

Recommendation: Add brief sections for each of these fields to frontmatter.md (or cross-reference the dedicated doc files).

---

Schema vs Code Coverage

Schema fields not in `FrontmatterConfig` struct (handled via direct map access)

These fields exist in the schema but are not typed in FrontmatterConfig. They are handled by reading directly from frontmatter[key] in specific compiler files:

Field	Handled In	Notes
bots	pkg/workflow/role_checks.go via onMap["bots"]	On-section sub-field
command	pkg/parser/schema_triggers.go	Command trigger processing
dependencies	pkg/workflow/compiler_orchestrator_tools.go	Deprecated field
github-app	pkg/workflow/workflow_github_app.go	Direct map access
infer	pkg/parser/include_processor.go whitelist only	Deprecated, use disable-model-invocation
disable-model-invocation	pkg/parser/include_processor.go whitelist only	Not processed (see Issue #1)

Deprecated/removed tools in schema not in `ToolsConfig` struct

Tool	Schema Status	Struct Status
tools.grep	DEPRECATED in schema (always available via bash)	Falls to Custom inline map
tools.serena	REMOVED in schema (use shared/mcp/serena.md)	Falls to Custom inline map

These are handled gracefully (no error) but silently ignored. The schema's deprecation message guides users correctly.

Recommendations

1. Implement or deprecate disable-model-invocation — either wire it to the compiler or emit a warning/error when used
2. Fix create-code-scanning-alert yaml tag to use singular in SafeOutputsConfig struct, update daily-safe-output-integrator.md
3. Add json: tags to SafeOutputsConfig or document that FrontmatterConfig.SafeOutputs is always nil
4. Add version/include to schema or restrict their use to non-validated contexts
5. Add frontmatter.md sections for tracker-id, check-for-updates, run-install-scripts, secret-masking, observability

Strategy Performance

• Strategy: Cross-Reference Map (4-way intersection) — NEW strategy (day 109 mod 10 = 9)
• Findings: 7 distinct inconsistencies
• Effectiveness: HIGH — parallel schema/struct/code comparison caught structural issues not visible from any single layer
• Should Reuse: YES — particularly effective for yaml/json tag mismatch detection

References:

• §24621083532

Generated by Schema Consistency Checker · ● 763K · ◷

• expires on Apr 20, 2026, 4:49 AM UTC

[github-actions[bot]]

This discussion has been marked as outdated by Schema Consistency Checker.

A newer discussion is available at Discussion #27270.