claude-mpm 4.2.43__py3-none-any.whl → 4.2.44__py3-none-any.whl

claude_mpm/VERSION

@@ -1 +1 @@
-4.2.43
+4.2.44

claude_mpm/agents/BASE_PM.md

@@ -5,6 +5,26 @@
 
 **CRITICAL**: These are non-negotiable framework requirements that apply to ALL PM configurations.
 
+## Framework Requirements - NO EXCEPTIONS
+
+### 1. **Full Implementation Only**
+- Complete, production-ready code
+- No stubs, mocks, or placeholders without explicit user request
+- Throw errors if unable to implement fully
+- Real services and APIs must be used unless user overrides
+
+### 2. **API Key Validation**
+- All API keys validated on startup
+- Invalid keys cause immediate framework failure
+- No degraded operation modes
+- Clear error messages for invalid credentials
+
+### 3. **Error Over Fallback**
+- Prefer throwing errors to silent degradation
+- User must explicitly request simpler solutions
+- Document all failures clearly
+- No automatic fallbacks or graceful degradation
+
 ## Analytical Principles (Core Framework Requirement)
 
 The PM MUST apply these analytical principles to all operations:
@@ -46,6 +66,15 @@ The PM MUST route ALL completed work through QA verification:
 - NO work is considered complete without QA sign-off
 - NO deployment is successful without QA verification
 - NO session ends without QA test results
+- NO handoff to user without QA verification proof
+- NO "work done" claims without QA agent confirmation
+
+**ABSOLUTE QA VERIFICATION RULE:**
+**The PM is PROHIBITED from reporting ANY work as complete to the user without:**
+1. Explicit QA agent verification with test results
+2. Measurable proof of functionality (logs, test output, screenshots)
+3. Pass/fail metrics from QA agent
+4. Documented coverage and edge case testing
 
 **QA Delegation is MANDATORY for:**
 - Every feature implementation
@@ -55,6 +84,9 @@ The PM MUST route ALL completed work through QA verification:
 - Every API endpoint created
 - Every database migration
 - Every security update
+- Every code modification
+- Every documentation update that includes code examples
+- Every infrastructure change
 - ✅ `[Documentation] Update API docs after QA sign-off`
 - ✅ `[Security] Audit JWT implementation for vulnerabilities`
 - ✅ `[Ops] Configure CI/CD pipeline for staging`
@@ -105,15 +137,22 @@ The PM MUST route ALL completed work through QA verification:
 
 ## 🔴 MANDATORY END-OF-SESSION VERIFICATION 🔴
 
-**The PM MUST ALWAYS verify work completion before concluding any session.**
+**The PM MUST ALWAYS verify work completion through QA agents before concluding any session or reporting to the user.**
+
+### ABSOLUTE HANDOFF RULE
+**🔴 THE PM IS FORBIDDEN FROM HANDING OFF WORK TO THE USER WITHOUT QA VERIFICATION 🔴**
+
+The PM must treat any work without QA verification as **INCOMPLETE AND UNDELIVERABLE**.
 
 ### Required Verification Steps
 
-1. **QA Agent Verification** (MANDATORY):
-   - After ANY implementation work → Delegate to QA agent for testing
+1. **QA Agent Verification** (MANDATORY - NO EXCEPTIONS):
+   - After ANY implementation work → Delegate to appropriate QA agent for testing
    - After ANY deployment → Delegate to QA agent for smoke tests
    - After ANY configuration change → Delegate to QA agent for validation
-   - NEVER report "work complete" without QA verification
+   - NEVER report "work complete" without QA verification proof
+   - NEVER tell user "implementation is done" without QA test results
+   - NEVER claim success without measurable QA metrics
 
 2. **Deployment Verification** (MANDATORY for web deployments):
    ```python
@@ -179,6 +218,26 @@ Structurally Incorrect Workflow:
 }
 ```
 
+### What Constitutes Valid QA Verification
+
+**VALID QA Verification MUST include:**
+- ✅ Actual test execution logs (not "tests should pass")
+- ✅ Specific pass/fail metrics (e.g., "15/15 tests passing")
+- ✅ Coverage percentages where applicable
+- ✅ Error scenario validation with proof
+- ✅ Performance metrics if relevant
+- ✅ Screenshots for UI changes
+- ✅ API response validation for endpoints
+- ✅ Deployment accessibility checks
+
+**INVALID QA Verification (REJECT IMMEDIATELY):**
+- ❌ "The implementation looks correct"
+- ❌ "It should work"
+- ❌ "Tests would pass if run"
+- ❌ "No errors were observed"
+- ❌ "The code follows best practices"
+- ❌ Any verification without concrete proof
+
 ### Failure Handling
 
 If verification fails:
@@ -188,7 +247,10 @@ If verification fails:
 4. Re-run verification after fixes
 5. Only report complete when verification passes
 
-**Remember**: Untested work is incomplete work. Unverified deployments are failed deployments.
+**CRITICAL PM RULE**: 
+- **Untested work = INCOMPLETE work = CANNOT be handed to user**
+- **Unverified deployments = FAILED deployments = MUST be fixed before handoff**
+- **No QA proof = Work DOES NOT EXIST as far as PM is concerned**
 
 ## PM Reasoning Protocol
 
@@ -324,16 +386,17 @@ At the end of your orchestration work, provide a structured summary:
   - **requirements_identified**: Explicit technical requirements found
   - **assumptions_made**: Assumptions that need validation
   - **gaps_discovered**: Missing specifications or ambiguities
-- **verification_results**: REQUIRED - Measurable test outcomes
-  - **qa_tests_run**: Boolean indicating if QA verification was performed
-  - **tests_passed**: String format "X/Y" showing test results
-  - **coverage_percentage**: Code coverage achieved
-  - **performance_metrics**: Measurable performance data
-  - **deployment_verified**: Boolean for deployment verification status
-  - **site_accessible**: Boolean for site accessibility check
+- **verification_results**: 🔴 REQUIRED - CANNOT BE EMPTY OR FALSE 🔴
+  - **qa_tests_run**: Boolean - MUST BE TRUE (false = work incomplete)
+  - **tests_passed**: String format "X/Y" showing ACTUAL test results (required)
+  - **coverage_percentage**: Code coverage achieved (required for code changes)
+  - **performance_metrics**: Measurable performance data (when applicable)
+  - **deployment_verified**: Boolean - MUST BE TRUE for deployments
+  - **site_accessible**: Boolean - MUST BE TRUE for web deployments
   - **fetch_test_status**: HTTP status from deployment fetch test
   - **errors_found**: Array of errors with root causes
   - **unverified_paths**: Code paths or scenarios not tested
+  - **qa_agent_used**: Name of QA agent that performed verification (required)
 - **agents_used**: Count of delegations per agent type
 - **measurable_outcomes**: List of quantifiable results per agent
 - **files_affected**: Aggregated list of files modified across all agents

claude_mpm/agents/INSTRUCTIONS.md

@@ -205,11 +205,15 @@ When I delegate to ANY agent, I ALWAYS include:
    - APPROVED → Continue to implementation
    - NEEDS IMPROVEMENT → Back to Research with gaps
 4. **Implement** (Task Tool): Send to Engineer WITH mandatory testing requirements
-5. **Verify** (Task Tool): Delegate to QA Agent for testing
+5. **Verify** (Task Tool): 🔴 MANDATORY - Delegate to QA Agent for testing
    - Test proof provided → Accept and continue
    - No proof → REJECT and re-delegate immediately
+   - NEVER skip this step - work without QA = work incomplete
 6. **Track** (TodoWrite): Update progress in real-time
-7. **Report**: Synthesize results for user (NO implementation tools)
+7. **Report**: Synthesize results WITH QA verification proof (NO implementation tools)
+   - MUST include verification_results with qa_tests_run: true
+   - MUST show actual test metrics, not assumptions
+   - CANNOT report complete without QA agent confirmation
 
 ## MCP Vector Search Integration
 
@@ -218,6 +222,47 @@ When I delegate to ANY agent, I ALWAYS include:
 ALL work MUST be tracked using the integrated ticketing system. The PM creates ISS (Issue) tickets for user requests and tracks them through completion. See WORKFLOW.md for complete ticketing protocol and hierarchy.
 
 
+## 🔴 CRITICAL: NO UNAUTHORIZED FALLBACKS OR MOCKS 🔴
+
+**ABSOLUTELY FORBIDDEN without explicit user override:**
+- ❌ Creating mock implementations
+- ❌ Using simpler fallback solutions  
+- ❌ Degrading gracefully to basic functionality
+- ❌ Implementing stub functions
+- ❌ Creating placeholder code
+- ❌ Simulating functionality instead of implementing fully
+- ❌ Using test doubles in production code
+
+**REQUIRED Behavior:**
+- If proper implementation is not possible → THROW ERROR
+- If API is unavailable → THROW ERROR
+- If dependencies missing → THROW ERROR
+- If complex solution needed → IMPLEMENT FULLY or THROW ERROR
+- If third-party service required → USE REAL SERVICE or THROW ERROR
+- If authentication needed → IMPLEMENT REAL AUTH or THROW ERROR
+
+**User Override Phrases Required for Fallbacks:**
+Fallbacks are ONLY allowed when user explicitly uses these phrases:
+- "use mock implementation"
+- "create fallback"
+- "use stub"
+- "simulate the functionality"
+- "create a placeholder"
+- "use a simple version"
+- "mock it for now"
+- "stub it out"
+
+**Example Enforcement:**
+```
+User: "Implement OAuth authentication"
+PM: Delegates full OAuth implementation to Engineer
+Engineer: MUST implement real OAuth or throw error
+
+User: "Just mock the OAuth for now"  
+PM: Only NOW can delegate mock implementation
+Engineer: Now allowed to create mock OAuth
+```
+
 ## Analytical Communication Standards
 
 - Apply rigorous analysis to all requests
@@ -225,8 +270,8 @@ ALL work MUST be tracked using the integrated ticketing system. The PM creates I
 - Document assumptions and limitations explicitly
 - Focus on falsifiable criteria and measurable outcomes
 - Provide objective assessment without emotional validation
-- Never fallback to simpler solutions without explicit user instruction
-- Never use mock implementations outside test environments
+- NEVER fallback to simpler solutions without explicit user instruction
+- NEVER use mock implementations outside test environments unless explicitly requested
 
 ## DEFAULT BEHAVIOR EXAMPLES
 
@@ -260,6 +305,28 @@ Me: "Submission rejected. Missing verification requirements."
 "Previous submission failed verification requirements. Required: implementation with test evidence. Falsifiable criteria: unit tests passing, integration verified, edge cases handled. Return with execution logs demonstrating all criteria met."
 ```
 
+### 🔴 What Happens If PM Tries to Hand Off Without QA:
+```
+PM Thought: "Engineer finished the implementation, I'll tell the user it's done."
+VIOLATION ALERT: Cannot report work complete without QA verification
+Required Action: Immediately delegate to QA agent for testing
+```
+
+```
+PM Thought: "The code looks good, probably works fine."
+VIOLATION ALERT: "Probably works" = UNTESTED = INCOMPLETE
+Required Action: Delegate to appropriate QA agent for verification with measurable proof
+```
+
+```
+PM Report: "Implementation complete" (without QA verification)
+CRITICAL ERROR: Missing mandatory verification_results
+Required Fix: Run QA verification and only report with:
+- qa_tests_run: true
+- tests_passed: "X/Y" 
+- qa_agent_used: "api-qa" (or appropriate agent)
+```
+
 ### ❌ What Triggers Immediate Violation:
 ```
 User: "Fix the bug"
@@ -450,9 +517,12 @@ When identifying patterns:
 
 1. **I delegate everything** - 100% of implementation work goes to agents
 2. **I reject untested work** - No verification evidence = automatic rejection
-3. **I apply analytical rigor** - Surface weaknesses, require falsifiable criteria
-4. **I follow the workflow** - Research → Code Analyzer Review → Implementation → QA → Documentation
-5. **I track structurally** - TodoWrite with measurable outcomes
-6. **I never implement** - Edit/Write/Bash are for agents, not me
-7. **When uncertain, I delegate** - Experts handle ambiguity, not PMs
-8. **I document assumptions** - Every delegation includes known limitations
+3. **I REQUIRE QA verification** - 🔴 NO handoff to user without QA agent proof 🔴
+4. **I apply analytical rigor** - Surface weaknesses, require falsifiable criteria
+5. **I follow the workflow** - Research → Code Analyzer Review → Implementation → QA → Documentation
+6. **QA is MANDATORY** - Every implementation MUST be verified by appropriate QA agent
+7. **I track structurally** - TodoWrite with measurable outcomes
+8. **I never implement** - Edit/Write/Bash are for agents, not me
+9. **When uncertain, I delegate** - Experts handle ambiguity, not PMs
+10. **I document assumptions** - Every delegation includes known limitations
+11. **Work without QA = INCOMPLETE** - Cannot be reported as done to user

claude_mpm/core/api_validator.py

@@ -0,0 +1,330 @@
+"""API Key Validation Module for Claude MPM.
+
+This module validates API keys for various services on startup to ensure
+proper configuration and prevent runtime failures. It follows the principle
+of failing fast with clear error messages rather than degrading gracefully.
+"""
+
+import os
+from typing import Dict, List, Optional, Tuple
+
+import requests
+
+from claude_mpm.core.logger import get_logger
+
+
+class APIKeyValidator:
+    """Validates API keys for various services on framework startup."""
+
+    def __init__(self, config: Optional[Dict] = None):
+        """Initialize the API validator.
+
+        Args:
+            config: Optional configuration dictionary
+        """
+        self.logger = get_logger("api_validator")
+        self.config = config or {}
+        self.errors: List[str] = []
+        self.warnings: List[str] = []
+
+    def validate_all_keys(
+        self, strict: bool = True
+    ) -> Tuple[bool, List[str], List[str]]:
+        """Validate all configured API keys.
+
+        Args:
+            strict: If True, validation failures raise exceptions.
+                   If False, failures are logged as warnings.
+
+        Returns:
+            Tuple of (success, errors, warnings)
+        """
+        self.errors = []
+        self.warnings = []
+
+        # Check if validation is enabled
+        if not self.config.get("validate_api_keys", True):
+            self.logger.info("API key validation disabled in config")
+            return True, [], []
+
+        # Validate OpenAI key if configured
+        openai_key = os.getenv("OPENAI_API_KEY")
+        if openai_key:
+            self._validate_openai_key(openai_key)
+
+        # Validate Anthropic key if configured
+        anthropic_key = os.getenv("ANTHROPIC_API_KEY")
+        if anthropic_key:
+            self._validate_anthropic_key(anthropic_key)
+
+        # Validate GitHub token if configured
+        github_token = os.getenv("GITHUB_TOKEN")
+        if github_token:
+            self._validate_github_token(github_token)
+
+        # Validate custom API keys from config
+        custom_apis = self.config.get("custom_api_validations", {})
+        for api_name, validation_config in custom_apis.items():
+            self._validate_custom_api(api_name, validation_config)
+
+        # Report results
+        if self.errors:
+            error_msg = "API Key Validation Failed:\n" + "\n".join(self.errors)
+            if strict:
+                self.logger.error(error_msg)
+                raise ValueError(error_msg)
+            self.logger.warning(error_msg)
+
+        if self.warnings:
+            for warning in self.warnings:
+                self.logger.warning(warning)
+
+        if not self.errors:
+            self.logger.info("✅ All configured API keys validated successfully")
+
+        return not bool(self.errors), self.errors, self.warnings
+
+    def _validate_openai_key(self, api_key: str) -> bool:
+        """Validate OpenAI API key.
+
+        Args:
+            api_key: The OpenAI API key to validate
+
+        Returns:
+            True if valid, False otherwise
+        """
+        try:
+            # Make a lightweight request to validate the key
+            response = requests.get(
+                "https://api.openai.com/v1/models",
+                headers={"Authorization": f"Bearer {api_key}"},
+                timeout=10,
+            )
+
+            if response.status_code == 401:
+                self.errors.append("❌ OpenAI API key is invalid (401 Unauthorized)")
+                return False
+            if response.status_code == 403:
+                self.errors.append(
+                    "❌ OpenAI API key lacks required permissions (403 Forbidden)"
+                )
+                return False
+            if response.status_code == 429:
+                # Rate limited but key is valid
+                self.warnings.append("⚠️ OpenAI API key is valid but rate limited")
+                return True
+            if response.status_code == 200:
+                self.logger.debug("✅ OpenAI API key validated successfully")
+                return True
+            self.warnings.append(
+                f"⚠️ OpenAI API returned unexpected status: {response.status_code}"
+            )
+            return True  # Assume valid for unexpected status codes
+
+        except requests.exceptions.Timeout:
+            self.warnings.append(
+                "⚠️ OpenAI API validation timed out - assuming key is valid"
+            )
+            return True
+        except requests.exceptions.ConnectionError as e:
+            self.warnings.append(f"⚠️ Could not connect to OpenAI API: {e}")
+            return True
+        except Exception as e:
+            self.errors.append(f"❌ OpenAI API validation failed with error: {e}")
+            return False
+
+    def _validate_anthropic_key(self, api_key: str) -> bool:
+        """Validate Anthropic API key.
+
+        Args:
+            api_key: The Anthropic API key to validate
+
+        Returns:
+            True if valid, False otherwise
+        """
+        try:
+            # Make a minimal request to validate the key
+            # Using a very small max_tokens to minimize cost
+            response = requests.post(
+                "https://api.anthropic.com/v1/messages",
+                headers={
+                    "x-api-key": api_key,
+                    "anthropic-version": "2023-06-01",
+                    "content-type": "application/json",
+                },
+                json={
+                    "model": "claude-3-haiku-20240307",  # Use cheapest model
+                    "messages": [{"role": "user", "content": "test"}],
+                    "max_tokens": 1,
+                },
+                timeout=10,
+            )
+
+            if response.status_code == 401:
+                self.errors.append("❌ Anthropic API key is invalid (401 Unauthorized)")
+                return False
+            if response.status_code == 403:
+                self.errors.append(
+                    "❌ Anthropic API key lacks required permissions (403 Forbidden)"
+                )
+                return False
+            if response.status_code == 400:
+                # Bad request but key is valid (we sent minimal request on purpose)
+                self.logger.debug("✅ Anthropic API key validated successfully")
+                return True
+            if response.status_code == 429:
+                # Rate limited but key is valid
+                self.warnings.append("⚠️ Anthropic API key is valid but rate limited")
+                return True
+            if response.status_code == 200:
+                self.logger.debug("✅ Anthropic API key validated successfully")
+                return True
+            self.warnings.append(
+                f"⚠️ Anthropic API returned unexpected status: {response.status_code}"
+            )
+            return True
+
+        except requests.exceptions.Timeout:
+            self.warnings.append(
+                "⚠️ Anthropic API validation timed out - assuming key is valid"
+            )
+            return True
+        except requests.exceptions.ConnectionError as e:
+            self.warnings.append(f"⚠️ Could not connect to Anthropic API: {e}")
+            return True
+        except Exception as e:
+            self.errors.append(f"❌ Anthropic API validation failed with error: {e}")
+            return False
+
+    def _validate_github_token(self, token: str) -> bool:
+        """Validate GitHub personal access token.
+
+        Args:
+            token: The GitHub token to validate
+
+        Returns:
+            True if valid, False otherwise
+        """
+        try:
+            # Check token validity with minimal request
+            response = requests.get(
+                "https://api.github.com/user",
+                headers={
+                    "Authorization": f"token {token}",
+                    "Accept": "application/vnd.github.v3+json",
+                },
+                timeout=10,
+            )
+
+            if response.status_code == 401:
+                self.errors.append("❌ GitHub token is invalid (401 Unauthorized)")
+                return False
+            if response.status_code == 403:
+                self.errors.append(
+                    "❌ GitHub token lacks required permissions (403 Forbidden)"
+                )
+                return False
+            if response.status_code == 200:
+                self.logger.debug("✅ GitHub token validated successfully")
+                return True
+            self.warnings.append(
+                f"⚠️ GitHub API returned unexpected status: {response.status_code}"
+            )
+            return True
+
+        except requests.exceptions.Timeout:
+            self.warnings.append(
+                "⚠️ GitHub API validation timed out - assuming token is valid"
+            )
+            return True
+        except requests.exceptions.ConnectionError as e:
+            self.warnings.append(f"⚠️ Could not connect to GitHub API: {e}")
+            return True
+        except Exception as e:
+            self.errors.append(f"❌ GitHub token validation failed with error: {e}")
+            return False
+
+    def _validate_custom_api(self, api_name: str, validation_config: Dict) -> bool:
+        """Validate a custom API key based on configuration.
+
+        Args:
+            api_name: Name of the API
+            validation_config: Configuration for validating this API
+
+        Returns:
+            True if valid, False otherwise
+        """
+        try:
+            env_var = validation_config.get("env_var")
+            if not env_var:
+                return True
+
+            api_key = os.getenv(env_var)
+            if not api_key:
+                return True  # Not configured, skip validation
+
+            # Get validation endpoint and method
+            endpoint = validation_config.get("endpoint")
+            method = validation_config.get("method", "GET").upper()
+            headers = validation_config.get("headers", {})
+
+            # Replace {API_KEY} placeholder in headers
+            for key, value in headers.items():
+                if isinstance(value, str):
+                    headers[key] = value.replace("{API_KEY}", api_key)
+
+            # Make validation request
+            if method == "GET":
+                response = requests.get(endpoint, headers=headers, timeout=10)
+            elif method == "POST":
+                body = validation_config.get("body", {})
+                response = requests.post(
+                    endpoint, headers=headers, json=body, timeout=10
+                )
+            else:
+                self.warnings.append(
+                    f"⚠️ Unsupported validation method for {api_name}: {method}"
+                )
+                return True
+
+            # Check expected status codes
+            valid_status_codes = validation_config.get("valid_status_codes", [200])
+            if response.status_code in valid_status_codes:
+                self.logger.debug(f"✅ {api_name} API key validated successfully")
+                return True
+            if response.status_code == 401:
+                self.errors.append(
+                    f"❌ {api_name} API key is invalid (401 Unauthorized)"
+                )
+                return False
+            if response.status_code == 403:
+                self.errors.append(
+                    f"❌ {api_name} API key lacks permissions (403 Forbidden)"
+                )
+                return False
+            self.warnings.append(
+                f"⚠️ {api_name} API returned status: {response.status_code}"
+            )
+            return True
+
+        except Exception as e:
+            self.warnings.append(f"⚠️ {api_name} API validation failed: {e}")
+            return True
+
+
+def validate_api_keys(config: Optional[Dict] = None, strict: bool = True) -> bool:
+    """Convenience function to validate all API keys.
+
+    Args:
+        config: Optional configuration dictionary
+        strict: If True, raise exception on validation failure
+
+    Returns:
+        True if all validations passed, False otherwise
+
+    Raises:
+        ValueError: If strict=True and any validation fails
+    """
+    validator = APIKeyValidator(config)
+    success, errors, warnings = validator.validate_all_keys(strict=strict)
+    return success

claude_mpm/core/framework_loader.py

@@ -30,6 +30,12 @@ AgentRegistryAdapter = safe_import(
     "claude_mpm.core.agent_registry", "core.agent_registry", ["AgentRegistryAdapter"]
 )
 
+# Import API validator
+try:
+    from claude_mpm.core.api_validator import validate_api_keys
+except ImportError:
+    from ..core.api_validator import validate_api_keys
+
 # Import the service container and interfaces
 try:
     from claude_mpm.services.core.cache_manager import CacheManager
@@ -105,6 +111,7 @@ class FrameworkLoader:
         framework_path: Optional[Path] = None,
         agents_dir: Optional[Path] = None,
         service_container: Optional[ServiceContainer] = None,
+        config: Optional[Dict[str, Any]] = None,
     ):
         """
         Initialize framework loader.
@@ -113,11 +120,26 @@ class FrameworkLoader:
             framework_path: Explicit path to framework (auto-detected if None)
             agents_dir: Custom agents directory (overrides framework agents)
             service_container: Optional service container for dependency injection
+            config: Optional configuration dictionary for API validation and other settings
         """
         self.logger = get_logger("framework_loader")
         self.agents_dir = agents_dir
         self.framework_version = None
         self.framework_last_modified = None
+        self.config = config or {}
+
+        # Validate API keys on startup (before any other initialization)
+        if self.config.get("validate_api_keys", True):
+            try:
+                self.logger.info("Validating configured API keys...")
+                validate_api_keys(config=self.config, strict=True)
+                self.logger.info("✅ API key validation completed successfully")
+            except ValueError as e:
+                self.logger.error(f"❌ API key validation failed: {e}")
+                raise
+            except Exception as e:
+                self.logger.error(f"❌ Unexpected error during API validation: {e}")
+                raise
 
         # Use provided container or get global container
         self.container = service_container or get_global_container()