aiox-core 5.0.7 → 5.0.8

package/.claude/skills/architect-first/scripts/check_coupling.py

@@ -0,0 +1,306 @@
+#!/usr/bin/env python3
+"""
+Zero-Coupling Validation Script
+
+Validates that modules/expansion-packs maintain zero-coupling principle:
+- No hardcoded cross-module imports
+- No hardcoded file paths to other modules
+- Configuration-based integration only
+
+Usage:
+    python check_coupling.py [--path PROJECT_PATH] [--config CONFIG_FILE]
+"""
+
+import os
+import re
+import sys
+import argparse
+from pathlib import Path
+from typing import List, Dict, Set, Tuple
+import yaml
+
+
+class CouplingViolation:
+    """Represents a coupling violation found in code"""
+
+    def __init__(
+        self,
+        file_path: str,
+        line_number: int,
+        line_content: str,
+        violation_type: str,
+        description: str,
+    ):
+        self.file_path = file_path
+        self.line_number = line_number
+        self.line_content = line_content.strip()
+        self.violation_type = violation_type
+        self.description = description
+
+    def __str__(self):
+        return (
+            f"\n  {self.violation_type}: {self.file_path}:{self.line_number}\n"
+            f"  {self.description}\n"
+            f"  > {self.line_content}"
+        )
+
+
+class CouplingChecker:
+    """Checks for coupling violations in codebase"""
+
+    def __init__(self, project_path: Path, config_path: Path = None):
+        self.project_path = project_path
+        self.violations: List[CouplingViolation] = []
+        self.config = self._load_config(config_path)
+
+        # Modules to check for coupling (from config or defaults)
+        self.modules = self.config.get("modules", [])
+        if not self.modules:
+            # Auto-detect expansion packs
+            expansion_pack_dir = project_path / "expansion-packs"
+            if expansion_pack_dir.exists():
+                self.modules = [
+                    d.name for d in expansion_pack_dir.iterdir() if d.is_dir()
+                ]
+
+        # File patterns to scan
+        self.file_patterns = self.config.get(
+            "file_patterns", ["*.py", "*.js", "*.ts", "*.yaml", "*.yml"]
+        )
+
+        # Exclude patterns
+        self.exclude_patterns = self.config.get(
+            "exclude_patterns",
+            [
+                "**/node_modules/**",
+                "**/__pycache__/**",
+                "**/venv/**",
+                "**/.venv/**",
+                "**/dist/**",
+                "**/build/**",
+            ],
+        )
+
+    def _load_config(self, config_path: Path = None) -> Dict:
+        """Load configuration file if exists"""
+        if config_path and config_path.exists():
+            with open(config_path, "r") as f:
+                return yaml.safe_load(f) or {}
+
+        # Try default config location
+        default_config = self.project_path / ".coupling-check.yaml"
+        if default_config.exists():
+            with open(default_config, "r") as f:
+                return yaml.safe_load(f) or {}
+
+        return {}
+
+    def _should_exclude(self, file_path: Path) -> bool:
+        """Check if file should be excluded from scanning"""
+        path_str = str(file_path)
+        for pattern in self.exclude_patterns:
+            if Path(path_str).match(pattern):
+                return True
+        return False
+
+    def _find_files_to_scan(self) -> List[Path]:
+        """Find all files to scan for coupling violations"""
+        files = []
+        for pattern in self.file_patterns:
+            for file_path in self.project_path.rglob(pattern):
+                if file_path.is_file() and not self._should_exclude(file_path):
+                    files.append(file_path)
+        return files
+
+    def _check_hardcoded_imports(self, file_path: Path, content: str):
+        """Check for hardcoded imports to other modules"""
+        lines = content.split("\n")
+
+        for line_num, line in enumerate(lines, 1):
+            # Python imports
+            if re.match(r"^\s*(from|import)\s+", line):
+                for module in self.modules:
+                    # Check if importing from another module directly
+                    if re.search(rf"\bfrom\s+{module}\b", line) or re.search(
+                        rf"\bimport\s+{module}\b", line
+                    ):
+                        self.violations.append(
+                            CouplingViolation(
+                                str(file_path),
+                                line_num,
+                                line,
+                                "HARDCODED_IMPORT",
+                                f"Direct import of module '{module}'. "
+                                f"Use plugin/config-based loading instead.",
+                            )
+                        )
+
+            # JavaScript/TypeScript imports
+            if re.search(r"(import|require)\s*\(?\s*['\"]", line):
+                for module in self.modules:
+                    if module in line:
+                        self.violations.append(
+                            CouplingViolation(
+                                str(file_path),
+                                line_num,
+                                line,
+                                "HARDCODED_IMPORT",
+                                f"Direct import of module '{module}'. "
+                                f"Use plugin/config-based loading instead.",
+                            )
+                        )
+
+    def _check_hardcoded_paths(self, file_path: Path, content: str):
+        """Check for hardcoded file paths to other modules"""
+        lines = content.split("\n")
+
+        for line_num, line in enumerate(lines, 1):
+            # Look for file path patterns
+            path_patterns = [
+                r'["\']([^"\']*(?:expansion-packs|modules)/([^"\']+))["\']',
+                r"Path\(['\"]([^'\"]*(?:expansion-packs|modules)/[^'\"]+)['\"]\)",
+            ]
+
+            for pattern in path_patterns:
+                matches = re.finditer(pattern, line)
+                for match in matches:
+                    path_str = match.group(1)
+                    # Check if path references another module
+                    for module in self.modules:
+                        if module in path_str:
+                            self.violations.append(
+                                CouplingViolation(
+                                    str(file_path),
+                                    line_num,
+                                    line,
+                                    "HARDCODED_PATH",
+                                    f"Hardcoded path to module '{module}': {path_str}. "
+                                    f"Use configuration-based path resolution.",
+                                )
+                            )
+
+    def _check_shared_state(self, file_path: Path, content: str):
+        """Check for shared global state between modules"""
+        lines = content.split("\n")
+
+        # Patterns that suggest shared state
+        shared_state_patterns = [
+            (r"\bglobal\s+\w+", "Global variable usage"),
+            (r"^\s*[A-Z_]+\s*=\s*", "Module-level constant that might be shared"),
+        ]
+
+        for line_num, line in enumerate(lines, 1):
+            for pattern, description in shared_state_patterns:
+                if re.search(pattern, line):
+                    # Check if it references other modules
+                    for module in self.modules:
+                        if module.lower() in line.lower():
+                            self.violations.append(
+                                CouplingViolation(
+                                    str(file_path),
+                                    line_num,
+                                    line,
+                                    "SHARED_STATE",
+                                    f"{description} referencing '{module}'.",
+                                )
+                            )
+
+    def check_file(self, file_path: Path):
+        """Check a single file for coupling violations"""
+        try:
+            with open(file_path, "r", encoding="utf-8") as f:
+                content = f.read()
+
+            self._check_hardcoded_imports(file_path, content)
+            self._check_hardcoded_paths(file_path, content)
+            self._check_shared_state(file_path, content)
+
+        except Exception as e:
+            print(f"Warning: Could not scan {file_path}: {e}", file=sys.stderr)
+
+    def run(self) -> int:
+        """Run coupling check on entire project"""
+        print("🔍 Checking for coupling violations...")
+        print(f"   Project: {self.project_path}")
+        print(f"   Modules: {', '.join(self.modules)}")
+        print()
+
+        files = self._find_files_to_scan()
+        print(f"📁 Scanning {len(files)} files...")
+        print()
+
+        for file_path in files:
+            self.check_file(file_path)
+
+        return self._report_results()
+
+    def _report_results(self) -> int:
+        """Report results and return exit code"""
+        if not self.violations:
+            print("✅ No coupling violations found!")
+            print("   Zero-coupling principle maintained.")
+            return 0
+
+        print(f"❌ Found {len(self.violations)} coupling violation(s):")
+
+        # Group violations by type
+        by_type: Dict[str, List[CouplingViolation]] = {}
+        for violation in self.violations:
+            if violation.violation_type not in by_type:
+                by_type[violation.violation_type] = []
+            by_type[violation.violation_type].append(violation)
+
+        # Report by type
+        for violation_type, violations in by_type.items():
+            print(f"\n{violation_type} ({len(violations)}):")
+            for violation in violations:
+                print(violation)
+
+        print("\n" + "=" * 80)
+        print("REMEDIATION STEPS:")
+        print("=" * 80)
+        print()
+        print("1. Remove hardcoded imports:")
+        print("   - Use plugin/adapter pattern")
+        print("   - Load modules via configuration")
+        print("   - Implement dependency injection")
+        print()
+        print("2. Externalize paths to YAML configuration:")
+        print("   - Define module paths in config file")
+        print("   - Use configuration loader to resolve paths")
+        print("   - Never hardcode cross-module paths")
+        print()
+        print("3. Eliminate shared state:")
+        print("   - Use message passing between modules")
+        print("   - Implement clean interfaces")
+        print("   - Each module maintains its own state")
+        print()
+        print("See: references/stop-rules-guide.md (Stop Rule 3)")
+        print()
+
+        return 1  # Exit code 1 indicates violations found
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Check for coupling violations in codebase"
+    )
+    parser.add_argument(
+        "--path",
+        type=Path,
+        default=Path.cwd(),
+        help="Project path to scan (default: current directory)",
+    )
+    parser.add_argument(
+        "--config", type=Path, help="Configuration file path (YAML)"
+    )
+
+    args = parser.parse_args()
+
+    checker = CouplingChecker(args.path, args.config)
+    exit_code = checker.run()
+    sys.exit(exit_code)
+
+
+if __name__ == "__main__":
+    main()

package/.claude/skills/architect-first/scripts/validate_risk_mitigation.py

@@ -0,0 +1,382 @@
+#!/usr/bin/env python3
+"""
+Risk Mitigation Validation Script
+
+Validates that identified risks have appropriate mitigation strategies.
+Checks project documentation for risk/mitigation coverage.
+
+Usage:
+    python validate_risk_mitigation.py [--path PROJECT_PATH] [--risks RISKS_FILE]
+"""
+
+import os
+import sys
+import argparse
+import re
+from pathlib import Path
+from typing import List, Dict, Tuple
+import yaml
+
+
+class Risk:
+    """Represents an identified risk"""
+
+    def __init__(self, name: str, description: str, severity: str, source: str):
+        self.name = name
+        self.description = description
+        self.severity = severity  # high, medium, low
+        self.source = source  # file where risk identified
+        self.mitigation = None
+
+    def __str__(self):
+        status = "✅ MITIGATED" if self.mitigation else "❌ NO MITIGATION"
+        return (
+            f"\n  [{self.severity.upper()}] {self.name}\n"
+            f"  {self.description}\n"
+            f"  Source: {self.source}\n"
+            f"  Status: {status}"
+        )
+
+
+class RiskMitigationValidator:
+    """Validates risk mitigation coverage"""
+
+    def __init__(self, project_path: Path, risks_file: Path = None):
+        self.project_path = project_path
+        self.risks_file = risks_file
+        self.risks: List[Risk] = []
+        self.mitigation_docs: Dict[str, str] = {}
+
+    def _find_risk_documents(self) -> List[Path]:
+        """Find all documents that might contain risks"""
+        risk_doc_patterns = [
+            "**/architecture/*.md",
+            "**/design/*.md",
+            "**/docs/**/*risk*.md",
+            "**/docs/**/*adr*.md",  # Architecture Decision Records
+            "**/*RISK*.md",
+        ]
+
+        docs = []
+        for pattern in risk_doc_patterns:
+            docs.extend(self.project_path.glob(pattern))
+
+        return list(set(docs))  # Remove duplicates
+
+    def _extract_risks_from_doc(self, doc_path: Path):
+        """Extract risks from a document"""
+        try:
+            with open(doc_path, "r", encoding="utf-8") as f:
+                content = f.read()
+
+            # Look for risk sections
+            risk_patterns = [
+                # Markdown headers with "risk"
+                r"#{1,6}\s+.*[Rr]isks?\s*.*\n(.*?)(?=\n#{1,6}|\Z)",
+                # Table format
+                r"\|\s*[Rr]isk\s*\|.*\n\|[-\s|]+\n((?:\|.*\n)*)",
+                # Bullet points
+                r"[-*]\s+\*\*[Rr]isk:?\*\*\s+(.*?)(?=\n[-*]|\n\n|\Z)",
+            ]
+
+            for pattern in risk_patterns:
+                matches = re.finditer(pattern, content, re.MULTILINE | re.DOTALL)
+                for match in matches:
+                    risk_text = match.group(1)
+                    self._parse_risks_from_text(risk_text, str(doc_path))
+
+        except Exception as e:
+            print(f"Warning: Could not parse {doc_path}: {e}", file=sys.stderr)
+
+    def _parse_risks_from_text(self, text: str, source: str):
+        """Parse individual risks from text block"""
+        # Simple heuristic: each line or paragraph is a risk
+        lines = [l.strip() for l in text.split("\n") if l.strip()]
+
+        for line in lines:
+            # Skip table headers
+            if re.match(r"^\|?[-\s|]+\|?$", line):
+                continue
+
+            # Extract from table row: | risk | description | severity |
+            table_match = re.match(r"\|\s*([^|]+)\s*\|\s*([^|]+)\s*\|", line)
+            if table_match:
+                name = table_match.group(1).strip()
+                description = table_match.group(2).strip()
+                severity = self._infer_severity(name, description)
+                self.risks.append(Risk(name, description, severity, source))
+                continue
+
+            # Extract from bullet: - **Risk:** description
+            bullet_match = re.match(
+                r"[-*]\s+\*\*([^:*]+):?\*\*\s+(.*)", line, re.IGNORECASE
+            )
+            if bullet_match:
+                name = bullet_match.group(1).strip()
+                description = bullet_match.group(2).strip()
+                severity = self._infer_severity(name, description)
+                self.risks.append(Risk(name, description, severity, source))
+                continue
+
+            # Generic line as risk
+            if len(line) > 10:  # Minimum length to be meaningful
+                severity = self._infer_severity(line, line)
+                self.risks.append(Risk(line[:50], line, severity, source))
+
+    def _infer_severity(self, name: str, description: str) -> str:
+        """Infer severity from risk name/description"""
+        text = (name + " " + description).lower()
+
+        high_keywords = ["critical", "severe", "major", "high", "blocker"]
+        low_keywords = ["minor", "low", "trivial", "cosmetic"]
+
+        if any(kw in text for kw in high_keywords):
+            return "high"
+        elif any(kw in text for kw in low_keywords):
+            return "low"
+        else:
+            return "medium"
+
+    def _find_mitigation_documents(self) -> List[Path]:
+        """Find documents that might contain mitigations"""
+        mitigation_patterns = [
+            "**/architecture/*.md",
+            "**/design/*.md",
+            "**/docs/**/*mitigation*.md",
+            "**/docs/**/*strategy*.md",
+            "**/*MITIGATION*.md",
+        ]
+
+        docs = []
+        for pattern in mitigation_patterns:
+            docs.extend(self.project_path.glob(pattern))
+
+        return list(set(docs))
+
+    def _extract_mitigations_from_doc(self, doc_path: Path):
+        """Extract mitigations from document"""
+        try:
+            with open(doc_path, "r", encoding="utf-8") as f:
+                content = f.read()
+
+            # Store entire content as potential mitigation source
+            self.mitigation_docs[str(doc_path)] = content
+
+        except Exception as e:
+            print(
+                f"Warning: Could not parse {doc_path}: {e}", file=sys.stderr
+            )
+
+    def _match_risks_to_mitigations(self):
+        """Match identified risks to mitigations"""
+        for risk in self.risks:
+            # Search for risk name/keywords in mitigation docs
+            risk_keywords = set(
+                re.findall(r"\b\w{4,}\b", risk.name.lower())
+            )  # Words 4+ chars
+
+            for doc_path, content in self.mitigation_docs.items():
+                content_lower = content.lower()
+
+                # Check if risk keywords appear in mitigation section
+                if any(keyword in content_lower for keyword in risk_keywords):
+                    # Look for mitigation keywords nearby
+                    mitigation_keywords = [
+                        "mitigation",
+                        "mitigate",
+                        "solution",
+                        "strategy",
+                        "address",
+                        "resolve",
+                    ]
+
+                    if any(kw in content_lower for kw in mitigation_keywords):
+                        risk.mitigation = doc_path
+                        break
+
+    def _load_risks_from_yaml(self):
+        """Load risks from YAML file if provided"""
+        if not self.risks_file or not self.risks_file.exists():
+            return
+
+        try:
+            with open(self.risks_file, "r") as f:
+                data = yaml.safe_load(f)
+
+            if "risks" in data:
+                for risk_data in data["risks"]:
+                    risk = Risk(
+                        name=risk_data.get("name", "Unnamed"),
+                        description=risk_data.get("description", ""),
+                        severity=risk_data.get("severity", "medium"),
+                        source=str(self.risks_file),
+                    )
+
+                    # Check if mitigation provided in YAML
+                    if "mitigation" in risk_data:
+                        risk.mitigation = "YAML: " + risk_data["mitigation"]
+
+                    self.risks.append(risk)
+
+        except Exception as e:
+            print(
+                f"Warning: Could not load risks from {self.risks_file}: {e}",
+                file=sys.stderr,
+            )
+
+    def run(self) -> int:
+        """Run risk mitigation validation"""
+        print("🔍 Validating risk mitigation coverage...")
+        print(f"   Project: {self.project_path}")
+        print()
+
+        # Load risks from YAML if provided
+        if self.risks_file:
+            print(f"📄 Loading risks from: {self.risks_file}")
+            self._load_risks_from_yaml()
+
+        # Find and parse risk documents
+        print("📁 Scanning project documentation for risks...")
+        risk_docs = self._find_risk_documents()
+        print(f"   Found {len(risk_docs)} potential risk documents")
+
+        for doc in risk_docs:
+            self._extract_risks_from_doc(doc)
+
+        print(f"   Identified {len(self.risks)} risks")
+        print()
+
+        # Find mitigation documents
+        print("📁 Scanning for mitigation documentation...")
+        mitigation_docs = self._find_mitigation_documents()
+        print(f"   Found {len(mitigation_docs)} potential mitigation documents")
+
+        for doc in mitigation_docs:
+            self._extract_mitigations_from_doc(doc)
+
+        print()
+
+        # Match risks to mitigations
+        print("🔗 Matching risks to mitigations...")
+        self._match_risks_to_mitigations()
+        print()
+
+        return self._report_results()
+
+    def _report_results(self) -> int:
+        """Report results and return exit code"""
+        if not self.risks:
+            print("⚠️  No risks identified in project documentation.")
+            print(
+                "   This might mean:"
+            )
+            print("   - Project has no documented risks")
+            print("   - Risk documentation not in expected locations")
+            print("   - Risk documentation format not recognized")
+            print()
+            print("   Recommended: Create risk documentation in:")
+            print("   - docs/architecture/risks.md")
+            print("   - Design documents with ## Risks section")
+            print("   - Architecture Decision Records (ADRs)")
+            return 0
+
+        # Categorize risks
+        mitigated = [r for r in self.risks if r.mitigation]
+        unmitigated = [r for r in self.risks if not r.mitigation]
+
+        high_unmitigated = [
+            r for r in unmitigated if r.severity == "high"
+        ]
+
+        print("=" * 80)
+        print("RISK MITIGATION REPORT")
+        print("=" * 80)
+        print()
+        print(f"Total Risks: {len(self.risks)}")
+        print(f"Mitigated: {len(mitigated)}")
+        print(f"Unmitigated: {len(unmitigated)}")
+        print()
+
+        if high_unmitigated:
+            print(f"⚠️  HIGH PRIORITY: {len(high_unmitigated)} high-severity risks without mitigation")
+            print()
+
+        # Report unmitigated risks first
+        if unmitigated:
+            print("❌ UNMITIGATED RISKS:")
+            for risk in sorted(
+                unmitigated, key=lambda r: {"high": 0, "medium": 1, "low": 2}[r.severity]
+            ):
+                print(risk)
+            print()
+
+        # Report mitigated risks
+        if mitigated:
+            print("✅ MITIGATED RISKS:")
+            for risk in mitigated:
+                print(risk)
+                print(f"  Mitigation: {risk.mitigation}")
+            print()
+
+        # Overall assessment
+        coverage = len(mitigated) / len(self.risks) * 100 if self.risks else 0
+
+        print("=" * 80)
+        print(f"COVERAGE: {coverage:.1f}%")
+        print("=" * 80)
+        print()
+
+        if coverage == 100:
+            print("✅ All identified risks have mitigation strategies!")
+            return 0
+        elif coverage >= 80:
+            print("⚠️  Good coverage, but some risks lack mitigation.")
+            if not high_unmitigated:
+                print("   No high-severity risks unmitigated. Consider acceptable.")
+                return 0
+        else:
+            print("❌ Low mitigation coverage. Address unmitigated risks.")
+
+        if unmitigated:
+            print()
+            print("REMEDIATION STEPS:")
+            print("-" * 80)
+            print("1. Document mitigation strategy for each unmitigated risk")
+            print("2. Create mitigation documentation in:")
+            print("   - Architecture Decision Records (ADRs)")
+            print("   - Design documents (## Risk Mitigation section)")
+            print("   - Dedicated mitigation strategy documents")
+            print("3. For each risk, specify:")
+            print("   - Mitigation approach (avoid, reduce, transfer, accept)")
+            print("   - Concrete steps to implement mitigation")
+            print("   - Contingency plan if mitigation fails")
+            print("   - Responsible party/team")
+            print()
+
+        # Exit code based on high-severity unmitigated risks
+        return 1 if high_unmitigated else 0
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Validate risk mitigation coverage"
+    )
+    parser.add_argument(
+        "--path",
+        type=Path,
+        default=Path.cwd(),
+        help="Project path to scan (default: current directory)",
+    )
+    parser.add_argument(
+        "--risks", type=Path, help="YAML file with explicit risk definitions"
+    )
+
+    args = parser.parse_args()
+
+    validator = RiskMitigationValidator(args.path, args.risks)
+    exit_code = validator.run()
+    sys.exit(exit_code)
+
+
+if __name__ == "__main__":
+    main()