genoma-evolution 1.0.0

package/backend/promethean/gepa_strategist.py

@@ -0,0 +1,213 @@
+"""
+②③ DIAGNOSTICA + FORMULA — GEPA Strategic Layer
+
+GEPA (Goal → Execution → Plan → Action) analyzes anomalies detected by trace ingestion
+and formulates SkillGenesis packets for DSPy compilation.
+
+This is the "brain" of the Promethean Cycle — it decides WHAT to learn.
+"""
+
+from __future__ import annotations
+import json
+import re
+from datetime import datetime
+from pathlib import Path
+from typing import Optional
+
+from .models import SkillGenesisPacket, CyclePhase, CycleState
+from .trace_ingestion import get_ingestor
+
+SKILLS_DIR = Path.home() / ".hermes" / "skills"
+MEMORY_DIR = Path.home() / ".hermes" / "memory"
+
+
+class GEPAStrategist:
+    """Strategic layer: diagnoses skill gaps and formulates learning objectives."""
+
+    def __init__(self):
+        self.ingestor = get_ingestor()
+
+    # ── Diagnosis ──────────────────────────────────────────────────
+    def diagnose(self, anomalies: list[dict]) -> list[dict]:
+        """Analyze anomalies and determine if they represent skill gaps.
+
+        Returns list of gap diagnoses with:
+        - gap_id: unique identifier
+        - root_cause: identified root cause
+        - existing_skills: skills that partially cover this (if any)
+        - confidence: 0-1 probability that a new skill would help
+        - recommended_action: "compile_skill" | "monitor" | "ignore"
+        """
+        gaps = []
+
+        for anomaly in anomalies:
+            sig = anomaly["error_signature"]
+            occurrences = anomaly["occurrences"]
+            agents = anomaly.get("agents_affected", [])
+
+            # Check if any existing skill covers this
+            existing = self._find_covering_skills(sig)
+
+            # Determine root cause from error pattern
+            root_cause = self._infer_root_cause(sig, anomaly.get("sample_traces", []))
+
+            # Calculate confidence based on:
+            # - Number of occurrences (more = more confident)
+            # - Number of agents affected (cross-agent = more confident)
+            # - Whether existing skills partially cover it
+            occ_factor = min(occurrences / 10, 1.0)  # Capped at 10 occurrences
+            agent_factor = min(len(agents) / 4, 1.0) if agents else 0.3
+            coverage_factor = 0.0 if existing else 0.5  # No coverage = higher need
+
+            confidence = round((occ_factor * 0.4 + agent_factor * 0.3 + coverage_factor * 0.3), 2)
+
+            # Decide action
+            if confidence > 0.5 and not existing:
+                action = "compile_skill"
+            elif confidence > 0.3:
+                action = "monitor"
+            else:
+                action = "ignore"
+
+            gaps.append({
+                "gap_id": f"gap_{sig[:20].replace(' ', '_')}",
+                "error_signature": sig,
+                "root_cause": root_cause,
+                "occurrences": occurrences,
+                "agents_affected": agents,
+                "existing_skills": existing,
+                "confidence": confidence,
+                "recommended_action": action,
+                "diagnosed_at": datetime.now().isoformat(),
+            })
+
+        return gaps
+
+    # ── Formulation ─────────────────────────────────────────────────
+    def formulate(self, gap: dict, cycle_state: CycleState) -> Optional[SkillGenesisPacket]:
+        """Formulate a SkillGenesis packet from a confirmed gap.
+
+        Only creates packets for gaps with recommended_action == 'compile_skill'.
+        """
+        if gap["recommended_action"] != "compile_skill":
+            return None
+
+        sig = gap["error_signature"]
+        root_cause = gap["root_cause"]
+
+        # Extract dataset from trace storage
+        dataset_path = self.ingestor.extract_dataset(sig, limit=50)
+
+        # Infer the DSPy signature from the error pattern
+        signature = self._infer_signature(sig, root_cause)
+
+        # Generate intent description
+        intent = f"Autonomous resolution for: {root_cause}. Detected from {gap['occurrences']} failures across {len(gap['agents_affected'])} agents."
+
+        # Select metric based on error type
+        metric = self._select_metric(sig)
+
+        # Calculate dynamic threshold based on confidence
+        threshold = max(0.10, gap["confidence"] * 0.30)
+
+        packet = SkillGenesisPacket(
+            intent=intent,
+            signature=signature,
+            dataset_path=dataset_path,
+            metric=metric,
+            threshold=threshold,
+            target_agent=",".join(gap["agents_affected"]) if gap["agents_affected"] else "all",
+        )
+
+        cycle_state.genesis_packets.append(packet)
+        return packet
+
+    def formulate_all(self, gaps: list[dict], cycle_state: CycleState) -> list[SkillGenesisPacket]:
+        """Formulate packets for all actionable gaps."""
+        packets = []
+        for gap in gaps:
+            packet = self.formulate(gap, cycle_state)
+            if packet:
+                packets.append(packet)
+        return packets
+
+    # ── Internal: Skill Discovery ───────────────────────────────────
+    def _find_covering_skills(self, error_signature: str) -> list[str]:
+        """Find existing skills that might cover this error pattern."""
+        if not SKILLS_DIR.exists():
+            return []
+
+        keywords = set(re.findall(r'[a-z]+', error_signature.lower()))
+        covering = []
+
+        for skill_dir in SKILLS_DIR.rglob("SKILL.md"):
+            try:
+                content = skill_dir.read_text()[:500].lower()
+                matches = sum(1 for kw in keywords if kw in content)
+                if matches >= 2:
+                    covering.append(skill_dir.parent.name)
+            except Exception:
+                continue
+
+        return covering
+
+    # ── Internal: Root Cause Inference ──────────────────────────────
+    def _infer_root_cause(self, error_signature: str, sample_traces: list[str]) -> str:
+        """Infer root cause from error signature and sample traces."""
+        patterns = {
+            r"timeout|timed?.*out": "Operation timeout — likely resource or network constraint",
+            r"auth|unauthorized|forbidden|401|403": "Authentication or authorization failure",
+            r"migrat|schema|drizzle.*error": "Database migration or schema mismatch",
+            r"build.*fail|compil|syntax|type.*error": "Build or compilation failure",
+            r"import.*error|module.*not.*found|no.*module": "Missing dependency or import path error",
+            r"deploy|eas|expo.*build": "Deployment pipeline failure",
+            r"docker|container|sandbox|e2b": "Sandbox or container orchestration failure",
+            r"network|dns|refused|unreachable|econnrefused": "Network connectivity failure",
+            r"memory|oom|killed|heap": "Memory exhaustion",
+            r"permission|denied|eacces": "File system permission error",
+        }
+
+        for pattern, cause in patterns.items():
+            if re.search(pattern, error_signature, re.IGNORECASE):
+                return cause
+
+        return f"Uncategorized operational failure: {error_signature[:80]}"
+
+    # ── Internal: Signature Inference ───────────────────────────────
+    def _infer_signature(self, error_signature: str, root_cause: str) -> str:
+        """Infer a DSPy Signature string from error context."""
+        if re.search(r"build|deploy|eas|dockerfile", error_signature, re.IGNORECASE):
+            return "error_log, build_context → fixed_config, explanation"
+        elif re.search(r"migrat|schema|drizzle", error_signature, re.IGNORECASE):
+            return "migration_error, schema_snapshot → fix_commands, root_cause"
+        elif re.search(r"auth|unauthorized|forbidden", error_signature, re.IGNORECASE):
+            return "auth_error, config_snapshot → fix_steps, updated_config"
+        elif re.search(r"import|module.*not.*found", error_signature, re.IGNORECASE):
+            return "import_error, package_json → fix_commands, dependency_name"
+        elif re.search(r"network|dns|refused|timeout", error_signature, re.IGNORECASE):
+            return "network_error, service_context → recovery_steps, root_cause"
+        else:
+            return "error_log, context → fix_steps, explanation"
+
+    # ── Internal: Metric Selection ──────────────────────────────────
+    def _select_metric(self, error_signature: str) -> str:
+        """Select the most appropriate metric for this type of error."""
+        if re.search(r"timeout|slow|performance", error_signature, re.IGNORECASE):
+            return "delta_resolution_time"
+        elif re.search(r"build|deploy|eas", error_signature, re.IGNORECASE):
+            return "delta_build_success_rate"
+        elif re.search(r"migrat|schema", error_signature, re.IGNORECASE):
+            return "delta_migration_success_rate"
+        else:
+            return "delta_resolution_rate"
+
+
+# ── Singleton ───────────────────────────────────────────────────────
+_strategist: Optional[GEPAStrategist] = None
+
+
+def get_strategist() -> GEPAStrategist:
+    global _strategist
+    if _strategist is None:
+        _strategist = GEPAStrategist()
+    return _strategist

package/backend/promethean/models.py

@@ -0,0 +1,260 @@
+"""
+Promethean Models — Data structures for the Ciclo Prometeico.
+
+SkillGenesis Packet: The interface between GEPA (strategy) and DSPy (compilation).
+TraceRecord: Standardized trace from any AI agent.
+CycleState: Full state machine for the 7-phase cycle.
+"""
+
+from __future__ import annotations
+from dataclasses import dataclass, field, asdict
+from datetime import datetime
+from enum import Enum
+from typing import Optional, Any
+import json
+import uuid
+
+
+# ── Phase Enum ──────────────────────────────────────────────────────
+class CyclePhase(str, Enum):
+    PERCIBE = "perceive"
+    DIAGNOSTICA = "diagnose"
+    FORMULA = "formulate"
+    COMPILA = "compile"
+    VALIDA = "validate"
+    DESPLIEGA = "deploy"
+    OBSERVA = "observe"
+
+
+# ── Trace Record (any agent → dashboard) ───────────────────────────
+@dataclass
+class TraceRecord:
+    """Standardized trace emitted by any AI agent."""
+    agent: str                    # "claude-code", "opencode", "codex", "hermes"
+    agent_version: str
+    timestamp: str                # ISO 8601
+    task: str                     # Description of what was attempted
+    outcome: str                  # "success" | "failure" | "partial"
+    error_signature: Optional[str] = None  # Unique error fingerprint
+    context: dict = field(default_factory=dict)  # files_touched, commands, stack_trace
+    resolution: Optional[str] = None  # How it was resolved (null if unresolved → gap)
+    trace_id: str = field(default_factory=lambda: str(uuid.uuid4())[:8])
+
+    def to_json(self) -> str:
+        return json.dumps(asdict(self), indent=2, default=str)
+
+    @classmethod
+    def from_json(cls, data: str | dict) -> "TraceRecord":
+        if isinstance(data, str):
+            data = json.loads(data)
+        return cls(**{k: v for k, v in data.items() if k in cls.__dataclass_fields__})
+
+    def to_canonical(self) -> CanonicalRun:
+        """Convert TraceRecord to vendor-neutral CanonicalRun schema."""
+        errors = []
+        if self.error_signature:
+            errors = [{"signature": self.error_signature, "message": None, "stack_excerpt": None, "count": 1}]
+
+        return CanonicalRun(
+            run_id=self.trace_id,
+            agent_name=self.agent,
+            agent_version=self.agent_version,
+            collector="hermes-trace-ingestor",
+            collector_version="0.1.0",
+            started_at=self.timestamp,
+            ended_at=self.timestamp,
+            task_name=self.task,
+            outcome=self.outcome,
+            provider="hermes",
+            errors=errors,
+            context=self.context or {},
+            resolution=self.resolution,
+        )
+
+
+# ── SkillGenesis Packet (GEPA → DSPy) ──────────────────────────────
+@dataclass
+class SkillGenesisPacket:
+    """GEPA formulates this. DSPy consumes it. A skill is born."""
+    intent: str                  # What the skill should do (human-readable)
+    signature: str               # "input_fields → output_fields" (DSPy Signature format)
+    dataset_path: str            # Path to training dataset (JSONL)
+    metric: str                  # Metric name for optimization
+    threshold: float = 0.15      # Minimum delta to accept (e.g., 0.15 = 15% improvement)
+    holdout: float = 0.2         # Fraction of data reserved for validation
+    optimizers: list[str] = field(default_factory=lambda: ["GEPA", "BootstrapFinetune"])
+    strategy: str = "p -> w -> p"  # BetterTogether strategy string
+    target_agent: str = "all"    # Which agent(s) this skill targets
+    max_attempts: int = 3        # Max re-compilation attempts if validation fails
+    packet_id: str = field(default_factory=lambda: str(uuid.uuid4())[:8])
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+    def to_json(self) -> str:
+        return json.dumps(self.to_dict(), indent=2)
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "SkillGenesisPacket":
+        return cls(**{k: v for k, v in data.items() if k in cls.__dataclass_fields__})
+
+
+# ── Compilation Result (DSPy → GEPA) ───────────────────────────────
+@dataclass
+class CompilationResult:
+    """DSPy returns this after compiling a skill."""
+    packet_id: str
+    success: bool
+    skill_name: str              # Generated skill name
+    skill_path: str              # Where the skill was saved
+    iterations: int              # Number of optimization iterations
+    best_score: float            # Best metric score achieved
+    delta: float                 # Improvement over baseline
+    threshold_met: bool          # delta >= threshold?
+    attempt: int = 1             # Which attempt (1 to max_attempts)
+    error: Optional[str] = None  # Error message if failed
+    compiled_at: str = field(default_factory=lambda: datetime.now().isoformat())
+
+
+# ── Cycle State ─────────────────────────────────────────────────────
+@dataclass
+class CycleState:
+    """Full state of a Promethean Cycle execution."""
+    cycle_id: str = field(default_factory=lambda: str(uuid.uuid4())[:8])
+    phase: CyclePhase = CyclePhase.PERCIBE
+    traces_ingested: int = 0
+    anomalies_detected: int = 0
+    genesis_packets: list[SkillGenesisPacket] = field(default_factory=list)
+    compilation_results: list[CompilationResult] = field(default_factory=list)
+    skills_deployed: int = 0
+    started_at: str = field(default_factory=lambda: datetime.now().isoformat())
+    completed_at: Optional[str] = None
+    errors: list[str] = field(default_factory=list)
+
+    def advance(self, new_phase: CyclePhase):
+        self.phase = new_phase
+        if new_phase == CyclePhase.OBSERVA:
+            self.completed_at = datetime.now().isoformat()
+
+    def summary(self) -> dict:
+        return {
+            "cycle_id": self.cycle_id,
+            "phase": self.phase.value,
+            "traces_ingested": self.traces_ingested,
+            "anomalies_detected": self.anomalies_detected,
+            "genesis_packets": len(self.genesis_packets),
+            "skills_compiled": len([r for r in self.compilation_results if r.success]),
+            "skills_deployed": self.skills_deployed,
+            "started_at": self.started_at,
+            "completed_at": self.completed_at,
+            "errors": self.errors,
+        }
+
+
+# ── Metric Snapshot (for delta calculation) ─────────────────────────
+@dataclass
+class MetricSnapshot:
+    """Before/after metric snapshot for a skill evaluation."""
+    skill_name: str
+    baseline: dict     # {"success_rate": 0.67, "avg_time": 98, ...}
+    evolved: dict      # {"success_rate": 0.94, "avg_time": 61, ...}
+    deltas: dict       # {"success_rate": +0.27, "avg_time": -0.38}
+    threshold: float
+    passed: bool
+    dataset_size: int
+    holdout_size: int
+    evaluated_at: str = field(default_factory=lambda: datetime.now().isoformat())
+
+
+# ── Canonical Run Schema (Agent-Agnostic Telemetry) ───────────────────
+@dataclass
+class ToolCallRecord:
+    """Record of a single tool invocation."""
+    id: str
+    name: str
+    input_summary: Optional[str] = None
+    duration_ms: Optional[int] = None
+    result_summary: Optional[str] = None
+    error: Optional[str] = None
+
+
+@dataclass
+class FileTouchRecord:
+    """Record of file read/write/delete operation."""
+    path: str
+    action: str = "write"  # "read" | "write" | "delete"
+    size_bytes: Optional[int] = None
+
+
+@dataclass
+class RunMetrics:
+    """Aggregated execution metrics for a run."""
+    input_tokens: Optional[int] = None
+    output_tokens: Optional[int] = None
+    cache_tokens: Optional[int] = None
+    latency_ms: Optional[int] = None
+    cost_usd: Optional[float] = None
+    tool_call_count: int = 0
+
+
+@dataclass
+class CanonicalRun:
+    """Vendor-neutral canonical run event. Maps from any agent's native format."""
+    # Required fields
+    run_id: str
+    agent_name: str
+    collector: str
+    started_at: str
+    task_name: str
+    outcome: str  # "success" | "failure" | "partial" | "unknown"
+
+    # Optional fields
+    agent_version: Optional[str] = None
+    provider: Optional[str] = None
+    model: Optional[str] = None
+    repo: Optional[str] = None
+    session_id: Optional[str] = None
+    ended_at: Optional[str] = None
+    tool_calls: list[ToolCallRecord] = field(default_factory=list)
+    files_touched: list[FileTouchRecord] = field(default_factory=list)
+    artifacts: list[dict] = field(default_factory=list)
+    errors: list[dict] = field(default_factory=list)
+    metrics: Optional[RunMetrics] = None
+    eval_scores: list[dict] = field(default_factory=list)
+    improvement_candidates: list[dict] = field(default_factory=list)
+    context: dict = field(default_factory=dict)
+    resolution: Optional[str] = None
+    collector_version: str = "0.1.0"
+
+    def to_dict(self) -> dict:
+        """Convert to dict, handling nested dataclasses."""
+        data = asdict(self)
+        # Convert nested dataclasses to dicts
+        if self.metrics:
+            data["metrics"] = asdict(self.metrics)
+        if self.tool_calls:
+            data["tool_calls"] = [asdict(tc) for tc in self.tool_calls]
+        if self.files_touched:
+            data["files_touched"] = [asdict(ft) for ft in self.files_touched]
+        return data
+
+    def to_json(self) -> str:
+        return json.dumps(self.to_dict(), indent=2, default=str)
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "CanonicalRun":
+        """Reconstruct from dict, handling nested dataclasses."""
+        # Reconstruct nested objects
+        if data.get("metrics") and not isinstance(data["metrics"], RunMetrics):
+            data["metrics"] = RunMetrics(**data["metrics"])
+        if data.get("tool_calls"):
+            data["tool_calls"] = [
+                ToolCallRecord(**tc) if isinstance(tc, dict) else tc
+                for tc in data["tool_calls"]
+            ]
+        if data.get("files_touched"):
+            data["files_touched"] = [
+                FileTouchRecord(**ft) if isinstance(ft, dict) else ft
+                for ft in data["files_touched"]
+            ]
+        return cls(**{k: v for k, v in data.items() if k in cls.__dataclass_fields__})

package/backend/promethean/skill_deployer.py

@@ -0,0 +1,195 @@
+"""
+⑥ DESPLIEGA — Skill Deployer Module
+
+Auto-registers compiled and validated skills into the skill registry.
+Creates SKILL.md files and makes them available to all agents.
+
+This is the "birth" — the skill becomes real and accessible.
+"""
+
+from __future__ import annotations
+import shutil
+from datetime import datetime
+from pathlib import Path
+from typing import Optional
+
+from .models import SkillGenesisPacket, CompilationResult, MetricSnapshot
+
+SKILLS_DIR = Path.home() / ".hermes" / "skills"
+
+
+class SkillDeployer:
+    """Deploys validated skills to the multi-agent skill registry."""
+
+    def __init__(self):
+        SKILLS_DIR.mkdir(parents=True, exist_ok=True)
+        self.deployment_log = Path.home() / ".hermes" / "traces" / "deployments.jsonl"
+
+    # ── Deploy ──────────────────────────────────────────────────────
+    def deploy(
+        self,
+        packet: SkillGenesisPacket,
+        compilation: CompilationResult,
+        validation: MetricSnapshot,
+    ) -> dict:
+        """Deploy a validated skill to the registry.
+
+        Returns deployment info with paths and status.
+        """
+        if not validation.passed:
+            return {
+                "deployed": False,
+                "skill_name": compilation.skill_name,
+                "reason": f"Validation failed. Delta {validation.deltas} < threshold {packet.threshold}",
+            }
+
+        # Determine skill category
+        category = self._categorize(packet)
+
+        # Create skill directory
+        skill_dir = SKILLS_DIR / category / compilation.skill_name
+        skill_dir.mkdir(parents=True, exist_ok=True)
+
+        # Generate SKILL.md
+        skill_md = self._generate_skill_md(packet, compilation, validation)
+        (skill_dir / "SKILL.md").write_text(skill_md)
+
+        # Copy compiled artifacts if they exist
+        compiled_path = Path(compilation.skill_path)
+        if compiled_path.exists():
+            for f in compiled_path.glob("*"):
+                if f.name != "SKILL.md":
+                    dest = skill_dir / f.name
+                    if f.is_dir():
+                        shutil.copytree(f, dest, dirs_exist_ok=True)
+                    else:
+                        shutil.copy2(f, dest)
+
+        # Log deployment
+        deploy_info = {
+            "deployed": True,
+            "skill_name": compilation.skill_name,
+            "category": category,
+            "skill_dir": str(skill_dir),
+            "packet_id": packet.packet_id,
+            "intent": packet.intent,
+            "delta": validation.deltas,
+            "threshold": packet.threshold,
+            "passed": validation.passed,
+            "deployed_at": datetime.now().isoformat(),
+            "target_agent": packet.target_agent,
+            "compilation_iteration": compilation.attempt,
+            "dspy_score": compilation.best_score,
+        }
+
+        with open(self.deployment_log, "a") as f:
+            f.write(__import__('json').dumps(deploy_info) + "\n")
+
+        return deploy_info
+
+    # ── SKILL.md Generation ─────────────────────────────────────────
+    def _generate_skill_md(
+        self,
+        packet: SkillGenesisPacket,
+        compilation: CompilationResult,
+        validation: MetricSnapshot,
+    ) -> str:
+        """Generate a professional SKILL.md for the new skill."""
+        return f"""---
+name: {compilation.skill_name}
+category: software-development
+description: Auto-generated by Promethean Cycle. {packet.intent}
+auto_generated: true
+promethean_packet_id: {packet.packet_id}
+generated_at: {datetime.now().isoformat()}
+---
+
+# {compilation.skill_name.replace('-', ' ').title()}
+
+> 🤖 Auto-compiled by the Promethean Cycle (GEPA ⊕ DSPy)
+> **Intent:** {packet.intent}
+> **Delta:** {validation.deltas}
+> **Threshold:** {packet.threshold} → {"✅ PASSED" if validation.passed else "❌ FAILED"}
+
+## When to Use
+
+This skill was automatically generated in response to detected operational failures.
+Use when encountering errors matching the pattern:
+
+```
+{packet.error_signature if hasattr(packet, 'error_signature') else packet.intent[:100]}
+```
+
+## Validation Results
+
+| Metric | Baseline | Evolved | Delta |
+|--------|----------|---------|-------|
+{chr(10).join(f"| {k} | {validation.baseline.get(k, 'N/A')} | {validation.evolved.get(k, 'N/A')} | {v} |" for k, v in validation.deltas.items())}
+
+- **Dataset size:** {validation.dataset_size}
+- **Holdout size:** {validation.holdout_size}
+- **DSPy Best Score:** {compilation.best_score}
+- **Compilation iterations:** {compilation.iterations}
+
+## Target Agents
+
+{packet.target_agent}
+
+## Compilation Strategy
+
+BetterTogether: `{packet.strategy}`
+
+## Signature
+
+```
+{packet.signature}
+```
+
+## Notes
+
+This skill was born from the Promethean Cycle — the dashboard detected a capability gap,
+GEPA formulated a learning objective, DSPy compiled the solution, and the delta validator
+confirmed its effectiveness. No human wrote this skill. The system learned it.
+"""
+
+    # ── Categorization ──────────────────────────────────────────────
+    def _categorize(self, packet: SkillGenesisPacket) -> str:
+        """Determine the best category for this skill."""
+        intent_lower = packet.intent.lower()
+        if any(kw in intent_lower for kw in ["deploy", "build", "docker", "ci", "pipeline"]):
+            return "devops"
+        elif any(kw in intent_lower for kw in ["database", "migration", "drizzle", "sql"]):
+            return "backend-patterns"
+        elif any(kw in intent_lower for kw in ["test", "validation", "qa", "verify"]):
+            return "testing"
+        elif any(kw in intent_lower for kw in ["auth", "login", "session", "oauth"]):
+            return "security"
+        elif any(kw in intent_lower for kw in ["expo", "react-native", "mobile", "app"]):
+            return "software-development"
+        else:
+            return "software-development"
+
+    # ── Registry Update ─────────────────────────────────────────────
+    def get_deployment_history(self, limit: int = 20) -> list[dict]:
+        """Get recent deployment history."""
+        if not self.deployment_log.exists():
+            return []
+
+        deployments = []
+        with open(self.deployment_log) as f:
+            for line in f:
+                if line.strip():
+                    deployments.append(__import__('json').loads(line))
+
+        return deployments[-limit:]
+
+
+# ── Singleton ───────────────────────────────────────────────────────
+_deployer: Optional[SkillDeployer] = None
+
+
+def get_deployer() -> SkillDeployer:
+    global _deployer
+    if _deployer is None:
+        _deployer = SkillDeployer()
+    return _deployer