@saulwade/swl-ses 1.5.1 → 1.6.0

package/habilidades/meta-skills-estandar/SKILL.md

@@ -9,12 +9,12 @@ description: >
   idiomas de framework y mapeo a frameworks de seguridad. Cargar cuando se
   esté escribiendo o auditando un SKILL.md y se necesiten patrones avanzados
   que no están en la regla core.
-version: "1.0.1"
+version: "1.1.1"
 evolved: true
-evolved-from: "1.0.0"
-evolved-at: "2026-05-15"
+evolved-from: "1.1.0"
+evolved-at: "2026-05-16"
 evolved-by: "aprender"
-evolved-note: "Gotcha 'absorber naming externo al portar patrón valioso' agregado. Origen: instrucción explícita del usuario en sesión 2026-05-15 al renombrar 'kiro-review-protocol' → 'protocolo-revision-swl' durante absorción cc-sdd."
+evolved-note: "v1.1.0 MINOR: 3 secciones nuevas (contratos controller↔worker + return explícito + evaluator-optimizer). v1.1.1 PATCH: corrige inconsistencia interna — ejemplos de la sección 'Pseudocódigo con return' usaban iter=0/while iter<3, contradiciendo el contrato 1-based de la sección anterior. Mismo skill que enseña off-by-one no debe cometerlo en sus ejemplos."
 herramientasPermitidas: [Read, Write, Edit]
 exclusiones:
   - "No cargar si solo se necesita el frontmatter obligatorio, el límite de líneas o la estructura de directorio — eso está en la regla core `reglas/skills-estandar.md` que se carga siempre."
@@ -321,3 +321,206 @@ al caso en cuestión en lugar de los tres.
 - Evaluador de skills: `comandos/swl/evaluar-skill.md` (usa W009, W010, W011).
 - Schema: `schemas/skill-frontmatter.schema.json`.
 - Normalizador de campos legacy: `scripts/lib/skill-normalizer.js`.
+
+---
+
+## Contratos controller ↔ worker en skills/agentes
+
+Cuando un skill orquesta un loop iterativo entre un **controller** (comando
+o agente padre) y un **worker** (agente o sub-skill invocado N veces), el
+contrato entre ambos DEBE explicitar tres dimensiones:
+
+| Dimensión | Pregunta | Riesgo si se omite |
+|---|---|---|
+| **Indexing** | ¿1-based o 0-based? | Off-by-one entre output paths (`iter-N/`) y argumentos al worker |
+| **Identificadores únicos** | ¿Cada sub-invocación tiene un ID propio? | Colisiones de output cuando hay paralelismo o sub-scopes |
+| **Convergencia** | ¿Cuándo termina el loop? `PASS` explícito, max-iter, ambos | Loops infinitos o terminación prematura |
+
+### Anti-patrón: convenciones distintas entre capas
+
+```
+# Controller (comando): zero-based
+iter = 0
+while iter < 3:
+    invocar(worker, iter=iter)
+    iter += 1
+
+# Worker (agente): one-based
+"Recibo iter ∈ {1, 2, 3}. Escribo a iter-N/."
+```
+
+Resultado: cuando el controller pasa `iter=0`, el worker espera `iter=1` y
+escribe a `iter-0/` que la documentación no contempla. El path documentado
+`iter-1/` nunca se llena hasta la segunda iteración. Bug silencioso —
+detectable solo cuando se intenta leer `iter-N-1/` para correlación entre
+iteraciones.
+
+### Pattern correcto: contrato explícito documentado
+
+```python
+# Controller (comando) — usar mismo indexing que el worker
+iter = 1
+MAX_ITER = 3
+while iter <= MAX_ITER:
+    invocar(worker, iter=iter, sub_id=sub_scope.id if redistribuir else None)
+    iter += 1
+```
+
+```yaml
+# Agente (worker) — declara qué recibe
+## Iteración del loop
+El agente recibe:
+- `iter`: entero ∈ {1, 2, 3} (one-indexed, coherente con paths `iter-N/`)
+- `sub_id`: opcional, identificador del sub-scope (string o null)
+- En iteraciones >= 2, ruta del output previo (`iter-<N-1>/`)
+
+| Modo | sub_id | Output |
+|------|--------|--------|
+| Monolítico | null | `iter-N/<archivos>` |
+| Redistribuido | "sub-1-X" | `iter-N/<sub_id>/<archivos>` |
+```
+
+### Origen
+
+Bug detectado en sesión 2026-05-16 del proyecto swl-ses (PR #28):
+`/swl:nemesis --remediar` con `iter=0` en el controller y agente esperando
+`iter ∈ {1,2,3}`. Adicional: invocación al worker sin pasar `sub_id` en
+modo redistribuido → todos los sub-scopes escribían al mismo path y se
+sobreescribían entre sí (fix en PR #29).
+
+Mantener el contrato comando ↔ agente ↔ skill ↔ skill `nemesis-redistribuir`
+coherente requiere documentarlo en los **tres** archivos: comando (controller),
+agente (worker) y skill operativo (orquestación). Inconsistencia en cualquiera
+de los tres = bug.
+
+---
+
+## Pseudocódigo en ADRs y skills: `return` siempre explícitos
+
+Cuando un ADR o skill describe lógica de control con pseudocódigo, las
+salidas tempranas DEBEN ser explícitas — no implícitas a través de naming
+de funciones helper.
+
+### Anti-patrón: nombre semántico sin `return`
+
+```
+# Indexing 1-based para no mezclar dos problemas (helper sin return +
+# off-by-one) en el mismo ejemplo. Aquí el bug pedagógico es solo el
+# helper ambiguo.
+iter = 1
+MAX_ITER = 3
+while iter <= MAX_ITER:
+    eval = invocar(evaluator, iter=iter)
+    if eval.status == "PASS": break
+    if not flag_remediar: emitir_reporte_y_salir()   # ← ¿sale del while? ¿del scope completo?
+    invocar(generator, eval.hallazgos)
+    iter += 1
+```
+
+Lector estricto puede interpretar `emitir_reporte_y_salir()` como
+"emite el reporte y retorna del scope completo" O como "función con
+side effect cuyo nombre prometía salida pero no la ejecuta". Ambigüedad
+detectada por revisor externo y reportada como bug del ADR.
+
+### Pattern correcto: `return` explícitos con valor
+
+```
+# Indexing 1-based coherente con la sección "Contratos controller ↔ worker"
+# arriba. Si este skill enseña a evitar off-by-one entre capas, sus propios
+# ejemplos deben usar el mismo indexing que el contrato canónico.
+iter = 1
+MAX_ITER = 3
+evaluacion = null
+while iter <= MAX_ITER:
+    evaluacion = invocar(evaluator, iter=iter)
+    if evaluacion.status == "PASS":
+        return { exito: True, iters: iter, evaluacion }   # convergencia
+    if not flag_remediar:
+        emitir_reporte(evaluacion)
+        return { exito: False, iters: iter, evaluacion }  # solo audita
+    invocar(generator, evaluacion.hallazgos)
+    iter += 1
+return activar_recovery_catalog(evaluacion)               # max-iter agotado
+```
+
+Cada path de salida es:
+- Explícito (`return` literal en pseudocódigo)
+- Tipado (objeto con campos esperados)
+- Comentado con la condición que lo dispara
+- Coherente con el indexing del contrato controller ↔ worker (1-based)
+
+### Regla
+
+El pseudocódigo de un ADR o skill es **contrato visual** entre el documento
+y el implementador. Funciones helper con nombres semánticos (`emitir_*`,
+`escalar_*`, `salir_*`) son aceptables PERO siempre acompañadas de `return`
+explícito en el pseudocódigo, no solo en la implementación.
+
+### Origen
+
+Bug del ADR-0021 detectado por revisor externo (sesión 2026-05-16):
+*"`emitir_reporte_y_salir()` no muestra explícitamente que sale del loop.
+Si la función solo emite output, la ejecución continúa a la siguiente
+línea, violando la retrocompatibilidad."* Verificado y corregido en
+el mismo ADR.
+
+---
+
+## Patrón evaluator-optimizer aplicado a auditoría
+
+Cuando un skill o agente implementa el patrón `audit → fix → re-audit`,
+adoptar el **patrón canónico evaluator-optimizer** del [cookbook oficial
+de Anthropic](https://github.com/anthropics/anthropic-cookbook/blob/main/patterns/agents/evaluator_optimizer.ipynb)
+en lugar de re-inventar nomenclatura propia.
+
+### Mapeo del patrón
+
+| Componente del cookbook | Equivalente en SWL |
+|---|---|
+| `generator(prompt, task, context)` | Agente que aplica correcciones (ej: `orquestador-swl` delegando a `depurador-swl`, `backend-python-swl`, etc.) |
+| `evaluator(prompt, content, task)` | Agente auditor (ej: `nemesis-auditor-swl`, `revisor-codigo-swl`) que produce veredicto estructurado |
+| Veredicto: `PASS / NEEDS_IMPROVEMENT / FAIL` | Status del JSON estructurado del evaluator |
+| `loop()` con `while evaluation != "PASS"` | Controller en el comando (no en el agente — ver sección "Contratos controller ↔ worker") |
+| Memoria de intentos previos | `.planning/<modulo>/iter-N/` con outputs de cada iteración |
+
+### Reglas obligatorias del patrón
+
+1. **Evaluator y generator NUNCA son el mismo agente**. La separación
+   revisor/ejecutor de `reglas/gobernanza.md` se mantiene.
+2. **El loop vive en el controller (comando)**, no en el evaluator ni en
+   el generator. Esto preserva privilegio mínimo del evaluator (sin Agent
+   tool) y delega orquestación a la capa correcta.
+3. **Convergencia por `PASS` explícito + max-iter como guardrail**. Anthropic
+   recomienda terminación natural; el max-iter (típicamente 3) evita loops
+   infinitos sin sustituir el criterio principal.
+4. **Output estructurado del evaluator** (JSON con schema versionado). El
+   markdown legible es complementario, no source of truth.
+5. **Recovery Catalog cuando max-iter agotado sin PASS**: aplicar
+   `reprompt → reduce-autonomy → escalate → terminate` según
+   `reglas/seguridad-agentes.md`.
+
+### Ejemplo aplicado
+
+ADR-0021 (`/swl:nemesis --remediar`):
+- Evaluator: `nemesis-auditor-swl` (atómico, sin Agent tool).
+- Generator: `orquestador-swl` invocado con hallazgos como input.
+- Loop: en `comandos/swl/nemesis.md` (controller).
+- Convergencia: `evaluacion.status == "PASS"`.
+- Max-iter: 3 hardcoded en comando.
+- Recovery: catálogo formal en escalada secuencial.
+
+### Cuándo NO aplicar este patrón
+
+- Audit one-shot sin remediación automática: aplicar solo el evaluator,
+  entregar reporte, fin.
+- Cuando el evaluator no puede emitir veredicto estructurado (ejemplo:
+  análisis de UX subjetivo): el patrón requiere clasificación binaria
+  PASS/no-PASS, no opina.
+- Para tareas donde el costo del loop (3-5× tokens) supera el valor de
+  la convergencia automática.
+
+### Origen y referencia
+
+Adoptado formalmente en swl-ses v1.5.2 vía ADR-0021. Citar el cookbook
+Anthropic directamente en ADRs evita re-inventar terminología y facilita
+la integración con otros sistemas que sigan el mismo patrón.

package/habilidades/meta-skills-estandar/recursos/convencion-examples.md

@@ -1,93 +1,93 @@
-# Convención `EXAMPLES.md` — recurso opcional para skills críticos
-
-Convención **opcional** para skills cuyo valor depende de ejemplos concretos
-con diff MAL → BIEN. Esta convención NO es retroactiva: las 63 carpetas
-`recursos/` existentes en `habilidades/` no se renombran. Solo aplica a:
-
-- Skills nuevos cuyo dominio se entiende mejor con ejemplos lado a lado.
-- Skills existentes que reciban actualización mayor y agreguen ejemplos.
-
----
-
-## Cuándo aplicarla
-
-Aplicar cuando:
-
-- El skill prescribe **decisiones técnicas** o **patrones** cuyo error es
-  sutil sin un caso concreto (ej: anti-patrones de async, gotchas de framework,
-  decisiones arquitecturales).
-- El skill se beneficia de mostrar 2-4 ejemplos lado a lado: el caso aplicado
-  correctamente vs el caso degenerado.
-- Los ejemplos suman > 100 líneas y meterlos en SKILL.md lo pasaría del
-  límite de 300 líneas.
-
-NO aplicar cuando:
-
-- El skill ya tiene `recursos/` con archivos temáticos específicos
-  (ej: `meta-skills-estandar/recursos/anti-patrones-y-leyes.md`). El nombre
-  temático es más informativo que `EXAMPLES.md`.
-- El skill es un how-to procedural sin antipatrones contrastables.
-- El skill tiene < 80 líneas en SKILL.md y los ejemplos caben en línea.
-
----
-
-## Estructura recomendada
-
-```
-habilidades/<skill-name>/
-├── SKILL.md
-└── recursos/
-    └── EXAMPLES.md
-```
-
-`SKILL.md` enlaza al final con:
-
-```markdown
-Para ejemplos concretos de aplicación, ver [`recursos/EXAMPLES.md`](recursos/EXAMPLES.md).
-```
-
-`EXAMPLES.md` contiene 2-4 ejemplos siguiendo el patrón:
-
-```markdown
-## Ejemplo N — [título corto del escenario]
-
-**Contexto**: [1-2 líneas]
-
-### ❌ Sin <skill-name> (hipotético)
-[código o descripción del enfoque incorrecto + consecuencia observable]
-
-### ✓ Con <skill-name>
-[código o descripción del enfoque correcto + por qué evita la consecuencia]
-```
-
-Cierre de `EXAMPLES.md`: tabla resumen de los ejemplos con la dimensión
-clave que cambió (costo, tiempo, severidad de bug, etc.).
-
----
-
-## Por qué OPCIONAL y no obligatoria
-
-- 63 carpetas `recursos/` ya existen con nomenclatura temática
-  (`anti-patrones-y-leyes.md`, `frameworks-seguridad.md`,
-  `idiomas-framework.md`). Forzar `EXAMPLES.md` rompería información
-  semántica del nombre.
-- La regla core `reglas/skills-estandar.md` ya prescribe que `SKILL.md`
-  no exceda 300 líneas y que los `recursos/` se nombren en kebab-case
-  con sufijo `.md` — esa regla cubre el 95% de los casos.
-- Esta convención **complementa** la regla core para skills donde un nombre
-  semántico genérico (`EXAMPLES.md`) comunica mejor el contenido que un
-  nombre específico (ej: `casos-decisiones-arquitecturales.md` es más largo
-  y menos buscable).
-
----
-
-## Origen
-
-Patrón observado en repos externos analizados el 2026-05-09
-(`temp/agent-skills-main`, `temp/andrej-karpathy-skills-main`):
-varios skills críticos exponen un `EXAMPLES.md` con diffs MAL/BIEN
-auto-cargable como referencia rápida del agente.
-
-Adoptado en `habilidades/doubt-driven-review/recursos/EXAMPLES.md` como
-primera aplicación. Casos futuros: skills de decisiones arquitecturales,
-seguridad, debugging avanzado.
+# Convención `EXAMPLES.md` — recurso opcional para skills críticos
+
+Convención **opcional** para skills cuyo valor depende de ejemplos concretos
+con diff MAL → BIEN. Esta convención NO es retroactiva: las 63 carpetas
+`recursos/` existentes en `habilidades/` no se renombran. Solo aplica a:
+
+- Skills nuevos cuyo dominio se entiende mejor con ejemplos lado a lado.
+- Skills existentes que reciban actualización mayor y agreguen ejemplos.
+
+---
+
+## Cuándo aplicarla
+
+Aplicar cuando:
+
+- El skill prescribe **decisiones técnicas** o **patrones** cuyo error es
+  sutil sin un caso concreto (ej: anti-patrones de async, gotchas de framework,
+  decisiones arquitecturales).
+- El skill se beneficia de mostrar 2-4 ejemplos lado a lado: el caso aplicado
+  correctamente vs el caso degenerado.
+- Los ejemplos suman > 100 líneas y meterlos en SKILL.md lo pasaría del
+  límite de 300 líneas.
+
+NO aplicar cuando:
+
+- El skill ya tiene `recursos/` con archivos temáticos específicos
+  (ej: `meta-skills-estandar/recursos/anti-patrones-y-leyes.md`). El nombre
+  temático es más informativo que `EXAMPLES.md`.
+- El skill es un how-to procedural sin antipatrones contrastables.
+- El skill tiene < 80 líneas en SKILL.md y los ejemplos caben en línea.
+
+---
+
+## Estructura recomendada
+
+```
+habilidades/<skill-name>/
+├── SKILL.md
+└── recursos/
+    └── EXAMPLES.md
+```
+
+`SKILL.md` enlaza al final con:
+
+```markdown
+Para ejemplos concretos de aplicación, ver [`recursos/EXAMPLES.md`](recursos/EXAMPLES.md).
+```
+
+`EXAMPLES.md` contiene 2-4 ejemplos siguiendo el patrón:
+
+```markdown
+## Ejemplo N — [título corto del escenario]
+
+**Contexto**: [1-2 líneas]
+
+### ❌ Sin <skill-name> (hipotético)
+[código o descripción del enfoque incorrecto + consecuencia observable]
+
+### ✓ Con <skill-name>
+[código o descripción del enfoque correcto + por qué evita la consecuencia]
+```
+
+Cierre de `EXAMPLES.md`: tabla resumen de los ejemplos con la dimensión
+clave que cambió (costo, tiempo, severidad de bug, etc.).
+
+---
+
+## Por qué OPCIONAL y no obligatoria
+
+- 63 carpetas `recursos/` ya existen con nomenclatura temática
+  (`anti-patrones-y-leyes.md`, `frameworks-seguridad.md`,
+  `idiomas-framework.md`). Forzar `EXAMPLES.md` rompería información
+  semántica del nombre.
+- La regla core `reglas/skills-estandar.md` ya prescribe que `SKILL.md`
+  no exceda 300 líneas y que los `recursos/` se nombren en kebab-case
+  con sufijo `.md` — esa regla cubre el 95% de los casos.
+- Esta convención **complementa** la regla core para skills donde un nombre
+  semántico genérico (`EXAMPLES.md`) comunica mejor el contenido que un
+  nombre específico (ej: `casos-decisiones-arquitecturales.md` es más largo
+  y menos buscable).
+
+---
+
+## Origen
+
+Patrón observado en repos externos analizados el 2026-05-09
+(`temp/agent-skills-main`, `temp/andrej-karpathy-skills-main`):
+varios skills críticos exponen un `EXAMPLES.md` con diffs MAL/BIEN
+auto-cargable como referencia rápida del agente.
+
+Adoptado en `habilidades/doubt-driven-review/recursos/EXAMPLES.md` como
+primera aplicación. Casos futuros: skills de decisiones arquitecturales,
+seguridad, debugging avanzado.