docs: fix documentation drift — permissions.write incorrectly documented as required

[github-actions]

Documentation Freshness Audit

This audit found the following inconsistencies between code and documentation:

Findings

Area	Issue	File(s)
Permissions	README incorrectly states compilation fails if permissions.write is omitted for write safe outputs	README.md
Permission table	README Permission Combinations table shows safe outputs can write: ❌ for Only read and Neither (default) rows — both are wrong; the executor always has $(System.AccessToken)	README.md
Front Matter Fields	execution-context: field missing from the Front Matter Fields reference table	README.md

Details

1. Wrong IMPORTANT warning about permissions.write

Lines 207–213 contained an [!IMPORTANT] callout claiming:

If you configure any safe output that requires write access... but omit permissions.write, compilation will fail with a clear error.

This is factually wrong. The code in src/compile/standalone.rs has no such check. The executor's Stage 3 job always has a write-capable token via $(System.AccessToken) (the pipeline's built-in OAuth token). permissions.write is an optional override for when you need cross-org writes or named-identity attribution. This behavior is correctly documented in docs/safe-outputs.md, docs/network.md, and prompts/create-ado-agentic-workflow.md, but contradicted in the README.

2. Wrong Permission Combinations table

The original table:

| Only `read`        | ✅ | ❌ |
| Neither (default)  | ❌ | ❌ |

Both rows should show ✅ for "Safe outputs can write?" because $(System.AccessToken) is always available to the Stage 3 executor. The updated table clarifies which token is used per row.

3. Missing execution-context: field in Front Matter Fields table

The execution-context: field exists in the FrontMatter struct (src/compile/types.rs, line 727–728), has its own documentation page (docs/execution-context.md), and is referenced in AGENTS.md, but was absent from the README's Front Matter Fields reference table.

Applied Fixes

• Replaced the false [!IMPORTANT] compilation-failure warning with a [!NOTE] clarifying permissions.write is optional and explaining when to use it
• Corrected the Permission Combinations table — all rows show ✅ for safe output write capability, with annotations showing which token is used
• Added execution-context: row to the Front Matter Fields table with a link to docs/execution-context.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

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

# Create a new branch
git checkout -b docs/fix-documentation-drift-permissions-fields-e121c98e02f368a6 main

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

# Push the branch and create the pull request
git push origin docs/fix-documentation-drift-permissions-fields-e121c98e02f368a6
gh pr create --title 'docs: fix documentation drift — permissions.write incorrectly documented as required' --base main --head docs/fix-documentation-drift-permissions-fields-e121c98e02f368a6 --repo githubnext/ado-aw

Generated by Documentation Freshness Check · sonnet46 7.1M · ◷