📝 Documentation drift detected — permissions validation lists incomplete set of write-requiring safe outputs

[github-actions]

Documentation Freshness Audit

The weekly documentation audit found the following inconsistency between code and documentation:

Findings

Area	Issue	File(s)
Permissions — Compile-Time Validation	Docs only mention 2 write-requiring safe outputs, but code enforces 5	src/compile/common.rs, AGENTS.md / copilot instructions

Details

In the Permissions section, the compile-time validation note reads:

If write-requiring safe-outputs (create-pull-request, create-work-item) are configured but permissions.write is missing, compilation fails with a clear error message.

However, WRITE_REQUIRING_SAFE_OUTPUTS in src/compile/common.rs contains five entries:

const WRITE_REQUIRING_SAFE_OUTPUTS: &[&str] = &[
    "create-pull-request",
    "create-work-item",
    "update-work-item",
    "create-wiki-page",
    "update-wiki-page",
];

update-work-item, create-wiki-page, and update-wiki-page are all omitted from the documentation of which safe outputs trigger the missing-permissions.write compile error. This is a genuine user-facing inaccuracy: a user who adds update-work-item, create-wiki-page, or update-wiki-page to their safe-outputs without a permissions.write service connection will receive a compilation error that the documentation gives no indication of.

Suggested Fixes

• Update the "Compile-Time Validation" paragraph in the Permissions section to list all five write-requiring safe outputs:

  If write-requiring safe-outputs (create-pull-request, create-work-item, update-work-item, create-wiki-page, update-wiki-page) are configured but permissions.write is missing, compilation fails with a clear error message.

• Optionally add a note to each of the update-work-item, create-wiki-page, and update-wiki-page tool documentation sections that permissions.write is required when these tools are configured.

---

This issue was created by the automated documentation freshness check.

Generated by Documentation Freshness Check · ◷