docs: fix documentation drift — duplicate IR entry, missing CLI commands, missing supply-chain field

[github-actions]

Documentation Freshness Audit

This audit found the following inconsistencies between the codebase and documentation:

Findings

Area	Issue	File(s)
Architecture tree	src/compile/ir/ directory listed twice — the first entry (13 lines) was missing summary.rs and had shorter/older descriptions	AGENTS.md
CLI command index	AGENTS.md doc-index entry for docs/cli.md listed only 14 commands, missing mcp-author, trace, inspect, graph, whatif, lint, catalog	AGENTS.md
CLI Reference	README CLI command listing missing 7 commands: mcp-author, trace, inspect, graph, whatif, lint, catalog	README.md
Front Matter table	supply-chain: field exists in FrontMatter struct and has a full docs/supply-chain.md page, but was absent from the README reference table	README.md
Documentation index	README docs index missing execution-context.md, supply-chain.md, safe-output-permissions.md, mcp-author.md	README.md

Details

1. Duplicate src/compile/ir/ in AGENTS.md architecture tree

The tree contained two separate entries for src/compile/ir/ under src/compile/. The first (older) entry was missing summary.rs — the public PipelineSummary/GraphSummary type that was added for agent-facing tooling. The second entry was complete and correct. Removed the first duplicate.

2. AGENTS.md docs/cli.md index entry

The inline command list in the docs/cli.md description only covered 14 commands (init through audit). Missing: mcp-author (IDE/Copilot Chat MCP server), trace (audit + IR correlation), inspect, graph, whatif, lint, catalog (all read-only IR query tools added in later releases).

3. README CLI Reference

Same gap as above — the Commands: block in the README was missing the same 7 commands that have real user-facing value.

4. README Front Matter table missing supply-chain:

The supply-chain: front matter field is fully implemented (src/compile/types.rs), has a dedicated reference page (docs/supply-chain.md), and is referenced in AGENTS.md's security section — but was completely absent from the README's Front Matter Fields reference table.

5. README docs index incomplete

Four doc pages referenced in AGENTS.md (and linked from other README sections) were not in the README docs index: execution-context.md, supply-chain.md, safe-output-permissions.md, mcp-author.md.

Applied Fixes

• Remove duplicate src/compile/ir/ block from AGENTS.md architecture tree
• Update AGENTS.md docs/cli.md index entry to list all non-hidden commands
• Add mcp-author, trace, inspect, graph, whatif, lint, catalog to README.md CLI Reference
• Add supply-chain row to README.md Front Matter Fields table
• Add execution-context.md, supply-chain.md, safe-output-permissions.md, mcp-author.md to README.md documentation 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 27818891665 -n agent -D /tmp/agent-27818891665

# Create a new branch
git checkout -b docs/fix-documentation-drift-2026-06-19-49e12aad84cc0e46 main

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

# Push the branch and create the pull request
git push origin docs/fix-documentation-drift-2026-06-19-49e12aad84cc0e46
gh pr create --title 'docs: fix documentation drift — duplicate IR entry, missing CLI commands, missing supply-chain field' --base main --head docs/fix-documentation-drift-2026-06-19-49e12aad84cc0e46 --repo githubnext/ado-aw

Generated by Documentation Freshness Check · 2.7K AIC · ⌖ 21.1 AIC · ⊞ 35K · ◷