@jaguilar87/gaia-ops 4.4.0 → 4.7.2

package/tools/scan/scanners/git.py

@@ -370,6 +370,10 @@ class GitScanner(BaseScanner):
     def scan(self, root: Path) -> ScanResult:
         """Scan the project for git configuration.
 
+        In multi-repo mode (workspace_info.is_multi_repo), scans ALL
+        subdirectories with .git and produces a 'repos' array. In
+        single-repo mode, behaves as before.
+
         Args:
             root: Absolute path to the project root directory.
 
@@ -379,6 +383,17 @@ class GitScanner(BaseScanner):
         start_ms = time.monotonic() * 1000
         warnings: List[str] = []
 
+        # Multi-repo mode: scan all repo subdirectories
+        if self.workspace_info and self.workspace_info.is_multi_repo:
+            section = self._scan_multi_repo(root, warnings)
+            elapsed = (time.monotonic() * 1000) - start_ms
+            return self.make_result(
+                sections={"git": section},
+                warnings=warnings,
+                duration_ms=elapsed,
+            )
+
+        # Single-repo mode (original behavior)
         git_dir = root / ".git"
         git_root = root
 
@@ -446,6 +461,69 @@ class GitScanner(BaseScanner):
             duration_ms=elapsed,
         )
 
+    def _scan_multi_repo(
+        self, root: Path, warnings: List[str]
+    ) -> Dict[str, Any]:
+        """Scan all repos in a multi-repo workspace.
+
+        Produces a section with 'repos' array where each entry has:
+        name, path, remote_url, platform, default_branch.
+
+        Also determines the primary platform from the first repo's origin.
+
+        Args:
+            root: Workspace root path.
+            warnings: Warning accumulator.
+
+        Returns:
+            Git section dict with 'repos' array and aggregate fields.
+        """
+        repos: List[Dict[str, Any]] = []
+        primary_platform: Optional[str] = None
+
+        for repo_dir in self.workspace_info.repo_dirs:
+            git_dir = repo_dir / ".git"
+            if not git_dir.is_dir():
+                continue
+
+            git_config = _parse_git_config(git_dir)
+            remotes = git_config["remotes"]
+            platform = _determine_primary_platform(remotes)
+            default_branch = _detect_default_branch(git_dir)
+
+            # Get origin remote URL
+            origin_url = None
+            for remote in remotes:
+                if remote.get("name") == "origin":
+                    origin_url = remote.get("url")
+                    break
+            if origin_url is None and remotes:
+                origin_url = remotes[0].get("url")
+
+            repo_entry: Dict[str, Any] = {
+                "name": repo_dir.name,
+                "path": str(repo_dir.relative_to(root)),
+                "remote_url": origin_url,
+                "platform": platform,
+                "default_branch": default_branch,
+            }
+            repos.append(repo_entry)
+
+            if primary_platform is None and platform:
+                primary_platform = platform
+
+        return {
+            "platform": primary_platform,
+            "workspace_type": "multi-repo",
+            "repos": repos,
+            "branch_strategy": {
+                "detected": False,
+                "pattern": None,
+                "indicators": ["multi-repo workspace — per-repo strategies vary"],
+            },
+            "monorepo": {"workspace_config": None},
+        }
+
     @staticmethod
     def _find_git_in_subdirs(
         root: Path,

package/tools/scan/scanners/infrastructure.py

@@ -77,6 +77,9 @@ _CICD_MARKERS: List[Dict[str, Any]] = [
     {"platform": "gitlab-ci", "type": "file", "path": ".gitlab-ci.yml"},
     {"platform": "jenkins", "type": "file", "path": "Jenkinsfile"},
     {"platform": "circleci", "type": "dir", "path": ".circleci"},
+    {"platform": "bitbucket-pipelines", "type": "file", "path": "bitbucket-pipelines.yml"},
+    {"platform": "cloud-build", "type": "file", "path": "cloudbuild.yaml"},
+    {"platform": "cloud-build", "type": "file", "path": "cloudbuild.json"},
 ]
 
 # ---------------------------------------------------------------------------
@@ -114,6 +117,10 @@ class InfrastructureScanner(BaseScanner):
     def scan(self, root: Path) -> ScanResult:
         """Scan for infrastructure indicators.
 
+        In multi-repo mode, scans each repo subdirectory and tags IaC
+        entries with their containing repo name. In single-repo mode,
+        behaves as before.
+
         Args:
             root: Absolute path to the project root directory.
 
@@ -132,6 +139,12 @@ class InfrastructureScanner(BaseScanner):
             paths = self._detect_paths(root, warnings)
             app_services = self._detect_application_services(root, warnings)
 
+            # Multi-repo mode: also scan each repo subdirectory and tag results
+            if self.workspace_info and self.workspace_info.is_multi_repo:
+                self._enrich_multi_repo(
+                    root, iac, containers, ci_cd, warnings
+                )
+
             # Only produce section when at least one indicator is found
             has_indicators = (
                 cloud_providers
@@ -174,6 +187,58 @@ class InfrastructureScanner(BaseScanner):
             duration_ms = (time.monotonic() - start) * 1000
             return self.make_result(sections={}, warnings=[str(exc)], duration_ms=duration_ms)
 
+    def _enrich_multi_repo(
+        self,
+        root: Path,
+        iac: List[Dict[str, Any]],
+        containers: List[Dict[str, Any]],
+        ci_cd: List[Dict[str, Any]],
+        warnings: List[str],
+    ) -> None:
+        """Tag IaC, container, and CI/CD entries with their containing repo.
+
+        For each entry whose base_path or config_path starts with a known
+        repo directory, adds a 'repo' field with the repo name. This helps
+        agents understand which repo owns each infrastructure component.
+
+        Args:
+            root: Workspace root path.
+            iac: IaC entries list (mutated in place).
+            containers: Container entries list (mutated in place).
+            ci_cd: CI/CD entries list (mutated in place).
+            warnings: Warning accumulator.
+        """
+        repo_names = {
+            str(rd.relative_to(root)): rd.name
+            for rd in self.workspace_info.repo_dirs
+        }
+
+        def _tag_repo(entry: Dict[str, Any], path_key: str) -> None:
+            """Add 'repo' field if path matches a known repo directory."""
+            path_val = entry.get(path_key, "")
+            if not path_val:
+                return
+            for repo_path, repo_name in repo_names.items():
+                if path_val == repo_path or path_val.startswith(repo_path + "/"):
+                    entry["repo"] = repo_name
+                    return
+
+        for entry in iac:
+            _tag_repo(entry, "base_path")
+
+        for entry in containers:
+            # Containers use 'files' list; tag based on first file's directory
+            files = entry.get("files", [])
+            if files:
+                first_file = files[0]
+                for repo_path, repo_name in repo_names.items():
+                    if first_file.startswith(repo_path + "/") or first_file.startswith(repo_path):
+                        entry["repo"] = repo_name
+                        break
+
+        for entry in ci_cd:
+            _tag_repo(entry, "config_path")
+
     # ------------------------------------------------------------------
     # Cloud provider detection
     # ------------------------------------------------------------------

package/tools/scan/scanners/stack.py

@@ -151,6 +151,14 @@ class StackScanner(BaseScanner):
             build_tools = self._detect_build_tools(root, warnings)
             project_identity = self._detect_project_identity(root, languages, warnings)
 
+            # Multi-repo workspace override: if orchestrator detected multi-repo,
+            # set project type and add workspace_repos listing
+            if self.workspace_info and self.workspace_info.is_multi_repo:
+                project_identity["type"] = "multi-repo-workspace"
+                project_identity["workspace_repos"] = self._build_workspace_repos(
+                    root, self.workspace_info.repo_dirs, warnings
+                )
+
             sections: Dict[str, Any] = {
                 "project_identity": project_identity,
                 "stack": {
@@ -821,6 +829,108 @@ class StackScanner(BaseScanner):
 
         return result
 
+    # ------------------------------------------------------------------
+    # Multi-repo workspace helpers
+    # ------------------------------------------------------------------
+
+    def _build_workspace_repos(
+        self,
+        root: Path,
+        repo_dirs: List[Path],
+        warnings: List[str],
+    ) -> List[Dict[str, Any]]:
+        """Build workspace_repos list for multi-repo workspaces.
+
+        For each subdirectory with .git, extracts name, relative path,
+        and primary language from the most prominent manifest file.
+
+        Args:
+            root: Workspace root path.
+            repo_dirs: List of subdirectory Paths that contain .git.
+            warnings: Warning accumulator.
+
+        Returns:
+            List of repo descriptor dicts.
+        """
+        repos: List[Dict[str, Any]] = []
+
+        for repo_dir in repo_dirs:
+            repo_entry: Dict[str, Any] = {
+                "name": repo_dir.name,
+                "path": str(repo_dir.relative_to(root)),
+            }
+
+            # Detect primary language from manifest files
+            primary_language = self._detect_primary_language(repo_dir)
+            if primary_language:
+                repo_entry["primary_language"] = primary_language
+
+            # Detect role from directory naming conventions
+            repo_entry["role"] = self._infer_repo_role(repo_dir, primary_language)
+
+            repos.append(repo_entry)
+
+        return repos
+
+    @staticmethod
+    def _detect_primary_language(repo_dir: Path) -> Optional[str]:
+        """Detect the primary language of a repo from its manifest files."""
+        manifest_checks = [
+            ("package.json", "javascript"),
+            ("pyproject.toml", "python"),
+            ("setup.py", "python"),
+            ("requirements.txt", "python"),
+            ("go.mod", "go"),
+            ("Cargo.toml", "rust"),
+            ("pom.xml", "java"),
+            ("build.gradle", "java"),
+            ("composer.json", "php"),
+            ("Gemfile", "ruby"),
+        ]
+
+        for filename, language in manifest_checks:
+            if (repo_dir / filename).is_file():
+                # Check for TypeScript indicator
+                if language == "javascript":
+                    for f in repo_dir.iterdir():
+                        if f.is_file() and f.name.startswith("tsconfig") and f.name.endswith(".json"):
+                            return "typescript"
+                return language
+
+        return None
+
+    @staticmethod
+    def _infer_repo_role(repo_dir: Path, primary_language: Optional[str]) -> str:
+        """Infer the role of a repo from its name and contents.
+
+        Returns one of: gitops, iac, platform, agent, library, application.
+        """
+        name_lower = repo_dir.name.lower()
+
+        # GitOps indicators
+        if any(kw in name_lower for kw in ("gitops", "flux", "argocd", "deploy")):
+            return "gitops"
+
+        # IaC indicators
+        if any(kw in name_lower for kw in ("iac", "infra", "terraform")):
+            return "iac"
+        # Also check for .tf files at root
+        try:
+            if any(f.suffix == ".tf" for f in repo_dir.iterdir() if f.is_file()):
+                return "iac"
+        except OSError:
+            pass
+
+        # Platform indicators
+        if any(kw in name_lower for kw in ("platform", "core", "shared", "common")):
+            return "platform"
+
+        # Agent indicators
+        if any(kw in name_lower for kw in ("agent", "bot", "assistant")):
+            return "agent"
+
+        return "application"
+
     # ------------------------------------------------------------------
     # File search helpers
     # ------------------------------------------------------------------

package/tools/scan/setup.py

@@ -8,7 +8,7 @@ functionality that gaia-scan needs when operating on a fresh project
 Functions:
 - create_claude_directory: mkdir .claude/ with symlinks and subdirs
 - copy_claude_md: deprecated no-op (identity now via submit hook)
-- copy_settings_json: copy settings.template.json (always replaces)
+- copy_settings_json: create minimal settings.json only if missing (non-invasive)
 - install_git_hooks: copy commit-msg hook to all git repos
 - generate_governance: interpolate governance.template.md
 - ensure_gaia_ops_package: npm install @jaguilar87/gaia-ops
@@ -57,7 +57,7 @@ def _get_template_path(name: str) -> Path:
     """Get the path to a template file.
 
     Args:
-        name: Template filename (e.g., 'settings.template.json').
+        name: Template filename (e.g., 'governance.template.md').
 
     Returns:
         Absolute path to the template file.
@@ -229,7 +229,7 @@ def copy_claude_md(project_root: Path) -> bool:
     """Deprecated — CLAUDE.md is no longer generated from template.
 
     Orchestrator identity is now injected by the UserPromptSubmit hook
-    via ops_identity.py + on-demand skills (project-dispatch, agent-response).
+    via ops_identity.py + deterministic surface routing + on-demand skills (agent-response).
     This avoids two sources of truth.
 
     Kept as no-op for backward compatibility with callers.
@@ -239,33 +239,140 @@ def copy_claude_md(project_root: Path) -> bool:
 
 
 def copy_settings_json(project_root: Path) -> bool:
-    """Copy settings.template.json to .claude/settings.json.
+    """Create a minimal .claude/settings.json only if it does not exist.
 
-    Always overwrites -- settings.json is a system template that changes
-    with each version. The template is the source of truth.
+    Non-invasive: never overwrites an existing settings.json.  Hooks are
+    provided by hooks.json (auto-discovered via the .claude/hooks symlink).
+    Env vars and permissions live in settings.local.json.
 
     Args:
         project_root: Project root directory.
 
     Returns:
-        True if file was written successfully.
+        True if file exists (created or already present).
     """
-    template_path = _get_template_path("settings.template.json")
     dest_path = project_root / ".claude" / "settings.json"
 
-    if not template_path.is_file():
-        logger.warning("settings.template.json not found at %s", template_path)
-        return False
+    if dest_path.is_file():
+        logger.info("settings.json already exists — not overwriting")
+        return True
 
     try:
-        shutil.copy2(str(template_path), str(dest_path))
-        logger.info("settings.json updated from template")
+        dest_path.parent.mkdir(parents=True, exist_ok=True)
+        dest_path.write_text("{}\n")
+        logger.info("settings.json created (minimal — hooks from hooks.json, env from settings.local.json)")
         return True
     except OSError as exc:
         logger.error("Failed to write settings.json: %s", exc)
         return False
 
 
+def merge_hooks_to_settings_local(project_root: Path) -> bool:
+    """Merge hooks from hooks.json into .claude/settings.local.json.
+
+    In npm mode, Claude Code reads hooks from settings files, not hooks.json
+    directly. This reads hooks.json from the installed package, converts
+    ${CLAUDE_PLUGIN_ROOT}/hooks/<script> paths to .claude/hooks/<script>,
+    and merges into settings.local.json with deduplication by command string.
+
+    Args:
+        project_root: Project root directory.
+
+    Returns:
+        True if settings.local.json was modified.
+    """
+    import re
+
+    claude_dir = project_root / ".claude"
+    settings_path = claude_dir / "settings.local.json"
+
+    # Find hooks.json from the package
+    hooks_json_path = None
+    # Strategy 1: installed npm package
+    pkg_root = _find_installed_package_root(project_root)
+    if pkg_root:
+        candidate = pkg_root / "hooks" / "hooks.json"
+        if candidate.is_file():
+            hooks_json_path = candidate
+    # Strategy 2: running from source (gaia-scan direct)
+    if not hooks_json_path:
+        candidate = _find_package_root() / "hooks" / "hooks.json"
+        if candidate.is_file():
+            hooks_json_path = candidate
+
+    if not hooks_json_path:
+        logger.info("hooks.json not found, skipping hooks merge")
+        return False
+
+    try:
+        hooks_data = json.loads(hooks_json_path.read_text())
+    except (json.JSONDecodeError, OSError):
+        logger.warning("hooks.json is invalid, skipping hooks merge")
+        return False
+
+    # Unwrap outer "hooks" key if present
+    source_hooks = hooks_data.get("hooks", hooks_data)
+
+    # Convert ${CLAUDE_PLUGIN_ROOT}/hooks/<script> to .claude/hooks/<script>
+    def convert_command(cmd: str) -> str:
+        return re.sub(r'\$\{CLAUDE_PLUGIN_ROOT\}/hooks/', '.claude/hooks/', cmd)
+
+    converted_hooks: Dict[str, list] = {}
+    for event, entries in source_hooks.items():
+        converted_hooks[event] = []
+        for entry in entries:
+            new_entry = dict(entry)
+            if "hooks" in new_entry:
+                new_entry["hooks"] = [
+                    {**h, "command": convert_command(h["command"])} if "command" in h else h
+                    for h in new_entry["hooks"]
+                ]
+            converted_hooks[event].append(new_entry)
+
+    # Load existing settings.local.json
+    existing: Dict[str, Any] = {}
+    if settings_path.exists():
+        try:
+            existing = json.loads(settings_path.read_text())
+        except (json.JSONDecodeError, OSError):
+            existing = {}
+
+    # Smart merge: deduplicate by command string
+    existing_hooks = existing.get("hooks", {})
+    changed = False
+
+    for event, new_entries in converted_hooks.items():
+        if event not in existing_hooks:
+            existing_hooks[event] = new_entries
+            changed = True
+            continue
+
+        # Collect existing command strings
+        existing_commands: set = set()
+        for entry in existing_hooks[event]:
+            for h in entry.get("hooks", []):
+                if "command" in h:
+                    existing_commands.add(h["command"])
+
+        # Add entries whose commands are not already present
+        for new_entry in new_entries:
+            new_commands = [h["command"] for h in new_entry.get("hooks", []) if "command" in h]
+            all_present = len(new_commands) > 0 and all(c in existing_commands for c in new_commands)
+            if not all_present:
+                existing_hooks[event].append(new_entry)
+                changed = True
+
+    if not changed:
+        logger.info("settings.local.json hooks already up to date")
+        return False
+
+    existing["hooks"] = existing_hooks
+    claude_dir.mkdir(parents=True, exist_ok=True)
+    settings_path.write_text(json.dumps(existing, indent=2) + "\n")
+    logger.info("Merged hooks into %s", settings_path)
+    return True
+
+
 def install_git_hooks(project_root: Path) -> int:
     """Install commit-msg git hook to all detected git repositories.
 

package/tools/scan/workspace.py

@@ -0,0 +1,85 @@
+"""
+Workspace Type Detection
+
+Detects whether the scan root is a single-repo, monorepo, or multi-repo workspace.
+Called by the orchestrator before individual scanners run, and importable by scanners
+that need workspace-aware behavior.
+
+Detection logic:
+  - If root has .git -> single-repo or monorepo (determined by stack scanner)
+  - If root has NO .git but 2+ immediate subdirectories have .git -> multi-repo-workspace
+  - Otherwise -> single-repo (default)
+"""
+
+import logging
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import List, Optional
+
+logger = logging.getLogger(__name__)
+
+# Directories to always skip during workspace scanning
+_SKIP_DIRS = frozenset({
+    "node_modules", "__pycache__", ".tox", ".venv",
+    "venv", "dist", "build", ".next", ".nuxt", "target",
+    ".pytest_cache", ".mypy_cache", ".ruff_cache", "vendor",
+    ".terraform", ".terragrunt-cache",
+})
+
+
+@dataclass(frozen=True)
+class WorkspaceInfo:
+    """Result of workspace type detection.
+
+    Attributes:
+        workspace_type: One of 'single-repo', 'monorepo', 'multi-repo-workspace'.
+        repo_dirs: For multi-repo, list of subdirectory Paths that contain .git.
+                   Empty for single-repo/monorepo.
+    """
+
+    workspace_type: str = "single-repo"
+    repo_dirs: List[Path] = field(default_factory=list)
+
+    @property
+    def is_multi_repo(self) -> bool:
+        return self.workspace_type == "multi-repo-workspace"
+
+
+def detect_workspace_type(root: Path) -> WorkspaceInfo:
+    """Detect the workspace type for the given root directory.
+
+    Args:
+        root: Absolute path to the project root directory.
+
+    Returns:
+        WorkspaceInfo with the detected workspace type and repo directories.
+    """
+    # If root itself has .git, it's a normal repo (single or monorepo)
+    if (root / ".git").is_dir():
+        return WorkspaceInfo(workspace_type="single-repo")
+
+    # Check immediate subdirectories for .git
+    git_subdirs: List[Path] = []
+    try:
+        for entry in sorted(root.iterdir()):
+            if not entry.is_dir():
+                continue
+            if entry.name.startswith(".") or entry.name in _SKIP_DIRS:
+                continue
+            if (entry / ".git").is_dir():
+                git_subdirs.append(entry)
+    except (PermissionError, OSError) as exc:
+        logger.debug("Failed to scan subdirectories of %s: %s", root, exc)
+
+    if len(git_subdirs) >= 2:
+        logger.info(
+            "Multi-repo workspace detected: %d repos in %s",
+            len(git_subdirs),
+            root,
+        )
+        return WorkspaceInfo(
+            workspace_type="multi-repo-workspace",
+            repo_dirs=git_subdirs,
+        )
+
+    return WorkspaceInfo(workspace_type="single-repo")

package/config/context-contracts.aws.json

@@ -1,42 +0,0 @@
-{
-  "_note": "Legacy file. Canonical source: context-contracts.json + cloud/{provider}.json",
-  "version": "3.0",
-  "provider": "aws",
-  "description": "Legacy AWS contracts (self-contained). Kept for backward compatibility with tests. Canonical source: context-contracts.json + cloud/aws.json. v3: removed backward-compat sections.",
-  "agents": {
-    "cloud-troubleshooter": {
-      "read": ["project_identity", "stack", "git", "environment",
-               "infrastructure", "orchestration", "cluster_details",
-               "infrastructure_topology", "terraform_infrastructure",
-               "gitops_configuration", "application_services",
-               "monitoring_observability",
-               "vpc_mapping", "load_balancers"],
-      "write": ["cluster_details", "infrastructure_topology", "vpc_mapping"]
-    },
-    "gitops-operator": {
-      "read": ["project_identity", "stack", "git", "environment",
-               "infrastructure", "orchestration", "gitops_configuration",
-               "cluster_details", "operational_guidelines"],
-      "write": ["gitops_configuration", "cluster_details"]
-    },
-    "terraform-architect": {
-      "read": ["project_identity", "stack", "git", "environment",
-               "infrastructure", "orchestration", "terraform_infrastructure",
-               "infrastructure_topology", "operational_guidelines",
-               "vpc_mapping", "load_balancers", "api_gateway"],
-      "write": ["terraform_infrastructure", "infrastructure_topology",
-                "vpc_mapping", "load_balancers", "api_gateway"]
-    },
-    "devops-developer": {
-      "read": ["project_identity", "stack", "git", "environment",
-               "infrastructure", "application_services",
-               "operational_guidelines"],
-      "write": ["application_services"]
-    },
-    "speckit-planner": {
-      "read": ["project_identity", "stack", "git", "environment",
-               "infrastructure", "operational_guidelines"],
-      "write": ["operational_guidelines"]
-    }
-  }
-}

package/config/context-contracts.gcp.json

@@ -1,39 +0,0 @@
-{
-  "_note": "Legacy file. Canonical source: context-contracts.json + cloud/{provider}.json",
-  "version": "3.0",
-  "provider": "gcp",
-  "description": "Legacy GCP contracts (self-contained). Kept for backward compatibility with tests. Canonical source: context-contracts.json + cloud/gcp.json. v3: removed backward-compat sections.",
-  "agents": {
-    "cloud-troubleshooter": {
-      "read": ["project_identity", "stack", "git", "environment",
-               "infrastructure", "orchestration", "cluster_details",
-               "infrastructure_topology", "terraform_infrastructure",
-               "gitops_configuration", "application_services",
-               "monitoring_observability"],
-      "write": ["cluster_details", "infrastructure_topology"]
-    },
-    "gitops-operator": {
-      "read": ["project_identity", "stack", "git", "environment",
-               "infrastructure", "orchestration", "gitops_configuration",
-               "cluster_details", "operational_guidelines"],
-      "write": ["gitops_configuration", "cluster_details"]
-    },
-    "terraform-architect": {
-      "read": ["project_identity", "stack", "git", "environment",
-               "infrastructure", "orchestration", "terraform_infrastructure",
-               "infrastructure_topology", "operational_guidelines"],
-      "write": ["terraform_infrastructure", "infrastructure_topology"]
-    },
-    "devops-developer": {
-      "read": ["project_identity", "stack", "git", "environment",
-               "infrastructure", "application_services",
-               "operational_guidelines"],
-      "write": ["application_services"]
-    },
-    "speckit-planner": {
-      "read": ["project_identity", "stack", "git", "environment",
-               "infrastructure", "operational_guidelines"],
-      "write": []
-    }
-  }
-}