theus-cli-darwin-x64 0.2.84

package/vendor/theus-arsenal/skills/puerta-de-entrega/hooks/puerta-entrega.py

@@ -0,0 +1,242 @@
+#!/usr/bin/env python3
+"""
+Hook de Stop: puerta de entrega (quality gate mecánica).
+Detecta trabajo incompleto, bibliotecas de aprendizaje sin actualizar y
+poco espacio en disco. Impide que el agente finalice cuando una tarea
+compleja terminó sin captura de aprendizaje.
+
+Instalación: copia este archivo a ~/.theus/scripts/puerta-entrega.py
+Configuración: regístralo en el evento Stop de tu configuración de hooks
+(ver SKILL.md de `puerta-de-entrega`).
+"""
+from __future__ import annotations
+
+import sys
+import os
+import re
+import json
+import datetime
+import shutil
+import logging
+from typing import Optional
+
+# ---- Configuración ----
+# Patrones de racionalización (el agente conversa en español o inglés,
+# así que se cubren ambos idiomas).
+RATIONALIZE = [
+    r'(?:this|that)\s+is\s+a\s+pre[- ]existing\s+(?:issue|bug)\b(?!\s+(?:that|which|and))',
+    r'skipping\s+(?:tests?|lint|coverage|type[- ]check)\s+for\s+now',
+    r'(?:tests?|coverage)\s+(?:are|is)\s+(?:failing|broken)\s+but\s+(?:I|we)\s+(?:\'ll|can|will)\s+(?:fix|address|resolve|handle)',
+    r'(?:not\s+addressing|won\'t\s+fix|leaving)\s+the\s+(?:failing|broken)\s+(?:tests?|builds?|integration\s+tests?)',
+    r'es\s+un\s+(?:problema|bug|error)\s+pre[- ]?existente\b(?!\s+(?:que|y))',
+    r'(?:omito|salto|saltando|omitiendo)\s+(?:las?\s+)?(?:pruebas?|tests?|lint|cobertura)\s+por\s+ahora',
+    r'(?:las?\s+)?(?:pruebas?|tests?)\s+(?:fallan|est[aá]n?\s+rotas?)\s+pero\s+(?:lo|las?)\s+(?:arreglar|resolver|atender)',
+]
+
+# Bibliotecas de aprendizaje a vigilar (rutas relativas al directorio de
+# memoria del proyecto). Personalízalas a tu propia estructura.
+LIBS = {
+    'ratings-tracker': 'ratings-tracker.md',
+    'decisions-log': 'decisions/log.md',
+    'growth-log': 'growth-log/',
+    'output-index': 'output-index.md',
+    'tooling-capabilities': 'tooling_capabilities.md',
+}
+
+MIN_CHARS = 40
+COMPLEX_THRESHOLD = 3
+DISK_REMIND_GB = 50
+DISK_WARN_GB = 30
+DISK_CRIT_GB = 15
+# ---- Fin de la configuración ----
+
+logging.basicConfig(
+    stream=sys.stderr,
+    format='%(levelname)s: %(message)s',
+    level=logging.INFO,
+)
+log = logging.getLogger('puerta-entrega')
+
+
+def get_agent_data_home() -> str:
+    """Raíz de datos del agente: THEUS_AGENT_DATA_HOME o ~/.theus/arsenal.
+
+    Replica la cadena de resolución de scripts/lib/agent-data-home.js
+    del arsenal para que el estado viva en un solo lugar."""
+    override = os.environ.get('THEUS_AGENT_DATA_HOME', '').strip()
+    if override:
+        return os.path.expanduser(override)
+    return os.path.expanduser(os.path.join('~', '.theus', 'arsenal'))
+
+
+def get_project_memory_dir() -> Optional[str]:
+    """Encuentra el directorio de memoria del proyecto actual.
+
+    Devuelve None si no existe directorio de memoria para este proyecto.
+    NO cae a otros proyectos (frontera de privacidad)."""
+    cwd = os.environ.get('THEUS_PROJECT_DIR', os.getcwd())
+    safe = cwd.replace(':', '-').replace('\\', '-').replace('/', '-')
+    mem = os.path.join(get_agent_data_home(), 'projects', safe, 'memory')
+    log.info('Buscando directorio de memoria: cwd=%s -> %s', cwd, mem)
+    if os.path.isdir(mem):
+        return mem
+    return None
+
+
+def check_disk() -> Optional[int]:
+    """Espacio libre en el disco que contiene el directorio home.
+
+    Multiplataforma: macOS, Linux, Windows.
+    Devuelve GB libres, o None si el home no está disponible."""
+    try:
+        home = os.path.expanduser('~')
+        free_gb = shutil.disk_usage(home).free // (2**30)
+        return free_gb
+    except (FileNotFoundError, PermissionError, OSError):
+        log.warning('no se puede verificar el espacio en disco (home inaccesible)')
+        return None
+
+
+def check_stale_libs(mem_dir: str) -> list[str]:
+    """Devuelve los nombres de bibliotecas no actualizadas hoy.
+
+    Manejo de OSError por archivo: los archivos ilegibles individuales se
+    omiten, pero el escaneo continúa con las bibliotecas restantes."""
+    today = datetime.date.today()
+    stale: list[str] = []
+    for name, path in LIBS.items():
+        full = os.path.join(mem_dir, path)
+        try:
+            if os.path.isdir(full):
+                has_today = False
+                for dirpath, _dirnames, filenames in os.walk(full):
+                    for f in filenames:
+                        fp = os.path.join(dirpath, f)
+                        try:
+                            mt = datetime.datetime.fromtimestamp(os.path.getmtime(fp)).date()
+                            if mt == today:
+                                has_today = True
+                                break
+                        except OSError:
+                            continue
+                    if has_today:
+                        break
+                if not has_today:
+                    stale.append(name)
+            elif os.path.exists(full):
+                try:
+                    mt = datetime.datetime.fromtimestamp(os.path.getmtime(full)).date()
+                    if mt != today:
+                        stale.append(name)
+                except OSError:
+                    stale.append(name)
+            else:
+                stale.append(name)
+        except OSError as e:
+            log.warning('no se puede acceder a la biblioteca %s: %s', name, e)
+            stale.append(name)
+    return stale
+
+
+def count_edits(text: str) -> int:
+    """Cuenta invocaciones de las herramientas Edit/Write en el transcript.
+
+    Empareja patrones JSON estructurados de llamadas a herramientas para
+    evitar falsos positivos con prosa normal. Escanea todo el transcript."""
+    return len(re.findall(r'"name":\s*"(?:Edit|Write)"', text))
+
+
+def main() -> None:
+    raw = sys.stdin.read()
+    # Los hooks de Stop escriben su retroalimentación en stderr, no stdout.
+    # El motor lee stderr como mensaje de respuesta del hook.
+    # NO reenviar el JSON crudo a stdout — pisaría el motivo del bloqueo.
+
+    # Resolver el transcript: el evento Stop entrega por stdin un JSON con
+    # transcript_path (contrato de hooks de Theus); se acepta también texto
+    # crudo como degradación.
+    transcript = raw
+    try:
+        payload = json.loads(raw)
+        if isinstance(payload, dict) and 'transcript_path' in payload:
+            tp = os.path.expanduser(payload['transcript_path'])
+            if os.path.exists(tp):
+                with open(tp, 'r', encoding='utf-8') as f:
+                    transcript = f.read()
+            else:
+                log.warning('transcript_path %s no encontrado, se usa stdin crudo', tp)
+    except (json.JSONDecodeError, TypeError, OSError):
+        pass
+
+    # 1. Verificación de disco — tres niveles: recordatorio / aviso / bloqueo
+    disk_free = check_disk()
+    if disk_free is not None:
+        if disk_free < DISK_CRIT_GB:
+            log.warning('Bloqueado: espacio en disco en %dGB (<%dGB). Libera espacio antes de continuar.',
+                        disk_free, DISK_CRIT_GB)
+            sys.exit(2)
+        if disk_free < DISK_WARN_GB:
+            log.warning('AVISO: espacio en disco en %dGB (<%dGB)', disk_free, DISK_WARN_GB)
+        elif disk_free < DISK_REMIND_GB:
+            log.info('Recordatorio: espacio en disco en %dGB (<%dGB)', disk_free, DISK_REMIND_GB)
+
+    # 2. Sesión corta — omitir el resto de verificaciones
+    if len(transcript) < MIN_CHARS:
+        sys.exit(0)
+
+    tail = transcript[-8000:]
+
+    # 3. Detección de patrones de racionalización
+    hits = []
+    for p in RATIONALIZE:
+        m = re.search(p, tail, re.IGNORECASE)
+        if m:
+            hits.append(m.group(0)[:80])
+    if hits:
+        log.warning('puerta-entrega: racionalización detectada — %s', hits)
+
+    # 4. Verificación de captura de aprendizaje
+    mem_dir = get_project_memory_dir()
+    edit_count = count_edits(transcript)
+    is_complex = edit_count >= COMPLEX_THRESHOLD
+
+    if mem_dir:
+        stale = check_stale_libs(mem_dir)
+    else:
+        # Sin directorio de memoria — instalación incompleta.
+        # Avisar pero NO bloquear: bloquear aquí atasca a usuarios nuevos
+        # que aún no crearon el directorio de memoria.
+        if is_complex:
+            log.warning('No hay directorio de memoria del proyecto — no se puede verificar la captura de aprendizaje.')
+            log.warning('Crea memory/ según el SKILL.md de puerta-de-entrega para activar la puerta.')
+        stale = []
+
+    parts = []
+    if is_complex:
+        status_icons = ['X' if s in stale else 'O' for s in LIBS]
+        parts.append(
+            f'\n  Tarea compleja ({edit_count} ediciones). '
+            f'Estado: [{"][".join(f"{k}:{v}" for k, v in zip(LIBS.keys(), status_icons))}]'
+        )
+    if stale:
+        parts.append(f'  Sin actualizar ({len(stale)}): {", ".join(stale)}')
+
+    if parts:
+        log.warning('\n'.join(parts))
+
+    # 5. Bloquear si una tarea compleja terminó sin captura de aprendizaje
+    if is_complex:
+        if len(stale) >= 3:
+            log.warning('Bloqueado: tarea compleja con >=3 bibliotecas de aprendizaje sin actualizar.')
+            log.warning(f'Sin actualizar: {", ".join(stale)}. Actualízalas antes de finalizar.')
+            sys.exit(2)
+        if 'growth-log' in stale:
+            log.warning('Bloqueado: hubo cambios de código pero sin actualizar growth-log.')
+            log.warning('Escribe en growth-log antes de finalizar (aunque sea "sin aprendizajes nuevos").')
+            sys.exit(2)
+
+    sys.exit(0)
+
+
+if __name__ == '__main__':
+    main()

package/vendor/theus-arsenal/skills/pulir-interfaces/SKILL.md

@@ -0,0 +1,126 @@
+---
+name: pulir-interfaces
+description: Aplica detalles concretos de ingeniería de diseño que hacen que las interfaces se sientan pulidas. Úsala al revisar o mejorar espaciado, tipografía, bordes, sombras, movimiento, áreas de toque, iconos, ajuste de texto y estados de interacción en la UI.
+---
+
+# Pulir interfaces
+
+Usa esta skill para los pequeños detalles de ingeniería de diseño que, acumulados, producen una interfaz más pulida.
+
+## Cuándo usarla
+
+- El usuario dice que la UI se siente rara, plana, genérica, apretada, saltarina o sin terminar.
+- Estás construyendo controles, tarjetas, listas, dashboards, navegación, formularios o barras de herramientas.
+- Un componente necesita estados de hover, active, focus, entrada, salida, carga o vacío.
+- Una revisión de frontend necesita recomendaciones concretas de antes/después.
+
+## Principios fundamentales
+
+### Radio concéntrico
+
+Para superficies redondeadas anidadas y cercanas:
+
+```text
+radio exterior = radio interior + padding
+```
+
+Si el padding es grande, trata las capas como superficies separadas en lugar de forzar la fórmula. Lo que importa es la coherencia óptica, no la adoración de la fórmula.
+
+### Alineación óptica
+
+El centrado geométrico no siempre es el centrado visual. Los botones de icono, los triángulos de reproducción, las flechas, las estrellas y los iconos asimétricos suelen necesitar un pequeño desplazamiento. Corrige el SVG cuando sea posible; si no, ajusta con un cambio de margen o padding a nivel de píxel.
+
+### Sombras y bordes
+
+Usa bordes para la separación y los anillos de focus. Usa sombras en capas cuando una tarjeta, un botón, un dropdown o un popover necesite profundidad. Las sombras deben ser transparentes y lo bastante sutiles para funcionar sobre distintos fondos.
+
+### Ajuste de texto
+
+- Usa `text-wrap: balance` en encabezados y títulos cortos.
+- Usa `text-wrap: pretty` en texto de cuerpo corto a mediano, leyendas, descripciones y elementos de lista.
+- Evita ambos en prosa larga, código y contenido preformateado.
+- Usa `font-variant-numeric: tabular-nums` para contadores, temporizadores, precios, tablas y otros números que se actualizan.
+
+### Suavizado de fuentes
+
+En macOS, aplica suavizado antialiased en el layout raíz cuando el proyecto no lo haga ya:
+
+```css
+html {
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+}
+```
+
+### Contornos de imágenes
+
+Las imágenes suelen necesitar un contorno interior sutil para que sus bordes no se difuminen con la superficie.
+
+```css
+img {
+  outline: 1px solid rgba(0, 0, 0, 0.1);
+  outline-offset: -1px;
+}
+
+@media (prefers-color-scheme: dark) {
+  img {
+    outline-color: rgba(255, 255, 255, 0.1);
+  }
+}
+```
+
+Usa contornos con alfa en negro o blanco neutro. No tiñas los contornos de imágenes con la paleta de la marca.
+
+### Movimiento
+
+Usa transiciones CSS para los cambios de estado interactivos, porque pueden reencaminarse cuando el usuario cambia de intención a mitad del movimiento. Reserva los keyframes para entradas escalonadas de un solo disparo o secuencias de carga.
+
+Buenos valores por defecto para el movimiento:
+
+- Entrada: combina opacidad, un `translateY` pequeño y, opcionalmente, blur.
+- Salida: más corta y discreta que la entrada, normalmente 150 ms.
+- Pulsación: `scale(0.96)` para botones táctiles, con una forma de desactivarlo cuando el movimiento distrae.
+- Cambio de iconos: fundido cruzado con opacidad, escala y blur en lugar de alternar la visibilidad de forma instantánea.
+
+### Alcance de las transiciones
+
+Nunca uses `transition: all`. Especifica las propiedades que cambian:
+
+```css
+.button {
+  transition-property: transform, background-color, box-shadow;
+  transition-duration: 150ms;
+  transition-timing-function: ease-out;
+}
+```
+
+Usa `will-change` solo para tartamudeos en el primer frame sobre propiedades amigables con el compositor como `transform`, `opacity` y `filter`. Nunca uses `will-change: all`.
+
+### Áreas de toque
+
+Los controles interactivos deben tener un área de toque de al menos 40x40 px, idealmente 44x44 px cuando el layout lo permite. Amplíala con un pseudoelemento cuando el icono visible sea más pequeño, pero no dejes que las áreas ampliadas se solapen.
+
+## Salida de la revisión
+
+Al revisar una pasada de pulido de UI, reporta los cambios concretos en filas de antes/después:
+
+| Principio | Antes | Después |
+| --- | --- | --- |
+| Radio concéntrico | Mismo radio en padre e hijo | El radio del padre tiene en cuenta el padding |
+| Números tabulares | El contador se desplaza al cambiar los dígitos | El contador usa `tabular-nums` |
+| Alcance de transición | `transition: all` | Propiedades de transición explícitas |
+
+Incluye rutas de archivos y propiedades cuando no sean obvias a partir de los fragmentos. Omite los principios que revisaste pero no cambiaste.
+
+## Checklist
+
+- Los elementos redondeados anidados son ópticamente coherentes.
+- Los iconos están centrados visualmente.
+- Botones, tarjetas y popovers usan bordes o sombras por la razón correcta.
+- Los encabezados y textos cortos evitan cortes de línea incómodos.
+- Los números dinámicos usan numerales tabulares.
+- Las imágenes tienen contornos neutros donde hace falta.
+- Las animaciones de entrada y salida están separadas, son sutiles e interrumpibles cuando corresponde.
+- Los botones tienen estados activos táctiles sin movimiento exagerado.
+- No existen `transition: all` ni `will-change: all`.
+- Los controles pequeños conservan áreas de toque usables.

package/vendor/theus-arsenal/skills/qa-navegador/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: qa-navegador
+description: Usa esta skill para automatizar pruebas visuales y verificación de interacciones de UI mediante automatización de navegador después de desplegar funcionalidades.
+---
+
+# QA de navegador — Pruebas visuales e interacción automatizadas
+
+## Cuándo usarla
+
+- Después de desplegar una funcionalidad a staging/preview
+- Cuando necesitas verificar el comportamiento de la UI en varias páginas
+- Antes de lanzar — confirmar que layouts, formularios e interacciones realmente funcionan
+- Al revisar PR que tocan código de frontend
+- Auditorías de accesibilidad y pruebas responsivas
+
+## Cómo funciona
+
+Usa el MCP de automatización de navegador (el navegador integrado de Theus, Playwright o Puppeteer) para interactuar con páginas en vivo como un usuario real.
+
+### Seguridad primero — radio de impacto (por defecto, solo lectura)
+
+El QA de navegador ejecuta autenticación real y recorridos reales de usuario, así que trata el radio de impacto de forma explícita.
+Por defecto opera en **solo lectura**: nunca ejecutes un recorrido **mutante** (checkout, pago, borrado,
+actualización masiva) contra una URL de producción — exige un opt-in explícito **y** una URL de
+staging/preview. Usa **credenciales de prueba** sembradas, nunca inicios de sesión reales de producción, y **redacta**
+credenciales/tokens/PII antes de guardar cualquier captura de pantalla.
+
+### Fase 1: Smoke test
+```
+1. Navegar a la URL objetivo
+2. Revisar errores de consola (filtrar ruido: analítica, terceros)
+3. Verificar que no haya 4xx/5xx en las peticiones de red
+4. Captura de pantalla del contenido sobre el pliegue en viewport de escritorio + móvil
+5. Revisar Core Web Vitals: LCP < 2.5s, CLS < 0.1, INP < 200ms
+   (INP reemplazó a FID en marzo de 2024; umbrales según web.dev)
+```
+
+### Fase 2: Prueba de interacción
+```
+1. Hacer clic en cada enlace de navegación — verificar que no haya enlaces muertos
+2. Enviar formularios con datos válidos — verificar el estado de éxito
+3. Enviar formularios con datos inválidos — verificar el estado de error
+4. Probar el flujo de autenticación: login → página protegida → logout (solo credenciales de prueba, nunca producción)
+5. Probar los recorridos críticos de usuario (checkout, onboarding, búsqueda)
+   — solo lectura por defecto; ejercita recorridos mutantes solo contra staging
+     con opt-in explícito (ver "Seguridad primero" arriba)
+```
+
+### Fase 3: Regresión visual
+```
+1. Capturar las páginas clave en 3 breakpoints (375px, 768px, 1440px)
+2. Comparar contra las capturas base versionadas
+   — sin línea base ⇒ reportar NO CONCLUYENTE, nunca un PASS silencioso
+3. Marcar desplazamientos de layout > 5px, elementos faltantes, desbordes
+4. Revisar el modo oscuro si aplica
+```
+
+### Fase 4: Accesibilidad
+```
+1. Ejecutar axe-core o equivalente en cada página
+2. Marcar violaciones de WCAG 2.2 AA (contraste, etiquetas, orden de foco)
+3. Verificar que la navegación por teclado funcione de extremo a extremo
+4. Revisar los landmarks para lectores de pantalla
+```
+
+> Nota: axe-core cubre automáticamente entre el 30 y el 40 % de WCAG. Una ejecución limpia es **necesaria,
+> no suficiente** — la navegación por teclado, el orden de foco y una pasada con lector de pantalla siguen requiriendo
+> revisión manual. No reportes "accesible" solo a partir de una pasada automatizada.
+
+## Formato de salida
+
+```markdown
+## Reporte de QA — [URL] — [timestamp]
+
+### Smoke test
+- Errores de consola: 0 críticos, 2 advertencias (ruido de analítica)
+- Red: todo 200/304, sin fallos
+- Core Web Vitals: LCP 1.2s ✓, CLS 0.02 ✓, INP 89ms ✓
+
+### Interacciones
+- [✓] Enlaces de navegación: 12/12 funcionando
+- [✗] Formulario de contacto: falta el estado de error para email inválido
+- [✓] Flujo de autenticación: login/logout funcionando
+
+### Visual
+- [✗] La sección hero se desborda en viewport de 375px
+- [✓] Modo oscuro: todas las páginas consistentes
+
+### Accesibilidad
+- 2 violaciones AA: falta texto alternativo en la imagen del hero, contraste bajo en los enlaces del footer
+
+### Veredicto: LANZAR CON CORRECCIONES (2 incidencias, 0 bloqueantes)
+# veredicto ∈ LANZAR / LANZAR CON CORRECCIONES / NO LANZAR; usa NO CONCLUYENTE si no hay línea base visual
+```
+
+## Integración
+
+Funciona con cualquier MCP de navegador:
+- Las herramientas MCP de navegador de Theus (preferidas — usan tu navegador real)
+- Playwright vía `mcp__browserbase__*`
+- Scripts directos de Puppeteer
+
+Combínala con la skill `vigilancia-canary` para monitoreo posdespliegue.

package/vendor/theus-arsenal/skills/ranking-grafo-social/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: ranking-grafo-social
+description: Ranking ponderado de grafo social para descubrir intros cálidas, puntuar puentes y detectar brechas de red en X y LinkedIn. Úsala cuando el usuario quiera el motor de ranking de grafo en sí, no el flujo completo de outreach o mantenimiento de red construido encima.
+---
+
+# Ranking de grafo social
+
+Capa canónica de ranking ponderado de grafo para outreach consciente de la red.
+
+Úsala cuando el usuario necesite:
+
+- rankear mutuals o conexiones existentes por valor de introducción
+- mapear rutas cálidas hacia una lista de objetivos
+- medir el valor de puente en conexiones de primer y segundo orden
+- decidir qué objetivos merecen una intro cálida frente a outreach directo en frío
+- entender la matemática del grafo por separado de `inteligencia-leads` u `optimizador-conexiones`
+
+## Cuándo usarla de forma independiente
+
+Elige esta skill cuando el usuario quiera principalmente el motor de ranking:
+
+- "¿quién en mi red está mejor posicionado para presentarme?"
+- "rankea mis mutuals según quién puede llevarme a estas personas"
+- "mapea mi grafo contra este ICP"
+- "muéstrame la matemática de los puentes"
+
+No la uses sola cuando el usuario en realidad quiera:
+
+- generación completa de leads y secuencias de outbound -> usa `inteligencia-leads`
+- podar, rebalancear y hacer crecer la red -> usa `optimizador-conexiones`
+
+## Entradas
+
+Recopila o infiere:
+
+- personas objetivo, empresas o definición de ICP
+- el grafo actual del usuario en X, LinkedIn o ambos
+- prioridades de ponderación como rol, industria, geografía y capacidad de respuesta
+- profundidad de recorrido y tolerancia al decaimiento
+
+## Modelo central
+
+Dado:
+
+- `T` = conjunto ponderado de objetivos
+- `M` = tus mutuals / conexiones directas actuales
+- `d(m, t)` = distancia mínima en saltos del mutual `m` al objetivo `t`
+- `w(t)` = peso del objetivo según la puntuación de señales
+
+Puntuación base de puente:
+
+```text
+B(m) = Σ_{t ∈ T} w(t) · λ^(d(m,t) - 1)
+```
+
+Donde:
+
+- `λ` es el factor de decaimiento, normalmente `0.5`
+- una ruta directa aporta el valor completo
+- cada salto extra reduce la contribución a la mitad
+
+Expansión de segundo orden:
+
+```text
+B_ext(m) = B(m) + α · Σ_{m' ∈ N(m) \\ M} Σ_{t ∈ T} w(t) · λ^(d(m',t))
+```
+
+Donde:
+
+- `N(m) \\ M` es el conjunto de personas que el mutual conoce y tú no
+- `α` descuenta el alcance de segundo orden, normalmente `0.3`
+
+Ranking final ajustado por respuesta:
+
+```text
+R(m) = B_ext(m) · (1 + β · engagement(m))
+```
+
+Donde:
+
+- `engagement(m)` es la capacidad de respuesta normalizada o la fuerza de la relación
+- `β` es el bono de engagement, normalmente `0.2`
+
+Interpretación:
+
+- Nivel 1: `R(m)` alto y rutas de puente directas -> pedir intros cálidas
+- Nivel 2: `R(m)` medio y rutas de puente de un salto -> pedir intros condicionales
+- Nivel 3: `R(m)` bajo o sin puente viable -> outreach directo o llenar la brecha de red
+
+## Señales de puntuación
+
+Pondera los objetivos antes del recorrido del grafo con lo que importe para el conjunto de prioridades actual:
+
+- alineación de rol o título
+- encaje de empresa o industria
+- actividad actual y recencia
+- relevancia geográfica
+- influencia o alcance
+- probabilidad de respuesta
+
+Pondera los mutuals después del recorrido con:
+
+- número de rutas ponderadas hacia el conjunto de objetivos
+- qué tan directas son esas rutas
+- capacidad de respuesta o historial de interacción previo
+- encaje contextual para hacer la introducción
+
+## Flujo de trabajo
+
+1. Construye el conjunto ponderado de objetivos.
+2. Extrae el grafo del usuario de X, LinkedIn o ambos.
+3. Calcula las puntuaciones de puente directas.
+4. Expande candidatos de segundo orden para los mutuals de mayor valor.
+5. Rankea por `R(m)`.
+6. Devuelve:
+   - las mejores solicitudes de intro cálida
+   - rutas de puente condicionales
+   - brechas del grafo donde no existe ruta cálida
+
+## Forma de la salida
+
+```text
+RANKING DE GRAFO SOCIAL
+=======================
+
+Conjunto de prioridades:
+Plataformas:
+Modelo de decaimiento:
+
+Mejores puentes
+- mutual / conexión
+  puntuación_base:
+  puntuación_extendida:
+  mejores_objetivos:
+  resumen_de_ruta:
+  acción_recomendada:
+
+Rutas condicionales
+- mutual / conexión
+  motivo:
+  costo del salto extra:
+
+Sin ruta cálida
+- objetivo
+  recomendación: outreach directo / llenar brecha del grafo
+```
+
+## Skills relacionadas
+
+- `inteligencia-leads` usa este modelo de ranking dentro del pipeline más amplio de descubrimiento de objetivos y outreach
+- `optimizador-conexiones` usa la misma lógica de puentes al decidir a quién mantener, podar o agregar
+- `voz-de-marca` debe ejecutarse antes de redactar cualquier solicitud de intro u outreach directo
+- `api-x` provee acceso al grafo de X y rutas de ejecución opcionales