docs: fix documentation drift — duplicate ir/ in AGENTS.md and env: field comment

[github-actions]

Documentation Freshness Audit

This audit found the following inconsistencies between code and documentation:

Findings

Area	Issue	File(s)
Architecture tree	src/compile/ir/ listed twice — first entry missing summary.rs, second entry missing tasks/, second entry in wrong alphabetical position	AGENTS.md
Front matter docs	env: field comment says "reserved, not yet implemented" but the field IS accepted by the parser (defined in FrontMatter struct in types.rs and sanitized); it's just not yet forwarded to compiled pipeline output	docs/front-matter.md

Details

AGENTS.md — Duplicate ir/ directory listing

The architecture tree in AGENTS.md contained two separate entries for src/compile/ir/:

• Lines 54–66: correct alphabetical position, included tasks/ subdirectory, but missing summary.rs
• Lines 105–117: at the end of compile/ (after types.rs), had summary.rs, but missing tasks/

The actual filesystem has one src/compile/ir/ directory containing both tasks/ and summary.rs. The second (misplaced) entry was removed; summary.rs was added to the first entry.

docs/front-matter.md — Misleading env: field comment

The commented-out env: example said # (reserved, not yet implemented). However:

• The env: HashMap<String, String> field IS declared in the FrontMatter struct (src/compile/types.rs)
• It IS deserialized from user-authored front matter (no parse error)
• It IS sanitized in FrontMatter::sanitize_config_fields()
• It is NOT currently forwarded to the compiled pipeline YAML (confirmed by searching all compilation code for front_matter.env)

"Reserved" implies the field name is blocked; "not yet implemented" implies it errors on use. Neither is accurate — the field is silently accepted. The comment now reads: # (accepted by parser, not yet forwarded to compiled pipeline output).

Applied Fixes

• Remove second duplicate src/compile/ir/ block from AGENTS.md architecture tree
• Add missing summary.rs to the (now-only) src/compile/ir/ entry in AGENTS.md
• Update docs/front-matter.md env: comment to accurately describe field behavior

---

This pull request was created by the automated documentation freshness check.

---

Warning

Protected Files — Push Permission Denied

This was originally intended as a pull request, but the patch modifies protected files. A human must create the pull request manually.

Protected files

• AGENTS.md

The push was rejected because GitHub Actions does not have workflows permission to push these changes, and is never allowed to make such changes, or other authorization being used does not have this permission.

Create the pull request manually

# Download the patch from the workflow run
gh run download 27877871595 -n agent -D /tmp/agent-27877871595

# Create a new branch
git checkout -b docs/fix-documentation-drift-f0e86e51d88a1e48 main

# Apply the patch (--3way handles cross-repo patches)
git am --3way /tmp/agent-27877871595/aw-docs-fix-documentation-drift.patch

# Push the branch and create the pull request
git push origin docs/fix-documentation-drift-f0e86e51d88a1e48
gh pr create --title 'docs: fix documentation drift — duplicate ir/ in AGENTS.md and env: field comment' --base main --head docs/fix-documentation-drift-f0e86e51d88a1e48 --repo githubnext/ado-aw

Generated by Documentation Freshness Check · 1.7K AIC · ⌖ 49.6 AIC · ⊞ 36.6K · ◷