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

mcp_ticketer/adapters/{github.py → github/adapter.py}

@@ -1,163 +1,63 @@
 """GitHub adapter implementation using REST API v3 and GraphQL API v4."""
 
+from __future__ import annotations
+
 import builtins
 import logging
 import re
-from datetime import datetime
+from datetime import date, datetime
 from pathlib import Path
 from typing import Any
 
 import httpx
 
-from ..core.adapter import BaseAdapter
-from ..core.env_loader import load_adapter_config, validate_adapter_config
-from ..core.models import Comment, Epic, Priority, SearchQuery, Task, TicketState
-from ..core.registry import AdapterRegistry
+from ...cache.memory import MemoryCache
+from ...core.adapter import BaseAdapter
+from ...core.env_loader import load_adapter_config, validate_adapter_config
+from ...core.models import (
+    Comment,
+    Epic,
+    Milestone,
+    Priority,
+    Project,
+    ProjectScope,
+    ProjectState,
+    ProjectStatistics,
+    SearchQuery,
+    Task,
+    TicketState,
+)
+from ...core.registry import AdapterRegistry
+from .client import GitHubClient
+from .mappers import (
+    map_github_issue_to_task,
+    map_github_milestone_to_epic,
+    map_github_milestone_to_milestone,
+    map_github_projectv2_to_project,
+)
+from .queries import (
+    CREATE_PROJECT_MUTATION,
+    DELETE_PROJECT_MUTATION,
+    GET_PROJECT_BY_ID_QUERY,
+    GET_PROJECT_ITERATIONS,
+    GET_PROJECT_QUERY,
+    ISSUE_FRAGMENT,
+    LIST_PROJECTS_QUERY,
+    SEARCH_ISSUES,
+    UPDATE_PROJECT_MUTATION,
+)
+from .types import (
+    GitHubStateMapping,
+    extract_state_from_issue,
+    get_github_state,
+    get_priority_from_labels,
+    get_priority_label,
+    get_state_label,
+)
 
 logger = logging.getLogger(__name__)
 
 
-class GitHubStateMapping:
-    """GitHub issue states and label-based extended states."""
-
-    # GitHub native states
-    OPEN = "open"
-    CLOSED = "closed"
-
-    # Extended states via labels
-    STATE_LABELS = {
-        TicketState.IN_PROGRESS: "in-progress",
-        TicketState.READY: "ready",
-        TicketState.TESTED: "tested",
-        TicketState.WAITING: "waiting",
-        TicketState.BLOCKED: "blocked",
-    }
-
-    # Priority labels
-    PRIORITY_LABELS = {
-        Priority.CRITICAL: ["P0", "critical", "urgent"],
-        Priority.HIGH: ["P1", "high"],
-        Priority.MEDIUM: ["P2", "medium"],
-        Priority.LOW: ["P3", "low"],
-    }
-
-
-class GitHubGraphQLQueries:
-    """GraphQL queries for GitHub API v4."""
-
-    ISSUE_FRAGMENT = """
-        fragment IssueFields on Issue {
-            id
-            number
-            title
-            body
-            state
-            createdAt
-            updatedAt
-            url
-            author {
-                login
-            }
-            assignees(first: 10) {
-                nodes {
-                    login
-                    email
-                }
-            }
-            labels(first: 20) {
-                nodes {
-                    name
-                    color
-                }
-            }
-            milestone {
-                id
-                number
-                title
-                state
-                description
-            }
-            projectCards(first: 10) {
-                nodes {
-                    project {
-                        name
-                        url
-                    }
-                    column {
-                        name
-                    }
-                }
-            }
-            comments(first: 100) {
-                nodes {
-                    id
-                    body
-                    author {
-                        login
-                    }
-                    createdAt
-                }
-            }
-            reactions(first: 10) {
-                nodes {
-                    content
-                    user {
-                        login
-                    }
-                }
-            }
-        }
-    """
-
-    GET_ISSUE = """
-        query GetIssue($owner: String!, $repo: String!, $number: Int!) {
-            repository(owner: $owner, name: $repo) {
-                issue(number: $number) {
-                    ...IssueFields
-                }
-            }
-        }
-    """
-
-    SEARCH_ISSUES = """
-        query SearchIssues($query: String!, $first: Int!, $after: String) {
-            search(query: $query, type: ISSUE, first: $first, after: $after) {
-                issueCount
-                pageInfo {
-                    hasNextPage
-                    endCursor
-                }
-                nodes {
-                    ... on Issue {
-                        ...IssueFields
-                    }
-                }
-            }
-        }
-    """
-
-    GET_PROJECT_ITERATIONS = """
-        query GetProjectIterations($projectId: ID!, $first: Int!, $after: String) {
-            node(id: $projectId) {
-                ... on ProjectV2 {
-                    iterations(first: $first, after: $after) {
-                        nodes {
-                            id
-                            title
-                            startDate
-                            duration
-                        }
-                        pageInfo {
-                            hasNextPage
-                            endCursor
-                        }
-                    }
-                }
-            }
-        }
-    """
-
-
 class GitHubAdapter(BaseAdapter[Task]):
     """Adapter for GitHub Issues tracking system."""
 
@@ -173,6 +73,7 @@ class GitHubAdapter(BaseAdapter[Task]):
                 - api_url: Optional API URL for GitHub Enterprise
                 - use_projects_v2: Enable Projects v2 (default: False)
                 - custom_priority_scheme: Custom priority label mapping
+                - labels_ttl: Label cache TTL in seconds (default: 300.0)
 
         """
         super().__init__(config)
@@ -211,23 +112,25 @@ class GitHubAdapter(BaseAdapter[Task]):
         self.use_projects_v2 = config.get("use_projects_v2", False)
         self.custom_priority_scheme = config.get("custom_priority_scheme", {})
 
-        # HTTP client with authentication
-        self.headers = {
-            "Authorization": f"Bearer {self.token}",
-            "Accept": "application/vnd.github.v3+json",
-            "X-GitHub-Api-Version": "2022-11-28",
-        }
-
-        self.client = httpx.AsyncClient(
-            base_url=self.api_url,
-            headers=self.headers,
+        # Initialize GitHub API client
+        self.gh_client = GitHubClient(
+            token=self.token,
+            owner=self.owner,
+            repo=self.repo,
+            api_url=self.api_url,
             timeout=30.0,
         )
 
-        # Cache for labels and milestones
-        self._labels_cache: list[dict[str, Any]] | None = None
+        # Keep legacy client reference for backward compatibility
+        # TODO: Gradually migrate all direct self.client usage to self.gh_client
+        self.client = self.gh_client.client
+        self.headers = self.gh_client.headers
+        self.graphql_url = self.gh_client.graphql_url
+
+        # Initialize TTL-based cache
+        self._labels_ttl = config.get("labels_ttl", 300.0)  # 5 min default
+        self._labels_cache = MemoryCache(default_ttl=self._labels_ttl)
         self._milestones_cache: list[dict[str, Any]] | None = None
-        self._rate_limit: dict[str, Any] = {}
 
     def validate_credentials(self) -> tuple[bool, str]:
         """Validate that required credentials are present.
@@ -259,225 +162,48 @@ class GitHubAdapter(BaseAdapter[Task]):
         return True, ""
 
     def _get_state_mapping(self) -> dict[TicketState, str]:
-        """Map universal states to GitHub states."""
-        return {
-            TicketState.OPEN: GitHubStateMapping.OPEN,
-            TicketState.IN_PROGRESS: GitHubStateMapping.OPEN,  # with label
-            TicketState.READY: GitHubStateMapping.OPEN,  # with label
-            TicketState.TESTED: GitHubStateMapping.OPEN,  # with label
-            TicketState.DONE: GitHubStateMapping.CLOSED,
-            TicketState.WAITING: GitHubStateMapping.OPEN,  # with label
-            TicketState.BLOCKED: GitHubStateMapping.OPEN,  # with label
-            TicketState.CLOSED: GitHubStateMapping.CLOSED,
-        }
+        """Map universal states to GitHub states (delegated to types module)."""
+        return {state: get_github_state(state) for state in TicketState}
 
     def _get_state_label(self, state: TicketState) -> str | None:
-        """Get the label name for extended states."""
-        return GitHubStateMapping.STATE_LABELS.get(state)
+        """Get the label name for extended states (delegated to types module)."""
+        return get_state_label(state)
 
     def _get_priority_from_labels(self, labels: list[str]) -> Priority:
-        """Extract priority from issue labels."""
-        label_names = [label.lower() for label in labels]
-
-        # Check custom priority scheme first
-        if self.custom_priority_scheme:
-            for priority_str, label_patterns in self.custom_priority_scheme.items():
-                for pattern in label_patterns:
-                    if any(pattern.lower() in label for label in label_names):
-                        return Priority(priority_str)
-
-        # Check default priority labels
-        for priority, priority_labels in GitHubStateMapping.PRIORITY_LABELS.items():
-            for priority_label in priority_labels:
-                if priority_label.lower() in label_names:
-                    return priority
-
-        return Priority.MEDIUM
+        """Extract priority from issue labels (delegated to types module)."""
+        return get_priority_from_labels(labels, self.custom_priority_scheme)
 
     def _get_priority_label(self, priority: Priority) -> str:
-        """Get label name for a priority level."""
-        # Check custom scheme first
-        if self.custom_priority_scheme:
-            labels = self.custom_priority_scheme.get(priority.value, [])
-            if labels:
-                return labels[0]
-
-        # Use default labels
-        labels = GitHubStateMapping.PRIORITY_LABELS.get(priority, [])
-        return (
-            labels[0]
-            if labels
-            else f"P{['0', '1', '2', '3'][list(Priority).index(priority)]}"
-        )
+        """Get label name for a priority level (delegated to types module)."""
+        return get_priority_label(priority, self.custom_priority_scheme)
 
     def _milestone_to_epic(self, milestone: dict[str, Any]) -> Epic:
-        """Convert GitHub milestone to Epic model.
-
-        Args:
-        ----
-            milestone: GitHub milestone data
-
-        Returns:
-        -------
-            Epic instance
-
-        """
-        return Epic(
-            id=str(milestone["number"]),
-            title=milestone["title"],
-            description=milestone.get("description", ""),
-            state=(
-                TicketState.OPEN if milestone["state"] == "open" else TicketState.CLOSED
-            ),
-            created_at=datetime.fromisoformat(
-                milestone["created_at"].replace("Z", "+00:00")
-            ),
-            updated_at=datetime.fromisoformat(
-                milestone["updated_at"].replace("Z", "+00:00")
-            ),
-            metadata={
-                "github": {
-                    "number": milestone["number"],
-                    "url": milestone.get("html_url"),
-                    "open_issues": milestone.get("open_issues", 0),
-                    "closed_issues": milestone.get("closed_issues", 0),
-                }
-            },
-        )
+        """Convert GitHub milestone to Epic model (delegated to mappers module)."""
+        return map_github_milestone_to_epic(milestone)
 
     def _extract_state_from_issue(self, issue: dict[str, Any]) -> TicketState:
-        """Extract ticket state from GitHub issue data."""
-        # Check if closed
-        if issue["state"] == "closed":
-            return TicketState.CLOSED
-
-        # Check labels for extended states
-        labels = []
-        if "labels" in issue:
-            if isinstance(issue["labels"], list):
-                labels = [
-                    label.get("name", "") if isinstance(label, dict) else str(label)
-                    for label in issue["labels"]
-                ]
-            elif isinstance(issue["labels"], dict) and "nodes" in issue["labels"]:
-                labels = [label["name"] for label in issue["labels"]["nodes"]]
-
-        label_names = [label.lower() for label in labels]
-
-        # Check for extended state labels
-        for state, label_name in GitHubStateMapping.STATE_LABELS.items():
-            if label_name.lower() in label_names:
-                return state
-
-        return TicketState.OPEN
+        """Extract ticket state from GitHub issue data (delegated to types module)."""
+        return extract_state_from_issue(issue)
 
     def _task_from_github_issue(self, issue: dict[str, Any]) -> Task:
-        """Convert GitHub issue to universal Task."""
-        # Extract labels
-        labels = []
-        if "labels" in issue:
-            if isinstance(issue["labels"], list):
-                labels = [
-                    label.get("name", "") if isinstance(label, dict) else str(label)
-                    for label in issue["labels"]
-                ]
-            elif isinstance(issue["labels"], dict) and "nodes" in issue["labels"]:
-                labels = [label["name"] for label in issue["labels"]["nodes"]]
-
-        # Extract state
-        state = self._extract_state_from_issue(issue)
-
-        # Extract priority
-        priority = self._get_priority_from_labels(labels)
-
-        # Extract assignee
-        assignee = None
-        if "assignees" in issue:
-            if isinstance(issue["assignees"], list) and issue["assignees"]:
-                assignee = issue["assignees"][0].get("login")
-            elif isinstance(issue["assignees"], dict) and "nodes" in issue["assignees"]:
-                nodes = issue["assignees"]["nodes"]
-                if nodes:
-                    assignee = nodes[0].get("login")
-        elif "assignee" in issue and issue["assignee"]:
-            assignee = issue["assignee"].get("login")
-
-        # Extract parent epic (milestone)
-        parent_epic = None
-        if issue.get("milestone"):
-            parent_epic = str(issue["milestone"]["number"])
-
-        # Parse dates
-        created_at = None
-        if issue.get("created_at"):
-            created_at = datetime.fromisoformat(
-                issue["created_at"].replace("Z", "+00:00")
-            )
-        elif issue.get("createdAt"):
-            created_at = datetime.fromisoformat(
-                issue["createdAt"].replace("Z", "+00:00")
-            )
-
-        updated_at = None
-        if issue.get("updated_at"):
-            updated_at = datetime.fromisoformat(
-                issue["updated_at"].replace("Z", "+00:00")
-            )
-        elif issue.get("updatedAt"):
-            updated_at = datetime.fromisoformat(
-                issue["updatedAt"].replace("Z", "+00:00")
-            )
-
-        # Build metadata
-        metadata = {
-            "github": {
-                "number": issue.get("number"),
-                "url": issue.get("url") or issue.get("html_url"),
-                "author": (
-                    issue.get("user", {}).get("login")
-                    if "user" in issue
-                    else issue.get("author", {}).get("login")
-                ),
-                "labels": labels,
-            }
-        }
-
-        # Add projects v2 info if available
-        if "projectCards" in issue and issue["projectCards"].get("nodes"):
-            metadata["github"]["projects"] = [
-                {
-                    "name": card["project"]["name"],
-                    "column": card["column"]["name"],
-                    "url": card["project"]["url"],
-                }
-                for card in issue["projectCards"]["nodes"]
-            ]
-
-        return Task(
-            id=str(issue["number"]),
-            title=issue["title"],
-            description=issue.get("body") or issue.get("bodyText"),
-            state=state,
-            priority=priority,
-            tags=labels,
-            parent_epic=parent_epic,
-            assignee=assignee,
-            created_at=created_at,
-            updated_at=updated_at,
-            metadata=metadata,
-        )
+        """Convert GitHub issue to universal Task (delegated to mappers module)."""
+        return map_github_issue_to_task(issue, self.custom_priority_scheme)
 
     async def _ensure_label_exists(
         self, label_name: str, color: str = "0366d6"
     ) -> None:
         """Ensure a label exists in the repository."""
-        if not self._labels_cache:
+        cache_key = "github_labels"
+        cached_labels = await self._labels_cache.get(cache_key)
+
+        if cached_labels is None:
             response = await self.client.get(f"/repos/{self.owner}/{self.repo}/labels")
             response.raise_for_status()
-            self._labels_cache = response.json()
+            cached_labels = response.json()
+            await self._labels_cache.set(cache_key, cached_labels)
 
         # Check if label exists
-        existing_labels = [label["name"].lower() for label in self._labels_cache]
+        existing_labels = [label["name"].lower() for label in cached_labels]
         if label_name.lower() not in existing_labels:
             # Create the label
             response = await self.client.post(
@@ -485,7 +211,8 @@ class GitHubAdapter(BaseAdapter[Task]):
                 json={"name": label_name, "color": color},
             )
             if response.status_code == 201:
-                self._labels_cache.append(response.json())
+                cached_labels.append(response.json())
+                await self._labels_cache.set(cache_key, cached_labels)
 
     async def _graphql_request(
         self, query: str, variables: dict[str, Any]
@@ -898,9 +625,7 @@ class GitHubAdapter(BaseAdapter[Task]):
         github_query = " ".join(search_parts)
 
         # Use GraphQL for better search capabilities
-        full_query = (
-            GitHubGraphQLQueries.ISSUE_FRAGMENT + GitHubGraphQLQueries.SEARCH_ISSUES
-        )
+        full_query = ISSUE_FRAGMENT + SEARCH_ISSUES
 
         variables = {
             "query": github_query,
@@ -1449,8 +1174,10 @@ Fixes #{issue_number}
             List of label dictionaries with 'id', 'name', and 'color' fields
 
         """
-        if self._labels_cache:
-            return self._labels_cache
+        cache_key = "github_labels"
+        cached = await self._labels_cache.get(cache_key)
+        if cached is not None:
+            return cached
 
         response = await self.client.get(f"/repos/{self.owner}/{self.repo}/labels")
         response.raise_for_status()
@@ -1462,7 +1189,7 @@ Fixes #{issue_number}
             for label in labels
         ]
 
-        self._labels_cache = standardized_labels
+        await self._labels_cache.set(cache_key, standardized_labels)
         return standardized_labels
 
     async def update_milestone(
@@ -1769,7 +1496,7 @@ Fixes #{issue_number}
             )
 
         # Execute GraphQL query to fetch iterations
-        query = GitHubGraphQLQueries.GET_PROJECT_ITERATIONS
+        query = GET_PROJECT_ITERATIONS
         variables = {"projectId": project_id, "first": min(limit, 100), "after": None}
 
         try:
@@ -2079,6 +1806,1420 @@ Fixes #{issue_number}
         except httpx.HTTPError as e:
             raise ValueError(f"Failed to list project labels: {e}") from e
 
+    # ========================================================================
+    # New Milestone Methods (Phase 2 - GitHub Native Support)
+    # ========================================================================
+
+    async def milestone_create(
+        self,
+        name: str,
+        target_date: date | None = None,
+        labels: list[str] | None = None,
+        description: str = "",
+        project_id: str | None = None,
+    ) -> Milestone:
+        """Create milestone using GitHub Milestones API.
+
+        GitHub milestones are repository-scoped and natively supported.
+
+        Args:
+        ----
+            name: Milestone name/title
+            target_date: Target completion date (optional)
+            labels: Labels for local storage (GitHub doesn't store labels on milestones)
+            description: Milestone description
+            project_id: Project ID (ignored for GitHub, repo-scoped)
+
+        Returns:
+        -------
+            Created Milestone object
+
+        Raises:
+        ------
+            ValueError: If repository is not configured
+            httpx.HTTPError: If API request fails
+
+        """
+        from datetime import datetime as dt
+
+        if not self.repo:
+            raise ValueError("Repository required for GitHub milestone operations")
+
+        # GitHub API expects ISO 8601 datetime for due_on
+        due_on = None
+        if target_date:
+            due_on = dt.combine(target_date, dt.min.time()).isoformat() + "Z"
+
+        milestone_data = {
+            "title": name,
+            "description": description,
+            "state": "open",
+        }
+
+        if due_on:
+            milestone_data["due_on"] = due_on
+
+        # Create milestone via GitHub API
+        response = await self.client.post(
+            f"/repos/{self.owner}/{self.repo}/milestones",
+            json=milestone_data,
+        )
+        response.raise_for_status()
+
+        gh_milestone = response.json()
+
+        # Convert to Milestone model
+        milestone = self._github_milestone_to_milestone(gh_milestone, labels)
+
+        # Save to local storage for label tracking
+        from pathlib import Path
+
+        from ...core.milestone_manager import MilestoneManager
+
+        config_dir = Path.home() / ".mcp-ticketer"
+        manager = MilestoneManager(config_dir)
+        manager.save_milestone(milestone)
+
+        logger.info(f"Created GitHub milestone: {milestone.id} ({milestone.name})")
+        return milestone
+
+    async def milestone_get(self, milestone_id: str) -> Milestone | None:
+        """Get milestone by ID (milestone number in GitHub).
+
+        Args:
+        ----
+            milestone_id: Milestone number as string
+
+        Returns:
+        -------
+            Milestone object or None if not found
+
+        Raises:
+        ------
+            ValueError: If repository is not configured
+
+        """
+        from pathlib import Path
+
+        from ...core.milestone_manager import MilestoneManager
+
+        if not self.repo:
+            raise ValueError("Repository required for GitHub milestone operations")
+
+        try:
+            # milestone_id is the milestone number in GitHub
+            response = await self.client.get(
+                f"/repos/{self.owner}/{self.repo}/milestones/{milestone_id}"
+            )
+
+            if response.status_code == 404:
+                return None
+
+            response.raise_for_status()
+            gh_milestone = response.json()
+
+            # Load labels from local storage
+            config_dir = Path.home() / ".mcp-ticketer"
+            manager = MilestoneManager(config_dir)
+            local_milestone = manager.get_milestone(milestone_id)
+            labels = local_milestone.labels if local_milestone else []
+
+            return self._github_milestone_to_milestone(gh_milestone, labels)
+
+        except httpx.HTTPError as e:
+            logger.error(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 from GitHub repository.
+
+        Note: project_id is ignored for GitHub (repo-scoped).
+
+        Args:
+        ----
+            project_id: Project ID (ignored, GitHub is repo-scoped)
+            state: Filter by state (open, active, closed, completed)
+
+        Returns:
+        -------
+            List of Milestone objects
+
+        Raises:
+        ------
+            ValueError: If repository is not configured
+
+        """
+        from pathlib import Path
+
+        from ...core.milestone_manager import MilestoneManager
+
+        if not self.repo:
+            raise ValueError("Repository required for GitHub milestone operations")
+
+        # Map our states to GitHub states
+        github_state = "all"
+        if state in ["open", "active"]:
+            github_state = "open"
+        elif state in ["completed", "closed"]:
+            github_state = "closed"
+
+        params = {
+            "state": github_state,
+            "sort": "due_on",
+            "direction": "asc",
+            "per_page": 100,
+        }
+
+        response = await self.client.get(
+            f"/repos/{self.owner}/{self.repo}/milestones",
+            params=params,
+        )
+        response.raise_for_status()
+
+        # Load labels from local storage
+        config_dir = Path.home() / ".mcp-ticketer"
+        manager = MilestoneManager(config_dir)
+
+        milestones = []
+        for gh_milestone in response.json():
+            milestone_id = str(gh_milestone["number"])
+            local_milestone = manager.get_milestone(milestone_id)
+            labels = local_milestone.labels if local_milestone else []
+
+            milestone = self._github_milestone_to_milestone(gh_milestone, labels)
+            milestones.append(milestone)
+
+        logger.info(
+            f"Listed {len(milestones)} GitHub milestones (state={github_state})"
+        )
+        return milestones
+
+    async def milestone_update(
+        self,
+        milestone_id: str,
+        name: str | None = None,
+        target_date: date | None = None,
+        state: str | None = None,
+        labels: list[str] | None = None,
+        description: str | None = None,
+    ) -> Milestone | None:
+        """Update milestone properties.
+
+        Args:
+        ----
+            milestone_id: Milestone number as string
+            name: New milestone name
+            target_date: New target date
+            state: New state (open, closed)
+            labels: New labels (stored locally)
+            description: New description
+
+        Returns:
+        -------
+            Updated Milestone object or None if not found
+
+        Raises:
+        ------
+            ValueError: If repository is not configured
+
+        """
+        from datetime import datetime as dt
+        from pathlib import Path
+
+        from ...core.milestone_manager import MilestoneManager
+
+        if not self.repo:
+            raise ValueError("Repository required for GitHub milestone operations")
+
+        update_data = {}
+
+        if name:
+            update_data["title"] = name
+        if description is not None:
+            update_data["description"] = description
+        if target_date:
+            due_on = dt.combine(target_date, dt.min.time()).isoformat() + "Z"
+            update_data["due_on"] = due_on
+        if state:
+            # Map our states to GitHub states
+            if state in ["completed", "closed"]:
+                update_data["state"] = "closed"
+            elif state in ["open", "active"]:
+                update_data["state"] = "open"
+
+        if not update_data and labels is None:
+            raise ValueError("At least one field must be updated")
+
+        # Update milestone via GitHub API
+        if update_data:
+            response = await self.client.patch(
+                f"/repos/{self.owner}/{self.repo}/milestones/{milestone_id}",
+                json=update_data,
+            )
+            response.raise_for_status()
+            gh_milestone = response.json()
+        else:
+            # Only labels updated, fetch current milestone
+            response = await self.client.get(
+                f"/repos/{self.owner}/{self.repo}/milestones/{milestone_id}"
+            )
+            response.raise_for_status()
+            gh_milestone = response.json()
+
+        # Update labels in local storage
+        config_dir = Path.home() / ".mcp-ticketer"
+        manager = MilestoneManager(config_dir)
+
+        if labels is not None:
+            milestone = self._github_milestone_to_milestone(gh_milestone, labels)
+            manager.save_milestone(milestone)
+            logger.info(f"Updated GitHub milestone: {milestone_id} (including labels)")
+            return milestone
+
+        # Load existing labels
+        local_milestone = manager.get_milestone(milestone_id)
+        existing_labels = local_milestone.labels if local_milestone else []
+
+        milestone = self._github_milestone_to_milestone(gh_milestone, existing_labels)
+        logger.info(f"Updated GitHub milestone: {milestone_id}")
+        return milestone
+
+    async def milestone_delete(self, milestone_id: str) -> bool:
+        """Delete milestone from GitHub repository.
+
+        Args:
+        ----
+            milestone_id: Milestone number as string
+
+        Returns:
+        -------
+            True if deleted, False if not found
+
+        Raises:
+        ------
+            ValueError: If repository is not configured
+
+        """
+        from pathlib import Path
+
+        from ...core.milestone_manager import MilestoneManager
+
+        if not self.repo:
+            raise ValueError("Repository required for GitHub milestone operations")
+
+        try:
+            response = await self.client.delete(
+                f"/repos/{self.owner}/{self.repo}/milestones/{milestone_id}"
+            )
+
+            # GitHub returns 204 No Content on successful deletion
+            if response.status_code == 204:
+                # Remove from local storage
+                config_dir = Path.home() / ".mcp-ticketer"
+                manager = MilestoneManager(config_dir)
+                manager.delete_milestone(milestone_id)
+
+                logger.info(f"Deleted GitHub milestone: {milestone_id}")
+                return True
+
+            # Handle 404 errors gracefully
+            if response.status_code == 404:
+                logger.warning(f"Milestone {milestone_id} not found for deletion")
+                return False
+
+            response.raise_for_status()
+            return True
+
+        except httpx.HTTPError 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[dict[str, Any]]:
+        """Get issues in milestone.
+
+        Args:
+        ----
+            milestone_id: Milestone number as string
+            state: Filter by state (open, closed, all)
+
+        Returns:
+        -------
+            List of issue dictionaries
+
+        Raises:
+        ------
+            ValueError: If repository is not configured
+
+        """
+        if not self.repo:
+            raise ValueError("Repository required for GitHub milestone operations")
+
+        params = {
+            "milestone": milestone_id,
+            "state": state or "all",
+            "per_page": 100,
+        }
+
+        response = await self.client.get(
+            f"/repos/{self.owner}/{self.repo}/issues",
+            params=params,
+        )
+        response.raise_for_status()
+
+        # Convert GitHub issues to our format
+        issues = []
+        for gh_issue in response.json():
+            # Skip pull requests (GitHub includes them in issues endpoint)
+            if "pull_request" in gh_issue:
+                continue
+
+            issues.append(
+                {
+                    "id": str(gh_issue["number"]),
+                    "identifier": f"#{gh_issue['number']}",
+                    "title": gh_issue["title"],
+                    "state": gh_issue["state"],
+                    "labels": [label["name"] for label in gh_issue.get("labels", [])],
+                    "created_at": gh_issue["created_at"],
+                    "updated_at": gh_issue["updated_at"],
+                }
+            )
+
+        logger.info(f"Retrieved {len(issues)} issues from milestone {milestone_id}")
+        return issues
+
+    def _github_milestone_to_milestone(
+        self,
+        gh_milestone: dict[str, Any],
+        labels: list[str] | None = None,
+    ) -> Milestone:
+        """Convert GitHub Milestone to universal Milestone model (delegated to mappers module)."""
+        return map_github_milestone_to_milestone(gh_milestone, self.repo, labels)
+
+    # =============================================================================
+    # GitHub Projects V2 Operations (Week 2: Core CRUD)
+    # =============================================================================
+
+    async def project_list(
+        self,
+        owner: str | None = None,
+        scope: ProjectScope = ProjectScope.ORGANIZATION,
+        state: ProjectState | None = None,
+        limit: int = 10,
+        cursor: str | None = None,
+    ) -> list[Project]:
+        """List projects for an organization or user.
+
+        Args:
+        ----
+            owner: Organization or user login (defaults to configured owner)
+            scope: Project scope (ORGANIZATION or USER)
+            state: Filter by project state (ACTIVE, COMPLETED, ARCHIVED)
+            limit: Maximum number of projects to return (default: 10)
+            cursor: Pagination cursor for next page
+
+        Returns:
+        -------
+            List of Project objects
+
+        Raises:
+        ------
+            ValueError: If owner not provided and not configured
+            RuntimeError: If GraphQL query fails
+
+        Example:
+        -------
+            projects = await adapter.project_list(owner="myorg", limit=20)
+
+        """
+        # Validate owner (use self.owner if not provided)
+        owner = owner or self.owner
+        if not owner:
+            raise ValueError("Owner required for GitHub project operations")
+
+        # Build GraphQL variables
+        variables = {
+            "owner": owner,
+            "first": limit,
+            "after": cursor,
+        }
+
+        try:
+            # Execute LIST_PROJECTS_QUERY
+            data = await self.gh_client.execute_graphql(
+                query=LIST_PROJECTS_QUERY,
+                variables=variables,
+            )
+
+            # Parse response and extract projects array
+            org_data = data.get("organization")
+            if not org_data:
+                logger.warning(f"Organization {owner} not found")
+                return []
+
+            projects_data = org_data.get("projectsV2", {})
+            project_nodes = projects_data.get("nodes", [])
+
+            # Map each project using mapper
+            projects = []
+            for project_data in project_nodes:
+                project = map_github_projectv2_to_project(project_data, owner)
+
+                # Filter by state if provided (post-query filtering)
+                if state is None or project.state == state:
+                    projects.append(project)
+
+            logger.info(f"Retrieved {len(projects)} projects for {owner}")
+            return projects
+
+        except Exception as e:
+            logger.error(f"Failed to list projects for {owner}: {e}")
+            raise RuntimeError(f"Failed to list projects: {e}") from e
+
+    async def project_get(
+        self,
+        project_id: str,
+        owner: str | None = None,
+    ) -> Project | None:
+        """Get a single project by ID or number.
+
+        Automatically detects ID format:
+        - Node ID format: "PVT_kwDOABCD..." (starts with PVT_)
+        - Number format: "123" (numeric string)
+
+        Args:
+        ----
+            project_id: Project node ID or number
+            owner: Organization or user login (defaults to configured owner)
+
+        Returns:
+        -------
+            Project object if found, None otherwise
+
+        Raises:
+        ------
+            ValueError: If owner not provided for number-based lookup
+            RuntimeError: If GraphQL query fails
+
+        Example:
+        -------
+            # By number
+            project = await adapter.project_get("42", owner="myorg")
+
+            # By node ID
+            project = await adapter.project_get("PVT_kwDOABCD1234")
+
+        """
+        try:
+            # Auto-detect ID format
+            if project_id.startswith("PVT_"):
+                # Use GET_PROJECT_BY_ID_QUERY for node IDs
+                data = await self.gh_client.execute_graphql(
+                    query=GET_PROJECT_BY_ID_QUERY,
+                    variables={"projectId": project_id},
+                )
+
+                project_data = data.get("node")
+                if not project_data:
+                    logger.warning(f"Project {project_id} not found")
+                    return None
+
+                # Extract owner from project data
+                owner_data = project_data.get("owner", {})
+                owner_login = owner_data.get("login", owner or self.owner)
+
+                project = map_github_projectv2_to_project(project_data, owner_login)
+                logger.info(f"Retrieved project {project_id} by node ID")
+                return project
+
+            else:
+                # Numeric ID - requires owner
+                owner = owner or self.owner
+                if not owner:
+                    raise ValueError("Owner required for number-based project lookup")
+
+                # Convert to integer
+                try:
+                    project_number = int(project_id)
+                except ValueError as e:
+                    raise ValueError(f"Invalid project ID format: {project_id}") from e
+
+                # Use GET_PROJECT_QUERY for number-based lookup
+                data = await self.gh_client.execute_graphql(
+                    query=GET_PROJECT_QUERY,
+                    variables={"owner": owner, "number": project_number},
+                )
+
+                org_data = data.get("organization")
+                if not org_data:
+                    logger.warning(f"Organization {owner} not found")
+                    return None
+
+                project_data = org_data.get("projectV2")
+                if not project_data:
+                    logger.warning(f"Project {project_id} not found for {owner}")
+                    return None
+
+                project = map_github_projectv2_to_project(project_data, owner)
+                logger.info(f"Retrieved project {project_id} by number")
+                return project
+
+        except Exception as e:
+            logger.error(f"Failed to get project {project_id}: {e}")
+            raise RuntimeError(f"Failed to get project: {e}") from e
+
+    async def project_create(
+        self,
+        title: str,
+        description: str | None = None,
+        owner: str | None = None,
+        scope: ProjectScope = ProjectScope.ORGANIZATION,
+    ) -> Project:
+        """Create a new GitHub Projects V2 project.
+
+        Args:
+        ----
+            title: Project title (required)
+            description: Project description (optional)
+            owner: Organization or user login (defaults to configured owner)
+            scope: Project scope (ORGANIZATION or USER)
+
+        Returns:
+        -------
+            Newly created Project object
+
+        Raises:
+        ------
+            ValueError: If owner not provided
+            RuntimeError: If creation fails (permissions, etc.)
+
+        Example:
+        -------
+            project = await adapter.project_create(
+                title="Q4 Features",
+                description="New features for Q4 2025",
+                owner="myorg"
+            )
+
+        """
+        # Validate owner
+        owner = owner or self.owner
+        if not owner:
+            raise ValueError("Owner required for GitHub project creation")
+
+        try:
+            # Get owner node ID (query organization)
+            # We need to fetch the organization/user to get its node ID
+            org_query = """
+                query GetOrgId($login: String!) {
+                    organization(login: $login) {
+                        id
+                    }
+                }
+            """
+
+            org_data = await self.gh_client.execute_graphql(
+                query=org_query,
+                variables={"login": owner},
+            )
+
+            org = org_data.get("organization")
+            if not org:
+                raise ValueError(f"Organization {owner} not found")
+
+            owner_id = org.get("id")
+
+            # Execute CREATE_PROJECT_MUTATION
+            data = await self.gh_client.execute_graphql(
+                query=CREATE_PROJECT_MUTATION,
+                variables={
+                    "ownerId": owner_id,
+                    "title": title,
+                },
+            )
+
+            # Parse response and extract created project
+            create_result = data.get("createProjectV2", {})
+            project_data = create_result.get("projectV2")
+
+            if not project_data:
+                raise RuntimeError("Project creation returned no data")
+
+            # Map using mapper
+            project = map_github_projectv2_to_project(project_data, owner)
+
+            # Update description if provided (requires separate mutation)
+            if description:
+                await self.project_update(
+                    project_id=project.id,
+                    description=description,
+                )
+
+            logger.info(f"Created project: {project.id} ({title})")
+            return project
+
+        except Exception as e:
+            logger.error(f"Failed to create project '{title}': {e}")
+            raise RuntimeError(f"Failed to create project: {e}") from e
+
+    async def project_update(
+        self,
+        project_id: str,
+        title: str | None = None,
+        description: str | None = None,
+        readme: str | None = None,
+        state: ProjectState | None = None,
+    ) -> Project | None:
+        """Update project metadata.
+
+        Supports partial updates - only provided fields are updated.
+
+        Args:
+        ----
+            project_id: Project node ID (PVT_...)
+            title: New project title (optional)
+            description: New project description (optional)
+            readme: New project readme (optional)
+            state: New project state (optional)
+
+        Returns:
+        -------
+            Updated Project object
+
+        Raises:
+        ------
+            ValueError: If project_id invalid or no fields to update
+            RuntimeError: If update fails
+
+        Example:
+        -------
+            project = await adapter.project_update(
+                project_id="PVT_kwDOABCD1234",
+                title="Updated Title",
+                state=ProjectState.COMPLETED
+            )
+
+        """
+        # Validate at least one field is provided
+        if not any([title, description, readme, state]):
+            raise ValueError("At least one field must be provided for update")
+
+        try:
+            # Build mutation variables (only include provided fields)
+            variables: dict[str, Any] = {"projectId": project_id}
+
+            if title is not None:
+                variables["title"] = title
+
+            if description is not None:
+                variables["shortDescription"] = description
+
+            if readme is not None:
+                variables["readme"] = readme
+
+            # Convert ProjectState to GitHub boolean
+            if state is not None:
+                # GitHub only has open/closed via the 'closed' boolean
+                if state in (ProjectState.COMPLETED, ProjectState.ARCHIVED):
+                    variables["closed"] = True
+                elif state == ProjectState.ACTIVE:
+                    variables["closed"] = False
+                # PLANNED and CANCELLED don't have direct mappings
+                # We'll keep the project open for PLANNED
+
+            # Execute UPDATE_PROJECT_MUTATION
+            data = await self.gh_client.execute_graphql(
+                query=UPDATE_PROJECT_MUTATION,
+                variables=variables,
+            )
+
+            # Parse response
+            update_result = data.get("updateProjectV2", {})
+            project_data = update_result.get("projectV2")
+
+            if not project_data:
+                logger.warning(f"Project {project_id} not found for update")
+                return None
+
+            # Extract owner from project data
+            owner_data = project_data.get("owner", {})
+            owner = owner_data.get("login", self.owner)
+
+            # Map using mapper
+            project = map_github_projectv2_to_project(project_data, owner)
+
+            logger.info(f"Updated project: {project_id}")
+            return project
+
+        except Exception as e:
+            logger.error(f"Failed to update project {project_id}: {e}")
+            raise RuntimeError(f"Failed to update project: {e}") from e
+
+    async def project_delete(
+        self,
+        project_id: str,
+        hard_delete: bool = False,
+    ) -> bool:
+        """Delete a project.
+
+        By default performs soft delete (closes project).
+        Set hard_delete=True to permanently delete.
+
+        Args:
+        ----
+            project_id: Project node ID (PVT_...)
+            hard_delete: If True, permanently delete; if False, soft delete (close)
+
+        Returns:
+        -------
+            True if successful, False otherwise
+
+        Raises:
+        ------
+            RuntimeError: If deletion fails
+
+        Example:
+        -------
+            # Soft delete (close)
+            await adapter.project_delete("PVT_kwDOABCD1234")
+
+            # Hard delete (permanent)
+            await adapter.project_delete("PVT_kwDOABCD1234", hard_delete=True)
+
+        """
+        try:
+            if hard_delete:
+                # Hard delete using DELETE_PROJECT_MUTATION
+                logger.warning(f"Permanently deleting project {project_id}")
+
+                data = await self.gh_client.execute_graphql(
+                    query=DELETE_PROJECT_MUTATION,
+                    variables={"projectId": project_id},
+                )
+
+                delete_result = data.get("deleteProjectV2", {})
+                deleted_project = delete_result.get("projectV2")
+
+                if deleted_project:
+                    logger.info(f"Permanently deleted project: {project_id}")
+                    return True
+                else:
+                    logger.warning(f"Failed to delete project {project_id}")
+                    return False
+
+            else:
+                # Soft delete by setting public=false and closed=true
+                data = await self.gh_client.execute_graphql(
+                    query=UPDATE_PROJECT_MUTATION,
+                    variables={
+                        "projectId": project_id,
+                        "public": False,
+                        "closed": True,
+                    },
+                )
+
+                update_result = data.get("updateProjectV2", {})
+                updated_project = update_result.get("projectV2")
+
+                if updated_project:
+                    logger.info(f"Soft deleted (closed) project: {project_id}")
+                    return True
+                else:
+                    logger.warning(f"Failed to close project {project_id}")
+                    return False
+
+        except Exception as e:
+            logger.error(f"Failed to delete project {project_id}: {e}")
+            raise RuntimeError(f"Failed to delete project: {e}") from e
+
+    async def invalidate_label_cache(self) -> None:
+        """Manually invalidate the label cache.
+
+        Useful when labels are modified externally or when you need
+        to force a refresh of cached label data.
+        """
+        await self._labels_cache.clear()
+
+    # =============================================================================
+    # GitHub Projects V2 Issue Operations (Week 3)
+    # =============================================================================
+
+    async def project_add_issue(
+        self,
+        project_id: str,
+        issue_id: str,
+    ) -> bool:
+        """Add an issue to a GitHub Projects V2 project.
+
+        Args:
+        ----
+            project_id: Project node ID (PVT_kwDOABCD...)
+            issue_id: Issue node ID (I_kwDOABCD...) or issue number with owner/repo
+
+        Returns:
+        -------
+            True if issue was added successfully
+
+        Raises:
+        ------
+            ValueError: If project_id or issue_id is invalid
+            RuntimeError: If GraphQL mutation fails
+
+        Example:
+        -------
+            # Add by issue node ID
+            success = await adapter.project_add_issue(
+                project_id="PVT_kwDOABCD1234",
+                issue_id="I_kwDOABCD5678"
+            )
+
+            # Add by issue number (requires owner/repo context)
+            success = await adapter.project_add_issue(
+                project_id="PVT_kwDOABCD1234",
+                issue_id="owner/repo#123"
+            )
+
+        Note:
+        ----
+            GitHub's addProjectV2ItemById mutation requires:
+            - projectId: Project node ID
+            - contentId: Issue/PR node ID (not item ID)
+
+        """
+        # Validate project_id format
+        if not project_id or not project_id.startswith("PVT_"):
+            raise ValueError(
+                f"Invalid project_id: {project_id}. "
+                "Project ID must start with 'PVT_' (e.g., PVT_kwDOABCD1234)"
+            )
+
+        # Validate issue_id is provided
+        if not issue_id:
+            raise ValueError("issue_id is required")
+
+        # If issue_id is in "owner/repo#number" format, resolve to node ID
+        content_id = issue_id
+        if "#" in issue_id and "/" in issue_id:
+            # Parse owner/repo#number format
+            try:
+                repo_part, number_str = issue_id.rsplit("#", 1)
+                owner, repo = repo_part.split("/")
+                issue_number = int(number_str)
+
+                # Query GitHub to get issue node ID
+                issue_query = """
+                    query GetIssueNodeId($owner: String!, $repo: String!, $number: Int!) {
+                        repository(owner: $owner, name: $repo) {
+                            issue(number: $number) {
+                                id
+                            }
+                        }
+                    }
+                """
+
+                result = await self._graphql_request(
+                    issue_query,
+                    {"owner": owner, "repo": repo, "number": issue_number},
+                )
+
+                repo_data = result.get("repository")
+                if not repo_data:
+                    raise ValueError(f"Repository {owner}/{repo} not found")
+
+                issue_data = repo_data.get("issue")
+                if not issue_data:
+                    raise ValueError(
+                        f"Issue #{issue_number} not found in {owner}/{repo}"
+                    )
+
+                content_id = issue_data["id"]
+                logger.debug(f"Resolved issue {issue_id} to node ID {content_id}")
+
+            except ValueError:
+                # Re-raise ValueError as-is (already has good message)
+                raise
+            except (KeyError, TypeError) as e:
+                raise ValueError(
+                    f"Invalid issue_id format: {issue_id}. "
+                    "Expected 'owner/repo#number' or issue node ID (I_kwDO...)"
+                ) from e
+
+        # Validate issue node ID format
+        if not content_id.startswith("I_") and not content_id.startswith("PR_"):
+            raise ValueError(
+                f"Invalid issue_id: {content_id}. "
+                "Issue ID must start with 'I_' or 'PR_' (e.g., I_kwDOABCD5678)"
+            )
+
+        try:
+            # Execute ADD_PROJECT_ITEM_MUTATION
+            from .queries import ADD_PROJECT_ITEM_MUTATION
+
+            data = await self.gh_client.execute_graphql(
+                query=ADD_PROJECT_ITEM_MUTATION,
+                variables={
+                    "projectId": project_id,
+                    "contentId": content_id,
+                },
+            )
+
+            # Check for successful addition
+            add_result = data.get("addProjectV2ItemById", {})
+            item_data = add_result.get("item")
+
+            if item_data:
+                logger.info(
+                    f"Successfully added issue {issue_id} to project {project_id}"
+                )
+                return True
+            else:
+                logger.warning(
+                    f"Failed to add issue {issue_id} to project {project_id}: No item returned"
+                )
+                return False
+
+        except Exception as e:
+            error_msg = str(e).lower()
+
+            # Handle "already exists" errors gracefully
+            if "already exists" in error_msg or "duplicate" in error_msg:
+                logger.info(f"Issue {issue_id} already exists in project {project_id}")
+                return True
+
+            # Log and re-raise other errors
+            logger.error(f"Failed to add issue {issue_id} to project {project_id}: {e}")
+            raise RuntimeError(f"Failed to add issue to project: {e}") from e
+
+    async def project_remove_issue(
+        self,
+        project_id: str,
+        item_id: str,
+    ) -> bool:
+        """Remove an issue from a GitHub Projects V2 project.
+
+        Args:
+        ----
+            project_id: Project node ID (PVT_kwDOABCD...)
+            item_id: Project item ID (PVTI_kwDOABCD...) NOT issue ID
+
+        Returns:
+        -------
+            True if issue was removed successfully
+
+        Raises:
+        ------
+            ValueError: If project_id or item_id is invalid
+            RuntimeError: If GraphQL mutation fails
+
+        Example:
+        -------
+            success = await adapter.project_remove_issue(
+                project_id="PVT_kwDOABCD1234",
+                item_id="PVTI_kwDOABCD5678"
+            )
+
+        Note:
+        ----
+            Requires the project ITEM ID (PVTI_*), not the issue ID (I_*).
+            Use project_get_issues() to find the item ID for an issue.
+
+        """
+        # Validate project_id format
+        if not project_id or not project_id.startswith("PVT_"):
+            raise ValueError(
+                f"Invalid project_id: {project_id}. "
+                "Project ID must start with 'PVT_' (e.g., PVT_kwDOABCD1234)"
+            )
+
+        # Validate item_id format
+        if not item_id or not item_id.startswith("PVTI_"):
+            raise ValueError(
+                f"Invalid item_id: {item_id}. "
+                "Item ID must start with 'PVTI_' (e.g., PVTI_kwDOABCD5678). "
+                "Note: This is the project item ID, not the issue ID. "
+                "Use project_get_issues() to get the item ID for an issue."
+            )
+
+        try:
+            # Execute REMOVE_PROJECT_ITEM_MUTATION
+            from .queries import REMOVE_PROJECT_ITEM_MUTATION
+
+            data = await self.gh_client.execute_graphql(
+                query=REMOVE_PROJECT_ITEM_MUTATION,
+                variables={
+                    "projectId": project_id,
+                    "itemId": item_id,
+                },
+            )
+
+            # Check for successful removal
+            delete_result = data.get("deleteProjectV2Item", {})
+            deleted_item_id = delete_result.get("deletedItemId")
+
+            if deleted_item_id:
+                logger.info(
+                    f"Successfully removed item {item_id} from project {project_id}"
+                )
+                return True
+            else:
+                logger.warning(
+                    f"Failed to remove item {item_id} from project {project_id}: "
+                    "No deleted item ID returned"
+                )
+                return False
+
+        except Exception as e:
+            error_msg = str(e).lower()
+
+            # Handle "not found" errors gracefully
+            if "not found" in error_msg or "does not exist" in error_msg:
+                logger.warning(
+                    f"Item {item_id} not found in project {project_id} "
+                    "(may have been already removed)"
+                )
+                return False
+
+            # Log and re-raise other errors
+            logger.error(
+                f"Failed to remove item {item_id} from project {project_id}: {e}"
+            )
+            raise RuntimeError(f"Failed to remove issue from project: {e}") from e
+
+    async def project_get_issues(
+        self,
+        project_id: str,
+        state: str | None = None,
+        limit: int = 10,
+        cursor: str | None = None,
+    ) -> list[Task]:
+        """Get issues in a GitHub Projects V2 project.
+
+        Args:
+        ----
+            project_id: Project node ID (PVT_kwDOABCD...)
+            state: Filter by issue state ("OPEN", "CLOSED", None for all)
+            limit: Maximum number of issues to return (default 10)
+            cursor: Pagination cursor for next page
+
+        Returns:
+        -------
+            List of Task objects representing issues in the project
+
+        Raises:
+        ------
+            ValueError: If project_id is invalid
+            RuntimeError: If GraphQL query fails
+
+        Example:
+        -------
+            # Get all open issues
+            issues = await adapter.project_get_issues(
+                project_id="PVT_kwDOABCD1234",
+                state="OPEN",
+                limit=20
+            )
+
+            # Get next page
+            issues = await adapter.project_get_issues(
+                project_id="PVT_kwDOABCD1234",
+                cursor=last_cursor
+            )
+
+        Note:
+        ----
+            Returns Task objects with additional project context:
+            - task.metadata["project_item_id"]: ID for removal operations
+            - task.metadata["project_number"]: Project number
+
+        """
+        # Validate project_id format
+        if not project_id or not project_id.startswith("PVT_"):
+            raise ValueError(
+                f"Invalid project_id: {project_id}. "
+                "Project ID must start with 'PVT_' (e.g., PVT_kwDOABCD1234)"
+            )
+
+        try:
+            # Execute PROJECT_ITEMS_QUERY
+            from .queries import PROJECT_ITEMS_QUERY
+
+            data = await self.gh_client.execute_graphql(
+                query=PROJECT_ITEMS_QUERY,
+                variables={
+                    "projectId": project_id,
+                    "first": limit,
+                    "after": cursor,
+                },
+            )
+
+            # Parse response and extract items array
+            project_node = data.get("node")
+            if not project_node:
+                logger.warning(f"Project {project_id} not found")
+                return []
+
+            items_data = project_node.get("items", {})
+            item_nodes = items_data.get("nodes", [])
+
+            # Filter items by content type (only "Issue", skip "PullRequest", "DraftIssue")
+            tasks = []
+            for item in item_nodes:
+                content = item.get("content")
+                if not content:
+                    # Skip archived items without content
+                    logger.debug(f"Skipping item {item.get('id')} without content")
+                    continue
+
+                content_type = content.get("__typename")
+
+                # Only process Issues
+                if content_type != "Issue":
+                    logger.debug(f"Skipping {content_type} item {item.get('id')}")
+                    continue
+
+                # Map GitHub issue to Task using existing mapper
+                from .mappers import map_github_issue_to_task
+
+                # Convert GraphQL format to format expected by mapper
+                issue_dict = {
+                    "number": content.get("number"),
+                    "title": content.get("title"),
+                    "state": content.get("state", "").lower(),
+                    "labels": content.get("labels", {}),
+                    # Note: PROJECT_ITEMS_QUERY doesn't include all issue fields
+                    # Only basic fields are available
+                }
+
+                task = map_github_issue_to_task(issue_dict, self.custom_priority_scheme)
+
+                # Add project context to metadata
+                if "github" not in task.metadata:
+                    task.metadata["github"] = {}
+
+                task.metadata["github"]["project_item_id"] = item["id"]
+                task.metadata["github"]["project_id"] = project_id
+
+                # Extract project number from project_id if needed
+                # Project node ID format: PVT_kwDO... but we don't have number here
+                # We'll need to query the project separately or store it
+
+                tasks.append(task)
+
+            # Filter by state if provided (post-query filtering)
+            if state:
+                state_lower = state.lower()
+                tasks = [
+                    task
+                    for task in tasks
+                    if (isinstance(task.state, str) and task.state == state_lower)
+                    or (
+                        hasattr(task.state, "value") and task.state.value == state_lower
+                    )
+                    or (
+                        state_lower == "open"
+                        and (
+                            (
+                                isinstance(task.state, str)
+                                and task.state
+                                in ["open", "in_progress", "blocked", "waiting"]
+                            )
+                            or (
+                                hasattr(task.state, "value")
+                                and task.state.value
+                                in ["open", "in_progress", "blocked", "waiting"]
+                            )
+                        )
+                    )
+                    or (
+                        state_lower == "closed"
+                        and (
+                            (
+                                isinstance(task.state, str)
+                                and task.state in ["done", "closed"]
+                            )
+                            or (
+                                hasattr(task.state, "value")
+                                and task.state.value in ["done", "closed"]
+                            )
+                        )
+                    )
+                ]
+
+            logger.info(
+                f"Retrieved {len(tasks)} issues from project {project_id} "
+                f"(filtered by state={state})"
+            )
+
+            return tasks
+
+        except Exception as e:
+            logger.error(f"Failed to get issues from project {project_id}: {e}")
+            raise RuntimeError(f"Failed to get project issues: {e}") from e
+
+    async def project_get_statistics(
+        self,
+        project_id: str,
+    ) -> ProjectStatistics:
+        """Get comprehensive statistics for a GitHub Projects V2 project.
+
+        Calculates issue state breakdown, priority distribution, and health status
+        by analyzing all issues in the project. Priority is determined from issue
+        labels (priority:low, priority/medium, etc.), and blocked status is detected
+        from "blocked" or "blocker" labels.
+
+        Health Scoring Logic:
+            - on_track: >70% complete AND <10% blocked
+            - at_risk: >40% complete AND <30% blocked
+            - off_track: Otherwise (low completion or high blocked rate)
+
+        Args:
+        ----
+            project_id: Project node ID (PVT_kwDOABCD...)
+
+        Returns:
+        -------
+            ProjectStatistics with metrics and health scoring
+
+        Raises:
+        ------
+            ValueError: If project_id is invalid format
+            RuntimeError: If statistics calculation fails
+
+        Example:
+        -------
+            stats = await adapter.project_get_statistics("PVT_kwDOABCD1234")
+            print(f"Health: {stats.health}, Progress: {stats.progress_percentage}%")
+            print(f"Priority breakdown: H={stats.priority_high_count}, "
+                  f"M={stats.priority_medium_count}")
+
+        Note:
+        ----
+            Fetches up to 1000 issues for reasonable performance. For projects
+            with >1000 issues, statistics may be based on a sample.
+
+        """
+        from ...core.models import ProjectStatistics
+
+        # Validate project_id format
+        if not project_id or not project_id.startswith("PVT_"):
+            raise ValueError(
+                f"Invalid project_id: {project_id}. "
+                "Project ID must start with 'PVT_' (e.g., PVT_kwDOABCD1234)"
+            )
+
+        logger.debug(f"Calculating statistics for project {project_id}")
+
+        try:
+            # Fetch all issues (limit 1000 for reasonable performance)
+            issues = await self.project_get_issues(project_id=project_id, limit=1000)
+        except Exception as e:
+            logger.error(f"Failed to fetch issues for statistics: {e}")
+            raise RuntimeError(f"Failed to calculate project statistics: {e}") from e
+
+        # Calculate basic counts
+        total = len(issues)
+        open_count = 0
+        closed_count = 0
+        in_progress_count = 0
+
+        # Count by priority (from labels)
+        priority_counts = {"low": 0, "medium": 0, "high": 0, "critical": 0}
+        blocked_count = 0
+
+        for issue in issues:
+            # Count by state (GitHub only has OPEN/CLOSED)
+            # We map based on state enum value
+            state_value = (
+                issue.state.value if hasattr(issue.state, "value") else str(issue.state)
+            )
+
+            if state_value in ["open", "in_progress", "blocked", "waiting"]:
+                if state_value == "in_progress":
+                    in_progress_count += 1
+                else:
+                    open_count += 1
+            elif state_value in ["done", "closed"]:
+                closed_count += 1
+            else:
+                # Default unrecognized states to open
+                open_count += 1
+
+            # Check tags (labels) for priority and blocked status
+            for tag in issue.tags:
+                tag_lower = tag.lower()
+
+                # Priority detection (priority:high, priority/low, etc.)
+                if "priority:" in tag_lower or "priority/" in tag_lower:
+                    # Extract priority level
+                    priority = (
+                        tag_lower.replace("priority:", "")
+                        .replace("priority/", "")
+                        .strip()
+                    )
+                    if priority in priority_counts:
+                        priority_counts[priority] += 1
+                    elif "crit" in priority or "p0" in priority:
+                        priority_counts["critical"] += 1
+                    elif "high" in priority or "p1" in priority:
+                        priority_counts["high"] += 1
+                    elif "med" in priority or "p2" in priority:
+                        priority_counts["medium"] += 1
+                    elif "low" in priority or "p3" in priority:
+                        priority_counts["low"] += 1
+
+                # Blocked detection
+                if "blocked" in tag_lower or "blocker" in tag_lower:
+                    blocked_count += 1
+
+        # Calculate health and progress
+        if total == 0:
+            health = "on_track"
+            progress_pct = 0.0
+        else:
+            completed_pct = (closed_count / total) * 100
+            blocked_pct = (blocked_count / total) * 100
+
+            # Health scoring logic
+            if completed_pct > 70 and blocked_pct < 10:
+                health = "on_track"
+            elif completed_pct > 40 and blocked_pct < 30:
+                health = "at_risk"
+            else:
+                health = "off_track"
+
+            progress_pct = completed_pct
+
+        # Create statistics object
+        stats = ProjectStatistics(
+            total_count=total,
+            open_count=open_count,
+            in_progress_count=in_progress_count,
+            completed_count=closed_count,
+            blocked_count=blocked_count,
+            priority_low_count=priority_counts["low"],
+            priority_medium_count=priority_counts["medium"],
+            priority_high_count=priority_counts["high"],
+            priority_critical_count=priority_counts["critical"],
+            health=health,
+            progress_percentage=round(progress_pct, 1),
+        )
+
+        logger.info(
+            f"Statistics for {project_id}: {total} issues, "
+            f"{health} health, {progress_pct:.1f}% complete, "
+            f"{blocked_count} blocked"
+        )
+
+        return stats
+
     async def close(self) -> None:
         """Close the HTTP client connection."""
         await self.client.aclose()