@saulwade/swl-ses 1.5.0 → 1.5.2

package/comandos/swl/nemesis.md

@@ -1,19 +1,23 @@
 ---
 name: swl:nemesis
 description: >
-  Auditoría iterativa Feynman + State Inconsistency (loop hasta convergencia).
-  Invoca el agente nemesis-auditor-swl con los 2 skills subordinados.
-  Persiste hallazgos en .planning/audit/findings/.
-allowed-tools: [Read, Grep, Glob, Bash, Write, Agent]
-argument-hint: "[--pass1 | --pass2 | --continue | --modulo <ruta>]"
+  Auditoría iterativa Feynman + State Inconsistency con loop evaluator-optimizer
+  opcional. Sin flag --remediar: solo audita (comportamiento clásico de
+  v1.5.x). Con --remediar: ciclo audit→fix→re-audit hasta convergencia
+  (max 3 iteraciones, Recovery Catalog si no converge). Modo redistribuido
+  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]"
 ---
 
-# /swl:nemesis — Auditoría iterativa de profundidad
+# /swl:nemesis — Auditoría iterativa con remediación opt-in
 
-Dos auditores en loop: Feynman interroga suposiciones línea por línea; State
-Inconsistency mapea pares de estado acoplado y encuentra mutaciones
-incompletas. Cada pasada alimenta la siguiente hasta que no aparecen hallazgos
-nuevos o se llega al máximo de 6 pasadas.
+Dos auditores en loop interno (Feynman + State Inconsistency) detectan bugs de
+profundidad que el código superficialmente correcto esconde. Con el flag
+`--remediar` el comando entra en modo **evaluator-optimizer** (patrón oficial
+de Anthropic, ADR-0021): el agente nemesis evalúa, el orquestador-swl remedia,
+y el ciclo continúa hasta convergencia o agotar el guardrail de 3 iteraciones.
 
 ## Cuándo invocar
 
@@ -25,6 +29,8 @@ nuevos o se llega al máximo de 6 pasadas.
   usar Nemesis para encontrar el patrón de fallo subyacente.
 - Para módulos legacy con alta deuda técnica donde los tests no cubren los
   caminos de estado.
+- **Para cerrar el loop audit→fix→re-audit en una sola invocación**: usar
+  `/swl:nemesis --remediar`. La autonomía es opt-in.
 
 ## Cuándo NO invocar
 
@@ -33,56 +39,186 @@ nuevos o se llega al máximo de 6 pasadas.
   `/swl:revisar` en su lugar.
 - El proyecto no tiene `agentes/nemesis-auditor-swl.md` instalado — verificar
   con `ls agentes/ | grep nemesis` antes de invocar.
-- La tarea urgente es un hotfix en producción — Nemesis es deliberado (8-20
-  turnos); en incidente activo, usar `/swl:verificar` acotado.
+- La tarea urgente es un hotfix en producción — Nemesis con `--remediar` es
+  deliberado (8-30 turnos); en incidente activo, usar `/swl:verificar` acotado.
 
 ## Modos disponibles
 
 | Modo | Flag | Descripción |
 |---|---|---|
-| Loop completo (default) | (sin flag) | Pasada 1 (Feynman) + Pasada 2 (State) + N pasadas alternadas hasta convergencia, máximo 6 en total |
-| Solo Feynman | `--pass1` | Una pasada Feynman exhaustiva; no ejecuta State |
-| Solo State | `--pass2` | Una pasada State Inconsistency; puede alimentarse con findings previos de Feynman si existen en `.planning/audit/findings/` |
-| Retomar | `--continue` | Continúa desde la última pasada registrada en `.planning/audit/findings/`; útil si la sesión se interrumpió |
-| Acotar módulo | `--modulo <ruta>` | Limita el scope a un archivo o subdirectorio específico; se puede combinar con cualquier otro flag |
+| **Solo auditar** (default) | (sin flag) | Pasada 1 (Feynman) + Pasada 2 (State) + N alternadas hasta convergencia interna, máximo 6 pasadas. Entrega reporte. NO remedia. Retrocompatible con v1.5.x. |
+| **Loop completo** | `--remediar` | Evaluator-optimizer: audita → invoca `orquestador-swl` con hallazgos → re-audita. Max 3 iteraciones. Convergencia cuando status=PASS. Recovery Catalog si no converge. |
+| Solo Feynman | `--pass1` | Una pasada Feynman exhaustiva; no ejecuta State. Ortogonal a `--remediar`. |
+| Solo State | `--pass2` | Una pasada State Inconsistency; puede alimentarse con findings previos. |
+| Retomar | `--continue` | Continúa desde la última iteración registrada en `.planning/audit/findings/`. |
+| 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). |
 
-## Qué produce
+## Flujo completo con `--remediar`
 
-Todos los archivos se crean en `.planning/audit/findings/`:
+```
+# iter usa indexing 1-based para alinear con el agente y los output paths
+# (.planning/audit/findings/iter-1/, iter-2/, iter-3/). Max 3 iteraciones.
+iter = 1
+MAX_ITER = 3
+evaluacion = null
 
-| Archivo | Cuándo se genera |
-|---|---|
-| `feynman-pass[N].md` | Al completar cada pasada Feynman (N = número de pasada) |
-| `state-pass[N].md` | Al completar cada pasada State Inconsistency |
-| `nemesis-verified.md` | Al final del loop completo; consolida todos los hallazgos con estado de verificación |
+# Fase 0 del comando: análisis del scope
+loc_total, modulos = analizar_scope(modulo_arg or "directorio actual")
 
-Si el directorio `.planning/audit/findings/` no existe, el agente lo crea antes
-de la primera escritura.
+# Decisión de redistribuir:
+#   1. --redistribuir explícito siempre activa redistribución (override del usuario).
+#   2. --modulo respeta el scope acotado por el usuario y NO redistribuye, aunque
+#      excede umbrales. El usuario ya delimitó intencionalmente.
+#   3. Sin --modulo: umbrales automáticos (> 1500 LOC ó > 5 módulos distintos).
+redistribuir = flag_redistribuir or (
+    not flag_modulo and (loc_total > 1500 or modulos > 5)
+)
 
-## Cómo interpretar el reporte
+if redistribuir:
+    cargar Skill("nemesis-redistribuir")
+    plan = generar_plan_redistribuido(scope)
+    persistir plan en .planning/audit/nemesis-plan.json
+    sub_scopes = plan.sub_scopes
+else:
+    sub_scopes = [scope_unico]
+
+# Fase 1+: loop evaluator-optimizer (iter ∈ {1, 2, 3})
+while iter <= MAX_ITER:
+    # Evaluator: invocar nemesis-auditor-swl una vez por sub-scope.
+    # En modo redistribuido cada sub_scope tiene un `id` (declarado en
+    # nemesis-plan.json) que el agente USA para construir la ruta de output
+    # `.planning/audit/findings/iter-N/<sub_id>/`. Sin sub_id, los reportes
+    # se sobrescribirían entre sub-scopes. En modo monolítico sub_id queda
+    # `null` y el agente escribe a `iter-N/` (sin subdirectorio).
+    for sub_scope in sub_scopes:
+        sub_id = sub_scope.id if redistribuir else null
+        invocar(nemesis-auditor-swl, sub_scope, iter=iter, sub_id=sub_id)
+        # Produce:
+        #   redistribuido → .planning/audit/findings/iter-N/<sub_id>/evaluacion.json + .md
+        #   monolítico    → .planning/audit/findings/iter-N/evaluacion.json + .md
+
+    # Consolidar (si modo redistribuido)
+    evaluacion = consolidar_evaluaciones(iter)
+    # Produce: .planning/audit/findings/iter-N/evaluacion.json consolidado
+    # (en modo monolítico no hay consolidación: el archivo ya está en iter-N/)
+
+    # Decisión sobre el JSON consolidado
+    if evaluacion.veredicto.status == "PASS":
+        emitir_reporte_final(evaluacion)
+        return { exito: True, iters: iter, evaluacion }   # convergencia
+
+    if not flag_remediar:
+        emitir_reporte(evaluacion)
+        return { exito: False, iters: iter, evaluacion }  # solo audita
+
+    if evaluacion.veredicto.status == "FAIL":
+        return activar_recovery_catalog("escalate", evaluacion.veredicto.razon_si_fail)
 
-Cada hallazgo en los archivos de pasada usa este formato:
+    if not evaluacion.veredicto.puede_remediar_automaticamente:
+        return activar_recovery_catalog("escalate", "Hallazgos no auto-remediables")
 
+    # Generator: invocar orquestador-swl con hallazgos como input
+    invocar(
+        orquestador-swl,
+        hallazgos=evaluacion.hallazgos,
+        feedback=evaluacion,
+        intentos_previos=hallazgos_de_iters_anteriores(iter),
+        iter=iter,
+    )
+    iter += 1
+
+# max-iter agotado sin PASS
+return activar_recovery_catalog_secuencial(evaluacion)
+# orden: reprompt(1ª) → reduce-autonomy(2ª) → escalate(3ª)
 ```
-## [SEVERIDAD] Título del hallazgo
 
-**Discovery path**: Feynman-only | State-only | Cross-feed Pass N → Pass M
-**Verification**: Code trace | PoC test | Both
-**Líneas afectadas**: archivo:L1-L2
+Los `return` son explícitos. Sin `--remediar`, el `return` del bloque
+`if not flag_remediar` impide que el flujo alcance la invocación del
+orquestador. La retrocompatibilidad es por construcción.
+
+## Activación de redistribución (Fase 0)
+
+| Condición | Acción |
+|---|---|
+| `loc_total > 1500` | Cargar `Skill("nemesis-redistribuir")` |
+| `archivos_modulos_distintos > 5` | Cargar `Skill("nemesis-redistribuir")` |
+| `--redistribuir` explícito | Cargar `Skill("nemesis-redistribuir")` |
+| `--modulo <ruta>` con scope acotado | NO redistribuir (respetar decisión explícita del usuario) |
+
+Cuando se activa, el comando registra un nudge en `.planning/nudges.jsonl`:
+
+```json
+{
+  "timestamp": "<ISO 8601>",
+  "tipo": "nemesis-redistribuido",
+  "mutation_category": "scope-adaptation",
+  "risk_level": "low",
+  "razon": "loc_total=3170 (>1500)",
+  "sub_scopes": 3,
+  "archivo_plan": ".planning/audit/nemesis-plan.json"
+}
+```
+
+## Recovery Catalog cuando max-iter sin PASS
+
+Tras 3 iteraciones del loop sin alcanzar `status=PASS`, el comando aplica en
+orden estricto el catálogo de `reglas/seguridad-agentes.md § Recovery Catalog`:
+
+1. **reprompt** (excedencia 1): re-invoca al orquestador con feedback reforzado
+   (qué hallazgos quedaron sin resolver, constraints adicionales). Una sola vez.
+2. **reduce-autonomy** (excedencia 2 consecutiva): baja `nivelRiesgo` efectivo,
+   pide confirmación al usuario antes de cada acción del generator.
+3. **escalate** (excedencia 3): pausa la cadena, invoca `notificador-swl`,
+   espera decisión humana del usuario.
+4. **terminate**: solo si el evaluator detecta violación de regla de seguridad
+   explícita (no por simple no-convergencia).
+
+Cada activación se registra en `.planning/nudges.jsonl` con
+`mutation_category: repair` y `risk_level` proporcional.
+
+## Qué produce
+
+Estructura de salida bajo `.planning/audit/findings/`:
 
-Descripción del problema y por qué es un bug y no solo código sospechoso.
 ```
+.planning/audit/findings/
+├── nemesis-plan.json                     # solo si modo redistribuido
+├── iter-1/
+│   ├── feynman-pass1.md                  # output crudo Feynman
+│   ├── feynman-pass2.md                  # si hubo segunda pasada Feynman
+│   ├── state-pass1.md                    # output crudo State
+│   ├── state-pass2.md                    # si hubo segunda pasada State
+│   ├── nemesis-verified.md               # reporte legible consolidado
+│   ├── evaluacion.json                   # veredicto estructurado
+│   ├── sub-1/                            # solo en modo redistribuido
+│   │   ├── feynman-pass1.md
+│   │   ├── state-pass1.md
+│   │   ├── nemesis-verified.md
+│   │   └── evaluacion.json
+│   ├── sub-2/
+│   └── sub-3/
+├── iter-2/                               # solo si --remediar y no convergió en iter 1
+│   └── (mismo formato)
+└── iter-3/                               # último intento si --remediar y no convergió
+    └── (mismo formato)
+```
+
+Cada `evaluacion.json` sigue el schema `nemesis-evaluacion-json` v1.0.0.
+
+## Cómo interpretar el reporte
 
-**Severidades**:
+### Severidades
 
 | Nivel | Criterio |
 |---|---|
-| CRITICAL | Explotable sin precondiciones; pérdida de datos o control total |
-| HIGH | Explotable bajo condiciones razonables; impacto severo |
-| MEDIUM | Requiere condiciones específicas; impacto moderado |
-| LOW | Impacto menor o difícil de explotar; documentar para trazabilidad |
+| CRÍTICO | Explotable sin precondiciones; pérdida de datos o control total |
+| ALTO | Explotable bajo condiciones razonables; impacto severo |
+| MEDIO | Requiere condiciones específicas; impacto moderado |
+| BAJO | Impacto menor o difícil de explotar; documentar para trazabilidad |
 
-**Discovery path** indica cuándo se encontró:
+### Discovery path
 
 - `Feynman-only`: Feynman lo detectó; State no lo confirmó ni refutó.
 - `State-only`: State Inconsistency lo encontró analizando mutaciones.
@@ -90,33 +226,71 @@ Descripción del problema y por qué es un bug y no solo código sospechoso.
   State lo confirmó como bug real en la pasada M (o viceversa). Estos
   hallazgos son los más confiables.
 
-**Verification** indica la evidencia disponible:
+### Veredicto JSON
 
-- `Code trace`: el path al bug se puede seguir leyendo el código.
-- `PoC test`: hay un caso de prueba que demuestra el comportamiento incorrecto.
-- `Both`: lo más sólido; implica un test listo para agregar a la suite.
+- `status: "PASS"` — convergencia. El loop terminó. 0 críticos + 0 altos.
+- `status: "NEEDS_IMPROVEMENT"` — el loop puede continuar (si `--remediar`).
+- `status: "FAIL"` — requiere intervención humana. El loop se detiene.
 
 ## Costo estimado
 
 | Modo | Turnos aproximados |
 |---|---|
-| Loop completo, módulo pequeño (< 500 LOC) | 8-12 turnos |
-| Loop completo, módulo mediano (500-2000 LOC) | 12-18 turnos |
-| Loop completo, módulo grande (> 2000 LOC) | 18-30 turnos |
-| Solo `--pass1` o `--pass2` | 4-8 turnos |
+| Solo auditar, módulo pequeño (< 500 LOC) | 8-12 |
+| Solo auditar, módulo mediano (500-1500 LOC) | 12-18 |
+| Solo auditar, módulo grande (> 1500 LOC, modo redistribuido) | 18-30 |
+| `--remediar`, módulo pequeño, converge en 1 iter | 12-18 |
+| `--remediar`, módulo mediano, 2-3 iters | 20-40 |
+| `--remediar`, módulo grande con redistribución, 3 iters | 40-70 |
+| Solo `--pass1` o `--pass2` | 4-8 |
 
-Para módulos mayores a 5000 LOC, usar `--modulo <ruta>` para acotar el scope.
-Un loop sobre un módulo gigante puede tomar 30+ turnos sin garantía de que los
-hallazgos sean más útiles que los de un subconjunto bien elegido.
+El costo del modo `--remediar` es 3-5× el del modo solo auditar. Es opt-in
+deliberado del usuario, no default.
 
 ## Ejemplos de invocación
 
+```bash
+# Modo clásico (retrocompatibilidad v1.5.x): solo audita
+/swl:nemesis
+/swl:nemesis --modulo backend/app/auth
+
+# Solo una pasada específica
+/swl:nemesis --pass1 --modulo backend/app/auth
+/swl:nemesis --pass2
+
+# Retomar auditoría interrumpida
+/swl:nemesis --continue
+
+# Modo evaluator-optimizer completo (nuevo en v1.5.2)
+/swl:nemesis --remediar --modulo backend/app/auth
+/swl:nemesis --remediar                              # scope = directorio actual
+/swl:nemesis --remediar --modulo database/schemas    # módulo grande → activa redistribución
+
+# Forzar redistribución aunque scope sea pequeño
+/swl:nemesis --redistribuir --modulo backend/app/auth
 ```
-/swl:nemesis                               # loop completo del proyecto
-/swl:nemesis --modulo src/auth             # acotado al módulo auth
-/swl:nemesis --pass1 --modulo src/auth     # solo Feynman sobre auth
-/swl:nemesis --pass2                       # solo State sobre findings existentes
-/swl:nemesis --continue                    # retoma desde la última pasada guardada
-```
+
+## Regla obligatoria sobre las citas archivo:línea del reporte
+
+Cuando se actúe sobre un hallazgo `archivo:linea` reportado por el evaluator,
+**verificar la cita** con `Read` antes de aplicar el fix. Esto es directiva de
+la regla global `verificar-citas-normativas.md` Familia 2 — citas
+archivo:línea en reportes de auditoría DEBEN re-verificarse contra el código
+actual antes de tomar acción. El loop de remediación NO sustituye esta
+verificación — el generator (orquestador-swl + agentes de stack) debe leer el
+archivo en su HEAD actual antes de modificar.
+
+## Referencias
+
+- ADR-0021: `nemesis-evaluator-optimizer` — diseño completo del patrón.
+- ADR-0018: introducción del agente nemesis-auditor-swl.
+- `agentes/nemesis-auditor-swl.md`: agente evaluator.
+- `agentes/orquestador-swl.md`: agente generator (delega a depurador, backend-*, frontend-*, etc.).
+- `habilidades/nemesis-evaluacion-json/SKILL.md`: schema del JSON estructurado.
+- `habilidades/nemesis-redistribuir/SKILL.md`: modo redistribuido para scope grande.
+- `reglas/seguridad-agentes.md § Recovery Catalog`: manejo de no-convergencia.
+- Cookbook Anthropic, patrón evaluator-optimizer:
+  https://github.com/anthropics/anthropic-cookbook/blob/main/patterns/agents/evaluator_optimizer.ipynb
 
 <!-- Adaptado de nemesis-auditor-main bajo MIT License (transmissions11/nemesis-auditor) -->
+<!-- Loop evaluator-optimizer agregado en v1.6.0 (ADR-0021), 2026-05-16 -->