From 1b6b05abcbff92a5add62735d9466a28e122b5fe Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Thu, 28 May 2026 19:23:42 +0000
Subject: [PATCH 1/3] Initial plan


From 6c5cdc8dab5ca15881ce4120cba79a5cbcc73387 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Thu, 28 May 2026 21:25:18 +0000
Subject: [PATCH 2/3] feat: support SPECKIT_WORKFLOW_RUN_ID override

---
 src/specify_cli/workflows/engine.py |  9 ++++++-
 tests/test_workflows.py             | 42 +++++++++++++++++++++++++++++
 2 files changed, 50 insertions(+), 1 deletion(-)

diff --git a/src/specify_cli/workflows/engine.py b/src/specify_cli/workflows/engine.py
index 65d9b3a272..0991122ddb 100644
--- a/src/specify_cli/workflows/engine.py
+++ b/src/specify_cli/workflows/engine.py
@@ -11,6 +11,7 @@
 from __future__ import annotations
 
 import json
+import os
 import re
 import uuid
 from datetime import datetime, timezone
@@ -433,8 +434,14 @@ def execute(
         """
         from . import STEP_REGISTRY
 
+        effective_run_id = run_id
+        if effective_run_id is None:
+            env_run_id = os.environ.get("SPECKIT_WORKFLOW_RUN_ID", "").strip()
+            if env_run_id:
+                effective_run_id = env_run_id
+
         state = RunState(
-            run_id=run_id,
+            run_id=effective_run_id,
             workflow_id=definition.id,
             project_root=self.project_root,
         )
diff --git a/tests/test_workflows.py b/tests/test_workflows.py
index 114e6b02cd..b0be905a71 100644
--- a/tests/test_workflows.py
+++ b/tests/test_workflows.py
@@ -2332,6 +2332,48 @@ def test_workflow_without_context_reference_unchanged(self, project_dir):
         assert state.status == RunStatus.COMPLETED
         assert state.step_results["only-step"]["output"]["stdout"].strip() == "hello"
 
+    def test_run_id_uses_speckit_workflow_run_id_env_override(self, project_dir, monkeypatch):
+        """When no run_id argument is provided, SPECKIT_WORKFLOW_RUN_ID overrides UUID generation."""
+        from specify_cli.workflows.engine import WorkflowDefinition, WorkflowEngine
+
+        monkeypatch.setenv("SPECKIT_WORKFLOW_RUN_ID", "env-run-123")
+        definition = WorkflowDefinition.from_string("""
+schema_version: "1.0"
+workflow:
+  id: "env-run-id"
+  name: "Env Run Id"
+  version: "1.0.0"
+steps:
+  - id: stamp
+    type: shell
+    run: "echo {{ context.run_id }}"
+""")
+        state = WorkflowEngine(project_dir).execute(definition)
+
+        assert state.run_id == "env-run-123"
+        assert state.step_results["stamp"]["output"]["stdout"].strip() == "env-run-123"
+
+    def test_run_id_arg_takes_precedence_over_env_override(self, project_dir, monkeypatch):
+        """Explicit run_id keeps existing precedence over SPECKIT_WORKFLOW_RUN_ID."""
+        from specify_cli.workflows.engine import WorkflowDefinition, WorkflowEngine
+
+        monkeypatch.setenv("SPECKIT_WORKFLOW_RUN_ID", "env-run-123")
+        definition = WorkflowDefinition.from_string("""
+schema_version: "1.0"
+workflow:
+  id: "explicit-run-id"
+  name: "Explicit Run Id"
+  version: "1.0.0"
+steps:
+  - id: stamp
+    type: shell
+    run: "echo {{ context.run_id }}"
+""")
+        state = WorkflowEngine(project_dir).execute(definition, run_id="explicit-456")
+
+        assert state.run_id == "explicit-456"
+        assert state.step_results["stamp"]["output"]["stdout"].strip() == "explicit-456"
+
 
 # ===== State Persistence Tests =====
 

From 71422b0db3b8f5bef43102db27bde4877d39941c Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Fri, 29 May 2026 14:33:22 +0000
Subject: [PATCH 3/3] docs: clarify run_id env var precedence wording

---
 src/specify_cli/workflows/engine.py | 2 +-
 tests/test_workflows.py             | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/specify_cli/workflows/engine.py b/src/specify_cli/workflows/engine.py
index 0991122ddb..2f68fab244 100644
--- a/src/specify_cli/workflows/engine.py
+++ b/src/specify_cli/workflows/engine.py
@@ -426,7 +426,7 @@ def execute(
         inputs:
             User-provided input values.
         run_id:
-            Optional run ID (auto-generated if not provided).
+            Optional run ID (uses SPECKIT_WORKFLOW_RUN_ID when set, otherwise auto-generated).
 
         Returns
         -------
diff --git a/tests/test_workflows.py b/tests/test_workflows.py
index b0be905a71..7995512d6f 100644
--- a/tests/test_workflows.py
+++ b/tests/test_workflows.py
@@ -2333,7 +2333,7 @@ def test_workflow_without_context_reference_unchanged(self, project_dir):
         assert state.step_results["only-step"]["output"]["stdout"].strip() == "hello"
 
     def test_run_id_uses_speckit_workflow_run_id_env_override(self, project_dir, monkeypatch):
-        """When no run_id argument is provided, SPECKIT_WORKFLOW_RUN_ID overrides UUID generation."""
+        """When no run_id argument is provided, SPECKIT_WORKFLOW_RUN_ID overrides the auto-generated run ID."""
         from specify_cli.workflows.engine import WorkflowDefinition, WorkflowEngine
 
         monkeypatch.setenv("SPECKIT_WORKFLOW_RUN_ID", "env-run-123")