[Schema Consistency] Schema Consistency Audit — 2026-04-28

[github-actions[bot]]

Schema consistency audit covering four areas: JSON schema (main_workflow_schema.json), parser/compiler implementation (pkg/parser/*.go, pkg/workflow/*.go), reference documentation (docs/src/content/docs/reference/), and in-repo workflows (.github/workflows/*.md).

Strategy used: New approach — Tool Registry Cross-Reference + Engine Property Documentation Sweep (day-of-year mod 10 = 8, triggering the 30% new-strategy path).

Summary

Area	Findings
Schema ↔ Code mismatches	3 (1 high, 2 medium)
Schema ↔ Docs gaps	4 (2 medium, 2 low)
Feature flag documentation	2 undocumented flags
Pre-computed diff false positives	2 methodology issues noted

Total actionable findings: 9

---

Critical Issues

1. tools.safety-prompt — In code, absent from schema and docs

The safety-prompt tool is listed in builtInToolNames (recognized by the compiler) and in tools_parser.go's valid tool map, but it is completely absent from:

• tools.properties in main_workflow_schema.json
• All reference documentation

Impact: Users who discover the tool name (e.g., from error messages or source inspection) get no IDE completion, no schema validation, and no documentation. The schema currently rejects it via JSON Schema validation even though the compiler accepts it.

Files:

• pkg/workflow/mcp_config_validation.go:41 — "safety-prompt": true in builtInToolNames
• pkg/workflow/tools_parser.go:170 — "safety-prompt": true in valid tools map
• pkg/parser/schemas/main_workflow_schema.json — tools.properties missing safety-prompt

View evidence

# builtInToolNames in mcp_config_validation.go:
"github", "playwright", "agentic-workflows", "cache-memory", "comment-memory",
"repo-memory", "bash", "edit", "web-fetch", "web-search",
"safety-prompt",   ← present in code
"timeout", "startup-timeout", "mount-as-clis"

# tools.properties in schema:
"agentic-workflows", "bash", "cache-memory", "comment-memory", "edit",
"github", "grep", "mount-as-clis", "playwright", "repo-memory",
"serena", "startup-timeout", "timeout", "web-fetch", "web-search"
#  ↑ safety-prompt missing!

---

2. Deprecated tools (grep, serena) give wrong compiler error

The schema marks tools.grep as deprecated: true with message "grep is always available as part of default bash tools. Remove this field and use bash tool instead." It marks tools.serena as x-removed: true with a helpful migration message pointing to shared/mcp/serena.md.

However, neither grep nor serena is in builtInToolNames. When a user writes tools: { grep: true }, the compiler calls ValidateToolsSection, which rejects it with a generic error:

tools.grep: unknown tool name. The 'tools' section only accepts built-in tool names.

The user never sees the specific, helpful deprecation/removal message that was carefully written into the schema.

Impact: Medium — confusing error messages; users don't see the migration path. serena also has an inconsistency: pkg/parser/mcp.go:186,214 still processes serena as a valid built-in MCP tool at parse time, but validation would have already rejected it.

Files:

• pkg/workflow/mcp_config_validation.go:121-139 — ValidateToolsSection does not check schema deprecation
• pkg/parser/schemas/main_workflow_schema.json — tools.grep.deprecated: true, tools.serena.x-removed: true
• pkg/parser/mcp.go:186,214 — serena still processed in MCP extraction (dead code path due to upstream validation rejection)

View schema deprecation messages

tools.grep:

{
  "deprecated": true,
  "x-deprecation-message": "grep is always available as part of default bash tools (echo, ls, pwd, cat, head, tail, grep, wc, sort, uniq, date, yq). Remove this field and use bash tool instead."
}

tools.serena:

{
  "deprecated": true,
  "x-removed": true,
  "x-removal-message": "tools.serena built-in support has been removed. Import shared/mcp/serena.md instead:\n  imports:\n    - uses: shared/mcp/serena.md\n      with:\n        languages: [\"go\", \"typescript\"]"
}

---

Documentation Gaps

3. features.mcp-cli — Implemented feature flag with zero doc coverage

The mcp-cli feature flag gates the entire MCP-CLI mounting subsystem in pkg/workflow/mcp_cli_mount.go. It is listed in pkg/constants/README.md:151 as MCPCLIFeatureFlag. Despite controlling a significant feature (mounting MCP servers as CLI executables in PATH), it has zero mentions in the reference documentation.

Files:

• pkg/workflow/mcp_cli_mount.go:57-64 — feature gate check
• pkg/constants/README.md:151 — constant defined
• docs/src/content/docs/reference/frontmatter.md — no mention

4. features.disable-xpia-prompt — Undocumented feature flag

The disable-xpia-prompt feature flag (constants.DisableXPIAPromptFeatureFlag) is referenced in code (pkg/constants/README.md:144) but has zero documentation in the reference docs. The flag name suggests it disables cross-prompt injection attack (XPIA) prompt injection, which is security-relevant.

---

5. engine.bare — Newly added field missing from engines.md

Added in v0.68.1 (per docs/src/content/docs/blog/2026-04-13-weekly-update.md), the engine.bare: true field suppresses automatic context loading (AGENTS.md for Copilot, CLAUDE.md for Claude). It is:

• ✅ In main_workflow_schema.json with full description
• ✅ Implemented in pkg/workflow/engine.go:159,306
• ✅ Mentioned in blog posts (2026-04-13, 2026-04-20)
• ✅ Present in docs/src/content/docs/reference/frontmatter-full.md:1683,1770
• ❌ No dedicated section in docs/src/content/docs/reference/engines.md (the main engine reference)
• ❌ No mention in docs/src/content/docs/reference/frontmatter.md

Impact: Users reading the main engine reference have no way to discover this feature.

6. run-install-scripts — In schema and code, missing from main frontmatter.md

The run-install-scripts: true field disables --ignore-scripts on npm install commands (supply-chain security). It is well-implemented in code and defined in the schema with a security warning, but docs/src/content/docs/reference/frontmatter.md contains no mention of it. It exists only in frontmatter-full.md.

Files:

• pkg/workflow/frontmatter_parsing.go:123-137 — implementation
• pkg/parser/schemas/main_workflow_schema.json — full definition with security context
• docs/src/content/docs/reference/frontmatter-full.md:5898-5904 — only coverage

---

Pre-computed Diff Methodology Issues

These are findings about schema-diff.json itself, not about the codebase:

7. parser_yaml_fields captures wrong struct

The parser_yaml_fields in the pre-computed diff contains only ["default", "options", "required", "type"] — these are fields from pkg/parser/import_processor.go's ParameterDefinition struct, not frontmatter parsing fields. The frontmatter parser uses a generic map[string]any (no struct tags), so there are no yaml struct tags to capture. This makes the in_schema_not_parser gap meaningless.

8. in_used_not_schema has false positives from markdown body

Fields like else, try, repo, refactor, authors, date, title, serena-find_symbol appear in in_used_not_schema because the diff script scans YAML key-value patterns across the entire workflow file, including the markdown body (which can contain YAML examples, instructions, or code blocks). Verified by checking line numbers: else: at lines 181, 200, 210 of daily-performance-summary.md are in the markdown body, not frontmatter.

---

Schema Improvements Needed

1. Add safety-prompt to tools.properties in the schema with description
2. Add engine.bare section to engines.md and frontmatter.md
3. Add run-install-scripts to frontmatter.md security section
4. Add features.mcp-cli and features.disable-xpia-prompt documentation to the features section of frontmatter.md
5. Add known feature flags to features.properties in schema (currently additionalProperties: true with empty properties — no IDE completion for mcp-cli, integrity-reactions, awf-diagnostic-logs, etc.)

Parser/Compiler Updates Required

1. ValidateToolsSection should emit deprecation-specific errors for deprecated/removed tools by checking schema deprecation metadata, instead of giving a generic "unknown tool name" error
2. Dead code: pkg/parser/mcp.go:186,214,425 still handle serena as a valid built-in, but ValidateToolsSection will have already rejected it. Either re-add serena to builtInToolNames (and emit the helpful removal warning) or remove the dead code path in mcp.go

---

Recommendations

1. Add safety-prompt to the schema — this is the highest-impact fix. A real tool that users can't discover via schema/docs.
2. Wire schema deprecation messages to compiler errors — ValidateToolsSection should look up x-deprecation-message / x-removal-message from the schema for better UX.
3. Document engine.bare in engines.md — recently shipped feature with no main-reference coverage.
4. Enumerate known feature flags in features.properties — currently the features schema object is completely open (additionalProperties: true). Adding known flags as properties with descriptions would unlock IDE completion.
5. Resolve serena handling — either add back to builtInToolNames with a warning+continue behavior, or remove from pkg/parser/mcp.go.

---

Strategy Performance

Attribute	Value
Strategy used	New: Tool Registry Cross-Reference + Engine Property Doc Sweep
Total findings	9
High-impact	2
Medium	5
Informational	2
Effectiveness	HIGH — tool registry comparison immediately surfaced safety-prompt gap
Should reuse	YES — save to strategy cache

---

References: Workflow run §25034412959

Generated by Schema Consistency Checker · ● 662.2K · ◷

• expires on Apr 29, 2026, 4:57 AM UTC

[github-actions[bot]]

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

A newer discussion is available at Discussion #29043.