[Schema Consistency] Backward Dependency Chain Tracing - Feb 17, 2026

[github-actions[bot]]

Summary

Strategy: Backward Dependency Chain Tracing (NEW APPROACH)
Date: February 17, 2026
Findings: 8 categories analyzed, 2 CRITICAL documentation gaps discovered
Effectiveness: ⭐⭐⭐⭐⭐ VERY HIGH

This run used a novel reverse-engineering approach: analyzing compiled GitHub Actions YAML (.lock.yml files) to discover runtime features, then tracing backward to frontmatter fields and schema definitions to identify undocumented behaviors.

Critical Documentation Gaps

🚨 GitHub Context Injection System (HIGH PRIORITY)

What was discovered:
When tools.github is enabled (default), the compiler automatically injects 30+ GitHub context variables into the agent prompt via a hidden system:

Auto-injected variables:

• GH_AW_GITHUB_ACTOR (from $\{\{ github.actor }})
• GH_AW_GITHUB_REPOSITORY (from $\{\{ github.repository }})
• GH_AW_GITHUB_WORKSPACE (from $\{\{ github.workspace }})
• GH_AW_GITHUB_EVENT_ISSUE_NUMBER (from $\{\{ github.event.issue.number }})
• GH_AW_GITHUB_EVENT_DISCUSSION_NUMBER (from $\{\{ github.event.discussion.number }})
• GH_AW_GITHUB_EVENT_PULL_REQUEST_NUMBER (from $\{\{ github.event.pull_request.number }})
• GH_AW_GITHUB_EVENT_COMMENT_ID (from $\{\{ github.event.comment.id }})
• GH_AW_GITHUB_RUN_ID (from $\{\{ github.run_id }})
• GH_AW_GITHUB_EVENT_INPUTS_* (from workflow_dispatch inputs)
• GH_AW_GITHUB_EVENT_WORKFLOW_RUN_* (from workflow_run events)
• ...and 20+ more

How it works:

1. Embedded prompt at pkg/workflow/prompts/github_context_prompt.md
2. Contains Handlebars-style conditionals: \{\\{\#if $\{\{ github.actor }} }}
3. Expressions extracted by ExpressionExtractor at compile time
4. Replaced with placeholders: __GH_AW_GITHUB_ACTOR__
5. Substituted at runtime in unified prompt creation step
6. Code: pkg/workflow/unified_prompt_step.go:325-347

Impact:

• Users don't know these context variables exist and can be used in workflows
• No documentation explaining which GitHub Actions expressions become available
• The __GH_AW_GITHUB_*__ placeholder format is never explained
• Affects ALL workflows using tools.github (enabled by default)

Recommendation:

1. Add schema description for tools.github explaining automatic context injection
2. Document the github-context system in reference docs
3. List all available GH_AW_GITHUB_* variables and their GitHub Actions sources
4. Explain the \{\\{\#if}} → __PLACEHOLDER__ → substitution flow

Code references:

• pkg/workflow/prompts/github_context_prompt.md - embedded prompt
• pkg/workflow/unified_prompt_step.go:325-347 - injection logic
• pkg/workflow/expression_extraction.go - expression parser

---

🚨 Multi-Job Workflow Architecture (HIGH PRIORITY)

What was discovered:
Simple frontmatter workflows are compiled into 6+ interdependent GitHub Actions jobs, but this architecture is completely undocumented.

Standard job structure:

pre_activation (comment triggers only) 
    ↓
detection (comment triggers only)
    ↓
activation (always first - 100% of workflows)
    ↓
agent (main agentic job)
    ↓
├─→ safe_outputs (when safe-outputs configured)
└─→ update_cache_memory (when cache-memory configured)
    ↓
conclusion (always last - summary, cleanup, reactions)

Job purposes:

• pre_activation: Validates comment source, checks bot status, filters by roles
• detection: Detects slash commands from issue/PR/discussion comments
• activation: Checks workflow timestamps, creates unified prompt, sets up context
• agent: Runs AI engine (Claude/Copilot/Codex) with the compiled prompt
• safe_outputs: Processes MCP tool outputs (creates issues, PRs, discussions, etc.)
• update_cache_memory: Saves cache-memory state back to GitHub Actions cache
• conclusion: Posts summary, adds reaction emojis, handles cleanup

Job generation rules:

• on: issue_comment → generates pre_activation, detection jobs
• on: schedule → skips detection, goes straight to activation
• safe-outputs: present → generates safe_outputs job
• cache-memory: present → generates update_cache_memory job

Impact:

• Users confused why their 10-line frontmatter becomes 150+ lines of compiled YAML
• No explanation of job dependencies and execution order
• Debugging is difficult without understanding job architecture
• Users don't know which job to check when workflows fail

Recommendation:

1. Add schema-level description explaining compilation model
2. Create dedicated docs page: docs/src/content/docs/concepts/compilation.md
3. Explain trigger type → job structure mapping
4. Add visual diagram showing job dependency graph
5. Document what each job does and when it runs

Code references:

• pkg/workflow/compiler_activation_jobs.go - activation job generation
• pkg/workflow/detection_job.go - detection job generation
• pkg/workflow/safe_outputs_steps.go - safe-outputs job generation
• pkg/workflow/cache.go - cache-memory job generation

---

Medium Priority Issues

View Agent CLI Flag Mapping Gap

Issue: Users don't understand how frontmatter configuration translates to agent CLI arguments

Example mappings discovered:

• tools.bash: ["*"] → --allow-all-tools --allow-all-paths
• tools.bash: ["cat", "ls"] → --allowed-tools 'shell(cat),shell(ls),...'
• sandbox.agent: workspace → --add-dir "\$\{GITHUB_WORKSPACE}"
• engine.max-turns: 15 → --max-turns 15
• engine.agent: "ci-cleaner" → --agent ci-cleaner (Copilot only)

Compiled Copilot command:

/usr/local/bin/copilot \
  --add-dir /tmp/gh-aw/ \
  --log-level all \
  --log-dir /tmp/gh-aw/sandbox/agent/logs/ \
  --add-dir "\$\{GITHUB_WORKSPACE}" \
  --disable-builtin-mcps \
  --agent ci-cleaner \
  --allow-all-tools \
  --allow-all-paths \
  --share /tmp/gh-aw/sandbox/agent/logs/conversation.md \
  --prompt "$(cat /tmp/gh-aw/aw-prompts/prompt.txt)"

Compiled Claude command:

claude \
  --print \
  --disable-slash-commands \
  --no-chrome \
  --max-turns 100 \
  --mcp-config /tmp/gh-aw/mcp-config/mcp-servers.json \
  --allowed-tools 'Bash,Edit,Glob,Grep,...' \
  --debug-file /tmp/gh-aw/agent-stdio.log \
  --verbose \
  --permission-mode bypassPermissions \
  --output-format stream-json

Recommendation:

• Add "How it Works" section to engine documentation
• Show examples: frontmatter field → generated CLI flags
• Document each engine's specific CLI arguments

View Network Domain Allowlist Defaults

Issue: Default network domain allowlists vary by engine but are not documented

Defaults discovered in compiled YAML:

Claude engine includes:

• anthropic.com
• api.anthropic.com
• sentry.io
• statsig.anthropic.com
• ghcr.io
• Plus 50+ common domains (github.com, pypi.org, npmjs.org, etc.)

Codex engine includes:

• openai.com
• api.openai.com
• Plus 40+ common domains

Copilot engine includes:

• api.githubcopilot.com
• api.business.githubcopilot.com
• telemetry.enterprise.githubcopilot.com
• Plus 30+ common domains

Environment variable pattern:

GH_AW_ALLOWED_DOMAINS: "*.githubusercontent.com,anthropic.com,api.anthropic.com,..."

Recommendation:

• Document default domain lists per engine in reference docs
• Explain how allow-domains and block-domains frontmatter fields modify defaults
• Add security note about which domains are added automatically

Code references:

• pkg/workflow/domains.go - domain allowlist generation
• pkg/workflow/engine_network_hooks.go - network hook generation

---

Positive Findings (Consistent)

✓ Model Override System - GH_AW_MODEL_AGENT_* environment variables properly documented and working
✓ Safe-Inputs/Safe-Outputs - Fields properly documented in schema
✓ Cache-Memory Variables - GH_AW_CACHE_DIR, GH_AW_CACHE_DESCRIPTION documented and working
✓ Concurrency Field - Both string and object formats properly supported via oneOf

---

Strategy Performance

Methodology Rating: ⭐⭐⭐⭐⭐ VERY HIGH

Why this strategy was extremely effective:

• Started from ground truth (compiled YAML) rather than assumptions
• Found implicit behaviors that wouldn't appear in forward schema→code analysis
• Revealed architectural patterns not documented anywhere
• Identified high-impact user confusion (multi-job structure)
• Discovered hidden systems (GitHub context injection)

Novel discoveries:

1. GitHub context injection system with 30+ auto-injected variables
2. Multi-job architecture patterns (6 standard job types)
3. Job dependency graph and execution order
4. Engine-specific network domain defaults
5. Frontmatter → CLI flag transformation patterns

Should reuse: YES - Extremely effective for finding undocumented runtime behaviors and implicit architectural patterns

Next strategy suggestions:

• Combine with "Error Message Archaeology" (Strategy 7) for comprehensive coverage
• Use backward tracing for other compilation artifacts (MCP configs, network hooks, sandbox setup)

---

Impact Assessment

Finding	Severity	Users Affected	Documentation Gap	Fix Priority
GitHub context injection undocumented	MEDIUM	All workflows with tools.github (100% default)	Complete	HIGH
Multi-job architecture undocumented	HIGH	All users (conceptual model)	Complete	HIGH
Agent CLI flag mapping unclear	MEDIUM	Users debugging agent behavior	Partial	MEDIUM
Default network domains undocumented	LOW	Security-conscious users	Complete	LOW

---

Recommendations Summary

High Priority

1. Document GitHub Context Injection System

   • Target: docs/src/content/docs/reference/frontmatter.md under tools.github
   • Content: List all GH_AW_GITHUB_* variables and their GitHub Actions sources
   • Impact: Clarifies hidden system affecting 100% of workflows

2. Document Multi-Job Architecture

   • Target: New page docs/src/content/docs/concepts/compilation.md
   • Content: Job generation rules, dependencies, execution order, visual diagram
   • Impact: Explains fundamental compilation model users don't understand

Medium Priority

3. Add CLI Flag Mapping Examples

   • Target: Extend engine documentation pages
   • Content: Show frontmatter → CLI flag transformations with examples

4. Document Network Domain Defaults

   • Target: New section in network/security documentation
   • Content: Per-engine default domain lists, allow/block interaction

---

Code References

GitHub context injection:

• pkg/workflow/prompts/github_context_prompt.md:1-27 - embedded prompt template
• pkg/workflow/unified_prompt_step.go:325-347 - context injection logic
• pkg/workflow/expression_extraction.go - expression parser

Multi-job architecture:

• pkg/workflow/compiler_activation_jobs.go - activation job
• pkg/workflow/detection_job.go - detection job
• pkg/workflow/safe_outputs_steps.go - safe-outputs job
• pkg/workflow/cache.go - cache-memory job

Agent execution:

• pkg/workflow/claude_engine.go:163 - Claude CLI generation
• pkg/workflow/copilot_engine_execution.go:76 - Copilot CLI generation
• pkg/workflow/codex_engine.go:137 - Codex CLI generation

---

References:

• §22093925288

AI generated by Schema Consistency Checker

• expires on Feb 24, 2026, 10:07 AM UTC

[github-actions[bot]]

This discussion was automatically closed because it expired on 2026-02-24T10:07:35.760Z.

Closed by Workflow