mcp-ticketer 2.0.1__py3-none-any.whl → 2.2.13__py3-none-any.whl

mcp_ticketer/adapters/linear/adapter.py

@@ -21,11 +21,13 @@ except ImportError:
 
 import builtins
 
+from ...cache.memory import MemoryCache
 from ...core.adapter import BaseAdapter
 from ...core.models import (
     Attachment,
     Comment,
     Epic,
+    Milestone,
     ProjectUpdate,
     ProjectUpdateHealth,
     SearchQuery,
@@ -45,10 +47,14 @@ from .mappers import (
 )
 from .queries import (
     ALL_FRAGMENTS,
+    ARCHIVE_CYCLE_MUTATION,
+    CREATE_CYCLE_MUTATION,
     CREATE_ISSUE_MUTATION,
     CREATE_LABEL_MUTATION,
     CREATE_PROJECT_UPDATE_MUTATION,
     GET_CUSTOM_VIEW_QUERY,
+    GET_CYCLE_ISSUES_QUERY,
+    GET_CYCLE_QUERY,
     GET_ISSUE_STATUS_QUERY,
     GET_PROJECT_UPDATE_QUERY,
     LIST_CYCLES_QUERY,
@@ -57,6 +63,7 @@ from .queries import (
     LIST_PROJECT_UPDATES_QUERY,
     LIST_PROJECTS_QUERY,
     SEARCH_ISSUES_QUERY,
+    UPDATE_CYCLE_MUTATION,
     UPDATE_ISSUE_MUTATION,
     WORKFLOW_STATES_QUERY,
 )
@@ -98,6 +105,7 @@ class LinearAdapter(BaseAdapter[Task]):
                 - team_key: Linear team key (e.g., 'BTA') OR
                 - team_id: Linear team UUID (e.g., '02d15669-7351-4451-9719-807576c16049')
                 - api_url: Optional Linear API URL (defaults to https://api.linear.app/graphql)
+                - labels_ttl: TTL for label cache in seconds (default: 300)
 
         Raises:
         ------
@@ -108,7 +116,8 @@ class LinearAdapter(BaseAdapter[Task]):
         # because parent constructor calls _get_state_mapping()
         self._team_data: dict[str, Any] | None = None
         self._workflow_states: dict[str, dict[str, Any]] | None = None
-        self._labels_cache: list[dict[str, Any]] | None = None
+        self._labels_ttl = config.get("labels_ttl", 300.0)  # 5 min default
+        self._labels_cache = MemoryCache(default_ttl=self._labels_ttl)
         self._users_cache: dict[str, dict[str, Any]] | None = None
         self._initialized = False
 
@@ -219,6 +228,13 @@ class LinearAdapter(BaseAdapter[Task]):
             logger.debug("Loading team data and workflow states...")
             team_id = await self._ensure_team_id()
 
+            # Validate team_id before initialization
+            if not team_id:
+                raise ValueError(
+                    "Cannot initialize Linear adapter without team_id. "
+                    "Ensure LINEAR_TEAM_KEY is configured correctly."
+                )
+
             # Load workflow states and labels for the team
             await self._load_workflow_states(team_id)
             await self._load_team_labels(team_id)
@@ -531,6 +547,51 @@ class LinearAdapter(BaseAdapter[Task]):
 
         return epic
 
+    def _validate_linear_uuid(self, uuid_value: str, field_name: str = "UUID") -> bool:
+        """Validate Linear UUID format (36 chars, 8-4-4-4-12 pattern).
+
+        Linear UUIDs follow standard UUID v4 format:
+        - Total length: 36 characters
+        - Pattern: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
+        - Contains exactly 4 hyphens at positions 8, 13, 18, 23
+
+        Args:
+        ----
+            uuid_value: UUID string to validate
+            field_name: Name of field for error messages (default: "UUID")
+
+        Returns:
+        -------
+            True if valid UUID format, False otherwise
+
+        Examples:
+        --------
+            >>> _validate_linear_uuid("12345678-1234-1234-1234-123456789012", "projectId")
+            True
+            >>> _validate_linear_uuid("invalid-uuid", "projectId")
+            False
+        """
+        logger = logging.getLogger(__name__)
+
+        if not isinstance(uuid_value, str):
+            logger.warning(f"{field_name} is not a string: {type(uuid_value).__name__}")
+            return False
+
+        if len(uuid_value) != 36:
+            logger.warning(
+                f"{field_name} has invalid length {len(uuid_value)}, expected 36 characters"
+            )
+            return False
+
+        if uuid_value.count("-") != 4:
+            logger.warning(
+                f"{field_name} has invalid format: {uuid_value}. "
+                f"Expected xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx pattern"
+            )
+            return False
+
+        return True
+
     async def _resolve_project_id(self, project_identifier: str) -> str | None:
         """Resolve project identifier (slug, name, short ID, or URL) to full UUID.
 
@@ -678,11 +739,31 @@ class LinearAdapter(BaseAdapter[Task]):
                             or slug_part.lower() == project_lower
                             or short_id.lower() == project_lower
                         ):
-                            return project["id"]
+                            project_uuid = project["id"]
+                            # Validate UUID format before returning
+                            if not self._validate_linear_uuid(
+                                project_uuid, "projectId"
+                            ):
+                                logging.getLogger(__name__).error(
+                                    f"Project '{project_identifier}' resolved to invalid UUID format: '{project_uuid}'. "
+                                    f"Expected 36-character UUID (xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx). "
+                                    f"This indicates a data inconsistency in Linear API response."
+                                )
+                                return None
+                            return project_uuid
 
                 # Also check exact name match (case-insensitive)
                 if project["name"].lower() == project_lower:
-                    return project["id"]
+                    project_uuid = project["id"]
+                    # Validate UUID format before returning
+                    if not self._validate_linear_uuid(project_uuid, "projectId"):
+                        logging.getLogger(__name__).error(
+                            f"Project '{project_identifier}' resolved to invalid UUID format: '{project_uuid}'. "
+                            f"Expected 36-character UUID (xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx). "
+                            f"This indicates a data inconsistency in Linear API response."
+                        )
+                        return None
+                    return project_uuid
 
             # No match found
             return None
@@ -882,33 +963,110 @@ class LinearAdapter(BaseAdapter[Task]):
             ) from e
 
     async def _load_workflow_states(self, team_id: str) -> None:
-        """Load and cache workflow states for the team.
+        """Load and cache workflow states for the team with semantic name matching.
+
+        Implements two-level mapping strategy to handle Linear workflows with
+        multiple states of the same type (e.g., "Todo", "Backlog", "Ready" all
+        being "unstarted"):
+
+        1. Semantic name matching: Match state names to universal states using
+           predefined mappings (flexible, respects custom workflows)
+        2. State type fallback: Use first state of matching type for unmapped
+           universal states (backward compatible)
+
+        This fixes issue 1M-552 where transitions to READY/TESTED/WAITING states
+        failed with "Discrepancy between issue state and state type" errors.
 
         Args:
         ----
             team_id: Linear team ID
 
         """
+        logger = logging.getLogger(__name__)
         try:
             result = await self.client.execute_query(
                 WORKFLOW_STATES_QUERY, {"teamId": team_id}
             )
 
-            workflow_states = {}
-            for state in result["team"]["states"]["nodes"]:
+            states = result["team"]["states"]["nodes"]
+
+            # Build auxiliary mappings for efficient lookup
+            state_by_name: dict[str, tuple[str, str]] = {}  # name → (state_id, type)
+            state_by_type: dict[str, str] = {}  # type → state_id (first occurrence)
+
+            # Sort states by position to ensure consistent selection
+            sorted_states = sorted(states, key=lambda s: s["position"])
+
+            for state in sorted_states:
+                state_id = state["id"]
+                state_name = state["name"].lower()
                 state_type = state["type"].lower()
-                if state_type not in workflow_states:
-                    workflow_states[state_type] = state
-                elif state["position"] < workflow_states[state_type]["position"]:
-                    workflow_states[state_type] = state
+
+                # Store by name for semantic matching (first occurrence wins)
+                if state_name not in state_by_name:
+                    state_by_name[state_name] = (state_id, state_type)
+
+                # Store by type for fallback (keep first occurrence by position)
+                if state_type not in state_by_type:
+                    state_by_type[state_type] = state_id
+
+            # Build final state map with semantic matching
+            workflow_states = {}
+
+            for universal_state in TicketState:
+                state_id = None
+                matched_strategy = None
+
+                # Strategy 1: Try semantic name matching
+                if universal_state in LinearStateMapping.SEMANTIC_NAMES:
+                    for semantic_name in LinearStateMapping.SEMANTIC_NAMES[
+                        universal_state
+                    ]:
+                        if semantic_name in state_by_name:
+                            state_id = state_by_name[semantic_name][0]
+                            matched_strategy = f"name:{semantic_name}"
+                            break
+
+                # Strategy 2: Fallback to type mapping
+                if not state_id:
+                    linear_type = LinearStateMapping.TO_LINEAR.get(universal_state)
+                    if linear_type:
+                        state_id = state_by_type.get(linear_type)
+                        if state_id:
+                            matched_strategy = f"type:{linear_type}"
+
+                if state_id:
+                    workflow_states[universal_state.value] = state_id
+                    logger.debug(
+                        f"Mapped {universal_state.value} → {state_id} "
+                        f"(strategy: {matched_strategy})"
+                    )
 
             self._workflow_states = workflow_states
 
+            # Log warning if multiple states of same type detected
+            type_counts: dict[str, int] = {}
+            for state in states:
+                state_type = state["type"].lower()
+                type_counts[state_type] = type_counts.get(state_type, 0) + 1
+
+            multi_state_types = {
+                type_: count for type_, count in type_counts.items() if count > 1
+            }
+            if multi_state_types:
+                logger.info(
+                    f"Team {team_id} has multiple states per type: {multi_state_types}. "
+                    "Using semantic name matching for state resolution."
+                )
+
         except Exception as e:
             raise ValueError(f"Failed to load workflow states: {e}") from e
 
     async def _load_team_labels(self, team_id: str) -> None:
-        """Load and cache labels for the team with retry logic.
+        """Load and cache labels for the team with retry logic and pagination.
+
+        Fetches ALL labels for the team using cursor-based pagination.
+        Handles teams with >250 labels (Linear's default page size).
 
         Args:
         ----
@@ -918,15 +1076,19 @@ class LinearAdapter(BaseAdapter[Task]):
         logger = logging.getLogger(__name__)
 
         query = """
-            query GetTeamLabels($teamId: String!) {
+            query GetTeamLabels($teamId: String!, $first: Int!, $after: String) {
                 team(id: $teamId) {
-                    labels {
+                    labels(first: $first, after: $after) {
                         nodes {
                             id
                             name
                             color
                             description
                         }
+                        pageInfo {
+                            hasNextPage
+                            endCursor
+                        }
                     }
                 }
             }
@@ -935,10 +1097,40 @@ class LinearAdapter(BaseAdapter[Task]):
         max_retries = 3
         for attempt in range(max_retries):
             try:
-                result = await self.client.execute_query(query, {"teamId": team_id})
-                labels = result.get("team", {}).get("labels", {}).get("nodes", [])
-                self._labels_cache = labels
-                logger.info(f"Loaded {len(labels)} labels for team {team_id}")
+                # Fetch all labels with pagination
+                all_labels: list[dict] = []
+                has_next_page = True
+                after_cursor = None
+                page_count = 0
+                max_pages = 10  # Safety limit: 10 pages * 250 labels = 2500 labels max
+
+                while has_next_page and page_count < max_pages:
+                    page_count += 1
+                    variables = {"teamId": team_id, "first": 250}
+                    if after_cursor:
+                        variables["after"] = after_cursor
+
+                    result = await self.client.execute_query(query, variables)
+                    labels_data = result.get("team", {}).get("labels", {})
+                    page_labels = labels_data.get("nodes", [])
+                    page_info = labels_data.get("pageInfo", {})
+
+                    all_labels.extend(page_labels)
+                    has_next_page = page_info.get("hasNextPage", False)
+                    after_cursor = page_info.get("endCursor")
+
+                if page_count >= max_pages and has_next_page:
+                    logger.warning(
+                        f"Reached max page limit ({max_pages}) for team {team_id}. "
+                        f"Loaded {len(all_labels)} labels, but more may exist."
+                    )
+
+                # Store in TTL-based cache
+                cache_key = f"linear_labels:{team_id}"
+                await self._labels_cache.set(cache_key, all_labels)
+                logger.info(
+                    f"Loaded {len(all_labels)} labels for team {team_id} ({page_count} page(s))"
+                )
                 return  # Success
 
             except Exception as e:
@@ -954,12 +1146,14 @@ class LinearAdapter(BaseAdapter[Task]):
                         f"Failed to load team labels after {max_retries} attempts: {e}",
                         exc_info=True,
                     )
-                    self._labels_cache = []  # Explicitly empty on failure
+                    # Store empty list in cache on failure
+                    cache_key = f"linear_labels:{team_id}"
+                    await self._labels_cache.set(cache_key, [])
 
     async def _find_label_by_name(
         self, name: str, team_id: str, max_retries: int = 3
     ) -> dict | None:
-        """Find a label by name using Linear API (server-side check) with retry logic.
+        """Find a label by name using Linear API (server-side check) with retry logic and pagination.
 
         Handles cache staleness by checking Linear's server-side state.
         This method is used when cache lookup misses to prevent duplicate
@@ -969,6 +1163,10 @@ class LinearAdapter(BaseAdapter[Task]):
         network failures and distinguish between "label not found" (None) and
         "check failed" (exception).
 
+        Uses cursor-based pagination with early exit optimization to handle
+        teams with >250 labels efficiently. Stops searching as soon as the
+        label is found.
+
         Args:
         ----
             name: Label name to search for (case-insensitive)
@@ -986,11 +1184,6 @@ class LinearAdapter(BaseAdapter[Task]):
                       (network/API failure). Caller must handle to prevent
                       duplicate label creation.
 
-        Note:
-        ----
-            This method queries Linear's API and returns the first 250 labels.
-            For teams with >250 labels, pagination would be needed (future enhancement).
-
         Related:
         -------
             1M-443: Fix duplicate label error when setting existing labels
@@ -1000,15 +1193,19 @@ class LinearAdapter(BaseAdapter[Task]):
         logger = logging.getLogger(__name__)
 
         query = """
-            query GetTeamLabels($teamId: String!) {
+            query GetTeamLabels($teamId: String!, $first: Int!, $after: String) {
                 team(id: $teamId) {
-                    labels(first: 250) {
+                    labels(first: $first, after: $after) {
                         nodes {
                             id
                             name
                             color
                             description
                         }
+                        pageInfo {
+                            hasNextPage
+                            endCursor
+                        }
                     }
                 }
             }
@@ -1016,20 +1213,47 @@ class LinearAdapter(BaseAdapter[Task]):
 
         for attempt in range(max_retries):
             try:
-                result = await self.client.execute_query(query, {"teamId": team_id})
-                labels = result.get("team", {}).get("labels", {}).get("nodes", [])
-
-                # Case-insensitive search
+                # Search with pagination and early exit
                 name_lower = name.lower()
-                for label in labels:
-                    if label["name"].lower() == name_lower:
-                        logger.debug(
-                            f"Found label '{name}' via server-side search (ID: {label['id']})"
-                        )
-                        return label
+                has_next_page = True
+                after_cursor = None
+                page_count = 0
+                max_pages = 10  # Safety limit: 10 pages * 250 labels = 2500 labels max
+                total_checked = 0
+
+                while has_next_page and page_count < max_pages:
+                    page_count += 1
+                    variables = {"teamId": team_id, "first": 250}
+                    if after_cursor:
+                        variables["after"] = after_cursor
+
+                    result = await self.client.execute_query(query, variables)
+                    labels_data = result.get("team", {}).get("labels", {})
+                    page_labels = labels_data.get("nodes", [])
+                    page_info = labels_data.get("pageInfo", {})
+
+                    total_checked += len(page_labels)
+
+                    # Case-insensitive search in current page
+                    for label in page_labels:
+                        if label["name"].lower() == name_lower:
+                            logger.debug(
+                                f"Found label '{name}' via server-side search "
+                                f"(ID: {label['id']}, checked {total_checked} labels)"
+                            )
+                            return label
+
+                    has_next_page = page_info.get("hasNextPage", False)
+                    after_cursor = page_info.get("endCursor")
+
+                if page_count >= max_pages and has_next_page:
+                    logger.warning(
+                        f"Reached max page limit ({max_pages}) searching for label '{name}'. "
+                        f"Checked {total_checked} labels, but more exist."
+                    )
 
                 # Label definitively doesn't exist (successful check)
-                logger.debug(f"Label '{name}' not found in {len(labels)} team labels")
+                logger.debug(f"Label '{name}' not found in {total_checked} team labels")
                 return None
 
             except Exception as e:
@@ -1096,9 +1320,9 @@ class LinearAdapter(BaseAdapter[Task]):
             created_label = result["issueLabelCreate"]["issueLabel"]
             label_id = created_label["id"]
 
-            # Update cache with new label
+            # Invalidate cache to force refresh on next access
             if self._labels_cache is not None:
-                self._labels_cache.append(created_label)
+                await self._labels_cache.clear()
 
             logger.info(f"Created new label '{name}' with ID: {label_id}")
             return label_id
@@ -1122,26 +1346,76 @@ class LinearAdapter(BaseAdapter[Task]):
                     f"Duplicate label detected for '{name}', attempting recovery lookup"
                 )
 
-                # Retry Tier 2: Query server for existing label
-                server_label = await self._find_label_by_name(name, team_id)
-
-                if server_label:
-                    label_id = server_label["id"]
+                # Retry Tier 2 with backoff: API eventual consistency requires delay
+                # Linear API has 100-500ms propagation delay between write and read
+                max_recovery_attempts = 5
+                backoff_delays = [0.1, 0.2, 0.5, 1.0, 1.5]  # Total: 3.3s max
 
-                    # Update cache with recovered label
-                    if self._labels_cache is not None:
-                        self._labels_cache.append(server_label)
+                for attempt in range(max_recovery_attempts):
+                    try:
+                        if attempt > 0:
+                            # Wait before retry (skip delay on first attempt)
+                            delay = backoff_delays[
+                                min(attempt - 1, len(backoff_delays) - 1)
+                            ]
+                            logger.debug(
+                                f"Label '{name}' duplicate detected. "
+                                f"Retrying retrieval (attempt {attempt + 1}/{max_recovery_attempts}) "
+                                f"after {delay}s delay for API propagation..."
+                            )
+                            await asyncio.sleep(delay)
+
+                        # Query server for existing label
+                        server_label = await self._find_label_by_name(name, team_id)
+
+                        if server_label:
+                            label_id = server_label["id"]
+
+                            # Invalidate cache to force refresh on next access
+                            if self._labels_cache is not None:
+                                await self._labels_cache.clear()
+
+                            logger.info(
+                                f"Successfully recovered existing label '{name}' (ID: {label_id}) "
+                                f"after {attempt + 1} attempt(s)"
+                            )
+                            return label_id
+
+                        # Label still not found, log and continue to next retry
+                        logger.debug(
+                            f"Label '{name}' not found in recovery attempt {attempt + 1}/{max_recovery_attempts}"
+                        )
 
-                    logger.info(
-                        f"Successfully recovered from duplicate label error: '{name}' "
-                        f"(ID: {label_id})"
-                    )
-                    return label_id
+                    except Exception as lookup_error:
+                        logger.warning(
+                            f"Recovery lookup failed on attempt {attempt + 1}/{max_recovery_attempts}: {lookup_error}"
+                        )
 
-                # Recovery failed - label exists but we can't retrieve it
+                        # If this is the last attempt, raise with context
+                        if attempt == max_recovery_attempts - 1:
+                            raise ValueError(
+                                f"Failed to recover label '{name}' after {max_recovery_attempts} attempts. "
+                                f"Last error: {lookup_error}. This may indicate:\n"
+                                f"  1. Network connectivity issues\n"
+                                f"  2. API propagation delay >{sum(backoff_delays):.1f}s (very unusual)\n"
+                                f"  3. Label exists beyond first 250 labels in team\n"
+                                f"  4. Permissions issue preventing label query\n"
+                                f"Please retry the operation or check Linear workspace status."
+                            ) from lookup_error
+
+                        # Not the last attempt, continue to next retry
+                        continue
+
+                # If we get here, all recovery attempts failed (label never found, no exceptions)
                 raise ValueError(
-                    f"Label '{name}' already exists but could not retrieve ID. "
-                    f"This may indicate a permissions issue or API inconsistency."
+                    f"Label '{name}' already exists but could not retrieve ID after "
+                    f"{max_recovery_attempts} attempts. The label query succeeded but returned no results.\n"
+                    f"This may indicate:\n"
+                    f"  1. API propagation delay >{sum(backoff_delays):.1f}s (very unusual)\n"
+                    f"  2. Label exists beyond first 250 labels in team\n"
+                    f"  3. Permissions issue preventing label query\n"
+                    f"  4. Team ID mismatch\n"
+                    f"Please retry the operation or check Linear workspace permissions."
                 ) from e
 
             # Not a duplicate error - re-raise original exception
@@ -1194,24 +1468,33 @@ class LinearAdapter(BaseAdapter[Task]):
         if not label_names:
             return []
 
-        # Ensure labels are loaded
-        if self._labels_cache is None:
-            team_id = await self._ensure_team_id()
+        # Get team ID for label operations
+        team_id = await self._ensure_team_id()
+
+        # Validate team_id before loading labels
+        if not team_id:
+            raise ValueError(
+                "Cannot resolve Linear labels without team_id. "
+                "Ensure LINEAR_TEAM_KEY is configured correctly."
+            )
+
+        # Check cache for labels
+        cache_key = f"linear_labels:{team_id}"
+        cached_labels = await self._labels_cache.get(cache_key)
+
+        # Load labels if not cached
+        if cached_labels is None:
             await self._load_team_labels(team_id)
+            cached_labels = await self._labels_cache.get(cache_key)
 
-        if self._labels_cache is None:
+        if not cached_labels:
             logger.error(
-                "Label cache is None after load attempt. Tags will be skipped."
+                "Label cache is empty after load attempt. Tags will be skipped."
             )
             return []
 
-        # Get team ID for creating new labels
-        team_id = await self._ensure_team_id()
-
         # Create name -> ID mapping (case-insensitive)
-        label_map = {
-            label["name"].lower(): label["id"] for label in (self._labels_cache or [])
-        }
+        label_map = {label["name"].lower(): label["id"] for label in cached_labels}
 
         logger.debug(f"Available labels in team: {list(label_map.keys())}")
 
@@ -1245,18 +1528,18 @@ class LinearAdapter(BaseAdapter[Task]):
                     ) from e
 
                 if server_label:
-                    # Label exists on server but not in cache - update cache
+                    # Label exists on server but not in cache - invalidate cache
                     label_id = server_label["id"]
                     label_ids.append(label_id)
                     label_map[name_lower] = label_id
 
-                    # Update cache to prevent future misses
+                    # Invalidate cache to force refresh on next access
                     if self._labels_cache is not None:
-                        self._labels_cache.append(server_label)
+                        await self._labels_cache.clear()
 
                     logger.info(
                         f"[Tier 2] Found stale label '{name}' on server (ID: {label_id}), "
-                        "updated cache"
+                        "invalidated cache for refresh"
                     )
                 else:
                     # Tier 3: Label truly doesn't exist - create it
@@ -1292,7 +1575,7 @@ class LinearAdapter(BaseAdapter[Task]):
 
         Returns:
         -------
-            Dictionary mapping TicketState to Linear state ID
+            Dictionary mapping TicketState to Linear state ID (UUID)
 
         """
         if not self._workflow_states:
@@ -1309,13 +1592,18 @@ class LinearAdapter(BaseAdapter[Task]):
             }
 
         # Return ID-based mapping using cached workflow states
+        # _workflow_states is keyed by universal_state.value (e.g., "open")
+        # and contains state UUIDs directly
         mapping = {}
-        for universal_state, linear_type in LinearStateMapping.TO_LINEAR.items():
-            if linear_type in self._workflow_states:
-                mapping[universal_state] = self._workflow_states[linear_type]["id"]
+        for universal_state in TicketState:
+            state_uuid = self._workflow_states.get(universal_state.value)
+            if state_uuid:
+                mapping[universal_state] = state_uuid
             else:
-                # Fallback to type name
-                mapping[universal_state] = linear_type
+                # Fallback to type name if state not found in cache
+                linear_type = LinearStateMapping.TO_LINEAR.get(universal_state)
+                if linear_type:
+                    mapping[universal_state] = linear_type
 
         return mapping
 
@@ -1419,6 +1707,13 @@ class LinearAdapter(BaseAdapter[Task]):
         logger = logging.getLogger(__name__)
         team_id = await self._ensure_team_id()
 
+        # Validate team_id before creating issue
+        if not team_id:
+            raise ValueError(
+                "Cannot create Linear issue without team_id. "
+                "Ensure LINEAR_TEAM_KEY is configured correctly."
+            )
+
         # Build issue input using mapper
         issue_input = build_linear_issue_input(task, team_id)
 
@@ -1529,6 +1824,22 @@ class LinearAdapter(BaseAdapter[Task]):
                 )
                 issue_input.pop("labelIds")
 
+        # Debug logging: Log mutation input before execution for troubleshooting
+        logger.debug(
+            "Creating Linear issue with input: %s",
+            {
+                "title": task.title,
+                "teamId": team_id,
+                "projectId": issue_input.get("projectId"),
+                "parentId": issue_input.get("parentId"),
+                "stateId": issue_input.get("stateId"),
+                "priority": issue_input.get("priority"),
+                "labelIds": issue_input.get("labelIds"),
+                "assigneeId": issue_input.get("assigneeId"),
+                "hasDescription": bool(task.description),
+            },
+        )
+
         try:
             result = await self.client.execute_mutation(
                 CREATE_ISSUE_MUTATION, {"input": issue_input}
@@ -1559,13 +1870,45 @@ class LinearAdapter(BaseAdapter[Task]):
         """
         team_id = await self._ensure_team_id()
 
+        # Validate team_id before creating teamIds array
+        if not team_id:
+            raise ValueError(
+                "Cannot create Linear project without team_id. "
+                "Ensure LINEAR_TEAM_KEY is configured correctly."
+            )
+
         project_input = {
             "name": epic.title,
             "teamIds": [team_id],
         }
 
         if epic.description:
-            project_input["description"] = epic.description
+            # Validate description length (Linear limit: 255 chars for project description)
+            # Matches validation in update_epic() for consistency
+            from mcp_ticketer.core.validators import FieldValidator, ValidationError
+
+            try:
+                validated_description = FieldValidator.validate_field(
+                    "linear", "epic_description", epic.description, truncate=False
+                )
+                project_input["description"] = validated_description
+            except ValidationError as e:
+                raise ValueError(
+                    f"Epic description validation failed: {e}. "
+                    f"Linear projects have a 255 character limit for descriptions. "
+                    f"Current length: {len(epic.description)} characters."
+                ) from e
+
+        # Debug logging: Log mutation input before execution for troubleshooting
+        logging.getLogger(__name__).debug(
+            "Creating Linear project with input: %s",
+            {
+                "name": epic.title,
+                "teamIds": [team_id],
+                "hasDescription": bool(project_input.get("description")),
+                "leadId": project_input.get("leadId"),
+            },
+        )
 
         # Create project mutation
         create_query = """
@@ -1677,6 +2020,20 @@ class LinearAdapter(BaseAdapter[Task]):
         if "icon" in updates:
             update_input["icon"] = updates["icon"]
 
+        # Debug logging: Log mutation input before execution for troubleshooting
+        logging.getLogger(__name__).debug(
+            "Updating Linear project %s with input: %s",
+            epic_id,
+            {
+                "name": update_input.get("name"),
+                "hasDescription": bool(update_input.get("description")),
+                "state": update_input.get("state"),
+                "targetDate": update_input.get("targetDate"),
+                "color": update_input.get("color"),
+                "icon": update_input.get("icon"),
+            },
+        )
+
         # ProjectUpdate mutation
         update_query = """
             mutation UpdateProject($id: String!, $input: ProjectUpdateInput!) {
@@ -1972,19 +2329,35 @@ class LinearAdapter(BaseAdapter[Task]):
             return False
 
     async def list(
-        self, limit: int = 10, offset: int = 0, filters: dict[str, Any] | None = None
-    ) -> builtins.list[Task]:
-        """List Linear issues with optional filtering.
+        self,
+        limit: int = 20,
+        offset: int = 0,
+        filters: dict[str, Any] | None = None,
+        compact: bool = False,
+    ) -> dict[str, Any] | builtins.list[Task]:
+        """List Linear issues with optional filtering and compact output.
 
         Args:
         ----
-            limit: Maximum number of issues to return
+            limit: Maximum number of issues to return (default: 20, max: 100)
             offset: Number of issues to skip (Note: Linear uses cursor-based pagination)
             filters: Optional filters (state, assignee, priority, etc.)
+            compact: Return compact format for token efficiency (default: False for backward compatibility)
 
         Returns:
         -------
-            List of tasks matching the criteria
+            When compact=True: Dictionary with items and pagination metadata
+            When compact=False: List of Task objects (backward compatible, default)
+
+        Design Decision: Backward Compatible Default (1M-554)
+        ------------------------------------------------------
+        Rationale: Backward compatibility prioritized to avoid breaking existing code.
+        Compact mode available via explicit compact=True for new code.
+
+        Default compact=False maintains existing return type (list[Task]).
+        Users can opt-in to compact mode for 77% token reduction.
+
+        Recommended: Use compact=True for new code to reduce token usage by ~77%.
 
         """
         # Validate credentials
@@ -1995,6 +2368,17 @@ class LinearAdapter(BaseAdapter[Task]):
         await self.initialize()
         team_id = await self._ensure_team_id()
 
+        # Validate team_id before filtering
+        if not team_id:
+            raise ValueError(
+                "Cannot list Linear issues without team_id. "
+                "Ensure LINEAR_TEAM_KEY is configured correctly."
+            )
+
+        # Enforce maximum limit to prevent excessive responses
+        if limit > 100:
+            limit = 100
+
         # Build issue filter
         issue_filter = build_issue_filter(
             team_id=team_id,
@@ -2034,6 +2418,24 @@ class LinearAdapter(BaseAdapter[Task]):
             for issue in result["issues"]["nodes"]:
                 tasks.append(map_linear_issue_to_task(issue))
 
+            # Return compact format with pagination metadata
+            if compact:
+                from .mappers import task_to_compact_format
+
+                compact_items = [task_to_compact_format(task) for task in tasks]
+                return {
+                    "status": "success",
+                    "items": compact_items,
+                    "pagination": {
+                        "total_returned": len(compact_items),
+                        "limit": limit,
+                        "offset": offset,
+                        "has_more": len(tasks)
+                        == limit,  # Heuristic: full page likely means more
+                    },
+                }
+
+            # Backward compatible: return list of Task objects
             return tasks
 
         except Exception as e:
@@ -2059,6 +2461,13 @@ class LinearAdapter(BaseAdapter[Task]):
         await self.initialize()
         team_id = await self._ensure_team_id()
 
+        # Validate team_id before searching
+        if not team_id:
+            raise ValueError(
+                "Cannot search Linear issues without team_id. "
+                "Ensure LINEAR_TEAM_KEY is configured correctly."
+            )
+
         # Build comprehensive issue filter
         issue_filter = {"team": {"id": {"eq": team_id}}}
 
@@ -2302,13 +2711,26 @@ class LinearAdapter(BaseAdapter[Task]):
             List of label dictionaries with 'id', 'name', and 'color' fields
 
         """
-        # Ensure labels are loaded
-        if self._labels_cache is None:
-            team_id = await self._ensure_team_id()
+        # Get team ID for label operations
+        team_id = await self._ensure_team_id()
+        # Validate team_id before loading labels
+        if not team_id:
+            raise ValueError(
+                "Cannot list Linear labels without team_id. "
+                "Ensure LINEAR_TEAM_KEY is configured correctly."
+            )
+
+        # Check cache for labels
+        cache_key = f"linear_labels:{team_id}"
+        cached_labels = await self._labels_cache.get(cache_key)
+
+        # Load labels if not cached
+        if cached_labels is None:
             await self._load_team_labels(team_id)
+            cached_labels = await self._labels_cache.get(cache_key)
 
         # Return cached labels or empty list if not available
-        if not self._labels_cache:
+        if not cached_labels:
             return []
 
         # Transform to standardized format
@@ -2318,9 +2740,19 @@ class LinearAdapter(BaseAdapter[Task]):
                 "name": label["name"],
                 "color": label.get("color", ""),
             }
-            for label in self._labels_cache
+            for label in cached_labels
         ]
 
+    async def invalidate_label_cache(self) -> None:
+        """Manually invalidate the label cache.
+
+        Useful when labels are modified externally or after creating new labels.
+        The cache will be automatically refreshed on the next label operation.
+
+        """
+        if self._labels_cache is not None:
+            await self._labels_cache.clear()
+
     async def upload_file(self, file_path: str, mime_type: str | None = None) -> str:
         """Upload a file to Linear's storage and return the asset URL.
 
@@ -2762,6 +3194,13 @@ class LinearAdapter(BaseAdapter[Task]):
         if team_id is None:
             team_id = await self._ensure_team_id()
 
+        # Validate team_id before listing cycles
+        if not team_id:
+            raise ValueError(
+                "Cannot list Linear cycles without team_id. "
+                "Ensure LINEAR_TEAM_KEY is configured correctly."
+            )
+
         try:
             # Fetch all cycles with pagination
             all_cycles: list[dict[str, Any]] = []
@@ -2876,6 +3315,13 @@ class LinearAdapter(BaseAdapter[Task]):
         if team_id is None:
             team_id = await self._ensure_team_id()
 
+        # Validate team_id before listing statuses
+        if not team_id:
+            raise ValueError(
+                "Cannot list Linear issue statuses without team_id. "
+                "Ensure LINEAR_TEAM_KEY is configured correctly."
+            )
+
         try:
             result = await self.client.execute_query(
                 LIST_ISSUE_STATUSES_QUERY, {"teamId": team_id}
@@ -2894,30 +3340,40 @@ class LinearAdapter(BaseAdapter[Task]):
 
     async def list_epics(
         self,
-        limit: int = 50,
+        limit: int = 20,
         offset: int = 0,
         state: str | None = None,
         include_completed: bool = True,
+        compact: bool = False,
         **kwargs: Any,
-    ) -> builtins.list[Epic]:
-        """List Linear projects (epics) with efficient pagination.
+    ) -> dict[str, Any] | builtins.list[Epic]:
+        """List Linear projects (epics) with efficient pagination and compact output.
 
         Args:
         ----
-            limit: Maximum number of projects to return (default: 50)
+            limit: Maximum number of projects to return (default: 20, max: 100)
             offset: Number of projects to skip (note: Linear uses cursor-based pagination)
             state: Filter by project state (e.g., "planned", "started", "completed", "canceled")
             include_completed: Whether to include completed projects (default: True)
+            compact: Return compact format for token efficiency (default: False for backward compatibility)
             **kwargs: Additional filter parameters (reserved for future use)
 
         Returns:
         -------
-            List of Epic objects mapped from Linear projects
+            When compact=True: Dictionary with items and pagination metadata
+            When compact=False: List of Epic objects (backward compatible, default)
 
         Raises:
         ------
             ValueError: If credentials are invalid or query fails
 
+        Design Decision: Backward Compatible with Opt-in Compact Mode (1M-554)
+        ----------------------------------------------------------------------
+        Rationale: Reduced default limit from 50 to 20 to match list() behavior.
+        Compact mode provides ~77% token reduction when explicitly enabled.
+
+        Recommended: Use compact=True for new code to reduce token usage.
+
         """
         # Validate credentials
         is_valid, error_message = self.validate_credentials()
@@ -2927,6 +3383,17 @@ class LinearAdapter(BaseAdapter[Task]):
         await self.initialize()
         team_id = await self._ensure_team_id()
 
+        # Validate team_id before listing projects
+        if not team_id:
+            raise ValueError(
+                "Cannot list Linear projects without team_id. "
+                "Ensure LINEAR_TEAM_KEY is configured correctly."
+            )
+
+        # Enforce maximum limit to prevent excessive responses
+        if limit > 100:
+            limit = 100
+
         # Build project filter using existing helper
         from .types import build_project_filter
 
@@ -2976,6 +3443,23 @@ class LinearAdapter(BaseAdapter[Task]):
             for project in paginated_projects:
                 epics.append(map_linear_project_to_epic(project))
 
+            # Return compact format with pagination metadata
+            if compact:
+                from .mappers import epic_to_compact_format
+
+                compact_items = [epic_to_compact_format(epic) for epic in epics]
+                return {
+                    "status": "success",
+                    "items": compact_items,
+                    "pagination": {
+                        "total_returned": len(compact_items),
+                        "limit": limit,
+                        "offset": offset,
+                        "has_more": has_next_page,  # Use actual Linear pagination status
+                    },
+                }
+
+            # Backward compatible: return list of Epic objects
             return epics
 
         except Exception as e:
@@ -3244,6 +3728,430 @@ class LinearAdapter(BaseAdapter[Task]):
             logger.error(f"Failed to get project update {update_id}: {e}")
             raise ValueError(f"Failed to get project update '{update_id}': {e}") from e
 
+    # Milestone Operations (1M-607 Phase 2: Linear Adapter Integration)
+
+    async def milestone_create(
+        self,
+        name: str,
+        target_date: datetime | None = None,
+        labels: list[str] | None = None,
+        description: str = "",
+        project_id: str | None = None,
+    ) -> Milestone:
+        """Create milestone using Linear Cycles.
+
+        Linear Cycles require start and end dates. If target_date is provided,
+        set startsAt to today and endsAt to target_date. If no target_date,
+        defaults to a 2-week cycle.
+
+        Args:
+        ----
+            name: Milestone name
+            target_date: Target completion date (optional)
+            labels: Labels for milestone grouping (optional, stored in metadata)
+            description: Milestone description
+            project_id: Associated project ID (optional)
+
+        Returns:
+        -------
+            Created Milestone object
+
+        Raises:
+        ------
+            ValueError: If credentials invalid or creation fails
+
+        """
+        logger = logging.getLogger(__name__)
+
+        # Validate credentials
+        is_valid, error_message = self.validate_credentials()
+        if not is_valid:
+            raise ValueError(error_message)
+
+        await self.initialize()
+        team_id = await self._ensure_team_id()
+
+        # Linear requires both start and end dates for cycles
+        from datetime import timedelta, timezone
+
+        starts_at = datetime.now(timezone.utc)
+        if target_date:
+            ends_at = target_date
+            # Ensure ends_at has timezone info
+            if ends_at.tzinfo is None:
+                ends_at = ends_at.replace(tzinfo=timezone.utc)
+        else:
+            # Default to 2 weeks from now
+            ends_at = starts_at + timedelta(days=14)
+
+        try:
+            result = await self.client.execute_query(
+                CREATE_CYCLE_MUTATION,
+                {
+                    "input": {
+                        "name": name,
+                        "description": description,
+                        "startsAt": starts_at.isoformat(),
+                        "endsAt": ends_at.isoformat(),
+                        "teamId": team_id,
+                    }
+                },
+            )
+
+            if not result.get("cycleCreate", {}).get("success"):
+                raise ValueError("Failed to create cycle")
+
+            cycle_data = result["cycleCreate"]["cycle"]
+            logger.info(
+                f"Created Linear cycle {cycle_data['id']} for milestone '{name}'"
+            )
+
+            # Convert Linear Cycle to Milestone model
+            return self._cycle_to_milestone(cycle_data, labels)
+
+        except Exception as e:
+            logger.error(f"Failed to create milestone '{name}': {e}")
+            raise ValueError(f"Failed to create milestone: {e}") from e
+
+    async def milestone_get(self, milestone_id: str) -> Milestone | None:
+        """Get milestone by ID with progress calculation.
+
+        Args:
+        ----
+            milestone_id: Milestone/Cycle identifier
+
+        Returns:
+        -------
+            Milestone object with calculated progress, None if not found
+
+        """
+        logger = logging.getLogger(__name__)
+
+        # Validate credentials
+        is_valid, error_message = self.validate_credentials()
+        if not is_valid:
+            raise ValueError(error_message)
+
+        await self.initialize()
+
+        try:
+            result = await self.client.execute_query(
+                GET_CYCLE_QUERY, {"id": milestone_id}
+            )
+
+            cycle_data = result.get("cycle")
+            if not cycle_data:
+                logger.debug(f"Cycle {milestone_id} not found")
+                return None
+
+            return self._cycle_to_milestone(cycle_data)
+
+        except Exception as e:
+            logger.warning(f"Failed to get milestone {milestone_id}: {e}")
+            return None
+
+    async def milestone_list(
+        self,
+        project_id: str | None = None,
+        state: str | None = None,
+    ) -> list[Milestone]:
+        """List milestones using Linear Cycles.
+
+        Args:
+        ----
+            project_id: Filter by project (not used by Linear Cycles)
+            state: Filter by state (open, active, completed, closed)
+
+        Returns:
+        -------
+            List of Milestone objects
+
+        """
+        logger = logging.getLogger(__name__)
+
+        # Validate credentials
+        is_valid, error_message = self.validate_credentials()
+        if not is_valid:
+            raise ValueError(error_message)
+
+        await self.initialize()
+        team_id = await self._ensure_team_id()
+
+        try:
+            result = await self.client.execute_query(
+                LIST_CYCLES_QUERY,
+                {"teamId": team_id, "first": 50, "after": None},
+            )
+
+            cycles = result.get("team", {}).get("cycles", {}).get("nodes", [])
+            milestones = [self._cycle_to_milestone(cycle) for cycle in cycles]
+
+            # Apply state filter if provided
+            if state:
+                milestones = [m for m in milestones if m.state == state]
+
+            logger.debug(f"Listed {len(milestones)} milestones (state={state})")
+            return milestones
+
+        except Exception as e:
+            logger.error(f"Failed to list milestones: {e}")
+            return []
+
+    async def milestone_update(
+        self,
+        milestone_id: str,
+        name: str | None = None,
+        target_date: datetime | None = None,
+        state: str | None = None,
+        labels: list[str] | None = None,
+        description: str | None = None,
+    ) -> Milestone | None:
+        """Update milestone properties.
+
+        Args:
+        ----
+            milestone_id: Milestone identifier
+            name: New name (optional)
+            target_date: New target date (optional)
+            state: New state (optional)
+            labels: New labels (optional, stored in metadata)
+            description: New description (optional)
+
+        Returns:
+        -------
+            Updated Milestone object, None if not found
+
+        """
+        logger = logging.getLogger(__name__)
+
+        # Validate credentials
+        is_valid, error_message = self.validate_credentials()
+        if not is_valid:
+            raise ValueError(error_message)
+
+        await self.initialize()
+
+        # Build update input
+        update_input = {}
+        if name:
+            update_input["name"] = name
+        if description is not None:
+            update_input["description"] = description
+        if target_date:
+            from datetime import timezone
+
+            # Ensure target_date has timezone
+            if target_date.tzinfo is None:
+                target_date = target_date.replace(tzinfo=timezone.utc)
+            update_input["endsAt"] = target_date.isoformat()
+        if state == "completed":
+            # Mark cycle as completed
+            from datetime import datetime, timezone
+
+            update_input["completedAt"] = datetime.now(timezone.utc).isoformat()
+
+        if not update_input:
+            # No updates provided, just return current milestone
+            return await self.milestone_get(milestone_id)
+
+        try:
+            result = await self.client.execute_query(
+                UPDATE_CYCLE_MUTATION,
+                {"id": milestone_id, "input": update_input},
+            )
+
+            if not result.get("cycleUpdate", {}).get("success"):
+                logger.warning(f"Failed to update cycle {milestone_id}")
+                return None
+
+            cycle_data = result["cycleUpdate"]["cycle"]
+            logger.info(f"Updated Linear cycle {milestone_id}")
+
+            return self._cycle_to_milestone(cycle_data, labels)
+
+        except Exception as e:
+            logger.error(f"Failed to update milestone {milestone_id}: {e}")
+            return None
+
+    async def milestone_delete(self, milestone_id: str) -> bool:
+        """Delete (archive) milestone.
+
+        Linear doesn't support permanent cycle deletion, so this archives the cycle.
+
+        Args:
+        ----
+            milestone_id: Milestone identifier
+
+        Returns:
+        -------
+            True if deleted successfully, False otherwise
+
+        """
+        logger = logging.getLogger(__name__)
+
+        # Validate credentials
+        is_valid, error_message = self.validate_credentials()
+        if not is_valid:
+            raise ValueError(error_message)
+
+        await self.initialize()
+
+        try:
+            result = await self.client.execute_query(
+                ARCHIVE_CYCLE_MUTATION, {"id": milestone_id}
+            )
+
+            success = result.get("cycleArchive", {}).get("success", False)
+            if success:
+                logger.info(f"Archived Linear cycle {milestone_id}")
+            else:
+                logger.warning(f"Failed to archive cycle {milestone_id}")
+
+            return success
+
+        except Exception as e:
+            logger.error(f"Failed to delete milestone {milestone_id}: {e}")
+            return False
+
+    async def milestone_get_issues(
+        self,
+        milestone_id: str,
+        state: str | None = None,
+    ) -> list[Task]:
+        """Get issues associated with milestone (cycle).
+
+        Args:
+        ----
+            milestone_id: Milestone identifier
+            state: Filter by issue state (optional)
+
+        Returns:
+        -------
+            List of Task objects in the milestone
+
+        """
+        logger = logging.getLogger(__name__)
+
+        # Validate credentials
+        is_valid, error_message = self.validate_credentials()
+        if not is_valid:
+            raise ValueError(error_message)
+
+        await self.initialize()
+
+        try:
+            result = await self.client.execute_query(
+                GET_CYCLE_ISSUES_QUERY, {"cycleId": milestone_id, "first": 100}
+            )
+
+            cycle_data = result.get("cycle")
+            if not cycle_data:
+                logger.warning(f"Cycle {milestone_id} not found")
+                return []
+
+            issues = cycle_data.get("issues", {}).get("nodes", [])
+
+            # Convert Linear issues to Task objects
+            tasks = [map_linear_issue_to_task(issue) for issue in issues]
+
+            # Filter by state if provided
+            if state:
+                state_filter = TicketState(state) if state else None
+                tasks = [t for t in tasks if t.state == state_filter]
+
+            logger.debug(f"Retrieved {len(tasks)} issues from milestone {milestone_id}")
+            return tasks
+
+        except Exception as e:
+            logger.error(f"Failed to get milestone issues {milestone_id}: {e}")
+            return []
+
+    def _cycle_to_milestone(
+        self,
+        cycle_data: dict[str, Any],
+        labels: list[str] | None = None,
+    ) -> Milestone:
+        """Convert Linear Cycle to universal Milestone model.
+
+        Determines state based on dates:
+        - completed: Has completedAt timestamp
+        - closed: Past end date without completion
+        - active: Current date between start and end
+        - open: Before start date
+
+        Args:
+        ----
+            cycle_data: Linear Cycle data from GraphQL
+            labels: Optional labels to associate with milestone
+
+        Returns:
+        -------
+            Milestone object
+
+        """
+        from datetime import datetime, timezone
+
+        # Determine state from dates
+        now = datetime.now(timezone.utc)
+
+        # Parse dates
+        starts_at_str = cycle_data.get("startsAt")
+        ends_at_str = cycle_data.get("endsAt")
+        completed_at_str = cycle_data.get("completedAt")
+
+        starts_at = (
+            datetime.fromisoformat(starts_at_str.replace("Z", "+00:00"))
+            if starts_at_str
+            else None
+        )
+        ends_at = (
+            datetime.fromisoformat(ends_at_str.replace("Z", "+00:00"))
+            if ends_at_str
+            else None
+        )
+        completed_at = (
+            datetime.fromisoformat(completed_at_str.replace("Z", "+00:00"))
+            if completed_at_str
+            else None
+        )
+
+        # Determine state
+        if completed_at:
+            state = "completed"
+        elif ends_at and now > ends_at:
+            state = "closed"  # Past due without completion
+        elif starts_at and ends_at and starts_at <= now <= ends_at:
+            state = "active"
+        else:
+            state = "open"  # Before start date
+
+        # Parse progress (Linear uses 0.0-1.0, we use 0-100)
+        progress = cycle_data.get("progress", 0.0)
+        progress_pct = progress * 100.0
+
+        return Milestone(
+            id=cycle_data["id"],
+            name=cycle_data["name"],
+            description=cycle_data.get("description", ""),
+            target_date=ends_at,
+            state=state,
+            labels=labels or [],
+            total_issues=cycle_data.get("issueCount", 0),
+            closed_issues=cycle_data.get("completedIssueCount", 0),
+            progress_pct=progress_pct,
+            created_at=None,  # Linear doesn't provide creation timestamp for cycles
+            updated_at=None,
+            platform_data={
+                "linear": {
+                    "cycle_id": cycle_data["id"],
+                    "starts_at": starts_at_str,
+                    "ends_at": ends_at_str,
+                    "completed_at": completed_at_str,
+                    "team": cycle_data.get("team"),
+                }
+            },
+        )
+
     async def close(self) -> None:
         """Close the adapter and clean up resources."""
         await self.client.close()