Skip to content

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

55.4 KB
Raw Blame
"""Tests for the bundled ``github`` extension (extensions/github/).

Validates:
- Bundled layout (manifest, README, command file, script twins)
- Catalog registration and wheel/source resolution via ``_locate_bundled_extension``
- Manifest validation, including that no alias claims the core command name
- Install/uninstall through ``ExtensionManager``
- Rendered command artifacts across command mode and skills mode, and in
  particular that ``{SCRIPT}`` resolves to a script the extension actually
  ships under ``.specify/extensions/github/scripts/`` rather than to core
- The ``before_taskstoissues`` / ``after_taskstoissues`` hook contract
- Behaviour of the bash, PowerShell and Python ``resolve-tasks`` twins
"""

from __future__ import annotations

import json
import os
import subprocess
import sys
import tomllib
from pathlib import Path

import pytest
import yaml

from specify_cli import _locate_bundled_extension
from tests.conftest import requires_bash
from tests.parity_helpers import (
    HAS_POWERSHELL,
    HAS_PWSH,
    POWERSHELL_EXE,
    WINDOWS_POWERSHELL,
)


PROJECT_ROOT = Path(__file__).resolve().parent.parent.parent.parent
EXT_DIR = PROJECT_ROOT / "extensions" / "github"
CORE_COMMAND = PROJECT_ROOT / "templates" / "commands" / "taskstoissues.md"

# A released Spec Kit version that satisfies the manifest floor. Installs are
# refused below it, so this cannot be an arbitrary synthetic value.
INSTALL_SPECKIT_VERSION = "1.0.12"
# The floor exists because auto-registered skills did not resolve command
# reference tokens until 0.12.17 (#3544).
MIN_SPECKIT_VERSION = "0.12.17"

COMMAND_NAME = "speckit.github.taskstoissues"
COMMAND_FILE = EXT_DIR / "commands" / f"{COMMAND_NAME}.md"

# The three script twins, keyed by the frontmatter variant that selects them.
SCRIPT_TWINS = {
    "sh": "scripts/bash/resolve-tasks.sh",
    "ps": "scripts/powershell/resolve-tasks.ps1",
    "py": "scripts/python/resolve_tasks.py",
}


def _extension_registrar_agents() -> list[str]:
    """Integrations supported by the extension command registrar."""
    from specify_cli.agents import CommandRegistrar

    return sorted(CommandRegistrar().AGENT_CONFIGS)


EXTENSION_REGISTRAR_AGENTS = _extension_registrar_agents()


def _manifest_dict() -> dict:
    return yaml.safe_load((EXT_DIR / "extension.yml").read_text(encoding="utf-8"))


def _command_frontmatter() -> dict:
    from specify_cli.agents import CommandRegistrar

    frontmatter, _ = CommandRegistrar().parse_frontmatter(
        COMMAND_FILE.read_text(encoding="utf-8")
    )
    return frontmatter


# -- Bundled extension layout -------------------------------------------------


class TestExtensionLayout:
    def test_extension_yml_has_required_fields(self):
        manifest = _manifest_dict()
        assert manifest["extension"]["id"] == "github"
        assert manifest["extension"]["name"] == "GitHub Integration"
        assert manifest["extension"]["author"] == "spec-kit-core"
        # Install rejects a manifest without a requires block.
        assert manifest["requires"]["speckit_version"]
        commands = {c["name"] for c in manifest["provides"]["commands"]}
        assert commands == {COMMAND_NAME}

    def test_readme_exists(self):
        readme = EXT_DIR / "README.md"
        assert readme.is_file()
        assert "GitHub Integration Extension" in readme.read_text(encoding="utf-8")

    def test_readme_documents_migration_from_core(self):
        text = (EXT_DIR / "README.md").read_text(encoding="utf-8")
        assert "specify extension add github" in text
        assert "/speckit.taskstoissues" in text
        assert COMMAND_NAME in text

    def test_readme_documents_generic_registration(self):
        text = (EXT_DIR / "README.md").read_text(encoding="utf-8")
        assert "`generic`" in text
        assert "configured `--commands-dir`" in text
        assert "commands and skills layouts" in text

    def test_command_file_exists(self):
        assert COMMAND_FILE.is_file()

    @pytest.mark.parametrize("rel_path", sorted(SCRIPT_TWINS.values()))
    def test_script_twin_ships(self, rel_path: str):
        assert (EXT_DIR / rel_path).is_file(), f"Missing script: {rel_path}"


# -- Catalog registration and bundle resolution -------------------------------


class TestCatalogEntry:
    def test_catalog_lists_github_as_bundled(self):
        catalog = json.loads(
            (PROJECT_ROOT / "extensions" / "catalog.json").read_text(encoding="utf-8")
        )
        entry = catalog["extensions"]["github"]
        assert entry["bundled"] is True
        assert entry["id"] == "github"
        assert entry["author"] == "spec-kit-core"

    def test_locate_bundled_extension_finds_github(self):
        located = _locate_bundled_extension("github")
        assert located is not None
        assert (located / "extension.yml").is_file()

    def test_pyproject_bundles_the_extension_into_the_wheel(self):
        pyproject = tomllib.loads(
            (PROJECT_ROOT / "pyproject.toml").read_text(encoding="utf-8")
        )
        force_include = pyproject["tool"]["hatch"]["build"]["targets"]["wheel"][
            "force-include"
        ]
        assert (
            force_include["extensions/github"]
            == "specify_cli/core_pack/extensions/github"
        )


# -- Manifest validation ------------------------------------------------------


class TestManifest:
    def test_manifest_validates(self):
        from specify_cli.extensions import ExtensionManifest

        m = ExtensionManifest(EXT_DIR / "extension.yml")
        assert m.id == "github"
        assert m.version == "1.0.4"
        assert [c["name"] for c in m.commands] == [COMMAND_NAME]

    def test_manifest_command_files_exist(self):
        from specify_cli.extensions import ExtensionManifest

        m = ExtensionManifest(EXT_DIR / "extension.yml")
        for cmd in m.commands:
            assert (EXT_DIR / cmd["file"]).is_file()

    def test_no_alias_claims_the_core_command(self):
        """Stage 1 keeps the core command; nothing here may shadow it.

        Alias names are not pattern-checked and the core-namespace guard
        applies to primary names only, so this is author discipline that a
        test has to hold in place.
        """
        from specify_cli.extensions import ExtensionManifest

        m = ExtensionManifest(EXT_DIR / "extension.yml")
        aliases = [a for cmd in m.commands for a in cmd.get("aliases", []) or []]
        assert aliases == []

    def test_declares_its_mandatory_external_tools(self):
        """The command runs ``git config`` and needs the GitHub MCP tools."""
        tools = {t["name"]: t for t in _manifest_dict()["requires"]["tools"]}
        assert set(tools) == {"git", "github-mcp-server"}
        assert all(t["required"] is True for t in tools.values())

    def test_version_floor_covers_all_rendering_prerequisites(self):
        """The floor must exclude releases that cannot render this command.

        Extension-local ``scripts/...`` rewriting landed in 0.12.6 (#3364),
        but auto-registered skills did not resolve ``__SPECKIT_COMMAND_*__``
        tokens until 0.12.17 (#3544). Versions through 0.12.16 therefore
        accept the extension but leak a raw command token in skills mode.
        """
        from packaging.specifiers import SpecifierSet

        floor = _manifest_dict()["requires"]["speckit_version"]
        spec = SpecifierSet(floor)
        assert "0.12.5" not in spec, floor
        assert "0.12.16" not in spec, floor
        assert MIN_SPECKIT_VERSION in spec, floor
        # And the version the install tests use must satisfy it.
        assert INSTALL_SPECKIT_VERSION in spec, floor

    def test_core_command_remains_unchanged(self):
        """Stage 1 is additive: the core command still ships."""
        assert CORE_COMMAND.is_file()


# -- Install / uninstall ------------------------------------------------------


class TestExtensionInstall:
    @pytest.mark.parametrize("skills_mode", [False, True], ids=["commands", "skills"])
    def test_generic_registers_and_removes_artifact_in_configured_directory(
        self, tmp_path: Path, skills_mode: bool
    ):
        from specify_cli.extensions import ExtensionManager

        project = tmp_path / "project"
        (project / ".specify").mkdir(parents=True)
        (project / ".specify" / "init-options.json").write_text(
            json.dumps({"ai": "generic", "ai_skills": skills_mode, "script": "sh"}),
            encoding="utf-8",
        )
        (project / ".specify" / "integration.json").write_text(
            json.dumps(
                {
                    "integration": "generic",
                    "default_integration": "generic",
                    "installed_integrations": ["generic"],
                    "integration_settings": {
                        "generic": {
                            "raw_options": "--commands-dir .myagent/commands"
                            + (" --skills" if skills_mode else ""),
                            "parsed_options": {
                                "commands_dir": ".myagent/commands",
                                "skills": skills_mode,
                            },
                        }
                    },
                }
            ),
            encoding="utf-8",
        )
        commands_dir = project / ".myagent" / "commands"
        commands_dir.mkdir(parents=True)
        core = commands_dir / (
            "speckit-taskstoissues/SKILL.md"
            if skills_mode else "speckit.taskstoissues.md"
        )
        core.parent.mkdir(parents=True, exist_ok=True)
        core.write_text("core command remains unchanged\n", encoding="utf-8")

        manager = ExtensionManager(project)
        manager.install_from_directory(
            EXT_DIR, INSTALL_SPECKIT_VERSION, register_commands=True
        )

        assert manager.registry.is_installed("github")
        assert (
            project / ".specify" / "extensions" / "github" / "extension.yml"
        ).is_file()
        artifact = commands_dir / (
            "speckit-github-taskstoissues/SKILL.md"
            if skills_mode else f"{COMMAND_NAME}.md"
        )
        assert artifact.is_file()
        content = artifact.read_text(encoding="utf-8")
        assert ".specify/extensions/github/scripts/bash/resolve-tasks.sh" in content
        assert "{SCRIPT}" not in content
        assert not (
            project / ".agents" / "skills" / "speckit-github-taskstoissues" / "SKILL.md"
        ).exists()
        assert manager.remove("github")
        assert not artifact.exists()
        assert core.read_text(encoding="utf-8") == "core command remains unchanged\n"

    def test_install_copies_command_and_scripts(self, tmp_path: Path):
        from specify_cli.extensions import ExtensionManager

        (tmp_path / ".specify").mkdir()
        manager = ExtensionManager(tmp_path)
        manifest = manager.install_from_directory(
            EXT_DIR, INSTALL_SPECKIT_VERSION, register_commands=False
        )

        assert manifest.id == "github"
        assert manager.registry.is_installed("github")
        assert {c["name"] for c in manifest.commands} == {COMMAND_NAME}

        installed = tmp_path / ".specify" / "extensions" / "github"
        assert (installed / "commands" / f"{COMMAND_NAME}.md").is_file()
        for rel_path in SCRIPT_TWINS.values():
            assert (installed / rel_path).is_file(), f"Missing script: {rel_path}"

    def test_remove_uninstalls_cleanly(self, tmp_path: Path):
        from specify_cli.extensions import ExtensionManager

        (tmp_path / ".specify").mkdir()
        manager = ExtensionManager(tmp_path)
        manager.install_from_directory(
            EXT_DIR, INSTALL_SPECKIT_VERSION, register_commands=False
        )

        assert manager.remove("github") is True
        assert not manager.registry.is_installed("github")
        assert not (tmp_path / ".specify" / "extensions" / "github").exists()

    @pytest.mark.parametrize(
        "agent,extension_artifacts,core_artifact",
        [
            (
                "copilot",
                [
                    f".github/agents/{COMMAND_NAME}.agent.md",
                    f".github/prompts/{COMMAND_NAME}.prompt.md",
                ],
                ".github/agents/speckit.taskstoissues.agent.md",
            ),
            (
                "claude",
                [".claude/skills/speckit-github-taskstoissues/SKILL.md"],
                ".claude/skills/speckit-taskstoissues/SKILL.md",
            ),
        ],
        ids=["command-mode", "skills-mode"],
    )
    def test_remove_deletes_registered_artifacts_and_keeps_core(
        self,
        tmp_path: Path,
        agent: str,
        extension_artifacts: list[str],
        core_artifact: str,
    ):
        from specify_cli.extensions import ExtensionManager

        (tmp_path / ".specify").mkdir()
        (tmp_path / ".specify" / "init-options.json").write_text(
            json.dumps({"ai": agent, "script": "sh"}), encoding="utf-8"
        )
        core = tmp_path / core_artifact
        core.parent.mkdir(parents=True)
        core.write_text("core taskstoissues\n", encoding="utf-8")

        manager = ExtensionManager(tmp_path)
        manager.install_from_directory(
            EXT_DIR, INSTALL_SPECKIT_VERSION, register_commands=True
        )
        for rel_path in extension_artifacts:
            assert (tmp_path / rel_path).is_file(), f"Not registered: {rel_path}"

        assert manager.remove("github") is True

        for rel_path in extension_artifacts:
            assert not (tmp_path / rel_path).exists(), f"Left behind: {rel_path}"
        assert core.read_text(encoding="utf-8") == "core taskstoissues\n"


# -- Rendered command artifacts -----------------------------------------------


class TestScriptPathResolution:
    def test_extension_registrar_scope_excludes_generic_and_none(self):
        from specify_cli.integrations import INTEGRATION_REGISTRY

        assert set(EXTENSION_REGISTRAR_AGENTS) == set(INTEGRATION_REGISTRY) - {
            "generic", "none"
        }

    def test_frontmatter_uses_plain_extension_local_spelling(self):
        """No ``../../`` escape hatch back into core scripts."""
        scripts = _command_frontmatter()["scripts"]
        assert set(scripts) == set(SCRIPT_TWINS)
        for variant, rel_path in SCRIPT_TWINS.items():
            assert scripts[variant].startswith(rel_path), scripts[variant]
            assert ".." not in scripts[variant]

    def test_adjusted_paths_resolve_under_the_installed_extension(self):
        from specify_cli.agents import CommandRegistrar

        adjusted = CommandRegistrar()._adjust_script_paths(
            _command_frontmatter(), extension_id="github"
        )["scripts"]

        for variant, rel_path in SCRIPT_TWINS.items():
            assert adjusted[variant].startswith(
                f".specify/extensions/github/{rel_path}"
            ), adjusted[variant]

    @pytest.mark.parametrize("variant,rel_path", sorted(SCRIPT_TWINS.items()))
    def test_rendered_command_points_at_a_script_that_ships(
        self, tmp_path: Path, variant: str, rel_path: str
    ):
        """End to end: install, render, and confirm the path exists on disk.

        A verbatim copy of the core command renders an extension-local path
        for core's ``check-prerequisites``, installs happily, and only fails
        when a user runs it. This pins the working spelling.
        """
        from specify_cli.extensions import CommandRegistrar, ExtensionManager

        project = tmp_path / "project"
        (project / ".specify").mkdir(parents=True)
        (project / ".specify" / "init-options.json").write_text(
            json.dumps({"ai": "copilot", "script": variant}), encoding="utf-8"
        )
        (project / ".github" / "agents").mkdir(parents=True)

        manager = ExtensionManager(project)
        manifest = manager.install_from_directory(
            EXT_DIR, INSTALL_SPECKIT_VERSION, register_commands=False
        )
        extension_dir = project / ".specify" / "extensions" / "github"

        CommandRegistrar().register_commands_for_agent(
            "copilot", manifest, extension_dir, project
        )

        rendered = project / ".github" / "agents" / f"{COMMAND_NAME}.agent.md"
        assert rendered.is_file()
        content = rendered.read_text(encoding="utf-8")

        assert "{SCRIPT}" not in content
        expected = f".specify/extensions/github/{rel_path}"
        assert expected in content
        # The rendered path must resolve to a file the extension ships.
        assert (project / expected).is_file()
        # And it must not have been rewritten into the core script tree.
        assert ".specify/scripts/" not in content

    @pytest.mark.parametrize("agent", EXTENSION_REGISTRAR_AGENTS)
    def test_every_extension_registrar_integration_renders_the_command(
        self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch, agent: str
    ):
        """The command works for every extension registrar integration.

        Covers both layouts in one sweep — command-file agents, skills-mode
        agents, and Hermes, which installs to ``~/.hermes/skills`` rather than
        a project-local directory (hence the redirected home). Generic has no
        static registrar config and does not register extension add-ons.
        """
        from specify_cli.extensions import CommandRegistrar, ExtensionManager

        home = tmp_path / "home"
        home.mkdir()
        monkeypatch.setenv("HOME", str(home))
        monkeypatch.setenv("USERPROFILE", str(home))

        project = tmp_path / "project"
        (project / ".specify").mkdir(parents=True)
        (project / ".specify" / "init-options.json").write_text(
            json.dumps({"ai": agent, "script": "sh"}), encoding="utf-8"
        )

        manager = ExtensionManager(project)
        manifest = manager.install_from_directory(
            EXT_DIR, INSTALL_SPECKIT_VERSION, register_commands=False
        )
        CommandRegistrar().register_commands_for_agent(
            agent, manifest, project / ".specify" / "extensions" / "github", project
        )

        installed = project / ".specify" / "extensions"
        artifacts = [
            p
            for root in (project, home)
            for p in root.rglob("*")
            if p.is_file()
            and installed not in p.parents
            and "taskstoissues" in p.as_posix().lower()
        ]
        assert artifacts, f"{agent} produced no command artifact"

        expected = f".specify/extensions/github/{SCRIPT_TWINS['sh']}"
        bodies = [p.read_text(encoding="utf-8") for p in artifacts]

        # No artifact may leak an unresolved placeholder...
        for artifact, content in zip(artifacts, bodies):
            assert "{SCRIPT}" not in content, artifact
        # ...and the command body must carry the resolved extension-local path.
        # Some integrations also emit a thin companion file (e.g. Copilot's
        # prompt shim, which only points at the agent), so this is "at least
        # one" rather than "all".
        assert any(expected in content for content in bodies), (
            f"{agent}: no artifact references {expected} "
            f"(wrote {[p.name for p in artifacts]})"
        )

    def test_rendered_skill_points_at_a_script_that_ships(self, tmp_path: Path):
        """Skills-mode layouts resolve ``{SCRIPT}`` the same way."""
        from specify_cli.extensions import CommandRegistrar, ExtensionManager

        project = tmp_path / "project"
        (project / ".specify").mkdir(parents=True)
        (project / ".specify" / "init-options.json").write_text(
            json.dumps({"ai": "codex", "ai_skills": True, "script": "sh"}),
            encoding="utf-8",
        )
        (project / ".agents" / "skills").mkdir(parents=True)

        manager = ExtensionManager(project)
        manifest = manager.install_from_directory(
            EXT_DIR, INSTALL_SPECKIT_VERSION, register_commands=False
        )
        extension_dir = project / ".specify" / "extensions" / "github"

        CommandRegistrar().register_commands_for_agent(
            "codex", manifest, extension_dir, project
        )

        skill = (
            project / ".agents" / "skills" / "speckit-github-taskstoissues" / "SKILL.md"
        )
        assert skill.is_file()
        content = skill.read_text(encoding="utf-8")

        assert "{SCRIPT}" not in content
        expected = f".specify/extensions/github/{SCRIPT_TWINS['sh']}"
        assert expected in content
        assert (project / expected).is_file()


# -- Behaviour parity with the core command -----------------------------------


class TestCommandBody:
    def test_preserves_the_hook_contract(self):
        """The hook keys are literal strings read out of extensions.yml."""
        body = COMMAND_FILE.read_text(encoding="utf-8")
        assert "hooks.before_taskstoissues" in body
        assert "hooks.after_taskstoissues" in body

    def test_git_extension_hooks_still_target_those_keys(self):
        """The live consumers of the hook contract keep firing."""
        git_manifest = yaml.safe_load(
            (PROJECT_ROOT / "extensions" / "git" / "extension.yml").read_text(
                encoding="utf-8"
            )
        )
        hooks = git_manifest["hooks"]
        assert "before_taskstoissues" in hooks
        assert "after_taskstoissues" in hooks

    def test_declares_the_github_mcp_tools(self):
        tools = _command_frontmatter()["tools"]
        assert "github/github-mcp-server/list_issues" in tools
        assert "github/github-mcp-server/issue_write" in tools

    def test_preserves_remote_validation(self):
        body = COMMAND_FILE.read_text(encoding="utf-8")
        assert "git config --get remote.origin.url" in body
        assert "ONLY PROCEED TO NEXT STEPS IF THE REMOTE IS A GITHUB URL" in body
        assert (
            "UNDER NO CIRCUMSTANCES EVER CREATE ISSUES IN REPOSITORIES THAT DO NOT "
            "MATCH THE REMOTE URL" in body
        )

    def test_readme_lists_every_dollar_skills_agent(self):
        """The invocation guide must name all `$speckit-` agents, not some.

        Regression: Command Code was omitted, so its users were pointed at a
        syntax their agent does not use.
        """
        from specify_cli._invocation_style import DOLLAR_SKILLS_AGENTS

        readme = (EXT_DIR / "README.md").read_text(encoding="utf-8")
        note = next(
            line for line in readme.splitlines() if "$speckit-github-taskstoissues" in line
        )

        display_names = {
            "codex": "Codex",
            "zcode": "ZCode",
            "command-code": "Command Code",
        }
        # If a new dollar-skills agent appears, this fails until it is named.
        assert set(display_names) == set(DOLLAR_SKILLS_AGENTS), (
            "DOLLAR_SKILLS_AGENTS changed; update the README invocation note "
            f"and this mapping: {sorted(DOLLAR_SKILLS_AGENTS)}"
        )
        for agent, display in display_names.items():
            assert display in note, f"README omits {display} ({agent}): {note}"

    def test_preserves_deduplication_and_pagination(self):
        body = COMMAND_FILE.read_text(encoding="utf-8")
        assert "list_issues" in body
        # Both open and closed issues: the tool returns both when `state` is omitted.
        assert "Do not pass a `state` value" in body
        # Cursor-based pagination, and the early exit that bounds the call count.
        assert "perPage: 100" in body
        assert "`after` parameter" in body
        assert "endCursor" in body
        assert "Stop paginating as soon as every task ID has been matched" in body
        # Four-digit and longer task IDs must still match.
        assert r"\bT\d{3,}\b" in body

    def test_body_differs_from_core_only_in_deprecation_and_script_invocation(self):
        """Behaviour parity, enforced as a diff rather than as spot checks.

        Apart from core-only deprecation metadata and notice, everything except
        the ``scripts:`` frontmatter and the two lines that read the new ``TASKS``
        value must match verbatim, so the two cannot silently drift while both exist.
        """
        import difflib

        core_text = CORE_COMMAND.read_text(encoding="utf-8")
        before_notice, notice_and_workflow = core_text.split("## Deprecation Notice\n", 1)
        _, workflow = notice_and_workflow.split("## User Input", 1)
        core = (before_notice + "## User Input" + workflow).splitlines()
        ext = COMMAND_FILE.read_text(encoding="utf-8").splitlines()
        core_description = yaml.safe_load(core[1])["description"]
        ext_description = yaml.safe_load(ext[1])["description"]
        assert core_description == "Deprecated: " + ext_description
        core[1] = ext[1]
        changed = [
            line
            for line in difflib.unified_diff(core, ext, n=0)
            if line.startswith(("+", "-")) and not line.startswith(("+++", "---"))
        ]

        # 3 script lines + 2 outline lines, each as one removal and one addition.
        assert len(changed) == 10, "\n".join(changed)

        markers = (
            "check-prerequisites",
            "check_prerequisites",
            "resolve-tasks",
            "resolve_tasks",
            "AVAILABLE_DOCS",
            "path to **tasks**",
        )
        assert all(
            any(marker in line for marker in markers) for line in changed
        ), "\n".join(changed)

    def test_uses_the_portable_command_reference_token(self):
        """A literal invocation would be correct for exactly one agent."""
        body = COMMAND_FILE.read_text(encoding="utf-8")
        assert "__SPECKIT_COMMAND_CONVERGE__" in body


# -- resolve-tasks script twins -----------------------------------------------

PY_SCRIPT = EXT_DIR / SCRIPT_TWINS["py"]
SH_SCRIPT = EXT_DIR / SCRIPT_TWINS["sh"]
PS_SCRIPT = EXT_DIR / SCRIPT_TWINS["ps"]


def _make_feature_project(tmp_path: Path) -> Path:
    project = tmp_path / "project"
    feature = project / "specs" / "001-demo"
    feature.mkdir(parents=True)
    (project / ".specify").mkdir(exist_ok=True)
    (project / ".specify" / "feature.json").write_text(
        json.dumps({"feature_directory": "specs/001-demo"}), encoding="utf-8"
    )
    (feature / "plan.md").write_text("# Plan\n", encoding="utf-8")
    (feature / "tasks.md").write_text(
        "- [ ] T001 Create project structure\n", encoding="utf-8"
    )
    (feature / "research.md").write_text("# Research\n", encoding="utf-8")
    return project


def _resolver_env() -> dict[str, str]:
    """Environment without inherited project or feature overrides."""
    env = dict(os.environ)
    env.pop("SPECIFY_FEATURE_DIRECTORY", None)
    env.pop("SPECIFY_INIT_DIR", None)
    env.pop("SPECIFY_FEATURE_NO_PERSIST", None)
    return env


def _run(cmd: list[str], cwd: Path) -> subprocess.CompletedProcess:
    return subprocess.run(
        cmd, cwd=cwd, capture_output=True, text=True, env=_resolver_env()
    )


class TestResolveTasksPython:
    def test_reports_feature_dir_tasks_and_docs(self, tmp_path: Path):
        project = _make_feature_project(tmp_path)
        result = _run([sys.executable, str(PY_SCRIPT), "--json"], project)

        assert result.returncode == 0, result.stderr
        payload = json.loads(result.stdout)
        assert Path(payload["FEATURE_DIR"]) == project / "specs" / "001-demo"
        assert Path(payload["TASKS"]) == project / "specs" / "001-demo" / "tasks.md"
        assert payload["AVAILABLE_DOCS"] == ["research.md", "tasks.md"]

    def test_ignores_inherited_resolver_overrides(
        self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
    ):
        project = _make_feature_project(tmp_path)
        feature_json = project / ".specify" / "feature.json"
        before = feature_json.read_bytes()
        monkeypatch.setenv("SPECIFY_INIT_DIR", str(tmp_path / "missing"))
        monkeypatch.setenv("SPECIFY_FEATURE_DIRECTORY", "specs/missing")
        monkeypatch.setenv("SPECIFY_FEATURE_NO_PERSIST", "1")

        result = _run([sys.executable, str(PY_SCRIPT), "--json"], project)

        assert result.returncode == 0, result.stderr
        assert Path(json.loads(result.stdout)["FEATURE_DIR"]) == (
            project / "specs" / "001-demo"
        )
        assert feature_json.read_bytes() == before

    def test_errors_when_tasks_md_is_missing(self, tmp_path: Path):
        project = _make_feature_project(tmp_path)
        (project / "specs" / "001-demo" / "tasks.md").unlink()

        result = _run([sys.executable, str(PY_SCRIPT), "--json"], project)

        assert result.returncode == 1
        assert "tasks.md not found" in result.stderr

    def test_text_mode_survives_a_cp1252_stdout(self, tmp_path: Path):
        """Regression: U+2713 is unencodable in cp1252.

        On Windows stdout falls back to the ANSI code page whenever it is not
        a console — a pipe or a redirect, which is exactly how agents invoke
        these scripts — so printing the glyph raised UnicodeEncodeError and
        aborted the report right after ``AVAILABLE_DOCS:``.
        """
        project = _make_feature_project(tmp_path)
        env = {**_resolver_env(), "PYTHONIOENCODING": "cp1252"}
        result = subprocess.run(
            [sys.executable, str(PY_SCRIPT)],
            cwd=project,
            capture_output=True,
            text=True,
            env=env,
        )

        assert result.returncode == 0, result.stderr
        assert "UnicodeEncodeError" not in result.stderr
        # The docs section must be complete, not truncated at the first marker.
        assert "AVAILABLE_DOCS:" in result.stdout
        assert "research.md" in result.stdout
        assert "tasks.md" in result.stdout
        # ASCII fallback, matching core and the PowerShell twin.
        assert "[OK] tasks.md" in result.stdout

    def test_json_mode_survives_a_cp1252_stdout_with_a_non_ascii_path(
        self, tmp_path: Path
    ):
        """Regression: the rendered command always runs ``--json``.

        Raw non-ASCII in the payload raised UnicodeEncodeError on a legacy
        stdout; ASCII escapes decode back to the same path.
        """
        project = tmp_path / "project"
        feature = project / "specs" / "001-功能"
        feature.mkdir(parents=True)
        (project / ".specify").mkdir()
        (project / ".specify" / "feature.json").write_text(
            json.dumps({"feature_directory": "specs/001-功能"}), encoding="utf-8"
        )
        (feature / "plan.md").write_text("# Plan\n", encoding="utf-8")
        (feature / "tasks.md").write_text("- [ ] T001 Task\n", encoding="utf-8")

        env = {**_resolver_env(), "PYTHONIOENCODING": "cp1252"}
        result = subprocess.run(
            [sys.executable, str(PY_SCRIPT), "--json"],
            cwd=project,
            capture_output=True,
            text=True,
            encoding="cp1252",
            env=env,
        )

        assert result.returncode == 0, result.stderr
        assert "UnicodeEncodeError" not in result.stderr
        assert result.stdout.isascii()
        payload = json.loads(result.stdout)
        assert Path(payload["FEATURE_DIR"]) == feature
        assert payload["AVAILABLE_DOCS"] == ["tasks.md"]

    def test_text_mode_uses_the_glyph_when_stdout_can_encode_it(
        self, tmp_path: Path
    ):
        project = _make_feature_project(tmp_path)
        env = {**_resolver_env(), "PYTHONIOENCODING": "utf-8"}
        result = subprocess.run(
            [sys.executable, str(PY_SCRIPT)],
            cwd=project,
            capture_output=True,
            text=True,
            encoding="utf-8",
            env=env,
        )

        assert result.returncode == 0, result.stderr
        assert "✓ tasks.md" in result.stdout

    def test_does_not_write_feature_json_without_an_override(self, tmp_path: Path):
        """Plain resolution stays read-only; only an override persists."""
        project = _make_feature_project(tmp_path)
        feature_json = project / ".specify" / "feature.json"
        before = feature_json.read_bytes()

        result = _run([sys.executable, str(PY_SCRIPT), "--json"], project)

        assert result.returncode == 0, result.stderr
        assert feature_json.read_bytes() == before


def _run_ps(project: Path) -> subprocess.CompletedProcess:
    return subprocess.run(
        [POWERSHELL_EXE, "-NoProfile", "-File", str(PS_SCRIPT), "-Json"],
        cwd=project,
        capture_output=True,
        text=True,
        encoding="utf-8",
        env=_resolver_env(),
    )


def _run_py(project: Path) -> subprocess.CompletedProcess:
    return subprocess.run(
        [sys.executable, str(PY_SCRIPT), "--json"],
        cwd=project,
        capture_output=True,
        text=True,
        encoding="utf-8",
        env=_resolver_env(),
    )


@pytest.mark.skipif(not HAS_POWERSHELL, reason="no PowerShell available")
class TestResolveTasksPowerShellParity:
    """The PowerShell twin must agree with the Python twin."""

    @pytest.mark.parametrize(
        "exe",
        [
            pytest.param(
                "pwsh",
                marks=pytest.mark.skipif(not HAS_PWSH, reason="pwsh not available"),
                id="pwsh",
            ),
            pytest.param(
                WINDOWS_POWERSHELL,
                marks=pytest.mark.skipif(
                    not WINDOWS_POWERSHELL, reason="Windows PowerShell 5.1 not available"
                ),
                id="windows-powershell-5.1",
            ),
        ],
    )
    def test_reads_bomless_utf8_feature_json(self, tmp_path: Path, exe: str | None):
        """The vendored resolver must decode non-ASCII paths on Windows PS 5.1."""
        assert exe is not None
        project = _make_feature_project(tmp_path)
        feature = _add_feature(project, "002-后台信息架构")
        feature_json = project / ".specify" / "feature.json"
        raw = json.dumps(
            {"feature_directory": "specs/002-后台信息架构"}, ensure_ascii=False
        ).encode("utf-8")
        assert raw.startswith(b"{") and "后台信息架构".encode("utf-8") in raw
        feature_json.write_bytes(raw)

        # Write the PowerShell result as UTF-8 inside the process so the
        # Windows console code page cannot alter a correct Unicode path.
        output = tmp_path / "resolved.json"
        env = {
            **_resolver_env(),
            "SPECKIT_RESOLVER_SCRIPT": str(PS_SCRIPT),
            "SPECKIT_RESOLVER_OUTPUT": str(output),
        }
        result = subprocess.run(
            [
                exe,
                "-NoProfile",
                "-Command",
                "$payload = & $env:SPECKIT_RESOLVER_SCRIPT -Json; "
                "[System.IO.File]::WriteAllText("
                "$env:SPECKIT_RESOLVER_OUTPUT, [string]$payload, "
                "(New-Object System.Text.UTF8Encoding($false)))",
            ],
            cwd=project,
            capture_output=True,
            text=True,
            env=env,
        )

        assert result.returncode == 0, result.stderr
        assert output.is_file(), result.stderr
        payload = json.loads(output.read_text(encoding="utf-8"))
        assert payload["FEATURE_DIR"] == str(feature)
        assert payload["TASKS"] == str(feature / "tasks.md")
        assert payload["AVAILABLE_DOCS"] == ["tasks.md"]

    def test_json_output_matches_python(self, tmp_path: Path):
        project = _make_feature_project(tmp_path)

        ps = _run_ps(project)
        py = _run_py(project)

        assert ps.returncode == 0, ps.stderr
        assert py.returncode == 0, py.stderr
        ps_payload = json.loads(ps.stdout)
        py_payload = json.loads(py.stdout)
        assert list(ps_payload) == ["FEATURE_DIR", "TASKS", "AVAILABLE_DOCS"]
        assert Path(ps_payload["FEATURE_DIR"]) == Path(py_payload["FEATURE_DIR"])
        assert Path(ps_payload["TASKS"]) == Path(py_payload["TASKS"])
        assert ps_payload["AVAILABLE_DOCS"] == py_payload["AVAILABLE_DOCS"]
        assert ps_payload["AVAILABLE_DOCS"] == ["research.md", "tasks.md"]

    def test_single_document_stays_a_json_array(self, tmp_path: Path):
        """ConvertTo-Json unwraps one-element arrays unless forced."""
        project = _make_feature_project(tmp_path)
        (project / "specs" / "001-demo" / "research.md").unlink()

        ps = _run_ps(project)
        py = _run_py(project)

        assert ps.returncode == 0, ps.stderr
        assert py.returncode == 0, py.stderr
        ps_docs = json.loads(ps.stdout)["AVAILABLE_DOCS"]
        assert isinstance(ps_docs, list)
        assert ps_docs == ["tasks.md"]
        assert ps_docs == json.loads(py.stdout)["AVAILABLE_DOCS"]

    def test_missing_tasks_md_fails_like_python(self, tmp_path: Path):
        project = _make_feature_project(tmp_path)
        (project / "specs" / "001-demo" / "tasks.md").unlink()

        ps = _run_ps(project)
        py = _run_py(project)

        assert ps.returncode == 1
        assert py.returncode == 1
        assert "tasks.md not found" in ps.stderr
        assert "tasks.md not found" in py.stderr
        assert ps.stdout.strip() == ""


@requires_bash
class TestResolveTasksBashJsonEscape:
    """``json_escape`` must emit valid JSON, matching core's implementation.

    Regression: the escape table silently lost a level of backslash quoting,
    so backslashes passed through unescaped and ``\\n``/``\\t`` collapsed to
    the bare letters ``n``/``t``. A Windows feature path would have produced
    invalid JSON that the agent then failed to parse.
    """

    CASES = {
        "backslash": "a\\b",
        "windows_path": "C:\\Users\\dev\\specs",
        "quote": 'a"b',
        "newline": "a\nb",
        "tab": "a\tb",
        "carriage_return": "a\rb",
        "control": "a\x01b",
    }

    @staticmethod
    def _escape(script: Path, tmp_path: Path, value: str) -> str:
        """Run the script's own ``json_escape`` over *value*, byte-exactly."""
        import re

        body = re.search(
            r"(json_escape\(\) \{.*?\n\})",
            script.read_text(encoding="utf-8"),
            re.S,
        )
        assert body, f"no json_escape found in {script}"

        # Callers pass a per-script subdirectory so the two harnesses do not
        # collide; pytest only creates tmp_path itself.
        tmp_path.mkdir(parents=True, exist_ok=True)
        payload = tmp_path / "value.txt"
        payload.write_text(value, encoding="utf-8", newline="")
        harness = tmp_path / "harness.sh"
        # Read the raw value from a file so the harness itself needs no quoting.
        harness.write_text(
            body.group(1) + '\nvalue="$(cat "$1")"\njson_escape "$value"\n',
            encoding="utf-8",
            newline="\n",
        )
        return subprocess.run(
            ["bash", str(harness), str(payload)],
            capture_output=True,
            check=True,
        ).stdout.decode("utf-8")

    @pytest.mark.parametrize("name", sorted(CASES))
    def test_escaping_round_trips_through_json(self, tmp_path: Path, name: str):
        value = self.CASES[name]
        escaped = self._escape(SH_SCRIPT, tmp_path, value)

        # The escaped text must be a valid JSON string body that decodes back
        # to exactly what went in.
        assert json.loads(f'"{escaped}"') == value, escaped

    @pytest.mark.parametrize("name", sorted(CASES))
    def test_matches_core_json_escape(self, tmp_path: Path, name: str):
        """Kept in step with core rather than diverging quietly."""
        core_common = PROJECT_ROOT / "scripts" / "bash" / "common.sh"
        value = self.CASES[name]

        ours = self._escape(SH_SCRIPT, tmp_path / "ours", value)
        theirs = self._escape(core_common, tmp_path / "theirs", value)

        assert ours == theirs

    def test_json_output_parses_for_a_path_with_a_backslash(self, tmp_path: Path):
        """End to end: a feature directory containing a backslash.

        POSIX allows a backslash in a filename, so this exercises the real
        emit path rather than the helper in isolation.
        """
        project = _make_feature_project(tmp_path)
        odd = project / "specs" / "we\\ird"
        try:
            odd.mkdir()
        except OSError:
            pytest.skip("filesystem rejects backslash in a path component")
        (odd / "plan.md").write_text("# Plan\n", encoding="utf-8")
        (odd / "tasks.md").write_text("- [ ] T001 x\n", encoding="utf-8")
        (project / ".specify" / "feature.json").write_text(
            json.dumps({"feature_directory": "specs/we\\ird"}), encoding="utf-8"
        )

        result = _run(["bash", str(SH_SCRIPT), "--json"], project)

        assert result.returncode == 0, result.stderr
        payload = json.loads(result.stdout)  # would raise on invalid escaping
        assert payload["FEATURE_DIR"].endswith("we\\ird")


@requires_bash
class TestResolveTasksBash:
    def test_matches_the_python_twin(self, tmp_path: Path):
        project = _make_feature_project(tmp_path)

        bash_result = _run(["bash", str(SH_SCRIPT), "--json"], project)
        py_result = _run([sys.executable, str(PY_SCRIPT), "--json"], project)

        assert bash_result.returncode == 0, bash_result.stderr
        assert py_result.returncode == 0, py_result.stderr

        bash_payload = json.loads(bash_result.stdout)
        py_payload = json.loads(py_result.stdout)
        assert bash_payload["AVAILABLE_DOCS"] == py_payload["AVAILABLE_DOCS"]
        assert Path(bash_payload["FEATURE_DIR"]).name == Path(
            py_payload["FEATURE_DIR"]
        ).name
        assert Path(bash_payload["TASKS"]).name == Path(py_payload["TASKS"]).name

    def test_errors_when_tasks_md_is_missing(self, tmp_path: Path):
        project = _make_feature_project(tmp_path)
        (project / "specs" / "001-demo" / "tasks.md").unlink()

        result = _run(["bash", str(SH_SCRIPT), "--json"], project)

        assert result.returncode == 1
        assert "tasks.md not found" in result.stderr


# -- Override contract, across all three twins --------------------------------

_TWINS = [
    pytest.param("sh", marks=requires_bash, id="bash"),
    pytest.param(
        "ps",
        marks=pytest.mark.skipif(not HAS_POWERSHELL, reason="no PowerShell available"),
        id="powershell",
    ),
    pytest.param("py", id="python"),
]


def _run_twin(
    twin: str, cwd: Path, **overrides: str
) -> subprocess.CompletedProcess:
    argv = {
        "sh": ["bash", str(SH_SCRIPT), "--json"],
        "ps": [POWERSHELL_EXE, "-NoProfile", "-File", str(PS_SCRIPT), "-Json"],
        "py": [sys.executable, str(PY_SCRIPT), "--json"],
    }[twin]
    return subprocess.run(
        argv,
        cwd=cwd,
        capture_output=True,
        text=True,
        encoding="utf-8",
        env={**_resolver_env(), **overrides},
    )


def _add_feature(project: Path, name: str) -> Path:
    feature = project / "specs" / name
    feature.mkdir(parents=True)
    (feature / "plan.md").write_text("# Plan\n", encoding="utf-8")
    (feature / "tasks.md").write_text("- [ ] T001 Task\n", encoding="utf-8")
    return feature


@pytest.mark.parametrize("twin", _TWINS)
@pytest.mark.parametrize(
    "integration,separator",
    [(None, None), ("copilot", "."), ("forge", "-"), ("cline", "-")],
    ids=["unconfigured", "dot", "forge", "cline"],
)
class TestResolverPrerequisiteHints:
    @pytest.fixture
    def project(
        self, tmp_path: Path, integration: str | None, separator: str | None
    ) -> Path:
        project = _make_feature_project(tmp_path)
        if integration is not None:
            (project / ".specify" / "integration.json").write_text(
                json.dumps(
                    {
                        "integration": integration,
                        "default_integration": integration,
                        "installed_integrations": [integration],
                        "integration_settings": {
                            integration: {"invoke_separator": separator}
                        },
                    }
                ),
                encoding="utf-8",
            )
        return project

    @pytest.mark.parametrize(
        "missing,error,hint",
        [
            (
                "feature",
                "Feature directory not found",
                "Run the Spec Kit specify command first to create the feature structure.",
            ),
            (
                "plan.md",
                "plan.md not found",
                "Run the Spec Kit plan command first to create the implementation plan.",
            ),
            (
                "tasks.md",
                "tasks.md not found",
                "Run the Spec Kit tasks command first to create the task list.",
            ),
        ],
        ids=["missing-feature", "missing-plan", "missing-tasks"],
    )
    def test_missing_prerequisite_has_a_syntax_neutral_hint(
        self, project: Path, twin: str, missing: str, error: str, hint: str
    ):
        if missing == "feature":
            (project / ".specify" / "feature.json").write_text(
                json.dumps({"feature_directory": "specs/does-not-exist"}),
                encoding="utf-8",
            )
        else:
            (project / "specs" / "001-demo" / missing).unlink()

        result = _run_twin(twin, project)

        assert result.returncode == 1
        assert result.stdout == ""
        assert f"ERROR: {error}" in result.stderr
        assert result.stderr.splitlines()[-1] == hint

    def test_complete_feature_still_resolves(self, project: Path, twin: str):
        feature = project / "specs" / "001-demo"
        (feature / "data-model.md").write_text("# Data Model\n", encoding="utf-8")
        contracts = feature / "contracts"
        contracts.mkdir()
        (contracts / "api.yaml").write_text("openapi: 3.0.0\n", encoding="utf-8")
        (feature / "quickstart.md").write_text("# Quickstart\n", encoding="utf-8")

        result = _run_twin(twin, project)

        assert result.returncode == 0, result.stderr
        assert result.stderr == ""
        payload = json.loads(result.stdout)
        assert Path(payload["FEATURE_DIR"]).parts[-2:] == ("specs", "001-demo")
        assert Path(payload["TASKS"]).parts[-3:] == ("specs", "001-demo", "tasks.md")
        assert payload["AVAILABLE_DOCS"] == [
            "research.md",
            "data-model.md",
            "contracts/",
            "quickstart.md",
            "tasks.md",
        ]


@pytest.mark.parametrize("twin", _TWINS)
class TestResolverOverrides:
    """``SPECIFY_INIT_DIR`` and ``SPECIFY_FEATURE_DIRECTORY``, per twin.

    Core's parity suites never execute these vendored copies, so drift in any
    one twin's precedence, relative-path handling or failure mode would
    otherwise ship unnoticed. Paths are compared by trailing components
    because Git Bash on Windows reports POSIX-style paths.
    """

    def test_feature_directory_override_beats_feature_json(
        self, tmp_path: Path, twin: str
    ):
        project = _make_feature_project(tmp_path)
        _add_feature(project, "002-override")

        result = _run_twin(
            twin, project, SPECIFY_FEATURE_DIRECTORY="specs/002-override"
        )

        assert result.returncode == 0, result.stderr
        payload = json.loads(result.stdout)
        # Relative override resolves against the project root.
        assert Path(payload["FEATURE_DIR"]).parts[-2:] == ("specs", "002-override")
        assert payload["AVAILABLE_DOCS"] == ["tasks.md"]

    def test_absolute_feature_directory_override(self, tmp_path: Path, twin: str):
        project = _make_feature_project(tmp_path)
        feature = _add_feature(project, "003-absolute")
        absolute = feature.as_posix()
        if twin == "sh":
            # Bash, like core's common.sh, treats only a leading "/" as
            # absolute, so give it the path in its own terms (on Git Bash a
            # Windows drive path would otherwise be joined to the root).
            absolute = subprocess.run(
                ["bash", "-c", "pwd"],
                cwd=feature,
                capture_output=True,
                text=True,
                check=True,
            ).stdout.strip()

        result = _run_twin(twin, project, SPECIFY_FEATURE_DIRECTORY=absolute)

        assert result.returncode == 0, result.stderr
        assert Path(json.loads(result.stdout)["FEATURE_DIR"]).name == "003-absolute"

    def test_missing_feature_directory_override_fails(
        self, tmp_path: Path, twin: str
    ):
        project = _make_feature_project(tmp_path)

        result = _run_twin(
            twin, project, SPECIFY_FEATURE_DIRECTORY="specs/does-not-exist"
        )

        assert result.returncode == 1
        assert "Feature directory not found" in result.stderr
        assert result.stdout.strip() == ""

    def test_relative_init_dir_is_resolved_from_cwd(self, tmp_path: Path, twin: str):
        _make_feature_project(tmp_path)

        result = _run_twin(twin, tmp_path, SPECIFY_INIT_DIR="project")

        assert result.returncode == 0, result.stderr
        feature_dir = Path(json.loads(result.stdout)["FEATURE_DIR"])
        assert feature_dir.parts[-3:] == ("project", "specs", "001-demo")

    def test_init_dir_beats_the_enclosing_project(self, tmp_path: Path, twin: str):
        """The override wins even when cwd is itself inside a Spec Kit project."""
        project = _make_feature_project(tmp_path)
        decoy = tmp_path / "decoy"
        (decoy / ".specify").mkdir(parents=True)

        result = _run_twin(twin, decoy, SPECIFY_INIT_DIR=project.as_posix())

        assert result.returncode == 0, result.stderr
        assert Path(json.loads(result.stdout)["FEATURE_DIR"]).name == "001-demo"

    def test_nonexistent_init_dir_fails(self, tmp_path: Path, twin: str):
        project = _make_feature_project(tmp_path)

        result = _run_twin(
            twin, project, SPECIFY_INIT_DIR=(tmp_path / "missing").as_posix()
        )

        assert result.returncode == 1
        assert "SPECIFY_INIT_DIR does not point to an existing directory" in (
            result.stderr
        )
        assert result.stdout.strip() == ""

    def test_init_dir_without_specify_fails(self, tmp_path: Path, twin: str):
        """No silent fallback to cwd when the override is not a project."""
        project = _make_feature_project(tmp_path)
        plain = tmp_path / "plain"
        plain.mkdir()

        result = _run_twin(twin, project, SPECIFY_INIT_DIR=plain.as_posix())

        assert result.returncode == 1
        assert "SPECIFY_INIT_DIR is not a Spec Kit project" in result.stderr
        assert result.stdout.strip() == ""


@pytest.mark.parametrize("twin", _TWINS)
class TestCoreResolutionParity:
    """Behaviours core's ``check-prerequisites`` has that this twin must keep.

    Core resolves via ``check-prerequisites --require-tasks --include-tasks``,
    which persists an override into ``feature.json`` and gates on ``plan.md``
    before ``tasks.md``. The process-wide ``SPECIFY_FEATURE_NO_PERSIST`` opt-out
    must suppress that write without changing which feature is resolved.
    Divergence here is not cosmetic: a lost override makes the next run read a
    different feature's task list, and a missing plan gate lets the command
    run where core would stop.
    """

    def test_override_persists_for_the_next_run(self, tmp_path: Path, twin: str):
        """feature.json points at A, an override selects B, then B sticks."""
        project = _make_feature_project(tmp_path)
        _add_feature(project, "002-override")
        feature_json = project / ".specify" / "feature.json"

        first = _run_twin(
            twin, project, SPECIFY_FEATURE_DIRECTORY="specs/002-override"
        )
        assert first.returncode == 0, first.stderr
        assert Path(json.loads(first.stdout)["FEATURE_DIR"]).name == "002-override"

        # Persisted as the relative path the other twins store, not absolute.
        stored = json.loads(feature_json.read_text(encoding="utf-8"))
        assert stored["feature_directory"] == "specs/002-override"

        # Second run, no override: core selects B again, so this must too.
        second = _run_twin(twin, project)
        assert second.returncode == 0, second.stderr
        assert Path(json.loads(second.stdout)["FEATURE_DIR"]).name == "002-override"

    @pytest.mark.parametrize("no_persist", ["1", "true"])
    def test_no_persist_preserves_existing_pin(
        self, tmp_path: Path, twin: str, no_persist: str
    ):
        project = _make_feature_project(tmp_path)
        _add_feature(project, "002-override")
        feature_json = project / ".specify" / "feature.json"
        before = feature_json.read_bytes()

        result = _run_twin(
            twin,
            project,
            SPECIFY_FEATURE_DIRECTORY="specs/002-override",
            SPECIFY_FEATURE_NO_PERSIST=no_persist,
        )

        assert result.returncode == 0, result.stderr
        payload = json.loads(result.stdout)
        assert Path(payload["FEATURE_DIR"]).parts[-2:] == ("specs", "002-override")
        assert Path(payload["TASKS"]).parts[-3:] == ("specs", "002-override", "tasks.md")
        assert payload["AVAILABLE_DOCS"] == ["tasks.md"]
        assert feature_json.read_bytes() == before

        second = _run_twin(twin, project)
        assert second.returncode == 0, second.stderr
        assert Path(json.loads(second.stdout)["FEATURE_DIR"]).name == "001-demo"

    @pytest.mark.parametrize("no_persist", ["1", "true"])
    def test_no_persist_does_not_create_feature_json(
        self, tmp_path: Path, twin: str, no_persist: str
    ):
        project = _make_feature_project(tmp_path)
        feature_json = project / ".specify" / "feature.json"
        feature_json.unlink()

        result = _run_twin(
            twin,
            project,
            SPECIFY_FEATURE_DIRECTORY="specs/001-demo",
            SPECIFY_FEATURE_NO_PERSIST=no_persist,
        )

        assert result.returncode == 0, result.stderr
        assert Path(json.loads(result.stdout)["FEATURE_DIR"]).parts[-2:] == (
            "specs",
            "001-demo",
        )
        assert not feature_json.exists()

    def test_missing_plan_md_is_rejected(self, tmp_path: Path, twin: str):
        """Core stops without plan.md even when tasks.md is present."""
        project = _make_feature_project(tmp_path)
        (project / "specs" / "001-demo" / "plan.md").unlink()

        result = _run_twin(twin, project)

        assert result.returncode == 1
        assert "plan.md not found" in result.stderr
        assert result.stdout.strip() == ""

    def test_spec_md_is_not_required(self, tmp_path: Path, twin: str):
        """Core passes no --require-spec here, so spec.md stays optional."""
        project = _make_feature_project(tmp_path)
        assert not (project / "specs" / "001-demo" / "spec.md").exists()

        result = _run_twin(twin, project)

        assert result.returncode == 0, result.stderr


@pytest.mark.skipif(os.name == "nt", reason="POSIX permission bits required")
@pytest.mark.skipif(
    hasattr(os, "geteuid") and os.geteuid() == 0, reason="root ignores mode bits"
)
@pytest.mark.parametrize("twin", _TWINS)
class TestUnreadableContractsDirectory:
    """An optional doc probe must never abort an otherwise valid resolution.

    Core treats an unreadable ``contracts/`` as simply unavailable; the bash
    and PowerShell twins suppress the error, and the Python twin has to catch
    ``OSError`` rather than let it escape.
    """

    def test_resolution_survives_an_unreadable_contracts_dir(
        self, tmp_path: Path, twin: str
    ):
        project = _make_feature_project(tmp_path)
        contracts = project / "specs" / "001-demo" / "contracts"
        contracts.mkdir()
        (contracts / "api.yaml").write_text("openapi: 3.0.0\n", encoding="utf-8")
        contracts.chmod(0o000)
        try:
            result = _run_twin(twin, project)
        finally:
            contracts.chmod(0o755)

        assert result.returncode == 0, result.stderr
        payload = json.loads(result.stdout)
        # Unreadable, so it is simply omitted; tasks.md still resolves.
        assert "contracts/" not in payload["AVAILABLE_DOCS"]
        assert payload["AVAILABLE_DOCS"] == ["research.md", "tasks.md"]