# CLAUDE.md — @saulwade/swl-ses v1.7.3

## Reglas de máxima prioridad (aplican SIEMPRE, sin excepción)

### Idioma y estilo de output
Aplican las reglas globales `@~/.claude/rules/brevedad-output.md` (español de México, brevedad, sin AI-isms) y `@~/.claude/rules/git-coauthor.md` (sin co-autores en commits) — cargadas automáticamente en cada sesión. NO duplicar su contenido inline en este archivo (regla `@reglas/sin-duplicacion-reglas-globales.md`).

### Uso obligatorio del sistema SWL
Aplica la regla global `@~/.claude/rules/usar-sistema-swl.md` — matriz operacional completa (qué agente/skill/comando usar por tipo de tarea, excepciones legítimas, anti-patrones). Cargar skills con `Skill("nombre")` antes de implementar.

### Cuatro principios de implementación (Karpathy)
Antes de implementar, refactorizar o corregir bugs: (1) **pensar antes de codificar** (no asumir en silencio), (2) **simplicidad primero** (sin abstracciones especulativas), (3) **cambios quirúrgicos** (leer archivo completo antes de editar, no refactor de oportunidad), (4) **ejecución orientada a metas** (criterios verificables, test que reproduce bugs antes del fix). Tabla operativa + mapeo a agentes SWL en `@docs/karpathy-principios.md`. Detalle + 9 ejemplos MAL→BIEN: `Skill("prevencion-sobreingenieria")` + `recursos/EXAMPLES.md`.

### Lectura de documentos Office y Jupyter
Cuando necesites leer el **contenido** de un archivo `.docx`, `.xlsx`, `.xls`, `.pptx` o `.ipynb`, NUNCA uses el Read tool directamente (no soporta esos formatos). Usa:
```bash
python scripts/vendor/markitdown/cli.py <ruta-al-archivo>
```
El Read tool sigue siendo correcto para `.pdf` (≤20 páginas), `.md`, `.txt` y código fuente. Para más opciones y casos de uso consultar `Skill("swl-markitdown")`.

### Versión SemVer del próximo release: decisión exclusiva del usuario
NUNCA asumir, sugerir como hecho consumado, ni escribir en ADRs/manifiestos/CHANGELOG el número del próximo release sin autorización explícita del usuario en la conversación actual. El agente puede **recomendar** el bump apropiado según SemVer estricto, pero la **decisión final del número es del usuario**. Detalle y origen del aprendizaje en `.planning/APRENDIZAJES.md` sesión 2026-05-16 (ADR-0021).

---

## Stack del proyecto

- **Runtime**: Node.js >=22.0.0 (ESM + CommonJS)
- **Tipo**: Sistema de scripts CLI + plugin para Claude Code (multi-runtime: Claude / Copilot / OpenCode / Codex / Gemini)
- **Formato fuente**: Markdown (agentes, skills, comandos, reglas) + JSON Schema (validación) + YAML (instintos)
- **Distribución**: npm package (`@saulwade/swl-ses`) + plugin Claude Code (`plugin.json`)
- **Dependencias runtime**: `docx ^9.6.1`, `pako ^2.1.0`, `readable-stream ^4.7.0` (mínimas; los hooks tienen zero-deps)
- **Idioma de salida**: 100% español (México) para componentes SWL; skills oficiales de Anthropic en inglés

## Comandos del proyecto

| Comando | Propósito |
|---|---|
| `npm test` | Tests unitarios (lib/, scripts/, hooks/) |
| `npm run test:all` | test + validar.js + validar-manifest.js |
| `npm run test:release` | test:all + test:userland + smoke (gate pre-publish) |
| `npm run test:validate` | `node scripts/validar.js` — validación estructural completa |
| `npm run test:manifest` | `node scripts/validar-manifest.js` — coherencia modulos/hooks |
| `npm run test:smoke` | Smoke test del instalador |
| `npm run gen-checklists` | Regenera `docs/checklists-consolidados/` desde reglas |
| `npm run gen-checklists:check` | Falla si hay drift (uso CI) |
| `npm run generate:docs` | Regenera `INVENTARIO.md` desde directorios |
| `npm run doctor` | Diagnóstico del sistema (`scripts/doctor.js`) |
| `npm run publish:dry` | Dry-run de publicación a npm + GitHub |
| `node scripts/verificar-release.js` | Gate pre-release: 15+ ubicaciones de versión, sincronización, AI-isms (si `SWL_AIISMS_GATE=1`) |
| `node scripts/generar-inventario.js` | Regenera contadores oficiales (NUNCA contar a mano) |
| `node scripts/derivar-feature-list.js` | Genera `.planning/feature-list.json` (derivado de `HOJA-RUTA.md`, gitignored, regenerable). Modo `--check` exit 2 si drift detectado. Consumido por `/swl:metricas fases`. |

## Code style

- **Nombres**: kebab-case para archivos, agentes SWL en español, GSD en inglés
- **Zero-dependencies en `hooks/lib/`**: sin dependencias npm externas
- **Escrituras atómicas obligatorias**: usar `atomicWriteSync()` / `atomicWriteJSON()` de `hooks/lib/atomic-write.js`. NUNCA `fs.writeFileSync` directo en archivos del sistema
- **JSONL para alta frecuencia**: usar `fs.appendFileSync(ruta, JSON.stringify(evento) + '\n')` en hooks de telemetría/auditoría — no `atomicWriteJSON` que reescribe todo
- **YAML inline en frontmatter**: `tools: [Read, Write]`, `skillsInvocables: [skill-a]`. NUNCA CSV string ni mezcla con lista multilínea
- **Mensajes de commit**: imperativo en español, formato `<tipo>(<scope>): <descripción>`
- **Sin `console.log` en producción** — excepto en `scripts/`, `bin/`, `hooks/`, `gateway/` (CLIs y daemons)
- **Nombre completo del paquete en npx**: todo mensaje del installer/docs usa `npx -y @saulwade/swl-ses@latest <comando>`. **NUNCA** `npx swl-ses@latest <comando>` sin el scope `@saulwade/` — eso resuelve al paquete legacy DEPRECATED (v5.13.1) que aún existe en npm tras el rebrand de 2026-04-30. El `@latest` es indispensable: sin él npx reutiliza la primera versión cacheada y el usuario corre código viejo sin saberlo. El `-y` evita la prompt de confirmación en CI/scripts
- **Fixtures `secret`/`token` en tests deben ser en español** (`secreto`, `tokenBearer`, `clave-test`). El hook `calidad-pre-commit.js` matchea `\bsecret\s*[=:]\s*["'][^"'\s]{4,}["']` y `\btoken\s*[=:]\s*["'][^"'\s]{8,}["']` — `const secret = "valor"` se bloquea como credencial hardcodeada aunque sea fixture legítimo. Renombrar a español elude el regex sin bypass (alternativas reconocidas por el hook: `placeholder`, `example`, `fake_`, `dummy_`, `os.environ`/`process.env`). Coherente con regla global de idioma. Origen: PR #11 sesión 2026-05-13
- **`git add archivo && git commit -m "..."` en un solo comando bash NO actualiza el index antes del PreToolUse hook**: el hook `calidad-pre-commit.js` evalúa el contenido staged previo al `&&`, no el actualizado en la misma línea. Síntoma: commit bloqueado por contenido que ya corregiste vía Write/Edit pero seguía staged en versión antigua. Fix: separar en dos calls Bash (`git add archivo` → ver resultado → `git commit -m "..."`). NUNCA usar `--no-verify` para bypassear. Origen: PR #11 sesión 2026-05-13
- **Secretos compartidos entre múltiples clientes MCP viven como variables de entorno persistentes del SO, NO en archivos JSON** [v2 — 2026-05-18 supersede patrón anterior]: cuando un MCP server (ej. Obsidian) se usa simultáneamente desde **Cursor + Claude Code CLI + VS Code**, cada cliente tiene SU PROPIO config (`~/.cursor/mcp.json` vs `~/.claude/settings.json` vs `~/AppData/Roaming/Code/User/mcp.json`). Duplicar `OBSIDIAN_API_KEY` en N archivos JSON genera drift al regenerar la apiKey con Reset Crypto del plugin. Patrón correcto: `setx OBSIDIAN_API_KEY <key>` (CMD) o `[Environment]::SetEnvironmentVariable("OBSIDIAN_API_KEY","<key>","User")` (PowerShell 7) → escribe a `HKCU\Environment` → todos los clientes heredan al spawnear el binario. Los configs JSON OMITEN la clave `env` por completo (NO `env: {}` vacío — eso pasa literal a `child_process.spawn` y REEMPLAZA el env del padre, rompiendo la herencia). Regenerar apiKey = un solo `setx` + reiniciar Cursor, sin tocar JSONs. Origen: sesión 2026-05-18 tras 6h peleando con 40101 a través de 3 configs descoordinados.

## Convenciones de arquitectura

- **Precedencia de capas**: Reglas base (`reglas/`) → Reglas por lenguaje (`reglas/{lang}/`) → Skills (`habilidades/`) → Instintos (`instintos/`). Cada capa puede especializar pero NUNCA contradecir las superiores
- **Privilegio mínimo de agentes**: un agente delegado NUNCA excede los permisos declarados en su propio frontmatter. La cadena de delegación no escala privilegios. Ver `@reglas/seguridad-agentes.md`
- **Preservación de datos en actualización**: `.planning/sessions/`, `.planning/comms/`, `_userland/`, `instintos/proyecto.yaml`, `APRENDIZAJES.md` NUNCA se sobreescriben
- **Documentación obligatoria**: toda funcionalidad nueva DEBE documentarse en `MANUAL_USO.md`, `COMANDOS.md`, `CLAUDE.md` y `README.md` ANTES del commit
- **Criterio dominio para incorporar skills externos**: solo si dominio = ingeniería de software general. Pregunta de filtro: *¿le sirve esto a un ingeniero de software en cualquier proyecto de software?* (ML Ops, Data Science, finanzas, etc. → descartar)
- **Filtro primario al analizar `temp/`**: antes de evaluar arquitectura, verificar **compatibilidad de dominio**. Si es incompatible, veredicto NINGUNA aplicabilidad sin análisis adicional
- **Variables de entorno opt-in enterprise**: ver `@docs/variables-entorno.md` (catálogo completo). Patrón obligatorio: `if (!process.env.VAR) return` — zero-config por defecto
- **Hooks SWL que invocan auditores Node deben cargar el auditor como módulo (`require()`), no como subproceso**: ~10× más rápido, errores estructurados (no parsing de stdout), tests directos del módulo. Excepción legítima: cuando el auditor es Python o Bash (`spawnSync`). Ejemplo aplicado en `hooks/claudemd-bloat-detector.js` que usa `require('./scripts/auditar-claudemd.js')` directamente. Antipatrón evitado: `spawnSync('node', [auditorPath, ...])` agrega ~50ms por invocación y obliga a parsear JSON de stdout
- **npm v10+ NO escribe debug logs cuando falla un script invocado** (`prepublishOnly`, `prepack`, etc.) — solo cuando falla npm-mismo (network, registry, auth). El default `loglevel=notice` mantiene `_logs/` vacío para errores de scripts. Para diagnóstico de `npm run publish:all` que falla en script propio, capturar stdout+stderr con redirección: PowerShell `npm run publish:all *>&1 | Tee-Object .planning/logs/publish-$(Get-Date -Format yyyyMMdd-HHmmss).log` o Bash `2>&1 | tee`. Alternativa permanente: `npm config set loglevel verbose`
- **`package.json#files` debe incluir TODOS los directorios referenciados por `bin/`, `hooks/`, `scripts/` o `comandos/`**: si un binario hace `require('./gateway/foo')` pero `gateway/` no está listado en `files`, **el módulo se omite del tarball npm y el binario falla con MODULE_NOT_FOUND tras instalación pública** — aunque la suite local pase. Bug latente histórico: `/swl:cron`, `/swl:gateway` e `/swl:inbox` instruyen `require('./gateway/...')` y rompían en npm porque `gateway/` no estaba en `files` desde versiones previas. Revelado al agregar `bin/swl-webhook-server` (v1.4.0). Verificar antes de cada release: `npm pack --dry-run | grep -E "^npm notice [0-9].*[Bb] (bin|gateway|hooks|scripts|comandos)/"` debe listar todos los directorios reales referenciados. Gate automatizable en `scripts/verificar-release.js`. Origen: PR #15 sesión 2026-05-13

## Referencias a docs clave (cargar bajo demanda con `@`)

- `@README.md` — overview público y quickstart
- `@MANUAL_USO.md` — manual operacional completo
- `@INSTALACION.md` — instalación, perfiles, configuración
- `@COMANDOS.md` — referencia detallada de cada `/swl:*`
- `@AGENTS.md` — catálogo de agentes con capacidades
- `@INVENTARIO.md` — conteos oficiales (regenerado por script)
- `@docs/variables-entorno.md` — variables opt-in completas
- `@docs/CI-CD-SETUP.md` — setup de pipelines
- `@.planning/adrs/README.md` — índice de decisiones arquitecturales

---

## Qué es este repositorio

Sistema de ingeniería de software auto-evolutivo multi-runtime polyglot (SDLC completo).
11 lenguajes, 7 runtimes (Claude, OpenClaude, OpenCode, Gemini, Cursor, Codex, Copilot), 61 agentes, 178 skills, 44 comandos, 71 reglas, 43 hooks.

## Estructura del repositorio

```
agentes/       habilidades/    comandos/swl/   contextos/      instintos/
reglas/        hooks/          schemas/        manifiestos/    plantillas/
scripts/       bin/            _userland/      .claude/        .planning/
```

## Flujos de trabajo

**Feature completa**: orquestador → discovery → PRD → arquitectura → plan → implementación (paralelo) → calidad (paralelo) → cierre
**Fases GSD**: discutir → planear → ejecutar → verificar
**Frontend**: investigador-ux → disenador-ui → accesibilidad → frontend-* → rendimiento
**Backend**: backend-api → backend-python/node → backend-workers → datos
**Mobile**: producto-prd → mobile-cross (decisión) → mobile-android/ios → tdd-qa

## Comandos del sistema (/swl:*)

Catálogo completo de 44 comandos `/swl:*` en `@COMANDOS.md`. Atajos mentales por categoría:

- **Ciclo GSD por fase**: `discutir-fase` → `planear-fase` → `ejecutar-fase` → `verificar` (con discovery routing, modo iterativo `--iterative` y `--until-converge`).
- **Anti-context-rot**: `checkpoint`, `compactar`.
- **Aprendizaje**: `aprender`, `evolucionar`, `autoresearch`, `reflect-skills`.
- **Calidad**: `revisar`, `verificar`, `nemesis` (auditoría Feynman + State, opcional `--remediar`).
- **Diagnóstico**: `salud`, `metricas`, `dashboard`, `evolucion-estado`.
- **Release**: `release`, `configurar-ci`.
- **Conocimiento**: `wiki`, `mapear-codebase`, `skill-search`, `ayuda`.

Para flags exactos y semántica de cada comando ver `@COMANDOS.md` y `@MANUAL_USO.md`.

## Reglas obligatorias (25 base + 40 por lenguaje)

Las reglas globales del usuario en `~/.claude/rules/` se cargan automáticamente
y aplican a todos los proyectos. Las reglas del sistema en `reglas/` se cargan
por matcher de archivos o vía `@reglas/<nombre>.md` desde el CLAUDE.md del
proyecto. Reglas de mayor uso:

| Regla | Carga cuando |
|-------|-------------|
| `usar-sistema-swl.md` | Siempre — matriz operacional: tarea → componente SWL obligatorio |
| `brevedad-output.md` | Siempre — idioma español, eficiencia de tokens |
| `seguridad.md` / `seguridad-agentes.md` | `*.py`, `*.ts`, `auth/`, agentes autónomos |
| `arreglar-al-detectar.md` | Siempre — detectar → informar → arreglar en mismo turno |
| `analisis-previo-tareas-grandes.md` | Solicitudes >10 archivos / >500 LOC / cross-módulo |
| `usar-context7.md` | Al generar código que importe librerías externas |
| `git-workflow.md` | Siempre |
| `skills-estandar.md` / `fragmentos-compartidos.md` | Crear/auditar skills o fragmentos |
| `registro-componentes-nuevos.md` | Crear cualquier componente nuevo (agente/skill/comando/hook/regla) — registro obligatorio en manifiestos + plugin.json + INVENTARIO en mismo commit |
| `auditorias-documentales-estructurales.md` | Ejecutar verificadores docs/release/manifest — gates de profundidad y cobertura completa (no muestra). Aplica reglas anti-cosméticas a auditorías |

Catálogo completo y matchers en `@INVENTARIO.md` sección Reglas.

@reglas/usar-sistema-swl.md

## Estrategia de modelos por nivel de criticidad (Model-Tier)

Asignar el modelo correcto a cada agente según la criticidad e irreversibilidad de la tarea.

| Nivel | Modelo | Campo en frontmatter | Agentes SWL | Criterio |
|-------|--------|---------------------|-------------|----------|
| **Crítico** | `claude-opus-4-7` | `model: claude-opus-4-7` | orquestador, arquitecto, revisor-seguridad, producto-prd | Decisiones irreversibles (arquitectura, seguridad, PRD) |
| **Estándar** | `claude-sonnet-4-6` | `model: claude-sonnet-4-6` | backend-*, frontend-*, mobile-*, tdd-qa, revisores de lenguaje | Implementación y revisión |
| **Ligero** | `claude-haiku-4-5-20251001` | `model: claude-haiku-4-5-20251001` | notificador, resolutor-build (búsquedas) | Operaciones deterministas rápidas |
| **Heredado** | (del padre) | `model: inherit` | Sub-agentes invocados por el orquestador | El padre decide |

**Reglas de asignación**: decisiones no reversibles → Opus; código → Sonnet; búsqueda/notificación → Haiku.
NUNCA usar Opus para tareas que Sonnet resuelve igual de bien.

**Workflow Opus 4.7**: tratar como ingeniero al que se delega (spec completa: intent + constraints + acceptance criteria + file locations). Sigue instrucciones literalmente — eliminar ambigüedad. Effort levels nativos: `high | xhigh | max`.

---

## Convenciones operacionales

Detalle completo en `@docs/convenciones-operacionales.md`. Resumen mínimo:

- **Score mínimo de calidad**: **9.0/10** para aprobar trabajo.
- **Modos de desarrollo**: `dev`, `review`, `research` (vía `/swl:contexto`).
- **`respositorios-git/` y `temp/` son material de referencia** — no modificar ni commitear.
- **Dependencias externas educativas son opt-in NO-dependencia** — el sistema funciona sin ellas.
- **Patrón "validar antes de invocar"** para herramientas externas opt-in (markitdown, MinerU, gh).
- **`skillsInvocables` requiere `Skill` en `tools:`** del agente.

## Mapa de propagación de cambios

Al modificar o agregar cualquier componente del sistema, **invocar
`Skill("doc-sync")` antes del commit final** para cargar el protocolo
proactivo completo. La tabla y checklist completos viven en
`@docs/mapa-propagacion.md` para mantener este archivo bajo el umbral
de 200 líneas (regla `auditar-claudemd.js`).

Resumen mínimo para uso inmediato:

- Cualquier componente nuevo o modificado (agente / skill / comando / hook / regla / schema / variable `SWL_*` / ADR / dependencia opt-in): consultar tabla completa en `@docs/mapa-propagacion.md` para saber qué archivos tocar.
- **Skill responsable**: `Skill("doc-sync") § Protocolo proactivo` (sub-secciones Tipo 1 a Tipo 8) tiene el detalle prescriptivo.
- **Antes de commit estructural**: regenerar inventario, validar manifiestos, verificar evolución (si tocó skill/agente), correr verificador docs-vs-código, suite completa, gate de release. Checklist exacto en `@docs/mapa-propagacion.md § Checklist único`.
- Si cualquier gate falla, **NO commitear** hasta corregir. Regla `arreglar-al-detectar.md` exige resolver en mismo turno.
