@saulwade/swl-ses 1.0.0

package/CLAUDE.md

@@ -0,0 +1,238 @@
+# CLAUDE.md — @saulwade/swl-ses v1.0.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")`.
+
+---
+
+## Qué es este repositorio
+
+Sistema de ingeniería de software auto-evolutivo multi-runtime polyglot (SDLC completo).
+11 lenguajes, 5 runtimes, 59 agentes, 151 skills, 42 comandos, 60 reglas, 37 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 (20 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 |
+| `patrones.md` | Patrones de diseño y arquitectura |
+| `testing.md` | test*/, *.test.*, *.spec.* |
+
+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).
+- **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.
+- **`skillsInvocables` en formato CSV estricto**: el campo `skillsInvocables` en frontmatter de agentes DEBE ser CSV puro en una sola línea (ej: `skillsInvocables: skill-a, skill-b, skill-c`). NUNCA mezclar formato lista YAML (`- item`) con CSV. 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.
+- **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: 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