docs: fix documentation drift — duplicate ir/ listing and 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, duplicate entry missing tasks/	AGENTS.md
CLI reference	7 commands present in src/main.rs missing from the Commands table	README.md

Details

1. Duplicate ir/ directory in AGENTS.md architecture

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

• First entry (after agentic_pipeline.rs): included tasks/ subdirectory but was missing summary.rs
• Second entry (after types.rs, as the closing └── of compile/): included summary.rs but was missing tasks/

There is only one src/compile/ir/ directory on disk. The duplicate was introduced when summary.rs was added and the second entry was created instead of updating the first. This would mislead AI agents reading the architecture into thinking there are two separate ir/ modules.

Fix: Remove the duplicate second listing; add summary.rs to the first (canonical) listing and change └── emit.rs to ├── emit.rs.

2. Missing CLI commands in README.md

The CLI reference Commands table was missing 7 commands that exist in src/main.rs:

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

These are all documented in docs/cli.md but were absent from the README quick-reference.

Applied Fixes

• AGENTS.md: Merged two ir/ directory listings into one, adding summary.rs
• README.md: Added mcp-author, trace, inspect, graph, whatif, lint, catalog to the CLI Commands table

---

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

# Create a new branch
git checkout -b docs/fix-documentation-drift-architecture-cli-748b6c3e6a096c56 main

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

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

Generated by Documentation Freshness Check · 1.4K AIC · ⌖ 19.1 AIC · ⊞ 35K · ◷