docs: fix documentation drift — permissions section, 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	[!IMPORTANT] callout falsely claims compilation fails when permissions.write is omitted	README.md
Permissions table	"Only read" and "Neither" rows wrongly show ❌ for safe-output writes	README.md
Front matter fields	execution-context field missing from Front Matter Fields table	README.md
Documentation index	docs/execution-context.md absent from Documentation section	README.md
ado-script reference	exec-context-pr.js missing from bundled scripts list	README.md

Details

Permissions section (critical)
The previous [!IMPORTANT] callout stated: "If you configure any safe output that requires write access ... but omit permissions.write, compilation will fail with a clear error." This was accurate in an older version but was subsequently changed. The compiler now defaults the Stage 3 executor to $(System.AccessToken) when no permissions.write service connection is configured — confirmed in src/compile/common.rs (generate_executor_ado_env()). docs/network.md and prompts/create-ado-agentic-workflow.md (which says "The compiler no longer requires permissions.write") were already correct.

Permission combinations table
The table showed ❌ for safe-output writes in the "Only read" and "Neither" rows, which is wrong. The executor always has a write token — it uses $(SC_WRITE_TOKEN) when permissions.write is set, otherwise $(System.AccessToken). The updated table reflects this and clarifies the token source.

Missing execution-context front-matter field
FrontMatter in src/compile/types.rs defines execution_context: Option<ExecutionContextConfig> (serialised as execution-context). This field is documented in docs/front-matter.md and docs/execution-context.md but was absent from the README's Front Matter Fields table.

Missing docs/execution-context.md in docs index
The Documentation section listed all other per-concept docs but omitted docs/execution-context.md, which covers the PR diff staging and aw-context/ artefacts feature.

Missing exec-context-pr.js in ado-script reference
The ado-script documentation entry listed only gate.js and import.js; exec-context-pr.js (the PR-context precompute bundle under scripts/ado-script/src/exec-context-pr/) was missing.

Applied Fixes

• Replace incorrect [!IMPORTANT] callout with accurate [!NOTE] explaining permissions.write is optional and the executor defaults to $(System.AccessToken)
• Fix Permission Combinations table: "Only read" and "Neither" now correctly show ✅ for safe-output writes with the token source noted
• Add execution-context row to Front Matter Fields table with link to docs/execution-context.md
• Add docs/execution-context.md entry to the Documentation index
• Add exec-context-pr.js to the ado-script bundled scripts list

---

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

# Create a new branch
git checkout -b docs/fix-documentation-drift-f47735f09bfa9ffc main

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

# Push the branch and create the pull request
git push origin docs/fix-documentation-drift-f47735f09bfa9ffc
gh pr create --title 'docs: fix documentation drift — permissions section, missing execution-context field' --base main --head docs/fix-documentation-drift-f47735f09bfa9ffc --repo githubnext/ado-aw

Generated by Documentation Freshness Check · sonnet46 8.9M · ◷