claude-mpm 4.11.0__py3-none-any.whl → 4.11.1__py3-none-any.whl

claude_mpm/cli/parsers/mpm_init_parser.py

@@ -31,8 +31,7 @@ def add_mpm_init_subparser(subparsers: Any) -> None:
         epilog=(
             "Examples:\n"
             "  claude-mpm mpm-init                                    # Initialize/update current directory\n"
-            "  claude-mpm mpm-init pause                              # Pause current session\n"
-            "  claude-mpm mpm-init resume                             # Resume latest session\n"
+            "  claude-mpm mpm-init --catchup                          # Show recent git history for context\n"
             "  claude-mpm mpm-init --review                           # Review project state without changes\n"
             "  claude-mpm mpm-init --update                           # Update existing CLAUDE.md\n"
             "  claude-mpm mpm-init --quick-update                     # Quick update based on recent git activity\n"
@@ -207,55 +206,57 @@ def add_mpm_init_subparser(subparsers: Any) -> None:
         help="Path to project directory (default: current directory)",
     )
 
-    # Add subparsers for pause/resume commands
+    # Add subparsers for context commands
     subcommands = mpm_init_parser.add_subparsers(
         dest="subcommand",
-        title="session management",
-        description="Commands for managing session pause/resume",
+        title="context management",
+        description="Commands for managing project context",
     )
 
-    # Pause subcommand
-    pause_parser = subcommands.add_parser(
-        "pause",
-        help="Pause current session and save state",
-        description="Pause the current session and capture state for later resumption",
-    )
-    pause_parser.add_argument(
-        "--summary",
-        "-s",
+    # Context subcommand (primary name)
+    context_parser = subcommands.add_parser(
+        "context",
+        help="Provide intelligent context for resuming work",
+        description="Analyze git history to provide context for resuming work",
+        epilog="Note: 'resume' is deprecated, use 'context' instead",
+    )
+    context_parser.add_argument(
+        "--session-id",
+        "-i",
         type=str,
-        help="Summary of what you were working on",
-    )
-    pause_parser.add_argument(
-        "--accomplishment",
-        "-a",
-        action="append",
-        help="Accomplishment from this session (can be used multiple times)",
+        help="Unused (for compatibility) - will be removed in future version",
     )
-    pause_parser.add_argument(
-        "--next-step",
-        "-n",
-        action="append",
-        help="Next step to continue work (can be used multiple times)",
+    context_parser.add_argument(
+        "--days",
+        type=int,
+        default=7,
+        help="Number of days of git history to analyze (default: 7)",
     )
-    pause_parser.add_argument(
+    context_parser.add_argument(
         "project_path",
         nargs="?",
         default=".",
         help="Path to project directory (default: current directory)",
     )
 
-    # Resume subcommand
+    # Resume subcommand (deprecated alias for backward compatibility)
     resume_parser = subcommands.add_parser(
         "resume",
-        help="Resume a paused session",
-        description="Resume the most recent (or specified) paused session",
+        help="[DEPRECATED] Use 'context' instead",
+        description="[DEPRECATED] This command is deprecated. Use 'context' instead.\n\n"
+        "Analyze git history to provide context for resuming work",
     )
     resume_parser.add_argument(
         "--session-id",
         "-i",
         type=str,
-        help="Specific session ID to resume (defaults to most recent)",
+        help="Unused (for compatibility) - will be removed in future version",
+    )
+    resume_parser.add_argument(
+        "--days",
+        type=int,
+        default=7,
+        help="Number of days of git history to analyze (default: 7)",
     )
     resume_parser.add_argument(
         "project_path",

claude_mpm/commands/mpm-init.md

@@ -7,10 +7,9 @@ Initialize or intelligently update your project for optimal use with Claude Code
 ```
 /mpm-init                      # Auto-detects and offers update or create
 /mpm-init update               # Lightweight update based on recent git activity
-/mpm-init catchup              # Show recent commit history for context
-/mpm-init pause                # Pause session and save state
-/mpm-init resume               # Resume most recent paused session
-/mpm-init resume --list        # List all paused sessions
+/mpm-init context              # Intelligent context analysis from git history
+/mpm-init context --days 14    # Analyze last 14 days of git history
+/mpm-init catchup              # Quick commit history display (no analysis)
 /mpm-init --review             # Review project state without changes
 /mpm-init --update             # Full update of existing CLAUDE.md
 /mpm-init --organize           # Organize project structure
@@ -21,7 +20,11 @@ Initialize or intelligently update your project for optimal use with Claude Code
 
 ## Description
 
-This command delegates to the Agentic Coder Optimizer agent to establish clear, single-path project standards for documentation, tooling, and workflows.
+This command has two primary modes:
+- **Project initialization/updates**: Delegates to the Agentic Coder Optimizer agent for documentation, tooling, and workflow setup
+- **Context analysis** (context/catchup): Provides intelligent project context from git history for resuming work
+
+**Note**: The `resume` subcommand is deprecated. Use `context` instead. The `resume` command still works for backward compatibility but will be removed in a future version.
 
 **Quick Update Mode**: Running `/mpm-init update` performs a lightweight update focused on recent git activity. It analyzes recent commits, generates an activity report, and updates documentation with minimal changes. Perfect for quick refreshes after development sprints.
 
@@ -58,6 +61,46 @@ This command delegates to the Agentic Coder Optimizer agent to establish clear,
 - `--no-preserve-custom`: Don't preserve custom sections
 - `--skip-archive`: Skip archiving existing files before updating
 
+## Context Analysis
+
+**Purpose**: Provide intelligent project context for resuming work by analyzing git history.
+
+### Commands
+
+#### `/mpm-init context` (Primary)
+```bash
+/mpm-init context                  # Analyze last 7 days of git history
+/mpm-init context --days 14        # Analyze last 14 days
+```
+
+Analyzes recent git commits to identify:
+- **Active work streams**: What was being worked on (themes from commit patterns)
+- **Intent and motivation**: Why this work matters (from commit messages)
+- **Risks and blockers**: What needs attention (stalled work, conflicts, anti-patterns)
+- **Recommended next actions**: What to work on next (logical continuations)
+
+**How it works**:
+1. Parses git history (default: last 7 days)
+2. PM delegates to Research agent with structured prompt
+3. Research analyzes work streams, intent, risks, recommendations
+4. PM presents intelligent summary for seamless work resumption
+
+**NOT session state**: This does NOT save/restore conversation state like Claude Code. Instead, it reconstructs project context from git history using conventional commits and commit message analysis.
+
+#### `/mpm-init resume` [DEPRECATED]
+Alias for `context`. Use `context` instead.
+
+### `/mpm-init catchup` (Simple Git History)
+```bash
+/mpm-init catchup
+```
+
+Quick display of last 25 commits across all branches. No analysis - just raw git log output with authors and dates. Use this for quick "what happened recently?" checks.
+
+**Distinction**:
+- **catchup**: Quick commit history (instant, no analysis)
+- **context**: Intelligent work resumption (10-30s, deep analysis)
+
 ## What This Command Does
 
 ### Auto-Detection (NEW)
@@ -150,92 +193,52 @@ Fast update based on recent 30-day git activity. Generates activity report and u
 
 **Note**: Typing `/mpm-init update` executes `claude-mpm mpm-init --quick-update` automatically.
 
-### Catchup Mode
+### Context Analysis (Intelligent Resumption)
 
-Show recent commit history to provide PM with project context:
+Get intelligent context for resuming work based on git history analysis:
 
+**Standard Context Analysis:**
 ```bash
-/mpm-init catchup
+/mpm-init context              # Analyze last 7 days (default)
+/mpm-init context --days 14    # Analyze last 14 days
+/mpm-init context --days 30    # Analyze last 30 days
 ```
 
-This displays:
-- Last 25 commits from all branches
-- Author attribution (WHO did WHAT)
-- Temporal context (WHEN)
-- Contributor activity summary
-- PM recommendations based on commit patterns
-
-Useful for understanding recent development activity and getting PM up to speed on project changes.
-
-### Session Management (Pause/Resume)
+This provides intelligent analysis including:
+- **Work stream identification** from commit patterns
+- **Intent analysis** (why work was done)
+- **Risk detection** (stalled work, conflicts, etc.)
+- **Recommended next actions** for seamless continuation
 
-Save and restore session state across Claude sessions:
+**How it works:**
+1. Parses git history (7 days default)
+2. PM delegates to Research agent with structured prompt
+3. Research agent provides deep analysis
+4. PM presents intelligent summary
 
-**Pause Current Session:**
-```bash
-/mpm-init pause
-```
-
-This captures and saves:
-- Conversation context and progress
-- Current git repository state
-- Active and completed todo items
-- Working directory status
-- Session timestamp and metadata
+**NOT session state**: This reconstructs context from git history, not saved conversation state.
 
-**Resume Previous Session:**
+**Backward Compatibility:**
 ```bash
-/mpm-init resume
+/mpm-init resume               # Still works but deprecated
 ```
 
-This loads and analyzes:
-- Most recent (or specified) paused session
-- Changes since pause (git commits, file modifications)
-- Potential conflicts or warnings
-- Full context for seamless continuation
+The old `resume` command redirects to `context` with a deprecation warning.
 
-**Pause Options:**
-- `-s, --summary TEXT`: Provide session summary
-- `-a, --accomplishment TEXT`: Record accomplishments (can be used multiple times)
-- `-n, --next-step TEXT`: Document next steps (can be used multiple times)
-- `--no-commit`: Skip creating git commit with session info
+### Quick Git History (Catchup)
 
-**Resume Options:**
-- `--session-id TEXT`: Resume specific session by ID
-- `--list`: List all available paused sessions
+Display recent commit history without analysis:
 
-**Example Usage:**
 ```bash
-# Pause with detailed context
-/mpm-init pause -s "Implemented authentication system" \
-  -a "Added login endpoint" \
-  -a "Created user model" \
-  -a "Wrote integration tests" \
-  -n "Add logout endpoint" \
-  -n "Implement password reset"
-
-# Resume latest session
-/mpm-init resume
-
-# List available sessions
-/mpm-init resume --list
-
-# Resume specific session
-/mpm-init resume --session-id session-20251020-012501
+/mpm-init catchup
 ```
 
-**Session Storage:**
-- Sessions saved in `.claude-mpm/sessions/pause/`
-- JSON format with secure permissions (0600)
-- Includes checksums for data integrity
-- Automatic git commit creation (unless `--no-commit`)
+Shows:
+- Last 25 commits from all branches
+- Author attribution and timestamps
+- Contributor activity summary
 
-**Use Cases:**
-- **Context Continuity**: Maintain context across multiple Claude sessions
-- **Team Handoffs**: Save state before passing work to another team member
-- **Long-running Projects**: Track progress over multiple work sessions
-- **Break Points**: Document progress at natural stopping points
-- **Change Awareness**: Detect what changed while you were away
+Use this for quick "what happened recently?" checks. For intelligent analysis, use `context` instead.
 
 ### Review Project State
 ```bash
@@ -284,6 +287,49 @@ Quick initialization without code analysis.
 
 This command routes between different modes:
 
+### Context Analysis Commands
+
+**IMPORTANT**: Context analysis commands (`/mpm-init context`, `/mpm-init catchup`) have distinct behaviors:
+
+**`/mpm-init context` - Delegates to PM**:
+```bash
+claude-mpm mpm-init context --days 7
+```
+
+This command delegates work to the PM framework:
+1. Parses git history (7 days default)
+2. PM constructs structured Research delegation prompt
+3. PM presents prompt for Research agent to analyze
+4. Research identifies work streams, intent, risks, recommendations
+5. PM synthesizes for user
+
+This is intelligent analysis requiring Research agent expertise.
+
+**How the PM delegates to Research:**
+The PM creates a delegation prompt that asks Research to analyze:
+- **Work Stream Identification**: Groups related commits into themes
+- **Intent Analysis**: Infers why work was done from commit messages
+- **Risk Detection**: Identifies stalled work, conflicts, and blockers
+- **Recommended Actions**: Suggests logical next steps for continuation
+
+**`/mpm-init catchup` - Direct CLI execution**:
+```bash
+claude-mpm mpm-init catchup
+```
+
+This executes directly via CLI without agent delegation:
+- Displays last 25 commits from all branches
+- Shows authors, dates, commit messages
+- Instant output (no analysis)
+
+This is a simple git log display utility.
+
+---
+
+### Project Initialization/Update Commands
+
+**IMPORTANT**: Standard initialization and update commands delegate to the Agentic Coder Optimizer agent.
+
 **Quick Update Mode** (`/mpm-init update`):
 ```bash
 claude-mpm mpm-init --quick-update
@@ -342,15 +388,20 @@ The command delegates to the Agentic Coder Optimizer agent which:
 ## Notes
 
 - **Quick Update vs Full Update**: Use `/mpm-init update` for fast activity-based updates (30 days), or `/mpm-init --update` for comprehensive doc refresh
-- **Session Management**: Use `/mpm-init pause` to save state and `/mpm-init resume` to continue later with full context
+- **Context Analysis**: Use `/mpm-init context` to analyze git history and get intelligent resumption context from Research agent
+- **Quick History**: Use `/mpm-init catchup` for instant commit history display without analysis
+- **Deprecation Notice**: The `resume` command is deprecated. Use `context` instead. The old command still works but shows a warning.
 - **Smart Mode**: Automatically detects existing CLAUDE.md and offers update vs recreate
 - **Safe Updates**: Previous versions always archived before updating
 - **Custom Content**: Your project-specific sections are preserved by default
-- **Git Integration**: Analyzes recent commits to understand project evolution; pause creates optional git commits
-- **Session Storage**: Paused sessions stored in `.claude-mpm/sessions/pause/` with secure permissions
-- **Change Detection**: Resume automatically detects and reports changes since pause
+- **Git Integration**: Analyzes recent commits to understand project evolution and provide work context
+- **Backward Compatibility**: All existing `resume` commands redirect to `context` with deprecation warning
 - **Argument Processing**: The slash command processes the `update` argument and routes to `--quick-update` flag
-- The command uses the Agentic Coder Optimizer agent for implementation
+- **Agent Delegation**:
+  - Project initialization and updates use the Agentic Coder Optimizer agent
+  - Context analysis (`context`) delegates to PM, who coordinates with Research agent
+  - Simple git history (`catchup`) executes directly via CLI without agent delegation
+- **NOT Session State**: Context analysis reconstructs project understanding from git history, not saved conversation state
 - AST analysis is enabled by default for comprehensive documentation
 - Priority rankings help AI agents focus on critical instructions first
 - The holistic review ensures documentation quality and completeness

claude_mpm/utils/git_analyzer.py

@@ -0,0 +1,305 @@
+"""
+Git history analysis utilities for intelligent context reconstruction.
+
+This module provides utilities to analyze git repository activity for
+context reconstruction and project intelligence. Extracted from the
+session management system to support git-based context approaches.
+"""
+
+import subprocess
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from claude_mpm.core.logging_utils import get_logger
+
+logger = get_logger(__name__)
+
+
+def analyze_recent_activity(
+    repo_path: str = ".", days: int = 7, max_commits: int = 50
+) -> Dict[str, Any]:
+    """
+    Analyze recent git activity for context reconstruction.
+
+    This function analyzes git history to provide comprehensive context about
+    recent project activity including commits, contributors, file changes,
+    and branch activity.
+
+    Args:
+        repo_path: Path to the git repository (default: current directory)
+        days: Number of days to look back (default: 7)
+        max_commits: Maximum number of commits to analyze (default: 50)
+
+    Returns:
+        Dict containing:
+        - time_range: str - Description of analysis period
+        - commits: List[Dict] - Recent commits with metadata
+        - branches: List[str] - Active branches in the repository
+        - contributors: Dict[str, Dict] - Contributor statistics
+        - file_changes: Dict[str, Dict] - File change statistics
+        - has_activity: bool - Whether any activity was found
+        - error: Optional[str] - Error message if analysis failed
+    """
+    repo_path_obj = Path(repo_path)
+    analysis = {
+        "time_range": f"last {days} days",
+        "commits": [],
+        "branches": [],
+        "contributors": {},
+        "file_changes": {},
+        "has_activity": False,
+    }
+
+    try:
+        # Get all branches
+        result = subprocess.run(
+            ["git", "branch", "-a"],
+            cwd=str(repo_path_obj),
+            capture_output=True,
+            text=True,
+            check=True,
+        )
+        branches = [
+            line.strip().replace("* ", "").replace("remotes/origin/", "")
+            for line in result.stdout.strip().split("\n")
+            if line.strip()
+        ]
+        analysis["branches"] = list(set(branches))
+
+        # Get recent commits from all branches
+        result = subprocess.run(
+            [
+                "git",
+                "log",
+                "--all",
+                f"--since={days} days ago",
+                f"--max-count={max_commits}",
+                "--format=%h|%an|%ae|%ai|%s",
+                "--name-status",
+            ],
+            cwd=str(repo_path_obj),
+            capture_output=True,
+            text=True,
+            check=True,
+        )
+
+        if not result.stdout.strip():
+            return analysis
+
+        analysis["has_activity"] = True
+
+        # Parse commit log
+        commits = []
+        current_commit = None
+        file_changes = {}
+
+        for line in result.stdout.strip().split("\n"):
+            if not line.strip():
+                continue
+
+            if "|" in line:
+                # Commit line
+                if current_commit:
+                    commits.append(current_commit)
+
+                parts = line.split("|", 4)
+                if len(parts) == 5:
+                    sha, author, email, timestamp, message = parts
+                    current_commit = {
+                        "sha": sha,
+                        "author": author,
+                        "email": email,
+                        "timestamp": timestamp,
+                        "message": message,
+                        "files": [],
+                    }
+
+                    # Track contributors
+                    if author not in analysis["contributors"]:
+                        analysis["contributors"][author] = {
+                            "email": email,
+                            "commits": 0,
+                        }
+                    analysis["contributors"][author]["commits"] += 1
+            # File change line
+            elif current_commit and "\t" in line:
+                parts = line.split("\t", 1)
+                if len(parts) == 2:
+                    status, file_path = parts
+                    current_commit["files"].append(
+                        {"status": status, "path": file_path}
+                    )
+
+                    # Track file changes
+                    if file_path not in file_changes:
+                        file_changes[file_path] = {
+                            "modifications": 0,
+                            "contributors": set(),
+                        }
+                    file_changes[file_path]["modifications"] += 1
+                    file_changes[file_path]["contributors"].add(
+                        current_commit["author"]
+                    )
+
+        # Add last commit
+        if current_commit:
+            commits.append(current_commit)
+
+        analysis["commits"] = commits
+
+        # Convert file changes to serializable format
+        analysis["file_changes"] = {
+            path: {
+                "modifications": info["modifications"],
+                "contributors": list(info["contributors"]),
+            }
+            for path, info in file_changes.items()
+        }
+
+    except subprocess.CalledProcessError as e:
+        logger.warning(f"Git command failed: {e}")
+        analysis["error"] = f"Git command failed: {e}"
+    except Exception as e:
+        logger.warning(f"Could not analyze recent activity: {e}")
+        analysis["error"] = str(e)
+
+    return analysis
+
+
+def get_current_branch(repo_path: str = ".") -> Optional[str]:
+    """
+    Get the current git branch name.
+
+    Args:
+        repo_path: Path to the git repository (default: current directory)
+
+    Returns:
+        Current branch name or None if not in a git repository
+    """
+    try:
+        result = subprocess.run(
+            ["git", "branch", "--show-current"],
+            cwd=str(Path(repo_path)),
+            capture_output=True,
+            text=True,
+            check=True,
+        )
+        return result.stdout.strip()
+    except Exception:
+        return None
+
+
+def get_commits_since(since_sha: str, repo_path: str = ".") -> List[Dict[str, str]]:
+    """
+    Get commits since a specific SHA.
+
+    Args:
+        since_sha: The SHA to get commits after
+        repo_path: Path to the git repository (default: current directory)
+
+    Returns:
+        List of commit dicts with sha, author, timestamp, and message
+    """
+    try:
+        result = subprocess.run(
+            ["git", "log", f"{since_sha}..HEAD", "--format=%h|%an|%ai|%s"],
+            cwd=str(Path(repo_path)),
+            capture_output=True,
+            text=True,
+            check=True,
+        )
+
+        commits = []
+        for line in result.stdout.strip().split("\n"):
+            if not line:
+                continue
+            parts = line.split("|", 3)
+            if len(parts) == 4:
+                sha, author, timestamp, message = parts
+                commits.append(
+                    {
+                        "sha": sha,
+                        "author": author,
+                        "timestamp": timestamp,
+                        "message": message,
+                    }
+                )
+
+        return commits
+
+    except Exception as e:
+        logger.warning(f"Could not get commits: {e}")
+        return []
+
+
+def get_current_status(repo_path: str = ".") -> Dict[str, Any]:
+    """
+    Get current git status.
+
+    Args:
+        repo_path: Path to the git repository (default: current directory)
+
+    Returns:
+        Dict with:
+        - clean: bool - Whether working directory is clean
+        - modified_files: List[str] - Modified files
+        - untracked_files: List[str] - Untracked files
+    """
+    status = {"clean": True, "modified_files": [], "untracked_files": []}
+
+    try:
+        result = subprocess.run(
+            ["git", "status", "--porcelain"],
+            cwd=str(Path(repo_path)),
+            capture_output=True,
+            text=True,
+            check=True,
+        )
+
+        modified_files = []
+        untracked_files = []
+
+        for line in result.stdout.strip().split("\n"):
+            if not line:
+                continue
+            status_code = line[:2]
+            file_path = line[3:]
+
+            if status_code.startswith("??"):
+                untracked_files.append(file_path)
+            else:
+                modified_files.append(file_path)
+
+        status = {
+            "clean": len(modified_files) == 0 and len(untracked_files) == 0,
+            "modified_files": modified_files,
+            "untracked_files": untracked_files,
+        }
+
+    except Exception as e:
+        logger.warning(f"Could not get status: {e}")
+
+    return status
+
+
+def is_git_repository(repo_path: str = ".") -> bool:
+    """
+    Check if the given path is a git repository.
+
+    Args:
+        repo_path: Path to check (default: current directory)
+
+    Returns:
+        True if the path is a git repository, False otherwise
+    """
+    try:
+        result = subprocess.run(
+            ["git", "rev-parse", "--git-dir"],
+            cwd=str(Path(repo_path)),
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+        return result.returncode == 0
+    except Exception:
+        return False

{claude_mpm-4.11.0.dist-info → claude_mpm-4.11.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: claude-mpm
-Version: 4.11.0
+Version: 4.11.1
 Summary: Claude Multi-Agent Project Manager - Orchestrate Claude with agent delegation and ticket tracking
 Author-email: Bob Matsuoka <bob@matsuoka.com>
 Maintainer: Claude MPM Team