@saulwade/swl-ses 2.6.0 → 2.6.1

package/CLAUDE.md

@@ -1,197 +1,197 @@
-# CLAUDE.md — @saulwade/swl-ses v2.6.0
-
-## Reglas de máxima prioridad (aplican SIEMPRE, sin excepción)
-
-### Idioma y estilo de output
-Aplican las reglas globales `@~/.claude/rules/brevedad-output.md` (español de México, brevedad, sin AI-isms) y `@~/.claude/rules/git-coauthor.md` (sin co-autores en commits) — cargadas automáticamente en cada sesión. NO duplicar su contenido inline en este archivo (regla `@reglas/sin-duplicacion-reglas-globales.md`).
-
-### Uso obligatorio del sistema SWL
-Aplica la regla global `@~/.claude/rules/usar-sistema-swl.md` — matriz operacional completa (qué agente/skill/comando usar por tipo de tarea, excepciones legítimas, anti-patrones). Cargar skills con `Skill("nombre")` antes de implementar.
-
-### Cuatro principios de implementación (Karpathy)
-Antes de implementar, refactorizar o corregir bugs: (1) **pensar antes de codificar** (no asumir en silencio), (2) **simplicidad primero** (sin abstracciones especulativas), (3) **cambios quirúrgicos** (leer archivo completo antes de editar, no refactor de oportunidad), (4) **ejecución orientada a metas** (criterios verificables, test que reproduce bugs antes del fix). Tabla operativa + mapeo a agentes SWL en `@docs/karpathy-principios.md`. Detalle + 9 ejemplos MAL→BIEN: `Skill("prevencion-sobreingenieria")` + `recursos/EXAMPLES.md`.
-
-### Lectura de documentos Office
-Cuando necesites leer el **contenido** de un archivo `.docx`, `.xlsx`, `.xls` o `.pptx`, NUNCA uses el Read tool directamente (no soporta esos formatos). Usa:
-```bash
-python scripts/vendor/markitdown/cli.py <ruta-al-archivo>
-```
-El Read tool sigue siendo correcto para `.pdf` (≤20 páginas), `.ipynb` (Claude Code actual lee notebooks nativamente: celdas + outputs), `.md`, `.txt` y código fuente. Para más opciones y casos de uso consultar `Skill("swl-markitdown")`.
-
-### Versión SemVer del próximo release: decisión exclusiva del usuario
-NUNCA asumir, sugerir como hecho consumado, ni escribir en ADRs/manifiestos/CHANGELOG el número del próximo release sin autorización explícita del usuario en la conversación actual. El agente puede **recomendar** el bump apropiado según SemVer estricto, pero la **decisión final del número es del usuario**. Detalle y origen del aprendizaje en `.planning/APRENDIZAJES.md` sesión 2026-05-16 (ADR-0021).
-
----
-
-## Stack del proyecto
-
-- **Runtime**: Node.js >=22.0.0 (ESM + CommonJS)
-- **Tipo**: Sistema de scripts CLI + plugin para Claude Code (multi-runtime: Claude / Copilot / OpenCode / Codex / Gemini)
-- **Formato fuente**: Markdown (agentes, skills, comandos, reglas) + JSON Schema (validación) + YAML (instintos)
-- **Distribución**: npm package (`@saulwade/swl-ses`) + plugin Claude Code (`plugin.json`)
-- **Dependencias runtime**: 1 directa (`docx ^9.6.1`; `pako` y `readable-stream` son transitivas de docx/jszip, no directas). Hooks y scripts/lib son zero-deps
-- **Idioma de salida**: 100% español (México) para componentes SWL; skills oficiales de Anthropic en inglés
-- **MCP del proyecto**: `code-review-graph` disponible vía `.mcp.json` (requiere `uvx`). Comportamiento: `@~/.claude/rules/usar-code-review-graph.md`
-
-## Comandos del proyecto
-
-| Comando | Propósito |
-|---|---|
-| `npm test` | Tests unitarios (lib/, scripts/, hooks/) |
-| `npm run test:all` | test + validar.js + validar-manifest.js |
-| `npm run test:release` | test:all + test:userland + smoke (gate pre-publish) |
-| `npm run test:validate` | `node scripts/validar.js` — validación estructural completa |
-| `npm run test:manifest` | `node scripts/validar-manifest.js` — coherencia modulos/hooks |
-| `npm run test:smoke` | Smoke test del instalador |
-| `npm run gen-checklists` | Regenera `docs/checklists-consolidados/` desde reglas |
-| `npm run gen-checklists:check` | Falla si hay drift (uso CI) |
-| `npm run generate:docs` | Regenera `INVENTARIO.md` desde directorios |
-| `npm run doctor` | Diagnóstico del sistema (`scripts/doctor.js`) |
-| `npm run publish:dry` | Dry-run de publicación a npm + GitHub |
-| `node scripts/verificar-release.js` | Gate pre-release: 15+ ubicaciones de versión, sincronización, AI-isms (si `SWL_AIISMS_GATE=1`) |
-| `node scripts/generar-inventario.js` | Regenera contadores oficiales + catálogos de INVENTARIO/SALUD/llms.txt (NUNCA contar a mano) |
-| `npm run gen-comandos` | Regenera los bloques `CATALOGO-COMANDOS` de COMANDOS.md y AGENTS.md desde frontmatter; `--check` (en test:all) detecta drift |
-| `node scripts/auditar-clases-conocidas.js` | Gate anti-reincidencia de clases de bug documentadas (C1 fecha UTC, C2 comparación sin normalizar EOL, C3 bloqueo ciego en hooks). En test:all |
-| `node scripts/canario-hooks.js [--smoke]` | Canario de hooks: grafo de requires distribuido en modulos.json (clase check-update); --smoke ejecuta los 49 en sandbox (en test:release) |
-| `node scripts/derivar-feature-list.js` | Genera `.planning/feature-list.json` (derivado de `HOJA-RUTA.md`, gitignored, regenerable). Modo `--check` exit 2 si drift detectado. Consumido por `/swl:status metricas fases`. |
-
-## Code style
-
-- **Nombres**: kebab-case para archivos; agentes SWL y vocabulario GSD (comandos `*-fase`, dir `.planning/fases/`) en español; paths runtime/técnicos de `.planning/` en inglés (`evolution/`, `auto-evolution/`, `user-profile/`, `archive/`, `traces/`, `sessions/`, `audit/`). Ver `@~/.claude/rules/analizar-directorios-antes-de-escribir.md § Eje técnico-runtime`
-- **Zero-dependencies en `hooks/lib/`**: sin dependencias npm externas
-- **Escrituras atómicas obligatorias**: usar `atomicWriteSync()` / `atomicWriteJSON()` de `hooks/lib/atomic-write.js`. NUNCA `fs.writeFileSync` directo en archivos del sistema
-- **JSONL para alta frecuencia**: usar `fs.appendFileSync(ruta, JSON.stringify(evento) + '\n')` en hooks de telemetría/auditoría — no `atomicWriteJSON` que reescribe todo
-- **Fechas de artefactos generados SIEMPRE locales**: `toLocaleDateString('sv')`, NUNCA `toISOString().slice(0,10)` — desde México la tarde ya es "mañana" en UTC (x7 sitios corregidos 2026-07-08)
-- **Reemplazos con backticks/regex vía `node -e` en bash mangean escapes en silencio** ("aplica" sin aplicar): usar heredoc `node <<'EOF'` + `String.raw` (x3 incidentes 2026-07-08)
-- **`plugin.json#agents`/`#skills` son alfabéticos**: insertar en posición — ningún gate valida el orden
-- **Todo gate de escaneo nuevo lleva test anti-regresión viva** ("el repo real pasa con exit 0") en `npm test`: pre-commit el gate no se escanea a sí mismo (`git ls-files` ignora untracked) y su doc NO escribe el patrón prohibido literal (se auto-detectó y tumbó el publish v2.5.1)
-- **Contrato del CLI (`bin/swl-ses.js`)**: todo subcomando exporta UNA función(opciones) sin efectos al require — test viviente `bin-contrato-comandos.test.js` (3 violaciones cazadas, una en campo)
-- **YAML inline en frontmatter**: `tools: [Read, Write]`, `skillsInvocables: [skill-a]`. NUNCA CSV string ni mezcla con lista multilínea
-- **Mensajes de commit**: imperativo en español, formato `<tipo>(<scope>): <descripción>`
-- **Sin `console.log` en producción** — excepto en `scripts/`, `bin/`, `hooks/`, `gateway/` (CLIs y daemons)
-- **Nombre completo del paquete en npx**: todo mensaje del installer/docs usa `npx -y @saulwade/swl-ses@latest <comando>`. **NUNCA** `npx swl-ses@latest <comando>` sin el scope `@saulwade/` — eso resuelve al paquete legacy DEPRECATED (v5.13.1) que aún existe en npm tras el rebrand de 2026-04-30. El `@latest` es indispensable: sin él npx reutiliza la primera versión cacheada y el usuario corre código viejo sin saberlo. El `-y` evita la prompt de confirmación en CI/scripts
-- **Fixtures `secret`/`token` en tests deben ser en español** (`secreto`, `tokenBearer`, `clave-test`). El hook `calidad-pre-commit.js` matchea `\bsecret\s*[=:]\s*["'][^"'\s]{4,}["']` y `\btoken\s*[=:]\s*["'][^"'\s]{8,}["']` — `const secret = "valor"` se bloquea como credencial hardcodeada aunque sea fixture legítimo. Renombrar a español elude el regex sin bypass (alternativas reconocidas por el hook: `placeholder`, `example`, `fake_`, `dummy_`, `os.environ`/`process.env`). Coherente con regla global de idioma. Origen: PR #11 sesión 2026-05-13
-- **Scopes de runtime SIEMPRE vía `scopesReales()` de `scripts/lib/detectar-runtime.js`** — NUNCA el patrón manual `[runtime.global, path.resolve(runtime.local)]`: desde el HOME el local relativo resuelve al global propio (duplicados) o al de OTRO runtime (scope "proyecto" fantasma — el local de OpenClaude es el global de Claude Code; un uninstall de ese fantasma borraría el global). 8 sitios corregidos el 2026-07-03 (doctor ×5, actualizar ×2, TUI ×4)
-- **`git add archivo && git commit -m "..."` en un solo comando bash NO actualiza el index antes del PreToolUse hook**: el hook `calidad-pre-commit.js` evalúa el contenido staged previo al `&&`, no el actualizado en la misma línea. Síntoma: commit bloqueado por contenido que ya corregiste vía Write/Edit pero seguía staged en versión antigua. Fix: separar en dos calls Bash (`git add archivo` → ver resultado → `git commit -m "..."`). NUNCA usar `--no-verify` para bypassear. Origen: PR #11 sesión 2026-05-13
-- **Secretos compartidos entre clientes MCP viven como variables de entorno persistentes del SO, NO en archivos JSON** [v2 — 2026-05-18]: un MCP usado desde Cursor + Claude Code + VS Code tiene un config JSON POR cliente; duplicar `OBSIDIAN_API_KEY` en N archivos genera drift al regenerar la apiKey. Patrón: `setx OBSIDIAN_API_KEY <key>` (o `[Environment]::SetEnvironmentVariable(..., "User")` en PS7) → escribe a `HKCU\Environment` → todos los clientes la heredan al spawnear el binario. Los JSON OMITEN la clave `env` por completo (NO `env: {}` vacío — pasa literal a `child_process.spawn` y REEMPLAZA el env del padre, rompiendo la herencia). Regenerar apiKey = un `setx` + reiniciar clientes, sin tocar JSONs. Origen: 2026-05-18, 6h de errores 40101 por 3 configs descoordinados.
-
-## Convenciones de arquitectura
-
-- **Precedencia de capas**: Reglas base (`reglas/`) → Reglas por lenguaje (`reglas/{lang}/`) → Skills (`habilidades/`) → Instintos (`instintos/`). Cada capa puede especializar pero NUNCA contradecir las superiores
-- **`reglas/` es la FUENTE; `~/.claude/rules/` son copias INSTALADAS** por el instalador: todo cambio a reglas base va en la fuente y se sincroniza — editar solo las copias es deuda volátil (el install las sobreescribe). Incluye las reglas globales personales del usuario (decisión 2026-06-12, commit `2f6b8de` — las 37 base viajan en `reglas-core`). Origen: Fase 09 (APRENDIZAJES 2026-06-11)
-- **Privilegio mínimo de agentes**: un agente delegado NUNCA excede los permisos declarados en su propio frontmatter. La cadena de delegación no escala privilegios. Ver `@reglas/seguridad-agentes.md`
-- **Preservación de datos en actualización**: `.planning/sessions/`, `.planning/comms/`, `_userland/`, `instintos/proyecto.yaml`, `APRENDIZAJES.md` NUNCA se sobreescriben
-- **Documentación obligatoria**: toda funcionalidad nueva DEBE documentarse en `MANUAL_USO.md`, `COMANDOS.md`, `CLAUDE.md` y `README.md` ANTES del commit
-- **Criterio dominio para incorporar skills externos**: solo si dominio = ingeniería de software general. Pregunta de filtro: *¿le sirve esto a un ingeniero de software en cualquier proyecto de software?* (ML Ops, Data Science, finanzas, etc. → descartar)
-- **Filtro primario al analizar `temp/`**: antes de evaluar arquitectura, verificar **compatibilidad de dominio**. Si es incompatible, veredicto NINGUNA aplicabilidad sin análisis adicional
-- **Variables de entorno opt-in enterprise**: ver `@docs/variables-entorno.md` (catálogo completo). Patrón obligatorio: `if (!process.env.VAR) return` — zero-config por defecto
-- **Hooks SWL que invocan auditores Node deben cargar el auditor como módulo (`require()`), no como subproceso**: ~10× más rápido, errores estructurados (no parsing de stdout), tests directos del módulo. Excepción legítima: cuando el auditor es Python o Bash (`spawnSync`). Ejemplo aplicado en `hooks/claudemd-bloat-detector.js` que usa `require('./scripts/auditar-claudemd.js')` directamente. Antipatrón evitado: `spawnSync('node', [auditorPath, ...])` agrega ~50ms por invocación y obliga a parsear JSON de stdout
-- **npm v10+ NO escribe debug logs cuando falla un script invocado** (`prepublishOnly`, `prepack`, etc.) — solo cuando falla npm-mismo (network, registry, auth). El default `loglevel=notice` mantiene `_logs/` vacío para errores de scripts. Para diagnóstico de `npm run publish:all` que falla en script propio, capturar stdout+stderr con redirección: PowerShell `npm run publish:all *>&1 | Tee-Object .planning/logs/publish-$(Get-Date -Format yyyyMMdd-HHmmss).log` o Bash `2>&1 | tee`. Alternativa permanente: `npm config set loglevel verbose`
-- **`package.json#files` debe incluir TODOS los directorios referenciados por `bin/`, `hooks/`, `scripts/` o `comandos/`**: si un binario hace `require('./gateway/foo')` pero `gateway/` no está listado en `files`, **el módulo se omite del tarball npm y el binario falla con MODULE_NOT_FOUND tras instalación pública** — aunque la suite local pase. Bug latente histórico: `/swl:cron`, `/swl:gateway` e `/swl:inbox` instruyen `require('./gateway/...')` y rompían en npm porque `gateway/` no estaba en `files` desde versiones previas. Revelado al agregar `bin/swl-webhook-server` (v1.4.0). Verificar antes de cada release: `npm pack --dry-run | grep -E "^npm notice [0-9].*[Bb] (bin|gateway|hooks|scripts|comandos)/"` debe listar todos los directorios reales referenciados. Gate automatizable en `scripts/verificar-release.js`. Origen: PR #15 sesión 2026-05-13
-- **Comandos `/swl:*` invocan vía CLI cross-scope, NUNCA rutas relativas al proyecto**: dentro de fenced code blocks de `comandos/swl/*.md` usar `swl-ses <sub>` (resolución: repo madre → bin en PATH → `npx -y @saulwade/swl-ses@latest <sub>`), no `node scripts/...` ni `require('./hooks/...')` — esas rutas rompen en instalación global/downstream (gates SDD G0/G1, telemetría, CI). Gate bloqueante en `scripts/validar.js §7b` (`auditar-invocaciones-comandos.js`); excluye SELF_DEV `{release, contribuir, evaluar-skill, reflect-skills}`. Wrappers en `scripts/cli/` se distribuyen SOLO vía npm (`package.json#files`), NO se cuentan en INVENTARIO ni en `modulos.json`; registro único en `bin/swl-ses.js`. Detalle: `@docs/invocacion-cli-cross-scope.md`. Origen: v2.2.0
-- **Componentes evolucionados: merge, no overwrite (invariante)**: el instalador NUNCA sobrescribe un componente con evolución del usuario (global o proyecto) — usa merge (preserve + `.evolved-diff.txt`). Distingue evolución de usuario (A) de shipped-evolved de fábrica (B) por hash del cuerpo canónico (`manifiestos/canonical-hashes.json`); el fuente NO porta marcadores `evolved` (gate inverso en `validar.js`). Detalle: ADR-0040. Origen: Fase 16
-
-## Referencias a docs clave (cargar bajo demanda con `@`)
-
-- `@README.md` — overview público y quickstart
-- `@MANUAL_USO.md` — manual operacional completo
-- `@INSTALACION.md` — instalación, perfiles, configuración
-- `@COMANDOS.md` — referencia detallada de cada `/swl:*`
-- `@AGENTS.md` — catálogo de agentes con capacidades
-- `@INVENTARIO.md` — conteos oficiales (regenerado por script)
-- `@docs/variables-entorno.md` — variables opt-in completas
-- `@docs/CI-CD-SETUP.md` — setup de pipelines
-- `@docs/evidencia-valor.md` — medición de valor en campo (`swl-ses valor`), frontera de datos downstream↔repo madre
-- `@.planning/adrs/README.md` — índice de decisiones arquitecturales
-
----
-
-## Qué es este repositorio
-
-Sistema de ingeniería de software auto-evolutivo multi-runtime polyglot (SDLC completo).
-11 lenguajes, 7 runtimes (Claude, OpenClaude, OpenCode, Gemini, Cursor, Codex, Copilot), 61 agentes, 181 skills, 48 comandos, 77 reglas, 49 hooks.
-
-## Estructura del repositorio
-
-```
-agentes/       habilidades/    comandos/swl/   contextos/      instintos/
-reglas/        hooks/          schemas/        manifiestos/    plantillas/
-scripts/       bin/            _userland/      .claude/        .planning/
-```
-
-## Flujos de trabajo
-
-**Feature completa**: orquestador → discovery → PRD → arquitectura → plan → implementación (paralelo) → calidad (paralelo) → cierre
-**Fases GSD**: discutir → planear → ejecutar → verificar
-**Frontend**: investigador-ux → disenador-ui → accesibilidad → frontend-* → rendimiento
-**Backend**: backend-api → backend-python/node → backend-workers → datos
-**Mobile**: producto-prd → mobile-cross (decisión) → mobile-android/ios → tdd-qa
-
-## Comandos del sistema (/swl:*)
-
-Catálogo completo de 48 comandos `/swl:*` en `@COMANDOS.md`. Atajos mentales por categoría:
-
-- **Ciclo GSD por fase**: `discutir-fase` → `planear-fase` → `ejecutar-fase` → `verificar` (con discovery routing, modo iterativo `--iterative` y `--until-converge`).
-- **Anti-context-rot**: `checkpoint`, `compactar`.
-- **Aprendizaje**: `aprender`, `evolucionar`, `evolucion-continua` (motor determinista on|off|status, ADR-0041), `autoresearch`, `reflect-skills`.
-- **Calidad**: `revisar`, `verificar`, `nemesis` (auditoría Feynman + State, opcional `--remediar`), `deuda-codigo` (cosecha de marcadores `simplificado:`), `seguridad` (postura del proyecto completo), `fix` (triage y despacho de reparaciones), `predecir` (panel pre-implementación; `--abogado-diablo` critica la decisión).
-- **Diagnóstico**: `salud`, `metricas`, `dashboard`, `evolucion-estado`.
-- **Release**: `release`, `configurar-ci`.
-- **Conocimiento**: `wiki`, `mapear-codebase`, `skill-search`, `ayuda`.
-
-Para flags exactos y semántica de cada comando ver `@COMANDOS.md` y `@MANUAL_USO.md`.
-
-## Reglas obligatorias (37 base + 40 por lenguaje)
-
-Las reglas globales del usuario en `~/.claude/rules/` se cargan automáticamente
-y aplican a todos los proyectos. Las reglas del sistema en `reglas/` se cargan
-por matcher de archivos o vía `@reglas/<nombre>.md` desde el CLAUDE.md del
-proyecto. Reglas de mayor uso:
-
-| Regla | Carga cuando |
-|-------|-------------|
-| `brevedad-output.md` | Siempre — idioma español, eficiencia de tokens |
-| `seguridad.md` / `seguridad-agentes.md` | `*.py`, `*.ts`, `auth/`, agentes autónomos |
-| `arreglar-al-detectar.md` | Siempre — detectar → informar → arreglar en mismo turno |
-| `analisis-previo-tareas-grandes.md` | Solicitudes >10 archivos / >500 LOC / cross-módulo |
-| `usar-context7.md` | Al generar código que importe librerías externas |
-| `git-workflow.md` | Siempre |
-| `skills-estandar.md` / `fragmentos-compartidos.md` | Crear/auditar skills o fragmentos |
-| `registro-componentes-nuevos.md` | Crear cualquier componente nuevo (agente/skill/comando/hook/regla) — registro obligatorio en manifiestos + plugin.json + INVENTARIO en mismo commit |
-| `auditorias-documentales-estructurales.md` | Ejecutar verificadores docs/release/manifest — gates de profundidad y cobertura completa (no muestra). Aplica reglas anti-cosméticas a auditorías |
-
-Catálogo completo y matchers en `@INVENTARIO.md` sección Reglas.
-
-<!-- La regla de la sección "Uso obligatorio del sistema SWL" NO se importa con @: la copia global ya carga sola; el @import duplicaba ~250 líneas/sesión. Depurado Fase 09 (commit 7273c9e). -->
-
-## Estrategia de modelos (Model-Tier)
-
-Tiers por alias (se actualizan solos, NUNCA ID pineado en frontmatter): `fable` solo orquestador (coordinación central); `opus` decisiones irreversibles (arquitecto, revisor-seguridad, producto-prd, abogado-diablo); `sonnet` implementación y revisión; `haiku` operaciones deterministas; `inherit` sub-agentes del orquestador. NUNCA un tier superior para lo que el inferior resuelve igual. Detalle (alias vs API cruda, workflow de delegación, effort levels): `@docs/model-tier.md`.
-
----
-
-## Convenciones operacionales
-
-Detalle completo en `@docs/convenciones-operacionales.md`. Resumen mínimo:
-
-- **Score mínimo de calidad**: **9.0/10** para aprobar trabajo.
-- **Modos de desarrollo**: `dev`, `review`, `research` (vía `/swl:contexto`).
-- **`respositorios-git/` y `temp/` son material de referencia** — no modificar ni commitear.
-- **Dependencias externas educativas son opt-in NO-dependencia** — el sistema funciona sin ellas.
-- **Patrón "validar antes de invocar"** para herramientas externas opt-in (markitdown, MinerU, gh).
-- **`skillsInvocables` requiere `Skill` en `tools:`** del agente.
-
-## Mapa de propagación de cambios
-
-Al modificar o agregar cualquier componente del sistema, **invocar
-`Skill("doc-sync")` antes del commit final** para cargar el protocolo
-proactivo completo. La tabla y checklist completos viven en
-`@docs/mapa-propagacion.md` para mantener este archivo bajo el umbral
-de 200 líneas (regla `auditar-claudemd.js`).
-
-Resumen mínimo para uso inmediato:
-
-- Cualquier componente nuevo o modificado (agente / skill / comando / hook / regla / schema / variable `SWL_*` / ADR / dependencia opt-in): consultar tabla completa en `@docs/mapa-propagacion.md` para saber qué archivos tocar.
-- **Skill responsable**: `Skill("doc-sync") § Protocolo proactivo` (sub-secciones Tipo 1 a Tipo 8) tiene el detalle prescriptivo.
-- **Antes de commit estructural**: regenerar inventario, validar manifiestos, verificar evolución (si tocó skill/agente), correr verificador docs-vs-código, suite completa, gate de release. Checklist exacto en `@docs/mapa-propagacion.md § Checklist único`.
-- Si cualquier gate falla, **NO commitear** hasta corregir. Regla `arreglar-al-detectar.md` exige resolver en mismo turno.
+# CLAUDE.md — @saulwade/swl-ses v2.6.1
+
+## Reglas de máxima prioridad (aplican SIEMPRE, sin excepción)
+
+### Idioma y estilo de output
+Aplican las reglas globales `@~/.claude/rules/brevedad-output.md` (español de México, brevedad, sin AI-isms) y `@~/.claude/rules/git-coauthor.md` (sin co-autores en commits) — cargadas automáticamente en cada sesión. NO duplicar su contenido inline en este archivo (regla `@reglas/sin-duplicacion-reglas-globales.md`).
+
+### Uso obligatorio del sistema SWL
+Aplica la regla global `@~/.claude/rules/usar-sistema-swl.md` — matriz operacional completa (qué agente/skill/comando usar por tipo de tarea, excepciones legítimas, anti-patrones). Cargar skills con `Skill("nombre")` antes de implementar.
+
+### Cuatro principios de implementación (Karpathy)
+Antes de implementar, refactorizar o corregir bugs: (1) **pensar antes de codificar** (no asumir en silencio), (2) **simplicidad primero** (sin abstracciones especulativas), (3) **cambios quirúrgicos** (leer archivo completo antes de editar, no refactor de oportunidad), (4) **ejecución orientada a metas** (criterios verificables, test que reproduce bugs antes del fix). Tabla operativa + mapeo a agentes SWL en `@docs/karpathy-principios.md`. Detalle + 9 ejemplos MAL→BIEN: `Skill("prevencion-sobreingenieria")` + `recursos/EXAMPLES.md`.
+
+### Lectura de documentos Office
+Cuando necesites leer el **contenido** de un archivo `.docx`, `.xlsx`, `.xls` o `.pptx`, NUNCA uses el Read tool directamente (no soporta esos formatos). Usa:
+```bash
+python scripts/vendor/markitdown/cli.py <ruta-al-archivo>
+```
+El Read tool sigue siendo correcto para `.pdf` (≤20 páginas), `.ipynb` (Claude Code actual lee notebooks nativamente: celdas + outputs), `.md`, `.txt` y código fuente. Para más opciones y casos de uso consultar `Skill("swl-markitdown")`.
+
+### Versión SemVer del próximo release: decisión exclusiva del usuario
+NUNCA asumir, sugerir como hecho consumado, ni escribir en ADRs/manifiestos/CHANGELOG el número del próximo release sin autorización explícita del usuario en la conversación actual. El agente puede **recomendar** el bump apropiado según SemVer estricto, pero la **decisión final del número es del usuario**. Detalle y origen del aprendizaje en `.planning/APRENDIZAJES.md` sesión 2026-05-16 (ADR-0021).
+
+---
+
+## Stack del proyecto
+
+- **Runtime**: Node.js >=22.0.0 (ESM + CommonJS)
+- **Tipo**: Sistema de scripts CLI + plugin para Claude Code (multi-runtime: Claude / Copilot / OpenCode / Codex / Gemini)
+- **Formato fuente**: Markdown (agentes, skills, comandos, reglas) + JSON Schema (validación) + YAML (instintos)
+- **Distribución**: npm package (`@saulwade/swl-ses`) + plugin Claude Code (`plugin.json`)
+- **Dependencias runtime**: 1 directa (`docx ^9.6.1`; `pako` y `readable-stream` son transitivas de docx/jszip, no directas). Hooks y scripts/lib son zero-deps
+- **Idioma de salida**: 100% español (México) para componentes SWL; skills oficiales de Anthropic en inglés
+- **MCP del proyecto**: `code-review-graph` disponible vía `.mcp.json` (requiere `uvx`). Comportamiento: `@~/.claude/rules/usar-code-review-graph.md`
+
+## Comandos del proyecto
+
+| Comando | Propósito |
+|---|---|
+| `npm test` | Tests unitarios (lib/, scripts/, hooks/) |
+| `npm run test:all` | test + validar.js + validar-manifest.js |
+| `npm run test:release` | test:all + test:userland + smoke (gate pre-publish) |
+| `npm run test:validate` | `node scripts/validar.js` — validación estructural completa |
+| `npm run test:manifest` | `node scripts/validar-manifest.js` — coherencia modulos/hooks |
+| `npm run test:smoke` | Smoke test del instalador |
+| `npm run gen-checklists` | Regenera `docs/checklists-consolidados/` desde reglas |
+| `npm run gen-checklists:check` | Falla si hay drift (uso CI) |
+| `npm run generate:docs` | Regenera `INVENTARIO.md` desde directorios |
+| `npm run doctor` | Diagnóstico del sistema (`scripts/doctor.js`) |
+| `npm run publish:dry` | Dry-run de publicación a npm + GitHub |
+| `node scripts/verificar-release.js` | Gate pre-release: 15+ ubicaciones de versión, sincronización, AI-isms (si `SWL_AIISMS_GATE=1`) |
+| `node scripts/generar-inventario.js` | Regenera contadores oficiales + catálogos de INVENTARIO/SALUD/llms.txt (NUNCA contar a mano) |
+| `npm run gen-comandos` | Regenera los bloques `CATALOGO-COMANDOS` de COMANDOS.md y AGENTS.md desde frontmatter; `--check` (en test:all) detecta drift |
+| `node scripts/auditar-clases-conocidas.js` | Gate anti-reincidencia de clases de bug documentadas (C1 fecha UTC, C2 comparación sin normalizar EOL, C3 bloqueo ciego en hooks). En test:all |
+| `node scripts/canario-hooks.js [--smoke]` | Canario de hooks: grafo de requires distribuido en modulos.json (clase check-update); --smoke ejecuta los 49 en sandbox (en test:release) |
+| `node scripts/derivar-feature-list.js` | Genera `.planning/feature-list.json` (derivado de `HOJA-RUTA.md`, gitignored, regenerable). Modo `--check` exit 2 si drift detectado. Consumido por `/swl:status metricas fases`. |
+
+## Code style
+
+- **Nombres**: kebab-case para archivos; agentes SWL y vocabulario GSD (comandos `*-fase`, dir `.planning/fases/`) en español; paths runtime/técnicos de `.planning/` en inglés (`evolution/`, `auto-evolution/`, `user-profile/`, `archive/`, `traces/`, `sessions/`, `audit/`). Ver `@~/.claude/rules/analizar-directorios-antes-de-escribir.md § Eje técnico-runtime`
+- **Zero-dependencies en `hooks/lib/`**: sin dependencias npm externas
+- **Escrituras atómicas obligatorias**: usar `atomicWriteSync()` / `atomicWriteJSON()` de `hooks/lib/atomic-write.js`. NUNCA `fs.writeFileSync` directo en archivos del sistema
+- **JSONL para alta frecuencia**: usar `fs.appendFileSync(ruta, JSON.stringify(evento) + '\n')` en hooks de telemetría/auditoría — no `atomicWriteJSON` que reescribe todo
+- **Fechas de artefactos generados SIEMPRE locales**: `toLocaleDateString('sv')`, NUNCA `toISOString().slice(0,10)` — desde México la tarde ya es "mañana" en UTC (x7 sitios corregidos 2026-07-08)
+- **Reemplazos con backticks/regex vía `node -e` en bash mangean escapes en silencio** ("aplica" sin aplicar): usar heredoc `node <<'EOF'` + `String.raw` (x3 incidentes 2026-07-08)
+- **`plugin.json#agents`/`#skills` son alfabéticos**: insertar en posición — ningún gate valida el orden
+- **Todo gate de escaneo nuevo lleva test anti-regresión viva** ("el repo real pasa con exit 0") en `npm test`: pre-commit el gate no se escanea a sí mismo (`git ls-files` ignora untracked) y su doc NO escribe el patrón prohibido literal (se auto-detectó y tumbó el publish v2.5.1)
+- **Contrato del CLI (`bin/swl-ses.js`)**: todo subcomando exporta UNA función(opciones) sin efectos al require — test viviente `bin-contrato-comandos.test.js` (3 violaciones cazadas, una en campo)
+- **YAML inline en frontmatter**: `tools: [Read, Write]`, `skillsInvocables: [skill-a]`. NUNCA CSV string ni mezcla con lista multilínea
+- **Mensajes de commit**: imperativo en español, formato `<tipo>(<scope>): <descripción>`
+- **Sin `console.log` en producción** — excepto en `scripts/`, `bin/`, `hooks/`, `gateway/` (CLIs y daemons)
+- **Nombre completo del paquete en npx**: todo mensaje del installer/docs usa `npx -y @saulwade/swl-ses@latest <comando>`. **NUNCA** `npx swl-ses@latest <comando>` sin el scope `@saulwade/` — eso resuelve al paquete legacy DEPRECATED (v5.13.1) que aún existe en npm tras el rebrand de 2026-04-30. El `@latest` es indispensable: sin él npx reutiliza la primera versión cacheada y el usuario corre código viejo sin saberlo. El `-y` evita la prompt de confirmación en CI/scripts
+- **Fixtures `secret`/`token` en tests deben ser en español** (`secreto`, `tokenBearer`, `clave-test`). El hook `calidad-pre-commit.js` matchea `\bsecret\s*[=:]\s*["'][^"'\s]{4,}["']` y `\btoken\s*[=:]\s*["'][^"'\s]{8,}["']` — `const secret = "valor"` se bloquea como credencial hardcodeada aunque sea fixture legítimo. Renombrar a español elude el regex sin bypass (alternativas reconocidas por el hook: `placeholder`, `example`, `fake_`, `dummy_`, `os.environ`/`process.env`). Coherente con regla global de idioma. Origen: PR #11 sesión 2026-05-13
+- **Scopes de runtime SIEMPRE vía `scopesReales()` de `scripts/lib/detectar-runtime.js`** — NUNCA el patrón manual `[runtime.global, path.resolve(runtime.local)]`: desde el HOME el local relativo resuelve al global propio (duplicados) o al de OTRO runtime (scope "proyecto" fantasma — el local de OpenClaude es el global de Claude Code; un uninstall de ese fantasma borraría el global). 8 sitios corregidos el 2026-07-03 (doctor ×5, actualizar ×2, TUI ×4)
+- **`git add archivo && git commit -m "..."` en un solo comando bash NO actualiza el index antes del PreToolUse hook**: el hook `calidad-pre-commit.js` evalúa el contenido staged previo al `&&`, no el actualizado en la misma línea. Síntoma: commit bloqueado por contenido que ya corregiste vía Write/Edit pero seguía staged en versión antigua. Fix: separar en dos calls Bash (`git add archivo` → ver resultado → `git commit -m "..."`). NUNCA usar `--no-verify` para bypassear. Origen: PR #11 sesión 2026-05-13
+- **Secretos compartidos entre clientes MCP viven como variables de entorno persistentes del SO, NO en archivos JSON** [v2 — 2026-05-18]: un MCP usado desde Cursor + Claude Code + VS Code tiene un config JSON POR cliente; duplicar `OBSIDIAN_API_KEY` en N archivos genera drift al regenerar la apiKey. Patrón: `setx OBSIDIAN_API_KEY <key>` (o `[Environment]::SetEnvironmentVariable(..., "User")` en PS7) → escribe a `HKCU\Environment` → todos los clientes la heredan al spawnear el binario. Los JSON OMITEN la clave `env` por completo (NO `env: {}` vacío — pasa literal a `child_process.spawn` y REEMPLAZA el env del padre, rompiendo la herencia). Regenerar apiKey = un `setx` + reiniciar clientes, sin tocar JSONs. Origen: 2026-05-18, 6h de errores 40101 por 3 configs descoordinados.
+
+## Convenciones de arquitectura
+
+- **Precedencia de capas**: Reglas base (`reglas/`) → Reglas por lenguaje (`reglas/{lang}/`) → Skills (`habilidades/`) → Instintos (`instintos/`). Cada capa puede especializar pero NUNCA contradecir las superiores
+- **`reglas/` es la FUENTE; `~/.claude/rules/` son copias INSTALADAS** por el instalador: todo cambio a reglas base va en la fuente y se sincroniza — editar solo las copias es deuda volátil (el install las sobreescribe). Incluye las reglas globales personales del usuario (decisión 2026-06-12, commit `2f6b8de` — las 37 base viajan en `reglas-core`). Origen: Fase 09 (APRENDIZAJES 2026-06-11)
+- **Privilegio mínimo de agentes**: un agente delegado NUNCA excede los permisos declarados en su propio frontmatter. La cadena de delegación no escala privilegios. Ver `@reglas/seguridad-agentes.md`
+- **Preservación de datos en actualización**: `.planning/sessions/`, `.planning/comms/`, `_userland/`, `instintos/proyecto.yaml`, `APRENDIZAJES.md` NUNCA se sobreescriben
+- **Documentación obligatoria**: toda funcionalidad nueva DEBE documentarse en `MANUAL_USO.md`, `COMANDOS.md`, `CLAUDE.md` y `README.md` ANTES del commit
+- **Criterio dominio para incorporar skills externos**: solo si dominio = ingeniería de software general. Pregunta de filtro: *¿le sirve esto a un ingeniero de software en cualquier proyecto de software?* (ML Ops, Data Science, finanzas, etc. → descartar)
+- **Filtro primario al analizar `temp/`**: antes de evaluar arquitectura, verificar **compatibilidad de dominio**. Si es incompatible, veredicto NINGUNA aplicabilidad sin análisis adicional
+- **Variables de entorno opt-in enterprise**: ver `@docs/variables-entorno.md` (catálogo completo). Patrón obligatorio: `if (!process.env.VAR) return` — zero-config por defecto
+- **Hooks SWL que invocan auditores Node deben cargar el auditor como módulo (`require()`), no como subproceso**: ~10× más rápido, errores estructurados (no parsing de stdout), tests directos del módulo. Excepción legítima: cuando el auditor es Python o Bash (`spawnSync`). Ejemplo aplicado en `hooks/claudemd-bloat-detector.js` que usa `require('./scripts/auditar-claudemd.js')` directamente. Antipatrón evitado: `spawnSync('node', [auditorPath, ...])` agrega ~50ms por invocación y obliga a parsear JSON de stdout
+- **npm v10+ NO escribe debug logs cuando falla un script invocado** (`prepublishOnly`, `prepack`, etc.) — solo cuando falla npm-mismo (network, registry, auth). El default `loglevel=notice` mantiene `_logs/` vacío para errores de scripts. Para diagnóstico de `npm run publish:all` que falla en script propio, capturar stdout+stderr con redirección: PowerShell `npm run publish:all *>&1 | Tee-Object .planning/logs/publish-$(Get-Date -Format yyyyMMdd-HHmmss).log` o Bash `2>&1 | tee`. Alternativa permanente: `npm config set loglevel verbose`
+- **`package.json#files` debe incluir TODOS los directorios referenciados por `bin/`, `hooks/`, `scripts/` o `comandos/`**: si un binario hace `require('./gateway/foo')` pero `gateway/` no está listado en `files`, **el módulo se omite del tarball npm y el binario falla con MODULE_NOT_FOUND tras instalación pública** — aunque la suite local pase. Bug latente histórico: `/swl:cron`, `/swl:gateway` e `/swl:inbox` instruyen `require('./gateway/...')` y rompían en npm porque `gateway/` no estaba en `files` desde versiones previas. Revelado al agregar `bin/swl-webhook-server` (v1.4.0). Verificar antes de cada release: `npm pack --dry-run | grep -E "^npm notice [0-9].*[Bb] (bin|gateway|hooks|scripts|comandos)/"` debe listar todos los directorios reales referenciados. Gate automatizable en `scripts/verificar-release.js`. Origen: PR #15 sesión 2026-05-13
+- **Comandos `/swl:*` invocan vía CLI cross-scope, NUNCA rutas relativas al proyecto**: dentro de fenced code blocks de `comandos/swl/*.md` usar `swl-ses <sub>` (resolución: repo madre → bin en PATH → `npx -y @saulwade/swl-ses@latest <sub>`), no `node scripts/...` ni `require('./hooks/...')` — esas rutas rompen en instalación global/downstream (gates SDD G0/G1, telemetría, CI). Gate bloqueante en `scripts/validar.js §7b` (`auditar-invocaciones-comandos.js`); excluye SELF_DEV `{release, contribuir, evaluar-skill, reflect-skills}`. Wrappers en `scripts/cli/` se distribuyen SOLO vía npm (`package.json#files`), NO se cuentan en INVENTARIO ni en `modulos.json`; registro único en `bin/swl-ses.js`. Detalle: `@docs/invocacion-cli-cross-scope.md`. Origen: v2.2.0
+- **Componentes evolucionados: merge, no overwrite (invariante)**: el instalador NUNCA sobrescribe un componente con evolución del usuario (global o proyecto) — usa merge (preserve + `.evolved-diff.txt`). Distingue evolución de usuario (A) de shipped-evolved de fábrica (B) por hash del cuerpo canónico (`manifiestos/canonical-hashes.json`); el fuente NO porta marcadores `evolved` (gate inverso en `validar.js`). Detalle: ADR-0040. Origen: Fase 16
+
+## Referencias a docs clave (cargar bajo demanda con `@`)
+
+- `@README.md` — overview público y quickstart
+- `@MANUAL_USO.md` — manual operacional completo
+- `@INSTALACION.md` — instalación, perfiles, configuración
+- `@COMANDOS.md` — referencia detallada de cada `/swl:*`
+- `@AGENTS.md` — catálogo de agentes con capacidades
+- `@INVENTARIO.md` — conteos oficiales (regenerado por script)
+- `@docs/variables-entorno.md` — variables opt-in completas
+- `@docs/CI-CD-SETUP.md` — setup de pipelines
+- `@docs/evidencia-valor.md` — medición de valor en campo (`swl-ses valor`), frontera de datos downstream↔repo madre
+- `@.planning/adrs/README.md` — índice de decisiones arquitecturales
+
+---
+
+## Qué es este repositorio
+
+Sistema de ingeniería de software auto-evolutivo multi-runtime polyglot (SDLC completo).
+11 lenguajes, 7 runtimes (Claude, OpenClaude, OpenCode, Gemini, Cursor, Codex, Copilot), 61 agentes, 181 skills, 48 comandos, 77 reglas, 49 hooks.
+
+## Estructura del repositorio
+
+```
+agentes/       habilidades/    comandos/swl/   contextos/      instintos/
+reglas/        hooks/          schemas/        manifiestos/    plantillas/
+scripts/       bin/            _userland/      .claude/        .planning/
+```
+
+## Flujos de trabajo
+
+**Feature completa**: orquestador → discovery → PRD → arquitectura → plan → implementación (paralelo) → calidad (paralelo) → cierre
+**Fases GSD**: discutir → planear → ejecutar → verificar
+**Frontend**: investigador-ux → disenador-ui → accesibilidad → frontend-* → rendimiento
+**Backend**: backend-api → backend-python/node → backend-workers → datos
+**Mobile**: producto-prd → mobile-cross (decisión) → mobile-android/ios → tdd-qa
+
+## Comandos del sistema (/swl:*)
+
+Catálogo completo de 48 comandos `/swl:*` en `@COMANDOS.md`. Atajos mentales por categoría:
+
+- **Ciclo GSD por fase**: `discutir-fase` → `planear-fase` → `ejecutar-fase` → `verificar` (con discovery routing, modo iterativo `--iterative` y `--until-converge`).
+- **Anti-context-rot**: `checkpoint`, `compactar`.
+- **Aprendizaje**: `aprender`, `evolucionar`, `evolucion-continua` (motor determinista on|off|status, ADR-0041), `autoresearch`, `reflect-skills`.
+- **Calidad**: `revisar`, `verificar`, `nemesis` (auditoría Feynman + State, opcional `--remediar`), `deuda-codigo` (cosecha de marcadores `simplificado:`), `seguridad` (postura del proyecto completo), `fix` (triage y despacho de reparaciones), `predecir` (panel pre-implementación; `--abogado-diablo` critica la decisión).
+- **Diagnóstico**: `salud`, `metricas`, `dashboard`, `evolucion-estado`.
+- **Release**: `release`, `configurar-ci`.
+- **Conocimiento**: `wiki`, `mapear-codebase`, `skill-search`, `ayuda`.
+
+Para flags exactos y semántica de cada comando ver `@COMANDOS.md` y `@MANUAL_USO.md`.
+
+## Reglas obligatorias (37 base + 40 por lenguaje)
+
+Las reglas globales del usuario en `~/.claude/rules/` se cargan automáticamente
+y aplican a todos los proyectos. Las reglas del sistema en `reglas/` se cargan
+por matcher de archivos o vía `@reglas/<nombre>.md` desde el CLAUDE.md del
+proyecto. Reglas de mayor uso:
+
+| Regla | Carga cuando |
+|-------|-------------|
+| `brevedad-output.md` | Siempre — idioma español, eficiencia de tokens |
+| `seguridad.md` / `seguridad-agentes.md` | `*.py`, `*.ts`, `auth/`, agentes autónomos |
+| `arreglar-al-detectar.md` | Siempre — detectar → informar → arreglar en mismo turno |
+| `analisis-previo-tareas-grandes.md` | Solicitudes >10 archivos / >500 LOC / cross-módulo |
+| `usar-context7.md` | Al generar código que importe librerías externas |
+| `git-workflow.md` | Siempre |
+| `skills-estandar.md` / `fragmentos-compartidos.md` | Crear/auditar skills o fragmentos |
+| `registro-componentes-nuevos.md` | Crear cualquier componente nuevo (agente/skill/comando/hook/regla) — registro obligatorio en manifiestos + plugin.json + INVENTARIO en mismo commit |
+| `auditorias-documentales-estructurales.md` | Ejecutar verificadores docs/release/manifest — gates de profundidad y cobertura completa (no muestra). Aplica reglas anti-cosméticas a auditorías |
+
+Catálogo completo y matchers en `@INVENTARIO.md` sección Reglas.
+
+<!-- La regla de la sección "Uso obligatorio del sistema SWL" NO se importa con @: la copia global ya carga sola; el @import duplicaba ~250 líneas/sesión. Depurado Fase 09 (commit 7273c9e). -->
+
+## Estrategia de modelos (Model-Tier)
+
+Tiers por alias (se actualizan solos, NUNCA ID pineado en frontmatter): `fable` solo orquestador (coordinación central); `opus` decisiones irreversibles (arquitecto, revisor-seguridad, producto-prd, abogado-diablo); `sonnet` implementación y revisión; `haiku` operaciones deterministas; `inherit` sub-agentes del orquestador. NUNCA un tier superior para lo que el inferior resuelve igual. Detalle (alias vs API cruda, workflow de delegación, effort levels): `@docs/model-tier.md`.
+
+---
+
+## Convenciones operacionales
+
+Detalle completo en `@docs/convenciones-operacionales.md`. Resumen mínimo:
+
+- **Score mínimo de calidad**: **9.0/10** para aprobar trabajo.
+- **Modos de desarrollo**: `dev`, `review`, `research` (vía `/swl:contexto`).
+- **`respositorios-git/` y `temp/` son material de referencia** — no modificar ni commitear.
+- **Dependencias externas educativas son opt-in NO-dependencia** — el sistema funciona sin ellas.
+- **Patrón "validar antes de invocar"** para herramientas externas opt-in (markitdown, MinerU, gh).
+- **`skillsInvocables` requiere `Skill` en `tools:`** del agente.
+
+## Mapa de propagación de cambios
+
+Al modificar o agregar cualquier componente del sistema, **invocar
+`Skill("doc-sync")` antes del commit final** para cargar el protocolo
+proactivo completo. La tabla y checklist completos viven en
+`@docs/mapa-propagacion.md` para mantener este archivo bajo el umbral
+de 200 líneas (regla `auditar-claudemd.js`).
+
+Resumen mínimo para uso inmediato:
+
+- Cualquier componente nuevo o modificado (agente / skill / comando / hook / regla / schema / variable `SWL_*` / ADR / dependencia opt-in): consultar tabla completa en `@docs/mapa-propagacion.md` para saber qué archivos tocar.
+- **Skill responsable**: `Skill("doc-sync") § Protocolo proactivo` (sub-secciones Tipo 1 a Tipo 8) tiene el detalle prescriptivo.
+- **Antes de commit estructural**: regenerar inventario, validar manifiestos, verificar evolución (si tocó skill/agente), correr verificador docs-vs-código, suite completa, gate de release. Checklist exacto en `@docs/mapa-propagacion.md § Checklist único`.
+- Si cualquier gate falla, **NO commitear** hasta corregir. Regla `arreglar-al-detectar.md` exige resolver en mismo turno.