@saulwade/swl-ses 1.6.7 → 1.7.0

package/reglas/sin-duplicacion-reglas-globales.md

@@ -0,0 +1,182 @@
+# Regla: Sin duplicación de reglas globales en CLAUDE.md de proyecto
+
+Esta regla es **OBLIGATORIA** y aplica al diseño/auditoría de cualquier
+`CLAUDE.md` de proyecto donde el sistema SWL esté instalado. Extiende el
+contrato canónico de `swl-claudemd` con un sub-caso específico: la
+duplicación inline de reglas que ya viven en `~/.claude/rules/`.
+
+---
+
+## Principio
+
+> Cuando una regla ya está documentada en `~/.claude/rules/` (carga global
+> automática en todas las sesiones del usuario), **el `CLAUDE.md` del
+> proyecto NO debe duplicarla inline**. La duplicación viola DRY a nivel
+> de gobernanza, genera drift cuando la regla global se actualiza, y
+> erosiona el contrato canónico de `CLAUDE.md` (≤200 LOC).
+
+La regla global es **la fuente de verdad**. El `CLAUDE.md` del proyecto
+puede referenciarla con `@~/.claude/rules/<archivo>.md` o agregar
+**matices propios del proyecto**, pero NUNCA re-derivar el principio.
+
+---
+
+## Cuándo aplicar
+
+OBLIGATORIO al:
+
+- Crear un `CLAUDE.md` de proyecto nuevo (`/swl:claudemd init-project`,
+  `/swl:nuevo-proyecto`, `/swl:adoptar-proyecto`).
+- Modificar `CLAUDE.md` de proyecto inline (`/swl:aprender` Paso 6 Tipo A,
+  edición manual del usuario, `Edit`/`Write` programático).
+- Revisar `CLAUDE.md` (`/swl:claudemd audit`, `/swl:claudemd refactor`,
+  hook `claudemd-bloat-detector`, hook `claudemd-duplicacion-detector`).
+
+NO aplica al:
+
+- `~/.claude/CLAUDE.md` (user-level) — ahí SÍ pueden declararse
+  preferencias personales que parafrasean o complementan reglas globales.
+- Documentación dentro del proyecto que no es `CLAUDE.md` (READMEs,
+  ADRs, docs de feature) — ahí no aplica el contrato canónico.
+
+---
+
+## Catálogo de reglas globales conocidas
+
+Las siguientes reglas globales se cargan automáticamente cada sesión y
+NO deben duplicarse en `CLAUDE.md` de proyecto:
+
+| Regla global | Sección canónica | Referencia para citar |
+|---|---|---|
+| `brevedad-output.md` | Idioma obligatorio: español de México | `@~/.claude/rules/brevedad-output.md § Idioma obligatorio` |
+| `brevedad-output.md` | Brevedad y eficiencia de output | `@~/.claude/rules/brevedad-output.md § Brevedad` |
+| `git-coauthor.md` | Sin co-autores en commits | `@~/.claude/rules/git-coauthor.md` |
+| `arreglar-al-detectar.md` | Detectar → Informar → Arreglar | `@~/.claude/rules/arreglar-al-detectar.md` |
+| `debatir-antes-de-aceptar.md` | Debatir decisiones que chocan con reglas | `@~/.claude/rules/debatir-antes-de-aceptar.md` |
+| `usar-context7.md` | Consultar Context7 antes de dependencias | `@~/.claude/rules/usar-context7.md` |
+
+Catálogo declarativo completo:
+`scripts/lib/reglas-globales-conocidas.json`. El catálogo es la fuente
+de verdad consumida por el auditor (`scripts/auditar-claudemd.js`) y el
+hook (`hooks/claudemd-duplicacion-detector.js`).
+
+---
+
+## Qué SÍ es legítimo en CLAUDE.md de proyecto
+
+Lo siguiente NO se considera duplicación y es bienvenido:
+
+1. **Matiz local específico**: "Convenciones locales: identificadores
+   técnicos en inglés (rutas, comandos), prosa en español." — el matiz
+   es del proyecto, no la regla del idioma.
+2. **Override explícito documentado**: "Override de
+   `~/.claude/rules/brevedad-output.md` § Brevedad: este proyecto usa
+   docstrings extendidos por requerimiento legal." — el override es
+   explícito y nombra la regla global.
+3. **Excepción acotada con justificación**: "Excepción a
+   `~/.claude/rules/arreglar-al-detectar.md`: bugs cosméticos en el
+   módulo legacy `X/` se difieren a Q3 por congelación." — la excepción
+   nombra la regla y justifica.
+4. **Referencia `@`**: `@~/.claude/rules/<archivo>.md` — incluir la
+   regla por referencia, no inline.
+
+---
+
+## Cómo detectarlo
+
+### Manual
+
+```bash
+node scripts/auditar-claudemd.js
+# Buscar en el output: "duplicacion-reglas-globales"
+```
+
+### Automático
+
+- **Auditor síncrono**: `scripts/auditar-claudemd.js` (dimensión 7,
+  severidad WARN, no bloquea).
+- **Hook async**: `hooks/claudemd-duplicacion-detector.js` (PostToolUse,
+  emite nudge a `.planning/evolucion/nudges.jsonl`).
+- **Comando**: `/swl:claudemd audit` reporta el conteo; `/swl:claudemd
+  refactor` propone el reemplazo concreto.
+
+---
+
+## Cómo remediar
+
+1. **Identificar el bloque** señalado por el auditor (línea aproximada).
+2. **Decidir**:
+   - ¿El bloque es 100% paráfrasis de la regla global? → **eliminar**.
+   - ¿El bloque agrega matiz local? → **reescribir como matiz corto**
+     (≤3 líneas) que nombra la regla global ("Convenciones locales:
+     <matiz>. Ver `@~/.claude/rules/<archivo>.md`.").
+3. **Verificar**: re-ejecutar `node scripts/auditar-claudemd.js` hasta
+   que la duplicación desaparezca.
+
+---
+
+## Anti-patrones
+
+- **Copiar contenido de reglas globales "para que esté visible"**: la
+  regla global YA está visible — se carga automáticamente. Copiarla en
+  cada proyecto es deuda silenciosa.
+- **Re-derivar el principio con palabras propias**: si dices "todo
+  contenido generado debe ser en español de México con acentos
+  correctos…" estás re-derivando `brevedad-output.md § Idioma`.
+- **Bloque "Reglas de máxima prioridad" que repite reglas globales**:
+  las reglas globales SON prioritarias por construcción — duplicarlas
+  no aumenta su prioridad.
+- **Idioma "Language" en inglés que dice "español"**: paradójico y
+  duplica la regla.
+- **Override implícito sin nombrar la regla global**: "este proyecto
+  usa docstrings extendidos" sin decir que es override de qué.
+- **Ignorar el WARN del auditor argumentando "es para claridad"**: el
+  auditor lleva razón. La regla global es suficiente claridad.
+
+---
+
+## Relación con otras reglas
+
+- `~/.claude/rules/memoria-consolidada.md § Reglas de no-duplicación`:
+  principio general "un dato vive en exactamente un canal". Esta regla
+  lo aplica al canal CLAUDE.md.
+- `~/.claude/rules/fragmentos-compartidos.md`: la analogía a nivel de
+  agentes (fragmentos `_*.md` se incrustan, no se duplican).
+- `~/.claude/rules/skills-estandar.md`: la analogía a nivel de skills
+  (skill referencia otro skill, no duplica su contenido).
+- `reglas/auditorias-documentales-estructurales.md § Para prosa
+  cuantificada en campos descriptivos`: hermana — verifica drift
+  cross-manifest. Esta regla verifica drift cross-fuente.
+
+---
+
+## Origen de esta regla
+
+Sesión 2026-05-22, swl-ses v1.7.0. El usuario pegó 4 fragmentos de
+`CLAUDE.md` de distintos proyectos que repetían la misma regla de idioma
+"español de México" en formas distintas (lista con bullets, H3 inline,
+lista numerada, sección "Language" en inglés). El análisis reveló:
+
+- La regla ya vivía en `~/.claude/rules/brevedad-output.md § Idioma
+  obligatorio: español de México` desde sesiones previas.
+- Cada proyecto la había re-derivado por iteraciones de
+  `/swl:aprender` Tipo A sin que ningún check detectara la
+  duplicación.
+- El bloat acumulado en cada `CLAUDE.md` consumía 7-15 líneas que
+  podían eliminarse sin perder semántica.
+
+Resolución: crear el catálogo declarativo + detector + dimensión 7 del
+auditor + hook PostToolUse + esta regla. Release v1.7.0 MINOR.
+
+---
+
+## Checklist al modificar CLAUDE.md de proyecto
+
+- [ ] ¿El bloque que voy a agregar parafrasea una regla global de
+      `~/.claude/rules/`?
+- [ ] Si sí: ¿agrega matiz local genuino, o solo repite el principio?
+- [ ] Si solo repite: NO agregar — la regla global ya aplica.
+- [ ] Si agrega matiz: redactar en ≤3 líneas que **nombran la regla
+      global** (referencia con `@~/.claude/rules/<archivo>.md`).
+- [ ] Tras escribir: ejecutar `node scripts/auditar-claudemd.js` y
+      confirmar 0 hallazgos `duplicacion-reglas-globales`.

package/reglas/verificar-citas-temporales.md

@@ -0,0 +1,139 @@
+# Regla: Comentarios temporales en código NO son verificación
+
+Esta regla es OBLIGATORIA para todo trabajo de Claude en swl-ses. Extiende la
+regla global `~/.claude/rules/verificar-citas-normativas.md § Familia 2` con
+el sub-caso específico de **comentarios temporales como `// Alineado con
+commits X+Y` o `// Refactorizado a vN.M.0`**.
+
+---
+
+## Principio
+
+> Un comentario en código que afirma alineación con otro commit, versión o
+> contrato (`// Alineado con commits X+Y`, `// Refactorizado a vN.M.0`,
+> `# Sincronizado con backend`, `<!-- Coherente con schema X -->`) **NO es
+> verificación** — es afirmación temporal sin prueba. Antes de actuar
+> sobre el comentario como si fuera evidencia, verificar contra la fuente
+> real con `grep` / `Read` / `git log`.
+
+El comentario puede haberse desactualizado silenciosamente si el commit
+referenciado se revirtió, nunca se aplicó, o si el refactor citado cambió
+después de escribir el comentario.
+
+---
+
+## Cuándo aplicar
+
+OBLIGATORIO verificar antes de aceptar como evidencia accionable:
+
+- Comentarios `// Alineado con commits <SHA>+<SHA>` en código
+- Comentarios `// Refactorizado a v<N.M.0>` o `// Migrado a <framework>`
+- Comentarios `# Sincronizado con backend` o `# Espejo del schema X`
+- Comentarios `<!-- Tipos coherentes con API vN -->`
+- Cualquier afirmación de cross-stack alignment en comentario inline
+
+NO aplica cuando:
+
+- El comentario describe la INTENCIÓN del código (no afirma alineación)
+- El comentario es una nota pendiente (`T‍ODO` / `FIXME`) con ticket asociado
+- El comentario es una explicación del POR QUÉ (no del QUÉ histórico)
+
+---
+
+## Cómo verificar
+
+Cuando un comentario afirma "alineado con X":
+
+1. Identificar **qué se afirma alineado**: archivo, commit, versión, schema.
+2. Localizar la fuente real:
+   ```bash
+   # Si afirma alineación con commit:
+   git show <SHA> -- <archivo-citado>
+
+   # Si afirma alineación con schema/types:
+   grep -rn "<campo-clave>" backend/ frontend/ schemas/
+   ```
+3. Comparar campo por campo. Si hay drift, NO confiar en el comentario.
+4. Actualizar el comentario o eliminarlo (un comentario stale es peor que
+   ningún comentario).
+
+---
+
+## Caso de origen — sesión SIGAF 2026-05-22
+
+`frontend/.../contratos/models/contrato.models.ts` línea 2 decía:
+
+```typescript
+// Alineados con el backend refactorizado (commits 284df74 + 5869ac9)
+```
+
+Pero el backend nunca aplicó ese refactor. El frontend enviaba 5 campos
+(`monto_total`, `fecha_inicio`, `fecha_termino`, `porcentaje_iva`,
+`tipo_contrato_id`) que Pydantic con `extra=ignore` descartaba
+silenciosamente. Los contratos se creaban sin monto ni vigencia durante
+semanas, hasta que se detectó por triangulación cross-stack (modelo
+SQLAlchemy + schema Pydantic + types TypeScript).
+
+El comentario funcionó como **falso anclaje de confianza**: un reviewer
+posterior lo leyó, asumió validez, y no verificó. La causa raíz era el
+comentario stale, no el código.
+
+---
+
+## Anti-patrones específicos
+
+- **Confiar en el comentario en code review**: el reviewer ve
+  `// Alineado con commits X+Y` y asume válido sin hacer `git show`.
+- **Propagar el comentario en refactors**: al copiar código, el comentario
+  viaja con él y eventualmente se vuelve falso sin que nadie lo note.
+- **No actualizar el comentario al revertir el commit citado**: el `git
+  revert` no borra comentarios — el comentario sobrevive afirmando
+  alineación con un commit que ya no existe en la línea de desarrollo.
+- **Usar el comentario como "prueba" en debates técnicos**: "ya está
+  alineado con X" cuando el comentario es la única evidencia es razonar
+  desde una afirmación no verificada.
+
+---
+
+## Alternativas seguras a los comentarios temporales
+
+Cuando se necesita marcar alineación cross-stack:
+
+| En vez de | Usar |
+|-----------|------|
+| `// Alineado con commits X+Y` | Test de contrato que valide el shape real en CI |
+| `// Refactorizado a v2.3.0` | Versión semántica en el archivo + lock |
+| `# Sincronizado con backend` | Tipos generados (OpenAPI codegen, Prisma) |
+| `<!-- Coherente con schema X -->` | Validador automatizado en pre-commit |
+
+Si el comentario es la única opción (no hay test/codegen disponible),
+incluir **fecha y SHA** explícitos para que la revisión periódica detecte
+drift:
+
+```typescript
+// Alineado con backend commit 284df74 al 2026-05-22.
+// Re-verificar si el endpoint POST /contratos cambia su contrato.
+```
+
+---
+
+## Relación con otras reglas
+
+- `~/.claude/rules/verificar-citas-normativas.md § Familia 2` — regla
+  global hermana. Esta regla extiende el principio al sub-caso "comentarios
+  temporales en código".
+- `reglas/arreglar-al-detectar.md` — un comentario stale detectado es
+  trabajo a resolver en mismo turno (actualizarlo o eliminarlo).
+- `~/.claude/rules/usar-sistema-swl.md` — invocar `revisor-codigo-swl`
+  cuando se sospecha drift acumulado de comentarios temporales en un
+  módulo.
+
+---
+
+## Checklist al detectar un comentario temporal
+
+- [ ] ¿El comentario afirma alineación con algo verificable (commit, schema, versión)?
+- [ ] ¿Verifiqué la fuente real con `grep`/`Read`/`git show` ANTES de actuar?
+- [ ] Si hay drift detectado, ¿actualicé/eliminé el comentario en el mismo commit?
+- [ ] Si voy a propagar el código (copy-paste, refactor), ¿el comentario sigue siendo válido?
+- [ ] Si el comentario es la única opción, ¿incluye fecha y SHA explícitos?

package/scripts/auditar-claudemd.js

@@ -13,6 +13,7 @@
  *   - Presencia de secciones canónicas (Stack, Comandos, Code style, Conventions, @references)
  *   - Uso de @references (al menos 1 si el archivo supera 80 líneas)
  *   - Placeholders sin reemplazar ([TBD], [TODO], [COMPLETAR])
+ *   - Referencia Karpathy (CLAUDE.md project-level >50 LOC menciona los 4 principios o el skill)
  *
  * Uso:
  *   node scripts/auditar-claudemd.js [ruta]                # Audita CLAUDE.md (default: ./)
@@ -26,11 +27,24 @@
 
 const fs = require('fs');
 const path = require('path');
+const os = require('os');
+
+// Lazy: el detector vive en scripts/lib/ y puede no estar presente en
+// destinos legacy. Si falta, la auditoría sigue con las 7 dimensiones
+// originales sin la dimensión 8.
+function cargarDetectorReglasDuplicadas() {
+  try {
+    return require('./lib/detector-reglas-duplicadas').detectarDuplicaciones;
+  } catch (_) {
+    return null;
+  }
+}
 
 // ─── Config ───────────────────────────────────────────────────────────────
 const MAX_LINES = parseInt(process.env.SWL_CLAUDEMD_MAX_LINES, 10) || 200;
 const MAX_BULLET_CHARS =
   parseInt(process.env.SWL_CLAUDEMD_MAX_BULLET_CHARS, 10) || 1000;
+const KARPATHY_MIN_LINES = 50;
 
 const SECCIONES_CANONICAS = [
   { nombre: 'Stack', regex: /^##\s+Stack/m },
@@ -39,6 +53,15 @@ const SECCIONES_CANONICAS = [
   { nombre: 'Conventions', regex: /^##\s+(Conventions|Convenciones)/im },
 ];
 
+// Patrones que reconocen que el CLAUDE.md incorpora los 4 principios Karpathy
+// o referencia explícita al skill prevencion-sobreingenieria.
+const KARPATHY_PATTERNS = [
+  /karpathy/i,
+  /cuatro\s+principios/i,
+  /4\s+principios/i,
+  /prevencion-sobreingenieria/i,
+];
+
 const PLACEHOLDERS = /\[(TBD|TODO|COMPLETAR|PENDIENTE|XXX|FIXME)\]/g;
 
 // ─── Auditoría ────────────────────────────────────────────────────────────
@@ -129,6 +152,42 @@ function auditar(rutaClaudeMd) {
     });
   }
 
+  // 6. Referencia a los 4 principios Karpathy o al skill prevencion-sobreingenieria.
+  //    Solo aplica a CLAUDE.md project-level con tamaño no trivial.
+  const tieneReferenciaKarpathy = detectarReferenciaKarpathy(contenido);
+  const esProjectLevel = !esRutaUserLevel(rutaClaudeMd);
+  if (!tieneReferenciaKarpathy && lineas.length > KARPATHY_MIN_LINES && esProjectLevel) {
+    hallazgos.push({
+      severidad: 'WARN',
+      regla: 'karpathy-reference',
+      mensaje: 'CLAUDE.md no menciona los cuatro principios Karpathy ni el skill prevencion-sobreingenieria',
+      sugerencia: 'Agregar la sub-sección compacta (ver `/swl:claudemd init-project` § Bloque obligatorio Karpathy)',
+    });
+  }
+
+  // 7. Duplicación de reglas globales (~/.claude/rules/) en CLAUDE.md de proyecto.
+  //    Solo aplica a project-level (user-level puede declarar preferencias).
+  let resultadoDuplicaciones = { evaluado: false, duplicaciones: [], total_reglas_evaluadas: 0 };
+  const detectarDuplicaciones = cargarDetectorReglasDuplicadas();
+  if (detectarDuplicaciones) {
+    try {
+      resultadoDuplicaciones = detectarDuplicaciones(contenido, null, {
+        esUserLevel: !esProjectLevel,
+      });
+      for (const dup of resultadoDuplicaciones.duplicaciones) {
+        hallazgos.push({
+          severidad: dup.severidad || 'WARN',
+          regla: 'duplicacion-reglas-globales',
+          mensaje: `Bloque duplica regla global \`~/.claude/rules/${dup.regla_global}\` (línea ~${dup.linea_aproximada})`,
+          sugerencia: dup.remediacion,
+          referencia_canonica: dup.referencia_canonica,
+        });
+      }
+    } catch (e) {
+      // Si el catálogo está corrupto o falla, no bloqueamos la auditoría.
+    }
+  }
+
   // ─── Veredicto ───────────────────────────────────────────────────────────
   const tieneError = hallazgos.some(h => h.severidad === 'ERROR');
   const tieneWarn = hallazgos.some(h => h.severidad === 'WARN');
@@ -145,11 +204,39 @@ function auditar(rutaClaudeMd) {
       secciones_presentes: SECCIONES_CANONICAS.filter(s => s.regex.test(contenido)).map(s => s.nombre),
       secciones_ausentes: seccionesAusentes.map(s => s.nombre),
       tiene_at_references: /@[a-zA-Z][a-zA-Z0-9_\-./]+\.md/.test(contenido),
+      tiene_referencia_karpathy: tieneReferenciaKarpathy,
+      es_project_level: esProjectLevel,
+      duplicaciones_reglas_globales: {
+        evaluado: resultadoDuplicaciones.evaluado,
+        total_reglas_evaluadas: resultadoDuplicaciones.total_reglas_evaluadas,
+        detectadas: resultadoDuplicaciones.duplicaciones.length,
+        ids: resultadoDuplicaciones.duplicaciones.map(d => d.id),
+      },
     },
     hallazgos,
   };
 }
 
+/**
+ * True si el contenido menciona los 4 principios Karpathy o el skill
+ * prevencion-sobreingenieria (cualquier coincidencia case-insensitive).
+ */
+function detectarReferenciaKarpathy(contenido) {
+  return KARPATHY_PATTERNS.some(re => re.test(contenido));
+}
+
+/**
+ * True si la ruta apunta a un CLAUDE.md user-level (~/.claude/CLAUDE.md).
+ * El check Karpathy NO aplica a user-level — esos siguen otro contrato
+ * (preferencias personales, no implementación).
+ */
+function esRutaUserLevel(rutaClaudeMd) {
+  if (!rutaClaudeMd) return false;
+  const homeClaudeDir = path.resolve(path.join(os.homedir(), '.claude'));
+  const rutaAbs = path.resolve(rutaClaudeMd);
+  return rutaAbs.startsWith(homeClaudeDir + path.sep) || rutaAbs === path.join(homeClaudeDir, 'CLAUDE.md');
+}
+
 /**
  * Detecta bullets/párrafos cuyo contenido excede MAX_BULLET_CHARS.
  * Un "bullet" es una línea que empieza con `-` o `*` (ignorando indentación).
@@ -249,6 +336,13 @@ function imprimirReporte(resultado) {
       console.log(`  - Secciones ausentes: ${m.secciones_ausentes.join(', ')}`);
     }
     console.log(`  - @references: ${m.tiene_at_references ? 'sí' : 'no'}`);
+    if (m.es_project_level) {
+      console.log(`  - Referencia Karpathy: ${m.tiene_referencia_karpathy ? 'sí' : 'no'}`);
+    }
+    if (m.duplicaciones_reglas_globales && m.duplicaciones_reglas_globales.evaluado) {
+      const d = m.duplicaciones_reglas_globales;
+      console.log(`  - Duplicaciones de reglas globales: ${d.detectadas}/${d.total_reglas_evaluadas} reglas duplicadas${d.detectadas > 0 ? ' (' + d.ids.join(', ') + ')' : ''}`);
+    }
     console.log('');
   }
 
@@ -294,4 +388,16 @@ if (require.main === module) {
   main();
 }
 
-module.exports = { auditar, ubicarClaudeMd, detectarBulletsGigantes, main, MAX_LINES, MAX_BULLET_CHARS };
+module.exports = {
+  auditar,
+  ubicarClaudeMd,
+  detectarBulletsGigantes,
+  detectarReferenciaKarpathy,
+  esRutaUserLevel,
+  main,
+  MAX_LINES,
+  MAX_BULLET_CHARS,
+  KARPATHY_MIN_LINES,
+  // Re-export lazy del detector (puede ser null si lib/ no está disponible):
+  cargarDetectorReglasDuplicadas,
+};