@jaguilar87/gaia-ops 2.5.8 → 2.6.0

package/bin/gaia-cleanup.js

@@ -25,7 +25,7 @@
 
 import { join, dirname, resolve } from 'path';
 import fs from 'fs/promises';
-import { existsSync } from 'fs';
+import { existsSync, lstatSync } from 'fs';
 import chalk from 'chalk';
 import ora from 'ora';
 
@@ -136,13 +136,15 @@ async function removeSymlinks() {
 
     let removed = 0;
     for (const symlinkPath of symlinks) {
-      if (existsSync(symlinkPath)) {
-        try {
+      try {
+        // Use lstat to check if path exists as a symlink (works for broken symlinks too)
+        const stats = lstatSync(symlinkPath);
+        if (stats.isSymbolicLink() || stats.isFile()) {
           await fs.unlink(symlinkPath);
           removed++;
-        } catch (error) {
-          // Ignore errors
         }
+      } catch (error) {
+        // Path doesn't exist or other error, skip
       }
     }
 

package/bin/gaia-uninstall.js

@@ -0,0 +1,111 @@
+#!/usr/bin/env node
+
+/**
+ * @jaguilar87/gaia-ops - Uninstall wrapper
+ *
+ * Safely uninstalls gaia-ops by:
+ * 1. Running gaia-cleanup to remove all generated files
+ * 2. Running npm uninstall to remove the package
+ *
+ * Usage:
+ *   npx gaia-uninstall
+ *   OR
+ *   npm exec gaia-uninstall
+ *
+ * This ensures a clean uninstallation with no leftover files.
+ */
+
+import { execSync } from 'child_process';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+import { existsSync } from 'fs';
+import chalk from 'chalk';
+import ora from 'ora';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const CWD = process.env.INIT_CWD || process.cwd();
+
+/**
+ * Run gaia-cleanup to remove generated files
+ */
+async function runCleanup() {
+  const spinner = ora('Running cleanup...').start();
+
+  try {
+    // Import and execute gaia-cleanup
+    const cleanupScript = join(__dirname, 'gaia-cleanup.js');
+
+    if (!existsSync(cleanupScript)) {
+      spinner.fail('Cleanup script not found');
+      return false;
+    }
+
+    // Execute cleanup by importing it
+    await import(`file://${cleanupScript}`);
+
+    spinner.succeed('Cleanup completed');
+    return true;
+  } catch (error) {
+    spinner.fail(`Cleanup failed: ${error.message}`);
+    return false;
+  }
+}
+
+/**
+ * Run npm uninstall
+ */
+function runUninstall() {
+  const spinner = ora('Uninstalling @jaguilar87/gaia-ops...').start();
+
+  try {
+    execSync('npm uninstall @jaguilar87/gaia-ops', {
+      cwd: CWD,
+      stdio: 'inherit'
+    });
+
+    spinner.succeed('Package uninstalled');
+    return true;
+  } catch (error) {
+    spinner.fail(`Uninstall failed: ${error.message}`);
+    return false;
+  }
+}
+
+/**
+ * Main function
+ */
+async function main() {
+  console.log(chalk.cyan('\n🗑️  @jaguilar87/gaia-ops uninstaller\n'));
+
+  try {
+    // Step 1: Run cleanup
+    const cleanupSuccess = await runCleanup();
+
+    if (!cleanupSuccess) {
+      console.log(chalk.yellow('\n⚠️  Cleanup had issues, but continuing with uninstall...\n'));
+    }
+
+    console.log('');
+
+    // Step 2: Run uninstall
+    const uninstallSuccess = runUninstall();
+
+    if (uninstallSuccess) {
+      console.log(chalk.green('\n✅ Uninstall complete!\n'));
+      console.log(chalk.gray('All gaia-ops files have been removed.'));
+      console.log(chalk.gray('Your project data (logs, tests, project-context) was preserved.\n'));
+    } else {
+      console.log(chalk.red('\n❌ Uninstall failed\n'));
+      console.log(chalk.yellow('You can try manually:'));
+      console.log(chalk.gray('  1. npx gaia-cleanup'));
+      console.log(chalk.gray('  2. npm uninstall @jaguilar87/gaia-ops\n'));
+      process.exit(1);
+    }
+  } catch (error) {
+    console.error(chalk.red(`\n❌ Uninstall error: ${error.message}\n`));
+    process.exit(1);
+  }
+}
+
+main();

package/config/delegation-matrix.md

@@ -0,0 +1,122 @@
+# Binary Delegation Matrix
+
+**Version:** 1.0.0
+**Purpose:** Deterministic decision of when to delegate vs execute locally
+
+## Decision Rules (Priority Order)
+
+| # | Condition | Decision | Confidence | Reason |
+|---|-----------|----------|------------|---------|
+| 1 | `has_task_id AND task_agent != None` | DELEGATE | 1.0 | Task metadata routing |
+| 2 | `security_tier == "T3"` | DELEGATE | 1.0 | T3 requires agent + approval |
+| 3 | `file_count >= 3` | DELEGATE | 0.9 | Multi-file threshold |
+| 4 | `file_span_multiple_dirs == True` | DELEGATE | 0.9 | Multiple directories |
+| 5 | `has_infrastructure_keywords AND requires_context` | DELEGATE | 0.85 | Infrastructure + context |
+| 6 | `has_chained_commands == True` | DELEGATE | 0.8 | Chained commands safety |
+| 7 | `tier == "T0" AND file_count <= 1 AND !has_approval_keywords` | LOCAL | 0.9 | Atomic T0 operation |
+| 8 | `tier == "T1" AND file_count <= 1 AND !requires_credentials` | LOCAL | 0.85 | Simple T1 validation |
+| 9 | DEFAULT (fallback) | DELEGATE | 0.5 | Safety default |
+
+## Binary Conditions Extracted
+
+```python
+@dataclass
+class DelegationConditions:
+    file_count: int                    # Count of files to modify
+    file_span_multiple_dirs: bool      # Files in multiple directories
+    has_chained_commands: bool         # Uses && or pipes
+    has_infrastructure_keywords: bool  # terraform/kubectl/etc
+    has_approval_keywords: bool        # apply/deploy/push/delete
+    security_tier: str                 # T0, T1, T2, T3
+    requires_context: bool             # Needs project-context.json
+    requires_credentials: bool         # Needs GCP/AWS/K8s creds
+    has_task_id: bool                  # Mentions task ID
+    task_agent: str                    # Agent from task metadata
+```
+
+## Examples
+
+```python
+# Example 1: Simple git status (LOCAL)
+conditions = DelegationConditions(
+    file_count=0,
+    file_span_multiple_dirs=False,
+    has_infrastructure_keywords=False,
+    security_tier="T0"
+)
+→ Decision: LOCAL (Rule 7: Atomic T0 operation)
+
+# Example 2: Terraform apply (DELEGATE)
+conditions = DelegationConditions(
+    has_infrastructure_keywords=True,
+    has_approval_keywords=True,
+    security_tier="T3"
+)
+→ Decision: DELEGATE (Rule 2: T3 requires agent)
+
+# Example 3: Multi-file edit (DELEGATE)
+conditions = DelegationConditions(
+    file_count=5,
+    file_span_multiple_dirs=True,
+    security_tier="T1"
+)
+→ Decision: DELEGATE (Rule 3: Multi-file threshold)
+```
+
+## Integration with Orchestrator
+
+```python
+from agent_router import should_delegate
+
+# At orchestrator entry point
+result = should_delegate(user_request, context={
+    "file_count": 3,
+    "multiple_directories": True
+})
+
+if result["delegate"]:
+    agent = result["suggested_agent"]
+    # Proceed with agent invocation
+else:
+    # Execute locally (orchestrator)
+    pass
+```
+
+## Confidence Levels
+
+- **1.0**: Absolute confidence (deterministic rules)
+- **0.9**: High confidence (clear patterns)
+- **0.85**: Medium-high confidence (strong indicators)
+- **0.8**: Medium confidence (good heuristics)
+- **0.5**: Low confidence (fallback/safety)
+
+## Security Considerations
+
+1. **T3 operations ALWAYS delegate** - No exceptions
+2. **Chained commands prefer delegation** - Safety over convenience
+3. **Default to delegation when uncertain** - Better safe than sorry
+4. **Infrastructure operations require context** - Never execute without proper context
+
+## Testing the Matrix
+
+```bash
+# Run standalone test
+python3 .claude/tools/0-guards/delegation_matrix.py
+
+# Test integration with router
+python3 -c "from tools.1-routing.agent_router import should_delegate; \
+    print(should_delegate('terraform apply', {'file_count': 1}))"
+```
+
+## Monitoring
+
+Delegation decisions are logged to:
+- `.claude/logs/delegation.jsonl` (if logging enabled)
+- Included in metrics collection for KPI tracking
+
+## Future Improvements
+
+1. **Machine Learning Enhancement**: Train on actual delegation outcomes
+2. **Custom Rules**: Allow project-specific delegation rules
+3. **Context Awareness**: Consider recent operations for better decisions
+4. **Performance Metrics**: Track decision accuracy and adjust thresholds

package/config/metrics_targets.json

@@ -0,0 +1,37 @@
+{
+  "kpi_targets": {
+    "routing_accuracy": {
+      "avg_confidence_min": 0.7,
+      "semantic_routing_rate_min": 0.6
+    },
+    "delegation_effectiveness": {
+      "avg_confidence_min": 0.8
+    },
+    "guard_effectiveness": {
+      "pass_rate_min": 0.9,
+      "phase_4_pass_rate_min": 1.0
+    },
+    "phase_completion": {
+      "phase_4_skip_rate_t3_max": 0.0
+    },
+    "approval_gate": {
+      "approval_rate_min": 0.5,
+      "avg_response_time_max_seconds": 300
+    },
+    "agent_performance": {
+      "success_rate_min": 0.8,
+      "avg_duration_max_ms": 30000
+    },
+    "overall_health": {
+      "score_min": 0.8
+    }
+  },
+  "alerting": {
+    "enabled": true,
+    "critical_thresholds": {
+      "phase_4_skip_rate_t3": 0.0,
+      "guard_pass_rate": 0.85,
+      "agent_success_rate": 0.7
+    }
+  }
+}

package/hooks/post_phase_hook.py

@@ -0,0 +1,97 @@
+#!/usr/bin/env python3
+"""
+Post-Phase Hook - Validar resultados DESPUÉS de cada fase.
+"""
+
+import sys
+import logging
+from pathlib import Path
+from typing import Dict, Any
+
+sys.path.insert(0, str(Path(__file__).parent.parent / "tools" / "0-guards"))
+
+from workflow_enforcer import get_enforcer, GuardViolation
+
+logger = logging.getLogger(__name__)
+
+
+def post_phase_4_approval(
+    tier: str,
+    user_response: str,
+    validation_result: Dict[str, Any]
+) -> Dict[str, Any]:
+    """
+    Validar que T3 operations recibieron approval.
+    """
+    enforcer = get_enforcer()
+
+    try:
+        if tier == "T3":
+            enforcer.enforce(
+                "guard_phase_4_approval_validation",
+                validation_result=validation_result
+            )
+
+        return {"valid": True, "reason": "Approval validation passed"}
+
+    except GuardViolation as e:
+        return {"valid": False, "reason": str(e)}
+
+
+def post_phase_6_ssot_update(
+    tier: str,
+    ssot_updated: bool
+) -> Dict[str, Any]:
+    """
+    Validar que T3 operations actualizaron SSOT.
+    """
+    enforcer = get_enforcer()
+
+    try:
+        enforcer.enforce(
+            "guard_phase_6_ssot_update_after_t3",
+            tier=tier,
+            ssot_updated=ssot_updated
+        )
+
+        return {"valid": True, "reason": "SSOT update validation passed"}
+
+    except GuardViolation as e:
+        return {"valid": False, "reason": str(e)}
+
+
+# CLI for testing
+if __name__ == "__main__":
+    logging.basicConfig(level=logging.INFO)
+
+    print("🧪 Testing Post-Phase Hooks...\n")
+
+    # Test post-phase 4 validation (T3 without approval)
+    result = post_phase_4_approval(
+        tier="T3",
+        user_response="reject",
+        validation_result={"approved": False, "action": "abort"}
+    )
+    print(f"Post-Phase 4 (T3 rejected): {result}")
+
+    # Test post-phase 4 validation (T3 with approval)
+    result = post_phase_4_approval(
+        tier="T3",
+        user_response="approve",
+        validation_result={"approved": True, "action": "proceed"}
+    )
+    print(f"Post-Phase 4 (T3 approved): {result}")
+
+    # Test post-phase 6 validation (T3 without SSOT update)
+    result = post_phase_6_ssot_update(
+        tier="T3",
+        ssot_updated=False
+    )
+    print(f"Post-Phase 6 (T3 no SSOT update): {result}")
+
+    # Test post-phase 6 validation (T3 with SSOT update)
+    result = post_phase_6_ssot_update(
+        tier="T3",
+        ssot_updated=True
+    )
+    print(f"Post-Phase 6 (T3 SSOT updated): {result}")

package/hooks/pre_phase_hook.py

@@ -0,0 +1,222 @@
+#!/usr/bin/env python3
+"""
+Pre-Phase Hook - Ejecutar guards ANTES de cada fase.
+Se invoca desde el orchestrator antes de comenzar una fase.
+"""
+
+import sys
+import logging
+from pathlib import Path
+from typing import Dict, Any, Optional
+
+# Add tools to path
+sys.path.insert(0, str(Path(__file__).parent.parent / "tools" / "0-guards"))
+
+from workflow_enforcer import get_enforcer, GuardViolation
+
+logger = logging.getLogger(__name__)
+
+
+def pre_phase_0_clarification(
+    ambiguity_score: float,
+    user_prompt: str
+) -> Dict[str, Any]:
+    """
+    Ejecutar guards antes de Phase 0 (Clarification).
+
+    Returns:
+        {"allowed": bool, "reason": str}
+    """
+    enforcer = get_enforcer()
+
+    try:
+        # Guard: Ambiguity threshold
+        enforcer.enforce(
+            "guard_phase_0_ambiguity_threshold",
+            ambiguity_score=ambiguity_score,
+            threshold=0.3
+        )
+
+        return {
+            "allowed": True,
+            "reason": "Phase 0 guards passed"
+        }
+
+    except GuardViolation as e:
+        return {
+            "allowed": False,
+            "reason": str(e)
+        }
+
+
+def pre_phase_1_routing(
+    agent_name: str,
+    routing_confidence: float,
+    available_agents: list
+) -> Dict[str, Any]:
+    """
+    Ejecutar guards antes de Phase 1 (Routing).
+    """
+    enforcer = get_enforcer()
+
+    try:
+        # Guard: Routing confidence
+        enforcer.enforce(
+            "guard_phase_1_routing_confidence",
+            routing_confidence=routing_confidence,
+            min_confidence=0.5
+        )
+
+        # Guard: Agent exists
+        enforcer.enforce(
+            "guard_phase_1_agent_exists",
+            agent_name=agent_name,
+            available_agents=available_agents
+        )
+
+        return {"allowed": True, "reason": "Phase 1 guards passed"}
+
+    except GuardViolation as e:
+        return {"allowed": False, "reason": str(e)}
+
+
+def pre_phase_2_context(
+    context_payload: Dict[str, Any],
+    agent_name: str
+) -> Dict[str, Any]:
+    """
+    Ejecutar guards antes de Phase 2 (Context Provisioning).
+    """
+    enforcer = get_enforcer()
+
+    # Determinar required sections según el agente
+    agent_requirements = {
+        "terraform-architect": ["project_details", "terraform_infrastructure", "operational_guidelines"],
+        "gitops-operator": ["project_details", "gitops_configuration", "cluster_details"],
+        "gcp-troubleshooter": ["project_details", "cluster_details"],
+        "devops-developer": ["project_details", "operational_guidelines"]
+    }
+
+    required_sections = agent_requirements.get(agent_name, ["project_details"])
+
+    try:
+        # Guard: Context completeness
+        enforcer.enforce(
+            "guard_phase_2_context_completeness",
+            context_payload=context_payload,
+            required_sections=required_sections
+        )
+
+        return {"allowed": True, "reason": "Phase 2 guards passed"}
+
+    except GuardViolation as e:
+        return {"allowed": False, "reason": str(e)}
+
+
+def pre_phase_4_approval(
+    tier: str,
+    realization_package: Dict[str, Any]
+) -> Dict[str, Any]:
+    """
+    Ejecutar guards antes de Phase 4 (Approval Gate).
+
+    CRITICAL: Este guard NO PUEDE fallar para T3 operations.
+    """
+    enforcer = get_enforcer()
+
+    try:
+        # Guard: Planning complete
+        enforcer.enforce(
+            "guard_phase_5_planning_complete",
+            realization_package=realization_package
+        )
+
+        # Note: El guard de approval_received se ejecuta DESPUÉS
+        # de recibir la respuesta del usuario en post_phase_4
+
+        return {"allowed": True, "reason": "Phase 4 pre-guards passed"}
+
+    except GuardViolation as e:
+        return {"allowed": False, "reason": str(e)}
+
+
+def pre_phase_5_realization(
+    tier: str,
+    approval_validation: Dict[str, Any],
+    realization_package: Dict[str, Any]
+) -> Dict[str, Any]:
+    """
+    Ejecutar guards antes de Phase 5 (Realization).
+
+    CRITICAL: Valida que T3 operations tengan aprobación.
+    """
+    enforcer = get_enforcer()
+
+    try:
+        # Guard: Approval mandatory for T3
+        enforcer.enforce(
+            "guard_phase_4_approval_mandatory",
+            tier=tier,
+            approval_received=approval_validation.get("approved", False)
+        )
+
+        # Guard: Approval validation
+        if tier == "T3":
+            enforcer.enforce(
+                "guard_phase_4_approval_validation",
+                validation_result=approval_validation
+            )
+
+        return {"allowed": True, "reason": "Phase 5 guards passed"}
+
+    except GuardViolation as e:
+        return {"allowed": False, "reason": str(e)}
+
+
+def pre_phase_6_ssot_update(
+    tier: str,
+    realization_success: bool
+) -> Dict[str, Any]:
+    """
+    Ejecutar guards antes de Phase 6 (SSOT Update).
+    """
+    if not realization_success:
+        return {
+            "allowed": False,
+            "reason": "Cannot update SSOT: Realization failed"
+        }
+
+    # Phase 6 no tiene guards bloqueantes adicionales
+    # (el guard de ssot_updated se ejecuta DESPUÉS del update)
+
+    return {"allowed": True, "reason": "Phase 6 pre-guards passed"}
+
+
+# CLI for testing
+if __name__ == "__main__":
+    logging.basicConfig(level=logging.INFO)
+
+    print("🧪 Testing Pre-Phase Hooks...\n")
+
+    # Test Phase 4 pre-guard
+    result = pre_phase_4_approval(
+        tier="T3",
+        realization_package={"files": [], "git_operations": {}}
+    )
+    print(f"Phase 4 pre-guard: {result}")
+
+    # Test Phase 5 pre-guard (sin approval - debe fallar)
+    result = pre_phase_5_realization(
+        tier="T3",
+        approval_validation={"approved": False},
+        realization_package={}
+    )
+    print(f"Phase 5 pre-guard (no approval): {result}")
+
+    # Test Phase 5 pre-guard (con approval - debe pasar)
+    result = pre_phase_5_realization(
+        tier="T3",
+        approval_validation={"approved": True, "action": "proceed_to_realization"},
+        realization_package={}
+    )
+    print(f"Phase 5 pre-guard (with approval): {result}")

package/hooks/pre_tool_use.py

@@ -16,6 +16,29 @@ from tenacity import retry, stop_after_attempt, wait_exponential
 
 from pre_kubectl_security import validate_gitops_workflow
 
+# ============================================================================
+# CLAUDE CODE ATTRIBUTION FOOTER DETECTION
+# ============================================================================
+
+def detect_claude_footers(command: str) -> bool:
+    """
+    Detect Claude Code attribution footers in any command.
+
+    Looks for patterns like:
+    - "Generated with Claude Code"
+    - "Co-Authored-By: Claude"
+    """
+    forbidden_patterns = [
+        r"Generated with\s+Claude Code",
+        r"Co-Authored-By:\s+Claude",
+    ]
+
+    for pattern in forbidden_patterns:
+        if re.search(pattern, command, re.IGNORECASE):
+            return True
+
+    return False
+
 # Configure logging
 logging.basicConfig(
     level=logging.INFO,
@@ -423,6 +446,16 @@ class PolicyEngine:
                 if not is_allowed:
                     return is_allowed, tier, reason
 
+            # INTERCEPT: Detect Claude Code attribution footers in ANY command
+            if detect_claude_footers(command):
+                logger.warning(f"Command contains Claude Code attribution footers: {command[:100]}")
+                return False, SecurityTier.T3_BLOCKED, (
+                    "❌ Command contains Claude Code attribution footers\n\n"
+                    "Remove these patterns and retry:\n"
+                    "  • 'Generated with Claude Code'\n"
+                    "  • 'Co-Authored-By: Claude'"
+                )
+
             # Enforce GitOps security rules for cluster-related commands
             if any(keyword in command for keyword in ("kubectl", "helm", "flux")):
                 try:

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@jaguilar87/gaia-ops",
-  "version": "2.5.8",
+  "version": "2.6.0",
   "description": "Multi-agent orchestration system for Claude Code - DevOps automation toolkit",
   "main": "index.js",
   "type": "module",
   "bin": {
     "gaia-init": "bin/gaia-init.js",
-    "gaia-cleanup": "bin/gaia-cleanup.js"
+    "gaia-cleanup": "bin/gaia-cleanup.js",
+    "gaia-uninstall": "bin/gaia-uninstall.js"
   },
   "keywords": [
     "claude-code",