@saulwade/swl-ses 1.8.0 → 1.9.0

package/CLAUDE.md

@@ -1,4 +1,4 @@
-# CLAUDE.md — @saulwade/swl-ses v1.8.0
+# CLAUDE.md — @saulwade/swl-ses v1.9.0
 
 ## Reglas de máxima prioridad (aplican SIEMPRE, sin excepción)
 
@@ -95,7 +95,7 @@ NUNCA asumir, sugerir como hecho consumado, ni escribir en ADRs/manifiestos/CHAN
 ## Qué es este repositorio
 
 Sistema de ingeniería de software auto-evolutivo multi-runtime polyglot (SDLC completo).
-11 lenguajes, 7 runtimes (Claude, OpenClaude, OpenCode, Gemini, Cursor, Codex, Copilot), 61 agentes, 178 skills, 44 comandos, 71 reglas, 44 hooks.
+11 lenguajes, 7 runtimes (Claude, OpenClaude, OpenCode, Gemini, Cursor, Codex, Copilot), 61 agentes, 181 skills, 45 comandos, 71 reglas, 45 hooks.
 
 ## Estructura del repositorio
 
@@ -115,7 +115,7 @@ scripts/       bin/            _userland/      .claude/        .planning/
 
 ## Comandos del sistema (/swl:*)
 
-Catálogo completo de 44 comandos `/swl:*` en `@COMANDOS.md`. Atajos mentales por categoría:
+Catálogo completo de 45 comandos `/swl:*` en `@COMANDOS.md`. Atajos mentales por categoría:
 
 - **Ciclo GSD por fase**: `discutir-fase` → `planear-fase` → `ejecutar-fase` → `verificar` (con discovery routing, modo iterativo `--iterative` y `--until-converge`).
 - **Anti-context-rot**: `checkpoint`, `compactar`.

package/README.md

@@ -1,4 +1,4 @@
-# swl-ses v1.8.0
+# swl-ses v1.9.0
 
 > El paquete anterior `@saulwadeleon/swl-software-engineering-system` está deprecado. Migrar a `@saulwade/swl-ses` (npmjs.org canónico) o `@saul-wade/swl-ses` (mirror en GitHub Packages) — el CLI `swl-ses` no cambia.
 
@@ -195,7 +195,7 @@ claude
 | `mobile` | Android + iOS + React Native/Flutter + UX |
 | `devops` | CI/CD + cloud + observabilidad + releases + seguridad |
 | `polyglot` | Todos los lenguajes: 11 lenguajes + revisores + build resolvers |
-| `completo` | Todo: 61 agentes + 178 habilidades + 44 comandos + 71 reglas + 44 hooks |
+| `completo` | Todo: 61 agentes + 181 habilidades + 45 comandos + 71 reglas + 45 hooks |
 
 ### Targets soportados
 
@@ -498,9 +498,9 @@ swl-ses/
   manifiestos/              # Perfiles y módulos de instalación
   agentes/                  # 60 agentes especializados
   habilidades/              # 160 habilidades modulares
-  comandos/swl/             # 44 comandos slash
+  comandos/swl/             # 45 comandos slash
   reglas/                   # 28 reglas base + 40 por lenguaje
-  hooks/                    # 44 hooks + 66 librerías en hooks/lib/
+  hooks/                    # 45 hooks + 69 librerías en hooks/lib/
   schemas/                  # 15 JSON Schemas
   contextos/                # 3 modos de desarrollo
   instintos/                # Instintos YAML con confianza
@@ -576,4 +576,4 @@ npm run field-report   # Reporte de uso real de skills y agentes
 
 ## Licencia
 
-MIT
+MIT

package/agentes/orquestador-swl.md

@@ -15,7 +15,12 @@ modeloAlterno: claude-haiku-4-5-20251001
 ventanaContexto: 200k
 permissionMode: plan
 color: white
-version: 1.2.0
+version: 1.3.0
+evolved: true
+evolved-from: "1.2.0"
+evolved-at: "2026-06-04"
+evolved-by: "evolucionar"
+evolved-note: "PE-005 sección 5 'Sub-agente background falla con API Error: Usage credits required for 1M context — verificar filesystem antes de re-intentar' + PE-006 sección 6 'Cuándo NO delegar a sub-agentes Opus 4.7 1M context'. Aprobación humana explícita pese a evolvable=false (función sistémica) — patrones de recovery operativos validados en OIC v1.5 2026-06-04 (2 sub-agentes background fallaron al cerrar pero dejaron ~700 LOC en disco)."
 nivelRiesgo: BAJO
 skillsInvocables: [compactacion-contexto, checkpoints-verificacion, aprendizaje-continuo, discutir-fase, ejecutar-fase, planear-fase, nuevo-proyecto, brainstorming, control-profundidad, prevencion-racionalizacion, estructura-proyecto-claude, workflow-claude-code, git-worktrees-paralelo, swl-dashboard, instalar-sistema, mapear-codebase, orquestacion-async, context-builder]
 skillsRestringidos: [fastapi-python, angular-component, angular-forms, postgresql-table-design]
@@ -160,6 +165,89 @@ Origen del patrón: documentado en skill global `harness-claude-code`
 gotcha "Sub-agente entra en autocompact thrashing con prompts >30k tokens"
 (SIGAF 2026-05-22).
 
+### 5. Sub-agente background falla con "API Error: Usage credits required for 1M context" — verificar filesystem antes de re-intentar
+
+Síntoma típico (caso real OIC v1.5 2026-06-04): un sub-agente lanzado con
+`run_in_background: true` (típicamente `implementador-swl` para un slice
+grande) notifica `status: completed` con `result: "API Error: Usage credits
+required for 1M context · run /usage-credits to turn them on, or /model to
+switch to standard context"`. El `total_tokens` del result es muy bajo
+(1k-2k) pese a `tool_uses` alto (29-35).
+
+**El error es al FINAL, no al inicio**: el sub-agente trabajó normalmente,
+escribió archivos en disco, e intentó procesar la respuesta JSON
+estructurada (o hacer el commit final) y excedió el contexto 1M en ese
+último step. Todo el trabajo real quedó en disco.
+
+**Protocolo OBLIGATORIO de recuperación** antes de re-implementar:
+
+```bash
+# 1. Verificar archivos staged/untracked relacionados con la tarea del agente
+git status --porcelain
+git diff --stat HEAD
+
+# 2. Si hay archivos del scope del slice/tarea: inspeccionar calidad
+git diff <archivo>
+ruff check <archivo>  # o equivalente del lenguaje
+pytest <tests_del_slice>  # validar funcionalidad
+
+# 3. Completar SOLO lo que falte (típicamente: el commit final + tests faltantes
+#    + integración como router.py, __init__.py, etc.)
+git add <archivos_validados>
+git commit -m "feat(...): retomado tras fallo de billing del sub-agente"
+```
+
+**NUNCA** asumir "fallo total" y re-implementar desde cero. Eso descarta
+horas de trabajo que está completo en disco.
+
+**Heurística de detección**:
+- `result` contiene "Usage credits", "1M context", "context limit exceeded"
+- `total_tokens` < 5000 con `tool_uses` >= 15 (≠ proporcional)
+- `duration_ms` > 60s (el agente trabajó tiempo real)
+
+**Mejora del prompt al sub-agente** cuando hay riesgo de 1M context:
+agregar al final del prompt `"si te quedas sin contexto al final, deja los
+archivos commitleables en disco para que el orquestador retome desde git
+status"`. Esto refuerza el comportamiento ya natural pero hace explícito el
+contrato.
+
+**Origen**: OIC Milestone v1.5 Slices 1 y 5 (2026-06-04). Los 2 sub-agentes
+background fallaron al cerrar pero dejaron ~700 LOC funcionales en disco.
+Detectado por `git status` antes de re-implementar.
+
+### 6. Cuándo NO delegar a sub-agentes Opus 4.7 [1M context]
+
+El modelo Opus 4.7 con 1M context (`claude-opus-4-7[1m]`) requiere créditos
+1M activos en la cuenta. En proyectos donde `/usage-credits` reporta que NO
+están activos, los sub-agentes 1M fallan al cerrar (ver sección 5 arriba)
+incluso si el trabajo real cabía en 200k.
+
+**Heurística de decisión**:
+
+| Situación | Acción |
+|---|---|
+| Proyecto con créditos 1M confirmados (`/usage-credits` muestra activo) | Delegar normalmente |
+| Proyecto sin créditos 1M y slice de < 500 LOC | Trabajo directo en main loop (mejor ROI que delegar) |
+| Proyecto sin créditos 1M y slice de 500-1500 LOC | Delegar con `model: 'sonnet'` override en el Agent tool call, o dividir en sub-slices |
+| Proyecto sin créditos 1M y slice de > 1500 LOC | Dividir en sub-slices < 500 LOC y trabajar directo |
+
+**Anti-patrón**: asumir que "el padre tiene 1M context entonces el sub-agente
+también". El sub-agente hereda el modelo, no los créditos. Los créditos son
+por-cuenta, no por-sesión.
+
+**Override seguro** cuando se delega y no hay créditos 1M:
+
+```typescript
+Agent({
+  subagent_type: "implementador-swl",
+  model: "sonnet",  // ← override explícito
+  prompt: "...",
+})
+```
+
+**Origen**: OIC Milestone v1.5 2026-06-04. 2 invocaciones background fallaron
+en cadena con el mismo error de billing antes de aplicar el override.
+
 ## Routing por fase + dominio (lookup tabular determinístico)
 
 Antes de delegar, **clasifica la petición** por dos ejes mecánicos en lugar de

package/agentes/revisor-codigo-swl.md

@@ -15,12 +15,12 @@ model: claude-sonnet-4-6
 modeloAlterno: claude-haiku-4-5-20251001
 ventanaContexto: 200k
 color: orange
-version: 1.2.0
+version: 1.2.2
 evolved: true
-evolved-from: "1.1.2"
-evolved-at: "2026-05-09"
-evolved-by: "aprender"
-evolved-note: "Reorganización de scoring con vocabulario 5-axis Addy Osmani sin duplicar capacidades existentes. Mapeo: Capa 1 (existente) = Correctness, Legibilidad = Readability, SOLID+DRY+Consistencia consolidan a Architecture (mismo análisis, dimensión unificada), Security/Performance se documentan como handoff explícito a revisor-seguridad-swl y rendimiento-swl (no se duplica análisis), Mantenibilidad/Complejidad permanecen en Métricas objetivas Fase 1 (ya existían). Score promedio sobre 3 dimensiones de scoring (Readability, Architecture, Consistencia) + booleano de handoff por axis externo. Veto items y formato de reporte preservados, retrocompatible. Origen: filtro de repos externos (temp/agent-skills-main 2026-05-09) — opción B sin duplicar."
+evolved-from: "1.2.1"
+evolved-at: "2026-06-05"
+evolved-by: "evolucionar"
+evolved-note: "+gating por versión de lenguaje antes de marcar sintaxis como SyntaxError CRÍTICO: leer requires-python/target-version/tsconfig/edition y refutar con import+linter del stack (aplicación de verificar-citas Familia 2 a claims de sintaxis). Generalizable a cualquier lenguaje version-dependent. Origen: falso positivo PEP 758 (except A,B: en Python 3.14) en sistema-verificacion-oic."
 nivelRiesgo: BAJO
 skillsInvocables: [checklist-calidad, patrones-python, api-rest-diseno, tdd-workflow, verificar-trabajo, verificacion-evidencia, swl-revisar-impacto, prevencion-sobreingenieria]
 skillsRestringidos: []
@@ -68,13 +68,22 @@ Responsabilidades concretas:
 
 ## Protocolo obligatorio al iniciar
 
+**Presupuesto de contexto (anti-thrashing):** tu ventana hereda el `CLAUDE.md`
+del proyecto + las reglas globales del usuario. En proyectos rule-heavy eso
+consume buena parte de la ventana antes de leer código — si además exploras el
+codebase completo, saturas y entras en autocompact thrashing (0 tokens útiles,
+observado 2026-06-05). Por eso: NO releas `CLAUDE.md` (ya está en tu contexto),
+lee SOLO los archivos del alcance recibido, y carga `skillsInvocables` bajo
+demanda — solo cuando el alcance concreto lo amerite, nunca al inicio "por si acaso".
+
 Antes de revisar cualquier código:
 
-1. **Leer CLAUDE.md** del proyecto — convenciones, anti-patrones conocidos.
-2. **Obtener el diff** del cambio a revisar: `git diff main..HEAD` o leer
-   los archivos indicados.
-3. **Leer el contexto** — archivos relacionados para entender el módulo completo,
-   no solo el cambio aislado.
+1. **Obtener el diff / alcance**: usar los archivos indicados por quien delega;
+   si no se indicaron, `git diff main..HEAD --name-only`. NO releer CLAUDE.md
+   (ya está en tu contexto heredado).
+2. **Leer los archivos del alcance PRIMERO**, antes de cargar cualquier skill.
+3. **Leer contexto adicional solo si es necesario** para entender el cambio —
+   acotado; no el módulo completo si el alcance es pequeño.
 4. **Verificar métricas base** con herramientas estáticas antes de hacer juicios.
 
 ## Revision en dos capas (obligatorio)
@@ -370,6 +379,19 @@ Solo los problemas CRÍTICOS bloquean el avance. MAYOR debe documentarse como de
 - Si el código es bueno, dilo explícitamente — los reportes vacíos de problemas
   son tan valiosos como los reportes con 10 problemas
 - No revises código que no puedes ejecutar ni compilar — pide el contexto necesario
+- NUNCA marques una construcción sintáctica como SyntaxError CRÍTICO sin verificar
+  primero la **versión objetivo del lenguaje** del proyecto. Mucha sintaxis es
+  válida solo a partir de cierta versión (Python: `requires-python` /
+  `tool.ruff.target-version` en `pyproject.toml`; TypeScript: `target`/`lib` en
+  `tsconfig.json`; Java: `--release`; C#: `<LangVersion>`; Rust: edition). Antes
+  de emitir el veredicto bloqueante, lee la versión objetivo y **refuta el presunto
+  error con evidencia ejecutable** del stack (`python -c "import <módulo>"`,
+  `ruff check`, `tsc --noEmit`, el compilador correspondiente). Evidencia >
+  afirmación: si la construcción importa/compila bajo la versión objetivo, NO es
+  un hallazgo — degrádalo o elimínalo. Esta es la aplicación de
+  `verificar-citas Familia 2` a claims de sintaxis: un revisor que afirma
+  "SyntaxError" sin verificar contra el target propaga un falso positivo
+  bloqueante.
 
 ## Gotchas / Errores comunes no obvios
 
@@ -381,6 +403,8 @@ Solo los problemas CRÍTICOS bloquean el avance. MAYOR debe documentarse como de
 
 **Hallazgos sin ejemplo de corrección**: un hallazgo que solo señala el problema sin mostrar cómo arreglarlo no es accionable. Causa: el revisor describe el anti-patrón pero no la alternativa correcta. Solución: todo hallazgo CRÍTICO o MAYOR incluye el código incorrecto y el código correcto esperado.
 
+**Marcar sintaxis version-dependent como SyntaxError sin verificar el target**: una construcción válida en la versión objetivo del proyecto se lee como error de sintaxis cuando el revisor la juzga contra su conocimiento general del lenguaje en vez de leer la versión objetivo. Causa: la validez sintáctica depende de la versión (`requires-python`/`target-version`, `tsconfig target`, `--release`, edition) y no es absoluta. Caso real (2026-06-05, `sistema-verificacion-oic`): `except A, B:` sin paréntesis — válido en Python ≥3.14 por PEP 758 — fue marcado como SyntaxError CRÍTICO/RECHAZADO en un proyecto con `requires-python >=3.14`; refutado con `python -c "import …"` + `ruff check` + CI verde. Solución: antes de un veredicto bloqueante por sintaxis, leer la versión objetivo del proyecto y refutar el presunto error con import/compilación real del stack (ver Reglas estrictas).
+
 ## Veto items — cap enforcement a 60/100
 
 Ciertos hallazgos son **no negociables** y violan reglas globales del sistema.

package/agentes/revisor-seguridad-swl.md

@@ -63,6 +63,13 @@ Antes de comenzar la auditoría:
    de archivos, autenticación, autorización, dependencias externas.
 3. **Obtener el diff** o la lista de archivos a auditar.
 4. **Mapear el flujo de datos**: de dónde viene el input, cómo se procesa, dónde se almacena.
+5. **Elegir el modo**: revisión de PR/diff (flujo estándar de abajo) o
+   **auditoría en profundidad** — en ese caso cargar
+   `Skill("checklist-seguridad")` y aplicar su *modo cobertura* (STRIDE +
+   OWASP con score compuesto, iterando con rotación de personas red-team y
+   registro en `hooks/lib/loop-telemetry.js`). Cada hallazgo se etiqueta con
+   ambas taxonomías y el reporte incluye la línea de cobertura
+   `OWASP: N/10 | STRIDE: M/6 | Score: X`.
 
 ## Flujo de trabajo paso a paso
 

package/agentes/tdd-qa-swl.md

@@ -11,9 +11,9 @@ model: claude-sonnet-4-6
 modeloAlterno: claude-haiku-4-5-20251001
 ventanaContexto: 200k
 color: purple
-version: 1.0.0
+version: 1.1.0
 nivelRiesgo: BAJO
-skillsInvocables: [tdd-workflow, testing-python, checklist-calidad, manejo-errores, webapp-testing, php-testing, nextjs-testing]
+skillsInvocables: [tdd-workflow, testing-python, checklist-calidad, manejo-errores, webapp-testing, php-testing, nextjs-testing, calidad-mutation-testing]
 skillsRestringidos: []
 permisosRed: false
 permisosEscritura: true
@@ -213,6 +213,27 @@ diff /tmp/baseline.txt /tmp/current.txt
 Toda regresión (test que antes pasaba y ahora falla) es un bloqueante.
 Reporta: qué test, qué falló, qué cambio lo causó.
 
+### Fase 6 — Gate de mutación (opt-in, módulos críticos)
+
+La cobertura mide ejecución, no calidad de asserts. Cuando el módulo es
+crítico (dinero, auth, cálculo regulatorio) Y hay runner de mutación
+instalado Y la suite corre en <2 min, cerrar la auditoría con mutación
+incremental sobre el diff:
+
+1. Cargar `Skill("calidad-mutation-testing")` — herramientas por stack,
+   modo incremental, umbrales por contexto.
+2. Correr la mutación SOLO sobre los archivos del diff de la fase
+   (`--since` / `--in-diff`), nunca el repo completo.
+3. Diagnosticar cada mutante sobreviviente: assert débil → endurecer el
+   assert; test faltante → escribir test de frontera dirigido; mutante
+   equivalente → excluir con anotación (NUNCA test artificial para matarlo).
+4. Reportar el mutation score junto a la cobertura. Umbral de referencia:
+   ≥85% en módulo crítico, ≥70% en lógica de negocio estándar.
+
+Si las precondiciones no se cumplen (sin runner, suite lenta, suite roja),
+omitir la fase y decirlo en el reporte — no es deuda silenciosa, es opt-in
+documentado.
+
 ## Convenciones de escritura de tests
 
 ### Python (pytest)

package/comandos/swl/autoresearch.md

@@ -1,6 +1,6 @@
 ---
 name: swl:autoresearch
-description: Ejecuta el loop de auto-mejora iterativa Autoresearch sobre un skill o agente. Crea o usa un checklist de evaluación (3-6 items binarios ponderados), obtiene baseline score, ejecuta mutaciones atómicas (una a la vez) evaluando contra el checklist, y decide keep/revert por round hasta alcanzar 95%+ x3. Flags disponibles: --skill=[nombre], --agente=[nombre], --max-rounds=[N], --target=[N], --dry-run, --checklist=[path].
+description: Ejecuta el loop de auto-mejora iterativa Autoresearch sobre un skill, un agente, o (modo --codigo) sobre código del proyecto contra una métrica arbitraria. Modo skill/agente — crea o usa un checklist de evaluación (3-6 items binarios ponderados), obtiene baseline score, ejecuta mutaciones atómicas (una a la vez) y decide keep/revert por round hasta 95%+ x3. Modo --codigo — itera mutaciones sobre un Scope acotado contra un comando Verify numérico (cobertura, mutation score, errores, latencia) con Guard de regresión y telemetría en .planning/loops/. Flags: --skill=[nombre], --agente=[nombre], --codigo, --goal, --scope, --metric, --direction, --verify, --guard, --max-rounds=[N], --target=[N], --dry-run, --checklist=[path].
 allowed_tools: ["Read", "Write", "Edit", "Bash", "Glob", "Grep"]
 ---
 
@@ -22,13 +22,20 @@ Este comando es distinto a `/swl:evolucionar`: donde evolucionar analiza evidenc
 ```
 --skill=[nombre]        Skill a mejorar (busca en habilidades/[nombre]/SKILL.md)
 --agente=[nombre]       Agente a mejorar (busca en agentes/[nombre].md)
---max-rounds=[N]        Máximo de iteraciones del loop (default: 10)
---target=[N]            Score objetivo en % (default: 95)
---dry-run               Analizar y crear checklist sin ejecutar mutaciones
---checklist=[path]      Ruta a checklist existente
+--codigo                Modo código: itera sobre código del proyecto contra una métrica (ver sección "Modo --codigo")
+--goal="..."            (--codigo) Meta textual del loop
+--scope="glob"          (--codigo) Archivos que el loop PUEDE modificar (glob acotado)
+--metric="..."          (--codigo) Qué mide la métrica (ej: "mutation score de src/pagos")
+--direction=[dir]       (--codigo) higher_is_better | lower_is_better
+--verify="cmd"          (--codigo) Comando shell cuya salida contiene el número de la métrica
+--guard="cmd"           (--codigo) Comando que debe pasar (exit 0) para aceptar una mutación
+--max-rounds=[N]        Máximo de iteraciones del loop (default: 10 skill/agente, 15 código)
+--target=[N]            Score objetivo (default: 95% en skills; en código lo define el usuario)
+--dry-run               Analizar y derivar configuración sin ejecutar mutaciones
+--checklist=[path]      Ruta a checklist existente (solo modo skill/agente)
 ```
 
-**Nota**: Se debe pasar `--skill` o `--agente`, no ambos. Si no se pasa ninguno, preguntar al usuario.
+**Nota**: Se debe pasar `--skill`, `--agente` o `--codigo` (excluyentes). Si no se pasa ninguno, preguntar al usuario.
 
 ## Paso 0 — Parseo de flags y carga de habilidades
 
@@ -168,3 +175,92 @@ Si el score mejoró respecto al baseline:
 - Si después de 3 rounds sin mejora, preguntar al usuario si continuar o parar
 - El caso de prueba NO cambia durante el loop
 - Mantener log completo del loop para auditoría
+
+---
+
+## Modo `--codigo` — Loop métrico sobre código del proyecto
+
+Generaliza el loop a **código del usuario**: la misma disciplina (mutación
+atómica → medir → keep/revert) pero la evaluación es un **comando Verify
+numérico** en lugar de un checklist. Patrón adoptado del análisis de
+autoresearch v2.1 (loop core), adaptado a las reglas SWL (HITL, git-workflow,
+telemetría en `.planning/loops/`).
+
+Métricas típicas: mutation score (cargar `Skill("calidad-mutation-testing")`),
+cobertura de tests, conteo de errores de tsc/lint (lower_is_better), latencia
+p95 de un benchmark, bundle size, tiempo de suite.
+
+### Paso C0 — Derivar y aprobar la configuración (HITL obligatorio)
+
+Completar con el usuario los campos faltantes y presentar el bloque para
+aprobación explícita ANTES de la primera mutación:
+
+```
+=== Autoresearch --codigo — Configuración ===
+Goal:      [meta textual]
+Scope:     [glob de archivos que el loop PUEDE tocar]
+Metric:    [qué mide] | Direction: [higher|lower]_is_better
+Verify:    [comando shell]
+Guard:     [comando shell o "(ninguno)"]
+Target:    [valor objetivo o "(mejora máxima en N rounds)"]
+Rounds:    [N, default 15]
+```
+
+**Safety screen del Verify/Guard (bloqueante)**: rechazar comandos que
+contengan `rm -rf`, `curl|sh`/`wget|sh`, `sudo`, `git push`, `--force`,
+redirecciones a archivos fuera del repo, o credenciales inline. El Verify se
+ejecuta una vez en dry-run para confirmar que produce un número parseable —
+si no, corregir el comando antes de iterar.
+
+**Guard por default**: si el proyecto tiene suite de tests, el Guard es la
+suite (`npm test` / `pytest`). Iterar sin Guard solo si el usuario lo aprueba
+explícitamente — una métrica que sube con la suite rota no es mejora.
+
+Si `--dry-run`: terminar aquí mostrando la configuración derivada.
+
+### Paso C1 — Baseline y telemetría
+
+```bash
+node -e "const lt=require('./hooks/lib/loop-telemetry');const r=lt.iniciarCorrida({tipo:'autoresearch',direccion:'[direction]',config:{goal:'[goal]',scope:'[scope]',verify:'[verify]',guard:'[guard]'}});console.log(r.dir)"
+```
+
+Correr Verify, extraer la métrica, registrar la iteración 0 (`estado:
+baseline`). Si el baseline ya cumple el target, terminar: no hay loop que correr.
+
+### Paso C2 — El loop
+
+Por cada round (hasta `--max-rounds`, default 15):
+
+1. **Revisar memoria**: últimas filas del TSV + `git log --oneline -10` — qué
+   funcionó, qué se revirtió. No repetir mutaciones ya revertidas.
+2. **UNA mutación atómica** dentro del Scope. Archivos fuera del Scope son
+   intocables — si la mejora "necesita" tocar otro archivo, pausar y
+   preguntar al usuario (anti-proxy-goal-drift).
+3. **Medir**: correr Verify → métrica nueva; correr Guard.
+4. **Decidir**:
+   - Métrica mejora Y Guard pasa → **keep**: commit `experiment(autoresearch): [descripción]`.
+   - Métrica no mejora O Guard falla → **revert**: descartar los cambios del
+     working tree (`git checkout -- [archivos tocados]`). NUNCA reescribir
+     historia para revertir — solo se commitea lo que se conserva.
+   - Verify truena → estado `crash`: descartar cambios, registrar, continuar.
+5. **Registrar** la iteración con `registrarIteracion` (métrica, delta, estado, descripción).
+6. **Condiciones de salida**: target alcanzado → ÉXITO; `detectarPlateau`
+   sobre las últimas 3 filas → PLATEAU (parar, no quemar rounds sin mejora);
+   3 reverts consecutivos → ESTANCAMIENTO (preguntar al usuario);
+   max rounds → ACOTADO.
+
+### Paso C3 — Cierre
+
+1. Escribir handoff: `escribirHandoff(dir, {source: 'swl:autoresearch', status: [COMPLETO|PLATEAU|ACOTADO|INTERRUMPIDO], config})`.
+2. Reporte final con trayectoria (`analizarTrayectoria`): rounds, keep/revert,
+   métrica inicial → final, mayor salto, y los commits `experiment(...)` generados.
+3. Ofrecer al usuario squash de los commits experimentales en un commit
+   semántico final (`git-workflow.md § Squash antes de merge`).
+
+### Reglas adicionales del modo `--codigo`
+
+- NUNCA `git push` desde el loop — los commits experimentales son locales.
+- NUNCA tocar archivos fuera del Scope aprobado.
+- NUNCA continuar tras plateau "por si acaso" — el plateau ES la señal de salida.
+- El hook `contexto-iteracion.js` inyecta el estado del loop en sesiones
+  largas; no releer el TSV completo en cada round (las últimas 3 filas bastan).

package/comandos/swl/metricas.md

@@ -22,6 +22,7 @@ costo estimado, herramientas más usadas y estado del presupuesto configurado.
 /swl:metricas             — Resumen de métricas de la sesión
 /swl:metricas detalle     — Desglose completo por herramienta y timeline
 /swl:metricas fases       — Progreso de fases del proyecto desde feature-list.json
+/swl:metricas loops       — Trayectorias de loops iterativos desde .planning/loops/
 /swl:metricas historico   — Abre el dashboard histórico multi-sesión (alias de /swl:dashboard)
 ```
 
@@ -318,6 +319,39 @@ node scripts/derivar-feature-list.js --check
 
 ---
 
+## Subcomando: `loops` — Trayectorias de loops iterativos
+
+Si el usuario invoca `/swl:metricas loops`, leer las corridas registradas por
+`hooks/lib/loop-telemetry.js` en `.planning/loops/`:
+
+```bash
+node -e "
+const fs = require('fs'), path = require('path');
+const lt = require('./hooks/lib/loop-telemetry');
+const base = path.join(process.cwd(), lt.DIR_LOOPS);
+let dirs = [];
+try { dirs = fs.readdirSync(base).map(d => path.join(base, d)).filter(d => fs.statSync(d).isDirectory()); } catch {}
+if (dirs.length === 0) { console.log('(sin corridas de loops registradas)'); process.exit(0); }
+for (const dir of dirs.sort().slice(-10)) {
+  try {
+    const t = lt.analizarTrayectoria(dir);
+    const h = lt.leerHandoff(dir);
+    console.log(path.basename(dir) + ' | iters: ' + t.totalIteraciones +
+      ' | keep/revert: ' + t.keeps + '/' + t.reverts +
+      ' | métrica: ' + t.metricaInicial + ' → ' + t.metricaFinal +
+      ' | plateau: ' + (t.plateau ? 'SÍ' : 'no') +
+      ' | status: ' + (h ? h.status : 'en curso'));
+  } catch (e) { console.log(path.basename(dir) + ' | (ilegible: ' + e.message + ')'); }
+}
+"
+```
+
+Reportar al usuario en tabla: corrida, iteraciones, keep/revert rate, métrica
+inicial → final, plateau y status del handoff. Si alguna corrida activa muestra
+plateau, sugerir cerrarla — seguir iterando sin mejora quema tokens.
+
+---
+
 ## Subcomando: `historico`
 
 Si el usuario invoca `/swl:metricas historico`, redirigir inmediatamente a:

package/comandos/swl/nemesis.md

@@ -8,7 +8,7 @@ description: >
   automático para scope > 1500 LOC o > 5 archivos en módulos distintos.
   Persiste hallazgos en .planning/audit/findings/iter-N/.
 allowed-tools: [Read, Grep, Glob, Bash, Write, Agent, Skill]
-argument-hint: "[--remediar] [--pass1 | --pass2 | --continue] [--modulo <ruta>] [--redistribuir] [--reset-plan]"
+argument-hint: "[--remediar] [--pass1 | --pass2 | --continue] [--modulo <ruta>] [--redistribuir] [--reset-plan] [--cross-model]"
 ---
 
 # /swl:nemesis — Auditoría iterativa con remediación opt-in
@@ -54,6 +54,29 @@ y el ciclo continúa hasta convergencia o agotar el guardrail de 3 iteraciones.
 | Acotar módulo | `--modulo <ruta>` | Limita el scope a un archivo o subdirectorio específico. Se combina con cualquier otro flag. |
 | Forzar redistribución | `--redistribuir` | Activa `Skill("nemesis-redistribuir")` aunque scope sea menor al umbral. |
 | Reset del plan | `--reset-plan` | Regenera `nemesis-plan.json` desde cero (descarta plan previo). |
+| **Revisión cross-modelo** | `--cross-model` | Opt-in: rutea la evaluación a un reviewer en OTRO modelo (vía MCP, p.ej. `gemini-review`/`codex-review`) para combatir *self-preferential bias*. Degrada al reviewer same-model si no hay MCP configurado (anuncia la degradación). Combina con `--remediar`. Ver `Skill("proceso-dynamic-workflows") § Revisión cross-modelo`. |
+
+## Revisión cross-modelo (`--cross-model`)
+
+El reviewer adversarial en el MISMO modelo aún arrastra *self-preferential bias*
+(uno de los 3 modos de falla nombrados en el blog oficial de dynamic workflows).
+`--cross-model` hace que la evaluación la emita un modelo DISTINTO al ejecutor:
+
+- **Wiring (opt-in, ligero)**: si hay un MCP reviewer configurado (patrón ARIS
+  `gemini-review`/`codex-review`: expone `review`/`review_reply`, devuelve JSON con
+  `threadId` + `response`), el paso de evaluación se rutea a ese MCP. swl-ses NO
+  embebe el servidor — lo provee el usuario con su API key del otro modelo.
+- **Degradación explícita** (regla `arreglar-al-detectar.md` / no-fallback-silencioso):
+  si el MCP no está disponible, NO falla — usa el reviewer same-model y **anuncia**
+  "cross-model solicitado pero MCP ausente → degradado a same-model".
+- **Reviewer memory + debate** (de ARIS `auto-review-loop`): el reviewer externo
+  arrastra sospechas entre iteraciones (un `threadId`); el ejecutor puede rebatir,
+  el reviewer falla el veredicto final — *"it can drive, never acquit"*.
+- **Trazabilidad**: el JSON del reviewer (`threadId`, `response`, score) se persiste
+  junto a `evaluacion.json` en `.planning/audit/findings/iter-N/` → veredicto
+  independiente auditable.
+
+Detalle del patrón: `Skill("proceso-dynamic-workflows") § Revisión cross-modelo`.
 
 ## Flujo completo con `--remediar`
 
@@ -207,6 +230,24 @@ Estructura de salida bajo `.planning/audit/findings/`:
 
 Cada `evaluacion.json` sigue el schema `nemesis-evaluacion-json` v1.0.0.
 
+### Telemetría de loop (obligatoria con `--remediar`)
+
+En modo `--remediar`, además de los `iter-N/` el comando registra la
+trayectoria en el formato estándar de telemetría de loops
+(`hooks/lib/loop-telemetry.js`). Esto habilita: inyección de estado por el
+hook `contexto-iteracion.js` durante las ejecuciones largas (8-30 turnos),
+detección de plateau, y lectura de la corrida por `/swl:metricas`.
+
+- Al iniciar iter-1: `iniciarCorrida({tipo: 'nemesis', direccion: 'lower_is_better', config: {modulo, maxIter: 3}})`.
+- Tras cada iteración: `registrarIteracion(dir, {iteracion: N, metrica: criticos+altos, delta, estado: 'keep', descripcion: 'iter N: status=<status>, X criticos, Y altos'})`.
+- Al cerrar (PASS, FAIL o Recovery Catalog): `escribirHandoff(dir, {source: 'swl:nemesis', status, findings: <hallazgos residuales con archivo_linea>, config})`.
+  Mapeo de status: PASS → `COMPLETO`, max iteraciones → `ACOTADO`, Recovery
+  Catalog/escalada → `INTERRUMPIDO`.
+
+El `handoff.json` resultante es consumible por una corrida posterior de
+`/swl:verificar --until-converge` o por el orquestador (los `findings`
+traen `archivo_linea` verificable según `verificar-citas-normativas.md § Familia 2`).
+
 ## Cómo interpretar el reporte
 
 ### Severidades

package/comandos/swl/planear-fase.md

@@ -161,6 +161,14 @@ El agente planificador-swl debe generar el plan con esta estructura exacta:
 ## Tests requeridos
 [lista de tests que deben existir al finalizar la fase]
 
+## Escenarios Gherkin (opt-in — solo si la fase tiene criterios de aceptación de negocio)
+[Si el CONTEXTO.md/PRD trae criterios de aceptación con reglas de negocio
+distinguibles, convertirlos en escenarios Given–When–Then siguiendo
+`habilidades/tdd-workflow/recursos/gherkin-bdd.md` y presentarlos al usuario
+para validación ANTES de aprobar el plan. Cada escenario validado se referencia
+desde la tarea que lo implementa (será su test RED). Omitir esta sección en
+fases técnicas puras — Gherkin sin lector de negocio es ceremonia.]
+
 ## Riesgos y mitigaciones
 | Riesgo | Impacto | Probabilidad | Mitigación |
 |--------|---------|-------------|-----------|