[Schema Consistency] Schema Consistency Check — 2026-05-12

[github-actions[bot]]

Summary

• Run date: 2026-05-12 (§25717271687)
• Inconsistencies found: 3 (1 high, 2 medium)
• Categories analyzed: Schema ↔ Parser/Compiler, Schema ↔ Documentation, Engine Registry ↔ Schema descriptions
• Strategies used: Pre-computed field-gap inspection + engine-registry vs schema-description audit + deprecated-marker consistency
• Status: ⚠️ Action needed

Critical Issues

1. Top-level command field declared in schema but never read by the parser/compiler

The main workflow schema declares a top-level command field:

"command": {
  "type": "string",
  "description": "Command name for the workflow"
}

Source: pkg/parser/schemas/main_workflow_schema.json (top-level properties.command).

However, there is no parser or compiler code that reads frontmatter["command"] as a top-level key:

• Searched: grep -rn 'frontmatter\["command"\]' pkg/workflow/ pkg/parser/ → no matches outside the schema file.
• The actual command-trigger configuration is read from on.slash_command (preferred) or the deprecated on.command (pkg/workflow/frontmatter_extraction_yaml.go: extractCommandConfig).
• No workflow file under .github/workflows/ uses a top-level command: key.

Impact: A user could write command: my-cmd at the top level of their frontmatter, schema validation would accept it, and the value would be silently ignored at compile time — producing a workflow that does not behave as written.

Suggested fix: Either (a) remove the top-level command property from the schema, or (b) wire extractCommandConfig to also accept a top-level command: key alongside on.slash_command and on.command.

Medium-Priority Issues

2. Engine ID list drifts from the engine registry

The schema's engine description text and examples enumerate the built-in engines as five entries:

built-in ('claude', 'codex', 'copilot', 'gemini', 'crush') or a named catalog entry

This phrase appears at four locations in pkg/parser/schemas/main_workflow_schema.json (around lines 10119, 10127, 10344, 10466).

But pkg/workflow/agentic_engine.go:439-446 actually registers seven built-in engines:

builtins := []CodingAgentEngine{
    NewClaudeEngine(),
    NewCodexEngine(),
    NewCopilotEngine(),
    NewGeminiEngine(),
    NewOpenCodeEngine(),
    NewCrushEngine(),
    NewPiEngine(),
}

opencode (pkg/workflow/opencode_engine.go:24) and pi (pkg/workflow/pi_engine.go:36) are missing from every schema description. opencode IS listed in docs/src/content/docs/reference/engines.md:21 so the docs and code agree, but the schema descriptions do not — they are stale.

Impact: Confusing for users reading the schema, and the IDE autocomplete/hover text omits two valid engines. Since the schema does not enforce an enum, this is descriptive drift rather than a validation bug.

Suggested fix: Update the four affected description strings to include 'opencode' and 'pi' (or generate the list from the registry at schema-bundle time).

3. Top-level rate-limit is legacy but not marked deprecated, and silently accepted

The schema describes the top-level rate-limit property as a legacy alias:

"rate-limit": {
  "type": "object",
  "description": "Legacy alias for 'user-rate-limit'. Prefer 'user-rate-limit' with 'max-runs-per-window'."
}

But unlike other deprecated keys in this schema (e.g. safe-outputs.create-agent-task at line ~3268 of frontmatter-full.md and the corresponding schema property both carry "deprecated": true), this property has no "deprecated": true marker.

The compiler accepts the legacy key silently:

// pkg/workflow/role_checks.go:222
rateLimitValue, exists = frontmatter["rate-limit"]
// ...
if legacyKey {
    roleLog.Print("Extracted legacy rate-limit configuration")  // internal log only
}

This is debug-only logging; no user-facing warning is emitted via console.FormatWarningMessage and no c.IncrementWarningCount() call is made (contrast with extractCommandConfig in frontmatter_extraction_yaml.go, which DOES emit a deprecation warning when the legacy on.command is used).

Additionally, the top-level rate-limit form is not documented anywhere in docs/src/content/docs/reference/ — only user-rate-limit is documented (in cost-management.md, rate-limiting-controls.md, frontmatter-full.md, glossary.md).

Impact: Users may continue using the legacy form indefinitely without any signal that they should migrate.

Suggested fix:

• Add "deprecated": true to the schema's top-level rate-limit property.
• Emit a stderr warning + IncrementWarningCount() in extractRateLimitConfig when legacyKey is true (mirroring the pattern in extractCommandConfig).

Documentation Gaps (informational)

Several top-level schema fields have no entry in the canonical docs/src/content/docs/reference/frontmatter.md page even though they are covered elsewhere in the docs tree:

Field	Page coverage
check-for-updates	1 reference doc
disable-model-invocation	1 reference doc
infer	1 reference doc
inline-sub-agents	1 reference doc
max-effective-tokens	1 reference doc
max-runs	1 reference doc
run-install-scripts	1 reference doc
rate-limit (legacy)	0 reference docs
tracker-id	2 reference docs

The central frontmatter.md page does not link to these, which can make discovery difficult. This is a doc-organization concern rather than a hard inconsistency.

Strategy Performance & Cache Update

Saved /tmp/gh-aw/cache-memory/strategies.json with four strategies:

1. Pre-computed field gaps + targeted code inspection — proven (3 findings)
2. Engine registry vs schema description audit — proven (1 finding)
3. Schema 'deprecated' marker consistency — proven (1 finding)
4. EngineConfig struct vs $defs/engine_config object form — explored, no findings (the schema's six-branch oneOf already covers runtime/provider correctly)

Notes for future runs:

• The pre-computed parser_yaml_fields list in schema-diff.json is noisy because the parser uses struct field names rather than top-level frontmatter keys; the workflow_yaml_fields is more useful but still contains nested-config keys.
• used_in_workflows in the diff includes content from non-frontmatter YAML blocks (independence, parallelism, etc.). Re-extract top-level frontmatter keys with awk '/^---$/{n++; next} n==1 && /^[a-zA-Z][a-zA-Z0-9_-]*:/'.
• High-signal starting points: schema fields described as 'Legacy', 'DEPRECATED', or 'unused'; engine-registry drift; and schema fields with no grep hit in pkg/workflow/.

Recommendations

1. Remove or wire up the top-level command schema field (Critical rejig docs #1). Pick one of the two paths and either delete the property or add frontmatter["command"] handling in extractCommandConfig.
2. Regenerate the engine ID list in schema descriptions (Medium Add workflow: githubnext/agentics/weekly-research #2). Replace the four hardcoded 'claude', 'codex', 'copilot', 'gemini', 'crush' strings with a build-time enumeration of the engine registry, or update them by hand to include 'opencode' and 'pi'.
3. Mark legacy keys consistently (Medium Add workflow: githubnext/agentics/weekly-research #3). Add "deprecated": true to the top-level rate-limit property and emit a user-visible deprecation warning from extractRateLimitConfig (pattern: see extractCommandConfig in frontmatter_extraction_yaml.go).
4. Add cross-links from frontmatter.md to dedicated reference pages for check-for-updates, disable-model-invocation, infer, inline-sub-agents, max-effective-tokens, max-runs, run-install-scripts, tracker-id, and user-rate-limit (doc polish, low priority).

Next Steps

• Decide whether top-level command should be removed from schema or wired into the parser
• Update engine ID enumeration in the four schema description strings
• Add "deprecated": true flag and emit user-visible warning for top-level rate-limit
• (Optional) Add a CI lint test that enumerates the engine registry and asserts the schema descriptions agree

References:

• §25717271687

Warning

Firewall blocked 2 domains

The following domains were blocked by the firewall during workflow execution:

• index.crates.io
• proxy.golang.org

To allow these domains, add them to the network.allowed list in your workflow frontmatter:

network:
  allowed:
    - defaults
    - "index.crates.io"
    - "proxy.golang.org"

See Network Configuration for more information.

Generated by Schema Consistency Checker · ● 18.3M · ◷

• expires on May 13, 2026, 6:36 AM UTC