docs: fix documentation drift — architecture tree, engine version, MCP env scope, schedule aliases, create-pr labels

[github-actions]

Documentation Freshness Audit

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

Findings

Area	Issue	File(s)
Architecture tree	Duplicate ir/ directory block — listed twice under compile/, first copy missing summary.rs	AGENTS.md
Engine version	Example version "1.0.48" stale; current COPILOT_CLI_VERSION is "1.0.62"	docs/engine.md
Safe outputs	create-pull-request labels field is a runtime agent parameter but was missing from the "Agent parameters" section	docs/safe-outputs.md
MCP config	env: incorrectly listed under "Common (both types)"; it is silently ignored for HTTP MCPs (common.rs emits only a stderr warning)	docs/mcp.md
Front matter	ado-aw-debug: field has no mention in front-matter.md — users reading the primary format reference had no path to docs/ado-aw-debug.md	docs/front-matter.md
Schedule syntax	biweekly/triweekly (no-hyphen aliases), weekday abbreviations (sun, mon, tue/tues, etc.), and bare utc offset all accepted by parser but not documented	docs/schedule-syntax.md
Authoring prompt	Bare weekly schedule (any day, scattered time) missing from the frequency table	prompts/create-ado-agentic-workflow.md

Details

AGENTS.md — duplicate ir/ block: Lines 54–66 contained an older, incomplete copy of the src/compile/ir/ subtree (missing summary.rs, slightly different descriptions). The correct and complete copy at lines 105–117 (which includes summary.rs) was kept; the duplicate was removed.

docs/engine.md — stale version example: The version field row used "1.0.48" as an example, but COPILOT_CLI_VERSION in src/engine.rs is "1.0.62". Updated to match.

docs/safe-outputs.md — missing labels agent parameter: CreatePrParams in src/safeoutputs/create_pull_request.rs has a labels: Vec<String> field that agents can pass at call time (subject to allowed-labels config), but docs only listed it as a front-matter configuration option, not an agent-callable parameter. Added to the "Agent parameters" section.

docs/mcp.md — env: scope: env: was listed under "Common (both types)" but src/compile/common.rs explicitly ignores it for HTTP MCPs (emitting only a stderr warning). Moved env: to a "Container stdio servers only" note with a pointer to use headers: for HTTP authentication.

docs/front-matter.md — ado-aw-debug: cross-reference: The ado_aw_debug field in FrontMatter had no mention anywhere in front-matter.md. Added a commented example in the YAML block and a prose section explaining the two sub-keys (skip-integrity, create-issue) with a link to docs/ado-aw-debug.md.

docs/schedule-syntax.md — undocumented aliases: The parser (src/fuzzy_schedule.rs) accepts biweekly/triweekly (no-hyphen), short weekday names (sun, mon, tue/tues, wed, thu/thurs, fri, sat), short unit forms (every 2d, every 2w), and bare utc offset. Added all of these to the reference.

prompts/create-ado-agentic-workflow.md — bare weekly missing: The frequency table skipped the bare weekly pattern (any day, scattered time), which is both supported in the code and documented in docs/schedule-syntax.md. Added to table.

Applied Fixes

• Remove duplicate ir/ subtree from AGENTS.md architecture section
• Update stale "1.0.48" version example to "1.0.62" in docs/engine.md
• Add labels runtime parameter to create-pull-request agent parameters in docs/safe-outputs.md
• Clarify env: is container-only (not HTTP) in docs/mcp.md
• Add ado-aw-debug: comment + prose section with link in docs/front-matter.md
• Add biweekly/triweekly aliases, weekday abbreviations, short unit forms, and bare utc to docs/schedule-syntax.md
• Add bare weekly row to frequency table in prompts/create-ado-agentic-workflow.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

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

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

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

# Push the branch and create the pull request
git push origin docs/fix-documentation-drift-june-2026-bb752751a90ade8d
gh pr create --title 'docs: fix documentation drift — architecture tree, engine version, MCP env scope, schedule aliases, create-pr labels' --base main --head docs/fix-documentation-drift-june-2026-bb752751a90ade8d --repo githubnext/ado-aw

Generated by Documentation Freshness Check · 2.2K AIC · ⌖ 33 AIC · ⊞ 34.7K · ◷