claude-mpm 5.4.64__py3-none-any.whl → 5.4.96__py3-none-any.whl

claude_mpm/services/pm_skills_deployer.py

@@ -1,27 +1,30 @@
 """PM Skills Deployer Service - Deploy bundled PM skills to projects.
 
-WHY: PM agents require specific templates and skills for proper operation.
+WHY: PM agents require specific framework management skills for proper operation.
 This service manages deployment of bundled PM skills from the claude-mpm
-package to individual project .claude-mpm directories with version tracking.
+package to the Claude Code skills directory with version tracking.
 
 DESIGN DECISIONS:
-- Deploys from src/claude_mpm/skills/bundled/pm/ to .claude-mpm/skills/pm/
+- Deploys from src/claude_mpm/skills/bundled/pm/ to .claude/skills/
+- Skills named mpm-* (framework management skills)
+- Direct deployment (no intermediate .claude-mpm/skills/pm/ step)
 - Uses package-relative paths (works for both installed and dev mode)
-- Supports two skill formats:
-  1. Directory structure: pm-skill-name/SKILL.md (new format)
-  2. Flat files: skill-name.md (legacy format in .claude-mpm/templates/)
-- Per-project deployment (NOT global like Claude Code skills)
+- Supports directory structure: mpm-skill-name/SKILL.md
+- Per-project deployment to .claude/skills/ (Claude Code location)
 - Version tracking via .claude-mpm/pm_skills_registry.yaml
 - Checksum validation for integrity verification
+- Conflict resolution: mpm-* skills from src WIN (overwrite existing)
+- Non-mpm-* skills in .claude/skills/ are untouched (user/git managed)
 - Non-blocking verification (returns warnings, doesn't halt execution)
 - Force flag to redeploy even if versions match
 
 ARCHITECTURE:
 1. Discovery: Find bundled PM skills in package (skills/bundled/pm/)
-2. Deployment: Copy SKILL.md files to .claude-mpm/skills/pm/{name}.md
-3. Registry: Track deployed versions and checksums
-4. Verification: Check deployment status (non-blocking)
-5. Updates: Compare bundled vs deployed versions
+2. Deployment: Copy SKILL.md files to .claude/skills/{name}/SKILL.md
+3. Conflict Check: Overwrite mpm-* skills, preserve non-mpm-* skills
+4. Registry: Track deployed versions and checksums
+5. Verification: Check deployment status (non-blocking)
+6. Updates: Compare bundled vs deployed versions
 
 PATH RESOLUTION:
 - Installed package: Uses __file__ to find skills/bundled/pm/
@@ -47,6 +50,22 @@ from claude_mpm.core.mixins import LoggerMixin
 # Security constants
 MAX_YAML_SIZE = 10 * 1024 * 1024  # 10MB limit to prevent YAML bombs
 
+# Required PM skills that MUST be deployed for PM agent to function properly
+# These are framework management skills that PM uses for orchestration
+REQUIRED_PM_SKILLS = [
+    "mpm-git-file-tracking",
+    "mpm-pr-workflow",
+    "mpm-ticketing-integration",
+    "mpm-delegation-patterns",
+    "mpm-verification-protocols",
+    "mpm-bug-reporting",
+    "mpm-teaching-mode",
+    "mpm-agent-update-workflow",
+    "mpm-circuit-breaker-enforcement",
+    "mpm-tool-usage-guide",
+    "mpm-session-management",
+]
+
 
 @dataclass
 class PMSkillInfo:
@@ -96,6 +115,7 @@ class VerificationResult:
         verified: Whether all skills are properly deployed
         warnings: List of warning messages
         missing_skills: List of missing skill names
+        corrupted_skills: List of corrupted skill names (checksum mismatch)
         outdated_skills: List of outdated skill names
         message: Summary message
         skill_count: Total number of deployed skills
@@ -104,6 +124,7 @@ class VerificationResult:
     verified: bool
     warnings: List[str]
     missing_skills: List[str]
+    corrupted_skills: List[str]
     outdated_skills: List[str]
     message: str
     skill_count: int = 0
@@ -130,8 +151,9 @@ class PMSkillsDeployerService(LoggerMixin):
     """Deploy and manage PM skills from bundled sources to projects.
 
     This service provides:
-    - Discovery of bundled PM skills (templates)
-    - Deployment to .claude-mpm/skills/pm/
+    - Discovery of bundled PM skills (mpm-* framework management skills)
+    - Deployment to .claude/skills/ (Claude Code location)
+    - Conflict resolution (mpm-* skills from src WIN)
     - Version tracking via pm_skills_registry.yaml
     - Checksum validation for integrity
     - Non-blocking verification (warnings only)
@@ -140,7 +162,7 @@ class PMSkillsDeployerService(LoggerMixin):
     Example:
         >>> deployer = PMSkillsDeployerService()
         >>> result = deployer.deploy_pm_skills(Path("/project/root"))
-        >>> print(f"Deployed {len(result.deployed)} skills")
+        >>> print(f"Deployed {len(result.deployed)} skills to .claude/skills/")
         >>>
         >>> verify_result = deployer.verify_pm_skills(Path("/project/root"))
         >>> if not verify_result.verified:
@@ -246,9 +268,9 @@ class PMSkillsDeployerService(LoggerMixin):
             project_dir: Project root directory
 
         Returns:
-            Path to .claude-mpm/skills/pm/
+            Path to .claude/skills/
         """
-        return project_dir / ".claude-mpm" / "skills" / "pm"
+        return project_dir / ".claude" / "skills"
 
     def _load_registry(self, project_dir: Path) -> Dict[str, Any]:
         """Load PM skills registry with security checks.
@@ -322,14 +344,12 @@ class PMSkillsDeployerService(LoggerMixin):
     def _discover_bundled_pm_skills(self) -> List[Dict[str, Any]]:
         """Discover all PM skills in bundled templates directory.
 
-        PM skills can be in two formats:
-        1. Directory structure: pm-skill-name/SKILL.md (new format)
-        2. Flat files: skill-name.md (legacy format for .claude-mpm/templates/)
+        PM skills follow mpm-skill-name/SKILL.md structure.
 
         Returns:
             List of skill dictionaries containing:
-            - name: Skill name (directory/filename without extension)
-            - path: Full path to skill file (SKILL.md or .md file)
+            - name: Skill name (directory name, e.g., mpm-git-file-tracking)
+            - path: Full path to skill file (SKILL.md)
             - type: File type (always 'md')
         """
         skills = []
@@ -340,11 +360,16 @@ class PMSkillsDeployerService(LoggerMixin):
             )
             return skills
 
-        # Scan for skill directories containing SKILL.md (new format)
+        # Scan for skill directories containing SKILL.md
         for skill_dir in self.bundled_pm_skills_path.iterdir():
             if not skill_dir.is_dir() or skill_dir.name.startswith("."):
                 continue
 
+            # Only process mpm-* skills (framework management)
+            if not skill_dir.name.startswith("mpm-"):
+                self.logger.debug(f"Skipping non-mpm skill: {skill_dir.name}")
+                continue
+
             skill_file = skill_dir / "SKILL.md"
             if skill_file.exists():
                 skills.append(
@@ -355,19 +380,6 @@ class PMSkillsDeployerService(LoggerMixin):
                     }
                 )
 
-        # Fallback: Scan for .md files directly (legacy format)
-        for skill_file in self.bundled_pm_skills_path.glob("*.md"):
-            if skill_file.name.startswith("."):
-                continue
-
-            skills.append(
-                {
-                    "name": skill_file.stem,
-                    "path": skill_file,
-                    "type": "md",
-                }
-            )
-
         self.logger.info(f"Discovered {len(skills)} bundled PM skills")
         return skills
 
@@ -379,9 +391,13 @@ class PMSkillsDeployerService(LoggerMixin):
     ) -> DeploymentResult:
         """Deploy bundled PM skills to project directory.
 
-        Copies PM skills from bundled templates to .claude-mpm/skills/pm/
+        Copies PM skills from bundled templates to .claude/skills/{name}/SKILL.md
         and updates registry with version and checksum information.
 
+        Conflict Resolution:
+        - mpm-* skills from src WIN (overwrite existing)
+        - Non-mpm-* skills in .claude/skills/ are untouched
+
         Args:
             project_dir: Project root directory
             force: If True, redeploy even if skill already exists
@@ -392,7 +408,7 @@ class PMSkillsDeployerService(LoggerMixin):
 
         Example:
             >>> result = deployer.deploy_pm_skills(Path("/project"), force=True)
-            >>> print(f"Deployed: {len(result.deployed)}")
+            >>> print(f"Deployed: {len(result.deployed)} to .claude/skills/")
         """
         skills = self._discover_bundled_pm_skills()
         deployed = []
@@ -447,8 +463,12 @@ class PMSkillsDeployerService(LoggerMixin):
                 if progress_callback:
                     progress_callback(skill_name, idx + 1, total_skills)
 
-                # Use skill name for target file (e.g., pm-delegation-patterns.md)
-                target_path = deployment_dir / f"{skill_name}.md"
+                # Create skill directory: .claude/skills/{skill_name}/
+                skill_dir = deployment_dir / skill_name
+                skill_dir.mkdir(parents=True, exist_ok=True)
+
+                # Target path: .claude/skills/{skill_name}/SKILL.md
+                target_path = skill_dir / "SKILL.md"
 
                 # SECURITY: Validate target path
                 if not self._validate_safe_path(deployment_dir, target_path):
@@ -468,7 +488,7 @@ class PMSkillsDeployerService(LoggerMixin):
                         )
                         continue
 
-                # Deploy skill
+                # Deploy skill (overwrites if exists - mpm-* skills WIN)
                 shutil.copy2(source_path, target_path)
 
                 # Add to deployed list
@@ -520,76 +540,107 @@ class PMSkillsDeployerService(LoggerMixin):
             message=message,
         )
 
-    def verify_pm_skills(self, project_dir: Path) -> VerificationResult:
-        """Verify PM skills are properly deployed (non-blocking).
+    def verify_pm_skills(
+        self, project_dir: Path, auto_repair: bool = True
+    ) -> VerificationResult:
+        """Verify PM skills are properly deployed with enhanced validation.
+
+        Checks ALL required PM skills for:
+        - Existence in deployment directory
+        - File integrity (non-empty, valid checksums)
+        - Version currency (compared to bundled source)
 
-        Checks deployment status and returns warnings without halting execution.
-        This allows graceful degradation if PM skills are missing.
+        Auto-repair logic:
+        - If auto_repair=True (default), automatically deploys missing/corrupted skills
+        - Reports what was fixed in the result
 
         Args:
             project_dir: Project root directory
+            auto_repair: If True, auto-deploy missing/corrupted skills (default: True)
 
         Returns:
-            VerificationResult with verification status and warnings
+            VerificationResult with detailed verification status:
+            - verified: True if all required skills are deployed and valid
+            - missing_skills: List of required skills not deployed
+            - corrupted_skills: List of skills with checksum mismatches
+            - warnings: List of warning messages
+            - skill_count: Total number of deployed skills
 
         Example:
             >>> result = deployer.verify_pm_skills(Path("/project"))
             >>> if not result.verified:
-            ...     for warning in result.warnings:
-            ...         print(f"WARNING: {warning}")
+            ...     print(f"Missing: {result.missing_skills}")
+            ...     print(f"Corrupted: {result.corrupted_skills}")
         """
         warnings = []
         missing_skills = []
+        corrupted_skills = []
         outdated_skills = []
 
         # Check if registry exists
         registry = self._load_registry(project_dir)
-        if not registry:
-            warnings.append("PM skills registry not found or invalid")
-            missing_skills.append("all")
-            return VerificationResult(
-                verified=False,
-                warnings=warnings,
-                missing_skills=missing_skills,
-                outdated_skills=outdated_skills,
-                message="PM skills not deployed. Run 'claude-mpm init' to deploy.",
-                skill_count=0,
-            )
-
-        # Check each registered skill exists
         deployment_dir = self._get_deployment_dir(project_dir)
-        deployed_skills = registry.get("skills", [])
+        deployed_skills_data = registry.get("skills", []) if registry else []
 
-        for skill in deployed_skills:
-            skill_name = skill["name"]
-            skill_file = deployment_dir / f"{skill_name}.md"
+        # Build lookup for deployed skills
+        deployed_lookup = {skill["name"]: skill for skill in deployed_skills_data}
 
+        # Check ALL required PM skills
+        for required_skill in REQUIRED_PM_SKILLS:
+            # Check if skill is in registry
+            if required_skill not in deployed_lookup:
+                warnings.append(f"Required PM skill missing: {required_skill}")
+                missing_skills.append(required_skill)
+                continue
+
+            # Check if skill file exists
+            skill_file = deployment_dir / required_skill / "SKILL.md"
             if not skill_file.exists():
-                warnings.append(f"Deployed skill file missing: {skill_name}")
-                missing_skills.append(skill_name)
+                warnings.append(
+                    f"Required PM skill file missing: {required_skill}/SKILL.md"
+                )
+                missing_skills.append(required_skill)
+                continue
+
+            # Check if skill file is empty/corrupted
+            try:
+                file_size = skill_file.stat().st_size
+                if file_size == 0:
+                    warnings.append(
+                        f"Required PM skill file is empty: {required_skill}/SKILL.md"
+                    )
+                    corrupted_skills.append(required_skill)
+                    continue
+            except OSError as e:
+                warnings.append(
+                    f"Cannot read required PM skill file: {required_skill}/SKILL.md - {e}"
+                )
+                corrupted_skills.append(required_skill)
                 continue
 
             # Verify checksum
+            deployed_skill = deployed_lookup[required_skill]
             current_checksum = self._compute_checksum(skill_file)
-            expected_checksum = skill.get("checksum", "")
+            expected_checksum = deployed_skill.get("checksum", "")
 
             if current_checksum != expected_checksum:
                 warnings.append(
-                    f"Skill checksum mismatch: {skill_name} (file may be corrupted)"
+                    f"Required PM skill checksum mismatch: {required_skill} (file may be corrupted)"
                 )
-                outdated_skills.append(skill_name)
+                corrupted_skills.append(required_skill)
 
-        # Check for available updates
+        # Check for available updates (bundled skills newer than deployed)
         bundled_skills = {s["name"]: s for s in self._discover_bundled_pm_skills()}
         for skill_name, bundled_skill in bundled_skills.items():
+            # Skip non-required skills
+            if skill_name not in REQUIRED_PM_SKILLS:
+                continue
+
             # Find corresponding deployed skill
-            deployed_skill = next(
-                (s for s in deployed_skills if s["name"] == skill_name), None
-            )
+            deployed_skill = deployed_lookup.get(skill_name)
 
             if not deployed_skill:
-                warnings.append(f"New PM skill available: {skill_name}")
-                missing_skills.append(skill_name)
+                # Already tracked as missing
                 continue
 
             # Check if checksums differ
@@ -597,23 +648,66 @@ class PMSkillsDeployerService(LoggerMixin):
             deployed_checksum = deployed_skill.get("checksum", "")
 
             if bundled_checksum != deployed_checksum:
-                warnings.append(f"PM skill update available: {skill_name}")
-                outdated_skills.append(skill_name)
+                # Don't add to outdated_skills if already in corrupted_skills
+                if skill_name not in corrupted_skills:
+                    warnings.append(f"PM skill update available: {skill_name}")
+                    outdated_skills.append(skill_name)
+
+        # Auto-repair if enabled and issues found
+        repaired_skills = []
+        if auto_repair and (missing_skills or corrupted_skills):
+            self.logger.info(
+                f"Auto-repairing PM skills: {len(missing_skills)} missing, "
+                f"{len(corrupted_skills)} corrupted"
+            )
+
+            # Deploy missing and corrupted skills
+            repair_result = self.deploy_pm_skills(project_dir, force=True)
 
-        verified = len(warnings) == 0
+            if repair_result.success:
+                repaired_skills = repair_result.deployed
+                self.logger.info(f"Auto-repaired {len(repaired_skills)} PM skills")
 
+                # Remove repaired skills from missing/corrupted lists
+                missing_skills = [s for s in missing_skills if s not in repaired_skills]
+                corrupted_skills = [
+                    s for s in corrupted_skills if s not in repaired_skills
+                ]
+
+                # Update warnings
+                if repaired_skills:
+                    warnings.append(
+                        f"Auto-repaired {len(repaired_skills)} PM skills: {', '.join(repaired_skills)}"
+                    )
+            else:
+                warnings.append(
+                    f"Auto-repair failed: {len(repair_result.errors)} errors"
+                )
+                self.logger.error(
+                    f"Auto-repair failed with errors: {repair_result.errors}"
+                )
+
+        # Determine verification status
+        verified = len(missing_skills) == 0 and len(corrupted_skills) == 0
+
+        # Build message
         if verified:
-            message = "All PM skills verified and up-to-date"
+            if repaired_skills:
+                message = f"All PM skills verified (auto-repaired {len(repaired_skills)} skills)"
+            else:
+                message = "All PM skills verified and up-to-date"
         else:
-            message = f"{len(warnings)} verification warnings found"
+            issue_count = len(missing_skills) + len(corrupted_skills)
+            message = f"{issue_count} PM skill issues found"
 
         return VerificationResult(
             verified=verified,
             warnings=warnings,
             missing_skills=missing_skills,
+            corrupted_skills=corrupted_skills,
             outdated_skills=outdated_skills,
             message=message,
-            skill_count=len(deployed_skills),
+            skill_count=len(deployed_skills_data),
         )
 
     def get_deployed_skills(self, project_dir: Path) -> List[PMSkillInfo]:
@@ -636,10 +730,10 @@ class PMSkillsDeployerService(LoggerMixin):
         skills = []
         for skill_data in registry.get("skills", []):
             skill_name = skill_data["name"]
-            deployed_path = deployment_dir / f"{skill_name}.md"
+            deployed_path = deployment_dir / skill_name / "SKILL.md"
 
             # Find source path (may not exist if bundled skills changed)
-            source_path = self.bundled_pm_skills_path / f"{skill_name}.md"
+            source_path = self.bundled_pm_skills_path / skill_name / "SKILL.md"
 
             skills.append(
                 PMSkillInfo(

claude_mpm/services/skills/git_skill_source_manager.py

@@ -1095,7 +1095,11 @@ class GitSkillSourceManager:
             if removed_skills:
                 self.logger.info(
                     f"Removed {len(removed_skills)} orphaned skills not referenced by agents: {removed_skills[:10]}"
-                    + (f" (and {len(removed_skills) - 10} more)" if len(removed_skills) > 10 else "")
+                    + (
+                        f" (and {len(removed_skills) - 10} more)"
+                        if len(removed_skills) > 10
+                        else ""
+                    )
                 )
 
         self.logger.info(