From 1ffaefc71553b8258b8730d3b236561bef754fbd Mon Sep 17 00:00:00 2001
From: wyongzhi <276409147+wyongzhi@users.noreply.github.com>
Date: Thu, 10 Sep 2026 16:25:56 -0700
Subject: [PATCH] docs: clarify stepEnvironment name scope; add cross-step
 same-name fixture

Section 3 lists what stepEnvironment names must not collide with (the
same list, and jobEnvironments) but never states that different steps
may reuse a name. One implementation read the omission as a fourth rule
and rejected such templates (openjd-rs #380). Add a note under the
constraints and name the two scopes in section 4. No rule changes.

Add 4--same-step-env-name-across-steps.yaml so the conformance suite
exercises the allowed case; it fails on the over-strict implementation
and passes once fixed.

Signed-off-by: wyongzhi <276409147+wyongzhi@users.noreply.github.com>
---
 .../4--same-step-env-name-across-steps.yaml   | 31 +++++++++++++++++++
 wiki/2023-09-Template-Schemas.md              |  6 +++-
 2 files changed, 36 insertions(+), 1 deletion(-)
 create mode 100644 conformance-tests/2023-09/base/job_templates/4--same-step-env-name-across-steps.yaml

diff --git a/conformance-tests/2023-09/base/job_templates/4--same-step-env-name-across-steps.yaml b/conformance-tests/2023-09/base/job_templates/4--same-step-env-name-across-steps.yaml
new file mode 100644
index 00000000..d5c41216
--- /dev/null
+++ b/conformance-tests/2023-09/base/job_templates/4--same-step-env-name-across-steps.yaml
@@ -0,0 +1,31 @@
+specificationVersion: jobtemplate-2023-09
+name: TestJob
+jobEnvironments:
+- name: JobEnv
+  variables:
+    JOB_VAR: value
+steps:
+- name: Step1
+  stepEnvironments:
+  - name: StepEnv
+    variables:
+      VAR1: value1
+  script:
+    actions:
+      onRun:
+        command: python
+        args:
+        - "-c"
+        - "print()"
+- name: Step2
+  stepEnvironments:
+  - name: StepEnv
+    variables:
+      VAR1: value2
+  script:
+    actions:
+      onRun:
+        command: python
+        args:
+        - "-c"
+        - "print()"
diff --git a/wiki/2023-09-Template-Schemas.md b/wiki/2023-09-Template-Schemas.md
index 2cd3441d..8a66eda2 100644
--- a/wiki/2023-09-Template-Schemas.md
+++ b/wiki/2023-09-Template-Schemas.md
@@ -872,6 +872,9 @@ Where:
         1. No two Environments in this list may have the same value for the `name` property.
         2. The Environments defined in this list must not have the same `name` as a Job Environment defined in the same
            Job Template.
+    * Note: The scope of a Step Environment's `name` is the Step that defines it. Different Steps may each define a
+      Step Environment with the same `name`; a Session only ever contains the Step Environments of a single Step, so
+      these names never collide.
 6. *hostRequirements* — Describes the requirements on Worker host's capabilities that must be satisfied for the Task(s) of
    the Step to be scheduled to the host. See: [&lt;HostRequirements&gt;](#33-hostrequirements).
 7. *parameterSpace* — Defines the parameterization of the Step's action; the available parameters, the values that they
@@ -1494,7 +1497,8 @@ variables: <EnvironmentVariables> # @optional
 
 Where:
 
-1. *name* — An identifier given to the environment that is unique within the Environment's defined scope.
+1. *name* — An identifier given to the environment that is unique within the Environment's defined scope: the Job
+   Template for a Job Environment, and the Step Template for a Step Environment.
 2. *description* — A description to apply to the environment. It has no functional purpose, but may appear in UI elements.
    See: [&lt;Description&gt;](#72-description).
 3. *script* — The action that is taken by this Environment when it is run on a Worker host.