@saulwade/swl-ses 1.4.2 → 1.5.1

package/CLAUDE.md

@@ -1,208 +1,209 @@
-# CLAUDE.md — @saulwade/swl-ses v1.4.2
-
-## Reglas de máxima prioridad (aplican SIEMPRE, sin excepción)
-
-### Idioma obligatorio: español de México
-Todo contenido generado DEBE ser en español de México: respuestas, código comentado, mensajes de commit, descripciones de PR, documentación y comunicación con el usuario. Usar ortografía correcta con acentos, signos de puntuación y gramática normativa. Evitar anglicismos innecesarios y traducciones literales del inglés. Esta regla tiene prioridad sobre cualquier otra instrucción de idioma.
-
-### Uso obligatorio del sistema SWL
-Toda tarea DEBE usar el sistema SWL completo: agentes especializados, habilidades, hooks y comandos `/swl:*`. NO hacer trabajo directo que un agente SWL especializado haría mejor. Para tareas complejas: `orquestador-swl`. Para implementación: `implementador-swl` o el agente de stack. Para debugging: `depurador-swl`. Para revisión: `revisor-codigo-swl`. Para planificación: `planificador-swl`. Cargar skills con `Skill("nombre")` antes de implementar.
-
-### Investigar antes de editar
-Investigar el codebase ANTES de editar. NUNCA modificar código que no se ha leído primero. Leer el archivo completo, entender el contexto, y solo entonces hacer cambios.
-
-### 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")`.
-
----
-
-## 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) |
-
-## 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 per-equipo van en `.claude/settings.local.json` (gitignored), no en `.claude/settings.json` (versionado)**: el archivo `settings.json` se sincroniza entre equipos vía git, así que NO puede contener valores per-máquina como apiKeys. Claude Code hace **deep merge** entre `settings.json` y `settings.local.json` — el local sobrescribe solo las keys que define. Patrón obligatorio para `OBSIDIAN_API_KEY` y similares: `settings.json` declara el server MCP con `env: {}` vacío; `settings.local.json` (cada equipo el suyo) tiene `mcpServers.obsidian.env.OBSIDIAN_API_KEY` con el valor del plugin Local REST API de ESE equipo. **NUNCA** poner dos `OBSIDIAN_API_KEY` en el mismo `env` — produce JSON inválido (síntoma: ConnectionRefused o 40101 silenciosos). Origen: PR #19 sesión 2026-05-13 (bug detectado al cambiar de WISC a WISCLAP)
-
-## 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)
-- `@CONTRIBUTING.md` — guía para colaboradores
-- `@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, 5 runtimes, 60 agentes, 158 skills, 44 comandos, 65 reglas, 41 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:*)
-
-Para la lista completa con descripción ver `@COMANDOS.md`. Comandos más usados:
-
-| Comando | Propósito |
-|---------|-----------|
-| `/swl:nuevo-proyecto` | Iniciar proyecto nuevo desde cero con entrevista |
-| `/swl:adoptar-proyecto` | Incorporar proyecto existente: análisis automático + entrevista corta |
-| `/swl:discutir-fase` / `/swl:planear-fase` / `/swl:ejecutar-fase` / `/swl:verificar` | Ciclo GSD por fase |
-| `/swl:checkpoint` / `/swl:compactar` | Anti-context-rot |
-| `/swl:claudemd` | Auditar/refactorizar/inicializar CLAUDE.md (audit, refactor, init-user, check) |
-| `/swl:aprender` / `/swl:evolucionar` / `/swl:autoresearch` | Aprendizaje y auto-evolución |
-| `/swl:salud` / `/swl:metricas` / `/swl:dashboard` | Diagnóstico y observabilidad |
-| `/swl:revisar` / `/swl:verificar` | Calidad de código (revisión por stack, verificación goal-backward). `/swl:verificar --full` activa parallel scorecard con 4 audits paralelos |
-| `/swl:nemesis` | Auditoría iterativa Feynman + State Inconsistency (loop hasta convergencia, ADR-0018). Flags: `--pass1`, `--pass2`, `--continue`, `--modulo <ruta>` |
-| `/swl:release` | Ciclo de release SemVer |
-| `/swl:configurar-ci` | Workflows CI/CD para proyectos del usuario |
-| `/swl:wiki` / `/swl:mapear-codebase` | Conocimiento de proyecto |
-| `/swl:ayuda` | Catálogo interactivo de comandos |
-
-## 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 |
-
-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
-
-- 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
-- Inventario completo: ver `@INVENTARIO.md` o `@.planning/ESTADO.md`
-- **Limpieza de registros resueltos**: no dejar items completados en listas de pendientes
-- **Dependencias externas educativas son opt-in NO-dependencia**: cuando se documenta un recurso externo (MCPs opcionales, plantillas comunitarias, indexadores externos) marcarlo explícitamente como **"NO es dependencia técnica de swl-ses"**. El sistema debe seguir funcionando sin ese recurso
-- **Patrón "validar antes de invocar"**: cualquier invocación a herramienta externa opt-in (markitdown, MinerU, gh, etc.) DEBE verificar primero (`command -v <bin>` / `try/catch execSync('<bin> --version')`) y, si no está disponible, **continuar con el flujo nativo de SWL sin emitir error al usuario**
-- **`skillsInvocables` requiere `Skill` en `tools:`**: si un agente declara `skillsInvocables: [...]` Y su cuerpo usa `Skill("nombre")`, debe incluir `Skill` en `tools:`. Verificar con `grep -c 'Skill(' agentes/X.md` >0
-- **Criterio gitignore para JSONL — runtime vs baseline**: runtime telemetry (alta frecuencia, recreable) → gitignore. Baseline auditable (histórico crítico, decisiones, evidencia gobernanza) → trackear. Pregunta filtro: *si borro este archivo, ¿se pierde info que el sistema necesita reconstruir desde otra fuente?* Sí → trackear
-
-## Mapa de propagación de cambios
-
-Al modificar un componente del sistema, verificar TODOS los archivos afectados.
-
-| Tipo de cambio | Archivos a verificar |
-|----------------|---------------------|
-| **Agente** | `plugin.json`, `manifiestos/modulos.json`, `INVENTARIO.md`, `AGENTS.md`, `SALUD.md`, `.planning/REPORTE-GRAFO.md` |
-| **Skill** | `plugin.json`, `manifiestos/modulos.json`, `INVENTARIO.md`, `CLAUDE.md` (si aplica al dominio) |
-| **Hook** | `plugin.json`, `.claude/settings.json`, `manifiestos/hooks-config.json` (event+matcher), `manifiestos/modulos.json` (ruta), `INVENTARIO.md`, `SALUD.md`. **AMBOS manifiestos son obligatorios** |
-| **Comando** | `COMANDOS.md`, `CLAUDE.md` (tabla de comandos), `INVENTARIO.md` |
-| **Regla** | `CLAUDE.md` (tabla de reglas), `INVENTARIO.md`, `SALUD.md` |
-| **Schema** | `INVENTARIO.md`, `SALUD.md` |
-| **Bump de versión** | 15+ ubicaciones — checklist en `/swl:release` paso 6 |
-| **CLAUDE.md (cualquier capa)** | Verificar con `/swl:claudemd audit` antes de commit |
-| **Cualquier `npm publish`** | Ejecutar `node scripts/verificar-release.js` ANTES, no solo en release formal. Detecta discrepancias de contadores y versiones invisibles al ojo humano (caso real v1.3.0: 18 discrepancias detectadas) |
-
-Esta tabla es obligatoria. Omitir un archivo causa fallos en `/swl:salud`.
-
-### Reglas auxiliares
-
-- **Regenerar inventario, nunca contar a mano**: antes de modificar contadores en CLAUDE.md/README.md/SALUD.md/AGENTS.md/package.json/plugin.json, ejecutar `node scripts/generar-inventario.js`. El script es la fuente de verdad
-- **Checklists consolidados se regeneran**: archivos en `docs/checklists-consolidados/` son derivados. Editar la regla origen y `npm run gen-checklists`. NO editar manualmente los generados
-- **Modelo por defecto headless**: scripts/bots externos invocan `claude -p --model claude-haiku-4-5-20251001 --effort low --max-budget-usd 0.50 --dangerously-skip-permissions`. Haiku 4.5 cuesta 5× menos
-- **File-based queue sobre PTY injection**: control remoto via `gateway/command-relay.js` → `.planning/inbox/cmd-*.json` → `/swl:inbox`. Tmux solo opt-in avanzado (`scripts/inbox-tmux-inject.js` Linux/macOS)
+# CLAUDE.md — @saulwade/swl-ses v1.5.1
+
+## Reglas de máxima prioridad (aplican SIEMPRE, sin excepción)
+
+### Idioma obligatorio: español de México
+Todo contenido generado DEBE ser en español de México: respuestas, código comentado, mensajes de commit, descripciones de PR, documentación y comunicación con el usuario. Usar ortografía correcta con acentos, signos de puntuación y gramática normativa. Evitar anglicismos innecesarios y traducciones literales del inglés. Esta regla tiene prioridad sobre cualquier otra instrucción de idioma.
+
+### Uso obligatorio del sistema SWL
+Toda tarea DEBE usar el sistema SWL completo: agentes especializados, habilidades, hooks y comandos `/swl:*`. NO hacer trabajo directo que un agente SWL especializado haría mejor. Para tareas complejas: `orquestador-swl`. Para implementación: `implementador-swl` o el agente de stack. Para debugging: `depurador-swl`. Para revisión: `revisor-codigo-swl`. Para planificación: `planificador-swl`. Cargar skills con `Skill("nombre")` antes de implementar.
+
+### Investigar antes de editar
+Investigar el codebase ANTES de editar. NUNCA modificar código que no se ha leído primero. Leer el archivo completo, entender el contexto, y solo entonces hacer cambios.
+
+### 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")`.
+
+---
+
+## 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 per-equipo van en `.claude/settings.local.json` (gitignored), no en `.claude/settings.json` (versionado)**: el archivo `settings.json` se sincroniza entre equipos vía git, así que NO puede contener valores per-máquina como apiKeys. Claude Code hace **deep merge** entre `settings.json` y `settings.local.json` — el local sobrescribe solo las keys que define. Patrón obligatorio para `OBSIDIAN_API_KEY` y similares: `settings.json` declara el server MCP con `env: {}` vacío; `settings.local.json` (cada equipo el suyo) tiene `mcpServers.obsidian.env.OBSIDIAN_API_KEY` con el valor del plugin Local REST API de ESE equipo. **NUNCA** poner dos `OBSIDIAN_API_KEY` en el mismo `env` — produce JSON inválido (síntoma: ConnectionRefused o 40101 silenciosos). Origen: PR #19 sesión 2026-05-13 (bug detectado al cambiar de WISC a WISCLAP)
+
+## 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)
+- `@CONTRIBUTING.md` — guía para colaboradores
+- `@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), 60 agentes, 160 skills, 44 comandos, 65 reglas, 41 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:*)
+
+Para la lista completa con descripción ver `@COMANDOS.md`. Comandos más usados:
+
+| Comando | Propósito |
+|---------|-----------|
+| `/swl:nuevo-proyecto` | Iniciar proyecto nuevo desde cero con entrevista |
+| `/swl:adoptar-proyecto` | Incorporar proyecto existente: análisis automático + entrevista corta |
+| `/swl:discutir-fase` / `/swl:planear-fase` / `/swl:ejecutar-fase` / `/swl:verificar` | Ciclo GSD por fase. `discutir-fase` empieza con discovery routing (5 paths: extender / sin-fase / nueva / decomposición / mixto). `ejecutar-fase --iterative` activa modo per-task con review adversarial. `verificar` clasifica claims (TASK/FIX/TEST_OR_BUILD/FEATURE_GO) para evidencia proporcional. |
+| `/swl:checkpoint` / `/swl:compactar` | Anti-context-rot |
+| `/swl:claudemd` | Auditar/refactorizar/inicializar CLAUDE.md (audit, refactor, init-user, check) |
+| `/swl:aprender` / `/swl:evolucionar` / `/swl:autoresearch` | Aprendizaje y auto-evolución |
+| `/swl:salud` / `/swl:metricas` / `/swl:dashboard` | Diagnóstico y observabilidad |
+| `/swl:revisar` / `/swl:verificar` | Calidad de código (revisión por stack, verificación goal-backward). `/swl:verificar --full` activa parallel scorecard con 4 audits paralelos |
+| `/swl:nemesis` | Auditoría iterativa Feynman + State Inconsistency (loop hasta convergencia, ADR-0018). Flags: `--pass1`, `--pass2`, `--continue`, `--modulo <ruta>` |
+| `/swl:release` | Ciclo de release SemVer |
+| `/swl:configurar-ci` | Workflows CI/CD para proyectos del usuario |
+| `/swl:wiki` / `/swl:mapear-codebase` | Conocimiento de proyecto |
+| `/swl:ayuda` | Catálogo interactivo de comandos |
+
+## 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 |
+
+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
+
+- 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
+- Inventario completo: ver `@INVENTARIO.md` o `@.planning/ESTADO.md`
+- **Limpieza de registros resueltos**: no dejar items completados en listas de pendientes
+- **Dependencias externas educativas son opt-in NO-dependencia**: cuando se documenta un recurso externo (MCPs opcionales, plantillas comunitarias, indexadores externos) marcarlo explícitamente como **"NO es dependencia técnica de swl-ses"**. El sistema debe seguir funcionando sin ese recurso
+- **Patrón "validar antes de invocar"**: cualquier invocación a herramienta externa opt-in (markitdown, MinerU, gh, etc.) DEBE verificar primero (`command -v <bin>` / `try/catch execSync('<bin> --version')`) y, si no está disponible, **continuar con el flujo nativo de SWL sin emitir error al usuario**
+- **`skillsInvocables` requiere `Skill` en `tools:`**: si un agente declara `skillsInvocables: [...]` Y su cuerpo usa `Skill("nombre")`, debe incluir `Skill` en `tools:`. Verificar con `grep -c 'Skill(' agentes/X.md` >0
+- **Criterio gitignore para JSONL — runtime vs baseline**: runtime telemetry (alta frecuencia, recreable) → gitignore. Baseline auditable (histórico crítico, decisiones, evidencia gobernanza) → trackear. Pregunta filtro: *si borro este archivo, ¿se pierde info que el sistema necesita reconstruir desde otra fuente?* Sí → trackear
+
+## Mapa de propagación de cambios
+
+Al modificar un componente del sistema, verificar TODOS los archivos afectados.
+
+| Tipo de cambio | Archivos a verificar |
+|----------------|---------------------|
+| **Agente** | `plugin.json`, `manifiestos/modulos.json`, `INVENTARIO.md`, `AGENTS.md`, `SALUD.md`, `.planning/REPORTE-GRAFO.md` |
+| **Skill** | `plugin.json`, `manifiestos/modulos.json`, `INVENTARIO.md`, `CLAUDE.md` (si aplica al dominio) |
+| **Hook** | `plugin.json`, `.claude/settings.json`, `manifiestos/hooks-config.json` (event+matcher), `manifiestos/modulos.json` (ruta), `INVENTARIO.md`, `SALUD.md`. **AMBOS manifiestos son obligatorios** |
+| **Comando** | `COMANDOS.md`, `CLAUDE.md` (tabla de comandos), `INVENTARIO.md` |
+| **Regla** | `CLAUDE.md` (tabla de reglas), `INVENTARIO.md`, `SALUD.md` |
+| **Schema** | `INVENTARIO.md`, `SALUD.md` |
+| **Bump de versión** | 15+ ubicaciones — checklist en `/swl:release` paso 6 |
+| **CLAUDE.md (cualquier capa)** | Verificar con `/swl:claudemd audit` antes de commit |
+| **Cualquier `npm publish`** | Ejecutar `node scripts/verificar-release.js` ANTES, no solo en release formal. Detecta discrepancias de contadores y versiones invisibles al ojo humano (caso real v1.3.0: 18 discrepancias detectadas) |
+
+Esta tabla es obligatoria. Omitir un archivo causa fallos en `/swl:salud`.
+
+### Reglas auxiliares
+
+- **Regenerar inventario, nunca contar a mano**: antes de modificar contadores en CLAUDE.md/README.md/SALUD.md/AGENTS.md/package.json/plugin.json, ejecutar `node scripts/generar-inventario.js`. El script es la fuente de verdad
+- **Checklists consolidados se regeneran**: archivos en `docs/checklists-consolidados/` son derivados. Editar la regla origen y `npm run gen-checklists`. NO editar manualmente los generados
+- **Modelo por defecto headless**: scripts/bots externos invocan `claude -p --model claude-haiku-4-5-20251001 --effort low --max-budget-usd 0.50 --dangerously-skip-permissions`. Haiku 4.5 cuesta 5× menos
+- **File-based queue sobre PTY injection**: control remoto via `gateway/command-relay.js` → `.planning/inbox/cmd-*.json` → `/swl:inbox`. Tmux solo opt-in avanzado (`scripts/inbox-tmux-inject.js` Linux/macOS)