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

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,7 +285,7 @@ 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.
 
     Args:
@@ -191,7 +298,18 @@ def should_skip_background_services(args, processed_argv):
     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",
+        ]
     )
 
 
@@ -234,7 +352,7 @@ def deploy_bundled_skills():
             if not skills_config.get("auto_deploy", True):
                 # Auto-deploy disabled, skip silently
                 return
-        except Exception:
+        except Exception:  # nosec B110
             # If config loading fails, assume auto-deploy is enabled (default)
             pass
 
@@ -252,11 +370,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 +410,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
@@ -308,63 +429,62 @@ def deploy_output_style_on_startup():
     communication without emojis and exclamation points. Styles are project-specific
     to allow different projects to have different communication styles.
 
-    DESIGN DECISION: This is non-blocking and idempotent. Deploys to project-level
-    directory (.claude/settings/output-styles/) instead of user-level to maintain
-    project isolation.
+    DESIGN DECISION: This is non-blocking and idempotent. Deploys to user-level
+    directory (~/.claude/output-styles/) which is the official Claude Code location
+    for custom output styles.
 
-    Deploys two styles:
-    - claude-mpm-style.md (professional mode)
+    Deploys all styles:
+    - claude-mpm.md (professional mode)
     - claude-mpm-teacher.md (teaching mode)
+    - claude-mpm-research.md (research mode - for codebase analysis)
     """
     try:
-        import shutil
-        from pathlib import Path
+        from ..core.output_style_manager import OutputStyleManager
 
-        # Source files (in framework package)
-        package_dir = Path(__file__).parent.parent / "agents"
-        professional_source = package_dir / "CLAUDE_MPM_OUTPUT_STYLE.md"
-        teacher_source = package_dir / "CLAUDE_MPM_TEACHER_OUTPUT_STYLE.md"
+        # Initialize the output style manager
+        manager = OutputStyleManager()
 
-        # Target directory (PROJECT-LEVEL, not user-level)
-        project_dir = Path.cwd()
-        output_styles_dir = project_dir / ".claude" / "settings" / "output-styles"
-        professional_target = output_styles_dir / "claude-mpm-style.md"
-        teacher_target = output_styles_dir / "claude-mpm-teacher.md"
-
-        # Create directory if it doesn't exist
-        output_styles_dir.mkdir(parents=True, exist_ok=True)
-
-        # Check if already deployed (both files exist and have content)
-        already_deployed = (
-            professional_target.exists()
-            and teacher_target.exists()
-            and professional_target.stat().st_size > 0
-            and teacher_target.stat().st_size > 0
-        )
+        # Check if Claude Code version supports output styles (>= 1.0.83)
+        if not manager.supports_output_styles():
+            # Skip deployment for older versions
+            # The manager will fall back to injecting content directly
+            return
 
-        if already_deployed:
+        # Check if all styles are already deployed and up-to-date
+        all_up_to_date = True
+        for style_config in manager.styles.values():
+            source_path = style_config["source"]
+            target_path = style_config["target"]
+
+            if not (
+                target_path.exists()
+                and source_path.exists()
+                and target_path.stat().st_size == source_path.stat().st_size
+            ):
+                all_up_to_date = False
+                break
+
+        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 both styles
-        deployed_count = 0
-        if professional_source.exists():
-            shutil.copy2(professional_source, professional_target)
-            deployed_count += 1
+        # Deploy all styles using the manager
+        results = manager.deploy_all_styles(activate_default=True)
 
-        if teacher_source.exists():
-            shutil.copy2(teacher_source, teacher_target)
-            deployed_count += 1
+        # Count successful deployments
+        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:
-            # Source files missing - log but don't fail
+            # Deployment failed - log but don't fail startup
             from ..core.logger import get_logger
 
             logger = get_logger("cli")
-            logger.debug("Output style source files not found")
+            logger.debug("Failed to deploy any output styles")
 
     except Exception as e:
         # Non-critical - log but don't fail startup
@@ -453,7 +573,95 @@ def _cleanup_orphaned_agents(deploy_target: Path, deployed_agents: list[str]) ->
     return removed_count
 
 
-def sync_remote_agents_on_startup():
+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.
 
@@ -466,28 +674,28 @@ def sync_remote_agents_on_startup():
     block startup to ensure claude-mpm remains functional.
 
     Workflow:
-    1. Cleanup legacy agent cache directories (if any)
-    2. Sync all enabled Git sources (download/cache files) - Phase 1 progress bar
-    3. Deploy agents to ~/.claude/agents/ - Phase 2 progress bar
-    4. Cleanup orphaned agents (ours but no longer deployed) - Phase 3
+    1. Sync all enabled Git sources (download/cache files) - Phase 1 progress bar
+    2. Deploy agents to ~/.claude/agents/ - Phase 2 progress bar
+    3. Cleanup orphaned agents (ours but no longer deployed) - Phase 3
+    4. Cleanup legacy agent cache directories (after sync/deployment) - Phase 4
     5. Log deployment results
-    """
-    # Cleanup legacy cache directories first (before syncing)
-    cleanup_legacy_agent_cache()
 
-    # DEPRECATED: Legacy warning - replaced by automatic cleanup above
+    Args:
+        force_sync: Force download even if cache is fresh (bypasses ETag).
+    """
+    # DEPRECATED: Legacy warning - no-op function, kept for compatibility
     check_legacy_cache()
 
     try:
+        # Load active profile if configured
+        # Get project root (where .claude-mpm exists)
+        from pathlib import Path
+
         from ..core.shared.config_loader import ConfigLoader
-        from ..services.agents.deployment.agent_deployment import AgentDeploymentService
         from ..services.agents.startup_sync import sync_agents_on_startup
         from ..services.profile_manager import ProfileManager
         from ..utils.progress import ProgressBar
 
-        # Load active profile if configured
-        # Get project root (where .claude-mpm exists)
-        from pathlib import Path
         project_root = Path.cwd()
 
         profile_manager = ProfileManager(project_dir=project_root)
@@ -508,7 +716,7 @@ def sync_remote_agents_on_startup():
                 )
 
         # Phase 1: Sync files from Git sources
-        result = sync_agents_on_startup()
+        result = sync_agents_on_startup(force_refresh=force_sync)
 
         # Only proceed with deployment if sync was enabled and ran
         if result.get("enabled") and result.get("sources_synced", 0) > 0:
@@ -531,297 +739,95 @@ def sync_remote_agents_on_startup():
                 logger.warning(f"Agent sync completed with {len(errors)} errors")
 
             # Phase 2: Deploy agents from cache to ~/.claude/agents/
-            # This mirrors the skills deployment pattern (lines 371-407)
+            # Use reconciliation service to respect configuration.yaml settings
             try:
-                # Initialize deployment service with profile-filtered configuration
-                from ..core.config import Config
-
-                deploy_config = None
-                if active_profile and profile_manager.active_profile:
-                    # Create config with excluded agents based on profile
-                    # Get all agents that should be excluded (not in enabled list)
-                    from pathlib import Path
-
-                    cache_dir = Path.home() / ".claude-mpm" / "cache" / "agents"
-                    if cache_dir.exists():
-                        # Find all agent files
-                        all_agent_files = [
-                            f
-                            for f in cache_dir.rglob("*.md")
-                            if "/agents/" in str(f)
-                            and str(f).count("/agents/") == 1
-                            and f.stem.lower() != "base-agent"
-                        ]
-
-                        # Build exclusion list for agents not in profile
-                        excluded_agents = []
-                        for agent_file in all_agent_files:
-                            agent_name = agent_file.stem
-                            if not profile_manager.is_agent_enabled(agent_name):
-                                excluded_agents.append(agent_name)
-
-                        if excluded_agents:
-                            # Get singleton config and update with profile settings
-                            # BUGFIX: Config is a singleton that ignores dict parameter if already initialized.
-                            # Creating Config({...}) doesn't store excluded_agents - use set() instead.
-                            deploy_config = Config()
-                            deploy_config.set("agent_deployment.excluded_agents", excluded_agents)
-                            deploy_config.set("agent_deployment.filter_non_mpm_agents", False)
-                            deploy_config.set("agent_deployment.case_sensitive", False)
-                            deploy_config.set("agent_deployment.exclude_dependencies", False)
-                            logger.info(
-                                f"Profile '{active_profile}': Excluding {len(excluded_agents)} agents from deployment"
-                            )
-
-                deployment_service = AgentDeploymentService(config=deploy_config)
-
-                # Count agents in cache to show accurate progress
                 from pathlib import Path
 
-                cache_dir = Path.home() / ".claude-mpm" / "cache" / "agents"
-                agent_count = 0
-
-                if cache_dir.exists():
-                    # BUGFIX (cache-count-inflation): Clean up stale cache files
-                    # from old repositories before counting to prevent inflated counts.
-                    # Issue: Old caches like bobmatnyc/claude-mpm-agents/agents/
-                    # were counted alongside current agents, inflating count
-                    # from 44 to 85.
-                    #
-                    # Solution: Remove files with nested /agents/ paths
-                    # (e.g., cache/agents/user/repo/agents/...)
-                    # Keep only current agents (e.g., cache/agents/engineer/...)
-                    removed_count = 0
-                    stale_dirs = set()
-
-                    for md_file in cache_dir.rglob("*.md"):
-                        # Stale cache files have multiple /agents/ in their path
-                        # Current: ~/.claude-mpm/cache/agents/engineer/...
-                        #          (1 occurrence)
-                        # Old: ~/.claude-mpm/cache/agents/bobmatnyc/.../agents/...
-                        #      (2+ occurrences)
-                        if str(md_file).count("/agents/") > 1:
-                            # Track parent directory for cleanup
-                            # Extract subdirectory under cache/agents/
-                            # (e.g., "bobmatnyc")
-                            parts = md_file.parts
-                            cache_agents_idx = parts.index("agents")
-                            if cache_agents_idx + 1 < len(parts):
-                                stale_subdir = parts[cache_agents_idx + 1]
-                                # Only remove if it's not a known category directory
-                                if stale_subdir not in [
-                                    "engineer",
-                                    "ops",
-                                    "qa",
-                                    "universal",
-                                    "documentation",
-                                    "claude-mpm",
-                                    "security",
-                                ]:
-                                    stale_dirs.add(cache_dir / stale_subdir)
-
-                            md_file.unlink()
-                            removed_count += 1
-
-                    # Remove empty stale directories
-                    for stale_dir in stale_dirs:
-                        if stale_dir.exists() and stale_dir.is_dir():
-                            try:
-                                # Remove directory and all contents
-                                import shutil
-
-                                shutil.rmtree(stale_dir)
-                            except Exception:
-                                pass  # Ignore cleanup errors
-
-                    if removed_count > 0:
-                        from loguru import logger
-
-                        logger.info(
-                            f"Cleaned up {removed_count} stale cache files "
-                            f"from old repositories"
-                        )
+                from ..core.unified_config import UnifiedConfig
+                from ..services.agents.deployment.startup_reconciliation import (
+                    perform_startup_reconciliation,
+                )
 
-                    # Count MD files in cache (agent markdown files from
-                    # current repos)
-                    # BUGFIX: Only count files in agent directories,
-                    # not docs/templates/READMEs
-                    # Valid agent paths must contain "/agents/" exactly ONCE
-                    # (current structure)
-                    # Exclude PM templates, BASE-AGENT, and documentation files
-                    pm_templates = {
-                        "base-agent.md",
-                        "circuit_breakers.md",
-                        "pm_examples.md",
-                        "pm_red_flags.md",
-                        "research_gate_examples.md",
-                        "response_format.md",
-                        "ticket_completeness_examples.md",
-                        "validation_templates.md",
-                        "git_file_tracking.md",
-                    }
-                    # Documentation files to exclude (by filename)
-                    doc_files = {
-                        "readme.md",
-                        "changelog.md",
-                        "contributing.md",
-                        "implementation-summary.md",
-                        "reorganization-plan.md",
-                        "auto-deploy-index.md",
-                    }
-
-                    # Find all markdown files (after cleanup)
-                    all_md_files = list(cache_dir.rglob("*.md"))
-
-                    # Filter to only agent files:
-                    # 1. Must have "/agents/" in path exactly ONCE
-                    #    (current structure)
-                    # 2. Must not be in PM templates or doc files
-                    # 3. Exclude BASE-AGENT.md which is not a deployable agent
-                    # 4. Exclude build artifacts (dist/, build/, .cache/)
-                    #    to prevent double-counting
-                    agent_files = [
-                        f
-                        for f in all_md_files
-                        if (
-                            # Must be in an agent directory (from current
-                            # cache structure)
-                            "/agents/" in str(f)
-                            # NEW: Only ONE /agents/ in path (excludes old
-                            # nested repos)
-                            # This prevents counting old caches like
-                            # bobmatnyc/claude-mpm-agents/agents/...
-                            and str(f).count("/agents/") == 1
-                            # Exclude PM templates, doc files, and BASE-AGENT
-                            and f.name.lower() not in pm_templates
-                            and f.name.lower() not in doc_files
-                            and f.name.lower() != "base-agent.md"
-                            # Exclude build artifacts (prevents double-counting
-                            # source + built files)
-                            and not any(
-                                part in str(f).split("/")
-                                for part in ["dist", "build", ".cache"]
-                            )
-                        )
-                    ]
-                    agent_count = len(agent_files)
-
-                if agent_count > 0:
-                    # Deploy agents to project-level directory where Claude Code expects them
-                    deploy_target = Path.cwd() / ".claude" / "agents"
-                    deployment_result = deployment_service.deploy_agents(
-                        target_dir=deploy_target,
-                        force_rebuild=False,  # Only deploy if versions differ
-                        deployment_mode="update",  # Version-aware updates
-                        config=deploy_config,  # Pass config to respect profile filtering
+                # Load configuration
+                unified_config = UnifiedConfig()
+
+                # Override with profile settings if active
+                if active_profile and profile_manager.active_profile:
+                    # Get enabled agents from profile (returns Set[str])
+                    profile_enabled_agents = (
+                        profile_manager.active_profile.get_enabled_agents()
+                    )
+                    # Update config with profile's enabled list (convert Set to List)
+                    unified_config.agents.enabled = list(profile_enabled_agents)
+                    logger.info(
+                        f"Profile '{active_profile}': Using {len(profile_enabled_agents)} enabled agents"
                     )
 
-                    # Get actual counts from deployment result (reflects configured agents)
-                    deployed = len(deployment_result.get("deployed", []))
-                    updated = len(deployment_result.get("updated", []))
-                    skipped = len(deployment_result.get("skipped", []))
-                    total_configured = deployed + updated + skipped
-
-                    # FALLBACK: If deployment result doesn't track skipped agents (async path),
-                    # count existing agents in target directory as "already deployed"
-                    # This ensures accurate reporting when agents are already up-to-date
-                    if total_configured == 0 and deploy_target.exists():
-                        existing_agents = list(deploy_target.glob("*.md"))
-                        # Filter out non-agent files (e.g., README.md, INSTRUCTIONS.md)
-                        agent_count_in_target = len(
-                            [
-                                f
-                                for f in existing_agents
-                                if not f.name.startswith(("README", "INSTRUCTIONS"))
-                            ]
-                        )
-                        if agent_count_in_target > 0:
-                            # All agents already deployed - count them as skipped
-                            skipped = agent_count_in_target
-                            total_configured = agent_count_in_target
+                # Perform reconciliation to deploy configured agents
+                project_path = Path.cwd()
+                agent_result, _skill_result = perform_startup_reconciliation(
+                    project_path=project_path, config=unified_config, silent=False
+                )
 
-                    # Create progress bar with actual configured agent count (not raw file count)
+                # Display results with progress bar
+                total_operations = (
+                    len(agent_result.deployed)
+                    + len(agent_result.removed)
+                    + len(agent_result.unchanged)
+                )
+
+                if total_operations > 0:
                     deploy_progress = ProgressBar(
-                        total=total_configured if total_configured > 0 else 1,
+                        total=total_operations,
                         prefix="Deploying agents",
                         show_percentage=True,
                         show_counter=True,
                     )
-
-                    # Update progress bar to completion
-                    deploy_progress.update(
-                        total_configured if total_configured > 0 else 1
-                    )
-
-                    # Cleanup orphaned agents (ours but no longer deployed)
-                    # Get list of deployed agent filenames (what should remain)
-                    deployed_filenames = []
-                    for agent_name in deployment_result.get("deployed", []):
-                        deployed_filenames.append(f"{agent_name}.md")
-                    for agent_name in deployment_result.get("updated", []):
-                        deployed_filenames.append(f"{agent_name}.md")
-                    for agent_name in deployment_result.get("skipped", []):
-                        deployed_filenames.append(f"{agent_name}.md")
-
-                    # Run cleanup and get count of removed agents
-                    removed = _cleanup_orphaned_agents(
-                        deploy_target, deployed_filenames
+                    deploy_progress.update(total_operations)
+
+                    # Build summary message
+                    deployed = len(agent_result.deployed)
+                    removed = len(agent_result.removed)
+                    unchanged = len(agent_result.unchanged)
+
+                    summary_parts = []
+                    if deployed > 0:
+                        summary_parts.append(f"{deployed} new")
+                    if removed > 0:
+                        summary_parts.append(f"{removed} removed")
+                    if unchanged > 0:
+                        summary_parts.append(f"{unchanged} unchanged")
+
+                    summary = f"Complete: {', '.join(summary_parts)}"
+                    deploy_progress.finish(summary)
+
+                # Display errors if any
+                if agent_result.errors:
+                    logger.warning(
+                        f"Agent deployment completed with {len(agent_result.errors)} errors"
                     )
+                    print("\n⚠️  Agent Deployment Errors:")
+                    max_errors_to_show = 10
+                    errors_to_display = agent_result.errors[:max_errors_to_show]
 
-                    # Show total configured agents (deployed + updated + already existing)
-                    # Include cache count for context and removed count if any
-                    if deployed > 0 or updated > 0:
-                        if removed > 0:
-                            deploy_progress.finish(
-                                f"Complete: {deployed} new, {updated} updated, {skipped} unchanged, "
-                                f"{removed} removed ({total_configured} configured from {agent_count} files in cache)"
-                            )
-                        else:
-                            deploy_progress.finish(
-                                f"Complete: {deployed} new, {updated} updated, {skipped} unchanged "
-                                f"({total_configured} configured from {agent_count} files in cache)"
-                            )
-                    elif removed > 0:
-                        deploy_progress.finish(
-                            f"Complete: {total_configured} agents deployed, "
-                            f"{removed} removed ({agent_count} files in cache)"
-                        )
-                    else:
-                        deploy_progress.finish(
-                            f"Complete: {total_configured} agents deployed "
-                            f"({agent_count} files in cache)"
-                        )
-
-                    # Display deployment errors to user (not just logs)
-                    deploy_errors = deployment_result.get("errors", [])
-                    if deploy_errors:
-                        # Log for debugging
-                        logger.warning(
-                            f"Agent deployment completed with {len(deploy_errors)} errors: {deploy_errors}"
-                        )
-
-                        # Display errors to user with clear formatting
-                        print("\n⚠️  Agent Deployment Errors:")
-
-                        # Show first 10 errors to avoid overwhelming output
-                        max_errors_to_show = 10
-                        errors_to_display = deploy_errors[:max_errors_to_show]
+                    for error in errors_to_display:
+                        print(f"   - {error}")
 
-                        for error in errors_to_display:
-                            # Format error message for readability
-                            # Errors typically come as strings like "agent.md: Error message"
-                            print(f"   - {error}")
+                    if len(agent_result.errors) > max_errors_to_show:
+                        remaining = len(agent_result.errors) - max_errors_to_show
+                        print(f"   ... and {remaining} more error(s)")
 
-                        # If more errors exist, show count
-                        if len(deploy_errors) > max_errors_to_show:
-                            remaining = len(deploy_errors) - max_errors_to_show
-                            print(f"   ... and {remaining} more error(s)")
+                    print(
+                        f"\n❌ Failed to deploy {len(agent_result.errors)} agent(s). "
+                        "Please check the error messages above."
+                    )
+                    print("   Run with --verbose for detailed error information.\n")
 
-                        # Show summary message
-                        print(
-                            f"\n❌ Failed to deploy {len(deploy_errors)} agent(s). Please check the error messages above."
-                        )
-                        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
@@ -830,6 +836,11 @@ def sync_remote_agents_on_startup():
                 logger = get_logger("cli")
                 logger.warning(f"Failed to deploy agents from cache: {e}")
 
+        # Phase 4: Cleanup legacy agent cache directories (after sync/deployment)
+        # CRITICAL: This must run AFTER sync completes because sync may recreate
+        # legacy directories. Running cleanup here ensures they're removed.
+        cleanup_legacy_agent_cache()
+
     except Exception as e:
         # Non-critical - log but don't fail startup
         from ..core.logger import get_logger
@@ -838,8 +849,14 @@ def sync_remote_agents_on_startup():
         logger.debug(f"Failed to sync remote agents: {e}")
         # Continue execution - agent sync failure shouldn't block startup
 
+        # Cleanup legacy cache even if sync failed
+        try:
+            cleanup_legacy_agent_cache()
+        except Exception:  # nosec B110
+            pass  # Ignore cleanup errors
+
 
-def sync_remote_skills_on_startup():
+def sync_remote_skills_on_startup(force_sync: bool = False):
     """
     Synchronize skill templates from remote sources on startup.
 
@@ -857,6 +874,9 @@ def sync_remote_skills_on_startup():
     4. Apply profile filtering if active
     5. Deploy resolved skills to ~/.claude/skills/ - Phase 2 progress bar
     6. Log deployment results with source indication
+
+    Args:
+        force_sync: Force download even if cache is fresh (bypasses ETag).
     """
     try:
         from pathlib import Path
@@ -962,7 +982,7 @@ def sync_remote_skills_on_startup():
 
         # Sync all sources with progress callback
         results = manager.sync_all_sources(
-            force=False, progress_callback=sync_progress.update
+            force=force_sync, progress_callback=sync_progress.update
         )
 
         # Finish sync progress bar with clear breakdown
@@ -982,150 +1002,191 @@ def sync_remote_skills_on_startup():
 
         # Phase 2: Scan agents and save to configuration.yaml
         # This step populates configuration.yaml with agent-referenced skills
-        if results["synced_count"] > 0:
-            agents_dir = Path.cwd() / ".claude" / "agents"
-
-            # Scan agents for skill requirements
-            agent_skills = get_required_skills_from_agents(agents_dir)
-
-            # Save to project-level configuration.yaml
-            project_config_path = Path.cwd() / ".claude-mpm" / "configuration.yaml"
-            save_agent_skills_to_config(list(agent_skills), project_config_path)
-
-            # Phase 3: Resolve which skills to deploy (user_defined or agent_referenced)
-            skills_to_deploy, skill_source = get_skills_to_deploy(project_config_path)
-
-            # Phase 4: Apply profile filtering if active
-            if active_profile and profile_manager.active_profile:
-                # Filter skills based on profile
-                if skills_to_deploy:
-                    # Filter the resolved skill list
-                    original_count = len(skills_to_deploy)
-                    filtered_skills = [
-                        skill
-                        for skill in skills_to_deploy
-                        if profile_manager.is_skill_enabled(skill)
-                    ]
-                    filtered_count = original_count - len(filtered_skills)
+        # CRITICAL: Always scan agents to populate agent_referenced, even when using cached skills.
+        # Without this, skill_filter=None causes ALL skills to deploy and NO cleanup to run.
+        agents_dir = Path.cwd() / ".claude" / "agents"
+
+        # Scan agents for skill requirements (ALWAYS run to ensure cleanup works)
+        agent_skills = get_required_skills_from_agents(agents_dir)
+        logger.info(
+            f"Agent scan found {len(agent_skills)} unique skills across deployed agents"
+        )
 
-                    # SAFEGUARD: Warn if all skills were filtered out (misconfiguration)
-                    if not filtered_skills and original_count > 0:
-                        logger.warning(
-                            f"Profile '{active_profile}' filtered ALL {original_count} skills. "
-                            f"This may indicate a naming mismatch in the profile."
-                        )
-                    elif filtered_count > 0:
-                        logger.info(
-                            f"Profile '{active_profile}' filtered {filtered_count} skills "
-                            f"({len(filtered_skills)} remaining)"
-                        )
+        # Save to project-level configuration.yaml
+        project_config_path = Path.cwd() / ".claude-mpm" / "configuration.yaml"
+        save_agent_skills_to_config(list(agent_skills), project_config_path)
+        logger.debug(
+            f"Saved {len(agent_skills)} agent-referenced skills to {project_config_path}"
+        )
 
-                    skills_to_deploy = filtered_skills
-                    skill_source = f"{skill_source} + profile filtered"
-                else:
-                    # No explicit skill list - filter from all available
-                    all_skills = manager.get_all_skills()
-                    filtered_skills = [
-                        skill["name"]
-                        for skill in all_skills
-                        if profile_manager.is_skill_enabled(skill["name"])
-                    ]
-                    skills_to_deploy = filtered_skills
-                    skill_source = "profile filtered"
+        # Phase 3: Resolve which skills to deploy (user_defined or agent_referenced)
+        skills_to_deploy, skill_source = get_skills_to_deploy(project_config_path)
+
+        # CRITICAL DEBUG: Log deployment resolution to diagnose cleanup issues
+        if skills_to_deploy:
+            logger.info(
+                f"Resolved {len(skills_to_deploy)} skills from {skill_source} (cleanup will run)"
+            )
+        else:
+            logger.warning(
+                f"No skills resolved from {skill_source} - will deploy ALL skills WITHOUT cleanup! "
+                f"This may indicate agent_referenced is empty in configuration.yaml."
+            )
+
+        # Phase 4: Apply profile filtering if active
+        if active_profile and profile_manager.active_profile:
+            # Filter skills based on profile
+            if skills_to_deploy:
+                # Filter the resolved skill list
+                original_count = len(skills_to_deploy)
+                filtered_skills = [
+                    skill
+                    for skill in skills_to_deploy
+                    if profile_manager.is_skill_enabled(skill)
+                ]
+                filtered_count = original_count - len(filtered_skills)
+
+                # SAFEGUARD: Warn if all skills were filtered out (misconfiguration)
+                if not filtered_skills and original_count > 0:
+                    logger.warning(
+                        f"Profile '{active_profile}' filtered ALL {original_count} skills. "
+                        f"This may indicate a naming mismatch in the profile."
+                    )
+                elif filtered_count > 0:
                     logger.info(
-                        f"Profile '{active_profile}': "
-                        f"{len(filtered_skills)} skills enabled from {len(all_skills)} available"
+                        f"Profile '{active_profile}' filtered {filtered_count} skills "
+                        f"({len(filtered_skills)} remaining)"
                     )
 
-            # Get all skills to determine counts
-            all_skills = manager.get_all_skills()
-            total_skill_count = len(all_skills)
+                skills_to_deploy = filtered_skills
+                skill_source = f"{skill_source} + profile filtered"
+            else:
+                # No explicit skill list - filter from all available
+                all_skills = manager.get_all_skills()
+                filtered_skills = [
+                    skill["name"]
+                    for skill in all_skills
+                    if profile_manager.is_skill_enabled(skill["name"])
+                ]
+                skills_to_deploy = filtered_skills
+                skill_source = "profile filtered"
+                logger.info(
+                    f"Profile '{active_profile}': "
+                    f"{len(filtered_skills)} skills enabled from {len(all_skills)} available"
+                )
 
-            # Determine skill count based on resolution
-            skill_count = (
-                len(skills_to_deploy) if skills_to_deploy else total_skill_count
+        # Get all skills to determine counts
+        all_skills = manager.get_all_skills()
+        total_skill_count = len(all_skills)
+
+        # Determine skill count based on resolution
+        skill_count = len(skills_to_deploy) if skills_to_deploy else total_skill_count
+
+        if skill_count > 0:
+            # Deploy skills with resolved filter
+            # Deploy ONLY to project directory (not user-level)
+            # DESIGN DECISION: Project-level deployment keeps skills isolated per project,
+            # avoiding pollution of user's global ~/.claude/skills/ directory.
+
+            # Deploy to project-local directory with cleanup
+            deployment_result = manager.deploy_skills(
+                target_dir=Path.cwd() / ".claude" / "skills",
+                force=force_sync,
+                # CRITICAL FIX: Empty list should mean "deploy no skills", not "deploy all"
+                # When skills_to_deploy is [], we want skill_filter=set() NOT skill_filter=None
+                # None means "no filtering" (deploy all), empty set means "filter to nothing"
+                skill_filter=set(skills_to_deploy)
+                if skills_to_deploy is not None
+                else None,
             )
 
-            if skill_count > 0:
-                # Deploy skills with resolved filter
-                # Deploy to project directory (like agents), not user directory
-                deployment_result = manager.deploy_skills(
-                    target_dir=Path.cwd() / ".claude" / "skills",
-                    force=False,
-                    skill_filter=set(skills_to_deploy) if skills_to_deploy else None,
+            # REMOVED: User-level deployment (lines 1068-1074)
+            # Reason: Skills should be project-specific, not user-global.
+            # Claude Code can read from project-level .claude/skills/ directory.
+
+            # Get actual counts from deployment result (use project-local for display)
+            deployed = deployment_result.get("deployed_count", 0)
+            skipped = deployment_result.get("skipped_count", 0)
+            filtered = deployment_result.get("filtered_count", 0)
+            removed = deployment_result.get("removed_count", 0)
+            total_available = deployed + skipped
+
+            # Only show progress bar if there are skills to deploy
+            if total_available > 0:
+                deploy_progress = ProgressBar(
+                    total=total_available,
+                    prefix="Deploying skill directories",
+                    show_percentage=True,
+                    show_counter=True,
+                )
+                # Update progress bar to completion
+                deploy_progress.update(total_available)
+            else:
+                # No skills to deploy - create dummy progress for message only
+                deploy_progress = ProgressBar(
+                    total=1,
+                    prefix="Deploying skill directories",
+                    show_percentage=False,
+                    show_counter=False,
                 )
+                deploy_progress.update(1)
 
-                # Get actual counts from deployment result
-                deployed = deployment_result.get("deployed_count", 0)
-                skipped = deployment_result.get("skipped_count", 0)
-                filtered = deployment_result.get("filtered_count", 0)
-                total_available = deployed + skipped
+            # Show total available skills (deployed + already existing)
+            # Include source indication (user_defined vs agent_referenced)
+            # Note: total_skill_count is from cache, total_available is what's deployed/needed
+            source_label = (
+                "user override" if skill_source == "user_defined" else "from agents"
+            )
 
-                # Only show progress bar if there are skills to deploy
-                if total_available > 0:
-                    deploy_progress = ProgressBar(
-                        total=total_available,
-                        prefix="Deploying skill directories",
-                        show_percentage=True,
-                        show_counter=True,
-                    )
-                    # Update progress bar to completion
-                    deploy_progress.update(total_available)
-                else:
-                    # No skills to deploy - create dummy progress for message only
-                    deploy_progress = ProgressBar(
-                        total=1,
-                        prefix="Deploying skill directories",
-                        show_percentage=False,
-                        show_counter=False,
-                    )
-                    deploy_progress.update(1)
+            # Build finish message with cleanup info
+            if deployed > 0 or removed > 0:
+                parts = []
+                if deployed > 0:
+                    parts.append(f"{deployed} new")
+                if skipped > 0:
+                    parts.append(f"{skipped} unchanged")
+                if removed > 0:
+                    parts.append(f"{removed} removed")
 
-                # Show total available skills (deployed + already existing)
-                # Include source indication (user_defined vs agent_referenced)
-                # Note: total_skill_count is from cache, total_available is what's deployed/needed
-                source_label = (
-                    "user override" if skill_source == "user_defined" else "from agents"
-                )
+                status = ", ".join(parts)
 
-                if deployed > 0:
-                    if filtered > 0:
-                        deploy_progress.finish(
-                            f"Complete: {deployed} new, {skipped} unchanged "
-                            f"({total_available} {source_label}, {filtered} files in cache)"
-                        )
-                    else:
-                        deploy_progress.finish(
-                            f"Complete: {deployed} new, {skipped} unchanged "
-                            f"({total_available} skills {source_label} from {total_skill_count} files in cache)"
-                        )
-                elif filtered > 0:
-                    # Skills filtered means agents require fewer skills than available
+                if filtered > 0:
                     deploy_progress.finish(
-                        f"No skills needed ({source_label}, {total_skill_count} files in cache)"
+                        f"Complete: {status} ({total_available} {source_label}, {filtered} files in cache)"
                     )
                 else:
                     deploy_progress.finish(
-                        f"Complete: {total_available} skills {source_label} "
-                        f"({total_skill_count} files in cache)"
+                        f"Complete: {status} ({total_available} skills {source_label} from {total_skill_count} files in cache)"
                     )
+            elif filtered > 0:
+                # Skills filtered means agents require fewer skills than available
+                deploy_progress.finish(
+                    f"No skills needed ({source_label}, {total_skill_count} files in cache)"
+                )
+            else:
+                # No changes - all skills already deployed
+                msg = f"Complete: {total_available} skills {source_label}"
+                if removed > 0:
+                    msg += f", {removed} removed"
+                msg += f" ({total_skill_count} files in cache)"
+                deploy_progress.finish(msg)
+
+            # Log deployment errors if any
+            from ..core.logger import get_logger
 
-                # Log deployment errors if any
-                from ..core.logger import get_logger
-
-                logger = get_logger("cli")
+            logger = get_logger("cli")
 
-                errors = deployment_result.get("errors", [])
-                if errors:
-                    logger.warning(
-                        f"Skill deployment completed with {len(errors)} errors: {errors}"
-                    )
+            errors = deployment_result.get("errors", [])
+            if errors:
+                logger.warning(
+                    f"Skill deployment completed with {len(errors)} errors: {errors}"
+                )
 
-                # Log sync errors if any
-                if results["failed_count"] > 0:
-                    logger.warning(
-                        f"Skill sync completed with {results['failed_count']} failures"
-                    )
+            # Log sync errors if any
+            if results["failed_count"] > 0:
+                logger.warning(
+                    f"Skill sync completed with {results['failed_count']} failures"
+                )
 
     except Exception as e:
         # Non-critical - log but don't fail startup
@@ -1208,7 +1269,7 @@ def show_agent_summary():
         # Display summary if we have agents
         if installed_count > 0 or available_count > 0:
             print(
-                f"✓ Agents: {installed_count} deployed / {available_count} cached",
+                f"✓ Agents: {installed_count} deployed / {max(0, available_count - installed_count)} cached",
                 flush=True,
             )
 
@@ -1225,61 +1286,64 @@ def show_skill_summary():
     Display skill availability summary on startup.
 
     WHY: Users should see at a glance how many skills are deployed and available
-    from collections, similar to the agent summary.
+    from cache, similar to the agent summary showing "X deployed / Y cached".
+
+    DESIGN DECISION: Fast, non-blocking check that counts skills from:
+    - Deployed skills: PROJECT-level .claude/skills/ directory
+    - Cached skills: ~/.claude-mpm/cache/skills/ directory (from remote sources)
 
-    DESIGN DECISION: Fast, non-blocking check that counts skills from deployment
-    directory and collection repos. Shows "X installed (Y available)" format.
+    Shows format: "✓ Skills: X deployed / Y cached"
     Failures are silent to avoid blocking startup.
     """
     try:
         from pathlib import Path
 
-        # Count deployed skills (installed)
-        skills_dir = Path.home() / ".claude" / "skills"
-        installed_count = 0
-        if skills_dir.exists():
+        # Count deployed skills (PROJECT-level, not user-level)
+        project_skills_dir = Path.cwd() / ".claude" / "skills"
+        deployed_count = 0
+        if project_skills_dir.exists():
             # Count directories with SKILL.md (excludes collection repos)
             # Exclude collection directories (obra-superpowers, etc.)
             skill_dirs = [
                 d
-                for d in skills_dir.iterdir()
+                for d in project_skills_dir.iterdir()
                 if d.is_dir()
                 and (d / "SKILL.md").exists()
                 and not (d / ".git").exists()  # Exclude collection repos
             ]
-            installed_count = len(skill_dirs)
+            deployed_count = len(skill_dirs)
 
-        # Count available skills in collections
-        available_count = 0
-        if skills_dir.exists():
-            # Scan all collection directories (those with .git)
-            for collection_dir in skills_dir.iterdir():
-                if (
-                    not collection_dir.is_dir()
-                    or not (collection_dir / ".git").exists()
-                ):
+        # Count cached skills (from remote sources, not deployed yet)
+        # This matches the agent summary pattern: deployed vs cached
+        cache_dir = Path.home() / ".claude-mpm" / "cache" / "skills"
+        cached_count = 0
+        if cache_dir.exists():
+            # Scan all repository directories in cache
+            # Cache structure: ~/.claude-mpm/cache/skills/{owner}/{repo}/...
+            for repo_dir in cache_dir.rglob("*"):
+                if not repo_dir.is_dir():
                     continue
 
-                # Count skill directories in this collection
+                # Count skill directories (those with SKILL.md)
                 # Skills can be nested in: skills/category/skill-name/SKILL.md
                 # or in flat structure: skill-name/SKILL.md
-                for root, dirs, files in os.walk(collection_dir):
+                for root, dirs, files in os.walk(repo_dir):
                     if "SKILL.md" in files:
-                        # Exclude build artifacts and hidden directories (within the collection)
-                        # Get relative path from collection_dir to avoid excluding based on .claude parent
+                        # Exclude build artifacts and hidden directories
                         root_path = Path(root)
-                        relative_parts = root_path.relative_to(collection_dir).parts
                         if not any(
                             part.startswith(".")
                             or part in ["dist", "build", "__pycache__"]
-                            for part in relative_parts
+                            for part in root_path.parts
                         ):
-                            available_count += 1
+                            cached_count += 1
 
-        # Display summary if we have skills
-        if installed_count > 0 or available_count > 0:
+        # Display summary using agent summary format: "X deployed / Y cached"
+        # Only show non-deployed cached skills (subtract deployed from cached)
+        non_deployed_cached = max(0, cached_count - deployed_count)
+        if deployed_count > 0 or non_deployed_cached > 0:
             print(
-                f"✓ Skills: {installed_count} installed ({available_count} available)",
+                f"✓ Skills: {deployed_count} deployed / {non_deployed_cached} cached",
                 flush=True,
             )
 
@@ -1292,33 +1356,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 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.
 
-    WHY: PM skills are essential for PM agent operation.
-    Shows deployment status and auto-deploys if missing.
+    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(f"\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
@@ -1353,7 +1458,7 @@ def auto_install_chrome_devtools_on_startup():
             if not chrome_devtools_config.get("auto_install", True):
                 # Auto-install disabled, skip silently
                 return
-        except Exception:
+        except Exception:  # nosec B110
             # If config loading fails, assume auto-install is enabled (default)
             pass
 
@@ -1371,7 +1476,29 @@ def auto_install_chrome_devtools_on_startup():
         # Continue execution - chrome-devtools installation failure shouldn't block startup
 
 
-def run_background_services():
+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.
 
@@ -1382,18 +1509,19 @@ def run_background_services():
     explicitly requests them via agent-manager commands. This prevents unwanted
     file creation in project .claude/ directories.
     See: SystemInstructionsDeployer and agent_deployment.py line 504-509
+
+    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... ✓"
+    # 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()  # 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)
@@ -1401,7 +1529,9 @@ def run_background_services():
     # 3. Discover and link runtime skills (user-added skills)
     # This ensures remote skills take precedence over bundled skills when names conflict
     deploy_bundled_skills()  # Base layer: package-bundled skills
-    sync_remote_skills_on_startup()  # Override layer: Git-based skills (takes precedence)
+    sync_remote_skills_on_startup(
+        force_sync=force_sync
+    )  # Override layer: Git-based skills (takes precedence)
     discover_and_link_runtime_skills()  # Discovery: user-added skills
     show_skill_summary()  # Display skill counts after deployment
     verify_and_show_pm_skills()  # PM skills verification and status
@@ -1503,7 +1633,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
@@ -1514,11 +1646,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
@@ -1601,7 +1739,7 @@ def verify_mcp_gateway_startup():
                                 loop.run_until_complete(
                                     asyncio.gather(*pending, return_exceptions=True)
                                 )
-                        except Exception:
+                        except Exception:  # nosec B110
                             pass  # Ignore cleanup errors
                         finally:
                             loop.close()
@@ -1695,7 +1833,7 @@ def check_for_updates_async():
 
                 logger = get_logger("upgrade_check")
                 logger.debug(f"Update check failed (non-critical): {e}")
-            except Exception:
+            except Exception:  # nosec B110
                 pass  # Avoid any errors in error handling
         finally:
             # Properly clean up event loop
@@ -1710,7 +1848,7 @@ def check_for_updates_async():
                         loop.run_until_complete(
                             asyncio.gather(*pending, return_exceptions=True)
                         )
-                except Exception:
+                except Exception:  # nosec B110
                     pass  # Ignore cleanup errors
                 finally:
                     loop.close()