From c951007e9e1dfa1f69cfce226b5ba5bd8353d6d3 Mon Sep 17 00:00:00 2001
From: "github-actions[bot]"
 <41898282+github-actions[bot]@users.noreply.github.com>
Date: Fri, 18 Sep 2026 01:10:32 +0000
Subject: [PATCH] docs: document reserved dependsOn/condition parameter names
 for target job/stage

Front matter parameters named dependsOn or condition on target: job or
target: stage collide with the compiler's auto-injected template
parameters and fail compilation, but this was undocumented in both
docs/targets.md and docs/parameters.md. Add the compile-time error
behavior to both pages, cross-linked.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 docs/parameters.md | 9 +++++++++
 docs/targets.md    | 6 ++++++
 2 files changed, 15 insertions(+)

diff --git a/docs/parameters.md b/docs/parameters.md
index 49d86b769..a72d1aac9 100644
--- a/docs/parameters.md
+++ b/docs/parameters.md
@@ -43,3 +43,12 @@ When `tools.cache-memory` is configured, the compiler automatically injects a `c
 - Creates an empty memory directory so the agent starts fresh
 
 If you define your own `clearMemory` parameter in the front matter, the auto-injected one is suppressed — your definition takes precedence.
+
+### Reserved names on `target: job` / `target: stage`
+
+On these two targets the compiler auto-injects its own `dependsOn` and
+`condition` template parameters (see [`docs/targets.md`](targets.md)) so
+callers can wire in external ordering at the `template:` invocation site.
+Declaring a front-matter `parameters:` entry named `dependsOn` or `condition`
+on `target: job` or `target: stage` is therefore a **compile-time error** —
+rename the parameter or switch targets.
diff --git a/docs/targets.md b/docs/targets.md
index 2af8c7169..e65995d63 100644
--- a/docs/targets.md
+++ b/docs/targets.md
@@ -97,6 +97,9 @@ stages:
 - The `condition` parameter is ANDed into the agent job's existing internal
   condition (PR gate, pipeline gate, etc.). Empty default preserves ADO's
   native `succeeded()` behaviour.
+- `dependsOn` and `condition` are reserved parameter names on `target: job`.
+  Declaring a front-matter `parameters:` entry with either name is a
+  **compile-time error** — rename the parameter or drop `target: job`.
 - Triggers (`on:`) are ignored with a warning (the parent pipeline controls triggers).
 - If the agent declares additional repositories via `repos:`, add them to the
   parent pipeline's `resources:` block (documented in the generated file header).
@@ -136,6 +139,9 @@ stages:
   behaviour.
 - The `dependsOn` parameter is typed `object`, matching ADO's native
   `dependsOn:` semantics (accepts a single string or a list).
+- `dependsOn` and `condition` are reserved parameter names on `target: stage`,
+  same as `target: job` — a front-matter `parameters:` entry with either name
+  is a **compile-time error**.
 - Same 3-job chain, job-name prefixing, and pool handling as `target: job`.
 - Triggers (`on:`) are ignored with a warning.
 - If the agent declares additional repositories via `repos:`, add them to the