[Schema Consistency] Schema Consistency Check - 2026-04-02

[github-actions[bot]]

Summary

• Inconsistencies Found: 9 across 4 layers (schema, parser/compiler, documentation, workflows)
• Strategy Used: Cross-Layer Field Diff (proven, run Add workflow: githubnext/agentics/weekly-research #4, day-of-year 92 % 10 = 2 → cached strategy)
• Critical Issues: 1 active struct/schema naming bug, 1 naming convention inconsistency
• Documentation Gaps: 5 schema fields with zero docs coverage
• Schema Gaps: 29 permission scopes in code but absent from schema

---

Critical Issues

1. create-code-scanning-alert singular vs plural mismatch

Layer	Key used
Schema (main_workflow_schema.json:6166)	create-code-scanning-alert (singular)
Raw parser (create_code_scanning_alert.go:21)	create-code-scanning-alert (singular)
Struct yaml tag (compiler_types.go:465)	create-code-scanning-alerts (plural)
Workflows (daily-semgrep-scan.md, daily-malicious-code-scan.md)	create-code-scanning-alert (singular)
Test workflow (daily-safe-output-integrator.md:421)	create-code-scanning-alerts (plural)

The struct field CreateCodeScanningAlerts carries yaml tag create-code-scanning-alerts (plural), but schema validation and every production workflow file use the singular form create-code-scanning-alert. The runtime raw-map parser reads the singular key directly, so runtime behavior is correct — but the struct yaml tag is inconsistent with the schema. If YAML is ever deserialized via the struct (instead of the raw map path), the field will not be populated.

Fix: Change compiler_types.go:465 yaml tag from create-code-scanning-alerts to create-code-scanning-alert, or update the schema and all workflow files to use plural. The raw parser in create_code_scanning_alert.go:21 must be updated to match whichever form is chosen.

2. dispatch_repository uses underscore, all peers use kebab-case

Layer	Key
Schema	dispatch_repository (underscore)
Struct yaml tag (compiler_types.go:487)	dispatch_repository (underscore)
All other safe-outputs keys	kebab-case (dispatch-workflow, create-issue, …)

The underscore naming is user-visible in YAML frontmatter and produces an inconsistent authoring experience. The schema's $comment at line 4534 lists dispatch-workflow (kebab) alongside dispatch_repository (underscore) in the same sentence.

---

Schema Gaps

3. 29 permission scopes in code but missing from schema

permissions.go defines 30+ scopes. The schema's $defs.github_actions_permissions enumerates only 18 standard GITHUB_TOKEN scopes. Scopes accepted by the compiler but that will fail schema validation:

View all 29 missing scopes

administration
codespaces
codespaces-lifecycle-admin
codespaces-metadata
copilot-requests
email-addresses
environments
git-signing
members
organization-administration
organization-announcement-banners
organization-codespaces
organization-copilot
organization-custom-org-roles
organization-custom-properties
organization-custom-repository-roles
organization-events
organization-hooks
organization-members
organization-packages
organization-personal-access-token-requests
organization-personal-access-tokens
organization-plan
organization-self-hosted-runners
organization-user-blocking
repository-custom-properties
repository-hooks
single-file
team-discussions
workflows

Impact: workflows that use fine-grained org-level permissions (e.g. copilot-requests: write) will fail schema validation even though the compiler accepts and processes them correctly.

---

Documentation Gaps

4. check-for-updates — completely undocumented

• Defined in schema (main_workflow_schema.json:8404) with description: "Control whether the compile-agentic version update check runs…"
• Implemented in compiler_orchestrator_workflow.go:229, update_check_validation.go, frontmatter_types.go:194
• The schema description even includes a URL https://github.github.com/gh-aw/reference/frontmatter/#check-for-updates — but that anchor does not exist in frontmatter.md
• 0 mentions across all reference docs

5. observability — completely undocumented

• Defined in schema (main_workflow_schema.json:8305) with sub-field job-summary: on|off
• Implemented in compiler_yaml_ai_execution.go:19
• 0 mentions across all reference docs (frontmatter.md, frontmatter-full.md, or any dedicated page)

# Undocumented feature that enables job summary output
observability:
  job-summary: on

6. mark-pull-request-as-ready-for-review — missing from safe-outputs.md

• Present in schema (main_workflow_schema.json:5575) and implemented
• Appears only in frontmatter-full.md comment form
• Not in safe-outputs.md where all other safe-output capabilities are documented

7. set-issue-type — missing from safe-outputs.md

• Present in schema and implemented
• Covered in glossary.md:200 and frontmatter-full.md:4638
• Not in safe-outputs.md — inconsistent with all peer safe-outputs that have a dedicated section there

8. --allow-host-service-ports auto-generation — undocumented

• When a workflow declares services: with port mappings, the compiler automatically generates --allow-host-service-ports expressions (service_ports.go, awf_helpers.go:100)
• This is an important behavior for users configuring service containers (e.g. PostgreSQL, Redis)
• Zero documentation in any docs page, including frontmatter-full.md and the job-level fields table in frontmatter.md

---

Structural Inconsistency

9. activation-comments schema placement vs struct placement

Layer	Location
Schema	Directly under safe-outputs.activation-comments
Struct (compiler_types.go:527)	Under SafeOutputMessagesConfig → safe-outputs.messages.activation-comments
Parser (safe_outputs_config.go:437)	Reads from top-level outputMap["activation-comments"], stores in config.Messages.ActivationComments

The parser correctly bridges both locations, and frontmatter-full.md shows the field at safe-outputs.activation-comments (matching the schema). However, the struct organization is misleading — ActivationComments lives in SafeOutputMessagesConfig rather than SafeOutputsConfig, creating a mismatch between schema, struct, and docs.

---

Recommendations

1. Fix the singular/plural yaml tag on CreateCodeScanningAlerts (compiler_types.go:465) — align it with schema and existing workflows (create-code-scanning-alert)
2. Standardize dispatch_repository to kebab-case dispatch-repository across schema and struct, or explicitly document the underscore as intentional with a migration note
3. Expand the schema permissions enum ($defs.github_actions_permissions) to include the 29 org-level and fine-grained scopes already supported by the compiler
4. Document check-for-updates in frontmatter.md and fix the broken schema description URL
5. Document observability in frontmatter.md — add a subsection under the engine/configuration area
6. Add mark-pull-request-as-ready-for-review and set-issue-type to safe-outputs.md following the existing section pattern
7. Add service container port auto-detection note to the Services section of frontmatter-full.md (line 569 area)

---

Strategy Performance

• Strategy: Cross-Layer Field Diff (run Add workflow: githubnext/agentics/weekly-research #4)
• Findings this run: 9
• Cumulative findings: 12 prior + 9 new analysis = maintained high signal
• Effectiveness: HIGH — struct yaml tag diffs and schema permission enum checks continue to surface real issues
• Should Reuse: YES

---

References:

• §23883794563

AI generated by Schema Consistency Checker · history

• expires on Apr 3, 2026, 4:36 AM UTC