Skip to content

💫 Toolkit to help you get started with SDD or any other process!

466 KB
Raw Blame
"""Tests for the workflow engine subsystem.

Covers:
- Step registry & auto-discovery
- Base classes (StepBase, StepContext, StepResult)
- Expression engine
- All 14 built-in step types
- Workflow definition loading & validation
- Workflow engine execution & state persistence
- Workflow catalog & registry
"""

from __future__ import annotations

import json

import os
import shutil
import stat
import sys
import tempfile
from pathlib import Path

import pytest
import yaml


# ---------------------------------------------------------------------------
# Fixtures
# ---------------------------------------------------------------------------

@pytest.fixture
def temp_dir():
    """Create a temporary directory for tests."""
    tmpdir = tempfile.mkdtemp()
    yield Path(tmpdir)
    # On Windows, file handles from dynamic imports or registry access may
    # still be held briefly after the test. Use ignore_errors to avoid
    # flaky teardown failures (WinError 32).
    shutil.rmtree(tmpdir, ignore_errors=(sys.platform == "win32"))


@pytest.fixture
def project_dir(temp_dir):
    """Create a mock spec-kit project with .specify/ directory."""
    specify_dir = temp_dir / ".specify"
    specify_dir.mkdir()
    (specify_dir / "workflows").mkdir()
    return temp_dir


@pytest.fixture
def sample_workflow_yaml():
    """Return a valid minimal workflow YAML string."""
    return """
schema_version: "1.0"
workflow:
  id: "test-workflow"
  name: "Test Workflow"
  version: "1.0.0"
  description: "A test workflow"

inputs:
  spec:
    type: string
    required: true
  scope:
    type: string
    default: "full"

steps:
  - id: step-one
    command: speckit.specify
    input:
      args: "{{ inputs.spec }}"

  - id: step-two
    command: speckit.plan
    input:
      args: "{{ steps.step-one.output.command }}"
"""


@pytest.fixture
def sample_workflow_file(project_dir, sample_workflow_yaml):
    """Write a sample workflow YAML to a file and return its path."""
    wf_dir = project_dir / ".specify" / "workflows" / "test-workflow"
    wf_dir.mkdir(parents=True, exist_ok=True)
    wf_path = wf_dir / "workflow.yml"
    wf_path.write_text(sample_workflow_yaml, encoding="utf-8")
    return wf_path


# ===== Step Registry Tests =====

class TestStepRegistry:
    """Test STEP_REGISTRY and auto-discovery."""

    def test_registry_populated(self):
        from specify_cli.workflows import STEP_REGISTRY

        assert len(STEP_REGISTRY) >= 10

    def test_all_step_types_registered(self):
        from specify_cli.workflows import STEP_REGISTRY

        expected = {
            "command", "shell", "prompt", "gate", "if", "switch",
            "while", "do-while", "fan-out", "fan-in", "init", "slot", "github", "workflow",
        }
        assert expected.issubset(set(STEP_REGISTRY.keys()))

    def test_get_step_type(self):
        from specify_cli.workflows import get_step_type

        step = get_step_type("command")
        assert step is not None
        assert step.type_key == "command"

    def test_get_step_type_missing(self):
        from specify_cli.workflows import get_step_type

        assert get_step_type("nonexistent") is None

    def test_register_step_duplicate_raises(self):
        from specify_cli.workflows import _register_step
        from specify_cli.workflows.step.command import CommandStep

        with pytest.raises(KeyError, match="already registered"):
            _register_step(CommandStep())

    def test_register_step_empty_key_raises(self):
        from specify_cli.workflows import _register_step
        from specify_cli.workflows.base import StepBase, StepResult

        class EmptyStep(StepBase):
            type_key = ""
            def execute(self, config, context):
                return StepResult()

        with pytest.raises(ValueError, match="empty type_key"):
            _register_step(EmptyStep())


# ===== Base Classes Tests =====

class TestBaseClasses:
    """Test StepBase, StepContext, StepResult."""

    def test_step_context_defaults(self):
        from specify_cli.workflows.base import StepContext

        ctx = StepContext()
        assert ctx.inputs == {}
        assert ctx.steps == {}
        assert ctx.item is None
        assert ctx.fan_in == {}
        assert ctx.default_integration is None

    def test_step_context_with_data(self):
        from specify_cli.workflows.base import StepContext

        ctx = StepContext(
            inputs={"name": "test"},
            default_integration="claude",
            default_model="sonnet-4",
        )
        assert ctx.inputs == {"name": "test"}
        assert ctx.default_integration == "claude"
        assert ctx.default_model == "sonnet-4"

    def test_step_result_defaults(self):
        from specify_cli.workflows.base import StepResult, StepStatus

        result = StepResult()
        assert result.status == StepStatus.COMPLETED
        assert result.output == {}
        assert result.next_steps == []
        assert result.error is None

    def test_step_status_values(self):
        from specify_cli.workflows.base import StepStatus

        assert StepStatus.PENDING == "pending"
        assert StepStatus.RUNNING == "running"
        assert StepStatus.COMPLETED == "completed"
        assert StepStatus.FAILED == "failed"
        assert StepStatus.SKIPPED == "skipped"
        assert StepStatus.PAUSED == "paused"

    def test_run_status_values(self):
        from specify_cli.workflows.base import RunStatus

        assert RunStatus.CREATED == "created"
        assert RunStatus.RUNNING == "running"
        assert RunStatus.PAUSED == "paused"
        assert RunStatus.COMPLETED == "completed"
        assert RunStatus.FAILED == "failed"
        assert RunStatus.ABORTED == "aborted"


# ===== Expression Engine Tests =====

class TestExpressions:
    """Test sandboxed expression evaluator."""

    def test_simple_variable(self):
        from specify_cli.workflows.expressions import evaluate_expression
        from specify_cli.workflows.base import StepContext

        ctx = StepContext(inputs={"name": "login"})
        assert evaluate_expression("{{ inputs.name }}", ctx) == "login"

    def test_step_output_reference(self):
        from specify_cli.workflows.expressions import evaluate_expression
        from specify_cli.workflows.base import StepContext

        ctx = StepContext(
            steps={"specify": {"output": {"file": "spec.md"}}}
        )
        assert evaluate_expression("{{ steps.specify.output.file }}", ctx) == "spec.md"

    def test_string_interpolation(self):
        from specify_cli.workflows.expressions import evaluate_expression
        from specify_cli.workflows.base import StepContext

        ctx = StepContext(inputs={"name": "login"})
        result = evaluate_expression("Feature: {{ inputs.name }} done", ctx)
        assert result == "Feature: login done"

    def test_multi_expression_no_surrounding_text(self):
        """Two expressions with no surrounding literal text must interpolate each,
        not collapse to None via the fullmatch fast path (#3208)."""
        from specify_cli.workflows.expressions import evaluate_expression
        from specify_cli.workflows.base import StepContext

        ctx = StepContext(inputs={"issue": "23"}, run_id="47c5eb4b")
        result = evaluate_expression(
            "{{ context.run_id }} {{ inputs.issue }}", ctx
        )
        assert result == "47c5eb4b 23"

    def test_multi_expression_adjacent_no_separator(self):
        """Back-to-back expressions with no separator still interpolate (#3208)."""
        from specify_cli.workflows.expressions import evaluate_expression
        from specify_cli.workflows.base import StepContext

        ctx = StepContext(inputs={"a": "foo", "b": "bar"})
        result = evaluate_expression("{{ inputs.a }}{{ inputs.b }}", ctx)
        assert result == "foobar"

    def test_single_expression_with_literal_braces_preserves_type(self):
        """A lone expression whose string argument contains a literal ``{{`` or ``}}``
        must still take the typed fast path and return a bool, not a string
        (the fix for #3208 must not coerce it to ``\"True\"``)."""
        from specify_cli.workflows.expressions import evaluate_expression
        from specify_cli.workflows.base import StepContext

        ctx = StepContext(inputs={"text": "uses {{ jinja }} syntax"})
        assert evaluate_expression("{{ inputs.text | contains('{{') }}", ctx) is True

        ctx = StepContext(inputs={"text": "uses }} syntax"})
        assert evaluate_expression("{{ inputs.text | contains('}}') }}", ctx) is True

    def test_multi_expression_with_literal_close_brace_in_argument(self):
        """A multi-expression template with a literal ``}}`` inside a string
        argument must interpolate, not raise. #3208/#3228 hardened the single-
        expression fast path for literal braces but left the interpolation path
        on ``_EXPR_PATTERN``, whose non-greedy body stops at the first ``}}`` --
        so the block was captured truncated and the filter parser raised
        ValueError."""
        from specify_cli.workflows.expressions import evaluate_expression
        from specify_cli.workflows.base import StepContext

        ctx = StepContext(inputs={"name": "Bob", "missing": None})
        # ``}}`` in the default fallback of the second block.
        result = evaluate_expression(
            "{{ inputs.name }}: {{ inputs.missing | default('}}') }}", ctx
        )
        assert result == "Bob: }}"
        # ``}}`` in the first block, expression following it.
        result = evaluate_expression(
            "{{ inputs.missing | default('}}') }} / {{ inputs.name }}", ctx
        )
        assert result == "}} / Bob"

    def test_multi_expression_with_literal_open_brace_in_argument(self):
        """A literal ``{{`` inside a string argument in a multi-expression
        template must not confuse block detection either."""
        from specify_cli.workflows.expressions import evaluate_expression
        from specify_cli.workflows.base import StepContext

        ctx = StepContext(inputs={"name": "Bob", "missing": None})
        result = evaluate_expression(
            "{{ inputs.name }} {{ inputs.missing | default('{{') }}", ctx
        )
        assert result == "Bob {{"

    def test_multi_expression_unbalanced_quote_still_raises(self):
        """A malformed block (an unbalanced quote in a filter arg) must still
        surface a ValueError, not be silently emitted verbatim.

        The quote-aware scan never finds a block-closing ``}}`` when a quote is
        left open, but a raw ``}}`` is still present in the tail. It must fall
        back to that raw delimiter and evaluate — same as the old regex path —
        so a typo fails loudly instead of being hidden (Copilot review on
        #3307)."""
        import pytest

        from specify_cli.workflows.expressions import evaluate_expression
        from specify_cli.workflows.base import StepContext

        ctx = StepContext(inputs={"name": "Bob", "missing": None})
        with pytest.raises(ValueError):
            evaluate_expression(
                "{{ inputs.name }} {{ inputs.missing | default('oops }}", ctx
            )

    def test_comparison_equals(self):
        from specify_cli.workflows.expressions import evaluate_expression
        from specify_cli.workflows.base import StepContext

        ctx = StepContext(inputs={"scope": "full"})
        assert evaluate_expression("{{ inputs.scope == 'full' }}", ctx) is True
        assert evaluate_expression("{{ inputs.scope == 'partial' }}", ctx) is False

    def test_comparison_not_equals(self):
        from specify_cli.workflows.expressions import evaluate_expression
        from specify_cli.workflows.base import StepContext

        ctx = StepContext(
            steps={"run-tests": {"output": {"exit_code": 1}}}
        )
        result = evaluate_expression("{{ steps.run-tests.output.exit_code != 0 }}", ctx)
        assert result is True

    def test_numeric_comparison(self):
        from specify_cli.workflows.expressions import evaluate_expression
        from specify_cli.workflows.base import StepContext

        ctx = StepContext(
            steps={"plan": {"output": {"task_count": 7}}}
        )
        assert evaluate_expression("{{ steps.plan.output.task_count > 5 }}", ctx) is True
        assert evaluate_expression("{{ steps.plan.output.task_count < 5 }}", ctx) is False

    def test_ordering_comparison_of_non_numeric_strings(self):
        """`<`/`>`/`<=`/`>=` between non-numeric strings must compare
        lexicographically, not silently return False.

        `_safe_compare` used to coerce both operands to int/float unconditionally;
        a non-numeric string (date, version tag, name) failed that coercion and
        the whole comparison returned False. Ordinary strings should order the
        way Python does; numeric strings must still compare as numbers."""
        from specify_cli.workflows.expressions import evaluate_expression
        from specify_cli.workflows.base import StepContext

        # ISO dates compare lexicographically (correct chronological order).
        ctx = StepContext(inputs={"d": "2026-01-01"})
        assert evaluate_expression("{{ inputs.d < '2026-02-01' }}", ctx) is True
        assert evaluate_expression("{{ inputs.d > '2026-02-01' }}", ctx) is False

        # Plain string ordering.
        ctx = StepContext(inputs={"name": "beta"})
        assert evaluate_expression("{{ inputs.name > 'alpha' }}", ctx) is True

        # Two numeric strings still compare numerically, not lexically
        # ("10" > "9" is True as numbers; as strings it would be False).
        ctx = StepContext(inputs={"v": "10"})
        assert evaluate_expression("{{ inputs.v > '9' }}", ctx) is True

        # A number vs a non-numeric string is genuinely incomparable -> False.
        ctx = StepContext(inputs={"n": 5})
        assert evaluate_expression("{{ inputs.n > 'abc' }}", ctx) is False

    def test_boolean_and(self):
        from specify_cli.workflows.expressions import evaluate_expression
        from specify_cli.workflows.base import StepContext

        ctx = StepContext(inputs={"a": True, "b": True})
        assert evaluate_expression("{{ inputs.a and inputs.b }}", ctx) is True

    def test_boolean_or(self):
        from specify_cli.workflows.expressions import evaluate_expression
        from specify_cli.workflows.base import StepContext

        ctx = StepContext(inputs={"a": False, "b": True})
        assert evaluate_expression("{{ inputs.a or inputs.b }}", ctx) is True

    @pytest.mark.parametrize(("expression", "expected"), [
        ("inputs.payload != '' and (inputs.payload | from_json | length)", False),
        ("inputs.payload == '' or (inputs.payload | from_json | length)", True),
        ("false and true or true", True),
        ("true or (false and (inputs.payload | from_json))", True),
    ])
    def test_boolean_short_circuits(self, expression, expected):
        from specify_cli.workflows.expressions import evaluate_expression
        from specify_cli.workflows.base import StepContext

        assert evaluate_expression(
            "{{ " + expression + " }}", StepContext(inputs={"payload": ""})
        ) is expected

    @pytest.mark.parametrize("expression", [
        "true and (inputs.payload | from_json)",
        "false or (inputs.payload | from_json)",
        "(inputs.payload | from_json) and false",
        "(inputs.payload | from_json) or true",
    ])
    def test_boolean_required_operand_still_raises(self, expression):
        from specify_cli.workflows.expressions import evaluate_expression
        from specify_cli.workflows.base import StepContext

        with pytest.raises(ValueError, match="from_json: invalid JSON"):
            evaluate_expression(
                "{{ " + expression + " }}", StepContext(inputs={"payload": ""})
            )

    def test_list_literal_preserves_quoted_commas(self):
        from specify_cli.workflows.expressions import evaluate_expression
        from specify_cli.workflows.base import StepContext

        ctx = StepContext()
        # commas inside a double-quoted element must not split it
        assert evaluate_expression('{{ ["a, b", "c"] }}', ctx) == ["a, b", "c"]
        assert evaluate_expression('{{ ["x, y, z"] }}', ctx) == ["x, y, z"]
        # single-quoted elements are handled the same way
        assert evaluate_expression("{{ ['a, b', 'c'] }}", ctx) == ["a, b", "c"]
        assert evaluate_expression("{{ ['p, q, r'] }}", ctx) == ["p, q, r"]
        # plain and empty lists still parse correctly
        assert evaluate_expression("{{ [1, 2, 3] }}", ctx) == [1, 2, 3]
        assert evaluate_expression("{{ [] }}", ctx) == []
        # nested lists (commas inside the inner brackets) stay intact
        assert evaluate_expression('{{ [["a", "b"], "c"] }}', ctx) == [["a", "b"], "c"]
        assert evaluate_expression("{{ [[1, 2], [3, 4]] }}", ctx) == [[1, 2], [3, 4]]

    def test_list_literal_ignores_trailing_and_empty_commas(self):
        from specify_cli.workflows.expressions import evaluate_expression
        from specify_cli.workflows.base import StepContext

        ctx = StepContext()
        # A trailing comma must not append a spurious None element.
        assert evaluate_expression("{{ [1, 2,] }}", ctx) == [1, 2]
        assert evaluate_expression("{{ [1,, 2] }}", ctx) == [1, 2]
        # …but an intentional empty-string element is still preserved.
        assert evaluate_expression("{{ ['', 'a'] }}", ctx) == ["", "a"]

    def test_list_literal_followed_by_index_is_not_misparsed_as_one_literal(self):
        """A list literal immediately followed by an index suffix, e.g.
        ``[1,2,3][1]``, both starts with ``[`` and ends with ``]`` -- the
        same shape as a genuine single list literal. Naively stripping the
        outer brackets from ``[1,2,3][1]`` yields ``1,2,3][1``, which then
        silently evaluates to ``[1, 2, None]`` instead of raising or
        resolving the index. It must not be misclassified as one literal;
        falling through to unresolvable (``None``) is safe, unlike silently
        returning a wrong-looking list.
        """
        from specify_cli.workflows.expressions import evaluate_expression
        from specify_cli.workflows.base import StepContext

        ctx = StepContext()
        assert evaluate_expression("{{ [1,2,3][1] }}", ctx) is None
        assert evaluate_expression("{{ [1,2][0] }}", ctx) is None
        # Genuine list literals -- including ones a bracket-depth scan must
        # still recognize as ending exactly at the final character -- are
        # unaffected.
        assert evaluate_expression("{{ [1, 2, 3] }}", ctx) == [1, 2, 3]
        assert evaluate_expression("{{ [[1, 2], 3] }}", ctx) == [[1, 2], 3]
        assert evaluate_expression("{{ ['a]', 'b'] }}", ctx) == ["a]", "b"]

    def test_operator_splitting_is_quote_aware(self):
        from specify_cli.workflows.expressions import (
            evaluate_condition,
            evaluate_expression,
        )
        from specify_cli.workflows.base import StepContext

        # An 'and'/'or'/'in' keyword INSIDE a quoted operand must not be treated
        # as a boolean/membership operator: the comparison applies to the whole
        # string literal.
        ctx = StepContext(inputs={"mode": "read and write"})
        assert evaluate_expression("{{ inputs.mode == 'read and write' }}", ctx) is True
        assert evaluate_expression("{{ inputs.mode == 'read or write' }}", ctx) is False
        # ...also when the quoted literal is on the left of the operator.
        left_ctx = StepContext(inputs={"x": "approve or reject"})
        assert evaluate_expression("{{ 'approve or reject' == inputs.x }}", left_ctx) is True
        # membership against a literal that contains a keyword
        assert evaluate_expression("{{ 'cat' in 'cat and dog' }}", StepContext()) is True

        # Literal-vs-literal equality no longer mis-strips to a garbage string
        # (previously `'done' == 'failed'` short-circuited to the truthy string
        # "done' == 'failed").
        assert evaluate_condition("{{ 'done' == 'failed' }}", StepContext()) is False
        assert evaluate_condition("{{ 'done' == 'done' }}", StepContext()) is True

        # A single quoted literal that itself contains operator text is preserved.
        assert evaluate_expression("{{ 'a == b' }}", StepContext()) == "a == b"
        assert evaluate_expression("{{ 'x and y' }}", StepContext()) == "x and y"

        # Regression: ordinary (unquoted-keyword) parsing still works.
        plain = StepContext(inputs={"a": 1, "b": 2, "mode": "read"})
        assert evaluate_expression("{{ inputs.mode == 'read' }}", plain) is True
        assert evaluate_expression("{{ inputs.a == 1 and inputs.b == 2 }}", plain) is True
        assert evaluate_expression("{{ inputs.a == 9 or inputs.b == 2 }}", plain) is True
        assert evaluate_expression("{{ inputs.missing | default('a and b') }}", plain) == "a and b"

    def test_pipe_detection_is_quote_aware(self):
        from specify_cli.workflows.expressions import evaluate_expression
        from specify_cli.workflows.base import StepContext

        # A literal '|' inside a quoted operand must not be treated as a filter
        # pipe: the comparison applies to the whole string.
        ctx = StepContext(inputs={"x": "a|b"})
        assert evaluate_expression("{{ inputs.x == 'a|b' }}", ctx) is True
        assert evaluate_expression("{{ inputs.x == 'a|b' }}", StepContext(inputs={"x": "z"})) is False
        # membership against a literal containing a pipe
        assert evaluate_expression("{{ 'a|b' in inputs.s }}", StepContext(inputs={"s": "x a|b y"})) is True
        # a single quoted literal containing pipes is preserved
        assert evaluate_expression("{{ 'a|b|c' }}", StepContext()) == "a|b|c"

        # Regression: real filters still work, including a pipe inside a filter arg.
        ctx2 = StepContext(inputs={"items": ["a", "b"], "s": "xabz"})
        assert evaluate_expression("{{ inputs.missing | default('y') }}", ctx2) == "y"
        assert evaluate_expression('{{ inputs.items | join("-") }}', ctx2) == "a-b"
        assert evaluate_expression("{{ inputs.s | contains('ab') }}", ctx2) is True
        assert evaluate_expression("{{ inputs.missing | default('a|b') }}", ctx2) == "a|b"

    def test_membership_against_non_iterable_is_false_not_error(self):
        from specify_cli.workflows.expressions import (
            evaluate_condition,
            evaluate_expression,
        )
        from specify_cli.workflows.base import StepContext

        # A non-iterable right operand (int, bool, None, float) makes a raw
        # `x in y` raise TypeError in Python. The evaluator must treat it as
        # "not contained" (False, and `not in` as True) instead of leaking the
        # TypeError and crashing the whole workflow run. This generalizes the
        # previous `right is not None` guard and mirrors _safe_compare, which
        # already swallows TypeError for the ordering operators.
        ctx = StepContext(inputs={"tag": "x", "count": 5, "ratio": 1.5, "flag": True})
        # `in` -> False and `not in` -> True for every non-iterable right
        # operand (int, float, bool, None), so neither operator can drift.
        for right in ("count", "ratio", "flag", "missing"):
            assert evaluate_expression(f"{{{{ inputs.tag in inputs.{right} }}}}", ctx) is False
            assert evaluate_expression(f"{{{{ inputs.tag not in inputs.{right} }}}}", ctx) is True
        # A condition that would otherwise crash the run now evaluates cleanly.
        assert evaluate_condition("{{ inputs.tag in inputs.count }}", ctx) is False

        # Regression: genuine membership over a real iterable still works.
        ok = StepContext(inputs={"items": ["x", "y"], "s": "xyz"})
        assert evaluate_expression("{{ 'x' in inputs.items }}", ok) is True
        assert evaluate_expression("{{ 'z' not in inputs.items }}", ok) is True
        assert evaluate_expression("{{ 'y' in inputs.s }}", ok) is True

    def test_filter_default(self):
        from specify_cli.workflows.expressions import evaluate_expression
        from specify_cli.workflows.base import StepContext

        ctx = StepContext()
        assert evaluate_expression("{{ inputs.missing | default('fallback') }}", ctx) == "fallback"

    def test_filter_join(self):
        from specify_cli.workflows.expressions import evaluate_expression
        from specify_cli.workflows.base import StepContext

        ctx = StepContext(inputs={"tags": ["a", "b", "c"]})
        assert evaluate_expression("{{ inputs.tags | join(', ') }}", ctx) == "a, b, c"

    def test_filter_contains(self):
        from specify_cli.workflows.expressions import evaluate_expression
        from specify_cli.workflows.base import StepContext

        ctx = StepContext(inputs={"text": "hello world"})
        assert evaluate_expression("{{ inputs.text | contains('world') }}", ctx) is True

    def test_filter_from_json_parses_object(self):
        from specify_cli.workflows.expressions import evaluate_expression
        from specify_cli.workflows.base import StepContext

        ctx = StepContext(
            steps={"emit": {"output": {"stdout": '{"items": [1, 2, 3]}'}}}
        )
        result = evaluate_expression("{{ steps.emit.output.stdout | from_json }}", ctx)
        assert result == {"items": [1, 2, 3]}

    def test_filter_from_json_invalid_json_raises(self):
        import pytest
        from specify_cli.workflows.expressions import evaluate_expression
        from specify_cli.workflows.base import StepContext

        ctx = StepContext(steps={"emit": {"output": {"stdout": "not json"}}})
        with pytest.raises(ValueError, match="from_json: invalid JSON"):
            evaluate_expression("{{ steps.emit.output.stdout | from_json }}", ctx)

    def test_filter_from_json_non_string_raises(self):
        import pytest
        from specify_cli.workflows.expressions import evaluate_expression
        from specify_cli.workflows.base import StepContext

        ctx = StepContext(steps={"emit": {"output": {"exit_code": 0}}})
        with pytest.raises(ValueError, match="expected a JSON string"):
            evaluate_expression("{{ steps.emit.output.exit_code | from_json }}", ctx)

    def test_filter_from_json_rejects_malformed_forms(self):
        # `from_json` is strict: no arguments and no trailing tokens. Every
        # mis-wired form — parenthesized, accidental arg, or trailing
        # garbage — must raise rather than silently fall through to the
        # unknown-filter path and return the unparsed value.
        import pytest
        from specify_cli.workflows.expressions import evaluate_expression
        from specify_cli.workflows.base import StepContext

        ctx = StepContext(steps={"emit": {"output": {"stdout": '{"a": 1}'}}})
        bad_forms = (
            "from_json()",
            "from_json('x')",
            "from_json ()",
            "from_json ('x')",
            "from_json)",
            "from_json extra",
            "from_json 'x'",
        )
        for bad in bad_forms:
            with pytest.raises(ValueError, match="from_json: expected"):
                evaluate_expression(
                    "{{ steps.emit.output.stdout | " + bad + " }}", ctx
                )

    def test_filter_upper_and_lower(self):
        from specify_cli.workflows.expressions import evaluate_expression
        from specify_cli.workflows.base import StepContext

        ctx = StepContext(inputs={"s": "Hello World", "empty": "", "mixed": "aBc"})
        assert evaluate_expression("{{ inputs.s | upper }}", ctx) == "HELLO WORLD"
        assert evaluate_expression("{{ inputs.s | lower }}", ctx) == "hello world"
        # An empty string is valid input, not a missing value: it must come back
        # empty rather than raising or falling through to `default`.
        assert evaluate_expression("{{ inputs.empty | upper }}", ctx) == ""
        assert evaluate_expression("{{ inputs.empty | lower }}", ctx) == ""
        # Case-only transforms are no-ops on already-conforming input.
        assert evaluate_expression("{{ inputs.mixed | upper }}", ctx) == "ABC"
        # Non-ASCII text uses Unicode case mapping without transliteration or loss.
        assert evaluate_expression("{{ inputs.uni | upper }}", StepContext(inputs={"uni": "café"})) == "CAFÉ"
        # Filters compose left to right with the rest of the chain.
        assert evaluate_expression("{{ inputs.s | upper | lower }}", ctx) == "hello world"

    def test_filter_upper_rejects_non_string(self):
        # A non-string value is an authoring mistake (e.g. `| upper` on an exit
        # code). It must raise a ValueError naming the problem rather than
        # coerce to "3" — which would look like a plausible result and hide the
        # mis-wiring — or leak AttributeError and crash the run.
        import pytest
        from specify_cli.workflows.expressions import evaluate_expression
        from specify_cli.workflows.base import StepContext

        ctx = StepContext(inputs={"items": ["a"], "n": 3, "flag": True, "none": None})
        for name in ("items", "n", "flag", "none"):
            with pytest.raises(ValueError, match="upper: expected a string value"):
                evaluate_expression("{{ inputs." + name + " | upper }}", ctx)

    def test_filter_lower_rejects_non_string(self):
        import pytest
        from specify_cli.workflows.expressions import evaluate_expression
        from specify_cli.workflows.base import StepContext

        ctx = StepContext(inputs={"items": ["a"], "n": 3, "flag": True, "none": None})
        for name in ("items", "n", "flag", "none"):
            with pytest.raises(ValueError, match="lower: expected a string value"):
                evaluate_expression("{{ inputs." + name + " | lower }}", ctx)

    def test_filter_split(self):
        from specify_cli.workflows.expressions import evaluate_expression
        from specify_cli.workflows.base import StepContext

        ctx = StepContext(
            inputs={
                "csv": "a,b,c",
                "multi": "x::y::z",
                "empty": "",
                "nodelim": "abc",
                "trailing": "a,b,",
            }
        )
        assert evaluate_expression("{{ inputs.csv | split(',') }}", ctx) == ["a", "b", "c"]
        assert evaluate_expression("{{ inputs.multi | split('::') }}", ctx) == ["x", "y", "z"]
        # An empty string is the one-element list [''], matching str.split. It
        # must not be treated as a missing value or return [].
        assert evaluate_expression("{{ inputs.empty | split(',') }}", ctx) == [""]
        # A separator that never occurs yields the whole string, not [].
        assert evaluate_expression("{{ inputs.nodelim | split(',') }}", ctx) == ["abc"]
        # Trailing empty field is preserved, so round-tripping is lossless.
        assert evaluate_expression("{{ inputs.trailing | split(',') }}", ctx) == ["a", "b", ""]
        # split composes with join to convert delimiters.
        assert evaluate_expression("{{ inputs.csv | split(',') | join('-') }}", ctx) == "a-b-c"

    def test_filter_split_rejects_non_string_inputs(self):
        # Both the value and the separator must be strings. A non-string
        # separator would otherwise leak a TypeError/AttributeError from
        # str.split and crash the run.
        import pytest
        from specify_cli.workflows.expressions import evaluate_expression
        from specify_cli.workflows.base import StepContext

        ctx = StepContext(inputs={"items": ["a", "b"], "csv": "a,b", "n": 3})
        with pytest.raises(ValueError, match="split: expected a string value"):
            evaluate_expression("{{ inputs.items | split(',') }}", ctx)
        with pytest.raises(ValueError, match="split: expected a string separator"):
            evaluate_expression("{{ inputs.csv | split(5) }}", ctx)

    def test_filter_split_rejects_empty_separator(self):
        # `str.split("")` raises the bare `ValueError: empty separator`, which
        # names neither the filter nor the expression and escapes the evaluator
        # as a raw Python error. An empty separator has no meaning, so it must
        # be reported by the filter itself like every other misuse.
        import pytest
        from specify_cli.workflows.expressions import evaluate_expression
        from specify_cli.workflows.base import StepContext

        ctx = StepContext(inputs={"csv": "a,b"})
        with pytest.raises(ValueError, match="split: separator must not be empty"):
            evaluate_expression("{{ inputs.csv | split('') }}", ctx)

    def test_filter_length(self):
        from specify_cli.workflows.expressions import evaluate_expression
        from specify_cli.workflows.base import StepContext

        ctx = StepContext(
            inputs={
                "items": ["a", "b", "c"],
                "empty_list": [],
                "s": "hello",
                "empty_str": "",
            }
        )
        assert evaluate_expression("{{ inputs.items | length }}", ctx) == 3
        assert evaluate_expression("{{ inputs.empty_list | length }}", ctx) == 0
        # Strings count characters, as in Jinja2.
        assert evaluate_expression("{{ inputs.s | length }}", ctx) == 5
        assert evaluate_expression("{{ inputs.empty_str | length }}", ctx) == 0
        # Composes with the rest of the chain, which is the motivating use.
        assert evaluate_expression("{{ inputs.csv_len | length }}", StepContext(inputs={"csv_len": "a,b,c"})) == 5
        assert evaluate_expression("{{ inputs.s | split('l') | length }}", ctx) == 3

    def test_filter_length_drives_conditions(self):
        # The motivating use: `length` makes an emptiness check expressible as a
        # condition, because 0 is falsy and any non-zero count is truthy.
        from specify_cli.workflows.expressions import evaluate_condition
        from specify_cli.workflows.base import StepContext

        ctx = StepContext(inputs={"items": ["a"], "empty": []})
        assert evaluate_condition("{{ inputs.items | length }}", ctx) is True
        assert evaluate_condition("{{ inputs.empty | length }}", ctx) is False

    def test_filter_length_rejects_unsupported_types(self):
        # length accepts only list and str. Mappings are excluded on purpose so
        # `{{ obj | length }}` cannot silently mean "key count" for one shape and
        # "value count" for another; other types are mis-wiring and must raise
        # rather than coerce to 0 (which is indistinguishable from "empty").
        import pytest
        from specify_cli.workflows.expressions import evaluate_expression
        from specify_cli.workflows.base import StepContext

        ctx = StepContext(
            inputs={"obj": {"a": 1}, "n": 3, "flag": True, "none": None, "ratio": 1.5}
        )
        with pytest.raises(ValueError, match="length: expected a list or string"):
            evaluate_expression("{{ inputs.obj | length }}", ctx)
        for name in ("n", "flag", "none", "ratio"):
            with pytest.raises(ValueError, match="length: expected a list or string"):
                evaluate_expression("{{ inputs." + name + " | length }}", ctx)

    def test_filter_to_json(self):
        from specify_cli.workflows.expressions import evaluate_expression
        from specify_cli.workflows.base import StepContext

        ctx = StepContext(
            inputs={
                "obj": {"b": 2, "a": 1},
                "items": [1, 2, 3],
                "s": "hi",
                "n": 3,
                "flag": False,
                "none": None,
                "uni": "café",
            }
        )
        # sort_keys=True pins key order, so output does not depend on dict
        # insertion order and stays byte-stable across runs.
        assert evaluate_expression("{{ inputs.obj | to_json }}", ctx) == '{"a": 1, "b": 2}'
        assert evaluate_expression("{{ inputs.items | to_json }}", ctx) == "[1, 2, 3]"
        assert evaluate_expression("{{ inputs.s | to_json }}", ctx) == '"hi"'
        assert evaluate_expression("{{ inputs.n | to_json }}", ctx) == "3"
        assert evaluate_expression("{{ inputs.flag | to_json }}", ctx) == "false"
        assert evaluate_expression("{{ inputs.none | to_json }}", ctx) == "null"
        # ensure_ascii=False keeps non-ASCII readable instead of \uXXXX-escaped,
        # so shell steps receive the original text.
        assert evaluate_expression("{{ inputs.uni | to_json }}", ctx) == '"café"'

    def test_filter_to_json_round_trips_from_json(self):
        # to_json is the inverse of from_json: a structured value survives an
        # evaluator-level round trip. Nothing here exercises a shell, and the
        # round trip is not extended to one — interpolation adds no quoting, so
        # the output is reproducible but not shell-safe (see docs/reference/
        # workflows.md, "Interpolation and shell safety").
        from specify_cli.workflows.expressions import evaluate_expression
        from specify_cli.workflows.base import StepContext

        ctx = StepContext(
            inputs={"obj": {"items": [1, 2, 3]}},
            steps={"emit": {"output": {"stdout": '{"items": [1, 2, 3]}'}}},
        )
        assert evaluate_expression(
            "{{ steps.emit.output.stdout | from_json | to_json }}", ctx
        ) == '{"items": [1, 2, 3]}'
        assert evaluate_expression(
            "{{ inputs.obj | to_json | from_json }}", ctx
        ) == {"items": [1, 2, 3]}

    def test_filter_to_json_rejects_non_serializable(self):
        # A non-serializable value must raise a ValueError naming the filter,
        # not leak a TypeError from json.dumps and crash the run.
        import pytest
        from specify_cli.workflows.expressions import evaluate_expression
        from specify_cli.workflows.base import StepContext

        ctx = StepContext(inputs={"obj": {"f": object()}, "step": object()})
        with pytest.raises(ValueError, match="to_json: value is not JSON-serializable"):
            evaluate_expression("{{ inputs.obj | to_json }}", ctx)
        with pytest.raises(ValueError, match="to_json: value is not JSON-serializable"):
            evaluate_expression("{{ inputs.step | to_json }}", ctx)

    def test_filter_to_json_rejects_non_finite_floats(self):
        # json.dumps defaults to allow_nan=True, which would emit bare
        # NaN/Infinity/-Infinity — none of them valid JSON. All three must
        # take the ValueError path instead, both at the top level and when
        # they are buried inside a container.
        import pytest
        from specify_cli.workflows.expressions import evaluate_expression
        from specify_cli.workflows.base import StepContext

        ctx = StepContext(
            inputs={
                "nan": float("nan"),
                "inf": float("inf"),
                "ninf": float("-inf"),
                "nested": [float("nan")],
            }
        )
        for name in ("nan", "inf", "ninf", "nested"):
            with pytest.raises(
                ValueError, match="to_json: value is not JSON-serializable"
            ):
                evaluate_expression(f"{{{{ inputs.{name} | to_json }}}}", ctx)

    def test_filter_to_json_rejects_non_string_keys(self):
        # JSON objects have string keys only. Without this check, json.dumps
        # would coerce 1 to "1" -- colliding with an existing "1" key -- and
        # sort_keys=True would raise an ordering TypeError on mixed key types,
        # which surfaced as a generic "not JSON-serializable" hiding the real
        # authoring mistake.
        import pytest
        from specify_cli.workflows.expressions import evaluate_expression
        from specify_cli.workflows.base import StepContext

        ctx = StepContext(
            inputs={
                "mixed": {1: "a", "2": "b"},
                "intkey": {1: "a"},
                "nested": {"outer": {3: "deep"}},
                "strkey": {"1": "a", "2": "b"},
            }
        )
        for name in ("mixed", "intkey", "nested"):
            with pytest.raises(
                ValueError, match="to_json: mapping keys must be strings"
            ):
                evaluate_expression(f"{{{{ inputs.{name} | to_json }}}}", ctx)
        # String keys, digit strings included, still serialize normally.
        assert (
            evaluate_expression("{{ inputs.strkey | to_json }}", ctx)
            == '{"1": "a", "2": "b"}'
        )

    def test_split_with_extra_argument_reports_unsupported_form(self):
        # split is new in this PR, so main's multi-argument guard has to cover
        # it as well. Without that it evaluated the argument fragment first and
        # reported "expected a string separator, got NoneType" -- the extra
        # argument, which is what the author actually got wrong, never
        # surfaced. main already pins default() and join() the same way; this
        # pins the filter added here.
        import pytest
        from specify_cli.workflows.expressions import evaluate_expression
        from specify_cli.workflows.base import StepContext

        ctx = StepContext(inputs={"s": "a,b,c"})
        with pytest.raises(
            ValueError, match="filter 'split' used in an unsupported form"
        ):
            evaluate_expression("{{ inputs.s | split(',', 1) }}", ctx)
        # A comma inside quotes is still a single argument.
        assert evaluate_expression("{{ inputs.s | split(',') }}", ctx) == [
            "a",
            "b",
            "c",
        ]

    def test_zero_arg_filters_reject_miswired_forms(self):
        # The strict no-argument branch is shared by from_json/upper/lower/
        # length/to_json. Every mis-wired form — parenthesized, accidental arg,
        # or trailing garbage — must raise naming the filter, rather than
        # silently falling through to the unknown-filter path.
        import pytest
        from specify_cli.workflows.expressions import evaluate_expression
        from specify_cli.workflows.base import StepContext

        ctx = StepContext(inputs={"s": "hi", "items": ["a"]})
        for fname in ("from_json", "upper", "lower", "length", "to_json"):
            for bad in (fname + "()", fname + "('x')", fname + ")", fname + " extra"):
                with pytest.raises(ValueError, match=fname + ": expected"):
                    evaluate_expression(
                        "{{ inputs.s | " + bad + " }}", ctx
                    )

    def test_filter_unknown_name_raises(self):
        # An unregistered filter name must fail loudly rather than silently
        # returning the unfiltered value (which hides a typo / unsupported
        # filter as a wrong result).
        import pytest
        from specify_cli.workflows.expressions import evaluate_expression
        from specify_cli.workflows.base import StepContext

        ctx = StepContext(inputs={"items": [1, 2, 3]})
        with pytest.raises(ValueError, match="unknown filter 'truncate'"):
            evaluate_expression("{{ inputs.items | truncate }}", ctx)

    def test_filter_unknown_name_with_args_raises(self):
        # The unknown-filter path must also catch the `name(arg)` form, which
        # otherwise falls through the recognized-args branch silently.
        import pytest
        from specify_cli.workflows.expressions import evaluate_expression
        from specify_cli.workflows.base import StepContext

        ctx = StepContext(inputs={"text": "hello"})
        with pytest.raises(ValueError, match="unknown filter 'truncate'"):
            evaluate_expression("{{ inputs.text | truncate('x') }}", ctx)

    def test_filter_map_non_string_attr_raises(self):
        # A non-string attribute (authoring mistake like `map(5)`) must raise a
        # ValueError naming the problem, not leak the cryptic AttributeError
        # from attr.split() that would escape the evaluator and crash the run.
        import pytest
        from specify_cli.workflows.expressions import evaluate_expression
        from specify_cli.workflows.base import StepContext

        ctx = StepContext(inputs={"rows": [{"id": "a"}, {"id": "b"}]})
        with pytest.raises(ValueError, match="map: expected a string attribute name"):
            evaluate_expression("{{ inputs.rows | map(5) }}", ctx)

    def test_filter_join_non_string_separator_raises(self):
        # A non-string separator (authoring mistake like `join(5)`) must raise a
        # ValueError, not leak the cryptic AttributeError from str.join.
        import pytest
        from specify_cli.workflows.expressions import evaluate_expression
        from specify_cli.workflows.base import StepContext

        ctx = StepContext(inputs={"tags": ["a", "b"]})
        with pytest.raises(ValueError, match="join: expected a string separator"):
            evaluate_expression("{{ inputs.tags | join(5) }}", ctx)

    def test_filter_contains_non_string_arg_on_string_raises(self):
        # For a string value, `contains` requires a string argument: `x in y` on
        # a string needs a string left operand. A non-string argument must raise
        # a ValueError, not leak the cryptic TypeError that would crash the run.
        import pytest
        from specify_cli.workflows.expressions import evaluate_expression
        from specify_cli.workflows.base import StepContext

        ctx = StepContext(inputs={"text": "hello"})
        with pytest.raises(ValueError, match="contains: expected a string argument"):
            evaluate_expression("{{ inputs.text | contains(5) }}", ctx)

    def test_filter_contains_non_string_arg_on_list_ok(self):
        # For a list value, membership of any element type is legitimate, so a
        # non-string argument stays valid and is not rejected.
        from specify_cli.workflows.expressions import evaluate_expression
        from specify_cli.workflows.base import StepContext

        ctx = StepContext(inputs={"nums": [1, 2, 5]})
        assert evaluate_expression("{{ inputs.nums | contains(5) }}", ctx) is True
        assert evaluate_expression("{{ inputs.nums | contains(9) }}", ctx) is False

    def test_registered_filters_unaffected(self):
        # Regression: every registered filter keeps working unchanged.
        from specify_cli.workflows.expressions import evaluate_expression
        from specify_cli.workflows.base import StepContext

        ctx = StepContext(
            inputs={
                "tags": ["a", "b", "c"],
                "text": "hello world",
                "missing": "",
                "rows": [{"id": "a"}, {"id": "b"}],
                "csv": "a,b,c",
                "obj": {"n": 1},
            },
            steps={"emit": {"output": {"stdout": '{"n": 1}'}}},
        )
        assert (
            evaluate_expression("{{ inputs.missing | default('fb') }}", ctx) == "fb"
        )
        assert evaluate_expression("{{ inputs.tags | join(', ') }}", ctx) == "a, b, c"
        assert evaluate_expression("{{ inputs.rows | map('id') }}", ctx) == ["a", "b"]
        assert (
            evaluate_expression("{{ inputs.text | contains('world') }}", ctx) is True
        )
        assert evaluate_expression(
            "{{ steps.emit.output.stdout | from_json }}", ctx
        ) == {"n": 1}
        assert evaluate_expression("{{ inputs.text | upper }}", ctx) == "HELLO WORLD"
        assert evaluate_expression("{{ inputs.text | lower }}", ctx) == "hello world"
        assert evaluate_expression("{{ inputs.csv | split(',') }}", ctx) == ["a", "b", "c"]
        assert evaluate_expression("{{ inputs.tags | length }}", ctx) == 3
        assert evaluate_expression("{{ inputs.obj | to_json }}", ctx) == '{"n": 1}'

    def test_registered_filter_list_covers_every_implemented_filter(self):
        # _REGISTERED_FILTERS drives the "known filter used in an unsupported
        # form" message, so it must stay in sync with what is implemented: a
        # registered-but-unimplemented name would be advertised in the expected
        # list yet raise as unknown.
        from specify_cli.workflows.expressions import _REGISTERED_FILTERS

        assert set(_REGISTERED_FILTERS) == {
            "default",
            "join",
            "map",
            "contains",
            "from_json",
            "upper",
            "lower",
            "split",
            "length",
            "to_json",
        }

    def test_registered_filter_unsupported_form_raises(self):
        # A *registered* filter used in an unsupported form (e.g. `| join` with
        # no argument) must fail loudly with a message that names it as a known
        # filter misused, not as an "unknown filter".
        import pytest
        from specify_cli.workflows.expressions import evaluate_expression
        from specify_cli.workflows.base import StepContext

        ctx = StepContext(inputs={"tags": ["a", "b", "c"]})
        with pytest.raises(
            ValueError, match="filter 'join' used in an unsupported form"
        ):
            evaluate_expression("{{ inputs.tags | join }}", ctx)
        with pytest.raises(
            ValueError, match="filter 'map' used in an unsupported form"
        ):
            evaluate_expression("{{ inputs.tags | map }}", ctx)
        # An arg-taking filter must not silently accept the wrong arity.
        with pytest.raises(
            ValueError, match="filter 'split' used in an unsupported form"
        ):
            evaluate_expression("{{ inputs.tags | split }}", ctx)
        with pytest.raises(
            ValueError, match="filter 'contains' used in an unsupported form"
        ):
            evaluate_expression("{{ inputs.tags | contains }}", ctx)

    def test_filter_call_with_trailing_tokens_fails_loudly(self):
        # A trailing operator/token after a filter's closing paren must not be
        # silently discarded (the parser used an unanchored regex). It must
        # fall through to the "unsupported form" ValueError, like the from_json
        # branch's strict trailing-token handling.
        import pytest
        from specify_cli.workflows.expressions import evaluate_expression
        from specify_cli.workflows.base import StepContext

        # A comparison after a filter (binds looser than the pipe) was dropped,
        # so `default('7') > '5'` silently returned '7'.
        with pytest.raises(ValueError, match="unsupported form"):
            evaluate_expression(
                "{{ inputs.missing | default('7') > '5' }}", StepContext(inputs={})
            )
        # Trailing garbage after a valid filter call.
        with pytest.raises(ValueError, match="unsupported form"):
            evaluate_expression(
                "{{ inputs.tags | join(',') extra }}",
                StepContext(inputs={"tags": ["a", "b"]}),
            )

    def test_multi_argument_filter_call_fails_loudly(self):
        """A second argument must be reported, not silently mis-evaluated.

        The whole captured argument text was handed to
        `_evaluate_simple_expression` as ONE expression. `"1, 2"` is not a valid
        expression, so it evaluated to None — making `default(1, 2)` return None
        (silently wrong) and `join(",", "extra")` raise a message blaming the
        separator rather than the extra argument.
        """
        import pytest
        from specify_cli.workflows.expressions import evaluate_expression
        from specify_cli.workflows.base import StepContext

        with pytest.raises(ValueError, match="unsupported form"):
            evaluate_expression(
                "{{ inputs.missing | default(1, 2) }}", StepContext(inputs={})
            )
        with pytest.raises(ValueError, match="unsupported form"):
            evaluate_expression(
                '{{ inputs.tags | join(",", "extra") }}',
                StepContext(inputs={"tags": ["a", "b"]}),
            )

    def test_single_argument_containing_a_comma_still_works(self):
        """The multi-argument check must skip quotes AND nested brackets.

        A single argument may legitimately contain a comma in two ways:

        * inside quotes — `join(", ")`, `default("a, b")`
        * inside a bracketed literal — `default([1, 2])`, which the expression
          evaluator supports and which resolves to a real list

        so the check uses `_find_top_level` (the same scanner the operator
        splitting uses) rather than a quote-only scan.
        """
        from specify_cli.workflows.expressions import evaluate_expression
        from specify_cli.workflows.base import StepContext

        ctx = StepContext(inputs={"tags": ["a", "b"]})
        assert evaluate_expression('{{ inputs.tags | join(", ") }}', ctx) == "a, b"
        assert evaluate_expression('{{ inputs.tags | join(",") }}', ctx) == "a,b"
        assert (
            evaluate_expression('{{ inputs.missing | default("a, b") }}', ctx)
            == "a, b"
        )
        # List literals: a comma inside brackets is not an argument separator.
        assert evaluate_expression(
            "{{ inputs.missing | default([1, 2]) }}", ctx
        ) == [1, 2]
        assert evaluate_expression(
            "{{ inputs.missing | default([1,2]) }}", ctx
        ) == [1, 2]
        assert evaluate_expression("{{ inputs.missing | default([]) }}", ctx) == []

    def test_multi_argument_after_a_literal_is_still_rejected(self):
        """A real second argument is rejected even when the first is a literal."""
        import pytest
        from specify_cli.workflows.expressions import evaluate_expression
        from specify_cli.workflows.base import StepContext

        with pytest.raises(ValueError, match="unsupported form"):
            evaluate_expression(
                "{{ inputs.missing | default([1,2], 3) }}", StepContext(inputs={})
            )

    def test_filter_on_a_comparison_operand_is_refused(self):
        """A filter mixed with a comparison must be reported, not guessed at.

        The pipe is detected before the operators, so
        `count > limit | default(5)` evaluated `count > limit` first and then
        applied `default` to the resulting bool — a no-op — silently returning
        the comparison against the *unfiltered* operand (False, where the author
        meant `10 > 5` = True).

        This is the mirror of a filter followed by a comparison
        (`default('7') > '5'`), which this module already refuses rather than
        guessing at the intended precedence. Both are now refused the same way.
        """
        import pytest
        from specify_cli.workflows.expressions import evaluate_expression
        from specify_cli.workflows.base import StepContext

        ctx = StepContext(inputs={"count": 10, "name": "x"})
        with pytest.raises(ValueError, match="ambiguous filter precedence"):
            evaluate_expression("{{ inputs.count > inputs.limit | default(5) }}", ctx)
        with pytest.raises(ValueError, match="ambiguous filter precedence"):
            evaluate_expression(
                '{{ inputs.name == inputs.other | default("x") }}', ctx
            )
        with pytest.raises(ValueError, match="ambiguous filter precedence"):
            evaluate_expression("{{ inputs.a and inputs.b | default(1) }}", ctx)

    def test_filter_after_a_unary_not_is_refused(self):
        """Unary `not` mis-binds the same way and must be caught too.

        `not` is a leading prefix rather than an infix token (the parser tests
        it with `expr.startswith("not ")`), so it has no surrounding space for
        the operator scan to match. Without an explicit check,
        `not inputs.missing | default(1)` evaluated `not inputs.missing` first
        and applied `default` to that boolean — a no-op — silently returning
        True where the author meant `not 1` = False.
        """
        import pytest
        from specify_cli.workflows.expressions import evaluate_expression
        from specify_cli.workflows.base import StepContext

        ctx = StepContext(inputs={"value": 0, "flag": True})
        with pytest.raises(ValueError, match="ambiguous filter precedence"):
            evaluate_expression("{{ not inputs.missing | default(1) }}", ctx)
        with pytest.raises(ValueError, match="ambiguous filter precedence"):
            evaluate_expression("{{ not inputs.value | default(1) }}", ctx)
        # A `not` that follows and/or is already caught by that token.
        with pytest.raises(ValueError, match="ambiguous filter precedence"):
            evaluate_expression(
                "{{ inputs.flag and not inputs.value | default(1) }}", ctx
            )
        # Plain unary `not`, with no filter, is untouched.
        assert evaluate_expression("{{ not inputs.value }}", ctx) is True
        assert evaluate_expression("{{ not inputs.flag }}", ctx) is False

    def test_plain_filters_and_chains_are_unaffected(self):
        """Only a filter mixed with an operator is refused."""
        from specify_cli.workflows.expressions import evaluate_expression
        from specify_cli.workflows.base import StepContext

        ctx = StepContext(inputs={"items": ["a", "b"], "count": 10, "name": "x"})
        assert evaluate_expression("{{ inputs.missing | default(5) }}", ctx) == 5
        assert evaluate_expression('{{ inputs.items | join(", ") }}', ctx) == "a, b"
        assert evaluate_expression("{{ inputs.items | contains('a') }}", ctx) is True
        # Operators without a filter, and filters without an operator, both fine.
        assert evaluate_expression("{{ inputs.count > 5 }}", ctx) is True
        assert evaluate_expression('{{ inputs.name == "x" }}', ctx) is True

    def test_chained_filters_apply_left_to_right(self):
        # Filters chain: each filter's result feeds the next. `map` yields a
        # list and `join` is the only filter that renders a list to a string,
        # so `map('name') | join(', ')` is the canonical pairing — it must not
        # raise. Previously the pipe parser split only at the first `|` and
        # handed the whole tail (`map('name') | join(', ')`) to one filter,
        # which the `name(arg)` regex mangled into a ValueError.
        from specify_cli.workflows.expressions import evaluate_expression
        from specify_cli.workflows.base import StepContext

        ctx = StepContext(
            inputs={
                "rows": [{"name": "a"}, {"name": "b"}],
                "tags": ["x", "y"],
                "missing": None,
            }
        )
        assert (
            evaluate_expression(
                "{{ inputs.rows | map('name') | join(', ') }}", ctx
            )
            == "a, b"
        )
        # A three-link chain: map -> join -> contains.
        assert (
            evaluate_expression(
                "{{ inputs.rows | map('name') | join(', ') | contains('a') }}",
                ctx,
            )
            is True
        )
        # default's fallback then flows into the next filter.
        assert (
            evaluate_expression(
                "{{ inputs.missing | default('x') | contains('x') }}", ctx
            )
            is True
        )

    def test_chained_filter_error_in_later_link_raises(self):
        # A mis-wired filter anywhere in the chain must fail loudly, not just
        # the first link.
        import pytest
        from specify_cli.workflows.expressions import evaluate_expression
        from specify_cli.workflows.base import StepContext

        ctx = StepContext(inputs={"rows": [{"name": "a"}]})
        with pytest.raises(ValueError, match="unknown filter 'bogus'"):
            evaluate_expression(
                "{{ inputs.rows | map('name') | bogus }}", ctx
            )

    def test_pipe_in_quoted_arg_is_not_a_filter_separator(self):
        # A literal `|` inside a quoted operand or filter argument must not be
        # mistaken for a filter-chain separator — the top-level split has to
        # respect quotes.
        from specify_cli.workflows.expressions import evaluate_expression
        from specify_cli.workflows.base import StepContext

        ctx = StepContext(inputs={"mode": "a|b", "tags": ["a|b", "c"]})
        assert evaluate_expression("{{ inputs.mode == 'a|b' }}", ctx) is True
        # `|` inside a filter argument stays part of the argument.
        assert (
            evaluate_expression("{{ inputs.tags | join(' | ') }}", ctx)
            == "a|b | c"
        )

    def test_condition_evaluation(self):
        from specify_cli.workflows.expressions import evaluate_condition
        from specify_cli.workflows.base import StepContext

        ctx = StepContext(inputs={"ready": True})
        assert evaluate_condition("{{ inputs.ready }}", ctx) is True
        assert evaluate_condition("{{ inputs.missing }}", ctx) is False

    def test_condition_strips_captured_command_output(self):
        """A condition resolving to captured stdout must honour "false".

        A ``shell`` step stores ``proc.stdout`` verbatim, so ``run: echo false``
        resolves to ``"false\\n"``. Without stripping, the trailing newline
        matched neither the "false" nor the "true" branch and fell through to
        ``bool("false\\n")`` -> True, so an ``if`` step took its ``then`` branch
        on a step that printed "false". There is no ``trim`` filter, so a
        workflow author cannot strip it themselves.
        """
        from specify_cli.workflows.expressions import evaluate_condition
        from specify_cli.workflows.base import StepContext

        ctx = StepContext(steps={"check": {"output": {"stdout": "false\n"}}})
        assert evaluate_condition("{{ steps.check.output.stdout }}", ctx) is False

        for raw in ("false\n", "false\r\n", " false", "false ", "FALSE\n"):
            assert evaluate_condition(raw, StepContext()) is False, raw
        for raw in ("true\n", " true ", "TRUE\r\n"):
            assert evaluate_condition(raw, StepContext()) is True, raw

    def test_condition_whitespace_only_string_stays_truthy(self):
        """Stripping must not turn a whitespace-only string into False.

        Only the "false"/"true" special case is stripped; everything else still
        falls through to ``bool(result)`` on the raw string.
        """
        from specify_cli.workflows.expressions import evaluate_condition
        from specify_cli.workflows.base import StepContext

        assert evaluate_condition("   ", StepContext()) is True
        assert evaluate_condition("falsey", StepContext()) is True

    def test_non_string_passthrough(self):
        from specify_cli.workflows.expressions import evaluate_expression
        from specify_cli.workflows.base import StepContext

        ctx = StepContext()
        assert evaluate_expression(42, ctx) == 42
        assert evaluate_expression(None, ctx) is None

    def test_string_literal(self):
        from specify_cli.workflows.expressions import evaluate_expression
        from specify_cli.workflows.base import StepContext

        ctx = StepContext()
        assert evaluate_expression("{{ 'hello' }}", ctx) == "hello"

    def test_numeric_literal(self):
        from specify_cli.workflows.expressions import evaluate_expression
        from specify_cli.workflows.base import StepContext

        ctx = StepContext()
        assert evaluate_expression("{{ 42 }}", ctx) == 42

    def test_boolean_literal(self):
        from specify_cli.workflows.expressions import evaluate_expression
        from specify_cli.workflows.base import StepContext

        ctx = StepContext()
        assert evaluate_expression("{{ true }}", ctx) is True
        assert evaluate_expression("{{ false }}", ctx) is False

    def test_parenthesised_grouping(self):
        """A parenthesised group is evaluated, not read as a dot path.

        The operator scans skip bracketed text so an operator inside an
        operand is not split on. Nothing unwrapped a group spanning the whole
        expression, so ``(a or b) and c`` split at the top-level ``and`` and
        then looked up ``(a or b)`` as a key, got ``None``, and read false --
        adding parentheses to make precedence explicit silently inverted the
        result.
        """
        from specify_cli.workflows.expressions import evaluate_expression
        from specify_cli.workflows.base import StepContext

        ctx = StepContext(inputs={"a": True, "b": False, "c": True, "n": 5})

        assert evaluate_expression("{{ (inputs.a or inputs.b) and inputs.c }}", ctx) is True
        assert evaluate_expression("{{ (inputs.b or inputs.b) and inputs.c }}", ctx) is False
        assert evaluate_expression("{{ (inputs.n) }}", ctx) == 5
        assert evaluate_expression("{{ (inputs.n > 1) }}", ctx) is True
        assert evaluate_expression("{{ ((inputs.n)) }}", ctx) == 5
        # A group is still only unwrapped when it spans the whole expression.
        assert evaluate_expression("{{ (inputs.a) and (inputs.b) }}", ctx) is False
        assert evaluate_expression("{{ (inputs.n) | default(9) }}", ctx) == 5
        # A parenthesis inside a string literal is not a group.
        assert evaluate_expression("{{ 'a(b' }}", ctx) == "a(b"
        assert evaluate_expression("{{ ('(') }}", ctx) == "("

    @pytest.mark.parametrize(
        ("expression", "expected"),
        [
            ("{{ inputs.b or\n  inputs.a }}", True),
            ("{{ inputs.a and\n  inputs.c }}", True),
            ("{{ inputs.b\nor inputs.a }}", True),
            ("{{ inputs.a\tand inputs.c }}", True),
            ("{{ not\n  inputs.b }}", True),
            ("{{ 'x' in\n  inputs.tags }}", True),
            ("{{ 'z' not\n  in inputs.tags }}", True),
            ("{{ 'z' not in\n  inputs.tags }}", True),
            ("{{ (inputs.b or\r\n  inputs.a) and inputs.c }}", True),
        ],
    )
    def test_operators_separated_by_any_whitespace(self, expression, expected):
        """Word operators are found across newlines and tabs, as in Jinja2.

        The operator scans match ``" or "`` and friends by their spaces, so an
        operator next to a line break was never split on: the whole expression
        was looked up as one dot path and came back ``None`` -- a false
        condition with no error.
        """
        from specify_cli.workflows.expressions import evaluate_expression
        from specify_cli.workflows.base import StepContext

        ctx = StepContext(
            inputs={"a": True, "b": False, "c": True, "mode": "fast", "tags": ["x", "y"]}
        )
        assert evaluate_expression(expression, ctx) is expected

    def test_condition_wrapped_across_lines_in_yaml(self):
        """A long condition broken after its operator keeps the line break in
        YAML (the continuation line is more indented, so ``>`` does not fold
        it), and still has to evaluate as written."""
        from specify_cli.workflows.expressions import evaluate_condition
        from specify_cli.workflows.base import StepContext

        step = yaml.safe_load(
            "condition: >-\n"
            "  {{ inputs.skip_review or\n"
            "     inputs.scope == 'docs' }}\n"
        )
        assert "\n" in step["condition"]

        ctx = StepContext(inputs={"skip_review": False, "scope": "docs"})
        assert evaluate_condition(step["condition"], ctx) is True

    def test_whitespace_inside_quoted_operand_is_kept(self):
        """Collapsing whitespace between tokens leaves string literals alone."""
        from specify_cli.workflows.expressions import evaluate_expression
        from specify_cli.workflows.base import StepContext

        ctx = StepContext(inputs={"title": "two  spaces", "text": "tab\there"})
        assert evaluate_expression("{{ inputs.title == 'two  spaces' }}", ctx) is True
        assert evaluate_expression("{{ inputs.title == 'two spaces' }}", ctx) is False
        assert evaluate_expression("{{ inputs.text\n  == 'tab\there' }}", ctx) is True
        assert evaluate_expression("{{ 'a  or  b' }}", ctx) == "a  or  b"

    def test_list_indexing(self):
        from specify_cli.workflows.expressions import evaluate_expression
        from specify_cli.workflows.base import StepContext

        ctx = StepContext(
            steps={"tasks": {"output": {"task_list": [{"file": "a.md"}, {"file": "b.md"}]}}}
        )
        result = evaluate_expression("{{ steps.tasks.output.task_list[0].file }}", ctx)
        assert result == "a.md"

    def test_negative_list_indexing(self):
        """``list[-1]`` resolves from the end, as Python and Jinja2 both do.

        Without it the index silently fell through to a dict lookup for the
        literal key ``"task_list[-1]"`` and produced ``None``, so a template
        reaching for the last element rendered empty with no error.
        """
        from specify_cli.workflows.expressions import evaluate_expression
        from specify_cli.workflows.base import StepContext

        ctx = StepContext(
            steps={"tasks": {"output": {"task_list": [{"file": "a.md"}, {"file": "b.md"}]}}}
        )
        assert evaluate_expression("{{ steps.tasks.output.task_list[-1].file }}", ctx) == "b.md"
        assert evaluate_expression("{{ steps.tasks.output.task_list[-2].file }}", ctx) == "a.md"
        # Out of range in either direction stays None rather than raising.
        assert evaluate_expression("{{ steps.tasks.output.task_list[-3] }}", ctx) is None
        assert evaluate_expression("{{ steps.tasks.output.task_list[2] }}", ctx) is None

    def test_context_run_id_resolves(self):
        """``{{ context.run_id }}`` resolves to ``StepContext.run_id``.

        Locks the contract from issue #2590: workflow templates can
        reference the engine-assigned run id for telemetry, artifact
        metadata, or per-run scratch isolation.
        """
        from specify_cli.workflows.expressions import evaluate_expression
        from specify_cli.workflows.base import StepContext

        ctx = StepContext(run_id="a1b2c3d4")
        assert evaluate_expression("{{ context.run_id }}", ctx) == "a1b2c3d4"

    def test_context_run_id_defaults_to_empty_when_unset(self):
        """``{{ context.run_id }}`` resolves to ``""`` when no run is
        active (dry-run, validation, ad-hoc evaluator usage) rather
        than raising — workflows referencing the variable never error
        outside a run context.
        """
        from specify_cli.workflows.expressions import evaluate_expression
        from specify_cli.workflows.base import StepContext

        # No run_id set on the context.
        ctx = StepContext()
        assert evaluate_expression("{{ context.run_id }}", ctx) == ""

    def test_context_run_id_string_interpolation(self):
        """Run id interpolates inside a larger template string — the
        common pattern for stamping shell commands and artifact paths
        with the run id.
        """
        from specify_cli.workflows.expressions import evaluate_expression
        from specify_cli.workflows.base import StepContext

        ctx = StepContext(run_id="deadbeef")
        result = evaluate_expression("RUN_ID={{ context.run_id }}", ctx)
        assert result == "RUN_ID=deadbeef"

    def test_comparison_greater_equal_and_less_equal(self):
        """``>=``/``<=`` evaluate like ``>``/``<``, for every operand shape.

        The operators were in ``_COMPARISON_OPERATORS`` and handed to
        ``_safe_compare``, but no test evaluated them, so the ``>=``/``<=``
        branches and their ordering relative to the single-char operators were
        unpinned.
        """
        from specify_cli.workflows.expressions import evaluate_expression
        from specify_cli.workflows.base import StepContext

        ctx = StepContext(inputs={"n": 5, "s10": "10", "s9": "9", "lo": "alpha", "hi": "beta"})
        assert evaluate_expression("{{ inputs.n >= 5 }}", ctx) is True
        assert evaluate_expression("{{ inputs.n <= 5 }}", ctx) is True
        assert evaluate_expression("{{ inputs.n >= 6 }}", ctx) is False
        assert evaluate_expression("{{ inputs.n <= 4 }}", ctx) is False
        # Numeric strings still compare as numbers ("10" >= "9", not lexically).
        assert evaluate_expression("{{ inputs.s10 >= inputs.s9 }}", ctx) is True
        assert evaluate_expression("{{ inputs.s9 <= inputs.s10 }}", ctx) is True
        # Non-numeric strings compare lexicographically.
        assert evaluate_expression("{{ inputs.hi >= inputs.lo }}", ctx) is True
        assert evaluate_expression("{{ inputs.lo <= inputs.hi }}", ctx) is True
        # A number against a non-numeric string is incomparable -> False.
        assert evaluate_expression("{{ inputs.n >= 'abc' }}", ctx) is False
        assert evaluate_expression("{{ inputs.n <= 'abc' }}", ctx) is False

    def test_boolean_literals_are_case_insensitive(self):
        """``{{ True }}``/``{{ TRUE }}`` resolve as booleans, as the ``.lower()``
        branch intends; only lowercase was pinned before."""
        from specify_cli.workflows.expressions import evaluate_expression
        from specify_cli.workflows.base import StepContext

        ctx = StepContext()
        for literal in ("True", "TRUE"):
            assert evaluate_expression("{{ " + literal + " }}", ctx) is True, literal
        for literal in ("False", "FALSE"):
            assert evaluate_expression("{{ " + literal + " }}", ctx) is False, literal

    def test_null_literals(self):
        """``none``/``null`` (any case) resolve to ``None``, not to a path."""
        from specify_cli.workflows.expressions import _collect_leaves, evaluate_expression
        from specify_cli.workflows.base import StepContext

        ctx = StepContext()
        for literal in ("none", "null", "None", "NULL", "nUlL"):
            assert evaluate_expression("{{ " + literal + " }}", ctx) is None, literal
            assert _collect_leaves(literal) == [], literal

    def test_filter_map_dot_path_attribute(self):
        """``map('a.b')`` walks nested dicts, not just a top-level key."""
        from specify_cli.workflows.expressions import evaluate_expression
        from specify_cli.workflows.base import StepContext

        ctx = StepContext(
            inputs={"rows": [{"result": {"status": "ok"}}, {"result": {"status": "bad"}}]}
        )
        assert evaluate_expression(
            "{{ inputs.rows | map('result.status') }}", ctx
        ) == ["ok", "bad"]
        # A missing branch of the path yields None for that element, as for a
        # missing top-level key.
        ctx_missing = StepContext(inputs={"rows": [{"result": {"status": "ok"}}, {}]})
        assert evaluate_expression(
            "{{ inputs.rows | map('result.status') }}", ctx_missing
        ) == ["ok", None]

    def test_filter_default_on_empty_string(self):
        """``default`` fires for an empty string too, not only for ``None``.

        ``_filter_default`` treats both as absent; only the ``None`` half was
        covered. Other falsy values (0, False, [], {}) are preserved.
        """
        from specify_cli.workflows.expressions import evaluate_expression
        from specify_cli.workflows.base import StepContext

        ctx = StepContext(
            inputs={
                "empty": "",
                "value": "kept",
                "missing": None,
                "zero": 0,
                "boolean": False,
                "empty_list": [],
                "empty_dict": {},
            }
        )
        assert evaluate_expression("{{ inputs.empty | default('fb') }}", ctx) == "fb"
        assert evaluate_expression("{{ inputs.missing | default('fb') }}", ctx) == "fb"
        # A non-empty value is passed through unchanged.
        assert evaluate_expression("{{ inputs.value | default('fb') }}", ctx) == "kept"
        # Documented falsy values (0, False, [], {}) are passed through unchanged.
        res_zero = evaluate_expression("{{ inputs.zero | default('fb') }}", ctx)
        assert res_zero == 0 and res_zero is not False
        assert evaluate_expression("{{ inputs.boolean | default('fb') }}", ctx) is False
        assert evaluate_expression("{{ inputs.empty_list | default('fb') }}", ctx) == []
        assert evaluate_expression("{{ inputs.empty_dict | default('fb') }}", ctx) == {}

    def test_filter_from_json_returns_non_object_types(self):
        """``from_json`` yields the parsed value for every JSON type, not only
        objects: arrays, numbers, booleans and ``null``."""
        from specify_cli.workflows.expressions import evaluate_expression
        from specify_cli.workflows.base import StepContext

        ctx = StepContext(
            inputs={"arr": "[1, 2, 3]", "num": "42", "fnum": "1.5", "t": "true", "nl": "null"}
        )
        assert evaluate_expression("{{ inputs.arr | from_json }}", ctx) == [1, 2, 3]
        assert evaluate_expression("{{ inputs.num | from_json }}", ctx) == 42
        assert evaluate_expression("{{ inputs.fnum | from_json }}", ctx) == 1.5
        assert evaluate_expression("{{ inputs.t | from_json }}", ctx) is True
        assert evaluate_expression("{{ inputs.nl | from_json }}", ctx) is None

    def test_filter_argument_resolved_from_namespace(self):
        """A filter argument may be a namespace path, not only a literal."""
        from specify_cli.workflows.expressions import evaluate_expression
        from specify_cli.workflows.base import StepContext

        ctx = StepContext(inputs={"tags": ["a", "b"], "sep": "-", "missing": None})
        assert evaluate_expression("{{ inputs.tags | join(inputs.sep) }}", ctx) == "a-b"
        assert evaluate_expression("{{ inputs.missing | default(inputs.sep) }}", ctx) == "-"

    def test_boolean_precedence_without_parentheses(self):
        """``and`` binds tighter than ``or``, so grouping is only needed to
        override it. With a=True, b=False, c=False: ``a or (b and c)`` is True;
        the wrong left-to-right reading ``(a or b) and c`` would be False."""
        from specify_cli.workflows.expressions import evaluate_expression
        from specify_cli.workflows.base import StepContext

        ctx = StepContext(inputs={"a": True, "b": False, "c": False})
        assert evaluate_expression("{{ inputs.a or inputs.b and inputs.c }}", ctx) is True
        # Explicit grouping overrides the default and flips the result.
        assert evaluate_expression("{{ (inputs.a or inputs.b) and inputs.c }}", ctx) is False

    def test_item_and_fan_in_namespace(self):
        """The ``item`` and ``fan_in`` roots resolve inside fan-out/fan-in, like
        ``inputs``/``steps``/``context``. Only the diagnostics probed them."""
        from specify_cli.workflows.expressions import evaluate_expression
        from specify_cli.workflows.base import StepContext

        ctx = StepContext(
            inputs={"x": "y"}, item={"name": "n1"}, fan_in={"results": [1, 2]}
        )
        assert evaluate_expression("{{ item.name }}", ctx) == "n1"
        assert evaluate_expression("{{ item }}", ctx) == {"name": "n1"}
        assert evaluate_expression("{{ fan_in.results }}", ctx) == [1, 2]
        assert evaluate_expression("{{ fan_in.results | join(', ') }}", ctx) == "1, 2"
        # An item that is itself a list indexes like any other list root.
        list_ctx = StepContext(inputs={"x": 1}, item=["x", "y"])
        assert evaluate_expression("{{ item[0] }}", list_ctx) == "x"
        assert evaluate_expression("{{ item[-1] }}", list_ctx) == "y"

    def test_interpolation_with_steps_and_item(self):
        """Interpolation resolves every root, not only ``inputs``/``context``."""
        from specify_cli.workflows.expressions import evaluate_expression
        from specify_cli.workflows.base import StepContext

        ctx = StepContext(
            steps={"emit": {"output": {"file": "a.md"}}}, item="row-1"
        )
        assert evaluate_expression("file={{ steps.emit.output.file }}", ctx) == "file=a.md"
        assert evaluate_expression("item={{ item }}", ctx) == "item=row-1"

    def test_empty_expression_block_is_empty_string(self):
        """A block with no expression interpolates to ``""`` (and in a condition
        coerces to False), rather than raising."""
        from specify_cli.workflows.expressions import (
            evaluate_condition,
            evaluate_expression,
        )
        from specify_cli.workflows.base import StepContext

        ctx = StepContext()
        assert evaluate_expression("{{ }}", ctx) == ""
        assert evaluate_condition("{{ }}", ctx) is False

    def test_missing_intermediate_path_resolves_to_none(self):
        """A path whose intermediate segment is absent resolves to ``None``
        rather than raising."""
        from specify_cli.workflows.expressions import evaluate_expression
        from specify_cli.workflows.base import StepContext

        ctx = StepContext(inputs={"a": {}})
        assert evaluate_expression("{{ inputs.a.b }}", ctx) is None
        assert evaluate_expression("{{ inputs.zzz.deep }}", ctx) is None

    def test_whitespace_inside_and_around_block(self):
        """Arbitrary whitespace around tokens is insignificant; none inside a
        quoted operand is not."""
        from specify_cli.workflows.expressions import evaluate_expression
        from specify_cli.workflows.base import StepContext

        ctx = StepContext(inputs={"n": 5, "missing": None})
        assert evaluate_expression("{{inputs.n}}", ctx) == 5
        assert evaluate_expression("{{   inputs.n   }}", ctx) == 5
        assert evaluate_expression("{{ inputs.missing | default( 'y' ) }}", ctx) == "y"
        assert evaluate_expression("{{ inputs.missing|default('y') }}", ctx) == "y"


# ===== Integration Dispatch Tests =====

class TestBuildExecArgs:
    """Test build_exec_args for CLI-based integrations."""

    def test_claude_exec_args(self):
        from specify_cli.integrations.claude import ClaudeIntegration
        impl = ClaudeIntegration()
        args = impl.build_exec_args("do stuff", model="sonnet-4")
        assert args[0] == "claude"
        assert args[1] == "-p"
        assert args[2] == "do stuff"
        assert "--model" in args
        assert "sonnet-4" in args
        assert "--output-format" in args

    def test_gemini_exec_args(self):
        from specify_cli.integrations.gemini import GeminiIntegration
        impl = GeminiIntegration()
        args = impl.build_exec_args("do stuff", model="gemini-2.5-pro")
        assert args[0] == "gemini"
        assert args[1] == "-p"
        assert "-m" in args
        assert "gemini-2.5-pro" in args

    def test_codex_exec_args(self):
        from specify_cli.integrations.codex import CodexIntegration
        impl = CodexIntegration()
        args = impl.build_exec_args("do stuff")
        assert args[0] == "codex"
        assert args[1] == "exec"
        assert args[2] == "do stuff"
        assert "--json" in args

    def test_copilot_exec_args(self, monkeypatch):
        monkeypatch.delenv("SPECKIT_COPILOT_ALLOW_ALL_TOOLS", raising=False)
        monkeypatch.delenv("SPECKIT_ALLOW_ALL_TOOLS", raising=False)
        from specify_cli.integrations.copilot import CopilotIntegration, _copilot_executable
        impl = CopilotIntegration()
        args = impl.build_exec_args("do stuff", model="claude-sonnet-4-20250514")
        assert args[0] == _copilot_executable()
        assert "-p" in args
        assert "--yolo" in args
        assert "--model" in args

    def test_copilot_new_env_var_disables_yolo(self, monkeypatch):
        monkeypatch.setenv("SPECKIT_COPILOT_ALLOW_ALL_TOOLS", "0")
        monkeypatch.delenv("SPECKIT_ALLOW_ALL_TOOLS", raising=False)
        from specify_cli.integrations.copilot import CopilotIntegration
        impl = CopilotIntegration()
        args = impl.build_exec_args("do stuff")
        assert "--yolo" not in args

    def test_copilot_deprecated_env_var_still_honoured(self, monkeypatch):
        monkeypatch.delenv("SPECKIT_COPILOT_ALLOW_ALL_TOOLS", raising=False)
        monkeypatch.setenv("SPECKIT_ALLOW_ALL_TOOLS", "0")
        import warnings
        from specify_cli.integrations.copilot import CopilotIntegration
        impl = CopilotIntegration()
        with warnings.catch_warnings(record=True) as w:
            warnings.simplefilter("always")
            args = impl.build_exec_args("do stuff")
        assert "--yolo" not in args
        assert any(
            "SPECKIT_ALLOW_ALL_TOOLS is deprecated" in str(x.message)
            and issubclass(x.category, UserWarning)
            for x in w
        )

    def test_copilot_new_env_var_takes_precedence(self, monkeypatch):
        monkeypatch.setenv("SPECKIT_COPILOT_ALLOW_ALL_TOOLS", "1")
        monkeypatch.setenv("SPECKIT_ALLOW_ALL_TOOLS", "0")
        from specify_cli.integrations.copilot import CopilotIntegration
        impl = CopilotIntegration()
        args = impl.build_exec_args("do stuff")
        assert "--yolo" in args

    def test_ide_only_returns_none(self):
        from specify_cli.integrations.kilocode import KilocodeIntegration
        impl = KilocodeIntegration()
        assert impl.build_exec_args("test") is None

    def test_no_model_omits_flag(self):
        from specify_cli.integrations.claude import ClaudeIntegration
        impl = ClaudeIntegration()
        args = impl.build_exec_args("do stuff", model=None)
        assert "--model" not in args

    def test_no_json_omits_flag(self):
        from specify_cli.integrations.claude import ClaudeIntegration
        impl = ClaudeIntegration()
        args = impl.build_exec_args("do stuff", output_json=False)
        assert "--output-format" not in args

    def test_rovodev_exec_args(self):
        from specify_cli.integrations.rovodev import RovodevIntegration

        impl = RovodevIntegration()
        args = impl.build_exec_args("/speckit.plan add OAuth")
        assert args[0:3] == ["acli", "rovodev", "run"]
        assert args[3] == "/speckit.plan add OAuth"
        assert "--output-schema" in args


# ===== Step Type Tests =====

class TestCommandStep:
    """Test the command step type."""

    def test_execute_basic(self):
        from unittest.mock import patch
        from specify_cli.workflows.step.command import CommandStep
        from specify_cli.workflows.base import StepContext, StepStatus

        step = CommandStep()
        ctx = StepContext(
            inputs={"name": "login"},
            default_integration="claude",
        )
        config = {
            "id": "test",
            "command": "speckit.specify",
            "input": {"args": "{{ inputs.name }}"},
        }
        with patch("specify_cli.workflows.step.command.shutil.which", return_value=None):
            result = step.execute(config, ctx)
        assert result.status == StepStatus.FAILED
        assert result.output["command"] == "speckit.specify"
        assert result.output["integration"] == "claude"
        assert result.output["input"]["args"] == "login"

    def test_per_step_integration_config_is_resolved_and_isolated(
        self, tmp_path, monkeypatch
    ):
        from specify_cli.workflows.base import StepContext, StepStatus
        from specify_cli.workflows.step.command import CommandStep

        calls = []

        def fake_run(args, **kwargs):
            calls.append((args, kwargs))
            return type("Result", (), {"returncode": 0})()

        monkeypatch.delenv(
            "SPECKIT_INTEGRATION_DOCKER_AGENT_EXTRA_ARGS", raising=False
        )
        monkeypatch.setattr(
            "shutil.which",
            lambda name: (
                "/usr/bin/docker-agent"
                if name in {"docker-agent", "/usr/bin/docker-agent"}
                else None
            ),
        )
        monkeypatch.setattr("subprocess.run", fake_run)

        step = CommandStep()
        context = StepContext(
            inputs={"config": "./review.yaml", "agent": "reviewer"},
            project_root=str(tmp_path),
        )
        first = step.execute(
            {
                "id": "review",
                "command": "speckit.plan",
                "integration": "docker-agent",
                "integration_args": ["{{ inputs.config }}"],
                "integration_options": {
                    "agent": "{{ inputs.agent }}",
                    "safety": "balanced",
                },
            },
            context,
        )
        second = step.execute(
            {
                "id": "implement",
                "command": "speckit.implement",
                "integration": "docker-agent",
                "integration_args": ["./implement.yaml"],
                "integration_options": {"agent": "implementer"},
            },
            context,
        )

        assert first.status is StepStatus.COMPLETED
        assert second.status is StepStatus.COMPLETED
        assert first.output["integration_args"] == ["./review.yaml"]
        assert first.output["integration_options"] == {
            "agent": "reviewer",
            "safety": "balanced",
        }
        assert calls[0][0] == [
            "/usr/bin/docker-agent",
            "run",
            "--exec",
            "./review.yaml",
            "--agent",
            "reviewer",
            "--safety",
            "balanced",
            "--",
            "/speckit-plan",
        ]
        assert calls[1][0] == [
            "/usr/bin/docker-agent",
            "run",
            "--exec",
            "./implement.yaml",
            "--agent",
            "implementer",
            "--",
            "/speckit-implement",
        ]
        assert calls[0][1]["cwd"] == str(tmp_path)
        assert calls[1][1]["cwd"] == str(tmp_path)

    @pytest.mark.parametrize(
        ("step_model", "default_model", "expected_model"),
        [
            ("step/model", "workflow/model", "step/model"),
            (None, "workflow/model", "workflow/model"),
        ],
    )
    def test_docker_agent_uses_one_effective_model(
        self,
        tmp_path,
        monkeypatch,
        step_model,
        default_model,
        expected_model,
    ):
        from specify_cli.workflows.base import StepContext, StepStatus
        from specify_cli.workflows.step.command import CommandStep

        calls = []

        def fake_run(args, **kwargs):
            calls.append(args)
            return type("Result", (), {"returncode": 0})()

        monkeypatch.delenv(
            "SPECKIT_INTEGRATION_DOCKER_AGENT_EXTRA_ARGS", raising=False
        )
        monkeypatch.setattr(
            "shutil.which",
            lambda name: (
                "/usr/bin/docker-agent"
                if name in {"docker-agent", "/usr/bin/docker-agent"}
                else None
            ),
        )
        monkeypatch.setattr("subprocess.run", fake_run)

        config = {
            "id": "implement",
            "command": "speckit.implement",
            "integration": "docker-agent",
            "integration_args": ["./agent.yaml"],
        }
        if step_model is not None:
            config["model"] = step_model

        result = CommandStep().execute(
            config,
            StepContext(
                default_model=default_model,
                project_root=str(tmp_path),
            ),
        )

        assert result.status is StepStatus.COMPLETED
        assert calls[0].count("--model") == 1
        assert calls[0][calls[0].index("--model") + 1] == expected_model

    def test_unsupported_runtime_config_fails_with_actionable_error(self):
        from specify_cli.workflows.base import StepContext, StepStatus
        from specify_cli.workflows.step.command import CommandStep

        result = CommandStep().execute(
            {
                "id": "review",
                "command": "speckit.plan",
                "integration": "claude",
                "integration_options": {"saftey": "balanced"},
            },
            StepContext(),
        )

        assert result.status is StepStatus.FAILED
        assert result.output["dispatched"] is False
        assert "does not support per-step 'integration_options'" in (
            result.error or ""
        )
        assert "saftey" in (result.error or "")

    def test_validate_rejects_malformed_runtime_config(self):
        from specify_cli.workflows.step.command import CommandStep

        step = CommandStep()
        errors = step.validate(
            {
                "id": "review",
                "command": "speckit.plan",
                "integration_args": "./agent.yaml",
                "integration_options": ["agent", "root"],
            }
        )

        assert any("'integration_args' must be a list" in error for error in errors)
        assert any(
            "'integration_options' must be a mapping" in error for error in errors
        )

        errors = step.validate(
            {
                "id": "review",
                "command": "speckit.plan",
                "integration_args": [42],
                "integration_options": {1: "root"},
            }
        )
        assert any("'integration_args[0]' must be a string" in error for error in errors)
        assert any("keys must be strings" in error for error in errors)

    def test_try_dispatch_resolves_rovodev_via_acli(self, tmp_path):
        """When acli is installed, rovodev dispatch succeeds via acli."""
        from unittest.mock import patch, MagicMock
        from specify_cli.workflows.step.command import CommandStep
        from specify_cli.workflows.base import StepContext, StepStatus

        step = CommandStep()
        ctx = StepContext(
            default_integration="rovodev",
            project_root=str(tmp_path),
        )
        config = {
            "id": "test",
            "command": "speckit.plan",
            "input": {"args": "add OAuth"},
        }

        mock_result = MagicMock()
        mock_result.returncode = 0
        mock_result.stdout = ""
        mock_result.stderr = ""

        with patch("specify_cli.workflows.step.command.shutil.which",
                    lambda name: "/usr/bin/acli" if name == "acli" else None), \
             patch("subprocess.run", return_value=mock_result):
            result = step.execute(config, ctx)

        assert result.status == StepStatus.COMPLETED
        assert result.output["dispatched"] is True
        assert result.output["exit_code"] == 0

    def test_validate_missing_command(self):
        from specify_cli.workflows.step.command import CommandStep

        step = CommandStep()
        errors = step.validate({"id": "test"})
        assert any("missing 'command'" in e for e in errors)

    def test_validate_rejects_non_mapping_input_and_options(self):
        from specify_cli.workflows.step.command import CommandStep
        from specify_cli.workflows.base import StepContext, StepStatus

        step = CommandStep()
        # execute() does input.items() / options.update(); a non-mapping must be
        # reported by validate(), not crash at run time (like switch 'cases').
        for bad in (None, "args", ["a", "b"], 5):
            errs = step.validate({"id": "c", "command": "/x", "input": bad})
            assert any("'input' must be a mapping" in e for e in errs), bad
        errs = step.validate({"id": "c", "command": "/x", "options": 42})
        assert any("'options' must be a mapping" in e for e in errs)
        # a valid mapping config is still accepted
        assert step.validate({"id": "c", "command": "/x", "input": {"args": "y"}, "options": {"k": 1}}) == []
        # execute() has no auto-validation guarantee (the engine may skip
        # validate), so a non-mapping input/options FAILS the step with the same
        # contract error — it does not silently coerce to empty and report
        # COMPLETED (which would defeat continue_on_error).
        res_in = step.execute({"id": "c", "command": "echo", "input": None}, StepContext())
        assert res_in.status is StepStatus.FAILED
        assert "'input' must be a mapping" in (res_in.error or "")
        res_opt = step.execute(
            {"id": "c", "command": "echo", "input": {}, "options": 42}, StepContext()
        )
        assert res_opt.status is StepStatus.FAILED
        assert "'options' must be a mapping" in (res_opt.error or "")

    @pytest.mark.parametrize("bad", [["claude"], {"a": 1}, 5, True])
    def test_validate_rejects_non_string_integration_and_model(self, bad):
        """A non-string 'integration'/'model' must be rejected at validation.

        execute() passes 'integration' to get_integration(), which uses it as a
        dict key — an unhashable list/dict raises a raw TypeError there, even on
        a validated run — and feeds 'model' into the CLI argv. Mirrors the
        'command'/'input'/'options' type checks.
        """
        from specify_cli.workflows.step.command import CommandStep

        step = CommandStep()
        errs = step.validate({"id": "c", "command": "/x", "integration": bad})
        assert any("'integration' must be a string" in e for e in errs), bad
        errs = step.validate({"id": "c", "command": "/x", "model": bad})
        assert any("'model' must be a string" in e for e in errs), bad

    def test_validate_accepts_none_and_expression_integration_model(self):
        """An explicit YAML-null (inherit default) or a '{{ ... }}' expression
        integration/model stays valid — only literal non-strings are rejected."""
        from specify_cli.workflows.step.command import CommandStep

        step = CommandStep()
        assert step.validate(
            {"id": "c", "command": "/x", "integration": None, "model": None}
        ) == []
        assert step.validate(
            {
                "id": "c",
                "command": "/x",
                "integration": "{{ inputs.agent }}",
                "model": "{{ inputs.model }}",
            }
        ) == []

    def test_validate_rejects_non_string_command(self):
        from specify_cli.workflows.step.command import CommandStep

        step = CommandStep()
        # execute() passes 'command' to build_command_invocation(), which does
        # command_name.startswith(...); a non-string crashes there with a raw
        # AttributeError. validate() must report it, like prompt-step 'prompt'.
        for bad in (None, ["a", "b"], 5, {"x": 1}):
            errs = step.validate({"id": "c", "command": bad})
            assert any("'command' must be a string" in e for e in errs), bad
        # a string command (incl. an expression) is still accepted
        assert step.validate({"id": "c", "command": "/x"}) == []
        assert step.validate({"id": "c", "command": "{{ inputs.cmd }}"}) == []

    def test_execute_non_string_command_fails_cleanly(self):
        from unittest.mock import patch
        from specify_cli.workflows.step.command import CommandStep
        from specify_cli.workflows.base import StepContext, StepStatus

        step = CommandStep()
        # The engine may skip validate(); a non-string 'command' must FAIL the
        # step with the contract error rather than reaching _try_dispatch and
        # crashing build_command_invocation with a raw AttributeError. Force a
        # resolvable integration + installed CLI so, absent the guard, dispatch
        # would actually be attempted and the crash would fire.
        ctx = StepContext(default_integration="claude")
        with patch("specify_cli.workflows.step.command.shutil.which",
                   return_value="/usr/bin/claude"):
            for bad in (None, ["a", "b"], 5, {"x": 1}):
                result = step.execute(
                    {"id": "c", "command": bad, "input": {}}, ctx
                )
                assert result.status is StepStatus.FAILED, bad
                assert "'command' must be a string" in (result.error or ""), bad

    def test_execute_non_string_integration_fails_loudly(self):
        """On an unvalidated run, an unhashable 'integration' would crash
        get_integration() (dict.get on a list) with a raw TypeError. execute()
        must fail the step with the contract error instead."""
        from specify_cli.workflows.step.command import CommandStep
        from specify_cli.workflows.base import StepContext, StepStatus

        step = CommandStep()
        res = step.execute(
            {"id": "c", "command": "speckit.specify", "integration": ["claude"]},
            StepContext(),
        )
        assert res.status is StepStatus.FAILED
        assert "'integration' must be a string" in (res.error or "")
        # non-string model likewise fails before build_exec_args
        res = step.execute(
            {"id": "c", "command": "speckit.specify", "integration": "claude", "model": ["m"]},
            StepContext(),
        )
        assert res.status is StepStatus.FAILED
        assert "'model' must be a string" in (res.error or "")

    @pytest.mark.parametrize("falsey", [[], {}, 0, False])
    def test_execute_falsey_non_string_integration_fails_loudly(self, falsey):
        """A *falsey* non-string ([], {}, 0, False) must fail the step, not be
        swallowed by an ``or``-fallback to the workflow default.

        A ``config.get('integration') or context.default_integration`` coerces a
        falsey non-string to the default *before* the type guard runs, so with a
        configured default the step would silently dispatch using the wrong
        integration instead of surfacing the contract error. The default is set
        here so a regression dispatches rather than fails-not-possible."""
        from specify_cli.workflows.step.command import CommandStep
        from specify_cli.workflows.base import StepContext, StepStatus

        step = CommandStep()
        ctx = StepContext(default_integration="claude", default_model="sonnet")
        res = step.execute(
            {"id": "c", "command": "speckit.specify", "integration": falsey}, ctx
        )
        assert res.status is StepStatus.FAILED, falsey
        assert "'integration' must be a string" in (res.error or ""), falsey
        # a falsey non-string model likewise reaches the guard
        res = step.execute(
            {"id": "c", "command": "speckit.specify", "model": falsey}, ctx
        )
        assert res.status is StepStatus.FAILED, falsey
        assert "'model' must be a string" in (res.error or ""), falsey

    def test_step_override_integration(self):
        from unittest.mock import patch
        from specify_cli.workflows.step.command import CommandStep
        from specify_cli.workflows.base import StepContext

        step = CommandStep()
        ctx = StepContext(default_integration="claude")
        config = {
            "id": "test",
            "command": "speckit.plan",
            "integration": "gemini",
            "input": {},
        }
        with patch("specify_cli.workflows.step.command.shutil.which", return_value=None):
            result = step.execute(config, ctx)
        assert result.output["integration"] == "gemini"

    def test_execute_non_string_integration_fails_cleanly(self):
        """A non-string integration (e.g. a list from an expression that resolved
        to one) must FAIL the step cleanly, not crash the run with
        'TypeError: unhashable type: list' from get_integration's dict lookup."""
        from specify_cli.workflows.step.command import CommandStep
        from specify_cli.workflows.base import StepContext, StepStatus

        step = CommandStep()
        config = {
            "id": "s", "command": "speckit.plan",
            "integration": ["claude"], "input": {},
        }
        result = step.execute(config, StepContext())
        assert result.status == StepStatus.FAILED

    def test_step_override_model(self):
        from unittest.mock import patch
        from specify_cli.workflows.step.command import CommandStep
        from specify_cli.workflows.base import StepContext

        step = CommandStep()
        ctx = StepContext(default_model="sonnet-4")
        config = {
            "id": "test",
            "command": "speckit.implement",
            "model": "opus-4",
            "input": {},
        }
        with patch("specify_cli.workflows.step.command.shutil.which", return_value=None):
            result = step.execute(config, ctx)
        assert result.output["model"] == "opus-4"

    def test_options_merge(self):
        from unittest.mock import patch
        from specify_cli.workflows.step.command import CommandStep
        from specify_cli.workflows.base import StepContext

        step = CommandStep()
        ctx = StepContext(default_options={"max-tokens": 8000})
        config = {
            "id": "test",
            "command": "speckit.plan",
            "options": {"thinking-budget": 32768},
            "input": {},
        }
        with patch("specify_cli.workflows.step.command.shutil.which", return_value=None):
            result = step.execute(config, ctx)
        assert result.output["options"]["max-tokens"] == 8000
        assert result.output["options"]["thinking-budget"] == 32768

    def test_dispatch_not_attempted_without_cli(self):
        """When the CLI tool is not installed, step should fail."""
        from unittest.mock import patch
        from specify_cli.workflows.step.command import CommandStep
        from specify_cli.workflows.base import StepContext, StepStatus

        step = CommandStep()
        ctx = StepContext(
            inputs={"name": "login"},
            default_integration="claude",
            project_root="/tmp",
        )
        config = {
            "id": "test",
            "command": "speckit.specify",
            "input": {"args": "{{ inputs.name }}"},
        }
        with patch("specify_cli.workflows.step.command.shutil.which", return_value=None):
            result = step.execute(config, ctx)
        assert result.status == StepStatus.FAILED
        assert result.output["dispatched"] is False
        assert result.error is not None

    def test_dispatch_with_mock_cli(self, tmp_path, monkeypatch):
        """When the CLI is installed, dispatch invokes the command by name."""
        from unittest.mock import patch, MagicMock
        from specify_cli.workflows.step.command import CommandStep
        from specify_cli.workflows.base import StepContext, StepStatus

        step = CommandStep()
        ctx = StepContext(
            inputs={"name": "login"},
            default_integration="claude",
            project_root=str(tmp_path),
        )
        config = {
            "id": "test",
            "command": "speckit.specify",
            "input": {"args": "{{ inputs.name }}"},
        }

        mock_result = MagicMock()
        mock_result.returncode = 0
        mock_result.stdout = '{"result": "done"}'
        mock_result.stderr = ""

        with patch("specify_cli.workflows.step.command.shutil.which", return_value="/usr/local/bin/claude"), \
             patch("specify_cli.integrations.base.shutil.which", return_value="/usr/local/bin/claude"), \
             patch("subprocess.run", return_value=mock_result) as mock_run:
            result = step.execute(config, ctx)

        assert result.status == StepStatus.COMPLETED
        assert result.output["dispatched"] is True
        assert result.output["exit_code"] == 0
        # Verify the CLI was called with the resolved path (via shutil.which,
        # which honors PATHEXT for ``.cmd``/``.bat`` shims on Windows), then
        # ``-p`` and the skill invocation.
        call_args = mock_run.call_args
        assert call_args[0][0][0] == "/usr/local/bin/claude"
        assert call_args[0][0][1] == "-p"
        # Claude is a SkillsIntegration so uses /speckit-specify
        assert "/speckit-specify login" in call_args[0][0][2]

    def test_dispatch_uses_executable_override_for_fallback_preflight(self, tmp_path, monkeypatch):
        """Command preflight falls back to build_exec_args() argv[0]."""
        from unittest.mock import MagicMock, patch
        from specify_cli.workflows.step.command import CommandStep
        from specify_cli.workflows.base import StepContext, StepStatus

        monkeypatch.setenv("SPECKIT_INTEGRATION_CLAUDE_EXECUTABLE", "/opt/claude")
        seen_which: list[str] = []

        def fake_which(name: str) -> str | None:
            seen_which.append(name)
            return name if name == "/opt/claude" else None

        step = CommandStep()
        ctx = StepContext(
            inputs={"name": "login"},
            default_integration="claude",
            project_root=str(tmp_path),
        )
        config = {
            "id": "test",
            "command": "speckit.specify",
            "input": {"args": "{{ inputs.name }}"},
        }

        mock_result = MagicMock()
        mock_result.returncode = 0
        mock_result.stdout = '{"result": "done"}'
        mock_result.stderr = ""

        with patch("specify_cli.workflows.step.command.shutil.which", side_effect=fake_which), \
             patch("subprocess.run", return_value=mock_result) as mock_run:
            result = step.execute(config, ctx)

        assert result.status == StepStatus.COMPLETED
        assert result.output["dispatched"] is True
        assert seen_which[:2] == ["claude", "/opt/claude"]
        call_args = mock_run.call_args
        assert call_args[0][0][0] == "/opt/claude"
        assert "/speckit-specify login" in call_args[0][0][2]

    def test_dispatch_failure_returns_failed_status(self, tmp_path):
        """When the CLI exits non-zero, the step should fail."""
        from unittest.mock import patch, MagicMock
        from specify_cli.workflows.step.command import CommandStep
        from specify_cli.workflows.base import StepContext, StepStatus

        step = CommandStep()
        ctx = StepContext(
            inputs={},
            default_integration="claude",
            project_root=str(tmp_path),
        )
        config = {
            "id": "test",
            "command": "speckit.specify",
            "input": {"args": "test"},
        }

        mock_result = MagicMock()
        mock_result.returncode = 1
        mock_result.stdout = ""
        mock_result.stderr = "API error"

        with patch("specify_cli.workflows.step.command.shutil.which", return_value="/usr/local/bin/claude"), \
             patch("specify_cli.integrations.base.shutil.which", return_value="/usr/local/bin/claude"), \
             patch("subprocess.run", return_value=mock_result):
            result = step.execute(config, ctx)

        assert result.status == StepStatus.FAILED
        assert result.output["dispatched"] is True
        assert result.output["exit_code"] == 1


class TestPromptStep:
    """Test the prompt step type."""

    def test_execute_basic(self):
        from unittest.mock import patch
        from specify_cli.workflows.step.prompt import PromptStep
        from specify_cli.workflows.base import StepContext, StepStatus

        step = PromptStep()
        ctx = StepContext(
            inputs={"file": "auth.py"},
            default_integration="claude",
        )
        config = {
            "id": "review",
            "type": "prompt",
            "prompt": "Review {{ inputs.file }} for security issues",
        }
        with patch("specify_cli.workflows.step.prompt.shutil.which", return_value=None):
            result = step.execute(config, ctx)
        assert result.status == StepStatus.FAILED
        assert result.output["prompt"] == "Review auth.py for security issues"
        assert result.output["integration"] == "claude"
        assert result.output["dispatched"] is False

    def test_execute_non_string_integration_fails_cleanly(self):
        """A non-string integration must FAIL the step cleanly, not crash with
        'TypeError: unhashable type: list' from get_integration's dict lookup."""
        from specify_cli.workflows.step.prompt import PromptStep
        from specify_cli.workflows.base import StepContext, StepStatus

        step = PromptStep()
        config = {
            "id": "p", "type": "prompt", "prompt": "do it",
            "integration": ["claude"],
        }
        result = step.execute(config, StepContext())
        assert result.status == StepStatus.FAILED

    def test_execute_with_step_integration(self):
        from unittest.mock import patch
        from specify_cli.workflows.step.prompt import PromptStep
        from specify_cli.workflows.base import StepContext

        step = PromptStep()
        ctx = StepContext(default_integration="claude")
        config = {
            "id": "review",
            "type": "prompt",
            "prompt": "Summarize the codebase",
            "integration": "gemini",
        }
        with patch("specify_cli.workflows.step.prompt.shutil.which", return_value=None):
            result = step.execute(config, ctx)
        assert result.output["integration"] == "gemini"

    def test_execute_with_model(self):
        from unittest.mock import patch
        from specify_cli.workflows.step.prompt import PromptStep
        from specify_cli.workflows.base import StepContext

        step = PromptStep()
        ctx = StepContext(default_integration="claude", default_model="sonnet-4")
        config = {
            "id": "review",
            "type": "prompt",
            "prompt": "hello",
            "model": "opus-4",
        }
        with patch("specify_cli.workflows.step.prompt.shutil.which", return_value=None):
            result = step.execute(config, ctx)
        assert result.output["model"] == "opus-4"

    def test_try_dispatch_resolves_rovodev_via_acli(self, tmp_path):
        """When acli is installed, rovodev prompt dispatch succeeds via acli."""
        from unittest.mock import patch, MagicMock
        from specify_cli.workflows.step.prompt import PromptStep
        from specify_cli.workflows.base import StepContext, StepStatus

        step = PromptStep()
        ctx = StepContext(
            default_integration="rovodev",
            project_root=str(tmp_path),
        )
        config = {
            "id": "test",
            "type": "prompt",
            "prompt": "Explain this code",
        }

        mock_result = MagicMock()
        mock_result.returncode = 0
        mock_result.stdout = ""
        mock_result.stderr = ""

        with patch("specify_cli.workflows.step.prompt.shutil.which",
                    lambda name: "/usr/bin/acli" if name == "acli" else None), \
             patch("subprocess.run", return_value=mock_result):
            result = step.execute(config, ctx)

        assert result.status == StepStatus.COMPLETED
        assert result.output["dispatched"] is True
        assert result.output["exit_code"] == 0

    def test_try_dispatch_executes_the_resolved_executable(self, tmp_path):
        """argv[0] must be the shutil.which-resolved path, not the bare name.

        On Windows subprocess.run calls CreateProcess, which ignores PATHEXT, so
        a bare `claude` installed as `claude.cmd` (the usual npm shim) raises
        WinError 2. That OSError is swallowed and reported as "CLI not found or
        not installed" even though the preflight which() just found it, while
        the `command` step -- which goes through
        IntegrationBase.dispatch_command -- resolves argv[0] and works.
        """
        from unittest.mock import patch, MagicMock
        from specify_cli.workflows.step.prompt import PromptStep
        from specify_cli.workflows.base import StepContext, StepStatus

        step = PromptStep()
        ctx = StepContext(default_integration="claude", project_root=str(tmp_path))
        config = {"id": "test", "type": "prompt", "prompt": "hello"}

        resolved = r"C:\tools\claude.CMD"
        mock_result = MagicMock()
        mock_result.returncode = 0
        mock_result.stdout = ""
        mock_result.stderr = ""

        with patch(
            "specify_cli.workflows.step.prompt.shutil.which",
            lambda name: resolved,
        ), patch("subprocess.run", return_value=mock_result) as run:
            result = step.execute(config, ctx)

        assert result.status == StepStatus.COMPLETED
        assert result.output["dispatched"] is True
        argv = run.call_args.args[0]
        assert argv[0] == resolved, argv

    def test_dispatch_with_mock_cli(self, tmp_path):
        from unittest.mock import patch, MagicMock
        from specify_cli.workflows.step.prompt import PromptStep
        from specify_cli.workflows.base import StepContext, StepStatus

        step = PromptStep()
        ctx = StepContext(
            default_integration="claude",
            project_root=str(tmp_path),
        )
        config = {
            "id": "ask",
            "type": "prompt",
            "prompt": "Explain this code",
        }

        mock_result = MagicMock()
        mock_result.returncode = 0
        mock_result.stdout = "Here is the explanation"
        mock_result.stderr = ""

        with patch("specify_cli.workflows.step.prompt.shutil.which", return_value="/usr/local/bin/claude"), \
             patch("subprocess.run", return_value=mock_result):
            result = step.execute(config, ctx)

        assert result.status == StepStatus.COMPLETED
        assert result.output["dispatched"] is True
        assert result.output["exit_code"] == 0

    def test_dispatch_uses_executable_override_for_fallback_preflight(self, tmp_path, monkeypatch):
        """Prompt preflight falls back to build_exec_args() argv[0]."""
        from unittest.mock import MagicMock, patch
        from specify_cli.workflows.step.prompt import PromptStep
        from specify_cli.workflows.base import StepContext, StepStatus

        monkeypatch.setenv("SPECKIT_INTEGRATION_CLAUDE_EXECUTABLE", "/opt/claude")
        seen_which: list[str] = []

        def fake_which(name: str) -> str | None:
            seen_which.append(name)
            return name if name == "/opt/claude" else None

        step = PromptStep()
        ctx = StepContext(
            default_integration="claude",
            project_root=str(tmp_path),
        )
        config = {
            "id": "ask",
            "type": "prompt",
            "prompt": "Explain this code",
        }

        mock_result = MagicMock()
        mock_result.returncode = 0
        mock_result.stdout = "Here is the explanation"
        mock_result.stderr = ""

        with patch("specify_cli.workflows.step.prompt.shutil.which", side_effect=fake_which), \
             patch("subprocess.run", return_value=mock_result) as mock_run:
            result = step.execute(config, ctx)

        assert result.status == StepStatus.COMPLETED
        assert result.output["dispatched"] is True
        assert seen_which[:2] == ["claude", "/opt/claude"]
        call_args = mock_run.call_args
        assert call_args[0][0][0] == "/opt/claude"
        assert call_args[0][0][2] == "Explain this code"

    def test_validate_missing_prompt(self):
        from specify_cli.workflows.step.prompt import PromptStep

        step = PromptStep()
        errors = step.validate({"id": "test"})
        assert any("missing 'prompt'" in e for e in errors)

    @pytest.mark.parametrize("bad_prompt", [None, ["review", "this"], 42, {"a": 1}])
    def test_validate_rejects_non_string_prompt(self, bad_prompt):
        """A non-string 'prompt' must be rejected at validation.

        execute() str()-coerces prompt and dispatches it to the integration
        CLI, so a null or list prompt would otherwise send the Python repr to
        the model as instructions — silently wrong. Mirrors the shell-step
        'run' type check.
        """
        from specify_cli.workflows.step.prompt import PromptStep

        step = PromptStep()
        errors = step.validate({"id": "p", "prompt": bad_prompt})
        assert any("'prompt' must be a string" in e for e in errors)

    def test_validate_valid(self):
        from specify_cli.workflows.step.prompt import PromptStep

        step = PromptStep()
        errors = step.validate({"id": "test", "prompt": "do something"})
        assert errors == []

    def test_validate_accepts_expression_prompt(self):
        """A '{{ ... }}' expression prompt is a str, so it stays valid."""
        from specify_cli.workflows.step.prompt import PromptStep

        step = PromptStep()
        errors = step.validate(
            {"id": "p", "prompt": "Review {{ inputs.file }}"}
        )
        assert errors == []

    @pytest.mark.parametrize("bad", [["claude"], {"a": 1}, 5, True])
    def test_validate_rejects_non_string_integration_and_model(self, bad):
        """A non-string 'integration'/'model' must be rejected at validation.

        execute() passes 'integration' to get_integration(), which uses it as a
        dict key — an unhashable list/dict raises a raw TypeError there, even on
        a validated run — and feeds 'model' into the CLI argv."""
        from specify_cli.workflows.step.prompt import PromptStep

        step = PromptStep()
        errs = step.validate({"id": "p", "prompt": "hi", "integration": bad})
        assert any("'integration' must be a string" in e for e in errs), bad
        errs = step.validate({"id": "p", "prompt": "hi", "model": bad})
        assert any("'model' must be a string" in e for e in errs), bad

    def test_validate_accepts_none_and_expression_integration_model(self):
        """An explicit YAML-null (inherit default) or a '{{ ... }}' expression
        integration/model stays valid — only literal non-strings are rejected."""
        from specify_cli.workflows.step.prompt import PromptStep

        step = PromptStep()
        assert step.validate(
            {"id": "p", "prompt": "hi", "integration": None, "model": None}
        ) == []
        assert step.validate(
            {
                "id": "p",
                "prompt": "hi",
                "integration": "{{ inputs.agent }}",
                "model": "{{ inputs.model }}",
            }
        ) == []

    def test_execute_non_string_integration_fails_loudly(self):
        """On an unvalidated run, an unhashable 'integration' would crash
        get_integration() (dict.get on a dict) with a raw TypeError. execute()
        must fail the step with the contract error instead."""
        from specify_cli.workflows.step.prompt import PromptStep
        from specify_cli.workflows.base import StepContext, StepStatus

        step = PromptStep()
        res = step.execute(
            {"id": "p", "prompt": "hi", "integration": {"a": 1}}, StepContext()
        )
        assert res.status is StepStatus.FAILED
        assert "'integration' must be a string" in (res.error or "")
        res = step.execute(
            {"id": "p", "prompt": "hi", "integration": "claude", "model": ["m"]},
            StepContext(),
        )
        assert res.status is StepStatus.FAILED
        assert "'model' must be a string" in (res.error or "")

    @pytest.mark.parametrize("falsey", [[], {}, 0, False])
    def test_execute_falsey_non_string_integration_fails_loudly(self, falsey):
        """A *falsey* non-string ([], {}, 0, False) must fail the step, not be
        swallowed by an ``or``-fallback to the workflow default.

        A ``config.get('integration') or context.default_integration`` coerces a
        falsey non-string to the default *before* the type guard runs, so with a
        configured default the step would silently dispatch using the wrong
        integration instead of surfacing the contract error. The default is set
        here so a regression dispatches rather than fails-not-possible."""
        from specify_cli.workflows.step.prompt import PromptStep
        from specify_cli.workflows.base import StepContext, StepStatus

        step = PromptStep()
        ctx = StepContext(default_integration="claude", default_model="sonnet")
        res = step.execute({"id": "p", "prompt": "hi", "integration": falsey}, ctx)
        assert res.status is StepStatus.FAILED, falsey
        assert "'integration' must be a string" in (res.error or ""), falsey
        # a falsey non-string model likewise reaches the guard
        res = step.execute({"id": "p", "prompt": "hi", "model": falsey}, ctx)
        assert res.status is StepStatus.FAILED, falsey
        assert "'model' must be a string" in (res.error or ""), falsey

    @pytest.mark.parametrize(
        "bad", ["30", True, float("inf"), float("nan"), 0, -5, ["30"], None, 10**400]
    )
    def test_validate_rejects_invalid_timeout(self, bad):
        """'timeout' reaches subprocess.run(), so validate() must reject junk.

        The sibling shell step already rejects exactly these values; the
        prompt step gained a ``timeout`` without the matching guard, so a
        workflow that fails validation as a shell step passed as a prompt one.

        ``10**400`` is an int too large to convert to float: it passes
        ``isinstance``/``> 0`` but makes ``math.isfinite()`` — and later
        ``subprocess.run()`` — raise ``OverflowError``, so the guard has to
        catch that rather than let it escape as the crash it exists to stop.
        """
        from specify_cli.workflows.step.prompt import PromptStep

        step = PromptStep()
        errors = step.validate(
            {"id": "p", "type": "prompt", "prompt": "hi", "timeout": bad}
        )
        assert any("'timeout' must be a positive number" in e for e in errors), (
            bad,
            errors,
        )

    @pytest.mark.parametrize("good", [300, 5, 0.5])
    def test_validate_accepts_valid_timeout(self, good):
        """A positive int/float timeout — and an absent one — stay valid."""
        from specify_cli.workflows.step.prompt import PromptStep

        step = PromptStep()
        for config in (
            {"id": "p", "type": "prompt", "prompt": "hi", "timeout": good},
            {"id": "p", "type": "prompt", "prompt": "hi"},
        ):
            errors = step.validate(config)
            assert not any("'timeout'" in e for e in errors), (config, errors)

    def test_execute_fails_cleanly_on_invalid_timeout(self, monkeypatch):
        """execute() must fail the step, not raise, on an invalid timeout.

        The engine does not auto-validate step config and re-raises anything a
        step throws, so an unvalidated ``timeout`` reaching subprocess.run()
        raised a raw ``TypeError: unsupported operand type(s) for +: 'float'
        and 'str'`` (or ``ValueError`` for NaN) that aborted the entire run —
        naming neither the step nor the field — after earlier steps had
        already run their side effects.
        """
        import subprocess
        from unittest.mock import patch

        from specify_cli.workflows.step.prompt import PromptStep
        from specify_cli.workflows.base import StepContext, StepStatus

        def fail_if_called(*args, **kwargs):
            raise AssertionError("subprocess.run should not run on invalid timeout")

        monkeypatch.setattr(subprocess, "run", fail_if_called)
        step = PromptStep()
        ctx = StepContext(inputs={}, default_integration="claude")
        # A string/list raises TypeError and NaN raises ValueError inside
        # subprocess.run(); ``True`` would silently become a 1s timeout (bool
        # is an int subclass); a non-positive value reports an immediate
        # TimeoutExpired for a command that never got the time to run; an int
        # too large to convert to float raises OverflowError.
        for bad in ("30", True, float("nan"), 0, -5, ["30"], 10**400):
            with patch(
                "specify_cli.workflows.step.prompt.shutil.which",
                return_value="/opt/claude",
            ):
                result = step.execute(
                    {
                        "id": "p",
                        "type": "prompt",
                        "prompt": "hi",
                        "integration": "claude",
                        "timeout": bad,
                    },
                    ctx,
                )
            assert result.status is StepStatus.FAILED, bad
            assert "'timeout' must be a positive number" in (result.error or ""), bad

    def test_try_dispatch_threads_project_root(self):
        """PromptStep._try_dispatch must pass context.project_root to build_exec_args."""
        from pathlib import Path
        from unittest.mock import MagicMock, patch

        from specify_cli.workflows.base import StepContext
        from specify_cli.workflows.step.prompt import PromptStep

        step = PromptStep()
        ctx = StepContext(project_root="/fake/project/root", default_integration="dummy")

        mock_impl = MagicMock()
        mock_impl.key = "dummy"
        mock_impl.build_exec_args.return_value = ["dummy", "args"]
        mock_get_integration = MagicMock(return_value=mock_impl)

        mock_result = MagicMock()
        mock_result.returncode = 0
        mock_result.stdout = ""
        mock_result.stderr = ""

        with patch("specify_cli.integrations.get_integration", mock_get_integration), \
             patch("specify_cli.workflows.step.prompt.shutil.which", return_value="/opt/dummy"), \
             patch("subprocess.run", return_value=mock_result):
            step.execute(
                {"id": "p", "type": "prompt", "prompt": "hi", "integration": "dummy"},
                ctx,
            )

        mock_impl.build_exec_args.assert_called_once_with(
            "hi",
            model=None,
            output_json=False,
            project_root=Path("/fake/project/root"),
        )


class TestShellStep:
    """Test the shell step type."""

    @staticmethod
    def _python_run(tmp_path, body):
        """A portable shell ``run`` that executes ``body`` with the current
        interpreter, avoiding non-portable shell quoting (e.g. Windows
        ``cmd.exe`` keeping single quotes) in the output_format tests."""
        import sys

        script = tmp_path / "emit.py"
        script.write_text(body, encoding="utf-8")
        return f'"{sys.executable}" "{script}"'

    def test_execute_echo(self):
        from specify_cli.workflows.step.shell import ShellStep
        from specify_cli.workflows.base import StepContext, StepStatus

        step = ShellStep()
        ctx = StepContext()
        config = {"id": "test", "run": "echo hello"}
        result = step.execute(config, ctx)
        assert result.status == StepStatus.COMPLETED
        assert result.output["exit_code"] == 0
        assert "hello" in result.output["stdout"]

    def test_execute_failure(self):
        from specify_cli.workflows.step.shell import ShellStep
        from specify_cli.workflows.base import StepContext, StepStatus

        step = ShellStep()
        ctx = StepContext()
        config = {"id": "test", "run": "exit 1"}
        result = step.execute(config, ctx)
        assert result.status == StepStatus.FAILED
        assert result.output["exit_code"] == 1
        assert result.error is not None

    def test_validate_missing_run(self):
        from specify_cli.workflows.step.shell import ShellStep

        step = ShellStep()
        errors = step.validate({"id": "test"})
        assert any("missing 'run'" in e for e in errors)

    @pytest.mark.parametrize("bad_run", [None, ["echo", "hi"], 42])
    def test_validate_rejects_non_string_run(self, bad_run):
        """A non-string 'run' must be rejected at validation.

        execute() str()-coerces run and invokes it under shell=True, so a
        null or list run would otherwise run the Python repr as a command.
        """
        from specify_cli.workflows.step.shell import ShellStep

        step = ShellStep()
        errors = step.validate({"id": "s", "run": bad_run})
        assert any("'run' must be a string" in e for e in errors)

    def test_validate_accepts_string_and_expression_run(self):
        from specify_cli.workflows.step.shell import ShellStep

        step = ShellStep()
        assert step.validate({"id": "s", "run": "echo hi"}) == []
        assert step.validate({"id": "s", "run": "{{ steps.x.output }}"}) == []

    def test_output_format_json_exposes_data(self, tmp_path):
        from specify_cli.workflows.step.shell import ShellStep
        from specify_cli.workflows.base import StepContext, StepStatus

        step = ShellStep()
        ctx = StepContext(project_root=str(tmp_path))
        config = {
            "id": "emit",
            "run": self._python_run(
                tmp_path, 'import json; print(json.dumps({"items": [1, 2]}))\n'
            ),
            "output_format": "json",
        }
        result = step.execute(config, ctx)
        assert result.status == StepStatus.COMPLETED
        assert result.output["data"] == {"items": [1, 2]}
        assert result.output["exit_code"] == 0  # raw keys still present

    def test_output_format_json_invalid_stdout_fails(self, tmp_path):
        from specify_cli.workflows.step.shell import ShellStep
        from specify_cli.workflows.base import StepContext, StepStatus

        step = ShellStep()
        ctx = StepContext(project_root=str(tmp_path))
        config = {
            "id": "emit",
            "run": self._python_run(tmp_path, "print('not-json')\n"),
            "output_format": "json",
        }
        result = step.execute(config, ctx)
        assert result.status == StepStatus.FAILED
        assert "output_format: json" in (result.error or "")

    def test_no_output_format_keeps_raw_output_only(self, tmp_path):
        from specify_cli.workflows.step.shell import ShellStep
        from specify_cli.workflows.base import StepContext, StepStatus

        step = ShellStep()
        ctx = StepContext(project_root=str(tmp_path))
        config = {
            "id": "emit",
            "run": self._python_run(
                tmp_path, 'import json; print(json.dumps({"items": []}))\n'
            ),
        }
        result = step.execute(config, ctx)
        assert result.status == StepStatus.COMPLETED
        assert "data" not in result.output

    def test_validate_rejects_unknown_output_format(self):
        from specify_cli.workflows.step.shell import ShellStep

        step = ShellStep()
        errors = step.validate({"id": "emit", "run": "exit 0", "output_format": "yaml"})
        assert any("'output_format' must be 'json'" in e for e in errors)

    def test_configured_timeout_is_passed_to_subprocess(self, monkeypatch):
        """A ``timeout:`` value on the step overrides the 300s default and is
        threaded through to ``subprocess.run`` (issue #3327)."""
        import subprocess

        from specify_cli.workflows.step.shell import ShellStep
        from specify_cli.workflows.base import StepContext, StepStatus

        captured: dict[str, object] = {}

        def fake_run(*args, **kwargs):
            captured["timeout"] = kwargs.get("timeout")
            return subprocess.CompletedProcess(
                args=args[0] if args else "", returncode=0, stdout=b"", stderr=b""
            )

        monkeypatch.setattr(subprocess, "run", fake_run)
        step = ShellStep()
        result = step.execute(
            {"id": "qa", "run": "echo hi", "timeout": 1800}, StepContext()
        )
        assert result.status == StepStatus.COMPLETED
        assert captured["timeout"] == 1800

    def test_default_timeout_preserved_when_omitted(self, monkeypatch):
        """Omitting ``timeout:`` preserves the historical 300s default."""
        import subprocess

        from specify_cli.workflows.step.shell import ShellStep
        from specify_cli.workflows.base import StepContext

        captured: dict[str, object] = {}

        def fake_run(*args, **kwargs):
            captured["timeout"] = kwargs.get("timeout")
            return subprocess.CompletedProcess(
                args=args[0] if args else "", returncode=0, stdout=b"", stderr=b""
            )

        monkeypatch.setattr(subprocess, "run", fake_run)
        step = ShellStep()
        step.execute({"id": "qa", "run": "echo hi"}, StepContext())
        assert captured["timeout"] == 300

    def test_timeout_error_reports_configured_value(self, monkeypatch):
        """The timeout failure message reflects the configured duration, not a
        hardcoded 300."""
        import subprocess

        from specify_cli.workflows.step.shell import ShellStep
        from specify_cli.workflows.base import StepContext, StepStatus

        def fake_run(*args, **kwargs):
            raise subprocess.TimeoutExpired(cmd="echo hi", timeout=5)

        monkeypatch.setattr(subprocess, "run", fake_run)
        step = ShellStep()
        result = step.execute(
            {"id": "qa", "run": "echo hi", "timeout": 5}, StepContext()
        )
        assert result.status == StepStatus.FAILED
        assert "5 seconds" in (result.error or "")

    def test_execute_fails_cleanly_on_invalid_timeout(self, monkeypatch):
        """execute() must fail the step (not raise) on an invalid timeout even
        when validate() was skipped — the engine does not auto-validate step
        config, so an unvalidated string/bool/non-finite timeout would
        otherwise crash subprocess.run() and take down the whole run."""
        import subprocess

        from specify_cli.workflows.step.shell import ShellStep
        from specify_cli.workflows.base import StepContext, StepStatus

        def fail_if_called(*args, **kwargs):
            raise AssertionError("subprocess.run should not run on invalid timeout")

        monkeypatch.setattr(subprocess, "run", fail_if_called)
        step = ShellStep()
        # A string would raise TypeError; ``True`` would silently become a 1s
        # timeout (bool is an int subclass); ``.inf`` would raise at runtime.
        for bad in ("30", True, float("inf"), 0):
            result = step.execute(
                {"id": "qa", "run": "echo hi", "timeout": bad}, StepContext()
            )
            assert result.status == StepStatus.FAILED
            assert "'timeout' must be a positive number" in (result.error or "")

    def test_validate_rejects_non_positive_timeout(self):
        from specify_cli.workflows.step.shell import ShellStep

        step = ShellStep()
        for bad in (0, -30):
            errors = step.validate({"id": "qa", "run": "echo hi", "timeout": bad})
            assert any("'timeout' must be a positive number" in e for e in errors)

    def test_validate_rejects_non_numeric_timeout(self):
        from specify_cli.workflows.step.shell import ShellStep

        step = ShellStep()
        # A string and a bool are both invalid (bool is an int subclass but a
        # config error, not a duration).
        for bad in ("30", True):
            errors = step.validate({"id": "qa", "run": "echo hi", "timeout": bad})
            assert any("'timeout' must be a positive number" in e for e in errors)

    def test_validate_rejects_non_finite_timeout(self):
        from specify_cli.workflows.step.shell import ShellStep

        step = ShellStep()
        # inf/nan are floats and slip past a plain ``> 0`` check (``nan <= 0``
        # is False), but ``subprocess.run(timeout=...)`` would then fail at
        # runtime. YAML ``.inf``/``.nan`` scalars parse to these via safe_load.
        for bad in (float("inf"), float("-inf"), float("nan")):
            errors = step.validate({"id": "qa", "run": "echo hi", "timeout": bad})
            assert any("'timeout' must be a positive number" in e for e in errors)

    def test_validate_rejects_huge_int_timeout(self):
        """A too-large-to-convert int must be reported, not raise OverflowError.

        ``math.isfinite(10**400)`` raises ``OverflowError: int too large to
        convert to float``. Such a value is an ``int`` and is not a ``bool``,
        so it clears every clause before ``isfinite()`` and raises there —
        escaping ``validate()`` as the uncaught crash this guard exists to
        prevent. ``specify workflow run`` then aborts with a bare traceback
        instead of "Workflow validation failed". Both signs reach
        ``isfinite()`` because it is checked before ``timeout <= 0``.
        ``subprocess.run(timeout=...)`` raises the same OverflowError, so the
        value is genuinely invalid rather than merely unrepresentable here.
        The prompt step already catches this (PR #3847).
        """
        from specify_cli.workflows.step.shell import ShellStep

        step = ShellStep()
        for bad in (10**400, -(10**400)):
            errors = step.validate({"id": "qa", "run": "echo hi", "timeout": bad})
            assert any(
                "'timeout' must be a positive number" in e for e in errors
            ), (bad, errors)

    def test_validate_workflow_reports_huge_int_timeout(self):
        """The huge-int timeout surfaces as a validation error end to end.

        ``specify workflow run`` calls ``engine.validate()`` before executing
        any step; an OverflowError escaping the shell step's ``validate()``
        propagates out of ``validate_workflow`` and kills the command with a
        traceback, so pin the whole path, not just the helper.
        """
        from specify_cli.workflows.engine import WorkflowDefinition, validate_workflow

        definition = WorkflowDefinition(
            {
                "schema_version": "1.0",
                "workflow": {"id": "demo", "name": "Demo", "version": "1.0.0"},
                "steps": [
                    {"id": "qa", "type": "shell", "run": "echo hi", "timeout": 10**400}
                ],
            }
        )
        errors = validate_workflow(definition)
        assert any("'timeout' must be a positive number" in e for e in errors), errors

    def test_execute_fails_cleanly_on_huge_int_timeout(self, monkeypatch):
        """execute() must fail just this step on a huge-int timeout.

        The engine does not auto-validate step config and re-raises anything a
        step throws, so on an unvalidated run the OverflowError would abort the
        whole workflow after earlier steps had already run their side effects.
        """
        import subprocess

        from specify_cli.workflows.step.shell import ShellStep
        from specify_cli.workflows.base import StepContext, StepStatus

        def fail_if_called(*args, **kwargs):
            raise AssertionError("subprocess.run should not run on invalid timeout")

        monkeypatch.setattr(subprocess, "run", fail_if_called)
        step = ShellStep()
        for bad in (10**400, -(10**400)):
            result = step.execute(
                {"id": "qa", "run": "echo hi", "timeout": bad}, StepContext()
            )
            assert result.status == StepStatus.FAILED, bad
            assert "'timeout' must be a positive number" in (result.error or ""), bad

    def test_validate_accepts_positive_numeric_timeout(self):
        from specify_cli.workflows.step.shell import ShellStep

        step = ShellStep()
        for good in (1, 300, 1800, 12.5):
            errors = step.validate({"id": "qa", "run": "echo hi", "timeout": good})
            assert not any("'timeout'" in e for e in errors)

class _StubStdin:
    """Stdin stub exposing only a fixed ``isatty`` result.

    A real ``TextIOWrapper.isatty`` is not assignable under some runners
    (e.g. pytest with capture disabled), so the gate tests force the value
    through this stub to stay deterministic regardless of how the suite is
    run.
    """

    def __init__(self, tty: bool):
        self._tty = tty

    def isatty(self) -> bool:
        return self._tty


class _FakeSys:
    """Stand-in for the gate module's ``sys`` with a fixed-``isatty`` stdin.

    Every other attribute delegates to the real ``sys``. Rebinding the gate
    module's ``sys`` name (rather than mutating the process-wide
    ``sys.stdin``) keeps the patch local to the gate module and leaves the
    real stdin untouched.
    """

    def __init__(self, tty: bool):
        self.stdin = _StubStdin(tty)

    def __getattr__(self, name):
        return getattr(sys, name)


def _force_gate_stdin(monkeypatch, *, tty: bool):
    from specify_cli.workflows.step import gate as gate_module

    monkeypatch.setattr(gate_module, "sys", _FakeSys(tty=tty))


class TestInitStep:
    """Test the init step type."""

    def test_docstring_lists_every_valid_script_type(self):
        # The `script` field docstring must not contradict the step's own
        # VALID_SCRIPT_TYPES (which includes 'py'); validate() accepts all three.
        from specify_cli.workflows.step.init import InitStep, VALID_SCRIPT_TYPES

        for script_type in VALID_SCRIPT_TYPES:
            assert f"``{script_type}``" in InitStep.__doc__

    def test_builds_here_argv_and_bootstraps(self, tmp_path):
        from specify_cli.workflows.step.init import InitStep
        from specify_cli.workflows.base import StepContext, StepStatus

        step = InitStep()
        ctx = StepContext(
            project_root=str(tmp_path), default_integration="copilot"
        )
        config = {"id": "bootstrap", "here": True, "script": "sh"}
        result = step.execute(config, ctx)

        assert result.status == StepStatus.COMPLETED
        assert result.output["exit_code"] == 0
        argv = result.output["argv"]
        assert argv[0] == "init"
        assert "--here" in argv
        assert "--integration" in argv and "copilot" in argv
        assert "--ignore-agent-tools" in argv
        assert (tmp_path / ".specify").is_dir()

    def test_explicit_null_ignore_agent_tools_keeps_documented_default(
        self, tmp_path
    ):
        """A bare ``ignore_agent_tools:`` must keep the documented default.

        The class docstring says "Because workflows run unattended, the step
        defaults to ``--ignore-agent-tools``" and the field docs say "defaults to
        ``true``". But ``config.get(key, True)`` applies the default only when the
        key is ABSENT — a bare ``ignore_agent_tools:`` in YAML parses to None,
        which ``_resolve_bool`` turned into False, dropping the flag and
        re-enabling the agent-CLI presence check for an unattended run.
        """
        from specify_cli.workflows.step.init import InitStep
        from specify_cli.workflows.base import StepContext, StepStatus

        step = InitStep()
        ctx = StepContext(
            project_root=str(tmp_path), default_integration="copilot"
        )
        result = step.execute(
            {
                "id": "bootstrap",
                "here": True,
                "script": "sh",
                "ignore_agent_tools": None,
            },
            ctx,
        )

        assert result.status == StepStatus.COMPLETED
        assert "--ignore-agent-tools" in result.output["argv"]

    def test_explicit_false_ignore_agent_tools_is_honoured(self, tmp_path):
        """An explicit ``false`` must still opt in to the agent-CLI check."""
        from specify_cli.workflows.step.init import InitStep
        from specify_cli.workflows.base import StepContext

        step = InitStep()
        ctx = StepContext(
            project_root=str(tmp_path), default_integration="copilot"
        )
        result = step.execute(
            {
                "id": "bootstrap",
                "here": True,
                "script": "sh",
                "ignore_agent_tools": False,
            },
            ctx,
        )

        assert "--ignore-agent-tools" not in result.output["argv"]

    def test_default_integration_falls_back_to_workflow_default(self, tmp_path):
        from specify_cli.workflows.step.init import InitStep
        from specify_cli.workflows.base import StepContext, StepStatus

        step = InitStep()
        ctx = StepContext(
            project_root=str(tmp_path), default_integration="copilot"
        )
        result = step.execute(
            {"id": "bootstrap", "here": True, "script": "sh"}, ctx
        )
        assert result.status == StepStatus.COMPLETED
        assert result.output["integration"] == "copilot"

    def test_default_integration_honors_env_var(self, tmp_path, monkeypatch):
        # With no step-level and no workflow-level default, the resolved
        # SPECKIT_INTEGRATION_DEFAULT value must drive both output.integration
        # and the argv passed to init (guards against reverting to the constant).
        from specify_cli.workflows.step.init import InitStep
        from specify_cli.workflows.base import StepContext, StepStatus

        monkeypatch.setenv("SPECKIT_INTEGRATION_DEFAULT", "gemini")
        step = InitStep()
        ctx = StepContext(project_root=str(tmp_path))
        result = step.execute(
            {"id": "bootstrap", "here": True, "script": "sh"}, ctx
        )
        assert result.status == StepStatus.COMPLETED
        assert result.output["integration"] == "gemini"
        argv = result.output["argv"]
        assert "--integration" in argv and "gemini" in argv

    def test_project_name_creates_subdirectory(self, tmp_path):
        from specify_cli.workflows.step.init import InitStep
        from specify_cli.workflows.base import StepContext, StepStatus

        step = InitStep()
        ctx = StepContext(
            project_root=str(tmp_path), default_integration="copilot"
        )
        result = step.execute(
            {
                "id": "bootstrap",
                "project": "demo",
                "script": "sh",
            },
            ctx,
        )
        assert result.status == StepStatus.COMPLETED
        assert (tmp_path / "demo" / ".specify").is_dir()

    def test_invalid_integration_fails(self, tmp_path):
        from specify_cli.workflows.step.init import InitStep
        from specify_cli.workflows.base import StepContext, StepStatus

        step = InitStep()
        ctx = StepContext(project_root=str(tmp_path))
        result = step.execute(
            {
                "id": "bootstrap",
                "here": True,
                "integration": "no-such-agent",
                "script": "sh",
            },
            ctx,
        )
        assert result.status == StepStatus.FAILED
        assert result.output["exit_code"] != 0
        assert result.error is not None

    def test_failed_init_surfaces_inits_own_message(self, tmp_path):
        """A failing init step must report init's diagnostics, not 'SystemExit: 1'.

        `typer.Exit(n)` — how `specify init` reports every ordinary failure —
        surfaces through `CliRunner` as `result.exception = SystemExit(n)`, so
        the unexpected-crash branch fired on routine errors too. `init` prints
        through Rich to stdout, leaving `result.stderr` empty, so the
        synthesized "SystemExit: 1" became the whole of stderr and preempted
        the `stderr.strip() or stdout.strip()` fallback — stranding the real
        message (here, the list of valid integrations) in stdout.
        """
        from specify_cli.workflows.step.init import InitStep
        from specify_cli.workflows.base import StepContext, StepStatus

        result = InitStep().execute(
            {
                "id": "bootstrap",
                "here": True,
                "integration": "no-such-agent",
                "script": "sh",
            },
            StepContext(project_root=str(tmp_path)),
        )

        assert result.status == StepStatus.FAILED
        assert result.error is not None
        assert result.error.strip() != "SystemExit: 1"

        # The real diagnostic reaches the caller...
        collapsed = " ".join(result.error.split())
        assert "no-such-agent" in collapsed or "Unknown" in collapsed, collapsed

        # ...and reaches a downstream step reading steps.<id>.output.stderr.
        # Asserting only "not the old sentinel" was too weak: an EMPTY stderr
        # satisfies that while still carrying no diagnostic at all, which is
        # exactly what dropping the synthesized detail left behind under
        # click >= 8.2 (separate streams, init prints through Rich to stdout).
        stderr = " ".join(result.output["stderr"].split())
        assert stderr, "output.stderr must not be empty for a failed init"
        assert stderr != "SystemExit: 1"
        assert "no-such-agent" in stderr or "Unknown" in stderr, stderr

    def test_unexpected_crash_still_reports_its_exception(self, monkeypatch, tmp_path):
        """The branch's original purpose is preserved for a genuine crash.

        Only `SystemExit` is now excluded; any other exception escaping the
        runner must still be surfaced, since nothing else would describe it.
        """
        from specify_cli.workflows.step.init import InitStep
        import typer.testing

        class _Result:
            exit_code = 1
            output = ""
            stderr = ""
            exception = RuntimeError("boom inside init")

        class _Runner:
            def __init__(self, *a, **k):
                pass

            def invoke(self, *a, **k):
                return _Result()

        monkeypatch.setattr(typer.testing, "CliRunner", _Runner)

        from specify_cli.workflows.base import StepContext

        _code, _stdout, stderr = InitStep()._run_init(
            ["init", "demo"], StepContext(project_root=str(tmp_path))
        )

        assert "RuntimeError: boom inside init" in stderr

    def test_non_empty_current_dir_without_force_fails_fast(self, tmp_path):
        from specify_cli.workflows.step.init import InitStep
        from specify_cli.workflows.base import StepContext, StepStatus

        (tmp_path / "existing.txt").write_text("data")

        step = InitStep()
        ctx = StepContext(
            project_root=str(tmp_path), default_integration="copilot"
        )
        result = step.execute(
            {"id": "bootstrap", "here": True, "script": "sh"},
            ctx,
        )
        assert result.status == StepStatus.FAILED
        assert "force: true" in (result.error or "")
        assert not (tmp_path / ".specify").exists()

    def test_engine_owned_dirs_do_not_trigger_non_empty_check(self, tmp_path):
        from specify_cli.workflows.step.init import InitStep
        from specify_cli.workflows.base import StepContext, StepStatus

        # Simulate the engine creating its run-state directory before steps run
        (tmp_path / ".specify" / "workflows" / "runs" / "abc123").mkdir(
            parents=True
        )

        step = InitStep()
        ctx = StepContext(
            project_root=str(tmp_path), default_integration="copilot"
        )
        result = step.execute(
            {"id": "bootstrap", "here": True, "script": "sh"},
            ctx,
        )
        assert result.status == StepStatus.COMPLETED
        # Verify --force was implicitly added
        assert "--force" in result.output["argv"]

    def test_default_integration_when_none_provided(self, tmp_path):
        from specify_cli.workflows.step.init import InitStep
        from specify_cli.workflows.base import StepContext, StepStatus

        step = InitStep()
        # No default_integration on context either
        ctx = StepContext(project_root=str(tmp_path))
        result = step.execute(
            {"id": "bootstrap", "here": True, "script": "sh"},
            ctx,
        )
        assert result.status == StepStatus.COMPLETED
        assert result.output["integration"] == "copilot"

    def test_integration_options_passed_through(self, tmp_path):
        from specify_cli.workflows.step.init import InitStep
        from specify_cli.workflows.base import StepContext, StepStatus

        step = InitStep()
        ctx = StepContext(
            project_root=str(tmp_path), default_integration="copilot"
        )
        result = step.execute(
            {
                "id": "bootstrap",
                "here": True,
                "script": "sh",
                "integration": "copilot",
                "integration_options": "--skills",
            },
            ctx,
        )
        assert result.status == StepStatus.COMPLETED
        assert "--integration-options" in result.output["argv"]
        assert "--skills" in result.output["argv"]
        assert result.output["integration_options"] == "--skills"

    def test_validate_rejects_bad_script(self):
        from specify_cli.workflows.step.init import InitStep

        step = InitStep()
        errors = step.validate({"id": "bootstrap", "script": "bogus"})
        assert any("'script' must be 'sh' or 'ps'" in e for e in errors)

    def test_validate_accepts_valid(self):
        from specify_cli.workflows.step.init import InitStep

        step = InitStep()
        assert step.validate({"id": "bootstrap", "script": "sh"}) == []


class TestGateStep:
    """Test the gate step type."""

    def test_docstring_lists_every_on_reject_behaviour(self):
        # The docstring must not contradict validate()/execute(): on_reject
        # accepts 'abort', 'skip', AND 'retry' (execute() has a dedicated
        # retry -> PAUSED branch), but the summary omitted 'retry'.
        from specify_cli.workflows.step.gate import GateStep

        for behaviour in ("abort", "skip", "retry"):
            assert behaviour in GateStep.__doc__

    @pytest.fixture(autouse=True)
    def _non_tty_stdin_by_default(self, monkeypatch):
        # Default every gate test to a non-TTY stdin so none can drop into
        # the interactive prompt and block on input() when the suite runs
        # with a real TTY. Interactive tests opt back in with
        # _force_gate_stdin(monkeypatch, tty=True).
        _force_gate_stdin(monkeypatch, tty=False)

    def test_execute_returns_paused(self):
        from specify_cli.workflows.step.gate import GateStep
        from specify_cli.workflows.base import StepContext, StepStatus

        step = GateStep()
        ctx = StepContext()
        config = {
            "id": "review",
            "message": "Review the spec.",
            "options": ["approve", "reject"],
            "on_reject": "abort",
        }
        result = step.execute(config, ctx)
        assert result.status == StepStatus.PAUSED
        assert result.output["message"] == "Review the spec."
        assert result.output["options"] == ["approve", "reject"]

    def test_message_expression_is_interpolated(self):
        """A gate ``message`` containing ``{{ }}`` is evaluated against the
        context before it is persisted, not shown verbatim."""
        from specify_cli.workflows.step.gate import GateStep
        from specify_cli.workflows.base import StepContext, StepStatus

        result = GateStep().execute(
            {
                "id": "review",
                "message": "Approve {{ inputs.feature }}?",
                "options": ["approve", "reject"],
            },
            StepContext(inputs={"feature": "login"}),
        )
        assert result.status == StepStatus.PAUSED
        assert result.output["message"] == "Approve login?"

    @pytest.mark.parametrize(
        "inputs", [{}, {"spec_verdict": None}, {"spec_verdict": ""}]
    )
    def test_missing_or_empty_verdict_input_uses_existing_pause_behavior(self, inputs):
        from specify_cli.workflows.step.gate import GateStep
        from specify_cli.workflows.base import StepContext, StepStatus

        result = GateStep().execute(
            {
                "id": "review",
                "message": "Review the spec.",
                "options": ["approve", "reject"],
                "verdict_input": "spec_verdict",
            },
            StepContext(inputs=inputs),
        )
        assert result.status == StepStatus.PAUSED
        assert result.output["choice"] is None

    @pytest.mark.parametrize("inputs", [{}, {"spec_verdict": ""}])
    def test_missing_or_empty_verdict_input_prompts_on_tty(self, monkeypatch, inputs):
        from specify_cli.workflows.step.gate import GateStep
        from specify_cli.workflows.base import StepContext, StepStatus

        _force_gate_stdin(monkeypatch, tty=True)
        monkeypatch.setattr(
            GateStep, "_prompt", staticmethod(lambda _message, _options: "approve")
        )
        result = GateStep().execute(
            {
                "id": "review",
                "message": "Review the spec.",
                "options": ["approve", "reject"],
                "verdict_input": "spec_verdict",
            },
            StepContext(inputs=inputs),
        )
        assert result.status == StepStatus.COMPLETED
        assert result.output["choice"] == "approve"

    def test_verdict_input_uses_canonical_option_spelling(self):
        from specify_cli.workflows.step.gate import GateStep
        from specify_cli.workflows.base import StepContext, StepStatus

        result = GateStep().execute(
            {
                "id": "review",
                "message": "Review the spec.",
                "options": ["Approve", "Reject"],
                "verdict_input": "spec_verdict",
            },
            StepContext(inputs={"spec_verdict": "aPpRoVe"}),
        )
        assert result.status == StepStatus.COMPLETED
        assert result.output["choice"] == "Approve"

    @pytest.mark.parametrize(
        ("value", "error_fragment"),
        [(42, "must be a string"), ("maybe", "does not match")],
    )
    def test_invalid_verdict_input_value_fails(self, value, error_fragment):
        from specify_cli.workflows.step.gate import GateStep
        from specify_cli.workflows.base import StepContext, StepStatus

        result = GateStep().execute(
            {
                "id": "review",
                "message": "Review the spec.",
                "options": ["approve", "reject"],
                "verdict_input": "spec_verdict",
            },
            StepContext(inputs={"spec_verdict": value}),
        )
        assert result.status == StepStatus.FAILED
        assert error_fragment in (result.error or "")

    def test_verdict_input_fails_inside_fan_out_context(self):
        from specify_cli.workflows.step.gate import GateStep
        from specify_cli.workflows.base import StepContext, StepStatus

        result = GateStep().execute(
            {
                "id": "review",
                "message": "Review the item.",
                "options": ["approve", "reject"],
                "verdict_input": "spec_verdict",
            },
            StepContext(
                inputs={"spec_verdict": "approve"},
                inside_fan_out=True,
            ),
        )

        assert result.status == StepStatus.FAILED
        assert "'verdict_input' is not supported inside fan-out" in (
            result.error or ""
        )

    @pytest.mark.parametrize(
        ("value", "error_fragment"),
        [(42, "must be a string"), ("maybe", "does not match")],
    )
    def test_failed_gate_persists_error_in_step_results(
        self, tmp_path, value, error_fragment
    ):
        """Engine persists result.error into step_results for failed gates."""
        from specify_cli.workflows.engine import WorkflowEngine

        wf_yaml = f"""
schema_version: "1.0"
workflow:
  id: "gate-error-persist"
  name: "Gate Error Persist"
  version: "1.0.0"
inputs:
  spec_verdict:
    type: {"number" if isinstance(value, int) else "string"}
    default: {value}
steps:
  - id: review
    type: gate
    message: "Review the spec."
    options: [approve, reject]
    on_reject: abort
    verdict_input: spec_verdict
"""
        wf_path = tmp_path / "wf.yml"
        wf_path.write_text(wf_yaml, encoding="utf-8")
        (tmp_path / ".specify").mkdir()
        engine = WorkflowEngine(tmp_path)
        definition = engine.load_workflow(str(wf_path))
        state = engine.execute(definition, {})
        assert state.status.value == "failed"
        step_data = state.step_results["review"]
        assert step_data["status"] == "failed"
        assert error_fragment in (step_data.get("error") or "")

    @pytest.mark.parametrize("invalid_value", ["", 42, None])
    def test_validate_invalid_verdict_input(self, invalid_value):
        from specify_cli.workflows.step.gate import GateStep

        errors = GateStep().validate({
            "id": "review",
            "message": "Review the spec.",
            "verdict_input": invalid_value,
        })
        assert any("verdict_input" in error for error in errors)

    @pytest.mark.parametrize(
        ("on_reject", "status", "aborted"),
        [
            ("abort", "failed", True),
            ("skip", "completed", False),
            ("retry", "paused", False),
        ],
    )
    def test_reject_verdict_input_preserves_reject_behavior(
        self, on_reject, status, aborted
    ):
        from specify_cli.workflows.step.gate import GateStep
        from specify_cli.workflows.base import StepContext

        context = StepContext(inputs={"spec_verdict": "reject"})
        result = GateStep().execute(
            {
                "id": "review",
                "message": "Review the spec.",
                "options": ["approve", "reject"],
                "on_reject": on_reject,
                "verdict_input": "spec_verdict",
            },
            context,
        )
        assert result.status.value == status
        assert result.output.get("aborted", False) is aborted
        assert context.inputs["spec_verdict"] == (
            "" if on_reject == "retry" else "reject"
        )

    def test_validate_missing_message(self):
        from specify_cli.workflows.step.gate import GateStep

        step = GateStep()
        errors = step.validate({"id": "test", "options": ["approve"]})
        assert any("missing 'message'" in e for e in errors)

    def test_validate_invalid_on_reject(self):
        from specify_cli.workflows.step.gate import GateStep

        step = GateStep()
        errors = step.validate({
            "id": "test",
            "message": "Review",
            "on_reject": "invalid",
        })
        assert any("on_reject" in e for e in errors)

    @pytest.mark.parametrize(
        "bad_on_reject", ["Abort", "fail", "stop", "SKIP", None, 5, ["abort"]]
    )
    def test_execute_invalid_on_reject_fails_loudly(self, bad_on_reject):
        """An unrecognised ``on_reject`` must not silently complete a rejection.

        ``validate`` rejects anything outside abort/skip/retry, but the engine
        does not auto-validate before ``execute``. The reject branch handles only
        "abort" and "retry", then falls through to its ``"skip"`` case — so a
        REJECTED gate reported COMPLETED and the run continued past the review
        the gate exists to enforce. Reachable by a capitalisation slip, a guessed
        verb, a non-string, or a bare ``on_reject:`` (which yields None, since
        ``config.get(k, default)`` does not replace an explicit null).
        """
        from specify_cli.workflows.step.gate import GateStep
        from specify_cli.workflows.base import StepContext, StepStatus

        result = GateStep().execute(
            {
                "id": "review",
                "message": "Review the spec.",
                "options": ["approve", "reject"],
                "on_reject": bad_on_reject,
                "verdict_input": "spec_verdict",
            },
            StepContext(inputs={"spec_verdict": "reject"}),
        )
        assert result.status == StepStatus.FAILED
        assert "'on_reject' must be" in (result.error or "")

    def test_validate_non_string_options_does_not_raise(self):
        """Non-string options with on_reject=abort/retry must be REPORTED as an
        error, not crash: the reject-choice check calls o.lower() on each option,
        which previously raised AttributeError on a non-string option and broke
        validate_workflow's 'return errors, never raise' contract."""
        from specify_cli.workflows.step.gate import GateStep

        step = GateStep()
        # on_reject defaults to "abort", which triggers the option-text check.
        errors = step.validate({"id": "test", "message": "Review", "options": [123]})
        assert any("must be strings" in e for e in errors)
        # also with an explicit retry on_reject
        errors = step.validate(
            {"id": "test", "message": "Review", "options": [True], "on_reject": "retry"}
        )
        assert any("must be strings" in e for e in errors)

    def test_interactive_prompt_renders_show_file(self, tmp_path, monkeypatch, capsys):
        from specify_cli.workflows.step.gate import GateStep
        from specify_cli.workflows.base import StepContext, StepStatus

        review = tmp_path / "spec.md"
        review.write_text("LINE-ONE\nLINE-TWO\n", encoding="utf-8")

        _force_gate_stdin(monkeypatch, tty=True)
        monkeypatch.setattr("builtins.input", lambda _prompt="": "1")

        step = GateStep()
        config = {
            "id": "review",
            "message": "Review the spec.",
            "show_file": str(review),
            "options": ["approve", "reject"],
        }
        result = step.execute(config, StepContext())
        out = capsys.readouterr().out

        assert "LINE-ONE" in out and "LINE-TWO" in out
        assert str(review) in out
        assert result.status == StepStatus.COMPLETED
        assert result.output["choice"] == "approve"

    def test_interactive_prompt_rejects_non_decimal_digit(self, monkeypatch, capsys):
        """A Unicode digit int() can't parse — e.g. the superscript '²', which
        str.isdigit() accepts but int() rejects — must be treated as an invalid
        choice, not crash the prompt loop with an uncaught ValueError."""
        from specify_cli.workflows.step.gate import GateStep

        _force_gate_stdin(monkeypatch, tty=True)
        inputs = iter(["²", "1"])  # superscript-two, then a real "1"
        monkeypatch.setattr("builtins.input", lambda _prompt="": next(inputs))

        choice = GateStep._prompt("Review the spec.", ["approve", "reject"])
        assert choice == "approve"

    @pytest.mark.parametrize(
        "options",
        [
            ["approve", "reject"],
            ["reject", "approve"],
            ["approve", "reject", "request-changes"],
        ],
        ids=["reject_last", "reject_first", "reject_middle"],
    )
    def test_eof_at_prompt_never_approves(self, monkeypatch, options):
        """Ctrl+D at a gate must not resolve to an approving option.

        `_prompt` returned `options[-1]`, assuming the reject option is last.
        `validate` only requires that *some* option is 'reject'/'abort', never
        that it is last, so `options: [approve, reject, request-changes]`
        validates clean and EOF returned 'request-changes' — which `execute`
        does not classify as a rejection, so the gate reported COMPLETED and
        the run walked past the human review.
        """
        from specify_cli.workflows.step.gate import GateStep

        _force_gate_stdin(monkeypatch, tty=True)

        def _boom(_prompt=""):
            raise EOFError

        monkeypatch.setattr("builtins.input", _boom)

        assert GateStep._prompt("Approve the plan?", options) == "reject"

    def test_eof_without_a_reject_option_keeps_last(self, monkeypatch):
        """With no reject/abort option declared, the last option is still used."""
        from specify_cli.workflows.step.gate import GateStep

        _force_gate_stdin(monkeypatch, tty=True)

        def _boom(_prompt=""):
            raise EOFError

        monkeypatch.setattr("builtins.input", _boom)

        assert GateStep._prompt("Pick one.", ["yes", "no"]) == "no"

    def test_ctrl_c_propagates_rather_than_becoming_a_verdict(self, monkeypatch):
        """Ctrl+C is not a gate decision — it must reach the engine.

        `WorkflowEngine` turns a propagated KeyboardInterrupt into
        `RunStatus.PAUSED` plus a `workflow_interrupted` event, so the operator
        can resume. Swallowing it here produced a *decision* instead: the reject
        branch fired `on_reject`, usually aborting the whole run — the one
        outcome an interrupted reviewer did not choose.
        """
        from specify_cli.workflows.step.gate import GateStep

        _force_gate_stdin(monkeypatch, tty=True)

        def _boom(_prompt=""):
            raise KeyboardInterrupt

        monkeypatch.setattr("builtins.input", _boom)

        with pytest.raises(KeyboardInterrupt):
            GateStep._prompt("Approve the plan?", ["approve", "reject"])

    def test_ctrl_c_at_a_gate_step_propagates(self, monkeypatch):
        """The step level must not convert it either — `execute` lets it through."""
        from specify_cli.workflows.step.gate import GateStep
        from specify_cli.workflows.base import StepContext

        _force_gate_stdin(monkeypatch, tty=True)

        def _boom(_prompt=""):
            raise KeyboardInterrupt

        monkeypatch.setattr("builtins.input", _boom)

        with pytest.raises(KeyboardInterrupt):
            GateStep().execute(
                {
                    "id": "review",
                    "message": "Approve the plan?",
                    "options": ["approve", "reject", "request-changes"],
                    "on_reject": "abort",
                },
                StepContext(),
            )

    def test_eof_at_a_gate_step_records_a_rejection(self, monkeypatch):
        """EOF still yields a verdict: there is no operator left to resume."""
        from specify_cli.workflows.step.gate import GateStep
        from specify_cli.workflows.base import StepContext, StepStatus

        _force_gate_stdin(monkeypatch, tty=True)

        def _boom(_prompt=""):
            raise EOFError

        monkeypatch.setattr("builtins.input", _boom)

        result = GateStep().execute(
            {
                "id": "review",
                "message": "Approve the plan?",
                "options": ["approve", "reject", "request-changes"],
                "on_reject": "abort",
            },
            StepContext(),
        )

        assert result.status is StepStatus.FAILED
        assert result.output["choice"] == "reject"

    def test_ctrl_c_at_a_gate_pauses_the_run(self, tmp_path, monkeypatch):
        """End to end: Ctrl+C at a gate pauses the run, it does not abort it.

        This is the contract the split exists to honour. Previously the reject
        fallback fired `on_reject: abort`, so an interrupted reviewer lost the
        run instead of being able to `specify workflow resume` it.
        """
        import yaml
        from specify_cli.workflows.engine import WorkflowEngine, RunStatus

        workflows = tmp_path / ".specify" / "workflows" / "demo"
        workflows.mkdir(parents=True)
        (workflows / "workflow.yml").write_text(
            yaml.safe_dump(
                {
                    "schema_version": "1.0",
                    "workflow": {"id": "demo", "name": "D", "version": "1.0.0"},
                    "steps": [
                        {
                            "id": "review",
                            "type": "gate",
                            "message": "Approve?",
                            "options": ["approve", "reject"],
                            "on_reject": "abort",
                        }
                    ],
                }
            ),
            encoding="utf-8",
        )

        _force_gate_stdin(monkeypatch, tty=True)

        def _boom(_prompt=""):
            raise KeyboardInterrupt

        monkeypatch.setattr("builtins.input", _boom)

        engine = WorkflowEngine(tmp_path)
        state = engine.execute(engine.load_workflow("demo"))

        assert state.status is RunStatus.PAUSED
        events = [e.get("event") for e in state.log_entries if isinstance(e, dict)]
        assert "workflow_interrupted" in events, events

    def test_interactive_prompt_missing_show_file_does_not_crash(
        self, tmp_path, monkeypatch, capsys
    ):
        from specify_cli.workflows.step.gate import GateStep
        from specify_cli.workflows.base import StepContext, StepStatus

        missing = tmp_path / "does-not-exist.md"

        _force_gate_stdin(monkeypatch, tty=True)
        monkeypatch.setattr("builtins.input", lambda _prompt="": "1")

        step = GateStep()
        config = {
            "id": "review",
            "message": "Review.",
            "show_file": str(missing),
            "options": ["approve", "reject"],
        }
        result = step.execute(config, StepContext())
        out = capsys.readouterr().out

        assert "could not read file" in out
        assert result.status == StepStatus.COMPLETED

    def test_non_interactive_show_file_still_pauses_without_reading(
        self, tmp_path, monkeypatch
    ):
        from specify_cli.workflows.step.gate import GateStep
        from specify_cli.workflows.base import StepContext, StepStatus

        review = tmp_path / "spec.md"
        review.write_text("CONTENT\n", encoding="utf-8")

        # stdin defaults to non-TTY via the autouse fixture.
        # The non-interactive path must not read the file; hard-fail if it does.
        monkeypatch.setattr(
            GateStep,
            "_read_show_file",
            staticmethod(
                lambda _p: (_ for _ in ()).throw(
                    AssertionError("show_file read on the non-interactive path")
                )
            ),
        )

        step = GateStep()
        config = {
            "id": "review",
            "message": "Review.",
            "show_file": str(review),
            "options": ["approve", "reject"],
        }
        result = step.execute(config, StepContext())
        assert result.status == StepStatus.PAUSED
        assert result.output["show_file"] == str(review)

    def test_read_show_file_empty(self, tmp_path):
        from specify_cli.workflows.step.gate import GateStep

        empty = tmp_path / "empty.md"
        empty.write_text("", encoding="utf-8")
        assert GateStep._read_show_file(str(empty)) == ["(file is empty)"]

    def test_read_show_file_truncates_large_file(self, tmp_path):
        from specify_cli.workflows.step.gate import GateStep

        big = tmp_path / "big.md"
        big.write_text(
            "\n".join(f"line{i}" for i in range(GateStep.MAX_SHOW_FILE_LINES + 50)),
            encoding="utf-8",
        )
        rendered = GateStep._read_show_file(str(big))
        # MAX_SHOW_FILE_LINES content lines + one truncation notice line.
        assert len(rendered) == GateStep.MAX_SHOW_FILE_LINES + 1
        assert "truncated" in rendered[-1]

    def test_read_show_file_invalid_path_does_not_raise(self):
        from specify_cli.workflows.step.gate import GateStep

        # An embedded NUL byte makes the OS reject the path with ValueError
        # before any I/O; it must degrade to a notice, not crash the prompt.
        rendered = GateStep._read_show_file("bad\x00path.md")
        assert len(rendered) == 1
        assert rendered[0].startswith("(could not read file:")

    def test_read_show_file_strips_control_chars(self, tmp_path):
        from specify_cli.workflows.step.gate import GateStep

        # A file with ANSI/control bytes must not inject escapes into the
        # terminal; ESC and other C0 controls are stripped, tab is kept.
        f = tmp_path / "ansi.md"
        f.write_text("a\x1b[2Jb\tc\x07d\n", encoding="utf-8")
        rendered = GateStep._read_show_file(str(f))
        assert rendered == ["a[2Jb\tcd"]
        assert "\x1b" not in rendered[0] and "\x07" not in rendered[0]

    def test_compose_prompt_sanitizes_show_file_path(self):
        from specify_cli.workflows.step.gate import GateStep

        # The displayed path header (and the read-error notice it produces)
        # must not carry escapes even when the path string itself contains
        # control characters — ESC, LF, and C1 CSI (\x9b); the file is still
        # opened with the raw value.
        out = GateStep._compose_prompt("Review.", "ev\x1bil\x9b[2J\npath.md")
        assert "\x1b" not in out and "\x9b" not in out
        assert "evil[2Jpath.md:" in out

    def test_interactive_non_string_message_renders(self, monkeypatch, capsys):
        from specify_cli.workflows.step.gate import GateStep
        from specify_cli.workflows.base import StepContext, StepStatus

        # A YAML numeric literal reaches the prompt as a non-string; it must
        # render rather than crash on the multi-line split.
        _force_gate_stdin(monkeypatch, tty=True)
        monkeypatch.setattr("builtins.input", lambda _prompt="": "1")

        step = GateStep()
        config = {"id": "review", "message": 123, "options": ["approve", "reject"]}
        result = step.execute(config, StepContext())
        out = capsys.readouterr().out
        assert "123" in out
        assert result.status == StepStatus.COMPLETED

    def test_templated_show_file_resolving_to_non_string_is_coerced(self):
        from specify_cli.workflows.step.gate import GateStep
        from specify_cli.workflows.base import StepContext, StepStatus

        # A single-expression template can resolve to a non-string (e.g. a
        # number from a prior step); it must be coerced to str, not skipped.
        # stdin defaults to non-TTY via the autouse fixture, so the path
        # stays non-interactive (-> PAUSED) and cannot block on input.
        step = GateStep()
        ctx = StepContext(steps={"prev": {"output": {"ref": 123}}})
        config = {
            "id": "review",
            "message": "Review.",
            "show_file": "{{ steps.prev.output.ref }}",
            "options": ["approve", "reject"],
        }
        result = step.execute(config, ctx)  # non-interactive -> PAUSED
        assert result.status == StepStatus.PAUSED
        assert result.output["show_file"] == "123"

    @pytest.mark.parametrize(
        "bad_options",
        [5, {"a": "approve"}, None, [], "approve"],
    )
    def test_execute_non_list_options_fails_cleanly(self, monkeypatch, bad_options):
        """A malformed ``options`` must FAIL the step, not crash the run.

        ``validate`` rejects a non-list/empty ``options``, but the engine does
        not auto-validate before ``execute``. On an interactive run a scalar/
        dict/None ``options`` would otherwise reach ``_prompt`` and raise a raw
        ``TypeError`` (``enumerate``/``len`` on a non-iterable) or ``KeyError``
        (indexing a dict), crashing the whole workflow. Mirrors the switch
        'cases' and command 'input' unvalidated-execute guards."""
        from specify_cli.workflows.step.gate import GateStep
        from specify_cli.workflows.base import StepContext, StepStatus

        # Force an interactive TTY so the crash-prone _prompt path is reached;
        # input() is stubbed so a (buggy) fall-through can't block the suite.
        _force_gate_stdin(monkeypatch, tty=True)
        monkeypatch.setattr("builtins.input", lambda _prompt="": "1")

        step = GateStep()
        config = {"id": "review", "message": "Review.", "options": bad_options}
        result = step.execute(config, StepContext())

        assert result.status == StepStatus.FAILED
        assert "options" in (result.error or "")
        assert result.output["choice"] is None

    def test_execute_non_string_options_element_fails_cleanly(self, monkeypatch):
        """A non-string option element must FAIL the step, not crash.

        A non-empty list with a non-string element passes the shape check but
        would reach the reject test ``choice.lower()`` and raise a raw
        ``AttributeError`` at run time. ``validate`` reports "must be strings";
        ``execute`` must fail cleanly on an unvalidated run too."""
        from specify_cli.workflows.step.gate import GateStep
        from specify_cli.workflows.base import StepContext, StepStatus

        _force_gate_stdin(monkeypatch, tty=True)
        monkeypatch.setattr("builtins.input", lambda _prompt="": "1")

        step = GateStep()
        config = {"id": "review", "message": "Review.", "options": [123, 456]}
        result = step.execute(config, StepContext())

        assert result.status == StepStatus.FAILED
        assert "options" in (result.error or "")

    def test_execute_non_list_options_fails_in_non_tty_too(self):
        """The guard runs before the non-TTY PAUSE short-circuit.

        A malformed ``options`` should surface as FAILED in CI (non-TTY) rather
        than PAUSING and only crashing later when an operator resumes on a real
        terminal."""
        from specify_cli.workflows.step.gate import GateStep
        from specify_cli.workflows.base import StepContext, StepStatus

        # Autouse fixture already forces non-TTY stdin.
        step = GateStep()
        config = {"id": "review", "message": "Review.", "options": 5}
        result = step.execute(config, StepContext())

        assert result.status == StepStatus.FAILED
        assert "options" in (result.error or "")


class TestIfThenStep:
    """Test the if/then/else step type."""

    def test_execute_then_branch(self):
        from specify_cli.workflows.step.if_then import IfThenStep
        from specify_cli.workflows.base import StepContext

        step = IfThenStep()
        ctx = StepContext(inputs={"scope": "full"})
        config = {
            "id": "check",
            "condition": "{{ inputs.scope == 'full' }}",
            "then": [{"id": "a", "command": "speckit.tasks"}],
            "else": [{"id": "b", "command": "speckit.plan"}],
        }
        result = step.execute(config, ctx)
        assert result.output["condition_result"] is True
        assert len(result.next_steps) == 1
        assert result.next_steps[0]["id"] == "a"

    def test_execute_else_branch(self):
        from specify_cli.workflows.step.if_then import IfThenStep
        from specify_cli.workflows.base import StepContext

        step = IfThenStep()
        ctx = StepContext(inputs={"scope": "backend"})
        config = {
            "id": "check",
            "condition": "{{ inputs.scope == 'full' }}",
            "then": [{"id": "a", "command": "speckit.tasks"}],
            "else": [{"id": "b", "command": "speckit.plan"}],
        }
        result = step.execute(config, ctx)
        assert result.output["condition_result"] is False
        assert result.next_steps[0]["id"] == "b"

    def test_validate_missing_condition(self):
        from specify_cli.workflows.step.if_then import IfThenStep

        step = IfThenStep()
        errors = step.validate({"id": "test", "then": []})
        assert any("missing 'condition'" in e for e in errors)

    @pytest.mark.parametrize("bad", [["a", "b"], {"k": "v"}, 5, 1.5])
    def test_validate_rejects_non_string_non_bool_condition(self, bad):
        # A list/dict/number condition is returned unchanged by
        # evaluate_expression, and evaluate_condition then bool()-coerces it, so
        # it silently resolves to its truthiness (e.g. [1, 2] is always True)
        # instead of erroring on the authoring mistake.
        from specify_cli.workflows.step.if_then import IfThenStep

        step = IfThenStep()
        errors = step.validate({"id": "test", "condition": bad, "then": []})
        assert any("'condition' must be a" in e for e in errors), bad

    @pytest.mark.parametrize(
        "good",
        [
            "true", "false", "{{ inputs.flag }}",
            True, False,  # unquoted YAML bool: resolved exactly, and it is the
                          # default this step itself uses -- must stay valid
        ],
    )
    def test_validate_accepts_string_or_bool_condition(self, good):
        from specify_cli.workflows.step.if_then import IfThenStep

        step = IfThenStep()
        errors = step.validate({"id": "test", "condition": good, "then": []})
        assert not any("'condition' must be a" in e for e in errors), good

    @pytest.mark.parametrize("bad_branch", [{"id": "x"}, "oops", 5])
    def test_execute_non_list_then_fails_loudly(self, bad_branch):
        """A non-list ``then`` must fail the step, not crash the run.

        ``validate`` rejects a non-list ``then``, but the engine does not
        auto-validate (see ``WorkflowEngine.load_workflow``) and feeds
        ``next_steps`` straight into ``_execute_steps``, which iterates them as
        step mappings. Before the guard, a non-list ``then`` (a single mapping
        or scalar authoring mistake) was iterated element-wise and raised
        AttributeError on ``.get()``, taking down the whole run. Mirrors the
        switch/fan-out non-list handling.
        """
        from specify_cli.workflows.step.if_then import IfThenStep
        from specify_cli.workflows.base import StepContext, StepStatus

        step = IfThenStep()
        ctx = StepContext(inputs={})
        result = step.execute(
            {"id": "branch", "condition": "true", "then": bad_branch}, ctx
        )
        assert result.status == StepStatus.FAILED
        assert "'then' must be a list of steps" in (result.error or "")
        assert result.next_steps == []

    @pytest.mark.parametrize("bad_branch", [{"id": "x"}, "oops", 5])
    def test_execute_non_list_else_fails_loudly(self, bad_branch):
        """A non-list ``else`` selected at runtime must fail the step, not crash.

        Same asymmetry as ``then``: the ``else`` branch is only reached when the
        condition is false, so a non-list ``else`` reaches ``next_steps`` and
        would crash the engine's step iteration on an unvalidated run.
        """
        from specify_cli.workflows.step.if_then import IfThenStep
        from specify_cli.workflows.base import StepContext, StepStatus

        step = IfThenStep()
        ctx = StepContext(inputs={})
        result = step.execute(
            {"id": "branch", "condition": "false", "then": [], "else": bad_branch},
            ctx,
        )
        assert result.status == StepStatus.FAILED
        assert "'else' must be a list of steps" in (result.error or "")
        assert result.next_steps == []

    def test_execute_none_else_stays_empty(self):
        """An explicit ``else: null`` selected at runtime stays an empty branch.

        ``validate`` deliberately accepts ``else: None``; the execute guard must
        normalize it to an empty branch (COMPLETED) rather than failing a
        validator-approved workflow when the condition is false.
        """
        from specify_cli.workflows.step.if_then import IfThenStep
        from specify_cli.workflows.base import StepContext, StepStatus

        step = IfThenStep()
        ctx = StepContext(inputs={})
        result = step.execute(
            {"id": "branch", "condition": "false", "then": [], "else": None}, ctx
        )
        assert result.status == StepStatus.COMPLETED
        assert result.next_steps == []

    @pytest.mark.parametrize("bad_else", [False, 0, "", {}, 42])
    def test_validate_rejects_non_list_else(self, bad_else):
        """A non-list 'else' must be rejected even when it is falsy.

        The original guard used ``if else_branch and ...`` which
        short-circuits for falsy non-list values (False/0/''/{}), letting a
        malformed else-branch pass validation only to be silently skipped at
        runtime. ``then`` is already strictly validated; ``else`` must match.
        """
        from specify_cli.workflows.step.if_then import IfThenStep

        step = IfThenStep()
        errors = step.validate(
            {"id": "i", "condition": "true", "then": [], "else": bad_else}
        )
        assert any("'else' must be a list of steps" in e for e in errors)

    @pytest.mark.parametrize("ok_else", [None, [], [{"id": "x", "command": "/y"}]])
    def test_validate_accepts_valid_else(self, ok_else):
        """An explicit 'else' of None or a list stays valid.

        ``else`` is set explicitly here (including ``else: None``) so the
        explicit-None case is exercised, not just the missing-key case.
        """
        from specify_cli.workflows.step.if_then import IfThenStep

        step = IfThenStep()
        errors = step.validate(
            {"id": "i", "condition": "true", "then": [], "else": ok_else}
        )
        assert not any("'else'" in e for e in errors)

    def test_validate_accepts_missing_else(self):
        """A missing 'else' key stays valid (no else branch)."""
        from specify_cli.workflows.step.if_then import IfThenStep

        step = IfThenStep()
        errors = step.validate({"id": "i", "condition": "true", "then": []})
        assert not any("'else'" in e for e in errors)


class TestSwitchStep:
    """Test the switch step type."""

    def test_execute_matches_case_ignoring_surrounding_whitespace(self):
        """A shell step's stdout keeps its trailing newline; the case must match.

        `ShellStep` stores `proc.stdout` verbatim, so `run: echo approve`
        resolves to "approve" plus a newline. Unstripped, that matched no
        `approve:` case and the switch silently fell through to `default:`
        while still reporting COMPLETED. There is no `trim` filter, so a
        workflow author cannot strip it themselves.
        """
        from specify_cli.workflows.step.switch import SwitchStep
        from specify_cli.workflows.base import StepContext, StepStatus

        config = {
            "id": "route",
            "expression": "{{ steps.check.output.stdout }}",
            "cases": {
                "approve": [{"id": "approved", "type": "command", "command": "echo"}],
                "reject": [{"id": "rejected", "type": "command", "command": "echo"}],
            },
            "default": [{"id": "fallback", "type": "command", "command": "echo"}],
        }
        for raw in ("approve\n", "approve\r\n", "  approve  ", "approve"):
            ctx = StepContext(steps={"check": {"output": {"stdout": raw}}})
            result = SwitchStep().execute(config, ctx)
            assert result.status == StepStatus.COMPLETED
            assert result.output["matched_case"] == "approve", repr(raw)
            assert [s["id"] for s in result.next_steps] == ["approved"], repr(raw)
            # The raw value is still reported unchanged.
            assert result.output["expression_value"] == raw

    def test_execute_still_falls_through_for_a_genuine_mismatch(self):
        """Stripping must not make unrelated values match."""
        from specify_cli.workflows.step.switch import SwitchStep
        from specify_cli.workflows.base import StepContext

        config = {
            "id": "route",
            "expression": "{{ steps.check.output.stdout }}",
            "cases": {
                "approve": [{"id": "approved", "type": "command", "command": "echo"}]
            },
            "default": [{"id": "fallback", "type": "command", "command": "echo"}],
        }
        ctx = StepContext(steps={"check": {"output": {"stdout": "approve-later\n"}}})
        result = SwitchStep().execute(config, ctx)

        assert result.output["matched_case"] == "__default__"
        assert [s["id"] for s in result.next_steps] == ["fallback"]

    def test_execute_matches_case(self):
        from specify_cli.workflows.step.switch import SwitchStep
        from specify_cli.workflows.base import StepContext

        step = SwitchStep()
        ctx = StepContext(
            steps={"review": {"output": {"choice": "approve"}}}
        )
        config = {
            "id": "route",
            "expression": "{{ steps.review.output.choice }}",
            "cases": {
                "approve": [{"id": "plan", "command": "speckit.plan"}],
                "reject": [{"id": "log", "type": "shell", "run": "echo rejected"}],
            },
            "default": [{"id": "abort", "type": "gate", "message": "Unknown"}],
        }
        result = step.execute(config, ctx)
        assert result.output["matched_case"] == "approve"
        assert result.next_steps[0]["id"] == "plan"

    def test_execute_falls_to_default(self):
        from specify_cli.workflows.step.switch import SwitchStep
        from specify_cli.workflows.base import StepContext

        step = SwitchStep()
        ctx = StepContext(
            steps={"review": {"output": {"choice": "unknown"}}}
        )
        config = {
            "id": "route",
            "expression": "{{ steps.review.output.choice }}",
            "cases": {
                "approve": [{"id": "plan", "command": "speckit.plan"}],
            },
            "default": [{"id": "fallback", "type": "gate", "message": "Fallback"}],
        }
        result = step.execute(config, ctx)
        assert result.output["matched_case"] == "__default__"
        assert result.next_steps[0]["id"] == "fallback"

    def test_execute_no_default_no_match(self):
        from specify_cli.workflows.step.switch import SwitchStep
        from specify_cli.workflows.base import StepContext

        step = SwitchStep()
        ctx = StepContext(
            steps={"review": {"output": {"choice": "other"}}}
        )
        config = {
            "id": "route",
            "expression": "{{ steps.review.output.choice }}",
            "cases": {
                "approve": [{"id": "plan", "command": "speckit.plan"}],
            },
        }
        result = step.execute(config, ctx)
        assert result.output["matched_case"] == "__default__"
        assert result.next_steps == []

    def test_execute_non_dict_cases_fails_loudly(self):
        """A non-mapping ``cases`` must fail the step, not crash the run.

        ``validate`` rejects a non-dict ``cases``, but the engine's
        ``execute()`` does not auto-validate (see ``WorkflowEngine.load_workflow``
        docstring). Before the guard, ``execute`` called ``cases.items()`` on the
        raw value, so an unvalidated run with a list/scalar ``cases`` raised
        AttributeError and took down the whole run instead of failing this step.
        Mirrors the fan-out step's non-list ``items`` handling.
        """
        from specify_cli.workflows.step.switch import SwitchStep
        from specify_cli.workflows.base import StepContext, StepStatus

        step = SwitchStep()
        ctx = StepContext(steps={"review": {"output": {"choice": "approve"}}})
        for bad_cases in (["approve"], "approve", 5):
            result = step.execute(
                {
                    "id": "route",
                    "expression": "{{ steps.review.output.choice }}",
                    "cases": bad_cases,
                },
                ctx,
            )
            assert result.status == StepStatus.FAILED
            assert "'cases' must be a mapping" in (result.error or "")
            # expression is still evaluated, so its value is surfaced for context.
            assert result.output["expression_value"] == "approve"

    @pytest.mark.parametrize("bad_branch", [{"id": "x"}, "oops", 5])
    def test_execute_non_list_matched_case_fails_loudly(self, bad_branch):
        """A matched case with a non-list body must fail the step, not crash.

        ``validate`` rejects a non-list case body, but the engine does not
        auto-validate (see ``WorkflowEngine.load_workflow``) and feeds the
        selected branch straight into ``_execute_steps``, which iterates it as
        step mappings. A non-list body (a single mapping or scalar authoring
        mistake) would be iterated element-wise and raise AttributeError on
        ``.get()``, taking down the whole run. Mirrors the non-mapping
        ``cases`` guard.
        """
        from specify_cli.workflows.step.switch import SwitchStep
        from specify_cli.workflows.base import StepContext, StepStatus

        step = SwitchStep()
        ctx = StepContext(steps={"review": {"output": {"choice": "approve"}}})
        result = step.execute(
            {
                "id": "route",
                "expression": "{{ steps.review.output.choice }}",
                "cases": {"approve": bad_branch},
            },
            ctx,
        )
        assert result.status == StepStatus.FAILED
        assert "case 'approve' must be a list of steps" in (result.error or "")
        assert result.next_steps == []
        # expression is still evaluated, so its value is surfaced for context.
        assert result.output["expression_value"] == "approve"

    @pytest.mark.parametrize("bad_branch", [{"id": "x"}, "oops", 5])
    def test_execute_non_list_default_fails_loudly(self, bad_branch):
        """A non-list ``default`` reached at runtime must fail, not crash.

        Same asymmetry as the case body: ``default`` is only selected when no
        case matches, so a non-list ``default`` reaches ``next_steps`` and would
        crash the engine's step iteration on an unvalidated run.
        """
        from specify_cli.workflows.step.switch import SwitchStep
        from specify_cli.workflows.base import StepContext, StepStatus

        step = SwitchStep()
        ctx = StepContext(steps={"review": {"output": {"choice": "other"}}})
        result = step.execute(
            {
                "id": "route",
                "expression": "{{ steps.review.output.choice }}",
                "cases": {"approve": [{"id": "plan", "command": "speckit.plan"}]},
                "default": bad_branch,
            },
            ctx,
        )
        assert result.status == StepStatus.FAILED
        assert "'default' must be a list of steps" in (result.error or "")
        assert result.next_steps == []
        # expression is still evaluated, so its value is surfaced for context.
        assert result.output["expression_value"] == "other"

    @pytest.mark.parametrize("ok_default", [None, [], [{"id": "x", "command": "/y"}]])
    def test_execute_none_default_stays_empty(self, ok_default):
        """An explicit ``default: null`` or a list default stays valid.

        ``validate`` deliberately accepts ``default: None``; the execute guard
        must normalize it to an empty branch (COMPLETED) rather than failing a
        validator-approved workflow.
        """
        from specify_cli.workflows.step.switch import SwitchStep
        from specify_cli.workflows.base import StepContext, StepStatus

        step = SwitchStep()
        ctx = StepContext(steps={"review": {"output": {"choice": "other"}}})
        result = step.execute(
            {
                "id": "route",
                "expression": "{{ steps.review.output.choice }}",
                "cases": {"approve": [{"id": "plan", "command": "speckit.plan"}]},
                "default": ok_default,
            },
            ctx,
        )
        assert result.status == StepStatus.COMPLETED
        assert result.output["matched_case"] == "__default__"
        assert result.next_steps == (ok_default or [])

    def test_validate_missing_expression(self):
        from specify_cli.workflows.step.switch import SwitchStep

        step = SwitchStep()
        errors = step.validate({"id": "test", "cases": {}})
        assert any("missing 'expression'" in e for e in errors)

    def test_validate_missing_cases(self):
        """`cases` is the switch's branch payload and must be required.

        Every other control-flow step requires its own: `if` requires `then`,
        `fan-out` requires `items` and `step`, `fan-in` a non-empty `wait_for`,
        `gate` a `message`. Without it, a `case:` typo validated clean and then
        reported COMPLETED with `matched_case: "__default__"` having dispatched
        nothing.
        """
        from specify_cli.workflows.step.switch import SwitchStep

        step = SwitchStep()

        # Absent entirely.
        errors = step.validate({"id": "route", "expression": "{{ inputs.x }}"})
        assert any("missing 'cases'" in e for e in errors), errors

        # The realistic slip: `case:` instead of `cases:`.
        errors = step.validate(
            {"id": "route", "expression": "{{ inputs.x }}", "case": {"a": []}}
        )
        assert any("missing 'cases'" in e for e in errors), errors

    def test_validate_accepts_an_empty_cases_mapping(self):
        """An explicitly declared but empty `cases:` is still a declaration."""
        from specify_cli.workflows.step.switch import SwitchStep

        errors = SwitchStep().validate(
            {"id": "route", "expression": "{{ inputs.x }}", "cases": {}}
        )
        assert not any("missing 'cases'" in e for e in errors), errors

    def test_validate_invalid_cases_and_default(self):
        from specify_cli.workflows.step.switch import SwitchStep

        step = SwitchStep()
        errors = step.validate({
            "id": "test",
            "expression": "{{ x }}",
            "cases": {"a": "not-a-list"},
            "default": "also-bad",
        })
        assert any("case 'a' must be a list" in e for e in errors)
        assert any("'default' must be a list" in e for e in errors)


class TestWhileStep:
    """Test the while loop step type."""

    def test_execute_condition_true(self):
        from specify_cli.workflows.step.while_loop import WhileStep
        from specify_cli.workflows.base import StepContext

        step = WhileStep()
        ctx = StepContext(
            steps={"run-tests": {"output": {"exit_code": 1}}}
        )
        config = {
            "id": "retry",
            "condition": "{{ steps.run-tests.output.exit_code != 0 }}",
            "max_iterations": 5,
            "steps": [{"id": "fix", "command": "speckit.implement"}],
        }
        result = step.execute(config, ctx)
        assert result.output["condition_result"] is True
        assert len(result.next_steps) == 1

    def test_execute_condition_false(self):
        from specify_cli.workflows.step.while_loop import WhileStep
        from specify_cli.workflows.base import StepContext

        step = WhileStep()
        ctx = StepContext(
            steps={"run-tests": {"output": {"exit_code": 0}}}
        )
        config = {
            "id": "retry",
            "condition": "{{ steps.run-tests.output.exit_code != 0 }}",
            "max_iterations": 5,
            "steps": [{"id": "fix", "command": "speckit.implement"}],
        }
        result = step.execute(config, ctx)
        assert result.output["condition_result"] is False
        assert result.next_steps == []

    @pytest.mark.parametrize("bad_steps", [{"id": "x"}, "oops", 5])
    def test_execute_non_list_steps_fails_loudly(self, bad_steps):
        """A non-list ``steps`` reached at runtime must fail the step, not crash.

        ``validate`` rejects a non-list ``steps``, but the engine does not
        auto-validate (see ``WorkflowEngine.load_workflow``) and feeds
        ``next_steps`` straight into ``_execute_steps``, which iterates them as
        step mappings. The while body only dispatches when the condition is
        truthy, so a non-list ``steps`` reaches ``next_steps`` and would crash
        the engine's step iteration on an unvalidated run. Mirrors the
        if/switch/fan-out non-list handling.
        """
        from specify_cli.workflows.step.while_loop import WhileStep
        from specify_cli.workflows.base import StepContext, StepStatus

        step = WhileStep()
        ctx = StepContext(inputs={})
        result = step.execute(
            {"id": "retry", "condition": "true", "steps": bad_steps}, ctx
        )
        assert result.status == StepStatus.FAILED
        assert "'steps' must be a list of steps" in (result.error or "")
        assert result.next_steps == []

    @pytest.mark.parametrize("bad_steps", [{"id": "x"}, "oops", 5])
    def test_execute_non_list_steps_ok_when_condition_false(self, bad_steps):
        """A false condition never dispatches the body, so a non-list ``steps``
        stays benign — the step completes without touching ``next_steps``.
        """
        from specify_cli.workflows.step.while_loop import WhileStep
        from specify_cli.workflows.base import StepContext, StepStatus

        step = WhileStep()
        ctx = StepContext(inputs={})
        result = step.execute(
            {"id": "retry", "condition": "false", "steps": bad_steps}, ctx
        )
        assert result.status == StepStatus.COMPLETED
        assert result.output["condition_result"] is False
        assert result.next_steps == []

    def test_validate_missing_fields(self):
        from specify_cli.workflows.step.while_loop import WhileStep

        step = WhileStep()
        errors = step.validate({"id": "test", "steps": []})
        assert any("missing 'condition'" in e for e in errors)
        # max_iterations is optional (defaults to 10)

    def test_validate_requires_steps_body(self):
        """A while loop with no body must be rejected, not silently a no-op.

        Without this, ``step:`` written instead of ``steps:`` -- an easy slip,
        since fan-out's payload key really is the singular ``step:`` -- passed
        ``specify workflow validate`` with zero errors, and then reported
        COMPLETED at run time while returning no ``next_steps``, so the loop
        never ran even once.
        """
        from specify_cli.workflows.base import StepContext, StepStatus
        from specify_cli.workflows.step.while_loop import WhileStep

        step = WhileStep()
        config = {
            "id": "retry",
            "condition": "true",
            # The mistype: singular 'step' instead of 'steps'.
            "step": {"id": "x", "type": "command", "command": "echo"},
        }
        errors = step.validate(config)
        assert errors == ["While step 'retry' is missing 'steps' field."], errors

        # Demonstrates why it matters: execution is a silent no-op.
        result = step.execute(config, StepContext())
        assert result.status == StepStatus.COMPLETED
        assert result.next_steps == []

    @pytest.mark.parametrize("bad", [["a", "b"], {"k": "v"}, 5, 1.5])
    def test_validate_rejects_non_string_non_bool_condition(self, bad):
        from specify_cli.workflows.step.while_loop import WhileStep

        step = WhileStep()
        errors = step.validate({"id": "test", "condition": bad, "steps": []})
        assert any("'condition' must be a" in e for e in errors), bad

    @pytest.mark.parametrize("good", [True, False, "true", "{{ inputs.go }}"])
    def test_validate_accepts_string_or_bool_condition(self, good):
        # ``condition: false`` unquoted is idiomatic YAML and is this step's own
        # default, so a literal bool must not be rejected.
        from specify_cli.workflows.step.while_loop import WhileStep

        step = WhileStep()
        errors = step.validate({"id": "test", "condition": good, "steps": []})
        assert not any("'condition' must be a" in e for e in errors), good

    def test_validate_invalid_max_iterations(self):
        from specify_cli.workflows.step.while_loop import WhileStep

        step = WhileStep()
        errors = step.validate({"id": "test", "condition": "{{ true }}", "max_iterations": 0, "steps": []})
        assert any("must be an integer >= 1" in e for e in errors)
        # bool is an int subclass; `max_iterations: true` must be rejected, not
        # silently treated as a single iteration.
        bool_errors = step.validate(
            {"id": "test", "condition": "{{ true }}", "max_iterations": True, "steps": []}
        )
        assert any("must be an integer >= 1" in e for e in bool_errors)


class TestDoWhileStep:
    """Test the do-while loop step type."""

    def test_execute_always_runs_once(self):
        from specify_cli.workflows.step.do_while import DoWhileStep
        from specify_cli.workflows.base import StepContext

        step = DoWhileStep()
        ctx = StepContext()
        config = {
            "id": "cycle",
            "condition": "{{ false }}",
            "max_iterations": 3,
            "steps": [{"id": "refine", "command": "speckit.specify"}],
        }
        result = step.execute(config, ctx)
        assert len(result.next_steps) == 1
        assert result.output["loop_type"] == "do-while"
        assert result.output["condition"] == "{{ false }}"

    def test_execute_with_true_condition(self):
        from specify_cli.workflows.step.do_while import DoWhileStep
        from specify_cli.workflows.base import StepContext

        step = DoWhileStep()
        ctx = StepContext()
        config = {
            "id": "cycle",
            "condition": "{{ true }}",
            "max_iterations": 5,
            "steps": [{"id": "work", "command": "speckit.plan"}],
        }
        result = step.execute(config, ctx)
        # Body always executes on first call regardless of condition
        assert len(result.next_steps) == 1
        assert result.output["max_iterations"] == 5

    def test_validate_rejects_bool_max_iterations(self):
        from specify_cli.workflows.step.do_while import DoWhileStep

        step = DoWhileStep()
        # bool is an int subclass; `max_iterations: true` must be rejected.
        errors = step.validate(
            {"id": "test", "condition": "{{ true }}", "max_iterations": True, "steps": []}
        )
        assert any("must be an integer >= 1" in e for e in errors)
        # a real positive integer is fully valid (no errors at all).
        ok = step.validate(
            {"id": "test", "condition": "{{ true }}", "max_iterations": 3, "steps": []}
        )
        assert ok == [], ok

    def test_execute_empty_steps(self):
        from specify_cli.workflows.step.do_while import DoWhileStep
        from specify_cli.workflows.base import StepContext

        step = DoWhileStep()
        ctx = StepContext()
        config = {
            "id": "empty",
            "condition": "{{ false }}",
            "max_iterations": 1,
            "steps": [],
        }
        result = step.execute(config, ctx)
        assert result.next_steps == []
        assert result.status.value == "completed"

    @pytest.mark.parametrize("bad_steps", [{"id": "x"}, "oops", 5])
    def test_execute_non_list_steps_fails_loudly(self, bad_steps):
        """A non-list ``steps`` must fail the step, not crash the run.

        ``validate`` rejects a non-list ``steps``, but the engine does not
        auto-validate (see ``WorkflowEngine.load_workflow``) and feeds
        ``next_steps`` straight into ``_execute_steps``, which iterates them as
        step mappings. The do-while body always dispatches on the first call
        regardless of condition, so a non-list ``steps`` always reaches
        ``next_steps`` and would crash the engine's step iteration on an
        unvalidated run. Mirrors the if/switch/fan-out non-list handling.
        """
        from specify_cli.workflows.step.do_while import DoWhileStep
        from specify_cli.workflows.base import StepContext, StepStatus

        step = DoWhileStep()
        ctx = StepContext(inputs={})
        result = step.execute(
            {"id": "cycle", "condition": "false", "steps": bad_steps}, ctx
        )
        assert result.status == StepStatus.FAILED
        assert "'steps' must be a list of steps" in (result.error or "")
        assert result.next_steps == []

    def test_validate_missing_fields(self):
        from specify_cli.workflows.step.do_while import DoWhileStep

        step = DoWhileStep()
        errors = step.validate({"id": "test", "steps": []})
        assert any("missing 'condition'" in e for e in errors)
        # max_iterations is optional (defaults to 10)

    def test_validate_requires_steps_body(self):
        """A do-while with no body must be rejected, not silently a no-op.

        The step's own docstring promises "The first invocation always returns
        the nested steps for execution" -- with no body it validated clean and
        then returned none, so the loop never ran even once.
        """
        from specify_cli.workflows.base import StepContext, StepStatus
        from specify_cli.workflows.step.do_while import DoWhileStep

        step = DoWhileStep()
        config = {"id": "refine", "condition": "true", "max_iterations": 3}
        errors = step.validate(config)
        assert errors == ["Do-while step 'refine' is missing 'steps' field."], errors

        result = step.execute(config, StepContext())
        assert result.status == StepStatus.COMPLETED
        assert result.next_steps == []

    @pytest.mark.parametrize("bad", [["a", "b"], {"k": "v"}, 5, 1.5])
    def test_validate_rejects_non_string_non_bool_condition(self, bad):
        from specify_cli.workflows.step.do_while import DoWhileStep

        step = DoWhileStep()
        errors = step.validate({"id": "test", "condition": bad, "steps": []})
        assert any("'condition' must be a" in e for e in errors), bad

    @pytest.mark.parametrize("good", [True, False, "true", "{{ inputs.go }}"])
    def test_validate_accepts_string_or_bool_condition(self, good):
        # ``condition: false`` unquoted is idiomatic YAML; evaluate_condition
        # resolves a literal bool exactly, so it must not be rejected.
        from specify_cli.workflows.step.do_while import DoWhileStep

        step = DoWhileStep()
        errors = step.validate({"id": "test", "condition": good, "steps": []})
        assert not any("'condition' must be a" in e for e in errors), good

    def test_validate_steps_not_list(self):
        from specify_cli.workflows.step.do_while import DoWhileStep

        step = DoWhileStep()
        errors = step.validate({
            "id": "test",
            "condition": "{{ true }}",
            "max_iterations": 3,
            "steps": "not-a-list",
        })
        assert any("'steps' must be a list" in e for e in errors)


class TestFanOutStep:
    """Test the fan-out step type."""

    def test_execute_with_items(self):
        from specify_cli.workflows.step.fan_out import FanOutStep
        from specify_cli.workflows.base import StepContext

        step = FanOutStep()
        ctx = StepContext(
            steps={"tasks": {"output": {"task_list": [
                {"file": "a.md"},
                {"file": "b.md"},
            ]}}}
        )
        config = {
            "id": "parallel",
            "items": "{{ steps.tasks.output.task_list }}",
            "max_concurrency": 3,
            "step": {"id": "impl", "command": "speckit.implement"},
        }
        result = step.execute(config, ctx)
        assert result.output["item_count"] == 2
        assert result.output["max_concurrency"] == 3

    def test_execute_non_list_items_fails_loudly(self):
        from specify_cli.workflows.step.fan_out import FanOutStep
        from specify_cli.workflows.base import StepContext, StepStatus

        step = FanOutStep()
        ctx = StepContext()
        config = {
            "id": "parallel",
            "items": "{{ undefined_var }}",
            "step": {"id": "impl", "command": "speckit.implement"},
        }
        result = step.execute(config, ctx)
        assert result.status == StepStatus.FAILED
        assert "'items' must resolve to a list" in (result.error or "")
        assert result.output["item_count"] == 0

    def test_execute_empty_list_items_is_valid(self):
        from specify_cli.workflows.step.fan_out import FanOutStep
        from specify_cli.workflows.base import StepContext, StepStatus

        step = FanOutStep()
        ctx = StepContext(steps={"tasks": {"output": {"task_list": []}}})
        config = {
            "id": "parallel",
            "items": "{{ steps.tasks.output.task_list }}",
            "step": {"id": "impl", "command": "speckit.implement"},
        }
        result = step.execute(config, ctx)
        assert result.status == StepStatus.COMPLETED
        assert result.output["item_count"] == 0

    def test_execute_non_dict_step_fails_loudly(self):
        """A truthy non-mapping ``step`` must fail the step, not crash the run.

        ``validate`` rejects a non-dict ``step``, but the engine's ``execute()``
        does not auto-validate (see ``WorkflowEngine.load_workflow``). On a
        COMPLETED fan-out the engine reads ``step_template`` back out and, when
        it is truthy, calls ``template.get("id", ...)`` while expanding items. A
        truthy non-mapping ``step`` (a scalar or list authoring mistake) raised
        AttributeError there and took down the whole run. Mirrors the fan-out
        non-list ``items`` guard and the switch non-dict ``cases`` guard.
        """
        from specify_cli.workflows.step.fan_out import FanOutStep
        from specify_cli.workflows.base import StepContext, StepStatus

        step = FanOutStep()
        ctx = StepContext(steps={"tasks": {"output": {"task_list": [1, 2]}}})
        # ``None`` is an explicit ``step: null``: ``config.get("step", {})`` only
        # substitutes the default for an *absent* key, so it reaches the guard
        # and must fail here too — matching ``validate``.
        for bad_step in (["impl"], "impl", 5, None):
            result = step.execute(
                {
                    "id": "parallel",
                    "items": "{{ steps.tasks.output.task_list }}",
                    "step": bad_step,
                },
                ctx,
            )
            assert result.status == StepStatus.FAILED
            assert "'step' must be a" in (result.error or "")
            assert result.output["item_count"] == 0
            assert result.output["step_template"] == {}

    def test_validate_missing_fields(self):
        from specify_cli.workflows.step.fan_out import FanOutStep

        step = FanOutStep()
        errors = step.validate({"id": "test"})
        assert any("missing 'items'" in e for e in errors)
        assert any("missing 'step'" in e for e in errors)

    def test_validate_step_not_mapping(self):
        from specify_cli.workflows.step.fan_out import FanOutStep

        step = FanOutStep()
        for bad_step in ("not-a-dict", ["impl"], 5, None):
            errors = step.validate({
                "id": "test",
                "items": "{{ x }}",
                "step": bad_step,
            })
            assert any("'step' must be a mapping" in e for e in errors), bad_step


class TestFanInStep:
    """Test the fan-in step type."""

    def test_execute_collects_results(self):
        from specify_cli.workflows.step.fan_in import FanInStep
        from specify_cli.workflows.base import StepContext

        step = FanInStep()
        ctx = StepContext(
            steps={
                "parallel": {"output": {"item_count": 2, "status": "done"}}
            }
        )
        config = {
            "id": "collect",
            "wait_for": ["parallel"],
            "output": {},
        }
        result = step.execute(config, ctx)
        assert len(result.output["results"]) == 1
        assert result.output["results"][0]["item_count"] == 2

    def test_execute_multiple_wait_for(self):
        from specify_cli.workflows.step.fan_in import FanInStep
        from specify_cli.workflows.base import StepContext

        step = FanInStep()
        ctx = StepContext(
            steps={
                "task-a": {"output": {"file": "a.md"}},
                "task-b": {"output": {"file": "b.md"}},
            }
        )
        config = {
            "id": "collect",
            "wait_for": ["task-a", "task-b"],
            "output": {},
        }
        result = step.execute(config, ctx)
        assert len(result.output["results"]) == 2
        assert result.output["results"][0]["file"] == "a.md"
        assert result.output["results"][1]["file"] == "b.md"

    def test_execute_missing_wait_for_step(self):
        from specify_cli.workflows.step.fan_in import FanInStep
        from specify_cli.workflows.base import StepContext

        step = FanInStep()
        ctx = StepContext(steps={})
        config = {
            "id": "collect",
            "wait_for": ["nonexistent"],
            "output": {},
        }
        result = step.execute(config, ctx)
        assert result.output["results"] == [{}]

    @pytest.mark.parametrize("bad_wait_for", ["stepA", 5, None, {"a": 1}])
    def test_execute_non_list_wait_for_fails_loudly(self, bad_wait_for):
        """A non-list ``wait_for`` must fail the step, not crash the run or
        silently produce a bogus join.

        ``validate`` rejects a non-list ``wait_for``, but the engine's
        ``execute()`` does not auto-validate. Before the guard, ``execute``
        iterated the raw value: a scalar (int/None) raised TypeError and took
        down the whole run, while a string silently iterated its characters and
        returned a join of empty results with a COMPLETED status — the exact
        "silent empty result + COMPLETED" wiring bug the engine's fan-in
        validation warns against. Mirrors the fan-out non-list ``items`` guard.
        """
        from specify_cli.workflows.step.fan_in import FanInStep
        from specify_cli.workflows.base import StepContext, StepStatus

        step = FanInStep()
        ctx = StepContext(steps={"a": {"output": {"x": 1}}})
        result = step.execute({"id": "collect", "wait_for": bad_wait_for}, ctx)
        assert result.status == StepStatus.FAILED
        assert "'wait_for' must be a list" in (result.error or "")
        assert result.output["results"] == []

    @pytest.mark.parametrize(
        "bad_output", [[], False, 0, "", ["a"], "oops", 5]
    )
    def test_execute_non_mapping_output_fails_loudly(self, bad_output):
        """A non-mapping ``output`` must fail the step, not drop every key.

        ``validate`` rejects it and says why: "execute() silently coerces a
        non-mapping output to {}, so the author's declared aggregation keys would
        vanish with no error." The engine does not auto-validate before
        ``execute``, so that is exactly what happened — and ``x or {}`` masked
        the falsy shapes (``[]``, ``false``, ``0``, ``''``) before the isinstance
        check even ran. The step still returned COMPLETED, so downstream
        ``steps.<id>.output.<key>`` resolved to None and interpolated as "".
        """
        from specify_cli.workflows.step.fan_in import FanInStep
        from specify_cli.workflows.base import StepContext, StepStatus

        step = FanInStep()
        ctx = StepContext(steps={"a": {"output": {"x": 1}}})
        result = step.execute(
            {"id": "collect", "wait_for": ["a"], "output": bad_output}, ctx
        )
        assert result.status == StepStatus.FAILED
        assert "'output' must be a mapping" in (result.error or "")
        assert result.output["results"] == []

    def test_execute_explicit_null_output_stays_valid(self):
        """An explicit ``output:`` (YAML null) is valid, matching ``validate``."""
        from specify_cli.workflows.step.fan_in import FanInStep
        from specify_cli.workflows.base import StepContext, StepStatus

        step = FanInStep()
        ctx = StepContext(steps={"a": {"output": {"x": 1}}})
        result = step.execute(
            {"id": "collect", "wait_for": ["a"], "output": None}, ctx
        )
        assert result.status == StepStatus.COMPLETED

    @pytest.mark.parametrize("bad_entry", [["a", "b"], {"a": 1}, 123, None])
    def test_execute_non_string_wait_for_entry_fails_loudly(self, bad_entry):
        """A ``wait_for`` list with a non-string entry must fail the step, not
        crash the run or silently produce a bogus join.

        The whole-list guard (``test_execute_non_list_wait_for_fails_loudly``)
        and the engine's fan-in validation both already reject the list *shape*,
        but neither the step's ``execute`` nor the engine's runtime path guarded
        the list's *elements*. On an unvalidated run an unhashable entry
        (a list/dict from a YAML indentation slip like ``wait_for: [[a, b]]``)
        crashed ``context.steps.get(entry, ...)`` with a raw TypeError, while a
        hashable-but-non-string entry (``wait_for: [123]``) silently joined an
        empty ``{}`` and still reported COMPLETED — the same wiring bug the
        list-shape guard exists to prevent. Mirrors the engine's
        ``test_non_string_wait_for_entry_is_rejected`` load-time check.
        """
        from specify_cli.workflows.step.fan_in import FanInStep
        from specify_cli.workflows.base import StepContext, StepStatus

        step = FanInStep()
        ctx = StepContext(steps={"a": {"output": {"x": 1}}})
        # A valid entry alongside the bad one proves it is the entry, not the
        # list, that is rejected.
        result = step.execute({"id": "collect", "wait_for": ["a", bad_entry]}, ctx)
        assert result.status == StepStatus.FAILED
        assert "'wait_for' entries must be step-id strings" in (result.error or "")
        assert result.output["results"] == []

    def test_validate_empty_wait_for(self):
        from specify_cli.workflows.step.fan_in import FanInStep

        step = FanInStep()
        errors = step.validate({"id": "test", "wait_for": []})
        assert any("non-empty list" in e for e in errors)

    def test_validate_wait_for_not_list(self):
        from specify_cli.workflows.step.fan_in import FanInStep

        step = FanInStep()
        errors = step.validate({"id": "test", "wait_for": "not-a-list"})
        assert any("non-empty list" in e for e in errors)

    @pytest.mark.parametrize("bad_output", [["{{ fan_in.results }}"], "{{ x }}", 42])
    def test_validate_rejects_non_mapping_output(self, bad_output):
        """A non-mapping 'output' must be rejected: execute() would otherwise
        silently coerce it to {} and drop the declared aggregation keys."""
        from specify_cli.workflows.step.fan_in import FanInStep

        step = FanInStep()
        errors = step.validate(
            {"id": "j", "wait_for": ["a"], "output": bad_output}
        )
        assert any("'output' must be a mapping" in e for e in errors)

    def test_validate_accepts_mapping_or_absent_output(self):
        from specify_cli.workflows.step.fan_in import FanInStep

        step = FanInStep()
        assert step.validate(
            {"id": "j", "wait_for": ["a"], "output": {"joined": "{{ x }}"}}
        ) == []
        assert step.validate({"id": "j", "wait_for": ["a"]}) == []


class TestFanOutConcurrency:
    """Fan-out honors max_concurrency through WorkflowEngine.execute()."""

    @staticmethod
    def _run(
        tmp_path, monkeypatch, items, max_concurrency, on_item=None, template=None
    ):
        """Run a public fan-out workflow with a probe that echoes ``context.item``."""
        from specify_cli.workflows import STEP_REGISTRY
        from specify_cli.workflows.base import StepBase, StepResult, StepStatus
        from specify_cli.workflows.engine import WorkflowDefinition, WorkflowEngine

        class _ProbeStep(StepBase):
            type_key = "probe"

            def execute(self, config, context):
                status = StepStatus.COMPLETED
                if on_item is not None:
                    override = on_item(context.item)
                    if override is not None:
                        status = override
                return StepResult(status=status, output={"seen": context.item})

        monkeypatch.setitem(STEP_REGISTRY, "probe", _ProbeStep())
        template = template or {"id": "impl", "type": "probe"}
        state = WorkflowEngine(tmp_path).execute(
            WorkflowDefinition(
                {
                    "workflow": {"id": "fan-out-test", "name": "Fan-out Test"},
                    "steps": [
                        {
                            "id": "fan",
                            "type": "fan-out",
                            "items": items,
                            "max_concurrency": max_concurrency,
                            "step": template,
                        }
                    ],
                }
            )
        )
        return state.step_results["fan"]["output"]["results"], state

    def test_sequential_default_preserves_order(self, tmp_path, monkeypatch):
        results, _ = self._run(tmp_path, monkeypatch, list(range(5)), 1)
        assert results == [{"seen": i} for i in range(5)]

    def test_concurrent_runs_all_items_in_item_order(self, tmp_path, monkeypatch):
        results, _ = self._run(tmp_path, monkeypatch, list(range(10)), 4)
        assert results == [{"seen": i} for i in range(10)]

    def test_sequential_and_concurrent_agree(self, tmp_path, monkeypatch):
        items = [{"n": i} for i in range(8)]
        seq, _ = self._run(tmp_path, monkeypatch, items, 1)
        con, _ = self._run(tmp_path, monkeypatch, items, 4)
        assert seq == con == [{"seen": {"n": i}} for i in range(8)]

    def test_shuffled_completion_preserves_item_order(self, tmp_path, monkeypatch):
        # Determinism keystone: completion order is forced to the exact REVERSE of
        # item order by an event chain (no sleeps) — item i blocks until item i+1
        # has finished, so item 0 completes LAST — yet results must still be in
        # item order. K == len(items) so all workers are in flight together.
        import threading

        n = 4
        done = [threading.Event() for _ in range(n)]
        completion: list[int] = []
        clock = threading.Lock()

        def on_item(item):
            if item + 1 < n:
                assert done[item + 1].wait(2.0), f"item {item + 1} never finished"
            with clock:
                completion.append(item)
            done[item].set()
            return None

        results, _ = self._run(tmp_path, monkeypatch, list(range(n)), n, on_item)
        assert results == [{"seen": i} for i in range(n)]
        assert completion == list(reversed(range(n)))

    def test_concurrency_is_real(self, tmp_path, monkeypatch):
        import threading

        # Deterministic proof of real parallelism (no wall-clock threshold to
        # tune or flake): every item must reach the barrier before any may pass.
        # Sequential execution would block the first item forever — the barrier
        # times out, raises BrokenBarrierError, and fails the test.
        n = 4
        barrier = threading.Barrier(n, timeout=5)

        def on_item(item):
            barrier.wait()
            return None

        results, _ = self._run(tmp_path, monkeypatch, list(range(n)), n, on_item)
        assert results == [{"seen": i} for i in range(n)]

    @pytest.mark.parametrize(
        "bad", [0, -1, None, "abc", 1.0, float("inf"), float("nan")]
    )
    def test_invalid_max_concurrency_coerces_to_sequential(
        self, tmp_path, monkeypatch, bad
    ):
        # float("inf") -> int() raises OverflowError (not TypeError/ValueError);
        # it must fall back to sequential like any other uncoercible value, not
        # crash the run.
        results, _ = self._run(tmp_path, monkeypatch, list(range(4)), bad)
        assert results == [{"seen": i} for i in range(4)]

    def test_string_max_concurrency_is_honored(self, tmp_path, monkeypatch):
        results, _ = self._run(tmp_path, monkeypatch, list(range(4)), "2")
        assert results == [{"seen": i} for i in range(4)]

    def test_context_item_isolation_across_threads(self, tmp_path, monkeypatch):
        items = [{"id": f"x{i}"} for i in range(6)]
        results, _ = self._run(tmp_path, monkeypatch, items, 6)
        assert [r["seen"]["id"] for r in results] == [f"x{i}" for i in range(6)]

    @pytest.mark.parametrize("max_concurrency", [1, 2])
    def test_marks_item_context_as_inside_fan_out(
        self, tmp_path, monkeypatch, max_concurrency
    ):
        from specify_cli.workflows import STEP_REGISTRY
        from specify_cli.workflows.base import StepBase, StepResult, StepStatus

        class _ContextProbeStep(StepBase):
            type_key = "context-probe"

            def execute(self, config, context):
                return StepResult(
                    status=StepStatus.COMPLETED,
                    output={"inside_fan_out": context.inside_fan_out},
                )

        monkeypatch.setitem(STEP_REGISTRY, "context-probe", _ContextProbeStep())
        results, _ = self._run(
            tmp_path,
            monkeypatch,
            ["a", "b"],
            max_concurrency,
            template={"id": "probe", "type": "context-probe"},
        )

        assert results == [
            {"inside_fan_out": True},
            {"inside_fan_out": True},
        ]

    def test_empty_items(self, tmp_path, monkeypatch):
        results, _ = self._run(tmp_path, monkeypatch, [], 4)
        assert results == []

    def test_concurrent_halt_status_not_clobbered_by_later_item(
        self, tmp_path, monkeypatch
    ):
        # Item 1 PAUSES (first halting item in order); item 3 FAILS while in
        # flight. The final run status must be the halting item's (PAUSED), never
        # a later item's (FAILED) that raced after it — matching sequential.
        from specify_cli.workflows.base import RunStatus, StepStatus

        def on_item(item):
            if item == 1:
                return StepStatus.PAUSED
            if item == 3:
                return StepStatus.FAILED
            return None

        results, state = self._run(tmp_path, monkeypatch, list(range(4)), 4, on_item)
        assert results == [{"seen": 0}, {"seen": 1}]
        assert state.status == RunStatus.PAUSED

    def test_halt_on_failure_sequential_returns_prefix(self, tmp_path, monkeypatch):
        from specify_cli.workflows.base import RunStatus, StepStatus

        def on_item(item):
            return StepStatus.FAILED if item == 2 else None

        results, state = self._run(tmp_path, monkeypatch, list(range(5)), 1, on_item)
        assert len(results) == 3  # items 0,1,2 ran; 3,4 never dispatched
        assert results[2] == {"seen": 2}
        assert state.status == RunStatus.FAILED

    def test_halt_on_failure_concurrent_includes_halting_item(
        self, tmp_path, monkeypatch
    ):
        # The concurrent prefix must match the sequential one: items up to and
        # INCLUDING the failing item (2), never a short prefix that drops it just
        # because a later in-flight item flipped the shared run status first.
        from specify_cli.workflows.base import RunStatus, StepStatus

        def on_item(item):
            return StepStatus.FAILED if item == 2 else None

        results, state = self._run(tmp_path, monkeypatch, list(range(6)), 4, on_item)
        assert results == [{"seen": 0}, {"seen": 1}, {"seen": 2}]
        assert state.status == RunStatus.FAILED

    def test_concurrent_restores_halting_item_error(self, tmp_path, monkeypatch):
        # After a concurrent fan-out halts, the run-level error must be the first
        # halting item's own error (parity with the sequential path), even when a
        # later concurrent item failed with a different error AND the halting
        # item's error is falsy. Covers the pool-join restore branch, which must
        # assign unconditionally rather than skip a falsy value.
        from specify_cli.workflows.base import (
            RunStatus,
            StepBase,
            StepResult,
            StepStatus,
        )

        class _ErrorProbe(StepBase):
            type_key = "err-probe"

            def execute(self, config, context):
                item = context.item
                if item == "halt":
                    # First failing item in item order; empty (falsy) error.
                    return StepResult(
                        status=StepStatus.FAILED, error="", output={}
                    )
                if item == "leak":
                    return StepResult(
                        status=StepStatus.FAILED,
                        error="leaked-error",
                        output={},
                    )
                return StepResult(
                    status=StepStatus.COMPLETED, output={"seen": item}
                )

        from specify_cli.workflows import STEP_REGISTRY

        monkeypatch.setitem(STEP_REGISTRY, "err-probe", _ErrorProbe())
        _results, state = self._run(
            tmp_path,
            monkeypatch,
            ["ok0", "halt", "ok2", "leak"],
            4,
            template={"id": "impl", "type": "err-probe"},
        )

        assert state.status == RunStatus.FAILED
        # Halt is attributed to "halt" (index 1). Its empty error must win over
        # the later "leak" item's error — the restore assigns the halting item's
        # error verbatim, even when falsy.
        assert state.error == ""

    def test_continue_on_error_item_does_not_halt_concurrent(
        self, tmp_path, monkeypatch
    ):
        # A failing item whose template sets continue_on_error must NOT truncate
        # the fan-out: every item still runs and is returned in order.
        from specify_cli.workflows.base import StepStatus

        def on_item(item):
            return StepStatus.FAILED if item == 2 else None

        results, _ = self._run(
            tmp_path,
            monkeypatch,
            list(range(5)),
            4,
            on_item,
            template={"id": "impl", "type": "probe", "continue_on_error": True},
        )
        assert results == [{"seen": i} for i in range(5)]

    def test_unknown_template_type_halts_concurrent_like_sequential(
        self, tmp_path, monkeypatch
    ):
        # A template whose type isn't registered fails fast and records no result;
        # the concurrent path must still attribute the halt to the first item and
        # return the same prefix as sequential — never run on as if completed.
        template = {"id": "impl", "type": "does-not-exist"}
        seq, s1 = self._run(tmp_path, monkeypatch, list(range(5)), 1, template=template)
        con, s2 = self._run(tmp_path, monkeypatch, list(range(5)), 4, template=template)
        assert seq == con == [{}]  # halted at the first item; rest never returned
        from specify_cli.workflows.base import RunStatus

        assert s1.status == s2.status == RunStatus.FAILED

    def test_first_exception_cancels_and_reraises(self, tmp_path, monkeypatch):
        def on_item(item):
            if item == 0:
                raise ValueError("boom")
            return None

        with pytest.raises(ValueError, match="boom"):
            self._run(tmp_path, monkeypatch, list(range(4)), 2, on_item)


class TestFanInWaitForValidation:
    """fan-in wait_for must reference a declared step (no silent empty join)."""

    @staticmethod
    def _errors(yaml_text):
        from specify_cli.workflows.engine import (
            WorkflowDefinition,
            validate_workflow,
        )

        return validate_workflow(WorkflowDefinition.from_string(yaml_text))

    def test_unknown_wait_for_id_is_rejected(self):
        errors = self._errors("""
workflow:
  id: wf
  name: wf
  version: "1.0.0"
steps:
  - id: collect
    type: fan-in
    wait_for: [ghost]
""")
        assert any(
            "unknown or not-yet-declared step id 'ghost'" in e for e in errors
        )

    def test_wait_for_declared_earlier_step_passes(self):
        errors = self._errors("""
workflow:
  id: wf
  name: wf
  version: "1.0.0"
steps:
  - id: produce
    type: command
    command: speckit.implement
  - id: collect
    type: fan-in
    wait_for: [produce]
""")
        assert not any("wait_for" in e for e in errors)

    def test_wait_for_conditionally_declared_step_passes(self):
        # A step declared inside an if-branch may be skipped at runtime, but it is
        # still "declared", so referencing it must validate — a legitimately-empty
        # runtime join stays valid.
        errors = self._errors("""
workflow:
  id: wf
  name: wf
  version: "1.0.0"
steps:
  - id: maybe
    type: if
    condition: "{{ inputs.flag }}"
    then:
      - id: branch_task
        type: command
        command: speckit.implement
  - id: collect
    type: fan-in
    wait_for: [branch_task]
""")
        assert not any("wait_for" in e for e in errors)

    def test_forward_reference_is_rejected(self):
        # wait_for points at a step declared AFTER the fan-in; its results cannot
        # exist when the fan-in runs, so it is flagged.
        errors = self._errors("""
workflow:
  id: wf
  name: wf
  version: "1.0.0"
steps:
  - id: collect
    type: fan-in
    wait_for: [later]
  - id: later
    type: command
    command: speckit.implement
""")
        assert any(
            "unknown or not-yet-declared step id 'later'" in e for e in errors
        )

    def test_self_reference_is_rejected(self):
        # A fan-in's own id is in scope by the time it is validated, so a
        # self-reference slips past the membership check while still producing
        # an empty join at runtime.
        errors = self._errors("""
workflow:
  id: wf
  name: wf
  version: "1.0.0"
steps:
  - id: collect
    type: fan-in
    wait_for: [collect]
""")
        assert any(
            "references itself" in e and "collect" in e for e in errors
        )

    def test_non_string_wait_for_entry_is_rejected(self):
        # A non-string entry (e.g. YAML `wait_for: [123]`) can never match a
        # real step id, so it must be flagged rather than silently ignored.
        errors = self._errors("""
workflow:
  id: wf
  name: wf
  version: "1.0.0"
steps:
  - id: collect
    type: fan-in
    wait_for: [123]
""")
        assert any(
            "must be step-id strings" in e and "int" in e for e in errors
        )

    def test_non_ascii_fan_out_item_index_is_rejected(self):
        errors = self._errors("""
workflow:
  id: wf
  name: wf
  version: "1.0.0"
steps:
  - id: fan
    type: fan-out
    items: [one]
    step:
      id: item
      type: command
      command: speckit.implement
  - id: collect
    type: fan-in
    wait_for: [fan:item:Ù¡]
""")
        assert any("unknown or not-yet-declared step id 'fan:item:Ù¡'" in e for e in errors)


# ===== Workflow Definition Tests =====

class TestWorkflowDefinition:
    """Test WorkflowDefinition loading and parsing."""

    def test_from_yaml(self, sample_workflow_file):
        from specify_cli.workflows.engine import WorkflowDefinition

        definition = WorkflowDefinition.from_yaml(sample_workflow_file)
        assert definition.id == "test-workflow"
        assert definition.name == "Test Workflow"
        assert definition.version == "1.0.0"
        assert len(definition.steps) == 2

    def test_from_string(self, sample_workflow_yaml):
        from specify_cli.workflows.engine import WorkflowDefinition

        definition = WorkflowDefinition.from_string(sample_workflow_yaml)
        assert definition.id == "test-workflow"
        assert len(definition.inputs) == 2

    @pytest.mark.parametrize(
        "block",
        [
            "workflow:\n  id: w\n  name: W\nsteps: []\ninputs: []\n",   # list
            "workflow:\n  id: w\n  name: W\nsteps: []\ninputs:\n",       # null
        ],
    )
    def test_resolve_inputs_tolerates_non_mapping_inputs(self, block):
        # execute()/resume() run UNVALIDATED definitions; a non-mapping `inputs:`
        # block (list/null) is stored raw and would crash _resolve_inputs at
        # `.items()`. It must be treated as "no inputs" instead.
        from specify_cli.workflows.engine import WorkflowDefinition, WorkflowEngine

        definition = WorkflowDefinition.from_string(block)
        resolved = WorkflowEngine()._resolve_inputs(definition, {})  # must not raise
        assert resolved == {}

    @pytest.mark.parametrize(
        "block", ["workflow:\nsteps: []\n", "workflow: hi\nsteps: []\n", "workflow: [a]\nsteps: []\n"]
    )
    def test_non_mapping_workflow_block_parses_then_validates(self, block):
        # A present-but-non-mapping `workflow:` block must not crash construction
        # with AttributeError; it should parse to an empty header so
        # validate_workflow reports the missing id/name (it reads the parsed
        # attributes, not the raw block).
        from specify_cli.workflows.engine import WorkflowDefinition, validate_workflow

        definition = WorkflowDefinition.from_string(block)  # must not raise
        assert definition.id == ""
        errors = validate_workflow(definition)
        assert any("workflow.id" in e for e in errors)
        # The RAW malformed value is preserved on .data (the guard only
        # normalizes the local var, not self.data) — .data is what gets written
        # back out when a definition is serialized. Assert it was NOT replaced
        # with {} by comparing against the original parse and confirming it is
        # still a non-mapping.
        import yaml

        raw_workflow = yaml.safe_load(block).get("workflow")
        assert definition.data["workflow"] == raw_workflow
        assert not isinstance(definition.data["workflow"], dict)

    def test_from_string_invalid(self):
        from specify_cli.workflows.engine import WorkflowDefinition

        with pytest.raises(ValueError, match="must be a mapping"):
            WorkflowDefinition.from_string("- just a list")

    def test_inputs_parsed(self, sample_workflow_yaml):
        from specify_cli.workflows.engine import WorkflowDefinition

        definition = WorkflowDefinition.from_string(sample_workflow_yaml)
        assert "spec" in definition.inputs
        assert definition.inputs["spec"]["required"] is True
        assert definition.inputs["scope"]["default"] == "full"


# ===== Workflow Validation Tests =====

class TestWorkflowValidation:
    """Test workflow validation."""

    def test_valid_workflow(self, sample_workflow_yaml):
        from specify_cli.workflows.engine import WorkflowDefinition, validate_workflow

        definition = WorkflowDefinition.from_string(sample_workflow_yaml)
        errors = validate_workflow(definition)
        assert errors == []

    def test_missing_id(self):
        from specify_cli.workflows.engine import WorkflowDefinition, validate_workflow

        definition = WorkflowDefinition.from_string("""
workflow:
  name: "Test"
  version: "1.0.0"
steps:
  - id: step-one
    command: speckit.specify
""")
        errors = validate_workflow(definition)
        assert any("workflow.id" in e for e in errors)

    def test_invalid_id_format(self):
        from specify_cli.workflows.engine import WorkflowDefinition, validate_workflow

        definition = WorkflowDefinition.from_string("""
workflow:
  id: "Invalid ID!"
  name: "Test"
  version: "1.0.0"
steps:
  - id: step-one
    command: speckit.specify
""")
        errors = validate_workflow(definition)
        assert any("lowercase alphanumeric" in e for e in errors)

    def test_workflow_id_with_trailing_newline_is_invalid(self):
        from specify_cli.workflows.engine import WorkflowDefinition, validate_workflow

        definition = WorkflowDefinition.from_string("""
workflow:
  id: "valid\\n"
  name: "Test"
  version: "1.0.0"
steps:
  - id: step-one
    command: speckit.specify
""")
        errors = validate_workflow(definition)
        assert any("lowercase alphanumeric" in e for e in errors)

    def test_non_string_workflow_id_reports_error(self):
        from specify_cli.workflows.engine import WorkflowDefinition, validate_workflow

        definition = WorkflowDefinition.from_string("""
workflow:
  id: 123
  name: "Test"
  version: "1.0.0"
steps:
  - id: step-one
    command: speckit.specify
""")
        errors = validate_workflow(definition)
        assert any("workflow.id" in e and "string" in e for e in errors)

    def test_non_string_name_reports_error(self):
        from specify_cli.workflows.engine import WorkflowDefinition, validate_workflow

        definition = WorkflowDefinition.from_string("""
workflow:
  id: "test"
  name: 123
  version: "1.0.0"
steps:
  - id: step-one
    command: speckit.specify
""")
        errors = validate_workflow(definition)
        assert any("workflow.name" in e and "string" in e for e in errors)

    def test_unquoted_float_version_reports_error(self):
        from specify_cli.workflows.engine import WorkflowDefinition, validate_workflow

        definition = WorkflowDefinition.from_string("""
workflow:
  id: "test"
  name: "Test"
  version: 1.0
steps:
  - id: step-one
    command: speckit.specify
""")
        errors = validate_workflow(definition)
        assert any("workflow.version" in e and "quote" in e for e in errors)

    def test_version_with_trailing_newline_is_invalid(self):
        from specify_cli.workflows.engine import WorkflowDefinition, validate_workflow

        definition = WorkflowDefinition.from_string("""
workflow:
  id: "test"
  name: "Test"
  version: "1.0.0\\n"
steps:
  - id: step-one
    command: speckit.specify
""")
        errors = validate_workflow(definition)
        assert any("semantic version" in e for e in errors)

    def test_non_string_step_id_reports_error(self):
        from specify_cli.workflows.engine import WorkflowDefinition, validate_workflow

        definition = WorkflowDefinition.from_string("""
workflow:
  id: "test"
  name: "Test"
  version: "1.0.0"
steps:
  - id: 123
    command: speckit.specify
""")
        errors = validate_workflow(definition)
        assert any("Step ID" in e and "string" in e for e in errors)

    def test_falsey_non_string_scalars_report_typed_errors(self):
        from specify_cli.workflows.engine import WorkflowDefinition, validate_workflow

        definition = WorkflowDefinition.from_string("""
workflow:
  id: 0
  name: false
  version: 0.0
steps:
  - id: 0
    command: speckit.specify
""")
        errors = validate_workflow(definition)
        assert any("'workflow.id' must be a string" in e for e in errors)
        assert any("'workflow.name' must be a string" in e for e in errors)
        assert any("'workflow.version' must be a string" in e for e in errors)
        assert any("Step ID must be a string" in e for e in errors)
        assert not any("missing" in e for e in errors)

    def test_unquoted_schema_version_accepted(self):
        from specify_cli.workflows.engine import WorkflowDefinition, validate_workflow

        definition = WorkflowDefinition.from_string("""
schema_version: 1.0
workflow:
  id: "test"
  name: "Test"
  version: "1.0.0"
steps:
  - id: step-one
    command: speckit.specify
""")
        errors = validate_workflow(definition)
        assert errors == []

    @pytest.mark.parametrize(
        "field, bad_value",
        [
            ("integration", ["claude"]),
            ("integration", {"name": "claude"}),
            ("integration", False),
            ("model", ["gpt-5"]),
            ("model", {"name": "gpt-5"}),
            ("model", 0),
            ("options", ["max_tokens"]),
            ("options", "max_tokens"),
            ("options", False),
        ],
    )
    def test_rejects_invalid_workflow_dispatch_defaults(self, field, bad_value):
        """Top-level dispatch defaults must retain their invalid shape for
        validation instead of being passed to a step or normalized to ``{}``.
        """
        from specify_cli.workflows.engine import WorkflowDefinition, validate_workflow

        definition = WorkflowDefinition(
            {
                "workflow": {
                    "id": "test",
                    "name": "Test",
                    "version": "1.0.0",
                    field: bad_value,
                },
                "steps": [{"id": "step-one", "command": "speckit.specify"}],
            }
        )

        errors = validate_workflow(definition)

        assert any(f"workflow.{field}" in error for error in errors), errors
        assert any(type(bad_value).__name__ in error for error in errors), errors
        if field == "options":
            assert definition.default_options == bad_value

    def test_preserves_valid_workflow_dispatch_defaults(self):
        """String and mapping defaults stay available unchanged to steps."""
        from specify_cli.workflows.engine import WorkflowDefinition, validate_workflow

        defaults = {
            "integration": "claude",
            "model": "gpt-5",
            "options": {"max_tokens": 8000},
        }
        definition = WorkflowDefinition(
            {
                "workflow": {
                    "id": "test",
                    "name": "Test",
                    "version": "1.0.0",
                    **defaults,
                },
                "steps": [{"id": "step-one", "command": "speckit.specify"}],
            }
        )

        assert definition.default_integration == defaults["integration"]
        assert definition.default_model == defaults["model"]
        assert definition.default_options == defaults["options"]
        assert validate_workflow(definition) == []

    def test_accepts_null_workflow_dispatch_defaults(self):
        """Null integration/model inherit at runtime and null options stays {}."""
        from specify_cli.workflows.engine import WorkflowDefinition, validate_workflow

        definition = WorkflowDefinition(
            {
                "workflow": {
                    "id": "test",
                    "name": "Test",
                    "version": "1.0.0",
                    "integration": None,
                    "model": None,
                    "options": None,
                },
                "steps": [{"id": "step-one", "command": "speckit.specify"}],
            }
        )

        assert definition.default_integration is None
        assert definition.default_model is None
        assert definition.default_options == {}
        assert validate_workflow(definition) == []

    def test_no_steps(self):
        from specify_cli.workflows.engine import WorkflowDefinition, validate_workflow

        definition = WorkflowDefinition.from_string("""
workflow:
  id: "test"
  name: "Test"
  version: "1.0.0"
steps: []
""")
        errors = validate_workflow(definition)
        assert any("no steps" in e.lower() for e in errors)

    def test_duplicate_step_ids(self):
        from specify_cli.workflows.engine import WorkflowDefinition, validate_workflow

        definition = WorkflowDefinition.from_string("""
workflow:
  id: "test"
  name: "Test"
  version: "1.0.0"
steps:
  - id: same-id
    command: speckit.specify
  - id: same-id
    command: speckit.plan
""")
        errors = validate_workflow(definition)
        assert any("Duplicate" in e for e in errors)

    def test_invalid_step_type(self):
        from specify_cli.workflows.engine import WorkflowDefinition, validate_workflow

        definition = WorkflowDefinition.from_string("""
workflow:
  id: "test"
  name: "Test"
  version: "1.0.0"
steps:
  - id: bad
    type: nonexistent
""")
        errors = validate_workflow(definition)
        assert any("invalid type" in e.lower() for e in errors)

    @pytest.mark.parametrize("step_type", [["shell"], {"name": "shell"}])
    def test_non_string_step_type_reports_error(self, step_type):
        """Unhashable YAML values must not crash registry membership checks."""
        from specify_cli.workflows.engine import WorkflowDefinition, validate_workflow

        definition = WorkflowDefinition(
            {
                "workflow": {
                    "id": "test",
                    "name": "Test",
                    "version": "1.0.0",
                },
                "steps": [{"id": "bad", "type": step_type}],
            }
        )

        errors = validate_workflow(definition)

        assert errors == [
            f"Step 'bad': 'type' must be a string, got "
            f"{type(step_type).__name__} ({step_type!r})."
        ]

    def test_nested_step_validation(self):
        from specify_cli.workflows.engine import WorkflowDefinition, validate_workflow

        definition = WorkflowDefinition.from_string("""
workflow:
  id: "test"
  name: "Test"
  version: "1.0.0"
steps:
  - id: branch
    type: if
    condition: "{{ true }}"
    then:
      - id: nested-a
        command: speckit.specify
    else:
      - id: nested-b
        command: speckit.plan
""")
        errors = validate_workflow(definition)
        assert errors == []

    def test_invalid_input_type(self):
        from specify_cli.workflows.engine import WorkflowDefinition, validate_workflow

        definition = WorkflowDefinition.from_string("""
workflow:
  id: "test"
  name: "Test"
  version: "1.0.0"
inputs:
  bad:
    type: array
steps:
  - id: step-one
    command: speckit.specify
""")
        errors = validate_workflow(definition)
        assert any("invalid type" in e.lower() for e in errors)

    def test_requires_with_recognized_keys_is_valid(self):
        from specify_cli.workflows.engine import WorkflowDefinition, validate_workflow

        definition = WorkflowDefinition.from_string("""
workflow:
  id: "test"
  name: "Test"
  version: "1.0.0"
requires:
  speckit_version: ">=0.7.2"
  integrations:
    any: ["claude", "gemini"]
steps:
  - id: step-one
    command: speckit.specify
""")
        errors = validate_workflow(definition)
        assert errors == []

    def test_requires_must_be_mapping(self):
        from specify_cli.workflows.engine import WorkflowDefinition, validate_workflow

        definition = WorkflowDefinition.from_string("""
workflow:
  id: "test"
  name: "Test"
  version: "1.0.0"
requires: "claude"
steps:
  - id: step-one
    command: speckit.specify
""")
        errors = validate_workflow(definition)
        assert any("'requires' must be a mapping" in e for e in errors)

    def test_requires_unknown_key_is_rejected(self):
        from specify_cli.workflows.engine import WorkflowDefinition, validate_workflow

        definition = WorkflowDefinition.from_string("""
workflow:
  id: "test"
  name: "Test"
  version: "1.0.0"
requires:
  speckit_version: ">=0.7.2"
  typo_key: true
steps:
  - id: step-one
    command: speckit.specify
""")
        errors = validate_workflow(definition)
        assert any("typo_key" in e and "requires" in e for e in errors)

    def test_requires_permissions_is_rejected_as_not_enforced(self):
        """A `requires.permissions` block looks like a runtime capability gate
        but no such gate exists — shell steps always run with the user's
        privileges. Reject it explicitly so authors are not misled into
        believing the declaration sandboxes execution.
        """
        from specify_cli.workflows.engine import WorkflowDefinition, validate_workflow

        definition = WorkflowDefinition.from_string("""
workflow:
  id: "test"
  name: "Test"
  version: "1.0.0"
requires:
  permissions:
    shell: true
steps:
  - id: run
    type: shell
    run: "echo hi"
""")
        errors = validate_workflow(definition)
        # Assert on specific markers from the intended message (the offending
        # key and the `gate` remediation) so the test fails if the validation
        # path or wording drifts, rather than passing on any error that merely
        # happens to contain "permissions" and "not".
        assert any("requires.permissions" in e and "gate" in e for e in errors)

    def test_requires_empty_sequence_is_rejected_as_non_mapping(self):
        """A non-mapping ``requires`` (e.g. an empty list) is an authoring
        error. Mirroring ``inputs``, validation checks ``isinstance(..., dict)``
        so ``requires: []`` surfaces instead of silently passing.
        """
        from specify_cli.workflows.engine import WorkflowDefinition, validate_workflow

        definition = WorkflowDefinition.from_string("""
workflow:
  id: "test"
  name: "Test"
  version: "1.0.0"
requires: []
steps:
  - id: step-one
    command: speckit.specify
""")
        errors = validate_workflow(definition)
        assert any("'requires' must be a mapping" in e for e in errors)

    def test_requires_yaml_null_is_rejected_as_non_mapping(self):
        """A bare ``requires:`` parses as YAML null. Like ``inputs``, a present
        block must be a mapping, so YAML null is rejected as an authoring error
        rather than being silently treated as an omitted block. (A truly
        omitted ``requires`` defaults to ``{}`` and stays valid.)
        """
        from specify_cli.workflows.engine import WorkflowDefinition, validate_workflow

        definition = WorkflowDefinition.from_string("""
workflow:
  id: "test"
  name: "Test"
  version: "1.0.0"
requires:
steps:
  - id: step-one
    command: speckit.specify
""")
        errors = validate_workflow(definition)
        assert any("'requires' must be a mapping" in e for e in errors)

    def test_requires_omitted_is_valid(self):
        """A workflow with no ``requires`` block at all defaults to ``{}`` and
        must validate cleanly — only a present-but-non-mapping value is an
        error (guards against over-correcting YAML-null rejection into also
        flagging the omitted case).
        """
        from specify_cli.workflows.engine import WorkflowDefinition, validate_workflow

        definition = WorkflowDefinition.from_string("""
workflow:
  id: "test"
  name: "Test"
  version: "1.0.0"
steps:
  - id: step-one
    command: speckit.specify
""")
        errors = validate_workflow(definition)
        assert not any("requires" in e for e in errors)


class TestGateVerdictInputValidation:
    """Gate verdict_input must reference a declared workflow input.

    ``_resolve_inputs`` iterates only over ``definition.inputs`` — a provided
    value for an undeclared name is silently dropped at both initial run and
    resume. So an undeclared ``verdict_input`` can never receive a value; the
    gate would pause forever. Surface this wiring error at validation time.
    """

    @staticmethod
    def _errors(yaml_text):
        from specify_cli.workflows.engine import (
            WorkflowDefinition,
            validate_workflow,
        )

        return validate_workflow(WorkflowDefinition.from_string(yaml_text))

    def test_undeclared_verdict_input_is_rejected(self):
        errors = self._errors("""
workflow:
  id: wf
  name: wf
  version: "1.0.0"
inputs:
  spec_verdict:
    type: string
    default: ""
steps:
  - id: review
    type: gate
    message: "Review?"
    options: [approve, reject]
    verdict_input: spec_verdit
""")
        assert any(
            "'verdict_input' references undeclared input 'spec_verdit'" in e
            for e in errors
        )

    def test_declared_verdict_input_passes(self):
        errors = self._errors("""
workflow:
  id: wf
  name: wf
  version: "1.0.0"
inputs:
  spec_verdict:
    type: string
    default: ""
steps:
  - id: review
    type: gate
    message: "Review?"
    options: [approve, reject]
    verdict_input: spec_verdict
""")
        assert not any("verdict_input" in e for e in errors)

    def test_gate_without_verdict_input_passes(self):
        errors = self._errors("""
workflow:
  id: wf
  name: wf
  version: "1.0.0"
steps:
  - id: review
    type: gate
    message: "Review?"
    options: [approve, reject]
""")
        assert not any("verdict_input" in e for e in errors)

    def test_malformed_verdict_input_no_duplicate_error(self):
        # Non-string verdict_input is already reported by GateStep.validate();
        # the cross-reference check must not pile on a confusing duplicate.
        errors = self._errors("""
workflow:
  id: wf
  name: wf
  version: "1.0.0"
inputs:
  spec_verdict:
    type: string
    default: ""
steps:
  - id: review
    type: gate
    message: "Review?"
    options: [approve, reject]
    verdict_input: 123
""")
        # Shape error from GateStep.validate()
        assert any("verdict_input" in e and "non-empty string" in e for e in errors)
        # No undeclared-input error (123 is not a string, so cross-check skips)
        assert not any("undeclared input" in e for e in errors)

    def test_retry_verdict_enum_must_allow_reset_sentinel(self):
        # on_reject: retry resets the bound input to "" before pausing, and
        # every resume re-resolves persisted inputs through _coerce_input. An
        # enum that omits "" makes that reset value instantly illegal, so the
        # next resume supplying any input dies with "value '' not in allowed
        # values" and no verdict can reach the gate again.
        errors = self._errors("""
workflow:
  id: wf
  name: wf
  version: "1.0.0"
inputs:
  spec_verdict:
    type: string
    enum: [approve, reject]
steps:
  - id: review
    type: gate
    message: "Review?"
    options: [approve, reject]
    on_reject: retry
    verdict_input: spec_verdict
""")
        assert any(
            "on_reject='retry' resets verdict input 'spec_verdict'" in e
            for e in errors
        ), errors

    def test_retry_verdict_enum_including_sentinel_passes(self):
        errors = self._errors("""
workflow:
  id: wf
  name: wf
  version: "1.0.0"
inputs:
  spec_verdict:
    type: string
    enum: ["", approve, reject]
    default: ""
steps:
  - id: review
    type: gate
    message: "Review?"
    options: [approve, reject]
    on_reject: retry
    verdict_input: spec_verdict
""")
        assert not any("on_reject='retry'" in e for e in errors), errors

    def test_verdict_enum_without_sentinel_passes_when_not_retry(self):
        # abort/skip never reset the input, so the enum need not admit "".
        for on_reject in ("abort", "skip"):
            errors = self._errors(f"""
workflow:
  id: wf
  name: wf
  version: "1.0.0"
inputs:
  spec_verdict:
    type: string
    enum: [approve, reject]
steps:
  - id: review
    type: gate
    message: "Review?"
    options: [approve, reject]
    on_reject: {on_reject}
    verdict_input: spec_verdict
""")
            assert not any("on_reject='retry'" in e for e in errors), (
                on_reject,
                errors,
            )

    def test_retry_verdict_without_enum_passes(self):
        # No enum means _coerce_input accepts "" — the documented shape.
        errors = self._errors("""
workflow:
  id: wf
  name: wf
  version: "1.0.0"
inputs:
  spec_verdict:
    type: string
    default: ""
steps:
  - id: review
    type: gate
    message: "Review?"
    options: [approve, reject]
    on_reject: retry
    verdict_input: spec_verdict
""")
        assert not any("on_reject='retry'" in e for e in errors), errors

    def test_retry_verdict_enum_wedge_is_reachable_end_to_end(self, tmp_path):
        """The validation error above guards a real, unrecoverable run state.

        Without the guard this workflow installs and runs fine, then wedges:
        the retry reset writes "" into the persisted inputs, and the next
        resume that supplies *any* input re-resolves them and dies on the
        enum. Only a resume with no inputs at all still works, so the bound
        verdict can never be delivered.
        """
        import pytest
        import yaml as _yaml

        from specify_cli.workflows.engine import WorkflowEngine

        definition_data = {
            "schema_version": "1.0",
            "workflow": {"id": "wf", "name": "WF", "version": "1.0.0"},
            "inputs": {
                "spec_verdict": {"type": "string", "enum": ["approve", "reject"]},
                "note": {"type": "string", "default": "a"},
            },
            "steps": [
                {
                    "id": "review",
                    "type": "gate",
                    "message": "Review?",
                    "options": ["approve", "reject"],
                    "on_reject": "retry",
                    "verdict_input": "spec_verdict",
                }
            ],
        }
        wf_dir = tmp_path / ".specify" / "workflows" / "wf"
        wf_dir.mkdir(parents=True)
        (wf_dir / "workflow.yml").write_text(
            _yaml.safe_dump(definition_data), encoding="utf-8"
        )

        engine = WorkflowEngine(tmp_path)
        definition = engine.load_workflow("wf")
        state = engine.execute(definition, inputs={"spec_verdict": "reject"})
        assert state.status.value == "paused"
        # The retry reset persisted a value the input's own enum forbids.
        assert state.inputs["spec_verdict"] == ""

        with pytest.raises(ValueError, match="not in allowed values"):
            engine.resume(state.run_id, inputs={"note": "b"})

    def test_verdict_input_in_switch_case(self):
        # Recursion coverage: bad reference inside a switch case must surface.
        errors = self._errors("""
workflow:
  id: wf
  name: wf
  version: "1.0.0"
steps:
  - id: branch
    type: switch
    expression: "{{ inputs.flag }}"
    cases:
      yes:
        - id: review
          type: gate
          message: "Review?"
          options: [approve, reject]
          verdict_input: ghost_input
""")
        assert any(
            "'verdict_input' references undeclared input 'ghost_input'" in e
            for e in errors
        )

    def test_verdict_input_in_if_branch(self):
        # Recursion coverage: bad reference inside an if-then branch.
        errors = self._errors("""
workflow:
  id: wf
  name: wf
  version: "1.0.0"
steps:
  - id: maybe
    type: if
    condition: "{{ inputs.flag }}"
    then:
      - id: review
        type: gate
        message: "Review?"
        options: [approve, reject]
        verdict_input: ghost_input
""")
        assert any(
            "'verdict_input' references undeclared input 'ghost_input'" in e
            for e in errors
        )

    def test_verdict_input_in_fan_out_template(self):
        # Fan-out items share workflow inputs, so a bound verdict would be
        # consumed by multiple item gates with undefined pause/resume semantics.
        errors = self._errors("""
workflow:
  id: wf
  name: wf
  version: "1.0.0"
inputs:
  spec_verdict:
    type: string
    default: ""
steps:
  - id: fan
    type: fan-out
    items: [a, b]
    step:
      id: review
      type: gate
      message: "Review?"
      options: [approve, reject]
      verdict_input: spec_verdict
""")
        assert any(
            "'verdict_input' is not supported inside fan-out templates" in e
            for e in errors
        )

    def test_verdict_input_nested_inside_fan_out_template(self):
        errors = self._errors("""
workflow:
  id: wf
  name: wf
  version: "1.0.0"
inputs:
  spec_verdict:
    type: string
    default: ""
steps:
  - id: fan
    type: fan-out
    items: [a, b]
    step:
      id: maybe-review
      type: if
      condition: "{{ item }}"
      then:
        - id: review
          type: gate
          message: "Review?"
          options: [approve, reject]
          verdict_input: spec_verdict
""")
        assert any(
            "'verdict_input' is not supported inside fan-out templates" in e
            for e in errors
        )

    def test_gate_without_verdict_input_in_fan_out_template_passes(self):
        errors = self._errors("""
workflow:
  id: wf
  name: wf
  version: "1.0.0"
steps:
  - id: fan
    type: fan-out
    items: [a, b]
    step:
      id: review
      type: gate
      message: "Review?"
      options: [approve, reject]
""")
        assert not any(
            "not supported inside fan-out templates" in e for e in errors
        )

    def test_malformed_inputs_block_no_cascade(self):
        # When the inputs block itself is malformed (already reported), the
        # cross-check is disabled so one authoring mistake does not cascade
        # into N spurious "undeclared" errors.
        errors = self._errors("""
workflow:
  id: wf
  name: wf
  version: "1.0.0"
inputs:
  - not_a_mapping
steps:
  - id: review
    type: gate
    message: "Review?"
    options: [approve, reject]
    verdict_input: spec_verdict
""")
        # Inputs-shape error is reported
        assert any("'inputs' must be a mapping" in e for e in errors)
        # No cascade of undeclared-input errors
        assert not any("undeclared input" in e for e in errors)


# ===== Workflow Engine Tests =====

class TestWorkflowEngine:
    """Test WorkflowEngine execution."""

    @pytest.mark.parametrize(
        ("field", "value"),
        [
            ("integration", ["claude"]),
            ("model", {"name": "gpt-5"}),
            ("options", ["max_tokens"]),
        ],
    )
    def test_execute_rejects_invalid_workflow_dispatch_defaults(
        self, project_dir, field, value
    ):
        from specify_cli.workflows.engine import WorkflowDefinition, WorkflowEngine

        definition = WorkflowDefinition(
            {
                "workflow": {
                    "id": "invalid-dispatch-defaults",
                    "name": "Invalid dispatch defaults",
                    "version": "1.0.0",
                    field: value,
                },
                "steps": [],
            }
        )

        with pytest.raises(ValueError, match=f"workflow.{field}"):
            WorkflowEngine(project_dir).execute(definition)

        assert not (project_dir / ".specify" / "workflows" / "runs").exists()

    def test_load_from_file(self, sample_workflow_file, project_dir):
        from specify_cli.workflows.engine import WorkflowEngine

        engine = WorkflowEngine(project_dir)
        definition = engine.load_workflow(str(sample_workflow_file))
        assert definition.id == "test-workflow"

    def test_load_from_installed_id(self, sample_workflow_file, project_dir):
        from specify_cli.workflows.engine import WorkflowEngine

        engine = WorkflowEngine(project_dir)
        definition = engine.load_workflow("test-workflow")
        assert definition.id == "test-workflow"

    def test_load_not_found(self, project_dir):
        from specify_cli.workflows.engine import WorkflowEngine

        engine = WorkflowEngine(project_dir)
        with pytest.raises(FileNotFoundError):
            engine.load_workflow("nonexistent")

    def test_execute_simple_workflow(self, project_dir):
        from unittest.mock import patch
        from specify_cli.workflows.engine import WorkflowEngine, WorkflowDefinition
        from specify_cli.workflows.base import RunStatus

        yaml_str = """
schema_version: "1.0"
workflow:
  id: "simple"
  name: "Simple"
  version: "1.0.0"
  integration: claude
inputs:
  name:
    type: string
    default: "test"
steps:
  - id: step-one
    command: speckit.specify
    input:
      args: "{{ inputs.name }}"
"""
        definition = WorkflowDefinition.from_string(yaml_str)
        engine = WorkflowEngine(project_dir)
        with patch("specify_cli.workflows.step.command.shutil.which", return_value=None):
            state = engine.execute(definition, {"name": "login"})

        assert state.status == RunStatus.FAILED
        assert "step-one" in state.step_results
        assert state.step_results["step-one"]["output"]["command"] == "speckit.specify"
        assert state.step_results["step-one"]["output"]["input"]["args"] == "login"

    def test_execute_rejects_invalid_origin_before_creating_run_state(
        self, project_dir
    ):
        from specify_cli.workflows.engine import WorkflowDefinition, WorkflowEngine

        definition = WorkflowDefinition.from_string("""
schema_version: "1.0"
workflow:
  id: "simple"
  name: "Simple"
  version: "1.0.0"
steps: []
""")
        engine = WorkflowEngine(project_dir)

        with pytest.raises(ValueError, match="installed_registry_root"):
            engine.execute(
                definition,
                run_id="invalid-origin",
                installed_workflow_id="simple",
                installed_registry_root=Path("relative-owner"),
            )

        run_dir = (
            project_dir
            / ".specify"
            / "workflows"
            / "runs"
            / "invalid-origin"
        )
        assert not run_dir.exists()

    def test_execute_with_gate_pauses(self, project_dir):
        from specify_cli.workflows.engine import WorkflowEngine, WorkflowDefinition
        from specify_cli.workflows.base import RunStatus

        yaml_str = """
schema_version: "1.0"
workflow:
  id: "gated"
  name: "Gated"
  version: "1.0.0"
steps:
  - id: step-one
    type: shell
    run: "echo test"
  - id: gate
    type: gate
    message: "Review?"
    options: [approve, reject]
    on_reject: abort
  - id: step-two
    type: shell
    run: "echo done"
"""
        definition = WorkflowDefinition.from_string(yaml_str)
        engine = WorkflowEngine(project_dir)
        state = engine.execute(definition)

        assert state.status == RunStatus.PAUSED
        assert "gate" in state.step_results
        assert state.step_results["gate"]["status"] == "paused"

    def test_execute_with_shell_step(self, project_dir):
        from specify_cli.workflows.engine import WorkflowEngine, WorkflowDefinition
        from specify_cli.workflows.base import RunStatus

        yaml_str = """
schema_version: "1.0"
workflow:
  id: "shell-test"
  name: "Shell Test"
  version: "1.0.0"
steps:
  - id: echo
    type: shell
    run: "echo workflow-output"
"""
        definition = WorkflowDefinition.from_string(yaml_str)
        engine = WorkflowEngine(project_dir)
        state = engine.execute(definition)

        assert state.status == RunStatus.COMPLETED
        assert "workflow-output" in state.step_results["echo"]["output"]["stdout"]

    def test_execute_with_if_then(self, project_dir):
        from specify_cli.workflows.engine import WorkflowEngine, WorkflowDefinition
        from specify_cli.workflows.base import RunStatus

        yaml_str = """
schema_version: "1.0"
workflow:
  id: "branching"
  name: "Branching"
  version: "1.0.0"
inputs:
  scope:
    type: string
    default: "full"
steps:
  - id: check
    type: if
    condition: "{{ inputs.scope == 'full' }}"
    then:
      - id: full-tasks
        type: shell
        run: "echo full"
    else:
      - id: partial-tasks
        type: shell
        run: "echo partial"
"""
        definition = WorkflowDefinition.from_string(yaml_str)
        engine = WorkflowEngine(project_dir)
        state = engine.execute(definition, {"scope": "full"})

        assert state.status == RunStatus.COMPLETED
        assert "full-tasks" in state.step_results
        assert "partial-tasks" not in state.step_results

    def test_execute_missing_required_input(self, project_dir):
        from specify_cli.workflows.engine import WorkflowEngine, WorkflowDefinition

        yaml_str = """
schema_version: "1.0"
workflow:
  id: "needs-input"
  name: "Needs Input"
  version: "1.0.0"
inputs:
  name:
    type: string
    required: true
steps:
  - id: step-one
    command: speckit.specify
    input:
      args: "{{ inputs.name }}"
"""
        definition = WorkflowDefinition.from_string(yaml_str)
        engine = WorkflowEngine(project_dir)

        with pytest.raises(ValueError, match="Required input"):
            engine.execute(definition, {})

    def test_integration_auto_default_uses_project_integration(self, project_dir):
        """`integration: auto` should resolve to .specify/integration.json's integration."""
        from specify_cli.workflows.engine import WorkflowEngine, WorkflowDefinition

        specify_dir = project_dir / ".specify"
        specify_dir.mkdir(parents=True, exist_ok=True)
        (specify_dir / "integration.json").write_text(
            json.dumps({"integration": "opencode", "version": "0.7.4"}),
            encoding="utf-8",
        )

        definition = WorkflowDefinition.from_string("""
schema_version: "1.0"
workflow:
  id: "auto-default"
  name: "Auto Default"
  version: "1.0.0"
inputs:
  integration:
    type: string
    default: "auto"
""")
        engine = WorkflowEngine(project_dir)
        resolved = engine._resolve_inputs(definition, {})
        assert resolved["integration"] == "opencode"

    def test_integration_auto_default_falls_back_when_no_integration_json(self, project_dir):
        """`integration: auto` should keep the literal "auto" when project state is missing.

        The engine itself must not invent an integration when
        ``.specify/integration.json`` is absent; any later validation or
        command resolution will handle an unresolved ``"auto"`` value.
        """
        from specify_cli.workflows.engine import WorkflowEngine, WorkflowDefinition

        definition = WorkflowDefinition.from_string("""
schema_version: "1.0"
workflow:
  id: "auto-fallback"
  name: "Auto Fallback"
  version: "1.0.0"
inputs:
  integration:
    type: string
    default: "auto"
""")
        engine = WorkflowEngine(project_dir)
        resolved = engine._resolve_inputs(definition, {})
        assert resolved["integration"] == "auto"

    def test_integration_explicit_input_overrides_auto(self, project_dir):
        """An explicit --input integration=X must win over `auto` even when integration.json exists."""
        from specify_cli.workflows.engine import WorkflowEngine, WorkflowDefinition

        specify_dir = project_dir / ".specify"
        specify_dir.mkdir(parents=True, exist_ok=True)
        (specify_dir / "integration.json").write_text(
            json.dumps({"integration": "opencode"}),
            encoding="utf-8",
        )

        definition = WorkflowDefinition.from_string("""
schema_version: "1.0"
workflow:
  id: "explicit-wins"
  name: "Explicit Wins"
  version: "1.0.0"
inputs:
  integration:
    type: string
    default: "auto"
""")
        engine = WorkflowEngine(project_dir)
        resolved = engine._resolve_inputs(definition, {"integration": "claude"})
        assert resolved["integration"] == "claude"

    def test_integration_explicit_auto_resolves_like_default(self, project_dir):
        """Passing ``integration=auto`` explicitly must resolve the sentinel,
        not pass it through as a literal — the workflow prompt advertises
        ``auto`` as a valid value, so the dispatch path must never see it.
        """
        from specify_cli.workflows.engine import WorkflowEngine, WorkflowDefinition

        specify_dir = project_dir / ".specify"
        specify_dir.mkdir(parents=True, exist_ok=True)
        (specify_dir / "integration.json").write_text(
            json.dumps({"integration": "opencode"}),
            encoding="utf-8",
        )

        definition = WorkflowDefinition.from_string("""
schema_version: "1.0"
workflow:
  id: "explicit-auto"
  name: "Explicit Auto"
  version: "1.0.0"
inputs:
  integration:
    type: string
    default: "auto"
""")
        engine = WorkflowEngine(project_dir)
        resolved = engine._resolve_inputs(definition, {"integration": "auto"})
        assert resolved["integration"] == "opencode"

    def test_integration_auto_ignores_malformed_integration_json(self, project_dir):
        """A malformed integration.json must not crash — fall back to the literal default."""
        from specify_cli.workflows.engine import WorkflowEngine, WorkflowDefinition

        specify_dir = project_dir / ".specify"
        specify_dir.mkdir(parents=True, exist_ok=True)
        (specify_dir / "integration.json").write_text("{not json", encoding="utf-8")

        definition = WorkflowDefinition.from_string("""
schema_version: "1.0"
workflow:
  id: "auto-malformed"
  name: "Auto Malformed"
  version: "1.0.0"
inputs:
  integration:
    type: string
    default: "auto"
""")
        engine = WorkflowEngine(project_dir)
        resolved = engine._resolve_inputs(definition, {})
        assert resolved["integration"] == "auto"

    def test_integration_auto_ignores_non_utf8_integration_json(self, project_dir):
        """A non-UTF8 integration.json must not crash — fall back to the literal default."""
        from specify_cli.workflows.engine import WorkflowEngine, WorkflowDefinition

        specify_dir = project_dir / ".specify"
        specify_dir.mkdir(parents=True, exist_ok=True)
        # 0xFF is invalid as the leading byte of a UTF-8 sequence, so
        # ``Path.read_text(encoding="utf-8")`` raises UnicodeDecodeError.
        (specify_dir / "integration.json").write_bytes(b"\xff\xfe\x00\x00")

        definition = WorkflowDefinition.from_string("""
schema_version: "1.0"
workflow:
  id: "auto-non-utf8"
  name: "Auto Non UTF-8"
  version: "1.0.0"
inputs:
  integration:
    type: string
    default: "auto"
""")
        engine = WorkflowEngine(project_dir)
        resolved = engine._resolve_inputs(definition, {})
        assert resolved["integration"] == "auto"

    def test_integration_auto_resolves_modern_normalized_state(self, project_dir):
        """`integration: auto` must resolve modern state files that record
        ``default_integration`` / ``installed_integrations`` and omit the
        legacy ``integration`` field."""
        from specify_cli.workflows.engine import WorkflowEngine, WorkflowDefinition

        specify_dir = project_dir / ".specify"
        specify_dir.mkdir(parents=True, exist_ok=True)
        (specify_dir / "integration.json").write_text(
            json.dumps(
                {
                    "version": "0.8.3",
                    "integration_state_schema": 1,
                    "default_integration": "claude",
                    "installed_integrations": ["claude", "copilot"],
                    "integration_settings": {},
                }
            ),
            encoding="utf-8",
        )

        definition = WorkflowDefinition.from_string("""
schema_version: "1.0"
workflow:
  id: "auto-modern"
  name: "Auto Modern"
  version: "1.0.0"
inputs:
  integration:
    type: string
    default: "auto"
""")
        engine = WorkflowEngine(project_dir)
        resolved = engine._resolve_inputs(definition, {})
        assert resolved["integration"] == "claude"

    def test_integration_auto_rejects_future_state_schema(self, project_dir):
        """`integration: auto` must not silently use a state file written by a newer
        CLI (``integration_state_schema`` greater than the current supported value);
        the resolver falls back to the literal default rather than guessing."""
        from specify_cli.workflows.engine import WorkflowEngine, WorkflowDefinition
        from specify_cli.integration_state import INTEGRATION_STATE_SCHEMA

        specify_dir = project_dir / ".specify"
        specify_dir.mkdir(parents=True, exist_ok=True)
        (specify_dir / "integration.json").write_text(
            json.dumps(
                {
                    "version": "99.0.0",
                    "integration_state_schema": INTEGRATION_STATE_SCHEMA + 1,
                    "default_integration": "claude",
                    "installed_integrations": ["claude"],
                    "integration_settings": {},
                }
            ),
            encoding="utf-8",
        )

        definition = WorkflowDefinition.from_string("""
schema_version: "1.0"
workflow:
  id: "auto-future-schema"
  name: "Auto Future Schema"
  version: "1.0.0"
inputs:
  integration:
    type: string
    default: "auto"
""")
        engine = WorkflowEngine(project_dir)
        resolved = engine._resolve_inputs(definition, {})
        assert resolved["integration"] == "auto"

    def test_default_value_is_validated_against_enum(self, project_dir):
        """Defaults must run through the same coercion/enum check as provided inputs."""
        from specify_cli.workflows.engine import WorkflowEngine, WorkflowDefinition

        definition = WorkflowDefinition.from_string("""
schema_version: "1.0"
workflow:
  id: "default-enum"
  name: "Default Enum"
  version: "1.0.0"
inputs:
  scope:
    type: string
    default: "not-in-enum"
    enum: ["full", "backend-only", "frontend-only"]
""")
        engine = WorkflowEngine(project_dir)
        with pytest.raises(ValueError, match="not in allowed values"):
            engine._resolve_inputs(definition, {})

    def test_default_value_is_coerced_to_declared_type(self, project_dir):
        """A numeric default declared as a string should still be coerced like a provided input."""
        from specify_cli.workflows.engine import WorkflowEngine, WorkflowDefinition

        definition = WorkflowDefinition.from_string("""
schema_version: "1.0"
workflow:
  id: "default-coerce"
  name: "Default Coerce"
  version: "1.0.0"
inputs:
  retries:
    type: number
    default: "3"
""")
        engine = WorkflowEngine(project_dir)
        resolved = engine._resolve_inputs(definition, {})
        assert resolved["retries"] == 3
        assert isinstance(resolved["retries"], int)

    def test_validate_workflow_rejects_invalid_default(self):
        """Authoring-time validation should reject defaults that violate enum."""
        from specify_cli.workflows.engine import WorkflowDefinition, validate_workflow

        definition = WorkflowDefinition.from_string("""
schema_version: "1.0"
workflow:
  id: "bad-default"
  name: "Bad Default"
  version: "1.0.0"
inputs:
  scope:
    type: string
    default: "not-in-enum"
    enum: ["full", "backend-only", "frontend-only"]
steps:
  - id: noop
    type: gate
    message: "noop"
    options: [approve]
""")
        errors = validate_workflow(definition)
        assert any("invalid default" in e for e in errors), errors

    def test_validate_workflow_exempts_integration_auto_sentinel(self):
        """``integration: auto`` is a runtime-resolved sentinel and must not fail validation."""
        from specify_cli.workflows.engine import WorkflowDefinition, validate_workflow

        definition = WorkflowDefinition.from_string("""
schema_version: "1.0"
workflow:
  id: "auto-ok"
  name: "Auto OK"
  version: "1.0.0"
inputs:
  integration:
    type: string
    default: "auto"
    enum: ["copilot", "claude", "gemini"]
steps:
  - id: noop
    type: gate
    message: "noop"
    options: [approve]
""")
        errors = validate_workflow(definition)
        assert not any("invalid default" in e for e in errors), errors

    def test_validate_workflow_still_checks_type_for_auto_sentinel(self):
        """The ``auto`` exemption only skips enum-membership; declared type is still enforced."""
        from specify_cli.workflows.engine import WorkflowDefinition, validate_workflow

        definition = WorkflowDefinition.from_string("""
schema_version: "1.0"
workflow:
  id: "auto-bad-type"
  name: "Auto Bad Type"
  version: "1.0.0"
inputs:
  integration:
    type: number
    default: "auto"
steps:
  - id: noop
    type: gate
    message: "noop"
    options: [approve]
""")
        errors = validate_workflow(definition)
        assert any("invalid default" in e for e in errors), errors

    def test_validate_workflow_rejects_bool_default_for_number_type(self):
        """``type: number`` paired with a bool default must fail — bool is a
        subclass of int so ``float(True)`` would otherwise silently coerce
        ``true`` to ``1``.
        """
        from specify_cli.workflows.engine import WorkflowDefinition, validate_workflow

        definition = WorkflowDefinition.from_string("""
schema_version: "1.0"
workflow:
  id: "bool-as-number"
  name: "Bool As Number"
  version: "1.0.0"
inputs:
  count:
    type: number
    default: true
steps:
  - id: noop
    type: gate
    message: "noop"
    options: [approve]
""")
        errors = validate_workflow(definition)
        assert any("invalid default" in e for e in errors), errors

    @pytest.mark.parametrize(
        "number", [2**53 + 1, 1792234567890123456, 2**63 - 1, -(2**63 - 1)]
    )
    @pytest.mark.parametrize("as_string", [False, True])
    def test_number_input_preserves_integer_precision(self, number, as_string):
        from specify_cli.workflows.engine import WorkflowEngine

        value = str(number) if as_string else number
        resolved = WorkflowEngine._coerce_input("record_id", value, {"type": "number"})

        assert resolved == number
        assert isinstance(resolved, int)

    @pytest.mark.parametrize(
        ("value", "expected"),
        [
            ("0", 0), (" +42 ", 42), ("-42", -42),
            ("3.5", 3.5), ("5.0", 5), ("1e3", 1000),
        ],
    )
    def test_number_input_retains_existing_numeric_forms(self, value, expected):
        from specify_cli.workflows.engine import WorkflowEngine

        resolved = WorkflowEngine._coerce_input("count", value, {"type": "number"})

        assert resolved == expected
        assert type(resolved) is type(expected)

    @pytest.mark.parametrize(
        "value", [True, False, None, [], "invalid", "nan", "inf", "-inf"]
    )
    def test_number_input_rejects_non_numbers_and_non_finite_values(self, value):
        from specify_cli.workflows.engine import WorkflowEngine

        with pytest.raises(ValueError, match="expected a number"):
            WorkflowEngine._coerce_input("count", value, {"type": "number"})

    def test_number_input_checks_enum_without_rounding(self):
        from specify_cli.workflows.engine import WorkflowEngine

        number = 2**53 + 1
        definition = {"type": "number", "enum": [number]}
        assert WorkflowEngine._coerce_input("record_id", str(number), definition) == number
        with pytest.raises(ValueError, match="not in allowed values"):
            WorkflowEngine._coerce_input("record_id", str(number - 1), definition)

    def test_coerce_number_input_rejects_infinity_cleanly(self):
        """An infinite float must surface as a clean ValueError (like NaN), not
        let ``int(inf)``'s OverflowError escape: ``int()`` of an infinity raises
        OverflowError, which is not ValueError/TypeError.
        """
        from specify_cli.workflows.engine import WorkflowEngine

        for value in (float("inf"), float("-inf"), "inf", "Infinity", "-inf"):
            with pytest.raises(ValueError, match="expected a number"):
                WorkflowEngine._coerce_input("count", value, {"type": "number"})
        # Finite values still coerce (whole floats normalize to int).
        assert WorkflowEngine._coerce_input("count", 5.0, {"type": "number"}) == 5
        assert WorkflowEngine._coerce_input("count", 3.5, {"type": "number"}) == 3.5

    def test_coerce_input_rejects_non_list_enum_cleanly(self):
        """A non-list ``enum`` (scalar or string) must raise a clean ValueError,
        not the raw ``TypeError`` from the ``value not in enum`` membership test.

        A scalar (``enum: 5``) makes ``value not in 5`` raise
        ``TypeError: argument of type 'int' is not iterable``. A bare string
        (``enum: "abc"``) is silently wrong instead — ``value in "abc"`` is a
        substring test, not enum membership — so it must be rejected too.
        """
        from specify_cli.workflows.engine import WorkflowEngine

        for bad_enum in (5, True, "abc", {"a": 1}):
            with pytest.raises(ValueError, match="invalid 'enum': must be a list"):
                WorkflowEngine._coerce_input(
                    "scope", "x", {"type": "string", "enum": bad_enum}
                )
        # A valid list ``enum`` still works, and ``None`` means "no enum".
        assert (
            WorkflowEngine._coerce_input(
                "scope", "a", {"type": "string", "enum": ["a", "b"]}
            )
            == "a"
        )
        assert (
            WorkflowEngine._coerce_input("scope", "x", {"type": "string"}) == "x"
        )

    def test_validate_workflow_rejects_non_list_enum(self):
        """A non-list ``enum`` must be reported as an error, not crash
        ``validate_workflow``. The membership test would raise ``TypeError``,
        which escapes its ``except ValueError`` and breaks the "return a list of
        errors, never raise" contract. This must surface even with no ``default``
        present (the coercion path that would otherwise catch it is only reached
        when a default exists).
        """
        from specify_cli.workflows.engine import WorkflowDefinition, validate_workflow

        definition = WorkflowDefinition.from_string("""
schema_version: "1.0"
workflow:
  id: "bad-enum"
  name: "Bad Enum"
  version: "1.0.0"
inputs:
  scope:
    type: string
    enum: 5
steps:
  - id: noop
    type: gate
    message: "noop"
    options: [approve]
""")
        errors = validate_workflow(definition)
        assert any("invalid 'enum': must be a list" in e for e in errors), errors

    def test_resolve_inputs_rejects_non_list_enum_at_runtime(self, project_dir):
        """``execute()`` accepts unvalidated definitions, so a non-list ``enum``
        can reach ``_resolve_inputs`` at run time. It must fail with a clean
        ValueError rather than the raw ``TypeError`` from the membership test.
        """
        from specify_cli.workflows.engine import WorkflowEngine, WorkflowDefinition

        definition = WorkflowDefinition.from_string("""
schema_version: "1.0"
workflow:
  id: "runtime-bad-enum"
  name: "Runtime Bad Enum"
  version: "1.0.0"
inputs:
  scope:
    type: string
    enum: 5
""")
        engine = WorkflowEngine(project_dir)
        with pytest.raises(ValueError, match="invalid 'enum': must be a list"):
            engine._resolve_inputs(definition, {"scope": "x"})

    def test_non_list_enum_on_integration_auto_still_rejected(self, project_dir):
        """The ``integration: auto`` sentinel strips a *list* ``enum`` before
        coercion (enum-membership is a runtime concern for ``auto``). A non-list
        ``enum`` must NOT be silently stripped by that path — it is still an
        authoring error and must fail with the clean shape ValueError.
        """
        from specify_cli.workflows.engine import WorkflowEngine, WorkflowDefinition

        definition = WorkflowDefinition.from_string("""
schema_version: "1.0"
workflow:
  id: "auto-bad-enum"
  name: "Auto Bad Enum"
  version: "1.0.0"
inputs:
  integration:
    type: string
    default: "auto"
    enum: 5
""")
        engine = WorkflowEngine(project_dir)
        with pytest.raises(ValueError, match="invalid 'enum': must be a list"):
            engine._resolve_inputs(definition, {})

    def test_validate_workflow_rejects_infinite_default_for_number_type(self):
        """``type: number`` with an infinite default (YAML ``.inf``) must be
        reported as an error, not raise. ``int(inf)`` raises OverflowError during
        coercion, which previously escaped validate_workflow's ValueError handler
        and broke its "return a list of errors" contract.
        """
        from specify_cli.workflows.engine import WorkflowDefinition, validate_workflow

        definition = WorkflowDefinition.from_string("""
schema_version: "1.0"
workflow:
  id: "inf-as-number"
  name: "Inf As Number"
  version: "1.0.0"
inputs:
  count:
    type: number
    default: .inf
steps:
  - id: noop
    type: gate
    message: "noop"
    options: [approve]
""")
        errors = validate_workflow(definition)
        assert any("invalid default" in e for e in errors), errors

    def test_validate_workflow_rejects_non_string_default_for_string_type(self):
        """``type: string`` must require an actual string — a numeric YAML
        default like ``5`` would otherwise slip through unvalidated.
        """
        from specify_cli.workflows.engine import WorkflowDefinition, validate_workflow

        definition = WorkflowDefinition.from_string("""
schema_version: "1.0"
workflow:
  id: "number-as-string"
  name: "Number As String"
  version: "1.0.0"
inputs:
  label:
    type: string
    default: 5
steps:
  - id: noop
    type: gate
    message: "noop"
    options: [approve]
""")
        errors = validate_workflow(definition)
        assert any("invalid default" in e for e in errors), errors

    def test_while_loop_condition_reads_latest_iteration(self, project_dir):
        """Regression: while-loop condition must see updated step output
        from the most recent iteration, not stale iteration-0 data.

        See https://github.com/github/spec-kit/issues/2592
        """
        from specify_cli.workflows.engine import WorkflowEngine, WorkflowDefinition
        from specify_cli.workflows.base import RunStatus

        # Shell step echoes a counter via a file.
        # Condition: exit_code != 0 means "keep looping" — but a non-zero
        # exit code would mark the step FAILED and abort the run, so we
        # use stdout-based comparison instead.
        #
        # Iteration 0: counter=1, echoes "1" → not "done" → loop continues
        # Iteration 1: counter=2, echoes "done" → condition false → stop
        # Without the fix, condition always reads iteration-0 stdout,
        # so the loop runs all max_iterations.
        import sys

        counter_file = project_dir / ".counter"
        counter_file.write_text("0", encoding="utf-8")
        py = sys.executable
        script_file = project_dir / "_tick.py"
        script_file.write_text(
            f"import pathlib; p = pathlib.Path(r'{counter_file}')\n"
            "n = int(p.read_text()) + 1; p.write_text(str(n))\n"
            "print('done' if n >= 2 else str(n), end='')\n",
            encoding="utf-8",
        )

        yaml_str = f"""
schema_version: "1.0"
workflow:
  id: "while-condition-update"
  name: "While Condition Update"
  version: "1.0.0"
steps:
  - id: retry-loop
    type: while
    condition: "{{{{ 'done' not in steps.attempt.output.stdout }}}}"
    max_iterations: 5
    steps:
      - id: attempt
        type: shell
        run: '"{py}" "{script_file}"'
"""
        definition = WorkflowDefinition.from_string(yaml_str)
        engine = WorkflowEngine(project_dir)
        state = engine.execute(definition)

        assert state.status == RunStatus.COMPLETED
        # The unprefixed key should reflect the latest iteration's result.
        assert state.step_results["attempt"]["output"]["stdout"] == "done"
        # Namespaced iteration-1 result should also exist.
        assert "retry-loop:attempt:1" in state.step_results
        # Counter should be 2 (iteration 0 + iteration 1), not 5.
        assert counter_file.read_text(encoding="utf-8").strip() == "2"

    def test_do_while_loop_condition_reads_latest_iteration(self, project_dir):
        """Regression: do-while loop condition must also see updated output.

        See https://github.com/github/spec-kit/issues/2592
        """
        from specify_cli.workflows.engine import WorkflowEngine, WorkflowDefinition
        from specify_cli.workflows.base import RunStatus

        import sys

        counter_file = project_dir / ".counter"
        counter_file.write_text("0", encoding="utf-8")
        py = sys.executable
        script_file = project_dir / "_tick.py"
        script_file.write_text(
            f"import pathlib; p = pathlib.Path(r'{counter_file}')\n"
            "n = int(p.read_text()) + 1; p.write_text(str(n))\n"
            "print('done' if n >= 2 else str(n), end='')\n",
            encoding="utf-8",
        )

        yaml_str = f"""
schema_version: "1.0"
workflow:
  id: "do-while-condition-update"
  name: "Do While Condition Update"
  version: "1.0.0"
steps:
  - id: retry-loop
    type: do-while
    condition: "{{{{ 'done' not in steps.attempt.output.stdout }}}}"
    max_iterations: 5
    steps:
      - id: attempt
        type: shell
        run: '"{py}" "{script_file}"'
"""
        definition = WorkflowDefinition.from_string(yaml_str)
        engine = WorkflowEngine(project_dir)
        state = engine.execute(definition)

        assert state.status == RunStatus.COMPLETED
        assert state.step_results["attempt"]["output"]["stdout"] == "done"
        assert counter_file.read_text(encoding="utf-8").strip() == "2"

    def test_while_loop_runs_to_max_when_condition_stays_true(self, project_dir):
        """While loop must still run to max_iterations when the condition
        never becomes false — copy-back must not break this path.

        See https://github.com/github/spec-kit/issues/2592
        """
        from specify_cli.workflows.engine import WorkflowEngine, WorkflowDefinition
        from specify_cli.workflows.base import RunStatus

        import sys

        counter_file = project_dir / ".counter"
        counter_file.write_text("0", encoding="utf-8")
        py = sys.executable
        script_file = project_dir / "_tick.py"
        script_file.write_text(
            f"import pathlib; p = pathlib.Path(r'{counter_file}')\n"
            "n = int(p.read_text()) + 1; p.write_text(str(n))\n"
            "print('pending', end='')\n",
            encoding="utf-8",
        )

        yaml_str = f"""
schema_version: "1.0"
workflow:
  id: "while-max-iterations"
  name: "While Max Iterations"
  version: "1.0.0"
steps:
  - id: retry-loop
    type: while
    condition: "{{{{ 'done' not in steps.tick.output.stdout }}}}"
    max_iterations: 3
    steps:
      - id: tick
        type: shell
        run: '"{py}" "{script_file}"'
"""
        definition = WorkflowDefinition.from_string(yaml_str)
        engine = WorkflowEngine(project_dir)
        state = engine.execute(definition)

        assert state.status == RunStatus.COMPLETED
        # All 3 iterations ran (iteration 0 + 2 loop iterations).
        assert counter_file.read_text(encoding="utf-8").strip() == "3"
        # Unprefixed key holds the last iteration's result.
        assert state.step_results["tick"]["output"]["stdout"] == "pending"
        # Namespaced keys for loop iterations exist.
        assert "retry-loop:tick:1" in state.step_results
        assert "retry-loop:tick:2" in state.step_results

    def test_loop_with_bool_max_iterations_uses_default_cap(self, project_dir):
        """A boolean max_iterations must fall back to the default cap of 10,
        not be treated as the int 1 (bool-is-int trap).

        ``max_iterations: true`` would otherwise slip past the int check
        (``isinstance(True, int)`` is True and ``True < 1`` is False) and
        cap the loop at ``range(True - 1) == range(0)`` — a single
        iteration. ``execute()`` does not auto-validate, so the engine's own
        guard is the only line of defence here.
        """
        from specify_cli.workflows.engine import WorkflowEngine, WorkflowDefinition
        from specify_cli.workflows.base import RunStatus

        import sys

        counter_file = project_dir / ".counter"
        counter_file.write_text("0", encoding="utf-8")
        py = sys.executable
        script_file = project_dir / "_tick.py"
        script_file.write_text(
            f"import pathlib; p = pathlib.Path(r'{counter_file}')\n"
            "n = int(p.read_text()) + 1; p.write_text(str(n))\n"
            "print('pending', end='')\n",
            encoding="utf-8",
        )

        yaml_str = f"""
schema_version: "1.0"
workflow:
  id: "while-bool-max-iterations"
  name: "While Bool Max Iterations"
  version: "1.0.0"
steps:
  - id: retry-loop
    type: while
    condition: "{{{{ 'done' not in steps.tick.output.stdout }}}}"
    max_iterations: true
    steps:
      - id: tick
        type: shell
        run: '"{py}" "{script_file}"'
"""
        definition = WorkflowDefinition.from_string(yaml_str)
        engine = WorkflowEngine(project_dir)
        state = engine.execute(definition)

        assert state.status == RunStatus.COMPLETED
        # Falls back to the default cap of 10, not range(True - 1) == 1 run.
        assert counter_file.read_text(encoding="utf-8").strip() == "10"

    def test_do_while_loop_runs_to_max_when_condition_stays_true(self, project_dir):
        """Do-while loop must still run to max_iterations when the condition
        never becomes false.

        See https://github.com/github/spec-kit/issues/2592
        """
        from specify_cli.workflows.engine import WorkflowEngine, WorkflowDefinition
        from specify_cli.workflows.base import RunStatus

        import sys

        counter_file = project_dir / ".counter"
        counter_file.write_text("0", encoding="utf-8")
        py = sys.executable
        script_file = project_dir / "_tick.py"
        script_file.write_text(
            f"import pathlib; p = pathlib.Path(r'{counter_file}')\n"
            "n = int(p.read_text()) + 1; p.write_text(str(n))\n"
            "print('pending', end='')\n",
            encoding="utf-8",
        )

        yaml_str = f"""
schema_version: "1.0"
workflow:
  id: "do-while-max-iterations"
  name: "Do While Max Iterations"
  version: "1.0.0"
steps:
  - id: retry-loop
    type: do-while
    condition: "{{{{ 'done' not in steps.tick.output.stdout }}}}"
    max_iterations: 3
    steps:
      - id: tick
        type: shell
        run: '"{py}" "{script_file}"'
"""
        definition = WorkflowDefinition.from_string(yaml_str)
        engine = WorkflowEngine(project_dir)
        state = engine.execute(definition)

        assert state.status == RunStatus.COMPLETED
        assert counter_file.read_text(encoding="utf-8").strip() == "3"
        assert state.step_results["tick"]["output"]["stdout"] == "pending"

    def test_while_loop_multi_step_body_inter_step_refs(self, project_dir):
        """Multi-step loop body: step B must see step A's output from the
        current iteration, not a stale previous one.

        See https://github.com/github/spec-kit/issues/2592
        """
        from specify_cli.workflows.engine import WorkflowEngine, WorkflowDefinition
        from specify_cli.workflows.base import RunStatus

        import sys

        counter_file = project_dir / ".counter"
        counter_file.write_text("0", encoding="utf-8")
        py = sys.executable

        # Step A: increments counter file, echoes the value.
        step_a_file = project_dir / "_step_a.py"
        step_a_file.write_text(
            f"import pathlib; p = pathlib.Path(r'{counter_file}')\n"
            "n = int(p.read_text()) + 1; p.write_text(str(n))\n"
            "print(str(n), end='')\n",
            encoding="utf-8",
        )

        # Step B uses {{ steps.step-a.output.stdout }} expression
        # substitution in its run command so the engine resolves the
        # aliased unprefixed key — this is the real inter-step test.
        yaml_str = f"""
schema_version: "1.0"
workflow:
  id: "while-multi-step"
  name: "While Multi Step"
  version: "1.0.0"
steps:
  - id: retry-loop
    type: while
    condition: "{{{{ 'done' not in steps.step-a.output.stdout }}}}"
    max_iterations: 3
    steps:
      - id: step-a
        type: shell
        run: '"{py}" "{step_a_file}"'
      - id: step-b
        type: shell
        run: "echo b-saw-{{{{ steps.step-a.output.stdout }}}}"
"""
        definition = WorkflowDefinition.from_string(yaml_str)
        engine = WorkflowEngine(project_dir)
        state = engine.execute(definition)

        assert state.status == RunStatus.COMPLETED
        # Both unprefixed keys reflect the latest iteration's results.
        assert state.step_results["step-a"]["output"]["stdout"] == "3"
        # Step B saw step A's output via expression substitution.
        assert "b-saw-3" in state.step_results["step-b"]["output"]["stdout"]
        # Namespaced keys exist for loop iterations.
        assert "retry-loop:step-a:1" in state.step_results
        assert "retry-loop:step-b:1" in state.step_results
        assert "retry-loop:step-a:2" in state.step_results
        assert "retry-loop:step-b:2" in state.step_results


# ===== context.run_id Tests =====
#
# End-to-end coverage for the `{{ context.run_id }}` template
# variable introduced in issue #2590. Locks resolution inside the
# three step types the acceptance criteria called out — shell `run:`,
# command `input.args:`, and switch `expression:` — plus the
# "workflow doesn't reference it" backward-compat path.


class TestContextRunId:
    """End-to-end tests for `{{ context.run_id }}` in workflow YAML."""

    def test_shell_run_resolves_run_id(self, project_dir):
        """`run: "echo {{ context.run_id }}"` substitutes the
        engine-assigned run id into the spawned shell, and the
        same value appears on `state.run_id`.
        """
        from specify_cli.workflows.engine import WorkflowDefinition, WorkflowEngine

        definition = WorkflowDefinition.from_string("""
schema_version: "1.0"
workflow:
  id: "stamp-run-id"
  name: "Stamp Run Id"
  version: "1.0.0"
steps:
  - id: stamp
    type: shell
    run: "echo RUN_ID={{ context.run_id }}"
""")
        engine = WorkflowEngine(project_dir)
        state = engine.execute(definition, run_id="abc12345")

        assert state.run_id == "abc12345"
        stdout = state.step_results["stamp"]["output"]["stdout"]
        assert stdout.strip() == "RUN_ID=abc12345"

    def test_command_input_args_resolves_run_id(self, project_dir):
        """`input.args: "{{ context.run_id }}"` is resolved by
        `CommandStep` and recorded in step output, even when CLI
        dispatch is unavailable (no integration installed). Covers
        the artifact-metadata use case from the issue.
        """
        from unittest.mock import patch
        from specify_cli.workflows.engine import WorkflowDefinition, WorkflowEngine

        definition = WorkflowDefinition.from_string("""
schema_version: "1.0"
workflow:
  id: "command-stamp"
  name: "Command Stamp"
  version: "1.0.0"
  integration: claude
steps:
  - id: tag-artifact
    command: speckit.specify
    input:
      args: "{{ context.run_id }}"
""")
        engine = WorkflowEngine(project_dir)
        with patch(
            "specify_cli.workflows.step.command.shutil.which",
            return_value=None,
        ):
            state = engine.execute(definition, run_id="cafef00d")

        # Even when dispatch fails (no CLI), the resolved input is
        # recorded so downstream observers see the run id in artifact
        # metadata.
        assert state.step_results["tag-artifact"]["output"]["input"]["args"] == "cafef00d"

    def test_switch_expression_matches_on_run_id(self, project_dir):
        """`switch` over `{{ context.run_id }}` matches against case
        keys, and the nested branch can ALSO reference
        `{{ context.run_id }}`. Demonstrates the run id is a
        first-class value in the expression engine (not just a
        string-interpolation token) AND that it propagates into
        nested step execution via the recursive `_execute_steps`
        traversal.
        """
        from specify_cli.workflows.engine import WorkflowDefinition, WorkflowEngine
        from specify_cli.workflows.base import RunStatus

        definition = WorkflowDefinition.from_string("""
schema_version: "1.0"
workflow:
  id: "switch-on-run-id"
  name: "Switch On Run Id"
  version: "1.0.0"
steps:
  - id: route
    type: switch
    expression: "{{ context.run_id }}"
    cases:
      target-run:
        - id: matched-branch
          type: shell
          run: "echo nested-run-id={{ context.run_id }}"
    default:
      - id: default-branch
        type: shell
        run: "echo defaulted"
""")
        engine = WorkflowEngine(project_dir)
        state = engine.execute(definition, run_id="target-run")

        assert state.status == RunStatus.COMPLETED
        assert state.step_results["route"]["output"]["matched_case"] == "target-run"
        assert "matched-branch" in state.step_results
        assert "default-branch" not in state.step_results
        # The nested branch sees the same run id — propagation through
        # recursive `_execute_steps` is intact.
        nested_stdout = state.step_results["matched-branch"]["output"]["stdout"]
        assert nested_stdout.strip() == "nested-run-id=target-run"

    def test_workflow_without_context_reference_unchanged(self, project_dir):
        """Workflows that do not reference `{{ context.run_id }}`
        continue to run exactly as before. Locks the byte-equivalent
        default required by the issue's acceptance criteria.
        """
        from specify_cli.workflows.engine import WorkflowDefinition, WorkflowEngine
        from specify_cli.workflows.base import RunStatus

        definition = WorkflowDefinition.from_string("""
schema_version: "1.0"
workflow:
  id: "no-context-ref"
  name: "No Context Ref"
  version: "1.0.0"
steps:
  - id: only-step
    type: shell
    run: "echo hello"
""")
        engine = WorkflowEngine(project_dir)
        state = engine.execute(definition)

        assert state.status == RunStatus.COMPLETED
        assert state.step_results["only-step"]["output"]["stdout"].strip() == "hello"

    def test_run_id_uses_speckit_workflow_run_id_env_override(self, project_dir, monkeypatch):
        """When no run_id argument is provided, SPECKIT_WORKFLOW_RUN_ID overrides the auto-generated run ID."""
        from specify_cli.workflows.engine import WorkflowDefinition, WorkflowEngine

        monkeypatch.setenv("SPECKIT_WORKFLOW_RUN_ID", "env-run-123")
        definition = WorkflowDefinition.from_string("""
schema_version: "1.0"
workflow:
  id: "env-run-id"
  name: "Env Run Id"
  version: "1.0.0"
steps:
  - id: stamp
    type: shell
    run: "echo {{ context.run_id }}"
""")
        state = WorkflowEngine(project_dir).execute(definition)

        assert state.run_id == "env-run-123"
        assert state.step_results["stamp"]["output"]["stdout"].strip() == "env-run-123"

    def test_run_id_arg_takes_precedence_over_env_override(self, project_dir, monkeypatch):
        """Explicit run_id keeps existing precedence over SPECKIT_WORKFLOW_RUN_ID."""
        from specify_cli.workflows.engine import WorkflowDefinition, WorkflowEngine

        monkeypatch.setenv("SPECKIT_WORKFLOW_RUN_ID", "env-run-123")
        definition = WorkflowDefinition.from_string("""
schema_version: "1.0"
workflow:
  id: "explicit-run-id"
  name: "Explicit Run Id"
  version: "1.0.0"
steps:
  - id: stamp
    type: shell
    run: "echo {{ context.run_id }}"
""")
        state = WorkflowEngine(project_dir).execute(definition, run_id="explicit-456")

        assert state.run_id == "explicit-456"
        assert state.step_results["stamp"]["output"]["stdout"].strip() == "explicit-456"


# ===== context.workflow_dir Tests =====


class TestContextWorkflowDir:
    """Tests for `{{ context.workflow_dir }}` and `SPECKIT_WORKFLOW_DIR`."""

    def test_context_workflow_dir_resolves(self):
        """``{{ context.workflow_dir }}`` resolves to ``StepContext.workflow_dir``."""
        from specify_cli.workflows.expressions import evaluate_expression
        from specify_cli.workflows.base import StepContext

        ctx = StepContext(workflow_dir="/home/user/my-workflow")
        assert evaluate_expression("{{ context.workflow_dir }}", ctx) == "/home/user/my-workflow"

    def test_context_workflow_dir_defaults_to_empty_when_unset(self):
        """``{{ context.workflow_dir }}`` resolves to ``""`` when no source
        path is available (string-loaded workflows, dry-run).
        """
        from specify_cli.workflows.expressions import evaluate_expression
        from specify_cli.workflows.base import StepContext

        ctx = StepContext()
        assert evaluate_expression("{{ context.workflow_dir }}", ctx) == ""

    def test_context_workflow_dir_string_interpolation(self):
        """Workflow dir interpolates inside a larger template string."""
        from specify_cli.workflows.expressions import evaluate_expression
        from specify_cli.workflows.base import StepContext

        ctx = StepContext(workflow_dir="/opt/workflows/setup")
        result = evaluate_expression("cp {{ context.workflow_dir }}/config.yml .", ctx)
        assert result == "cp /opt/workflows/setup/config.yml ."

    def test_step_context_workflow_dir(self):
        """StepContext accepts and stores workflow_dir."""
        from specify_cli.workflows.base import StepContext

        ctx = StepContext(workflow_dir="/some/path")
        assert ctx.workflow_dir == "/some/path"

        ctx_none = StepContext()
        assert ctx_none.workflow_dir is None

    def test_from_yaml_sets_workflow_dir(self, project_dir):
        """Workflow loaded from a YAML file has workflow_dir set to the
        file's parent directory.
        """
        from specify_cli.workflows.engine import WorkflowDefinition, WorkflowEngine

        wf_dir = project_dir / "my-workflows"
        wf_dir.mkdir()
        wf_file = wf_dir / "setup.yml"
        wf_file.write_text("""
schema_version: "1.0"
workflow:
  id: "from-yaml"
  name: "From YAML"
  version: "1.0.0"
steps:
  - id: check-dir
    type: shell
    run: "echo DIR={{ context.workflow_dir }}"
""")
        definition = WorkflowDefinition.from_yaml(wf_file)
        engine = WorkflowEngine(project_dir)
        state = engine.execute(definition)

        stdout = state.step_results["check-dir"]["output"]["stdout"]
        assert stdout.strip() == f"DIR={wf_dir.resolve()}"

    def test_from_string_has_empty_workflow_dir(self, project_dir):
        """String-loaded workflows have empty workflow_dir."""
        from specify_cli.workflows.engine import WorkflowDefinition, WorkflowEngine

        definition = WorkflowDefinition.from_string("""
schema_version: "1.0"
workflow:
  id: "from-string"
  name: "From String"
  version: "1.0.0"
steps:
  - id: check-dir
    type: shell
    run: "echo DIR={{ context.workflow_dir }}"
""")
        engine = WorkflowEngine(project_dir)
        state = engine.execute(definition)

        stdout = state.step_results["check-dir"]["output"]["stdout"]
        assert stdout.strip() == "DIR="

    def test_shell_step_receives_speckit_workflow_dir_env_var(self, project_dir):
        """Shell steps receive SPECKIT_WORKFLOW_DIR in their environment."""
        from specify_cli.workflows.engine import WorkflowDefinition, WorkflowEngine
        import sys

        wf_dir = project_dir / "wf"
        wf_dir.mkdir()
        wf_file = wf_dir / "workflow.yml"
        python = sys.executable.replace("\\", "/")
        wf_file.write_text(f"""
schema_version: "1.0"
workflow:
  id: "env-var-test"
  name: "Env Var Test"
  version: "1.0.0"
steps:
  - id: print-env
    type: shell
    run: '"{python}" -c "import os; print(os.environ.get(''SPECKIT_WORKFLOW_DIR'', ''UNSET''))"'
""")
        definition = WorkflowDefinition.from_yaml(wf_file)
        engine = WorkflowEngine(project_dir)
        state = engine.execute(definition)

        stdout = state.step_results["print-env"]["output"]["stdout"]
        assert stdout.strip() == str(wf_dir.resolve())

    def test_shell_step_no_env_var_when_workflow_dir_unset(self, project_dir, monkeypatch):
        """Shell steps do not set SPECKIT_WORKFLOW_DIR for string-loaded workflows."""
        from specify_cli.workflows.engine import WorkflowDefinition, WorkflowEngine
        import sys

        monkeypatch.delenv("SPECKIT_WORKFLOW_DIR", raising=False)

        python = sys.executable.replace("\\", "/")
        definition = WorkflowDefinition.from_string(f"""
schema_version: "1.0"
workflow:
  id: "no-env-var"
  name: "No Env Var"
  version: "1.0.0"
steps:
  - id: check-env
    type: shell
    run: '"{python}" -c "import os; print(os.environ.get(''SPECKIT_WORKFLOW_DIR'', ''UNSET''))"'
""")
        engine = WorkflowEngine(project_dir)
        state = engine.execute(definition)

        stdout = state.step_results["check-env"]["output"]["stdout"]
        assert stdout.strip() == "UNSET"

    def test_resume_preserves_original_workflow_dir(self, project_dir):
        """Resumed workflow uses the original source directory, not the
        run-directory copy path.
        """
        from specify_cli.workflows.engine import WorkflowDefinition, WorkflowEngine
        from specify_cli.workflows.base import RunStatus

        wf_dir = project_dir / "original-source"
        wf_dir.mkdir()
        wf_file = wf_dir / "resumable.yml"
        wf_file.write_text("""
schema_version: "1.0"
workflow:
  id: "resumable"
  name: "Resumable"
  version: "1.0.0"
steps:
  - id: gate-step
    type: gate
    message: "Approve?"
  - id: after-gate
    type: shell
    run: "echo DIR={{ context.workflow_dir }}"
""")
        definition = WorkflowDefinition.from_yaml(wf_file)
        engine = WorkflowEngine(project_dir)

        # Execute -- gate pauses the workflow
        state = engine.execute(definition)
        assert state.status == RunStatus.PAUSED
        assert state.workflow_dir == str(wf_dir.resolve())

        # Simulate gate approval by patching the gate step
        from unittest.mock import patch
        from specify_cli.workflows.base import StepResult

        with patch(
            "specify_cli.workflows.step.gate.GateStep.execute",
            return_value=StepResult(output={"approved": True}),
        ):
            state = engine.resume(state.run_id)

        assert state.status == RunStatus.COMPLETED
        stdout = state.step_results["after-gate"]["output"]["stdout"]
        assert stdout.strip() == f"DIR={wf_dir.resolve()}"

    def test_workflow_dir_persisted_in_state(self, project_dir):
        """workflow_dir is persisted in state.json and survives load/save."""
        from specify_cli.workflows.engine import WorkflowDefinition, WorkflowEngine, RunState

        wf_dir = project_dir / "persist-test"
        wf_dir.mkdir()
        wf_file = wf_dir / "workflow.yml"
        wf_file.write_text("""
schema_version: "1.0"
workflow:
  id: "persist-wfdir"
  name: "Persist WfDir"
  version: "1.0.0"
steps:
  - id: noop
    type: shell
    run: "echo ok"
""")
        definition = WorkflowDefinition.from_yaml(wf_file)
        engine = WorkflowEngine(project_dir)
        state = engine.execute(definition)

        # Reload state from disk and verify workflow_dir survived
        loaded = RunState.load(state.run_id, project_dir)
        assert loaded.workflow_dir == str(wf_dir.resolve())

    def test_installed_workflow_has_workflow_dir(self, project_dir):
        """Installed-by-ID workflows get workflow_dir pointing to the
        installation directory (.specify/workflows/<id>/).
        """
        from specify_cli.workflows.engine import WorkflowEngine
        from specify_cli.workflows.base import RunStatus

        wf_id = "installed-wfdir"
        install_dir = project_dir / ".specify" / "workflows" / wf_id
        install_dir.mkdir(parents=True)
        (install_dir / "workflow.yml").write_text("""
schema_version: "1.0"
workflow:
  id: "installed-wfdir"
  name: "Installed WfDir"
  version: "1.0.0"
steps:
  - id: check-dir
    type: shell
    run: "echo DIR={{ context.workflow_dir }}"
""")
        engine = WorkflowEngine(project_dir)
        definition = engine.load_workflow(wf_id)
        state = engine.execute(definition)

        assert state.status == RunStatus.COMPLETED
        stdout = state.step_results["check-dir"]["output"]["stdout"]
        assert stdout.strip() == f"DIR={install_dir.resolve()}"

    def test_workflow_dir_is_resolved_to_absolute(self, project_dir):
        """workflow_dir is resolved to an absolute path even when the
        source path is relative.
        """
        from specify_cli.workflows.engine import WorkflowDefinition, WorkflowEngine
        import os

        wf_dir = project_dir / "rel-test"
        wf_dir.mkdir()
        wf_file = wf_dir / "workflow.yml"
        wf_file.write_text("""
schema_version: "1.0"
workflow:
  id: "rel-path"
  name: "Relative Path"
  version: "1.0.0"
steps:
  - id: check
    type: shell
    run: "echo ok"
""")
        # Load via a relative path
        saved_cwd = os.getcwd()
        try:
            os.chdir(project_dir)
            rel_path = Path("rel-test/workflow.yml")
            definition = WorkflowDefinition.from_yaml(rel_path)
            engine = WorkflowEngine(project_dir)
            state = engine.execute(definition)
        finally:
            os.chdir(saved_cwd)

        assert Path(state.workflow_dir).is_absolute()
        assert state.workflow_dir == str(wf_dir.resolve())


# ===== continue_on_error Tests =====
#
# Locks the contract documented in workflows/README.md "Error Handling"
# section: when a step returns `StepResult(status=StepStatus.FAILED, ...)` and
# `continue_on_error: true` is declared, the engine records the step's
# `output` (with `exit_code` and `stderr` from the failure) and its
# `status` (sibling key on `steps.<id>`, not nested under `output`)
# and continues to the next sibling step instead of halting the run.
# Gate aborts (`output.aborted`) still halt regardless of the flag.
# Unhandled exceptions raised out of `step_impl.execute()` are out of
# scope for this flag — they propagate to `WorkflowEngine.execute()`
# and abort the run.


class TestWorkflowDispatchDefaultExecution:
    """Execution safeguards for defaults inherited by dispatch steps."""

    @pytest.mark.parametrize(
        "defaults",
        [
            {
                "integration": "claude",
                "model": "gpt-5",
                "options": {"max_tokens": 8000},
            },
            {"integration": None, "model": None, "options": None},
        ],
    )
    def test_execute_accepts_valid_and_null_dispatch_defaults(
        self, project_dir, defaults
    ):
        """Defaults with supported shapes remain executable without validation."""
        from specify_cli.workflows.base import RunStatus
        from specify_cli.workflows.engine import WorkflowDefinition, WorkflowEngine

        definition = WorkflowDefinition(
            {
                "workflow": {
                    "id": "valid-defaults",
                    "name": "Valid Defaults",
                    "version": "1.0.0",
                    **defaults,
                },
                "steps": [],
            }
        )

        state = WorkflowEngine(project_dir).execute(definition)

        assert state.status == RunStatus.COMPLETED
        assert state.step_results == {}


class TestContinueOnError:
    """Test the `continue_on_error` step-level field."""

    def test_undeclared_failure_halts_run(self, project_dir):
        """Default behaviour (no `continue_on_error`): a failing step
        halts the workflow run with `status == StepStatus.FAILED`.

        Locks the byte-equivalent default — workflows that do not
        declare the flag must behave exactly as before this feature.
        """
        from specify_cli.workflows.engine import WorkflowDefinition, WorkflowEngine
        from specify_cli.workflows.base import RunStatus

        definition = WorkflowDefinition.from_string("""
schema_version: "1.0"
workflow:
  id: "halt-on-fail"
  name: "Halt On Fail"
  version: "1.0.0"
steps:
  - id: fail-step
    type: shell
    run: "exit 7"
  - id: after
    type: shell
    run: "echo should-not-run"
""")
        engine = WorkflowEngine(project_dir)
        state = engine.execute(definition)

        assert state.status == RunStatus.FAILED
        assert "fail-step" in state.step_results
        assert state.step_results["fail-step"]["output"]["exit_code"] == 7
        # Subsequent step never executes when the flag is absent.
        assert "after" not in state.step_results

    def test_declared_and_fired_continues_run(self, project_dir):
        """`continue_on_error: true` + failing step: the run keeps
        going, the failed step's result is recorded, and the
        downstream step runs.
        """
        from specify_cli.workflows.engine import WorkflowDefinition, WorkflowEngine
        from specify_cli.workflows.base import RunStatus

        definition = WorkflowDefinition.from_string("""
schema_version: "1.0"
workflow:
  id: "continue-past-fail"
  name: "Continue Past Fail"
  version: "1.0.0"
steps:
  - id: flaky-step
    type: shell
    run: "exit 42"
    continue_on_error: true
  - id: after
    type: shell
    run: "echo did-run"
""")
        engine = WorkflowEngine(project_dir)
        state = engine.execute(definition)

        assert state.status == RunStatus.COMPLETED
        # Failed step's exit_code is preserved so downstream branching
        # can inspect it.
        assert state.step_results["flaky-step"]["output"]["exit_code"] == 42
        assert state.step_results["flaky-step"]["status"] == "failed"
        # Downstream step ran successfully.
        assert state.step_results["after"]["output"]["exit_code"] == 0

    def test_declared_but_step_succeeded_is_noop(self, project_dir):
        """`continue_on_error: true` on a step that succeeds is a
        no-op — the flag only changes behaviour on StepStatus.FAILED status.
        """
        from specify_cli.workflows.engine import WorkflowDefinition, WorkflowEngine
        from specify_cli.workflows.base import RunStatus

        definition = WorkflowDefinition.from_string("""
schema_version: "1.0"
workflow:
  id: "flag-but-success"
  name: "Flag But Success"
  version: "1.0.0"
steps:
  - id: ok-step
    type: shell
    run: "echo ok"
    continue_on_error: true
  - id: after
    type: shell
    run: "echo done"
""")
        engine = WorkflowEngine(project_dir)
        state = engine.execute(definition)

        assert state.status == RunStatus.COMPLETED
        assert state.step_results["ok-step"]["status"] == "completed"
        assert state.step_results["ok-step"]["output"]["exit_code"] == 0
        assert state.step_results["after"]["output"]["exit_code"] == 0

    def test_if_branch_routes_around_failure(self, project_dir):
        """End-to-end: `continue_on_error` + `if` cleanly routes around
        a failure. The recovery branch runs; the success branch does
        not.

        Mirrors the canonical usage pattern from the original feature
        discussion in issue #2591.
        """
        from specify_cli.workflows.engine import WorkflowDefinition, WorkflowEngine
        from specify_cli.workflows.base import RunStatus

        definition = WorkflowDefinition.from_string("""
schema_version: "1.0"
workflow:
  id: "route-around"
  name: "Route Around Failure"
  version: "1.0.0"
steps:
  - id: heavy-thing
    type: shell
    run: "exit 1"
    continue_on_error: true
  - id: check-result
    type: if
    condition: "{{ steps.heavy-thing.output.exit_code != 0 }}"
    then:
      - id: recovery
        type: shell
        run: "echo recovery-ran"
    else:
      - id: happy-path
        type: shell
        run: "echo happy-path-ran"
""")
        engine = WorkflowEngine(project_dir)
        state = engine.execute(definition)

        assert state.status == RunStatus.COMPLETED
        assert "recovery" in state.step_results
        assert "happy-path" not in state.step_results

    def test_gate_abort_still_halts_with_continue_on_error(
        self, project_dir, monkeypatch
    ):
        """`continue_on_error` does NOT override a deliberate gate
        abort. `output.aborted` always halts the run with
        `status == ABORTED`.

        Aborts are explicit operator decisions; continue_on_error
        is for transient/expected step failures only.
        """
        from specify_cli.workflows.engine import WorkflowDefinition, WorkflowEngine
        from specify_cli.workflows.base import RunStatus
        from specify_cli.workflows.step.gate import GateStep

        # Force the gate step into interactive mode and feed a "reject"
        # choice so the abort path actually runs in the test env (default
        # behaviour returns StepStatus.PAUSED when stdin is not a TTY).
        _force_gate_stdin(monkeypatch, tty=True)
        monkeypatch.setattr(
            GateStep, "_prompt", staticmethod(lambda _msg, _opts: "reject")
        )

        definition = WorkflowDefinition.from_string("""
schema_version: "1.0"
workflow:
  id: "gate-abort-halts"
  name: "Gate Abort Halts"
  version: "1.0.0"
steps:
  - id: gate-step
    type: gate
    message: "Approve?"
    options: [approve, reject]
    on_reject: abort
    continue_on_error: true
  - id: should-not-run
    type: shell
    run: "echo nope"
""")
        engine = WorkflowEngine(project_dir)
        state = engine.execute(definition)

        assert state.status == RunStatus.ABORTED
        assert "should-not-run" not in state.step_results

    def test_gate_reject_matches_case_insensitively(
        self, project_dir, monkeypatch
    ):
        """A capitalised reject option (`options: [Approve, Reject]`) still
        aborts the run. `validate` accepts a reject choice case-insensitively,
        so the runtime reject check must agree — a case-sensitive comparison
        would treat the echoed `Reject` as approval and silently run
        downstream steps.
        """
        from specify_cli.workflows.engine import WorkflowDefinition, WorkflowEngine
        from specify_cli.workflows.base import RunStatus
        from specify_cli.workflows.step.gate import GateStep

        # `_prompt` echoes the option's original casing, so the operator
        # picking "Reject" hands `execute` the capitalised string.
        _force_gate_stdin(monkeypatch, tty=True)
        monkeypatch.setattr(
            GateStep, "_prompt", staticmethod(lambda _msg, _opts: "Reject")
        )

        definition = WorkflowDefinition.from_string("""
schema_version: "1.0"
workflow:
  id: "gate-reject-case"
  name: "Gate Reject Case"
  version: "1.0.0"
steps:
  - id: gate-step
    type: gate
    message: "Approve?"
    options: [Approve, Reject]
    on_reject: abort
  - id: should-not-run
    type: shell
    run: "echo nope"
""")
        engine = WorkflowEngine(project_dir)
        state = engine.execute(definition)

        assert state.status == RunStatus.ABORTED
        assert "should-not-run" not in state.step_results

    def test_validation_rejects_non_bool_continue_on_error(self):
        """`continue_on_error` must be a literal boolean; coerced
        strings like `"true"` are rejected at validation time so
        authoring mistakes surface before execution.
        """
        from specify_cli.workflows.engine import (
            WorkflowDefinition,
            validate_workflow,
        )

        definition = WorkflowDefinition.from_string("""
schema_version: "1.0"
workflow:
  id: "bad-coe"
  name: "Bad COE"
  version: "1.0.0"
steps:
  - id: step-one
    type: shell
    run: "true"
    continue_on_error: "true"
""")
        errors = validate_workflow(definition)
        assert any(
            "continue_on_error" in e and "boolean" in e for e in errors
        ), errors

    def test_validation_accepts_bool_continue_on_error(self):
        """Boolean values pass validation cleanly."""
        from specify_cli.workflows.engine import (
            WorkflowDefinition,
            validate_workflow,
        )

        for value in (True, False):
            yaml_value = "true" if value else "false"
            definition = WorkflowDefinition.from_string(f"""
schema_version: "1.0"
workflow:
  id: "good-coe"
  name: "Good COE"
  version: "1.0.0"
steps:
  - id: step-one
    type: shell
    run: "true"
    continue_on_error: {yaml_value}
""")
            errors = validate_workflow(definition)
            assert errors == [], errors

    def test_engine_ignores_truthy_non_bool_continue_on_error(self, project_dir):
        """Defense-in-depth: even if a caller bypasses
        `validate_workflow()` and feeds the engine a definition with
        `continue_on_error: "true"` (a string), the engine must NOT
        honour the flag — only a literal boolean enables the
        behaviour. `WorkflowEngine.execute()` does not auto-validate
        (the `WorkflowEngine.load_workflow` docstring explicitly
        notes the definition is "not yet validated; call
        `validate_workflow()` or `engine.validate()` separately"),
        so the engine guards against truthy non-bool values itself
        via an identity check rather than truthiness.
        """
        from specify_cli.workflows.engine import WorkflowDefinition, WorkflowEngine
        from specify_cli.workflows.base import RunStatus

        # Bypass `validate_workflow()` — execute() is what would
        # be called by a caller that skipped validation.
        definition = WorkflowDefinition.from_string("""
schema_version: "1.0"
workflow:
  id: "string-coe"
  name: "String COE"
  version: "1.0.0"
steps:
  - id: fail-step
    type: shell
    run: "exit 1"
    continue_on_error: "true"
  - id: should-not-run
    type: shell
    run: "echo should-not-run"
""")
        engine = WorkflowEngine(project_dir)
        state = engine.execute(definition)

        # String "true" is truthy but not a literal boolean, so the
        # engine must treat the step as a halting failure.
        assert state.status == RunStatus.FAILED
        assert "should-not-run" not in state.step_results

    def test_continue_on_error_failure_not_surfaced_as_terminal_error(
        self, project_dir
    ):
        """A continue_on_error step's error must not be reported as the
        terminal run error when a later step fails for a different reason.

        Regression test: the engine sets state.error only at terminal
        branches, not in the continue_on_error branch. A handled failure
        must not leak into the run-level error.
        """
        from specify_cli.workflows.engine import WorkflowDefinition, WorkflowEngine
        from specify_cli.workflows.base import RunStatus

        definition = WorkflowDefinition.from_string("""
schema_version: "1.0"
workflow:
  id: "coe-leak"
  name: "COE Leak"
  version: "1.0.0"
steps:
  - id: handled-failure
    type: shell
    run: "exit 42"
    continue_on_error: true
  - id: terminal-failure
    type: shell
    run: "exit 7"
""")
        engine = WorkflowEngine(project_dir)
        state = engine.execute(definition)

        assert state.status == RunStatus.FAILED
        # The terminal error must be from the terminal-failure step, not
        # the handled-failure step.
        assert state.error is not None
        assert "42" not in (state.error or "")
        # The handled step's per-step error is still preserved.
        assert state.step_results["handled-failure"]["status"] == "failed"
        assert state.step_results["handled-failure"].get("error") is not None

    def test_unknown_step_type_sets_run_error(self, project_dir):
        """An unregistered step type fails the run with a descriptive
        run-level error persisted on state.error.

        The engine sets state.error at the unknown-step-type terminal
        branch, mirroring the other terminal failure paths.
        """
        from specify_cli.workflows.engine import WorkflowDefinition, WorkflowEngine
        from specify_cli.workflows.base import RunStatus

        # execute() bypasses validate_workflow(), which is what would
        # otherwise reject the unknown type up front.
        definition = WorkflowDefinition.from_string("""
schema_version: "1.0"
workflow:
  id: "unknown-type"
  name: "Unknown Type"
  version: "1.0.0"
steps:
  - id: mystery
    type: definitely-not-a-real-step
""")
        engine = WorkflowEngine(project_dir)
        state = engine.execute(definition)

        assert state.status == RunStatus.FAILED
        assert state.error == "Unknown step type: 'definitely-not-a-real-step'"

    def test_unknown_step_type_ignores_continue_on_error(self, project_dir):
        """A missing implementation is terminal even with recovery enabled."""
        from specify_cli.workflows.engine import WorkflowDefinition, WorkflowEngine
        from specify_cli.workflows.base import RunStatus

        definition = WorkflowDefinition.from_string("""
schema_version: "1.0"
workflow:
  id: "unknown-type-recovery"
  name: "Unknown Type Recovery"
  version: "1.0.0"
steps:
  - id: mystery
    type: definitely-not-a-real-step
    continue_on_error: true
  - id: after
    type: shell
    run: "echo should-not-run"
""")
        state = WorkflowEngine(project_dir).execute(definition)

        assert state.status == RunStatus.FAILED
        assert state.error == "Unknown step type: 'definitely-not-a-real-step'"
        assert "after" not in state.step_results
        events = [entry["event"] for entry in state.log_entries]
        assert "step_failed" in events
        assert "step_continue_on_error" not in events

    def test_unknown_step_type_events_match_main(self, project_dir):
        """Only step_started and step_failed, and no projected step result."""
        from specify_cli.workflows.engine import WorkflowDefinition, WorkflowEngine
        from specify_cli.workflows.base import RunStatus

        definition = WorkflowDefinition.from_string("""
schema_version: "1.0"
workflow:
  id: "unknown-type-events"
  name: "Unknown Type Events"
  version: "1.0.0"
steps:
  - id: mystery
    type: definitely-not-a-real-step
""")
        state = WorkflowEngine(project_dir).execute(definition)

        assert state.status == RunStatus.FAILED
        assert [
            entry["event"]
            for entry in state.log_entries
            if entry.get("step_id") == "mystery"
        ] == ["step_started", "step_failed"]
        assert "mystery" not in state.step_results


# ===== State Persistence Tests =====

class TestRunState:
    """Test RunState persistence and loading."""

    def test_save_and_load(self, project_dir):
        from specify_cli.workflows.engine import RunState
        from specify_cli.workflows.base import RunStatus

        state = RunState(
            run_id="test-run",
            workflow_id="test-workflow",
            project_root=project_dir,
        )
        state.status = RunStatus.RUNNING
        state.inputs = {"name": "login"}
        state.step_results = {
            "step-one": {
                "output": {"file": "spec.md"},
                "status": "completed",
            }
        }
        state.save()

        loaded = RunState.load("test-run", project_dir)
        assert loaded.run_id == "test-run"
        assert loaded.workflow_id == "test-workflow"
        assert loaded.status == RunStatus.RUNNING
        assert loaded.inputs == {"name": "login"}
        assert loaded.step_results == state.step_results

    def test_run_artifacts_keep_non_ascii_text_readable(self, project_dir):
        """state.json, inputs.json and log.jsonl are human-auditable run
        records, so non-ASCII text must be written as authored rather than
        as ``\\uXXXX`` escapes (#4875)."""
        from specify_cli.workflows.engine import RunState

        text = "演示:完整闭环 — ¿aprobar? 日本語"
        state = RunState(
            run_id="non-ascii-run",
            workflow_id="test-workflow",
            project_root=project_dir,
        )
        state.inputs = {"spec": text}
        state.step_results = {"gate": {"output": {"message": text}}}
        state.save()
        state.append_log({"event": "gate_message", "message": text})

        for name in ("state.json", "inputs.json", "log.jsonl"):
            raw = (state.runs_dir / name).read_text(encoding="utf-8")
            assert text in raw, name
            assert "\\u" not in raw, name

        loaded = RunState.load("non-ascii-run", project_dir)
        assert loaded.inputs == {"spec": text}
        assert loaded.step_results == state.step_results
        log_line = (state.runs_dir / "log.jsonl").read_text(encoding="utf-8")
        assert json.loads(log_line)["message"] == text

    def test_run_artifacts_round_trip_a_lone_surrogate(self, project_dir):
        """A lone surrogate (e.g. an undecodable byte in a CLI argument) cannot
        be encoded as UTF-8. It must still save, escaped, and load back intact
        instead of crashing the run."""
        from specify_cli.workflows.engine import RunState

        value = "bad byte: \udc80"
        state = RunState(
            run_id="surrogate-run",
            workflow_id="test-workflow",
            project_root=project_dir,
        )
        state.inputs = {"spec": value}
        state.save()
        state.append_log({"event": "input", "value": value})

        loaded = RunState.load("surrogate-run", project_dir)
        assert loaded.inputs == {"spec": value}
        log_line = (state.runs_dir / "log.jsonl").read_text(encoding="utf-8")
        assert json.loads(log_line)["value"] == value

    def test_workflow_snapshot_keeps_non_ascii_text_readable(self, project_dir):
        """The workflow.yml copied into the run directory is the definition as
        authored, so its non-ASCII text must not be escaped (#4875)."""
        from specify_cli.workflows.engine import WorkflowDefinition, WorkflowEngine

        name = "Demo Hello Pipeline (教学演示版)"
        wf_dir = project_dir / "non-ascii-snapshot"
        wf_dir.mkdir()
        wf_file = wf_dir / "workflow.yml"
        wf_file.write_text(
            f"""
schema_version: "1.0"
workflow:
  id: "non-ascii-snapshot"
  name: "{name}"
  version: "1.0.0"
steps:
  - id: noop
    type: shell
    run: "echo ok"
""",
            encoding="utf-8",
        )
        definition = WorkflowDefinition.from_yaml(wf_file)
        state = WorkflowEngine(project_dir).execute(definition)

        snapshot = state.runs_dir / "workflow.yml"
        raw = snapshot.read_text(encoding="utf-8")
        assert name in raw
        assert "\\u" not in raw and "\\x" not in raw
        assert yaml.safe_load(raw)["workflow"]["name"] == name

    @pytest.mark.parametrize("invalid_step_results", [None, [], "invalid", 1, True])
    def test_load_rejects_non_object_step_results(
        self, project_dir, invalid_step_results
    ):
        """Persisted step results must be a JSON object."""
        from specify_cli.workflows.engine import RunState

        state = RunState(
            run_id="invalid-results",
            workflow_id="test-workflow",
            project_root=project_dir,
        )
        state.save()
        state_path = state.runs_dir / "state.json"
        state_data = json.loads(state_path.read_text(encoding="utf-8"))
        state_data["step_results"] = invalid_step_results
        state_path.write_text(json.dumps(state_data), encoding="utf-8")

        with pytest.raises(ValueError, match="step_results.*JSON object"):
            RunState.load("invalid-results", project_dir)

    @pytest.mark.parametrize("invalid_result", [None, [], "invalid", 1, True])
    def test_load_rejects_non_object_step_result_records(
        self, project_dir, invalid_result
    ):
        """Each persisted step result must be a JSON object."""
        from specify_cli.workflows.engine import RunState

        state = RunState(
            run_id="invalid-record",
            workflow_id="test-workflow",
            project_root=project_dir,
        )
        state.save()
        state_path = state.runs_dir / "state.json"
        state_data = json.loads(state_path.read_text(encoding="utf-8"))
        state_data["step_results"] = {"step-one": invalid_result}
        state_path.write_text(json.dumps(state_data), encoding="utf-8")

        with pytest.raises(
            ValueError,
            match="step_results record 'step-one' must be a JSON object",
        ):
            RunState.load("invalid-record", project_dir)

    def test_load_defaults_missing_step_results_for_legacy_state(self, project_dir):
        """Legacy states without step results load with an empty mapping."""
        from specify_cli.workflows.engine import RunState

        state = RunState(
            run_id="legacy-results",
            workflow_id="test-workflow",
            project_root=project_dir,
        )
        state.save()
        state_path = state.runs_dir / "state.json"
        state_data = json.loads(state_path.read_text(encoding="utf-8"))
        state_data.pop("step_results")
        state_path.write_text(json.dumps(state_data), encoding="utf-8")

        loaded = RunState.load("legacy-results", project_dir)
        assert loaded.step_results == {}

    def test_load_not_found(self, project_dir):
        from specify_cli.workflows.engine import RunState

        with pytest.raises(FileNotFoundError):
            RunState.load("nonexistent", project_dir)

    def test_load_rejects_stored_run_id_mismatch(self, project_dir):
        """The state payload cannot redirect later writes to another run."""
        from specify_cli.workflows.engine import RunState

        run_dir = (
            project_dir
            / ".specify"
            / "workflows"
            / "runs"
            / "requested-run"
        )
        run_dir.mkdir(parents=True)
        (run_dir / "state.json").write_text(
            json.dumps(
                {
                    "run_id": "other-run",
                    "workflow_id": "test-workflow",
                    "status": "created",
                }
            ),
            encoding="utf-8",
        )

        with pytest.raises(
            ValueError,
            match="stored run_id 'other-run' does not match requested run_id 'requested-run'",
        ):
            RunState.load("requested-run", project_dir)

    @pytest.mark.parametrize(
        "bad_current_step_index",
        ["not-a-number", 1.5, -1, [0], {"index": 0}, True],
    )
    def test_load_rejects_invalid_current_step_index(
        self, project_dir, bad_current_step_index
    ):
        """Reject non-integer and negative resume indices at load time.

        ``bool`` is covered explicitly because it subclasses ``int``.
        """
        from specify_cli.workflows.engine import RunState

        run_dir = (
            project_dir / ".specify" / "workflows" / "runs" / "bad-index-run"
        )
        run_dir.mkdir(parents=True)
        (run_dir / "state.json").write_text(
            json.dumps(
                {
                    "run_id": "bad-index-run",
                    "workflow_id": "test-workflow",
                    "status": "paused",
                    "current_step_index": bad_current_step_index,
                }
            ),
            encoding="utf-8",
        )

        with pytest.raises(
            ValueError, match="'current_step_index' must be a non-negative integer"
        ):
            RunState.load("bad-index-run", project_dir)

    @pytest.mark.parametrize(
        ("installed_workflow_id", "installed_registry_root"),
        [
            ("", None),
            ("gated-wf\n", None),
            ("gated-wf", "relative-owner"),
        ],
    )
    def test_init_rejects_invalid_installed_origin(
        self, installed_workflow_id, installed_registry_root
    ):
        from specify_cli.workflows.engine import RunState

        with pytest.raises(ValueError, match="Invalid run state"):
            RunState(
                run_id="test-run",
                workflow_id="test-workflow",
                installed_workflow_id=installed_workflow_id,
                installed_registry_root=installed_registry_root,
            )

    def test_init_rejects_registry_root_without_workflow_id(
        self, project_dir
    ):
        from specify_cli.workflows.engine import RunState

        with pytest.raises(ValueError, match="requires"):
            RunState(
                run_id="test-run",
                workflow_id="test-workflow",
                installed_registry_root=str(project_dir),
            )

    @pytest.mark.parametrize(
        "malicious_run_id",
        [
            # Parent-directory traversal — the classic path-escape vector.
            "../escape",
            "..",
            "../../etc/passwd",
            # Embedded path separators — both POSIX and Windows.
            "foo/bar",
            "foo\\bar",
            # Leading non-alphanumeric characters that the existing
            # pattern's anchor blocks (would be mistaken for CLI flags
            # or hidden files in shell completions / error messages).
            ".hidden",
            "-flag",
            # NUL byte — some filesystems treat the prefix as a valid
            # path and silently truncate at the NUL.
            "foo\x00bar",
            # Empty string — degenerate case, matches no file but the
            # validator should reject it before any I/O.
            "",
        ],
    )
    def test_load_rejects_path_traversal(self, project_dir, malicious_run_id):
        """``RunState.load`` validates ``run_id`` before touching the
        filesystem.

        Without this guard, a value like ``../escape`` passed via
        ``specify workflow resume`` would interpolate path-traversal
        segments into the lookup path. ``state_path.exists()`` would
        probe arbitrary paths the process can read (a file-existence
        oracle) and ``json.load`` would happily parse attacker-planted
        JSON from outside ``.specify/workflows/runs/``. The check must
        fire *before* the path is built — ``__init__``'s identical
        regex on ``state_data["run_id"]`` fires too late.
        """
        from specify_cli.workflows.engine import RunState

        # Plant a state.json *outside* the legitimate ``runs/`` directory
        # at the location ``../escape`` would traverse to, so a missing
        # guard would surface as a successful load rather than a
        # ``FileNotFoundError`` (which would be ambiguous with the
        # not-found case).
        runs_dir = project_dir / ".specify" / "workflows" / "runs"
        runs_dir.mkdir(parents=True, exist_ok=True)
        attacker_dir = project_dir / ".specify" / "workflows" / "escape"
        attacker_dir.mkdir(exist_ok=True)
        (attacker_dir / "state.json").write_text(
            json.dumps(
                {
                    "run_id": "pwned",
                    "workflow_id": "attacker-owned",
                    "status": "created",
                }
            ),
            encoding="utf-8",
        )

        with pytest.raises(ValueError, match="Invalid run_id"):
            RunState.load(malicious_run_id, project_dir)

    @pytest.mark.parametrize(
        "bad_run_id",
        [
            # One vector per category from ``test_load_rejects_path_traversal``
            # — enough to prove both entry points agree without re-running
            # the full attack matrix here.
            "../escape",    # parent-directory traversal
            "foo/bar",      # embedded path separator
            ".hidden",      # leading non-alphanumeric
            "valid\n",      # regex end-anchor bypass
            "",             # empty / degenerate
        ],
    )
    def test_init_and_load_share_validation(self, project_dir, bad_run_id):
        """``__init__`` *and* ``load`` reject the same malformed IDs.

        The two entry points must stay in sync — drift would let an ID
        slip in via one path that the other would reject, producing
        confusing crashes mid-workflow. The previous version of this
        test only exercised ``__init__`` and ``_validate_run_id`` (the
        shared helper), so a regression in ``load`` — e.g. someone
        deleting the ``cls._validate_run_id(run_id)`` call there — could
        slip through despite ``__init__`` and the helper staying
        aligned. We now hit ``load`` directly with the same vector so
        any drift between the two call sites is caught by this test.
        """
        from specify_cli.workflows.engine import RunState

        # ``__init__`` rejects up front.
        with pytest.raises(ValueError, match="Invalid run_id"):
            RunState(run_id=bad_run_id)

        # The shared helper rejects the value too (sanity check that the
        # ``__init__`` rejection came from the validator, not some
        # unrelated constructor failure).
        with pytest.raises(ValueError, match="Invalid run_id"):
            RunState._validate_run_id(bad_run_id)

        # And ``load`` rejects it *before* touching the filesystem. This
        # is the assertion the previous version was missing: without it,
        # a regression in ``load`` (e.g. forgetting to call the
        # validator before building the path) would not be caught even
        # though ``__init__`` and the helper still agreed.
        with pytest.raises(ValueError, match="Invalid run_id"):
            RunState.load(bad_run_id, project_dir)

    def test_append_log(self, project_dir):
        from specify_cli.workflows.engine import RunState

        state = RunState(
            run_id="log-test",
            workflow_id="test",
            project_root=project_dir,
        )
        state.append_log({"event": "test_event", "data": "hello"})

        log_file = state.runs_dir / "log.jsonl"
        assert log_file.exists()
        lines = log_file.read_text().strip().split("\n")
        entry = json.loads(lines[0])
        assert entry["event"] == "test_event"
        assert "timestamp" in entry

    def test_error_persists_across_save_and_load(self, project_dir):
        """Run-level error survives a save/load round trip."""
        from specify_cli.workflows.engine import RunState
        from specify_cli.workflows.base import RunStatus

        state = RunState(
            run_id="err-run",
            workflow_id="test-wf",
            project_root=project_dir,
        )
        state.status = RunStatus.FAILED
        state.error = "Something went wrong"
        state.save()

        loaded = RunState.load("err-run", project_dir)
        assert loaded.error == "Something went wrong"

    def test_error_defaults_none_for_legacy_state(self, project_dir):
        """Old state.json files without an error field load with error=None."""
        from specify_cli.workflows.engine import RunState

        state = RunState(
            run_id="legacy-run",
            workflow_id="test-wf",
            project_root=project_dir,
        )
        state.save()

        # Manually strip the error field to simulate a legacy state file.
        state_path = state.runs_dir / "state.json"
        data = json.loads(state_path.read_text())
        data.pop("error", None)
        state_path.write_text(json.dumps(data), encoding="utf-8")

        loaded = RunState.load("legacy-run", project_dir)
        assert loaded.error is None

    def test_resume_clears_stale_error(self, project_dir):
        """A resumed run starts with state.error = None."""
        from specify_cli.workflows.engine import RunState
        from specify_cli.workflows.base import RunStatus

        state = RunState(
            run_id="resume-err",
            workflow_id="test-wf",
            project_root=project_dir,
        )
        state.status = RunStatus.FAILED
        state.error = "Previous failure"
        state.save()

        loaded = RunState.load("resume-err", project_dir)
        assert loaded.error == "Previous failure"

        loaded.error = None
        loaded.status = RunStatus.RUNNING
        loaded.save()

        reloaded = RunState.load("resume-err", project_dir)
        assert reloaded.error is None


class TestListRuns:
    """Test listing workflow runs."""

    def test_list_empty(self, project_dir):
        from specify_cli.workflows.engine import WorkflowEngine

        engine = WorkflowEngine(project_dir)
        assert engine.list_runs() == []

    def test_list_after_execution(self, project_dir):
        from specify_cli.workflows.engine import WorkflowEngine, WorkflowDefinition

        yaml_str = """
schema_version: "1.0"
workflow:
  id: "list-test"
  name: "List Test"
  version: "1.0.0"
steps:
  - id: step-one
    type: shell
    run: "echo test"
"""
        definition = WorkflowDefinition.from_string(yaml_str)
        engine = WorkflowEngine(project_dir)
        engine.execute(definition)

        runs = engine.list_runs()
        assert len(runs) == 1
        assert runs[0]["workflow_id"] == "list-test"

    def test_list_skips_malformed_json(self, project_dir):
        from specify_cli.workflows.engine import WorkflowEngine

        runs_dir = project_dir / ".specify" / "workflows" / "runs"
        bad_dir = runs_dir / "bad-run"
        bad_dir.mkdir(parents=True)
        (bad_dir / "state.json").write_text("{invalid json", encoding="utf-8")

        engine = WorkflowEngine(project_dir)
        assert engine.list_runs() == []

    def test_list_skips_unreadable_file(self, project_dir):
        import sys
        import subprocess
        from specify_cli.workflows.engine import WorkflowEngine

        runs_dir = project_dir / ".specify" / "workflows" / "runs"
        bad_dir = runs_dir / "bad-run"
        bad_dir.mkdir(parents=True)
        state_file = bad_dir / "state.json"
        state_file.write_text('{"run_id": "x"}', encoding="utf-8")

        if sys.platform == "win32":
            subprocess.run(["attrib", "+R", str(state_file)], check=True)
        else:
            state_file.chmod(0o000)

        try:
            engine = WorkflowEngine(project_dir)
            if sys.platform == "win32":
                assert engine.list_runs() == [{"run_id": "x"}]
            else:
                assert engine.list_runs() == []
        finally:
            if sys.platform == "win32":
                subprocess.run(["attrib", "-R", str(state_file)], check=True)
            else:
                state_file.chmod(0o644)

    def test_list_skips_non_dict_payload(self, project_dir):
        from specify_cli.workflows.engine import WorkflowEngine

        runs_dir = project_dir / ".specify" / "workflows" / "runs"
        bad_dir = runs_dir / "bad-run"
        bad_dir.mkdir(parents=True)
        (bad_dir / "state.json").write_text('["not", "a", "dict"]', encoding="utf-8")

        engine = WorkflowEngine(project_dir)
        assert engine.list_runs() == []

    def test_list_skips_empty_dict_payload(self, project_dir):
        from specify_cli.workflows.engine import WorkflowEngine

        runs_dir = project_dir / ".specify" / "workflows" / "runs"
        bad_dir = runs_dir / "bad-run"
        bad_dir.mkdir(parents=True)
        (bad_dir / "state.json").write_text('{}', encoding="utf-8")

        engine = WorkflowEngine(project_dir)
        assert engine.list_runs() == []

    def test_list_skips_bad_file_with_valid_sibling(self, project_dir):
        from specify_cli.workflows.engine import WorkflowEngine, WorkflowDefinition

        runs_dir = project_dir / ".specify" / "workflows" / "runs"
        bad_dir = runs_dir / "bad-run"
        bad_dir.mkdir(parents=True)
        (bad_dir / "state.json").write_text("{bad", encoding="utf-8")

        yaml_str = """
schema_version: "1.0"
workflow:
  id: "good-run"
  name: "Good Run"
  version: "1.0.0"
steps:
  - id: step-one
    type: shell
    run: "echo test"
"""
        definition = WorkflowDefinition.from_string(yaml_str)
        engine = WorkflowEngine(project_dir)
        engine.execute(definition)

        runs = engine.list_runs()
        assert len(runs) == 1
        assert runs[0]["workflow_id"] == "good-run"

    def test_list_skips_invalid_utf8_with_valid_sibling(self, project_dir):
        from specify_cli.workflows.engine import WorkflowEngine, WorkflowDefinition

        runs_dir = project_dir / ".specify" / "workflows" / "runs"
        bad_dir = runs_dir / "bad-utf8"
        bad_dir.mkdir(parents=True)
        (bad_dir / "state.json").write_bytes(b"\xff\xfe invalid utf8")

        yaml_str = """
schema_version: "1.0"
workflow:
  id: "good-run-utf8"
  name: "Good Run UTF8"
  version: "1.0.0"
steps:
  - id: step-one
    type: shell
    run: "echo test"
"""
        definition = WorkflowDefinition.from_string(yaml_str)
        engine = WorkflowEngine(project_dir)
        engine.execute(definition)

        runs = engine.list_runs()
        assert len(runs) == 1
        assert runs[0]["workflow_id"] == "good-run-utf8"

    def test_list_skips_oserror_with_valid_sibling(self, project_dir, monkeypatch):
        import builtins
        from specify_cli.workflows.engine import WorkflowEngine, WorkflowDefinition

        runs_dir = project_dir / ".specify" / "workflows" / "runs"
        bad_dir = runs_dir / "bad-oserror"
        bad_dir.mkdir(parents=True)
        state_file = bad_dir / "state.json"
        state_file.write_text('{"run_id": "bad"}', encoding="utf-8")

        original_open = builtins.open

        def _mock_open(path, *args, **kwargs):
            if str(path).endswith("state.json") and "bad-oserror" in str(path):
                raise OSError("permission denied")
            return original_open(path, *args, **kwargs)

        monkeypatch.setattr(builtins, "open", _mock_open)

        yaml_str = """
schema_version: "1.0"
workflow:
  id: "good-run-oserror"
  name: "Good Run OSError"
  version: "1.0.0"
steps:
  - id: step-one
    type: shell
    run: "echo test"
"""
        definition = WorkflowDefinition.from_string(yaml_str)
        engine = WorkflowEngine(project_dir)
        engine.execute(definition)

        runs = engine.list_runs()
        assert len(runs) == 1
        assert runs[0]["workflow_id"] == "good-run-oserror"


# ===== Workflow Registry Tests =====

class TestWorkflowRegistry:
    """Test WorkflowRegistry operations."""

    def test_add_and_get(self, project_dir):
        from specify_cli.workflows.catalog import WorkflowRegistry

        registry = WorkflowRegistry(project_dir)
        registry.add("test-wf", {"name": "Test", "version": "1.0.0"})

        entry = registry.get("test-wf")
        assert entry is not None
        assert entry["name"] == "Test"
        assert "installed_at" in entry

    def test_remove(self, project_dir):
        from specify_cli.workflows.catalog import WorkflowRegistry

        registry = WorkflowRegistry(project_dir)
        registry.add("test-wf", {"name": "Test"})
        assert registry.is_installed("test-wf")

        registry.remove("test-wf")
        assert not registry.is_installed("test-wf")

    @pytest.mark.parametrize("error_type", [OSError, TypeError, ValueError])
    def test_remove_rolls_back_in_memory_on_save_failure(
        self, project_dir, monkeypatch, error_type
    ):
        """A save() failure during remove() must not leave the in-memory registry
        out of sync with the (unchanged) file on disk, mirroring add()'s rollback."""
        from specify_cli.workflows.catalog import WorkflowRegistry
        import specify_cli.workflows.catalog as catalog_mod

        registry = WorkflowRegistry(project_dir)
        registry.add("test-wf", {"name": "Test", "version": "1.0.0"})

        def boom(*args, **kwargs):
            raise error_type("save failed")

        monkeypatch.setattr(catalog_mod.json, "dump", boom)
        with pytest.raises(error_type):
            registry.remove("test-wf")
        monkeypatch.undo()

        # In-memory state must still show the entry (rolled back), matching
        # the untouched file on disk.
        assert registry.is_installed("test-wf")
        fresh = WorkflowRegistry(project_dir)
        assert fresh.is_installed("test-wf")

    def test_list(self, project_dir):
        from specify_cli.workflows.catalog import WorkflowRegistry

        registry = WorkflowRegistry(project_dir)
        registry.add("wf-a", {"name": "A"})
        registry.add("wf-b", {"name": "B"})

        installed = registry.list()
        assert "wf-a" in installed
        assert "wf-b" in installed

    def test_is_installed(self, project_dir):
        from specify_cli.workflows.catalog import WorkflowRegistry

        registry = WorkflowRegistry(project_dir)
        assert not registry.is_installed("missing")

        registry.add("exists", {"name": "Exists"})
        assert registry.is_installed("exists")

    def test_persistence(self, project_dir):
        from specify_cli.workflows.catalog import WorkflowRegistry

        registry1 = WorkflowRegistry(project_dir)
        registry1.add("test-wf", {"name": "Test"})

        # Load fresh
        registry2 = WorkflowRegistry(project_dir)
        assert registry2.is_installed("test-wf")

    def test_load_read_oserror_refuses_to_save_over_existing_data(self, project_dir, monkeypatch):
        """A transient read failure (e.g. temporarily unreadable file) must not be
        treated the same as a corrupted/missing registry: constructing a registry
        on top of it -- and thus any query a caller makes before ever calling
        save() -- must fail closed instead of silently reporting an empty
        registry that a caller could then act on and overwrite."""
        from specify_cli.workflows.catalog import WorkflowRegistry
        import builtins

        registry1 = WorkflowRegistry(project_dir)
        registry1.add("test-wf", {"name": "Test", "version": "1.0.0"})
        registry_path = registry1.registry_path
        real_open = builtins.open

        def _raising_open(file, mode="r", *args, **kwargs):
            if Path(file) == registry_path and "r" in mode:
                raise OSError("simulated read failure")
            return real_open(file, mode, *args, **kwargs)

        monkeypatch.setattr(builtins, "open", _raising_open)
        with pytest.raises(OSError):
            WorkflowRegistry(project_dir)
        # The original entry must survive on disk untouched.
        data = json.loads(registry_path.read_text(encoding="utf-8"))
        assert "test-wf" in data["workflows"]

    def test_load_read_oserror_fails_closed_not_silently_empty(self, project_dir, monkeypatch):
        """Root cause: a registry that failed to read must never let a query
        method (is_installed/get/list) report as if nothing were installed --
        a caller (e.g. bundled workflow install) that only checks
        is_installed() before writing a file would otherwise overwrite real
        data on a transient read failure, long before any save() call could
        catch it. The failure must surface at construction, before any query
        or side effect is possible."""
        from specify_cli.workflows.catalog import WorkflowRegistry
        import builtins

        registry1 = WorkflowRegistry(project_dir)
        registry1.add("test-wf", {"name": "Test", "version": "1.0.0"})
        registry_path = registry1.registry_path
        real_open = builtins.open

        def _raising_open(file, mode="r", *args, **kwargs):
            if Path(file) == registry_path and "r" in mode:
                raise OSError("simulated read failure")
            return real_open(file, mode, *args, **kwargs)

        monkeypatch.setattr(builtins, "open", _raising_open)
        with pytest.raises(OSError):
            WorkflowRegistry(project_dir)

    @pytest.mark.skipif(not hasattr(os, "symlink"), reason="symlinks are unavailable")
    def test_load_symlinked_workflows_dir_fails_closed_not_silently_empty(
        self, project_dir
    ):
        """A symlinked .specify/workflows is the same fail-open hazard as a
        read OSError: silently reporting an empty registry lets a read-only
        caller (e.g. the bundler's remove path) conclude a workflow isn't
        installed, skip removing it, and then delete the bundle record --
        leaving the workflow untracked but still on disk. Raise here too,
        exactly like the unreadable-file case, so callers cannot act on
        fabricated empty state."""
        from specify_cli.workflows.catalog import WorkflowRegistry
        import json as _json

        outside = project_dir.parent / "outside-workflows"
        outside.mkdir(parents=True, exist_ok=True)
        (outside / "workflow-registry.json").write_text(
            _json.dumps({"schema_version": "1.0", "workflows": {"evil": {}}}),
            encoding="utf-8",
        )
        workflows_link = project_dir / ".specify" / "workflows"
        workflows_link.rmdir()
        workflows_link.symlink_to(outside, target_is_directory=True)

        with pytest.raises(OSError):
            WorkflowRegistry(project_dir)


# ===== Workflow Catalog Tests =====

class TestWorkflowCatalog:
    """Test WorkflowCatalog catalog resolution."""

    @pytest.fixture(params=["workflow", "step"])
    def removal_catalog(self, request, project_dir, monkeypatch):
        from specify_cli.workflows.catalog import WorkflowCatalog, WorkflowValidationError
        from specify_cli.workflows.step.catalog import StepCatalog, StepValidationError

        kind = request.param
        catalog_cls, error = (
            (WorkflowCatalog, WorkflowValidationError)
            if kind == "workflow" else (StepCatalog, StepValidationError)
        )
        env_key = f"SPECKIT_{kind.upper()}_CATALOG_URL"
        monkeypatch.delenv(env_key, raising=False)
        config = project_dir / ".specify" / f"{kind}-catalogs.yml"
        return catalog_cls(project_dir), error, config, env_key

    @pytest.mark.parametrize("index,original_index", [(0, 2), (1, 4), (2, 3), (3, 1)])
    def test_remove_catalog_uses_listed_position(
        self, removal_catalog, index, original_index
    ):
        catalog, _, config, _ = removal_catalog
        data = {"notes": "keep", "catalogs": [
            {"name": "skipped", "url": "  "},
            {"name": "duplicate", "url": "https://example.com/low.json", "priority": 10},
            {"name": "duplicate", "url": "https://example.com/first.json", "priority": "2"},
            {"url": "https://example.com/unnamed.json"},
            {"name": "duplicate", "url": "https://example.com/tied.json", "priority": 2},
        ]}
        config.write_text(yaml.safe_dump(data, sort_keys=False), encoding="utf-8")
        selected = catalog.get_catalog_configs()[index]
        assert selected["url"] == data["catalogs"][original_index]["url"]

        assert catalog.remove_catalog(index) == selected["name"]

        data["catalogs"].pop(original_index)
        assert yaml.safe_load(config.read_text(encoding="utf-8")) == data

    @pytest.mark.parametrize("index", [-1, 1])
    def test_remove_catalog_bounds_use_visible_entries(self, removal_catalog, index):
        catalog, error, config, _ = removal_catalog
        config.write_text(
            "# keep this comment\ncatalogs:\n  - name: skipped\n"
            "  - url: https://example.com/only.json\n", encoding="utf-8",
        )
        before = config.read_bytes()
        with pytest.raises(error, match="out of range"):
            catalog.remove_catalog(index)
        assert config.read_bytes() == before

    def test_remove_catalog_refuses_environment_source(self, removal_catalog, monkeypatch):
        catalog, error, config, env_key = removal_catalog
        catalog.add_catalog("https://example.com/project.json", "project")
        before = config.read_bytes()
        monkeypatch.setenv(env_key, " https://example.com/override.json ")
        assert catalog.get_catalog_configs()[0]["name"] == "env-override"

        with pytest.raises(error, match=env_key) as exc:
            catalog.remove_catalog(0)
        assert "Unset" in str(exc.value)
        assert config.read_bytes() == before

    def test_remove_catalog_ignores_blank_environment_override(self, removal_catalog, monkeypatch):
        catalog, _, config, env_key = removal_catalog
        catalog.add_catalog("https://example.com/project.json", "project")
        monkeypatch.setenv(env_key, " \t ")
        assert catalog.remove_catalog(0) == "project"
        assert yaml.safe_load(config.read_text(encoding="utf-8"))["catalogs"] == []

    @pytest.mark.parametrize("entry", ["invalid", {"name": "no-url"}, {
        "url": "https://example.com/invalid.json", "priority": "invalid",
    }])
    def test_remove_catalog_rejects_unlistable_config(self, removal_catalog, entry):
        catalog, error, config, _ = removal_catalog
        config.write_text(yaml.safe_dump({"catalogs": [entry]}), encoding="utf-8")
        before = config.read_bytes()
        with pytest.raises(error):
            catalog.get_catalog_configs()
        with pytest.raises(error):
            catalog.remove_catalog(0)
        assert config.read_bytes() == before

    @pytest.mark.parametrize("catalog_type", ["workflow", "step"])
    def test_non_mapping_cache_metadata_is_invalid(
        self, project_dir, catalog_type
    ):
        from specify_cli.workflows.catalog import WorkflowCatalog
        from specify_cli.workflows.step.catalog import StepCatalog

        catalog_cls = WorkflowCatalog if catalog_type == "workflow" else StepCatalog
        catalog = catalog_cls(project_dir)
        _, metadata_path = catalog._get_cache_paths(
            f"https://example.com/{catalog_type}.json"
        )
        metadata_path.parent.mkdir(parents=True, exist_ok=True)
        metadata_path.write_text("[]", encoding="utf-8")

        assert catalog._is_url_cache_valid(
            f"https://example.com/{catalog_type}.json"
        ) is False

    def test_non_mapping_cached_workflow_catalog_is_refetched(
        self, project_dir, monkeypatch
    ):
        import io

        from specify_cli.authentication import http as auth_http
        from specify_cli.workflows.catalog import (
            WorkflowCatalog,
            WorkflowCatalogEntry,
        )

        url = "https://example.com/workflows.json"
        catalog = WorkflowCatalog(project_dir)
        cache_path, metadata_path = catalog._get_cache_paths(url)
        cache_path.parent.mkdir(parents=True, exist_ok=True)
        cache_path.write_text("[]", encoding="utf-8")
        metadata_path.write_text(
            json.dumps({"fetched_at": 4_102_444_800}),
            encoding="utf-8",
        )

        payload = {"schema_version": "1.0", "workflows": {}}

        class _FakeResponse(io.BytesIO):
            def geturl(self):
                return url

        monkeypatch.setattr(
            auth_http,
            "open_url",
            lambda url, timeout=30, redirect_validator=None: _FakeResponse(
                json.dumps(payload).encode("utf-8")
            ),
        )
        entry = WorkflowCatalogEntry(
            url=url,
            name="test",
            priority=1,
            install_allowed=True,
        )

        assert catalog._fetch_single_catalog(entry) == payload

    @pytest.mark.parametrize("catalog_type", ["workflow", "step"])
    def test_non_utf8_cached_catalog_is_refetched(
        self, project_dir, monkeypatch, catalog_type
    ):
        import io

        from specify_cli.authentication import http as auth_http
        from specify_cli.workflows.catalog import WorkflowCatalog, WorkflowCatalogEntry
        from specify_cli.workflows.step.catalog import StepCatalog, StepCatalogEntry

        catalog_cls = WorkflowCatalog if catalog_type == "workflow" else StepCatalog
        entry_cls = (
            WorkflowCatalogEntry
            if catalog_type == "workflow"
            else StepCatalogEntry
        )
        payload_key = "workflows" if catalog_type == "workflow" else "steps"
        url = f"https://example.com/{catalog_type}.json"
        catalog = catalog_cls(project_dir)
        cache_path, metadata_path = catalog._get_cache_paths(url)
        cache_path.parent.mkdir(parents=True, exist_ok=True)
        cache_path.write_bytes(b"\xff\xfe")
        metadata_path.write_text(
            json.dumps({"fetched_at": 4_102_444_800}),
            encoding="utf-8",
        )
        payload = {"schema_version": "1.0", payload_key: {}}

        class _FakeResponse(io.BytesIO):
            def geturl(self):
                return url

        monkeypatch.setattr(
            auth_http,
            "open_url",
            lambda url, timeout=30, redirect_validator=None: _FakeResponse(
                json.dumps(payload).encode("utf-8")
            ),
        )
        entry = entry_cls(
            url=url,
            name="test",
            priority=1,
            install_allowed=True,
        )

        assert catalog._fetch_single_catalog(entry) == payload
        assert json.loads(cache_path.read_text(encoding="utf-8")) == payload

    def test_non_mapping_stale_workflow_catalog_is_rejected(
        self, project_dir, monkeypatch
    ):
        from specify_cli.authentication import http as auth_http
        from specify_cli.workflows.catalog import (
            WorkflowCatalog,
            WorkflowCatalogEntry,
            WorkflowCatalogError,
        )

        url = "https://example.com/workflows.json"
        catalog = WorkflowCatalog(project_dir)
        cache_path, _ = catalog._get_cache_paths(url)
        cache_path.parent.mkdir(parents=True, exist_ok=True)
        cache_path.write_text("[]", encoding="utf-8")

        def _offline(url, timeout=30, redirect_validator=None):
            raise OSError("offline")

        monkeypatch.setattr(auth_http, "open_url", _offline)
        entry = WorkflowCatalogEntry(
            url=url,
            name="test",
            priority=1,
            install_allowed=True,
        )

        with pytest.raises(WorkflowCatalogError, match="Failed to fetch catalog"):
            catalog._fetch_single_catalog(entry, force_refresh=True)

    def test_search_with_non_string_fields(self, project_dir, monkeypatch):
        """Non-string workflow fields (null/int name/description) must not
        raise TypeError in search — StepCatalog.search already coerces these."""
        from specify_cli.workflows.catalog import WorkflowCatalog

        catalog = WorkflowCatalog(project_dir)
        monkeypatch.setattr(catalog, "_get_merged_workflows", lambda **kw: {
            "42": {
                "id": 42,
                "name": None,
                "description": 99,
                "_catalog_name": "test",
                "_install_allowed": True,
            },
        })

        assert len(catalog.search()) == 1
        assert len(catalog.search(query="42")) == 1
        assert len(catalog.search(query="missing")) == 0

    def test_default_catalogs(self, project_dir, monkeypatch):
        from specify_cli.workflows.catalog import WorkflowCatalog

        monkeypatch.setattr(Path, "home", lambda: project_dir)
        monkeypatch.delenv("SPECKIT_WORKFLOW_CATALOG_URL", raising=False)
        catalog = WorkflowCatalog(project_dir)
        entries = catalog.get_active_catalogs()
        assert len(entries) == 2
        assert entries[0].name == "default"
        assert entries[1].name == "community"

    def test_env_var_override(self, project_dir, monkeypatch):
        from specify_cli.workflows.catalog import WorkflowCatalog

        monkeypatch.setenv("SPECKIT_WORKFLOW_CATALOG_URL", "https://example.com/catalog.json")
        catalog = WorkflowCatalog(project_dir)
        entries = catalog.get_active_catalogs()
        assert len(entries) == 1
        assert entries[0].name == "env-override"
        assert entries[0].url == "https://example.com/catalog.json"

    def test_project_level_config(self, project_dir):
        from specify_cli.workflows.catalog import WorkflowCatalog

        config_path = project_dir / ".specify" / "workflow-catalogs.yml"
        config_path.write_text(yaml.dump({
            "catalogs": [{
                "name": "custom",
                "url": "https://example.com/wf-catalog.json",
                "priority": 1,
                "install_allowed": True,
            }]
        }))

        catalog = WorkflowCatalog(project_dir)
        entries = catalog.get_active_catalogs()
        assert len(entries) == 1
        assert entries[0].name == "custom"

    @pytest.mark.parametrize("body", ["[]\n", "false\n", "0\n", "''\n"])
    def test_falsy_non_mapping_config_rejected(self, project_dir, body):
        """A FALSY non-mapping top-level config ([], false, 0, '') must raise,
        like a truthy non-mapping (5, a bare list) already does. The previous
        ``yaml.safe_load(...) or {}`` coerced these to {} and silently swallowed
        them, diverging from the truthy case."""
        from specify_cli.workflows.catalog import WorkflowCatalog, WorkflowValidationError

        config_path = project_dir / ".specify" / "workflow-catalogs.yml"
        config_path.write_text(body, encoding="utf-8")
        catalog = WorkflowCatalog(project_dir)
        with pytest.raises(WorkflowValidationError, match="expected a mapping"):
            catalog._load_catalog_config(config_path)

    @pytest.mark.parametrize("body", ["catalogs: {}\n", "catalogs: ''\n", "catalogs: 0\n", "catalogs: false\n"])
    def test_falsy_non_list_catalogs_rejected(self, project_dir, body):
        """A FALSY non-list ``catalogs:`` value must raise, like a truthy one
        (``catalogs: 5``) already does. The shape check sat behind the emptiness
        check, so these were silently swallowed as "no catalogs"."""
        from specify_cli.workflows.catalog import WorkflowCatalog, WorkflowValidationError

        config_path = project_dir / ".specify" / "workflow-catalogs.yml"
        config_path.write_text(body, encoding="utf-8")
        catalog = WorkflowCatalog(project_dir)
        with pytest.raises(WorkflowValidationError, match="'catalogs' must be a list"):
            catalog._load_catalog_config(config_path)

    @pytest.mark.parametrize("body", ["catalogs:\n", "catalogs: []\n"])
    def test_absent_or_empty_catalogs_is_noop(self, project_dir, body):
        """An explicit ``catalogs:`` null or an empty list stays a valid no-op —
        the layer contributes nothing and resolution falls through."""
        from specify_cli.workflows.catalog import WorkflowCatalog

        config_path = project_dir / ".specify" / "workflow-catalogs.yml"
        config_path.write_text(body, encoding="utf-8")
        catalog = WorkflowCatalog(project_dir)
        assert catalog._load_catalog_config(config_path) is None

    @pytest.mark.parametrize("body", ["", "# only a comment\n", "null\n", "~\n"])
    def test_empty_or_null_config_is_noop(self, project_dir, body):
        """An empty document, comment-only file, or explicit top-level null is a
        valid no-op: the loader returns None so that config layer is skipped and
        get_active_catalogs falls through to the next one. It must NOT be
        confused with a falsy non-mapping, which raises."""
        from specify_cli.workflows.catalog import WorkflowCatalog

        config_path = project_dir / ".specify" / "workflow-catalogs.yml"
        config_path.write_text(body, encoding="utf-8")
        catalog = WorkflowCatalog(project_dir)
        assert catalog._load_catalog_config(config_path) is None

    @pytest.mark.parametrize("bad_priority", [True, False, float("inf")])
    def test_config_priority_bool_or_inf_rejected(self, project_dir, bad_priority):
        """`priority: true` must not be silently coerced to 1, and `priority: .inf`
        must not crash with an uncaught OverflowError — both raise a clean
        validation error (parity with the base CatalogStackBase loader)."""
        from specify_cli.workflows.catalog import WorkflowCatalog, WorkflowValidationError

        config_path = project_dir / ".specify" / "workflow-catalogs.yml"
        config_path.write_text(yaml.dump({
            "catalogs": [{
                "name": "bad",
                "url": "https://example.com/wf-catalog.json",
                "priority": bad_priority,
                "install_allowed": True,
            }]
        }))
        catalog = WorkflowCatalog(project_dir)
        with pytest.raises(WorkflowValidationError, match="Invalid priority|expected integer"):
            catalog.get_active_catalogs()

    def test_validate_url_http_rejected(self, project_dir):
        from specify_cli.workflows.catalog import WorkflowCatalog, WorkflowValidationError

        catalog = WorkflowCatalog(project_dir)
        with pytest.raises(WorkflowValidationError, match="HTTPS"):
            catalog._validate_catalog_url("http://evil.com/catalog.json")

    def test_validate_url_localhost_http_allowed(self, project_dir):
        from specify_cli.workflows.catalog import WorkflowCatalog

        catalog = WorkflowCatalog(project_dir)
        # Should not raise
        catalog._validate_catalog_url("http://localhost:8080/catalog.json")

    @pytest.mark.parametrize(
        "url",
        [
            "https://[::1",              # unterminated IPv6 bracket
            "https://[not-an-ip]/x",     # bracketed non-IP host
            "https://example.com:notaport/catalog.json",
        ],
    )
    def test_validate_url_malformed_raises_validation_error(self, project_dir, url):
        """A malformed authority must raise WorkflowValidationError, not leak a
        raw ValueError.

        ``urlparse``/``.hostname`` raise ValueError on a malformed IPv6
        authority. The command handler only catches WorkflowValidationError,
        so a raw ValueError would surface as an uncaught traceback instead of a
        clean 'Error:' message + exit 1. Mirrors specify_cli.catalogs (#3435).
        """
        from specify_cli.workflows.catalog import (
            WorkflowCatalog,
            WorkflowValidationError,
        )

        catalog = WorkflowCatalog(project_dir)
        with pytest.raises(WorkflowValidationError, match="malformed"):
            catalog._validate_catalog_url(url)

    def test_fetch_malformed_redirect_target_raises_catalog_error(
        self, project_dir, monkeypatch
    ):
        """A malformed post-redirect URL must raise WorkflowCatalogError, not a
        raw ValueError.

        The fetch path re-validates ``resp.geturl()`` after following redirects,
        so a hostile/broken redirect to a malformed authority
        (``https://[::1``) hits ``urlparse``/``.hostname`` and raises
        ``ValueError``. Without the guard that ValueError is re-wrapped by the
        broad ``except`` as ``Failed to fetch catalog ...: Invalid IPv6 URL``;
        the guard turns it into a clean ``... malformed URL ...`` refusal. The
        initial ``entry.url`` is valid so validation only trips on the redirect
        target. Mirrors specify_cli.catalogs (#3435).
        """
        from specify_cli.workflows.catalog import (
            WorkflowCatalog,
            WorkflowCatalogEntry,
            WorkflowCatalogError,
        )
        from specify_cli.authentication import http as auth_http

        class _FakeResponse:
            def __enter__(self):
                return self

            def __exit__(self, exc_type, exc, tb):
                return False

            def read(self):
                return b"{}"

            def geturl(self):
                # A redirect landing on a malformed IPv6 authority.
                return "https://[::1"

        monkeypatch.setattr(
            auth_http,
            "open_url",
            lambda url, timeout=30, redirect_validator=None: _FakeResponse(),
        )

        catalog = WorkflowCatalog(project_dir)
        entry = WorkflowCatalogEntry(
            url="https://example.com/catalog.json",
            name="test",
            priority=1,
            install_allowed=True,
        )
        # A fresh project_dir has no cache to fall back to, so the error
        # propagates instead of being masked by a stale-cache read.
        with pytest.raises(WorkflowCatalogError, match="malformed"):
            catalog._fetch_single_catalog(entry, force_refresh=True)

    def test_fetch_validates_every_redirect_hop(self, project_dir, monkeypatch):
        """A redirect_validator is passed to open_url and rejects a non-HTTPS
        INTERMEDIATE hop — closing the https -> http -> attacker-https chain a
        terminal-URL-only check would miss. Mirrors presets/extensions
        (#3523 / #3524)."""
        from specify_cli.workflows.catalog import (
            WorkflowCatalog,
            WorkflowCatalogEntry,
            WorkflowCatalogError,
        )
        from specify_cli.authentication import http as auth_http

        captured = {}

        def fake_open(url, timeout=30, redirect_validator=None):
            captured["rv"] = redirect_validator
            # Simulate the hop urllib validates before following the redirect.
            redirect_validator(
                "https://good.example/catalog.json", "http://evil.test/hop"
            )
            raise AssertionError("redirect_validator should have raised")

        monkeypatch.setattr(auth_http, "open_url", fake_open)

        catalog = WorkflowCatalog(project_dir)
        entry = WorkflowCatalogEntry(
            url="https://good.example/catalog.json",
            name="test",
            priority=1,
            install_allowed=True,
        )
        with pytest.raises(WorkflowCatalogError, match="HTTPS"):
            catalog._fetch_single_catalog(entry, force_refresh=True)
        assert captured["rv"] is not None

    def test_fetch_rejects_oversized_catalog_response(
        self, project_dir, monkeypatch
    ):
        from specify_cli.authentication import http as auth_http
        from specify_cli.workflows import catalog as catalog_module
        from specify_cli.workflows.catalog import (
            WorkflowCatalog,
            WorkflowCatalogEntry,
            WorkflowCatalogError,
        )

        monkeypatch.setattr(catalog_module, "MAX_JSON_CATALOG_BYTES", 32)
        requested_sizes: list[int] = []

        class _FakeResponse:
            def __init__(self):
                self.body = b"x" * 64
                self.offset = 0

            def __enter__(self):
                return self

            def __exit__(self, exc_type, exc, tb):
                return False

            def geturl(self):
                return "https://example.com/catalog.json"

            def read(self, size=-1):
                requested_sizes.append(size)
                assert size >= 0
                chunk_size = min(size, 7)
                chunk = self.body[self.offset : self.offset + chunk_size]
                self.offset += len(chunk)
                return chunk

        monkeypatch.setattr(
            auth_http,
            "open_url",
            lambda url, timeout=30, redirect_validator=None: _FakeResponse(),
        )

        catalog = WorkflowCatalog(project_dir)
        entry = WorkflowCatalogEntry(
            url="https://example.com/catalog.json",
            name="test",
            priority=1,
            install_allowed=True,
        )

        with pytest.raises(WorkflowCatalogError, match="exceeds maximum size"):
            catalog._fetch_single_catalog(entry, force_refresh=True)

        assert requested_sizes
        assert not catalog.cache_dir.exists()

    def test_add_catalog(self, project_dir):
        from specify_cli.workflows.catalog import WorkflowCatalog

        catalog = WorkflowCatalog(project_dir)
        catalog.add_catalog("https://example.com/new-catalog.json", "my-catalog")

        config_path = project_dir / ".specify" / "workflow-catalogs.yml"
        assert config_path.exists()
        data = yaml.safe_load(config_path.read_text())
        assert len(data["catalogs"]) == 1
        assert data["catalogs"][0]["url"] == "https://example.com/new-catalog.json"

    def test_add_catalog_with_existing_inf_priority(self, project_dir):
        """add_catalog() derives the new priority from existing ones via
        _coerce_priority; an existing `priority: .inf` must not crash it
        (int(float('inf')) is an OverflowError) — it is treated as 0 and the add
        succeeds."""
        from specify_cli.workflows.catalog import WorkflowCatalog

        config_path = project_dir / ".specify" / "workflow-catalogs.yml"
        config_path.parent.mkdir(parents=True, exist_ok=True)
        config_path.write_text(yaml.dump({
            "catalogs": [{
                "name": "existing",
                "url": "https://a.example.com/c.json",
                "priority": float("inf"),
                "install_allowed": True,
            }]
        }))

        catalog = WorkflowCatalog(project_dir)
        catalog.add_catalog("https://b.example.com/c.json", "new")

        data = yaml.safe_load(config_path.read_text())
        new = next(c for c in data["catalogs"] if c["url"] == "https://b.example.com/c.json")
        assert new["priority"] == 1  # max(inf coerced to 0) + 1

    def test_add_catalog_normalizes_stored_url_for_idempotency(self, project_dir):
        from specify_cli.workflows.catalog import WorkflowCatalog, WorkflowValidationError

        catalog = WorkflowCatalog(project_dir)
        assert (
            catalog.add_catalog("https://example.com/catalog.json", "mine")
            == "added"
        )
        config_path = project_dir / ".specify" / "workflow-catalogs.yml"
        data = yaml.safe_load(config_path.read_text(encoding="utf-8"))
        data["catalogs"][0]["url"] = "  https://example.com/catalog.json  "
        config_path.write_text(yaml.safe_dump(data), encoding="utf-8")
        original = config_path.read_bytes()

        assert (
            catalog.add_catalog("https://example.com/catalog.json", "mine")
            == "unchanged"
        )
        assert config_path.read_bytes() == original

        with pytest.raises(WorkflowValidationError, match="already configured"):
            catalog.add_catalog("https://example.com/catalog.json", "different")

    def test_remove_catalog(self, project_dir):
        from specify_cli.workflows.catalog import WorkflowCatalog

        catalog = WorkflowCatalog(project_dir)
        catalog.add_catalog("https://example.com/c1.json", "first")
        catalog.add_catalog("https://example.com/c2.json", "second")

        removed = catalog.remove_catalog(0)
        assert removed == "first"

        config_path = project_dir / ".specify" / "workflow-catalogs.yml"
        data = yaml.safe_load(config_path.read_text())
        assert len(data["catalogs"]) == 1

    def test_remove_catalog_invalid_index(self, project_dir):
        from specify_cli.workflows.catalog import WorkflowCatalog, WorkflowValidationError

        catalog = WorkflowCatalog(project_dir)
        catalog.add_catalog("https://example.com/c1.json")

        with pytest.raises(WorkflowValidationError, match="out of range"):
            catalog.remove_catalog(5)

    @pytest.mark.parametrize("bad", [[], False, 0, ""])
    def test_remove_catalog_rejects_falsy_non_mapping_config(
        self, project_dir, bad
    ):
        from specify_cli.workflows.catalog import WorkflowCatalog, WorkflowValidationError

        config_path = project_dir / ".specify" / "workflow-catalogs.yml"
        config_path.write_text(yaml.safe_dump(bad), encoding="utf-8")

        with pytest.raises(WorkflowValidationError, match="expected a mapping"):
            WorkflowCatalog(project_dir).remove_catalog(0)

    def test_get_catalog_configs(self, project_dir):
        from specify_cli.workflows.catalog import WorkflowCatalog

        catalog = WorkflowCatalog(project_dir)
        configs = catalog.get_catalog_configs()
        assert len(configs) == 2
        assert configs[0]["name"] == "default"
        assert isinstance(configs[0]["install_allowed"], bool)

    def test_load_catalog_config_non_dict_yaml_raises(self, project_dir):
        """A YAML catalog config that is a list (not a mapping) must raise WorkflowValidationError."""
        from specify_cli.workflows.catalog import WorkflowCatalog, WorkflowValidationError

        config_path = project_dir / ".specify" / "workflow-catalogs.yml"
        config_path.write_text("- item1\n- item2\n", encoding="utf-8")

        catalog = WorkflowCatalog(project_dir)
        with pytest.raises(WorkflowValidationError, match="expected a mapping"):
            catalog.get_active_catalogs()

    def test_add_catalog_malformed_yaml_raises(self, project_dir):
        """A malformed YAML config file must raise WorkflowValidationError when adding a catalog."""
        from specify_cli.workflows.catalog import WorkflowCatalog, WorkflowValidationError

        config_path = project_dir / ".specify" / "workflow-catalogs.yml"
        config_path.write_text(": invalid: yaml: {\n", encoding="utf-8")

        catalog = WorkflowCatalog(project_dir)
        with pytest.raises(WorkflowValidationError, match="unreadable or malformed"):
            catalog.add_catalog("https://example.com/new.json")

    def test_remove_catalog_malformed_yaml_raises(self, project_dir):
        """A malformed YAML config file must raise WorkflowValidationError when removing a catalog."""
        from specify_cli.workflows.catalog import WorkflowCatalog, WorkflowValidationError

        catalog = WorkflowCatalog(project_dir)
        catalog.add_catalog("https://example.com/c1.json", "first")

        config_path = project_dir / ".specify" / "workflow-catalogs.yml"
        config_path.write_text(": bad: yaml: {\n", encoding="utf-8")

        with pytest.raises(WorkflowValidationError, match="unreadable or malformed"):
            catalog.remove_catalog(0)

    def test_add_catalog_wraps_write_oserror(self, project_dir, monkeypatch):
        """An OSError on write must be wrapped as WorkflowValidationError."""
        from specify_cli.workflows.catalog import WorkflowCatalog, WorkflowValidationError
        import builtins

        catalog = WorkflowCatalog(project_dir)
        config_path = project_dir / ".specify" / "workflow-catalogs.yml"
        real_open = builtins.open

        def _raising_open(file, mode="r", *args, **kwargs):
            if Path(file) == config_path and "w" in mode:
                raise OSError("simulated write failure")
            return real_open(file, mode, *args, **kwargs)

        monkeypatch.setattr(builtins, "open", _raising_open)
        with pytest.raises(WorkflowValidationError, match="Failed to write catalog config"):
            catalog.add_catalog("https://example.com/new-catalog.json", "my-catalog")

    def test_remove_catalog_wraps_write_oserror(self, project_dir, monkeypatch):
        """An OSError on write must be wrapped as WorkflowValidationError."""
        from specify_cli.workflows.catalog import WorkflowCatalog, WorkflowValidationError
        import builtins

        catalog = WorkflowCatalog(project_dir)
        catalog.add_catalog("https://example.com/c1.json", "first")
        config_path = project_dir / ".specify" / "workflow-catalogs.yml"
        real_open = builtins.open

        def _raising_open(file, mode="r", *args, **kwargs):
            if Path(file) == config_path and "w" in mode:
                raise OSError("simulated write failure")
            return real_open(file, mode, *args, **kwargs)

        monkeypatch.setattr(builtins, "open", _raising_open)
        with pytest.raises(WorkflowValidationError, match="Failed to write catalog config"):
            catalog.remove_catalog(0)

    def test_oversized_workflow_catalog_does_not_block_healthy_one(self, project_dir, monkeypatch):
        """A healthy catalog still works after an oversized one was rejected."""
        from specify_cli.workflows.catalog import (
            WorkflowCatalog,
            WorkflowCatalogEntry,
            WorkflowCatalogError,
        )
        from specify_cli.authentication import http as auth_http
        from specify_cli.workflows import catalog as catalog_module

        monkeypatch.setattr(catalog_module, "MAX_JSON_CATALOG_BYTES", 512)

        call_count = [0]

        class _OversizedResponse:
            def __init__(self):
                self._data = b"x" * 1024
                self._pos = 0

            def read(self, n=-1):
                if n < 0:
                    chunk = self._data[self._pos:]
                    self._pos = len(self._data)
                    return chunk
                chunk = self._data[self._pos : self._pos + n]
                self._pos += len(chunk)
                return chunk

            def geturl(self):
                return "https://bad.example.com/catalog.json"

            def __enter__(self):
                return self

            def __exit__(self, *a):
                pass

        class _HealthyResponse:
            def __init__(self):
                self._data = b'{"workflows": {}}'
                self._pos = 0

            def read(self, n=-1):
                if n < 0:
                    chunk = self._data[self._pos:]
                    self._pos = len(self._data)
                    return chunk
                chunk = self._data[self._pos : self._pos + n]
                self._pos += len(chunk)
                return chunk

            def geturl(self):
                return "https://good.example.com/catalog.json"

            def __enter__(self):
                return self

            def __exit__(self, *a):
                pass

        def fake_open(url, timeout=30, redirect_validator=None):
            call_count[0] += 1
            if call_count[0] == 1:
                return _OversizedResponse()
            return _HealthyResponse()

        monkeypatch.setattr(auth_http, "open_url", fake_open)

        catalog = WorkflowCatalog(project_dir)

        bad_entry = WorkflowCatalogEntry(
            url="https://bad.example.com/catalog.json",
            name="bad",
            priority=1,
            install_allowed=True,
        )
        with pytest.raises(WorkflowCatalogError, match="exceeds maximum size"):
            catalog._fetch_single_catalog(bad_entry, force_refresh=True)

        good_entry = WorkflowCatalogEntry(
            url="https://good.example.com/catalog.json",
            name="good",
            priority=1,
            install_allowed=True,
        )
        result = catalog._fetch_single_catalog(good_entry, force_refresh=True)
        assert isinstance(result, dict)


# ===== Integration Test =====

class TestWorkflowIntegration:
    """End-to-end workflow execution tests."""

    def test_full_sequential_workflow(self, project_dir):
        """Execute a multi-step sequential workflow end to end."""
        from specify_cli.workflows.engine import WorkflowEngine, WorkflowDefinition
        from specify_cli.workflows.base import RunStatus

        yaml_str = """
schema_version: "1.0"
workflow:
  id: "e2e-test"
  name: "E2E Test"
  version: "1.0.0"
  integration: claude
inputs:
  feature:
    type: string
    default: "login"
steps:
  - id: specify
    type: shell
    run: "echo speckit.specify {{ inputs.feature }}"

  - id: check-scope
    type: if
    condition: "{{ inputs.feature == 'login' }}"
    then:
      - id: echo-full
        type: shell
        run: "echo full scope"
    else:
      - id: echo-partial
        type: shell
        run: "echo partial scope"

  - id: plan
    type: shell
    run: "echo speckit.plan"
"""
        definition = WorkflowDefinition.from_string(yaml_str)
        engine = WorkflowEngine(project_dir)
        state = engine.execute(definition)

        assert state.status == RunStatus.COMPLETED
        assert "specify" in state.step_results
        assert "check-scope" in state.step_results
        assert "echo-full" in state.step_results
        assert "echo-partial" not in state.step_results
        assert "plan" in state.step_results

    def test_switch_workflow(self, project_dir):
        """Test switch step type in a workflow."""
        from specify_cli.workflows.engine import WorkflowEngine, WorkflowDefinition
        from specify_cli.workflows.base import RunStatus

        yaml_str = """
schema_version: "1.0"
workflow:
  id: "switch-test"
  name: "Switch Test"
  version: "1.0.0"
inputs:
  action:
    type: string
    default: "plan"
steps:
  - id: route
    type: switch
    expression: "{{ inputs.action }}"
    cases:
      specify:
        - id: do-specify
          type: shell
          run: "echo specify"
      plan:
        - id: do-plan
          type: shell
          run: "echo plan"
    default:
      - id: do-default
        type: shell
        run: "echo default"
"""
        definition = WorkflowDefinition.from_string(yaml_str)
        engine = WorkflowEngine(project_dir)
        state = engine.execute(definition)

        assert state.status == RunStatus.COMPLETED
        assert "do-plan" in state.step_results
        assert "do-specify" not in state.step_results


# ===== Step Registry Tests =====

class TestStepRegistryCustom:
    """Test StepRegistry operations for custom step types."""

    def test_add_and_get(self, project_dir):
        from specify_cli.workflows.step.catalog import StepRegistry

        registry = StepRegistry(project_dir)
        registry.add("deploy", {"name": "Deploy", "version": "1.0.0", "type_key": "deploy"})

        entry = registry.get("deploy")
        assert entry is not None
        assert entry["name"] == "Deploy"
        assert "installed_at" in entry

    def test_add_does_not_mutate_input_metadata(self, project_dir):
        from specify_cli.workflows.step.catalog import StepRegistry

        registry = StepRegistry(project_dir)
        metadata = {
            "name": "Deploy",
            "type_key": "deploy",
            "nested": {"key": "original"},
        }

        registry.add("deploy", metadata)

        assert "installed_at" not in metadata
        assert "updated_at" not in metadata
        metadata["nested"]["key"] = "changed-after-add"
        assert registry.get("deploy")["nested"]["key"] == "original"

    def test_remove(self, project_dir):
        from specify_cli.workflows.step.catalog import StepRegistry

        registry = StepRegistry(project_dir)
        registry.add("deploy", {"name": "Deploy", "type_key": "deploy"})
        assert registry.is_installed("deploy")

        registry.remove("deploy")
        assert not registry.is_installed("deploy")

    def test_remove_missing_returns_false(self, project_dir):
        from specify_cli.workflows.step.catalog import StepRegistry

        registry = StepRegistry(project_dir)
        removed = registry.remove("nonexistent")
        assert removed is False

    def test_list(self, project_dir):
        from specify_cli.workflows.step.catalog import StepRegistry

        registry = StepRegistry(project_dir)
        registry.add("step-a", {"name": "A", "type_key": "step-a"})
        registry.add("step-b", {"name": "B", "type_key": "step-b"})

        installed = registry.list()
        assert "step-a" in installed
        assert "step-b" in installed

    def test_is_installed(self, project_dir):
        from specify_cli.workflows.step.catalog import StepRegistry

        registry = StepRegistry(project_dir)
        assert not registry.is_installed("missing")

        registry.add("exists", {"name": "Exists", "type_key": "exists"})
        assert registry.is_installed("exists")

    def test_persistence(self, project_dir):
        from specify_cli.workflows.step.catalog import StepRegistry

        registry1 = StepRegistry(project_dir)
        registry1.add("deploy", {"name": "Deploy", "type_key": "deploy"})

        registry2 = StepRegistry(project_dir)
        assert registry2.is_installed("deploy")

    def test_corrupted_registry_resets(self, project_dir):
        from specify_cli.workflows.step.catalog import StepRegistry

        registry = StepRegistry(project_dir)
        registry.steps_dir.mkdir(parents=True, exist_ok=True)
        registry.registry_path.write_text("not json", encoding="utf-8")

        # Loading again should reset
        registry2 = StepRegistry(project_dir)
        assert registry2.list() == {}

    def test_registry_missing_steps_key_resets(self, project_dir):
        """Valid JSON but missing 'steps' key should not crash add/get."""
        from specify_cli.workflows.step.catalog import StepRegistry
        import json as _json

        registry = StepRegistry(project_dir)
        registry.steps_dir.mkdir(parents=True, exist_ok=True)
        # Valid JSON but 'steps' is not a dict
        registry.registry_path.write_text(
            _json.dumps({"schema_version": "1.0", "steps": "bad"}),
            encoding="utf-8",
        )

        registry2 = StepRegistry(project_dir)
        # Should be safe to call add/get without KeyError
        assert registry2.list() == {}
        registry2.add("deploy", {"name": "Deploy", "type_key": "deploy"})
        assert registry2.is_installed("deploy")

    @pytest.mark.skipif(sys.platform == "win32", reason="chmod not reliable on Windows")
    def test_registry_unreadable_file_resets(self, project_dir):
        """OSError reading the registry file should fall back to default."""
        from specify_cli.workflows.step.catalog import StepRegistry
        import json as _json

        registry = StepRegistry(project_dir)
        registry.steps_dir.mkdir(parents=True, exist_ok=True)
        # Write valid registry first
        registry.registry_path.write_text(
            _json.dumps({"schema_version": "1.0", "steps": {"existing": {}}}),
            encoding="utf-8",
        )
        # Make it unreadable
        registry.registry_path.chmod(0o000)
        try:
            registry2 = StepRegistry(project_dir)
            assert registry2.list() == {}
        finally:
            registry.registry_path.chmod(0o644)

        # After restoring permissions the registry is fully functional
        registry2.add("deploy", {"name": "Deploy", "type_key": "deploy"})
        assert registry2.is_installed("deploy")

    @pytest.mark.skipif(not hasattr(os, "symlink"), reason="symlinks are unavailable")
    def test_registry_load_refuses_symlinked_steps_dir(self, project_dir):
        """A symlinked steps directory must not be read from (defense-in-depth)."""
        from specify_cli.workflows.step.catalog import StepRegistry
        import json as _json

        outside = project_dir.parent / "outside-steps"
        outside.mkdir(parents=True, exist_ok=True)
        (outside / "step-registry.json").write_text(
            _json.dumps({"schema_version": "1.0", "steps": {"evil": {}}}),
            encoding="utf-8",
        )
        steps_link = project_dir / ".specify" / "workflows" / "steps"
        steps_link.symlink_to(outside, target_is_directory=True)

        registry = StepRegistry(project_dir)
        assert registry.list() == {}

    @pytest.mark.skipif(not hasattr(os, "symlink"), reason="symlinks are unavailable")
    def test_registry_save_refuses_symlinked_steps_dir(self, project_dir):
        """save() must refuse symlinked registry paths (defense-in-depth)."""
        from specify_cli.workflows.step.catalog import StepRegistry, StepValidationError

        outside = project_dir.parent / "outside-steps-save"
        outside.mkdir(parents=True, exist_ok=True)
        steps_link = project_dir / ".specify" / "workflows" / "steps"
        steps_link.symlink_to(outside, target_is_directory=True)

        registry = StepRegistry(project_dir)
        with pytest.raises(StepValidationError, match="symlinked path"):
            registry.save()


# ===== Step Catalog Tests =====

class TestStepCatalog:
    """Test StepCatalog catalog resolution."""

    # -- Config shape guards ----------------------------------------------
    # StepCatalog._load_catalog_config is a duplicated twin of
    # WorkflowCatalog._load_catalog_config, so it needs its own coverage: a
    # regression in one loader would not be caught by the other's tests.

    @pytest.mark.parametrize("body", ["[]\n", "false\n", "0\n", "''\n"])
    def test_falsy_non_mapping_config_rejected(self, project_dir, body):
        """A FALSY non-mapping top level had the same ``or {}`` coercion, which
        bypassed the isinstance guard. It must raise like a truthy non-mapping."""
        from specify_cli.workflows.step.catalog import StepCatalog, StepValidationError

        config_path = project_dir / ".specify" / "step-catalogs.yml"
        config_path.write_text(body, encoding="utf-8")
        catalog = StepCatalog(project_dir)
        with pytest.raises(StepValidationError, match="expected a mapping"):
            catalog._load_catalog_config(config_path)

    @pytest.mark.parametrize(
        "body", ["catalogs: {}\n", "catalogs: ''\n", "catalogs: 0\n", "catalogs: false\n"]
    )
    def test_falsy_non_list_catalogs_rejected(self, project_dir, body):
        """...and the same nested guard: a FALSY non-list ``catalogs:`` value must
        raise rather than being swallowed as "no catalogs"."""
        from specify_cli.workflows.step.catalog import StepCatalog, StepValidationError

        config_path = project_dir / ".specify" / "step-catalogs.yml"
        config_path.write_text(body, encoding="utf-8")
        catalog = StepCatalog(project_dir)
        with pytest.raises(StepValidationError, match="'catalogs' must be a list"):
            catalog._load_catalog_config(config_path)

    @pytest.mark.parametrize(
        "body",
        ["", "# only a comment\n", "null\n", "~\n", "catalogs:\n", "catalogs: []\n"],
    )
    def test_empty_or_null_config_is_noop(self, project_dir, body):
        """An empty document, explicit null, or absent/empty ``catalogs:`` stays a
        valid no-op — the layer contributes nothing and resolution falls
        through."""
        from specify_cli.workflows.step.catalog import StepCatalog

        config_path = project_dir / ".specify" / "step-catalogs.yml"
        config_path.write_text(body, encoding="utf-8")
        catalog = StepCatalog(project_dir)
        assert catalog._load_catalog_config(config_path) is None

    def test_default_catalogs(self, project_dir, monkeypatch):
        from specify_cli.workflows.step.catalog import StepCatalog

        monkeypatch.setattr(Path, "home", lambda: project_dir)
        monkeypatch.delenv("SPECKIT_STEP_CATALOG_URL", raising=False)
        catalog = StepCatalog(project_dir)
        entries = catalog.get_active_catalogs()
        assert len(entries) == 2
        assert entries[0].name == "default"
        assert entries[1].name == "community"

    def test_env_var_override(self, project_dir, monkeypatch):
        from specify_cli.workflows.step.catalog import StepCatalog

        monkeypatch.setenv("SPECKIT_STEP_CATALOG_URL", "https://example.com/step-catalog.json")
        catalog = StepCatalog(project_dir)
        entries = catalog.get_active_catalogs()
        assert len(entries) == 1
        assert entries[0].name == "env-override"
        assert entries[0].url == "https://example.com/step-catalog.json"

    def test_project_level_config(self, project_dir):
        from specify_cli.workflows.step.catalog import StepCatalog

        config_path = project_dir / ".specify" / "step-catalogs.yml"
        config_path.write_text(yaml.dump({
            "catalogs": [{
                "name": "custom",
                "url": "https://example.com/step-catalog.json",
                "priority": 1,
                "install_allowed": True,
            }]
        }))

        catalog = StepCatalog(project_dir)
        entries = catalog.get_active_catalogs()
        assert len(entries) == 1
        assert entries[0].name == "custom"

    @pytest.mark.parametrize("bad_priority", [True, False, float("inf")])
    def test_config_priority_bool_or_inf_rejected(self, project_dir, bad_priority):
        """`priority: true`/`.inf` in a step-catalog config raise a clean
        validation error instead of coercing to 1 / crashing with OverflowError."""
        from specify_cli.workflows.step.catalog import StepCatalog, StepValidationError

        config_path = project_dir / ".specify" / "step-catalogs.yml"
        config_path.write_text(yaml.dump({
            "catalogs": [{
                "name": "bad",
                "url": "https://example.com/step-catalog.json",
                "priority": bad_priority,
                "install_allowed": True,
            }]
        }))
        catalog = StepCatalog(project_dir)
        with pytest.raises(StepValidationError, match="Invalid priority|expected integer"):
            catalog.get_active_catalogs()

    def test_validate_url_http_rejected(self, project_dir):
        from specify_cli.workflows.step.catalog import StepCatalog, StepValidationError

        catalog = StepCatalog(project_dir)
        with pytest.raises(StepValidationError, match="HTTPS"):
            catalog._validate_catalog_url("http://evil.com/step-catalog.json")

    def test_validate_url_localhost_http_allowed(self, project_dir):
        from specify_cli.workflows.step.catalog import StepCatalog

        catalog = StepCatalog(project_dir)
        # Should not raise
        catalog._validate_catalog_url("http://localhost:8080/step-catalog.json")

    @pytest.mark.parametrize(
        "url",
        [
            "https://[::1",              # unterminated IPv6 bracket
            "https://[not-an-ip]/x",     # bracketed non-IP host
            "https://example.com:notaport/steps.json",
        ],
    )
    def test_validate_url_malformed_raises_validation_error(self, project_dir, url):
        """A malformed authority must raise StepValidationError, not leak a raw
        ValueError past the command handler (which only catches
        StepValidationError). Mirrors specify_cli.catalogs (#3435).
        """
        from specify_cli.workflows.step.catalog import StepCatalog, StepValidationError

        catalog = StepCatalog(project_dir)
        with pytest.raises(StepValidationError, match="malformed"):
            catalog._validate_catalog_url(url)

    def test_fetch_malformed_redirect_target_raises_catalog_error(
        self, project_dir, monkeypatch
    ):
        """A malformed post-redirect URL must raise StepCatalogError, not a raw
        ValueError.

        The fetch path re-validates ``resp.geturl()`` after redirects, so a
        broken redirect to a bracketed non-IP host (``https://[not-an-ip]/x``)
        makes ``urlparse``/``.hostname`` raise ``ValueError``. Without the guard
        that leaks out as ``... Invalid IPv6 URL`` re-wrapping; the guard turns
        it into a clean ``... malformed URL ...`` refusal. The initial
        ``entry.url`` is valid so validation only trips on the redirect target.
        Mirrors specify_cli.catalogs (#3435).
        """
        from specify_cli.workflows.step.catalog import (
            StepCatalog,
            StepCatalogEntry,
            StepCatalogError,
        )
        from specify_cli.authentication import http as auth_http

        class _FakeResponse:
            def __enter__(self):
                return self

            def __exit__(self, exc_type, exc, tb):
                return False

            def read(self):
                return b"{}"

            def geturl(self):
                # A redirect landing on a bracketed non-IP authority.
                return "https://[not-an-ip]/x"

        monkeypatch.setattr(
            auth_http,
            "open_url",
            lambda url, timeout=30, redirect_validator=None: _FakeResponse(),
        )

        catalog = StepCatalog(project_dir)
        entry = StepCatalogEntry(
            url="https://example.com/steps.json",
            name="test",
            priority=1,
            install_allowed=True,
        )
        # A fresh project_dir has no cache to fall back to, so the error
        # propagates instead of being masked by a stale-cache read.
        with pytest.raises(StepCatalogError, match="malformed"):
            catalog._fetch_single_catalog(entry, force_refresh=True)

    def test_fetch_validates_every_redirect_hop(self, project_dir, monkeypatch):
        """A redirect_validator is passed to open_url and rejects a non-HTTPS
        INTERMEDIATE hop — closing the https -> http -> attacker-https chain a
        terminal-URL-only check would miss. Mirrors presets/extensions
        (#3523 / #3524)."""
        from specify_cli.workflows.step.catalog import (
            StepCatalog,
            StepCatalogEntry,
            StepCatalogError,
        )
        from specify_cli.authentication import http as auth_http

        captured = {}

        def fake_open(url, timeout=30, redirect_validator=None):
            captured["rv"] = redirect_validator
            # Simulate the hop urllib validates before following the redirect.
            redirect_validator(
                "https://good.example/steps.json", "http://evil.test/hop"
            )
            raise AssertionError("redirect_validator should have raised")

        monkeypatch.setattr(auth_http, "open_url", fake_open)

        catalog = StepCatalog(project_dir)
        entry = StepCatalogEntry(
            url="https://good.example/steps.json",
            name="test",
            priority=1,
            install_allowed=True,
        )
        with pytest.raises(StepCatalogError, match="HTTPS"):
            catalog._fetch_single_catalog(entry, force_refresh=True)
        assert captured["rv"] is not None

    def test_fetch_rejects_oversized_catalog_response(
        self, project_dir, monkeypatch
    ):
        from specify_cli.authentication import http as auth_http
        from specify_cli.workflows.step import catalog as catalog_module
        from specify_cli.workflows.step.catalog import (
            StepCatalog,
            StepCatalogEntry,
            StepCatalogError,
        )

        monkeypatch.setattr(catalog_module, "MAX_JSON_CATALOG_BYTES", 32)
        requested_sizes: list[int] = []

        class _FakeResponse:
            def __init__(self):
                self.body = b"x" * 64
                self.offset = 0

            def __enter__(self):
                return self

            def __exit__(self, exc_type, exc, tb):
                return False

            def geturl(self):
                return "https://example.com/steps.json"

            def read(self, size=-1):
                requested_sizes.append(size)
                assert size >= 0
                chunk_size = min(size, 7)
                chunk = self.body[self.offset : self.offset + chunk_size]
                self.offset += len(chunk)
                return chunk

        monkeypatch.setattr(
            auth_http,
            "open_url",
            lambda url, timeout=30, redirect_validator=None: _FakeResponse(),
        )

        catalog = StepCatalog(project_dir)
        entry = StepCatalogEntry(
            url="https://example.com/steps.json",
            name="test",
            priority=1,
            install_allowed=True,
        )

        with pytest.raises(StepCatalogError, match="exceeds maximum size"):
            catalog._fetch_single_catalog(entry, force_refresh=True)

        assert requested_sizes
        assert not catalog.cache_dir.exists()

    def test_add_catalog(self, project_dir):
        from specify_cli.workflows.step.catalog import StepCatalog

        catalog = StepCatalog(project_dir)
        catalog.add_catalog("https://example.com/new-steps.json", "my-steps")

        config_path = project_dir / ".specify" / "step-catalogs.yml"
        assert config_path.exists()
        data = yaml.safe_load(config_path.read_text())
        assert len(data["catalogs"]) == 1
        assert data["catalogs"][0]["url"] == "https://example.com/new-steps.json"

    def test_add_catalog_with_existing_inf_priority(self, project_dir):
        """Step-catalog add_catalog() must not crash when an existing entry has a
        `priority: .inf` (int(float('inf')) is an OverflowError) — _coerce_priority
        treats it as 0 and the add succeeds."""
        from specify_cli.workflows.step.catalog import StepCatalog

        config_path = project_dir / ".specify" / "step-catalogs.yml"
        config_path.parent.mkdir(parents=True, exist_ok=True)
        config_path.write_text(yaml.dump({
            "catalogs": [{
                "name": "existing",
                "url": "https://a.example.com/s.json",
                "priority": float("inf"),
                "install_allowed": True,
            }]
        }))

        catalog = StepCatalog(project_dir)
        catalog.add_catalog("https://b.example.com/s.json", "new")

        data = yaml.safe_load(config_path.read_text())
        new = next(c for c in data["catalogs"] if c["url"] == "https://b.example.com/s.json")
        assert new["priority"] == 1  # max(inf coerced to 0) + 1

    def test_add_catalog_empty_yaml_file(self, project_dir):
        """An empty YAML config file should be treated as empty, not corrupted."""
        from specify_cli.workflows.step.catalog import StepCatalog

        config_path = project_dir / ".specify" / "step-catalogs.yml"
        config_path.write_text("", encoding="utf-8")

        catalog = StepCatalog(project_dir)
        # Should not raise StepValidationError "corrupted"
        catalog.add_catalog("https://example.com/steps.json", "my-steps")

        data = yaml.safe_load(config_path.read_text())
        assert len(data["catalogs"]) == 1
        assert data["catalogs"][0]["url"] == "https://example.com/steps.json"

    @pytest.mark.parametrize("bad", [[], False, 0, ""])
    def test_add_catalog_rejects_falsy_non_mapping_config(
        self, project_dir, bad
    ):
        from specify_cli.workflows.step.catalog import StepCatalog, StepValidationError

        config_path = project_dir / ".specify" / "step-catalogs.yml"
        original = yaml.safe_dump(bad)
        config_path.write_text(original, encoding="utf-8")

        with pytest.raises(StepValidationError, match="expected a mapping"):
            StepCatalog(project_dir).add_catalog(
                "https://example.com/steps.json", "my-steps"
            )

        assert config_path.read_text(encoding="utf-8") == original

    def test_add_catalog_normalizes_stored_url_for_idempotency(self, project_dir):
        from specify_cli.workflows.step.catalog import StepCatalog, StepValidationError

        catalog = StepCatalog(project_dir)
        assert (
            catalog.add_catalog("https://example.com/steps.json", "mine")
            == "added"
        )
        config_path = project_dir / ".specify" / "step-catalogs.yml"
        data = yaml.safe_load(config_path.read_text(encoding="utf-8"))
        data["catalogs"][0]["url"] = "  https://example.com/steps.json  "
        config_path.write_text(yaml.safe_dump(data), encoding="utf-8")
        original = config_path.read_bytes()

        assert (
            catalog.add_catalog("https://example.com/steps.json", "mine")
            == "unchanged"
        )
        assert config_path.read_bytes() == original

        with pytest.raises(StepValidationError, match="already configured"):
            catalog.add_catalog("https://example.com/steps.json", "different")

    def test_remove_catalog(self, project_dir):
        from specify_cli.workflows.step.catalog import StepCatalog

        catalog = StepCatalog(project_dir)
        catalog.add_catalog("https://example.com/s1.json", "first")
        catalog.add_catalog("https://example.com/s2.json", "second")

        removed = catalog.remove_catalog(0)
        assert removed == "first"

        config_path = project_dir / ".specify" / "step-catalogs.yml"
        data = yaml.safe_load(config_path.read_text())
        assert len(data["catalogs"]) == 1

    def test_remove_catalog_invalid_index(self, project_dir):
        from specify_cli.workflows.step.catalog import StepCatalog, StepValidationError

        catalog = StepCatalog(project_dir)
        catalog.add_catalog("https://example.com/s1.json")

        with pytest.raises(StepValidationError, match="out of range"):
            catalog.remove_catalog(5)

    @pytest.mark.parametrize("bad", [[], False, 0, ""])
    def test_remove_catalog_rejects_falsy_non_mapping_config(
        self, project_dir, bad
    ):
        from specify_cli.workflows.step.catalog import StepCatalog, StepValidationError

        config_path = project_dir / ".specify" / "step-catalogs.yml"
        config_path.write_text(yaml.safe_dump(bad), encoding="utf-8")

        with pytest.raises(StepValidationError, match="expected a mapping"):
            StepCatalog(project_dir).remove_catalog(0)

    def test_remove_catalog_no_config(self, project_dir):
        from specify_cli.workflows.step.catalog import StepCatalog, StepValidationError

        catalog = StepCatalog(project_dir)
        with pytest.raises(StepValidationError, match="No step catalog config file found"):
            catalog.remove_catalog(0)

    def test_add_catalog_wraps_write_oserror(self, project_dir, monkeypatch):
        from specify_cli.workflows.step.catalog import StepCatalog, StepValidationError
        import builtins

        catalog = StepCatalog(project_dir)
        config_path = project_dir / ".specify" / "step-catalogs.yml"
        real_open = builtins.open

        def _raising_open(file, mode="r", *args, **kwargs):
            if Path(file) == config_path and "w" in mode:
                raise OSError("simulated write failure")
            return real_open(file, mode, *args, **kwargs)

        monkeypatch.setattr(builtins, "open", _raising_open)
        with pytest.raises(StepValidationError, match="Failed to write catalog config"):
            catalog.add_catalog("https://example.com/new-steps.json", "my-steps")

    def test_remove_catalog_wraps_write_oserror(self, project_dir, monkeypatch):
        from specify_cli.workflows.step.catalog import StepCatalog, StepValidationError
        import builtins

        catalog = StepCatalog(project_dir)
        catalog.add_catalog("https://example.com/s1.json", "first")
        config_path = project_dir / ".specify" / "step-catalogs.yml"
        real_open = builtins.open

        def _raising_open(file, mode="r", *args, **kwargs):
            if Path(file) == config_path and "w" in mode:
                raise OSError("simulated write failure")
            return real_open(file, mode, *args, **kwargs)

        monkeypatch.setattr(builtins, "open", _raising_open)
        with pytest.raises(StepValidationError, match="Failed to write catalog config"):
            catalog.remove_catalog(0)

    def test_get_catalog_configs(self, project_dir):
        from specify_cli.workflows.step.catalog import StepCatalog

        catalog = StepCatalog(project_dir)
        configs = catalog.get_catalog_configs()
        assert len(configs) == 2
        assert configs[0]["name"] == "default"
        assert isinstance(configs[0]["install_allowed"], bool)

    def test_search_with_mock_catalog(self, project_dir, monkeypatch):
        from specify_cli.workflows.step.catalog import StepCatalog

        mock_data = {
            "schema_version": "1.0",
            "steps": {
                "deploy": {
                    "id": "deploy",
                    "name": "Deploy Step",
                    "description": "Deploy to production",
                    "version": "1.0.0",
                },
                "notify": {
                    "id": "notify",
                    "name": "Notify Step",
                    "description": "Send notifications",
                    "version": "1.0.0",
                },
            },
        }

        catalog = StepCatalog(project_dir)
        monkeypatch.setattr(catalog, "_get_merged_steps", lambda **kw: {
            "deploy": dict(mock_data["steps"]["deploy"], _catalog_name="test", _install_allowed=True),
            "notify": dict(mock_data["steps"]["notify"], _catalog_name="test", _install_allowed=True),
        })

        results = catalog.search()
        assert len(results) == 2

        results = catalog.search(query="deploy")
        assert len(results) == 1
        assert results[0]["id"] == "deploy"

    def test_search_with_non_string_fields(self, project_dir, monkeypatch):
        """Non-string catalog fields (e.g. integer id) must not raise TypeError."""
        from specify_cli.workflows.step.catalog import StepCatalog

        catalog = StepCatalog(project_dir)
        monkeypatch.setattr(catalog, "_get_merged_steps", lambda **kw: {
            "42": {
                "id": 42,
                "name": None,
                "description": 99,
                "_catalog_name": "test",
                "_install_allowed": True,
            },
        })

        results = catalog.search()
        assert len(results) == 1

        results = catalog.search(query="42")
        assert len(results) == 1

        results = catalog.search(query="missing")
        assert len(results) == 0

    def test_get_merged_steps_normalizes_list_ids_to_strings(self, project_dir, monkeypatch):
        """List-based catalog entries with non-string ids must be normalized."""
        from specify_cli.workflows.step.catalog import StepCatalog, StepCatalogEntry

        catalog = StepCatalog(project_dir)
        entry = StepCatalogEntry(
            name="test",
            url="https://example.com/steps.json",
            priority=1,
            install_allowed=True,
        )
        monkeypatch.setattr(catalog, "get_active_catalogs", lambda: [entry])
        monkeypatch.setattr(
            catalog,
            "_fetch_single_catalog",
            lambda _entry, _force_refresh=False: {
                "steps": [{"id": 42, "name": "Integer ID"}]
            },
        )

        merged = catalog._get_merged_steps()
        assert "42" in merged
        assert 42 not in merged
        assert merged["42"]["id"] == "42"

    def test_get_step_info_returns_entry_or_none(self, project_dir, monkeypatch):
        """get_step_info returns matching entry or None for missing ids."""
        from specify_cli.workflows.step.catalog import StepCatalog

        catalog = StepCatalog(project_dir)
        monkeypatch.setattr(catalog, "_get_merged_steps", lambda **kw: {
            "deploy": {
                "id": "deploy",
                "name": "Deploy Step",
                "version": "1.0.0",
                "_catalog_name": "test",
                "_install_allowed": True,
            },
        })

        info = catalog.get_step_info("deploy")
        assert info is not None
        assert info["name"] == "Deploy Step"

        missing = catalog.get_step_info("nonexistent")
        assert missing is None

    def test_oversized_step_catalog_does_not_block_healthy_one(self, project_dir, monkeypatch):
        """A healthy step catalog still works after an oversized one was rejected."""
        from specify_cli.workflows.catalog import (
            StepCatalog,
            StepCatalogEntry,
            StepCatalogError,
        )
        from specify_cli.authentication import http as auth_http
        from specify_cli.workflows.step import catalog as step_catalog_module

        monkeypatch.setattr(step_catalog_module, "MAX_JSON_CATALOG_BYTES", 512)

        call_count = [0]

        class _OversizedResponse:
            def __init__(self):
                self._data = b"x" * 1024
                self._pos = 0

            def read(self, n=-1):
                if n < 0:
                    chunk = self._data[self._pos:]
                    self._pos = len(self._data)
                    return chunk
                chunk = self._data[self._pos : self._pos + n]
                self._pos += len(chunk)
                return chunk

            def geturl(self):
                return "https://bad.example.com/steps.json"

            def __enter__(self):
                return self

            def __exit__(self, *a):
                pass

        class _HealthyResponse:
            def __init__(self):
                self._data = b'{"steps": {}}'
                self._pos = 0

            def read(self, n=-1):
                if n < 0:
                    chunk = self._data[self._pos:]
                    self._pos = len(self._data)
                    return chunk
                chunk = self._data[self._pos : self._pos + n]
                self._pos += len(chunk)
                return chunk

            def geturl(self):
                return "https://good.example.com/steps.json"

            def __enter__(self):
                return self

            def __exit__(self, *a):
                pass

        def fake_open(url, timeout=30, redirect_validator=None):
            call_count[0] += 1
            if call_count[0] == 1:
                return _OversizedResponse()
            return _HealthyResponse()

        monkeypatch.setattr(auth_http, "open_url", fake_open)

        catalog = StepCatalog(project_dir)

        bad_entry = StepCatalogEntry(
            url="https://bad.example.com/steps.json",
            name="bad",
            priority=1,
            install_allowed=True,
        )
        with pytest.raises(StepCatalogError, match="exceeds maximum size"):
            catalog._fetch_single_catalog(bad_entry, force_refresh=True)

        good_entry = StepCatalogEntry(
            url="https://good.example.com/steps.json",
            name="good",
            priority=1,
            install_allowed=True,
        )
        result = catalog._fetch_single_catalog(good_entry, force_refresh=True)
        assert isinstance(result, dict)


# ===== Load Custom Steps Tests =====

class TestLoadCustomSteps:
    """Test dynamic loading of custom step types from the filesystem."""

    def test_empty_steps_dir(self, project_dir):
        from specify_cli.workflows import load_custom_steps

        loaded = load_custom_steps(project_dir)
        assert loaded == []

    def test_no_steps_dir(self, project_dir):
        from specify_cli.workflows import load_custom_steps

        # .specify/workflows/steps does not exist
        loaded = load_custom_steps(project_dir)
        assert loaded == []

    def test_load_valid_custom_step(self, project_dir):
        from specify_cli.workflows import load_custom_steps, STEP_REGISTRY

        step_dir = project_dir / ".specify" / "workflows" / "steps" / "test-custom"
        step_dir.mkdir(parents=True)

        step_yml = """
schema_version: "1.0"
step:
  type_key: "test-custom"
  name: "Test Custom Step"
  version: "1.0.0"
  author: "test"
  description: "A test custom step"
"""
        (step_dir / "step.yml").write_text(step_yml, encoding="utf-8")

        init_py = """
from specify_cli.workflows.base import StepBase, StepResult

class TestCustomStep(StepBase):
    type_key = "test-custom"

    def execute(self, config, context):
        return StepResult()
"""
        (step_dir / "__init__.py").write_text(init_py, encoding="utf-8")

        loaded = load_custom_steps(project_dir)
        assert "test-custom" in loaded
        assert "test-custom" in STEP_REGISTRY

    def test_skip_missing_step_yml(self, project_dir):
        from specify_cli.workflows import load_custom_steps

        step_dir = project_dir / ".specify" / "workflows" / "steps" / "bad-step"
        step_dir.mkdir(parents=True)
        (step_dir / "__init__.py").write_text("# no step.yml", encoding="utf-8")

        loaded = load_custom_steps(project_dir)
        assert "bad-step" not in loaded

    def test_skip_missing_init_py(self, project_dir):
        from specify_cli.workflows import load_custom_steps

        step_dir = project_dir / ".specify" / "workflows" / "steps" / "bad-step2"
        step_dir.mkdir(parents=True)
        (step_dir / "step.yml").write_text(
            "step:\n  type_key: bad-step2\n", encoding="utf-8"
        )

        loaded = load_custom_steps(project_dir)
        assert "bad-step2" not in loaded

    @pytest.mark.skipif(not hasattr(os, "symlink"), reason="symlinks are unavailable")
    def test_skip_symlinked_step_files(self, project_dir):
        from specify_cli.workflows import load_custom_steps

        step_dir = project_dir / ".specify" / "workflows" / "steps" / "bad-symlinked-files"
        step_dir.mkdir(parents=True)

        outside = project_dir.parent / "outside-step-files"
        outside.mkdir(parents=True, exist_ok=True)
        step_yml_target = outside / "step.yml"
        step_yml_target.write_text("step:\n  type_key: bad-symlinked-files\n", encoding="utf-8")
        init_target = outside / "__init__.py"
        init_target.write_text("# external code", encoding="utf-8")

        (step_dir / "step.yml").symlink_to(step_yml_target)
        (step_dir / "__init__.py").symlink_to(init_target)

        loaded = load_custom_steps(project_dir)
        assert "bad-symlinked-files" not in loaded

    def test_skip_already_registered(self, project_dir):
        from specify_cli.workflows import load_custom_steps

        # "command" is already registered as a built-in step
        step_dir = project_dir / ".specify" / "workflows" / "steps" / "command"
        step_dir.mkdir(parents=True)
        (step_dir / "step.yml").write_text(
            "step:\n  type_key: command\n", encoding="utf-8"
        )
        (step_dir / "__init__.py").write_text("", encoding="utf-8")

        # Should not raise KeyError; just skip
        loaded = load_custom_steps(project_dir)
        assert "command" not in loaded

    def test_skip_broken_init_py(self, project_dir):
        from specify_cli.workflows import load_custom_steps

        step_dir = project_dir / ".specify" / "workflows" / "steps" / "broken-step"
        step_dir.mkdir(parents=True)
        (step_dir / "step.yml").write_text(
            "step:\n  type_key: broken-step\n", encoding="utf-8"
        )
        (step_dir / "__init__.py").write_text(
            "raise RuntimeError('broken')", encoding="utf-8"
        )

        # Should not propagate exception
        loaded = load_custom_steps(project_dir)
        assert "broken-step" not in loaded

    def test_module_name_sanitized_for_hyphenated_type_key(self, project_dir):
        """type_key values with hyphens produce valid Python module identifiers."""
        import hashlib
        import sys
        from specify_cli.workflows import load_custom_steps, STEP_REGISTRY

        step_dir = project_dir / ".specify" / "workflows" / "steps" / "my-hyphen-step"
        step_dir.mkdir(parents=True)
        (step_dir / "step.yml").write_text(
            "step:\n  type_key: my-hyphen-step\n  name: Hyphen Step\n",
            encoding="utf-8",
        )

        init_py = """
from specify_cli.workflows.base import StepBase, StepResult

class HyphenStep(StepBase):
    type_key = "my-hyphen-step"

    def execute(self, config, context):
        return StepResult()
"""
        (step_dir / "__init__.py").write_text(init_py, encoding="utf-8")

        loaded = load_custom_steps(project_dir)
        assert "my-hyphen-step" in loaded
        assert "my-hyphen-step" in STEP_REGISTRY
        # Synthetic module name must be a valid identifier (hyphens → underscores)
        # and include a collision-resistant hash suffix.
        key_hash = hashlib.sha256(b"my-hyphen-step").hexdigest()[:8]
        module_name = f"_speckit_custom_step_my_hyphen_step_{key_hash}"
        assert module_name in sys.modules

    def test_package_relative_import(self, project_dir):
        """Steps can use relative imports to access sibling modules."""
        import hashlib
        import sys
        from specify_cli.workflows import load_custom_steps, STEP_REGISTRY

        step_dir = project_dir / ".specify" / "workflows" / "steps" / "pkg-step"
        step_dir.mkdir(parents=True)
        (step_dir / "step.yml").write_text(
            "step:\n  type_key: pkg-step\n  name: Package Step\n",
            encoding="utf-8",
        )
        # Helper module that the step will import relatively
        (step_dir / "helpers.py").write_text(
            "HELPER_VALUE = 'hello'\n", encoding="utf-8"
        )
        init_py = """
from specify_cli.workflows.base import StepBase, StepResult
from .helpers import HELPER_VALUE

class PkgStep(StepBase):
    type_key = "pkg-step"
    helper = HELPER_VALUE

    def execute(self, config, context):
        return StepResult()
"""
        (step_dir / "__init__.py").write_text(init_py, encoding="utf-8")

        loaded = load_custom_steps(project_dir)
        assert "pkg-step" in loaded
        assert "pkg-step" in STEP_REGISTRY
        # Verify the relative import actually resolved; module name includes hash suffix.
        key_hash = hashlib.sha256(b"pkg-step").hexdigest()[:8]
        module_name = f"_speckit_custom_step_pkg_step_{key_hash}"
        assert module_name in sys.modules
        assert sys.modules[module_name].PkgStep.helper == "hello"

    def test_module_name_collision_resistance(self, project_dir):
        """'a-b' and 'a_b' produce different module names despite the same sanitized form."""
        import hashlib

        # Simulate the module name generation for two type_keys that sanitize the same way
        def make_module_name(type_key: str) -> str:
            import re
            safe_key = re.sub(r"[^A-Za-z0-9_]", "_", type_key)
            key_hash = hashlib.sha256(type_key.encode()).hexdigest()[:8]
            return f"_speckit_custom_step_{safe_key}_{key_hash}"

        name_a = make_module_name("a-b")
        name_b = make_module_name("a_b")
        assert name_a != name_b, "Module names for 'a-b' and 'a_b' must differ"


# ===== CLI Step Remove Tests =====

















class TestResumeWithInputs:
    """Test that `workflow resume` can accept updated workflow inputs."""

    _WF_CMD = """
schema_version: "1.0"
workflow:
  id: "resume-cmd-wf"
  name: "Resume Cmd WF"
  version: "1.0.0"
inputs:
  cmd:
    type: string
    default: "exit 1"
steps:
  - id: s
    type: shell
    run: "{{ inputs.cmd }}"
"""

    _WF_NUM = """
schema_version: "1.0"
workflow:
  id: "resume-num-wf"
  name: "Resume Num WF"
  version: "1.0.0"
inputs:
  count:
    type: number
    default: 1
steps:
  - id: gate
    type: gate
    message: "Review"
    options: [approve, reject]
"""

    _WF_GATE_VERDICT = """
schema_version: "1.0"
workflow:
  id: "resume-gate-verdict-wf"
  name: "Resume Gate Verdict WF"
  version: "1.0.0"
inputs:
  spec_verdict:
    type: string
    default: ""
steps:
  - id: gate
    type: gate
    message: "Review"
    options: [approve, reject]
    on_reject: retry
    verdict_input: spec_verdict
"""

    _WF_RUNTIME_CONFIG = """
schema_version: "1.0"
workflow:
  id: "resume-runtime-config-wf"
  name: "Resume Runtime Config WF"
  version: "1.0.0"
inputs:
  config:
    type: string
    default: "./initial-agent.yaml"
  agent_name:
    type: string
    default: "initial-root"
  model_name:
    type: string
    default: "initial/model"
steps:
  - id: implement
    type: command
    command: speckit.implement
    integration: docker-agent
    integration_args:
      - "{{ inputs.config }}"
    integration_options:
      agent: "{{ inputs.agent_name }}"
      safety: balanced
    model: "{{ inputs.model_name }}"
"""

    _WF_DYNAMIC_INTEGRATION = """
schema_version: "1.0"
workflow:
  id: "resume-dynamic-integration-wf"
  name: "Resume Dynamic Integration WF"
  version: "1.0.0"
inputs:
  integration:
    type: string
    default: docker-agent
  config:
    type: string
    default: "./initial-agent.yaml"
steps:
  - id: implement
    type: command
    command: speckit.implement
    integration: "{{ inputs.integration }}"
    integration_args:
      - "{{ inputs.config }}"
"""

    def _engine(self, project_dir):
        from specify_cli.workflows.engine import WorkflowEngine
        return WorkflowEngine(project_dir)

    def test_resume_with_input_reruns_step_with_new_value(self, project_dir):
        from specify_cli.workflows.engine import WorkflowDefinition
        from specify_cli.workflows.base import RunStatus

        definition = WorkflowDefinition.from_string(self._WF_CMD)
        engine = self._engine(project_dir)

        state = engine.execute(definition)
        assert state.status == RunStatus.FAILED  # "exit 1" fails

        resumed = engine.resume(state.run_id, {"cmd": "exit 0"})
        assert resumed.status == RunStatus.COMPLETED
        assert resumed.inputs["cmd"] == "exit 0"

    def test_resume_without_input_preserves_inputs(self, project_dir):
        from specify_cli.workflows.engine import WorkflowDefinition
        from specify_cli.workflows.base import RunStatus

        definition = WorkflowDefinition.from_string(self._WF_CMD)
        engine = self._engine(project_dir)

        state = engine.execute(definition)
        assert state.status == RunStatus.FAILED

        resumed = engine.resume(state.run_id)
        assert resumed.status == RunStatus.FAILED  # still "exit 1"
        assert resumed.inputs["cmd"] == "exit 1"

    def test_resume_re_resolves_complete_integration_config(
        self, project_dir, monkeypatch
    ):
        from specify_cli.workflows.base import RunStatus
        from specify_cli.workflows.engine import WorkflowDefinition

        calls = []
        return_codes = iter((1, 0))

        def fake_run(args, **kwargs):
            calls.append(args)
            return type("Result", (), {"returncode": next(return_codes)})()

        monkeypatch.delenv(
            "SPECKIT_INTEGRATION_DOCKER_AGENT_EXTRA_ARGS", raising=False
        )
        monkeypatch.setattr(
            "shutil.which",
            lambda name: (
                "/usr/bin/docker-agent"
                if name in {"docker-agent", "/usr/bin/docker-agent"}
                else None
            ),
        )
        monkeypatch.setattr("subprocess.run", fake_run)

        definition = WorkflowDefinition.from_string(self._WF_RUNTIME_CONFIG)
        engine = self._engine(project_dir)
        state = engine.execute(definition)

        assert state.status is RunStatus.FAILED
        assert state.step_results["implement"]["integration_args"] == [
            "./initial-agent.yaml"
        ]
        assert state.step_results["implement"]["integration_options"] == {
            "agent": "initial-root",
            "safety": "balanced",
        }

        resumed = engine.resume(
            state.run_id,
            {
                "config": "./changed-on-resume.yaml",
                "agent_name": "changed-root",
                "model_name": "changed/model",
            },
        )

        assert resumed.status is RunStatus.COMPLETED
        assert resumed.inputs["config"] == "./changed-on-resume.yaml"
        assert len(calls) == 2
        assert "./initial-agent.yaml" in calls[0]
        assert "./changed-on-resume.yaml" in calls[1]
        assert "./initial-agent.yaml" not in calls[1]
        assert calls[1][calls[1].index("--agent") + 1] == "changed-root"
        assert calls[1][calls[1].index("--model") + 1] == "changed/model"

    def test_resume_does_not_mix_new_integration_with_old_runtime_config(
        self, project_dir, monkeypatch
    ):
        from specify_cli.workflows.base import RunStatus
        from specify_cli.workflows.engine import WorkflowDefinition

        monkeypatch.delenv(
            "SPECKIT_INTEGRATION_DOCKER_AGENT_EXTRA_ARGS", raising=False
        )
        monkeypatch.setattr(
            "shutil.which",
            lambda name: (
                "/usr/bin/docker-agent"
                if name in {"docker-agent", "/usr/bin/docker-agent"}
                else None
            ),
        )
        monkeypatch.setattr(
            "subprocess.run",
            lambda *args, **kwargs: type("Result", (), {"returncode": 1})(),
        )

        definition = WorkflowDefinition.from_string(self._WF_DYNAMIC_INTEGRATION)
        engine = self._engine(project_dir)
        state = engine.execute(definition)
        assert state.status is RunStatus.FAILED

        resumed = engine.resume(
            state.run_id,
            {"integration": "claude", "config": "./changed-on-resume.yaml"},
        )

        assert resumed.status is RunStatus.FAILED
        step_result = resumed.step_results["implement"]
        assert step_result["integration"] == "claude"
        assert step_result["integration_args"] == ["./changed-on-resume.yaml"]
        assert "Integration 'claude'" in (step_result["error"] or "")
        assert "./initial-agent.yaml" not in str(step_result)

    def test_resume_merges_and_coerces_typed_input(self, project_dir):
        import json as _json
        from specify_cli.workflows.engine import WorkflowDefinition
        from specify_cli.workflows.base import RunStatus

        definition = WorkflowDefinition.from_string(self._WF_NUM)
        engine = self._engine(project_dir)

        state = engine.execute(definition)
        assert state.status == RunStatus.PAUSED

        resumed = engine.resume(state.run_id, {"count": "5"})
        assert resumed.inputs["count"] == 5  # coerced string -> number

        inputs_file = (
            project_dir / ".specify" / "workflows" / "runs" / state.run_id / "inputs.json"
        )
        assert _json.loads(inputs_file.read_text())["inputs"]["count"] == 5

    def test_resume_invalid_typed_input_raises(self, project_dir):
        from specify_cli.workflows.engine import WorkflowDefinition

        definition = WorkflowDefinition.from_string(self._WF_NUM)
        engine = self._engine(project_dir)

        state = engine.execute(definition)
        with pytest.raises(ValueError):
            engine.resume(state.run_id, {"count": "not-a-number"})

    def test_resume_rejects_legacy_invalid_options_before_state_mutation(
        self, project_dir, monkeypatch
    ):
        from specify_cli.workflows.base import RunStatus
        from specify_cli.workflows.engine import RunState, WorkflowDefinition

        definition = WorkflowDefinition.from_string(self._WF_NUM)
        engine = self._engine(project_dir)
        state = engine.execute(definition)
        assert state.status == RunStatus.PAUSED

        workflow_copy = (
            project_dir
            / ".specify"
            / "workflows"
            / "runs"
            / state.run_id
            / "workflow.yml"
        )
        workflow_copy.write_text(
            self._WF_NUM.replace(
                'version: "1.0.0"', 'version: "1.0.0"\n  options: [max_tokens]'
            ),
            encoding="utf-8",
        )

        def fail_step_context(*args, **kwargs):
            raise AssertionError("StepContext must not be created")

        monkeypatch.setattr("specify_cli.workflows.engine.StepContext", fail_step_context)

        with pytest.raises(ValueError, match="'workflow.options' must be a mapping or null"):
            engine.resume(state.run_id, {"count": "5"})

        reloaded = RunState.load(state.run_id, project_dir)
        assert reloaded.status == RunStatus.PAUSED
        assert reloaded.error is None
        assert reloaded.inputs["count"] == 1

    def test_retry_verdict_input_is_consumed_and_can_be_replaced(self, project_dir):
        import json as _json
        from specify_cli.workflows.engine import WorkflowDefinition
        from specify_cli.workflows.base import RunStatus

        definition = WorkflowDefinition.from_string(self._WF_GATE_VERDICT)
        engine = self._engine(project_dir)

        state = engine.execute(definition, {"spec_verdict": "reject"})
        assert state.status == RunStatus.PAUSED
        assert state.inputs["spec_verdict"] == ""

        inputs_file = (
            project_dir / ".specify" / "workflows" / "runs" / state.run_id / "inputs.json"
        )
        assert _json.loads(inputs_file.read_text())["inputs"]["spec_verdict"] == ""

        paused_again = engine.resume(state.run_id)
        assert paused_again.status == RunStatus.PAUSED
        assert paused_again.inputs["spec_verdict"] == ""

        completed = engine.resume(state.run_id, {"spec_verdict": "approve"})
        assert completed.status == RunStatus.COMPLETED
        assert completed.step_results["gate"]["output"]["choice"] == "approve"













class TestWorkflowCliAlignment:
    """CLI alignment with extension/preset commands (#2342)."""

    def test_registry_add_rolls_back_memory_on_save_failure(self, project_dir, monkeypatch):
        from specify_cli.workflows.catalog import WorkflowRegistry

        registry = WorkflowRegistry(project_dir)
        registry.add("align-wf", {"version": "1.0.0", "source": "catalog"})

        def boom():
            raise OSError("disk full")

        monkeypatch.setattr(registry, "save", boom)
        with pytest.raises(OSError):
            registry.add("align-wf", {"version": "2.0.0", "source": "catalog"})
        assert registry.get("align-wf")["version"] == "1.0.0"

        with pytest.raises(OSError):
            registry.add("other-wf", {"version": "1.0.0", "source": "catalog"})
        assert registry.get("other-wf") is None

    @pytest.mark.parametrize("error_type", [TypeError, ValueError])
    def test_registry_add_rolls_back_memory_on_serialization_failure(
        self, project_dir, monkeypatch, error_type
    ):
        from specify_cli.workflows.catalog import WorkflowRegistry

        registry = WorkflowRegistry(project_dir)
        registry.add("align-wf", {"version": "1.0.0", "source": "catalog"})

        def boom():
            raise error_type("not JSON serializable")

        monkeypatch.setattr(registry, "save", boom)
        with pytest.raises(error_type):
            registry.add("align-wf", {"version": "2.0.0", "source": "catalog"})
        assert registry.get("align-wf")["version"] == "1.0.0"

        with pytest.raises(error_type):
            registry.add("other-wf", {"version": "1.0.0", "source": "catalog"})
        assert registry.get("other-wf") is None

    def test_registry_add_survives_non_dict_existing_entry(self, project_dir):
        from specify_cli.workflows.catalog import WorkflowRegistry

        registry = WorkflowRegistry(project_dir)
        registry.data["workflows"]["align-wf"] = "corrupted"
        registry.add("align-wf", {"version": "1.0.0", "source": "catalog"})
        assert registry.get("align-wf")["version"] == "1.0.0"

    def test_step_registry_add_survives_non_dict_existing_entry(self, project_dir):
        """StepRegistry.add must treat a corrupted non-dict existing entry as
        absent rather than crash on existing.get() (parity with
        WorkflowRegistry.add)."""
        from specify_cli.workflows.step.catalog import StepRegistry

        registry = StepRegistry(project_dir)
        registry.data["steps"]["my-step"] = "corrupted"
        registry.add("my-step", {"version": "1.0.0"})
        assert registry.get("my-step")["version"] == "1.0.0"

    @pytest.mark.parametrize(
        "contents",
        [
            "not json",
            "[]",
            '{"schema_version": "1.0"}',
            '{"schema_version": "1.0", "workflows": "broken"}',
        ],
    )
    def test_registry_load_rejects_corrupt_contents(
        self, project_dir, contents
    ):
        from specify_cli.workflows.catalog import WorkflowRegistry

        registry = WorkflowRegistry(project_dir)
        registry.workflows_dir.mkdir(parents=True, exist_ok=True)
        registry.registry_path.write_text(contents, encoding="utf-8")

        with pytest.raises(OSError, match="corrupt"):
            WorkflowRegistry(project_dir)

        assert registry.registry_path.read_text(encoding="utf-8") == contents

    def test_registry_save_refuses_symlinked_parent(self, project_dir, tmp_path):
        """Construction now fails closed on a symlinked .specify just like
        an unreadable registry file: a symlinked parent must never be
        silently tolerated up to save() -- it must raise immediately."""
        from specify_cli.workflows.catalog import WorkflowRegistry

        outside = tmp_path / "outside-specify"
        outside.mkdir()
        specify_dir = project_dir / ".specify"
        if specify_dir.exists():
            shutil.rmtree(specify_dir)
        specify_dir.symlink_to(outside)
        with pytest.raises(OSError, match="symlink"):
            WorkflowRegistry(project_dir)
        assert not (outside / "workflows").exists()

    @pytest.mark.skipif(sys.platform == "win32", reason="chmod mode bits not reliable on Windows")
    def test_registry_save_preserves_existing_file_mode(self, project_dir):
        """A registry shared as 0640/0644 must keep that mode after a save,
        not be silently replaced by mkstemp's 0600 default -- otherwise
        every add/remove locks other project users out of a previously
        shared registry file."""
        from specify_cli.workflows.catalog import WorkflowRegistry

        registry = WorkflowRegistry(project_dir)
        registry.add("first-wf", {"name": "First"})
        registry.registry_path.chmod(0o644)

        registry.add("second-wf", {"name": "Second"})

        mode = stat.S_IMODE(registry.registry_path.stat().st_mode)
        assert mode == 0o644, f"expected 0644, got {oct(mode)}"

    @pytest.mark.skipif(not hasattr(os, "fchown"), reason="os.fchown is unavailable")
    def test_registry_save_preserves_existing_owner_group(
        self, project_dir, monkeypatch
    ):
        from specify_cli.workflows.catalog import WorkflowRegistry
        import specify_cli.workflows.catalog as catalog_mod

        registry = WorkflowRegistry(project_dir)
        registry.add("first-wf", {"name": "First"})
        existing = registry.registry_path.stat()
        calls: list[tuple[os.stat_result, int, int]] = []

        monkeypatch.setattr(
            catalog_mod.os,
            "fchown",
            lambda fd, uid, gid: calls.append((os.fstat(fd), uid, gid)),
        )
        registry.add("second-wf", {"name": "Second"})

        assert len(calls) == 1
        temp_stat, uid, gid = calls[0]
        assert stat.S_ISREG(temp_stat.st_mode)
        assert uid == existing.st_uid
        assert gid == existing.st_gid

    @pytest.mark.skipif(sys.platform == "win32", reason="chmod mode bits not reliable on Windows")
    def test_registry_save_on_new_registry_uses_secure_default_mode(self, project_dir):
        """A brand-new registry file (no prior mode to preserve) should keep
        mkstemp's secure 0600 default rather than something more permissive."""
        from specify_cli.workflows.catalog import WorkflowRegistry

        registry = WorkflowRegistry(project_dir)
        registry.add("first-wf", {"name": "First"})

        mode = stat.S_IMODE(registry.registry_path.stat().st_mode)
        assert mode == 0o600, f"expected 0600, got {oct(mode)}"

    @pytest.mark.skipif(not hasattr(os, "symlink"), reason="symlinks are unavailable")
    def test_registry_save_rejects_swapped_temp_without_touching_target(
        self, project_dir, monkeypatch
    ):
        from specify_cli.workflows.catalog import WorkflowRegistry
        import specify_cli.workflows.catalog as catalog_mod

        registry = WorkflowRegistry(project_dir)
        registry.add("first-wf", {"name": "First"})
        registry.registry_path.chmod(0o640)

        victim = project_dir / "victim.txt"
        victim.write_text("untouched", encoding="utf-8")
        victim.chmod(0o600)

        tmp_path = None
        real_mkstemp = catalog_mod.tempfile.mkstemp
        real_dump = catalog_mod.json.dump

        def tracking_mkstemp(*args, **kwargs):
            nonlocal tmp_path
            fd, name = real_mkstemp(*args, **kwargs)
            tmp_path = Path(name)
            return fd, name

        def swap_after_dump(*args, **kwargs):
            result = real_dump(*args, **kwargs)
            assert tmp_path is not None
            tmp_path.unlink()
            tmp_path.symlink_to(victim)
            return result

        monkeypatch.setattr(catalog_mod.tempfile, "mkstemp", tracking_mkstemp)
        monkeypatch.setattr(catalog_mod.json, "dump", swap_after_dump)

        with pytest.raises(OSError):
            registry.add("second-wf", {"name": "Second"})

        assert victim.read_text(encoding="utf-8") == "untouched"
        if sys.platform != "win32":
            assert stat.S_IMODE(victim.stat().st_mode) == 0o600
        assert not registry.registry_path.is_symlink()
        assert WorkflowRegistry(project_dir).is_installed("first-wf")

    @pytest.mark.skipif(sys.platform == "win32", reason="chmod mode bits not reliable on Windows")
    def test_registry_save_failure_preserves_file_on_disk(self, project_dir, monkeypatch):
        """A failed dump must not truncate the persisted registry, and must
        not alter its on-disk mode either -- the chmod-to-match-existing-mode
        step operates on the temp file, never the target, so a failed save
        (which never reaches os.replace) cannot touch the original's mode."""
        from specify_cli.workflows.catalog import WorkflowRegistry

        registry = WorkflowRegistry(project_dir)
        registry.add("align-wf", {"version": "1.0.0", "source": "catalog"})
        registry.registry_path.chmod(0o644)

        import specify_cli.workflows.catalog as catalog_mod

        def boom(*args, **kwargs):
            raise OSError("disk full")

        monkeypatch.setattr(catalog_mod.json, "dump", boom)
        with pytest.raises(OSError):
            registry.add("align-wf", {"version": "2.0.0", "source": "catalog"})
        monkeypatch.undo()

        fresh = WorkflowRegistry(project_dir)
        assert fresh.get("align-wf")["version"] == "1.0.0"
        assert stat.S_IMODE(registry.registry_path.stat().st_mode) == 0o644
        assert not list(registry.workflows_dir.glob("*.tmp"))