[Schema Consistency] Schema/Docs Drift: 7 undocumented schema fields, 2 broken See: anchors, inline-sub-agents schema mismatch

[github-actions[bot]]

Summary

• Inconsistencies found: 10 (across schema/docs/parser)
• Categories analyzed: Schema ↔ Parser, Schema ↔ Docs, Schema ↔ Workflows, Parser ↔ Docs
• Strategy used: Schema-vs-frontmatter.md heading coverage (proven, day-of-year mod 10 = 1)
• Result: Reference documentation (frontmatter.md) covers only ~30 of 58 top-level schema fields; several schema description URLs point to non-existent anchors.

Critical Issues

1. Broken See: doc anchors embedded in the JSON schema

Two top-level schema descriptions tell users to "See: https://github.github.com/gh-aw/reference/frontmatter/#..." — but those anchors don't exist in docs/src/content/docs/reference/frontmatter.md. Following the schema link lands the user on a page with no matching section.

Schema field	Anchor URL in description	Anchor exists?
check-for-updates	.../frontmatter/#check-for-updates	❌ No heading in frontmatter.md
run-install-scripts	.../frontmatter/#run-install-scripts	❌ No heading in frontmatter.md
strict	.../frontmatter/#strict-mode-strict	✅ matches ### Strict Mode (\strict:`)`

Files: pkg/parser/schemas/main_workflow_schema.json:9420 (check-for-updates), :9426 (run-install-scripts).

2. Schema field rejected by compiler but allowed by schema (inline-sub-agents)

pkg/workflow/compiler_validators.go:59-62 rejects inline-sub-agents: false at compile time:

if workflowData.InlineSubAgentsDisabled {
    msg := "inline-sub-agents: false is not supported. Inline sub-agents are always enabled. Remove inline-sub-agents from your frontmatter."
    return formatCompilerError(markdownPath, "error", msg, errors.New(...))
}

But the schema (main_workflow_schema.json:2723) declares "type": "boolean" — meaning a schema-level validator would accept false and only the compiler catches it. The schema should constrain this to "const": true (or "enum": [true]) so schema-aware editors/CI flag the value before compile.

Documentation Gaps

The canonical reference doc docs/src/content/docs/reference/frontmatter.md (30 ### sections) is missing dedicated coverage for several top-level schema fields that are implemented and used:

Top-level schema fields with no `### ` section in frontmatter.md

Schema field	In schema	In code	In frontmatter.md	Notes
max-effective-tokens	✅ :3683	✅ pkg/workflow/engine.go:118-181 (parsed top-level)	❌	Only mentioned in engines.md table and ADR 31418-...md. Used in .github/workflows/schema-consistency-checker.md:13.
max-runs	✅ :3698	✅ pkg/workflow/engine.go + awf_config.go	❌	Only mentioned in engines.md table.
check-for-updates	✅ :9417	✅ pkg/workflow/update_check_validation.go	❌	Only frontmatter-full.md:6932 (auto-generated commented dump).
run-install-scripts	✅ :9425	✅	❌	Only frontmatter-full.md:6943 (auto-generated commented dump).
disable-model-invocation	✅ :2949	✅ pkg/parser/include_processor.go:203	❌	Only frontmatter-full.md:1632.
inline-sub-agents	✅ :2723	✅	❌ in frontmatter.md	Has its own page (reference/inline-sub-agents.md), but not linked from frontmatter.md.
user-rate-limit	✅	✅	❌ (no string match in frontmatter.md)	Documented in reference/rate-limiting-controls.md and cost-management.md but not in canonical frontmatter.md.

max-effective-tokens is the most concerning: the schema describes a numeric ET budget cap with a default of 10000000, the parser handles both int and numeric-string forms (pkg/workflow/engine.go:139-149), and the engine config exposes it on EngineConfig.MaxEffectiveTokens — but a user reading the docs has no idea this exists. The ADR (docs/adr/31418-...md) is the only narrative reference, and ADRs aren't user documentation.

Schema Improvements Needed

1. inline-sub-agents: change "type": "boolean" → "const": true (or "enum": [true]) at main_workflow_schema.json:2723, since the compiler rejects false. Keep the deprecation note.
2. Schema description URLs: either drop the See: URLs for check-for-updates and run-install-scripts, or add the corresponding ### sections in frontmatter.md so the anchors resolve.

Parser Updates Required

No parser correctness bugs were found in this scan. The compiler/parser correctly implements every field examined; the gap is between code+schema (which agree) and the reference documentation (which lags).

Workflow Violations

No workflow files were found violating the schema. Spot-check: .github/workflows/schema-consistency-checker.md uses max-effective-tokens: 20000000, which is valid per the schema (oneOf: integer|numeric string).

The in_used_not_schema list from schema-diff.json (e.g., affected_sections, prompt_phases, verdict, serena-find_symbol) appears to be from markdown-body content (audit/eval workflows and inline tool-name keys), not actual top-level frontmatter — likely a false-positive of the extractor, worth a follow-up to the diff script rather than a real inconsistency.

Recommendations

1. Add frontmatter.md sections for max-effective-tokens, max-runs, check-for-updates, run-install-scripts, disable-model-invocation, user-rate-limit, and a cross-link to inline-sub-agents.md. This single change resolves both the documentation gap and the broken schema anchor links.
2. Tighten the inline-sub-agents schema to "const": true so editor schema validators surface the same rejection that the compiler does.
3. Audit other See: https://github.github.com/gh-aw/...#anchor URLs in the schema and lock-file generator — only 3 currently exist (strict, check-for-updates, run-install-scripts); 2 of 3 are broken.
4. (Optional) Fix schema-diff.json extractor so used_in_workflows excludes keys inside the markdown body — currently it surfaces things like verdict and serena-find_symbol that aren't frontmatter.

Strategy Performance

• Strategy used: Schema-vs-frontmatter.md heading coverage + broken-anchor detection (proven path)
• Findings: 10 (7 documentation gaps + 2 broken anchors + 1 schema-vs-compiler enforcement mismatch)
• Effectiveness: HIGH — every finding is concrete, single-file, and actionable
• Should reuse: YES; cached as strategy-1, strategy-2, strategy-3 in /tmp/gh-aw/cache-memory/strategies.json

Next Steps

• Add missing ### sections to docs/src/content/docs/reference/frontmatter.md
• Constrain inline-sub-agents schema to const: true
• Verify all See: https://github.github.com/gh-aw/... URLs in main_workflow_schema.json resolve
• Improve schema-diff.json extractor to ignore markdown-body keys

Generated by Schema Consistency Checker · ● 8.8M · ◷

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

[github-actions[bot]]

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

A newer discussion is available at Discussion #31645.