claude-mpm 5.0.9__py3-none-any.whl → 5.4.41__py3-none-any.whl

claude_mpm/services/version_control/git_operations.py

@@ -18,6 +18,11 @@ from dataclasses import dataclass, field
 from datetime import datetime, timezone
 from typing import Any, Dict, List, Optional
 
+# Privileged users who can push directly to main branch
+# All other users must use feature branches and PRs
+PRIVILEGED_GIT_USERS = ["bobmatnyc@users.noreply.github.com"]
+PROTECTED_BRANCHES = ["main", "master"]
+
 
 @dataclass
 class GitBranchInfo:
@@ -101,6 +106,94 @@ class GitOperationsManager:
         if not self._is_git_repository():
             raise GitOperationError(f"Not a Git repository: {project_root}")
 
+    def _get_current_git_user(self) -> str:
+        """
+        Get the current Git user email.
+
+        Returns:
+            Git user email configured in repository or globally
+
+        Raises:
+            GitOperationError: If git user.email is not configured
+        """
+        try:
+            result = self._run_git_command(["config", "user.email"])
+            email = result.stdout.strip()
+            if not email:
+                raise GitOperationError(
+                    "Git user.email is not configured. "
+                    "Please configure it with: git config user.email 'your@email.com'"
+                )
+            return email
+        except GitOperationError as e:
+            raise GitOperationError(
+                "Git user.email is not configured. "
+                "Please configure it with: git config user.email 'your@email.com'"
+            ) from e
+
+    def _is_privileged_user(self) -> bool:
+        """
+        Check if the current Git user is privileged to push to protected branches.
+
+        Returns:
+            True if user email is in PRIVILEGED_GIT_USERS, False otherwise
+        """
+        try:
+            current_user = self._get_current_git_user()
+            return current_user in PRIVILEGED_GIT_USERS
+        except GitOperationError:
+            # If we can't determine user, assume not privileged
+            return False
+
+    def _enforce_branch_protection(
+        self, target_branch: str, operation: str
+    ) -> Optional[GitOperationResult]:
+        """
+        Enforce branch protection rules for protected branches.
+
+        Args:
+            target_branch: Branch being operated on
+            operation: Operation being performed (e.g., "push", "merge")
+
+        Returns:
+            GitOperationResult with error if protection violated, None if allowed
+        """
+        # Check if target branch is protected
+        if target_branch not in PROTECTED_BRANCHES:
+            return None
+
+        # Check if user is privileged
+        if self._is_privileged_user():
+            return None
+
+        # Get current user for error message
+        try:
+            current_user = self._get_current_git_user()
+        except GitOperationError:
+            current_user = "unknown"
+
+        # Build helpful error message
+        error_message = (
+            f"Direct {operation} to '{target_branch}' branch is restricted.\n"
+            f"Only {', '.join(PRIVILEGED_GIT_USERS)} can {operation} directly to protected branches.\n"
+            f"Current user: {current_user}\n\n"
+            f"Please use the feature branch workflow:\n"
+            f"  1. git checkout -b feature/your-feature-name\n"
+            f"  2. Make your changes and commit\n"
+            f"  3. git push -u origin feature/your-feature-name\n"
+            f"  4. Create a Pull Request on GitHub for review"
+        )
+
+        return GitOperationResult(
+            success=False,
+            operation=f"{operation}_branch_protection",
+            message=f"Branch protection: {operation} to '{target_branch}' denied",
+            error=error_message,
+            branch_before=self.get_current_branch(),
+            branch_after=self.get_current_branch(),
+            execution_time=0.0,
+        )
+
     def _is_git_repository(self) -> bool:
         """Check if the directory is a Git repository."""
         return self.git_dir.exists() and self.git_dir.is_dir()
@@ -503,6 +596,11 @@ class GitOperationsManager:
         start_time = datetime.now(timezone.utc)
         current_branch = self.get_current_branch()
 
+        # Enforce branch protection for target branch
+        protection_result = self._enforce_branch_protection(target_branch, "merge")
+        if protection_result:
+            return protection_result
+
         try:
             # Switch to target branch
             if current_branch != target_branch:
@@ -659,6 +757,11 @@ class GitOperationsManager:
         if not branch_name:
             branch_name = current_branch
 
+        # Enforce branch protection
+        protection_result = self._enforce_branch_protection(branch_name, "push")
+        if protection_result:
+            return protection_result
+
         try:
             # Build push command
             push_args = ["push"]

claude_mpm/skills/skill_manager.py

@@ -2,7 +2,9 @@
 
 import json
 from pathlib import Path
-from typing import Dict, List, Optional
+from typing import Any, Dict, List, Optional
+
+import yaml
 
 from claude_mpm.core.logging_utils import get_logger
 
@@ -56,12 +58,79 @@ class SkillManager:
         if mapping_count > 0:
             logger.info(f"Loaded skill mappings for {mapping_count} agents")
 
+    def _get_pm_skills(self, project_dir: Optional[Path] = None) -> List[Dict[str, Any]]:
+        """Load PM skills from project's .claude-mpm/skills/pm/ directory.
+
+        PM skills are special required skills deployed per-project,
+        NOT fetched from the skills repository.
+
+        Args:
+            project_dir: Project directory. Defaults to current working directory.
+
+        Returns:
+            List of PM skill dictionaries with metadata
+        """
+        if project_dir is None:
+            project_dir = Path.cwd()
+
+        pm_skills_dir = project_dir / ".claude-mpm" / "skills" / "pm"
+
+        if not pm_skills_dir.exists():
+            logger.debug("PM skills directory not found")
+            return []
+
+        skills = []
+        for skill_dir in pm_skills_dir.iterdir():
+            if skill_dir.is_dir():
+                skill_file = skill_dir / "SKILL.md"
+                if skill_file.exists():
+                    skill = self._load_pm_skill(skill_file)
+                    if skill:
+                        skills.append(skill)
+
+        if skills:
+            logger.debug(f"Loaded {len(skills)} PM skills from {pm_skills_dir}")
+
+        return skills
+
+    def _load_pm_skill(self, skill_file: Path) -> Optional[Dict[str, Any]]:
+        """Load a single PM skill from SKILL.md file.
+
+        Args:
+            skill_file: Path to SKILL.md file
+
+        Returns:
+            Dictionary with skill metadata and content, or None if failed
+        """
+        try:
+            content = skill_file.read_text(encoding='utf-8')
+
+            # Parse YAML frontmatter
+            if content.startswith('---'):
+                parts = content.split('---', 2)
+                if len(parts) >= 3:
+                    metadata = yaml.safe_load(parts[1])
+                    body = parts[2].strip()
+
+                    return {
+                        'name': metadata.get('name', skill_file.parent.name),
+                        'version': metadata.get('version', '1.0.0'),
+                        'description': metadata.get('description', ''),
+                        'when_to_use': metadata.get('when_to_use', ''),
+                        'content': body,
+                        'is_pm_skill': True
+                    }
+        except Exception as e:
+            logger.warning(f"Failed to load PM skill {skill_file}: {e}")
+
+        return None
+
     def get_agent_skills(self, agent_type: str) -> List[Skill]:
         """
-        Get all skills for an agent (bundled + discovered).
+        Get all skills for an agent (bundled + discovered + PM skills if PM agent).
 
         Args:
-            agent_type: Agent type/ID (e.g., 'engineer', 'python_engineer')
+            agent_type: Agent type/ID (e.g., 'engineer', 'python_engineer', 'pm')
 
         Returns:
             List of Skill objects for this agent
@@ -86,6 +155,26 @@ class SkillManager:
             if skill not in skills:
                 skills.append(skill)
 
+        # Add PM skills for PM agent only
+        if agent_type.lower() in ('pm', 'project-manager', 'project_manager'):
+            pm_skill_dicts = self._get_pm_skills()
+            for pm_skill_dict in pm_skill_dicts:
+                # Convert PM skill dict to Skill object
+                pm_skill = Skill(
+                    name=pm_skill_dict['name'],
+                    path=Path.cwd() / ".claude-mpm" / "skills" / "pm" / pm_skill_dict['name'],
+                    content=pm_skill_dict['content'],
+                    source='pm',  # Special source type for PM skills
+                    version=pm_skill_dict['version'],
+                    skill_id=pm_skill_dict['name'],
+                    description=pm_skill_dict['description'],
+                    agent_types=['pm', 'project-manager', 'project_manager']
+                )
+                skills.append(pm_skill)
+
+            if pm_skill_dicts:
+                logger.debug(f"Added {len(pm_skill_dicts)} PM skills for PM agent")
+
         return skills
 
     def enhance_agent_prompt(

claude_mpm/utils/agent_dependency_loader.py

@@ -658,12 +658,24 @@ class AgentDependencyLoader:
                 "Robust installer not available, falling back to simple installation"
             )
             try:
-                cmd = [sys.executable, "-m", "pip", "install"]
-
                 # Check environment and add appropriate flags
                 import os
                 import sysconfig
 
+                # Check if in UV tool environment (no pip available)
+                uv_tool_dir = os.environ.get("UV_TOOL_DIR", "")
+                is_uv_tool = (
+                    (uv_tool_dir and "claude-mpm" in uv_tool_dir)
+                    or ".local/share/uv/tools/" in sys.executable
+                    or "/uv/tools/" in sys.executable
+                )
+
+                if is_uv_tool:
+                    cmd = ["uv", "pip", "install"]
+                    logger.debug("Using 'uv pip install' for UV tool environment")
+                else:
+                    cmd = [sys.executable, "-m", "pip", "install"]
+
                 # Check if in virtualenv
                 in_virtualenv = (
                     (hasattr(sys, "base_prefix") and sys.base_prefix != sys.prefix)

claude_mpm/utils/agent_filters.py

@@ -4,10 +4,14 @@ Agent filtering utilities for claude-mpm.
 WHY: This module provides centralized filtering logic to remove non-deployable
 agents (BASE_AGENT) and already-deployed agents from user-facing displays.
 
+ARCHITECTURE:
+- SOURCE: ~/.claude-mpm/cache/agents/ (git repository cache)
+- DEPLOYMENT: .claude/agents/ (project-level deployment location)
+
 DESIGN DECISIONS:
 - BASE_AGENT is a build tool, not a deployable agent - filter everywhere
-- Deployed agent detection supports both new (.claude-mpm/agents/) and
-  legacy (.claude/agents/)
+- Deployed agent detection checks .claude/agents/ for all deployed agents
+- Supports both virtual (.mpm_deployment_state) and physical (.md files) detection
 - Case-insensitive BASE_AGENT detection for robustness
 - Pure functions for easy testing and reuse
 
@@ -102,10 +106,11 @@ def get_deployed_agent_ids(project_dir: Optional[Path] = None) -> Set[str]:
 
     Design Rationale:
         - Primary detection: Virtual deployment state (.mpm_deployment_state)
-        - Fallback detection: Physical .md files (.claude-mpm/agents/, .claude/agents/)
+        - Fallback detection: Physical .md files in .claude/agents/
         - Returns leaf names for consistent comparison with agent_id formats
         - Combines both detection methods for complete coverage
         - Graceful error handling for malformed or missing state files
+        - Only checks project-level deployment (simplified architecture)
 
     Related:
         - Fixes checkbox interface showing all agents as "○ [Available]" instead of "● [Installed]"
@@ -115,24 +120,17 @@ def get_deployed_agent_ids(project_dir: Optional[Path] = None) -> Set[str]:
     deployed = set()
 
     # Track if project_dir was explicitly provided
-    explicit_project_dir = project_dir is not None
 
     if project_dir is None:
         project_dir = Path.cwd()
 
     # NEW: Check virtual deployment state (primary method)
     # This is the current deployment model used by Claude Code
+    # Only checking project-level deployment in simplified architecture
     deployment_state_paths = [
         project_dir / ".claude" / "agents" / ".mpm_deployment_state",
     ]
 
-    # Only check user-level state if using default project directory
-    # This prevents test isolation issues when explicit project_dir is provided
-    if not explicit_project_dir:
-        deployment_state_paths.append(
-            Path.home() / ".claude" / "agents" / ".mpm_deployment_state"
-        )
-
     for state_path in deployment_state_paths:
         if state_path.exists():
             try:
@@ -162,42 +160,17 @@ def get_deployed_agent_ids(project_dir: Optional[Path] = None) -> Set[str]:
                 continue
 
     # EXISTING: Check physical .md files (fallback for backward compatibility)
-    # Check new architecture
-    new_agents_dir = project_dir / ".claude-mpm" / "agents"
-    if new_agents_dir.exists():
-        for file in new_agents_dir.glob("*.md"):
-            if file.stem not in {"BASE-AGENT", ".DS_Store"}:
-                deployed.add(file.stem)
-
-    # Check legacy architecture
-    legacy_agents_dir = project_dir / ".claude" / "agents"
-    if legacy_agents_dir.exists():
-        for file in legacy_agents_dir.glob("*.md"):
+    # Check project deployment location (.claude/agents/)
+    agents_dir = project_dir / ".claude" / "agents"
+    if agents_dir.exists():
+        for file in agents_dir.glob("*.md"):
             if file.stem not in {"BASE-AGENT", ".DS_Store"}:
                 deployed.add(file.stem)
 
-    # Check .claude/templates/ directory (where agents are actually deployed)
-    templates_dir = project_dir / ".claude" / "templates"
-    if templates_dir.exists():
-        for file in templates_dir.glob("*.md"):
-            if file.stem not in {
-                "BASE-AGENT",
-                ".DS_Store",
-                "README",
-                "circuit-breakers",
-            }:
-                # Skip template/example files
-                if not any(x in file.stem for x in ["example", "template", "pm-"]):
-                    deployed.add(file.stem)
-
-    # Check user-level directory only if using default project directory
-    # This prevents test isolation issues when explicit project_dir is provided
-    if not explicit_project_dir:
-        user_agents_dir = Path.home() / ".claude" / "agents"
-        if user_agents_dir.exists():
-            for file in user_agents_dir.glob("*.md"):
-                if file.stem not in {"BASE-AGENT", ".DS_Store"}:
-                    deployed.add(file.stem)
+    # NOTE: .claude/templates/ contains PM instruction templates, NOT deployed agents
+    # It should NOT be checked here. Agents are deployed to:
+    # - .mpm_deployment_state (virtual deployment)
+    # - .claude/agents/*.md (project deployment)
 
     return deployed
 

claude_mpm/utils/gitignore.py

@@ -212,6 +212,9 @@ def ensure_claude_mpm_gitignore(project_dir: str = ".") -> dict:
         entries_to_add = [
             ".claude-mpm/",
             ".claude/agents/",
+            ".mcp.json",
+            ".claude.json",
+            ".claude/",
         ]
 
         added, existing = manager.ensure_entries(entries_to_add)

claude_mpm/utils/migration.py

@@ -2,7 +2,7 @@
 
 WHY: Phase 3 of 1M-486 requires migrating from old single-tier deployment
      (~/.claude/agents/, ~/.claude/skills/) to new two-phase architecture:
-     - Cache: ~/.claude-mpm/cache/remote-agents/, ~/.claude-mpm/cache/skills/
+     - Cache: ~/.claude-mpm/cache/agents/, ~/.claude-mpm/cache/skills/
      - Deployment: .claude-mpm/agents/, .claude-mpm/skills/
 
 DESIGN DECISIONS:
@@ -41,7 +41,7 @@ class MigrationUtility:
         self.old_agent_dir = Path.home() / ".claude" / "agents"
         self.old_skill_dir = Path.home() / ".claude" / "skills"
 
-        self.new_agent_cache = Path.home() / ".claude-mpm" / "cache" / "remote-agents"
+        self.new_agent_cache = Path.home() / ".claude-mpm" / "cache" / "agents"
         self.new_skill_cache = Path.home() / ".claude-mpm" / "cache" / "skills"
 
     def detect_old_locations(self) -> Dict[str, bool]:
@@ -80,7 +80,7 @@ class MigrationUtility:
     def migrate_agents(
         self, dry_run: bool = False, auto_confirm: bool = False
     ) -> Dict[str, any]:
-        """Migrate agents from ~/.claude/agents/ to ~/.claude-mpm/cache/remote-agents/.
+        """Migrate agents from ~/.claude/agents/ to ~/.claude-mpm/cache/agents/.
 
         Args:
             dry_run: Preview migration without making changes
@@ -329,7 +329,7 @@ class MigrationUtility:
 
         warning += "\nThe deployment architecture has changed:\n"
         warning += "  OLD: ~/.claude/agents/ (single-tier, global)\n"
-        warning += "  NEW: ~/.claude-mpm/cache/remote-agents/ → .claude-mpm/agents/ (two-phase, per-project)\n\n"
+        warning += "  NEW: ~/.claude-mpm/cache/agents/ → .claude-mpm/agents/ (two-phase, per-project)\n\n"
 
         warning += "To migrate:\n"
         warning += "  claude-mpm migrate\n\n"

claude_mpm/utils/robust_installer.py

@@ -82,6 +82,7 @@ class RobustPackageInstaller:
         self.attempts: List[InstallAttempt] = []
         self.success_cache: Dict[str, bool] = {}
         self.in_virtualenv = self._check_virtualenv()
+        self.is_uv_tool = self._check_uv_tool_installation()
         self.is_pep668_managed = self._check_pep668_managed()
         self.pep668_warning_shown = False
 
@@ -261,6 +262,36 @@ class RobustPackageInstaller:
 
         return False
 
+    def _check_uv_tool_installation(self) -> bool:
+        """
+        Check if running in UV tool environment (no pip available).
+
+        WHY: UV tool environments don't have pip installed. The executable
+        path typically contains ".local/share/uv/tools/" and the UV_TOOL_DIR
+        environment variable is set. In such environments, we need to use
+        'uv pip' instead of 'python -m pip'.
+
+        Returns:
+            True if UV tool environment, False otherwise
+        """
+        import os
+
+        # Check UV_TOOL_DIR environment variable
+        uv_tool_dir = os.environ.get("UV_TOOL_DIR", "")
+        if uv_tool_dir and "claude-mpm" in uv_tool_dir:
+            logger.debug(f"UV tool environment detected via UV_TOOL_DIR: {uv_tool_dir}")
+            return True
+
+        # Check executable path for UV tool patterns
+        executable = sys.executable
+        if ".local/share/uv/tools/" in executable or "/uv/tools/" in executable:
+            logger.debug(
+                f"UV tool environment detected via executable path: {executable}"
+            )
+            return True
+
+        return False
+
     def _show_pep668_warning(self) -> None:
         """
         Show warning about PEP 668 managed environment.
@@ -301,7 +332,12 @@ class RobustPackageInstaller:
         Returns:
             Command as list of arguments
         """
-        base_cmd = [sys.executable, "-m", "pip", "install"]
+        # UV tool environments don't have pip; use uv pip instead
+        if self.is_uv_tool:
+            base_cmd = ["uv", "pip", "install"]
+            logger.debug("Using 'uv pip install' for UV tool environment")
+        else:
+            base_cmd = [sys.executable, "-m", "pip", "install"]
 
         # Determine appropriate flags based on environment
         if self.in_virtualenv:
@@ -651,7 +687,12 @@ class RobustPackageInstaller:
             Tuple of (success, error_message)
         """
         try:
-            cmd = [sys.executable, "-m", "pip", "install"]
+            # UV tool environments don't have pip; use uv pip instead
+            if self.is_uv_tool:
+                cmd = ["uv", "pip", "install"]
+                logger.debug("Using 'uv pip install' for batch installation")
+            else:
+                cmd = [sys.executable, "-m", "pip", "install"]
 
             # Add appropriate flags based on environment
             if self.in_virtualenv:
@@ -702,7 +743,10 @@ class RobustPackageInstaller:
 
         # Add environment status
         lines.append("")
-        if self.in_virtualenv:
+        if self.is_uv_tool:
+            lines.append("✓ Environment: UV Tool Environment")
+            lines.append("  Using 'uv pip' command (pip not available)")
+        elif self.in_virtualenv:
             lines.append("✓ Environment: Virtual Environment (isolated)")
             lines.append("  No special pip flags needed")
         elif self.is_pep668_managed: