@saulwade/swl-ses 1.2.2 → 1.3.0

package/CLAUDE.md

@@ -1,255 +1,196 @@
-# CLAUDE.md — @saulwade/swl-ses v1.2.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")`.
-
----
-
-## Qué es este repositorio
-
-Sistema de ingeniería de software auto-evolutivo multi-runtime polyglot (SDLC completo).
-11 lenguajes, 5 runtimes, 59 agentes, 153 skills, 42 comandos, 64 reglas, 40 hooks.
-**Idioma**: 100% español (México) para componentes SWL y skills Anthropic en inglés.
-
-## 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:*)
-
-| 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 → 9 archivos |
-| `/swl:discutir-fase` | Recopilar contexto antes de planificar |
-| `/swl:planear-fase` | Crear PLAN.md con vertical slices |
-| `/swl:ejecutar-fase` | Ejecutar plan con commits atómicos |
-| `/swl:verificar` | Verificar implementación contra spec |
-| `/swl:checkpoint` | Guardar estado para continuar después |
-| `/swl:compactar` | Reducir contexto preservando información clave |
-| `/swl:configurar-ci` | Instalar y gestionar workflows CI/CD de swl-ses en proyectos usuario (init/status/uninstall) |
-| `/swl:aprender` | Extraer aprendizajes de la sesión |
-| `/swl:evolucionar` | Auto-evolución de agentes/skills |
-| `/swl:autoresearch` | Loop de auto-mejora iterativa de skills |
-| `/swl:salud` | Diagnóstico de integridad del sistema |
-| `/swl:release` | Ciclo de release SemVer |
-| `/swl:revisar` | Revisión de código por tecnología |
-| `/swl:brainstorm` | Brainstorming estructurado |
-| `/swl:metricas` | Ver métricas de sesión (tokens, costo) |
-| `/swl:modelo` | Consultar/forzar modelo (haiku/sonnet/opus) |
-| `/swl:contexto` | Cambiar modo: dev/review/research |
-| `/swl:sesiones` | Historial y retoma de sesiones |
-| `/swl:instintos` | Gestionar instintos YAML |
-| `/swl:plugins` | Gestionar plugins de _userland/ |
-| `/swl:instalar` | Instalar SWL desde Claude Code |
-| `/swl:actualizar` | Actualizar SWL a última versión |
-| `/swl:auditar-deps` | Auditoría de dependencias (CVEs) |
-| `/swl:mapear-codebase` | Analizar codebase existente → ARQUITECTURA.md + STACK.md + TRAMPAS.md |
-| `/swl:crear-skill` | Crear nuevo skill con guía interactiva |
-| `/swl:gateway` | Configurar gateway multi-plataforma |
-| `/swl:cron` | Gestionar tareas programadas |
-| `/swl:revisar-impacto` | Análisis de impacto estructural con code-review-graph (blast radius, risk score, comunidades) |
-| `/swl:wiki` | Gestionar wiki de conocimiento del proyecto (init/ingest/query/lint) — patrón Karpathy |
-| `/swl:inbox` | Consumir comandos entrantes del gateway (Telegram/Discord/webhook) encolados por CommandRelay |
-| `/swl:reflect-skills` | Analizar historial JSONL para detectar intenciones repetidas candidatas a skill/comando emergente |
-| `/swl:evaluar-skill` | Evaluar calidad de un skill con PluginEval (2 capas, badge) |
-| `/swl:dashboard` | Dashboard interactivo del sistema |
-| `/swl:mcp-status` | Estado de servidores MCP conectados |
-| `/swl:notificaciones` | Gestionar notificaciones Telegram opt-in: init, status, disable, bot daemon |
-| `/swl:skill-search` | Buscar skills por keyword o dominio |
-| `/swl:contribuir` | Contribuir evoluciones de _userland/ al core vía PR (filtro dominio + PluginEval ≥80) |
-| `/swl:ayuda` | Ayuda interactiva: catálogo, detalle de comando, búsqueda por keyword |
-
-## Reglas obligatorias (24 base + 40 por lenguaje)
-
-| Regla | Carga cuando |
-|-------|-------------|
-| `brevedad-output.md` | Siempre — idioma español, uso obligatorio de SWL y eficiencia de tokens |
-| `seguridad.md` | *.py, *.ts, auth/, Dockerfile |
-| `estilo-codigo.md` | *.py, *.ts, *.js, *.css |
-| `pruebas.md` | *.py, *.ts, test*/, *.spec.* |
-| `arquitectura.md` | Cambios estructurales |
-| `git-workflow.md` | Siempre |
-| `performance.md` | *.py, *.ts, *.sql |
-| `docs.md` | *.md, docs/, README |
-| `accesibilidad.md` | *.html, *.tsx, *.component.* |
-| `cloud-infra.md` | *.tf, terraform/, k8s/, docker* |
-| `api-diseno.md` | api/, routes/, endpoints/ |
-| `skills-estandar.md` | habilidades/, skills/, SKILL.md |
-| `seguridad-agentes.md` | Agentes autónomos, MCP, delegación, permisos |
-| `gobernanza.md` | Proyectos con múltiples contribuidores |
-| `hooks.md` | hooks/, *.hook.js |
-| `markitdown.md` | Lectura de archivos Office/Jupyter |
-| `fragmentos-compartidos.md` | Crear o auditar bloques `agentes/_*.md` o `reglas/_fragmentos/_*.md` reutilizados por ≥3 agentes (tercer tier entre regla y skill, sin overhead runtime) |
-| `patrones.md` | Patrones de diseño y arquitectura |
-| `testing.md` | test*/, *.test.*, *.spec.* |
-| `usar-context7.md` | OBLIGATORIA al generar código que importe librerías/frameworks externos. Aplica a `backend-*-swl`, `frontend-*-swl`, `mobile-*-swl`, `implementador-swl`, `llm-apps-swl`, `pagos-swl`, `datos-swl`. Verifica versión actual y deprecaciones via Context7 MCP antes de agregar deps o generar imports. |
-| `arreglar-al-detectar.md` | Siempre — al detectar cualquier error, bug, inconsistencia o anomalía durante cualquier trabajo: informar y resolver en el mismo turno, sin deuda silenciosa ni bypass |
-| `analisis-previo-tareas-grandes.md` | Cuando la solicitud implica >10 archivos, >500 LOC, cross-módulo, porte de sistema o repo en `temp/`: auditar primero, presentar tabla comparativa + 3 opciones de alcance, esperar confirmación |
-
-Reglas por lenguaje (5 por lenguaje × 8 lenguajes): Java, Go, Rust, C#, Kotlin, Swift, PHP, Next.js — en `reglas/` con subdirectorios.
-
-## 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.
-Esta tabla es **obligatoria** al crear o actualizar agentes. El objetivo es reducir costos
-un 40–60% sin comprometer calidad en tareas que no lo requieren.
-
-| Nivel | Modelo | Campo en frontmatter | Agentes SWL | Criterio de asignación |
-|-------|--------|---------------------|-------------|------------------------|
-| **Crítico** | `claude-opus-4-7` | `model: claude-opus-4-7` | orquestador-swl, arquitecto-swl, revisor-seguridad-swl, producto-prd-swl | Decisiones irreversibles: arquitectura, seguridad, PRD. El error tiene alto costo de corrección |
-| **Estándar** | `claude-sonnet-4-6` | `model: claude-sonnet-4-6` | backend-*-swl, frontend-*-swl, mobile-*-swl, tdd-qa-swl, revisores de lenguaje | Implementación y revisión. Balance óptimo costo/calidad para la mayoría de tareas |
-| **Ligero** | `claude-haiku-4-5-20251001` | `model: claude-haiku-4-5-20251001` | notificador-swl, resolutor-build-swl (búsquedas simples) | Operaciones deterministas rápidas: notificaciones, búsquedas, formateo, transformaciones |
-| **Heredado** | (del padre) | `model: inherit` | Sub-agentes invocados por el orquestador | El agente padre decide el modelo según el contexto |
-
-### Reglas de asignación
-
-- Si la tarea toca **decisiones de diseño no reversibles** → Opus obligatorio
-- Si la tarea es **implementación o revisión de código** → Sonnet por defecto
-- Si la tarea es **búsqueda, formateo o notificación** → Haiku
-- Si un agente Sonnet necesita análisis crítico eventual → definir `modeloAlterno: claude-opus-4-7`
-- **NUNCA** usar Opus para tareas que Sonnet puede resolver igual de bien (búsquedas, lecturas, notificaciones)
-
-### Justificación
-
-Opus 4.7 supera a 4.6 en ~3× en resolución de tareas de producción de coding
-y 98.5% vs 54.5% en agudeza visual. Mismo precio por token que 4.6 ($5/$25 por M tokens).
-El tokenizer de 4.7 produce 1.0–1.35× más tokens para el mismo contenido, por lo que
-los umbrales de compactación y los presupuestos de contexto se han recalibrado en `compactacion-contexto` y `context-builder`.
-
-Opus 4.7 cuesta ~5× más que Sonnet por token. Usar Opus en tareas que no lo requieren
-desperdicia entre 300–500% de presupuesto sin mejora observable en el resultado final.
-
-### Workflow de delegación (Opus 4.7)
-
-Opus 4.7 rinde mejor tratado como **ingeniero al que se delega** que como pair programmer
-al que se guía línea por línea. Implicaciones para agentes SWL:
-
-- **Orquestadores y planificadores**: entregar spec completa al delegar (intent +
-  constraints + acceptance criteria + file locations). Evitar microgestión turn-by-turn.
-- **Sub-agentes en paralelo**: Opus 4.7 usa menos sub-agentes por defecto. Si una
-  tarea requiere paralelismo, especificarlo en el prompt de forma explícita.
-- **Instrucciones literales**: 4.7 sigue instrucciones con menos inferencia que 4.6.
-  Los prompts ambiguos se ejecutan al pie de la letra — eliminar ambigüedades.
-- **Effort levels nativos** (`high | xhigh | max`): el skill `control-profundidad`
-  queda deprecated en favor del control de esfuerzo nativo de Claude Code.
-
----
-
-## Convenciones
-
-- Nombres en **kebab-case**. Agentes SWL en español, GSD en inglés.
-- Skills se cargan vía `Skill("nombre")`, nunca leyendo AGENTS.md directamente.
-- 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 de agentes, skills, hooks y métricas: ver `INVENTARIO.md` o `.planning/ESTADO.md`.
-- Los mensajes de commit generados automáticamente siempre deben estar en español.
-- **Zero-dependencies en `hooks/lib/`**: sin dependencias npm externas.
-- **Escrituras atómicas obligatorias**: usar `atomicWriteSync()`/`atomicWriteJSON()` de `hooks/lib/atomic-write.js`.
-- **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.
-- **Limpieza de registros resueltos**: no dejar items completados en listas de pendientes.
-- **Directorios excluidos de verificación de console.log**: `scripts/`, `bin/`, `hooks/`, `gateway/`.
-- **Variables de entorno opt-in para integraciones enterprise**: hooks con exportación externa (OTLP, webhooks) usan el patrón `if (!process.env.VAR) return` — zero-config por defecto, activos solo cuando la variable está configurada. Nunca requerir configuración para funcionamiento básico. Variables opt-in conocidas: `SWL_GUARDRAIL_MODELO=1` (activa `hooks/guardrail-modelo.js` para observación de degradación de modelo), `SWL_AUDIT_SKILLS=1` (activa `scripts/audit-skills.sh` para auditoría de skills vía snyk-agent-scan), `SWL_AUDIT_FRAMEWORKS=1` (activa `scripts/auditar-cobertura-frameworks.js` en `/swl:salud` paso 5c para reportar cobertura de NIST CSF/AI RMF/MITRE ATLAS/ATT&CK/D3FEND), `SWL_AUDIT_AGENTES=1` (activa `scripts/auditar-agentes-gaps.js` en `/swl:salud` paso 5d para reportar gaps SAP-Agents en los 59 agentes), `SWL_MC_URL` (URL base de Mission Control, ej. `http://localhost:3000` — activa integración opt-in con el dashboard externo, ver `/swl:dashboard`), `SWL_MC_TOKEN` (API key de Mission Control cuando `SWL_MC_URL` está definida), `SWL_AIISMS_GATE=1` (activa gate en `scripts/verificar-release.js` que corre detector Python de AI-isms contra CHANGELOG.md y RELEASE_NOTES.md, bloquea el release si p0_count > 0), `SWL_AIISMS_HOOK=0` (desactiva `hooks/aiisms-detector.js` que se dispara en PostToolUse sobre Write/Edit/MultiEdit de archivos .md y emite nudge si hay AI-ism P0; activo por defecto cuando Python 3.10+ está disponible), `SWL_REPAIR_LOOP_THRESHOLD` (default `3`; umbral de nudges drift-detectado no accionados del mismo par `(metrica, agente)` en ventana de 14 días tras el cual `scripts/lib/drift-detector.js` marca el nudge como `banned: true` para prevenir saturación de `nudges.jsonl`; patrón adaptado de evolver GEP), `SWL_SUGERIR_REGEN_INVENTARIO=0` (silencia `hooks/sugerir-regenerar-inventario.js` que en PostToolUse Write/Edit/MultiEdit sugiere regenerar `INVENTARIO.md` cuando el agente toca `agentes/`, `habilidades/`, `comandos/swl/`, `hooks/` o `reglas/`; activo por defecto con cooldown de 30 min por carpeta), `SWL_FUZZY_CLASIFICADOR=1` (activa fuzzy matching en `hooks/clasificador-mensajes.js` como segunda pasada cuando regex no detecta señales — útil para typos y variantes morfológicas, ej: `docmentacion` → señal DOCUMENTACIÓN; usa `hooks/lib/text-similarity.js` con Levenshtein adaptativo + stem ES; nunca degrada el comportamiento default; costo ~5-15ms por prompt), `SWL_CTX_WARNING` (default `40`; porcentaje de uso de contexto a partir del cual `hooks/monitor-contexto.js` emite WARNING; calibrado con evidencia del issue Anthropic #34685 que documenta degradación detectable ~20-40%; subir a 50-60 si los avisos resultan ruidosos), `SWL_CTX_CRITICAL` (default `55`; porcentaje de uso a partir del cual emite CRITICAL y dispara compresión Fase 1; sweet spot 40-50% según el issue #34685, dejamos margen al 55), `SWL_CTX_PROACTIVA` (default `35`; porcentaje a partir del cual sugiere compactación proactiva en puntos naturales — git commit, tests OK, fin de subagente), `SWL_VALIDAR_MEMORIA=0` (desactiva `hooks/validar-memoria-hook.js` que en PostToolUse Write/Edit/MultiEdit sobre `APRENDIZAJES.md`, `instintos/proyecto.yaml`, `instintos/global.yaml` o `instintos/perfil-usuario.yaml` ejecuta `scripts/validar-memoria.js` para detectar fugas de secretos/PII y duplicación cross-canal; activo por defecto), `SWL_FORMATO_VALIDACION=0` (desactiva `hooks/validar-formato-post-subagente.js` que en SubagentStop valida output del subagente contra `manifiestos/agent-output-schemas.json` para los agentes con schema declarado y registra violaciones en `.planning/evolucion/formato-violaciones.jsonl`; activo por defecto).
-- **Criterio de dominio para incorporar skills de proyectos usuario**: una habilidad generada en un proyecto swl-ses solo se incorpora al core si su dominio es **ingeniería de software general** (SDLC, backend, frontend, QA, DevOps, seguridad). Skills de dominios externos (ML Ops, Data Science, finanzas, bio-informática, etc.) se descartan aunque estén bien escritas. Pregunta de filtro: *¿le sirve esto a un ingeniero de software en cualquier proyecto de software?*
-- **Filtro primario al analizar repos en `temp/`**: antes de evaluar arquitectura o patrones, verificar **compatibilidad de dominio** con ingeniería de software general. Si el dominio es incompatible (ML productivo, ciencia de datos, dominio vertical específico), veredicto NINGUNA aplicabilidad sin análisis adicional.
-- **JSONL para eventos de alta frecuencia**: usar `fs.appendFileSync(ruta, JSON.stringify(evento) + '\n')` en hooks de telemetría/auditoría — no `atomicWriteJSON` que reescribe el archivo completo. Reservar `atomicWriteJSON` para archivos de estado mutable.
-- **Criterio gitignore para JSONL — runtime vs baseline**: los archivos JSONL del sistema se clasifican en dos categorías con destino opuesto en `.gitignore`. **Runtime telemetry** (alta frecuencia, recreable, consumo agregado por scripts de métricas): NO se trackea, va a `.gitignore` con comentario explicando origen y consumo. Ejemplos: `.planning/evolucion/memory-usage.jsonl`, `.planning/evolucion/formato-violaciones.jsonl`, `.planning/evolucion/nudges.jsonl`. **Baseline auditable** (histórico crítico, decisiones registradas, evidencia de gobernanza): SÍ se trackea como ground truth. Ejemplos: `.planning/evolucion/evoluciones.jsonl`, `.planning/evolucion/alertas-persistentes.json`, `.planning/audit.jsonl`, `politica-evolvable.md`. Pregunta de filtro: *si borro este archivo, ¿se pierde información que el sistema necesita reconstruir desde otra fuente?* Si sí → trackear. Si se reconstruye en próximas N sesiones → gitignore.
-- **`skillsInvocables` requiere `Skill` en `tools:`**: si un agente declara `skillsInvocables: [...]` Y su cuerpo usa `Skill("nombre")` para invocarlas dinámicamente, debe incluir `Skill` en su array `tools:`. Si solo lista skills como metadata/recomendación (sin invocación dinámica en el cuerpo), `Skill` en tools es opcional. La verificación: `grep -c 'Skill(' agentes/X.md` — si el conteo es >0, el agente NECESITA `Skill` en tools. Auditado en v1.1.1: 4 agentes (investigador, perfilador-usuario, planificador, red-team) tenían el bug y fueron corregidos.
-- **`skillsInvocables`, `skillsRestringidos` y `tools` como array YAML inline**: estos tres campos en frontmatter de agentes DEBEN ser array YAML inline (ej: `tools: [Read, Write, Edit]`, `skillsInvocables: [skill-a, skill-b]`). NUNCA usar formato CSV string (causa parser ambiguity y bugs históricos documentados). NUNCA mezclar array inline con lista YAML multilínea (`- item`). Cada valor debe ser un nombre de skill existente en `habilidades/` — nunca nombres de agentes ni skills inexistentes. Verificar con `ls habilidades/ | grep nombre` antes de agregar. Migración masiva ejecutada en v1.1.0 vía `scripts/migrar-csv-a-array.js` (idempotente).
-- **Precedencia de capas del sistema**: Reglas base (`reglas/`) → Reglas por lenguaje (`reglas/{lang}/`) → Skills (`habilidades/`) → Instintos (`instintos/`). Cada capa puede especializar pero NUNCA contradecir las capas superiores. Si hay conflicto, la capa más general (regla base) prevalece. Los instintos solo aplican dentro de su scope (proyecto/dominio/global) y nunca sobreescriben reglas ni skills.
-- **Privilegio mínimo de agentes**: un agente delegado NUNCA excede los permisos declarados en su propio frontmatter (`permisosRed`, `permisosEscritura`, `permisosComandos`, `tools`). La cadena de delegación no escala privilegios: si el agente padre tiene `nivelRiesgo: ALTO` y delega a un agente `BAJO`, el hijo opera con sus restricciones propias. Ver `reglas/seguridad-agentes.md`.
-- **Dependencias externas educativas se marcan como opt-in NO-dependencia**: cuando se documenta un recurso externo de tipo educativo/formativo (guías, MCPs de documentación, plantillas comunitarias como `cc.bruniaux.com`, indexadores externos como GitNexus) en MANUAL_USO.md sección Dependencias externas, marcar explícitamente **"NO es dependencia técnica de swl-ses"** y advertir si sus componentes (slash commands, agentes, hooks) no están coordinados con los del sistema SWL. El sistema debe seguir funcionando sin ese recurso — si un recurso se vuelve necesario para un flujo, deja de ser educativo y requiere ADR. Aplica también a MCPs opcionales, librerías opt-in y herramientas de terceros referenciadas en docs.
-- **Patrón obligatorio "validar antes de invocar" para dependencias externas opt-in**: cualquier invocación desde un comando, skill o hook de swl-ses a una herramienta externa opt-in (markitdown, MinerU, gh, gitnexus, mineru-open-api, etc.) **DEBE** verificar primero si está disponible (`command -v <bin>` en Bash, `execSync('<bin> --version', { stdio: 'ignore' })` en Node) y, si no lo está, **continuar con el flujo nativo de SWL sin emitir error al usuario**. Una falla en la dependencia externa nunca debe romper el flujo principal. Para verificación silenciosa, usar `2>/dev/null` o `try/catch`. Este patrón aplica a todos los wrappers en `scripts/vendor/` y a cualquier invocación cross-tool en hooks. Sin este check, el sistema deja de cumplir con su contrato "opt-in NO-dependencia".
-- **Siempre usar `@latest` en invocaciones `npx`**: todo mensaje impreso por installer, hook de check-update, scripts de inicialización y documentación que sugiera ejecutar el CLI debe usar `npx swl-ses@latest <comando>`, nunca `npx swl-ses <comando>` desnudo. Sin `@latest`, npx cachea la primera versión encontrada por máquina y la reutiliza indefinidamente; tras publicar una nueva versión, los usuarios existentes siguen corriendo la vieja sin saberlo. Regla cubre: `scripts/instalador.js`, `hooks/check-update.js`, `scripts/check-update.js`, `scripts/inicializar.js`, README, MANUAL_USO, COMANDOS, INSTALACION.
-
-## Mapa de propagación de cambios
-
-Al modificar un componente del sistema, verificar TODOS los archivos afectados. Un cambio incompleto causa desincronización.
-
-| Tipo de cambio | Archivos a verificar |
-|----------------|---------------------|
-| **Agente nuevo o modificado** | `plugin.json`, `manifiestos/modulos.json`, `INVENTARIO.md`, `AGENTS.md`, `SALUD.md`, `.planning/REPORTE-GRAFO.md` |
-| **Skill nuevo o modificado** | `plugin.json`, `manifiestos/modulos.json`, `INVENTARIO.md`, `CLAUDE.md` (tabla de skills por dominio) |
-| **Hook nuevo o modificado** | `plugin.json`, `.claude/settings.json`, `manifiestos/hooks-config.json` (event+matcher), `manifiestos/modulos.json` (ruta archivo), `INVENTARIO.md`, `SALUD.md`. **AMBOS manifiestos son obligatorios**: sin `hooks-config.json` el hook no se registra en settings.json del destino, sin `modulos.json` el instalador no lo copia. `scripts/validar-manifest.js` bloquea el CI si falta cualquiera. |
-| **Comando nuevo o modificado** | `COMANDOS.md`, `CLAUDE.md` (tabla de comandos), `INVENTARIO.md` |
-| **Regla nueva o modificada** | `CLAUDE.md` (tabla de reglas), `INVENTARIO.md`, `SALUD.md` |
-| **Schema nuevo o modificado** | `INVENTARIO.md`, `SALUD.md` |
-| **Bump de versión** | 15+ ubicaciones en 14 archivos — ver checklist en `/swl:release` paso 6 |
-| **Frontmatter de agente (`skillsInvocables`)** | `manifiestos/modulos.json`, `.planning/REPORTE-GRAFO.md` (re-generar grafo) |
-
-Esta tabla es obligatoria. Omitir un archivo causa fallos en `/swl:salud` y desincronización del grafo de dependencias.
-
-### Regla obligatoria: regenerar inventario, nunca contar a mano
-
-Antes de modificar contadores de agentes, skills, comandos, reglas o hooks en CLAUDE.md, README.md, SALUD.md, AGENTS.md, package.json o plugin.json, ejecutar SIEMPRE:
-
-```bash
-node scripts/generar-inventario.js
-```
-
-Motivo: Estimé "28 hooks" visualmente y propagué el error a 5 archivos; el conteo real (regenerado) era 30. Contar manualmente no es fuente de verdad — el script que recorre los directorios sí lo es. Aplica a cualquier proyecto SWL, no solo al sistema.
-
-### Regla: checklists consolidados se regeneran, no se editan a mano
-
-Los archivos en `docs/checklists-consolidados/` son derivados de las secciones `## Checklist` de las reglas en `reglas/`. Para modificar el contenido, editar la regla origen y ejecutar:
-
-```bash
-npm run gen-checklists           # regenera todos los archivos
-npm run gen-checklists:check     # falla si hay drift (uso CI)
-```
-
-NO editar manualmente los archivos generados. Cada uno lleva header `<!-- GENERADO desde reglas/X.md -->`. Origen: opción B del análisis de repos externos (2026-05-09) — patrón "fuente única, presentación múltiple" sin duplicar contenido.
-
-### Regla: modelo por defecto para auto-ejecución headless
-
-Cuando un script o bot externo invoca `claude -p` sin intervención humana, usar por defecto:
-
-```bash
-claude -p \
-  --model claude-haiku-4-5-20251001 \
-  --effort low \
-  --max-budget-usd 0.50 \
-  --dangerously-skip-permissions \
-  --allowedTools "Read Grep Glob Bash(git status:*) ..." \
-  "<mensaje>"
-```
-
-Haiku 4.5 cuesta 5× menos que Sonnet/Opus y cubre consultas headless típicas (status, log, lecturas, resúmenes). El primer invoke por cwd cuesta ~$0.15 por cache warmup del CLAUDE.md + reglas; invocaciones subsiguientes dentro de 5min son $0.001-0.05. Con Opus el warmup sube a ~$0.90 por invocación — reservar Opus solo para auto-exec que requiera razonamiento profundo.
-
-### Decisión de arquitectura: file-based queue sobre PTY injection
-
-Para control remoto de Claude desde canales externos (Telegram, Discord), el patrón adoptado es **file-based inbox** (`gateway/command-relay.js` escribe a `.planning/inbox/cmd-*.json`, consumidor `/swl:inbox` o `claude -p` headless) en lugar de PTY injection (AppleScript macOS / tmux send-keys Linux). Razones:
-
-- Portable Windows/Linux/macOS con un solo mecanismo
-- Auditable por archivo con audit trail en `.planning/inbox/audit.jsonl`
-- Compatible con HITL (humano decide si ejecutar), ortogonal a la validación del CommandRelay
-- Tmux queda como modo opt-in avanzado vía `scripts/inbox-tmux-inject.js` solo Linux/macOS
+# CLAUDE.md — @saulwade/swl-ses v1.3.0
+
+## 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)
+- **`@latest` en npx**: todo mensaje del installer/docs usa `npx swl-ses@latest <comando>`. Sin `@latest`, npx cachea la primera versión y el usuario corre vieja sin saberlo
+
+## 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
+
+## 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, 59 agentes, 155 skills, 43 comandos, 64 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: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 (24 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. Reglas de mayor uso:
+
+| Regla | Carga cuando |
+|-------|-------------|
+| `brevedad-output.md` | Siempre — idioma español, uso obligatorio de SWL, 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.
+
+## 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 |
+
+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)

package/README.md

@@ -1,4 +1,4 @@
-# swl-ses v1.2.0
+# swl-ses v1.3.0
 
 > El paquete anterior `@saulwadeleon/swl-software-engineering-system` está deprecado. Migrar a `@saulwade/swl-ses` (npmjs.org canónico) o `@saul-wade/swl-ses` (mirror en GitHub Packages) — el CLI `swl-ses` no cambia.
 
@@ -177,7 +177,7 @@ claude
 | `mobile` | Android + iOS + React Native/Flutter + UX |
 | `devops` | CI/CD + cloud + observabilidad + releases + seguridad |
 | `polyglot` | Todos los lenguajes: 11 lenguajes + revisores + build resolvers |
-| `completo` | Todo: 59 agentes + 153 habilidades + 42 comandos + 64 reglas + 40 hooks |
+| `completo` | Todo: 59 agentes + 155 habilidades + 43 comandos + 64 reglas + 41 hooks |
 
 ### Targets soportados
 
@@ -478,8 +478,8 @@ swl-ses/
       seguridad.js          # Validaciones de seguridad
   manifiestos/              # Perfiles y módulos de instalación
   agentes/                  # 59 agentes especializados
-  habilidades/              # 153 habilidades modulares
-  comandos/swl/             # 42 comandos slash
+  habilidades/              # 155 habilidades modulares
+  comandos/swl/             # 43 comandos slash
   reglas/                   # 20 reglas base + 40 por lenguaje
   hooks/                    # 39 hooks + 62 librerías en hooks/lib/
   schemas/                  # 14 JSON Schemas