[Schema Consistency] Schema consistency check: limit handling and documentation gaps (2026-11-11)

[github-actions[bot]]

🔍 Schema consistency check — 2026-11-11

Four inconsistencies were found in a targeted comparison of the schema, compiler, documentation, and repository workflows. The cached field-gap triage strategy was reused. No critical issue was established.

Key findings

1. Zero-valued limits pass the schema but are discarded by the parser. max-turns and max-tool-denials both reference templatable_integer, which permits integer 0 (pkg/parser/schemas/main_workflow_schema.json:4957, :4962, :15601). Their parsers require at least 1 and return an empty value for zero (pkg/workflow/engine_config_parser.go:59, :98, :121). In the max-turns path, an empty value can lead to the configured default being used (pkg/workflow/compiler_orchestrator_engine.go:739). Authors can therefore submit schema-valid configuration that does not apply the requested limit. Decide whether zero has a supported meaning; otherwise use the positive-integer schema for both fields and add compiler validation and regression cases.

2. The schema permits skip questions that the compiler rejects. skip-if-decision items only require a nonblank string (pkg/parser/schemas/main_workflow_schema.json:10), but the parser rejects any question containing ${{ (pkg/workflow/skip_if_decision.go:25). The reference correctly says Actions expressions are unsupported (docs/src/content/docs/reference/frontmatter.md:84). Add a matching schema constraint or clearly document this compiler-only restriction in the schema description, and test the same example against both validation paths.

3. The skip-decision documentation omits a sandbox prerequisite. The compiler rejects nonempty skip questions when the AWF agent sandbox is disabled (pkg/workflow/compiler_orchestrator_workflow.go:731), while the feature description mentions protected-session incompatibility but not that prerequisite (docs/src/content/docs/reference/frontmatter.md:58). Document the requirement and the empty-list exception in the reference and schema description; add a focused documentation or validation regression.

4. Generated reference examples violate their own schema. docs/src/content/docs/reference/frontmatter-full.md:4335 and :4361 show example-value as an Actions expression, although the referenced schema requires the ${{ ... }} form (pkg/parser/schemas/main_workflow_schema.json:15601). The same generated reference uses example-value for source-sha (:80), whose schema requires 40 hexadecimal characters (pkg/parser/schemas/main_workflow_schema.json:211). The generator falls back to this literal for strings (scripts/generate-schema-docs.js:131). Generate valid examples from schema examples or constraints and validate representative generated alternatives in tests.

Scope and workflow observations

The precomputed diff reports no top-level keys used by repository workflows that are absent from the schema. Its three apparent schema-versus-struct gaps (docker-image-pull-policy, skip-if-decision, and work-queue-policy) have raw-frontmatter handling and were not treated as missing implementations. Sampled workflows include code-simplifier.md and daily-file-diet.md; no workflow violation was established. The review was targeted, not exhaustive, and did not execute workflow code or validate every workflow and documentation example.

Strategy performance: precomputed field-gap triage plus focused constraint and example checks; four findings; high effectiveness; reuse recommended.

Next actions

• Align the numeric limit schema and parser behavior, with zero-value regression tests.
• Align skip-question schema validation and document its sandbox prerequisite.
• Fix and validate schema-generated reference examples.
• Check existing workflows when implementing those changes.

References: §42965455909

Generated by ✅ Schema Consistency Checker · codex · routed: gpt61 medium · ~11 AIC · ⌖ ~2 AIC · ⊞ 470 · ◷

• expires on Nov 11, 2026, 9:29 PM UTC-08:00

[github-actions[bot]]

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

A newer discussion is available at Discussion #77077.