ouroboros-ai 0.26.2.dev36__tar.gz → 0.26.2.dev38__tar.gz

{ouroboros_ai-0.26.2.dev36 → ouroboros_ai-0.26.2.dev38}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ouroboros-ai
-Version: 0.26.2.dev36
+Version: 0.26.2.dev38
 Summary: Specification-first workflow engine for AI coding agents. Works with Claude Code and Codex CLI.
 Author-email: Q00 <jqyu.lee@gmail.com>
 License-File: LICENSE

{ouroboros_ai-0.26.2.dev36 → ouroboros_ai-0.26.2.dev38}/scripts/install.sh

@@ -140,11 +140,9 @@ if [ "$HAS_UV" = true ]; then
 elif [ "$HAS_PIPX" = true ]; then
   INSTALL_METHOD="pipx"
   if [ -n "$PRE_FLAG" ]; then
-    pipx install --pip-args='--pre' "$INSTALL_SPEC" 2>/dev/null \
-      || pipx upgrade --pip-args='--pre' "$INSTALL_SPEC"
+    pipx install --force --pip-args='--pre' "$INSTALL_SPEC"
   else
-    pipx install "$INSTALL_SPEC" 2>/dev/null \
-      || pipx upgrade "$INSTALL_SPEC"
+    pipx install --force "$INSTALL_SPEC"
   fi
 else
   INSTALL_METHOD="pip"
@@ -184,11 +182,11 @@ if command -v claude &>/dev/null; then
 
   # MCP command matches the installer that actually ran in step 3
   if [ "$INSTALL_METHOD" = "uv" ]; then
-    OUROBOROS_ENTRY='{"command":"uvx","args":["--from","ouroboros-ai[claude]","ouroboros","mcp","serve"],"timeout":600}'
+    OUROBOROS_ENTRY='{"command":"uvx","args":["--from","ouroboros-ai[claude]","ouroboros","mcp","serve"]}'
   elif [ "$INSTALL_METHOD" = "pipx" ]; then
-    OUROBOROS_ENTRY='{"command":"ouroboros","args":["mcp","serve"],"timeout":600}'
+    OUROBOROS_ENTRY='{"command":"ouroboros","args":["mcp","serve"]}'
   else
-    OUROBOROS_ENTRY='{"command":"python3","args":["-m","ouroboros","mcp","serve"],"timeout":600}'
+    OUROBOROS_ENTRY='{"command":"python3","args":["-m","ouroboros","mcp","serve"]}'
   fi
 
   # Find a working Python: system python3, or uv-managed python

{ouroboros_ai-0.26.2.dev36 → ouroboros_ai-0.26.2.dev38}/skills/pm/SKILL.md

@@ -15,7 +15,26 @@ PM-focused Socratic interview that produces a Product Requirements Document.
 ToolSearch query: "+ouroboros pm_interview"
 ```
 
-If not found → tell user to run `ooo setup` first. Stop.
+If not found → **diagnose before telling user to run setup**:
+
+1. Check if MCP is already configured:
+   ```bash
+   grep -q '"ouroboros"' ~/.claude/mcp.json 2>/dev/null && echo "CONFIGURED" || echo "NOT_CONFIGURED"
+   ```
+
+2. **If NOT_CONFIGURED** → tell user to run `ooo setup` first. Stop.
+
+3. **If CONFIGURED** → MCP is registered but the server isn't connecting. Do NOT tell the user to run `ooo setup` again. Instead show:
+   ```
+   Ouroboros MCP is configured but not connected.
+
+   Try these steps in order:
+   1. Restart Claude Code (Cmd+Shift+P → "Reload Window" or close/reopen terminal)
+   2. Check MCP status: type /mcp in Claude Code
+   3. If ouroboros shows "error", try: ooo update
+   4. If still failing, re-run: ooo setup
+   ```
+   Stop.
 
 ### Step 2: Start Interview
 

{ouroboros_ai-0.26.2.dev36 → ouroboros_ai-0.26.2.dev38}/skills/setup/SKILL.md

@@ -123,16 +123,44 @@ Runtime backend            [✓] Detected
 
 | Environment | Mode | Action |
 |:------------|:-----|:-------|
-| uvx + uv Python >= 3.12 | **Ready** | Proceed to MCP registration |
-| System Python >= 3.12 | **Ready** | Proceed to MCP registration |
+| uvx + Python >= 3.12 | **Ready** | Proceed to MCP registration (uvx mode — extras always included) |
+| No uvx + `ouroboros` binary in PATH | **Check deps** | Verify `[claude]` extras, then proceed (binary mode) |
+| No uvx + Python >= 3.12 + `python3 -m ouroboros` works | **Check deps** | Verify `[claude]` extras, then proceed (pip mode) |
 | uvx + Python < 3.12 only | **Install needed** | Run `uv python install 3.12` then proceed |
-| No uvx | **Install needed** | Run `curl -LsSf https://astral.sh/uv/install.sh \| sh` then `uv python install 3.12` |
+| No uvx + no ouroboros binary + no pip package | **Install needed** | Install uv first, then proceed |
 
-**IMPORTANT**: If Python >= 3.12 is not available, DO NOT skip to "Plugin-Only mode". Guide the user to install the prerequisites. MCP is required for the full Ouroboros experience.
+**For binary/pip modes — verify `[claude]` extras are installed:**
+
+Check method depends on how ouroboros was installed:
+```bash
+# Detect install method
+pipx list 2>/dev/null | grep -q ouroboros && echo "PIPX" || echo "NOT_PIPX"
+```
+
+- **pipx users** (binary mode, installed via pipx):
+  ```bash
+  pipx runpip ouroboros-ai show claude-agent-sdk 2>/dev/null && echo "DEPS_OK" || echo "DEPS_MISSING"
+  ```
+  If `DEPS_MISSING`: `pipx install --force ouroboros-ai[claude]`
+
+- **pip users** (pip mode):
+  ```bash
+  python3 -c "import claude_agent_sdk" 2>/dev/null && echo "DEPS_OK" || echo "DEPS_MISSING"
+  ```
+  If `DEPS_MISSING`: `python3 -m pip install ouroboros-ai[claude]`
+
+If deps are missing and the user doesn't want to fix manually, recommend uvx:
+```
+Or install uvx (recommended — handles deps automatically):
+  curl -LsSf https://astral.sh/uv/install.sh | sh
+Then re-run: ooo setup
+```
+
+**IMPORTANT**: The MCP server requires one of: (1) uvx, (2) ouroboros binary in PATH, or (3) ouroboros pip-installed. For options 2 and 3, the `[claude]` extra must also be installed. If none are available, guide the user to install uv — do NOT write a non-working fallback to mcp.json.
 
 **If prerequisites are missing, show:**
 ```
-Ouroboros requires Python >= 3.12 for the MCP server.
+Ouroboros requires uvx (recommended) or the ouroboros package installed.
 
 Quick install (< 1 minute):
   curl -LsSf https://astral.sh/uv/install.sh | sh
@@ -173,12 +201,13 @@ This enables:
 
 **Automatically create or update `~/.claude/mcp.json`** (user-level, works across all projects).
 
-Choose the MCP command based on how ouroboros is installed:
-- If `uvx` is available: `{"command": "uvx", "args": ["--from", "ouroboros-ai[claude]", "ouroboros", "mcp", "serve"], "timeout": 600}`
-- If `ouroboros` binary is in PATH (pipx install): `{"command": "ouroboros", "args": ["mcp", "serve"], "timeout": 600}`
-- Fallback (pip install): `{"command": "python3", "args": ["-m", "ouroboros", "mcp", "serve"], "timeout": 600}`
+Choose the MCP command based on how ouroboros is installed (check in order):
+1. If `which uvx` succeeds: `{"command": "uvx", "args": ["--from", "ouroboros-ai[claude]", "ouroboros", "mcp", "serve"]}`
+2. If `which ouroboros` succeeds: `{"command": "ouroboros", "args": ["mcp", "serve"]}`
+3. If `python3 -c "import ouroboros"` succeeds: `{"command": "python3", "args": ["-m", "ouroboros", "mcp", "serve"]}`
+4. If none of the above → **do NOT write to mcp.json**. Instead show the prerequisites message from Step 1 and stop.
 
-If `~/.claude/mcp.json` already exists, merge intelligently (preserve other servers).
+If `~/.claude/mcp.json` already exists, read it, **always overwrite the `ouroboros` key** with the entry above (to fix stale args from older versions), and preserve all other server entries.
 
 **Celebration Checkpoint 2:**
 ```

{ouroboros_ai-0.26.2.dev36 → ouroboros_ai-0.26.2.dev38}/skills/update/SKILL.md

@@ -80,38 +80,46 @@ When the user invokes this skill:
 
 4. **Run update** (if user chose to update):
 
-   a. **Update PyPI package** — detect the original install method and use the same one:
+   a. **Update PyPI package** — detect the original install method and preserve `[claude]` extras:
 
-   Check which installer was used (in priority order):
+   Check which installer was used:
    ```bash
    uv tool list 2>/dev/null | grep -q ouroboros && echo "uv"
    pipx list 2>/dev/null | grep -q ouroboros && echo "pipx"
    ```
 
+   > This skill runs inside Claude Code, so always use `ouroboros-ai[claude]`
+   > (includes `claude-agent-sdk` and `anthropic` required for MCP tools).
+
    - If installed via **uv tool** (most common with install.sh):
      ```bash
      # For pre-release targets:
-     uv tool install --upgrade --prerelease=allow ouroboros-ai
+     uv tool install --upgrade --prerelease=allow ouroboros-ai[claude]
      # For stable targets:
-     uv tool install --upgrade ouroboros-ai
+     uv tool install --upgrade ouroboros-ai[claude]
      ```
 
    - If installed via **pipx**:
+     > `pipx upgrade` cannot add extras to an existing venv — use `install --force` to reinstall with extras.
      ```bash
      # For pre-release targets:
-     pipx upgrade --pip-args='--pre' ouroboros-ai
+     pipx install --force --pip-args='--pre' ouroboros-ai[claude]
      # For stable targets:
-     pipx upgrade ouroboros-ai
+     pipx install --force ouroboros-ai[claude]
      ```
 
    - If installed via **pip** (fallback):
      ```bash
      # For pre-release targets:
-     python3 -m pip install --upgrade --pre ouroboros-ai
+     python3 -m pip install --upgrade --pre ouroboros-ai[claude]
      # For stable targets:
-     python3 -m pip install --upgrade ouroboros-ai
+     python3 -m pip install --upgrade ouroboros-ai[claude]
      ```
 
+   > **Note**: The `[claude]` extra is critical — it installs `claude-agent-sdk` and
+   > `anthropic` which are required for MCP tool execution. Omitting it causes MCP
+   > tools to fail silently at call time.
+
    b. **Update runtime integration**:
 
    For Claude Code:
@@ -125,7 +133,21 @@ When the user invokes this skill:
    ouroboros setup --runtime codex --non-interactive
    ```
 
-   c. **Verify and update CLAUDE.md version marker**:
+   c. **Refresh MCP server config** (fixes stale args from older versions):
+
+   Run the same setup command used in step b to ensure MCP config is current:
+
+   For Claude Code:
+   ```bash
+   ouroboros setup --runtime claude --non-interactive
+   ```
+
+   For Codex CLI (already handled by step b above — skip this step).
+
+   This ensures `~/.claude/mcp.json` has the latest MCP command and args
+   (e.g., `ouroboros-ai[claude]` extras). Skips if already up to date.
+
+   d. **Verify and update CLAUDE.md version marker**:
    ```bash
    NEW_VERSION=$(ouroboros --version 2>/dev/null | grep -oE '[0-9]+\.[0-9]+\.[0-9]+[a-z0-9.]*')
    echo "Installed: v$NEW_VERSION"

{ouroboros_ai-0.26.2.dev36 → ouroboros_ai-0.26.2.dev38}/src/ouroboros/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.26.2.dev36'
-__version_tuple__ = version_tuple = (0, 26, 2, 'dev36')
+__version__ = version = '0.26.2.dev38'
+__version_tuple__ = version_tuple = (0, 26, 2, 'dev38')
 
 __commit_id__ = commit_id = None

{ouroboros_ai-0.26.2.dev36 → ouroboros_ai-0.26.2.dev38}/src/ouroboros/cli/commands/run.py

@@ -20,6 +20,7 @@ if TYPE_CHECKING:
 
 from ouroboros.cli.formatters import console
 from ouroboros.cli.formatters.panels import print_error, print_info, print_success, print_warning
+from ouroboros.core.project_paths import resolve_seed_project_path
 from ouroboros.core.security import InputValidator
 from ouroboros.core.worktree import (
     TaskWorkspace,
@@ -27,6 +28,7 @@ from ouroboros.core.worktree import (
     maybe_prepare_task_workspace,
     maybe_restore_task_workspace,
 )
+from ouroboros.evaluation.verification_artifacts import build_verification_artifacts
 
 
 class _DefaultWorkflowGroup(typer.core.TyperGroup):
@@ -101,6 +103,12 @@ def _load_seed_from_yaml(seed_file: Path) -> dict[str, Any]:
         raise typer.Exit(1) from e
 
 
+def _resolve_cli_project_dir(seed: "Seed", seed_file: Path) -> Path:
+    """Resolve the project directory for CLI execution and verification."""
+    stable_base = seed_file.parent.resolve()
+    return resolve_seed_project_path(seed, stable_base=stable_base) or stable_base
+
+
 async def _initialize_mcp_manager(
     config_path: Path,
     tool_prefix: str,  # noqa: ARG001
@@ -218,6 +226,7 @@ async def _run_orchestrator(
     event_store = EventStore(f"sqlite+aiosqlite:///{db_path}")
     await event_store.initialize()
 
+    project_dir = _resolve_cli_project_dir(seed, seed_file)
     session_repo = SessionRepository(event_store)
     workspace: TaskWorkspace | None = None
     execution_id: str | None = None
@@ -235,14 +244,14 @@ async def _run_orchestrator(
             workspace = maybe_restore_task_workspace(
                 resume_session,
                 persisted,
-                fallback_source_cwd=Path.cwd(),
+                fallback_source_cwd=project_dir,
             )
             session_id_for_run = resume_session
             execution_id = reconstructed.value.execution_id
         else:
             session_id_for_run = f"orch_{uuid4().hex[:12]}"
             execution_id = f"exec_{uuid4().hex[:12]}"
-            workspace = maybe_prepare_task_workspace(Path.cwd(), session_id_for_run)
+            workspace = maybe_prepare_task_workspace(project_dir, session_id_for_run)
     except WorktreeError as e:
         print_error(f"Task workspace error: {e.message}")
         raise typer.Exit(1) from e
@@ -253,7 +262,7 @@ async def _run_orchestrator(
 
     adapter = create_agent_runtime(
         backend=runtime_backend,
-        cwd=Path(workspace.effective_cwd) if workspace else Path.cwd(),
+        cwd=Path(workspace.effective_cwd) if workspace else project_dir,
     )
     runner = OrchestratorRunner(
         adapter,
@@ -301,12 +310,28 @@ async def _run_orchestrator(
                     print_info("Running post-execution QA...")
                     qa_handler = QAHandler()
                     quality_bar = _derive_quality_bar(seed)
+                    execution_artifact = _get_verification_artifact(res.summary, res.final_message)
+                    verification_working_dir = (
+                        Path(workspace.effective_cwd) if workspace is not None else project_dir
+                    )
+                    try:
+                        verification = await build_verification_artifacts(
+                            res.execution_id,
+                            execution_artifact,
+                            verification_working_dir,
+                        )
+                        artifact = verification.artifact
+                        reference = verification.reference
+                    except Exception as e:
+                        artifact = execution_artifact
+                        reference = f"Verification artifact generation failed: {e}"
 
                     qa_result = await qa_handler.handle(
                         {
-                            "artifact": _get_verification_artifact(res.summary, res.final_message),
+                            "artifact": artifact,
                             "artifact_type": "test_output",
                             "quality_bar": quality_bar,
+                            "reference": reference,
                             "seed_content": yaml.dump(seed_data, default_flow_style=False),
                             "pass_threshold": 0.80,
                         }

{ouroboros_ai-0.26.2.dev36 → ouroboros_ai-0.26.2.dev38}/src/ouroboros/cli/commands/setup.py

@@ -32,6 +32,101 @@ from ouroboros.cli.formatters.panels import (
 )
 from ouroboros.persistence.brownfield import BrownfieldStore
 
+# Canonical MCP args for Claude Code uvx installs — single source of truth.
+_CLAUDE_UVX_ARGS: list[str] = [
+    "--from",
+    "ouroboros-ai[claude]",
+    "ouroboros",
+    "mcp",
+    "serve",
+]
+
+
+def _detect_mcp_entry() -> dict[str, object] | None:
+    """Build the correct MCP entry based on how ouroboros is installed.
+
+    Priority: uvx > ouroboros binary > python3 -m ouroboros (verified).
+    Returns None if no working method is found.
+    Matches the contract in install.sh and skills/setup/SKILL.md.
+    """
+    if shutil.which("uvx"):
+        return {"command": "uvx", "args": list(_CLAUDE_UVX_ARGS)}
+    if shutil.which("ouroboros"):
+        return {"command": "ouroboros", "args": ["mcp", "serve"]}
+    # Only use python3 fallback if ouroboros is actually importable
+    import subprocess
+
+    try:
+        subprocess.run(
+            ["python3", "-c", "import ouroboros"],
+            capture_output=True,
+            timeout=10,
+            check=True,
+        )
+    except (subprocess.CalledProcessError, FileNotFoundError, subprocess.TimeoutExpired):
+        return None
+    return {"command": "python3", "args": ["-m", "ouroboros", "mcp", "serve"]}
+
+
+def _ensure_claude_mcp_entry() -> None:
+    """Ensure ~/.claude/mcp.json has a correct ouroboros MCP entry.
+
+    Creates the entry if missing (detecting install method), updates stale
+    uvx args (e.g. ouroboros-ai without [claude] extras), and removes the
+    legacy timeout key.  Skips the file write when nothing changed.
+    """
+    mcp_config_path = Path.home() / ".claude" / "mcp.json"
+    mcp_config_path.parent.mkdir(parents=True, exist_ok=True)
+
+    mcp_data: dict = {}
+    if mcp_config_path.exists():
+        mcp_data = json.loads(mcp_config_path.read_text())
+
+    mcp_data.setdefault("mcpServers", {})
+
+    existing = mcp_data["mcpServers"].get("ouroboros")
+    detected = _detect_mcp_entry()
+    needs_write = False
+
+    if existing is None:
+        if detected is None:
+            print_warning(
+                "Cannot register MCP server: no working ouroboros installation found.\n"
+                "Install with: curl -LsSf https://astral.sh/uv/install.sh | sh"
+            )
+            return
+        mcp_data["mcpServers"]["ouroboros"] = detected
+        needs_write = True
+        print_success("Registered MCP server in ~/.claude/mcp.json")
+    else:
+        # Remove legacy timeout key
+        if "timeout" in existing:
+            del existing["timeout"]
+            needs_write = True
+            print_info("Removed legacy MCP timeout override.")
+
+        # Update entry to match currently detected install method, but only
+        # for known standard commands. Custom entries (docker, nix, etc.) are
+        # left untouched so we don't break user-managed configurations.
+        _KNOWN_COMMANDS = {"uvx", "ouroboros", "python3", "python"}
+        if detected is not None and existing.get("command") in _KNOWN_COMMANDS:
+            if (
+                existing.get("command") != detected["command"]
+                or existing.get("args") != detected["args"]
+            ):
+                existing["command"] = detected["command"]
+                existing["args"] = detected["args"]
+                needs_write = True
+                print_info("Updated MCP server entry to match current install method.")
+
+        if not needs_write:
+            print_info("MCP server already registered.")
+
+    if needs_write:
+        with mcp_config_path.open("w") as f:
+            json.dump(mcp_data, f, indent=2)
+
+
 app = typer.Typer(
     name="setup",
     help="Set up Ouroboros for your environment.",
@@ -227,32 +322,9 @@ def _setup_codex(codex_path: str) -> None:
     _register_codex_mcp_server()
     _print_codex_config_guidance(config_path)
 
-    # Also register MCP server for Codex users who also have Claude Code
-    mcp_config_path = Path.home() / ".claude" / "mcp.json"
-    if mcp_config_path.exists() or (Path.home() / ".claude").is_dir():
-        mcp_config_path.parent.mkdir(parents=True, exist_ok=True)
-
-        mcp_data: dict = {}
-        if mcp_config_path.exists():
-            mcp_data = json.loads(mcp_config_path.read_text())
-
-        mcp_data.setdefault("mcpServers", {})
-        entry = mcp_data["mcpServers"].get("ouroboros", {})
-        if not entry:
-            entry = {
-                "command": "uvx",
-                "args": ["--from", "ouroboros-ai", "ouroboros", "mcp", "serve"],
-            }
-        removed_timeout = entry.pop("timeout", None) is not None
-        mcp_data["mcpServers"]["ouroboros"] = entry
-
-        with mcp_config_path.open("w") as f:
-            json.dump(mcp_data, f, indent=2)
-
-        if removed_timeout:
-            print_info("Removed legacy Claude MCP timeout override.")
-        else:
-            print_info("Updated Claude MCP server config.")
+    # Also register/fix MCP server for Codex users who also have Claude Code
+    if (Path.home() / ".claude").is_dir():
+        _ensure_claude_mcp_entry()
 
 
 def _setup_claude(claude_path: str) -> None:
@@ -279,32 +351,8 @@ def _setup_claude(claude_path: str) -> None:
     with config_path.open("w") as f:
         yaml.dump(config_dict, f, default_flow_style=False, sort_keys=False)
 
-    # Register MCP server in ~/.claude/mcp.json
-    mcp_config_path = Path.home() / ".claude" / "mcp.json"
-    mcp_config_path.parent.mkdir(parents=True, exist_ok=True)
-
-    mcp_data: dict = {}
-    if mcp_config_path.exists():
-        mcp_data = json.loads(mcp_config_path.read_text())
-
-    mcp_data.setdefault("mcpServers", {})
-    if "ouroboros" not in mcp_data["mcpServers"]:
-        mcp_data["mcpServers"]["ouroboros"] = {
-            "command": "uvx",
-            "args": ["--from", "ouroboros-ai", "ouroboros", "mcp", "serve"],
-        }
-        with mcp_config_path.open("w") as f:
-            json.dump(mcp_data, f, indent=2)
-        print_success("Registered MCP server in ~/.claude/mcp.json")
-    else:
-        entry = mcp_data["mcpServers"]["ouroboros"]
-        if "timeout" in entry:
-            del entry["timeout"]
-            with mcp_config_path.open("w") as f:
-                json.dump(mcp_data, f, indent=2)
-            print_info("Removed legacy MCP timeout override.")
-        else:
-            print_info("MCP server already registered.")
+    # Register/fix MCP server in ~/.claude/mcp.json
+    _ensure_claude_mcp_entry()
 
     print_success(f"Configured Claude Code runtime (CLI: {claude_path})")
     print_info(f"Config saved to: {config_path}")

ouroboros_ai-0.26.2.dev38/src/ouroboros/core/project_paths.py

@@ -0,0 +1,59 @@
+"""Helpers for resolving project directories from seed and runtime context."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+
+def resolve_path_against_base(raw_path: str | Path | None, *, stable_base: Path) -> Path | None:
+    """Resolve a path against a stable base directory."""
+    if raw_path is None:
+        return None
+
+    candidate = Path(raw_path).expanduser()
+    if candidate.is_absolute():
+        return candidate.resolve()
+    return (stable_base / candidate).resolve()
+
+
+def project_path_candidates_from_seed(seed: Any) -> tuple[str, ...]:
+    """Extract likely project directories from seed metadata and brownfield refs."""
+    if seed is None:
+        return ()
+
+    candidates: list[str] = []
+    seed_meta = getattr(seed, "metadata", None)
+    if seed_meta is not None:
+        project_dir = getattr(seed_meta, "project_dir", None) or getattr(
+            seed_meta,
+            "working_directory",
+            None,
+        )
+        if isinstance(project_dir, str) and project_dir:
+            candidates.append(project_dir)
+
+    brownfield_context = getattr(seed, "brownfield_context", None)
+    context_references = getattr(brownfield_context, "context_references", ()) or ()
+
+    for reference in context_references:
+        path = getattr(reference, "path", None)
+        role = getattr(reference, "role", None)
+        if isinstance(path, str) and path and role == "primary":
+            candidates.append(path)
+
+    for reference in context_references:
+        path = getattr(reference, "path", None)
+        if isinstance(path, str) and path and path not in candidates:
+            candidates.append(path)
+
+    return tuple(candidates)
+
+
+def resolve_seed_project_path(seed: Any, *, stable_base: Path) -> Path | None:
+    """Resolve the highest-priority project path encoded in a seed."""
+    for candidate in project_path_candidates_from_seed(seed):
+        resolved = resolve_path_against_base(candidate, stable_base=stable_base)
+        if resolved is not None:
+            return resolved
+    return None