@saulwade/swl-ses 1.6.8 → 1.7.0

package/agentes/orquestador-swl.md

@@ -15,7 +15,7 @@ modeloAlterno: claude-haiku-4-5-20251001
 ventanaContexto: 200k
 permissionMode: plan
 color: white
-version: 1.1.0
+version: 1.2.0
 nivelRiesgo: BAJO
 skillsInvocables: [compactacion-contexto, checkpoints-verificacion, aprendizaje-continuo, discutir-fase, ejecutar-fase, planear-fase, nuevo-proyecto, brainstorming, control-profundidad, prevencion-racionalizacion, estructura-proyecto-claude, workflow-claude-code, git-worktrees-paralelo, swl-dashboard, instalar-sistema, mapear-codebase, orquestacion-async, context-builder]
 skillsRestringidos: [fastapi-python, angular-component, angular-forms, postgresql-table-design]
@@ -124,6 +124,42 @@ paralelismo:
 La regla de paralelización del Nivel 3 sigue aplicando, pero ahora el
 orquestador DEBE invocarla explícitamente en el prompt del sub-agente.
 
+### 4. Tamaño máximo del prompt al sub-agente
+
+Los sub-agentes pueden entrar en **autocompact thrashing** cuando reciben
+prompts mayores a ~30k tokens. Síntoma observado (caso real SIGAF
+2026-05-22): tras 4 tool uses sin escribir un solo archivo, el sub-agente
+aborta con "Autocompact is thrashing: the context refilled to the limit
+within 3 turns of the previous compact, 3 times in a row".
+
+Cota dura: **prompt al sub-agente ≤ 30k tokens** (intent + constraints +
+acceptance criteria + file locations + dependencies).
+
+| Tamaño estimado del prompt | Acción |
+|----------------------------|--------|
+| < 10k tokens | Delegar normalmente |
+| 10k–30k tokens | Delegar pero monitorear; si el sub-agente tarda más de 3 turnos sin output, abortar y dividir |
+| > 30k tokens | NO delegar — dividir en sub-tareas <10k tokens cada una, o ejecutar directamente sin delegar |
+
+### Cuándo hacer el trabajo directo en lugar de delegar
+
+Cuando la spec ya está completamente clara para el orquestador, delegar
+solo agrega overhead de contexto sin valor:
+
+- **Scope < 5 archivos** con código boilerplate similar → trabajo directo.
+- **Scope ≥ 5 archivos no relacionados** con lógica específica por
+  archivo → delegar.
+- **Prompt requeriría >30k tokens** de specs/ejemplos → trabajo directo
+  (delegar es contraproducente).
+
+Regla práctica: si te encuentras escribiendo specs por más de 5 minutos
+para preparar la delegación, es señal de que el trabajo directo es más
+eficiente que la delegación.
+
+Origen del patrón: documentado en skill global `harness-claude-code`
+gotcha "Sub-agente entra en autocompact thrashing con prompts >30k tokens"
+(SIGAF 2026-05-22).
+
 ## Routing por fase + dominio (lookup tabular determinístico)
 
 Antes de delegar, **clasifica la petición** por dos ejes mecánicos en lugar de

package/comandos/swl/adoptar-proyecto.md

@@ -2,6 +2,11 @@
 name: swl:adoptar-proyecto
 description: Incorpora un proyecto existente al sistema SWL. Analiza automáticamente el codebase (stack, arquitectura, dependencias, estado git) y combina los hallazgos con una entrevista corta al usuario para generar los 9 archivos de .planning/ con información real del proyecto — no plantillas vacías.
 allowed_tools: ["Read", "Write", "Edit", "Bash", "Glob", "Grep", "Agent"]
+evolved: true
+evolved-from: "1.6.8"
+evolved-at: "2026-05-22"
+evolved-by: "aprender"
+evolved-note: "Paso 8 — validación síncrona del auditor tras modificar CLAUDE.md (contrato cruzado con /swl:claudemd)"
 ---
 
 # /swl:adoptar-proyecto — Incorporar un proyecto existente al sistema SWL
@@ -187,6 +192,29 @@ Verificar el estado de `CLAUDE.md` en la raíz del proyecto:
 Esta referencia carga la matriz operacional del sistema SWL al inicio de cada
 sesión y es el contrato base de uso del sistema para el proyecto adoptado.
 
+### Validación síncrona post-modificación (contrato cruzado con /swl:claudemd)
+
+Tras generar o modificar `CLAUDE.md` en este paso, ejecutar el auditor
+síncrono para verificar que respeta el contrato canónico:
+
+```bash
+node scripts/auditar-claudemd.js --json
+# Fallback si el script no está en el proyecto destino:
+npx -y @saulwade/swl-ses@latest audit-claudemd --json
+```
+
+Evaluar `veredicto`:
+
+- `OK` → continuar al Paso 9.
+- `WARN tamano-total` → el CLAUDE.md preexistente más la modificación
+  excedió el umbral. Reportar al usuario y proponer extracción a
+  `@docs/lessons-<tema>.md` antes de cerrar.
+- `WARN bullet-gigante` → revisar y condensar el bullet detectado.
+- `WARN` otras reglas → reportar al usuario pero permitir continuar.
+- `ERROR placeholders` → **DETENER**, revertir la modificación y reportar.
+
+Detalle del contrato cruzado en `@docs/contrato-aprender-claudemd.md`.
+
 ## Paso 9 — Reporte final
 
 ```

package/comandos/swl/aprender.md

@@ -3,10 +3,10 @@ name: swl:aprender
 description: Extrae aprendizajes de la sesión de trabajo actual. Analiza patrones de errores, decisiones y soluciones para generar nuevas reglas y habilidades que mejoran el sistema. Actualiza CLAUDE.md del proyecto y propone nuevas habilidades al sistema SWL.
 allowed_tools: ["Read", "Write", "Edit", "Bash", "Glob", "Grep"]
 evolved: true
-evolved-from: "5.12.3"
-evolved-at: "2026-04-25"
+evolved-from: "1.6.9"
+evolved-at: "2026-05-22"
 evolved-by: "aprender"
-evolved-note: "Paso 2 — filtro crítico obligatorio sobre reportes de sub-agentes Explore para evitar sobre-ingeniería al analizar papers académicos"
+evolved-note: "Paso 6.5 § Protocolo 4.5 — detección de duplicación de reglas globales tras Tipo A (regla sin-duplicacion-reglas-globales.md, v1.7.0)"
 ---
 
 # /swl:aprender — Extracción de aprendizajes y mejora del sistema
@@ -392,6 +392,145 @@ Resultado: 0/2 OK, 2 con fallos
 
 Si el verificador reporta fallo, corregir el archivo puntual (agregar bump o ejecutar `markAsEvolved()`), NO saltarse la verificación. El gap que esta verificación cierra es exactamente el que el usuario detectó al auditar la sesión de aprender del 2026-04-20: `markAsEvolved` ejecutado sin bump de `version` → cambio invisible al resto del sistema pese a que el archivo quedó protegido contra reinstalación.
 
+## Paso 6.5 — Validación de CLAUDE.md tras aplicar Tipo A (auditor síncrono)
+
+> Este paso es **OBLIGATORIO** si en Paso 6 se aplicó al menos un aprendizaje
+> Tipo A (regla agregada a `CLAUDE.md` del proyecto). El hook
+> `claudemd-bloat-detector.js` ya emite nudge async cuando se modifica
+> `CLAUDE.md`, pero el nudge llega DESPUÉS del Paso 7 — y el comando
+> habría seguido sin saber que el contrato canónico se rompió.
+>
+> Este Paso 6.5 invoca el auditor SÍNCRONAMENTE, antes de pasar a Paso 7.
+
+### Por qué existe este paso
+
+`/swl:aprender` y `/swl:claudemd` operan sobre el mismo archivo desde
+ángulos distintos: aprender **muta**, claudemd **prescribe contrato**. Sin
+validación cruzada, una sesión de aprender puede agregar 25 líneas inline
+a un CLAUDE.md que estaba en 195 LOC → resultado 220 LOC, WARN líneas,
+contrato roto silenciosamente.
+
+Origen del gap: detectado en 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).
+
+### Procedimiento
+
+Solo si en Paso 6 se aplicó al menos un Tipo A:
+
+1. **Ejecutar el auditor síncrono**:
+
+   ```bash
+   node scripts/auditar-claudemd.js --json
+   ```
+
+   Si el script no está disponible en el proyecto destino (instalación
+   global vía npm), invocar:
+
+   ```bash
+   npx -y @saulwade/swl-ses@latest audit-claudemd --json
+   ```
+
+2. **Leer el JSON de respuesta** y evaluar `veredicto`:
+
+   | Veredicto | Acción |
+   |-----------|--------|
+   | `OK` | Continuar a Paso 7. El Tipo A se aplicó respetando el contrato. |
+   | `WARN` con regla `tamano-total` (líneas > umbral) | Aplicar protocolo de extracción (sub-paso 3) |
+   | `WARN` con regla `bullet-gigante` | Aplicar protocolo de condensación (sub-paso 4) |
+   | `WARN` con regla `duplicacion-reglas-globales` | **DETENER y reformular** — el Tipo A duplica regla global. Aplicar protocolo de duplicación (sub-paso 4.5) |
+   | `WARN` con otra regla (secciones, @references, karpathy) | Reportar al usuario pero permitir continuar |
+   | `ERROR` con regla `placeholders` | **DETENER** — revertir Tipo A y reportar al usuario |
+
+3. **Protocolo de extracción** (WARN líneas excedidas):
+
+   ```
+   El Tipo A aplicado dejó CLAUDE.md en [N] líneas (umbral: 200).
+
+   Opciones:
+   [A] Condensar la regla agregada a ≤3 líneas y re-escribir en CLAUDE.md
+   [B] Extraer el cuerpo a @docs/lessons-<tema-kebab>.md y dejar 1 línea
+       en CLAUDE.md: "- **<título>**: [resumen 1 línea]. Detalle en
+       @docs/lessons-<tema>.md"
+   [C] Aceptar el WARN y continuar (ajustar SWL_CLAUDEMD_MAX_LINES en
+       caso de que el límite real del proyecto sea mayor)
+
+   ¿Qué prefieres?
+   ```
+
+   Por defecto, recomendar **[B] Extraer** cuando el aprendizaje requiere
+   más de 5 líneas o incluye ejemplos de código. Recomendar **[A] Condensar**
+   cuando el aprendizaje cabe en 1-3 líneas sin perder accionabilidad.
+
+4. **Protocolo de condensación** (WARN bullet-gigante):
+
+   Un bullet/párrafo >1000 chars es ilegible. Convertir a tabla, lista
+   jerárquica o extraer a `@docs/`. NO dejar el bullet gigante aunque el
+   usuario lo apruebe — viola el contrato canónico de CLAUDE.md.
+
+4.5. **Protocolo de duplicación de reglas globales** (WARN `duplicacion-reglas-globales`):
+
+   Esto significa que el Tipo A aplicado **parafrasea una regla que ya
+   vive en `~/.claude/rules/`** y se carga globalmente. Duplicarla
+   inline en CLAUDE.md de proyecto viola la regla
+   `reglas/sin-duplicacion-reglas-globales.md`.
+
+   El auditor reporta cuál regla global se duplica y la línea
+   aproximada. Ejemplo de hallazgo:
+
+   ```
+   [WARN] Bloque duplica regla global `~/.claude/rules/brevedad-output.md`
+          (línea ~14)
+   ```
+
+   Acción obligatoria:
+
+   ```
+   El Tipo A que se acaba de agregar parafrasea la regla global
+   `~/.claude/rules/<archivo>.md` § <sección> (línea ~N).
+
+   Opciones:
+   [A] Eliminar el bloque local — la regla global YA aplica
+       automáticamente en cada sesión SWL.
+   [B] Reescribir el bloque como matiz local (≤3 líneas) que
+       nombra explícitamente la regla global:
+       "Convenciones locales del proyecto: <matiz>.
+        Ver @~/.claude/rules/<archivo>.md."
+   [C] Documentar override explícito con justificación:
+       "Override de ~/.claude/rules/<archivo>.md por <razón>."
+
+   ¿Qué prefieres?
+   ```
+
+   Por defecto, **recomendar [A] Eliminar** salvo que el bloque agregue
+   matiz local genuino del proyecto. NUNCA aceptar el WARN sin
+   resolución — eso convierte el comando en cómplice de la duplicación
+   que la regla prohíbe.
+
+5. **Re-ejecutar el auditor** tras la corrección hasta veredicto OK o
+   WARN consultivo aceptable (con confirmación explícita del usuario para
+   los WARN no resueltos).
+
+### Reglas duras
+
+- NUNCA pasar al Paso 7 con veredicto `ERROR placeholders`. Revertir el Tipo
+  A primero.
+- NUNCA aceptar `WARN tamano-total` o `WARN bullet-gigante` sin proponer al
+  menos una de las opciones [A]/[B]. El usuario debe decidir conscientemente
+  si vivir con el WARN.
+- Si el aprendizaje Tipo A genera 2+ secciones nuevas, evaluar si el
+  contenido pertenece a un archivo `@docs/lessons-<tema>.md` desde el inicio
+  en lugar de inline.
+
+### Anti-patrón explícito
+
+❌ Aplicar Tipo A inline sin Paso 6.5 → CLAUDE.md crece descontroladamente →
+contrato canónico violado silenciosamente → próxima ejecución de
+`/swl:claudemd audit` reporta WARN, pero el daño ya está en el commit.
+
+✅ Aplicar Tipo A → ejecutar auditor sync en Paso 6.5 → si hay drift,
+condensar o extraer → CLAUDE.md permanece dentro del contrato.
+
 ## Paso 7 — APRENDIZAJES.md y reporte
 
 Crea o actualiza `.planning/APRENDIZAJES.md` con registro de la sesión: título, categoría, contexto, aprendizaje, acción tomada, métricas.

package/comandos/swl/claudemd.md

@@ -2,6 +2,11 @@
 name: swl:claudemd
 description: Audita, refactoriza, valida o inicializa archivos CLAUDE.md según best practices Anthropic (ADR-0016). Subcomandos audit (analiza calidad), refactor (sugiere extracciones), check (verifica secciones canónicas), init-user (crea ~/.claude/CLAUDE.md template), init-project (genera CLAUDE.md raíz del proyecto).
 allowed_tools: ["Read", "Write", "Edit", "Bash", "Glob", "Grep"]
+evolved: true
+evolved-from: "1.6.9"
+evolved-at: "2026-05-22"
+evolved-by: "aprender"
+evolved-note: "Audit dimensión 7 — duplicación de reglas globales (cataloga 6 reglas de ~/.claude/rules/ que NO deben duplicarse inline). Refactor propone reemplazo canónico. Aplica regla nueva sin-duplicacion-reglas-globales.md."
 ---
 
 # /swl:claudemd — Tratamiento profesional de CLAUDE.md
@@ -149,6 +154,20 @@ existente NO incluye `@reglas/usar-sistema-swl.md` o NO menciona los cuatro
 principios Karpathy (o `prevencion-sobreingenieria`), emitir hallazgo WARN
 recomendando agregarlo manualmente.
 
+### Validación síncrona post-generación
+
+Tras `init-project` generar el archivo nuevo, ejecutar inmediatamente
+`audit` sobre el resultado:
+
+```bash
+node scripts/auditar-claudemd.js --json
+```
+
+Veredicto esperado: `OK` (el template debe respetar el contrato por
+construcción). Cualquier WARN/ERROR es bug del template — reportar al
+usuario y abrir issue para corrección. Este check es parte del contrato
+cruzado con `/swl:aprender` documentado en `@docs/contrato-aprender-claudemd.md`.
+
 ### audit — checks específicos sobre Karpathy
 
 El subcomando `audit` verifica además de las dimensiones estándar:
@@ -162,6 +181,45 @@ recomendando agregar la sub-sección compacta (4 líneas) como guía de
 implementación. NO emite WARN para CLAUDE.md mínimos (<50 LOC) ni para
 archivos `~/.claude/CLAUDE.md` user-level (esos siguen otro contrato).
 
+### audit — checks específicos sobre duplicación de reglas globales
+
+El subcomando `audit` también detecta (dimensión 7) si CLAUDE.md duplica
+reglas que ya viven en `~/.claude/rules/` y se cargan globalmente.
+Consume el catálogo declarativo
+`scripts/lib/reglas-globales-conocidas.json` que cataloga 6 reglas
+conocidas:
+
+- `brevedad-output.md` § Idioma obligatorio: español de México
+- `brevedad-output.md` § Brevedad y eficiencia de output
+- `git-coauthor.md` § Sin co-autores en commits
+- `arreglar-al-detectar.md` § Detectar → Informar → Arreglar
+- `debatir-antes-de-aceptar.md`
+- `usar-context7.md`
+
+Si detecta duplicación: emite hallazgo `duplicacion-reglas-globales`
+severidad WARN con línea aproximada y remediación específica. NO bloquea
+el comando — sirve como nudge para limpiar el CLAUDE.md.
+
+NO aplica a `~/.claude/CLAUDE.md` user-level (ahí sí pueden declararse
+preferencias personales que parafrasean reglas globales).
+
+Aplica regla `reglas/sin-duplicacion-reglas-globales.md`.
+
+### refactor — propuestas para duplicaciones de reglas globales
+
+Cuando `audit` detecta duplicaciones, el subcomando `refactor` propone
+el reemplazo concreto usando `construirSugerenciaRefactor()` del
+detector. Cada propuesta incluye:
+
+- **Bloque a eliminar** (línea aproximada en CLAUDE.md)
+- **Regla global afectada** (archivo + sección canónica)
+- **Reemplazo sugerido** (3 opciones):
+  1. Eliminar el bloque — la regla global YA aplica automáticamente
+  2. Reescribir como matiz local en ≤3 líneas referenciando la regla
+  3. Documentar override explícito con justificación
+
+El refactor SOLO imprime el diff propuesto. El usuario decide aplicar.
+
 ## Variables de entorno
 
 Ver `@docs/variables-entorno.md` sección "Calidad de CLAUDE.md":

package/comandos/swl/ejecutar-fase.md

@@ -2,6 +2,11 @@
 name: swl:ejecutar-fase
 description: Recibe el número de una fase y la implementa siguiendo el PLAN.md. Delega al agente implementador-swl, hace commits atómicos por slice, produce RESUMEN.md y actualiza ESTADO.md y HOJA-RUTA.md al terminar.
 allowed_tools: ["Read", "Write", "Edit", "Bash", "Glob", "Grep"]
+evolved: true
+evolved-from: "1.6.8"
+evolved-at: "2026-05-22"
+evolved-by: "aprender"
+evolved-note: "Paso 4.2 — cota dura 30k tokens al prompt del sub-agente para prevenir autocompact thrashing (origen SIGAF 2026-05-22)"
 ---
 
 # /swl:ejecutar-fase <n> [--iterative] — Ejecutar implementación de una fase
@@ -109,6 +114,15 @@ Anuncia inicio del slice (nombre, tipo AFK/HITL, número de tareas). Si es HITL
 ### 4.2 — Delegación al implementador-swl
 Delega con instrucción precisa: contexto a leer (PROYECTO.md, PLAN.md, CONTEXTO.md, CLAUDE.md), tareas del slice, criterio de verificación. El skill define las reglas de commit atómico y formato.
 
+**Cota dura del prompt al sub-agente**: ≤30k tokens (intent + constraints + acceptance criteria + file locations). Por encima de esa cifra el sub-agente puede entrar en autocompact thrashing y abortar sin escribir archivos (caso real SIGAF 2026-05-22). Si el prompt necesario excede 30k tokens:
+
+- Dividir el slice en sub-slices más pequeños (<10k tokens de spec cada uno).
+- O ejecutar directamente sin delegar si la spec está clara para ti (scope <5 archivos boilerplate similar).
+
+Indicador para optar por trabajo directo: si pasas más de 5 minutos escribiendo specs para preparar la delegación, el costo de delegar supera el ahorro.
+
+Detalle del patrón anti-thrashing en `agentes/orquestador-swl.md` sección "4. Tamaño máximo del prompt al sub-agente".
+
 ### 4.3 — Verificación del slice
 Ejecuta comandos de verificación del PLAN.md, verifica archivos, revisa commits (`git log --oneline -5`), corre tests. Si falla: máximo 2 reintentos antes de escalar al usuario.
 

package/comandos/swl/nuevo-proyecto.md

@@ -2,6 +2,11 @@
 name: swl:nuevo-proyecto
 description: Inicializa un proyecto nuevo desde cero. Hace preguntas al usuario, investiga el stack tecnológico y produce la estructura de planeación completa en .planning/.
 allowed_tools: ["Read", "Write", "Edit", "Bash", "Glob", "Grep"]
+evolved: true
+evolved-from: "1.6.8"
+evolved-at: "2026-05-22"
+evolved-by: "aprender"
+evolved-note: "Paso 6 — validación síncrona del auditor tras generar CLAUDE.md inicial (contrato cruzado con /swl:claudemd)"
 ---
 
 # /swl:nuevo-proyecto — Inicializar proyecto nuevo
@@ -156,6 +161,30 @@ Si ya existe `CLAUDE.md` (verificado en Paso 1), revisar que incluya
 `@reglas/usar-sistema-swl.md` en la sección de reglas obligatorias. Si NO
 lo incluye, agregarlo en este paso preservando el resto del contenido.
 
+### Validación síncrona post-generación (contrato cruzado con /swl:claudemd)
+
+Tras generar el `CLAUDE.md` inicial, ejecutar el auditor síncrono para
+verificar el contrato canónico desde el primer commit:
+
+```bash
+node scripts/auditar-claudemd.js --json
+# Fallback:
+npx -y @saulwade/swl-ses@latest audit-claudemd --json
+```
+
+Veredicto esperado en proyecto nuevo: `OK` (el template generado debe
+respetar el contrato por construcción). Si reporta WARN o ERROR:
+
+- `WARN secciones-canonicas` ausentes → bug del template, abrir issue.
+- `ERROR placeholders` → bug del template, reemplazar `[ej.]` con
+  ejemplos reales o HTML comments.
+
+Cualquier otro WARN/ERROR es señal de que el template necesita ajuste —
+reportar al usuario y considerar invocar `/swl:claudemd refactor` antes
+de continuar.
+
+Detalle del contrato cruzado en `@docs/contrato-aprender-claudemd.md`.
+
 ## Paso 7 — Reporte al usuario
 
 Al terminar, reporta:

package/habilidades/swl-claudemd/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: swl-claudemd
 description: Conocimiento operacional para auditar y mantener archivos CLAUDE.md — contrato canónico de secciones (best practices Anthropic, ADR-0016), umbrales de bloat (líneas totales, bullets gigantes, placeholders, @references rotas), reglas de extracción a archivos referenciados con @, y plantillas de inicialización (init-user para ~/.claude/CLAUDE.md, init-project para CLAUDE.md raíz detectando stack). Provee las reglas; el comando /swl:claudemd ejecuta el flujo. Cargar desde ese comando o cuando el hook claudemd-bloat-detector sugiera intervención.
-version: "1.0.2"
+version: "1.2.0"
 herramientasPermitidas: [Read, Write, Edit, Bash, Glob, Grep]
 exclusiones:
   - "No cargar para editar reglas globales en ~/.claude/rules/ — usar Edit directo."
@@ -9,6 +9,11 @@ exclusiones:
   - "No cargar para validar otros archivos (.md de docs, READMEs) — solo CLAUDE.md tiene contrato canónico."
   - "No cargar para generar el bloque del installer en CLAUDE.md de proyectos destino — eso lo hace scripts/lib/transformadores/claude.js."
 evolvable: true
+evolved: true
+evolved-from: "1.1.0"
+evolved-at: "2026-05-22"
+evolved-by: "aprender"
+evolved-note: "Dimensión 8 — detección de duplicación de reglas globales (catálogo declarativo en scripts/lib/reglas-globales-conocidas.json). Refactor propone reemplazo canónico. Hook claudemd-duplicacion-detector.js complementa la capa async. Aplica regla nueva reglas/sin-duplicacion-reglas-globales.md (v1.7.0)."
 ---
 
 # Habilidad: Tratamiento profesional de CLAUDE.md
@@ -58,7 +63,7 @@ node scripts/auditar-claudemd.js --json    # para parsing
 node scripts/auditar-claudemd.js --strict  # exit 1 si WARN
 ```
 
-El auditor verifica siete dimensiones:
+El auditor verifica ocho dimensiones:
 
 | Dimensión | Regla | Severidad |
 |---|---|---|
@@ -69,6 +74,7 @@ El auditor verifica siete dimensiones:
 | @references | Archivos >80 líneas usan al menos un `@docs/...md` | WARN |
 | Placeholders | `[TBD]`, `[TODO]`, `[COMPLETAR]` | ERROR |
 | Karpathy reference | Project-level >50 LOC menciona "Karpathy", los 4 principios, o `prevencion-sobreingenieria` | WARN |
+| Duplicación reglas globales | Bloque inline parafrasea regla de `~/.claude/rules/` ya cargada globalmente (catálogo en `scripts/lib/reglas-globales-conocidas.json`) | WARN |
 
 Veredicto final: ERROR → WARN → OK (el más severo gana).
 
@@ -219,6 +225,182 @@ Esta dimensión es WARN, no ERROR — guía sin imponer. CLAUDE.md user-level
 
 ---
 
+## Interacción con /swl:aprender (contrato cruzado)
+
+`/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/evolucion/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.
+
+---
+
+---
+
+## Detección de duplicación de reglas globales (dimensión 8)
+
+### Por qué existe
+
+Las reglas en `~/.claude/rules/` se cargan automáticamente en cada
+sesión SWL. Si un proyecto duplica inline el contenido de esas reglas
+en su `CLAUDE.md`, ocurren tres patologías:
+
+1. **Bloat acumulativo**: 7-15 líneas por regla duplicada × N proyectos
+   = inflación silenciosa que rompe el umbral de 200 LOC.
+2. **Drift al actualizar la global**: si la regla global cambia, las
+   copias en cada CLAUDE.md quedan obsoletas sin alerta.
+3. **Erosión del contrato canónico**: cada CLAUDE.md re-deriva el
+   principio con palabras propias, generando 4 paráfrasis distintas
+   del mismo contenido.
+
+La regla `reglas/sin-duplicacion-reglas-globales.md` (v1.7.0) prohíbe
+esta duplicación. Esta dimensión del auditor la detecta.
+
+### Catálogo declarativo
+
+`scripts/lib/reglas-globales-conocidas.json` lista las reglas globales
+conocidas con sus patrones de detección. Estructura por entrada:
+
+```json
+{
+  "id": "idioma-espanol-mexico",
+  "regla_global": "brevedad-output.md",
+  "seccion_canonica": "Idioma obligatorio: español de México",
+  "referencia_canonica": "@~/.claude/rules/brevedad-output.md § Idioma obligatorio",
+  "patrones": ["\\bespañol\\s+de\\s+M[ée]xico\\b", "..."],
+  "min_matches": 2,
+  "remediacion_sugerida": "Eliminar el bloque local..."
+}
+```
+
+Reglas incluidas en v1.7.0:
+
+- `idioma-espanol-mexico` (brevedad-output.md § Idioma)
+- `brevedad-sin-aiisms` (brevedad-output.md § Brevedad)
+- `git-sin-coautores` (git-coauthor.md)
+- `arreglar-al-detectar` (arreglar-al-detectar.md)
+- `debatir-antes-de-aceptar` (debatir-antes-de-aceptar.md)
+- `usar-context7` (usar-context7.md)
+
+### Cuándo NO se evalúa
+
+- **User-level** (`~/.claude/CLAUDE.md`): ahí sí pueden declararse
+  preferencias personales que parafrasean reglas globales. La opción
+  `esUserLevel: true` skipea la evaluación.
+- **Archivos < 20 LOC**: CLAUDE.md mínimos no acumulan duplicaciones
+  con suficiente densidad para evaluar.
+
+### Capa async — hook
+
+`hooks/claudemd-duplicacion-detector.js` (PostToolUse, no bloquea)
+ejecuta el detector tras cualquier Write/Edit a CLAUDE.md y emite
+nudge a `.planning/evolucion/nudges.jsonl` con `kind:
+claudemd-duplicacion-reglas`. Opt-out: `SWL_CLAUDEMD_DUPLICACION=0`.
+
+### Cómo refactorizar duplicaciones detectadas
+
+Tres opciones para cada hallazgo:
+
+1. **Eliminar** (default recomendado): el bloque solo repite la regla
+   global, eliminarlo no pierde información.
+2. **Convertir a matiz local** (≤3 líneas): si el bloque agrega valor
+   local genuino, reescribirlo corto referenciando la regla global:
+   ```markdown
+   Convenciones locales: identificadores técnicos en inglés (rutas,
+   comandos). Ver @~/.claude/rules/brevedad-output.md.
+   ```
+3. **Documentar override explícito** (raro): si el proyecto contradice
+   la regla global por requerimiento documentable:
+   ```markdown
+   Override de @~/.claude/rules/brevedad-output.md § Brevedad: este
+   proyecto exige docstrings extendidos por compliance regulatorio.
+   ```
+
+### Anti-patrón: "lo dejo por claridad"
+
+La regla global YA es visible — se carga automáticamente. Duplicarla
+no aumenta su prioridad ni su claridad; solo crea deuda. Si el WARN
+del auditor incomoda, la respuesta correcta es **resolver la
+duplicación**, no aceptar el WARN.
+
+---
+
 ## Gotchas / Errores comunes no obvios
 
 - **Marcar tablas como bullets gigantes**: el detector debe excluir