@saulwade/swl-ses 1.6.3 → 1.6.6

package/comandos/swl/exportar-vault.md

@@ -105,6 +105,7 @@ Si tras `ToolSearch` el MCP carga sus tools pero la primera llamada (ej.
 el síntoma es claro: apiKey desincronizada.
 
 Acción:
+
 1. Leer la apiKey actual del plugin con
    `grep '"apiKey"' "F:/Google Drive/Developer/Obsidian/Vault/SWL/.obsidian/plugins/obsidian-local-rest-api/data.json"`
 2. Reportar al usuario que actualice en **claude.ai → Settings → Connectors
@@ -152,6 +153,7 @@ META - SWL Software Engineering System.md
 Algoritmo de match (en cascada — cada pasada solo se ejecuta si la anterior no resolvió match único):
 
 **Normaliza ambos lados** a comparación robusta antes de cualquier pasada:
+
 - Strip extensión `.md`.
 - Strip prefijo `DEV - ` o `META - ` (cualquier prefijo seguido de ` - `).
 - Lowercase.
@@ -161,17 +163,21 @@ Algoritmo de match (en cascada — cada pasada solo se ejecuta si la anterior no
 Aplica el mismo procesamiento al slug del proyecto local.
 
 **Pasada 1 — Match exacto**:
+
 - Si la cadena normalizada del slug local coincide carácter a carácter con la de algún canónico, ese es el match. Caso típico: `sigaf` ↔ `DEV - SIGAF`.
 
 **Pasada 2 — Match por prefijo bidireccional**:
+
 - Si la cadena del slug local es **prefijo** de la cadena de algún canónico, ese canónico matchea. Ej: `ecosistemamultiagenteia` es prefijo de `ecosistemamultiagenteiaoicine` → match con `DEV - Ecosistema Multi-Agente IA OIC-INE`.
 - Inversamente: si la cadena de algún canónico es prefijo de la del slug local, también matchea (cubre el caso opuesto: vault con nombre más corto que el slug del proyecto).
 - Solo se acepta el match si la pasada produce **exactamente 1** candidato. Si hay 2+ ambiguos, NO usar — pasar a siguiente pasada con el alias o fallback final, listando los candidatos en el WARNING del Paso 5.
 
 **Pasada 3 — Aliases conocidos**:
+
 - Si ninguna pasada anterior resolvió, intenta con sinónimos del slug local antes del fallback (ver lista de aliases más abajo). Para cada alias, repite Pasada 1 y Pasada 2.
 
 **Pasada 4 — Fallback**:
+
 - Si todo lo anterior es vacío:
   - Usar como `related_vault_project` el valor `[[DEV - {Nombre-Title-Case}]]` (fallback antiguo).
   - **Reportar warning explícito al usuario** en el paso 5 indicando que no se encontró nodo canónico y sugerir crear `02-Projects/DEV - {Nombre}.md` en el vault.
@@ -180,13 +186,13 @@ Resultado del algoritmo: el nombre canónico es el basename del archivo sin `.md
 
 Ejemplos de match esperado (con la pasada que lo resuelve):
 
-| Slug local | Normalizado local | Canónico que matchea | Pasada | Nombre canónico resuelto |
-|------------|-------------------|----------------------|--------|--------------------------|
-| `sigaf` | `sigaf` | `sigaf` | 1 (exacto) | `DEV - SIGAF` |
-| `sigm` | `sigm` | `sigm` | 1 (exacto) | `DEV - SIGM` |
-| `swl-software-engineering-system` | `swlsoftwareengineeringsystem` | `swlsoftwareengineeringsystem` | 1 (exacto) | `META - SWL Software Engineering System` |
-| `ecosistema-multi-agente-ia` | `ecosistemamultiagenteia` | `ecosistemamultiagenteiaoicine` | 2 (prefijo del slug en canónico) | `DEV - Ecosistema Multi-Agente IA OIC-INE` |
-| `swl-ses` | `swlses` | ninguno (ver nota) | 3 (alias → reemplaza slug por `swlsoftwareengineeringsystem` y repite 1) | `META - SWL Software Engineering System` |
+| Slug local                        | Normalizado local              | Canónico que matchea            | Pasada                                                                   | Nombre canónico resuelto                   |
+| --------------------------------- | ------------------------------ | ------------------------------- | ------------------------------------------------------------------------ | ------------------------------------------ |
+| `sigaf`                           | `sigaf`                        | `sigaf`                         | 1 (exacto)                                                               | `DEV - SIGAF`                              |
+| `sigm`                            | `sigm`                         | `sigm`                          | 1 (exacto)                                                               | `DEV - SIGM`                               |
+| `swl-software-engineering-system` | `swlsoftwareengineeringsystem` | `swlsoftwareengineeringsystem`  | 1 (exacto)                                                               | `META - SWL Software Engineering System`   |
+| `ecosistema-multi-agente-ia`      | `ecosistemamultiagenteia`      | `ecosistemamultiagenteiaoicine` | 2 (prefijo del slug en canónico)                                         | `DEV - Ecosistema Multi-Agente IA OIC-INE` |
+| `swl-ses`                         | `swlses`                       | ninguno (ver nota)              | 3 (alias → reemplaza slug por `swlsoftwareengineeringsystem` y repite 1) | `META - SWL Software Engineering System`   |
 
 **Nota sobre el caso `swl-ses`** — un lector cuidadoso puede preguntarse por qué Pasada 2 (prefijo) no captura este caso, dado que `swlses` y `swlsoftwareengineeringsystem` comparten el inicio `swls`. La verificación carácter a carácter:
 
@@ -263,11 +269,11 @@ reviewed: false
 
 ## Métricas que cambiaron
 
-| Métrica | Antes | Después |
-|---------|-------|---------|
-| LOC | | |
-| Endpoints | | |
-| Tests | | |
+| Métrica   | Antes | Después |
+| --------- | ----- | ------- |
+| LOC       |       |         |
+| Endpoints |       |         |
+| Tests     |       |         |
 
 ## Bloqueantes o deuda detectada
 
@@ -280,11 +286,13 @@ Ejecutar `/sync-projects {proyecto-slug}` en el vault para integrar los cambios
 ---
 
 **Archivos fuente consultados:**
+
 - `.planning/COMPACTACION.md` (última)
 - `.planning/APRENDIZAJES.md` (últimas entradas)
 - Git log del día
 
 **Notas:**
+
 - Este archivo vive en 00-Inbox/ del vault. Saul lo procesa manualmente o con `/sync-projects`.
 - No sobreescribe nada en `02-Projects/`, `04-Resources/` ni `07-Decisions/` del vault.
 ```
@@ -313,6 +321,7 @@ mcp__obsidian__obsidian_append_content({
 ```
 
 Ventajas frente al filesystem:
+
 - **No pasa por `proteccion-rutas.js`** — el MCP opera vía HTTPS al puerto
   27124, fuera del flujo de Bash/Write/Edit.
 - **Sin staging intermedio**: escribe directamente al archivo final del vault.
@@ -321,6 +330,7 @@ Ventajas frente al filesystem:
   manejar separators de path.
 
 Notas operativas:
+
 - Si el archivo ya existe con ese timestamp (raro), agregar sufijo `_b`
   al nombre antes de invocar `append_content`. El MCP de obsidian no
   sobreescribe si el archivo existe — `append` agrega al final.
@@ -354,6 +364,7 @@ escribe a `_userland/staging/<timestamp>.md` dentro del CWD, luego mueve con
 `Bash` (`mv` o PowerShell `Move-Item`).
 
 Reportar al usuario qué canal se usó:
+
 - Canal A → `[OK] Vía: MCP Obsidian (puerto 27124)`
 - Canal B → `[OK] Vía: filesystem directo (MCP no disponible)`
 - Canal Híbrido → `[OK] Vía: filesystem para Inbox, MCP para promociones`
@@ -391,11 +402,78 @@ Reportar al usuario el desglose final del modo híbrido:
 [OK] Revisión aprobada (reviewed: true) en el Inbox
 ```
 
+## Paso 4b — Verificación post-escritura (obligatorio)
+
+**Inmediatamente después** de cada escritura del Paso 4 (Inbox, promociones en
+`02-Projects/`, `07-Decisions/`, `04-Resources/`, `10-Archive/`), confirma que el
+archivo en disco **existe y tiene contenido sustantivo**. Sin este paso, Obsidian
+puede mostrar nodos fantasma (pestaña con título pero cuerpo vacío) cuando el MCP
+falló con `40101`, timeout o `append_content` sobre ruta incorrecta.
+
+### Cuándo verificar
+
+| Escritura                                                     | Verificar                                                     |
+| ------------------------------------------------------------- | ------------------------------------------------------------- |
+| Export en `00-Inbox/`                                         | **Siempre**                                                   |
+| Append a `02-Projects/DEV - *.md`                             | **Siempre** (leer tramo final o archivo completo si es corto) |
+| Nota nueva en `07-Decisions/`, `04-Resources/`, `10-Archive/` | **Siempre**                                                   |
+| Solo `reviewed: true` en Inbox existente                      | Opcional (el archivo ya existía)                              |
+
+### Cómo verificar (orden de preferencia)
+
+1. **MCP** — `obsidian_get_file_contents` con path **relativo al vault SWL**
+   (sin prefijo `F:\...`):
+   ```json
+   { "filepath": "00-Inbox/2026-05-18_1530_export-swl-ses.md" }
+   ```
+2. **Filesystem** — si el Paso 4 usó canal B, leer el mismo path absoluto con
+   `Read` o `Get-Content` y comparar longitud.
+
+### Criterios de aprobación (todos deben cumplirse)
+
+| #   | Criterio            | Umbral                                                                                                                                                   |
+| --- | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 1   | El archivo existe   | Sin error 404 / `ENOENT`                                                                                                                                 |
+| 2   | Longitud del cuerpo | ≥ **500 caracteres** (sin contar solo frontmatter vacío)                                                                                                 |
+| 3   | Marcador de export  | Contiene `type: export-swl` en frontmatter **o** al menos una sección `## Logros de la sesión` / `## Sesión` / `## Decisiones` con texto bajo el heading |
+| 4   | No es fantasma      | El cuerpo **no** es solo el título del archivo, una línea en blanco, o el nombre del nodo sin párrafos                                                   |
+
+Si el export es deliberadamente corto (<500 caracteres), bajar el umbral a
+≥ **200 caracteres** solo si el frontmatter incluye `type: export-swl` y al
+menos un bullet bajo `## Logros` o `## Sesión`; en caso contrario, tratar como
+fallo.
+
+### Si la verificación falla
+
+1. **No** reportar `[OK] Export creado` al usuario.
+2. Registrar en la salida: `[FAIL] Verificación post-escritura: <motivo>`.
+3. **Un reintento** con el canal alternativo (MCP ↔ filesystem del Paso 4).
+4. Si sigue fallando: reconstruir el Markdown desde `.planning/COMPACTACION.md`
+   - artefactos de sesión y escribir de nuevo; si aún falla, abortar y pedir
+     al usuario revisar Obsidian (vault activo Paso 0c, apiKey Paso 0d).
+5. Si Obsidian ya abrió una pestaña fantasma: cerrar la pestaña en el IDE de
+   Obsidian; **no** dejar el tab apuntando a un path que no pasó verificación.
+
+### Salida interna (para el Paso 5)
+
+Guardar mentalmente (o en el reporte):
+
+```
+[OK] Verificación: 00-Inbox/2026-05-18_1530_export-swl-ses.md — 2847 chars, secciones OK
+```
+
+o
+
+```
+[FAIL] Verificación: cuerpo 42 chars — reintento vía filesystem
+```
+
 ## Paso 5 — Confirmación
 
-Reporta al usuario:
+Reporta al usuario **solo si el Paso 4b aprobó** el Inbox (y cada promoción, si aplica):
 
 - Ruta exacta del archivo creado.
+- Resultado del Paso 4b (caracteres verificados o `[FAIL]` si abortaste).
 - Conteo de palabras.
 - **Nombre canónico resuelto**: indicar qué nodo de `02-Projects/` enlazó el export. Si no hubo match, marcar el warning explícito.
 - Recordatorio: "Al abrir el vault en tu próxima sesión, ejecuta `/sync-projects {proyecto-slug}` para integrar formalmente estos cambios."
@@ -404,6 +482,7 @@ Formato esperado cuando hay match:
 
 ```
 [OK] Export creado: F:\...\2026-05-04_1748_export-swl-ses.md (487 palabras)
+[OK] Verificación post-escritura: 3124 chars, type: export-swl, secciones OK
 [OK] Enlace canónico: [[META - SWL Software Engineering System]]
 
 Próximo paso: al abrir el vault, ejecuta:
@@ -440,6 +519,9 @@ Próximo paso: al abrir el vault, ejecuta:
 - **Recurrir al workaround del filesystem antes de cargar el schema del
   MCP con `ToolSearch`**. Tools deferred ≠ tools ausentes — el MCP server
   está corriendo, solo falta cargar el schema. Cargar antes de defaultear.
+- **Declarar éxito sin Paso 4b**. Un `append_content` o `Write` que no lanza
+  error no garantiza contenido en disco ni en el índice de Obsidian — genera
+  nodos fantasma en el grafo. Siempre leer de vuelta antes del `[OK]`.
 
 ## Relación con otros comandos SWL
 
@@ -458,6 +540,7 @@ Produce:
 
 ```
 [OK] Export creado: F:\Google Drive\Developer\Obsidian\Vault\SWL\00-Inbox\2026-04-16_2130_export-sigaf.md (487 palabras)
+[OK] Verificación post-escritura: 2980 chars, secciones OK
 [OK] Vía: MCP Obsidian (puerto 27124)
 [OK] Enlace canónico: [[DEV - SIGAF]]
 
@@ -467,6 +550,15 @@ Próximo paso: al abrir el vault, ejecuta:
 
 ## Historial de cambios del comando
 
+- **v1.4.1** (2026-05-18) — **Paso 4b — Verificación post-escritura**
+  obligatoria tras cada escritura MCP o filesystem. Origen: exports MCP fallidos
+  (40101 / vault activo incorrecto) dejaron pestañas y nodos en el grafo sin
+  archivo en disco o con cuerpo vacío; reconstrucción manual desde
+  `COMPACTACION.md`. Criterios: existencia, ≥500 chars (o ≥200 con frontmatter
+  completo), secciones de export, anti-fantasma; un reintento con canal alternativo;
+  no reportar `[OK]` sin verificación. Anti-patrón y ejemplos del Paso 5
+  actualizados.
+
 - **v1.4.0** (2026-05-13) — Agregados Pasos 0c y 0d con verificación previa
   del vault activo de Obsidian y de la apiKey del MCP. Origen: sesión
   2026-05-13 con autorización ampliada del usuario para promover docs;
@@ -488,4 +580,4 @@ Próximo paso: al abrir el vault, ejecuta:
   el orden de preferencia (MCP primero, filesystem como fallback explícito)
   y agrega la nota de "tools deferred ≠ tools ausentes" en anti-patrones.
   Aplicación de la regla `consultar-vault-primero.md § Workflow forzoso
-  para escritura al vault`.
+para escritura al vault`.

package/comandos/swl/nemesis.md

@@ -228,9 +228,30 @@ Cada `evaluacion.json` sigue el schema `nemesis-evaluacion-json` v1.0.0.
 
 ### Veredicto JSON
 
-- `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.
+Los tres status del JSON estructurado del evaluator (definidos canónicamente
+en `agentes/nemesis-auditor-swl.md § Veredicto status`):
+
+- **`status: "PASS"`** — convergencia. 0 críticos + 0 altos. Pueden quedar
+  hallazgos MEDIOS/BAJOS/informativos. El loop termina con éxito.
+
+- **`status: "NEEDS_IMPROVEMENT"`** — hay críticos o altos pero **todos** tienen
+  `accion_sugerida` concreta + `agente_recomendado` válido. El comando con
+  `--remediar` invoca al `orquestador-swl` automáticamente. Sin `--remediar`,
+  el reporte queda como acción pendiente para el usuario.
+
+- **`status: "FAIL"`** — hay al menos un hallazgo que cumple cualquiera de:
+  - Veto items según `reglas/gobernanza.md § Veto items`.
+  - Cambio arquitectural ambiguo (requiere ADR / decisión del usuario).
+  - Decisión de producto (comportamiento esperado no definido).
+  - Datos de entrada inválidos en el alcance auditado.
+
+  El loop se detiene de inmediato y escala a Recovery Catalog. Origen del
+  refuerzo: SIGAF sesión 2026-05-21 (alineación L2 — el comando y el agente
+  deben tener idéntico criterio de FAIL para evitar loops vacíos).
+
+**Regla de consistencia**: si esta sección del comando y la del agente
+diverge en wording, el agente es la fuente de verdad operacional (lo
+implementa). Actualizar el comando para alinear, NO al revés.
 
 ## Costo estimado
 
@@ -299,6 +320,52 @@ bugs adyacentes que el fix original no cubrió.
 /swl:nemesis --redistribuir --modulo backend/app/auth
 ```
 
+## Inyectar foco adicional durante el loop con `SendMessage`
+
+Durante una ejecución `--remediar` larga (8-30 turnos en módulos grandes), el
+usuario humano puede observar que el evaluator está siguiendo una pista débil
+o ignorando una sospecha concreta. **No es necesario abortar el comando** —
+usar `SendMessage` para inyectar foco adicional al agente en curso sin perder
+el progreso del loop.
+
+Patrón validado (origen: SIGAF sesión 2026-05-21, mejora D1):
+
+```
+# El usuario ve en el chat que la iteración 2 está auditando solo
+# permisos y olvida revisar el invariante de auditoría.
+# SendMessage al agente activo:
+
+SendMessage({
+  to: "nemesis-auditor-swl",   // o el nombre asignado del agente activo
+  message: "Antes de cerrar iteración 2: revisa también el invariante de
+            auditoría inmutable en module/audit/handlers.py. Sospecho que
+            handle_revoke() escribe a la tabla aprobaciones_historial sin
+            verificar que el VBO original siga vigente."
+});
+```
+
+El agente recibe el mensaje en su próximo turno y lo trata como instrucción
+adicional sin reiniciar el loop. El registro `audit/findings/iter-N/` queda
+intacto.
+
+**Cuándo aplicar**:
+
+- El loop lleva ≥2 iteraciones y el reporte sugiere que olvida un patrón obvio
+  para el contexto del módulo.
+- Se detecta que el evaluator está dando vueltas sobre el mismo hallazgo de
+  baja severidad y conviene priorizar otra zona del código.
+- El usuario tiene contexto adicional (incidente reciente, decisión de ADR
+  no documentado en CLAUDE.md) que el agente no puede inferir solo.
+
+**Cuándo NO aplicar**:
+
+- La iteración actual está progresando bien — no interrumpir loops que
+  convergen.
+- El cambio que se quiere inyectar es de scope (cambiar `--modulo`): ahí sí
+  abortar con Ctrl+C, reset con `--reset-plan` y re-invocar.
+- Inyectar instrucciones contradictorias con el plan congelado del loop —
+  viola regla `seguridad-agentes.md § Anti-proxy-goal-drift`.
+
 ## Regla obligatoria sobre las citas archivo:línea del reporte
 
 Cuando se actúe sobre un hallazgo `archivo:linea` reportado por el evaluator,

package/comandos/swl/release.md

@@ -174,9 +174,69 @@ y debe versionarse.
 
 ## Paso 7 — Generar CHANGELOG
 
-Lee CHANGELOG.md existente (o créalo). Agrega entrada al inicio con formato Keep a Changelog:
+Desde v1.6.5 este paso usa el skill `changelog-generator` para parsear
+Conventional Commits y producir el bloque listo para insertar (ADR-0029).
 
-- Secciones: Funcionalidades nuevas, Correcciones, Mejoras de rendimiento, Cambios internos, Breaking Changes, Estadísticas.
+### Paso 7.1 — Cargar skill y previsualizar
+
+```
+Skill("changelog-generator")
+```
+
+Ejecutar el parser determinista contra los commits del rango actual:
+
+```bash
+node habilidades/changelog-generator/scripts/parse-commits.js \
+  --from <tag-anterior> --to HEAD --version <nueva-version> --format markdown
+```
+
+El script imprime el bloque markdown listo para insertar Y reporta a stderr
+el ratio de conformidad Conventional Commits. Categorías generadas en orden
+canónico: Breaking changes → Nuevas funcionalidades → Correcciones →
+Mejoras de rendimiento → Cambios internos → Reversiones → Evoluciones de
+skills/agentes → Mantenimiento → Otros.
+
+### Paso 7.2 — Gate de conformidad
+
+Verificar la conformidad (impresa a stderr o vía `--format json`):
+
+- **>= 80% conformidad**: continuar a 7.3.
+- **< 80% conformidad**: detenerse y reportar al usuario los commits caídos
+  bajo "Otros". Pedir decisión:
+  1. Continuar con el bloque generado (los "Otros" quedan al final del CHANGELOG).
+  2. Abortar release y reescribir commits no conformes (`git rebase -i`).
+  3. Editar manualmente la sección "Otros" antes de insertar.
+
+NO continuar automáticamente con conformidad baja — el changelog público
+queda confuso.
+
+### Paso 7.3 — Insertar en CHANGELOG.md
+
+Leer `CHANGELOG.md` actual:
+- Si no existe: crear con header `# Changelog\n\n` y luego el bloque nuevo.
+- Si existe: insertar el bloque nuevo inmediatamente después del header
+  `# Changelog` (antes de la entrada anterior).
+
+Escritura atómica obligatoria (regla CLAUDE.md). Usar `atomicWriteSync` desde
+`hooks/lib/atomic-write.js` cuando se llame programáticamente.
+
+### Paso 7.4 — Verificar entrada generada
+
+```bash
+head -40 CHANGELOG.md
+```
+
+Confirmar:
+- Header `## [<nueva-version>] - YYYY-MM-DD` presente.
+- Categorías generadas tienen contenido coherente con los commits del rango.
+- Breaking changes (si los hay) aparecen al inicio.
+
+### Fallback manual (legacy v1.6.4 y anterior)
+
+Si el parser falla o el skill no está disponible, mantener el flujo manual
+de versiones previas:
+- Secciones: Funcionalidades nuevas, Correcciones, Mejoras de rendimiento,
+  Cambios internos, Breaking Changes, Estadísticas.
 - Descripciones legibles por humanos (sin prefijo feat:/fix:).
 - Omitir commits style: y test: del changelog público.
 

package/comandos/swl/salud.md

@@ -347,6 +347,38 @@ Documentación completa en `@docs/variables-entorno.md`.
 Este paso siempre se ejecuta (no es opt-in) — la calidad de CLAUDE.md
 es métrica continua del sistema.
 
+## Paso 5g — Smoke test de servidores MCP (opt-in)
+
+Si el proyecto declara servidores MCP en `.claude/settings.json` o en
+`~/.cursor/mcp.json` o `~/.claude/settings.json` (global), ejecutar un smoke
+test rápido para detectar configuraciones rotas antes de que fallen en uso
+interactivo:
+
+```bash
+python scripts/mcp-orchestrator.py status --json 2>/dev/null
+```
+
+El orchestrator levanta un proceso MCP fresh por cada server configurado y
+reporta:
+
+- `status: "OK"` — handshake completo + lista de tools devuelta correctamente
+- `status: "ERROR"` — fallo de handshake, autenticación o spawn
+
+Casos detectables que `/swl:salud` debe reportar:
+
+| Síntoma | Causa probable | Acción sugerida |
+|---|---|---|
+| `40101 Authorization required` | apiKey desincronizada entre cliente y plugin | Verificar `HKCU\Environment` (Windows) o variable de entorno del shell coincide con apiKey del plugin |
+| `Server failed to start` | Binario no encontrado en `command` | Verificar path absoluto del binario |
+| `Connection refused` | Plugin/servicio destino no corriendo | Iniciar plugin (ej. Obsidian con Local REST API activo) |
+| `env=None passed` | Config tiene `"env": {}` literal — rompe herencia | Omitir clave `env` por completo en JSON (no dejar vacía) |
+
+Si no hay servers configurados, este paso se omite silenciosamente.
+
+Este smoke test detecta drift de apiKeys ANTES de que el usuario interactivo
+encuentre 40101 en una invocación crítica. Recomendado ejecutar como parte del
+flujo `/swl:salud` periódico mensual.
+
 ## Paso 5e — Verificación de drift de skills (skills-lock)
 
 Si existe `manifiestos/skills-lock.json`, comparar el hash actual de cada

package/comandos/swl/verificar.md

@@ -21,6 +21,7 @@ Eres el coordinador de verificación SWL. Tu trabajo es asegurar la calidad del
 | `--until-converge` | Itera el ciclo verificar → corregir → re-verificar hasta convergencia (0 hallazgos CRÍTICO + ALTO + MAYOR en una pasada nueva) o hasta alcanzar `--max-iter`. Compatible con `--ultra` y `--solo-codigo`/`--solo-seguridad`. Ver sección "Modo `--until-converge`". |
 | `--max-iter=N` | Límite de iteraciones para `--until-converge`. Default: `5`. Rango válido: 1-10. |
 | `--no-prompt` | Suprime la confirmación interactiva entre pasadas (para CI). Solo aplica con `--until-converge`. |
+| `--ci-aware` | Antes de declarar convergencia natural en `--until-converge`, espera el estado terminal del CI sobre el HEAD pushed. Convergencia confirmada solo si CI verde + revisores APROBADO. CI rojo reabre el loop con los hallazgos del workflow como pasada N+1. Útil cuando el alcance modifica migraciones, seeds o tests E2E que el CI valida pero los revisores locales no. Ver sección 4.6.7. |
 
 ### Cuándo usar `--ultra`
 
@@ -286,9 +287,18 @@ El loop se detiene cuando se cumple **cualquiera** de estas señales (la primera
 | **A — éxito** | La pasada N produce 0 hallazgos nuevos de severidad `CRÍTICO`, `ALTO` o `MAYOR` | Convergencia natural — la fase está limpia |
 | **B — adversarial** | La pasada N+1 introduce ≥5 hallazgos NUEVOS sobre el código corregido en la pasada N | Las correcciones están introduciendo regresión; escalar al usuario |
 | **C — máximo** | Se alcanza `--max-iter=N` (default 5) sin converger | No-convergente; reportar al usuario |
+| **D — CI verde** (solo con `--ci-aware`) | Tras Señal A, el CI sobre el HEAD pushed termina en estado `success` para todos los workflows aplicables al SHA | Convergencia confirmada cross-stack (revisores + tests locales + CI con migraciones/seeds/E2E) |
 
 Los hallazgos `MEDIO`, `BAJO` y `SUGERENCIA` no rompen convergencia — se acumulan como deuda técnica documentada.
 
+**Importante sobre la Señal D**: sin `--ci-aware`, la convergencia natural se evalúa SOLO contra revisores + suite local. Esto NO detecta bugs que solo emergen en CI:
+- Migraciones aplicadas a BD limpia (CI fresh) vs BD productiva (donde seeds ya corrieron).
+- Seeds dependientes que fallan en cadena por orden migración↔seed invertido.
+- Tests E2E que requieren datos demo.
+- Partial unique indexes con `WHERE` que no son predicado puro (rompen en CI fresh).
+
+Origen del flag: SIGAF 2026-05-15 declaró convergencia natural en Pasada 3 (commit `4d2fb23`) basado en revisores APROBADO + 2161 pytest passed. 3 commits posteriores el CI Playwright reveló 3 tests E2E fallando por bug introducido en la propia Pasada 2 (migración 0061 con índice `WHERE` que rompía seeds en BD limpia). El loop cerró sin validar la integración E2E.
+
 ### 4.6.2 — Control de pausa entre iteraciones
 
 Antes de invocar al implementador para aplicar correcciones de la pasada N, el comando muestra un resumen y permite al usuario decidir:
@@ -381,9 +391,63 @@ El VERIFICACION.md reportado al usuario al final del loop incluye una sección a
 - Estado persistido: `.planning/fases/0N-converge-run-[timestamp].json`
 ```
 
-### 4.6.7 — Backward compatibility
+### 4.6.7 — Protocolo `--ci-aware` (Señal D)
+
+Cuando `--ci-aware` está activo, el bucle de convergencia se extiende con un gate adicional ANTES de declarar Señal A como cierre definitivo:
+
+**Precondición**: el último commit de la pasada N debe estar pusheado a la rama remota. Si no:
+
+```
+Pasada N converge natural pero --ci-aware requiere CI sobre HEAD pushed.
+
+HEAD local: abc1234 (no pusheado)
+[p] push automático + monitor CI
+[c] continuar sin --ci-aware (convergencia solo local)
+[q] abortar — pushear manualmente y re-invocar
+```
+
+Con `--no-prompt`: default es `p` (push automático).
+
+**Algoritmo de espera**:
+
+1. Tras Señal A, obtener SHA actual de `HEAD` y ejecutar `git ls-remote origin <rama>` para confirmar que está sincronizado.
+2. Listar workflows aplicables al SHA con:
+   ```bash
+   gh run list --branch <rama> --limit 10 \
+     --json status,conclusion,name,headSha \
+     --jq '.[] | select(.headSha == "<SHA>")'
+   ```
+3. Esperar usando la regla global `monitor-ci.md` (patrón Monitor con `gh --jq`, NO `| jq`).
+4. Clasificar resultado:
+   - **Todos `completed`+`success`** → Señal D confirmada, convergencia válida.
+   - **Algún workflow en `failure` o `cancelled`** → reabrir loop. Los hallazgos se extraen del log con `gh run view <run-id> --log-failed` y se procesan como pasada N+1.
+   - **Algún workflow `skipped` legítimo** (no se disparó por `paths:` filter) → NO suma al gate; convergencia válida si los aplicables están `success`.
+   - **Workflows aún en `in_progress` después del timeout configurado en monitor-ci** → escalar al usuario, no cerrar convergencia.
+
+**Workflows aplicables vs no aplicables**:
+
+`gh run list` puede listar workflows que NO se dispararon en el SHA actual por filtros `paths:` en el `on:` del workflow (ej. cambio solo en frontend no dispara Backend CI). Esos son **legítimamente ausentes**, no fallos.
+
+El gate solo evalúa workflows que **sí se dispararon en el SHA**. La verificación es:
+
+```bash
+gh run list --branch <rama> --limit 10 --json headSha,name,status,conclusion \
+  --jq '[.[] | select(.headSha | startswith("<sha-corto>"))] | all(.[]; .status == "completed" and .conclusion == "success")'
+```
 
-Sin `--until-converge`, el comportamiento del comando es idéntico al actual: una sola pasada, ofrece correcciones tras el veredicto, sale. El flag es 100% aditivo.
+Output `true` → Señal D. `false` con detalle → reabrir loop.
+
+**Anti-patrones explícitos**:
+
+- **Tratar timeout del monitor como "verde por default"**: el timeout significa "estado desconocido", NO `success`. Re-armar monitor o escalar al usuario.
+- **Sumar skipped legítimo como pass sin matizar**: si el workflow X no se disparó porque el commit solo tocó docs, está bien, pero el reporte final debe enumerarlo: "Frontend CI: skipped por filtro paths (commit toca solo backend/)".
+- **Asumir verde porque `git push` retornó exit 0**: push exitoso ≠ CI verde. push solo confirma que GitHub aceptó el push.
+
+Origen: regla global `monitor-ci.md` cubre este protocolo en detalle. Esta sección lo activa específicamente para `/swl:verificar`.
+
+### 4.6.8 — Backward compatibility
+
+Sin `--until-converge`, el comportamiento del comando es idéntico al actual: una sola pasada, ofrece correcciones tras el veredicto, sale. Los flags `--until-converge` y `--ci-aware` son 100% aditivos.
 
 ## Paso 5 — Verificación de criterios de aceptación
 
@@ -401,6 +465,56 @@ Ejemplo de tabla de verificación:
 | El usuario puede crear una cuenta | Test e2e / manual | PASA / FALLA / PENDIENTE |
 ```
 
+### Smoke test manual obligatorio para módulos frontend grandes
+
+Origen: SIGAF sesión 2026-05-21 (mejora D2). Cuando el alcance de la
+verificación toca un **componente frontend > 2,000 LOC** (típicamente módulos
+como `/catalogos`, `/contratos`, `/expedientes` que crecen orgánicamente), la
+verificación automática NO es suficiente. Los tests unitarios pueden pasar y
+el linter quedar limpio mientras el componente está **roto en el render
+real** (estado inicial mal calculado, evento que no propaga, route guard que
+redirige en loop, error de hidratación SSR que solo aparece en producción).
+
+Reglas duras para esta sub-categoría:
+
+1. **Detección automática del trigger**: si el revisor de código reporta
+   ≥1 archivo en `frontend/` con LOC > 2000, OR la suma de LOC de archivos
+   modificados en el último commit en `frontend/` excede 1500, activar este
+   sub-paso.
+
+2. **Smoke test manual obligatorio**: el VERIFICACION.md DEBE incluir un
+   bloque `## Smoke test manual (módulo frontend grande)` con los siguientes
+   checks que el usuario humano marca PASA/FALLA antes del merge:
+
+   ```markdown
+   ## Smoke test manual — frontend/<modulo> (X LOC)
+
+   - [ ] Arranca el dev server sin errores en consola
+   - [ ] Renderiza la pantalla principal del módulo sin pantalla blanca
+   - [ ] Navegación a cada sub-ruta funciona (listar nombres)
+   - [ ] Acciones CRUD principales completan flujo end-to-end
+   - [ ] No hay warnings de hidratación en consola (SSR si aplica)
+   - [ ] Layout responsive funciona en viewport mobile + desktop
+   - [ ] [Si aplica] Web vitals sin regresión vs commit anterior
+   ```
+
+3. **NO marcar verificación como APROBADA** hasta que el bloque esté completo
+   o el usuario explícitamente exente checks específicos con justificación.
+
+4. **El comando NO ejecuta el smoke automáticamente** (requiere browser
+   humano); su responsabilidad es **incluir el bloque en VERIFICACION.md** y
+   marcar la decisión de verificación como `APROBADO_CON_OBSERVACIONES`
+   hasta que el bloque se cierre.
+
+**Cuándo NO aplicar este sub-paso**:
+
+- Módulos backend puros (cobertura suficiente con tests de integración).
+- Cambios cosméticos a componentes frontend grandes (typo en texto, ajuste
+  de color de un botón) — la heurística LOC sigue disparándose pero el
+  usuario puede exentar con `[exento: cambio cosmético en X líneas]`.
+- Módulos con cobertura E2E > 70% probada (webapp-testing, Playwright,
+  Cypress) — el smoke automático cubre la necesidad.
+
 ## Paso 6 — Consolidación y generación del VERIFICACION.md
 
 Consolida todos los hallazgos en `.planning/fases/0N-VERIFICACION.md`: