docs: fix documentation drift — remove duplicate ir/ listing and add missing CLI commands

[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 missing tasks.rs	AGENTS.md
CLI Reference	7 non-hidden subcommands absent from Commands table: mcp-author, inspect, graph, whatif, lint, catalog, trace	README.md

Details

AGENTS.md — duplicate ir/ directory block

The src/compile/ir/ directory appeared twice in the architecture tree:

• First entry (line 54, using ├──): listed tasks.rs but omitted summary.rs
• Second entry (line 105, using └──): listed summary.rs but omitted tasks.rs

Both files exist on disk (src/compile/ir/tasks.rs and src/compile/ir/summary.rs). The duplicate first block was removed and tasks.rs was added to the canonical second block, which now correctly lists all 13 files in the directory.

README.md — missing CLI commands

The Commands table in the CLI Reference section showed only 14 of the 21 non-hidden subcommands defined in src/main.rs. The following 7 were missing:

Command	Purpose
mcp-author	Author-facing stdio MCP server for IDE/Copilot Chat integrations
inspect	Inspect a source file's typed IR
graph	Query the resolved dependency graph (dump/deps/outputs)
whatif	Static reachability: classify jobs skipped if a step/job fails
lint	Run structural lint checks over an agent source file
catalog	List safe-outputs, runtimes, tools, engines, and models
trace	Trace a build's failing-job chain using audit data + local IR graph

All seven are documented in docs/cli.md; they were simply absent from the README's command summary.

Applied Fixes

• Remove duplicate src/compile/ir/ block from AGENTS.md architecture tree
• Add tasks.rs to the canonical ir/ listing in AGENTS.md
• Add 7 missing subcommands (mcp-author, inspect, graph, whatif, lint, catalog, trace) to the Commands table in README.md

---

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 27730793126 -n agent -D /tmp/agent-27730793126

# Create a new branch
git checkout -b docs/fix-documentation-drift-ir-cli-commands-60d68cf2c73faff0 main

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

# Push the branch and create the pull request
git push origin docs/fix-documentation-drift-ir-cli-commands-60d68cf2c73faff0
gh pr create --title 'docs: fix documentation drift — remove duplicate ir/ listing and add missing CLI commands' --base main --head docs/fix-documentation-drift-ir-cli-commands-60d68cf2c73faff0 --repo githubnext/ado-aw

Generated by Documentation Freshness Check · 2.1K AIC · ⌖ 47.3 AIC · ⊞ 36.2K · ◷