@saulwade/swl-ses 1.4.2 → 1.5.1

package/habilidades/discutir-fase/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: discutir-fase
-description: Cuestionario adaptativo que se ejecuta antes de planear una fase de desarrollo. Extrae decisiones técnicas y de negocio del usuario, clasifica respuestas como "cerradas" (no negociables) o "abiertas" (decisión delegada al agente), y produce un archivo CONTEXTO.md que alimenta al planificador.
-version: "1.0.0"
+description: Cuestionario adaptativo que se ejecuta antes de planear una fase de desarrollo. Extrae decisiones técnicas y de negocio del usuario, clasifica respuestas como "cerradas" (no negociables) o "abiertas" (decisión delegada al agente), y produce un archivo CONTEXTO.md que alimenta al planificador. Inicia con discovery routing (5 paths) que evita el cuestionario completo cuando no aplica.
+version: "1.1.0"
 herramientasPermitidas: [Read, Write, Edit, Bash, Glob, Grep]
 exclusiones:
   - "No cargar si el usuario ya tiene un CONTEXTO.md poblado para la fase en curso — ir directo a `planear-fase`."
@@ -35,6 +35,54 @@ antipatrón de planear con suposiciones implícitas que luego se contradicen.
 
 ---
 
+## Paso 0 — Discovery routing (obligatorio antes del cuestionario)
+
+Antes de lanzar el cuestionario adaptativo, ejecuta **scan ligero** de
+`.planning/` para identificar la ruta correcta. Esto evita gastar turnos en
+un cuestionario cuando la petición del usuario no requiere una fase nueva.
+
+Inspirado en `kiro-discovery` (cc-sdd) — ver `temp/cc-sdd-main/tools/cc-sdd/templates/agents/claude-code-skills/skills/kiro-discovery/SKILL.md`.
+
+### Inventario rápido (solo metadata, NO leer contenido completo)
+
+1. `Glob` sobre `.planning/fases/*.md` → lista de fases existentes y su estado.
+2. `Read` de `.planning/HOJA-RUTA.md` (si existe) — para mapear la petición a roadmap.
+3. `Read` del `.planning/ESTADO.md` (si existe) — para conocer fase activa.
+
+Si no hay `.planning/`, marca **proyecto verde** y salta al cuestionario completo (Ruta C por defecto).
+
+### Determinar la ruta
+
+| Ruta | Cuándo aplica | Acción |
+|------|--------------|--------|
+| **RUTA_A** — Extiende fase existente | La petición es una extensión, fix o enhancement dentro del scope de una fase ya planeada. Cabe en `tasks` de un PLAN.md existente. | NO ejecutar cuestionario. Informar al usuario: "Esto encaja en la fase `<N>`. ¿Procedo a actualizar su PLAN.md o lanzar `/swl:ejecutar-fase <N>` directo?" |
+| **RUTA_B** — Sin fase necesaria | Fix trivial (<5 archivos, 1 tarea, sin decisiones de scope). Bug puntual, typo, dependencia, refactor menor. | NO ejecutar cuestionario. Informar al usuario: "Esto no requiere fase formal. Procedo directo con `implementador-swl` o el agente de stack. ¿De acuerdo?" |
+| **RUTA_C** — Nueva fase single-scope | Petición nueva, no encaja en fases existentes, single-domain. | Ejecutar cuestionario completo (Bloques 1-4). |
+| **RUTA_D** — Decomposición multi-fase | Petición spans múltiples dominios o produciría >20 tareas en una sola fase. | Ejecutar cuestionario **resumido** (Bloque 1 + Bloque 4) para extraer decisiones de scope. Luego sugerir descomposición en N fases. Confirmar con usuario antes de proceder. |
+| **RUTA_E** — Mixto | La petición combina: extensión de fase existente + nueva fase + posiblemente fix trivial. | Presentar al usuario la decomposición propuesta y confirmar antes de proceder. Para la parte "nueva fase" ejecutar cuestionario reducido. |
+
+### Heurísticas de matching
+
+- Si la petición menciona explícitamente "fase N" → considerar RUTA_A primero.
+- Si la petición empieza con "arregla", "corrige", "fix", "elimina" → considerar RUTA_B primero.
+- Si la petición empieza con "implementa", "crea", "agrega feature" → RUTA_C o RUTA_D.
+- Si la petición tiene `y`, `,`, `también` enumerando >2 cosas distintas → RUTA_D o RUTA_E.
+
+### Cómo presentar el veredicto
+
+Tras el scan, emite un mensaje corto al usuario antes del cuestionario:
+
+```
+Discovery routing: RUTA_<X>
+Justificación: <una oración explicando por qué>
+Próximo paso: <qué se hará a continuación>
+¿Procedo? [s/N o sugerir otra ruta]
+```
+
+Solo después de confirmar la ruta procede con el cuestionario (si aplica).
+
+---
+
 ## Protocolo de entrevista adaptativa
 
 ### Regla 1 — Máximo 4 preguntas por mensaje

package/habilidades/ejecutar-task-iterativo/SKILL.md

@@ -0,0 +1,278 @@
+---
+name: ejecutar-task-iterativo
+description: >
+  Modo iterativo de ejecución por tarea (opt-in via /swl:ejecutar-fase --iterative)
+  donde cada tarea atómica recibe contexto fresco, implementer dispatched como
+  sub-agente independiente, revisión task-local con protocolo-revision-swl,
+  auto-debug en BLOCKED, y commit por tarea. Alternativa al modo default
+  (oleadas paralelas con verificación al final de fase). Cargar cuando la fase
+  tiene tareas con dependencias secuenciales fuertes, módulos críticos donde
+  cada tarea merece revisión adversarial inmediata, o cuando la fase tiene
+  >12 tareas y el modo paralelo arriesga acumular deuda no detectada.
+version: "1.0.0"
+herramientasPermitidas: [Read, Write, Edit, Bash, Glob, Grep, Agent]
+exclusiones:
+  - "No cargar si /swl:ejecutar-fase NO recibió el flag --iterative — el modo default sigue siendo oleadas paralelas."
+  - "No cargar para fases pequeñas (<5 tareas) — el overhead per-task supera el beneficio."
+  - "No cargar para tareas que no son atómicas o no tienen verificación clara — la iteración requiere boundary explícito por tarea."
+  - "No cargar si PLAN.md no tiene `estado: aprobado` — requirement freeze obligatorio antes de ejecutar."
+evolvable: true
+---
+
+# Ejecución iterativa per-task
+
+## Propósito
+
+El modo default de `/swl:ejecutar-fase` ejecuta tareas en **oleadas paralelas**
+y verifica al final de la fase con `verificar-trabajo` goal-backward. Esto es
+eficiente para fases con tareas independientes y bajo riesgo.
+
+Sin embargo, hay casos donde la granularidad task-por-task es superior:
+
+- Tareas con dependencias secuenciales fuertes (cada una depende del resultado de la anterior).
+- Módulos críticos (dinero, permisos, datos irreversibles) donde cada tarea merece revisión adversarial.
+- Fases con >12 tareas, donde el modo paralelo arriesga acumular deuda silenciosa.
+- El usuario explícitamente pide "una a una, revisando cada una".
+
+Este skill implementa ese modo: 1 tarea por iteración, contexto fresco,
+implementer dispatchado como sub-agente, review task-local con
+`protocolo-revision-swl`, auto-debug en `BLOCKED`, y commit por tarea.
+
+Adaptado del patrón `kiro-impl` de cc-sdd, manteniendo identidad SWL.
+
+## Cuándo cargar
+
+- `/swl:ejecutar-fase N --iterative` (flag explícito del usuario)
+- El usuario pide "ejecuta el plan tarea por tarea con revisión en cada una"
+- El PLAN.md declara en su frontmatter `modo_ejecucion: iterativo`
+
+## Cuándo NO cargar
+
+Ver `exclusiones` en frontmatter.
+
+---
+
+## Precondiciones (verificar antes de iterar)
+
+1. `.planning/fases/0N-PLAN.md` con `estado: aprobado` (requirement freeze).
+2. `.planning/ESTADO.md` inicializado o actualizado.
+3. Working tree limpio (`git status --porcelain` vacío) o el usuario explícitamente autoriza cambios pendientes.
+4. Tests del proyecto en estado "verde de base" — capturar baseline antes del primer task para detectar regresiones limpiamente.
+5. Validation commands descubiertos del proyecto (test, build, lint, smoke):
+
+```bash
+node -e "const p=require('./package.json');console.log(JSON.stringify(p.scripts||{}))" 2>/dev/null
+```
+
+Si no se pueden derivar comandos canónicos → reportar al usuario y pedir
+guía antes de iterar.
+
+---
+
+## El loop iterativo (1 task por iteración)
+
+### Disciplina del loop
+
+- **Una sola sub-tarea por iteración** (ej. 3.1, luego 3.2, luego 3.3 — no batch).
+- **Contexto fresco**: al inicio de cada iteración, re-leer `PLAN.md` para
+  determinar la siguiente tarea actionable. NO confiar en memoria acumulada
+  de iteraciones previas.
+- **Memoria residual mínima**: tras cada iteración, retener solo 1 línea
+  ("3.1: APPROVED, 3 archivos cambiados"). Descartar status report completo
+  y detalles del reviewer.
+- **Re-read tasks.md antes de cada nuevo dispatch** — el implementer previo
+  pudo agregar `## Implementation Notes` que aplican a la siguiente tarea.
+
+### Iteración estándar
+
+Para cada sub-tarea pendiente, en orden:
+
+#### Paso 1 — Identificar la siguiente tarea
+
+```bash
+# Re-leer PLAN.md y encontrar primera tarea no marcada [x]
+grep -E "^\s*- \[ \]" .planning/fases/0N-PLAN.md | head -1
+```
+
+- Saltear tareas con anotación `_Blocked:_`.
+- Verificar dependencias declaradas en `_Depends:_` — si una dependencia no está `[x]`, ejecutarla primero o pedir resolución al usuario.
+- Leer `_Boundary:_` para identificar los paths/módulos que esta tarea puede tocar.
+
+#### Paso 2 — Dispatch del implementer (como sub-agente fresh)
+
+Construir prompt con:
+
+- Texto literal de la tarea (no parafrasear).
+- Boundary scope.
+- Paths a spec files (`PLAN.md`, `CONTEXTO.md`, otros).
+- IDs literales de requirements/design references (NO inventar `REQ-*` aliases).
+- Validation commands del proyecto (test, build, smoke) relevantes a la tarea.
+- Implementation Notes previas del PLAN.md que apliquen al boundary actual.
+- Indicación de si la tarea es behavioral (requiere feature flag opcional) o no-behavioral.
+
+Invocar el sub-agente vía `Agent` tool con `subagent_type` apropiado:
+
+- Backend Python → `backend-python-swl`
+- Backend Node → `backend-node-swl`
+- Frontend React → `frontend-react-swl`
+- ... (matriz `usar-sistema-swl.md`)
+- Fallback: `implementador-swl`
+
+El sub-agente debe devolver un **Status Report estructurado** con campo
+`STATUS: READY_FOR_REVIEW | BLOCKED | NEEDS_CONTEXT`.
+
+#### Paso 3 — Manejar el status del implementer
+
+Parsear el status solo del bloque exacto `## Status Report` con campo `STATUS:`.
+Si el status no es parseable, re-dispatch UNA VEZ pidiendo el bloque estructurado.
+Sin status parseable tras 2 dispatches → escalar.
+
+| Status | Acción |
+|--------|--------|
+| `READY_FOR_REVIEW` | Continuar al Paso 4 (review) |
+| `NEEDS_CONTEXT` | Re-dispatch UNA VEZ con el contexto adicional solicitado. Si persiste → Paso 5 (debug) |
+| `BLOCKED` | Saltar a Paso 5 (debug). NO marcar la tarea como saltada |
+
+#### Paso 4 — Review task-local
+
+Invocar el revisor apropiado al stack:
+
+- `revisor-codigo-swl` (general)
+- `revisor-react-swl` / `revisor-angular-swl` (frontend)
+- `revisor-typescript-swl` / `revisor-python-*` / etc.
+- `revisor-seguridad-swl` (si la tarea toca auth, secretos, input externo)
+
+El revisor carga `Skill("protocolo-revision-swl")` y emite veredicto:
+
+| Verdict | Acción |
+|---------|--------|
+| `APPROVED` con score ≥9.0 | Continuar al Paso 6 (commit) |
+| `REJECTED` (1er ciclo) | Re-dispatch del implementer con las findings del revisor. Volver al Paso 3 |
+| `REJECTED` (2do ciclo) | Saltar al Paso 5 (debug) — la remediación no convergió |
+
+Veredictos persistidos en `.planning/audit/reviews/<task-id>-<ts>.json`.
+
+#### Paso 5 — Auto-debug (cuando BLOCKED o REJECTED persiste)
+
+Invocar `depurador-swl` con contexto fresh:
+
+- Síntoma exacto del blocker o de los findings que no se resolvieron.
+- Stack trace, output del comando fallido, exit code.
+- Reviewer feedback si aplica.
+- `_Boundary:_` de la tarea.
+- Implementation Notes relacionadas.
+
+El depurador retorna:
+
+```
+ROOT_CAUSE: <descripción>
+FIX_PLAN: <pasos concretos>
+VERIFICATION: <cómo verificar el fix>
+NEXT_ACTION: RETRY_TASK | BLOCK_TASK | STOP_FOR_HUMAN
+CONFIDENCE: HIGH | MEDIUM | LOW
+```
+
+- `RETRY_TASK` con CONFIDENCE HIGH/MEDIUM → re-dispatch implementer con el fix plan. Volver al Paso 3.
+- `BLOCK_TASK` → marcar tarea con `_Blocked:_<razón>_` en PLAN.md. Actualizar ESTADO.md. Continuar con la SIGUIENTE tarea (no esta).
+- `STOP_FOR_HUMAN` → pausar el loop y escalar al usuario con el informe del depurador.
+
+#### Paso 6 — Commit atómico de la tarea
+
+Tras APPROVED:
+
+```bash
+git add <archivos del diff de esta tarea>
+git commit -m "<tipo>(<scope>): <descripción imperativa de la tarea>
+
+Tarea: <task-id> — <texto literal>
+Plan: .planning/fases/0N-PLAN.md
+Review: .planning/audit/reviews/<task-id>-<ts>.json"
+```
+
+Marcar la tarea como `[x]` en PLAN.md en el mismo commit (o en commit
+inmediato siguiente atómico).
+
+#### Paso 7 — Update de ESTADO.md y memoria
+
+- Marcar tarea `[x]` en PLAN.md.
+- Actualizar ESTADO.md con: tarea completada, commit hash, archivos cambiados, score del review.
+- Agregar al final del PLAN.md, en sección `## Implementation Notes`, cualquier learning relevante para tareas futuras del mismo boundary o dependencia.
+- Retener solo 1 línea en memoria de iteración para el siguiente loop.
+
+#### Paso 8 — Próxima iteración o cierre
+
+- Si quedan tareas pendientes: volver al Paso 1.
+- Si todas las tareas están `[x]` o `_Blocked:_`: cerrar el loop e invocar
+  el flujo de cierre estándar de `ejecutar-fase` (RESUMEN.md, actualizar
+  HOJA-RUTA.md, verificación goal-backward final con `verificar-trabajo` —
+  ver Paso 6-8 del comando `/swl:ejecutar-fase`).
+
+---
+
+## Persistencia de aprendizajes entre tareas
+
+A diferencia del modo paralelo (donde cada wave es relativamente
+independiente), el modo iterativo propaga aprendizajes:
+
+### En PLAN.md, sección `## Implementation Notes`:
+
+```markdown
+## Implementation Notes
+
+- **Tarea 1.2 (POST /facturas)**: `Pydantic v2` cambia `parse_obj` → `model_validate`.
+  Aplica a futuras tareas que validen schemas con v2.
+- **Tarea 2.1 (migración)**: `Alembic` no detecta cambios en `JSONB` automáticamente —
+  marcar con `nullable=False` explícito.
+```
+
+El implementer del paso 2 lee estas notes antes de empezar. Esto evita
+repetir los mismos errores task-a-task.
+
+---
+
+## Diferencias clave con el modo default (paralelo por oleadas)
+
+| Aspecto | Modo default (paralelo) | Modo iterativo (este skill) |
+|---------|------------------------|----------------------------|
+| Granularidad | Oleada (varias tareas en paralelo) | 1 tarea por iteración |
+| Contexto del implementer | Acumulado entre tareas de la misma oleada | Fresco por tarea (sub-agente nuevo) |
+| Review | Al final de fase con `verificar-trabajo` | Tras cada tarea con `protocolo-revision-swl` |
+| Auto-debug | Manual o post-mortem | Automático en BLOCKED |
+| Commit | Atómico por slice/tarea (similar) | Atómico estricto por tarea + review JSON |
+| Implementation Notes | No requeridas | Propagadas entre tareas |
+| Costo en tokens | Menor | Mayor (~1.5-2× por contexto fresh) |
+| Cuándo preferir | Fases con tareas independientes, riesgo bajo | Tareas con dependencias fuertes, módulos críticos, fases grandes |
+
+---
+
+## Gotchas / Errores comunes no obvios
+
+- **Re-usar contexto acumulado del implementer entre iteraciones**: el implementer del task 3.2 NO debe tener en su contexto el reporte completo del task 3.1 — solo el `## Implementation Notes` relevante. Causa: ahorro falso de tokens. Solución: dispatch fresh siempre, los notes son el canal explícito de propagación.
+- **Saltar el Paso 4 (review) "porque la tarea es chica"**: el review per-task es lo que distingue este modo del default. Sin review per-task, el modo iterativo es solo "lento sin beneficio". Solución: si la tarea es realmente trivial, no usar modo iterativo.
+- **Auto-debug que sugiere FIX y se aplica sin re-review**: tras debug → fix → COMMIT directo es anti-patrón. Solución: cada FIX debe volver al Paso 4 (review) antes de commit.
+- **Boundary violations toleradas porque "el implementer tenía que tocar eso"**: si un archivo fuera del boundary aparece en el diff y el revisor lo marca como finding, no se puede aceptar sin extender el boundary EN EL PLAN.md (decisión documentada). Solución: si el boundary necesita extenderse, actualizar PLAN.md primero y volver a iterar.
+- **`MERGED` en main sin marcar la tarea `[x]` en PLAN.md**: deja ESTADO.md y PLAN.md desincronizados. Solución: marcar `[x]` está en el MISMO commit del cambio (no commit aparte).
+
+---
+
+## Relación con otros componentes SWL
+
+| Componente | Relación |
+|-----------|----------|
+| `ejecutar-fase` | Skill padre — el flag `--iterative` cede el control a este skill |
+| `protocolo-revision-swl` | Invocado en Paso 4 por el revisor |
+| `verificar-trabajo` | Invocado al cerrar el loop como verificación goal-backward final |
+| `depurador-swl` | Invocado en Paso 5 cuando hay BLOCKED o REJECTED persistente |
+| `implementador-swl` y agentes de stack | Dispatchados como sub-agentes en Paso 2 |
+| `notificador-swl` | Invocado en STOP_FOR_HUMAN o ESCALATE |
+| `reglas/seguridad-agentes.md` § Recovery Catalog | Marco de escalada (reprompt → reduce-autonomy → escalate → terminate) |
+
+## Checklist de cierre del loop
+
+- [ ] Todas las tareas pendientes están `[x]` o `_Blocked:_<razón>_`
+- [ ] Cada tarea tiene su review JSON en `.planning/audit/reviews/`
+- [ ] PLAN.md tiene `## Implementation Notes` con aprendizajes relevantes
+- [ ] ESTADO.md actualizado con commit hashes y scores
+- [ ] Verificación goal-backward final ejecutada (`verificar-trabajo`)
+- [ ] RESUMEN.md generado (paso del flujo estándar de `ejecutar-fase`)
+- [ ] Working tree limpio o con cambios pendientes documentados

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

@@ -9,7 +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.0"
+version: "1.0.1"
+evolved: true
+evolved-from: "1.0.0"
+evolved-at: "2026-05-15"
+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."
 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."
@@ -293,6 +298,22 @@ al caso en cuestión en lugar de los tres.
 - **Cargar este skill cuando la regla core basta**: esto invierte el trade-off
   de context budget. Cargar `meta-skills-estandar` solo cuando se necesita
   contenido extendido, no por defecto.
+- **Absorber naming externo al portar un patrón valioso**: cuando un skill
+  externo (de cc-sdd, harness-sdd, langchain, kiro, etc.) aporta un patrón
+  útil, la tentación es importar también el nombre original (`kiro-review`,
+  `kiro-impl`, `langchain-router`). Causa: economía cognitiva en la transición.
+  Costo: rompe la identidad del sistema receptor, confunde routing del
+  orquestador, viola la regla de idioma español MX y crea acoplamiento
+  conceptual con un sistema externo cuya API puede cambiar. Solución
+  obligatoria: **portar el patrón, adaptar el nombre al naming del sistema
+  receptor**. Para SWL: usar prefijo `swl-` o sufijo `-swl`, en español MX,
+  con el dominio del problema (no del sistema origen). Ejemplo real
+  (2026-05-15): el patrón `kiro-review` de cc-sdd se absorbió como
+  `protocolo-revision-swl` por instrucción explícita del usuario; `kiro-impl`
+  iterativo se absorbió como `ejecutar-task-iterativo`. Documentar el origen
+  en la sección "Referencias" o "Origen" del skill, NO en el nombre. Verificar
+  con `git log --grep="kiro\|otro-prefijo-externo"` que no quedan menciones
+  del naming externo en el codebase del sistema receptor.
 
 ## Referencias
 

package/habilidades/node-experto/SKILL.md

@@ -4,9 +4,9 @@ description: Node.js y TypeScript backend moderno. Cubre patterns de Express/Fas
 version: "1.0.1"
 evolved: true
 evolved-from: "1.0.0"
-evolved-at: "2026-05-14"
+evolved-at: "2026-05-15"
 evolved-by: "aprender"
-evolved-note: "Gotcha req.destroy() vs req.pause() en handlers HTTP nativos — origen PR #13 webhook-server"
+evolved-note: "Gotcha req.destroy() vs req.pause() en HTTP nativos (PR #13). + CRLF regex breakage en Windows + serializar TOML con literal '''...''' (Sub-fase 11/11.5 v1.5.1)."
 herramientasPermitidas: [Read, Write, Glob]
 exclusiones:
   - "No cargar para aplicaciones Next.js con App Router — Next.js tiene patrones de Server Components, SSR y caché que difieren del backend Node puro; cargar `nextjs-experto`."
@@ -272,6 +272,17 @@ if (require.main === module) {
 
 **`req.destroy()` en un handler `http` cierra el socket antes de poder enviar la respuesta**: cuando se aborta la lectura del body (por ejemplo al exceder `maxPayloadBytes`), llamar `req.destroy()` en el listener `data` cierra el socket inmediatamente. El subsiguiente `res.writeHead(413); res.end()` del handler falla porque ya no hay socket — el cliente recibe `ECONNRESET` en lugar de 413. Causa: `destroy()` no espera al flush de la respuesta pendiente; equivale a un `RST` TCP. Fix: usar `req.pause()` + un flag `abortado = true` + rechazar la promesa de lectura; dejar que el handler envíe `res.writeHead(413); res.end(...)` normalmente. Node cierra el socket por sí solo tras `res.end()`. Aplica a servidores HTTP nativos sin Express/Fastify, donde el control del body es manual.
 
+**Regex multi-line con `\n` falla con archivos CRLF de Windows**: un parser que usa `/^---\n([\s\S]*?)\n---\n/` para detectar frontmatter YAML rompe con archivos commiteados en Windows (donde git aplica `core.autocrlf=true` y convierte LF↔CRLF al checkout). Caso real (Sub-fase 11.5 v1.5.1, swl-ses): `parsearFrontmatter` en `scripts/lib/transformadores/base.js` devolvía `frontmatter:{}` y `cuerpo:<archivo entero>` para los 60 agentes `agentes/*.md` cuando se ejecutaba en Windows. Resultado downstream: `transformarAgente` de Codex generaba TOML con `description = ""` y `developer_instructions` con el frontmatter duplicado dentro del body. Bug latente que solo aparece al ejecutar contra archivos reales con CRLF. Fix: normalizar antes del match — `const norm = String(contenido).replace(/\r\n/g, '\n').replace(/\r/g, '\n');` y aplicar regex sobre `norm`. Siempre asumir que cualquier archivo leído de filesystem en Windows puede tener CRLF, incluso si git lo "almacena" como LF. Aplica a TODA función con regex multi-line que reciba contenido de filesystem.
+
+**Serializar TOML zero-deps: preferir `'''literal'''` sobre `"""basic"""` para multi-line con backslashes**: TOML soporta dos sintaxis multi-line — basic `"""..."""` que procesa escapes (`\n`, `\t`, `\\`) y literal `'''...'''` que preserva el contenido tal cual. Caso real (Sub-fase 11 v1.5.1, swl-ses): al serializar el cuerpo Markdown de agentes SWL (con regex `\n`, paths Windows con `\`, etc.) a `developer_instructions` de `~/.codex/agents/*.toml`, usar basic `"""..."""` exigía escapar cada `\` a `\\` (laborioso y propenso a bugs). Solución: usar literal `'''...'''` por default (preserva Markdown crudo) y caer a basic `"""..."""` con escape SOLO si el cuerpo contiene `'''` literal (raro). Helper en `scripts/lib/transformadores/codex.js`:
+```js
+_tomlMultiline(s) {
+  if (!s.includes("'''")) return `'''\n${s}\n'''`;
+  return `"""\n${s.replace(/\\/g, '\\\\').replace(/"""/g, '\\"""')}\n"""`;
+}
+```
+Aplica a cualquier serialización TOML manual sin librería (`@iarna/toml`, etc.) donde el contenido es texto rico con caracteres especiales.
+
 ```js
 // MAL — ECONNRESET en cliente, nunca recibe 413
 req.on('data', chunk => {