# 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.
