@jaguilar87/gaia-ops 4.4.0 → 4.7.2

package/dist/gaia-ops/tools/validation/README.md

@@ -0,0 +1,244 @@
+# Validation Module
+
+**Purpose:** Approval gates and commit validation for T3 operations
+
+## Overview
+
+This module provides two critical validation components for the gaia-ops system:
+
+1. **Commit Message Validator** - Enforces Conventional Commits format
+2. **Approval Gate** - Manages T3 approval workflow with audit trail
+
+## Core Components
+
+### 1. Commit Message Validator
+
+**MOVED:** Commit validation has been moved to `hooks/modules/validation/commit_validator.py`
+and is now only used internally by `hooks/modules/tools/bash_validator.py`.
+
+This ensures commit validation is enforced automatically during git commit commands
+without requiring explicit imports in agent code.
+
+**What it validates:**
+- ✅ Conventional Commits format (`type(scope): description`)
+- ✅ Allowed types (feat, fix, refactor, docs, test, chore, ci, perf, style, build)
+- ✅ Subject line rules (max 72 chars, no period at end)
+- ✅ Forbidden footers (no "Generated with" footers)
+
+**Configuration:** `.claude/config/git_standards.json` (SSOT)
+**Logs:** `.claude/logs/commit-violations.jsonl`
+
+---
+
+### 2. Approval Gate
+
+Manages T3 operation approval workflow with structured questions and audit trail.
+
+**Files:**
+- `approval_gate.py` - Main approval gate
+- `test_approval_gate.py` - Test suite
+
+**Usage:**
+```python
+from tools.validation import request_approval, process_approval_response
+
+# Generate approval question
+approval = request_approval(
+    realization_package,
+    agent_name="gitops-operator",
+    phase="Phase 4"
+)
+
+# Show summary to user
+print(approval["summary"])
+
+# Ask for approval
+response = AskUserQuestion(**approval["question_config"])
+
+# Process response
+result = process_approval_response(
+    approval["gate_instance"],
+    response,
+    realization_package,
+    agent_name,
+    phase
+)
+
+if result["approved"]:
+    # Proceed to execution
+    execute_plan()
+else:
+    # Halt workflow
+    return {"status": "rejected"}
+```
+
+**Features:**
+- 📊 Visual summary of realization package
+- 🔍 Counts operations and resources
+- 📝 Audit trail of all approval decisions
+- ✅ Structured approval questions for AskUserQuestion
+
+**Logs:** `.claude/logs/approvals.jsonl`
+
+**Testing:**
+```bash
+python3 .claude/tools/validation/test_approval_gate.py
+```
+
+---
+
+## Integration with Skills
+
+This validation module works with skills in a **hybrid model**:
+
+- **Skills** (`.claude/skills/`) - Document patterns and guide agents
+- **Code** (this module) - Enforce rules and ensure consistency
+
+**Skills updated:**
+- `approval/SKILL.md` - References automatic validation
+- `execution/SKILL.md` - Documents commit validation integration
+
+**Division of responsibility:**
+- **Skills guide:** Show examples, explain context, teach patterns
+- **Code enforces:** Block invalid commits, log decisions, ensure compliance
+
+---
+
+## Architecture
+
+```
+┌──────────────────────────────────────────────────────────┐
+│  config/git_standards.json (SSOT)                         │
+│  - Conventional commit types                              │
+│  - Forbidden footers                                      │
+│  - Max lengths                                            │
+└──────────────────────────────────────────────────────────┘
+                        │
+                        ▼
+┌──────────────────────────────────────────────────────────┐
+│  hooks/modules/validation/ (Commit Validation)            │
+│  └─ commit_validator.py                                   │
+│     └─ Used by bash_validator.py only                     │
+└──────────────────────────────────────────────────────────┘
+                        │
+                        ▼
+┌──────────────────────────────────────────────────────────┐
+│  tools/validation/ (Approval Enforcement)                 │
+│  └─ approval_gate.py                                      │
+│     └─ Manages T3 approval workflow                       │
+└──────────────────────────────────────────────────────────┘
+                        │
+                        ▼
+┌──────────────────────────────────────────────────────────┐
+│  skills/ (Guidance)                              │
+│  ├─ approval/SKILL.md                                     │
+│  │  └─ How to present plans                               │
+│  └─ execution/SKILL.md                                    │
+│     └─ How to execute safely                              │
+└──────────────────────────────────────────────────────────┘
+                        │
+                        ▼
+┌──────────────────────────────────────────────────────────┐
+│  logs/ (Audit Trail)                                      │
+│  ├─ commit-violations.jsonl                               │
+│  └─ approvals.jsonl                                       │
+└──────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Security Tiers
+
+| Tier | Operations | Validation | Approval Gate |
+|------|-----------|-----------|---------------|
+| T0 | Read-only | No | No |
+| T1 | Local changes | Yes | No |
+| T2 | Reversible remote | Yes | No |
+| T3 | Irreversible | **Yes** | **Yes** ⚠️ |
+
+**T3 operations require:**
+1. ✅ Commit message validation (enforced by commit_validator.py)
+2. ✅ Approval gate (enforced by approval_gate.py)
+3. ✅ Audit trail (logged automatically)
+
+---
+
+## Files
+
+```
+validation/
+├── __init__.py                    # Module exports
+├── README.md                      # This file
+└── approval_gate.py               # T3 approval workflow
+
+Note: commit_validator.py moved to hooks/modules/validation/
+```
+
+---
+
+## Configuration
+
+**Git Standards:** `.claude/config/git_standards.json`
+
+Example:
+```json
+{
+  "commit_message": {
+    "type_allowed": ["feat", "fix", "refactor", "docs", "test", "chore"],
+    "subject_max_length": 72,
+    "footer_forbidden": ["Generated with Claude Code"]
+  },
+  "enforcement": {
+    "enabled": true,
+    "block_on_failure": true,
+    "log_violations": true
+  }
+}
+```
+
+---
+
+## Logs
+
+**Commit Violations:** `.claude/logs/commit-violations.jsonl`
+
+Example entry:
+```json
+{
+  "timestamp": "2026-01-15T19:34:12.345678",
+  "message": "Added new feature...",
+  "errors": [{"type": "INVALID_FORMAT", "message": "..."}],
+  "error_count": 1
+}
+```
+
+**Approvals:** `.claude/logs/approvals.jsonl`
+
+Example entry:
+```json
+{
+  "timestamp": "2026-01-15T19:35:00.123456",
+  "agent": "gitops-operator",
+  "phase": "Phase 4",
+  "approved": true,
+  "user_response": "✅ Aprobar y ejecutar",
+  "files_count": 2,
+  "operations": "git push origin main",
+  "git_commit": "feat(graphql): update image to v1.0.180"
+}
+```
+
+---
+
+## See Also
+
+- `.claude/config/git_standards.json` - Git standards configuration
+- `.claude/skills/approval/SKILL.md` - Approval workflow patterns
+- `.claude/skills/execution/SKILL.md` - Execution workflow patterns
+- `CLAUDE.md` - Orchestrator protocol with T3 workflow
+
+---
+
+**Version:** 4.2.0
+**Last Updated:** 2026-03-11
+**Maintained by:** gaia-ops validation team

package/dist/gaia-ops/tools/validation/__init__.py

@@ -0,0 +1,17 @@
+"""
+Validation Module: Approval gates for T3 operations
+
+This module provides T3 approval gate enforcement.
+Ensures infrastructure changes and critical operations follow proper governance.
+
+Note: commit_validator.py has been moved to hooks/modules/validation/
+      and is now only used by bash_validator.py
+"""
+
+from .approval_gate import ApprovalGate, request_approval, process_approval_response
+
+__all__ = [
+    "ApprovalGate",
+    "request_approval",
+    "process_approval_response",
+]

package/dist/gaia-ops/tools/validation/approval_gate.py

@@ -0,0 +1,321 @@
+"""
+Approval Gate Enforcement
+
+Ensures that no realization occurs without explicit user approval.
+This is a CRITICAL component of the Two-Phase Workflow.
+"""
+
+import json
+import os
+from typing import Dict, Any, Optional
+from datetime import datetime
+
+
+class ApprovalGate:
+    """
+    Enforces approval gate before any realization actions.
+
+    CRITICAL: This gate is MANDATORY in the workflow. No realization
+    can proceed without explicit user approval via AskUserQuestion.
+    """
+
+    def __init__(self):
+        # Calculate base path (.claude/) from this file location
+        # From .claude/tools/validation/ go up to .claude/
+        base_path = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+        self.approval_log_path = os.path.join(base_path, "logs", "approvals.jsonl")
+        self._ensure_log_directory()
+
+    def _ensure_log_directory(self):
+        """Ensure the logs directory exists."""
+        log_dir = os.path.dirname(self.approval_log_path)
+        os.makedirs(log_dir, exist_ok=True)
+
+    def generate_approval_question(
+        self,
+        realization_package: Dict[str, Any],
+        agent_name: str,
+        phase: str
+    ) -> Dict[str, Any]:
+        """
+        Generate the approval question configuration for AskUserQuestion tool.
+
+        Args:
+            realization_package: The plan to be realized
+            agent_name: Name of the agent that generated the plan
+            phase: Current phase (e.g., "Phase 3.3")
+
+        Returns:
+            Dict with AskUserQuestion configuration
+        """
+
+        critical_ops = self._get_critical_operations(realization_package)
+        operation_count = self._get_operation_count(realization_package)
+
+        return {
+            "questions": [{
+                "question": f"¿Apruebas la realización de este plan? Se ejecutará: {critical_ops}",
+                "header": "Approval",
+                "multiSelect": False,
+                "options": [
+                    {
+                        "label": "✅ Aprobar y ejecutar",
+                        "description": f"Proceder con {operation_count} operaciones: {critical_ops}"
+                    },
+                    {
+                        "label": "❌ Rechazar",
+                        "description": "Cancelar la realización. No se harán cambios."
+                    }
+                ]
+            }]
+        }
+
+    def generate_summary(self, realization_package: Dict[str, Any]) -> str:
+        """
+        Generate human-readable summary of the realization package.
+
+        This summary should be presented to the user BEFORE calling
+        AskUserQuestion so they have full context for their decision.
+        """
+
+        summary_parts = []
+        summary_parts.append("="*60)
+        summary_parts.append("📦 REALIZATION PACKAGE - APPROVAL REQUIRED")
+        summary_parts.append("="*60)
+
+        # Files
+        if "files" in realization_package:
+            files = realization_package["files"]
+            summary_parts.append(f"\n**Archivos a crear/modificar:** {len(files)}")
+            for file_info in files[:10]:  # Show first 10
+                action = file_info.get('action', 'create')
+                summary_parts.append(f"  [{action}] {file_info['path']}")
+            if len(files) > 10:
+                summary_parts.append(f"  ... y {len(files) - 10} archivos más")
+
+        # Git operations
+        if "git_operations" in realization_package:
+            git_ops = realization_package["git_operations"]
+            summary_parts.append(f"\n**Git Operations:**")
+            summary_parts.append(f"  Commit: {git_ops.get('commit_message', 'N/A')}")
+            summary_parts.append(f"  Branch: {git_ops.get('branch', 'main')}")
+            summary_parts.append(f"  Remote: {git_ops.get('remote', 'origin')}")
+            summary_parts.append(f"  Operation: git push")
+
+        # Resources affected
+        if "resources_affected" in realization_package:
+            resources = realization_package["resources_affected"]
+            summary_parts.append(f"\n**Recursos Afectados en el Cluster:**")
+            for resource_type, items in resources.items():
+                if isinstance(items, list):
+                    summary_parts.append(f"  {resource_type}: {len(items)}")
+                    for item in items[:5]:
+                        summary_parts.append(f"    - {item}")
+                    if len(items) > 5:
+                        summary_parts.append(f"    ... y {len(items) - 5} más")
+                else:
+                    summary_parts.append(f"  {resource_type}: {items}")
+
+        # Terraform operations
+        if "terraform_operations" in realization_package:
+            tf_ops = realization_package["terraform_operations"]
+            summary_parts.append(f"\n**Terraform Operations:**")
+            summary_parts.append(f"  Command: {tf_ops.get('command', 'N/A')}")
+            summary_parts.append(f"  Path: {tf_ops.get('path', 'N/A')}")
+            if "resources" in tf_ops:
+                summary_parts.append(f"  Resources to change: {len(tf_ops['resources'])}")
+
+        # Validation results (if present)
+        if "validation_results" in realization_package:
+            validation = realization_package["validation_results"]
+            summary_parts.append(f"\n**Pre-Deployment Validation:**")
+            summary_parts.append(f"  Status: {validation.get('status', 'N/A')}")
+            if validation.get('warnings'):
+                summary_parts.append(f"  ⚠️  Warnings: {len(validation['warnings'])}")
+                for warning in validation['warnings'][:3]:
+                    summary_parts.append(f"    - {warning}")
+
+        # Estimated impact
+        if "estimated_impact" in realization_package:
+            impact = realization_package["estimated_impact"]
+            summary_parts.append(f"\n**Estimated Impact:**")
+            summary_parts.append(f"  Downtime: {impact.get('downtime', 'None expected')}")
+            summary_parts.append(f"  Risk Level: {impact.get('risk_level', 'Medium')}")
+
+        summary_parts.append("\n" + "="*60)
+
+        return "\n".join(summary_parts)
+
+    def _get_critical_operations(self, realization_package: Dict[str, Any]) -> str:
+        """Extract critical operations for the approval question."""
+        operations = []
+
+        if "git_operations" in realization_package:
+            git_ops = realization_package["git_operations"]
+            branch = git_ops.get('branch', 'main')
+            operations.append(f"git push origin {branch}")
+
+        if "kubectl_operations" in realization_package:
+            operations.append("kubectl apply")
+
+        if "terraform_operations" in realization_package:
+            tf_ops = realization_package["terraform_operations"]
+            command = tf_ops.get('command', 'apply')
+            operations.append(f"terraform {command}")
+
+        if "flux_operations" in realization_package:
+            operations.append("flux reconcile")
+
+        return ", ".join(operations) if operations else "cambios al repositorio"
+
+    def _get_operation_count(self, realization_package: Dict[str, Any]) -> int:
+        """Count total operations in the package."""
+        count = 0
+
+        if "files" in realization_package:
+            count += len(realization_package["files"])
+
+        if "git_operations" in realization_package:
+            count += 2  # commit + push
+
+        if "kubectl_operations" in realization_package:
+            kubectl_ops = realization_package["kubectl_operations"]
+            count += len(kubectl_ops) if isinstance(kubectl_ops, list) else 1
+
+        if "terraform_operations" in realization_package:
+            count += 1
+
+        return count
+
+    def validate_approval_response(self, user_response: str) -> Dict[str, Any]:
+        """
+        Validate the user's approval response.
+
+        Args:
+            user_response: The response from AskUserQuestion
+
+        Returns:
+            Dict with validation result and action to take
+        """
+
+        if user_response == "✅ Aprobar y ejecutar":
+            return {
+                "approved": True,
+                "action": "proceed_to_realization",
+                "message": "✅ Aprobación recibida. Procediendo a Fase 5 (Realization)..."
+            }
+
+        elif user_response == "❌ Rechazar":
+            return {
+                "approved": False,
+                "action": "halt_workflow",
+                "message": "❌ Realización rechazada por el usuario. Workflow detenido."
+            }
+
+        else:
+            # User selected "Other" or provided custom response
+            return {
+                "approved": False,
+                "action": "clarify_with_user",
+                "message": f"⚠️  Respuesta no estándar recibida: '{user_response}'. Se requiere clarificación.",
+                "user_input": user_response
+            }
+
+    def log_approval(
+        self,
+        realization_package: Dict[str, Any],
+        user_response: str,
+        approved: bool,
+        agent_name: str,
+        phase: str
+    ):
+        """
+        Log the approval decision for audit trail.
+
+        This creates a permanent record of all approval decisions
+        for compliance and troubleshooting purposes.
+        """
+
+        log_entry = {
+            "timestamp": datetime.now().isoformat(),
+            "agent": agent_name,
+            "phase": phase,
+            "approved": approved,
+            "user_response": user_response,
+            "files_count": len(realization_package.get("files", [])),
+            "operations": self._get_critical_operations(realization_package),
+            "git_commit": realization_package.get("git_operations", {}).get("commit_message", "N/A")
+        }
+
+        # Append to JSONL log file
+        with open(self.approval_log_path, "a") as f:
+            f.write(json.dumps(log_entry) + "\n")
+
+        return log_entry
+
+
+# Convenience function for orchestrator to use
+def request_approval(
+    realization_package: Dict[str, Any],
+    agent_name: str,
+    phase: str
+) -> Dict[str, Any]:
+    """
+    Main function to request approval from user.
+
+    This should be called by the orchestrator in Phase 4 (Approval Gate).
+
+    Args:
+        realization_package: The complete realization package from the agent
+        agent_name: Name of the agent that generated the plan
+        phase: Current phase identifier
+
+    Returns:
+        Dict with:
+        - summary: String to present to user
+        - question_config: Dict to pass to AskUserQuestion tool
+    """
+
+    gate = ApprovalGate()
+
+    return {
+        "summary": gate.generate_summary(realization_package),
+        "question_config": gate.generate_approval_question(realization_package, agent_name, phase),
+        "gate_instance": gate
+    }
+
+
+def process_approval_response(
+    gate_instance: ApprovalGate,
+    user_response: str,
+    realization_package: Dict[str, Any],
+    agent_name: str,
+    phase: str
+) -> Dict[str, Any]:
+    """
+    Process the user's approval response.
+
+    Args:
+        gate_instance: The ApprovalGate instance from request_approval
+        user_response: The user's response from AskUserQuestion
+        realization_package: The realization package
+        agent_name: Name of the agent
+        phase: Current phase
+
+    Returns:
+        Dict with validation result and action to take
+    """
+
+    # Validate response
+    validation = gate_instance.validate_approval_response(user_response)
+
+    # Log the decision
+    gate_instance.log_approval(
+        realization_package,
+        user_response,
+        validation["approved"],
+        agent_name,
+        phase
+    )
+
+    return validation