[Schema Consistency] Schema Consistency Report - 2026-04-30

[github-actions[bot]]

Analysis of schema, parser/compiler, documentation, and workflow files for inconsistencies. Strategy used: Hybrid — Schema vs Code Struct Comparison + Engine Enum Cross-check + Documentation Coverage Audit (first run; no prior cache).

Summary

Metric	Value
Inconsistencies Found	7
Categories Analyzed	Schema, Parser/Compiler, Documentation, Workflows
Strategy Used	Hybrid (Schema↔Struct, Engine Enum, Docs Coverage)
New Strategy	Yes (no prior cache)
Analysis Date	2026-04-30
Workflow Run	§25147873049

---

Critical Issues

1. safe-outputs.create-code-scanning-alert — Singular/Plural Naming Mismatch

Impact: Medium — Naming inconsistency between the struct yaml tag and all other references.

Layer	Value
JSON Schema (main_workflow_schema.json:6345)	create-code-scanning-alert (singular)
Parsing code (create_code_scanning_alert.go:24)	reads outputMap["create-code-scanning-alert"] (singular)
Documentation (safe-outputs.md:690)	create-code-scanning-alert (singular)
SafeOutputsConfig struct yaml tag (compiler_types.go:575)	yaml:"create-code-scanning-alerts,omitempty" (plural)

The Go struct yaml tag says create-code-scanning-alerts (plural) while the schema, parsing code, and documentation all use create-code-scanning-alert (singular). Since parsing is done manually via map key lookup rather than yaml.Unmarshal, this doesn't cause a runtime bug — but it is misleading to developers reading the struct, and could cause confusion if any tooling relies on marshaling a SafeOutputsConfig struct back to YAML.

Recommended fix: Change the struct yaml tag at pkg/workflow/compiler_types.go:575:

// From:
CreateCodeScanningAlerts *CreateCodeScanningAlertsConfig `yaml:"create-code-scanning-alerts,omitempty"`
// To:
CreateCodeScanningAlerts *CreateCodeScanningAlertsConfig `yaml:"create-code-scanning-alert,omitempty"`

---

2. engine Schema Missing opencode as Supported Built-in

Impact: Medium — Schema validation and IDE autocompletion will not recognize opencode as a valid engine string.

Layer	Value
Schema description (main_workflow_schema.json)	"Engine name: built-in ('claude', 'codex', 'copilot', 'gemini', 'crush') or a named catalog entry"
Code (constants/engine_constants.go:24)	OpenCodeEngine EngineName = "opencode"
Code constants (constants/README.md:55)	AgenticEngines = ["claude", "codex", "copilot", "gemini", "opencode", "crush"]
Documentation (engines.md)	Lists opencode in the engine comparison table

The opencode engine is fully implemented in code and documented, but not mentioned in the schema's engine string description. This means schema-based validators and IDE plugins will not autocomplete or validate engine: opencode.

Recommended fix: Update the engine string description in pkg/parser/schemas/main_workflow_schema.json:

"description": "Engine name: built-in ('claude', 'codex', 'copilot', 'gemini', 'crush', 'opencode') or a named catalog entry"

Also update the engine_config $defs object id descriptions in the same file.

---

Documentation Gaps

3. Nine safe-outputs Fields Missing from Main safe-outputs.md

Impact: Low–Medium — Fields are documented in frontmatter-full.md or spec docs, but users consulting the primary safe-outputs.md reference won't find them.

The following schema properties are defined under safe-outputs but not covered in docs/src/content/docs/reference/safe-outputs.md:

Field	Where Documented Instead
activation-comments	frontmatter-full.md
create-agent-task	Schema $comment only (deprecated)
id-token	frontmatter-full.md
mark-pull-request-as-ready-for-review	frontmatter-full.md only
max-patch-files	frontmatter-full.md
merge-pull-request	safe-outputs-specification.md, glossary.md
report-incomplete	safe-outputs-specification.md, glossary.md
scripts	custom-safe-outputs.md
set-issue-type	frontmatter-full.md

Notably, merge-pull-request, mark-pull-request-as-ready-for-review, and set-issue-type have no dedicated section in the main safe-outputs.md guide — users would need to find them via the exhaustive reference or specification docs.

---

4. features Schema Does Not Enumerate Known Feature Flag Names

Impact: Low — Known feature flags are documented in the glossary but the schema can't validate them.

The features schema uses "additionalProperties": true with no enumerated property names. The glossary documents these known flags: action-mode, copilot-requests, mcp-gateway, integrity-reactions, cli-proxy, awf-diagnostic-logs, byok-copilot (deprecated). A typo in a feature flag name (e.g., copilot-request instead of copilot-requests) silently passes schema validation.

Recommended fix: Add a properties block with the known flags to the features schema while keeping additionalProperties: true for extensibility:

"features": {
  "type": "object",
  "additionalProperties": true,
  "properties": {
    "copilot-requests": { "type": "boolean" },
    "action-mode": { "type": "string" },
    "mcp-gateway": { "type": "boolean" },
    "integrity-reactions": { "type": "boolean" },
    "cli-proxy": { "type": "boolean" },
    "awf-diagnostic-logs": { "type": "boolean" }
  }
}

---

Schema Improvements Needed

5. safe-outputs.comment-memory Struct Tag Does Not Reflect User-Facing Location

Impact: Low — Developer confusion rather than user-facing bug.

SafeOutputsConfig has yaml:"comment-memory,omitempty" at pkg/workflow/compiler_types.go (line within SafeOutputsConfig struct). However, comment-memory is a tools field — the compiler extracts it from tools.comment-memory and copies it into the compiled SafeOutputsConfig. The schema correctly places comment-memory under tools (verified at main_workflow_schema.json:4081).

The struct yaml tag implies safe-outputs.comment-memory is a user-writable field, which it is not. This is internal compiler state.

Recommended fix: Add a comment to the struct field clarifying it's populated at compile-time from tools.comment-memory, not directly from user frontmatter:

// Populated at compile time from tools.comment-memory (not a user-facing safe-outputs field)
CommentMemory *CommentMemoryConfig `yaml:"comment-memory,omitempty"`

---

6. safe-outputs.create-agent-task Deprecated but No Schema Deprecation Marker

Impact: Very Low — create-agent-task is deprecated in favor of create-agent-session. The schema has both fields and a $comment noting the deprecation, but there is no formal JSON Schema deprecated: true annotation on the field itself. This is a minor polish item.

---

Workflow Violations / False Positives

7. in_used_not_schema Fields Are Not Real Violations

The pre-computed diff flagged these as "used in workflow files but not in schema": authors, date, else, https, refactor, repo, serena-find_referencing_code_snippets, serena-find_symbol, title, try.

Investigation shows these are not frontmatter fields:

• authors, date, title — appear inside blog post template bodies in weekly-blog-post-writer.md
• else, try — Python/JavaScript code blocks inside workflow instruction text
• https — raw URL text in workflow file bodies
• repo, refactor — parts of GitHub search query strings in workflow instructions
• serena-* — MCP tool references in workflow instructions

No action needed — these are body content false positives from the pre-computed field extraction, not real frontmatter fields.

---

Recommendations

1. Fix create-code-scanning-alerts struct yaml tag (singular→plural rename at pkg/workflow/compiler_types.go:575) to match schema and parsing behavior.
2. Add opencode to engine schema descriptions in the engine_config $defs string type description — low effort, high visibility for IDE users.
3. Add dedicated sections to safe-outputs.md for mark-pull-request-as-ready-for-review, merge-pull-request, and set-issue-type — these are non-obvious capabilities that users looking at the main guide will miss.
4. Add report-incomplete to safe-outputs.md — it's a mandatory safe output type documented only in the spec and glossary, not the practical guide.
5. Consider enumerating known features flags in the schema for better IDE validation support.

---

Strategy Performance

Strategy	Findings	Effectiveness
Schema vs Code Struct Field Comparison	2	High
Engine Enum Documentation Cross-check	1	High
Safe-Outputs Documentation Coverage Audit	4	Medium

All three strategies will be cached for future runs. The create-code-scanning-alert singular/plural mismatch and the missing opencode engine description are the highest-value findings.

Next Steps

• Fix pkg/workflow/compiler_types.go:575 yaml tag (singular create-code-scanning-alert)
• Update pkg/parser/schemas/main_workflow_schema.json engine string descriptions to include opencode
• Add merge-pull-request, mark-pull-request-as-ready-for-review, report-incomplete, set-issue-type sections to docs/src/content/docs/reference/safe-outputs.md
• Optionally enumerate known features flags in schema for validation support

Generated by Schema Consistency Checker · ● 619.4K · ◷

• expires on May 1, 2026, 4:54 AM UTC

[github-actions[bot]]

This discussion was automatically closed because it expired on 2026-05-01T04:54:45.702Z.

Closed by Workflow