@saulwade/swl-ses 1.8.0 → 2.0.0

package/comandos/swl/aprobar-plan.md

@@ -0,0 +1,152 @@
+---
+name: swl:aprobar-plan
+description: Aprueba el PLAN.md de una fase y lo firma con un lock SHA256 (gate G1 de SDD). Transiciona el frontmatter de estado borrador a aprobado y escribe .planning/locks/<plan>.lock. Es la única vía válida de aprobación — ejecutar-fase verifica este lock antes de implementar y detiene la ejecución si el plan fue mutado tras la firma.
+allowed_tools: ["Read", "Write", "Edit", "Bash", "Glob"]
+---
+
+# /swl:aprobar-plan <n> — Aprobar y firmar el plan de una fase (Gate G1)
+
+Eres el guardián del gate G1 del enforcement SDD. Tu trabajo es transicionar un
+PLAN de `borrador` a `aprobado` Y firmarlo con un lock SHA256, de modo que
+cualquier mutación posterior del plan sea detectable por `/swl:ejecutar-fase`.
+
+Este comando es la **única vía documentada de aprobación**. Editar el frontmatter
+a mano (`estado: aprobado`) deja el plan en modo legacy (cláusula de gracia D-05):
+se ejecuta con advertencia pero sin protección de integridad. Usar este comando
+es lo que activa el gate real.
+
+## Uso
+
+```
+/swl:aprobar-plan 9
+```
+
+El argumento `<n>` es el número de la fase cuyo PLAN se aprueba.
+
+## Paso 1 — Localizar el PLAN
+
+Resuelve la ruta `.planning/fases/0N-PLAN.md` (N con cero a la izquierda si N < 10).
+
+- Si no existe: detente con "No existe el PLAN de la fase N. Ejecuta `/swl:planear-fase N` primero."
+- Lee el archivo completo.
+
+## Paso 2 — Validar el estado actual del frontmatter
+
+Lee el campo `estado:` del frontmatter:
+
+- Si `estado: borrador` → continúa al Paso 3 (caso normal).
+- Si `estado: aprobado` → ya está aprobado. Verifica si existe el lock:
+  ```bash
+  node -e "const {verificarPlan}=require('./scripts/lib/plan-lock'); console.log(JSON.stringify(verificarPlan('.planning/fases/0N-PLAN.md')))"
+  ```
+  - Si `modo: "firmado"` → informa "El plan ya está aprobado y firmado." y termina.
+  - Si `modo: "legacy"` (aprobado sin lock) → pregunta al usuario: "El plan está
+    aprobado pero sin firmar (modo legacy). ¿Lo firmo ahora para activar el gate
+    G1?" Si confirma, salta al Paso 4 (firmar sin re-transicionar).
+  - Si `modo: "mutado"` → el plan cambió tras una firma previa. Informa el
+    `hashEsperado` vs `hashActual` y pregunta si re-aprobar (re-firmar el estado
+    actual). Procede solo con confirmación explícita.
+- Si no hay campo `estado` → detente: "El PLAN no tiene campo `estado` en el
+  frontmatter. Revisa que sea un plan válido generado por `/swl:planear-fase`."
+
+## Paso 2.5 — Validar la matriz REQ×T (trazabilidad G4)
+
+Lee `.planning/fases/0N-CONTEXTO.md` y extrae los IDs `REQ-NN:` de la sección de
+criterios de aceptación.
+
+- **CONTEXTO sin REQ-IDs** (fases legacy 01-09): advertencia informativa
+  ("CONTEXTO sin REQ-IDs — trazabilidad no exigible, gracia legacy") y continúa.
+- **CONTEXTO con REQ-IDs**: verifica que el PLAN cubra TODOS:
+  ```bash
+  node scripts/verificar-trazabilidad.js --fase=N --solo-plan
+  ```
+  - Exit 0 → continúa al Paso 3.
+  - Exit 1 (REQ huérfanos) → **RECHAZA la aprobación**. Lista los REQ sin tarea y
+    remite a `/swl:planear-fase N` para cubrirlos (o a retirar el REQ del CONTEXTO
+    con marca "RETIRADO — razón"). NO firmes un plan con REQ huérfanos.
+
+## Paso 3 — Confirmar con el usuario antes de aprobar
+
+NUNCA apruebes sin confirmación explícita. Presenta un resumen breve del plan
+(número de slices, tareas, slices HITL) y pregunta:
+
+```
+El plan de la fase N tiene [X] slices y [Y] tareas ([Z] HITL).
+¿Confirmas la aprobación? Al aprobar se firma con SHA256 y queda inmutable:
+cualquier edición posterior detendrá /swl:ejecutar-fase.
+```
+
+Espera respuesta afirmativa. Si el usuario pide cambios, NO apruebes — remítelo
+a `/swl:planear-fase N` para refinar.
+
+## Paso 4 — Transicionar y firmar
+
+1. **Transicionar** (omitir si el plan ya estaba `aprobado` en modo legacy):
+   edita el frontmatter `estado: borrador` → `estado: aprobado` y agrega
+   `aprobadoPor: usuario (<nombre>) — <fecha>, via /swl:aprobar-plan`.
+
+2. **Firmar** — escribe el lock SHA256:
+   ```bash
+   node -e "const {firmarPlan}=require('./scripts/lib/plan-lock'); const r=firmarPlan('.planning/fases/0N-PLAN.md'); console.log(JSON.stringify(r))"
+   ```
+   Verifica que el resultado sea `ok: true` y que exista
+   `.planning/locks/0N-PLAN.md.lock`.
+
+3. **Verificar** la firma de inmediato:
+   ```bash
+   node -e "const {verificarPlan}=require('./scripts/lib/plan-lock'); console.log(JSON.stringify(verificarPlan('.planning/fases/0N-PLAN.md')))"
+   ```
+   Debe retornar `modo: "firmado"`, `ok: true`.
+
+4. **Marcar la fase como activa** (gate G0 — `hooks/spec-gate.js` consume este
+   archivo): escribe `.planning/locks/fase-activa.json` con el sha256 devuelto
+   por `firmarPlan`:
+   ```bash
+   node -e "
+   const {atomicWriteJSON} = require('./hooks/lib/atomic-write');
+   const {verificarPlan} = require('./scripts/lib/plan-lock');
+   const v = verificarPlan('.planning/fases/0N-PLAN.md');
+   atomicWriteJSON('.planning/locks/fase-activa.json', {
+     numero: N,
+     planPath: '.planning/fases/0N-PLAN.md',
+     sha256: v.hashEsperado,
+     aprobadoEn: new Date().toISOString(),
+     aprobadoPor: 'usuario via /swl:aprobar-plan'
+   });
+   console.log('fase activa: 0N');
+   "
+   ```
+   Este archivo es runtime local (gitignored — a diferencia del `.lock`, que SÍ
+   se versiona como evidencia). `/swl:ejecutar-fase` lo elimina al cerrar la fase.
+   Si se re-firma un plan (re-aprobación tras mutación), re-escribir también
+   fase-activa.json para que el hash quede alineado.
+
+## Paso 5 — Reporte
+
+```
+Plan de la fase N aprobado y firmado (gate G1 activo).
+
+estado: borrador -> aprobado
+lock: .planning/locks/0N-PLAN.md.lock
+fase activa: .planning/locks/fase-activa.json (gate G0 cubierto)
+sha256: <hash corto>
+
+Cualquier edición del PLAN tras esta firma detendrá /swl:ejecutar-fase con un
+mensaje de "plan mutado tras aprobación". Para cambiar el plan: edítalo y vuelve
+a ejecutar /swl:aprobar-plan N.
+
+Próximo paso: /swl:ejecutar-fase N
+```
+
+## Reglas de comportamiento
+
+- NUNCA apruebes un plan sin confirmación explícita del usuario.
+- NUNCA modifiques el contenido del plan al aprobarlo — solo el campo `estado`
+  del frontmatter y la línea `aprobadoPor`. El cuerpo es lo que se firma.
+- El lock vive en `.planning/locks/` y SÍ se versiona en git (es evidencia de
+  aprobación, parte del audit trail de SDD).
+- Si el usuario quiere cambiar el plan después de aprobado, el flujo correcto es
+  editar el PLAN y re-ejecutar `/swl:aprobar-plan N` (re-firma). NUNCA editar el
+  lock a mano.
+- El número de versión del release que publique esta fase lo decide el usuario
+  (regla CLAUDE.md) — este comando no toca versiones.

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/ayuda.md

@@ -44,7 +44,7 @@ Formato: tabla compacta con nombre, descripción corta y flags principales.
 | `/swl:revisar [stack\|archivo]` | Revisión de código por tecnología (auto-detect) |
 | `/swl:revisar-impacto` | Análisis de blast radius y risk score |
 | `/swl:evaluar-skill [nombre]` | Evaluación PluginEval de 2 capas con badge |
-| `/swl:salud` | Diagnóstico de integridad del sistema |
+| `/swl:status salud` | Diagnóstico de integridad del sistema |
 | `/swl:auditar-deps` | Auditoría de dependencias (CVEs) |
 
 #### Aprendizaje y evolución
@@ -70,8 +70,8 @@ Formato: tabla compacta con nombre, descripción corta y flags principales.
 
 | Comando | Descripción |
 |---------|------------|
-| `/swl:metricas [resumen\|detalle]` | Métricas de sesión (tokens, costo) |
-| `/swl:dashboard [today\|stats]` | Dashboard histórico multi-sesión |
+| `/swl:status metricas [resumen\|detalle]` | Métricas de sesión (tokens, costo) |
+| `/swl:status dashboard [today\|stats]` | Dashboard histórico multi-sesión |
 | `/swl:mcp-status` | Estado de servidores MCP conectados |
 
 #### Instalación y sistema

package/comandos/swl/discutir-fase.md

@@ -178,6 +178,12 @@ Espera confirmación. Si hay correcciones, ajusta y presenta el resumen nuevamen
 
 Una vez confirmado, crea `.planning/fases/0N-CONTEXTO.md` (donde N es el número de fase con cero a la izquierda si N < 10, ej: `01-CONTEXTO.md`, `02-CONTEXTO.md`).
 
+**TDD es default ON** (gate G2, decisión D-07 vNext): NO preguntes "¿quieres TDD?".
+La fase se ejecuta con ciclo RED→GREEN→REFACTOR y evidencia en telemetría salvo que
+el usuario pida desactivarlo explícitamente. Si lo desactiva: exige la razón, regístrala
+en el campo `**TDD**` del CONTEXTO y anota la excepción en `.planning/AUDITORIA.md`
+(el opt-out se declara y registra — nunca es silencioso).
+
 Estructura del archivo:
 
 ```markdown
@@ -187,6 +193,8 @@ Estructura del archivo:
 **Fase**: N de M (total de fases en el roadmap)
 **Fecha de discusión**: [fecha actual]
 **Estado**: Listo para planear
+**TDD**: on  <!-- default. Si el usuario lo desactiva: `off — razón: [...]` + entry en AUDITORIA.md -->
+
 
 ## Objetivo de la fase
 [descripción clara del objetivo]
@@ -209,8 +217,18 @@ Estructura del archivo:
 ## Pantallas / vistas (si aplica)
 [descripción de pantallas]
 
-## Criterios de aceptación
-[lista medible de criterios]
+## Criterios de aceptación (REQ)
+[criterios binarios y verificables con ID estable REQ-NN — trazabilidad G4:
+- **REQ-01**: [criterio binario verificable]
+- **REQ-02**: [criterio binario verificable]
+Un REQ emitido NUNCA se renumera ni se reusa: si un criterio se descarta, marcarlo
+"RETIRADO — razón" conservando el número. planear-fase exige que cada tarea T-NN
+declare qué REQ verifica (matriz REQ×T) y aprobar-plan rechaza planes con REQ
+huérfanos. verificar-trazabilidad.js valida la cadena REQ→T→commit→test al cierre.
+Método de verificación: por default cada REQ exige un test con marker
+`verifica: REQ-NN`; los REQ satisfechos por prosa/docs/configuración llevan la
+anotación `(verificación: inspección)` en el criterio — exigen tarea y commit
+pero no test automatizado.]
 
 ## Riesgos identificados
 [lista con nivel de impacto: ALTO/MEDIO/BAJO]

package/comandos/swl/ejecutar-fase.md

@@ -18,6 +18,7 @@ Eres el coordinador de ejecución SWL. Orquestas la implementación real del có
 ```
 /swl:ejecutar-fase 1                # modo default — oleadas paralelas
 /swl:ejecutar-fase 2 --iterative    # modo iterativo — 1 tarea, review per-task, auto-debug
+/swl:ejecutar-fase 3 --sin-verify   # omite el verify automático del cierre (desviación registrada)
 ```
 
 ### Cuándo usar `--iterative` (modo opt-in)
@@ -48,7 +49,7 @@ Si NO hay `--iterative`, carga el flujo default:
 Skill("ejecutar-fase")
 ```
 
-El skill define el protocolo completo de ejecución por tarea (leer > verificar dependencias > implementar > verificar > commit > actualizar ESTADO.md), el formato de commit atómico, las 3 reglas de desviación (menor/moderada/mayor), el manejo de tareas HITL, TDD opcional, el formato de ESTADO.md y el checklist de cierre de fase.
+El skill define el protocolo completo de ejecución por tarea (leer > verificar dependencias > implementar > verificar > commit > actualizar ESTADO.md), el formato de commit atómico, las 3 reglas de desviación (menor/moderada/mayor), el manejo de tareas HITL, TDD por default con evidencia RED en telemetría de loops (opt-out solo si el CONTEXTO declara `**TDD**: off` con razón — gate G2, ADR-0035), el formato de ESTADO.md y el checklist de cierre de fase.
 
 Luego carga habilidades específicas del stack detectado en PLAN.md o PROYECTO.md:
 - Backend Python: `Skill("fastapi-experto")`, `Skill("patrones-python")`
@@ -75,10 +76,33 @@ Verifica en orden:
 5. **Requirement Freeze**: verifica que el frontmatter del PLAN.md contenga
    `estado: aprobado`. Si contiene `estado: borrador` o no tiene campo `estado`:
    - DETENER ejecución
-   - Reportar: "El PLAN.md no está aprobado. Ejecuta `/swl:planear-fase N` y
-     confirma el plan antes de ejecutar."
+   - Reportar: "El PLAN.md no está aprobado. Ejecuta `/swl:aprobar-plan N` para
+     aprobarlo y firmarlo antes de ejecutar."
    - NO proceder sin aprobación explícita del usuario
 
+6. **Gate G1 — verificación de integridad del plan firmado**: tras confirmar
+   `estado: aprobado`, recomputa el hash del PLAN y compáralo contra su lock:
+   ```bash
+   node -e "const {verificarPlan}=require('./scripts/lib/plan-lock'); console.log(JSON.stringify(verificarPlan('.planning/fases/0N-PLAN.md')))"
+   ```
+   Interpreta el resultado:
+   - `ok: true, modo: "firmado"` → el plan no fue mutado tras su aprobación.
+     Continúa con normalidad.
+   - `ok: true, modo: "legacy"` → plan aprobado SIN lock (creado antes de la
+     Fase 09, cláusula de gracia D-05). Muestra una **advertencia visible** al
+     usuario: "Plan en modo legacy (sin firma SHA256). Se ejecuta sin
+     verificación de integridad. Para firmarlo: `/swl:aprobar-plan N`." y
+     continúa.
+   - `ok: false, modo: "mutado"` → **DETENER ejecución**. El plan cambió tras la
+     firma. Reporta `hashEsperado` y `hashActual` y di: "El PLAN fue modificado
+     después de su aprobación. Revisa los cambios y vuelve a aprobarlo con
+     `/swl:aprobar-plan N` antes de ejecutar." NO proceder.
+   - `ok: false` con cualquier otro modo (`lock-corrupto`, `sin-firmar`,
+     `no-existe`) → DETENER y reportar el `motivo` exacto.
+
+   Repite esta verificación al inicio de cada slice (el plan no debe mutar
+   durante la ejecución — Requirement Freeze).
+
 Lee los tres archivos completos. Verifica estado de Git (`git status`, `git log --oneline -5`). Si hay cambios no commiteados, pregunta cómo proceder.
 
 **Nota sobre Requirement Freeze**: una vez que el plan está aprobado y la ejecución
@@ -147,7 +171,30 @@ Al completar todos los slices, genera `.planning/fases/0N-RESUMEN.md` con: slice
 
 Marca fase completada en HOJA-RUTA.md con fecha. Actualiza ESTADO.md con estado general.
 
-## Paso 8 — Reporte final
+**Liberar la fase activa** (gate G0): elimina `.planning/locks/fase-activa.json` —
+la fase ya no está en ejecución y `hooks/spec-gate.js` debe volver a advertir si se
+escribe código sin una nueva fase aprobada:
+
+```bash
+node -e "const fs=require('fs'); const p='.planning/locks/fase-activa.json'; if(fs.existsSync(p)){fs.unlinkSync(p); console.log('fase activa liberada')} else {console.log('sin fase activa que liberar')}"
+```
+
+NO eliminar el `.lock` del plan (`0N-PLAN.md.lock`) — ese es evidencia de
+aprobación versionada, no runtime.
+
+## Paso 8 — Verificación automática y reporte final
+
+**Verify automático (gate G4)**: tras generar RESUMEN.md y liberar la fase activa,
+invoca `/swl:verificar --until-converge` automáticamente — el cierre de fase ya no
+es un paso manual recomendado, es parte del flujo.
+
+- Opt-out: si el usuario invocó `/swl:ejecutar-fase N --sin-verify`, omite la
+  verificación y registra la desviación en el RESUMEN.md ("verificación diferida
+  por --sin-verify — razón: [la que dé el usuario]").
+- Si la verificación converge (Señal A): el VERIFICACION.md queda generado y el
+  reporte final lo incluye.
+- Si NO converge (Señal B/C) o queda abortada: reportar el estado del loop al
+  usuario — la fase NO se declara verificada.
 
 ```
 Fase N — [nombre] completada.
@@ -156,13 +203,13 @@ Slices implementados: [N de N]
 Commits creados: [N]
 Tests pasando: [N de N]
 Desviaciones del plan: [N, o "ninguna"]
+Verificación: [convergió en pasada K | diferida por --sin-verify | NO convergió — ver detalle]
 
 Archivos generados:
 - .planning/fases/0N-RESUMEN.md
+- .planning/fases/0N-VERIFICACION.md (verify automático)
 - .planning/ESTADO.md (actualizado)
 - .planning/HOJA-RUTA.md (actualizado)
-
-Próximo paso recomendado: /swl:verificar
 ```
 
 ## Reglas de comportamiento

package/comandos/swl/evolucionar.md

@@ -215,7 +215,7 @@ score_after = (evals_pass / evals_total) * 100 × factor_peso
 | `score_baseline - 5 <= score_after < score_baseline` | **Requiere revisión humana** — reportar diferencia; usuario decide si acepta la regresión menor o revierte |
 
 Los 3 casos registran evento en `.planning/evolution/evoluciones.jsonl` para el
-dashboard `/swl:evolucion-estado`.
+dashboard `/swl:status evolucion`.
 
 ### Regla de oro
 

package/comandos/swl/inbox.md

@@ -43,7 +43,7 @@ Por cada comando en la cola, decidir:
 | Tipo de contenido | Acción |
 |-------------------|--------|
 | Instrucción de trabajo clara ("arregla el bug X", "ejecuta pruebas") | Procesar como prompt del usuario. Ejecutar la tarea siguiendo el flujo normal SWL. |
-| Slash command (`/swl:salud`, `/swl:metricas`, etc.) | Invocar ese comando directamente. |
+| Slash command (`/swl:status salud`, `/swl:status metricas`, etc.) | Invocar ese comando directamente. |
 | Pregunta/consulta ("¿cómo va X?", "estado del release") | Responder con la información solicitada. Enviar respuesta al gateway si aplica. |
 | Feedback/corrección ("no uses Y", "prefiero Z") | Escribir a `.planning/evolution/feedback-queue.jsonl` con tipo correspondiente y marcar como procesado. |
 | Contenido ambiguo o sospechoso | Marcar como descartado con razón registrada. |

package/comandos/swl/instalar.md

@@ -185,7 +185,7 @@ Doctor:     <resultado>
 Siguiente paso:
   /swl:nuevo-proyecto    → si es un proyecto nuevo
   /swl:mapear-codebase   → si ya hay código existente
-  /swl:salud             → para diagnóstico profundo del sistema
+  /swl:status salud             → para diagnóstico profundo del sistema
 ```
 
 Si la instalación fue local, menciona: "Para instalar SWL en otro proyecto, abre Claude Code en ese proyecto y ejecuta `/swl:instalar` nuevamente."

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:status 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

@@ -146,7 +146,12 @@ El agente planificador-swl debe generar el plan con esta estructura exacta:
 ...
 
 ## Modelos y esquemas de datos
-[tablas, campos, tipos, constraints — si la fase introduce datos nuevos]
+[tablas, campos, tipos, constraints — si la fase introduce datos nuevos.
+Los schemas declarados aquí (Pydantic/Zod/JSON Schema/OpenAPI) son **contrato
+verificable**, parte de la spec: la tarea que los implementa se verifica con
+contract testing (`Skill("calidad-contract-testing")`), no solo con tests
+unitarios. Declarar el schema con la estrictez de la promesa real (requeridos
+marcados, sin campos extra implícitos).]
 
 ## Endpoints a implementar
 | Método | Ruta | Descripción | Roles permitidos |
@@ -161,10 +166,28 @@ 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 |
 |--------|---------|-------------|-----------|
 
+## Matriz REQ×T (obligatoria si el CONTEXTO tiene criterios REQ-NN)
+[tabla REQ → tareas que lo verifican. Cada tarea declara `**Verifica REQ**: REQ-XX`.
+Todo REQ sin tarea = plan NO apto para aprobación (aprobar-plan lo rechaza).
+La convención de cierre de cadena: commits con footer `Refs: REQ-NN` y tests con
+marker `# verifica: REQ-NN` (Python) / `// verifica: REQ-NN` (JS/TS) — validada
+por `scripts/verificar-trazabilidad.js`. Omitir solo en CONTEXTOs legacy sin REQ-IDs.]
+
+| REQ | Tareas que lo verifican |
+|-----|------------------------|
+
 ## Criterios de aceptación de la fase
 [copia del CONTEXTO.md, verificados contra el plan]
 
@@ -182,6 +205,7 @@ Una vez que el agente planificador-swl produce el PLAN.md, ejecuta una revisión
 - [ ] ¿El orden de implementación respeta las dependencias (BD → service → endpoint → frontend)?
 - [ ] ¿Hay criterios de verificación para cada slice?
 - [ ] ¿Los criterios de aceptación de la fase están cubiertos por los slices?
+- [ ] Si el CONTEXTO tiene REQ-IDs: ¿la matriz REQ×T cubre TODOS los REQ (cero huérfanos)?
 - [ ] ¿Los riesgos ALTO del CONTEXTO.md están mitigados en el plan?
 - [ ] ¿Hay tests especificados para cada área crítica?
 - [ ] ¿Hay tareas HITL claramente marcadas?

package/comandos/swl/plugins.md

@@ -122,7 +122,7 @@ echo "Plugin <nombre> v<version> instalado en _userland/plugins/<nombre>/"
 echo "Componentes: agentes=$(count), skills=$(count), reglas=$(count), hooks=$(count)"
 ```
 
-Indicar al usuario que ejecute `/swl:salud` para verificar integridad global.
+Indicar al usuario que ejecute `/swl:status salud` para verificar integridad global.
 
 ---