[Schema Consistency] Schema Consistency Check - 2026-05-30

[github-actions[bot]]

Summary

• Inconsistencies confirmed: 7 (all re-verified against current main @ adab887)
• Categories analyzed: Schema ↔ Parser, Schema ↔ Docs, Parser ↔ Docs, Schema internals
• Strategies used: docs-coverage, deprecation-flags, validFields-cross-check, $defs-integrity, shared-forbidden, doc-anchors, deprecation-enforcement (proven cache strategies; day-of-year mod = 0 → proven mode)
• New finding this run: none net-new, but a recurring false positive was characterized (strict) and one low-confidence strategy (additionalProperties) was dropped as unverifiable rather than reported speculatively

All seven items below were independently reproduced in the current tree this run. None are net-new regressions, but each remains unfixed and is safe to action.

Critical / High-Priority Issues

1. Three top-level schema fields have ZERO curated documentation (Schema ↔ Docs)

check-for-updates, disable-model-invocation, and run-install-scripts are all valid properties in pkg/parser/schemas/main_workflow_schema.json but appear in no curated doc under docs/src/content/docs/ (excluding the auto-generated frontmatter-full.md). Users can only discover them by reading the generated reference.

2. applyTo is an undocumented escape hatch with a stale code comment (Schema ↔ Parser)

• pkg/parser/include_processor.go:267 still lists "applyTo": true in the validFields allowlist.
• pkg/parser/schema_utilities.go:14 comments that applyTo is "now validated by the schema" — but applyTo is not a property in main_workflow_schema.json (jq '.properties | has("applyTo")' → false).
• applyTo has zero curated-doc mentions.

The comment is factually wrong, and the field is silently accepted by the parser while the schema would reject it under additionalProperties: false.

Documentation Gaps

3. Two schema descriptions link to non-existent doc anchors (Schema ↔ Docs)

The check-for-updates and run-install-scripts descriptions both link to reference/frontmatter/#<field> anchors, but docs/src/content/docs/reference/frontmatter.md has no heading that slugifies to either anchor. Both links are dead.

Anchor verification details

Field	Anchor in schema	Matching heading in frontmatter.md
check-for-updates	frontmatter/#check-for-updates	0
run-install-scripts	frontmatter/#run-install-scripts	0

Schema Improvements Needed

4. Deprecated fields lack the JSON Schema deprecated flag (Schema internals)

Two fields are described as deprecated/legacy in prose but carry neither "deprecated": true nor an x-deprecation-message, so tooling/IDEs cannot surface the deprecation:

• inline-sub-agents — description starts "Deprecated switch for inline sub-agent support...", .deprecated = null
• rate-limit — description starts "Legacy alias for 'user-rate-limit'...", .deprecated = null

⚠️ Detection note for future runs: a case-insensitive Deprecated|Legacy description scan also flags strict — this is a false positive. The strict description lists "(5) Deprecated Fields" as a strict-mode feature; strict itself is not deprecated. Exclude it.

5. Dead $def: templatable_integer (Schema internals, low)

$defs.templatable_integer is defined but never $ref'd anywhere in the schema (0 references), whereas its sibling templatable_boolean is referenced. Either wire it up where integer fields are templatable or remove it.

Parser Updates Required

6. Legacy rate-limit alias emits no user-visible deprecation warning (Parser ↔ Docs)

pkg/workflow/role_checks.go:301 logs roleLog.Print("Extracted legacy rate-limit configuration") — a debug-level logger line, not a user-facing compile warning. By contrast pkg/workflow/compiler_validators.go:344 emits an EXPERIMENTAL warning for user-rate-limit. The deprecated alias should warn users to migrate; today it is silently accepted.

7. SharedWorkflowForbiddenFields contains dead entries (Schema internals, low)

pkg/constants/constants.go lists "command" (line 328) and "roles" (line 336) in SharedWorkflowForbiddenFields, but neither is a top-level schema property (jq '.properties | has("command")' / has("roles") → false). Since the top-level schema is additionalProperties: false, these would already be rejected — the entries are dead/defensive. Harmless, but worth pruning or commenting as intentional.

Recommendations

1. Docs: add curated reference sections for check-for-updates, disable-model-invocation, run-install-scripts (fixes rejig docs #1 and the dead anchors in Add workflow: githubnext/agentics/weekly-research #3).
2. Parser: fix the false comment at schema_utilities.go:14 and decide whether applyTo should be a real schema property or removed from validFields (Add workflow: githubnext/agentics/weekly-research #2).
3. Schema: add "deprecated": true (+ optional x-deprecation-message) to inline-sub-agents and rate-limit (Add workflow: githubnext/agentics/weekly-research #4); remove or wire up templatable_integer (Add workflow: githubnext/agentics/weekly-research #5).
4. Compiler: promote the legacy rate-limit debug log to a real deprecation warning, mirroring the user-rate-limit experimental warning (add cli flag to guard dropping a agentic workflow instructinos file #6).
5. Constants: prune or annotate the dead command/roles entries in SharedWorkflowForbiddenFields (Weekly Research Report: AI Workflow Automation Landscape and Market Opportunities - August 2025 #7).

Strategy Performance

• Strategies used: 7 proven cache strategies (7, 8, 9, 10, 12, 13, 16)
• Findings: 7 confirmed / 0 false-positives reported (1 false positive strict correctly excluded; 1 strategy additionalProperties dropped as unverifiable due to on being a oneOf composite that breaks plain jq paths)
• Effectiveness: HIGH — all proven strategies reproduced cleanly against current code
• Should reuse: YES. Cache updated with bumped success counts, the strict false-positive caveat (strategy-10), and the oneOf-traversal caveat (strategy-18).

Next Steps

• Document check-for-updates, disable-model-invocation, run-install-scripts (fixes dead anchors too)
• Correct schema_utilities.go:14 comment and resolve applyTo status
• Add deprecated flags to inline-sub-agents and rate-limit
• Emit a user-visible deprecation warning for legacy rate-limit
• Remove dead $def templatable_integer and prune dead SharedWorkflowForbiddenFields entries

References: §26676862620

Generated by ✅ Schema Consistency Checker · opus48 1.1M · ◷

• expires on May 31, 2026, 6:34 AM UTC

[github-actions[bot]]

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

A newer discussion is available at Discussion #36077.