@saulwade/swl-ses 2.2.4 → 2.3.1

package/habilidades/state-inconsistency-auditor-swl/recursos/coupled-state-patterns.md

@@ -1,147 +1,147 @@
-# Patrones de Estado Acoplado — Language-Agnostic
-
-9 patrones de estado acoplado frecuentes en sistemas Python, TypeScript, Go, Rust, Java y C#.
-
----
-
-## Patrón 1: Balance ↔ Caché derivada
-
-**Descripción**: un valor base (balance de cuenta, stock de inventario, crédito disponible) tiene una caché calculada a partir de él (porcentaje disponible, categoría de riesgo, tier de cliente).
-
-**Invariante**: la caché debe reflejar el balance actual, no el del momento en que se calculó.
-
-**Paths de mutación riesgosos**: cualquier operación que modifica el balance directamente sin pasar por el flujo que actualiza la caché.
-
-**Trigger típico**: función de ajuste manual, importación masiva, o corrección administrativa que escribe el balance sin llamar al servicio que recalcula la caché.
-
-**Consecuencia**: decisiones que leen la caché (¿aplica descuento? ¿otorgar crédito?) usan datos obsoletos.
-
----
-
-## Patrón 2: Registro principal ↔ Índice secundario
-
-**Descripción**: una tabla o colección tiene un índice secundario (índice invertido, tabla de búsqueda rápida, lista de IDs por categoría) que debe estar sincronizado con la tabla principal.
-
-**Invariante**: toda entrada en la tabla principal tiene exactamente una entrada correspondiente en el índice secundario (o exactamente ninguna, según el diseño).
-
-**Paths de mutación riesgosos**: delete de la tabla principal sin delete del índice; insert sin insert correspondiente; update que cambia la clave del índice sin actualizar el índice.
-
-**Trigger típico**: función de "purga" o "limpieza" que borra de la tabla principal pero olvida el índice. O migración que popula la tabla principal pero no regenera el índice.
-
-**Consecuencia**: búsquedas por índice devuelven resultados incorrectos (IDs que ya no existen, o registros que no aparecen en búsqueda aunque existan).
-
----
-
-## Patrón 3: Contador agregado ↔ Suma de partes
-
-**Descripción**: un contador de totales (total de pedidos, total de puntos, total de items activos) debe ser igual a la suma de los contadores individuales.
-
-**Invariante**: `total == sum(individuales)` siempre.
-
-**Paths de mutación riesgosos**: operaciones que modifican un contador individual sin ajustar el total. Frecuente en operaciones de batch donde el total se actualiza una sola vez al final pero un error parcial deja los individuales en estado inconsistente.
-
-**Trigger típico**: transacción fallida a mitad que actualiza N de M elementos pero no revierte el total; o función que incrementa directamente el conteo individual sin notificar al agregador.
-
-**Consecuencia**: reportes y dashboards muestran cifras incorrectas; límites y cuotas se aplican con base en datos erróneos.
-
----
-
-## Patrón 4: Sesión / Permiso derivado ↔ Recurso de origen
-
-**Descripción**: un objeto de sesión, token, o permiso derivado almacena un snapshot de los permisos o atributos del actor al momento de su creación. El actor puede cambiar después.
-
-**Invariante**: depende del diseño. Si los permisos se evalúan en tiempo de solicitud, el objeto derivado debe reflejar el estado actual del actor. Si se usan permisos fijados al momento de creación, el invariante es documentado explícitamente.
-
-**Paths de mutación riesgosos**: revocar permisos al actor sin invalidar sesiones activas; cambiar el rol del actor sin forzar re-autenticación; eliminar al actor sin expirar sus tokens.
-
-**Trigger típico**: función de "deshabilitar cuenta" que setea `is_active=False` en el usuario pero no invalida los tokens JWT o sesiones existentes.
-
-**Consecuencia**: actor deshabilitado sigue operando hasta que el token expira naturalmente.
-
----
-
-## Patrón 5: Posición ↔ Factor de salud cacheado
-
-**Descripción**: un recurso con múltiples atributos (posición de deuda: monto + colateral + fecha + valor de mercado del colateral) tiene un factor calculado (ratio LTV, score de riesgo, estado de salud) que se cachea por rendimiento.
-
-**Invariante**: el factor cacheado debe recalcularse cada vez que cualquiera de sus inputs cambia.
-
-**Paths de mutación riesgosos**: actualizar cualquier input del cálculo sin invalidar o recalcular el factor cacheado.
-
-**Trigger típico**: función que actualiza el colateral sin llamar a `recalcular_factor()`. O función de ajuste de precio que modifica el valor de mercado sin propagar la invalidación de caché.
-
-**Consecuencia**: decisiones de riesgo (¿emitir alerta? ¿bloquear operación?) usan un factor obsoleto.
-
----
-
-## Patrón 6: Replica / Proyección ↔ Origen CDC
-
-**Descripción**: un sistema mantiene una replica o proyección de datos de origen para acelerar lecturas (tabla denormalizada, proyección CQRS, replica de lectura, caché materializada). El origen puede cambiar vía CDC (Change Data Capture), eventos de dominio, o sincronización periódica.
-
-**Invariante**: la replica debe converger al estado del origen dentro de la ventana de latencia acordada.
-
-**Paths de mutación riesgosos**: escrituras directas al origen que no emiten el evento de dominio necesario para actualizar la replica; fallos en el consumer de eventos que quedan silenciosos; migraciones que modifican el origen sin reprocesar los eventos para actualizar la replica.
-
-**Trigger típico**: endpoint de "corrección de datos" que escribe directo a la BD origen sin publicar el evento de dominio correspondiente.
-
-**Consecuencia**: lecturas de la replica devuelven datos obsoletos indefinidamente.
-
----
-
-## Patrón 7: Inventario total ↔ Items en almacén (por ubicación)
-
-**Descripción**: el inventario total de un SKU es la suma de los items en cada almacén o ubicación. Se mantiene desnormalizado por rendimiento.
-
-**Invariante**: `inventario_total[SKU] == sum(items_por_ubicacion[ubicacion][SKU] for ubicacion in todas)`
-
-**Paths de mutación riesgosos**: movimiento entre almacenes que decrementa una ubicación sin incrementar la otra; recepción en almacén sin incrementar el total; ajuste de inventario físico que corrige la ubicación sin propagar al total.
-
-**Trigger típico**: función de "ajuste de cierre" que actualiza el stock físico de un almacén sin pasar por la capa de negocio que mantiene el total sincronizado.
-
-**Consecuencia**: órdenes de compra se emiten sobre stock inexistente; o stock disponible no se vende por parecer agotado.
-
----
-
-## Patrón 8: Estado de workflow ↔ Timestamps de auditoría
-
-**Descripción**: una entidad con workflow (pedido, solicitud, tarea) almacena su estado actual y los timestamps de cada transición. El timestamp de la última transición debe corresponder al estado actual.
-
-**Invariante**: `estado_actual` siempre tiene un timestamp asociado que refleja cuándo se alcanzó ese estado.
-
-**Paths de mutación riesgosos**: funciones que cambian el estado sin registrar el timestamp; o funciones que registran el timestamp sin actualizar el estado.
-
-**Trigger típico**: función de "forzar estado" en panel de administración que escribe `estado = 'COMPLETADO'` directamente sin pasar por la máquina de estados que registra `completado_en = now()`.
-
-**Consecuencia**: reportes de tiempo de ciclo son incorrectos; SLAs no se calculan bien; auditorías de cumplimiento fallan.
-
----
-
-## Patrón 9: Configuración global ↔ Snapshot por instancia
-
-**Descripción**: hay una configuración global (tasa de impuesto, precio de tarifa, límite de política) y objetos que almacenan el valor que tenía la configuración en el momento de su creación (tasa de impuesto aplicada a esta factura, precio de tarifa al momento de la reserva).
-
-**Invariante**: el snapshot por instancia debe preservar el valor histórico, nunca actualizarse cuando cambia la configuración global. Pero si hay un bug en la creación, el snapshot puede haber capturado un valor incorrecto.
-
-**Paths de mutación riesgosos**: función que no captura el snapshot al crear la instancia y usa la configuración global en tiempo de lectura; o función de retroactiva que sobreescribe snapshots históricos con el valor actual de la configuración.
-
-**Trigger típico**: migración de datos que "normaliza" snapshots históricos al valor actual de la configuración global, destruyendo la trazabilidad.
-
-**Consecuencia**: recálculos retroactivos producen cifras incorrectas; auditorías de facturación no reproducen los valores originales.
-
----
-
-## Patrones de enmascaramiento
-
-Código defensivo que oculta invariantes rotos en lugar de detectarlos:
-
-| Patrón | Código típico | Por qué es señal de alerta |
-|--------|--------------|---------------------------|
-| Ternario de clamp | `a > b ? a - b : 0` | Si el invariante se mantuviera, `a` nunca sería menor que `b` |
-| Try/catch vacío | `try { ... } catch {}` | El revert por estado roto se captura y se ignora |
-| Early exit en cero | `if value == 0: return` | Omite el cómputo cuando el estado roto produce cero |
-| Cap con min() | `min(calculado, disponible)` | El over-counting es el bug; `min()` solo evita el error visible |
-| Fallback a default | `valor = d.get(k, 0)` | Si la key debería existir pero fue eliminada sin limpiar el par, el default enmascara el dato faltante |
-
-Cuando se encuentra cualquiera de estos patrones en código que involucra dos valores acoplados, rastrear si el patrón existe porque el invariante ya estaba roto en algún path de mutación.
-
-<!-- Adaptado de nemesis-auditor-main bajo MIT License (https://github.com/0xiehnnkta/nemesis-auditor) -->
+# Patrones de Estado Acoplado — Language-Agnostic
+
+9 patrones de estado acoplado frecuentes en sistemas Python, TypeScript, Go, Rust, Java y C#.
+
+---
+
+## Patrón 1: Balance ↔ Caché derivada
+
+**Descripción**: un valor base (balance de cuenta, stock de inventario, crédito disponible) tiene una caché calculada a partir de él (porcentaje disponible, categoría de riesgo, tier de cliente).
+
+**Invariante**: la caché debe reflejar el balance actual, no el del momento en que se calculó.
+
+**Paths de mutación riesgosos**: cualquier operación que modifica el balance directamente sin pasar por el flujo que actualiza la caché.
+
+**Trigger típico**: función de ajuste manual, importación masiva, o corrección administrativa que escribe el balance sin llamar al servicio que recalcula la caché.
+
+**Consecuencia**: decisiones que leen la caché (¿aplica descuento? ¿otorgar crédito?) usan datos obsoletos.
+
+---
+
+## Patrón 2: Registro principal ↔ Índice secundario
+
+**Descripción**: una tabla o colección tiene un índice secundario (índice invertido, tabla de búsqueda rápida, lista de IDs por categoría) que debe estar sincronizado con la tabla principal.
+
+**Invariante**: toda entrada en la tabla principal tiene exactamente una entrada correspondiente en el índice secundario (o exactamente ninguna, según el diseño).
+
+**Paths de mutación riesgosos**: delete de la tabla principal sin delete del índice; insert sin insert correspondiente; update que cambia la clave del índice sin actualizar el índice.
+
+**Trigger típico**: función de "purga" o "limpieza" que borra de la tabla principal pero olvida el índice. O migración que popula la tabla principal pero no regenera el índice.
+
+**Consecuencia**: búsquedas por índice devuelven resultados incorrectos (IDs que ya no existen, o registros que no aparecen en búsqueda aunque existan).
+
+---
+
+## Patrón 3: Contador agregado ↔ Suma de partes
+
+**Descripción**: un contador de totales (total de pedidos, total de puntos, total de items activos) debe ser igual a la suma de los contadores individuales.
+
+**Invariante**: `total == sum(individuales)` siempre.
+
+**Paths de mutación riesgosos**: operaciones que modifican un contador individual sin ajustar el total. Frecuente en operaciones de batch donde el total se actualiza una sola vez al final pero un error parcial deja los individuales en estado inconsistente.
+
+**Trigger típico**: transacción fallida a mitad que actualiza N de M elementos pero no revierte el total; o función que incrementa directamente el conteo individual sin notificar al agregador.
+
+**Consecuencia**: reportes y dashboards muestran cifras incorrectas; límites y cuotas se aplican con base en datos erróneos.
+
+---
+
+## Patrón 4: Sesión / Permiso derivado ↔ Recurso de origen
+
+**Descripción**: un objeto de sesión, token, o permiso derivado almacena un snapshot de los permisos o atributos del actor al momento de su creación. El actor puede cambiar después.
+
+**Invariante**: depende del diseño. Si los permisos se evalúan en tiempo de solicitud, el objeto derivado debe reflejar el estado actual del actor. Si se usan permisos fijados al momento de creación, el invariante es documentado explícitamente.
+
+**Paths de mutación riesgosos**: revocar permisos al actor sin invalidar sesiones activas; cambiar el rol del actor sin forzar re-autenticación; eliminar al actor sin expirar sus tokens.
+
+**Trigger típico**: función de "deshabilitar cuenta" que setea `is_active=False` en el usuario pero no invalida los tokens JWT o sesiones existentes.
+
+**Consecuencia**: actor deshabilitado sigue operando hasta que el token expira naturalmente.
+
+---
+
+## Patrón 5: Posición ↔ Factor de salud cacheado
+
+**Descripción**: un recurso con múltiples atributos (posición de deuda: monto + colateral + fecha + valor de mercado del colateral) tiene un factor calculado (ratio LTV, score de riesgo, estado de salud) que se cachea por rendimiento.
+
+**Invariante**: el factor cacheado debe recalcularse cada vez que cualquiera de sus inputs cambia.
+
+**Paths de mutación riesgosos**: actualizar cualquier input del cálculo sin invalidar o recalcular el factor cacheado.
+
+**Trigger típico**: función que actualiza el colateral sin llamar a `recalcular_factor()`. O función de ajuste de precio que modifica el valor de mercado sin propagar la invalidación de caché.
+
+**Consecuencia**: decisiones de riesgo (¿emitir alerta? ¿bloquear operación?) usan un factor obsoleto.
+
+---
+
+## Patrón 6: Replica / Proyección ↔ Origen CDC
+
+**Descripción**: un sistema mantiene una replica o proyección de datos de origen para acelerar lecturas (tabla denormalizada, proyección CQRS, replica de lectura, caché materializada). El origen puede cambiar vía CDC (Change Data Capture), eventos de dominio, o sincronización periódica.
+
+**Invariante**: la replica debe converger al estado del origen dentro de la ventana de latencia acordada.
+
+**Paths de mutación riesgosos**: escrituras directas al origen que no emiten el evento de dominio necesario para actualizar la replica; fallos en el consumer de eventos que quedan silenciosos; migraciones que modifican el origen sin reprocesar los eventos para actualizar la replica.
+
+**Trigger típico**: endpoint de "corrección de datos" que escribe directo a la BD origen sin publicar el evento de dominio correspondiente.
+
+**Consecuencia**: lecturas de la replica devuelven datos obsoletos indefinidamente.
+
+---
+
+## Patrón 7: Inventario total ↔ Items en almacén (por ubicación)
+
+**Descripción**: el inventario total de un SKU es la suma de los items en cada almacén o ubicación. Se mantiene desnormalizado por rendimiento.
+
+**Invariante**: `inventario_total[SKU] == sum(items_por_ubicacion[ubicacion][SKU] for ubicacion in todas)`
+
+**Paths de mutación riesgosos**: movimiento entre almacenes que decrementa una ubicación sin incrementar la otra; recepción en almacén sin incrementar el total; ajuste de inventario físico que corrige la ubicación sin propagar al total.
+
+**Trigger típico**: función de "ajuste de cierre" que actualiza el stock físico de un almacén sin pasar por la capa de negocio que mantiene el total sincronizado.
+
+**Consecuencia**: órdenes de compra se emiten sobre stock inexistente; o stock disponible no se vende por parecer agotado.
+
+---
+
+## Patrón 8: Estado de workflow ↔ Timestamps de auditoría
+
+**Descripción**: una entidad con workflow (pedido, solicitud, tarea) almacena su estado actual y los timestamps de cada transición. El timestamp de la última transición debe corresponder al estado actual.
+
+**Invariante**: `estado_actual` siempre tiene un timestamp asociado que refleja cuándo se alcanzó ese estado.
+
+**Paths de mutación riesgosos**: funciones que cambian el estado sin registrar el timestamp; o funciones que registran el timestamp sin actualizar el estado.
+
+**Trigger típico**: función de "forzar estado" en panel de administración que escribe `estado = 'COMPLETADO'` directamente sin pasar por la máquina de estados que registra `completado_en = now()`.
+
+**Consecuencia**: reportes de tiempo de ciclo son incorrectos; SLAs no se calculan bien; auditorías de cumplimiento fallan.
+
+---
+
+## Patrón 9: Configuración global ↔ Snapshot por instancia
+
+**Descripción**: hay una configuración global (tasa de impuesto, precio de tarifa, límite de política) y objetos que almacenan el valor que tenía la configuración en el momento de su creación (tasa de impuesto aplicada a esta factura, precio de tarifa al momento de la reserva).
+
+**Invariante**: el snapshot por instancia debe preservar el valor histórico, nunca actualizarse cuando cambia la configuración global. Pero si hay un bug en la creación, el snapshot puede haber capturado un valor incorrecto.
+
+**Paths de mutación riesgosos**: función que no captura el snapshot al crear la instancia y usa la configuración global en tiempo de lectura; o función de retroactiva que sobreescribe snapshots históricos con el valor actual de la configuración.
+
+**Trigger típico**: migración de datos que "normaliza" snapshots históricos al valor actual de la configuración global, destruyendo la trazabilidad.
+
+**Consecuencia**: recálculos retroactivos producen cifras incorrectas; auditorías de facturación no reproducen los valores originales.
+
+---
+
+## Patrones de enmascaramiento
+
+Código defensivo que oculta invariantes rotos en lugar de detectarlos:
+
+| Patrón | Código típico | Por qué es señal de alerta |
+|--------|--------------|---------------------------|
+| Ternario de clamp | `a > b ? a - b : 0` | Si el invariante se mantuviera, `a` nunca sería menor que `b` |
+| Try/catch vacío | `try { ... } catch {}` | El revert por estado roto se captura y se ignora |
+| Early exit en cero | `if value == 0: return` | Omite el cómputo cuando el estado roto produce cero |
+| Cap con min() | `min(calculado, disponible)` | El over-counting es el bug; `min()` solo evita el error visible |
+| Fallback a default | `valor = d.get(k, 0)` | Si la key debería existir pero fue eliminada sin limpiar el par, el default enmascara el dato faltante |
+
+Cuando se encuentra cualquiera de estos patrones en código que involucra dos valores acoplados, rastrear si el patrón existe porque el invariante ya estaba roto en algún path de mutación.
+
+<!-- Adaptado de nemesis-auditor-main bajo MIT License (https://github.com/0xiehnnkta/nemesis-auditor) -->

package/habilidades/structured-outputs/SKILL.md

@@ -99,7 +99,7 @@ def obtener_structured(
             })
 
         respuesta = llm_client.messages.create(
-            model="claude-sonnet-4-6-20250514",
+            model="claude-sonnet-5",
             max_tokens=2048,
             system=f"Responde SOLO en JSON válido según este schema:\n"
                    f"{json.dumps(response_model.model_json_schema(), indent=2)}",
@@ -291,7 +291,7 @@ El patrón `from_provider` abstrae el proveedor de LLM:
 client = crear_cliente_structured("openai", model="gpt-4o")
 
 # Anthropic
-client = crear_cliente_structured("anthropic", model="claude-sonnet-4-6-20250514")
+client = crear_cliente_structured("anthropic", model="claude-sonnet-5")
 
 # La interfaz es idéntica: client.create(response_model=MiModelo, messages=[...])
 ```

package/habilidades/swl-claudemd/recursos/contrato-aprender.md

@@ -1,83 +1,83 @@
-# Contrato cruzado con /swl:aprender (y todo comando que escriba a CLAUDE.md)
-
-`/swl:aprender` y `/swl:claudemd` operan sobre el mismo archivo desde
-ángulos opuestos: aprender **muta**, claudemd **prescribe contrato**.
-Sin coordinación explícita, una sesión de aprender puede romper el
-contrato silenciosamente.
-
-## El gap arquitectural que esta interacción cierra
-
-`/swl:aprender` Paso 6 Tipo A agrega reglas a `CLAUDE.md` del proyecto.
-El hook `claudemd-bloat-detector.js` (PostToolUse, async, no bloqueante)
-emite nudge tras Write/Edit/MultiEdit sobre CLAUDE.md, pero **el nudge
-llega después** del comando de aprender. Resultado: aprender termina,
-reporta éxito al usuario, y solo después aparece el nudge — con el
-commit ya hecho.
-
-Origen detectado: sesión 2026-05-22 al evaluar el flujo SIGAF→swl-ses.
-CLAUDE.md SIGAF recibió ~25 líneas inline de "Triangulación schema
-cross-stack" sin validación post-mutación → archivo probablemente
-superó el umbral de 200 LOC sin warning consciente.
-
-## Contrato canónico de interacción
-
-Para cualquier comando SWL que escriba a CLAUDE.md del proyecto
-(`/swl:aprender`, `/swl:adoptar-proyecto`, `/swl:nuevo-proyecto`,
-`/swl:claudemd init-project`, futuros comandos similares):
-
-1. **Antes de escribir**: opcional, pero recomendado — leer el tamaño
-   actual del archivo y estimar el delta.
-2. **Después de escribir**: OBLIGATORIO ejecutar el auditor síncrono:
-
-   ```bash
-   node scripts/auditar-claudemd.js --json
-   # o fallback:
-   npx -y @saulwade/swl-ses@latest audit-claudemd --json
-   ```
-
-3. **Evaluar veredicto**:
-   - `OK` → continuar
-   - `WARN tamano-total` → proponer condensar o extraer a `@docs/lessons-<tema>.md`
-   - `WARN bullet-gigante` → proponer condensar a tabla/lista jerárquica
-   - `WARN secciones-canonicas` / `WARN sin-at-references` / `WARN karpathy-reference` → reportar al usuario, permitir continuar
-   - `ERROR placeholders` → **DETENER** y revertir
-
-4. **Re-ejecutar el auditor** tras la corrección hasta veredicto OK o
-   WARN aceptable.
-
-## Doble red de seguridad
-
-El sistema tiene dos capas de protección complementarias:
-
-| Capa | Mecanismo | Cuándo actúa | Bloqueo |
-|------|-----------|--------------|---------|
-| Síncrona | Paso 6.5 de `/swl:aprender` (y equivalente en otros comandos) | Justo después del Write/Edit, antes del reporte final | Bloquea pasos posteriores hasta resolver |
-| Asíncrona | Hook `claudemd-bloat-detector.js` (PostToolUse) | Tras cualquier Write/Edit/MultiEdit a CLAUDE.md (incluso fuera de comandos SWL) | No bloquea — emite nudge a `.planning/evolution/nudges.jsonl` |
-
-La capa síncrona es proactiva (detiene el comando antes de reportar
-éxito). La asíncrona es retroactiva (cubre escrituras desde fuera de
-comandos SWL, ej. edición manual).
-
-## Por qué NO se duplica al hook
-
-El hook async existente cubre el caso de escrituras desde **cualquier
-fuente** (edición manual del usuario, otros comandos, scripts externos).
-Es la red de seguridad universal. La validación síncrona en aprender es
-específica para el flujo del comando — donde el agente puede actuar
-sobre el WARN antes de continuar.
-
-NO crear un hook nuevo dedicado a aprender — duplicaría el rol del
-existente. La invocación síncrona en el Paso 6.5 es suficiente.
-
-## Reglas duras
-
-- `/swl:aprender` Paso 6.5 es OBLIGATORIO si se aplicó Tipo A.
-- `/swl:adoptar-proyecto` Paso 8 debe ejecutar el auditor tras
-  generar/modificar CLAUDE.md.
-- `/swl:nuevo-proyecto` Paso 6 debe ejecutar el auditor tras generar
-  CLAUDE.md inicial.
-- `/swl:claudemd init-project` debe ejecutar el auditor sobre el
-  archivo recién generado.
-
-Cualquier comando futuro que escriba a CLAUDE.md DEBE seguir este
-contrato.
+# Contrato cruzado con /swl:aprender (y todo comando que escriba a CLAUDE.md)
+
+`/swl:aprender` y `/swl:claudemd` operan sobre el mismo archivo desde
+ángulos opuestos: aprender **muta**, claudemd **prescribe contrato**.
+Sin coordinación explícita, una sesión de aprender puede romper el
+contrato silenciosamente.
+
+## El gap arquitectural que esta interacción cierra
+
+`/swl:aprender` Paso 6 Tipo A agrega reglas a `CLAUDE.md` del proyecto.
+El hook `claudemd-bloat-detector.js` (PostToolUse, async, no bloqueante)
+emite nudge tras Write/Edit/MultiEdit sobre CLAUDE.md, pero **el nudge
+llega después** del comando de aprender. Resultado: aprender termina,
+reporta éxito al usuario, y solo después aparece el nudge — con el
+commit ya hecho.
+
+Origen detectado: sesión 2026-05-22 al evaluar el flujo SIGAF→swl-ses.
+CLAUDE.md SIGAF recibió ~25 líneas inline de "Triangulación schema
+cross-stack" sin validación post-mutación → archivo probablemente
+superó el umbral de 200 LOC sin warning consciente.
+
+## Contrato canónico de interacción
+
+Para cualquier comando SWL que escriba a CLAUDE.md del proyecto
+(`/swl:aprender`, `/swl:adoptar-proyecto`, `/swl:nuevo-proyecto`,
+`/swl:claudemd init-project`, futuros comandos similares):
+
+1. **Antes de escribir**: opcional, pero recomendado — leer el tamaño
+   actual del archivo y estimar el delta.
+2. **Después de escribir**: OBLIGATORIO ejecutar el auditor síncrono:
+
+   ```bash
+   node scripts/auditar-claudemd.js --json
+   # o fallback:
+   npx -y @saulwade/swl-ses@latest audit-claudemd --json
+   ```
+
+3. **Evaluar veredicto**:
+   - `OK` → continuar
+   - `WARN tamano-total` → proponer condensar o extraer a `@docs/lessons-<tema>.md`
+   - `WARN bullet-gigante` → proponer condensar a tabla/lista jerárquica
+   - `WARN secciones-canonicas` / `WARN sin-at-references` / `WARN karpathy-reference` → reportar al usuario, permitir continuar
+   - `ERROR placeholders` → **DETENER** y revertir
+
+4. **Re-ejecutar el auditor** tras la corrección hasta veredicto OK o
+   WARN aceptable.
+
+## Doble red de seguridad
+
+El sistema tiene dos capas de protección complementarias:
+
+| Capa | Mecanismo | Cuándo actúa | Bloqueo |
+|------|-----------|--------------|---------|
+| Síncrona | Paso 6.5 de `/swl:aprender` (y equivalente en otros comandos) | Justo después del Write/Edit, antes del reporte final | Bloquea pasos posteriores hasta resolver |
+| Asíncrona | Hook `claudemd-bloat-detector.js` (PostToolUse) | Tras cualquier Write/Edit/MultiEdit a CLAUDE.md (incluso fuera de comandos SWL) | No bloquea — emite nudge a `.planning/evolution/nudges.jsonl` |
+
+La capa síncrona es proactiva (detiene el comando antes de reportar
+éxito). La asíncrona es retroactiva (cubre escrituras desde fuera de
+comandos SWL, ej. edición manual).
+
+## Por qué NO se duplica al hook
+
+El hook async existente cubre el caso de escrituras desde **cualquier
+fuente** (edición manual del usuario, otros comandos, scripts externos).
+Es la red de seguridad universal. La validación síncrona en aprender es
+específica para el flujo del comando — donde el agente puede actuar
+sobre el WARN antes de continuar.
+
+NO crear un hook nuevo dedicado a aprender — duplicaría el rol del
+existente. La invocación síncrona en el Paso 6.5 es suficiente.
+
+## Reglas duras
+
+- `/swl:aprender` Paso 6.5 es OBLIGATORIO si se aplicó Tipo A.
+- `/swl:adoptar-proyecto` Paso 8 debe ejecutar el auditor tras
+  generar/modificar CLAUDE.md.
+- `/swl:nuevo-proyecto` Paso 6 debe ejecutar el auditor tras generar
+  CLAUDE.md inicial.
+- `/swl:claudemd init-project` debe ejecutar el auditor sobre el
+  archivo recién generado.
+
+Cualquier comando futuro que escriba a CLAUDE.md DEBE seguir este
+contrato.