[Schema Consistency] 🔍 Schema Consistency Check - Implementation File Coverage Analysis (2025-11-10)

[github-actions[bot]]

🔍 Schema Consistency Check - Implementation File Coverage Analysis

Date: 2025-11-10
Strategy: Strategy-010 - Implementation File Coverage & Architectural Pattern Analysis
Analysis Scope: 33 schema fields, 116 implementation files, 110 production workflows

Summary

This analysis mapped schema fields to their implementation files in pkg/workflow/ to identify architectural patterns, dead code, and documentation gaps. The key finding: most fields follow a clear pattern (dedicated files for complex features, inline handling for simple ones), but we found critical issues with unused fields and missing documentation.

Key Metrics:

• ✅ 15 of 33 fields have dedicated implementation files
• ❌ 1 field (githubActionsStep) is confirmed dead code
• ⚠️ 4 fields never used in 110 production workflows
• 📊 116 implementation files organized into 9 categories
• 📝 1 field (post-steps) used in production but NOT documented

Critical Findings

Critical Findings

1. 🚨 githubActionsStep - Dead Code (3rd Confirmation)

Severity: HIGH
Status: Confirmed across 3 consecutive analyses

The githubActionsStep field exists in the schema but has zero implementation:

• ✅ Exists in main_workflow_schema.json
• ❌ NO parser implementation in pkg/parser/
• ❌ NO compiler handling in pkg/workflow/
• ❌ NO documentation in docs/
• ❌ NEVER used in 110 production workflows

Evidence:

# Schema definition exists
$ jq '.properties.githubActionsStep' pkg/parser/schemas/main_workflow_schema.json
{
  "type": "object",
  "description": "GitHub Actions workflow step",
  ...
}

# No parser usage
$ grep -r "githubActionsStep" pkg/parser/*.go
# (no results)

# No compiler usage
$ grep -r "githubActionsStep" pkg/workflow/*.go
# (no results)

# Never used in workflows
$ find .github/workflows -name "*.md" -exec grep -l "githubActionsStep" {} \;
# (no results)

Recommendation: Remove from main_workflow_schema.json in next release OR clearly document its intended future use.

Impact: Schema bloat, user confusion, maintenance burden.

---

2. 📝 post-steps Field - Undocumented but Used

Severity: MEDIUM
Status: Feature exists and works, but users can't discover it

The post-steps field is:

• ✅ Implemented in pkg/workflow/compiler.go
• ✅ Used in 1 production workflow (.github/workflows/test-post-steps.md)
• ❌ NOT documented in docs/src/content/docs/reference/frontmatter.md
• ❌ NOT mentioned in any reference documentation

Evidence:

# Used in production
$ grep -l "^post-steps:" .github/workflows/*.md
.github/workflows/test-post-steps.md

# Not documented
$ grep -r "post-steps" docs/src/content/docs/reference/
# (no results)

Recommendation: Add documentation section in frontmatter.md with examples and use cases.

Impact: Valuable feature remains hidden from users.

---

3. 🗑️ Truly Unused Fields

Severity: LOW-MEDIUM
Status: Fields in schema never used in practice

Four fields exist in the schema but are never used in 110 production workflows:

Field	In Schema	Has Implementation	Used in Workflows	Notes
githubActionsStep	✅	❌	❌	Dead code
run-name	✅	✅	❌	Implemented but unused
runtimes	✅	✅	❌	Also in included_file_schema.json
timeout_minutes	✅	✅	❌	Legacy alias for timeout-minutes

Recommendation:

• githubActionsStep: Remove from schema
• run-name: Add examples or consider deprecation
• runtimes: Document with examples OR remove if not ready
• timeout_minutes: Deprecate in favor of timeout-minutes

---

4. ⚠️ Misleading "Never Used" Analysis

Severity: INFO
Status: Important methodological insight

Key Discovery: Initial analysis showed many fields as "never used" because they're actually nested properties, not top-level fields:

Field	Appears "Unused" at Top-Level	Actually Used As
command	❌	✅ on.command (trigger)
container	❌	✅ mcp-servers[].container
env	❌	✅ jobs[].env, steps[].env
github-token	❌	✅ safe-outputs[].github-token

Lesson: Field usage analysis must account for schema nesting structure.

Schema ↔ Implementation Mapping

Schema ↔ Implementation Mapping

Fields with Dedicated Implementation Files (15)

These fields have their own pkg/workflow/{field}.go files:

Field	Implementation File	Usage in Workflows
cache	pkg/workflow/cache.go	1 workflow (1%)
command	pkg/workflow/command.go	Nested: on.command
concurrency	pkg/workflow/concurrency.go	3 workflows (3%)
engine	pkg/workflow/engine.go	74 workflows (67%)
env	pkg/workflow/env.go	Nested: jobs[].env
features	pkg/workflow/features.go	Mentioned in 47 contexts
github-token	pkg/workflow/github_token.go	Nested: safe-outputs[]
imports	pkg/workflow/imports.go	56 workflows (51%)
jobs	pkg/workflow/jobs.go	1 workflow (1%)
mcp-servers	pkg/workflow/mcp_servers.go	20 workflows (18%)
network	pkg/workflow/network.go	32 workflows (29%)
permissions	pkg/workflow/permissions.go	79 workflows (72%)
safe-outputs	pkg/workflow/safe_outputs.go	67 workflows (61%)
secret-masking	pkg/workflow/secret_masking.go	1 workflow (1%)
tools	pkg/workflow/tools.go	69 workflows (63%)

Fields Handled Inline (19)

These fields are processed in compiler.go or scattered across multiple files:

Simple fields (inline handling is appropriate):

• description - metadata field
• name - workflow name
• run-name - workflow run name (unused)
• source - tracking metadata

Complex fields (might benefit from dedicated files):

• on - trigger configuration (handled in compiler.go, filters.go, stop_after.go)
• steps - step definitions (handled in compiler.go, compiler_jobs.go)
• if - conditional logic (scattered across bundler.go, compiler_jobs.go)
• container - MCP container config (in mcp-config.go, fetch.go)

Specialized fields:

• roles - validation in role_checks.go
• strict - validation in strict_mode_validation.go
• post-steps - handled in compiler.go

Dead Code (1)

❌ githubActionsStep - No implementation anywhere

Implementation File Organization

Implementation File Analysis

The 116 non-test implementation files in pkg/workflow/ are organized into 9 clear categories:

1. Direct Schema Field Handlers (15 files)

Files that directly implement top-level schema fields:

• cache.go, command.go, concurrency.go, engine.go, env.go, features.go, github_token.go, imports.go, jobs.go, mcp_servers.go, network.go, permissions.go, safe_outputs.go, secret_masking.go, tools.go

2. Feature Support Files (30 files)

Files implementing sub-features or nested properties:

• Safe Outputs: add_comment.go, add_labels.go, create_discussion.go, create_issue.go, create_pr_review_comment.go, update_issue.go, missing_tool.go
• Trigger Features: filters.go, manual_approval.go, reactions.go, stop_after.go
• Tool Features: artifacts.go, firewall.go
• Other: notify_comment.go, role_checks.go, safe_jobs.go, strict_mode_validation.go

3. Engine Implementations (5 files)

AI engine adapters:

• agentic_engine.go, claude_engine.go, codex_engine.go, copilot_engine.go, custom_engine.go

4. Engine Support (10 files)

Engine helpers and configurations:

• claude_logs.go, claude_mcp.go, claude_settings.go, claude_tools.go, engine_firewall_support.go, engine_helpers.go, engine_network_hooks.go, engine_output.go, engine_validation.go, edit_tool_prompt.go

5. Compiler Core (5 files)

Core compilation logic:

• compiler.go, compiler_jobs.go, compiler_yaml.go, frontmatter_extraction.go, yaml_generation.go

6. Validation (8 files)

Schema and security validation:

• bundler_validation.go, docker_validation.go, npm_validation.go, pip_validation.go, engine_validation.go, permissions_validator.go, step_order_validation.go, validation.go

7. Security (7 files)

Security and safety features:

• domain_sanitization.go, expression_safety.go, redact_secrets.go, threat_detection.go, xpia.go, strict_mode_validation.go, firewall.go

8. GitHub Integration (20 files)

GitHub API and toolset integrations:

• action_cache.go, action_pins.go, action_resolver.go, github_context.go, github_tool_to_toolset.go, github_toolsets.go, git_patch.go, pr.go, etc.

9. Utilities (16 files)

Helper functions and utilities:

• args.go, bundler.go, expressions.go, nodejs.go, semver.go, shell.go, strings.go, template.go, yaml.go, etc.

Insight: The architecture is well-organized with clear separation of concerns. Most files fall into logical categories.

Usage Statistics

Workflow Field Usage Analysis

Analyzed 110 production workflows in .github/workflows/:

Heavily Used Fields (50%+ adoption)

Field	Workflows	Adoption	Notes
on	79	72%	Trigger configuration
permissions	79	72%	GitHub permissions
engine	74	67%	AI engine selection
tools	69	63%	Tool configuration
safe-outputs	67	61%	Output handling
timeout-minutes	67	61%	Timeout configuration
imports	56	51%	Shared component imports

Moderately Used Fields (10-49% adoption)

Field	Workflows	Adoption	Notes
name	35	32%	Workflow name
network	32	29%	Network permissions
strict	27	25%	Strict mode
steps	26	24%	Custom steps
mcp-servers	20	18%	MCP server config

Rarely Used Fields (1-9% adoption)

Field	Workflows	Adoption	Notes
concurrency	3	3%	Concurrency control
roles	3	3%	Role-based access
source	3	3%	Source tracking
if	3	3%	Conditional execution
description	2	2%	Workflow description
cache	1	1%	Cache configuration
jobs	1	1%	Custom jobs
post-steps	1	1%	Undocumented!
secret-masking	1	1%	Secret masking
services	1	1%	Service containers

Never Used (0% adoption)

Field	In Schema	Has Impl	Status
githubActionsStep	✅	❌	Dead code
run-name	✅	✅	Implemented but unused
runtimes	✅	✅	Unclear if ready
timeout_minutes	✅	✅	Legacy alias

Documentation Coverage

Documentation Analysis

Well Documented Fields (13)

These fields have H3 sections in docs/src/content/docs/reference/frontmatter.md:

• AI Engine (engine)
• Description (description)
• Feature Flags (features)
• GitHub Token (github-token)
• Network Permissions (network)
• Permissions (permissions)
• Repository Access Roles (roles)
• Run Configuration (run-name, runs-on, timeout-minutes)
• Safe Outputs (safe-outputs)
• Source Tracking (source)
• Strict Mode (strict)
• Trigger Events (on)
• Workflow Concurrency Control (concurrency)

Fields in Specialized Docs (9)

These fields are documented in other reference files:

• cache → tools.md (under cache-memory)
• command → triggers.md (under on.command)
• container → guides/mcps.md
• imports → imports.md
• mcp-servers → guides/mcps.md
• secret-masking → Mentioned briefly
• steps → Mentioned in jobs context
• tools → tools.md

Undocumented (5)

Fields that lack documentation:

Field	Status	Recommendation
post-steps	❌ Used but not documented	HIGH PRIORITY - Add to frontmatter.md
githubActionsStep	❌ Dead code	Remove from schema
run-name	⚠️ Documented but never used	Add examples or deprecate
runtimes	⚠️ In schema, not documented	Document or remove
timeout_minutes	Legacy	Don't document (use timeout-minutes)

Recommendations

Recommendations

🔴 HIGH PRIORITY

1. Remove githubActionsStep from Schema

Issue: Confirmed dead code across 3 consecutive analyses
Impact: Reduces schema complexity, eliminates user confusion
Risk: None (never used anywhere)
Action: Remove from main_workflow_schema.json

2. Document post-steps Field

Issue: Used in production (test-post-steps.md) but completely undocumented
Impact: Users can't discover valuable feature
Risk: Feature adoption blocked by lack of documentation
Action: Add comprehensive section to frontmatter.md with:

• Purpose and use cases
• Syntax and examples
• Relationship to regular steps
• When to use post-steps vs steps

3. Resolve timeout_minutes Ambiguity

Issue: Legacy alias never used (0 of 110 workflows)
Impact: Schema clarity, reduce confusion
Risk: Very low
Action: Mark as deprecated or remove from schema

4. Investigate runtimes Field Status

Issue: Exists in both main and included schemas but never used
Impact: Unclear if feature is production-ready
Risk: Either dead code or missing critical documentation
Action: Either:

• Document with examples if ready for production
• Remove from schema if not ready

---

🟡 MEDIUM PRIORITY

5. Consider Dedicated Files for Complex Inline Fields

Issue: Complex features handled inline in compiler.go
Impact: Harder to maintain and understand
Files to consider:

• on → pkg/workflow/triggers.go (currently in compiler.go, filters.go)
• steps → pkg/workflow/steps.go (currently in compiler_jobs.go)
• if → pkg/workflow/conditions.go (currently scattered)

Benefit: Clearer code organization, easier maintenance
Risk: Refactoring effort

6. Add Usage Statistics to Schema

Issue: No way to track field adoption rates
Impact: Helps prioritize documentation and deprecation decisions
Action: Consider adding custom schema properties:

• x-usage-count: Number of workflows using field
• x-adoption-rate: Percentage adoption
• x-last-updated: When field was last modified

---

🟢 LOW PRIORITY

7. Review Rarely Used Fields

Issue: Some fields have very low adoption (1-3%)
Fields:

• cache (1 workflow) - Underutilized? Add examples?
• jobs (1 workflow) - Custom jobs rare?
• services (1 workflow) - Unclear use case?

Impact: Could improve adoption of valuable features
Risk: May be intentionally niche features (acceptable)
Action: Add prominent examples or cookbook recipes

Strategy Performance

Strategy Used: Strategy-010 - Implementation File Coverage & Architectural Pattern Analysis
Findings: 7 issues across critical to low severity
Effectiveness: ⭐⭐⭐⭐⭐ VERY HIGH
Should Reuse: ✅ YES - Every 4-5 analyses

Key Insights:

1. Architectural clarity: The 116 implementation files follow clear patterns organized into 9 categories
2. Nested properties matter: Many "unused" fields are actually used as nested properties (command → on.command)
3. Dedicated vs inline: 15 fields have dedicated files, 19 handled inline - both patterns have merit
4. Dead code confirmation: githubActionsStep has zero presence across all layers (3rd confirmation)

Complements Other Strategies:

• Strategy-002: Field-level enum validation
• Strategy-007: Example validation
• Strategy-009: End-to-end feature tracing

This strategy provides the architectural perspective that reveals code organization patterns invisible to field-level analysis.

Files Analyzed

Schemas (3):

• pkg/parser/schemas/main_workflow_schema.json
• pkg/parser/schemas/included_file_schema.json
• pkg/parser/schemas/mcp_config_schema.json

Parser (1):

• pkg/parser/frontmatter.go

Implementation (116 files):

• pkg/workflow/*.go (all non-test files)

Documentation (7+ files):

• docs/src/content/docs/reference/frontmatter.md
• docs/src/content/docs/reference/*.md

Production Workflows (110):

• .github/workflows/*.md (all workflow files)

Next Steps

• Create issue: Remove githubActionsStep field from schema
• Create issue: Document post-steps field in frontmatter.md
• Create issue: Investigate runtimes field status
• Create issue: Deprecate or remove timeout_minutes
• Consider: Refactor complex inline fields to dedicated files
• Consider: Add usage tracking to schema metadata

---

Strategy cache updated at /tmp/gh-aw/cache-memory/strategies.json

AI generated by Schema Consistency Checker

[github-actions[bot]]

This discussion was automatically closed because it was created by an agentic workflow more than 1 week ago.