@saulwade/swl-ses 1.7.3 → 1.8.0

package/CLAUDE.md

@@ -1,196 +1,196 @@
-# CLAUDE.md — @saulwade/swl-ses v1.7.3
-
-## 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 y Jupyter
-Cuando necesites leer el **contenido** de un archivo `.docx`, `.xlsx`, `.xls`, `.pptx` o `.ipynb`, 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), `.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**: `docx ^9.6.1`, `pako ^2.1.0`, `readable-stream ^4.7.0` (mínimas; los hooks tienen zero-deps)
-- **Idioma de salida**: 100% español (México) para componentes SWL; skills oficiales de Anthropic en inglés
-
-## 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 (NUNCA contar a mano) |
-| `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:metricas fases`. |
-
-## Code style
-
-- **Nombres**: kebab-case para archivos, agentes SWL en español, GSD en inglés
-- **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
-- **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
-- **`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 múltiples clientes MCP viven como variables de entorno persistentes del SO, NO en archivos JSON** [v2 — 2026-05-18 supersede patrón anterior]: cuando un MCP server (ej. Obsidian) se usa simultáneamente desde **Cursor + Claude Code CLI + VS Code**, cada cliente tiene SU PROPIO config (`~/.cursor/mcp.json` vs `~/.claude/settings.json` vs `~/AppData/Roaming/Code/User/mcp.json`). Duplicar `OBSIDIAN_API_KEY` en N archivos JSON genera drift al regenerar la apiKey con Reset Crypto del plugin. Patrón correcto: `setx OBSIDIAN_API_KEY <key>` (CMD) o `[Environment]::SetEnvironmentVariable("OBSIDIAN_API_KEY","<key>","User")` (PowerShell 7) → escribe a `HKCU\Environment` → todos los clientes heredan al spawnear el binario. Los configs JSON OMITEN la clave `env` por completo (NO `env: {}` vacío — eso pasa literal a `child_process.spawn` y REEMPLAZA el env del padre, rompiendo la herencia). Regenerar apiKey = un solo `setx` + reiniciar Cursor, sin tocar JSONs. Origen: sesión 2026-05-18 tras 6h peleando con 40101 a través de 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
-- **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
-
-## 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
-- `@.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, 178 skills, 44 comandos, 71 reglas, 43 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 44 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`, `autoresearch`, `reflect-skills`.
-- **Calidad**: `revisar`, `verificar`, `nemesis` (auditoría Feynman + State, opcional `--remediar`).
-- **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 (25 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 |
-|-------|-------------|
-| `usar-sistema-swl.md` | Siempre — matriz operacional: tarea → componente SWL obligatorio |
-| `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.
-
-@reglas/usar-sistema-swl.md
-
-## Estrategia de modelos por nivel de criticidad (Model-Tier)
-
-Asignar el modelo correcto a cada agente según la criticidad e irreversibilidad de la tarea.
-
-| Nivel | Modelo | Campo en frontmatter | Agentes SWL | Criterio |
-|-------|--------|---------------------|-------------|----------|
-| **Crítico** | `claude-opus-4-7` | `model: claude-opus-4-7` | orquestador, arquitecto, revisor-seguridad, producto-prd | Decisiones irreversibles (arquitectura, seguridad, PRD) |
-| **Estándar** | `claude-sonnet-4-6` | `model: claude-sonnet-4-6` | backend-*, frontend-*, mobile-*, tdd-qa, revisores de lenguaje | Implementación y revisión |
-| **Ligero** | `claude-haiku-4-5-20251001` | `model: claude-haiku-4-5-20251001` | notificador, resolutor-build (búsquedas) | Operaciones deterministas rápidas |
-| **Heredado** | (del padre) | `model: inherit` | Sub-agentes invocados por el orquestador | El padre decide |
-
-**Reglas de asignación**: decisiones no reversibles → Opus; código → Sonnet; búsqueda/notificación → Haiku.
-NUNCA usar Opus para tareas que Sonnet resuelve igual de bien.
-
-**Workflow Opus 4.7**: tratar como ingeniero al que se delega (spec completa: intent + constraints + acceptance criteria + file locations). Sigue instrucciones literalmente — eliminar ambigüedad. Effort levels nativos: `high | xhigh | max`.
-
----
-
-## 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 v1.8.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 y Jupyter
+Cuando necesites leer el **contenido** de un archivo `.docx`, `.xlsx`, `.xls`, `.pptx` o `.ipynb`, 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), `.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**: `docx ^9.6.1`, `pako ^2.1.0`, `readable-stream ^4.7.0` (mínimas; los hooks tienen zero-deps)
+- **Idioma de salida**: 100% español (México) para componentes SWL; skills oficiales de Anthropic en inglés
+
+## 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 (NUNCA contar a mano) |
+| `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: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
+- **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
+- **`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 múltiples clientes MCP viven como variables de entorno persistentes del SO, NO en archivos JSON** [v2 — 2026-05-18 supersede patrón anterior]: cuando un MCP server (ej. Obsidian) se usa simultáneamente desde **Cursor + Claude Code CLI + VS Code**, cada cliente tiene SU PROPIO config (`~/.cursor/mcp.json` vs `~/.claude/settings.json` vs `~/AppData/Roaming/Code/User/mcp.json`). Duplicar `OBSIDIAN_API_KEY` en N archivos JSON genera drift al regenerar la apiKey con Reset Crypto del plugin. Patrón correcto: `setx OBSIDIAN_API_KEY <key>` (CMD) o `[Environment]::SetEnvironmentVariable("OBSIDIAN_API_KEY","<key>","User")` (PowerShell 7) → escribe a `HKCU\Environment` → todos los clientes heredan al spawnear el binario. Los configs JSON OMITEN la clave `env` por completo (NO `env: {}` vacío — eso pasa literal a `child_process.spawn` y REEMPLAZA el env del padre, rompiendo la herencia). Regenerar apiKey = un solo `setx` + reiniciar Cursor, sin tocar JSONs. Origen: sesión 2026-05-18 tras 6h peleando con 40101 a través de 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
+- **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
+
+## 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
+- `@.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, 178 skills, 44 comandos, 71 reglas, 44 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 44 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`, `autoresearch`, `reflect-skills`.
+- **Calidad**: `revisar`, `verificar`, `nemesis` (auditoría Feynman + State, opcional `--remediar`).
+- **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 (25 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 |
+|-------|-------------|
+| `usar-sistema-swl.md` | Siempre — matriz operacional: tarea → componente SWL obligatorio |
+| `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.
+
+@reglas/usar-sistema-swl.md
+
+## Estrategia de modelos por nivel de criticidad (Model-Tier)
+
+Asignar el modelo correcto a cada agente según la criticidad e irreversibilidad de la tarea.
+
+| Nivel | Modelo | Campo en frontmatter | Agentes SWL | Criterio |
+|-------|--------|---------------------|-------------|----------|
+| **Crítico** | `claude-opus-4-7` | `model: claude-opus-4-7` | orquestador, arquitecto, revisor-seguridad, producto-prd | Decisiones irreversibles (arquitectura, seguridad, PRD) |
+| **Estándar** | `claude-sonnet-4-6` | `model: claude-sonnet-4-6` | backend-*, frontend-*, mobile-*, tdd-qa, revisores de lenguaje | Implementación y revisión |
+| **Ligero** | `claude-haiku-4-5-20251001` | `model: claude-haiku-4-5-20251001` | notificador, resolutor-build (búsquedas) | Operaciones deterministas rápidas |
+| **Heredado** | (del padre) | `model: inherit` | Sub-agentes invocados por el orquestador | El padre decide |
+
+**Reglas de asignación**: decisiones no reversibles → Opus; código → Sonnet; búsqueda/notificación → Haiku.
+NUNCA usar Opus para tareas que Sonnet resuelve igual de bien.
+
+**Workflow Opus 4.7**: tratar como ingeniero al que se delega (spec completa: intent + constraints + acceptance criteria + file locations). Sigue instrucciones literalmente — eliminar ambigüedad. Effort levels nativos: `high | xhigh | max`.
+
+---
+
+## 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.