nexo-brain 5.3.26 → 5.3.27

package/src/skills_runtime 2.py

@@ -1,932 +0,0 @@
-from __future__ import annotations
-"""Runtime helpers for Skills v2.
-
-This module is the single execution gate for skills. It decides:
-- guide vs execute vs hybrid mode
-- whether a skill is allowed to run
-- how parameters are validated and rendered
-- how execution is routed through the stable `nexo scripts run` CLI
-"""
-
-import json
-import os
-import re
-import subprocess
-import sys
-from pathlib import Path
-
-from db import (
-    approve_skill,
-    capture_outcome_pattern,
-    collect_skill_improvement_candidates,
-    collect_scriptable_skill_candidates,
-    create_skill,
-    get_featured_skills,
-    get_skill,
-    get_skill_outcome_evidence,
-    get_skill_execution_spec,
-    init_db,
-    list_outcome_pattern_candidates,
-    list_skill_outcome_reviews,
-    materialize_personal_skill_definition,
-    record_skill_usage,
-    render_command_template,
-    sync_skill_directories,
-    update_skill,
-)
-from script_registry import doctor_script
-
-NEXO_HOME = Path(os.environ.get("NEXO_HOME", str(Path.home() / ".nexo")))
-NEXO_CODE = Path(os.environ.get("NEXO_CODE", str(Path(__file__).resolve().parent)))
-VALID_LEVELS = {"trace", "draft", "published", "stable", "archived"}
-
-
-def _parse_params(params) -> dict:
-    if isinstance(params, dict):
-        return params
-    if isinstance(params, str):
-        text = params.strip()
-        if not text:
-            return {}
-        return json.loads(text)
-    return {}
-
-
-def _ensure_ready():
-    init_db()
-
-
-def _resolve_mode(requested: str, skill: dict) -> str:
-    mode = (requested or "auto").strip().lower()
-    if mode in {"guide", "execute", "hybrid"}:
-        return mode
-    effective = str(skill.get("mode", "") or "").strip().lower()
-    if effective in {"guide", "execute", "hybrid"}:
-        return effective
-    if skill.get("file_path") and skill.get("content"):
-        return "hybrid"
-    if skill.get("file_path"):
-        return "execute"
-    return "guide"
-
-
-def _summarize_skill(skill: dict) -> str:
-    steps = []
-    gotchas = []
-    try:
-        steps = json.loads(skill.get("steps", "[]"))
-    except json.JSONDecodeError:
-        pass
-    try:
-        gotchas = json.loads(skill.get("gotchas", "[]"))
-    except json.JSONDecodeError:
-        pass
-
-    lines = [
-        f"[{skill['id']}] {skill['name']}",
-        skill.get("description", "") or "(no description)",
-    ]
-    if steps:
-        lines.append("Steps:")
-        for index, step in enumerate(steps[:6], 1):
-            lines.append(f"{index}. {step}")
-    elif skill.get("content"):
-        lines.append(skill["content"][:800])
-    if gotchas:
-        lines.append("Gotchas:")
-        for gotcha in gotchas[:4]:
-            lines.append(f"- {gotcha}")
-    return "\n".join(lines).strip()
-
-
-def _resolve_cli_command() -> list[str]:
-    installed = NEXO_HOME / "bin" / "nexo"
-    if installed.is_file():
-        return [str(installed)]
-    return [sys.executable, str(NEXO_CODE / "cli.py")]
-
-
-def _run_skill_script(skill: dict, argv: list[str], timeout: int = 300) -> dict:
-    if not argv:
-        return {"returncode": 1, "stdout": "", "stderr": "No command to execute"}
-
-    env = {
-        **os.environ,
-        "NEXO_HOME": str(NEXO_HOME),
-        "NEXO_CODE": str(NEXO_CODE),
-        "NEXO_SKILL_ID": skill["id"],
-        "NEXO_SKILL_NAME": skill["name"],
-    }
-
-    cli_cmd = _resolve_cli_command()
-    cmd = [*cli_cmd, "scripts", "run", argv[0], *argv[1:]]
-    try:
-        result = subprocess.run(
-            cmd,
-            capture_output=True,
-            text=True,
-            timeout=timeout,
-            env=env,
-        )
-        return {
-            "returncode": result.returncode,
-            "stdout": result.stdout,
-            "stderr": result.stderr,
-            "command": cmd,
-        }
-    except subprocess.TimeoutExpired:
-        return {
-            "returncode": 124,
-            "stdout": "",
-            "stderr": f"Skill execution timed out after {timeout}s",
-            "command": cmd,
-        }
-
-
-def get_featured_skill_summaries(limit: int = 5) -> list[dict]:
-    _ensure_ready()
-    sync_skill_directories()
-    featured = []
-    for skill in get_featured_skills(limit=limit):
-        triggers = []
-        try:
-            triggers = json.loads(skill.get("trigger_patterns", "[]"))
-        except json.JSONDecodeError:
-            pass
-        featured.append(
-            {
-                "id": skill["id"],
-                "name": skill["name"],
-                "mode": skill.get("mode", "guide"),
-                "execution_level": skill.get("execution_level", "none"),
-                "source_kind": skill.get("source_kind", "personal"),
-                "trust_score": skill.get("trust_score", 0),
-                "trigger_patterns": triggers[:3],
-                "outcome_review": {
-                    "has_evidence": bool((skill.get("_outcome_review") or {}).get("has_evidence")),
-                    "recommended_action": (skill.get("_outcome_review") or {}).get("recommended_action", "observe"),
-                    "success_rate": (skill.get("_outcome_review") or {}).get("success_rate"),
-                    "resolved_outcomes": (skill.get("_outcome_review") or {}).get("resolved_outcomes", 0),
-                    "ranking_weight": float(skill.get("_outcome_rank", 0.0)),
-                },
-            }
-        )
-    return featured
-
-
-def _skill_json_list(skill: dict, key: str) -> list:
-    try:
-        value = json.loads(skill.get(key, "[]"))
-    except json.JSONDecodeError:
-        value = []
-    return value if isinstance(value, list) else []
-
-
-def _outcome_skill_id(candidate: dict) -> str:
-    raw_parts = [
-        candidate.get("area", ""),
-        candidate.get("task_type", ""),
-        candidate.get("goal_profile_id", ""),
-        candidate.get("selected_choice", ""),
-    ]
-    chunks = []
-    for part in raw_parts:
-        cleaned = re.sub(r"[^A-Z0-9]+", "-", str(part or "").upper()).strip("-")
-        if cleaned:
-            chunks.append(cleaned[:12])
-    suffix = "-".join(chunks[:4]) or "GENERAL"
-    return f"SK-OUTCOME-{suffix}"
-
-
-def _outcome_pattern_to_skill_payload(candidate: dict, learning_id: int) -> dict:
-    selected_choice = candidate.get("selected_choice", "")
-    context_label = candidate.get("context_label", "contexto general")
-    evidence = candidate.get("evidence") or []
-    evidence_summary = ", ".join(
-        f"eval#{item.get('evaluation_id')}/outcome#{item.get('outcome_id')}:{item.get('status')}"
-        for item in evidence[:5]
-    )
-    description = (
-        f"Draft skill candidate derived from {candidate.get('resolved_outcomes', 0)} resolved outcomes "
-        f"for '{selected_choice}' in {context_label}."
-    )
-    steps = [
-        f"Confirm that the current case matches {context_label}.",
-        f"Use '{selected_choice}' as the default starting strategy.",
-        "Check fresh constraints or evidence that could invalidate the historical pattern.",
-        "Link and evaluate the resulting outcome so the evidence base keeps improving.",
-    ]
-    gotchas = [
-        "Do not apply this skill if current evidence contradicts the pattern.",
-        "Keep outcomes linked; a pattern without fresh feedback should not gain trust forever.",
-    ]
-    content = "\n".join(
-        [
-            f"# Outcome pattern skill candidate — {selected_choice}",
-            "",
-            description,
-            "",
-            "## Evidence",
-            f"- Success rate: {candidate.get('success_rate', 0.0):.3f}",
-            f"- Resolved outcomes: {candidate.get('resolved_outcomes', 0)}",
-            f"- Context: {context_label}",
-            f"- Evidence refs: {evidence_summary or 'none'}",
-            "",
-            "## Steps",
-            *(f"{index}. {step}" for index, step in enumerate(steps, 1)),
-            "",
-            "## Gotchas",
-            *(f"- {gotcha}" for gotcha in gotchas),
-            "",
-        ]
-    )
-    tags = [
-        "outcomes-derived",
-        str(candidate.get("area") or "").strip(),
-        str(candidate.get("task_type") or "").strip(),
-        str(candidate.get("goal_profile_id") or "").strip(),
-    ]
-    trigger_patterns = [
-        str(candidate.get("selected_choice") or "").strip(),
-        str(candidate.get("area") or "").strip(),
-        str(candidate.get("task_type") or "").strip(),
-    ]
-    return {
-        "id": _outcome_skill_id(candidate),
-        "name": f"Outcome Pattern: {selected_choice}",
-        "description": description,
-        "level": "draft",
-        "mode": "guide",
-        "tags": [item for item in tags if item],
-        "trigger_patterns": [item for item in trigger_patterns if item],
-        "linked_learnings": [int(learning_id)],
-        "steps": steps,
-        "gotchas": gotchas,
-        "content": content,
-    }
-
-
-def test_skill(skill_id: str, params=None, mode: str = "auto", context: str = "") -> dict:
-    result = apply_skill(skill_id, params=params, mode=mode, dry_run=True, context=context or "skill_test")
-    result["tested"] = True
-    result["test_kind"] = "dry_run"
-    return result
-
-
-def promote_skill(skill_id: str, target_level: str = "published", reason: str = "") -> dict:
-    _ensure_ready()
-    sync_skill_directories()
-    skill = get_skill(skill_id)
-    if not skill:
-        return {"ok": False, "error": f"Skill {skill_id} not found"}
-    clean_target = str(target_level or "published").strip().lower()
-    if clean_target not in VALID_LEVELS:
-        return {"ok": False, "error": f"Unsupported target_level: {target_level}"}
-    if clean_target == "archived":
-        return {"ok": False, "error": "Use retire_skill to archive skills explicitly"}
-    outcome_review = get_skill_outcome_evidence(skill_id)
-    if outcome_review.get("has_evidence"):
-        recommended = outcome_review.get("recommended_action")
-        if clean_target == "published" and recommended not in {"promote_published", "promote_stable"}:
-            return {
-                "ok": False,
-                "error": "Outcome evidence does not yet support promotion to published",
-                "outcome_review": outcome_review,
-            }
-        if clean_target == "stable" and recommended != "promote_stable":
-            return {
-                "ok": False,
-                "error": "Outcome evidence does not yet support promotion to stable",
-                "outcome_review": outcome_review,
-            }
-    updated = update_skill(skill_id, level=clean_target)
-    if "error" in updated:
-        return {"ok": False, "error": updated["error"]}
-    return {
-        "ok": True,
-        "skill_id": skill_id,
-        "previous_level": skill.get("level", ""),
-        "level": updated.get("level", clean_target),
-        "reason": str(reason or "").strip(),
-        "outcome_review": outcome_review,
-    }
-
-
-def retire_skill(skill_id: str, replacement_id: str = "", reason: str = "") -> dict:
-    _ensure_ready()
-    sync_skill_directories()
-    skill = get_skill(skill_id)
-    if not skill:
-        return {"ok": False, "error": f"Skill {skill_id} not found"}
-    replacement = None
-    clean_replacement = str(replacement_id or "").strip()
-    if clean_replacement:
-        replacement = get_skill(clean_replacement)
-        if not replacement:
-            return {"ok": False, "error": f"Replacement skill {clean_replacement} not found"}
-    updated = update_skill(skill_id, level="archived")
-    if "error" in updated:
-        return {"ok": False, "error": updated["error"]}
-    return {
-        "ok": True,
-        "skill_id": skill_id,
-        "level": updated.get("level", "archived"),
-        "replacement_id": clean_replacement,
-        "reason": str(reason or "").strip(),
-        "outcome_review": get_skill_outcome_evidence(skill_id),
-    }
-
-
-def review_skill_outcomes(skill_id: str, auto_apply: bool = False) -> dict:
-    _ensure_ready()
-    sync_skill_directories()
-    skill = get_skill(skill_id)
-    if not skill:
-        return {"ok": False, "error": f"Skill {skill_id} not found"}
-
-    review = get_skill_outcome_evidence(skill_id)
-    if "error" in review:
-        return {"ok": False, "error": review["error"]}
-
-    result = {
-        "ok": True,
-        "skill_id": skill_id,
-        "level": skill.get("level", ""),
-        "review": review,
-        "auto_applied": False,
-        "applied_action": "",
-    }
-    if not auto_apply:
-        return result
-
-    action = review.get("recommended_action")
-    target_level = ""
-    if action == "promote_published":
-        target_level = "published"
-    elif action == "promote_stable":
-        target_level = "stable"
-    elif action == "retire":
-        target_level = "archived"
-    if not target_level:
-        return result
-
-    updated = update_skill(skill_id, level=target_level)
-    if "error" in updated:
-        return {"ok": False, "error": updated["error"], "review": review}
-    result["auto_applied"] = True
-    result["applied_action"] = action
-    result["level"] = updated.get("level", target_level)
-    result["skill"] = updated
-    return result
-
-
-def compose_skills(
-    *,
-    new_skill_id: str,
-    name: str,
-    component_ids: list[str],
-    description: str = "",
-    level: str = "draft",
-    mode: str = "guide",
-    tags: list[str] | None = None,
-    trigger_patterns: list[str] | None = None,
-) -> dict:
-    _ensure_ready()
-    sync_skill_directories()
-    if get_skill(new_skill_id):
-        return {"ok": False, "error": f"Skill {new_skill_id} already exists"}
-    components = []
-    for skill_id in component_ids:
-        skill = get_skill(skill_id)
-        if not skill:
-            return {"ok": False, "error": f"Component skill {skill_id} not found"}
-        components.append(skill)
-    if not components:
-        return {"ok": False, "error": "At least one component skill is required"}
-
-    merged_steps: list[str] = []
-    merged_gotchas: list[str] = []
-    merged_tags = set(tags or [])
-    merged_triggers = set(trigger_patterns or [])
-    linked_learnings = set()
-    source_sessions = set()
-    content_lines = [f"# {name}", "", description or "Composite skill built from existing NEXO skills.", "", "## Components"]
-    for skill in components:
-        content_lines.append(f"- {skill['id']}: {skill['name']}")
-        for step in _skill_json_list(skill, "steps"):
-            if step and step not in merged_steps:
-                merged_steps.append(step)
-        for gotcha in _skill_json_list(skill, "gotchas"):
-            if gotcha and gotcha not in merged_gotchas:
-                merged_gotchas.append(gotcha)
-        for trigger in _skill_json_list(skill, "trigger_patterns"):
-            if trigger:
-                merged_triggers.add(trigger)
-        for tag in _skill_json_list(skill, "tags"):
-            if tag:
-                merged_tags.add(tag)
-        for item in _skill_json_list(skill, "linked_learnings"):
-            if item:
-                linked_learnings.add(item)
-        for item in _skill_json_list(skill, "source_sessions"):
-            if item:
-                source_sessions.add(item)
-
-    if merged_steps:
-        content_lines.extend(["", "## Steps"])
-        for index, step in enumerate(merged_steps, 1):
-            content_lines.append(f"{index}. {step}")
-    if merged_gotchas:
-        content_lines.extend(["", "## Gotchas"])
-        for gotcha in merged_gotchas:
-            content_lines.append(f"- {gotcha}")
-
-    created = create_skill(
-        skill_id=new_skill_id,
-        name=name,
-        description=description or f"Composite skill built from {', '.join(component_ids)}",
-        level=level,
-        tags=sorted(merged_tags),
-        trigger_patterns=sorted(merged_triggers),
-        source_sessions=sorted(source_sessions),
-        linked_learnings=sorted(linked_learnings),
-        steps=merged_steps,
-        gotchas=merged_gotchas,
-        content="\n".join(content_lines).strip() + "\n",
-        mode=mode,
-        source_kind="personal",
-    )
-    if "error" in created:
-        return {"ok": False, "error": created["error"]}
-    return {
-        "ok": True,
-        "skill_id": new_skill_id,
-        "component_ids": component_ids,
-        "level": created.get("level", level),
-        "mode": created.get("mode", mode),
-    }
-
-
-def apply_skill(skill_id: str, params=None, mode: str = "auto", dry_run: bool = False, context: str = "") -> dict:
-    _ensure_ready()
-    sync_skill_directories()
-    skill = get_skill(skill_id)
-    if not skill:
-        return {"ok": False, "error": f"Skill {skill_id} not found"}
-
-    effective_mode = _resolve_mode(mode, skill)
-    response = {
-        "ok": True,
-        "skill_id": skill["id"],
-        "skill_name": skill["name"],
-        "requested_mode": mode,
-        "resolved_mode": effective_mode,
-        "approval_state": {
-            "approval_required": bool(skill.get("approval_required", 0)),
-            "approved_at": skill.get("approved_at", ""),
-            "execution_level": skill.get("execution_level", "none"),
-        },
-    }
-
-    if effective_mode in {"guide", "hybrid"}:
-        response["guide_summary"] = _summarize_skill(skill)
-
-    if effective_mode in {"execute", "hybrid"}:
-        exec_spec = get_skill_execution_spec(skill_id)
-        if "error" in exec_spec:
-            response["ok"] = False
-            response["error"] = exec_spec["error"]
-            return response
-
-        if not skill.get("file_path"):
-            response["ok"] = False
-            response["error"] = f"Skill {skill_id} has no executable script"
-            return response
-
-        if exec_spec["execution_level"] in {"read-only", "local", "remote"} and not skill.get("approved_at"):
-            skill = approve_skill(skill_id, execution_level=exec_spec["execution_level"], approved_by="system:auto")
-            response["approval_state"] = {
-                "approval_required": bool(skill.get("approval_required", 0)),
-                "approved_at": skill.get("approved_at", ""),
-                "execution_level": skill.get("execution_level", exec_spec["execution_level"]),
-            }
-
-        doctor = doctor_script(skill["file_path"])
-        response["script_doctor"] = doctor
-        if doctor["status"] == "fail":
-            response["ok"] = False
-            response["error"] = "Skill script failed validation"
-            return response
-
-        rendered = render_command_template(skill, _parse_params(params))
-        if not rendered.get("ok"):
-            response["ok"] = False
-            response["error"] = "Invalid skill parameters"
-            response["param_errors"] = rendered.get("errors", [])
-            return response
-
-        argv = rendered["argv"] or [skill["file_path"]]
-        response["resolved_params"] = rendered["params"]
-        response["script_command"] = argv
-        if dry_run:
-            response["dry_run"] = True
-            return response
-
-        execution = _run_skill_script(skill, argv)
-        response["execution_result"] = execution
-        success = execution["returncode"] == 0
-        record = record_skill_usage(
-            skill_id=skill_id,
-            success=success,
-            context=context or skill["name"],
-            notes=(execution["stderr"] or execution["stdout"])[:500],
-        )
-        response["usage_recorded"] = {
-            "success": success,
-            "trust_score": record.get("trust_score"),
-            "level": record.get("level"),
-            "promotion": record.get("_promotion"),
-        }
-        if not success:
-            response["ok"] = False
-            response["error"] = f"Skill execution failed with exit {execution['returncode']}"
-
-    return response
-
-
-def sync_skills() -> dict:
-    _ensure_ready()
-    return sync_skill_directories()
-
-
-def approve_skill_execution(skill_id: str, execution_level: str = "", approved_by: str = "") -> dict:
-    _ensure_ready()
-    return approve_skill(skill_id, execution_level=execution_level, approved_by=approved_by)
-
-
-def list_evolution_candidates() -> dict:
-    _ensure_ready()
-    sync_skill_directories()
-    outcome_patterns = [
-        candidate
-        for candidate in list_outcome_pattern_candidates(limit=20)
-        if candidate.get("candidate_type") == "reinforce_strategy" and candidate.get("suggested_skill_candidate")
-    ]
-    return {
-        "scriptable": collect_scriptable_skill_candidates(),
-        "improvements": collect_skill_improvement_candidates(),
-        "outcome_patterns": outcome_patterns,
-        "outcome_lifecycle": list_skill_outcome_reviews(limit=20, actionable_only=True),
-    }
-
-
-def materialize_outcome_pattern_skill(pattern_key: str) -> dict:
-    _ensure_ready()
-    sync_skill_directories()
-    candidates = list_outcome_pattern_candidates(limit=200)
-    candidate = next((item for item in candidates if item.get("pattern_key") == pattern_key), None)
-    if not candidate:
-        return {"ok": False, "error": "Outcome pattern candidate not found"}
-    if candidate.get("candidate_type") != "reinforce_strategy":
-        return {"ok": False, "error": "Only reinforce_strategy patterns can seed a skill"}
-    if not candidate.get("suggested_skill_candidate"):
-        return {"ok": False, "error": "Pattern is not strong enough yet to seed a skill draft"}
-
-    learning_result = capture_outcome_pattern(pattern_key, target="learning", category="outcomes")
-    if "error" in learning_result:
-        return {"ok": False, "error": learning_result["error"]}
-    learning = learning_result.get("learning") or {}
-    skill_id = _outcome_skill_id(candidate)
-    existing = get_skill(skill_id)
-    if existing:
-        return {
-            "ok": True,
-            "created": False,
-            "skill": existing,
-            "candidate": candidate,
-            "learning": learning,
-        }
-
-    payload = _outcome_pattern_to_skill_payload(candidate, int(learning.get("id", 0) or 0))
-    created = materialize_personal_skill_definition(payload)
-    if "error" in created:
-        return {"ok": False, "error": created["error"]}
-    return {
-        "ok": True,
-        "created": True,
-        "skill": created,
-        "candidate": candidate,
-        "learning": learning,
-    }
-
-
-def auto_promote_outcome_patterns_to_skills(
-    *,
-    min_success_rate: float = 0.8,
-    max_promotions: int = 3,
-) -> dict:
-    """Promote mature outcome patterns to draft skills without manual approval.
-
-    Closes Fase 2 item 2 of NEXO-AUDIT-2026-04-11. Until this function ran
-    automatically, every outcome pattern that crossed the suggested-skill
-    threshold sat in the candidates table waiting for an explicit
-    nexo_skill_seed_from_outcome_pattern call. The materialization helper
-    already existed (see materialize_outcome_pattern_skill above), but no
-    process invoked it on a schedule.
-
-    This wrapper:
-      - Lists current outcome pattern candidates (top 20).
-      - Filters to reinforce_strategy candidates that the analyzer already
-        flagged as suggested_skill_candidate=True (resolved >= 4) AND whose
-        success_rate is at or above min_success_rate (default 0.8).
-      - Calls materialize_outcome_pattern_skill() per qualifying candidate,
-        capped at max_promotions per invocation so a sudden flood does not
-        materialize dozens of skills in one cycle.
-      - materialize_outcome_pattern_skill() is itself idempotent: if the
-        target skill id already exists it returns created=False without
-        re-creating, so this function is safe to run repeatedly.
-
-    Returns a stats dict:
-        {
-          "promoted": [list of {pattern_key, skill_id, created}],
-          "skipped": [list of {pattern_key, reason}],
-          "errors":  [list of {pattern_key, error}],
-          "scanned": int,  # number of candidates inspected
-        }
-
-    Best-effort: never raises. A single failing pattern logs an error entry
-    but lets the loop continue, so one bad row never blocks the queue.
-    """
-    _ensure_ready()
-    sync_skill_directories()
-
-    promoted: list[dict] = []
-    skipped: list[dict] = []
-    errors: list[dict] = []
-
-    try:
-        candidates = list_outcome_pattern_candidates(limit=20)
-    except Exception as e:
-        return {
-            "promoted": [],
-            "skipped": [],
-            "errors": [{"pattern_key": "*", "error": f"list_outcome_pattern_candidates raised: {e}"}],
-            "scanned": 0,
-        }
-
-    scanned = 0
-    promote_budget = max(0, int(max_promotions))
-    for candidate in candidates:
-        scanned += 1
-        pattern_key = (candidate.get("pattern_key") or "").strip()
-        if not pattern_key:
-            skipped.append({"pattern_key": "", "reason": "missing pattern_key"})
-            continue
-        if candidate.get("candidate_type") != "reinforce_strategy":
-            skipped.append({"pattern_key": pattern_key, "reason": "not reinforce_strategy"})
-            continue
-        if not candidate.get("suggested_skill_candidate"):
-            skipped.append({"pattern_key": pattern_key, "reason": "below suggested_skill_candidate threshold"})
-            continue
-        success_rate = float(candidate.get("success_rate") or 0.0)
-        if success_rate < float(min_success_rate):
-            skipped.append({
-                "pattern_key": pattern_key,
-                "reason": f"success_rate {success_rate:.3f} < {min_success_rate:.3f}",
-            })
-            continue
-        if promote_budget <= 0:
-            skipped.append({"pattern_key": pattern_key, "reason": "promotion budget exhausted"})
-            continue
-
-        try:
-            result = materialize_outcome_pattern_skill(pattern_key)
-        except Exception as e:
-            errors.append({"pattern_key": pattern_key, "error": str(e)})
-            continue
-
-        if not result.get("ok"):
-            errors.append({
-                "pattern_key": pattern_key,
-                "error": result.get("error", "materialize_outcome_pattern_skill failed"),
-            })
-            continue
-
-        skill = result.get("skill") or {}
-        promoted.append({
-            "pattern_key": pattern_key,
-            "skill_id": skill.get("id") or skill.get("skill_id"),
-            "created": bool(result.get("created")),
-            "success_rate": success_rate,
-            "resolved_outcomes": int(candidate.get("resolved_outcomes") or 0),
-        })
-        # Only newly-created skills consume the budget. Idempotent re-use of
-        # an existing skill costs nothing because it didn't materialize a new
-        # one — letting other candidates through.
-        if result.get("created"):
-            promote_budget -= 1
-
-    return {
-        "promoted": promoted,
-        "skipped": skipped,
-        "errors": errors,
-        "scanned": scanned,
-    }
-
-
-def detect_skill_coactivation_candidates(
-    *,
-    min_co_occurrence: int = 3,
-    min_success_rate: float = 0.6,
-    limit: int = 20,
-) -> list[dict]:
-    """Detect pairs of skills that fire together and could be composed.
-
-    Closes Fase 5 item 5 of NEXO-AUDIT-2026-04-11. NEXO already has
-    compose_skills (manual composer), auto_promote_outcome_patterns_to_skills
-    (Fase 2 item 2), and auto_promote_skill_evolution (guide → executable
-    draft). What it lacked is the Voyager-style observation pass: when
-    the same two skills are used inside the same session multiple times,
-    a composite skill probably wants to exist.
-
-    This function reads skill_usage rows, groups by session_id to get
-    the set of skills per session, builds a co-occurrence count over
-    all unordered pairs, and returns candidates whose count is at or
-    above min_co_occurrence and whose joint success rate is at or
-    above min_success_rate.
-
-    Args:
-        min_co_occurrence: minimum number of sessions both skills must
-            have co-occurred in. Default 3 — same threshold the
-            outcome_pattern detector uses.
-        min_success_rate: minimum joint success rate (success rows /
-            total rows for the pair). Default 0.6.
-        limit: max candidates to return. Default 20.
-
-    Returns a list (newest co-occurrence first):
-        [
-          {
-            "skill_a": str, "skill_b": str,
-            "co_occurrence": int,
-            "joint_success_rate": float,
-            "sessions": [session_id, ...],
-            "suggested_skill_id": str,   # canonical id for the composite
-          },
-          ...
-        ]
-
-    Pure DB read, never raises. Empty list when skill_usage table is
-    missing or no candidates qualify.
-    """
-    _ensure_ready()
-    try:
-        from db import get_db
-        conn = get_db()
-        # Sanity check the table exists.
-        conn.execute("SELECT 1 FROM skill_usage LIMIT 1").fetchone()
-    except Exception:
-        return []
-
-    try:
-        rows = conn.execute(
-            "SELECT skill_id, session_id, success FROM skill_usage "
-            "WHERE session_id IS NOT NULL AND session_id != '' "
-            "ORDER BY created_at DESC LIMIT 5000"
-        ).fetchall()
-    except Exception:
-        return []
-
-    by_session: dict[str, list[tuple[str, int]]] = {}
-    for row in rows:
-        sid = (row["session_id"] or "").strip() if hasattr(row, "keys") else (row[1] or "").strip()
-        if not sid:
-            continue
-        skill_id = row["skill_id"] if hasattr(row, "keys") else row[0]
-        success = row["success"] if hasattr(row, "keys") else row[2]
-        by_session.setdefault(sid, []).append((skill_id, int(success or 0)))
-
-    pair_stats: dict[tuple[str, str], dict] = {}
-    for sid, usages in by_session.items():
-        # Distinct skills with their best (any) success in this session.
-        seen_in_session: dict[str, int] = {}
-        for skill_id, success in usages:
-            seen_in_session[skill_id] = max(seen_in_session.get(skill_id, 0), success)
-        skills_in_session = sorted(seen_in_session.keys())
-        if len(skills_in_session) < 2:
-            continue
-        for i in range(len(skills_in_session)):
-            for j in range(i + 1, len(skills_in_session)):
-                pair = (skills_in_session[i], skills_in_session[j])
-                stats = pair_stats.setdefault(
-                    pair,
-                    {"co_occurrence": 0, "joint_success": 0, "sessions": []},
-                )
-                stats["co_occurrence"] += 1
-                # Joint success: both skills succeeded in this session.
-                if seen_in_session[pair[0]] and seen_in_session[pair[1]]:
-                    stats["joint_success"] += 1
-                stats["sessions"].append(sid)
-
-    candidates: list[dict] = []
-    for (skill_a, skill_b), stats in pair_stats.items():
-        co = stats["co_occurrence"]
-        if co < int(min_co_occurrence):
-            continue
-        rate = stats["joint_success"] / co if co > 0 else 0.0
-        if rate < float(min_success_rate):
-            continue
-        # Deterministic suggested id derived from the pair so re-running
-        # the detector points at the same composite skill.
-        suggested_id = "SK-COMPOSE-" + "+".join(sorted([skill_a, skill_b]))
-        candidates.append({
-            "skill_a": skill_a,
-            "skill_b": skill_b,
-            "co_occurrence": co,
-            "joint_success_rate": round(rate, 3),
-            "sessions": stats["sessions"][:5],
-            "suggested_skill_id": suggested_id,
-        })
-
-    candidates.sort(key=lambda c: (-c["co_occurrence"], -c["joint_success_rate"]))
-    return candidates[: max(1, int(limit))]
-
-
-def auto_promote_skill_evolution(approved_by: str = "system:auto") -> dict:
-    """Convert mature guide skills into executable drafts without manual approval."""
-    _ensure_ready()
-    sync_skill_directories()
-    promoted = []
-    skipped = []
-    for candidate in collect_scriptable_skill_candidates():
-        skill = get_skill(candidate["id"])
-        if not skill or skill.get("file_path"):
-            continue
-
-        steps = candidate.get("steps") or []
-        gotchas = candidate.get("gotchas") or []
-        description = candidate.get("description", "") or "Automated skill generated from repeated successful usage."
-        lines = [
-            "#!/usr/bin/env python3",
-            '"""Auto-generated executable skill draft."""',
-            "import json",
-            "import sys",
-            "",
-            "def main() -> int:",
-            "    payload = {",
-            f"        'skill_id': {json.dumps(candidate['id'])},",
-            f"        'skill_name': {json.dumps(candidate['name'])},",
-            f"        'description': {json.dumps(description)},",
-            f"        'steps': {json.dumps(steps, ensure_ascii=False)},",
-            f"        'gotchas': {json.dumps(gotchas, ensure_ascii=False)},",
-            "        'argv': sys.argv[1:],",
-            "    }",
-            "    print(json.dumps(payload, ensure_ascii=False))",
-            "    return 0",
-            "",
-            'if __name__ == "__main__":',
-            "    raise SystemExit(main())",
-            "",
-        ]
-        update = update_skill(
-            candidate["id"],
-            mode=candidate.get("suggested_mode", "hybrid"),
-            execution_level=candidate.get("suggested_execution_level", "read-only"),
-            approval_required=0,
-            approved_by=approved_by,
-        )
-        if "error" in update:
-            skipped.append({"id": candidate["id"], "reason": update["error"]})
-            continue
-
-        materialized = materialize_personal_skill_definition(
-            {
-                "id": candidate["id"],
-                "name": candidate["name"],
-                "description": description,
-                "level": skill.get("level", "published"),
-                "mode": candidate.get("suggested_mode", "hybrid"),
-                "execution_level": candidate.get("suggested_execution_level", "read-only"),
-                "approved_by": approved_by,
-                "tags": json.loads(skill.get("tags", "[]")) if skill.get("tags") else [],
-                "trigger_patterns": candidate.get("trigger_patterns", []),
-                "source_sessions": candidate.get("source_sessions", []),
-                "steps": steps,
-                "gotchas": gotchas,
-                "content": skill.get("content", ""),
-                "command_template": {"argv": ["{{file_path}}"]},
-                "executable_entry": "script.py",
-                "script_body": "\n".join(lines),
-            }
-        )
-        if "error" in materialized:
-            skipped.append({"id": candidate["id"], "reason": materialized["error"]})
-            continue
-
-        promoted.append(
-            {
-                "id": candidate["id"],
-                "mode": candidate.get("suggested_mode", "hybrid"),
-                "execution_level": candidate.get("suggested_execution_level", "read-only"),
-            }
-        )
-    return {"promoted": promoted, "skipped": skipped}