[Schema Consistency] 🔍 Schema Consistency Check #9 - Cross-File Feature Tracing (Oct 27, 2025)

[github-actions[bot]]

🔍 Schema Consistency Check - October 27, 2025

Summary

• Inconsistencies Found: 5 issues
• Categories Analyzed: Schema (nested structure), Parser, Documentation, Workflows
• Strategy Used: Cross-File Feature Consistency & Implementation Gap Detection (Strategy-009)
• New Strategy: YES - First time tracing features end-to-end through all layers
• Total Runs: 9 (This is the 9th consistency check)

Executive Summary

This analysis used a new end-to-end tracing strategy to follow features from schema → parser → compiler → docs → workflows. The key discovery: schema nesting structure matters critically. Previous strategies incorrectly flagged features as "missing" when they were actually correctly nested under parent properties:

• ✅ cache-memory is under tools.cache-memory (not top-level)
• ✅ stop-after is under on.stop-after (not top-level)
• ✅ safe-jobs migrated to safe-outputs.jobs (backwards compatible)

This strategy revealed excellent architectural decisions (proper nesting, backwards compatibility) while confirming one persistent issue (dead code) and identifying areas needing clarification.

---

Critical Issues

1. 🟡 CONFIRMED: githubActionsStep is Dead Code

Status: Low priority but should be removed

Evidence:

• ✅ Schema: Field exists with description "GitHub Actions workflow step"
• ❌ Parser: Not referenced anywhere in pkg/parser/
• ❌ Compiler: No implementation in pkg/workflow/
• ❌ Docs: No documentation
• ❌ Usage: Zero workflows use it (checked all 55 workflows)

History: Confirmed dead by 3 different strategies:

• Strategy-002 (2025-10-23)
• Strategy-007 (2025-10-26)
• Strategy-009 (2025-10-27)

Impact: LOW - Doesn't affect functionality but clutters schema

Recommendation: Remove githubActionsStep from pkg/parser/schemas/main_workflow_schema.json

---

2. 🟢 RESOLVED: cache-memory, stop-after, safe-jobs Are NOT Missing

Previous Concern: Earlier strategies flagged these as missing from schema

Resolution: These features are correctly placed in nested schema properties:

Feature	Location	Status
cache-memory	tools.cache-memory	✅ Correctly nested
stop-after	on.stop-after	✅ Correctly nested
safe-jobs	safe-outputs.jobs	✅ Migrated with backwards compat

Backwards Compatibility Discovery:

The compiler in pkg/workflow/compiler.go:971 handles safe-jobs migration elegantly - workflows can use either:

• New: safe-outputs: jobs: {...}
• Old: safe-jobs: {...} (still works!)

Impact: POSITIVE - Excellent schema organization and backwards compatibility

No Action Required: Architecture is correct

---

Documentation Gaps

3. 🟡 post-steps: Minimal Documentation

Feature: post-steps

• ✅ Schema: Defined with description "Custom workflow steps to run after AI execution"
• ⚠️ Compiler: Mentioned in compiler.go, no dedicated file
• ⚠️ Docs: Listed in frontmatter.md but no examples or usage guide
• ✅ Usage: 1 workflow uses it

Gap: Users know the field exists but don't have practical examples

Recommendation:

• MEDIUM Priority: Add examples section to docs/src/content/docs/reference/frontmatter.md
• Show practical use cases for post-steps
• Explain when to use post-steps vs steps vs safe-outputs

---

4. 🟡 features: Unused Experimental Feature Flag

Feature: features

• ✅ Schema: Well-described "Feature flags to enable experimental or optional features"
• ✅ Compiler: Has dedicated file pkg/workflow/features.go
• ✅ Docs: Documented in safe-outputs.md, engines.md, markdown.md
• ❌ Usage: Zero production workflows use it

Questions:

• Is this still experimental?
• What features can be enabled?
• Should this be promoted or deprecated?

Recommendation:

• LOW Priority: Add adoption guide if feature is ready
• Or mark as experimental in schema if still in development
• Document which features can be toggled

---

5. 🟡 runtimes: Unclear Implementation Status

Feature: runtimes

• ✅ Schema: Well-described "Runtime environment version overrides"
• ✅ Parser: Extracted in frontmatter.go:948
• ⚠️ Compiler: No dedicated file (possibly in runtime_setup.go?)
• ✅ Docs: Documented in frontmatter-full.md
• ❌ Usage: Zero production workflows use it

Questions:

• Is this feature functional?
• If yes, where is the implementation?
• If no, why is it in schema?

Recommendation:

• MEDIUM Priority: Verify implementation status
• If functional: Add practical example to docs
• If not functional: Remove from schema or add "Coming soon" note

---

Positive Findings

✅ Excellent Schema Organization

1. Logical Nesting: Tools under tools, triggers under on, safe outputs under safe-outputs
2. Backwards Compatibility: Old safe-jobs still works while migrating to safe-outputs.jobs
3. Implementation Quality: 328 workflow files support all schema features
4. Feature Adoption:
   • 27 workflows use strict: true (49% adoption)
   • 25 workflows use network (45% adoption)
   • 3 workflows use concurrency (5% adoption)

✅ All Production Workflows Valid

• Checked all 55 workflows in .github/workflows/
• Zero schema violations found
• Features used correctly across all workflows

---

Recommendations

Immediate Actions

1. Remove Dead Code (LOW PRIORITY)
   • Remove githubActionsStep from main_workflow_schema.json
   • It's been confirmed dead by 3 independent analyses

Documentation Actions

2. Improve post-steps Documentation (MEDIUM PRIORITY)

   • Add practical examples to frontmatter.md
   • Explain use cases vs other step types

3. Clarify runtimes Status (MEDIUM PRIORITY)

   • Verify if feature is functional
   • Add examples if working
   • Mark as experimental or remove if not ready

4. Features Adoption Guide (LOW PRIORITY)

   • Document what features can be enabled
   • Show when to use feature flags

---

Strategy Performance

Strategy 009: Cross-File Feature Consistency

Metrics:

• Findings: 5 issues (3 documentation gaps, 1 dead code, 1 unclear status)
• Effectiveness: VERY HIGH
• False Positives: 3 (cache-memory, stop-after, safe-jobs were actually correct)
• New Insights: Schema nesting structure critical to understand

Key Learnings:

1. Must check nested properties, not just top-level fields
2. Backwards compatibility creates dual locations (old + new)
3. 328 implementation files but only ~50 are feature implementations

Should Reuse: YES - Every 4-5 runs to catch schema reorganization and field migrations

---

Appendix: Features Traced

Feature	Schema	Parser	Compiler	Docs	Usage	Status
cache-memory	✅ tools	✅	✅ cache.go	✅	0	Nested correctly
stop-after	✅ on	✅	✅ stop_after.go	✅	0	Nested correctly
safe-jobs	✅ safe-outputs	✅	✅ safe_jobs.go	✅	0	Migrated + backwards compat
strict	✅	✅	✅ strict_mode.go	✅	27	Working perfectly
network	✅	✅	✅ network.go	✅	25	Working perfectly
concurrency	✅	✅	✅ concurrency.go	✅	3	Working perfectly
post-steps	✅	⚠️	⚠️ compiler.go	⚠️	1	Needs docs
features	✅	✅	✅ features.go	✅	0	Unused experimental
runtimes	✅	✅	⚠️	✅	0	Unclear status
githubActionsStep	✅	❌	❌	❌	0	Dead code

---

Conclusion

This consistency check reveals excellent architectural decisions in schema organization and backwards compatibility. The main findings are:

1. ✅ Schema structure is sound - Nested properties are logical and well-organized
2. ✅ Backwards compatibility works - Field migrations handled gracefully
3. ✅ Production workflows valid - All 55 workflows comply with schema
4. 🟡 Documentation gaps exist - post-steps, features, runtimes need better docs
5. 🟡 Dead code confirmed - githubActionsStep should be removed

Overall Assessment: System is in good health. Issues are minor (documentation, dead code) not critical bugs.

---

Generated by Strategy-009: Cross-File Feature Consistency & Implementation Gap Detection
Full report: /tmp/gh-aw/cache-memory/consistency-report-2025-10-27.md
Strategy database: /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 month ago.