docs: clarify allowed-files is an exclusive allowlist, not an additive exception list

docs/src/content/docs/reference/glossary.md

@@ -192,7 +192,7 @@ A security mechanism on `create-pull-request` and `push-to-pull-request-branch`
 
 ### Allowed Files
 
-A strict scope filter for `create-pull-request` and `push-to-pull-request-branch` safe outputs. When `allowed-files:` is set to a list of glob patterns, only files matching those patterns may be modified — any other file is refused. Runs independently from [Protected Files](#protected-files): both checks must pass. To modify a protected file, it must both match `allowed-files` and have `protected-files: allowed`. See [Safe Outputs (Pull Requests)](/gh-aw/reference/safe-outputs-pull-requests/#exempting-specific-files-with-allowed-files).
+An exclusive allowlist for `create-pull-request` and `push-to-pull-request-branch` safe outputs. When `allowed-files:` is set to a list of glob patterns, **only** files matching those patterns may be modified — every other file (including normal source files) is refused. This is a restriction, not an exception: listing `.github/workflows/*` does not additionally allow normal source files; it blocks them. Runs independently from [Protected Files](#protected-files): both checks must pass. To modify a protected file, it must both match `allowed-files` and have `protected-files: allowed`. See [Safe Outputs (Pull Requests)](/gh-aw/reference/safe-outputs-pull-requests/#restricting-changes-to-specific-files-with-allowed-files).
 
 ## Workflow Components
 

docs/src/content/docs/reference/safe-outputs-pull-requests.md

@@ -113,9 +113,18 @@ safe-outputs:
 
 When protected file protection triggers and is set to `blocked`, the 🛡️ **Protected Files** section appears in the agent failure issue or comment generated by the conclusion job. It includes the blocked operation, the specific files found, and a YAML remediation snippet showing how to configure `protected-files: fallback-to-issue`.
 
-### Exempting Specific Files with `allowed-files`
+### Restricting Changes to Specific Files with `allowed-files`
 
-When a workflow is designed to modify only specific files, use `allowed-files` to define a strict allowlist. When set, every file touched by the patch must match at least one pattern — any file outside the list is refused. The `allowed-files` and `protected-files` checks are **orthogonal**: both run independently and both must pass. To modify a protected file, it must both match `allowed-files` **and** `protected-files` must be set to `allowed`.
+Use `allowed-files` to restrict a safe output to a fixed set of files. When set, it acts as an **exclusive allowlist**: every file touched by the patch must match at least one pattern, and any file outside the list is always refused — including normal source files. The `allowed-files` and `protected-files` checks are **orthogonal**: both run independently and both must pass. To modify a protected file, it must both match `allowed-files` **and** `protected-files` must be set to `allowed`.
+
+> [!CAUTION]
+> `allowed-files` is an **exclusive allowlist**, not an "additionally allow" list. Setting `allowed-files: [".github/workflows/*"]` blocks **all other files**, including normal source code like `src/**`. If you want to allow `.github/workflows/*` alongside regular source files, you must list every pattern explicitly:
+> ```yaml
+> allowed-files:
+>   - .github/workflows/*
+>   - src/**
+> ```
+> Files not listed are refused regardless of whether they are normally unprotected.
 
 ```yaml wrap
 safe-outputs:
@@ -140,7 +149,7 @@ Patterns support `*` (any characters except `/`) and `**` (any characters includ
 | `**/package.json` | `package.json` at any path depth |
 
 > [!NOTE]
-> When `allowed-files` is set, it acts as a strict scope filter: only files matching the patterns may be modified, and any file outside the list is always refused. Files that *do* match are still subject to the `protected-files` policy, which runs independently. To modify a protected file, it must both match `allowed-files` **and** `protected-files` must be set to `allowed`. When `allowed-files` is not set, only the `protected-files` policy applies.
+> When `allowed-files` is not set, only the `protected-files` policy applies and all non-protected files are permitted.
 
 > [!WARNING]
 > `allowed-files` should enumerate exactly the files the workflow legitimately manages. Overly broad patterns (e.g., `**`) disable all protection.

pkg/parser/schemas/main_workflow_schema.json

@@ -5316,7 +5316,7 @@
                   "items": {
                     "type": "string"
                   },
-                  "description": "List of glob patterns for files that are exempt from protected-file protection. Acts as a strict allowlist checked independently of the protected-files policy; both checks must pass for a file to be allowed. To modify a protected file, it must both match allowed-files and be permitted by protected-files (e.g. protected-files: allowed). Supports * (any characters except /) and ** (any characters including /)."
+                  "description": "Exclusive allowlist of glob patterns. When set, every file in the patch must match at least one pattern — files outside the list are always refused, including normal source files. This is a restriction, not an exception: setting allowed-files: [\".github/workflows/*\"] blocks all other files. To allow multiple sets of files, list all patterns explicitly. Acts independently of the protected-files policy; both checks must pass. To modify a protected file, it must both match allowed-files and be permitted by protected-files (e.g. protected-files: allowed). Supports * (any characters except /) and ** (any characters including /)."
                 }
               },
               "additionalProperties": false,
@@ -6357,7 +6357,7 @@
                   "items": {
                     "type": "string"
                   },
-                  "description": "List of glob patterns for files that are exempt from protected-file protection. Acts as a strict allowlist checked independently of the protected-files policy; both checks must pass for a file to be allowed. To modify a protected file, it must both match allowed-files and be permitted by protected-files (e.g. protected-files: allowed). Supports * (any characters except /) and ** (any characters including /)."
+                  "description": "Exclusive allowlist of glob patterns. When set, every file in the patch must match at least one pattern — files outside the list are always refused, including normal source files. This is a restriction, not an exception: setting allowed-files: [\".github/workflows/*\"] blocks all other files. To allow multiple sets of files, list all patterns explicitly. Acts independently of the protected-files policy; both checks must pass. To modify a protected file, it must both match allowed-files and be permitted by protected-files (e.g. protected-files: allowed). Supports * (any characters except /) and ** (any characters including /)."
                 }
               },
               "additionalProperties": false