feat(compile): add pool-overrides for per-job pool configuration (#1464)

docs/front-matter.md

@@ -26,6 +26,15 @@ pool:                          # Optional pool configuration
 # pool:                        # 1ES pool format
 #   name: AZS-1ES-L-MMS-ubuntu-22.04
 #   os: linux                  # Operating system: "linux" or "windows". Defaults to "linux".
+# pool:                        # Pool with per-job overrides (see "Per-Job Pool Overrides" below)
+#   name: SpecializedPool
+#   overrides:
+#     detection:
+#       vmImage: ubuntu-22.04
+#     safe-outputs:
+#       vmImage: ubuntu-22.04
+#     conclusion:
+#       vmImage: ubuntu-22.04
 repos:                           # compact repository declarations (replaces repositories: + checkout:)
   - my-org/my-repo               # shorthand: alias="my-repo", type=git, ref=refs/heads/main, checkout=true
   - reponame=my-org/another-repo # shorthand with explicit alias
@@ -271,7 +280,66 @@ local diagnostics. It is **not** a regular safe-output tool. Use
 `create-issue` to file a GitHub issue from debug pipelines; see
 [`ado-aw-debug.md`](ado-aw-debug.md) for the full reference.
 
-## Workspace Defaults
+## Per-Job Pool Overrides (`pool.overrides:`)
+
+By default `pool:` is applied to every generated job — Setup, Agent, Detection,
+SafeOutputs, Teardown, and Conclusion. The optional `pool.overrides:` map lets
+you assign a different pool to individual jobs while keeping the default for the
+rest. It is a sub-key of `pool:`, not a separate top-level key.
+
+```yaml
+pool:
+  name: SpecializedLinuxPool       # default for all jobs
+  overrides:
+    detection:
+      vmImage: ubuntu-22.04        # lightweight Microsoft-hosted image
+    safe-outputs:
+      vmImage: ubuntu-22.04
+    conclusion:
+      vmImage: ubuntu-22.04
+```
+
+### Valid keys
+
+| Key | Generated job |
+|---|---|
+| `setup` | Setup (emitted only when `setup:` steps are declared) |
+| `agent` | Agent |
+| `detection` | Detection |
+| `safe-outputs` | SafeOutputs (and SafeOutputs_Reviewed — see below) |
+| `safe-outputs-reviewed` | SafeOutputs_Reviewed only (overrides the `safe-outputs` inheritance) |
+| `teardown` | Teardown (emitted only when `teardown:` steps are declared) |
+| `conclusion` | Conclusion (emitted only when `safe-outputs:` is configured) |
+
+`safe-outputs-reviewed` inherits the `safe-outputs` override unless it has its
+own entry. `manual-review` is **not** a valid key — the ManualReview job is
+agentless and always runs on `pool: server`.
+
+Unknown keys produce a compiler warning and are ignored (forward-compat).
+
+### Constraints
+
+- Each override value accepts the same **object** pool format as the top-level
+  `pool:` (Microsoft-hosted `vmImage:` or self-hosted `name:`). A bare pool-name
+  string is not accepted here — use `name:`. The same mutual-exclusion rules
+  apply: `name:` and `vmImage:` cannot both be specified; `demands:` requires
+  `name:`.
+- Not supported for `target: 1es` — the 1ES pipeline template controls pool
+  selection. Specifying `pool.overrides:` with `target: 1es` is a compile-time
+  error.
+
+### Trust boundary note
+
+> When a `pool.overrides:` entry points to a different **self-hosted** pool
+> than the default `pool:`, that pool's administrators and agents are trusted
+> with the pipeline artifacts and credentials available to that job. For
+> Detection, SafeOutputs, and Conclusion, this includes the safe-output NDJSON
+> and the write-capable `SC_WRITE_TOKEN`. For `agent` and `setup`, the
+> overridden pool's administrators are trusted with the checked-out source tree
+> and the read-only build token. Using a Microsoft-hosted `vmImage:` override
+> does not change the trust boundary.
+
+
 
 The `workspace:` field controls which directory the agent runs in. When it is
 not set explicitly, the compiler chooses a default based on which repositories

docs/safe-outputs.md

@@ -123,6 +123,15 @@ apply one note to every tool.
 The Detection threat gate always runs first, so a flagged run applies nothing —
 automatic or reviewed.
 
+> **Trust boundary note for `pool.overrides:`:** When `pool.overrides:` is used
+> to move Detection, SafeOutputs, or Conclusion onto a different **self-hosted**
+> pool than the Agent job, that pool's administrators and agents are trusted with
+> the pipeline artifacts and credentials available to those jobs — including the
+> safe-output NDJSON and the write-capable `SC_WRITE_TOKEN`. Using a
+> Microsoft-hosted `vmImage:` override does not change the trust boundary.
+> See [`docs/front-matter.md`](front-matter.md#per-job-pool-overrides-pooloverrides)
+> for the full reference.
+
 ### Safe-outputs summary tab
 
 Every run that proposes safe outputs publishes a human-readable **build summary