docs: fix documentation drift — missing files, commands, and planned labels

[github-actions]

Documentation Freshness Audit

This audit found the following inconsistencies between code and documentation:

Findings

Area	Issue	File(s)
Architecture tree	exec_context/ directory lists only 3 files but has 9 — 7 contributor files missing	AGENTS.md
Architecture tree	inspect/ directory lists 3 files and marks trace, whatif, lint, catalog as "(planned)" — all 6 missing files are now implemented	AGENTS.md
Architecture tree	compile/source_path_guard.rs not listed	AGENTS.md
Architecture tree	audit/pipeline_graph.rs not listed	AGENTS.md
Architecture tree	mcp_author/ module (mod.rs + tests.rs) absent entirely	AGENTS.md
CLI commands	lint command undocumented	docs/cli.md
CLI commands	catalog command undocumented	docs/cli.md

Details

exec_context/ contributors (7 new files): ci_push.rs, manual.rs, pipeline.rs, pr_checks.rs, repo.rs, schedule.rs, workitem.rs — these implement the contributor fan-out described in docs/execution-context.md but were never added to the architecture tree.

inspect/ (6 new files + stale "(planned)" label): graph_deps.rs, graph_outputs.rs, whatif.rs, trace.rs, lint.rs, catalog.rs — were marked as planned in the architecture comment but are fully implemented. Also removed the stale "(planned)" label.

compile/source_path_guard.rs: Security guard for caller-supplied workflow source paths (used by audit::pipeline_graph and mcp_author). Already referenced by module-level doc comments in both call sites but missing from the tree.

audit/pipeline_graph.rs: Populates the pipeline_graph section of AuditData by correlating IR graph facts with the runtime build. Not listed in the audit directory tree.

mcp_author/: Author-facing MCP server exposing read-only IR inspection tools over stdio for IDE/Copilot Chat. Referenced in the docs index but absent from the architecture tree.

lint and catalog CLI commands: Both are real, documented entry points in src/main.rs that were not reflected in docs/cli.md.

Applied Fixes

• AGENTS.md: add 7 new exec_context/ contributor files to architecture tree
• AGENTS.md: add compile/source_path_guard.rs to architecture tree
• AGENTS.md: add audit/pipeline_graph.rs to architecture tree
• AGENTS.md: add mcp_author/ module (mod.rs + tests.rs) to architecture tree
• AGENTS.md: add 6 now-implemented inspect/ files and remove stale "(planned)" label
• docs/cli.md: document the lint command with its flags
• docs/cli.md: document the catalog command with its flags

---

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

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

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

# Push the branch and create the pull request
git push origin docs/fix-documentation-drift-2026-06-e1424d5b14c17f48
gh pr create --title 'docs: fix documentation drift — missing files, commands, and planned labels' --base main --head docs/fix-documentation-drift-2026-06-e1424d5b14c17f48 --repo githubnext/ado-aw

Generated by Documentation Freshness Check · 772.6 AIC · ⌖ 19.9 AIC · ⊞ 35.7K · ◷