docs: fix permissions docs and add missing execution-context field

[github-actions]

Documentation Freshness Audit

This audit found the following inconsistencies between code and documentation:

Findings

Area	Issue	File(s)
Permissions	README claimed compilation fails when permissions.write is omitted — code always defaults executor to $(System.AccessToken)	README.md
Permissions table	Only read and Neither (default) rows showed ❌ for "Safe outputs can write?" — executor always has a write token	README.md
Front matter fields	execution-context field missing from README's Front Matter Fields table	README.md
ado-script reference	Missing exec-context-pr.js from bundled helpers list	README.md

Details

1. Incorrect [!IMPORTANT] block (lines 207–213)

The old README stated: "If you configure any safe output that requires write access ... but omit permissions.write, compilation will fail with a clear error."

This is wrong. src/compile/common.rs (generate_executor_ado_env) always emits SYSTEM_ACCESSTOKEN: $(System.AccessToken) when no write service connection is configured — the executor has a working write-capable token by default. The prompts/create-ado-agentic-workflow.md file already documented this correctly; README was the outlier.

2. Permission Combinations table rows incorrect

The old table showed:

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

Both rows should have ✅ for "Safe outputs can write?" because the executor uses $(System.AccessToken) when no permissions.write ARM SC is configured.

3. execution-context field missing from README Front Matter table

execution_context: Option<ExecutionContextConfig> is defined in src/compile/types.rs and documented in docs/execution-context.md and prompts/create-ado-agentic-workflow.md, but was absent from README's quick-reference table.

4. exec-context-pr.js missing from ado-script reference

The README docs index listed only gate.js, import.js; AGENTS.md correctly lists gate.js, import.js, exec-context-pr.js.

Applied Fixes

• Replace false [!IMPORTANT] block with a [!NOTE] explaining that permissions.write is optional and the default executor token is $(System.AccessToken)
• Fix Permission Combinations table — all rows now correctly show ✅ for "Safe outputs can write?", with clarifying notes on which token is used
• Add execution-context row to the README Front Matter Fields table
• Add exec-context-pr.js to the ado-script docs index reference

---

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

# Create a new branch
git checkout -b docs/fix-permissions-table-and-missing-fields-ad0b6cd9c399051e main

# Apply the patch (--3way handles cross-repo patches)
git am --3way /tmp/agent-27098853392/aw-docs-fix-permissions-table-and-missing-fields.patch

# Push the branch and create the pull request
git push origin docs/fix-permissions-table-and-missing-fields-ad0b6cd9c399051e
gh pr create --title 'docs: fix permissions docs and add missing execution-context field' --base main --head docs/fix-permissions-table-and-missing-fields-ad0b6cd9c399051e --repo githubnext/ado-aw

Generated by Documentation Freshness Check · sonnet46 6.9M · ◷