spec-kitty-cli 3.1.2a2__tar.gz → 3.1.2a3__tar.gz

{spec_kitty_cli-3.1.2a2 → spec_kitty_cli-3.1.2a3}/CHANGELOG.md

@@ -9,6 +9,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.1.2a3] - 2026-04-12
+
+### Fixed
+
+- **Merge-time numbering lock and retry safety** — `mission_number` assignment now acquires a file lock before scanning existing prefixes, MergeState uses `mission_id` as its canonical key, and interrupted merges no longer risk duplicate or skipped numbers on retry. Closes #601.
+- **CLI no longer hangs 15–20 min when offline queue is full and session expired** — the offline queue drain path now respects a bounded timeout instead of blocking indefinitely on expired-session retries. Closes #598, #602.
+- **Sonar readiness and parser findings addressed** — actionable maintenance issues flagged by SonarCloud (code smells, complexity, minor bugs) are resolved. Closes #599, #600.
+
 ## [3.1.2a2] - 2026-04-11
 
 ### Added

{spec_kitty_cli-3.1.2a2 → spec_kitty_cli-3.1.2a3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: spec-kitty-cli
-Version: 3.1.2a2
+Version: 3.1.2a3
 Summary: Spec Kitty, a tool for Specification Driven Development (SDD) agentic projects, with kanban and git worktree isolation.
 Project-URL: Repository, https://github.com/Priivacy-ai/spec-kitty
 Project-URL: Issues, https://github.com/Priivacy-ai/spec-kitty/issues
@@ -500,10 +500,12 @@ register, login, logout, and recover forgotten passwords.
 ```
 
 **What this does:**
-- Creates `kitty-specs/001-auth-system/spec.md` with user stories
+- Creates `kitty-specs/auth-system/spec.md` with user stories and mints a canonical `mission_id` (ULID) in `meta.json`
 - **Enters discovery interview** - Answer questions before continuing!
 - All planning happens in the main repo (worktrees created later during implementation)
 
+> **Note:** Mission identity is a ULID (`mission_id` in `meta.json`). The three-digit numeric prefix (e.g. `001-auth-system`) is display-only and is only assigned at merge time. Branches and worktrees use the mission's `mid8` (first 8 chars of the ULID) for collision-free naming. See the [mission identity migration runbook](docs/migration/mission-id-canonical-identity.md).
+
 **⚠️ Important:** Continue in the same session - no need to change directories!
 
 #### 4b. Define HOW to Build (In Main Repo)
@@ -610,11 +612,13 @@ spec-kitty next --agent <agent> --mission <slug>
 ## 📋 Quick Reference: Command Order
 
 ### Required Workflow (Once per project)
+
 ```
 1️⃣  /spec-kitty.charter     → In main repo (sets project principles)
 ```
 
 ### Required Workflow (Each feature)
+
 ```
 2️⃣  /spec-kitty.specify          → Create spec (in main repo)
 3️⃣  /spec-kitty.plan             → Define technical approach (in main repo)
@@ -627,6 +631,7 @@ spec-kitty next --agent <agent> --mission <slug>
 ```
 
 ### Optional Enhancement Commands
+
 ```
 /spec-kitty.research   → After /plan: Investigate technical decisions
 /spec-kitty.analyze    → After /tasks: Cross-artifact consistency check
@@ -658,7 +663,7 @@ Spec Kitty automatically protects you with multiple layers:
 **Worktree Charter Sharing:**
 When creating execution workspaces, Spec Kitty uses symlinks to share the charter:
 ```
-.worktrees/001-feature-lane-a/.kittify/memory -> ../../../../.kittify/memory
+.worktrees/my-feature-01J6XW9K-lane-a/.kittify/memory -> ../../../../.kittify/memory
 ```
 This ensures all work packages follow the same project principles.
 
@@ -686,6 +691,7 @@ Spec Kitty differentiates between the **project** that holds your entire codebas
 For glossary-first terminology (including semantic-integrity rules), see [`glossary/README.md`](glossary/README.md).
 
 ### Project
+
 **Definition**: The entire codebase (one Git repository) that contains all missions, features, and `.kittify/` automation.
 
 **Examples**:
@@ -703,18 +709,21 @@ For glossary-first terminology (including semantic-integrity rules), see [`gloss
 ---
 
 ### Feature
+
 **Definition**: A single unit of work tracked by Spec Kitty. Every feature has its own spec, plan, tasks, and one or more execution worktrees.
 
+> **Mission identity (as of mission 083):** A mission's canonical machine identity is `mission_id` — a ULID minted at creation and immutable for the lifetime of the mission. The three-digit `mission_number` prefix shown in directory names is **display-only metadata** and is assigned at merge time. Selectors use `mission_id`, `mid8` (first 8 chars of the ULID), or `mission_slug`; ambiguous handles return a structured error. See the [mission identity migration runbook](docs/migration/mission-id-canonical-identity.md).
+
 **Examples**:
 - "001-auth-system feature"
 - "005-refactor-mission-system feature" (this document)
 - "042-dashboard-refresh feature"
 
 **Structure**:
-- Specification: `/kitty-specs/###-feature-name/spec.md`
-- Plan: `/kitty-specs/###-feature-name/plan.md`
-- Tasks: `/kitty-specs/###-feature-name/tasks.md`
-- Implementation: `.worktrees/###-feature-name-lane-a/`, `.worktrees/###-feature-name-lane-b/`, and so on
+- Specification: `/kitty-specs/<human-slug>/spec.md` (directory listing shows `NNN-<human-slug>` once `mission_number` is assigned at merge)
+- Plan: `/kitty-specs/<human-slug>/plan.md`
+- Tasks: `/kitty-specs/<human-slug>/tasks.md`
+- Implementation: `.worktrees/<human-slug>-<mid8>-lane-a/`, `.worktrees/<human-slug>-<mid8>-lane-b/`, and so on (e.g. `.worktrees/my-feature-01J6XW9K-lane-a/`)
 
 **Lifecycle**:
 1. `/spec-kitty.specify` – Create the feature and its branch
@@ -732,6 +741,7 @@ For glossary-first terminology (including semantic-integrity rules), see [`gloss
 ---
 
 ### Mission
+
 **Definition**: A domain adapter that configures Spec Kitty (workflows, templates, validation). Missions are project-wide; all features in a project share the same active mission.
 
 **Examples**:
@@ -1167,6 +1177,7 @@ graph TD
 - Main branch stays clean without manual `git checkout` juggling
 
 ### The Pattern
+
 ```
 my-project/                    # Main repo (main branch)
 ├── .worktrees/
@@ -1179,6 +1190,7 @@ my-project/                    # Main repo (main branch)
 ```
 
 ### The Rules
+
 1. **Planning commands** run in the primary repo root
 2. **Implementation branches** live under `.worktrees/`
 3. **Trust the path printed by Spec Kitty** instead of guessing the worktree name
@@ -1264,7 +1276,6 @@ cat .kittify/metadata.yaml
 | `SPECIFY_TEMPLATE_REPO` | Optional. Override the GitHub repository slug (`owner/name`) to fetch templates from when you explicitly want a remote source. |
 | `CODEX_HOME` | Required when using the Codex CLI so it loads project-specific prompts. Point it to your project’s `.codex/` directory—set it manually with `export CODEX_HOME=\"$(pwd)/.codex\"` or automate it via [`direnv`](https://github.com/Priivacy-ai/spec-kitty/blob/main/docs/index.md#codex-cli-automatically-load-project-prompts-linux-macos-wsl) on Linux/macOS/WSL. |
 
-
 ## 🔧 Prerequisites
 
 - **Linux/macOS** (or WSL2 on Windows)

{spec_kitty_cli-3.1.2a2 → spec_kitty_cli-3.1.2a3}/README.md

@@ -402,10 +402,12 @@ register, login, logout, and recover forgotten passwords.
 ```
 
 **What this does:**
-- Creates `kitty-specs/001-auth-system/spec.md` with user stories
+- Creates `kitty-specs/auth-system/spec.md` with user stories and mints a canonical `mission_id` (ULID) in `meta.json`
 - **Enters discovery interview** - Answer questions before continuing!
 - All planning happens in the main repo (worktrees created later during implementation)
 
+> **Note:** Mission identity is a ULID (`mission_id` in `meta.json`). The three-digit numeric prefix (e.g. `001-auth-system`) is display-only and is only assigned at merge time. Branches and worktrees use the mission's `mid8` (first 8 chars of the ULID) for collision-free naming. See the [mission identity migration runbook](docs/migration/mission-id-canonical-identity.md).
+
 **⚠️ Important:** Continue in the same session - no need to change directories!
 
 #### 4b. Define HOW to Build (In Main Repo)
@@ -512,11 +514,13 @@ spec-kitty next --agent <agent> --mission <slug>
 ## 📋 Quick Reference: Command Order
 
 ### Required Workflow (Once per project)
+
 ```
 1️⃣  /spec-kitty.charter     → In main repo (sets project principles)
 ```
 
 ### Required Workflow (Each feature)
+
 ```
 2️⃣  /spec-kitty.specify          → Create spec (in main repo)
 3️⃣  /spec-kitty.plan             → Define technical approach (in main repo)
@@ -529,6 +533,7 @@ spec-kitty next --agent <agent> --mission <slug>
 ```
 
 ### Optional Enhancement Commands
+
 ```
 /spec-kitty.research   → After /plan: Investigate technical decisions
 /spec-kitty.analyze    → After /tasks: Cross-artifact consistency check
@@ -560,7 +565,7 @@ Spec Kitty automatically protects you with multiple layers:
 **Worktree Charter Sharing:**
 When creating execution workspaces, Spec Kitty uses symlinks to share the charter:
 ```
-.worktrees/001-feature-lane-a/.kittify/memory -> ../../../../.kittify/memory
+.worktrees/my-feature-01J6XW9K-lane-a/.kittify/memory -> ../../../../.kittify/memory
 ```
 This ensures all work packages follow the same project principles.
 
@@ -588,6 +593,7 @@ Spec Kitty differentiates between the **project** that holds your entire codebas
 For glossary-first terminology (including semantic-integrity rules), see [`glossary/README.md`](glossary/README.md).
 
 ### Project
+
 **Definition**: The entire codebase (one Git repository) that contains all missions, features, and `.kittify/` automation.
 
 **Examples**:
@@ -605,18 +611,21 @@ For glossary-first terminology (including semantic-integrity rules), see [`gloss
 ---
 
 ### Feature
+
 **Definition**: A single unit of work tracked by Spec Kitty. Every feature has its own spec, plan, tasks, and one or more execution worktrees.
 
+> **Mission identity (as of mission 083):** A mission's canonical machine identity is `mission_id` — a ULID minted at creation and immutable for the lifetime of the mission. The three-digit `mission_number` prefix shown in directory names is **display-only metadata** and is assigned at merge time. Selectors use `mission_id`, `mid8` (first 8 chars of the ULID), or `mission_slug`; ambiguous handles return a structured error. See the [mission identity migration runbook](docs/migration/mission-id-canonical-identity.md).
+
 **Examples**:
 - "001-auth-system feature"
 - "005-refactor-mission-system feature" (this document)
 - "042-dashboard-refresh feature"
 
 **Structure**:
-- Specification: `/kitty-specs/###-feature-name/spec.md`
-- Plan: `/kitty-specs/###-feature-name/plan.md`
-- Tasks: `/kitty-specs/###-feature-name/tasks.md`
-- Implementation: `.worktrees/###-feature-name-lane-a/`, `.worktrees/###-feature-name-lane-b/`, and so on
+- Specification: `/kitty-specs/<human-slug>/spec.md` (directory listing shows `NNN-<human-slug>` once `mission_number` is assigned at merge)
+- Plan: `/kitty-specs/<human-slug>/plan.md`
+- Tasks: `/kitty-specs/<human-slug>/tasks.md`
+- Implementation: `.worktrees/<human-slug>-<mid8>-lane-a/`, `.worktrees/<human-slug>-<mid8>-lane-b/`, and so on (e.g. `.worktrees/my-feature-01J6XW9K-lane-a/`)
 
 **Lifecycle**:
 1. `/spec-kitty.specify` – Create the feature and its branch
@@ -634,6 +643,7 @@ For glossary-first terminology (including semantic-integrity rules), see [`gloss
 ---
 
 ### Mission
+
 **Definition**: A domain adapter that configures Spec Kitty (workflows, templates, validation). Missions are project-wide; all features in a project share the same active mission.
 
 **Examples**:
@@ -1069,6 +1079,7 @@ graph TD
 - Main branch stays clean without manual `git checkout` juggling
 
 ### The Pattern
+
 ```
 my-project/                    # Main repo (main branch)
 ├── .worktrees/
@@ -1081,6 +1092,7 @@ my-project/                    # Main repo (main branch)
 ```
 
 ### The Rules
+
 1. **Planning commands** run in the primary repo root
 2. **Implementation branches** live under `.worktrees/`
 3. **Trust the path printed by Spec Kitty** instead of guessing the worktree name
@@ -1166,7 +1178,6 @@ cat .kittify/metadata.yaml
 | `SPECIFY_TEMPLATE_REPO` | Optional. Override the GitHub repository slug (`owner/name`) to fetch templates from when you explicitly want a remote source. |
 | `CODEX_HOME` | Required when using the Codex CLI so it loads project-specific prompts. Point it to your project’s `.codex/` directory—set it manually with `export CODEX_HOME=\"$(pwd)/.codex\"` or automate it via [`direnv`](https://github.com/Priivacy-ai/spec-kitty/blob/main/docs/index.md#codex-cli-automatically-load-project-prompts-linux-macos-wsl) on Linux/macOS/WSL. |
 
-
 ## 🔧 Prerequisites
 
 - **Linux/macOS** (or WSL2 on Windows)

{spec_kitty_cli-3.1.2a2 → spec_kitty_cli-3.1.2a3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "spec-kitty-cli"
-version = "3.1.2a2"
+version = "3.1.2a3"
 description = "Spec Kitty, a tool for Specification Driven Development (SDD) agentic projects, with kanban and git worktree isolation."
 readme = "README.md"
 license = { file = "LICENSE" }
@@ -201,6 +201,9 @@ max-complexity = 15  # Match SonarCloud S3776 threshold
 [tool.mypy]
 # Keep strict mode as the default quality bar for actively maintained code.
 strict = true
+# Point mypy at the source tree so it resolves specify_cli from src/ rather than
+# an installed wheel that may lack a py.typed marker.
+mypy_path = "src"
 
 [[tool.mypy.overrides]]
 # When checking a narrow file path under ``specify_cli``, mypy otherwise walks

{spec_kitty_cli-3.1.2a2 → spec_kitty_cli-3.1.2a3}/src/specify_cli/auth/device_flow/poller.py

@@ -18,7 +18,7 @@ from __future__ import annotations
 
 import asyncio
 import logging
-from typing import Any
+from typing import Any, NoReturn
 from collections.abc import Awaitable, Callable
 
 from ..errors import DeviceFlowDenied, DeviceFlowExpired, NetworkError
@@ -86,6 +86,55 @@ class DeviceFlowPoller:
         """Return the wrapped :class:`DeviceFlowState`."""
         return self._state
 
+    def _raise_if_expired(self) -> None:
+        """Stop polling once the local device-flow state has expired."""
+        if self._state.is_expired():
+            raise DeviceFlowExpired(
+                f"Device authorization expired after {self._state.expires_in} seconds. "
+                "Run `spec-kitty auth login --headless` again."
+            )
+
+    @staticmethod
+    def _raise_terminal_error(error: str, response: dict[str, Any]) -> NoReturn:
+        """Raise the terminal exception for a non-retriable OAuth error."""
+        if error == "access_denied":
+            raise DeviceFlowDenied(
+                "User denied the authorization request. "
+                "Run `spec-kitty auth login --headless` to try again."
+            )
+
+        if error == "expired_token":
+            raise DeviceFlowExpired(
+                "Device code expired before approval. "
+                "Run `spec-kitty auth login --headless` to try again."
+            )
+
+        desc = response.get("error_description", error)
+        raise DeviceFlowDenied(f"Unexpected device flow error: {desc}")
+
+    def _handle_response(
+        self,
+        response: dict[str, Any],
+        *,
+        interval: int,
+        on_pending: Callable[[DeviceFlowState], None] | None,
+    ) -> tuple[dict[str, Any] | None, int]:
+        """Classify a token response and return the next loop state."""
+        error = response.get("error")
+        if error is None:
+            return response, interval
+
+        if error == "authorization_pending":
+            if on_pending is not None:
+                on_pending(self._state)
+            return None, interval
+
+        if error == "slow_down":
+            next_interval = min(interval + _SLOW_DOWN_BACKOFF, _MAX_INTERVAL_SECONDS)
+            return None, next_interval
+
+        self._raise_terminal_error(error, response)
+
     async def poll(
         self,
         token_request: Callable[[str], Awaitable[dict[str, Any]]],
@@ -131,11 +180,7 @@ class DeviceFlowPoller:
         interval = min(self._state.interval, _MAX_INTERVAL_SECONDS)
 
         while True:
-            if self._state.is_expired():
-                raise DeviceFlowExpired(
-                    f"Device authorization expired after {self._state.expires_in} seconds. "
-                    "Run `spec-kitty auth login --headless` again."
-                )
+            self._raise_if_expired()
 
             # Sleep BEFORE the first poll too -- gives the user time to open
             # the browser and approve. This is intentional UX, not a bug.
@@ -150,33 +195,10 @@ class DeviceFlowPoller:
                 log.warning("Network error during device flow poll: %s", exc)
                 continue
 
-            error = response.get("error")
-            if error is None:
-                # Success: response contains access_token, refresh_token, etc.
-                return response
-
-            if error == "authorization_pending":
-                if on_pending is not None:
-                    on_pending(self._state)
-                continue
-
-            if error == "slow_down":
-                # RFC 8628 §3.5: bump interval, but still cap at 10s (FR-018).
-                interval = min(interval + _SLOW_DOWN_BACKOFF, _MAX_INTERVAL_SECONDS)
-                continue
-
-            if error == "access_denied":
-                raise DeviceFlowDenied(
-                    "User denied the authorization request. "
-                    "Run `spec-kitty auth login --headless` to try again."
-                )
-
-            if error == "expired_token":
-                raise DeviceFlowExpired(
-                    "Device code expired before approval. "
-                    "Run `spec-kitty auth login --headless` to try again."
-                )
-
-            # Unknown error -- propagate with whatever description SaaS gave us.
-            desc = response.get("error_description", error)
-            raise DeviceFlowDenied(f"Unexpected device flow error: {desc}")
+            handled_response, interval = self._handle_response(
+                response,
+                interval=interval,
+                on_pending=on_pending,
+            )
+            if handled_response is not None:
+                return handled_response

{spec_kitty_cli-3.1.2a2 → spec_kitty_cli-3.1.2a3}/src/specify_cli/cli/commands/__init__.py

@@ -59,7 +59,7 @@ def register_commands(app: typer.Typer) -> None:
     app.command(name="materialize")(materialize_module.materialize)
     app.command()(merge_module.merge)
     app.command(name="merge-driver-event-log", hidden=True)(merge_driver_module.merge_driver_event_log)
-    app.command()(migrate_module.migrate)
+    app.add_typer(migrate_module.app, name="migrate")
     app.add_typer(mission_module.app, name="mission")
     app.command(name="next")(next_cmd_module.next_step)
     app.add_typer(mission_type_module.app, name="mission-type")

{spec_kitty_cli-3.1.2a2 → spec_kitty_cli-3.1.2a3}/src/specify_cli/cli/commands/accept.py

@@ -17,7 +17,7 @@ from specify_cli.acceptance import (
     perform_acceptance,
 )
 from specify_cli.cli import StepTracker
-from specify_cli.cli.selector_resolution import resolve_selector
+from specify_cli.cli.selector_resolution import resolve_mission_handle
 from specify_cli.cli.helpers import check_version_compatibility, console, show_banner
 from specify_cli.tasks_support import LANES, TaskCliError, find_repo_root
 from specify_cli.sync.events import emit_wp_status_changed
@@ -158,24 +158,24 @@ def accept(
         tracker.add("verify", "Run readiness checks")
         console.print()
         tracker.start("detect")
-    try:
-        mission_slug = resolve_selector(
-            canonical_value=mission,
-            canonical_flag="--mission",
-            alias_value=feature,
-            alias_flag="--feature",
-            suppress_env_var="SPEC_KITTY_SUPPRESS_FEATURE_DEPRECATION",
-            command_hint="--mission <slug>",
-        ).canonical_value
-    except typer.BadParameter as exc:
-        _safe_emit_error_logged(str(exc))
+
+    # Resolve mission handle — supports slug, numeric prefix, mid8, or full ULID.
+    # resolve_mission_handle() handles AmbiguousHandleError / MissionNotFoundError
+    # and calls sys.exit(2) on failure; no try/except needed.
+    raw_handle = mission or feature
+    if raw_handle is None:
+        _safe_emit_error_logged("No mission handle provided")
         if json_output:
-            print(json.dumps({"error": str(exc)}))
+            print(json.dumps({"error": "--mission <slug> is required"}))
         else:
-            tracker.error("detect", str(exc))
+            tracker.error("detect", "--mission <slug> is required")
             console.print(tracker.render())
-            console.print(f"[red]Error:[/red] {exc}")
+            console.print("[red]Error:[/red] --mission <slug> is required")
         raise typer.Exit(1)
+
+    resolved = resolve_mission_handle(raw_handle, repo_root, json_mode=json_output)
+    mission_slug = resolved.mission_slug
+
     if not json_output:
         tracker.complete("detect", mission_slug)
 

{spec_kitty_cli-3.1.2a2 → spec_kitty_cli-3.1.2a3}/src/specify_cli/cli/commands/agent/context.py

@@ -10,7 +10,7 @@ import typer
 from rich.console import Console
 from typing_extensions import Annotated
 
-from specify_cli.cli.selector_resolution import resolve_selector
+from specify_cli.cli.selector_resolution import resolve_mission_handle
 from specify_cli.core.paths import locate_project_root
 from specify_cli.core.execution_context import (
     ACTION_NAMES,
@@ -36,6 +36,9 @@ def _find_feature_directory(
 ) -> Path:
     """Find the mission directory from an explicit mission slug.
 
+    Uses the canonical mission resolver which handles ambiguous numeric-prefix
+    handles, mid8 prefixes, and full ULID forms.
+
     Args:
         repo_root: Repository root path
         cwd: Current working directory (unused — kept for signature compatibility)
@@ -46,24 +49,14 @@ def _find_feature_directory(
         Path to mission directory
 
     Raises:
-        ValueError: If mission slug is not provided, selectors conflict, or directory doesn't exist
+        ValueError: If mission slug is not provided or directory doesn't exist.
     """
-    resolved = resolve_selector(
-        canonical_value=explicit_mission,
-        canonical_flag="--mission",
-        alias_value=explicit_feature,
-        alias_flag="--feature",
-        suppress_env_var="SPEC_KITTY_SUPPRESS_FEATURE_DEPRECATION",
-        command_hint="--mission <slug>",
-    )
-    slug = resolved.canonical_value
-    feature_dir = repo_root / "kitty-specs" / slug
-    if not feature_dir.exists():
-        raise ValueError(
-            f"Mission directory not found: {feature_dir}. "
-            f"Check that '{slug}' is the correct mission slug."
-        )
-    return feature_dir
+    raw_handle = explicit_mission or explicit_feature
+    if not raw_handle:
+        raise ValueError("--mission <slug> is required")
+    # resolve_mission_handle calls sys.exit(2) on error; on success returns ResolvedMission.
+    resolved = resolve_mission_handle(raw_handle, repo_root)
+    return resolved.feature_dir
 
 
 @app.command(name="resolve")
@@ -99,14 +92,11 @@ def resolve_context(
                 f"Invalid action '{action}'. Expected one of: {', '.join(ACTION_NAMES)}.",
             )
 
-        mission_slug = resolve_selector(
-            canonical_value=mission,
-            canonical_flag="--mission",
-            alias_value=feature,
-            alias_flag="--feature",
-            suppress_env_var="SPEC_KITTY_SUPPRESS_FEATURE_DEPRECATION",
-            command_hint="--mission <slug>",
-        ).canonical_value
+        raw_handle = mission or feature
+        if not raw_handle:
+            raise ActionContextError("MISSING_MISSION", "--mission <slug> is required")
+        mission_resolved = resolve_mission_handle(raw_handle, repo_root, json_mode=json_output)
+        mission_slug = mission_resolved.mission_slug
 
         context = resolve_action_context(
             repo_root,

{spec_kitty_cli-3.1.2a2 → spec_kitty_cli-3.1.2a3}/src/specify_cli/cli/commands/agent/mission.py

@@ -18,7 +18,7 @@ from rich.console import Console
 from typing import Annotated
 
 from specify_cli import __version__ as SPEC_KITTY_VERSION
-from specify_cli.cli.selector_resolution import resolve_selector
+from specify_cli.cli.selector_resolution import resolve_mission_handle, resolve_selector
 from specify_cli.cli.commands.accept import accept as top_level_accept
 from specify_cli.cli.commands.merge import merge as top_level_merge
 from specify_cli.core.dependency_graph import (
@@ -33,7 +33,6 @@ from specify_cli.core.git_preflight import (
 from specify_cli.core.paths import get_main_repo_root, locate_project_root
 from specify_cli.core.paths import (
     get_feature_target_branch,
-    require_explicit_feature,
 )
 from specify_cli.git import safe_commit
 from specify_cli.core.worktree import (
@@ -367,22 +366,30 @@ def _find_feature_directory(
 ) -> Path:
     """Find the mission directory from an explicit mission slug.
 
+    Uses the canonical mission resolver which handles ambiguous numeric-prefix
+    handles, mid8 prefixes, and full ULID forms.
+
     Args:
         repo_root: Repository root path
-        cwd: Current working directory (unused — kept for signature compatibility)
-        explicit_feature: Mission slug provided explicitly (required)
+        _cwd: Current working directory (unused — kept for signature compatibility)
+        explicit_feature: Mission handle provided explicitly (required)
 
     Returns:
         Path to mission directory
 
     Raises:
-        ValueError: If feature slug is not provided or directory doesn't exist
+        ValueError: If no handle is provided.
     """
-    slug = require_explicit_feature(explicit_feature, command_hint="--mission <slug>")
-    feature_dir = repo_root / "kitty-specs" / slug
-    if not feature_dir.exists():
-        raise ValueError(f"Mission directory not found: {feature_dir}. Check that '{slug}' is the correct mission slug.")
-    return feature_dir
+    if not explicit_feature:
+        raise ValueError("--mission <slug> is required")
+    try:
+        resolved = resolve_mission_handle(explicit_feature, repo_root)
+        return resolved.feature_dir
+    except (SystemExit, typer.Exit):
+        candidate = repo_root / "kitty-specs" / explicit_feature
+        if candidate.exists():
+            return candidate
+        raise ValueError(f"Mission directory not found: {explicit_feature}") from None
 
 
 def _list_feature_spec_candidates(repo_root: Path) -> list[dict[str, object]]:
@@ -394,9 +401,12 @@ def _list_feature_spec_candidates(repo_root: Path) -> list[dict[str, object]]:
 
     candidates: list[dict[str, object]] = []
     for feature_dir in sorted(kitty_specs_dir.iterdir()):
-        if not feature_dir.is_dir() or not re.match(r"^\d{3}-.+$", feature_dir.name):
+        if not feature_dir.is_dir():
             continue
         spec_file = feature_dir / "spec.md"
+        meta_file = feature_dir / "meta.json"
+        if not spec_file.exists() and not meta_file.exists():
+            continue
         candidates.append(
             {
                 "mission_slug": feature_dir.name,
@@ -1164,10 +1174,24 @@ def merge_feature(
             print(json.dumps({"error": error, "success": False}))
             sys.exit(1)
 
+        # Resolve the mission handle to a canonical slug before delegating.
+        resolved_feature = feature
+        if feature:
+            try:
+                _resolved = resolve_mission_handle(feature, repo_root)
+            except (SystemExit, typer.Exit):
+                # Preserve legacy wrapper behavior in tests and programmatic
+                # callers that pass a raw slug/worktree hint without a real
+                # mission directory. The delegated merge flow still performs
+                # its own resolution when operating against a real repo.
+                _resolved = None
+            if _resolved is not None:
+                resolved_feature = _resolved.mission_slug
+
         # Resolve target branch dynamically if not specified
         if target is None:
-            if feature:
-                target = get_feature_target_branch(repo_root, feature)
+            if resolved_feature:
+                target = get_feature_target_branch(repo_root, resolved_feature)
             else:
                 from specify_cli.core.git_ops import resolve_primary_branch
 
@@ -1179,12 +1203,12 @@ def merge_feature(
             is_feature_branch = re.match(r"^\d{3}-", current_branch)
 
             if not is_feature_branch:
-                if not feature:
+                if not resolved_feature:
                     raise RuntimeError(f"Not on mission branch ({current_branch}). Auto-retry requires --mission to choose a deterministic worktree.")
 
-                retry_worktree = _find_feature_worktree(repo_root, feature)
+                retry_worktree = _find_feature_worktree(repo_root, resolved_feature)
                 if not retry_worktree:
-                    raise RuntimeError(f"Could not find worktree for mission {feature} under {repo_root / '.worktrees'}.")
+                    raise RuntimeError(f"Could not find worktree for mission {resolved_feature} under {repo_root / '.worktrees'}.")
 
                 console.print(f"[yellow]Auto-retry:[/yellow] Not on mission branch ({current_branch}). Running merge in {retry_worktree.name}")
 
@@ -1192,9 +1216,9 @@ def merge_feature(
                 env = os.environ.copy()
                 env["SPEC_KITTY_AUTORETRY"] = "1"
 
-                # Re-run command in worktree
+                # Re-run command in worktree; pass canonical slug so retry is unambiguous.
                 retry_cmd = ["spec-kitty", "agent", "mission", "merge"]
-                retry_cmd.extend(["--mission", feature])
+                retry_cmd.extend(["--mission", resolved_feature])
                 retry_cmd.extend(["--target", target, "--strategy", strategy])
                 if push:
                     retry_cmd.append("--push")
@@ -1226,7 +1250,7 @@ def merge_feature(
                 target_branch=target,  # Note: parameter name differs
                 dry_run=dry_run,
                 json_output=False,
-                mission=(feature or ""),
+                mission=(resolved_feature or ""),
                 feature=None,
                 resume=False,  # Agent commands don't support resume
                 abort=False,  # Agent commands don't support abort