@saulwade/swl-ses 1.6.8 → 1.7.1

package/hooks/claudemd-duplicacion-detector.js

@@ -0,0 +1,170 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Hook: claudemd-duplicacion-detector.js
+ * Tipo: PostToolUse  (aplica a: Write, Edit, MultiEdit)
+ *
+ * Detecta duplicación de reglas globales (`~/.claude/rules/`) inline en
+ * `CLAUDE.md` de proyecto recién modificados. Consume el detector
+ * `scripts/lib/detector-reglas-duplicadas.js` que lee el catálogo
+ * declarativo `scripts/lib/reglas-globales-conocidas.json`.
+ *
+ * Aplica la regla `reglas/sin-duplicacion-reglas-globales.md`:
+ * el `CLAUDE.md` del proyecto NO debe duplicar reglas que ya viven en
+ * `~/.claude/rules/`. La regla global es fuente de verdad; el proyecto
+ * referencia, no duplica.
+ *
+ * Opt-out: SWL_CLAUDEMD_DUPLICACION=0 desactiva completamente el hook.
+ *
+ * Comportamiento:
+ *   - Nunca bloquea operaciones (exit code 0 siempre)
+ *   - Solo emite nudge cuando hay duplicaciones detectadas
+ *   - Solo se dispara con archivos cuyo basename sea exactamente CLAUDE.md
+ *   - Respeta exclusiones: temp/, node_modules/, respositorios-git/
+ *   - NO evalúa user-level (~/.claude/CLAUDE.md) — ahí sí pueden
+ *     declararse preferencias personales
+ *
+ * Formato del nudge:
+ *   {
+ *     id: string,
+ *     kind: "claudemd-duplicacion-reglas",
+ *     target: "documentador-swl",
+ *     source: "hooks/claudemd-duplicacion-detector.js",
+ *     message: "...",
+ *     data: { archivo, duplicaciones: [...] },
+ *     ts: ISO,
+ *     accionado: false
+ *   }
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const crypto = require('crypto');
+
+// ─── Opt-out global ───────────────────────────────────────────────────────
+if (process.env.SWL_CLAUDEMD_DUPLICACION === '0') {
+  process.exit(0);
+}
+
+let hookInput = '';
+try {
+  hookInput = fs.readFileSync(0, 'utf-8');
+} catch (_) {
+  process.exit(0);
+}
+
+let evento;
+try {
+  evento = JSON.parse(hookInput);
+} catch (_) {
+  process.exit(0);
+}
+
+const toolName = evento?.tool_name;
+const toolInput = evento?.tool_input;
+
+if (!toolName || !['Write', 'Edit', 'MultiEdit'].includes(toolName)) {
+  process.exit(0);
+}
+
+const filePath = toolInput?.file_path;
+if (!filePath) {
+  process.exit(0);
+}
+
+// Solo CLAUDE.md (basename exacto, case-sensitive)
+const basename = path.basename(filePath);
+if (basename !== 'CLAUDE.md') {
+  process.exit(0);
+}
+
+const pathNormalized = filePath.replace(/\\/g, '/');
+const RUTAS_EXCLUIDAS = [
+  '/temp/',
+  '/node_modules/',
+  '/respositorios-git/',
+  '/.planning/',
+];
+if (RUTAS_EXCLUIDAS.some((excluida) => pathNormalized.includes(excluida))) {
+  process.exit(0);
+}
+
+// User-level: no evaluar (puede declarar preferencias personales)
+const homeClaudeDir = path.resolve(path.join(os.homedir(), '.claude'));
+const rutaAbs = path.resolve(filePath);
+const esUserLevel = rutaAbs.startsWith(homeClaudeDir + path.sep) || rutaAbs === path.join(homeClaudeDir, 'CLAUDE.md');
+
+// El archivo debe existir
+if (!fs.existsSync(filePath)) {
+  process.exit(0);
+}
+
+// ─── Cargar detector ──────────────────────────────────────────────────────
+const CWD = process.cwd();
+const detectorPath = path.join(CWD, 'scripts', 'lib', 'detector-reglas-duplicadas.js');
+if (!fs.existsSync(detectorPath)) {
+  // No hay detector instalado en este destino; salir silenciosamente
+  process.exit(0);
+}
+
+let resultado;
+try {
+  const { detectarDuplicaciones } = require(detectorPath);
+  const contenido = fs.readFileSync(filePath, 'utf8');
+  resultado = detectarDuplicaciones(contenido, null, { esUserLevel });
+} catch (_) {
+  // Cualquier error del detector: salir silenciosamente
+  process.exit(0);
+}
+
+// Solo emitir nudge si hay duplicaciones detectadas
+if (!resultado || !resultado.evaluado || resultado.duplicaciones.length === 0) {
+  process.exit(0);
+}
+
+// ─── Construir nudge ──────────────────────────────────────────────────────
+const rutaRelativa = path.relative(CWD, filePath).replace(/\\/g, '/');
+const topDuplicaciones = resultado.duplicaciones
+  .slice(0, 5)
+  .map((d) => `  - [${d.severidad}] ${d.id} (regla global: ${d.regla_global}, línea ~${d.linea_aproximada})`)
+  .join('\n');
+
+const nudge = {
+  id: crypto.randomBytes(8).toString('hex'),
+  kind: 'claudemd-duplicacion-reglas',
+  target: 'documentador-swl',
+  source: 'hooks/claudemd-duplicacion-detector.js',
+  message:
+    `[claudemd-dup] ${rutaRelativa} duplica ${resultado.duplicaciones.length} regla(s) global(es):\n` +
+    topDuplicaciones + '\n' +
+    `  Ejecutar \`/swl:claudemd audit\` para detalle, ` +
+    `\`/swl:claudemd refactor\` para sugerencias de reemplazo.\n` +
+    `  Ver regla: \`reglas/sin-duplicacion-reglas-globales.md\`.`,
+  data: {
+    archivo: rutaRelativa,
+    total_evaluadas: resultado.total_reglas_evaluadas,
+    detectadas: resultado.duplicaciones.length,
+    ids: resultado.duplicaciones.map((d) => d.id),
+    reglas_globales: [...new Set(resultado.duplicaciones.map((d) => d.regla_global))],
+  },
+  ts: new Date().toISOString(),
+  accionado: false,
+  accionado_ts: null,
+  accionado_por: null,
+};
+
+// ─── Persistir a nudges.jsonl ─────────────────────────────────────────────
+try {
+  const nudgesPath = path.join(CWD, '.planning', 'evolucion', 'nudges.jsonl');
+  const nudgesDir = path.dirname(nudgesPath);
+  if (!fs.existsSync(nudgesDir)) {
+    fs.mkdirSync(nudgesDir, { recursive: true });
+  }
+  fs.appendFileSync(nudgesPath, JSON.stringify(nudge) + '\n', 'utf-8');
+} catch (_) {
+  // No fallar el hook por error de escritura
+}
+
+process.exit(0);

package/manifiestos/hooks-config.json

@@ -356,6 +356,15 @@
       "maxConsecutiveFailures": 5,
       "degradeOnFailure": "skip"
     },
+    "claudemd-duplicacion-detector.js": {
+      "event": "PostToolUse",
+      "matcher": "Write|Edit|MultiEdit",
+      "description": "Detecta duplicación de reglas globales (~/.claude/rules/) inline en CLAUDE.md de proyecto. Consume scripts/lib/detector-reglas-duplicadas.js + catálogo scripts/lib/reglas-globales-conocidas.json. Aplica regla reglas/sin-duplicacion-reglas-globales.md. Emite nudge a .planning/evolucion/nudges.jsonl si hay duplicaciones detectadas. No bloquea — kind: claudemd-duplicacion-reglas. Excluye temp/, node_modules/, respositorios-git/, .planning/, ~/.claude/ (user-level). Opt-out: SWL_CLAUDEMD_DUPLICACION=0.",
+      "blocking": false,
+      "async": true,
+      "maxConsecutiveFailures": 5,
+      "degradeOnFailure": "skip"
+    },
     "validar-intent-spec.js": {
       "event": "PostToolUse",
       "matcher": "Write|Edit|MultiEdit",

package/manifiestos/modulos.json

@@ -905,7 +905,9 @@
         "reglas/registro-componentes-nuevos.md",
         "reglas/auditorias-documentales-estructurales.md",
         "reglas/intent-engineering.md",
-        "reglas/tests-cleanup.md"
+        "reglas/tests-cleanup.md",
+        "reglas/verificar-citas-temporales.md",
+        "reglas/sin-duplicacion-reglas-globales.md"
       ],
       "targets": [
         "claude",
@@ -1024,6 +1026,7 @@
         "hooks/inbox-aviso.js",
         "hooks/aiisms-detector.js",
         "hooks/claudemd-bloat-detector.js",
+        "hooks/claudemd-duplicacion-detector.js",
         "hooks/validar-intent-spec.js",
         "hooks/sugerir-regenerar-inventario.js",
         "hooks/sugerir-contribuir.js",
@@ -1219,6 +1222,8 @@
       "tipo": "scripts",
       "archivos": [
         "scripts/auditar-claudemd.js",
+        "scripts/lib/detector-reglas-duplicadas.js",
+        "scripts/lib/reglas-globales-conocidas.json",
         "docs/variables-entorno.md"
       ],
       "targets": [

package/manifiestos/skills-lock.json

@@ -1,8 +1,8 @@
 {
   "lockfileVersion": 1,
-  "generatedAt": "2026-05-22T17:02:33.598Z",
+  "generatedAt": "2026-05-22T23:28:47.439Z",
   "skillsCount": 177,
-  "lockHash": "sha256:5d644809f2e8c7741a4553f1f6f493d309d4913782c9560bf06bd735eed1701e",
+  "lockHash": "sha256:d0306679d924ecbbd0071f532df9f2cfb499817eb42b0bb5e6e5ebcdacb941f2",
   "skills": [
     {
       "nombre": "accesibilidad-a11y",
@@ -1099,9 +1099,9 @@
     {
       "nombre": "swl-claudemd",
       "path": "habilidades/swl-claudemd/SKILL.md",
-      "hash": "sha256:dd8ef172d38668e261fc88ff22e614559a05a4f13b2c612c2da3ea2388494377",
-      "bytes": 13666,
-      "version": "\"1.0.2\""
+      "hash": "sha256:0f5eed29f3fedb3bca8036ae5680901712520b31190ad416700c732b2b5897e4",
+      "bytes": 21518,
+      "version": "\"1.2.0\""
     },
     {
       "nombre": "swl-dashboard",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@saulwade/swl-ses",
-  "version": "1.6.8",
-  "description": "Sistema de ingenieria de software auto-evolutivo multi-runtime polyglot con 61 agentes, 177 habilidades, 44 comandos, 69 reglas y 42 hooks. Soporta 11 lenguajes y 7 runtimes: Claude Code, OpenClaude, OpenCode, Gemini CLI, Cursor, Codex CLI (soporte completo); GitHub Copilot (soporte parcial). 100% en espanol (Mexico). Multi-target install (--target CSV / --all-runtimes), autoconfig MCP en Cursor/Codex con --with-mcp, agentes Codex en TOML, hooks Cursor (17 eventos) y Codex (6 eventos). Gateway bidireccional con relay Telegram y auditoria profunda Nemesis con loop evaluator-optimizer opt-in (ADR-0021) y 8 tools ejecutables. v1.6.5 integra 3 patrones de awesome-codex-skills (ComposioHQ, MIT) — agent-deep-links + changelog-generator + gh-fix-ci-swl — ADR-0029, y promueve 3 evoluciones SIGAF al sistema global (D1 nemesis SendMessage + D2 verificar smoke frontend + L2 alineacion veredicto).",
+  "version": "1.7.1",
+  "description": "Sistema de ingenieria de software auto-evolutivo multi-runtime polyglot con 61 agentes, 177 habilidades, 44 comandos, 71 reglas y 43 hooks. Soporta 11 lenguajes y 7 runtimes: Claude Code, OpenClaude, OpenCode, Gemini CLI, Cursor, Codex CLI (soporte completo); GitHub Copilot (soporte parcial). 100% en espanol (Mexico). Multi-target install (--target CSV / --all-runtimes), autoconfig MCP en Cursor/Codex con --with-mcp, agentes Codex en TOML, hooks Cursor (17 eventos) y Codex (6 eventos). Gateway bidireccional con relay Telegram y auditoria profunda Nemesis con loop evaluator-optimizer opt-in (ADR-0021) y 8 tools ejecutables. v1.7.1 introduce dimension 8 del auditor CLAUDE.md (deteccion de duplicacion de reglas globales) + hook PostToolUse claudemd-duplicacion-detector + regla sin-duplicacion-reglas-globales.md + catalogo declarativo reglas-globales-conocidas.json con 6 reglas (idioma, brevedad, git-coauthor, arreglar-al-detectar, debatir, context7).",
   "bin": {
     "swl-ses": "bin/swl-ses.js",
     "swl-telegram-bot": "bin/swl-telegram-bot.js",

package/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "swl-ses",
-  "version": "1.6.8",
-  "description": "Sistema de ingenieria de software auto-evolutivo multi-runtime polyglot. 61 agentes, 177 habilidades, 44 comandos, 69 reglas y 42 hooks. 62 librerias. 11 lenguajes. Soporta Claude Code, Copilot, OpenCode, Codex y Gemini CLI. Loop evaluator-optimizer en /swl:nemesis (ADR-0021). 3 patrones de awesome-codex-skills (ComposioHQ, MIT) adoptados (ADR-0029) — agent-deep-links + changelog-generator + gh-fix-ci-swl. Promueve 3 evoluciones SIGAF (D1 nemesis SendMessage, D2 verificar smoke frontend, L2 alineacion veredicto).",
+  "version": "1.7.1",
+  "description": "Sistema de ingenieria de software auto-evolutivo multi-runtime polyglot. 61 agentes, 177 habilidades, 44 comandos, 71 reglas y 43 hooks. 62 librerias. 11 lenguajes. Soporta Claude Code, Copilot, OpenCode, Codex y Gemini CLI. Loop evaluator-optimizer en /swl:nemesis (ADR-0021). v1.7.1 introduce dimension 8 del auditor CLAUDE.md (deteccion de duplicacion de reglas globales), hook PostToolUse claudemd-duplicacion-detector, regla sin-duplicacion-reglas-globales y catalogo declarativo de 6 reglas globales conocidas (idioma, brevedad, git-coauthor, arreglar-al-detectar, debatir, context7).",
   "author": "Saul Wade Leon",
   "license": "MIT",
   "repository": "https://github.com/saul-wade/swl-ses",

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

@@ -29,6 +29,17 @@ 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 =
@@ -154,6 +165,29 @@ function auditar(rutaClaudeMd) {
     });
   }
 
+  // 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');
@@ -172,6 +206,12 @@ function auditar(rutaClaudeMd) {
       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,
   };
@@ -299,6 +339,10 @@ function imprimirReporte(resultado) {
     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('');
   }
 
@@ -354,4 +398,6 @@ module.exports = {
   MAX_LINES,
   MAX_BULLET_CHARS,
   KARPATHY_MIN_LINES,
+  // Re-export lazy del detector (puede ser null si lib/ no está disponible):
+  cargarDetectorReglasDuplicadas,
 };