docs: fix documentation drift — duplicate ir/ block in AGENTS.md, missing fields and links in README.md

[github-actions]

Documentation Freshness Audit

This audit found the following inconsistencies between code and documentation:

Findings

Area	Issue	File(s)
Architecture tree	compile/ir/ directory listed twice in AGENTS.md — first block (outdated) missing summary.rs; second block (canonical) missing tasks/	AGENTS.md
Front matter fields	supply-chain: front-matter field (FrontMatter.supply_chain) missing from README table	README.md
Documentation index	docs/execution-context.md, docs/supply-chain.md, docs/safe-output-permissions.md, docs/mcp-author.md exist in docs/ and are linked in AGENTS.md but absent from README's Documentation index	README.md

Details

AGENTS.md — Duplicate ir/ directory block

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

• The first block (after agentic_pipeline.rs) included tasks/ but was missing summary.rs, and had less-specific file descriptions.
• The second block (at the end of compile/, labeled "see docs/ir.md") included summary.rs and had accurate descriptions, but was missing the tasks/ subdirectory.

Both pointed to the same single directory on disk. The fix removes the first (outdated) block and adds tasks/ to the second (canonical) block.

README.md — Missing supply-chain: in front-matter fields table

FrontMatter in src/compile/types.rs has a supply_chain field (serialized as supply-chain:). It was already documented in docs/front-matter.md and docs/supply-chain.md, but was absent from the quick-reference table in README.md.

README.md — Missing docs links in Documentation index

The following docs existed in docs/ and were referenced in AGENTS.md but were not listed in README.md's Documentation section:

• docs/execution-context.md — referenced only in the front-matter table cell, not the index
• docs/supply-chain.md — not referenced anywhere in README
• docs/safe-output-permissions.md — not referenced anywhere in README
• docs/mcp-author.md — not referenced anywhere in README

Applied Fixes

• Removed duplicate (outdated) compile/ir/ block from AGENTS.md architecture tree
• Added tasks/ subdirectory entry to the canonical ir/ block in AGENTS.md
• Added supply-chain: row to the front-matter fields table in README.md
• Added docs/execution-context.md, docs/supply-chain.md, docs/safe-output-permissions.md to README.md "Authoring agent files" index
• Added docs/mcp-author.md to README.md "Compiler internals & operations" index

---

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

• README.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 27777708162 -n agent -D /tmp/agent-27777708162

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

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

# Push the branch and create the pull request
git push origin docs/fix-documentation-drift-b39d2373f5e2583c
gh pr create --title 'docs: fix documentation drift — duplicate ir/ block in AGENTS.md, missing fields and links in README.md' --base main --head docs/fix-documentation-drift-b39d2373f5e2583c --repo githubnext/ado-aw

Generated by Documentation Freshness Check · 2.3K AIC · ⌖ 19.3 AIC · ⊞ 35K · ◷