claude-mpm 5.4.85__py3-none-any.whl → 5.6.76__py3-none-any.whl

claude_mpm/cli/parsers/skill_source_parser.py

@@ -76,6 +76,10 @@ def add_skill_source_subparser(subparsers) -> argparse.ArgumentParser:
         dest="skip_test",
         help="Skip immediate testing (not recommended)",
     )
+    add_parser.add_argument(
+        "--token",
+        help="GitHub token or env var reference (e.g., ghp_xxx or $PRIVATE_TOKEN)",
+    )
 
     # Remove repository
     remove_parser = skill_source_subparsers.add_parser(

claude_mpm/cli/parsers/skills_parser.py

@@ -167,6 +167,11 @@ def add_skills_subparser(subparsers) -> argparse.ArgumentParser:
         action="store_true",
         help="Force redeployment of already deployed skills",
     )
+    deploy_github_parser.add_argument(
+        "--all",
+        action="store_true",
+        help="Deploy all available skills, not just agent-referenced ones",
+    )
 
     # List available GitHub skills
     list_available_parser = skills_subparsers.add_parser(

claude_mpm/cli/startup.py

@@ -13,6 +13,49 @@ import sys
 from pathlib import Path
 
 
+def cleanup_user_level_hooks() -> bool:
+    """Remove stale user-level hooks directory.
+
+    WHY: claude-mpm previously deployed hooks to ~/.claude/hooks/claude-mpm/
+    (user-level). This is now deprecated in favor of project-level hooks
+    configured in .claude/settings.local.json. Stale user-level hooks can
+    cause conflicts and confusion.
+
+    DESIGN DECISION: Runs early in startup, before project hook sync.
+    Non-blocking - failures are logged at debug level but don't prevent startup.
+
+    Returns:
+        bool: True if hooks were cleaned up, False if none found or cleanup failed
+    """
+    import shutil
+
+    user_hooks_dir = Path.home() / ".claude" / "hooks" / "claude-mpm"
+
+    if not user_hooks_dir.exists():
+        return False
+
+    try:
+        from ..core.logger import get_logger
+
+        logger = get_logger("startup")
+        logger.debug(f"Removing stale user-level hooks directory: {user_hooks_dir}")
+
+        shutil.rmtree(user_hooks_dir)
+
+        logger.debug("User-level hooks cleanup complete")
+        return True
+    except Exception as e:
+        # Non-critical - log but don't fail startup
+        try:
+            from ..core.logger import get_logger
+
+            logger = get_logger("startup")
+            logger.debug(f"Failed to cleanup user-level hooks (non-fatal): {e}")
+        except Exception:  # nosec B110
+            pass  # Avoid any errors in error handling
+        return False
+
+
 def sync_hooks_on_startup(quiet: bool = False) -> bool:
     """Ensure hooks are up-to-date on startup.
 
@@ -20,7 +63,12 @@ def sync_hooks_on_startup(quiet: bool = False) -> bool:
     Reinstalling hooks ensures the hook format matches the current code.
 
     DESIGN DECISION: Shows brief status message on success for user awareness.
-    Failures are logged but don't prevent startup to ensure claude-mpm remains functional.
+    Failures are logged but don't prevent startup to ensure claude-mpm
+    remains functional.
+
+    Workflow:
+    1. Cleanup stale user-level hooks (~/.claude/hooks/claude-mpm/)
+    2. Reinstall project-level hooks to .claude/settings.local.json
 
     Args:
         quiet: If True, suppress all output (used internally)
@@ -28,28 +76,45 @@ def sync_hooks_on_startup(quiet: bool = False) -> bool:
     Returns:
         bool: True if hooks were synced successfully, False otherwise
     """
+    is_tty = not quiet and sys.stdout.isatty()
+
+    # Step 1: Cleanup stale user-level hooks first
+    if is_tty:
+        print("Cleaning user-level hooks...", end=" ", flush=True)
+
+    cleaned = cleanup_user_level_hooks()
+
+    if is_tty:
+        if cleaned:
+            print("✓")
+        else:
+            print("(none found)")
+
+    # Step 2: Install project-level hooks
     try:
         from ..hooks.claude_hooks.installer import HookInstaller
 
         installer = HookInstaller()
 
         # Show brief status (hooks sync is fast)
-        if not quiet:
-            print("Syncing Claude Code hooks...", end=" ", flush=True)
+        if is_tty:
+            print("Installing project hooks...", end=" ", flush=True)
 
         # Reinstall hooks (force=True ensures update)
         success = installer.install_hooks(force=True)
 
-        if not quiet:
+        if is_tty:
             if success:
-                print("✓")
+                # Count hooks from settings file
+                hook_count = _count_installed_hooks(installer.settings_file)
+                print(f"{hook_count} hooks configured ✓")
             else:
                 print("(skipped)")
 
         return success
 
     except Exception as e:
-        if not quiet:
+        if is_tty:
             print("(error)")
         # Log but don't fail startup
         from ..core.logger import get_logger
@@ -59,6 +124,30 @@ def sync_hooks_on_startup(quiet: bool = False) -> bool:
         return False
 
 
+def _count_installed_hooks(settings_file: Path) -> int:
+    """Count the number of hook event types configured in settings.
+
+    Args:
+        settings_file: Path to the settings.local.json file
+
+    Returns:
+        int: Number of hook event types configured (e.g., 7 for all events)
+    """
+    import json
+
+    try:
+        if not settings_file.exists():
+            return 0
+
+        with settings_file.open() as f:
+            settings = json.load(f)
+
+        hooks = settings.get("hooks", {})
+        return len(hooks)
+    except Exception:
+        return 0
+
+
 def cleanup_legacy_agent_cache() -> None:
     """Remove legacy hierarchical agent cache directories.
 
@@ -161,7 +250,25 @@ def setup_early_environment(argv):
     # CRITICAL: Suppress ALL logging by default
     # This catches all loggers (claude_mpm.*, service.*, framework_loader, etc.)
     # This will be overridden by setup_mcp_server_logging() based on user preference
-    logging.getLogger().setLevel(logging.CRITICAL + 1)  # Root logger catches everything
+    root_logger = logging.getLogger()
+    root_logger.setLevel(logging.CRITICAL + 1)  # Root logger catches everything
+    root_logger.handlers = []  # Remove any handlers
+
+    # Also suppress common module loggers explicitly to prevent handler leakage
+    for logger_name in [
+        "claude_mpm",
+        "path_resolver",
+        "file_loader",
+        "framework_loader",
+        "service",
+        "instruction_loader",
+        "agent_loader",
+        "startup",
+    ]:
+        module_logger = logging.getLogger(logger_name)
+        module_logger.setLevel(logging.CRITICAL + 1)
+        module_logger.handlers = []
+        module_logger.propagate = False
 
     # Process argv
     if argv is None:
@@ -178,9 +285,15 @@ def should_skip_background_services(args, processed_argv):
     """
     Determine if background services should be skipped for this command.
 
-    WHY: Some commands (help, version, configure, doctor) don't need
+    WHY: Some commands (help, version, configure, doctor, oauth) don't need
     background services and should start faster.
 
+    NOTE: Headless mode with --resume skips background services because:
+    - Each claude-mpm call is a NEW process (orchestrators like Vibe Kanban)
+    - First message (no --resume): Run full init (hooks, agents, skills)
+    - Follow-up messages (with --resume): Skip init to avoid latency
+    - Hooks/agents/skills are already deployed from the first message
+
     Args:
         args: Parsed arguments
         processed_argv: Processed command line arguments
@@ -188,10 +301,30 @@ def should_skip_background_services(args, processed_argv):
     Returns:
         bool: True if background services should be skipped
     """
+    # Headless mode with --resume: skip init for follow-up messages
+    # Each orchestrator call is a new process, so we need to skip init
+    # on follow-ups to avoid re-running hooks/agents/skills sync every time
+    is_headless = getattr(args, "headless", False)
+    has_resume = getattr(args, "resume", False) or "--resume" in (processed_argv or [])
+
+    if is_headless and has_resume:
+        return True
+
     skip_commands = ["--version", "-v", "--help", "-h"]
     return any(cmd in (processed_argv or sys.argv[1:]) for cmd in skip_commands) or (
         hasattr(args, "command")
-        and args.command in ["info", "doctor", "config", "mcp", "configure"]
+        and args.command
+        in [
+            "info",
+            "doctor",
+            "config",
+            "mcp",
+            "configure",
+            "hook-errors",
+            "autotodos",
+            "commander",
+            "oauth",
+        ]
     )
 
 
@@ -252,11 +385,13 @@ def deploy_bundled_skills():
         if deployment_result.get("deployed"):
             # Show simple feedback for deployed skills
             deployed_count = len(deployment_result["deployed"])
-            print(f"✓ Bundled skills ready ({deployed_count} deployed)", flush=True)
+            if sys.stdout.isatty():
+                print(f"✓ Bundled skills ready ({deployed_count} deployed)", flush=True)
             logger.info(f"Skills: Deployed {deployed_count} skill(s)")
         elif not deployment_result.get("errors"):
             # No deployment needed, skills already present
-            print("✓ Bundled skills ready", flush=True)
+            if sys.stdout.isatty():
+                print("✓ Bundled skills ready", flush=True)
 
         if deployment_result.get("errors"):
             logger.warning(
@@ -290,7 +425,8 @@ def discover_and_link_runtime_skills():
 
         discover_skills()
         # Show simple success feedback
-        print("✓ Runtime skills linked", flush=True)
+        if sys.stdout.isatty():
+            print("✓ Runtime skills linked", flush=True)
     except Exception as e:
         # Import logger here to avoid circular imports
         from ..core.logger import get_logger
@@ -315,7 +451,7 @@ def deploy_output_style_on_startup():
     Deploys all styles:
     - claude-mpm.md (professional mode)
     - claude-mpm-teacher.md (teaching mode)
-    - claude-mpm-founders.md (founders mode)
+    - claude-mpm-research.md (research mode - for codebase analysis)
     """
     try:
         from ..core.output_style_manager import OutputStyleManager
@@ -345,7 +481,8 @@ def deploy_output_style_on_startup():
 
         if all_up_to_date:
             # Show feedback that output styles are ready
-            print("✓ Output styles ready", flush=True)
+            if sys.stdout.isatty():
+                print("✓ Output styles ready", flush=True)
             return
 
         # Deploy all styles using the manager
@@ -355,7 +492,8 @@ def deploy_output_style_on_startup():
         deployed_count = sum(1 for success in results.values() if success)
 
         if deployed_count > 0:
-            print(f"✓ Output styles deployed ({deployed_count} styles)", flush=True)
+            if sys.stdout.isatty():
+                print(f"✓ Output styles deployed ({deployed_count} styles)", flush=True)
         else:
             # Deployment failed - log but don't fail startup
             from ..core.logger import get_logger
@@ -450,6 +588,94 @@ def _cleanup_orphaned_agents(deploy_target: Path, deployed_agents: list[str]) ->
     return removed_count
 
 
+def _save_deployment_state_after_reconciliation(
+    agent_result, project_path: Path
+) -> None:
+    """Save deployment state after reconciliation to prevent duplicate deployment.
+
+    WHY: After perform_startup_reconciliation() deploys agents to .claude/agents/,
+    we need to save a deployment state file so that ClaudeRunner.setup_agents()
+    can detect agents are already deployed and skip redundant deployment.
+
+    This prevents the "✓ Deployed 31 native agents" duplicate deployment that
+    occurs when setup_agents() doesn't know reconciliation already ran.
+
+    Args:
+        agent_result: DeploymentResult from perform_startup_reconciliation()
+        project_path: Project root directory
+
+    DESIGN DECISION: Use same state file format as ClaudeRunner._save_deployment_state()
+    Located at: .claude-mpm/cache/deployment_state.json
+
+    State file format:
+    {
+        "version": "5.6.13",
+        "agent_count": 15,
+        "deployment_hash": "sha256:...",
+        "deployed_at": 1234567890.123
+    }
+    """
+    import hashlib
+    import json
+    import time
+
+    from ..core.logger import get_logger
+
+    logger = get_logger("cli")
+
+    try:
+        # Get version from package
+        from claude_mpm import __version__
+
+        # Path to state file (matches ClaudeRunner._get_deployment_state_path())
+        state_file = project_path / ".claude-mpm" / "cache" / "deployment_state.json"
+        agents_dir = project_path / ".claude" / "agents"
+
+        # Count deployed agents
+        if agents_dir.exists():
+            agent_count = len(list(agents_dir.glob("*.md")))
+        else:
+            agent_count = 0
+
+        # Calculate deployment hash (matches ClaudeRunner._calculate_deployment_hash())
+        # CRITICAL: Must match exact hash algorithm used in ClaudeRunner
+        # Hashes filename + file content (not mtime) for consistency
+        deployment_hash = ""
+        if agents_dir.exists():
+            agent_files = sorted(agents_dir.glob("*.md"))
+            hash_obj = hashlib.sha256()
+            for agent_file in agent_files:
+                # Include filename and content in hash (matches ClaudeRunner)
+                hash_obj.update(agent_file.name.encode())
+                try:
+                    hash_obj.update(agent_file.read_bytes())
+                except Exception as e:
+                    logger.debug(f"Error reading {agent_file} for hash: {e}")
+
+            deployment_hash = hash_obj.hexdigest()
+
+        # Create state data
+        state_data = {
+            "version": __version__,
+            "agent_count": agent_count,
+            "deployment_hash": deployment_hash,
+            "deployed_at": time.time(),
+        }
+
+        # Ensure directory exists
+        state_file.parent.mkdir(parents=True, exist_ok=True)
+
+        # Write state file
+        state_file.write_text(json.dumps(state_data, indent=2))
+        logger.debug(
+            f"Saved deployment state after reconciliation: {agent_count} agents"
+        )
+
+    except Exception as e:
+        # Non-critical error - log but don't fail startup
+        logger.debug(f"Failed to save deployment state: {e}")
+
+
 def sync_remote_agents_on_startup(force_sync: bool = False):
     """
     Synchronize agent templates from remote sources on startup.
@@ -612,6 +838,12 @@ def sync_remote_agents_on_startup(force_sync: bool = False):
                     )
                     print("   Run with --verbose for detailed error information.\n")
 
+                # Save deployment state to prevent duplicate deployment in ClaudeRunner
+                # This ensures setup_agents() skips deployment since we already reconciled
+                _save_deployment_state_after_reconciliation(
+                    agent_result=agent_result, project_path=project_path
+                )
+
             except Exception as e:
                 # Deployment failure shouldn't block startup
                 from ..core.logger import get_logger
@@ -1139,33 +1371,74 @@ def show_skill_summary():
 
 
 def verify_and_show_pm_skills():
-    """Verify PM skills and display status.
+    """Verify PM skills and display status with enhanced validation.
 
-    WHY: PM skills are essential for PM agent operation.
-    Shows deployment status and auto-deploys if missing.
+    WHY: PM skills are CRITICAL for PM agent operation. PM must KNOW if
+    framework knowledge is unavailable at startup. Enhanced validation
+    checks all required skills exist, are not corrupted, and auto-repairs
+    if needed.
+
+    Shows deployment status:
+    - "✓ PM skills: 8/8 verified" if all required skills are valid
+    - "⚠ PM skills: 2 missing, auto-repairing..." if issues detected
+    - Non-blocking but visible warning if auto-repair fails
     """
     try:
         from pathlib import Path
 
-        from ..services.pm_skills_deployer import PMSkillsDeployerService
+        from ..services.pm_skills_deployer import (
+            REQUIRED_PM_SKILLS,
+            PMSkillsDeployerService,
+        )
 
         deployer = PMSkillsDeployerService()
         project_dir = Path.cwd()
 
-        result = deployer.verify_pm_skills(project_dir)
+        # Verify with auto-repair enabled
+        result = deployer.verify_pm_skills(project_dir, auto_repair=True)
 
         if result.verified:
-            # Show verified status
-            print(f"✓ PM skills: {result.skill_count} verified", flush=True)
+            # Show verified status with count
+            total_required = len(REQUIRED_PM_SKILLS)
+            if sys.stdout.isatty():
+                print(
+                    f"✓ PM skills: {total_required}/{total_required} verified",
+                    flush=True,
+                )
         else:
-            # Auto-deploy if missing
-            print("Deploying PM skills...", end="", flush=True)
-            deploy_result = deployer.deploy_pm_skills(project_dir)
-            if deploy_result.success:
-                total = len(deploy_result.deployed) + len(deploy_result.skipped)
-                print(f"\r✓ PM skills: {total} deployed" + " " * 20, flush=True)
+            # Show warning with details
+            missing_count = len(result.missing_skills)
+            corrupted_count = len(result.corrupted_skills)
+
+            # Build status message
+            issues = []
+            if missing_count > 0:
+                issues.append(f"{missing_count} missing")
+            if corrupted_count > 0:
+                issues.append(f"{corrupted_count} corrupted")
+
+            status = ", ".join(issues)
+
+            # Check if auto-repair was attempted
+            if "Auto-repaired" in result.message:
+                # Auto-repair succeeded
+                total_required = len(REQUIRED_PM_SKILLS)
+                if sys.stdout.isatty():
+                    print(
+                        f"✓ PM skills: {total_required}/{total_required} verified (auto-repaired)",
+                        flush=True,
+                    )
             else:
-                print("\r⚠ PM skills: deployment failed" + " " * 20, flush=True)
+                # Auto-repair failed or not attempted
+                if sys.stdout.isatty():
+                    print(f"⚠ PM skills: {status}", flush=True)
+
+                # Log warnings for debugging
+                from ..core.logger import get_logger
+
+                logger = get_logger("cli")
+                for warning in result.warnings:
+                    logger.warning(f"PM skills: {warning}")
 
     except ImportError:
         # PM skills deployer not available - skip silently
@@ -1218,6 +1491,28 @@ def auto_install_chrome_devtools_on_startup():
         # Continue execution - chrome-devtools installation failure shouldn't block startup
 
 
+def sync_deployment_on_startup(force_sync: bool = False) -> None:
+    """Consolidated deployment block: hooks + agents.
+
+    WHY: Groups all deployment tasks into a single logical block for clarity.
+    This ensures hooks and agents are deployed together before other services.
+
+    Order:
+    1. Hook cleanup (remove ~/.claude/hooks/claude-mpm/)
+    2. Hook reinstall (update .claude/settings.local.json)
+    3. Agent sync from remote Git sources
+
+    Args:
+        force_sync: Force download even if cache is fresh (bypasses ETag).
+    """
+    # Step 1-2: Hooks (cleanup + reinstall handled by sync_hooks_on_startup)
+    sync_hooks_on_startup()  # Shows "Syncing Claude Code hooks... ✓"
+
+    # Step 3: Agents from remote sources
+    sync_remote_agents_on_startup(force_sync=force_sync)
+    show_agent_summary()  # Display agent counts after deployment
+
+
 def run_background_services(force_sync: bool = False):
     """
     Initialize all background services on startup.
@@ -1233,19 +1528,21 @@ def run_background_services(force_sync: bool = False):
     Args:
         force_sync: Force download even if cache is fresh (bypasses ETag).
     """
-    # Sync hooks early to ensure up-to-date configuration
-    # RATIONALE: Hooks should be synced before other services to fix stale configs
-    # This is fast (<100ms) and non-blocking, so it doesn't delay startup
-    sync_hooks_on_startup()  # Shows "Syncing Claude Code hooks... ✓"
+    # Run startup migrations FIRST (before any sync operations)
+    # These fix configuration issues from previous versions
+    from .startup_migrations import run_migrations
+
+    run_migrations()
+
+    # Consolidated deployment block: hooks + agents
+    # RATIONALE: Hooks and agents are deployed together before other services
+    # This ensures the deployment phase is complete before configuration checks
+    sync_deployment_on_startup(force_sync=force_sync)
 
     initialize_project_registry()
     check_mcp_auto_configuration()
     verify_mcp_gateway_startup()
     check_for_updates_async()
-    sync_remote_agents_on_startup(
-        force_sync=force_sync
-    )  # Sync agents from remote sources
-    show_agent_summary()  # Display agent counts after deployment
 
     # Skills deployment order (precedence: remote > bundled)
     # 1. Deploy bundled skills first (base layer from package)
@@ -1357,7 +1654,9 @@ def check_mcp_auto_configuration():
         from ..services.mcp_gateway.auto_configure import check_and_configure_mcp
 
         # Show progress feedback - this operation can take 10+ seconds
-        print("Checking MCP configuration...", end="", flush=True)
+        # Only show progress message in TTY mode to avoid interfering with Claude Code's status display
+        if sys.stdout.isatty():
+            print("Checking MCP configuration...", end="", flush=True)
 
         # This function handles all the logic:
         # - Checks if already configured
@@ -1368,11 +1667,17 @@ def check_mcp_auto_configuration():
         check_and_configure_mcp()
 
         # Clear the "Checking..." message by overwriting with spaces
-        print("\r" + " " * 30 + "\r", end="", flush=True)
+        # Only use carriage return clearing if stdout is a real TTY
+        if sys.stdout.isatty():
+            print("\r" + " " * 30 + "\r", end="", flush=True)
+        # In non-TTY mode, don't print anything - the "Checking..." message will just remain on its line
 
     except Exception as e:
         # Clear progress message on error
-        print("\r" + " " * 30 + "\r", end="", flush=True)
+        # Only use carriage return clearing if stdout is a real TTY
+        if sys.stdout.isatty():
+            print("\r" + " " * 30 + "\r", end="", flush=True)
+        # In non-TTY mode, don't print anything - the "Checking..." message will just remain on its line
 
         # Non-critical - log but don't fail
         from ..core.logger import get_logger