@saulwade/swl-ses 2.3.1 → 2.4.1

package/CLAUDE.md

@@ -1,240 +1,241 @@
-# CLAUDE.md — @saulwade/swl-ses v2.3.1
-
-## 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**: 1 directa (`docx ^9.6.1`; `pako` y `readable-stream` son transitivas de docx/jszip, no directas). Hooks y scripts/lib son zero-deps
-- **Idioma de salida**: 100% español (México) para componentes SWL; skills oficiales de Anthropic en inglés
-- **MCP del proyecto**: `code-review-graph` disponible vía `.mcp.json` (requiere `uvx`). Comportamiento: `@~/.claude/rules/usar-code-review-graph.md`
-
-## 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:status metricas fases`. |
-
-## Code style
-
-- **Nombres**: kebab-case para archivos; agentes SWL y vocabulario GSD (comandos `*-fase`, dir `.planning/fases/`) en español; paths runtime/técnicos de `.planning/` en inglés (`evolution/`, `auto-evolution/`, `user-profile/`, `archive/`, `traces/`, `sessions/`, `audit/`). Ver `@~/.claude/rules/analizar-directorios-antes-de-escribir.md § Eje técnico-runtime`
-- **Zero-dependencies en `hooks/lib/`**: sin dependencias npm externas
-- **Escrituras atómicas obligatorias**: usar `atomicWriteSync()` / `atomicWriteJSON()` de `hooks/lib/atomic-write.js`. NUNCA `fs.writeFileSync` directo en archivos del sistema
-- **JSONL para alta frecuencia**: usar `fs.appendFileSync(ruta, JSON.stringify(evento) + '\n')` en hooks de telemetría/auditoría — no `atomicWriteJSON` que reescribe todo
-- **YAML inline en frontmatter**: `tools: [Read, Write]`, `skillsInvocables: [skill-a]`. NUNCA CSV string ni mezcla con lista multilínea
-- **Mensajes de commit**: imperativo en español, formato `<tipo>(<scope>): <descripción>`
-- **Sin `console.log` en producción** — excepto en `scripts/`, `bin/`, `hooks/`, `gateway/` (CLIs y daemons)
-- **Nombre completo del paquete en npx**: todo mensaje del installer/docs usa `npx -y @saulwade/swl-ses@latest <comando>`. **NUNCA** `npx swl-ses@latest <comando>` sin el scope `@saulwade/` — eso resuelve al paquete legacy DEPRECATED (v5.13.1) que aún existe en npm tras el rebrand de 2026-04-30. El `@latest` es indispensable: sin él npx reutiliza la primera versión cacheada y el usuario corre código viejo sin saberlo. El `-y` evita la prompt de confirmación en CI/scripts
-- **Fixtures `secret`/`token` en tests deben ser en español** (`secreto`, `tokenBearer`, `clave-test`). El hook `calidad-pre-commit.js` matchea `\bsecret\s*[=:]\s*["'][^"'\s]{4,}["']` y `\btoken\s*[=:]\s*["'][^"'\s]{8,}["']` — `const secret = "valor"` se bloquea como credencial hardcodeada aunque sea fixture legítimo. Renombrar a español elude el regex sin bypass (alternativas reconocidas por el hook: `placeholder`, `example`, `fake_`, `dummy_`, `os.environ`/`process.env`). Coherente con regla global de idioma. Origen: PR #11 sesión 2026-05-13
-- **`git add archivo && git commit -m "..."` en un solo comando bash NO actualiza el index antes del PreToolUse hook**: el hook `calidad-pre-commit.js` evalúa el contenido staged previo al `&&`, no el actualizado en la misma línea. Síntoma: commit bloqueado por contenido que ya corregiste vía Write/Edit pero seguía staged en versión antigua. Fix: separar en dos calls Bash (`git add archivo` → ver resultado → `git commit -m "..."`). NUNCA usar `--no-verify` para bypassear. Origen: PR #11 sesión 2026-05-13
-- **Secretos compartidos entre clientes MCP viven como variables de entorno persistentes del SO, NO en archivos JSON** [v2 — 2026-05-18]: un MCP usado desde Cursor + Claude Code + VS Code tiene un config JSON POR cliente; duplicar `OBSIDIAN_API_KEY` en N archivos genera drift al regenerar la apiKey. Patrón: `setx OBSIDIAN_API_KEY <key>` (o `[Environment]::SetEnvironmentVariable(..., "User")` en PS7) → escribe a `HKCU\Environment` → todos los clientes la heredan al spawnear el binario. Los JSON OMITEN la clave `env` por completo (NO `env: {}` vacío — pasa literal a `child_process.spawn` y REEMPLAZA el env del padre, rompiendo la herencia). Regenerar apiKey = un `setx` + reiniciar clientes, sin tocar JSONs. Origen: 2026-05-18, 6h de errores 40101 por 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
-- **`reglas/` es la FUENTE; `~/.claude/rules/` son copias INSTALADAS** por el instalador: todo cambio a reglas base va en la fuente y se sincroniza — editar solo las copias es deuda volátil (el install las sobreescribe). Incluye las reglas globales personales del usuario (decisión 2026-06-12, commit `2f6b8de` — las 37 base viajan en `reglas-core`). Origen: Fase 09 (APRENDIZAJES 2026-06-11)
-- **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
-- **Comandos `/swl:*` invocan vía CLI cross-scope, NUNCA rutas relativas al proyecto**: dentro de fenced code blocks de `comandos/swl/*.md` usar `swl-ses <sub>` (resolución: repo madre → bin en PATH → `npx -y @saulwade/swl-ses@latest <sub>`), no `node scripts/...` ni `require('./hooks/...')` — esas rutas rompen en instalación global/downstream (gates SDD G0/G1, telemetría, CI). Gate bloqueante en `scripts/validar.js §7b` (`auditar-invocaciones-comandos.js`); excluye SELF_DEV `{release, contribuir, evaluar-skill, reflect-skills}`. Wrappers en `scripts/cli/` se distribuyen SOLO vía npm (`package.json#files`), NO se cuentan en INVENTARIO ni en `modulos.json`; registro único en `bin/swl-ses.js`. Detalle: `@docs/invocacion-cli-cross-scope.md`. Origen: v2.2.0
-- **Componentes evolucionados: merge, no overwrite (invariante)**: el instalador NUNCA sobrescribe un componente con evolución del usuario (global o proyecto) — usa merge (preserve + `.evolved-diff.txt`). Distingue evolución de usuario (A) de shipped-evolved de fábrica (B) por hash del cuerpo canónico (`manifiestos/canonical-hashes.json`); el fuente NO porta marcadores `evolved` (gate inverso en `validar.js`). Detalle: ADR-0040. Origen: Fase 16
-
-## 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), 60 agentes, 182 skills, 44 comandos, 77 reglas, 50 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 (37 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 |
-|-------|-------------|
-| `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.
-
-<!-- La regla de la sección "Uso obligatorio del sistema SWL" NO se importa con @: la copia global ya carga sola; el @import duplicaba ~250 líneas/sesión. Depurado Fase 09 (commit 7273c9e). -->
-
-## 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 | Alias (resuelve a) | Campo en frontmatter | Agentes SWL | Criterio |
-|-------|--------|---------------------|-------------|----------|
-| **Crítico** | `opus` (hoy Opus 4.8) | `model: opus` | orquestador, arquitecto, revisor-seguridad, producto-prd | Decisiones irreversibles (arquitectura, seguridad, PRD) |
-| **Estándar** | `sonnet` (hoy Sonnet 5) | `model: sonnet` | backend-*, frontend-*, mobile-*, tdd-qa, revisores de lenguaje | Implementación y revisión |
-| **Ligero** | `haiku` (hoy Haiku 4.5) | `model: haiku` | notificador, resolutor-build (búsquedas) | Operaciones deterministas rápidas |
-| **Heredado** | (del padre) | `model: inherit` | Sub-agentes invocados por el orquestador | El padre decide |
-
-**Por qué alias y no ID pineado**: el frontmatter usa alias (`opus`/`sonnet`/`haiku`), no IDs completos. El alias *resuelve al modelo vigente de su familia y se actualiza solo* ([doc oficial](https://code.claude.com/docs/en/model-config): "aliases point to the recommended version and update over time"). Esto elimina la migración manual en cada release de modelo (antes: opus 4.7→4.8, sonnet 4.6→5). En Bedrock/Vertex el alias resuelve al modelo que ese proveedor sí ofrece, evitando IDs inexistentes; y degrada limpio en versiones antiguas de Claude Code. **Caveat**: los alias son un constructo de Claude Code, no de la API cruda — el código que llama a la API/SDK directamente (`gateway/agent-executor.js`, tablas de precios/telemetría) sí usa el ID completo (`claude-sonnet-5`).
-
-**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.8 / Sonnet 5**: tratar como ingeniero al que se delega (spec completa: intent + constraints + acceptance criteria + file locations). Sigue instrucciones literalmente — eliminar ambigüedad. Effort levels nativos: `low | medium | high | xhigh | max` (Sonnet 5 y Opus 4.8; Sonnet 4.6 no soportaba `xhigh`).
-
----
-
-## 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.
-
-<!-- code-review-graph MCP tools -->
-## MCP Tools: code-review-graph
-
-**IMPORTANT: This project has a knowledge graph. ALWAYS use the
-code-review-graph MCP tools BEFORE using Grep/Glob/Read to explore
-the codebase.** The graph is faster, cheaper (fewer tokens), and gives
-you structural context (callers, dependents, test coverage) that file
-scanning cannot.
-
-### When to use graph tools FIRST
-
-- **Exploring code**: `semantic_search_nodes` or `query_graph` instead of Grep
-- **Understanding impact**: `get_impact_radius` instead of manually tracing imports
-- **Code review**: `detect_changes` + `get_review_context` instead of reading entire files
-- **Finding relationships**: `query_graph` with callers_of/callees_of/imports_of/tests_for
-- **Architecture questions**: `get_architecture_overview` + `list_communities`
-
-Fall back to Grep/Glob/Read **only** when the graph doesn't cover what you need.
-
-### Key Tools
-
-| Tool | Use when |
-|------|----------|
-| `detect_changes` | Reviewing code changes — gives risk-scored analysis |
-| `get_review_context` | Need source snippets for review — token-efficient |
-| `get_impact_radius` | Understanding blast radius of a change |
-| `get_affected_flows` | Finding which execution paths are impacted |
-| `query_graph` | Tracing callers, callees, imports, tests, dependencies |
-| `semantic_search_nodes` | Finding functions/classes by name or keyword |
-| `get_architecture_overview` | Understanding high-level codebase structure |
-| `refactor_tool` | Planning renames, finding dead code |
-
-### Workflow
-
-1. The graph auto-updates on file changes (via hooks).
-2. Use `detect_changes` for code review.
-3. Use `get_affected_flows` to understand impact.
-4. Use `query_graph` pattern="tests_for" to check coverage.
+# CLAUDE.md — @saulwade/swl-ses v2.4.1
+
+## 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**: 1 directa (`docx ^9.6.1`; `pako` y `readable-stream` son transitivas de docx/jszip, no directas). Hooks y scripts/lib son zero-deps
+- **Idioma de salida**: 100% español (México) para componentes SWL; skills oficiales de Anthropic en inglés
+- **MCP del proyecto**: `code-review-graph` disponible vía `.mcp.json` (requiere `uvx`). Comportamiento: `@~/.claude/rules/usar-code-review-graph.md`
+
+## 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:status metricas fases`. |
+
+## Code style
+
+- **Nombres**: kebab-case para archivos; agentes SWL y vocabulario GSD (comandos `*-fase`, dir `.planning/fases/`) en español; paths runtime/técnicos de `.planning/` en inglés (`evolution/`, `auto-evolution/`, `user-profile/`, `archive/`, `traces/`, `sessions/`, `audit/`). Ver `@~/.claude/rules/analizar-directorios-antes-de-escribir.md § Eje técnico-runtime`
+- **Zero-dependencies en `hooks/lib/`**: sin dependencias npm externas
+- **Escrituras atómicas obligatorias**: usar `atomicWriteSync()` / `atomicWriteJSON()` de `hooks/lib/atomic-write.js`. NUNCA `fs.writeFileSync` directo en archivos del sistema
+- **JSONL para alta frecuencia**: usar `fs.appendFileSync(ruta, JSON.stringify(evento) + '\n')` en hooks de telemetría/auditoría — no `atomicWriteJSON` que reescribe todo
+- **YAML inline en frontmatter**: `tools: [Read, Write]`, `skillsInvocables: [skill-a]`. NUNCA CSV string ni mezcla con lista multilínea
+- **Mensajes de commit**: imperativo en español, formato `<tipo>(<scope>): <descripción>`
+- **Sin `console.log` en producción** — excepto en `scripts/`, `bin/`, `hooks/`, `gateway/` (CLIs y daemons)
+- **Nombre completo del paquete en npx**: todo mensaje del installer/docs usa `npx -y @saulwade/swl-ses@latest <comando>`. **NUNCA** `npx swl-ses@latest <comando>` sin el scope `@saulwade/` — eso resuelve al paquete legacy DEPRECATED (v5.13.1) que aún existe en npm tras el rebrand de 2026-04-30. El `@latest` es indispensable: sin él npx reutiliza la primera versión cacheada y el usuario corre código viejo sin saberlo. El `-y` evita la prompt de confirmación en CI/scripts
+- **Fixtures `secret`/`token` en tests deben ser en español** (`secreto`, `tokenBearer`, `clave-test`). El hook `calidad-pre-commit.js` matchea `\bsecret\s*[=:]\s*["'][^"'\s]{4,}["']` y `\btoken\s*[=:]\s*["'][^"'\s]{8,}["']` — `const secret = "valor"` se bloquea como credencial hardcodeada aunque sea fixture legítimo. Renombrar a español elude el regex sin bypass (alternativas reconocidas por el hook: `placeholder`, `example`, `fake_`, `dummy_`, `os.environ`/`process.env`). Coherente con regla global de idioma. Origen: PR #11 sesión 2026-05-13
+- **`git add archivo && git commit -m "..."` en un solo comando bash NO actualiza el index antes del PreToolUse hook**: el hook `calidad-pre-commit.js` evalúa el contenido staged previo al `&&`, no el actualizado en la misma línea. Síntoma: commit bloqueado por contenido que ya corregiste vía Write/Edit pero seguía staged en versión antigua. Fix: separar en dos calls Bash (`git add archivo` → ver resultado → `git commit -m "..."`). NUNCA usar `--no-verify` para bypassear. Origen: PR #11 sesión 2026-05-13
+- **Secretos compartidos entre clientes MCP viven como variables de entorno persistentes del SO, NO en archivos JSON** [v2 — 2026-05-18]: un MCP usado desde Cursor + Claude Code + VS Code tiene un config JSON POR cliente; duplicar `OBSIDIAN_API_KEY` en N archivos genera drift al regenerar la apiKey. Patrón: `setx OBSIDIAN_API_KEY <key>` (o `[Environment]::SetEnvironmentVariable(..., "User")` en PS7) → escribe a `HKCU\Environment` → todos los clientes la heredan al spawnear el binario. Los JSON OMITEN la clave `env` por completo (NO `env: {}` vacío — pasa literal a `child_process.spawn` y REEMPLAZA el env del padre, rompiendo la herencia). Regenerar apiKey = un `setx` + reiniciar clientes, sin tocar JSONs. Origen: 2026-05-18, 6h de errores 40101 por 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
+- **`reglas/` es la FUENTE; `~/.claude/rules/` son copias INSTALADAS** por el instalador: todo cambio a reglas base va en la fuente y se sincroniza — editar solo las copias es deuda volátil (el install las sobreescribe). Incluye las reglas globales personales del usuario (decisión 2026-06-12, commit `2f6b8de` — las 37 base viajan en `reglas-core`). Origen: Fase 09 (APRENDIZAJES 2026-06-11)
+- **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
+- **Comandos `/swl:*` invocan vía CLI cross-scope, NUNCA rutas relativas al proyecto**: dentro de fenced code blocks de `comandos/swl/*.md` usar `swl-ses <sub>` (resolución: repo madre → bin en PATH → `npx -y @saulwade/swl-ses@latest <sub>`), no `node scripts/...` ni `require('./hooks/...')` — esas rutas rompen en instalación global/downstream (gates SDD G0/G1, telemetría, CI). Gate bloqueante en `scripts/validar.js §7b` (`auditar-invocaciones-comandos.js`); excluye SELF_DEV `{release, contribuir, evaluar-skill, reflect-skills}`. Wrappers en `scripts/cli/` se distribuyen SOLO vía npm (`package.json#files`), NO se cuentan en INVENTARIO ni en `modulos.json`; registro único en `bin/swl-ses.js`. Detalle: `@docs/invocacion-cli-cross-scope.md`. Origen: v2.2.0
+- **Componentes evolucionados: merge, no overwrite (invariante)**: el instalador NUNCA sobrescribe un componente con evolución del usuario (global o proyecto) — usa merge (preserve + `.evolved-diff.txt`). Distingue evolución de usuario (A) de shipped-evolved de fábrica (B) por hash del cuerpo canónico (`manifiestos/canonical-hashes.json`); el fuente NO porta marcadores `evolved` (gate inverso en `validar.js`). Detalle: ADR-0040. Origen: Fase 16
+
+## 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), 60 agentes, 182 skills, 45 comandos, 77 reglas, 49 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 45 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`), `deuda-codigo` (cosecha de marcadores `simplificado:`).
+- **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 (37 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 |
+|-------|-------------|
+| `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.
+
+<!-- La regla de la sección "Uso obligatorio del sistema SWL" NO se importa con @: la copia global ya carga sola; el @import duplicaba ~250 líneas/sesión. Depurado Fase 09 (commit 7273c9e). -->
+
+## 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 | Alias (resuelve a) | Campo en frontmatter | Agentes SWL | Criterio |
+|-------|--------|---------------------|-------------|----------|
+| **Frontier** | `fable` (hoy Fable 5) | `model: fable` | orquestador (alterno: `opus`) | Coordinación central multi-agente: routing, scope, gates HITL — las decisiones más caras de corregir |
+| **Crítico** | `opus` (hoy Opus 4.8) | `model: opus` | arquitecto, revisor-seguridad, producto-prd | Decisiones irreversibles (arquitectura, seguridad, PRD) |
+| **Estándar** | `sonnet` (hoy Sonnet 5) | `model: sonnet` | backend-*, frontend-*, mobile-*, tdd-qa, revisores de lenguaje | Implementación y revisión |
+| **Ligero** | `haiku` (hoy Haiku 4.5) | `model: haiku` | notificador, resolutor-build (búsquedas) | Operaciones deterministas rápidas |
+| **Heredado** | (del padre) | `model: inherit` | Sub-agentes invocados por el orquestador | El padre decide |
+
+**Por qué alias y no ID pineado**: el frontmatter usa alias (`fable`/`opus`/`sonnet`/`haiku`), no IDs completos. El alias *resuelve al modelo vigente de su familia y se actualiza solo* ([doc oficial](https://code.claude.com/docs/en/model-config): "aliases point to the recommended version and update over time"). Esto elimina la migración manual en cada release de modelo (antes: opus 4.7→4.8, sonnet 4.6→5). En Bedrock/Vertex el alias resuelve al modelo que ese proveedor sí ofrece, evitando IDs inexistentes; y degrada limpio en versiones antiguas de Claude Code. **Caveat**: los alias son un constructo de Claude Code, no de la API cruda — el código que llama a la API/SDK directamente (`gateway/agent-executor.js`, tablas de precios/telemetría) sí usa el ID completo (`claude-sonnet-5`).
+
+**Reglas de asignación**: coordinación central (solo orquestador) → Fable; decisiones no reversibles → Opus; código → Sonnet; búsqueda/notificación → Haiku.
+NUNCA usar un tier superior para tareas que el inferior resuelve igual de bien (Fable no se propaga a sub-agentes).
+
+**Workflow Opus 4.8 / Sonnet 5**: tratar como ingeniero al que se delega (spec completa: intent + constraints + acceptance criteria + file locations). Sigue instrucciones literalmente — eliminar ambigüedad. Effort levels nativos: `low | medium | high | xhigh | max` (Sonnet 5 y Opus 4.8; Sonnet 4.6 no soportaba `xhigh`).
+
+---
+
+## 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.
+
+<!-- code-review-graph MCP tools -->
+## MCP Tools: code-review-graph
+
+**IMPORTANT: This project has a knowledge graph. ALWAYS use the
+code-review-graph MCP tools BEFORE using Grep/Glob/Read to explore
+the codebase.** The graph is faster, cheaper (fewer tokens), and gives
+you structural context (callers, dependents, test coverage) that file
+scanning cannot.
+
+### When to use graph tools FIRST
+
+- **Exploring code**: `semantic_search_nodes` or `query_graph` instead of Grep
+- **Understanding impact**: `get_impact_radius` instead of manually tracing imports
+- **Code review**: `detect_changes` + `get_review_context` instead of reading entire files
+- **Finding relationships**: `query_graph` with callers_of/callees_of/imports_of/tests_for
+- **Architecture questions**: `get_architecture_overview` + `list_communities`
+
+Fall back to Grep/Glob/Read **only** when the graph doesn't cover what you need.
+
+### Key Tools
+
+| Tool | Use when |
+|------|----------|
+| `detect_changes` | Reviewing code changes — gives risk-scored analysis |
+| `get_review_context` | Need source snippets for review — token-efficient |
+| `get_impact_radius` | Understanding blast radius of a change |
+| `get_affected_flows` | Finding which execution paths are impacted |
+| `query_graph` | Tracing callers, callees, imports, tests, dependencies |
+| `semantic_search_nodes` | Finding functions/classes by name or keyword |
+| `get_architecture_overview` | Understanding high-level codebase structure |
+| `refactor_tool` | Planning renames, finding dead code |
+
+### Workflow
+
+1. The graph auto-updates on file changes (via hooks).
+2. Use `detect_changes` for code review.
+3. Use `get_affected_flows` to understand impact.
+4. Use `query_graph` pattern="tests_for" to check coverage.