From 3967778ea9836f29387d2ab7b23f726c8f933b03 Mon Sep 17 00:00:00 2001
From: Manfred Riem <15701806+mnriem@users.noreply.github.com>
Date: Fri, 9 Oct 2026 07:03:50 -0500
Subject: [PATCH 01/10] Add built-in GitHub workflow step

Assisted-by: GitHub Copilot (model: GPT-6 Sol, autonomous)
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: ec94c538-a8b2-4c39-81fc-3ba5f0a59ce6
---
 docs/reference/workflows.md                   |  55 +++
 src/specify_cli/workflows/__init__.py         |   2 +
 .../workflows/step/github/__init__.py         | 353 ++++++++++++++++++
 tests/test_workflows.py                       |   4 +-
 tests/workflows/test_github_step.py           | 294 +++++++++++++++
 workflows/ARCHITECTURE.md                     |   3 +-
 6 files changed, 708 insertions(+), 3 deletions(-)
 create mode 100644 src/specify_cli/workflows/step/github/__init__.py
 create mode 100644 tests/workflows/test_github_step.py

diff --git a/docs/reference/workflows.md b/docs/reference/workflows.md
index b99fbea42c..0dadd45a0e 100644
--- a/docs/reference/workflows.md
+++ b/docs/reference/workflows.md
@@ -570,6 +570,7 @@ specify workflow run speckit -i spec="Build a kanban board with drag-and-drop ta
 | `command`    | Invoke a Spec Kit command (e.g., `speckit.plan`) |
 | `prompt`     | Send an arbitrary prompt to the AI coding agent  |
 | `shell`      | Execute a shell command and capture output       |
+| `github`     | Post/retrieve GitHub comments or check out a PR   |
 | `init`       | Bootstrap a project (like `specify init`)        |
 | `slot`       | Named workflow slot; skipped when unfilled       |
 | `gate`       | Pause for human approval before continuing       |
@@ -582,6 +583,60 @@ specify workflow run speckit -i spec="Build a kanban board with drag-and-drop ta
 
 > **Security note:** a `shell` step runs a local command with **your** privileges. There is no capability sandbox — `requires` is an advisory pre-condition block (spec-kit version, integrations), not a runtime gate, so it does **not** restrict what a step can do. In particular there is no `requires.permissions` capability gate: it is rejected by validation precisely because it would imply a sandbox that does not exist. Review any catalog or downloaded workflow before running it, and use a `gate` step to require explicit approval before sensitive or destructive shell commands.
 
+### GitHub step
+
+`type: github` uses the installed `gh` CLI and its active authentication for a
+repository whose `origin` points to `github.com`. The token needs read access
+for PRs/issues, and issue-comment write access only for `comment`. The step
+does not request or elevate permissions. It does not interpret issue/comment
+contents as workflow instructions or apply labels. GitHub operations require
+network access; tests should mock the API rather than post live comments.
+
+```yaml
+- id: publish-plan
+  type: github
+  operation: comment
+  target: issue
+  number: "{{ inputs.issue_number }}"
+  body_file: docs/plan.md
+  artifact: reviewed-plan
+  maintainer_action:
+    summary: "Review the plan before scheduling implementation."
+    possible_labels: [ready-for-review]
+
+- id: retrieve-plan
+  type: github
+  operation: fetch-artifact
+  target: issue
+  number: "{{ inputs.issue_number }}"
+  artifact: reviewed-plan
+  write_to: docs/retrieved-plan.md
+
+- id: checkout
+  type: github
+  operation: checkout-pr
+  number: "{{ inputs.pr_number }}"
+```
+
+For `comment`, supply exactly one of `body` (text), `body_file` (UTF-8 file),
+or `body_files` (non-empty list of UTF-8 files joined with two newlines).
+`target` is `issue` or `pull_request`; `number` must resolve to a positive
+integer. `artifact` is an optional stable alphanumeric identifier (hyphens
+and underscores allowed), required by `fetch-artifact`. `maintainer_action`
+adds a **proposal only** section with `summary` and `possible_labels` to the
+comment; it never changes GitHub labels. The posted comment includes a
+digest-bearing marker tying it to the workflow run and step. Re-running the
+same step in the same run reuses an identical comment rather than posting a
+duplicate; changed content or a changed author fails instead. `fetch-artifact`
+requires exactly one intact, previously marked comment authored by the active
+GitHub account. It writes only to a *new* relative file under the project
+root, with an existing directory; symlinks and overwrites are refused.
+`checkout-pr` fetches GitHub's `pull/<number>/head` ref, verifies its SHA
+matches the API's PR head, and checks out that commit detached. Local changes
+that prevent checkout cause the step to fail.
+GitHub steps cannot be nested in `fan-out`: an item has no distinct run/step
+identity for safe comment retries.
+
 ### Custom step packages
 
 Custom step types are installed with `specify workflow step`. A step is a
diff --git a/src/specify_cli/workflows/__init__.py b/src/specify_cli/workflows/__init__.py
index baa3b8fa09..18e40a098f 100644
--- a/src/specify_cli/workflows/__init__.py
+++ b/src/specify_cli/workflows/__init__.py
@@ -49,6 +49,7 @@ def _register_builtin_steps() -> None:
     from .step.fan_in import FanInStep
     from .step.fan_out import FanOutStep
     from .step.gate import GateStep
+    from .step.github import GitHubStep
     from .step.if_then import IfThenStep
     from .step.init import InitStep
     from .step.prompt import PromptStep
@@ -62,6 +63,7 @@ def _register_builtin_steps() -> None:
     _register_step(FanInStep())
     _register_step(FanOutStep())
     _register_step(GateStep())
+    _register_step(GitHubStep())
     _register_step(IfThenStep())
     _register_step(InitStep())
     _register_step(PromptStep())
diff --git a/src/specify_cli/workflows/step/github/__init__.py b/src/specify_cli/workflows/step/github/__init__.py
new file mode 100644
index 0000000000..b02015c700
--- /dev/null
+++ b/src/specify_cli/workflows/step/github/__init__.py
@@ -0,0 +1,353 @@
+"""GitHub workflow step: post comments, retrieve posted artifacts, or check out a PR."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+import subprocess
+from pathlib import Path
+from typing import Any
+
+from specify_cli.workflows.base import StepBase, StepContext, StepResult, StepStatus
+from specify_cli.workflows.expressions import evaluate_expression
+
+_IDENTIFIER = re.compile(r"[A-Za-z0-9][A-Za-z0-9_-]{0,99}\Z")
+_NUMBER = re.compile(r"[1-9][0-9]*\Z")
+_ORIGIN = re.compile(
+    r"(?:https://github\.com/|git@github\.com:)([A-Za-z0-9_.-]+)/([A-Za-z0-9_.-]+?)(?:\.git)?/?\Z"
+)
+_MARKER = re.compile(
+    r"<!-- speckit-github:v1 artifact=([A-Za-z0-9_-]+) "
+    r"run=([A-Za-z0-9_-]+) step=([A-Za-z0-9_-]+) "
+    r"sha256=([a-f0-9]{64}) -->\Z"
+)
+_MARKER_PREFIX = "<!-- speckit-github:"
+
+
+def _run(args: list[str], root: Path, *, input_text: str | None = None) -> str:
+    try:
+        result = subprocess.run(
+            args, cwd=root, input=input_text, capture_output=True, text=True,
+            timeout=60, check=False,
+        )
+    except (OSError, subprocess.TimeoutExpired) as exc:
+        raise ValueError(f"{args[0]} request failed: {exc}") from exc
+    if result.returncode:
+        # Do not echo CLI stderr: authentication errors can contain sensitive data.
+        raise ValueError(
+            f"{args[0]} request failed (exit code {result.returncode}): "
+            f"{' '.join(args[1:3])}"
+        )
+    return result.stdout.strip()
+
+
+def _api(root: Path, endpoint: str, *, method: str = "GET", data: dict[str, str] | None = None,
+         paginated: bool = False) -> Any:
+    args = ["gh", "api", "--method", method, endpoint]
+    if paginated:
+        args.extend(["--paginate", "--slurp"])
+    if data is not None:
+        args.extend(["--input", "-"])
+    raw = _run(args, root, input_text=json.dumps(data) if data is not None else None)
+    try:
+        return json.loads(raw)
+    except json.JSONDecodeError as exc:
+        raise ValueError(f"GitHub returned invalid JSON for {endpoint}") from exc
+
+
+def _project_path(root: Path, value: str, *, writing: bool) -> Path:
+    path = Path(value)
+    if (not value or path.is_absolute() or "\\" in value
+            or any(part in ("..", ".") for part in value.split("/"))):
+        raise ValueError(f"Path must be relative and inside the project: {value!r}")
+    candidate = root / path
+    if candidate == root:
+        raise ValueError("Path must name a file inside the project")
+    current = root
+    for part in path.parts:
+        current = current / part
+        if current.is_symlink():
+            raise ValueError(f"Symlinked paths are not allowed: {value!r}")
+    if not candidate.resolve().is_relative_to(root.resolve()):
+        raise ValueError(f"Path escapes the project: {value!r}")
+    if writing:
+        if candidate.exists():
+            raise ValueError(f"Destination already exists: {value!r}")
+        if not candidate.parent.is_dir():
+            raise ValueError(f"Destination directory does not exist: {value!r}")
+    elif not candidate.is_file():
+        raise ValueError(f"File does not exist: {value!r}")
+    return candidate
+
+
+def _resolved(value: Any, context: StepContext) -> Any:
+    if isinstance(value, str) and "{{" in value:
+        return evaluate_expression(value, context)
+    return value
+
+
+def _string(value: Any, name: str) -> str:
+    if not isinstance(value, str) or not value.strip():
+        raise ValueError(f"'{name}' must be a non-empty string")
+    return value
+
+
+def _number(value: Any) -> int:
+    if isinstance(value, bool) or not (
+        (isinstance(value, int) and value > 0)
+        or (isinstance(value, str) and _NUMBER.fullmatch(value))
+    ):
+        raise ValueError("'number' must be a positive integer")
+    return int(value)
+
+
+def _identity(root: Path) -> tuple[str, str]:
+    origin = _run(["git", "remote", "get-url", "origin"], root)
+    match = _ORIGIN.fullmatch(origin)
+    if not match:
+        raise ValueError("GitHub step requires a github.com origin remote")
+    repo = f"{match[1]}/{match[2]}"
+    # Use absolute API endpoints; a GH_HOST override must not redirect requests
+    # to an unexpected host. gh manages authentication without exposing a token.
+    return repo, f"https://api.github.com/repos/{repo}"
+
+
+def _comments(root: Path, url: str) -> list[dict[str, Any]]:
+    pages = _api(root, f"{url}/comments?per_page=100", paginated=True)
+    if not isinstance(pages, list) or not all(isinstance(page, list) for page in pages):
+        raise ValueError("GitHub returned an invalid comment list")
+    comments = [comment for page in pages for comment in page]
+    if not all(isinstance(comment, dict) for comment in comments):
+        raise ValueError("GitHub returned an invalid comment")
+    return comments
+
+
+def _marked(comment: dict[str, Any]) -> tuple[str, str, str, str, str] | None:
+    text = comment.get("body")
+    if not isinstance(text, str) or _MARKER_PREFIX not in text:
+        return None
+    body, sep, marker = text.rpartition("\n\n")
+    match = _MARKER.fullmatch(marker) if sep else None
+    if not match or hashlib.sha256(body.encode("utf-8")).hexdigest() != match[4]:
+        raise ValueError("GitHub artifact has an invalid marker or content digest")
+    return body, match[1], match[2], match[3], match[4]
+
+
+def _author(comment: dict[str, Any]) -> str | None:
+    user = comment.get("user")
+    return user.get("login") if isinstance(user, dict) else None
+
+
+class GitHubStep(StepBase):
+    """Run bounded GitHub operations through an authenticated gh CLI."""
+
+    type_key = "github"
+
+    def validate(self, config: dict[str, Any]) -> list[str]:
+        errors = super().validate(config)
+        operation = config.get("operation")
+        if operation not in ("comment", "fetch-artifact", "checkout-pr"):
+            errors.append(
+                "GitHub step 'operation' must be comment, fetch-artifact, or checkout-pr."
+            )
+            return errors
+        expected = {
+            "comment": {"id", "type", "operation", "target", "number", "body", "body_file",
+                        "body_files", "artifact", "maintainer_action", "continue_on_error"},
+            "fetch-artifact": {"id", "type", "operation", "target", "number", "artifact",
+                               "write_to", "continue_on_error"},
+            "checkout-pr": {"id", "type", "operation", "number", "continue_on_error"},
+        }[operation]
+        for key in config.keys() - expected:
+            errors.append(f"GitHub step has unsupported field {key!r}.")
+        if operation != "checkout-pr" and config.get("target") not in ("issue", "pull_request"):
+            errors.append("GitHub step 'target' must be issue or pull_request.")
+        if "number" not in config:
+            errors.append("GitHub step requires 'number'.")
+        elif not (isinstance(config["number"], str) and "{{" in config["number"]):
+            try:
+                _number(config["number"])
+            except ValueError as exc:
+                errors.append(str(exc))
+        if operation == "comment":
+            if sum(key in config for key in ("body", "body_file", "body_files")) != 1:
+                errors.append("GitHub comment requires exactly one of body, body_file, body_files.")
+            if "body_files" in config and (
+                not isinstance(config["body_files"], list) or not config["body_files"]
+                or not all(isinstance(v, str) and v.strip() for v in config["body_files"])
+            ):
+                errors.append("'body_files' must be a non-empty list of paths.")
+            action = config.get("maintainer_action")
+            if action is not None and (
+                not isinstance(action, dict) or set(action) != {"summary", "possible_labels"}
+                or not isinstance(action["summary"], str)
+                or not isinstance(action["possible_labels"], list)
+                or not all(isinstance(v, str) and v.strip() for v in action["possible_labels"])
+            ):
+                errors.append(
+                    "'maintainer_action' requires a summary and a list of possible_labels."
+                )
+        if operation == "fetch-artifact" and "write_to" not in config:
+            errors.append("GitHub fetch-artifact requires 'write_to'.")
+        if "artifact" in config and not (
+            isinstance(config["artifact"], str) and _IDENTIFIER.fullmatch(config["artifact"])
+        ):
+            errors.append(
+                "'artifact' must be a stable alphanumeric identifier (hyphens/underscores allowed)."
+            )
+        if operation == "fetch-artifact" and "artifact" not in config:
+            errors.append("GitHub fetch-artifact requires 'artifact'.")
+        for name in ("body", "body_file", "write_to"):
+            if name in config and not isinstance(config[name], str):
+                errors.append(f"'{name}' must be a string.")
+        return errors
+
+    def execute(self, config: dict[str, Any], context: StepContext) -> StepResult:
+        try:
+            errors = self.validate(config)
+            if errors:
+                raise ValueError("; ".join(errors))
+            if not context.project_root:
+                raise ValueError("GitHub step requires a project root")
+            if context.inside_fan_out:
+                raise ValueError(
+                    "GitHub steps cannot run inside fan-out "
+                    "(run/step retry identity is not unique per item)"
+                )
+            root = Path(context.project_root).resolve()
+            repo, url = _identity(root)
+            number = _number(_resolved(config["number"], context))
+            operation = config["operation"]
+            if operation == "checkout-pr":
+                return self._checkout(root, url, number)
+            target = config["target"]
+            resource_kind = "pulls" if target == "pull_request" else "issues"
+            resource = _api(root, f"{url}/{resource_kind}/{number}")
+            if (not isinstance(resource, dict) or resource.get("number") != number
+                    or (target == "issue" and "pull_request" in resource)):
+                raise ValueError(f"GitHub {target} #{number} does not match the requested target")
+            issue_url = f"{url}/issues/{number}"
+            if operation == "comment":
+                return self._comment(config, context, root, repo, issue_url, number)
+            return self._fetch(config, context, root, issue_url)
+        except (ValueError, OSError, UnicodeError) as exc:
+            return StepResult(status=StepStatus.FAILED, error=f"GitHub step: {exc}")
+
+    @staticmethod
+    def _viewer(root: Path) -> str:
+        user = _api(root, "https://api.github.com/user")
+        if not isinstance(user, dict):
+            raise ValueError("GitHub returned an invalid authenticated user")
+        return _string(user.get("login"), "authenticated user login")
+
+    def _comment(self, config: dict[str, Any], context: StepContext, root: Path,
+                 repo: str, issue_url: str, number: int) -> StepResult:
+        if "body" in config:
+            body = _string(_resolved(config["body"], context), "body")
+        elif "body_file" in config:
+            source = _string(_resolved(config["body_file"], context), "body_file")
+            path = _project_path(root, source, writing=False)
+            body = path.read_text(encoding="utf-8")
+        else:
+            paths = [
+                _project_path(root, _string(_resolved(p, context), "body_files entry"), writing=False)
+                for p in config["body_files"]
+            ]
+            body = "\n\n".join(path.read_text(encoding="utf-8") for path in paths)
+        if not body.strip():
+            raise ValueError("Comment body must not be empty")
+        action = config.get("maintainer_action")
+        if action is not None:
+            summary = _string(_resolved(action["summary"], context), "maintainer_action.summary")
+            labels = [
+                _string(_resolved(label, context), "possible_labels")
+                for label in action["possible_labels"]
+            ]
+            proposed = ", ".join(labels) if labels else "None"
+            body += (
+                f"\n\n### Maintainer action (proposal only)\n{summary}"
+                f"\n\nPossible labels: {proposed}"
+            )
+        artifact = config.get("artifact", "-")
+        run_id = _string(context.run_id, "run_id")
+        step_id = _string(config["id"], "id")
+        if not all(_IDENTIFIER.fullmatch(value) for value in (run_id, step_id)) or (
+            artifact != "-" and not _IDENTIFIER.fullmatch(artifact)
+        ):
+            raise ValueError("Artifact, run ID, and step ID must be safe identifiers")
+        digest = hashlib.sha256(body.encode("utf-8")).hexdigest()
+        marked_body = (f"{body}\n\n<!-- speckit-github:v1 artifact={artifact} "
+                       f"run={run_id} step={step_id} sha256={digest} -->")
+        viewer = self._viewer(root)
+        existing = []
+        for comment in _comments(root, issue_url):
+            marked = _marked(comment)
+            if marked and marked[2:4] == (run_id, step_id):
+                existing.append((comment, marked))
+        if len(existing) > 1:
+            raise ValueError("Multiple comments exist for this run and step")
+        if existing:
+            comment, marked = existing[0]
+            if marked[0] != body or marked[1] != artifact or _author(comment) != viewer:
+                raise ValueError(
+                    "Existing run/step comment differs or is not owned by the authenticated user"
+                )
+            comment_id = comment.get("id")
+        else:
+            posted = _api(root, f"{issue_url}/comments", method="POST", data={"body": marked_body})
+            if not isinstance(posted, dict):
+                raise ValueError("GitHub returned an invalid posted comment")
+            comment_id = posted.get("id")
+        if not isinstance(comment_id, int) or isinstance(comment_id, bool) or comment_id <= 0:
+            raise ValueError("GitHub comment has no valid ID")
+        return StepResult(output={"repository": repo, "number": number, "comment_id": comment_id,
+                                  "artifact": artifact if artifact != "-" else None})
+
+    def _fetch(self, config: dict[str, Any], context: StepContext, root: Path,
+               issue_url: str) -> StepResult:
+        name = _string(_resolved(config["write_to"], context), "write_to")
+        destination = _project_path(root, name, writing=True)
+        viewer = self._viewer(root)
+        matches = []
+        for comment in _comments(root, issue_url):
+            marked = _marked(comment)
+            if marked and marked[1] == config["artifact"]:
+                matches.append((comment, marked[0]))
+        if len(matches) != 1:
+            raise ValueError(
+                f"Expected exactly one trusted artifact {config['artifact']!r}; "
+                f"found {len(matches)}"
+            )
+        comment, body = matches[0]
+        if _author(comment) != viewer:
+            raise ValueError("GitHub artifact was not posted by the authenticated user")
+        comment_id = comment.get("id")
+        if not isinstance(comment_id, int) or isinstance(comment_id, bool) or comment_id <= 0:
+            raise ValueError("GitHub artifact has no valid comment ID")
+        try:
+            with destination.open("x", encoding="utf-8") as stream:
+                stream.write(body)
+        except FileExistsError as exc:
+            raise ValueError(f"Destination already exists: {destination}") from exc
+        except OSError as exc:
+            raise ValueError(f"Cannot write artifact: {exc}") from exc
+        return StepResult(output={"path": str(destination), "comment_id": comment_id})
+
+    @staticmethod
+    def _checkout(root: Path, url: str, number: int) -> StepResult:
+        pr = _api(root, f"{url}/pulls/{number}")
+        head = pr.get("head") if isinstance(pr, dict) else None
+        sha = head.get("sha") if isinstance(head, dict) else None
+        if not isinstance(sha, str) or not re.fullmatch(r"[a-f0-9]{40}", sha):
+            raise ValueError("GitHub PR has no valid head SHA")
+        _run(["git", "fetch", "origin", f"pull/{number}/head"], root)
+        fetched = _run(["git", "rev-parse", "FETCH_HEAD"], root)
+        if fetched != sha:
+            raise ValueError(
+                "Fetched PR head differs from the GitHub PR head; retry after the PR settles"
+            )
+        _run(["git", "-c", "advice.detachedHead=false", "checkout", "--detach", sha], root)
+        if _run(["git", "rev-parse", "HEAD"], root) != sha:
+            raise ValueError("Checked-out HEAD differs from the GitHub PR head")
+        return StepResult(output={"head_sha": sha, "number": number})
diff --git a/tests/test_workflows.py b/tests/test_workflows.py
index 9716c6578a..f830fa9867 100644
--- a/tests/test_workflows.py
+++ b/tests/test_workflows.py
@@ -4,7 +4,7 @@
 - Step registry & auto-discovery
 - Base classes (StepBase, StepContext, StepResult)
 - Expression engine
-- All 12 built-in step types
+- All 13 built-in step types
 - Workflow definition loading & validation
 - Workflow engine execution & state persistence
 - Workflow catalog & registry
@@ -106,7 +106,7 @@ def test_all_step_types_registered(self):
 
         expected = {
             "command", "shell", "prompt", "gate", "if", "switch",
-            "while", "do-while", "fan-out", "fan-in", "init", "slot",
+            "while", "do-while", "fan-out", "fan-in", "init", "slot", "github",
         }
         assert expected.issubset(set(STEP_REGISTRY.keys()))
 
diff --git a/tests/workflows/test_github_step.py b/tests/workflows/test_github_step.py
new file mode 100644
index 0000000000..e6d4b918aa
--- /dev/null
+++ b/tests/workflows/test_github_step.py
@@ -0,0 +1,294 @@
+"""Deterministic tests for the built-in GitHub workflow step."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+from specify_cli.workflows import BUILTIN_STEP_TYPES, get_step_type
+from specify_cli.workflows.base import RunStatus, StepContext, StepStatus
+from specify_cli.workflows.engine import WorkflowDefinition, WorkflowEngine
+from specify_cli.workflows.step import github
+
+
+@pytest.fixture
+def context(tmp_path: Path) -> StepContext:
+    return StepContext(
+        inputs={"issue": "12", "pr": 7},
+        project_root=str(tmp_path),
+        run_id="run-1",
+    )
+
+
+@pytest.fixture
+def api(monkeypatch):
+    comments: list[dict] = []
+    calls: list[tuple[str, str]] = []
+
+    def fake_api(root, endpoint, *, method="GET", data=None, paginated=False):
+        calls.append((method, endpoint))
+        if endpoint.endswith("/user"):
+            return {"login": "maintainer"}
+        if endpoint.endswith("/pulls/7"):
+            return {"number": 7, "head": {"sha": "a" * 40}}
+        if endpoint.endswith("/issues/12"):
+            return {"number": 12}
+        if endpoint.endswith("/comments?per_page=100"):
+            assert paginated
+            return [comments[:]]
+        if endpoint.endswith("/comments") and method == "POST":
+            comment = {"id": len(comments) + 1, "body": data["body"],
+                       "user": {"login": "maintainer"}}
+            comments.append(comment)
+            return comment
+        raise AssertionError(f"Unexpected API call: {method} {endpoint}")
+
+    monkeypatch.setattr(github, "_api", fake_api)
+    monkeypatch.setattr(github, "_identity", lambda root: (
+        "owner/repo", "https://api.github.com/repos/owner/repo",
+    ))
+    return comments, calls
+
+
+def config(**kwargs):
+    definition = {"id": "post-plan", "type": "github", "operation": "comment",
+                  "target": "issue", "number": "{{ inputs.issue }}"}
+    definition.update(kwargs)
+    return definition
+
+
+def test_registered_builtin_and_validation():
+    step = get_step_type("github")
+    assert step is not None
+    assert "github" in BUILTIN_STEP_TYPES
+    assert step.validate(config(body="text")) == []
+    assert step.validate(config(body_file="plan.md")) == []
+    assert step.validate(config(body_files=["plan.md"])) == []
+    assert step.validate(config(body="text", body_file="plan.md"))
+    assert step.validate(config(body_files=[]))
+    assert step.validate(config(body="text", number=True))
+    assert step.validate(config(body="text", target="repository"))
+    assert step.validate(config(body="text", unexpected="field"))
+    assert step.validate(config(body="text", maintainer_action={"summary": "x"}))
+    assert step.validate({"id": "fetch", "type": "github", "operation": "fetch-artifact",
+                          "target": "issue", "number": 12, "write_to": "result.md"})
+    assert step.validate({"id": "checkout", "type": "github", "operation": "checkout-pr",
+                          "number": 0})
+
+
+def test_comment_retry_is_idempotent_and_changed_content_fails(context, api):
+    comments, calls = api
+    step = get_step_type("github")
+    definition = config(body="Plan for {{ inputs.issue }}", artifact="plan",
+                        maintainer_action={"summary": "Review only",
+                                           "possible_labels": ["approved"]})
+    first = step.execute(definition, context)
+    again = step.execute(definition, context)
+    assert first.status == again.status == StepStatus.COMPLETED
+    assert first.output["comment_id"] == again.output["comment_id"] == 1
+    assert len(comments) == 1
+    assert "Plan for 12" in comments[0]["body"]
+    assert "Possible labels: approved" in comments[0]["body"]
+    assert not any("/labels" in endpoint for _, endpoint in calls)
+    assert len([method for method, _ in calls if method == "POST"]) == 1
+    changed = step.execute(config(body="Different", artifact="plan"), context)
+    assert changed.status == StepStatus.FAILED
+    assert "differs" in changed.error
+    assert len(comments) == 1
+
+
+def test_comment_files_and_fetch_artifact(context, api):
+    comments, _ = api
+    root = Path(context.project_root)
+    (root / "one.md").write_text("First")
+    (root / "two.md").write_text("Second")
+    step = get_step_type("github")
+    posted = step.execute(config(body_files=["one.md", "two.md"], artifact="report"), context)
+    assert posted.status == StepStatus.COMPLETED
+    result = step.execute({"id": "retrieve", "type": "github", "operation": "fetch-artifact",
+                           "target": "issue", "number": 12, "artifact": "report",
+                           "write_to": "result.md"}, context)
+    assert result.status == StepStatus.COMPLETED, result.error
+    assert (root / "result.md").read_text() == "First\n\nSecond"
+    assert result.output["comment_id"] == comments[0]["id"]
+    again = step.execute({"id": "retrieve", "operation": "fetch-artifact",
+                          "target": "issue", "number": 12, "artifact": "report",
+                          "write_to": "result.md"}, context)
+    assert again.status == StepStatus.FAILED
+    assert (root / "result.md").read_text() == "First\n\nSecond"
+
+
+def test_engine_executes_github_yaml_without_shell(context, api):
+    comments, _ = api
+    definition = WorkflowDefinition.from_string("""
+schema_version: "1.0"
+workflow:
+  id: github-pipeline
+  name: GitHub pipeline
+  version: "1.0.0"
+inputs:
+  issue:
+    type: number
+    required: true
+steps:
+  - id: publish
+    type: github
+    operation: comment
+    target: issue
+    number: "{{ inputs.issue }}"
+    body: "Plan for {{ inputs.issue }}"
+    artifact: plan
+""")
+    engine = WorkflowEngine(Path(context.project_root))
+    assert engine.validate(definition) == []
+    state = engine.execute(definition, {"issue": "12"}, run_id="pipeline1")
+    assert state.status == RunStatus.COMPLETED
+    assert state.step_results["publish"]["output"]["comment_id"] == 1
+    assert len(comments) == 1
+
+
+def test_pull_request_comment_uses_issue_comment_endpoint(context, api):
+    comments, calls = api
+    definition = config(body="PR feedback", target="pull_request", number=7)
+    result = get_step_type("github").execute(definition, context)
+    assert result.status == StepStatus.COMPLETED, result.error
+    assert get_step_type("github").execute(definition, context).status == StepStatus.COMPLETED
+    assert len(comments) == 1
+    assert any(url.endswith("/pulls/7") for _, url in calls)
+    assert any(method == "POST" and url.endswith("/issues/7/comments")
+               for method, url in calls)
+
+
+@pytest.mark.parametrize("change,expected", [
+    (lambda comments: comments[0].update(body=comments[0]["body"].replace("First", "Altered")), "digest"),
+    (lambda comments: comments[0].update(user={"login": "someone-else"}), "not posted"),
+    (lambda comments: comments.append(dict(comments[0], id=2)), "found 2"),
+])
+def test_fetch_rejects_untrusted_or_ambiguous(context, api, change, expected):
+    comments, _ = api
+    step = get_step_type("github")
+    assert step.execute(config(body="First", artifact="report"), context).status == StepStatus.COMPLETED
+    change(comments)
+    result = step.execute({"id": "retrieve", "operation": "fetch-artifact",
+                           "target": "issue", "number": 12, "artifact": "report",
+                           "write_to": "result.md"}, context)
+    assert result.status == StepStatus.FAILED
+    assert expected in result.error
+    assert not (Path(context.project_root) / "result.md").exists()
+
+
+@pytest.mark.parametrize("name", ["../elsewhere", "/tmp/elsewhere", "absent/result.md", "link/result.md"])
+def test_fetch_rejects_unsafe_destinations(context, api, name, tmp_path):
+    root = Path(context.project_root)
+    (root / "link").symlink_to(tmp_path.parent, target_is_directory=True)
+    step = get_step_type("github")
+    assert step.execute(config(body="text", artifact="report"), context).status == StepStatus.COMPLETED
+    result = step.execute({"id": "fetch", "operation": "fetch-artifact", "target": "issue",
+                           "number": 12, "artifact": "report", "write_to": name}, context)
+    assert result.status == StepStatus.FAILED
+
+
+def test_bad_identifiers_and_missing_artifact_fail_without_post(context, api):
+    comments, calls = api
+    step = get_step_type("github")
+    for number in (0, "-1", True, "1; echo bad", None):
+        result = step.execute(config(body="hello", number=number), context)
+        assert result.status == StepStatus.FAILED
+        assert "number" in result.error
+    result = step.execute({"id": "fetch", "operation": "fetch-artifact", "target": "issue",
+                           "number": 12, "artifact": "missing", "write_to": "result.md"}, context)
+    assert result.status == StepStatus.FAILED
+    assert "found 0" in result.error
+    assert not comments
+    assert not any(method == "POST" for method, _ in calls)
+
+
+def test_comment_rejects_symlinked_source_and_fan_out(context, api, tmp_path):
+    root = Path(context.project_root)
+    (root / "link.md").symlink_to(tmp_path.parent / "outside.md")
+    step = get_step_type("github")
+    result = step.execute(config(body_file="link.md"), context)
+    assert result.status == StepStatus.FAILED
+    assert "Symlinked" in result.error
+    context.inside_fan_out = True
+    result = step.execute(config(body="hi"), context)
+    assert result.status == StepStatus.FAILED
+    assert "fan-out" in result.error
+
+
+def test_api_error_fails_without_success_shaped_output(context, api, monkeypatch):
+    monkeypatch.setattr(github, "_api", lambda *args, **kwargs: (_ for _ in ()).throw(
+        ValueError("GitHub request failed (exit code 403)")))
+    result = get_step_type("github").execute(config(body="hi"), context)
+    assert result.status == StepStatus.FAILED
+    assert "403" in result.error
+    assert result.output == {}
+
+
+def test_api_posts_json_on_stdin_and_slurps_comment_pages(context, monkeypatch):
+    observed = []
+
+    def fake_run(args, root, *, input_text=None):
+        observed.append((args, input_text))
+        return "[[]]" if "--paginate" in args else '{"id": 1}'
+
+    monkeypatch.setattr(github, "_run", fake_run)
+    root = Path(context.project_root)
+    assert github._api(root, "https://api.github.com/repos/o/r/issues/1/comments",
+                       method="POST", data={"body": "private body"}) == {"id": 1}
+    assert observed[0][1] == '{"body": "private body"}'
+    assert "private body" not in " ".join(observed[0][0])
+    assert github._api(root, "https://api.github.com/repos/o/r/issues/1/comments",
+                       paginated=True) == [[]]
+    assert observed[1][0][-2:] == ["--paginate", "--slurp"]
+
+
+def test_identity_rejects_non_github_origin(context, monkeypatch):
+    assert github._ORIGIN.fullmatch("https://evil.example/owner/repo.git") is None
+    assert github._ORIGIN.fullmatch("https://github.com/owner/repo.git")
+    monkeypatch.setattr(github, "_run", lambda args, root, **kwargs: "https://evil.example/owner/repo.git")
+    with pytest.raises(ValueError, match="github.com origin"):
+        github._identity(Path(context.project_root))
+
+
+def test_comment_rejects_wrong_target(context, api, monkeypatch):
+    step = get_step_type("github")
+    original_api = github._api
+
+    def wrong_target(root, endpoint, **kwargs):
+        if endpoint.endswith("/issues/12"):
+            return {"number": 12, "pull_request": {}}
+        return original_api(root, endpoint, **kwargs)
+
+    monkeypatch.setattr(github, "_api", wrong_target)
+    bad = step.execute(config(body="hi"), context)
+    assert bad.status == StepStatus.FAILED
+    assert "does not match" in bad.error
+
+
+def test_checkout_verifies_head_before_checkout(context, api, monkeypatch):
+    commands = []
+    sha = "a" * 40
+
+    def fake_run(args, root, *, input_text=None):
+        commands.append(args)
+        if args[:2] == ["git", "rev-parse"]:
+            return sha
+        return ""
+
+    monkeypatch.setattr(github, "_run", fake_run)
+    step = get_step_type("github")
+    definition = {"id": "checkout", "type": "github", "operation": "checkout-pr",
+                  "number": "{{ inputs.pr }}"}
+    result = step.execute(definition, context)
+    assert result.status == StepStatus.COMPLETED
+    assert result.output["head_sha"] == sha
+    assert ["git", "fetch", "origin", "pull/7/head"] in commands
+    assert ["git", "-c", "advice.detachedHead=false", "checkout", "--detach", sha] in commands
+    assert commands[-1] == ["git", "rev-parse", "HEAD"]
+    commands.clear()
+    monkeypatch.setattr(github, "_run", lambda args, root, **kwargs: "b" * 40)
+    failed = step.execute(definition, context)
+    assert failed.status == StepStatus.FAILED
+    assert "differs" in failed.error
diff --git a/workflows/ARCHITECTURE.md b/workflows/ARCHITECTURE.md
index 6070823a2a..8fe70a8709 100644
--- a/workflows/ARCHITECTURE.md
+++ b/workflows/ARCHITECTURE.md
@@ -79,13 +79,14 @@ When a `gate` step pauses execution, the engine persists `current_step_index` an
 
 ## Step Types
 
-The engine ships with 12 built-in step types, each in its own subpackage under `src/specify_cli/workflows/step/`:
+The engine ships with 13 built-in step types, each in its own subpackage under `src/specify_cli/workflows/step/`:
 
 | Type Key | Class | Purpose | Returns `next_steps`? |
 |----------|-------|---------|-----------------------|
 | `command` | `CommandStep` | Invoke an installed Spec Kit command via integration CLI | No |
 | `prompt` | `PromptStep` | Send an arbitrary inline prompt to integration CLI | No |
 | `shell` | `ShellStep` | Run a shell command, capture output | No |
+| `github` | `GitHubStep` | GitHub comments, artifacts, and PR checkout | No |
 | `init` | `InitStep` | Bootstrap a project (equivalent to `specify init`) | No |
 | `slot` | `SlotStep` | Named workflow slot; skipped when unfilled | No |
 | `gate` | `GateStep` | Interactive human review/approval | No (pauses in CI) |

From e8f5f35a28db99e3a73f3cbafaab59698182ad87 Mon Sep 17 00:00:00 2001
From: Manfred Riem <15701806+mnriem@users.noreply.github.com>
Date: Fri, 9 Oct 2026 07:09:48 -0500
Subject: [PATCH 02/10] Preserve GitHub artifact bytes across fresh workflow
 runs

Assisted-by: GitHub Copilot (model: GPT-6 Sol, autonomous)
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: ec94c538-a8b2-4c39-81fc-3ba5f0a59ce6
---
 docs/reference/workflows.md                   |  15 +-
 .../workflows/step/github/__init__.py         | 104 +++++++++++---
 tests/workflows/test_github_step.py           | 131 +++++++++++++++++-
 3 files changed, 228 insertions(+), 22 deletions(-)

diff --git a/docs/reference/workflows.md b/docs/reference/workflows.md
index 0dadd45a0e..c04e1cfc30 100644
--- a/docs/reference/workflows.md
+++ b/docs/reference/workflows.md
@@ -591,6 +591,13 @@ for PRs/issues, and issue-comment write access only for `comment`. The step
 does not request or elevate permissions. It does not interpret issue/comment
 contents as workflow instructions or apply labels. GitHub operations require
 network access; tests should mock the API rather than post live comments.
+In GitHub Actions, a repository-scoped `GITHUB_TOKEN` is supported: when
+`GITHUB_ACTIONS=true` and `GITHUB_REPOSITORY` matches `origin`, the step
+verifies that the active credential is an installation token restricted to
+that repository, then checks the author against `github-actions[bot]`.
+User tokens (including user tokens used inside Actions) use `GET /user` for
+author verification instead. Other app installation tokens are not accepted
+as the Actions bot identity.
 
 ```yaml
 - id: publish-plan
@@ -628,9 +635,11 @@ comment; it never changes GitHub labels. The posted comment includes a
 digest-bearing marker tying it to the workflow run and step. Re-running the
 same step in the same run reuses an identical comment rather than posting a
 duplicate; changed content or a changed author fails instead. `fetch-artifact`
-requires exactly one intact, previously marked comment authored by the active
-GitHub account. It writes only to a *new* relative file under the project
-root, with an existing directory; symlinks and overwrites are refused.
+requires exactly one intact, previously marked comment authored by the
+verified account/bot. It writes only the original artifact bytes, excluding
+the maintainer-action footer and marker, to a *new* relative file under the
+project root. Missing parent directories are created inside the project
+after the comment is verified; symlinks and overwrites are refused.
 `checkout-pr` fetches GitHub's `pull/<number>/head` ref, verifies its SHA
 matches the API's PR head, and checks out that commit detached. Local changes
 that prevent checkout cause the step to fail.
diff --git a/src/specify_cli/workflows/step/github/__init__.py b/src/specify_cli/workflows/step/github/__init__.py
index b02015c700..2d7760bc6d 100644
--- a/src/specify_cli/workflows/step/github/__init__.py
+++ b/src/specify_cli/workflows/step/github/__init__.py
@@ -4,6 +4,7 @@
 
 import hashlib
 import json
+import os
 import re
 import subprocess
 from pathlib import Path
@@ -18,9 +19,9 @@
     r"(?:https://github\.com/|git@github\.com:)([A-Za-z0-9_.-]+)/([A-Za-z0-9_.-]+?)(?:\.git)?/?\Z"
 )
 _MARKER = re.compile(
-    r"<!-- speckit-github:v1 artifact=([A-Za-z0-9_-]+) "
+    r"<!-- speckit-github:v2 artifact=([A-Za-z0-9_-]+) "
     r"run=([A-Za-z0-9_-]+) step=([A-Za-z0-9_-]+) "
-    r"sha256=([a-f0-9]{64}) -->\Z"
+    r"bytes=([0-9]+) sha256=([a-f0-9]{64}) -->\Z"
 )
 _MARKER_PREFIX = "<!-- speckit-github:"
 
@@ -74,13 +75,48 @@ def _project_path(root: Path, value: str, *, writing: bool) -> Path:
     if writing:
         if candidate.exists():
             raise ValueError(f"Destination already exists: {value!r}")
-        if not candidate.parent.is_dir():
-            raise ValueError(f"Destination directory does not exist: {value!r}")
     elif not candidate.is_file():
         raise ValueError(f"File does not exist: {value!r}")
     return candidate
 
 
+def _write_artifact(root: Path, destination: Path, body: str) -> None:
+    """Create a new file through directory handles; refuse symlinked parents."""
+    data = body.encode("utf-8")
+    if os.name == "nt":
+        destination.parent.mkdir(parents=True, exist_ok=True)
+        _project_path(root, str(destination.relative_to(root)), writing=True)
+        with destination.open("xb") as stream:
+            stream.write(data)
+        return
+
+    flags = os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW
+    directory = os.open(root, flags)
+    try:
+        for part in destination.relative_to(root).parts[:-1]:
+            try:
+                child = os.open(part, flags, dir_fd=directory)
+            except FileNotFoundError:
+                try:
+                    os.mkdir(part, dir_fd=directory)
+                except FileExistsError:
+                    pass
+                child = os.open(part, flags, dir_fd=directory)
+            os.close(directory)
+            directory = child
+        name = destination.name
+        fd = os.open(name, os.O_WRONLY | os.O_CREAT | os.O_EXCL | os.O_NOFOLLOW,
+                     0o600, dir_fd=directory)
+        try:
+            with os.fdopen(fd, "wb") as stream:
+                stream.write(data)
+        except OSError:
+            os.unlink(name, dir_fd=directory)
+            raise
+    finally:
+        os.close(directory)
+
+
 def _resolved(value: Any, context: StepContext) -> Any:
     if isinstance(value, str) and "{{" in value:
         return evaluate_expression(value, context)
@@ -129,9 +165,17 @@ def _marked(comment: dict[str, Any]) -> tuple[str, str, str, str, str] | None:
         return None
     body, sep, marker = text.rpartition("\n\n")
     match = _MARKER.fullmatch(marker) if sep else None
-    if not match or hashlib.sha256(body.encode("utf-8")).hexdigest() != match[4]:
+    encoded = body.encode("utf-8")
+    if not match or hashlib.sha256(encoded).hexdigest() != match[5]:
         raise ValueError("GitHub artifact has an invalid marker or content digest")
-    return body, match[1], match[2], match[3], match[4]
+    artifact_bytes = int(match[4])
+    if artifact_bytes > len(encoded):
+        raise ValueError("GitHub artifact has an invalid byte length")
+    try:
+        artifact = encoded[:artifact_bytes].decode("utf-8")
+    except UnicodeDecodeError as exc:
+        raise ValueError("GitHub artifact has an invalid UTF-8 boundary") from exc
+    return body, match[1], match[2], match[3], artifact
 
 
 def _author(comment: dict[str, Any]) -> str | None:
@@ -230,12 +274,34 @@ def execute(self, config: dict[str, Any], context: StepContext) -> StepResult:
             issue_url = f"{url}/issues/{number}"
             if operation == "comment":
                 return self._comment(config, context, root, repo, issue_url, number)
-            return self._fetch(config, context, root, issue_url)
+            return self._fetch(config, context, root, repo, issue_url)
         except (ValueError, OSError, UnicodeError) as exc:
             return StepResult(status=StepStatus.FAILED, error=f"GitHub step: {exc}")
 
     @staticmethod
-    def _viewer(root: Path) -> str:
+    def _viewer(root: Path, repo: str) -> str:
+        if (os.environ.get("GITHUB_ACTIONS") == "true"
+                and os.environ.get("GITHUB_REPOSITORY", "").lower() == repo.lower()):
+            try:
+                installation = _api(
+                    root, "https://api.github.com/installation/repositories"
+                )
+            except ValueError:
+                # A user token used inside Actions does not have this installation
+                # endpoint. It must identify itself through /user instead.
+                pass
+            else:
+                repositories = installation.get("repositories") if isinstance(installation, dict) else None
+                if (not isinstance(repositories, list)
+                        or installation.get("total_count") != 1
+                        or len(repositories) != 1
+                        or not isinstance(repositories[0], dict)
+                        or not isinstance(repositories[0].get("full_name"), str)
+                        or repositories[0]["full_name"].lower() != repo.lower()):
+                    raise ValueError(
+                        "Actions installation token must be scoped to this repository only"
+                    )
+                return "github-actions[bot]"
         user = _api(root, "https://api.github.com/user")
         if not isinstance(user, dict):
             raise ValueError("GitHub returned an invalid authenticated user")
@@ -248,15 +314,16 @@ def _comment(self, config: dict[str, Any], context: StepContext, root: Path,
         elif "body_file" in config:
             source = _string(_resolved(config["body_file"], context), "body_file")
             path = _project_path(root, source, writing=False)
-            body = path.read_text(encoding="utf-8")
+            body = path.read_bytes().decode("utf-8")
         else:
             paths = [
                 _project_path(root, _string(_resolved(p, context), "body_files entry"), writing=False)
                 for p in config["body_files"]
             ]
-            body = "\n\n".join(path.read_text(encoding="utf-8") for path in paths)
+            body = "\n\n".join(path.read_bytes().decode("utf-8") for path in paths)
         if not body.strip():
             raise ValueError("Comment body must not be empty")
+        artifact_bytes = len(body.encode("utf-8"))
         action = config.get("maintainer_action")
         if action is not None:
             summary = _string(_resolved(action["summary"], context), "maintainer_action.summary")
@@ -277,9 +344,9 @@ def _comment(self, config: dict[str, Any], context: StepContext, root: Path,
         ):
             raise ValueError("Artifact, run ID, and step ID must be safe identifiers")
         digest = hashlib.sha256(body.encode("utf-8")).hexdigest()
-        marked_body = (f"{body}\n\n<!-- speckit-github:v1 artifact={artifact} "
-                       f"run={run_id} step={step_id} sha256={digest} -->")
-        viewer = self._viewer(root)
+        marked_body = (f"{body}\n\n<!-- speckit-github:v2 artifact={artifact} "
+                       f"run={run_id} step={step_id} bytes={artifact_bytes} sha256={digest} -->")
+        viewer = self._viewer(root, repo)
         existing = []
         for comment in _comments(root, issue_url):
             marked = _marked(comment)
@@ -298,6 +365,8 @@ def _comment(self, config: dict[str, Any], context: StepContext, root: Path,
             posted = _api(root, f"{issue_url}/comments", method="POST", data={"body": marked_body})
             if not isinstance(posted, dict):
                 raise ValueError("GitHub returned an invalid posted comment")
+            if _author(posted) != viewer:
+                raise ValueError("Posted comment author does not match the authenticated identity")
             comment_id = posted.get("id")
         if not isinstance(comment_id, int) or isinstance(comment_id, bool) or comment_id <= 0:
             raise ValueError("GitHub comment has no valid ID")
@@ -305,15 +374,15 @@ def _comment(self, config: dict[str, Any], context: StepContext, root: Path,
                                   "artifact": artifact if artifact != "-" else None})
 
     def _fetch(self, config: dict[str, Any], context: StepContext, root: Path,
-               issue_url: str) -> StepResult:
+               repo: str, issue_url: str) -> StepResult:
         name = _string(_resolved(config["write_to"], context), "write_to")
         destination = _project_path(root, name, writing=True)
-        viewer = self._viewer(root)
+        viewer = self._viewer(root, repo)
         matches = []
         for comment in _comments(root, issue_url):
             marked = _marked(comment)
             if marked and marked[1] == config["artifact"]:
-                matches.append((comment, marked[0]))
+                matches.append((comment, marked[4]))
         if len(matches) != 1:
             raise ValueError(
                 f"Expected exactly one trusted artifact {config['artifact']!r}; "
@@ -326,8 +395,7 @@ def _fetch(self, config: dict[str, Any], context: StepContext, root: Path,
         if not isinstance(comment_id, int) or isinstance(comment_id, bool) or comment_id <= 0:
             raise ValueError("GitHub artifact has no valid comment ID")
         try:
-            with destination.open("x", encoding="utf-8") as stream:
-                stream.write(body)
+            _write_artifact(root, destination, body)
         except FileExistsError as exc:
             raise ValueError(f"Destination already exists: {destination}") from exc
         except OSError as exc:
diff --git a/tests/workflows/test_github_step.py b/tests/workflows/test_github_step.py
index e6d4b918aa..fa25019cf7 100644
--- a/tests/workflows/test_github_step.py
+++ b/tests/workflows/test_github_step.py
@@ -119,6 +119,120 @@ def test_comment_files_and_fetch_artifact(context, api):
     assert (root / "result.md").read_text() == "First\n\nSecond"
 
 
+def test_fetch_creates_fresh_nested_parent_and_restores_only_artifact(context, api):
+    root = Path(context.project_root)
+    artifact = "# Assessment\r\n\r\nCafé\r\n\r\n### Maintainer action (proposal only)\r\nLiteral artifact text.\r\n"
+    (root / "assessment.md").write_bytes(artifact.encode("utf-8"))
+    step = get_step_type("github")
+    definition = config(body_file="assessment.md", artifact="assessment",
+                        maintainer_action={"summary": "Please review before proceeding.",
+                                           "possible_labels": ["ready"]})
+    assert step.execute(definition, context).status == StepStatus.COMPLETED
+    destination = root / ".specify" / "bugs" / "fresh-label" / "assessment.md"
+    assert not destination.parent.exists()
+    result = step.execute({"id": "rehydrate", "type": "github", "operation": "fetch-artifact",
+                           "target": "issue", "number": 12, "artifact": "assessment",
+                           "write_to": ".specify/bugs/fresh-label/assessment.md"}, context)
+    assert result.status == StepStatus.COMPLETED, result.error
+    assert destination.read_bytes() == artifact.encode("utf-8")
+    assert "Please review before proceeding" not in destination.read_text(encoding="utf-8")
+    assert step.execute(definition, context).status == StepStatus.COMPLETED
+
+
+def test_actions_installation_token_verifies_bot_author(context, api, monkeypatch):
+    comments, _ = api
+    monkeypatch.setenv("GITHUB_ACTIONS", "true")
+    monkeypatch.setenv("GITHUB_REPOSITORY", "owner/repo")
+    original_api = github._api
+
+    def actions_api(root, endpoint, **kwargs):
+        if endpoint.endswith("/installation/repositories"):
+            return {"total_count": 1, "repositories": [{"full_name": "owner/repo"}]}
+        if endpoint.endswith("/user"):
+            raise AssertionError("Actions installation tokens do not need /user")
+        result = original_api(root, endpoint, **kwargs)
+        if kwargs.get("method") == "POST":
+            result["user"] = {"login": "github-actions[bot]"}
+        return result
+
+    monkeypatch.setattr(github, "_api", actions_api)
+    step = get_step_type("github")
+    definition = config(body="Artifact", artifact="report")
+    assert step.execute(definition, context).status == StepStatus.COMPLETED
+    assert step.execute(definition, context).status == StepStatus.COMPLETED
+    result = step.execute({"id": "fetch", "operation": "fetch-artifact", "target": "issue",
+                           "number": 12, "artifact": "report", "write_to": "new/fix.md"}, context)
+    assert result.status == StepStatus.COMPLETED, result.error
+    assert (Path(context.project_root) / "new" / "fix.md").read_bytes() == b"Artifact"
+    assert len(comments) == 1
+
+
+@pytest.mark.parametrize("installation", [
+    {"total_count": 1, "repositories": [{"full_name": "elsewhere/repo"}]},
+    {"total_count": 2, "repositories": [{"full_name": "owner/repo"}]},
+    {"total_count": 1, "repositories": [{"full_name": 42}]},
+])
+def test_actions_rejects_untrusted_installation(context, api, monkeypatch, installation):
+    comments, _ = api
+    monkeypatch.setenv("GITHUB_ACTIONS", "true")
+    monkeypatch.setenv("GITHUB_REPOSITORY", "owner/repo")
+    original_api = github._api
+    monkeypatch.setattr(
+        github, "_api",
+        lambda root, endpoint, **kwargs: installation
+        if endpoint.endswith("/installation/repositories")
+        else original_api(root, endpoint, **kwargs),
+    )
+    result = get_step_type("github").execute(config(body="text"), context)
+    assert result.status == StepStatus.FAILED
+    assert "scoped to this repository" in result.error
+    assert not comments
+
+
+def test_actions_user_token_uses_user_identity(context, api, monkeypatch):
+    monkeypatch.setenv("GITHUB_ACTIONS", "true")
+    monkeypatch.setenv("GITHUB_REPOSITORY", "owner/repo")
+    original_api = github._api
+
+    def user_token(root, endpoint, **kwargs):
+        if endpoint.endswith("/installation/repositories"):
+            raise ValueError("Installation endpoint unavailable to user token")
+        return original_api(root, endpoint, **kwargs)
+
+    monkeypatch.setattr(github, "_api", user_token)
+    assert get_step_type("github").execute(config(body="text"), context).status == StepStatus.COMPLETED
+
+
+def test_actions_rejects_comment_from_wrong_bot(context, api, monkeypatch):
+    comments, _ = api
+    monkeypatch.setenv("GITHUB_ACTIONS", "true")
+    monkeypatch.setenv("GITHUB_REPOSITORY", "owner/repo")
+    original_api = github._api
+    monkeypatch.setattr(
+        github, "_api",
+        lambda root, endpoint, **kwargs: (
+            {"total_count": 1, "repositories": [{"full_name": "owner/repo"}]}
+            if endpoint.endswith("/installation/repositories")
+            else original_api(root, endpoint, **kwargs)
+        ),
+    )
+    result = get_step_type("github").execute(config(body="text"), context)
+    assert result.status == StepStatus.FAILED
+    assert "author does not match" in result.error
+    assert len(comments) == 1  # The server posted, but success is not reported.
+
+
+def test_fetch_does_not_create_directories_for_untrusted_artifact(context, api):
+    step = get_step_type("github")
+    root = Path(context.project_root)
+    result = step.execute({"id": "rehydrate", "operation": "fetch-artifact",
+                           "target": "issue", "number": 12, "artifact": "missing",
+                           "write_to": ".specify/bugs/fresh-label/fix.md"}, context)
+    assert result.status == StepStatus.FAILED
+    assert "found 0" in result.error
+    assert not (root / ".specify").exists()
+
+
 def test_engine_executes_github_yaml_without_shell(context, api):
     comments, _ = api
     definition = WorkflowDefinition.from_string("""
@@ -178,7 +292,7 @@ def test_fetch_rejects_untrusted_or_ambiguous(context, api, change, expected):
     assert not (Path(context.project_root) / "result.md").exists()
 
 
-@pytest.mark.parametrize("name", ["../elsewhere", "/tmp/elsewhere", "absent/result.md", "link/result.md"])
+@pytest.mark.parametrize("name", ["../elsewhere", "/tmp/elsewhere", "link/result.md"])
 def test_fetch_rejects_unsafe_destinations(context, api, name, tmp_path):
     root = Path(context.project_root)
     (root / "link").symlink_to(tmp_path.parent, target_is_directory=True)
@@ -189,6 +303,21 @@ def test_fetch_rejects_unsafe_destinations(context, api, name, tmp_path):
     assert result.status == StepStatus.FAILED
 
 
+def test_fetch_rejects_symlinked_missing_parent_and_existing_destination(context, api, tmp_path):
+    root = Path(context.project_root)
+    (root / ".specify").mkdir()
+    (root / ".specify" / "bugs").symlink_to(tmp_path.parent, target_is_directory=True)
+    (root / "existing.md").write_text("keep", encoding="utf-8")
+    step = get_step_type("github")
+    assert step.execute(config(body="original", artifact="report"), context).status == StepStatus.COMPLETED
+    for name in (".specify/bugs/new/fix.md", "existing.md"):
+        result = step.execute({"id": "fetch", "operation": "fetch-artifact", "target": "issue",
+                               "number": 12, "artifact": "report", "write_to": name}, context)
+        assert result.status == StepStatus.FAILED
+    assert (root / "existing.md").read_text() == "keep"
+    assert not (tmp_path.parent / "new").exists()
+
+
 def test_bad_identifiers_and_missing_artifact_fail_without_post(context, api):
     comments, calls = api
     step = get_step_type("github")

From 8f24674b8b5d20d2fa27da775e8ff8bd96b91a36 Mon Sep 17 00:00:00 2001
From: Manfred Riem <15701806+mnriem@users.noreply.github.com>
Date: Fri, 9 Oct 2026 07:11:17 -0500
Subject: [PATCH 03/10] Clarify Actions bot identity constraint

Assisted-by: GitHub Copilot (model: GPT-6 Sol, autonomous)
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: ec94c538-a8b2-4c39-81fc-3ba5f0a59ce6
---
 docs/reference/workflows.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/reference/workflows.md b/docs/reference/workflows.md
index c04e1cfc30..f1cdafa470 100644
--- a/docs/reference/workflows.md
+++ b/docs/reference/workflows.md
@@ -596,8 +596,8 @@ In GitHub Actions, a repository-scoped `GITHUB_TOKEN` is supported: when
 verifies that the active credential is an installation token restricted to
 that repository, then checks the author against `github-actions[bot]`.
 User tokens (including user tokens used inside Actions) use `GET /user` for
-author verification instead. Other app installation tokens are not accepted
-as the Actions bot identity.
+author verification instead. A non-Actions app token cannot post as
+`github-actions[bot]`; an unexpected post author fails the step.
 
 ```yaml
 - id: publish-plan

From 21ab9e5b90c3ba84fd311dec4dc5a5301e4bfe51 Mon Sep 17 00:00:00 2001
From: Manfred Riem <15701806+mnriem@users.noreply.github.com>
Date: Fri, 9 Oct 2026 15:24:33 -0500
Subject: [PATCH 04/10] Address GitHub workflow step review findings

Assisted-by: GitHub Copilot (model: GPT-6 Sol, autonomous)
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: ec94c538-a8b2-4c39-81fc-3ba5f0a59ce6
---
 docs/reference/workflows.md                   |  8 ++-
 extensions/github/README.md                   |  4 +-
 .../workflows/step/github/__init__.py         | 33 ++++-----
 tests/workflows/test_github_step.py           | 69 ++++++++++++++++++-
 4 files changed, 92 insertions(+), 22 deletions(-)

diff --git a/docs/reference/workflows.md b/docs/reference/workflows.md
index f1cdafa470..820f90f62a 100644
--- a/docs/reference/workflows.md
+++ b/docs/reference/workflows.md
@@ -639,7 +639,13 @@ requires exactly one intact, previously marked comment authored by the
 verified account/bot. It writes only the original artifact bytes, excluding
 the maintainer-action footer and marker, to a *new* relative file under the
 project root. Missing parent directories are created inside the project
-after the comment is verified; symlinks and overwrites are refused.
+after the comment is verified; symlinks and overwrites are refused. Run and
+step IDs are hashed in the marker so workflow-valid IDs (including dots)
+remain valid. Foreign-authored comments are ignored before parsing markers;
+malformed markers from the verified author fail explicitly. This implementation
+does not provide handle-anchored writes on Windows, so `fetch-artifact` fails
+closed there rather than writing outside the project.
+
 `checkout-pr` fetches GitHub's `pull/<number>/head` ref, verifies its SHA
 matches the API's PR head, and checks out that commit detached. Local changes
 that prevent checkout cause the step to fail.
diff --git a/extensions/github/README.md b/extensions/github/README.md
index ade406599b..b25d2c5fd6 100644
--- a/extensions/github/README.md
+++ b/extensions/github/README.md
@@ -1,8 +1,8 @@
 # GitHub Integration Extension
 
-This bundled, **opt-in** extension is the home for Spec Kit's GitHub *platform* functionality. Today it provides one command, `speckit.github.taskstoissues`, which turns a feature's `tasks.md` into dependency-ordered GitHub issues.
+This bundled, **opt-in** extension owns Spec Kit's GitHub *agent command* functionality. Today it provides one command, `speckit.github.taskstoissues`, which turns a feature's `tasks.md` into dependency-ordered GitHub issues. The separate built-in [`github` workflow step](../../docs/reference/workflows.md#github-step) is a deterministic workflow building block for comments, artifacts, and PR checkout: registering the step does not install this extension or invoke the step automatically. A workflow must explicitly select `type: github` to run it.
 
-> NOTE: `git` and `github` are deliberately separate domains. The [`git` extension](../git/README.md) owns local version-control workflow (feature branches, commits, remote detection); this extension owns interactions with the GitHub platform itself.
+> NOTE: `git` and `github` are deliberately separate domains. The [`git` extension](../git/README.md) owns local version-control workflow (feature branches, commits, remote detection); this extension owns its GitHub agent command, not the workflow engine's built-in step.
 
 ## Why an extension?
 
diff --git a/src/specify_cli/workflows/step/github/__init__.py b/src/specify_cli/workflows/step/github/__init__.py
index 2d7760bc6d..058144d000 100644
--- a/src/specify_cli/workflows/step/github/__init__.py
+++ b/src/specify_cli/workflows/step/github/__init__.py
@@ -20,7 +20,7 @@
 )
 _MARKER = re.compile(
     r"<!-- speckit-github:v2 artifact=([A-Za-z0-9_-]+) "
-    r"run=([A-Za-z0-9_-]+) step=([A-Za-z0-9_-]+) "
+    r"run=([a-f0-9]{64}) step=([a-f0-9]{64}) "
     r"bytes=([0-9]+) sha256=([a-f0-9]{64}) -->\Z"
 )
 _MARKER_PREFIX = "<!-- speckit-github:"
@@ -82,14 +82,13 @@ def _project_path(root: Path, value: str, *, writing: bool) -> Path:
 
 def _write_artifact(root: Path, destination: Path, body: str) -> None:
     """Create a new file through directory handles; refuse symlinked parents."""
-    data = body.encode("utf-8")
-    if os.name == "nt":
-        destination.parent.mkdir(parents=True, exist_ok=True)
-        _project_path(root, str(destination.relative_to(root)), writing=True)
-        with destination.open("xb") as stream:
-            stream.write(data)
-        return
+    if (os.name == "nt" or not hasattr(os, "O_DIRECTORY")
+            or not hasattr(os, "O_NOFOLLOW")
+            or os.open not in os.supports_dir_fd
+            or os.mkdir not in os.supports_dir_fd):
+        raise ValueError("Safe artifact writes are unsupported on this platform")
 
+    data = body.encode("utf-8")
     flags = os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW
     directory = os.open(root, flags)
     try:
@@ -337,18 +336,16 @@ def _comment(self, config: dict[str, Any], context: StepContext, root: Path,
                 f"\n\nPossible labels: {proposed}"
             )
         artifact = config.get("artifact", "-")
-        run_id = _string(context.run_id, "run_id")
-        step_id = _string(config["id"], "id")
-        if not all(_IDENTIFIER.fullmatch(value) for value in (run_id, step_id)) or (
-            artifact != "-" and not _IDENTIFIER.fullmatch(artifact)
-        ):
-            raise ValueError("Artifact, run ID, and step ID must be safe identifiers")
+        run_id = hashlib.sha256(_string(context.run_id, "run_id").encode("utf-8")).hexdigest()
+        step_id = hashlib.sha256(_string(config["id"], "id").encode("utf-8")).hexdigest()
         digest = hashlib.sha256(body.encode("utf-8")).hexdigest()
         marked_body = (f"{body}\n\n<!-- speckit-github:v2 artifact={artifact} "
                        f"run={run_id} step={step_id} bytes={artifact_bytes} sha256={digest} -->")
         viewer = self._viewer(root, repo)
         existing = []
         for comment in _comments(root, issue_url):
+            if _author(comment) != viewer:
+                continue
             marked = _marked(comment)
             if marked and marked[2:4] == (run_id, step_id):
                 existing.append((comment, marked))
@@ -356,9 +353,9 @@ def _comment(self, config: dict[str, Any], context: StepContext, root: Path,
             raise ValueError("Multiple comments exist for this run and step")
         if existing:
             comment, marked = existing[0]
-            if marked[0] != body or marked[1] != artifact or _author(comment) != viewer:
+            if marked[0] != body or marked[1] != artifact:
                 raise ValueError(
-                    "Existing run/step comment differs or is not owned by the authenticated user"
+                    "Existing run/step comment differs from current content or artifact"
                 )
             comment_id = comment.get("id")
         else:
@@ -380,6 +377,8 @@ def _fetch(self, config: dict[str, Any], context: StepContext, root: Path,
         viewer = self._viewer(root, repo)
         matches = []
         for comment in _comments(root, issue_url):
+            if _author(comment) != viewer:
+                continue
             marked = _marked(comment)
             if marked and marked[1] == config["artifact"]:
                 matches.append((comment, marked[4]))
@@ -389,8 +388,6 @@ def _fetch(self, config: dict[str, Any], context: StepContext, root: Path,
                 f"found {len(matches)}"
             )
         comment, body = matches[0]
-        if _author(comment) != viewer:
-            raise ValueError("GitHub artifact was not posted by the authenticated user")
         comment_id = comment.get("id")
         if not isinstance(comment_id, int) or isinstance(comment_id, bool) or comment_id <= 0:
             raise ValueError("GitHub artifact has no valid comment ID")
diff --git a/tests/workflows/test_github_step.py b/tests/workflows/test_github_step.py
index fa25019cf7..e155d97ea1 100644
--- a/tests/workflows/test_github_step.py
+++ b/tests/workflows/test_github_step.py
@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 from pathlib import Path
+from types import SimpleNamespace
 
 import pytest
 
@@ -98,6 +99,64 @@ def test_comment_retry_is_idempotent_and_changed_content_fails(context, api):
     assert len(comments) == 1
 
 
+def test_valid_punctuated_step_id_posts_and_retries(context, api):
+    comments, _ = api
+    definition = config(id="publish.plan", body="Plan")
+    assert get_step_type("github").validate(definition) == []
+    step = get_step_type("github")
+    assert step.execute(definition, context).status == StepStatus.COMPLETED
+    assert step.execute(definition, context).status == StepStatus.COMPLETED
+    assert len(comments) == 1
+    workflow = WorkflowDefinition.from_string("""
+schema_version: "1.0"
+workflow:
+  id: punctuated-step
+  name: Punctuated step
+  version: "1.0.0"
+steps:
+  - id: publish.plan
+    type: github
+    operation: comment
+    target: issue
+    number: 12
+    body: Plan
+""")
+    engine = WorkflowEngine(Path(context.project_root))
+    assert engine.validate(workflow) == []
+    assert engine.execute(workflow, run_id="new-run").status == RunStatus.COMPLETED
+    assert len(comments) == 2
+
+
+def test_foreign_markers_cannot_block_post_or_fetch(context, api):
+    comments, _ = api
+    step = get_step_type("github")
+    definition = config(body="Original", artifact="report")
+    assert step.execute(definition, context).status == StepStatus.COMPLETED
+    comments.append({"id": 2, "body": "Bad\n\n<!-- speckit-github:v2",
+                     "user": {"login": "stranger"}})
+    comments.append({"id": 3, "body": comments[0]["body"],
+                     "user": {"login": "stranger"}})
+    assert step.execute(definition, context).status == StepStatus.COMPLETED
+    result = step.execute({"id": "fetch", "operation": "fetch-artifact",
+                           "target": "issue", "number": 12, "artifact": "report",
+                           "write_to": "result.md"}, context)
+    assert result.status == StepStatus.COMPLETED, result.error
+    assert (Path(context.project_root) / "result.md").read_text() == "Original"
+    assert len(comments) == 3
+
+
+def test_only_foreign_marker_is_not_a_trusted_artifact(context, api):
+    comments, _ = api
+    step = get_step_type("github")
+    assert step.execute(config(body="Original", artifact="report"), context).status == StepStatus.COMPLETED
+    comments[0]["user"] = {"login": "stranger"}
+    result = step.execute({"id": "fetch", "operation": "fetch-artifact",
+                           "target": "issue", "number": 12, "artifact": "report",
+                           "write_to": "result.md"}, context)
+    assert result.status == StepStatus.FAILED
+    assert "found 0" in result.error
+
+
 def test_comment_files_and_fetch_artifact(context, api):
     comments, _ = api
     root = Path(context.project_root)
@@ -276,7 +335,7 @@ def test_pull_request_comment_uses_issue_comment_endpoint(context, api):
 
 @pytest.mark.parametrize("change,expected", [
     (lambda comments: comments[0].update(body=comments[0]["body"].replace("First", "Altered")), "digest"),
-    (lambda comments: comments[0].update(user={"login": "someone-else"}), "not posted"),
+    (lambda comments: comments[0].update(user={"login": "someone-else"}), "found 0"),
     (lambda comments: comments.append(dict(comments[0], id=2)), "found 2"),
 ])
 def test_fetch_rejects_untrusted_or_ambiguous(context, api, change, expected):
@@ -318,6 +377,14 @@ def test_fetch_rejects_symlinked_missing_parent_and_existing_destination(context
     assert not (tmp_path.parent / "new").exists()
 
 
+def test_windows_write_fails_closed_before_creating_directories(context, monkeypatch):
+    root = Path(context.project_root)
+    monkeypatch.setattr(github, "os", SimpleNamespace(name="nt"))
+    with pytest.raises(ValueError, match="unsupported"):
+        github._write_artifact(root, root / "new" / "report.md", "report")
+    assert not (root / "new").exists()
+
+
 def test_bad_identifiers_and_missing_artifact_fail_without_post(context, api):
     comments, calls = api
     step = get_step_type("github")

From 14acaa81fd4b354e540085625453278a821410f2 Mon Sep 17 00:00:00 2001
From: Manfred Riem <15701806+mnriem@users.noreply.github.com>
Date: Fri, 9 Oct 2026 15:36:45 -0500
Subject: [PATCH 05/10] Support GitHub workflow steps in fan-out

Assisted-by: GitHub Copilot (model: GPT-6 Sol, autonomous)
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: ec94c538-a8b2-4c39-81fc-3ba5f0a59ce6
---
 docs/reference/workflows.md                   |   8 +-
 src/specify_cli/workflows/base.py             |   6 +
 src/specify_cli/workflows/engine.py           |  14 ++
 .../workflows/step/github/__init__.py         |  15 ++-
 tests/workflows/test_github_step.py           | 121 +++++++++++++++++-
 workflows/README.md                           |  10 +-
 6 files changed, 162 insertions(+), 12 deletions(-)

diff --git a/docs/reference/workflows.md b/docs/reference/workflows.md
index 820f90f62a..2a8ff34d27 100644
--- a/docs/reference/workflows.md
+++ b/docs/reference/workflows.md
@@ -649,8 +649,12 @@ closed there rather than writing outside the project.
 `checkout-pr` fetches GitHub's `pull/<number>/head` ref, verifies its SHA
 matches the API's PR head, and checks out that commit detached. Local changes
 that prevent checkout cause the step to fail.
-GitHub steps cannot be nested in `fan-out`: an item has no distinct run/step
-identity for safe comment retries.
+GitHub comments in `fan-out` (including nested branches) use the item's
+parent/step/index path in their retry identity, so identical items still create
+distinct comments and retry without duplicates. Concurrent fan-out comments
+operate on distinct markers. Artifact retrieval in fan-out needs a distinct
+`write_to` path per item; concurrent `checkout-pr` fails explicitly because
+items share a working tree (use sequential fan-out for checkout).
 
 ### Custom step packages
 
diff --git a/src/specify_cli/workflows/base.py b/src/specify_cli/workflows/base.py
index 59d8319d4d..d61ccb1938 100644
--- a/src/specify_cli/workflows/base.py
+++ b/src/specify_cli/workflows/base.py
@@ -59,6 +59,12 @@ class StepContext:
     #: Whether the current step is executing inside a fan-out template.
     inside_fan_out: bool = False
 
+    #: Stable fan-out item path (including parent and item index), for retries.
+    fan_out_key: str | None = None
+
+    #: Number of concurrent workers in the current fan-out.
+    fan_out_concurrency: int = 1
+
     #: Fan-in aggregated results (set only for fan-in steps).
     fan_in: dict[str, Any] = field(default_factory=dict)
 
diff --git a/src/specify_cli/workflows/engine.py b/src/specify_cli/workflows/engine.py
index d7ad0fb857..c7aa3d897d 100644
--- a/src/specify_cli/workflows/engine.py
+++ b/src/specify_cli/workflows/engine.py
@@ -1536,16 +1536,25 @@ def run_item(idx: int, item_ctx: StepContext) -> Any:
             results: list[Any] = []
             previous_item = context.item
             previous_inside_fan_out = context.inside_fan_out
+            previous_fan_out_key = context.fan_out_key
+            previous_fan_out_concurrency = context.fan_out_concurrency
             context.inside_fan_out = True
             try:
                 for item_idx, item_val in enumerate(items):
                     context.item = item_val
+                    item_key = item_id(item_idx)
+                    context.fan_out_key = (
+                        f"{previous_fan_out_key}:{item_key}"
+                        if previous_fan_out_key else item_key
+                    )
                     results.append(run_item(item_idx, context))
                     if state.status in halting:
                         break
             finally:
                 context.item = previous_item
                 context.inside_fan_out = previous_inside_fan_out
+                context.fan_out_key = previous_fan_out_key
+                context.fan_out_concurrency = previous_fan_out_concurrency
             return results
 
         # Concurrent path — bounded sliding window; results assembled in item order.
@@ -1562,6 +1571,11 @@ def run_isolated(idx: int) -> Any:
                     context,
                     item=items[idx],
                     inside_fan_out=True,
+                    fan_out_concurrency=max(context.fan_out_concurrency, workers),
+                    fan_out_key=(
+                        f"{context.fan_out_key}:{item_id(idx)}"
+                        if context.fan_out_key else item_id(idx)
+                    ),
                 ),
             )
 
diff --git a/src/specify_cli/workflows/step/github/__init__.py b/src/specify_cli/workflows/step/github/__init__.py
index 058144d000..31a522f40e 100644
--- a/src/specify_cli/workflows/step/github/__init__.py
+++ b/src/specify_cli/workflows/step/github/__init__.py
@@ -253,16 +253,16 @@ def execute(self, config: dict[str, Any], context: StepContext) -> StepResult:
                 raise ValueError("; ".join(errors))
             if not context.project_root:
                 raise ValueError("GitHub step requires a project root")
-            if context.inside_fan_out:
-                raise ValueError(
-                    "GitHub steps cannot run inside fan-out "
-                    "(run/step retry identity is not unique per item)"
-                )
             root = Path(context.project_root).resolve()
             repo, url = _identity(root)
             number = _number(_resolved(config["number"], context))
             operation = config["operation"]
             if operation == "checkout-pr":
+                if context.inside_fan_out and context.fan_out_concurrency > 1:
+                    raise ValueError(
+                        "checkout-pr cannot run concurrently in fan-out "
+                        "because items share one working tree"
+                    )
                 return self._checkout(root, url, number)
             target = config["target"]
             resource_kind = "pulls" if target == "pull_request" else "issues"
@@ -337,7 +337,10 @@ def _comment(self, config: dict[str, Any], context: StepContext, root: Path,
             )
         artifact = config.get("artifact", "-")
         run_id = hashlib.sha256(_string(context.run_id, "run_id").encode("utf-8")).hexdigest()
-        step_id = hashlib.sha256(_string(config["id"], "id").encode("utf-8")).hexdigest()
+        step_name = _string(config["id"], "id")
+        if context.fan_out_key is not None:
+            step_name = f"{context.fan_out_key}\0{step_name}"
+        step_id = hashlib.sha256(step_name.encode("utf-8")).hexdigest()
         digest = hashlib.sha256(body.encode("utf-8")).hexdigest()
         marked_body = (f"{body}\n\n<!-- speckit-github:v2 artifact={artifact} "
                        f"run={run_id} step={step_id} bytes={artifact_bytes} sha256={digest} -->")
diff --git a/tests/workflows/test_github_step.py b/tests/workflows/test_github_step.py
index e155d97ea1..9d19d2347b 100644
--- a/tests/workflows/test_github_step.py
+++ b/tests/workflows/test_github_step.py
@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 from pathlib import Path
+from textwrap import indent
 from types import SimpleNamespace
 
 import pytest
@@ -321,6 +322,120 @@ def test_engine_executes_github_yaml_without_shell(context, api):
     assert len(comments) == 1
 
 
+@pytest.mark.parametrize("workers", [1, 3])
+@pytest.mark.parametrize("nested", [False, True])
+def test_github_comment_fan_out_retries_per_index(context, api, workers, nested):
+    comments, calls = api
+    if nested:
+        template = """id: branch
+type: if
+condition: true
+then:
+  - id: publish
+    type: github
+    operation: comment
+    target: issue
+    number: 12
+    body: "same content"
+"""
+    else:
+        template = """id: publish
+type: github
+operation: comment
+target: issue
+number: 12
+body: "same content"
+"""
+    workflow = WorkflowDefinition.from_string("""
+schema_version: "1.0"
+workflow:
+  id: fan-out-github
+  name: Fan-out GitHub
+  version: "1.0.0"
+steps:
+  - id: fan
+    type: fan-out
+    items: "{{ ['same', 'same', 'same'] }}"
+    max_concurrency: WORKERS
+    step:
+TEMPLATE
+""".replace("WORKERS", str(workers)).replace("TEMPLATE", indent(template, "      ").rstrip()))
+    engine = WorkflowEngine(Path(context.project_root))
+    assert engine.validate(workflow) == []
+    assert engine.execute(workflow, run_id="fan-run").status == RunStatus.COMPLETED
+    assert len(comments) == 3
+    assert engine.execute(workflow, run_id="fan-run").status == RunStatus.COMPLETED
+    assert len(comments) == 3
+    assert len([method for method, _ in calls if method == "POST"]) == 3
+
+
+def test_github_fetch_artifact_fan_out_writes_distinct_paths(context, api):
+    root = Path(context.project_root)
+    step = get_step_type("github")
+    assert step.execute(config(body="Shared", artifact="report"), context).status == StepStatus.COMPLETED
+    workflow = WorkflowDefinition.from_string("""
+schema_version: "1.0"
+workflow:
+  id: fetch-fan-out
+  name: Fetch fan-out
+  version: "1.0.0"
+steps:
+  - id: fetch-all
+    type: fan-out
+    items: "{{ ['one', 'two'] }}"
+    max_concurrency: 2
+    step:
+      id: fetch
+      type: github
+      operation: fetch-artifact
+      target: issue
+      number: 12
+      artifact: report
+      write_to: "artifacts/{{ item }}.md"
+""")
+    engine = WorkflowEngine(root)
+    assert engine.validate(workflow) == []
+    assert engine.execute(workflow).status == RunStatus.COMPLETED
+    assert (root / "artifacts" / "one.md").read_text() == "Shared"
+    assert (root / "artifacts" / "two.md").read_text() == "Shared"
+
+
+@pytest.mark.parametrize("workers,expected", [(1, RunStatus.COMPLETED), (2, RunStatus.FAILED)])
+def test_checkout_pr_fan_out_requires_sequential_worktree(context, api, monkeypatch,
+                                                         workers, expected):
+    calls = []
+
+    def fake_run(args, root, *, input_text=None):
+        calls.append(args)
+        return "a" * 40 if args[:2] == ["git", "rev-parse"] else ""
+
+    monkeypatch.setattr(github, "_run", fake_run)
+    workflow = WorkflowDefinition.from_string("""
+schema_version: "1.0"
+workflow:
+  id: checkout-fan-out
+  name: Checkout fan-out
+  version: "1.0.0"
+steps:
+  - id: checkouts
+    type: fan-out
+    items: "{{ [7, 7] }}"
+    max_concurrency: WORKERS
+    step:
+      id: checkout
+      type: github
+      operation: checkout-pr
+      number: "{{ item }}"
+""".replace("WORKERS", str(workers)))
+    state = WorkflowEngine(Path(context.project_root)).execute(workflow)
+    assert state.status == expected
+    if workers == 1:
+        assert len([call for call in calls if call[:2] == ["git", "fetch"]]) == 2
+    else:
+        assert not calls
+        assert "share one working tree" in state.error
+
+
 def test_pull_request_comment_uses_issue_comment_endpoint(context, api):
     comments, calls = api
     definition = config(body="PR feedback", target="pull_request", number=7)
@@ -400,7 +515,7 @@ def test_bad_identifiers_and_missing_artifact_fail_without_post(context, api):
     assert not any(method == "POST" for method, _ in calls)
 
 
-def test_comment_rejects_symlinked_source_and_fan_out(context, api, tmp_path):
+def test_comment_rejects_symlinked_source_inside_fan_out(context, api, tmp_path):
     root = Path(context.project_root)
     (root / "link.md").symlink_to(tmp_path.parent / "outside.md")
     step = get_step_type("github")
@@ -408,9 +523,9 @@ def test_comment_rejects_symlinked_source_and_fan_out(context, api, tmp_path):
     assert result.status == StepStatus.FAILED
     assert "Symlinked" in result.error
     context.inside_fan_out = True
+    context.fan_out_key = "fan:post:0"
     result = step.execute(config(body="hi"), context)
-    assert result.status == StepStatus.FAILED
-    assert "fan-out" in result.error
+    assert result.status == StepStatus.COMPLETED
 
 
 def test_api_error_fails_without_success_shaped_output(context, api, monkeypatch):
diff --git a/workflows/README.md b/workflows/README.md
index ccca55aee9..b55ff34795 100644
--- a/workflows/README.md
+++ b/workflows/README.md
@@ -85,7 +85,7 @@ The bundled `speckit` workflow only declares `spec` (and optional
 
 ## Step Types
 
-Workflows support 12 built-in step types:
+Workflows support 13 built-in step types:
 
 ### Command Steps (default)
 
@@ -172,6 +172,14 @@ killed and the step fails; it must be a positive number and defaults to
 `300` (five minutes) when omitted. Raise it for long-running gates such as
 full builds, linter aggregators, or integration-test targets.
 
+### GitHub Steps
+
+The built-in `github` step posts comments, retrieves workflow-posted artifacts,
+or checks out a PR head when a workflow explicitly uses `type: github`. It
+does not install or invoke the opt-in GitHub agent-command extension. See the
+[GitHub step reference](../docs/reference/workflows.md#github-step) for the
+operations, credentials, retry behavior, and fan-out constraints.
+
 ### Init Steps
 
 Bootstrap a project the same way `specify init` does — scaffolding

From f37ba1d49467bc0746eab4926bf19693c10a9001 Mon Sep 17 00:00:00 2001
From: Manfred Riem <15701806+mnriem@users.noreply.github.com>
Date: Fri, 9 Oct 2026 15:47:22 -0500
Subject: [PATCH 06/10] Limit built-in GitHub workflow step to explicit labels

Remove comment, artifact, and PR checkout operations from the first release. Keep retries idempotent by checking existing issue or PR labels before adding the requested label, and document the smaller contract.

Assisted-by: GitHub Copilot (model: GPT-6 Sol, autonomous)

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot-Session: ec94c538-a8b2-4c39-81fc-3ba5f0a59ce6
---
 docs/reference/workflows.md                   |  81 +-
 extensions/github/README.md                   |   2 +-
 src/specify_cli/workflows/base.py             |   6 -
 src/specify_cli/workflows/engine.py           |  14 -
 .../workflows/step/github/__init__.py         | 427 +++--------
 tests/workflows/test_github_step.py           | 714 +++++-------------
 workflows/ARCHITECTURE.md                     |   2 +-
 workflows/README.md                           |  10 +-
 8 files changed, 296 insertions(+), 960 deletions(-)

diff --git a/docs/reference/workflows.md b/docs/reference/workflows.md
index 2a8ff34d27..eb6fb322c2 100644
--- a/docs/reference/workflows.md
+++ b/docs/reference/workflows.md
@@ -570,7 +570,7 @@ specify workflow run speckit -i spec="Build a kanban board with drag-and-drop ta
 | `command`    | Invoke a Spec Kit command (e.g., `speckit.plan`) |
 | `prompt`     | Send an arbitrary prompt to the AI coding agent  |
 | `shell`      | Execute a shell command and capture output       |
-| `github`     | Post/retrieve GitHub comments or check out a PR   |
+| `github`     | Add an explicit issue or pull-request label       |
 | `init`       | Bootstrap a project (like `specify init`)        |
 | `slot`       | Named workflow slot; skipped when unfilled       |
 | `gate`       | Pause for human approval before continuing       |
@@ -586,75 +586,32 @@ specify workflow run speckit -i spec="Build a kanban board with drag-and-drop ta
 ### GitHub step
 
 `type: github` uses the installed `gh` CLI and its active authentication for a
-repository whose `origin` points to `github.com`. The token needs read access
-for PRs/issues, and issue-comment write access only for `comment`. The step
-does not request or elevate permissions. It does not interpret issue/comment
-contents as workflow instructions or apply labels. GitHub operations require
-network access; tests should mock the API rather than post live comments.
-In GitHub Actions, a repository-scoped `GITHUB_TOKEN` is supported: when
-`GITHUB_ACTIONS=true` and `GITHUB_REPOSITORY` matches `origin`, the step
-verifies that the active credential is an installation token restricted to
-that repository, then checks the author against `github-actions[bot]`.
-User tokens (including user tokens used inside Actions) use `GET /user` for
-author verification instead. A non-Actions app token cannot post as
-`github-actions[bot]`; an unexpected post author fails the step.
+repository whose `origin` points to `github.com`. The active token needs
+permission to read the issue or pull request and to write its labels (for
+example, `issues: write` for issues or `pull-requests: write` for PRs when
+using `GITHUB_TOKEN` in Actions). The step uses only the existing token: it
+does not request or elevate permissions. It does not inspect issue contents
+for instructions or make a maintainer decision.
 
 ```yaml
-- id: publish-plan
+- id: mark-ready
   type: github
-  operation: comment
+  operation: add-label
   target: issue
   number: "{{ inputs.issue_number }}"
-  body_file: docs/plan.md
-  artifact: reviewed-plan
-  maintainer_action:
-    summary: "Review the plan before scheduling implementation."
-    possible_labels: [ready-for-review]
-
-- id: retrieve-plan
-  type: github
-  operation: fetch-artifact
-  target: issue
-  number: "{{ inputs.issue_number }}"
-  artifact: reviewed-plan
-  write_to: docs/retrieved-plan.md
-
-- id: checkout
-  type: github
-  operation: checkout-pr
-  number: "{{ inputs.pr_number }}"
+  label: ready-for-review
 ```
 
-For `comment`, supply exactly one of `body` (text), `body_file` (UTF-8 file),
-or `body_files` (non-empty list of UTF-8 files joined with two newlines).
 `target` is `issue` or `pull_request`; `number` must resolve to a positive
-integer. `artifact` is an optional stable alphanumeric identifier (hyphens
-and underscores allowed), required by `fetch-artifact`. `maintainer_action`
-adds a **proposal only** section with `summary` and `possible_labels` to the
-comment; it never changes GitHub labels. The posted comment includes a
-digest-bearing marker tying it to the workflow run and step. Re-running the
-same step in the same run reuses an identical comment rather than posting a
-duplicate; changed content or a changed author fails instead. `fetch-artifact`
-requires exactly one intact, previously marked comment authored by the
-verified account/bot. It writes only the original artifact bytes, excluding
-the maintainer-action footer and marker, to a *new* relative file under the
-project root. Missing parent directories are created inside the project
-after the comment is verified; symlinks and overwrites are refused. Run and
-step IDs are hashed in the marker so workflow-valid IDs (including dots)
-remain valid. Foreign-authored comments are ignored before parsing markers;
-malformed markers from the verified author fail explicitly. This implementation
-does not provide handle-anchored writes on Windows, so `fetch-artifact` fails
-closed there rather than writing outside the project.
-
-`checkout-pr` fetches GitHub's `pull/<number>/head` ref, verifies its SHA
-matches the API's PR head, and checks out that commit detached. Local changes
-that prevent checkout cause the step to fail.
-GitHub comments in `fan-out` (including nested branches) use the item's
-parent/step/index path in their retry identity, so identical items still create
-distinct comments and retry without duplicates. Concurrent fan-out comments
-operate on distinct markers. Artifact retrieval in fan-out needs a distinct
-`write_to` path per item; concurrent `checkout-pr` fails explicitly because
-items share a working tree (use sequential fan-out for checkout).
+integer. `label` is one explicit label name (up to 50 characters) and must
+already exist in the repository. Both values may use workflow expressions.
+The step checks the target type and its existing labels, skips the write when
+the label is already present, and verifies GitHub's response after adding it.
+The output includes `repository`, `target`, `number`, `label`, and `added`
+(`true` only when a label was added). Repeated execution and fan-out items
+are safe to retry: an already-present label is left unchanged. This first
+version does not post comments, restore artifacts, check out PRs, or infer
+which label a maintainer would choose.
 
 ### Custom step packages
 
diff --git a/extensions/github/README.md b/extensions/github/README.md
index b25d2c5fd6..06e38dd67b 100644
--- a/extensions/github/README.md
+++ b/extensions/github/README.md
@@ -1,6 +1,6 @@
 # GitHub Integration Extension
 
-This bundled, **opt-in** extension owns Spec Kit's GitHub *agent command* functionality. Today it provides one command, `speckit.github.taskstoissues`, which turns a feature's `tasks.md` into dependency-ordered GitHub issues. The separate built-in [`github` workflow step](../../docs/reference/workflows.md#github-step) is a deterministic workflow building block for comments, artifacts, and PR checkout: registering the step does not install this extension or invoke the step automatically. A workflow must explicitly select `type: github` to run it.
+This bundled, **opt-in** extension owns Spec Kit's GitHub *agent command* functionality. Today it provides one command, `speckit.github.taskstoissues`, which turns a feature's `tasks.md` into dependency-ordered GitHub issues. The separate built-in [`github` workflow step](../../docs/reference/workflows.md#github-step) adds an explicitly configured issue or pull-request label: registering the step does not install this extension or invoke the step automatically. A workflow must explicitly select `type: github` to run it.
 
 > NOTE: `git` and `github` are deliberately separate domains. The [`git` extension](../git/README.md) owns local version-control workflow (feature branches, commits, remote detection); this extension owns its GitHub agent command, not the workflow engine's built-in step.
 
diff --git a/src/specify_cli/workflows/base.py b/src/specify_cli/workflows/base.py
index d61ccb1938..59d8319d4d 100644
--- a/src/specify_cli/workflows/base.py
+++ b/src/specify_cli/workflows/base.py
@@ -59,12 +59,6 @@ class StepContext:
     #: Whether the current step is executing inside a fan-out template.
     inside_fan_out: bool = False
 
-    #: Stable fan-out item path (including parent and item index), for retries.
-    fan_out_key: str | None = None
-
-    #: Number of concurrent workers in the current fan-out.
-    fan_out_concurrency: int = 1
-
     #: Fan-in aggregated results (set only for fan-in steps).
     fan_in: dict[str, Any] = field(default_factory=dict)
 
diff --git a/src/specify_cli/workflows/engine.py b/src/specify_cli/workflows/engine.py
index c7aa3d897d..d7ad0fb857 100644
--- a/src/specify_cli/workflows/engine.py
+++ b/src/specify_cli/workflows/engine.py
@@ -1536,25 +1536,16 @@ def run_item(idx: int, item_ctx: StepContext) -> Any:
             results: list[Any] = []
             previous_item = context.item
             previous_inside_fan_out = context.inside_fan_out
-            previous_fan_out_key = context.fan_out_key
-            previous_fan_out_concurrency = context.fan_out_concurrency
             context.inside_fan_out = True
             try:
                 for item_idx, item_val in enumerate(items):
                     context.item = item_val
-                    item_key = item_id(item_idx)
-                    context.fan_out_key = (
-                        f"{previous_fan_out_key}:{item_key}"
-                        if previous_fan_out_key else item_key
-                    )
                     results.append(run_item(item_idx, context))
                     if state.status in halting:
                         break
             finally:
                 context.item = previous_item
                 context.inside_fan_out = previous_inside_fan_out
-                context.fan_out_key = previous_fan_out_key
-                context.fan_out_concurrency = previous_fan_out_concurrency
             return results
 
         # Concurrent path — bounded sliding window; results assembled in item order.
@@ -1571,11 +1562,6 @@ def run_isolated(idx: int) -> Any:
                     context,
                     item=items[idx],
                     inside_fan_out=True,
-                    fan_out_concurrency=max(context.fan_out_concurrency, workers),
-                    fan_out_key=(
-                        f"{context.fan_out_key}:{item_id(idx)}"
-                        if context.fan_out_key else item_id(idx)
-                    ),
                 ),
             )
 
diff --git a/src/specify_cli/workflows/step/github/__init__.py b/src/specify_cli/workflows/step/github/__init__.py
index 31a522f40e..39439b229a 100644
--- a/src/specify_cli/workflows/step/github/__init__.py
+++ b/src/specify_cli/workflows/step/github/__init__.py
@@ -1,10 +1,8 @@
-"""GitHub workflow step: post comments, retrieve posted artifacts, or check out a PR."""
+"""GitHub workflow step: add an explicit label to an issue or pull request."""
 
 from __future__ import annotations
 
-import hashlib
 import json
-import os
 import re
 import subprocess
 from pathlib import Path
@@ -13,121 +11,53 @@
 from specify_cli.workflows.base import StepBase, StepContext, StepResult, StepStatus
 from specify_cli.workflows.expressions import evaluate_expression
 
-_IDENTIFIER = re.compile(r"[A-Za-z0-9][A-Za-z0-9_-]{0,99}\Z")
 _NUMBER = re.compile(r"[1-9][0-9]*\Z")
 _ORIGIN = re.compile(
     r"(?:https://github\.com/|git@github\.com:)([A-Za-z0-9_.-]+)/([A-Za-z0-9_.-]+?)(?:\.git)?/?\Z"
 )
-_MARKER = re.compile(
-    r"<!-- speckit-github:v2 artifact=([A-Za-z0-9_-]+) "
-    r"run=([a-f0-9]{64}) step=([a-f0-9]{64}) "
-    r"bytes=([0-9]+) sha256=([a-f0-9]{64}) -->\Z"
-)
-_MARKER_PREFIX = "<!-- speckit-github:"
 
 
 def _run(args: list[str], root: Path, *, input_text: str | None = None) -> str:
     try:
         result = subprocess.run(
-            args, cwd=root, input=input_text, capture_output=True, text=True,
-            timeout=60, check=False,
+            args,
+            cwd=root,
+            input=input_text,
+            capture_output=True,
+            text=True,
+            timeout=60,
+            check=False,
         )
     except (OSError, subprocess.TimeoutExpired) as exc:
         raise ValueError(f"{args[0]} request failed: {exc}") from exc
     if result.returncode:
-        # Do not echo CLI stderr: authentication errors can contain sensitive data.
-        raise ValueError(
-            f"{args[0]} request failed (exit code {result.returncode}): "
-            f"{' '.join(args[1:3])}"
-        )
+        # CLI stderr may contain authentication details; never include it in run state.
+        raise ValueError(f"{args[0]} request failed (exit code {result.returncode})")
     return result.stdout.strip()
 
 
-def _api(root: Path, endpoint: str, *, method: str = "GET", data: dict[str, str] | None = None,
-         paginated: bool = False) -> Any:
+def _api(root: Path, endpoint: str, *, labels: list[str] | None = None) -> Any:
+    method = "POST" if labels is not None else "GET"
     args = ["gh", "api", "--method", method, endpoint]
-    if paginated:
-        args.extend(["--paginate", "--slurp"])
-    if data is not None:
+    if labels is not None:
         args.extend(["--input", "-"])
-    raw = _run(args, root, input_text=json.dumps(data) if data is not None else None)
+    raw = _run(
+        args,
+        root,
+        input_text=json.dumps({"labels": labels}) if labels is not None else None,
+    )
     try:
         return json.loads(raw)
     except json.JSONDecodeError as exc:
         raise ValueError(f"GitHub returned invalid JSON for {endpoint}") from exc
 
 
-def _project_path(root: Path, value: str, *, writing: bool) -> Path:
-    path = Path(value)
-    if (not value or path.is_absolute() or "\\" in value
-            or any(part in ("..", ".") for part in value.split("/"))):
-        raise ValueError(f"Path must be relative and inside the project: {value!r}")
-    candidate = root / path
-    if candidate == root:
-        raise ValueError("Path must name a file inside the project")
-    current = root
-    for part in path.parts:
-        current = current / part
-        if current.is_symlink():
-            raise ValueError(f"Symlinked paths are not allowed: {value!r}")
-    if not candidate.resolve().is_relative_to(root.resolve()):
-        raise ValueError(f"Path escapes the project: {value!r}")
-    if writing:
-        if candidate.exists():
-            raise ValueError(f"Destination already exists: {value!r}")
-    elif not candidate.is_file():
-        raise ValueError(f"File does not exist: {value!r}")
-    return candidate
-
-
-def _write_artifact(root: Path, destination: Path, body: str) -> None:
-    """Create a new file through directory handles; refuse symlinked parents."""
-    if (os.name == "nt" or not hasattr(os, "O_DIRECTORY")
-            or not hasattr(os, "O_NOFOLLOW")
-            or os.open not in os.supports_dir_fd
-            or os.mkdir not in os.supports_dir_fd):
-        raise ValueError("Safe artifact writes are unsupported on this platform")
-
-    data = body.encode("utf-8")
-    flags = os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW
-    directory = os.open(root, flags)
-    try:
-        for part in destination.relative_to(root).parts[:-1]:
-            try:
-                child = os.open(part, flags, dir_fd=directory)
-            except FileNotFoundError:
-                try:
-                    os.mkdir(part, dir_fd=directory)
-                except FileExistsError:
-                    pass
-                child = os.open(part, flags, dir_fd=directory)
-            os.close(directory)
-            directory = child
-        name = destination.name
-        fd = os.open(name, os.O_WRONLY | os.O_CREAT | os.O_EXCL | os.O_NOFOLLOW,
-                     0o600, dir_fd=directory)
-        try:
-            with os.fdopen(fd, "wb") as stream:
-                stream.write(data)
-        except OSError:
-            os.unlink(name, dir_fd=directory)
-            raise
-    finally:
-        os.close(directory)
-
-
 def _resolved(value: Any, context: StepContext) -> Any:
     if isinstance(value, str) and "{{" in value:
         return evaluate_expression(value, context)
     return value
 
 
-def _string(value: Any, name: str) -> str:
-    if not isinstance(value, str) or not value.strip():
-        raise ValueError(f"'{name}' must be a non-empty string")
-    return value
-
-
 def _number(value: Any) -> int:
     if isinstance(value, bool) or not (
         (isinstance(value, int) and value > 0)
@@ -137,75 +67,58 @@ def _number(value: Any) -> int:
     return int(value)
 
 
+def _label(value: Any) -> str:
+    if (
+        not isinstance(value, str)
+        or not value.strip()
+        or len(value) > 50
+        or any(ord(char) < 32 or ord(char) == 127 for char in value)
+    ):
+        raise ValueError(
+            "'label' must be a non-empty label name of at most 50 characters without control characters"
+        )
+    return value
+
+
+def _label_names(value: Any) -> set[str]:
+    if not isinstance(value, list) or not all(
+        isinstance(entry, dict) and isinstance(entry.get("name"), str)
+        for entry in value
+    ):
+        raise ValueError("GitHub returned an invalid label list")
+    return {entry["name"].casefold() for entry in value}
+
+
 def _identity(root: Path) -> tuple[str, str]:
     origin = _run(["git", "remote", "get-url", "origin"], root)
     match = _ORIGIN.fullmatch(origin)
     if not match:
         raise ValueError("GitHub step requires a github.com origin remote")
-    repo = f"{match[1]}/{match[2]}"
-    # Use absolute API endpoints; a GH_HOST override must not redirect requests
-    # to an unexpected host. gh manages authentication without exposing a token.
-    return repo, f"https://api.github.com/repos/{repo}"
-
-
-def _comments(root: Path, url: str) -> list[dict[str, Any]]:
-    pages = _api(root, f"{url}/comments?per_page=100", paginated=True)
-    if not isinstance(pages, list) or not all(isinstance(page, list) for page in pages):
-        raise ValueError("GitHub returned an invalid comment list")
-    comments = [comment for page in pages for comment in page]
-    if not all(isinstance(comment, dict) for comment in comments):
-        raise ValueError("GitHub returned an invalid comment")
-    return comments
-
-
-def _marked(comment: dict[str, Any]) -> tuple[str, str, str, str, str] | None:
-    text = comment.get("body")
-    if not isinstance(text, str) or _MARKER_PREFIX not in text:
-        return None
-    body, sep, marker = text.rpartition("\n\n")
-    match = _MARKER.fullmatch(marker) if sep else None
-    encoded = body.encode("utf-8")
-    if not match or hashlib.sha256(encoded).hexdigest() != match[5]:
-        raise ValueError("GitHub artifact has an invalid marker or content digest")
-    artifact_bytes = int(match[4])
-    if artifact_bytes > len(encoded):
-        raise ValueError("GitHub artifact has an invalid byte length")
-    try:
-        artifact = encoded[:artifact_bytes].decode("utf-8")
-    except UnicodeDecodeError as exc:
-        raise ValueError("GitHub artifact has an invalid UTF-8 boundary") from exc
-    return body, match[1], match[2], match[3], artifact
-
-
-def _author(comment: dict[str, Any]) -> str | None:
-    user = comment.get("user")
-    return user.get("login") if isinstance(user, dict) else None
+    repository = f"{match[1]}/{match[2]}"
+    return repository, f"https://api.github.com/repos/{repository}"
 
 
 class GitHubStep(StepBase):
-    """Run bounded GitHub operations through an authenticated gh CLI."""
+    """Add only the label explicitly specified by a workflow author."""
 
     type_key = "github"
 
     def validate(self, config: dict[str, Any]) -> list[str]:
         errors = super().validate(config)
-        operation = config.get("operation")
-        if operation not in ("comment", "fetch-artifact", "checkout-pr"):
-            errors.append(
-                "GitHub step 'operation' must be comment, fetch-artifact, or checkout-pr."
-            )
-            return errors
-        expected = {
-            "comment": {"id", "type", "operation", "target", "number", "body", "body_file",
-                        "body_files", "artifact", "maintainer_action", "continue_on_error"},
-            "fetch-artifact": {"id", "type", "operation", "target", "number", "artifact",
-                               "write_to", "continue_on_error"},
-            "checkout-pr": {"id", "type", "operation", "number", "continue_on_error"},
-        }[operation]
-        for key in config.keys() - expected:
-            errors.append(f"GitHub step has unsupported field {key!r}.")
-        if operation != "checkout-pr" and config.get("target") not in ("issue", "pull_request"):
+        if config.get("operation") != "add-label":
+            errors.append("GitHub step 'operation' must be add-label.")
+        if config.get("target") not in ("issue", "pull_request"):
             errors.append("GitHub step 'target' must be issue or pull_request.")
+        for key in config.keys() - {
+            "id",
+            "type",
+            "operation",
+            "target",
+            "number",
+            "label",
+            "continue_on_error",
+        }:
+            errors.append(f"GitHub step has unsupported field {key!r}.")
         if "number" not in config:
             errors.append("GitHub step requires 'number'.")
         elif not (isinstance(config["number"], str) and "{{" in config["number"]):
@@ -213,37 +126,13 @@ def validate(self, config: dict[str, Any]) -> list[str]:
                 _number(config["number"])
             except ValueError as exc:
                 errors.append(str(exc))
-        if operation == "comment":
-            if sum(key in config for key in ("body", "body_file", "body_files")) != 1:
-                errors.append("GitHub comment requires exactly one of body, body_file, body_files.")
-            if "body_files" in config and (
-                not isinstance(config["body_files"], list) or not config["body_files"]
-                or not all(isinstance(v, str) and v.strip() for v in config["body_files"])
-            ):
-                errors.append("'body_files' must be a non-empty list of paths.")
-            action = config.get("maintainer_action")
-            if action is not None and (
-                not isinstance(action, dict) or set(action) != {"summary", "possible_labels"}
-                or not isinstance(action["summary"], str)
-                or not isinstance(action["possible_labels"], list)
-                or not all(isinstance(v, str) and v.strip() for v in action["possible_labels"])
-            ):
-                errors.append(
-                    "'maintainer_action' requires a summary and a list of possible_labels."
-                )
-        if operation == "fetch-artifact" and "write_to" not in config:
-            errors.append("GitHub fetch-artifact requires 'write_to'.")
-        if "artifact" in config and not (
-            isinstance(config["artifact"], str) and _IDENTIFIER.fullmatch(config["artifact"])
-        ):
-            errors.append(
-                "'artifact' must be a stable alphanumeric identifier (hyphens/underscores allowed)."
-            )
-        if operation == "fetch-artifact" and "artifact" not in config:
-            errors.append("GitHub fetch-artifact requires 'artifact'.")
-        for name in ("body", "body_file", "write_to"):
-            if name in config and not isinstance(config[name], str):
-                errors.append(f"'{name}' must be a string.")
+        if "label" not in config:
+            errors.append("GitHub step requires 'label'.")
+        elif not (isinstance(config["label"], str) and "{{" in config["label"]):
+            try:
+                _label(config["label"])
+            except ValueError as exc:
+                errors.append(str(exc))
         return errors
 
     def execute(self, config: dict[str, Any], context: StepContext) -> StepResult:
@@ -251,171 +140,39 @@ def execute(self, config: dict[str, Any], context: StepContext) -> StepResult:
             errors = self.validate(config)
             if errors:
                 raise ValueError("; ".join(errors))
+            number = _number(_resolved(config["number"], context))
+            label = _label(_resolved(config["label"], context))
             if not context.project_root:
                 raise ValueError("GitHub step requires a project root")
             root = Path(context.project_root).resolve()
-            repo, url = _identity(root)
-            number = _number(_resolved(config["number"], context))
-            operation = config["operation"]
-            if operation == "checkout-pr":
-                if context.inside_fan_out and context.fan_out_concurrency > 1:
-                    raise ValueError(
-                        "checkout-pr cannot run concurrently in fan-out "
-                        "because items share one working tree"
-                    )
-                return self._checkout(root, url, number)
+            repository, url = _identity(root)
             target = config["target"]
-            resource_kind = "pulls" if target == "pull_request" else "issues"
-            resource = _api(root, f"{url}/{resource_kind}/{number}")
-            if (not isinstance(resource, dict) or resource.get("number") != number
-                    or (target == "issue" and "pull_request" in resource)):
-                raise ValueError(f"GitHub {target} #{number} does not match the requested target")
-            issue_url = f"{url}/issues/{number}"
-            if operation == "comment":
-                return self._comment(config, context, root, repo, issue_url, number)
-            return self._fetch(config, context, root, repo, issue_url)
-        except (ValueError, OSError, UnicodeError) as exc:
-            return StepResult(status=StepStatus.FAILED, error=f"GitHub step: {exc}")
-
-    @staticmethod
-    def _viewer(root: Path, repo: str) -> str:
-        if (os.environ.get("GITHUB_ACTIONS") == "true"
-                and os.environ.get("GITHUB_REPOSITORY", "").lower() == repo.lower()):
-            try:
-                installation = _api(
-                    root, "https://api.github.com/installation/repositories"
+            kind = "pulls" if target == "pull_request" else "issues"
+            resource = _api(root, f"{url}/{kind}/{number}")
+            if (
+                not isinstance(resource, dict)
+                or resource.get("number") != number
+                or (target == "issue" and "pull_request" in resource)
+            ):
+                raise ValueError(
+                    f"GitHub {target} #{number} does not match the requested target"
                 )
-            except ValueError:
-                # A user token used inside Actions does not have this installation
-                # endpoint. It must identify itself through /user instead.
-                pass
-            else:
-                repositories = installation.get("repositories") if isinstance(installation, dict) else None
-                if (not isinstance(repositories, list)
-                        or installation.get("total_count") != 1
-                        or len(repositories) != 1
-                        or not isinstance(repositories[0], dict)
-                        or not isinstance(repositories[0].get("full_name"), str)
-                        or repositories[0]["full_name"].lower() != repo.lower()):
-                    raise ValueError(
-                        "Actions installation token must be scoped to this repository only"
-                    )
-                return "github-actions[bot]"
-        user = _api(root, "https://api.github.com/user")
-        if not isinstance(user, dict):
-            raise ValueError("GitHub returned an invalid authenticated user")
-        return _string(user.get("login"), "authenticated user login")
-
-    def _comment(self, config: dict[str, Any], context: StepContext, root: Path,
-                 repo: str, issue_url: str, number: int) -> StepResult:
-        if "body" in config:
-            body = _string(_resolved(config["body"], context), "body")
-        elif "body_file" in config:
-            source = _string(_resolved(config["body_file"], context), "body_file")
-            path = _project_path(root, source, writing=False)
-            body = path.read_bytes().decode("utf-8")
-        else:
-            paths = [
-                _project_path(root, _string(_resolved(p, context), "body_files entry"), writing=False)
-                for p in config["body_files"]
-            ]
-            body = "\n\n".join(path.read_bytes().decode("utf-8") for path in paths)
-        if not body.strip():
-            raise ValueError("Comment body must not be empty")
-        artifact_bytes = len(body.encode("utf-8"))
-        action = config.get("maintainer_action")
-        if action is not None:
-            summary = _string(_resolved(action["summary"], context), "maintainer_action.summary")
-            labels = [
-                _string(_resolved(label, context), "possible_labels")
-                for label in action["possible_labels"]
-            ]
-            proposed = ", ".join(labels) if labels else "None"
-            body += (
-                f"\n\n### Maintainer action (proposal only)\n{summary}"
-                f"\n\nPossible labels: {proposed}"
-            )
-        artifact = config.get("artifact", "-")
-        run_id = hashlib.sha256(_string(context.run_id, "run_id").encode("utf-8")).hexdigest()
-        step_name = _string(config["id"], "id")
-        if context.fan_out_key is not None:
-            step_name = f"{context.fan_out_key}\0{step_name}"
-        step_id = hashlib.sha256(step_name.encode("utf-8")).hexdigest()
-        digest = hashlib.sha256(body.encode("utf-8")).hexdigest()
-        marked_body = (f"{body}\n\n<!-- speckit-github:v2 artifact={artifact} "
-                       f"run={run_id} step={step_id} bytes={artifact_bytes} sha256={digest} -->")
-        viewer = self._viewer(root, repo)
-        existing = []
-        for comment in _comments(root, issue_url):
-            if _author(comment) != viewer:
-                continue
-            marked = _marked(comment)
-            if marked and marked[2:4] == (run_id, step_id):
-                existing.append((comment, marked))
-        if len(existing) > 1:
-            raise ValueError("Multiple comments exist for this run and step")
-        if existing:
-            comment, marked = existing[0]
-            if marked[0] != body or marked[1] != artifact:
+            existing = _label_names(resource.get("labels"))
+            output = {
+                "repository": repository,
+                "target": target,
+                "number": number,
+                "label": label,
+                "added": False,
+            }
+            if label.casefold() in existing:
+                return StepResult(output=output)
+            labels = _api(root, f"{url}/issues/{number}/labels", labels=[label])
+            if label.casefold() not in _label_names(labels):
                 raise ValueError(
-                    "Existing run/step comment differs from current content or artifact"
+                    f"GitHub did not apply label {label!r} to {target} #{number}"
                 )
-            comment_id = comment.get("id")
-        else:
-            posted = _api(root, f"{issue_url}/comments", method="POST", data={"body": marked_body})
-            if not isinstance(posted, dict):
-                raise ValueError("GitHub returned an invalid posted comment")
-            if _author(posted) != viewer:
-                raise ValueError("Posted comment author does not match the authenticated identity")
-            comment_id = posted.get("id")
-        if not isinstance(comment_id, int) or isinstance(comment_id, bool) or comment_id <= 0:
-            raise ValueError("GitHub comment has no valid ID")
-        return StepResult(output={"repository": repo, "number": number, "comment_id": comment_id,
-                                  "artifact": artifact if artifact != "-" else None})
-
-    def _fetch(self, config: dict[str, Any], context: StepContext, root: Path,
-               repo: str, issue_url: str) -> StepResult:
-        name = _string(_resolved(config["write_to"], context), "write_to")
-        destination = _project_path(root, name, writing=True)
-        viewer = self._viewer(root, repo)
-        matches = []
-        for comment in _comments(root, issue_url):
-            if _author(comment) != viewer:
-                continue
-            marked = _marked(comment)
-            if marked and marked[1] == config["artifact"]:
-                matches.append((comment, marked[4]))
-        if len(matches) != 1:
-            raise ValueError(
-                f"Expected exactly one trusted artifact {config['artifact']!r}; "
-                f"found {len(matches)}"
-            )
-        comment, body = matches[0]
-        comment_id = comment.get("id")
-        if not isinstance(comment_id, int) or isinstance(comment_id, bool) or comment_id <= 0:
-            raise ValueError("GitHub artifact has no valid comment ID")
-        try:
-            _write_artifact(root, destination, body)
-        except FileExistsError as exc:
-            raise ValueError(f"Destination already exists: {destination}") from exc
-        except OSError as exc:
-            raise ValueError(f"Cannot write artifact: {exc}") from exc
-        return StepResult(output={"path": str(destination), "comment_id": comment_id})
-
-    @staticmethod
-    def _checkout(root: Path, url: str, number: int) -> StepResult:
-        pr = _api(root, f"{url}/pulls/{number}")
-        head = pr.get("head") if isinstance(pr, dict) else None
-        sha = head.get("sha") if isinstance(head, dict) else None
-        if not isinstance(sha, str) or not re.fullmatch(r"[a-f0-9]{40}", sha):
-            raise ValueError("GitHub PR has no valid head SHA")
-        _run(["git", "fetch", "origin", f"pull/{number}/head"], root)
-        fetched = _run(["git", "rev-parse", "FETCH_HEAD"], root)
-        if fetched != sha:
-            raise ValueError(
-                "Fetched PR head differs from the GitHub PR head; retry after the PR settles"
-            )
-        _run(["git", "-c", "advice.detachedHead=false", "checkout", "--detach", sha], root)
-        if _run(["git", "rev-parse", "HEAD"], root) != sha:
-            raise ValueError("Checked-out HEAD differs from the GitHub PR head")
-        return StepResult(output={"head_sha": sha, "number": number})
+            output["added"] = True
+            return StepResult(output=output)
+        except (ValueError, OSError) as exc:
+            return StepResult(status=StepStatus.FAILED, error=f"GitHub step: {exc}")
diff --git a/tests/workflows/test_github_step.py b/tests/workflows/test_github_step.py
index 9d19d2347b..6f3ba0c5bf 100644
--- a/tests/workflows/test_github_step.py
+++ b/tests/workflows/test_github_step.py
@@ -1,10 +1,9 @@
-"""Deterministic tests for the built-in GitHub workflow step."""
+"""Tests for the opt-in-by-use built-in GitHub label step (no live API calls)."""
 
 from __future__ import annotations
 
+import json
 from pathlib import Path
-from textwrap import indent
-from types import SimpleNamespace
 
 import pytest
 
@@ -17,589 +16,232 @@
 @pytest.fixture
 def context(tmp_path: Path) -> StepContext:
     return StepContext(
-        inputs={"issue": "12", "pr": 7},
-        project_root=str(tmp_path),
-        run_id="run-1",
+        inputs={"number": 12}, project_root=str(tmp_path), run_id="run-1"
     )
 
 
 @pytest.fixture
 def api(monkeypatch):
-    comments: list[dict] = []
-    calls: list[tuple[str, str]] = []
-
-    def fake_api(root, endpoint, *, method="GET", data=None, paginated=False):
-        calls.append((method, endpoint))
-        if endpoint.endswith("/user"):
-            return {"login": "maintainer"}
-        if endpoint.endswith("/pulls/7"):
-            return {"number": 7, "head": {"sha": "a" * 40}}
+    stored: list[str] = []
+    calls: list[tuple[str, str, list[str] | None]] = []
+
+    def fake_api(root, endpoint, *, labels: list[str] | None = None):
+        calls.append(("POST" if labels is not None else "GET", endpoint, labels))
         if endpoint.endswith("/issues/12"):
-            return {"number": 12}
-        if endpoint.endswith("/comments?per_page=100"):
-            assert paginated
-            return [comments[:]]
-        if endpoint.endswith("/comments") and method == "POST":
-            comment = {"id": len(comments) + 1, "body": data["body"],
-                       "user": {"login": "maintainer"}}
-            comments.append(comment)
-            return comment
-        raise AssertionError(f"Unexpected API call: {method} {endpoint}")
+            return {"number": 12, "labels": [{"name": name} for name in stored]}
+        if endpoint.endswith("/pulls/12"):
+            return {"number": 12, "labels": [{"name": name} for name in stored]}
+        if endpoint.endswith("/issues/12/labels") and labels is not None:
+            for name in labels:
+                if name.casefold() not in {existing.casefold() for existing in stored}:
+                    stored.append(name)
+            return [{"name": name} for name in stored]
+        raise AssertionError(f"Unexpected API call: {endpoint}")
 
     monkeypatch.setattr(github, "_api", fake_api)
-    monkeypatch.setattr(github, "_identity", lambda root: (
-        "owner/repo", "https://api.github.com/repos/owner/repo",
-    ))
-    return comments, calls
-
-
-def config(**kwargs):
-    definition = {"id": "post-plan", "type": "github", "operation": "comment",
-                  "target": "issue", "number": "{{ inputs.issue }}"}
-    definition.update(kwargs)
+    monkeypatch.setattr(
+        github,
+        "_identity",
+        lambda root: ("owner/repo", "https://api.github.com/repos/owner/repo"),
+    )
+    return stored, calls
+
+
+def config(**overrides):
+    definition = {
+        "id": "label",
+        "type": "github",
+        "operation": "add-label",
+        "target": "issue",
+        "number": "{{ inputs.number }}",
+        "label": "ready-for-review",
+    }
+    definition.update(overrides)
     return definition
 
 
-def test_registered_builtin_and_validation():
+def test_builtin_registered_and_accepts_only_add_label():
     step = get_step_type("github")
     assert step is not None
     assert "github" in BUILTIN_STEP_TYPES
-    assert step.validate(config(body="text")) == []
-    assert step.validate(config(body_file="plan.md")) == []
-    assert step.validate(config(body_files=["plan.md"])) == []
-    assert step.validate(config(body="text", body_file="plan.md"))
-    assert step.validate(config(body_files=[]))
-    assert step.validate(config(body="text", number=True))
-    assert step.validate(config(body="text", target="repository"))
-    assert step.validate(config(body="text", unexpected="field"))
-    assert step.validate(config(body="text", maintainer_action={"summary": "x"}))
-    assert step.validate({"id": "fetch", "type": "github", "operation": "fetch-artifact",
-                          "target": "issue", "number": 12, "write_to": "result.md"})
-    assert step.validate({"id": "checkout", "type": "github", "operation": "checkout-pr",
-                          "number": 0})
-
-
-def test_comment_retry_is_idempotent_and_changed_content_fails(context, api):
-    comments, calls = api
-    step = get_step_type("github")
-    definition = config(body="Plan for {{ inputs.issue }}", artifact="plan",
-                        maintainer_action={"summary": "Review only",
-                                           "possible_labels": ["approved"]})
-    first = step.execute(definition, context)
-    again = step.execute(definition, context)
-    assert first.status == again.status == StepStatus.COMPLETED
-    assert first.output["comment_id"] == again.output["comment_id"] == 1
-    assert len(comments) == 1
-    assert "Plan for 12" in comments[0]["body"]
-    assert "Possible labels: approved" in comments[0]["body"]
-    assert not any("/labels" in endpoint for _, endpoint in calls)
-    assert len([method for method, _ in calls if method == "POST"]) == 1
-    changed = step.execute(config(body="Different", artifact="plan"), context)
-    assert changed.status == StepStatus.FAILED
-    assert "differs" in changed.error
-    assert len(comments) == 1
-
-
-def test_valid_punctuated_step_id_posts_and_retries(context, api):
-    comments, _ = api
-    definition = config(id="publish.plan", body="Plan")
-    assert get_step_type("github").validate(definition) == []
-    step = get_step_type("github")
-    assert step.execute(definition, context).status == StepStatus.COMPLETED
-    assert step.execute(definition, context).status == StepStatus.COMPLETED
-    assert len(comments) == 1
-    workflow = WorkflowDefinition.from_string("""
-schema_version: "1.0"
-workflow:
-  id: punctuated-step
-  name: Punctuated step
-  version: "1.0.0"
-steps:
-  - id: publish.plan
-    type: github
-    operation: comment
-    target: issue
-    number: 12
-    body: Plan
-""")
-    engine = WorkflowEngine(Path(context.project_root))
-    assert engine.validate(workflow) == []
-    assert engine.execute(workflow, run_id="new-run").status == RunStatus.COMPLETED
-    assert len(comments) == 2
+    assert step.validate(config()) == []
+    assert step.validate(config(target="pull_request")) == []
+    for operation in ("comment", "fetch-artifact", "checkout-pr", "remove-label", None):
+        assert step.validate(config(operation=operation))
+    assert step.validate(config(body="Not supported"))
+
+
+def test_issue_label_added_once_and_retry_skips_write(context, api):
+    labels, calls = api
+    step = get_step_type("github")
+    first = step.execute(config(), context)
+    retry = step.execute(config(), context)
+    assert first.status == retry.status == StepStatus.COMPLETED
+    assert first.output == {
+        "repository": "owner/repo",
+        "target": "issue",
+        "number": 12,
+        "label": "ready-for-review",
+        "added": True,
+    }
+    assert retry.output == {**first.output, "added": False}
+    assert labels == ["ready-for-review"]
+    assert len([method for method, _, _ in calls if method == "POST"]) == 1
+
+
+def test_pull_request_uses_issue_labels_endpoint(context, api):
+    labels, calls = api
+    result = get_step_type("github").execute(config(target="pull_request"), context)
+    assert result.status == StepStatus.COMPLETED
+    assert result.output["target"] == "pull_request"
+    assert labels == ["ready-for-review"]
+    assert calls[0][1].endswith("/pulls/12")
+    assert calls[1][1].endswith("/issues/12/labels")
 
 
-def test_foreign_markers_cannot_block_post_or_fetch(context, api):
-    comments, _ = api
-    step = get_step_type("github")
-    definition = config(body="Original", artifact="report")
-    assert step.execute(definition, context).status == StepStatus.COMPLETED
-    comments.append({"id": 2, "body": "Bad\n\n<!-- speckit-github:v2",
-                     "user": {"login": "stranger"}})
-    comments.append({"id": 3, "body": comments[0]["body"],
-                     "user": {"login": "stranger"}})
-    assert step.execute(definition, context).status == StepStatus.COMPLETED
-    result = step.execute({"id": "fetch", "operation": "fetch-artifact",
-                           "target": "issue", "number": 12, "artifact": "report",
-                           "write_to": "result.md"}, context)
-    assert result.status == StepStatus.COMPLETED, result.error
-    assert (Path(context.project_root) / "result.md").read_text() == "Original"
-    assert len(comments) == 3
-
-
-def test_only_foreign_marker_is_not_a_trusted_artifact(context, api):
-    comments, _ = api
-    step = get_step_type("github")
-    assert step.execute(config(body="Original", artifact="report"), context).status == StepStatus.COMPLETED
-    comments[0]["user"] = {"login": "stranger"}
-    result = step.execute({"id": "fetch", "operation": "fetch-artifact",
-                           "target": "issue", "number": 12, "artifact": "report",
-                           "write_to": "result.md"}, context)
-    assert result.status == StepStatus.FAILED
-    assert "found 0" in result.error
+def test_existing_label_is_case_insensitive_and_skips_post(context, api):
+    labels, calls = api
+    labels.append("Ready-For-Review")
+    result = get_step_type("github").execute(config(), context)
+    assert result.status == StepStatus.COMPLETED
+    assert result.output["added"] is False
+    assert len(calls) == 1
 
 
-def test_comment_files_and_fetch_artifact(context, api):
-    comments, _ = api
-    root = Path(context.project_root)
-    (root / "one.md").write_text("First")
-    (root / "two.md").write_text("Second")
-    step = get_step_type("github")
-    posted = step.execute(config(body_files=["one.md", "two.md"], artifact="report"), context)
-    assert posted.status == StepStatus.COMPLETED
-    result = step.execute({"id": "retrieve", "type": "github", "operation": "fetch-artifact",
-                           "target": "issue", "number": 12, "artifact": "report",
-                           "write_to": "result.md"}, context)
-    assert result.status == StepStatus.COMPLETED, result.error
-    assert (root / "result.md").read_text() == "First\n\nSecond"
-    assert result.output["comment_id"] == comments[0]["id"]
-    again = step.execute({"id": "retrieve", "operation": "fetch-artifact",
-                          "target": "issue", "number": 12, "artifact": "report",
-                          "write_to": "result.md"}, context)
-    assert again.status == StepStatus.FAILED
-    assert (root / "result.md").read_text() == "First\n\nSecond"
-
-
-def test_fetch_creates_fresh_nested_parent_and_restores_only_artifact(context, api):
-    root = Path(context.project_root)
-    artifact = "# Assessment\r\n\r\nCafé\r\n\r\n### Maintainer action (proposal only)\r\nLiteral artifact text.\r\n"
-    (root / "assessment.md").write_bytes(artifact.encode("utf-8"))
-    step = get_step_type("github")
-    definition = config(body_file="assessment.md", artifact="assessment",
-                        maintainer_action={"summary": "Please review before proceeding.",
-                                           "possible_labels": ["ready"]})
-    assert step.execute(definition, context).status == StepStatus.COMPLETED
-    destination = root / ".specify" / "bugs" / "fresh-label" / "assessment.md"
-    assert not destination.parent.exists()
-    result = step.execute({"id": "rehydrate", "type": "github", "operation": "fetch-artifact",
-                           "target": "issue", "number": 12, "artifact": "assessment",
-                           "write_to": ".specify/bugs/fresh-label/assessment.md"}, context)
-    assert result.status == StepStatus.COMPLETED, result.error
-    assert destination.read_bytes() == artifact.encode("utf-8")
-    assert "Please review before proceeding" not in destination.read_text(encoding="utf-8")
-    assert step.execute(definition, context).status == StepStatus.COMPLETED
-
-
-def test_actions_installation_token_verifies_bot_author(context, api, monkeypatch):
-    comments, _ = api
-    monkeypatch.setenv("GITHUB_ACTIONS", "true")
-    monkeypatch.setenv("GITHUB_REPOSITORY", "owner/repo")
-    original_api = github._api
-
-    def actions_api(root, endpoint, **kwargs):
-        if endpoint.endswith("/installation/repositories"):
-            return {"total_count": 1, "repositories": [{"full_name": "owner/repo"}]}
-        if endpoint.endswith("/user"):
-            raise AssertionError("Actions installation tokens do not need /user")
-        result = original_api(root, endpoint, **kwargs)
-        if kwargs.get("method") == "POST":
-            result["user"] = {"login": "github-actions[bot]"}
-        return result
-
-    monkeypatch.setattr(github, "_api", actions_api)
-    step = get_step_type("github")
-    definition = config(body="Artifact", artifact="report")
-    assert step.execute(definition, context).status == StepStatus.COMPLETED
-    assert step.execute(definition, context).status == StepStatus.COMPLETED
-    result = step.execute({"id": "fetch", "operation": "fetch-artifact", "target": "issue",
-                           "number": 12, "artifact": "report", "write_to": "new/fix.md"}, context)
-    assert result.status == StepStatus.COMPLETED, result.error
-    assert (Path(context.project_root) / "new" / "fix.md").read_bytes() == b"Artifact"
-    assert len(comments) == 1
-
-
-@pytest.mark.parametrize("installation", [
-    {"total_count": 1, "repositories": [{"full_name": "elsewhere/repo"}]},
-    {"total_count": 2, "repositories": [{"full_name": "owner/repo"}]},
-    {"total_count": 1, "repositories": [{"full_name": 42}]},
-])
-def test_actions_rejects_untrusted_installation(context, api, monkeypatch, installation):
-    comments, _ = api
-    monkeypatch.setenv("GITHUB_ACTIONS", "true")
-    monkeypatch.setenv("GITHUB_REPOSITORY", "owner/repo")
-    original_api = github._api
-    monkeypatch.setattr(
-        github, "_api",
-        lambda root, endpoint, **kwargs: installation
-        if endpoint.endswith("/installation/repositories")
-        else original_api(root, endpoint, **kwargs),
-    )
-    result = get_step_type("github").execute(config(body="text"), context)
+@pytest.mark.parametrize("number", [0, -1, True, None, "1; echo bad", ""])
+def test_invalid_number_fails_before_any_api_call(context, api, number):
+    _, calls = api
+    result = get_step_type("github").execute(config(number=number), context)
     assert result.status == StepStatus.FAILED
-    assert "scoped to this repository" in result.error
-    assert not comments
-
-
-def test_actions_user_token_uses_user_identity(context, api, monkeypatch):
-    monkeypatch.setenv("GITHUB_ACTIONS", "true")
-    monkeypatch.setenv("GITHUB_REPOSITORY", "owner/repo")
-    original_api = github._api
+    assert "number" in result.error
+    assert calls == []
 
-    def user_token(root, endpoint, **kwargs):
-        if endpoint.endswith("/installation/repositories"):
-            raise ValueError("Installation endpoint unavailable to user token")
-        return original_api(root, endpoint, **kwargs)
-
-    monkeypatch.setattr(github, "_api", user_token)
-    assert get_step_type("github").execute(config(body="text"), context).status == StepStatus.COMPLETED
 
-
-def test_actions_rejects_comment_from_wrong_bot(context, api, monkeypatch):
-    comments, _ = api
-    monkeypatch.setenv("GITHUB_ACTIONS", "true")
-    monkeypatch.setenv("GITHUB_REPOSITORY", "owner/repo")
-    original_api = github._api
-    monkeypatch.setattr(
-        github, "_api",
-        lambda root, endpoint, **kwargs: (
-            {"total_count": 1, "repositories": [{"full_name": "owner/repo"}]}
-            if endpoint.endswith("/installation/repositories")
-            else original_api(root, endpoint, **kwargs)
-        ),
-    )
-    result = get_step_type("github").execute(config(body="text"), context)
+@pytest.mark.parametrize(
+    "label", [None, "", " ", "bad\nlabel", "bad\x7flabel", "a" * 51, ["ready"]]
+)
+def test_invalid_label_fails_before_any_api_call(context, api, label):
+    _, calls = api
+    result = get_step_type("github").execute(config(label=label), context)
     assert result.status == StepStatus.FAILED
-    assert "author does not match" in result.error
-    assert len(comments) == 1  # The server posted, but success is not reported.
+    assert "label" in result.error
+    assert calls == []
 
 
-def test_fetch_does_not_create_directories_for_untrusted_artifact(context, api):
+def test_missing_fields_and_unsupported_operations_fail(context, api):
+    _, calls = api
     step = get_step_type("github")
-    root = Path(context.project_root)
-    result = step.execute({"id": "rehydrate", "operation": "fetch-artifact",
-                           "target": "issue", "number": 12, "artifact": "missing",
-                           "write_to": ".specify/bugs/fresh-label/fix.md"}, context)
-    assert result.status == StepStatus.FAILED
-    assert "found 0" in result.error
-    assert not (root / ".specify").exists()
+    for broken in (
+        config(target="repository"),
+        config(operation="comment"),
+        {key: value for key, value in config().items() if key != "label"},
+        {key: value for key, value in config().items() if key != "number"},
+        config(body="unexpected"),
+    ):
+        assert step.validate(broken)
+        assert step.execute(broken, context).status == StepStatus.FAILED
+    assert calls == []
 
 
-def test_engine_executes_github_yaml_without_shell(context, api):
-    comments, _ = api
-    definition = WorkflowDefinition.from_string("""
-schema_version: "1.0"
-workflow:
-  id: github-pipeline
-  name: GitHub pipeline
-  version: "1.0.0"
-inputs:
-  issue:
-    type: number
-    required: true
-steps:
-  - id: publish
-    type: github
-    operation: comment
-    target: issue
-    number: "{{ inputs.issue }}"
-    body: "Plan for {{ inputs.issue }}"
-    artifact: plan
-""")
-    engine = WorkflowEngine(Path(context.project_root))
-    assert engine.validate(definition) == []
-    state = engine.execute(definition, {"issue": "12"}, run_id="pipeline1")
-    assert state.status == RunStatus.COMPLETED
-    assert state.step_results["publish"]["output"]["comment_id"] == 1
-    assert len(comments) == 1
-
-
-@pytest.mark.parametrize("workers", [1, 3])
-@pytest.mark.parametrize("nested", [False, True])
-def test_github_comment_fan_out_retries_per_index(context, api, workers, nested):
-    comments, calls = api
-    if nested:
-        template = """id: branch
-type: if
-condition: true
-then:
-  - id: publish
-    type: github
-    operation: comment
-    target: issue
-    number: 12
-    body: "same content"
-"""
-    else:
-        template = """id: publish
-type: github
-operation: comment
-target: issue
-number: 12
-body: "same content"
-"""
-    workflow = WorkflowDefinition.from_string("""
-schema_version: "1.0"
-workflow:
-  id: fan-out-github
-  name: Fan-out GitHub
-  version: "1.0.0"
-steps:
-  - id: fan
-    type: fan-out
-    items: "{{ ['same', 'same', 'same'] }}"
-    max_concurrency: WORKERS
-    step:
-TEMPLATE
-""".replace("WORKERS", str(workers)).replace("TEMPLATE", indent(template, "      ").rstrip()))
-    engine = WorkflowEngine(Path(context.project_root))
-    assert engine.validate(workflow) == []
-    assert engine.execute(workflow, run_id="fan-run").status == RunStatus.COMPLETED
-    assert len(comments) == 3
-    assert engine.execute(workflow, run_id="fan-run").status == RunStatus.COMPLETED
-    assert len(comments) == 3
-    assert len([method for method, _ in calls if method == "POST"]) == 3
-
-
-def test_github_fetch_artifact_fan_out_writes_distinct_paths(context, api):
-    root = Path(context.project_root)
+def test_wrong_issue_target_and_malformed_labels_fail(context, api, monkeypatch):
+    original_api = github._api
     step = get_step_type("github")
-    assert step.execute(config(body="Shared", artifact="report"), context).status == StepStatus.COMPLETED
-    workflow = WorkflowDefinition.from_string("""
-schema_version: "1.0"
-workflow:
-  id: fetch-fan-out
-  name: Fetch fan-out
-  version: "1.0.0"
-steps:
-  - id: fetch-all
-    type: fan-out
-    items: "{{ ['one', 'two'] }}"
-    max_concurrency: 2
-    step:
-      id: fetch
-      type: github
-      operation: fetch-artifact
-      target: issue
-      number: 12
-      artifact: report
-      write_to: "artifacts/{{ item }}.md"
-""")
-    engine = WorkflowEngine(root)
-    assert engine.validate(workflow) == []
-    assert engine.execute(workflow).status == RunStatus.COMPLETED
-    assert (root / "artifacts" / "one.md").read_text() == "Shared"
-    assert (root / "artifacts" / "two.md").read_text() == "Shared"
-
 
-@pytest.mark.parametrize("workers,expected", [(1, RunStatus.COMPLETED), (2, RunStatus.FAILED)])
-def test_checkout_pr_fan_out_requires_sequential_worktree(context, api, monkeypatch,
-                                                         workers, expected):
-    calls = []
-
-    def fake_run(args, root, *, input_text=None):
-        calls.append(args)
-        return "a" * 40 if args[:2] == ["git", "rev-parse"] else ""
+    def wrong_target(root, endpoint, **kwargs):
+        if endpoint.endswith("/issues/12"):
+            return {"number": 12, "pull_request": {}, "labels": []}
+        return original_api(root, endpoint, **kwargs)
 
-    monkeypatch.setattr(github, "_run", fake_run)
-    workflow = WorkflowDefinition.from_string("""
-schema_version: "1.0"
-workflow:
-  id: checkout-fan-out
-  name: Checkout fan-out
-  version: "1.0.0"
-steps:
-  - id: checkouts
-    type: fan-out
-    items: "{{ [7, 7] }}"
-    max_concurrency: WORKERS
-    step:
-      id: checkout
-      type: github
-      operation: checkout-pr
-      number: "{{ item }}"
-""".replace("WORKERS", str(workers)))
-    state = WorkflowEngine(Path(context.project_root)).execute(workflow)
-    assert state.status == expected
-    if workers == 1:
-        assert len([call for call in calls if call[:2] == ["git", "fetch"]]) == 2
-    else:
-        assert not calls
-        assert "share one working tree" in state.error
-
-
-def test_pull_request_comment_uses_issue_comment_endpoint(context, api):
-    comments, calls = api
-    definition = config(body="PR feedback", target="pull_request", number=7)
-    result = get_step_type("github").execute(definition, context)
-    assert result.status == StepStatus.COMPLETED, result.error
-    assert get_step_type("github").execute(definition, context).status == StepStatus.COMPLETED
-    assert len(comments) == 1
-    assert any(url.endswith("/pulls/7") for _, url in calls)
-    assert any(method == "POST" and url.endswith("/issues/7/comments")
-               for method, url in calls)
-
-
-@pytest.mark.parametrize("change,expected", [
-    (lambda comments: comments[0].update(body=comments[0]["body"].replace("First", "Altered")), "digest"),
-    (lambda comments: comments[0].update(user={"login": "someone-else"}), "found 0"),
-    (lambda comments: comments.append(dict(comments[0], id=2)), "found 2"),
-])
-def test_fetch_rejects_untrusted_or_ambiguous(context, api, change, expected):
-    comments, _ = api
-    step = get_step_type("github")
-    assert step.execute(config(body="First", artifact="report"), context).status == StepStatus.COMPLETED
-    change(comments)
-    result = step.execute({"id": "retrieve", "operation": "fetch-artifact",
-                           "target": "issue", "number": 12, "artifact": "report",
-                           "write_to": "result.md"}, context)
+    monkeypatch.setattr(github, "_api", wrong_target)
+    result = step.execute(config(), context)
     assert result.status == StepStatus.FAILED
-    assert expected in result.error
-    assert not (Path(context.project_root) / "result.md").exists()
+    assert "does not match" in result.error
 
-
-@pytest.mark.parametrize("name", ["../elsewhere", "/tmp/elsewhere", "link/result.md"])
-def test_fetch_rejects_unsafe_destinations(context, api, name, tmp_path):
-    root = Path(context.project_root)
-    (root / "link").symlink_to(tmp_path.parent, target_is_directory=True)
-    step = get_step_type("github")
-    assert step.execute(config(body="text", artifact="report"), context).status == StepStatus.COMPLETED
-    result = step.execute({"id": "fetch", "operation": "fetch-artifact", "target": "issue",
-                           "number": 12, "artifact": "report", "write_to": name}, context)
+    monkeypatch.setattr(
+        github,
+        "_api",
+        lambda root, endpoint, **kwargs: {"number": 12, "labels": "invalid"},
+    )
+    result = step.execute(config(), context)
     assert result.status == StepStatus.FAILED
+    assert "invalid label list" in result.error
 
 
-def test_fetch_rejects_symlinked_missing_parent_and_existing_destination(context, api, tmp_path):
-    root = Path(context.project_root)
-    (root / ".specify").mkdir()
-    (root / ".specify" / "bugs").symlink_to(tmp_path.parent, target_is_directory=True)
-    (root / "existing.md").write_text("keep", encoding="utf-8")
+def test_api_failure_or_missing_posted_label_is_not_success(context, api, monkeypatch):
     step = get_step_type("github")
-    assert step.execute(config(body="original", artifact="report"), context).status == StepStatus.COMPLETED
-    for name in (".specify/bugs/new/fix.md", "existing.md"):
-        result = step.execute({"id": "fetch", "operation": "fetch-artifact", "target": "issue",
-                               "number": 12, "artifact": "report", "write_to": name}, context)
-        assert result.status == StepStatus.FAILED
-    assert (root / "existing.md").read_text() == "keep"
-    assert not (tmp_path.parent / "new").exists()
-
-
-def test_windows_write_fails_closed_before_creating_directories(context, monkeypatch):
-    root = Path(context.project_root)
-    monkeypatch.setattr(github, "os", SimpleNamespace(name="nt"))
-    with pytest.raises(ValueError, match="unsupported"):
-        github._write_artifact(root, root / "new" / "report.md", "report")
-    assert not (root / "new").exists()
-
-
-def test_bad_identifiers_and_missing_artifact_fail_without_post(context, api):
-    comments, calls = api
-    step = get_step_type("github")
-    for number in (0, "-1", True, "1; echo bad", None):
-        result = step.execute(config(body="hello", number=number), context)
-        assert result.status == StepStatus.FAILED
-        assert "number" in result.error
-    result = step.execute({"id": "fetch", "operation": "fetch-artifact", "target": "issue",
-                           "number": 12, "artifact": "missing", "write_to": "result.md"}, context)
-    assert result.status == StepStatus.FAILED
-    assert "found 0" in result.error
-    assert not comments
-    assert not any(method == "POST" for method, _ in calls)
+    original_api = github._api
 
+    def no_label(root, endpoint, **kwargs):
+        if kwargs.get("labels") is not None:
+            return []
+        return original_api(root, endpoint, **kwargs)
 
-def test_comment_rejects_symlinked_source_inside_fan_out(context, api, tmp_path):
-    root = Path(context.project_root)
-    (root / "link.md").symlink_to(tmp_path.parent / "outside.md")
-    step = get_step_type("github")
-    result = step.execute(config(body_file="link.md"), context)
+    monkeypatch.setattr(github, "_api", no_label)
+    result = step.execute(config(), context)
     assert result.status == StepStatus.FAILED
-    assert "Symlinked" in result.error
-    context.inside_fan_out = True
-    context.fan_out_key = "fan:post:0"
-    result = step.execute(config(body="hi"), context)
-    assert result.status == StepStatus.COMPLETED
-
-
-def test_api_error_fails_without_success_shaped_output(context, api, monkeypatch):
-    monkeypatch.setattr(github, "_api", lambda *args, **kwargs: (_ for _ in ()).throw(
-        ValueError("GitHub request failed (exit code 403)")))
-    result = get_step_type("github").execute(config(body="hi"), context)
+    assert "did not apply label" in result.error
+    monkeypatch.setattr(
+        github,
+        "_api",
+        lambda *args, **kwargs: (_ for _ in ()).throw(ValueError("GitHub API failed")),
+    )
+    result = step.execute(config(), context)
     assert result.status == StepStatus.FAILED
-    assert "403" in result.error
+    assert "GitHub API failed" in result.error
     assert result.output == {}
 
 
-def test_api_posts_json_on_stdin_and_slurps_comment_pages(context, monkeypatch):
+def test_api_post_uses_json_stdin_and_does_not_put_label_in_arguments(
+    context, monkeypatch
+):
     observed = []
 
     def fake_run(args, root, *, input_text=None):
         observed.append((args, input_text))
-        return "[[]]" if "--paginate" in args else '{"id": 1}'
+        return '[{"name":"ready"}]'
 
     monkeypatch.setattr(github, "_run", fake_run)
-    root = Path(context.project_root)
-    assert github._api(root, "https://api.github.com/repos/o/r/issues/1/comments",
-                       method="POST", data={"body": "private body"}) == {"id": 1}
-    assert observed[0][1] == '{"body": "private body"}'
-    assert "private body" not in " ".join(observed[0][0])
-    assert github._api(root, "https://api.github.com/repos/o/r/issues/1/comments",
-                       paginated=True) == [[]]
-    assert observed[1][0][-2:] == ["--paginate", "--slurp"]
-
-
-def test_identity_rejects_non_github_origin(context, monkeypatch):
-    assert github._ORIGIN.fullmatch("https://evil.example/owner/repo.git") is None
-    assert github._ORIGIN.fullmatch("https://github.com/owner/repo.git")
-    monkeypatch.setattr(github, "_run", lambda args, root, **kwargs: "https://evil.example/owner/repo.git")
-    with pytest.raises(ValueError, match="github.com origin"):
-        github._identity(Path(context.project_root))
-
-
-def test_comment_rejects_wrong_target(context, api, monkeypatch):
-    step = get_step_type("github")
-    original_api = github._api
-
-    def wrong_target(root, endpoint, **kwargs):
-        if endpoint.endswith("/issues/12"):
-            return {"number": 12, "pull_request": {}}
-        return original_api(root, endpoint, **kwargs)
-
-    monkeypatch.setattr(github, "_api", wrong_target)
-    bad = step.execute(config(body="hi"), context)
-    assert bad.status == StepStatus.FAILED
-    assert "does not match" in bad.error
+    github._api(
+        Path(context.project_root),
+        "https://api.github.com/repos/o/r/issues/12/labels",
+        labels=["ready"],
+    )
+    assert json.loads(observed[0][1]) == {"labels": ["ready"]}
+    assert "ready" not in observed[0][0]
 
 
-def test_checkout_verifies_head_before_checkout(context, api, monkeypatch):
-    commands = []
-    sha = "a" * 40
+def test_origin_must_be_github_dot_com(context, monkeypatch):
+    monkeypatch.setattr(
+        github, "_run", lambda args, root, **kwargs: "https://evil.example/o/r.git"
+    )
+    with pytest.raises(ValueError, match="github.com origin"):
+        github._identity(Path(context.project_root))
 
-    def fake_run(args, root, *, input_text=None):
-        commands.append(args)
-        if args[:2] == ["git", "rev-parse"]:
-            return sha
-        return ""
 
-    monkeypatch.setattr(github, "_run", fake_run)
-    step = get_step_type("github")
-    definition = {"id": "checkout", "type": "github", "operation": "checkout-pr",
-                  "number": "{{ inputs.pr }}"}
-    result = step.execute(definition, context)
-    assert result.status == StepStatus.COMPLETED
-    assert result.output["head_sha"] == sha
-    assert ["git", "fetch", "origin", "pull/7/head"] in commands
-    assert ["git", "-c", "advice.detachedHead=false", "checkout", "--detach", sha] in commands
-    assert commands[-1] == ["git", "rev-parse", "HEAD"]
-    commands.clear()
-    monkeypatch.setattr(github, "_run", lambda args, root, **kwargs: "b" * 40)
-    failed = step.execute(definition, context)
-    assert failed.status == StepStatus.FAILED
-    assert "differs" in failed.error
+def test_engine_executes_label_yaml_and_fan_out_with_retries(context, api):
+    labels, calls = api
+    workflow = WorkflowDefinition.from_string("""
+schema_version: "1.0"
+workflow:
+  id: label-items
+  name: Label items
+  version: "1.0.0"
+steps:
+  - id: labels
+    type: fan-out
+    items: "{{ ['ready', 'needs-review'] }}"
+    max_concurrency: 2
+    step:
+      id: add-label
+      type: github
+      operation: add-label
+      target: issue
+      number: 12
+      label: "{{ item }}"
+""")
+    engine = WorkflowEngine(Path(context.project_root))
+    assert engine.validate(workflow) == []
+    assert engine.execute(workflow, run_id="labels-run").status == RunStatus.COMPLETED
+    assert set(labels) == {"ready", "needs-review"}
+    assert engine.execute(workflow, run_id="labels-run").status == RunStatus.COMPLETED
+    assert len([method for method, _, _ in calls if method == "POST"]) == 2
diff --git a/workflows/ARCHITECTURE.md b/workflows/ARCHITECTURE.md
index 8fe70a8709..078cb082b6 100644
--- a/workflows/ARCHITECTURE.md
+++ b/workflows/ARCHITECTURE.md
@@ -86,7 +86,7 @@ The engine ships with 13 built-in step types, each in its own subpackage under `
 | `command` | `CommandStep` | Invoke an installed Spec Kit command via integration CLI | No |
 | `prompt` | `PromptStep` | Send an arbitrary inline prompt to integration CLI | No |
 | `shell` | `ShellStep` | Run a shell command, capture output | No |
-| `github` | `GitHubStep` | GitHub comments, artifacts, and PR checkout | No |
+| `github` | `GitHubStep` | Add an explicit issue or pull-request label | No |
 | `init` | `InitStep` | Bootstrap a project (equivalent to `specify init`) | No |
 | `slot` | `SlotStep` | Named workflow slot; skipped when unfilled | No |
 | `gate` | `GateStep` | Interactive human review/approval | No (pauses in CI) |
diff --git a/workflows/README.md b/workflows/README.md
index b55ff34795..670649cf30 100644
--- a/workflows/README.md
+++ b/workflows/README.md
@@ -174,11 +174,11 @@ full builds, linter aggregators, or integration-test targets.
 
 ### GitHub Steps
 
-The built-in `github` step posts comments, retrieves workflow-posted artifacts,
-or checks out a PR head when a workflow explicitly uses `type: github`. It
-does not install or invoke the opt-in GitHub agent-command extension. See the
-[GitHub step reference](../docs/reference/workflows.md#github-step) for the
-operations, credentials, retry behavior, and fan-out constraints.
+The built-in `github` step adds an explicitly configured issue or pull-request
+label when a workflow uses `type: github`. It does not install or invoke the
+opt-in GitHub agent-command extension. See the
+[GitHub step reference](../docs/reference/workflows.md#github-step) for
+configuration, credentials, and retry behavior.
 
 ### Init Steps
 

From f05c5f511d54ccc00b853cf23db11ceec1078e05 Mon Sep 17 00:00:00 2001
From: Manfred Riem <15701806+mnriem@users.noreply.github.com>
Date: Fri, 9 Oct 2026 16:20:38 -0500
Subject: [PATCH 07/10] Test supported GitHub workflow origin formats

Cover HTTPS and SSH remotes with and without .git, including the repository identifier and derived API URL used by the label step.

Assisted-by: GitHub Copilot (model: GPT-6 Sol, autonomous)

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot-Session: ec94c538-a8b2-4c39-81fc-3ba5f0a59ce6
---
 tests/workflows/test_github_step.py | 25 +++++++++++++++++++++++++
 1 file changed, 25 insertions(+)

diff --git a/tests/workflows/test_github_step.py b/tests/workflows/test_github_step.py
index 6f3ba0c5bf..f92b020d72 100644
--- a/tests/workflows/test_github_step.py
+++ b/tests/workflows/test_github_step.py
@@ -210,6 +210,31 @@ def fake_run(args, root, *, input_text=None):
     assert "ready" not in observed[0][0]
 
 
+@pytest.mark.parametrize(
+    "origin",
+    [
+        "https://github.com/owner/repo.git",
+        "https://github.com/owner/repo",
+        "git@github.com:owner/repo.git",
+        "git@github.com:owner/repo",
+    ],
+)
+def test_github_origin_derives_repository_and_api_url(context, monkeypatch, origin):
+    root = Path(context.project_root)
+    calls = []
+
+    def fake_run(args, cwd, *, input_text=None):
+        calls.append((args, cwd))
+        return origin
+
+    monkeypatch.setattr(github, "_run", fake_run)
+    assert github._identity(root) == (
+        "owner/repo",
+        "https://api.github.com/repos/owner/repo",
+    )
+    assert calls == [(["git", "remote", "get-url", "origin"], root)]
+
+
 def test_origin_must_be_github_dot_com(context, monkeypatch):
     monkeypatch.setattr(
         github, "_run", lambda args, root, **kwargs: "https://evil.example/o/r.git"

From 054a760b1ebe6ba9047c822671b8f32c759e5311 Mon Sep 17 00:00:00 2001
From: Manfred Riem <15701806+mnriem@users.noreply.github.com>
Date: Fri, 9 Oct 2026 16:28:24 -0500
Subject: [PATCH 08/10] Accept standard GitHub SSH origin URLs

Recognize ssh://git@github.com remotes and case-insensitive GitHub hostnames while keeping the API fixed to api.github.com. Cover allowed formats and lookalike-host rejections, and distinguish Git remotes from REST endpoints in the reference.

Assisted-by: GitHub Copilot (model: GPT-6 Sol, autonomous)

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot-Session: ec94c538-a8b2-4c39-81fc-3ba5f0a59ce6
---
 docs/reference/workflows.md                   |  5 ++++-
 .../workflows/step/github/__init__.py         |  4 +++-
 tests/workflows/test_github_step.py           | 20 +++++++++++++++----
 3 files changed, 23 insertions(+), 6 deletions(-)

diff --git a/docs/reference/workflows.md b/docs/reference/workflows.md
index eb6fb322c2..417a337169 100644
--- a/docs/reference/workflows.md
+++ b/docs/reference/workflows.md
@@ -586,7 +586,10 @@ specify workflow run speckit -i spec="Build a kanban board with drag-and-drop ta
 ### GitHub step
 
 `type: github` uses the installed `gh` CLI and its active authentication for a
-repository whose `origin` points to `github.com`. The active token needs
+repository whose `origin` points to `github.com` via HTTPS, SCP-style SSH, or
+`ssh://git@github.com/`. The origin URL identifies the repository; label
+requests go to its `api.github.com` REST endpoint, not to the Git remote URL.
+The active token needs
 permission to read the issue or pull request and to write its labels (for
 example, `issues: write` for issues or `pull-requests: write` for PRs when
 using `GITHUB_TOKEN` in Actions). The step uses only the existing token: it
diff --git a/src/specify_cli/workflows/step/github/__init__.py b/src/specify_cli/workflows/step/github/__init__.py
index 39439b229a..edd98202ec 100644
--- a/src/specify_cli/workflows/step/github/__init__.py
+++ b/src/specify_cli/workflows/step/github/__init__.py
@@ -13,7 +13,9 @@
 
 _NUMBER = re.compile(r"[1-9][0-9]*\Z")
 _ORIGIN = re.compile(
-    r"(?:https://github\.com/|git@github\.com:)([A-Za-z0-9_.-]+)/([A-Za-z0-9_.-]+?)(?:\.git)?/?\Z"
+    r"(?:https://github\.com/|git@github\.com:|ssh://git@github\.com/)"
+    r"([A-Za-z0-9_.-]+)/([A-Za-z0-9_.-]+?)(?:\.git)?/?\Z",
+    re.IGNORECASE,
 )
 
 
diff --git a/tests/workflows/test_github_step.py b/tests/workflows/test_github_step.py
index f92b020d72..9e698be455 100644
--- a/tests/workflows/test_github_step.py
+++ b/tests/workflows/test_github_step.py
@@ -215,8 +215,12 @@ def fake_run(args, root, *, input_text=None):
     [
         "https://github.com/owner/repo.git",
         "https://github.com/owner/repo",
+        "https://GitHub.COM/owner/repo.git",
         "git@github.com:owner/repo.git",
         "git@github.com:owner/repo",
+        "git@GITHUB.com:owner/repo.git",
+        "ssh://git@github.com/owner/repo.git",
+        "ssh://git@GITHUB.COM/owner/repo",
     ],
 )
 def test_github_origin_derives_repository_and_api_url(context, monkeypatch, origin):
@@ -235,10 +239,18 @@ def fake_run(args, cwd, *, input_text=None):
     assert calls == [(["git", "remote", "get-url", "origin"], root)]
 
 
-def test_origin_must_be_github_dot_com(context, monkeypatch):
-    monkeypatch.setattr(
-        github, "_run", lambda args, root, **kwargs: "https://evil.example/o/r.git"
-    )
+@pytest.mark.parametrize(
+    "origin",
+    [
+        "https://evil.example/o/r.git",
+        "https://github.com.evil.example/o/r.git",
+        "ssh://git@github.com.evil.example/o/r.git",
+        "ssh://other@github.com/o/r.git",
+        "git@github.com.evil.example:o/r.git",
+    ],
+)
+def test_origin_must_be_github_dot_com(context, monkeypatch, origin):
+    monkeypatch.setattr(github, "_run", lambda args, root, **kwargs: origin)
     with pytest.raises(ValueError, match="github.com origin"):
         github._identity(Path(context.project_root))
 

From a8581508adb8a38f9ae819039ab161b187c5ccf2 Mon Sep 17 00:00:00 2001
From: Manfred Riem <15701806+mnriem@users.noreply.github.com>
Date: Fri, 9 Oct 2026 16:32:20 -0500
Subject: [PATCH 09/10] Select GitHub label repository explicitly

Require a validated owner/repo workflow field instead of reading a Git origin. Keep label operations fixed to the GitHub API and cover operation from directories without a checkout.

Assisted-by: GitHub Copilot (model: GPT-6 Sol, autonomous)

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot-Session: ec94c538-a8b2-4c39-81fc-3ba5f0a59ce6
---
 docs/reference/workflows.md                   |  27 ++--
 .../workflows/step/github/__init__.py         |  42 +++---
 tests/workflows/test_github_step.py           | 130 +++++++++++-------
 3 files changed, 118 insertions(+), 81 deletions(-)

diff --git a/docs/reference/workflows.md b/docs/reference/workflows.md
index 417a337169..e0bcc0fbb3 100644
--- a/docs/reference/workflows.md
+++ b/docs/reference/workflows.md
@@ -585,21 +585,20 @@ specify workflow run speckit -i spec="Build a kanban board with drag-and-drop ta
 
 ### GitHub step
 
-`type: github` uses the installed `gh` CLI and its active authentication for a
-repository whose `origin` points to `github.com` via HTTPS, SCP-style SSH, or
-`ssh://git@github.com/`. The origin URL identifies the repository; label
-requests go to its `api.github.com` REST endpoint, not to the Git remote URL.
-The active token needs
-permission to read the issue or pull request and to write its labels (for
-example, `issues: write` for issues or `pull-requests: write` for PRs when
-using `GITHUB_TOKEN` in Actions). The step uses only the existing token: it
-does not request or elevate permissions. It does not inspect issue contents
-for instructions or make a maintainer decision.
+`type: github` uses the installed `gh` CLI and its active authentication.
+Specify the GitHub repository as `owner/repo`; no Git remote or source checkout
+is required. Requests go to GitHub's `api.github.com` REST endpoint for that
+repository. The active token needs permission to read the issue or pull request
+and to write its labels (for example, `issues: write` for issues or
+`pull-requests: write` for PRs when using `GITHUB_TOKEN` in Actions). The step
+uses only the existing token: it does not request or elevate permissions. It
+does not inspect issue contents for instructions or make a maintainer decision.
 
 ```yaml
 - id: mark-ready
   type: github
   operation: add-label
+  repository: owner/repo
   target: issue
   number: "{{ inputs.issue_number }}"
   label: ready-for-review
@@ -607,9 +606,11 @@ for instructions or make a maintainer decision.
 
 `target` is `issue` or `pull_request`; `number` must resolve to a positive
 integer. `label` is one explicit label name (up to 50 characters) and must
-already exist in the repository. Both values may use workflow expressions.
-The step checks the target type and its existing labels, skips the write when
-the label is already present, and verifies GitHub's response after adding it.
+already exist in the repository. `repository`, `number`, and `label` may use
+workflow expressions. The repository must resolve to a single `owner/repo`
+name, not a URL or Git remote. The step checks the target type and its existing
+labels, skips the write when the label is already present, and verifies GitHub's
+response after adding it.
 The output includes `repository`, `target`, `number`, `label`, and `added`
 (`true` only when a label was added). Repeated execution and fan-out items
 are safe to retry: an already-present label is left unchanged. This first
diff --git a/src/specify_cli/workflows/step/github/__init__.py b/src/specify_cli/workflows/step/github/__init__.py
index edd98202ec..47b498fc52 100644
--- a/src/specify_cli/workflows/step/github/__init__.py
+++ b/src/specify_cli/workflows/step/github/__init__.py
@@ -12,11 +12,7 @@
 from specify_cli.workflows.expressions import evaluate_expression
 
 _NUMBER = re.compile(r"[1-9][0-9]*\Z")
-_ORIGIN = re.compile(
-    r"(?:https://github\.com/|git@github\.com:|ssh://git@github\.com/)"
-    r"([A-Za-z0-9_.-]+)/([A-Za-z0-9_.-]+?)(?:\.git)?/?\Z",
-    re.IGNORECASE,
-)
+_REPOSITORY = re.compile(r"[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+\Z")
 
 
 def _run(args: list[str], root: Path, *, input_text: str | None = None) -> str:
@@ -69,6 +65,16 @@ def _number(value: Any) -> int:
     return int(value)
 
 
+def _repository(value: Any) -> str:
+    if (
+        not isinstance(value, str)
+        or not _REPOSITORY.fullmatch(value)
+        or any(part in (".", "..") for part in value.split("/"))
+    ):
+        raise ValueError("'repository' must be a GitHub owner/repo name")
+    return value
+
+
 def _label(value: Any) -> str:
     if (
         not isinstance(value, str)
@@ -91,15 +97,6 @@ def _label_names(value: Any) -> set[str]:
     return {entry["name"].casefold() for entry in value}
 
 
-def _identity(root: Path) -> tuple[str, str]:
-    origin = _run(["git", "remote", "get-url", "origin"], root)
-    match = _ORIGIN.fullmatch(origin)
-    if not match:
-        raise ValueError("GitHub step requires a github.com origin remote")
-    repository = f"{match[1]}/{match[2]}"
-    return repository, f"https://api.github.com/repos/{repository}"
-
-
 class GitHubStep(StepBase):
     """Add only the label explicitly specified by a workflow author."""
 
@@ -116,6 +113,7 @@ def validate(self, config: dict[str, Any]) -> list[str]:
             "type",
             "operation",
             "target",
+            "repository",
             "number",
             "label",
             "continue_on_error",
@@ -128,6 +126,15 @@ def validate(self, config: dict[str, Any]) -> list[str]:
                 _number(config["number"])
             except ValueError as exc:
                 errors.append(str(exc))
+        if "repository" not in config:
+            errors.append("GitHub step requires 'repository'.")
+        elif not (
+            isinstance(config["repository"], str) and "{{" in config["repository"]
+        ):
+            try:
+                _repository(config["repository"])
+            except ValueError as exc:
+                errors.append(str(exc))
         if "label" not in config:
             errors.append("GitHub step requires 'label'.")
         elif not (isinstance(config["label"], str) and "{{" in config["label"]):
@@ -144,10 +151,9 @@ def execute(self, config: dict[str, Any], context: StepContext) -> StepResult:
                 raise ValueError("; ".join(errors))
             number = _number(_resolved(config["number"], context))
             label = _label(_resolved(config["label"], context))
-            if not context.project_root:
-                raise ValueError("GitHub step requires a project root")
-            root = Path(context.project_root).resolve()
-            repository, url = _identity(root)
+            repository = _repository(_resolved(config["repository"], context))
+            root = Path(context.project_root or ".").resolve()
+            url = f"https://api.github.com/repos/{repository}"
             target = config["target"]
             kind = "pulls" if target == "pull_request" else "issues"
             resource = _api(root, f"{url}/{kind}/{number}")
diff --git a/tests/workflows/test_github_step.py b/tests/workflows/test_github_step.py
index 9e698be455..466ac1174e 100644
--- a/tests/workflows/test_github_step.py
+++ b/tests/workflows/test_github_step.py
@@ -39,11 +39,6 @@ def fake_api(root, endpoint, *, labels: list[str] | None = None):
         raise AssertionError(f"Unexpected API call: {endpoint}")
 
     monkeypatch.setattr(github, "_api", fake_api)
-    monkeypatch.setattr(
-        github,
-        "_identity",
-        lambda root: ("owner/repo", "https://api.github.com/repos/owner/repo"),
-    )
     return stored, calls
 
 
@@ -52,6 +47,7 @@ def config(**overrides):
         "id": "label",
         "type": "github",
         "operation": "add-label",
+        "repository": "owner/repo",
         "target": "issue",
         "number": "{{ inputs.number }}",
         "label": "ready-for-review",
@@ -86,6 +82,7 @@ def test_issue_label_added_once_and_retry_skips_write(context, api):
     }
     assert retry.output == {**first.output, "added": False}
     assert labels == ["ready-for-review"]
+    assert calls[0][1] == "https://api.github.com/repos/owner/repo/issues/12"
     assert len([method for method, _, _ in calls if method == "POST"]) == 1
 
 
@@ -108,6 +105,82 @@ def test_existing_label_is_case_insensitive_and_skips_post(context, api):
     assert len(calls) == 1
 
 
+def test_repository_expression_selects_api_target_without_git_origin(context, api):
+    labels, calls = api
+    context.inputs["repository"] = "other/project"
+    context.project_root = None
+    result = get_step_type("github").execute(
+        config(repository="{{ inputs.repository }}"), context
+    )
+    assert result.status == StepStatus.COMPLETED
+    assert result.output["repository"] == "other/project"
+    assert labels == ["ready-for-review"]
+    assert [endpoint for _, endpoint, _ in calls] == [
+        "https://api.github.com/repos/other/project/issues/12",
+        "https://api.github.com/repos/other/project/issues/12/labels",
+    ]
+
+
+def test_api_requests_need_no_git_remote(context, monkeypatch):
+    calls = []
+
+    def fake_run(args, root, *, input_text=None):
+        assert args[:2] == ["gh", "api"]
+        calls.append((args, input_text))
+        if args[2:4] == ["--method", "GET"]:
+            return '{"number": 12, "labels": []}'
+        return '[{"name": "ready-for-review"}]'
+
+    monkeypatch.setattr(github, "_run", fake_run)
+    result = get_step_type("github").execute(config(), context)
+    assert result.status == StepStatus.COMPLETED
+    assert result.output["added"] is True
+    assert calls[0][0][-1] == "https://api.github.com/repos/owner/repo/issues/12"
+    assert calls[1][0][4] == "https://api.github.com/repos/owner/repo/issues/12/labels"
+    assert json.loads(calls[1][1]) == {"labels": ["ready-for-review"]}
+
+
+@pytest.mark.parametrize(
+    "repository",
+    [
+        None,
+        "",
+        " ",
+        "owner",
+        "owner/",
+        "/repo",
+        "owner/repo/extra",
+        "owner/..",
+        "./repo",
+        "owner/repo?x=1",
+        "https://github.com/owner/repo",
+        "git@github.com:owner/repo",
+        "owner/repo\nx",
+        ["owner", "repo"],
+    ],
+)
+def test_invalid_repository_fails_before_any_api_call(context, api, repository):
+    _, calls = api
+    step = get_step_type("github")
+    assert step.validate(config(repository=repository))
+    result = step.execute(config(repository=repository), context)
+    assert result.status == StepStatus.FAILED
+    assert "repository" in result.error
+    assert calls == []
+
+
+def test_invalid_resolved_repository_fails_before_api_call(context, api):
+    _, calls = api
+    context.inputs["repository"] = "other/repo/extra"
+    step = get_step_type("github")
+    definition = config(repository="{{ inputs.repository }}")
+    assert step.validate(definition) == []
+    result = step.execute(definition, context)
+    assert result.status == StepStatus.FAILED
+    assert "repository" in result.error
+    assert calls == []
+
+
 @pytest.mark.parametrize("number", [0, -1, True, None, "1; echo bad", ""])
 def test_invalid_number_fails_before_any_api_call(context, api, number):
     _, calls = api
@@ -136,6 +209,7 @@ def test_missing_fields_and_unsupported_operations_fail(context, api):
         config(operation="comment"),
         {key: value for key, value in config().items() if key != "label"},
         {key: value for key, value in config().items() if key != "number"},
+        {key: value for key, value in config().items() if key != "repository"},
         config(body="unexpected"),
     ):
         assert step.validate(broken)
@@ -210,51 +284,6 @@ def fake_run(args, root, *, input_text=None):
     assert "ready" not in observed[0][0]
 
 
-@pytest.mark.parametrize(
-    "origin",
-    [
-        "https://github.com/owner/repo.git",
-        "https://github.com/owner/repo",
-        "https://GitHub.COM/owner/repo.git",
-        "git@github.com:owner/repo.git",
-        "git@github.com:owner/repo",
-        "git@GITHUB.com:owner/repo.git",
-        "ssh://git@github.com/owner/repo.git",
-        "ssh://git@GITHUB.COM/owner/repo",
-    ],
-)
-def test_github_origin_derives_repository_and_api_url(context, monkeypatch, origin):
-    root = Path(context.project_root)
-    calls = []
-
-    def fake_run(args, cwd, *, input_text=None):
-        calls.append((args, cwd))
-        return origin
-
-    monkeypatch.setattr(github, "_run", fake_run)
-    assert github._identity(root) == (
-        "owner/repo",
-        "https://api.github.com/repos/owner/repo",
-    )
-    assert calls == [(["git", "remote", "get-url", "origin"], root)]
-
-
-@pytest.mark.parametrize(
-    "origin",
-    [
-        "https://evil.example/o/r.git",
-        "https://github.com.evil.example/o/r.git",
-        "ssh://git@github.com.evil.example/o/r.git",
-        "ssh://other@github.com/o/r.git",
-        "git@github.com.evil.example:o/r.git",
-    ],
-)
-def test_origin_must_be_github_dot_com(context, monkeypatch, origin):
-    monkeypatch.setattr(github, "_run", lambda args, root, **kwargs: origin)
-    with pytest.raises(ValueError, match="github.com origin"):
-        github._identity(Path(context.project_root))
-
-
 def test_engine_executes_label_yaml_and_fan_out_with_retries(context, api):
     labels, calls = api
     workflow = WorkflowDefinition.from_string("""
@@ -272,6 +301,7 @@ def test_engine_executes_label_yaml_and_fan_out_with_retries(context, api):
       id: add-label
       type: github
       operation: add-label
+      repository: owner/repo
       target: issue
       number: 12
       label: "{{ item }}"

From 5d39d3199e91d176800ab868cc5ae17fa1729fc7 Mon Sep 17 00:00:00 2001
From: Manfred Riem <15701806+mnriem@users.noreply.github.com>
Date: Fri, 9 Oct 2026 17:24:58 -0500
Subject: [PATCH 10/10] Keep bundled extension outside GitHub step PR

Restore the opt-in extension README to the target branch version. The built-in label step is documented in the workflow reference, so this PR does not ship an extension change or require an extension version bump.

Assisted-by: GitHub Copilot (model: GPT-6 Sol, autonomous)

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot-Session: ec94c538-a8b2-4c39-81fc-3ba5f0a59ce6
---
 extensions/github/README.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/extensions/github/README.md b/extensions/github/README.md
index bab697b451..8aaf46a5c3 100644
--- a/extensions/github/README.md
+++ b/extensions/github/README.md
@@ -1,8 +1,8 @@
 # GitHub Integration Extension
 
-This bundled, **opt-in** extension owns Spec Kit's GitHub *agent command* functionality. Today it provides one command, `speckit.github.taskstoissues`, which turns a feature's `tasks.md` into dependency-ordered GitHub issues. The separate built-in [`github` workflow step](../../docs/reference/workflows.md#github-step) adds an explicitly configured issue or pull-request label: registering the step does not install this extension or invoke the step automatically. A workflow must explicitly select `type: github` to run it.
+This bundled, **opt-in** extension is the home for Spec Kit's GitHub *platform* functionality. Today it provides one command, `speckit.github.taskstoissues`, which turns a feature's `tasks.md` into dependency-ordered GitHub issues.
 
-> NOTE: `git` and `github` are deliberately separate domains. The [`git` extension](../git/README.md) owns local version-control workflow (feature branches, commits, remote detection); this extension owns its GitHub agent command, not the workflow engine's built-in step.
+> NOTE: `git` and `github` are deliberately separate domains. The [`git` extension](../git/README.md) owns local version-control workflow (feature branches, commits, remote detection); this extension owns interactions with the GitHub platform itself.
 
 ## Why an extension?