@saulwade/swl-ses 2.5.3 → 2.6.0

package/habilidades/doubt-driven-review/SKILL.md

@@ -1,191 +1,207 @@
----
-name: doubt-driven-review
-description: >
-  Adversarial peer review de decisiones técnicas antes de comprometerlas.
-  Cuestiona supuestos, fuerza la articulación de alternativas descartadas y
-  detecta confianza injustificada. Cargar antes de decidir arquitecturas
-  irreversibles, elegir un framework crítico, definir un contrato de API
-  público o aprobar un PR de alto impacto. NO cubre adversarial review de
-  memoria (eso lo hace red-team-swl) ni de seguridad de código (eso lo hace
-  revisor-seguridad-swl) — este skill se especializa en decisiones técnicas
-  con costo de cambio alto.
-version: "1.1.0"
-exclusiones:
-  - "No cargar para revisión de memoria SWL (APRENDIZAJES.md, instintos/) — esa es responsabilidad de red-team-swl."
-  - "No cargar para auditoría de seguridad de código (OWASP, CVEs, inyección) — usar revisor-seguridad-swl."
-  - "No cargar para decisiones reversibles de bajo costo (formato de output, nombre de variable, refactor menor) — el overhead del review no compensa."
-  - "No cargar para code review estándar de PR — eso es revisor-codigo-swl; este skill aplica a decisiones de diseño, no a calidad de código."
----
-
-# Doubt-Driven Review
-
-## Cuándo cargar
-
-- Antes de aprobar un ADR que toma una decisión irreversible.
-- Antes de comprometer un contrato público de API o un schema de BD que afecta integraciones externas.
-- Antes de elegir un framework, librería o patrón con costo de migración alto.
-- Antes de fusionar un PR cuyo blast radius incluye módulos críticos.
-- Cuando el equipo o el agente exhibe **alta confianza con baja evidencia** sobre una decisión técnica.
-
-## Cuándo NO cargar
-
-- Para revisar código por calidad — eso es `revisor-codigo-swl` con `Skill("checklist-calidad")`.
-- Para revisar seguridad — eso es `revisor-seguridad-swl` con `Skill("checklist-seguridad")`.
-- Para validar memoria contra prompt injection o privacidad — eso es `red-team-swl`.
-- Para discutir alcances con el usuario — eso es `Skill("brainstorming")` o `swl:discutir-fase`.
-- Para fixes triviales o decisiones reversibles en menos de 10 minutos.
-
-## Principio
-
-> Una decisión cuya alternativa no se ha articulado, no es una decisión:
-> es una preferencia. Toda decisión técnica con costo de cambio alto debe
-> sobrevivir a un round adversarial antes de comprometerse.
-
-El skill ejecuta un protocolo en 5 pasos. Cada paso produce evidencia en
-texto. La salida del skill NO aprueba ni rechaza — produce un reporte que
-el agente o usuario humano usa para decidir.
-
-## Protocolo
-
-### Paso 1 — Articular la decisión y su irreversibilidad
-
-Pedir explícitamente:
-
-- **Qué se decide**: 1-3 oraciones, sin jerga ambigua.
-- **Qué se descarta**: la decisión opuesta concreta.
-- **Costo de revertir**: estimación en turnos / archivos / horas si en 3 meses se concluye que fue incorrecta.
-
-Si el costo de revertir es < 4 horas y < 5 archivos: la decisión NO es candidata
-a doubt-driven review. Cerrar el skill y proceder.
-
-### Paso 2 — Forzar 3 alternativas descartadas
-
-El agente o usuario debe articular las 3 alternativas más fuertes que NO se eligieron, con:
-
-- Por qué cada una es plausible (≥ 1 razón concreta).
-- Qué tradeoff la hace inferior a la elegida (sin frase genérica como "menos flexible").
-
-Si la persona/agente no puede articular 3 alternativas: **señal de decisión bajo-evidencia**.
-Reportar: "Decisión propuesta sin alternativas articuladas. Riesgo de selección por inercia."
-
-### Paso 3 — Buscar contraevidencia activamente
-
-Para la decisión propuesta:
-
-- Listar 3 escenarios donde la decisión **fallaría** o produciría costos no anticipados.
-- Listar 1 caso histórico (dentro o fuera del proyecto) donde una decisión similar resultó incorrecta.
-- Identificar 1 supuesto de la decisión que NO está validado con evidencia (corre el riesgo de ser falso).
-
-Si los 3 escenarios de falla son improbables Y el supuesto está validado: la decisión gana robustez.
-Si ≥ 1 escenario tiene probabilidad ≥ 30%: documentar el riesgo en el reporte.
-
-### Paso 4 — Detectar confianza injustificada
-
-Patrones a marcar como red flags:
-
-- "Es la mejor práctica" sin citar fuente o caso.
-- "Siempre se hace así" sin verificar el contexto del proyecto actual.
-- "Es lo que recomienda <autoridad>" sin verificar que la recomendación aplica al stack/escala/dominio.
-- "No hay otra opción razonable" cuando el paso 2 ya forzó 3 alternativas.
-- Cita de un blog post o tweet como evidencia única.
-- Argumentos de tipo "todo el mundo lo usa" sin métrica concreta.
-
-Por cada red flag detectado: 1 línea en el reporte con cita textual del argumento.
-
-### Paso 5 — Trigger de reversión
-
-Toda decisión que pase doubt-driven review debe incluir:
-
-- **Trigger de reversión**: condición observable que, de cumplirse, obliga a reabrir la decisión.
-  Ejemplos válidos: "p95 de latencia > 800ms en producción durante 7 días",
-  "≥3 reportes de bugs relacionados con la limitación X en 30 días", "vendor X
-  publica deprecation notice", "costo mensual de infra excede $Y".
-- **Fecha de reevaluación automática**: 6-12 meses desde la fecha de decisión.
-
-Si la decisión NO puede tener trigger observable: es una decisión **basada en preferencia**,
-no en hipótesis falsable. Documentarla como tal en el reporte.
-
-## Formato del reporte
-
-```markdown
-## Doubt-Driven Review — [decisión] — [fecha]
-
-### Decisión articulada
-- Qué se decide: [...]
-- Qué se descarta: [...]
-- Costo de revertir: [estimación]
-
-### Alternativas articuladas
-1. [alt-1]: plausible porque [...]; descartada porque [tradeoff concreto]
-2. [alt-2]: ...
-3. [alt-3]: ...
-
-### Contraevidencia
-- Escenario de falla 1 [prob: alta/media/baja]: [...]
-- Escenario de falla 2 [prob: ...]: [...]
-- Escenario de falla 3 [prob: ...]: [...]
-- Caso histórico relevante: [...]
-- Supuesto sin validar: [...]
-
-### Red flags detectados
-- [línea N: cita textual del argumento débil]
-- [...]
-- (o "Ninguno")
-
-### Trigger de reversión
-- Condición: [observable falsable]
-- Fecha de reevaluación: [YYYY-MM-DD]
-
-### Veredicto
-- ROBUSTA — pasó los 5 pasos sin red flags y con trigger claro
-- ACEPTABLE — pasó con 1-2 red flags documentados y trigger claro
-- BAJO-EVIDENCIA — falla en pasos 2, 4 o 5; reabrir antes de comprometer
-```
-
-## Anti-patrones del skill
-
-- **Auto-revisión**: el agente que tomó la decisión ejecuta el skill sobre sí mismo.
-  Pierde el efecto adversarial. Cargar el skill desde un agente distinto al
-  decisor (ej: `arquitecto-swl` decidió → `revisor-codigo-swl` ejecuta el skill
-  con foco en la decisión).
-- **Trigger inverificable**: "cuando el sistema deje de escalar" no es trigger.
-  Debe ser una métrica observable con valor numérico o evento concreto.
-- **Alternativas de paja**: las 3 alternativas no pueden ser opciones triviales
-  inferiores a propósito. Si las 3 son obviamente peores, el skill perdió su valor
-  — pedir 3 alternativas reales o aceptar que la decisión es bajo-evidencia.
-- **Convertirlo en proceso burocrático**: aplicar doubt-driven a decisiones
-  reversibles es overhead. El paso 1 filtra esto explícitamente.
-
-## Entrada operacional
-
-Este skill tiene dos vías de invocación en el sistema:
-
-1. **`abogado-diablo-swl`** (vía principal) — el agente lo carga en su Fase 0 y
-   ejecuta los 5 pasos añadiendo pre-mortem y dictamen. Punto de entrada del
-   usuario: `/swl:predecir --abogado-diablo`.
-2. **Carga directa** por un agente distinto al decisor (ej: `arquitecto-swl`
-   decidió → otro agente ejecuta el skill sobre la decisión) — válida cuando no
-   se necesita el pre-mortem completo.
-
-## Relación con otras capacidades del sistema
-
-- `abogado-diablo-swl`: el agente que operacionaliza este skill (pre-mortem +
-  dictamen PROCEDER/CON CONDICIONES/NO PROCEDER). Este skill define el protocolo;
-  el agente lo ejecuta con separación decisor/crítico garantizada.
-- `red-team-swl`: cubre adversarial review de **memoria del sistema** (perfil-usuario,
-  instintos, APRENDIZAJES). Doubt-driven cubre **decisiones técnicas**. NO duplicación.
-- `arquitecto-swl`: produce ADRs. Doubt-driven se carga ANTES de aceptar el ADR.
-- `revisor-codigo-swl`: revisa calidad de código ya escrito. Doubt-driven revisa
-  decisiones ANTES de escribir código.
-- `Skill("verificar-trabajo")`: verificación goal-backward del resultado.
-  Doubt-driven es goal-backward del **diseño**, no del resultado.
-
-## Origen
-
-Patrón observado en `temp/agent-skills-main/skills/doubt-driven-development`
-(2026-05-09). Adaptado al sistema swl-ses: en español, con trigger de
-reversión obligatorio (alineado con `reglas/arquitectura.md` § ADRs en estado
-Propuesto), y con relación explícita a `red-team-swl` para evitar duplicar
-funciones que ya existen en el sistema.
-
-Para ejemplos concretos de aplicación, ver [`recursos/EXAMPLES.md`](recursos/EXAMPLES.md).
+---
+name: doubt-driven-review
+description: >
+  Adversarial peer review de decisiones técnicas antes de comprometerlas.
+  Cuestiona supuestos, fuerza la articulación de alternativas descartadas y
+  detecta confianza injustificada. Cargar antes de decidir arquitecturas
+  irreversibles, elegir un framework crítico, definir un contrato de API
+  público o aprobar un PR de alto impacto. NO cubre adversarial review de
+  memoria (eso lo hace red-team-swl) ni de seguridad de código (eso lo hace
+  revisor-seguridad-swl) — este skill se especializa en decisiones técnicas
+  con costo de cambio alto.
+version: "1.2.0"
+exclusiones:
+  - "No cargar para revisión de memoria SWL (APRENDIZAJES.md, instintos/) — esa es responsabilidad de red-team-swl."
+  - "No cargar para auditoría de seguridad de código (OWASP, CVEs, inyección) — usar revisor-seguridad-swl."
+  - "No cargar para decisiones reversibles de bajo costo (formato de output, nombre de variable, refactor menor) — el overhead del review no compensa."
+  - "No cargar para code review estándar de PR — eso es revisor-codigo-swl; este skill aplica a decisiones de diseño, no a calidad de código."
+---
+
+# Doubt-Driven Review
+
+## Cuándo cargar
+
+- Antes de aprobar un ADR que toma una decisión irreversible.
+- Antes de comprometer un contrato público de API o un schema de BD que afecta integraciones externas.
+- Antes de elegir un framework, librería o patrón con costo de migración alto.
+- Antes de fusionar un PR cuyo blast radius incluye módulos críticos.
+- Cuando el equipo o el agente exhibe **alta confianza con baja evidencia** sobre una decisión técnica.
+
+## Cuándo NO cargar
+
+- Para revisar código por calidad — eso es `revisor-codigo-swl` con `Skill("checklist-calidad")`.
+- Para revisar seguridad — eso es `revisor-seguridad-swl` con `Skill("checklist-seguridad")`.
+- Para validar memoria contra prompt injection o privacidad — eso es `red-team-swl`.
+- Para discutir alcances con el usuario — eso es `Skill("brainstorming")` o `swl:discutir-fase`.
+- Para fixes triviales o decisiones reversibles en menos de 10 minutos.
+
+## Principio
+
+> Una decisión cuya alternativa no se ha articulado, no es una decisión:
+> es una preferencia. Toda decisión técnica con costo de cambio alto debe
+> sobrevivir a un round adversarial antes de comprometerse.
+
+El skill ejecuta un protocolo en 5 pasos. Cada paso produce evidencia en
+texto. La salida del skill NO aprueba ni rechaza — produce un reporte que
+el agente o usuario humano usa para decidir.
+
+## Protocolo
+
+### Paso 1 — Articular la decisión y su irreversibilidad
+
+Pedir explícitamente:
+
+- **Qué se decide**: 1-3 oraciones, sin jerga ambigua.
+- **Qué se descarta**: la decisión opuesta concreta.
+- **Costo de revertir**: estimación en turnos / archivos / horas si en 3 meses se concluye que fue incorrecta.
+
+Si el costo de revertir es < 4 horas y < 5 archivos: la decisión NO es candidata
+a doubt-driven review. Cerrar el skill y proceder.
+
+### Paso 2 — Forzar 3 alternativas descartadas
+
+El agente o usuario debe articular las 3 alternativas más fuertes que NO se eligieron, con:
+
+- Por qué cada una es plausible (≥ 1 razón concreta).
+- Qué tradeoff la hace inferior a la elegida (sin frase genérica como "menos flexible").
+
+Si la persona/agente no puede articular 3 alternativas: **señal de decisión bajo-evidencia**.
+Reportar: "Decisión propuesta sin alternativas articuladas. Riesgo de selección por inercia."
+
+### Paso 3 — Buscar contraevidencia activamente
+
+Para la decisión propuesta:
+
+- Listar 3 escenarios donde la decisión **fallaría** o produciría costos no anticipados.
+- Listar 1 caso histórico (dentro o fuera del proyecto) donde una decisión similar resultó incorrecta.
+- Identificar 1 supuesto de la decisión que NO está validado con evidencia (corre el riesgo de ser falso).
+
+Si los 3 escenarios de falla son improbables Y el supuesto está validado: la decisión gana robustez.
+Si ≥ 1 escenario tiene probabilidad ≥ 30%: documentar el riesgo en el reporte.
+
+### Paso 4 — Detectar confianza injustificada
+
+Patrones a marcar como red flags:
+
+- "Es la mejor práctica" sin citar fuente o caso.
+- "Siempre se hace así" sin verificar el contexto del proyecto actual.
+- "Es lo que recomienda <autoridad>" sin verificar que la recomendación aplica al stack/escala/dominio.
+- "No hay otra opción razonable" cuando el paso 2 ya forzó 3 alternativas.
+- Cita de un blog post o tweet como evidencia única.
+- Argumentos de tipo "todo el mundo lo usa" sin métrica concreta.
+
+Por cada red flag detectado: 1 línea en el reporte con cita textual del argumento.
+
+### Paso 5 — Trigger de reversión
+
+Toda decisión que pase doubt-driven review debe incluir:
+
+- **Trigger de reversión**: condición observable que, de cumplirse, obliga a reabrir la decisión.
+  Ejemplos válidos: "p95 de latencia > 800ms en producción durante 7 días",
+  "≥3 reportes de bugs relacionados con la limitación X en 30 días", "vendor X
+  publica deprecation notice", "costo mensual de infra excede $Y".
+- **Fecha de reevaluación automática**: 6-12 meses desde la fecha de decisión.
+
+Si la decisión NO puede tener trigger observable: es una decisión **basada en preferencia**,
+no en hipótesis falsable. Documentarla como tal en el reporte.
+
+## Formato del reporte
+
+```markdown
+## Doubt-Driven Review — [decisión] — [fecha]
+
+### Decisión articulada
+- Qué se decide: [...]
+- Qué se descarta: [...]
+- Costo de revertir: [estimación]
+
+### Alternativas articuladas
+1. [alt-1]: plausible porque [...]; descartada porque [tradeoff concreto]
+2. [alt-2]: ...
+3. [alt-3]: ...
+
+### Contraevidencia
+- Escenario de falla 1 [prob: alta/media/baja]: [...]
+- Escenario de falla 2 [prob: ...]: [...]
+- Escenario de falla 3 [prob: ...]: [...]
+- Caso histórico relevante: [...]
+- Supuesto sin validar: [...]
+
+### Red flags detectados
+- [línea N: cita textual del argumento débil]
+- [...]
+- (o "Ninguno")
+
+### Trigger de reversión
+- Condición: [observable falsable]
+- Fecha de reevaluación: [YYYY-MM-DD]
+
+### Veredicto
+- ROBUSTA — pasó los 5 pasos sin red flags y con trigger claro
+- ACEPTABLE — pasó con 1-2 red flags documentados y trigger claro
+- BAJO-EVIDENCIA — falla en pasos 2, 4 o 5; reabrir antes de comprometer
+```
+
+## Patrón validado: dictamen adversarial convertido en gates de activación
+
+[Caso real 2026-07-10, ADR-0042] La forma de mayor valor del veredicto
+adversarial no es el veto sino la **conversión de cada condición del dictamen
+en un gate verificable del propio diseño**: el abogado del diablo (verificando
+contra el repo con archivo:línea, no opinando) produjo 3 pre-mortems plausibles
+(canary sin señal estadística, el-sistema-escribe-su-propio-examen, headless
+que compite con la sesión del usuario) y 7 condiciones; en lugar de rechazar
+el plan, las condiciones se integraron como gates de activación escalonados
+(G-B…G-E) con criterios observables y triggers de reversión. Resultado: la
+decisión del usuario se respeta, el riesgo queda contenido POR CONSTRUCCIÓN y
+el dictamen deja de ser un documento — se vuelve arquitectura. Requisitos del
+patrón: el crítico verifica afirmaciones contra el código real (no memoria),
+cada condición tiene verificación binaria, y los gates viven en el ADR con
+fecha de reevaluación.
+
+## Anti-patrones del skill
+
+- **Auto-revisión**: el agente que tomó la decisión ejecuta el skill sobre sí mismo.
+  Pierde el efecto adversarial. Cargar el skill desde un agente distinto al
+  decisor (ej: `arquitecto-swl` decidió → `revisor-codigo-swl` ejecuta el skill
+  con foco en la decisión).
+- **Trigger inverificable**: "cuando el sistema deje de escalar" no es trigger.
+  Debe ser una métrica observable con valor numérico o evento concreto.
+- **Alternativas de paja**: las 3 alternativas no pueden ser opciones triviales
+  inferiores a propósito. Si las 3 son obviamente peores, el skill perdió su valor
+  — pedir 3 alternativas reales o aceptar que la decisión es bajo-evidencia.
+- **Convertirlo en proceso burocrático**: aplicar doubt-driven a decisiones
+  reversibles es overhead. El paso 1 filtra esto explícitamente.
+
+## Entrada operacional
+
+Este skill tiene dos vías de invocación en el sistema:
+
+1. **`abogado-diablo-swl`** (vía principal) — el agente lo carga en su Fase 0 y
+   ejecuta los 5 pasos añadiendo pre-mortem y dictamen. Punto de entrada del
+   usuario: `/swl:predecir --abogado-diablo`.
+2. **Carga directa** por un agente distinto al decisor (ej: `arquitecto-swl`
+   decidió → otro agente ejecuta el skill sobre la decisión) — válida cuando no
+   se necesita el pre-mortem completo.
+
+## Relación con otras capacidades del sistema
+
+- `abogado-diablo-swl`: el agente que operacionaliza este skill (pre-mortem +
+  dictamen PROCEDER/CON CONDICIONES/NO PROCEDER). Este skill define el protocolo;
+  el agente lo ejecuta con separación decisor/crítico garantizada.
+- `red-team-swl`: cubre adversarial review de **memoria del sistema** (perfil-usuario,
+  instintos, APRENDIZAJES). Doubt-driven cubre **decisiones técnicas**. NO duplicación.
+- `arquitecto-swl`: produce ADRs. Doubt-driven se carga ANTES de aceptar el ADR.
+- `revisor-codigo-swl`: revisa calidad de código ya escrito. Doubt-driven revisa
+  decisiones ANTES de escribir código.
+- `Skill("verificar-trabajo")`: verificación goal-backward del resultado.
+  Doubt-driven es goal-backward del **diseño**, no del resultado.
+
+## Origen
+
+Patrón observado en `temp/agent-skills-main/skills/doubt-driven-development`
+(2026-05-09). Adaptado al sistema swl-ses: en español, con trigger de
+reversión obligatorio (alineado con `reglas/arquitectura.md` § ADRs en estado
+Propuesto), y con relación explícita a `red-team-swl` para evitar duplicar
+funciones que ya existen en el sistema.
+
+Para ejemplos concretos de aplicación, ver [`recursos/EXAMPLES.md`](recursos/EXAMPLES.md).

package/habilidades/drift-detection/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: drift-detection
-version: 1.0.0
+version: 1.0.1
 herramientasPermitidas: [Read]
 description: "Detección de drift de métricas de agentes/skills via ventana deslizante (7d) vs baseline (4 semanas). Integrado al operador Reflect del ciclo AGP."
 exclusiones:
@@ -38,6 +38,11 @@ Adaptado de `runDriftCheck`/`getDriftTimeline` en mission-control-main (MIT).
 
 ## Exports del módulo
 
+Los bloques `js` de este skill documentan la API con el layout del repo madre
+(`scripts/lib/`, `hooks/lib/`); en instalaciones destino los módulos viven
+aplanados junto a los hooks instalados. Referencia de API, no comandos a
+ejecutar tal cual en proyectos consumidores.
+
 ```js
 const { detectarDrift, generarLineaTemporal } = require('./scripts/lib/drift-detector');
 ```

package/habilidades/ejecutar-fase/SKILL.md

@@ -47,7 +47,7 @@ Antes de la primera tarea Y al inicio de cada slice, verificar que el PLAN no
 fue mutado tras su aprobación:
 
 ```bash
-node -e "const {verificarPlan}=require('./scripts/lib/plan-lock'); console.log(JSON.stringify(verificarPlan('.planning/fases/0N-PLAN.md')))"
+swl-ses verificar-plan --fase=0N
 ```
 
 - `modo: "firmado"` → continuar.
@@ -84,13 +84,13 @@ Tras commitear una tarea (y al cerrar la fase), evaluar las adyacencias de riesg
 del diff y anexar propuestas SOLO si hay señal. Propone, nunca bloquea ni ejecuta:
 
 ```bash
-node hooks/lib/propose-step.js --rango=HEAD~1..HEAD
+swl-ses propose-step --rango=HEAD~1..HEAD
 ```
 
 Si imprime un anexo, agregarlo al reporte de la tarea (y al RESUMEN.md al cerrar
 la fase). Si no imprime nada, silencio — no agregar sección vacía. Opt-out con
 `SWL_PROPOSE=0`. Antes de una acción autónoma de clase `cambio_reversible`,
-registrar el auto-checkpoint: `node hooks/lib/autonomia.js --accion "<acción>"`.
+registrar el auto-checkpoint: `swl-ses autonomia --accion="<acción>"`.
 Detalle en el fragmento `agentes/_propose-step.md`.
 
 ### Protocolo de retry con backoff exponencial
@@ -325,7 +325,7 @@ sigue el ciclo con evidencia.
 Al iniciar la primera tarea de código de la fase, abrir la corrida de evidencia:
 
 ```bash
-node -e "const lt=require('./hooks/lib/loop-telemetry');const r=lt.iniciarCorrida({tipo:'tdd',direccion:'lower_is_better',config:{fase:'0N',tarea:'T-NN'}});console.log(r.dir)"
+swl-ses loop-telemetry iniciar --tipo=tdd --direccion=lower_is_better --config='{"fase":"0N","tarea":"T-NN"}'
 ```
 
 **RED**: Escribir el test que describe el comportamiento esperado.
@@ -334,14 +334,14 @@ de sintaxis o configuración. **Registrar la evidencia** (métrica = tests falla
 descripción = fallo exacto):
 
 ```bash
-node -e "const lt=require('./hooks/lib/loop-telemetry');lt.registrarIteracion('<dir>',{iteracion:0,metrica:<N_fallan>,delta:0,estado:'baseline',descripcion:'RED T-NN: <fallo exacto del runner>'})"
+swl-ses loop-telemetry registrar --dir=<dir> --iteracion=0 --metrica=<N_fallan> --delta=0 --estado=baseline --descripcion="RED T-NN: <fallo exacto del runner>"
 ```
 
 **GREEN**: Escribir la implementación mínima que hace pasar el test.
 "Mínima" significa: no implementar más de lo que el test exige. Registrar:
 
 ```bash
-node -e "const lt=require('./hooks/lib/loop-telemetry');lt.registrarIteracion('<dir>',{iteracion:1,metrica:0,delta:-<N>,estado:'keep',descripcion:'GREEN T-NN: suite verde'})"
+swl-ses loop-telemetry registrar --dir=<dir> --iteracion=1 --metrica=0 --delta=-<N> --estado=keep --descripcion="GREEN T-NN: suite verde"
 ```
 
 **REFACTOR**: Limpiar el código sin cambiar el comportamiento.

package/habilidades/eval-framework/SKILL.md

@@ -47,6 +47,11 @@ evolvable: true  # default para skill estandar
 
 ## Uso típico desde agente o test
 
+Los bloques `js` de esta sección documentan la API de los módulos con el
+layout del repo madre (`scripts/lib/`); en instalaciones destino viven
+aplanados junto a los hooks instalados. Para ejecución en proyectos
+consumidores usar el CLI (`swl-ses run-eval`, sección final).
+
 ### Validar output contra schema
 
 ```js
@@ -137,12 +142,12 @@ cat > /tmp/eval.json << 'EOF'
 }
 EOF
 
-# Ejecutar
-node scripts/run-eval.js /tmp/eval.json
+# Ejecutar (CLI cross-scope; en el repo madre equivale a scripts/run-eval.js)
+swl-ses run-eval /tmp/eval.json
 # Exit 0 si valid, 1 si inválido. Persiste métricas automáticamente.
 
 # Reconstruir agregado desde JSONL si se corrompe
-node scripts/run-eval.js --rebuild-aggregate
+swl-ses run-eval --rebuild-aggregate
 ```
 
 ---