claude-mpm 3.0.1__py3-none-any.whl → 3.1.0__py3-none-any.whl

claude_mpm/schemas/workflow_validator.py

@@ -0,0 +1,411 @@
+#!/usr/bin/env python3
+"""
+Ticket Workflow Schema Validator
+================================
+
+Utility module for validating and working with ticket workflow schemas.
+
+WHY: This module exists to ensure workflow definitions are valid and consistent
+before they are used in the ticketing system. By validating workflows at load
+time, we prevent runtime errors and ensure all workflows follow the same structure.
+
+DESIGN DECISIONS:
+- Uses jsonschema for validation to leverage existing JSON Schema standards
+- Provides both validation and helper functions for common workflow operations
+- Returns detailed error messages to help users fix invalid workflows
+- Validates business logic beyond just schema structure
+
+Usage:
+    from claude_mpm.schemas.workflow_validator import WorkflowValidator
+    
+    validator = WorkflowValidator()
+    
+    # Validate a workflow
+    errors = validator.validate_workflow(workflow_dict)
+    if errors:
+        print(f"Validation failed: {errors}")
+    
+    # Load and validate from file
+    workflow = validator.load_workflow_file("standard_workflow.json")
+"""
+
+import json
+import logging
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Set, Tuple
+
+try:
+    import jsonschema
+    from jsonschema import Draft7Validator, validators
+    JSONSCHEMA_AVAILABLE = True
+except ImportError:
+    JSONSCHEMA_AVAILABLE = False
+    logging.warning("jsonschema not available, workflow validation disabled")
+
+logger = logging.getLogger(__name__)
+
+
+class WorkflowValidator:
+    """
+    Validates ticket workflow definitions against the schema.
+    
+    WHY: Ensures workflow definitions are valid before use, preventing
+    runtime errors and ensuring consistency across all workflows.
+    """
+    
+    def __init__(self, schema_path: Optional[Path] = None):
+        """
+        Initialize the workflow validator.
+        
+        Args:
+            schema_path: Path to the workflow schema file. If not provided,
+                        uses the default schema location.
+        """
+        self.schema_path = schema_path or self._get_default_schema_path()
+        self.schema = self._load_schema()
+        self._validator = None
+        
+        if JSONSCHEMA_AVAILABLE and self.schema:
+            self._validator = Draft7Validator(self.schema)
+    
+    def _get_default_schema_path(self) -> Path:
+        """Get the default path to the workflow schema."""
+        return Path(__file__).parent / "ticket_workflow_schema.json"
+    
+    def _load_schema(self) -> Optional[Dict[str, Any]]:
+        """Load the workflow schema from file."""
+        try:
+            if self.schema_path.exists():
+                with open(self.schema_path, 'r') as f:
+                    return json.load(f)
+            else:
+                logger.error(f"Schema file not found: {self.schema_path}")
+                return None
+        except Exception as e:
+            logger.error(f"Failed to load schema: {e}")
+            return None
+    
+    def validate_workflow(self, workflow: Dict[str, Any]) -> List[str]:
+        """
+        Validate a workflow definition.
+        
+        WHY: Validates both schema structure and business logic to ensure
+        the workflow is not only syntactically correct but also logically
+        consistent and usable.
+        
+        Args:
+            workflow: Workflow definition dictionary
+            
+        Returns:
+            List of validation error messages (empty if valid)
+        """
+        errors = []
+        
+        # Schema validation
+        if JSONSCHEMA_AVAILABLE and self._validator:
+            for error in self._validator.iter_errors(workflow):
+                errors.append(f"Schema error at {'.'.join(str(p) for p in error.path)}: {error.message}")
+        
+        # Business logic validation
+        if not errors:  # Only validate logic if schema is valid
+            logic_errors = self._validate_business_logic(workflow)
+            errors.extend(logic_errors)
+        
+        return errors
+    
+    def _validate_business_logic(self, workflow: Dict[str, Any]) -> List[str]:
+        """
+        Validate workflow business logic beyond schema requirements.
+        
+        WHY: Schema validation ensures structure, but we also need to validate
+        that the workflow makes logical sense (e.g., transitions reference
+        existing statuses, mappings are consistent, etc.)
+        """
+        errors = []
+        
+        # Extract status and resolution IDs
+        status_ids = {s['id'] for s in workflow.get('status_states', {}).get('states', [])}
+        resolution_ids = {r['id'] for r in workflow.get('resolution_types', {}).get('types', [])}
+        
+        # Validate default status exists
+        default_status = workflow.get('status_states', {}).get('default_status')
+        if default_status and default_status not in status_ids:
+            errors.append(f"Default status '{default_status}' not found in status definitions")
+        
+        # Validate transitions reference existing statuses
+        for i, transition in enumerate(workflow.get('transitions', {}).get('rules', [])):
+            from_status = transition.get('from_status')
+            to_status = transition.get('to_status')
+            
+            if from_status != '*' and from_status not in status_ids:
+                errors.append(f"Transition {i}: from_status '{from_status}' not found")
+            
+            if to_status not in status_ids:
+                errors.append(f"Transition {i}: to_status '{to_status}' not found")
+        
+        # Validate status-resolution mappings
+        for i, mapping in enumerate(workflow.get('status_resolution_mapping', {}).get('mappings', [])):
+            status_id = mapping.get('status_id')
+            if status_id not in status_ids:
+                errors.append(f"Status-resolution mapping {i}: status '{status_id}' not found")
+            
+            # Check resolution IDs (unless wildcard)
+            for resolution in mapping.get('allowed_resolutions', []):
+                if resolution != '*' and resolution not in resolution_ids:
+                    errors.append(f"Status-resolution mapping {i}: resolution '{resolution}' not found")
+            
+            # Check default resolution exists in allowed resolutions
+            default_res = mapping.get('default_resolution')
+            allowed_res = mapping.get('allowed_resolutions', [])
+            if default_res and '*' not in allowed_res and default_res not in allowed_res:
+                errors.append(f"Status-resolution mapping {i}: default resolution '{default_res}' not in allowed resolutions")
+        
+        # Validate there's at least one initial status
+        initial_statuses = [s for s in workflow.get('status_states', {}).get('states', []) 
+                           if s.get('category') == 'initial']
+        if not initial_statuses:
+            errors.append("No initial status defined (category='initial')")
+        
+        # Validate there's at least one terminal status
+        terminal_statuses = [s for s in workflow.get('status_states', {}).get('states', []) 
+                            if s.get('category') == 'terminal']
+        if not terminal_statuses:
+            errors.append("No terminal status defined (category='terminal')")
+        
+        # Validate escalation rules reference existing statuses
+        for i, rule in enumerate(workflow.get('business_rules', {}).get('escalation_rules', [])):
+            condition_status = rule.get('condition', {}).get('status')
+            if condition_status and condition_status not in status_ids:
+                errors.append(f"Escalation rule {i}: condition status '{condition_status}' not found")
+            
+            action_status = rule.get('action', {}).get('change_status')
+            if action_status and action_status not in status_ids:
+                errors.append(f"Escalation rule {i}: action status '{action_status}' not found")
+        
+        return errors
+    
+    def load_workflow_file(self, filepath: Path) -> Optional[Dict[str, Any]]:
+        """
+        Load and validate a workflow from file.
+        
+        Args:
+            filepath: Path to workflow JSON file
+            
+        Returns:
+            Validated workflow dictionary or None if invalid
+        """
+        try:
+            with open(filepath, 'r') as f:
+                workflow = json.load(f)
+            
+            errors = self.validate_workflow(workflow)
+            if errors:
+                logger.error(f"Workflow validation failed for {filepath}:")
+                for error in errors:
+                    logger.error(f"  - {error}")
+                return None
+            
+            return workflow
+            
+        except Exception as e:
+            logger.error(f"Failed to load workflow from {filepath}: {e}")
+            return None
+    
+    def get_valid_transitions(self, workflow: Dict[str, Any], from_status: str) -> List[Dict[str, Any]]:
+        """
+        Get valid transitions from a given status.
+        
+        WHY: Helper function to easily determine what transitions are available
+        from a specific status, supporting both specific and wildcard rules.
+        
+        Args:
+            workflow: Workflow definition
+            from_status: Current status ID
+            
+        Returns:
+            List of valid transition rules
+        """
+        transitions = []
+        
+        for rule in workflow.get('transitions', {}).get('rules', []):
+            rule_from = rule.get('from_status')
+            if rule_from == from_status or rule_from == '*':
+                transitions.append(rule)
+        
+        return transitions
+    
+    def get_allowed_resolutions(self, workflow: Dict[str, Any], status: str) -> Tuple[List[str], bool]:
+        """
+        Get allowed resolutions for a given status.
+        
+        WHY: Helper function to determine which resolutions are valid for a
+        specific status, and whether a resolution is required.
+        
+        Args:
+            workflow: Workflow definition
+            status: Status ID
+            
+        Returns:
+            Tuple of (allowed_resolution_ids, is_required)
+        """
+        for mapping in workflow.get('status_resolution_mapping', {}).get('mappings', []):
+            if mapping.get('status_id') == status:
+                allowed = mapping.get('allowed_resolutions', [])
+                required = mapping.get('requires_resolution', False)
+                
+                # Handle wildcard
+                if '*' in allowed:
+                    all_resolutions = [r['id'] for r in workflow.get('resolution_types', {}).get('types', [])]
+                    return all_resolutions, required
+                
+                return allowed, required
+        
+        return [], False
+    
+    def validate_transition(self, workflow: Dict[str, Any], from_status: str, 
+                          to_status: str, data: Dict[str, Any]) -> List[str]:
+        """
+        Validate a specific status transition.
+        
+        WHY: Ensures a proposed transition is valid according to the workflow
+        rules and that all required fields are provided.
+        
+        Args:
+            workflow: Workflow definition
+            from_status: Current status
+            to_status: Target status
+            data: Transition data (should include required fields)
+            
+        Returns:
+            List of validation errors (empty if valid)
+        """
+        errors = []
+        
+        # Find applicable transition rules
+        valid_transitions = self.get_valid_transitions(workflow, from_status)
+        matching_rule = None
+        
+        for rule in valid_transitions:
+            if rule.get('to_status') == to_status:
+                matching_rule = rule
+                break
+        
+        if not matching_rule:
+            errors.append(f"No valid transition from '{from_status}' to '{to_status}'")
+            return errors
+        
+        # Check required fields
+        required_fields = matching_rule.get('required_fields', [])
+        for field in required_fields:
+            if field not in data or data[field] is None:
+                errors.append(f"Required field '{field}' missing for transition")
+        
+        # If transitioning to a terminal status, check resolution requirements
+        target_status = next((s for s in workflow.get('status_states', {}).get('states', []) 
+                             if s['id'] == to_status), None)
+        
+        if target_status and target_status.get('category') == 'terminal':
+            allowed_resolutions, requires_resolution = self.get_allowed_resolutions(workflow, to_status)
+            
+            if requires_resolution and 'resolution' not in data:
+                errors.append(f"Resolution required for status '{to_status}'")
+            elif 'resolution' in data and data['resolution'] not in allowed_resolutions:
+                errors.append(f"Resolution '{data['resolution']}' not allowed for status '{to_status}'")
+        
+        return errors
+
+
+def create_example_workflows():
+    """
+    Create example workflow files for testing and demonstration.
+    
+    WHY: Provides ready-to-use workflow examples that demonstrate different
+    use cases and configuration options.
+    """
+    examples_dir = Path(__file__).parent / "examples"
+    examples_dir.mkdir(exist_ok=True)
+    
+    # Bug tracking workflow
+    bug_workflow = {
+        "schema_version": "1.0.0",
+        "workflow_id": "bug_tracking",
+        "workflow_version": "1.0.0",
+        "metadata": {
+            "name": "Bug Tracking Workflow",
+            "description": "Workflow optimized for software bug tracking",
+            "workflow_type": "bug_tracking"
+        },
+        "status_states": {
+            "states": [
+                {"id": "reported", "name": "Reported", "category": "initial"},
+                {"id": "confirmed", "name": "Confirmed", "category": "active"},
+                {"id": "in_progress", "name": "In Progress", "category": "active"},
+                {"id": "fixed", "name": "Fixed", "category": "active"},
+                {"id": "verified", "name": "Verified", "category": "terminal"},
+                {"id": "closed", "name": "Closed", "category": "terminal"},
+                {"id": "rejected", "name": "Rejected", "category": "terminal"}
+            ]
+        },
+        "resolution_types": {
+            "types": [
+                {"id": "fixed", "name": "Fixed", "category": "successful"},
+                {"id": "cannot_reproduce", "name": "Cannot Reproduce", "category": "invalid"},
+                {"id": "duplicate", "name": "Duplicate", "category": "invalid"},
+                {"id": "by_design", "name": "By Design", "category": "invalid"},
+                {"id": "wont_fix", "name": "Won't Fix", "category": "unsuccessful"}
+            ]
+        },
+        "transitions": {
+            "rules": [
+                {"from_status": "reported", "to_status": "confirmed", "name": "Confirm Bug"},
+                {"from_status": "reported", "to_status": "rejected", "name": "Reject"},
+                {"from_status": "confirmed", "to_status": "in_progress", "name": "Start Fix"},
+                {"from_status": "in_progress", "to_status": "fixed", "name": "Mark Fixed"},
+                {"from_status": "fixed", "to_status": "verified", "name": "Verify Fix"},
+                {"from_status": "verified", "to_status": "closed", "name": "Close"}
+            ]
+        },
+        "status_resolution_mapping": {
+            "mappings": [
+                {
+                    "status_id": "verified",
+                    "allowed_resolutions": ["fixed"],
+                    "requires_resolution": true
+                },
+                {
+                    "status_id": "closed",
+                    "allowed_resolutions": ["*"],
+                    "requires_resolution": true
+                },
+                {
+                    "status_id": "rejected",
+                    "allowed_resolutions": ["cannot_reproduce", "duplicate", "by_design", "wont_fix"],
+                    "requires_resolution": true
+                }
+            ]
+        }
+    }
+    
+    with open(examples_dir / "bug_tracking_workflow.json", 'w') as f:
+        json.dump(bug_workflow, f, indent=2)
+    
+    logger.info("Created example workflow files")
+
+
+if __name__ == "__main__":
+    # Example usage
+    validator = WorkflowValidator()
+    
+    # Load and validate the standard workflow
+    example_path = Path(__file__).parent / "examples" / "standard_workflow.json"
+    if example_path.exists():
+        workflow = validator.load_workflow_file(example_path)
+        if workflow:
+            print(f"Successfully loaded workflow: {workflow['metadata']['name']}")
+            
+            # Test some helper functions
+            transitions = validator.get_valid_transitions(workflow, "open")
+            print(f"\nValid transitions from 'open': {[t['name'] for t in transitions]}")
+            
+            resolutions, required = validator.get_allowed_resolutions(workflow, "resolved")
+            print(f"\nResolutions for 'resolved' status: {resolutions} (required: {required})")

{claude_mpm-3.0.1.dist-info → claude_mpm-3.1.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: claude-mpm
-Version: 3.0.1
+Version: 3.1.0
 Summary: Claude Multi-agent Project Manager - Clean orchestration with ticket management
 Home-page: https://github.com/bobmatnyc/claude-mpm
 Author: Claude MPM Team
@@ -220,6 +220,8 @@ Claude MPM provides a modular framework for extending Claude's capabilities:
 - **File System Protection**: Automatic sandboxing prevents file operations outside the working directory
 - **Path Traversal Prevention**: Blocks attempts to escape the project directory using `..` or symlinks
 - **Write Operation Control**: All write operations are validated while read operations remain unrestricted
+- **Agent-Level Restrictions**: Each agent can have custom file access boundaries via `file_access` configuration
+- **PM Agent Orchestration**: New PM (Project Manager) agent ensures all sub-agents operate within security boundaries
 - **Transparent Security**: Zero-configuration security that works automatically in the background
 - **Comprehensive Logging**: All security events are logged for audit purposes
 

{claude_mpm-3.0.1.dist-info → claude_mpm-3.1.0.dist-info}/RECORD

@@ -1,7 +1,6 @@
-claude_mpm/__init__.py,sha256=sAbTZkHe3vWYAKDWdGyGVue5zwLD7nCOHZwZrLALM8A,395
+claude_mpm/__init__.py,sha256=TRneXzyApGyF7cRerpTn7aCbYLu-AJhPHjQf-dMBElQ,666
 claude_mpm/__main__.py,sha256=smBw-5J3nf5s6GgQjj384GUr28YotIX-WNOxqpP0wnE,310
-claude_mpm/_version.py,sha256=4w4S1hWcUnRsA3wylRad272Nvb5pcv7L8gpn7UBpYN8,159
-claude_mpm/cli.py,sha256=_6tUSY0FqBN6cHR6awuXgqm2-Hlh-L508rB-RDgflPU,26036
+claude_mpm/cli.py,sha256=5GeRclnY-VNDaGnv7XUXDOniHZfACJ8HUYVUUXEHh9g,26340
 claude_mpm/cli_enhancements.py,sha256=nwdOrbXITRqvcq_vrJtPKW1GDS7dLIG4UqjoUet2vR0,10890
 claude_mpm/cli_main.py,sha256=KCAe-ws73NrIg5qmFhPdZ1a4uoiaEZ-lldYzQ6KfnJg,306
 claude_mpm/constants.py,sha256=5AG5hgBxOC7gMNHDx0lAhS-FQ8gXhtGtqJ9Moj3S6ro,4044
@@ -10,7 +9,7 @@ claude_mpm/agents/BASE_AGENT_TEMPLATE.md,sha256=TYgSd9jNBMWp4mAOBUl9dconX4RcGbvm
 claude_mpm/agents/INSTRUCTIONS.md,sha256=X6bOhSII3pZVZh_Vw_zMYRdfLtyl5Mmf_jhrVYfNxFs,7200
 claude_mpm/agents/__init__.py,sha256=r-p7ervzjLPD7_8dm2tXX_fwvdTZy6KwKA03ofxN3sA,3275
 claude_mpm/agents/agent-template.yaml,sha256=koKJn8MCAJx0QNQMHouvIZrwvw5qjPV0U-aV-YVyk6s,2036
-claude_mpm/agents/agent_loader.py,sha256=UZf3Od23gSKe_k-EokatQdQKqS38lRQq_ifUYU5I0qU,44024
+claude_mpm/agents/agent_loader.py,sha256=P4h3qupJHvZL9dfb6ntB582xenYv9JbkMOVav_kNkAo,44030
 claude_mpm/agents/agent_loader_integration.py,sha256=z_DXxAIeuUD71HBYdxxvcFKoQYQxITLo8oAdN_M4LTA,7610
 claude_mpm/agents/agents_metadata.py,sha256=Xju9Yim6XSv2u1J_Swre5VJySbdxxC-9TzpOfXG8ibg,5170
 claude_mpm/agents/base_agent.json,sha256=wvopTu58PEdvgvjBi45J5aBA6bxs5_v1KC84CbJeRzY,3820
@@ -96,8 +95,13 @@ claude_mpm/orchestration/archive/subprocess_orchestrator.py,sha256=TYTAHX6p4OpgB
 claude_mpm/orchestration/archive/system_prompt_orchestrator.py,sha256=R16sc-94kQVeGjJzTYmvKn0aYgj_9qxyzShDy1E5zpE,12853
 claude_mpm/orchestration/archive/wrapper_orchestrator.py,sha256=cvL0NJf9kCWf3QJl67ySwvtR1Hd9Rym28Ii8Rtsdi6Q,6806
 claude_mpm/schemas/README_SECURITY.md,sha256=6BiFZ9VuMllijQkYEx_lAT7wwXhMeO3FQtih7WMvsAI,3297
-claude_mpm/schemas/agent_schema.json,sha256=vEp9dFCqUmxLzkNLmB34uvCmGemNv1DiVYNcUXBDONc,15963
+claude_mpm/schemas/agent_schema.json,sha256=PukBzcAs8SzLHU6tYn8hjdYcnH8xrdvWD9hwvcasy0U,12385
+claude_mpm/schemas/agent_schema_documentation.md,sha256=pQTxXNhxDqDK_0mMohszPOx3NOBKz-YOJPAU5h_iSQg,6405
 claude_mpm/schemas/agent_schema_security_notes.md,sha256=gzx6Z4xL5x0QISiXVDcwRGNnfegRgVK7jx7jAcc5910,6449
+claude_mpm/schemas/ticket_workflow_documentation.md,sha256=F51WiIkJg2Z9BLA7FqwkAPy6YOXKYF4--E-NAYRx4yM,12784
+claude_mpm/schemas/ticket_workflow_schema.json,sha256=AVedOeNfOdJdERaxEz4ZJj4aVZaHzfungg3C5Y_02qg,19112
+claude_mpm/schemas/workflow_validator.py,sha256=qRgGodJoIZQaLfZ8OzWz3Y9eVNz3ckrQwkJ2RvccxAs,17175
+claude_mpm/schemas/examples/standard_workflow.json,sha256=POQdxPIoJRD2qe4-17a35pGqFX5hfmGttXWPfeZ8qRs,13835
 claude_mpm/scripts/__init__.py,sha256=M2n9fQeyfILC8gogXvJv6ixnu7hwpqLEqLWJRaUN0MU,37
 claude_mpm/scripts/ticket.py,sha256=GmFimtTJxc927cCzJvvJH3gvoxXQtAB-W-xnuclcvNs,9350
 claude_mpm/services/__init__.py,sha256=-EBm07Lh9mjcofiQHCqyCCQJMLi9akVArPlz8i_kEOo,226
@@ -167,9 +171,9 @@ claude_mpm/utils/path_operations.py,sha256=6pLMnAWBVzHkgp6JyQHmHbGD-dWn-nX21yV4E
 claude_mpm/utils/paths.py,sha256=Xv0SZWdZRkRjN9e6clBcA165ya00GNQxt7SwMz51tfA,10153
 claude_mpm/validation/__init__.py,sha256=bJ19g9lnk7yIjtxzN8XPegp87HTFBzCrGQOpFgRTf3g,155
 claude_mpm/validation/agent_validator.py,sha256=GCA2b2rKhKDeaNyUqWxTiWIs3sDdWjD9cgOFRp9K6ic,18227
-claude_mpm-3.0.1.dist-info/licenses/LICENSE,sha256=cSdDfXjoTVhstrERrqme4zgxAu4GubU22zVEHsiXGxs,1071
-claude_mpm-3.0.1.dist-info/METADATA,sha256=O4UprzdFs-f48tg4SYr4fTLe3ROPbhEd-q3kgXS0X20,13906
-claude_mpm-3.0.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-claude_mpm-3.0.1.dist-info/entry_points.txt,sha256=PknO31um7d8bt6GjOiVeYpdJpjND0_C1z-LQfY6UfiU,142
-claude_mpm-3.0.1.dist-info/top_level.txt,sha256=1nUg3FEaBySgm8t-s54jK5zoPnu3_eY6EP6IOlekyHA,11
-claude_mpm-3.0.1.dist-info/RECORD,,
+claude_mpm-3.1.0.dist-info/licenses/LICENSE,sha256=cSdDfXjoTVhstrERrqme4zgxAu4GubU22zVEHsiXGxs,1071
+claude_mpm-3.1.0.dist-info/METADATA,sha256=jtA8pwlqe3dPFBhH4xQwzsULplyAeqBY8RLsUia0zUg,14139
+claude_mpm-3.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+claude_mpm-3.1.0.dist-info/entry_points.txt,sha256=PknO31um7d8bt6GjOiVeYpdJpjND0_C1z-LQfY6UfiU,142
+claude_mpm-3.1.0.dist-info/top_level.txt,sha256=1nUg3FEaBySgm8t-s54jK5zoPnu3_eY6EP6IOlekyHA,11
+claude_mpm-3.1.0.dist-info/RECORD,,

claude_mpm/_version.py

@@ -1,4 +0,0 @@
-# file generated by setuptools_scm
-# don't change, don't track in version control
-__version__ = version = '3.0.1'
-__version_tuple__ = version_tuple = (3, 0, 1)