@saulwade/swl-ses 1.0.0

package/habilidades/infra-github-actions/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: infra-github-actions
+description: >
+  GitHub Actions CI/CD para proyectos que usan swl-ses. Cubre los tres workflows
+  distribuidos (swl-security.yml, swl-ci.yml, release-please.yml), setup del secret
+  CLAUDE_API_KEY, branch protection y troubleshooting. Cargar cuando se configura
+  CI/CD con GitHub Actions en un proyecto donde está instalado swl-ses.
+---
+
+# infra-github-actions — GitHub Actions con swl-ses
+
+## Cuándo cargar
+
+- Al ejecutar `/swl:configurar-ci init` y necesitar guía de setup
+- Al depurar un workflow que no dispara o falla por API key
+- Al configurar branch protection en el proyecto
+- Al decidir si adoptar release-please vs el flujo manual actual
+
+## Cuándo NO cargar
+
+- El proyecto usa Azure DevOps Pipelines o GitLab CI — esos tienen su propia configuración
+- El objetivo es Kubernetes, Terraform o infraestructura cloud (cargar `kubernetes-orquestacion` o `terraform-experto`)
+- La tarea es solo correr tests localmente sin CI
+- El proyecto no usa GitHub como repositorio
+
+---
+
+## Workflows distribuidos por swl-ses
+
+| Archivo | Propósito | Secrets requeridos |
+|---------|-----------|-------------------|
+| `swl-security.yml` | Revisión semántica de seguridad con Claude en cada PR | `CLAUDE_API_KEY` |
+| `swl-ci.yml` | Lint + tests en push y PRs. Node 22+24, Python/Rust/Go comentados | Ninguno |
+| `release-please.yml` | Release PR automático + tag + GitHub Release | Ninguno (`GITHUB_TOKEN` automático) |
+
+Instalación con: `/swl:configurar-ci init`
+
+---
+
+## Reglas obligatorias
+
+**NUNCA** commitear API keys en código ni en archivos de workflow.
+Todo secret va en GitHub Settings → Secrets and variables → Actions.
+
+**Permisos mínimos siempre**: declarar solo `contents: read` y `pull-requests: write`
+en el nivel del workflow. Nunca `permissions: write-all`.
+
+**Los workflows de forks externos no reciben secrets** por diseño de GitHub.
+La revisión de seguridad con Claude solo funciona en PRs desde ramas del mismo repo,
+no desde repos forked. Es un comportamiento de GitHub, no un bug.
+
+**No hardcodear nombres de rama** más allá de `main`. Si el proyecto usa otra rama
+por defecto, editar el `on: push: branches` en los workflows copiados.
+
+---
+
+## Setup de CLAUDE_API_KEY
+
+1. Ir a https://console.anthropic.com y crear o copiar la API key
+2. En GitHub: Settings → Secrets and variables → Actions → New repository secret
+   - Nombre: `CLAUDE_API_KEY`
+   - Valor: la API key
+3. La key necesita permisos tanto para Claude API como para Claude Code
+
+Verificar con gh CLI si el secret ya existe:
+```bash
+gh secret list | grep CLAUDE_API_KEY
+```
+
+Para configurar vía CLI (valor desde stdin, no queda en historial):
+```bash
+gh secret set CLAUDE_API_KEY
+```
+
+---
+
+## Branch protection
+
+Aplicar después de tener CI funcionando. El script del repo swl-ses:
+
+```bash
+# Ver qué haría sin aplicar cambios
+node scripts/configurar-branch-protection.js --dry-run
+
+# Aplicar
+node scripts/configurar-branch-protection.js
+```
+
+Requiere `gh` CLI autenticado y permisos de admin en el repositorio.
+
+Configura: require PR, status checks (`test (22)`, `test (24)`, `smoke`),
+1 approval, bloquea force-push y deletions.
+
+---
+
+## Adoptar release-please (opt-in)
+
+Ver `docs/RELEASE-PLEASE-MIGRATION.md` para comparativa completa.
+
+El flujo actual del repo swl-ses usa `scripts/publicar.js` (manual). release-please
+es una alternativa automática viable para proyectos de usuarios.
+
+Instalar:
+```
+/swl:configurar-ci --with-release-please
+```
+
+Una vez activo, el flujo es:
+1. Hacer merge de commits convencionales a main
+2. release-please abre un "Release PR" automático con bump de versión y CHANGELOG
+3. Al mergear ese PR → tag git + GitHub Release creado automáticamente
+
+---
+
+## Gotchas / Errores comunes no obvios
+
+**GitHub Free + repo privado → 403 en branch protection Y Rulesets**: tanto el endpoint legacy
+`/repos/.../branches/{}/protection` como el endpoint moderno `/repos/.../rulesets` requieren
+**plan de pago** en repos privados (HTTP 403 "Upgrade to GitHub Pro or make this repository public"
+en ambos). Mi documentación inicial afirmó incorrectamente que Rulesets era gratis para repos
+privados Free — verificación empírica posterior confirmó que NO. Ambos endpoints están bloqueados.
+
+Planes que destraban la feature en privado:
+- **Pro** ($4/mes): aplica a repos en cuenta personal del titular Pro.
+- **Team** ($4/usuario/mes): aplica solo a repos **de la organización** que paga Team. NO aplica
+  a repos en la cuenta personal del admin de la org. Para que Team aplique al repo, transferirlo:
+  `gh repo transfer cuenta-personal/repo --new-owner org`.
+
+Sin plan de pago y manteniendo repo privado, las opciones son: pre-push hook local
+(bypasseable con `--no-verify`) y workflow advisory (no bloquea push, crea issue post-hoc).
+
+**Push directo a main bloqueado tras activar branch protection**: si configuraste
+branch protection antes de que tu usuario tuviera al menos un PR mergeado con los
+status checks pasando, el repo puede quedar en estado donde nadie puede mergear.
+Causa: GitHub verifica los status checks declarados antes de permitir el merge; si
+los checks no han corrido en el branch, el botón de merge queda bloqueado.
+Fix: crear una rama temporal con un cambio trivial, abrir PR, dejar que los checks
+corran, y mergear. Luego ya funciona el flujo normal.
+
+**GITHUB_TOKEN no puede aprobar su propio PR** al usar release-please: release-please
+crea un Release PR con el GITHUB_TOKEN del bot — ese mismo token no puede aprobarlo
+si el repo requiere al menos 1 approval humano. Causa: GitHub bloquea la auto-aprobación
+con el token de Actions por defecto.
+Fix: crear un Personal Access Token (PAT) con scope `repo` y usarlo en el workflow:
+`token: ${{ secrets.MY_RELEASE_TOKEN }}`. O reducir el required approvals a 0 para
+el Release PR (no recomendado en repos con múltiples contribuidores).
+
+**`anthropics/claude-code-security-review@main` falla con "API key not set"**: el
+secret `CLAUDE_API_KEY` no está configurado o el nombre no coincide exactamente.
+La action es sensible a mayúsculas — `claude_api_key` (minúsculas) no funciona.
+Fix: verificar con `gh secret list`. El nombre debe ser exactamente `CLAUDE_API_KEY`.
+
+**El workflow `swl-ci.yml` pasa localmente pero falla en CI con "lint script not found"**:
+el campo `lint` no está definido en `package.json` del proyecto del usuario. La plantilla
+usa `npm run lint --if-present` precisamente para ser tolerante, pero si el proyecto
+tiene un nombre distinto (ej: `eslint`, `check`) el step se salta silenciosamente.
+Fix: agregar el script `"lint": "..."` en `package.json` o editar el workflow para usar
+el nombre correcto.
+
+**release-please genera changelog con commits `chore(release)` del repo padre swl-ses**:
+si el proyecto del usuario adoptó los mensajes de commit de swl-ses que incluyen
+`chore(release): v5.X.Y`, release-please los interpreta como commits de release
+y puede generar bumps incorrectos.
+Fix: usar mensajes de commit convencionales estándar para el proyecto del usuario,
+separados del estilo de swl-ses. Los prefijos `feat:`, `fix:`, `chore:` sin el
+patrón `(release): vX.Y.Z` no causan conflicto.

package/habilidades/instalar-sistema/.evolved.json

@@ -0,0 +1,9 @@
+{
+  "SKILL.md": {
+    "evolved": true,
+    "evolvedFrom": "5.10.4",
+    "evolvedAt": "2026-04-20",
+    "evolvedBy": "aprender",
+    "evolvedNote": "state file busqueda en 7 ubicaciones"
+  }
+}

package/habilidades/instalar-sistema/SKILL.md

@@ -0,0 +1,221 @@
+---
+name: instalar-sistema
+description: "Instala o actualiza el sistema SWL en el proyecto actual. Usar PROACTIVAMENTE cuando: (1) el usuario pide instalar SWL, (2) se detecta que el proyecto no tiene .claude/agents/ ni .claude/skills/ con componentes SWL, (3) el usuario menciona perfiles de instalación o pide agregar agentes/skills al proyecto. NO usar cuando SWL ya está instalado y funcionando correctamente."
+user-invocable: false
+version: "1.0.1"
+herramientasPermitidas: [Read, Write, Edit, Bash, Glob, Grep]
+exclusiones:
+  - "No cargar si SWL ya está instalado y funcionando (`doctor` pasa sin errores); no reinstalar para resolver problemas de uso del sistema."
+  - "No cargar para actualizar un skill o agente individual; editar el SKILL.md o agente directamente en `habilidades/` o `agentes/`."
+  - "No cargar para diagnosticar integridad del sistema instalado; usar `/swl:salud`."
+  - "No cargar para añadir skills de `_userland/` al core; usar `/swl:contribuir`."
+evolvable: true  # default para skill estandar
+---
+# Skill: instalar-sistema
+
+Gestiona la instalación, actualización y verificación del sistema SWL (swl-ses) dentro de un proyecto mediante Claude Code.
+
+## Cuándo se activa
+
+Este skill se activa proactivamente cuando:
+
+- El usuario dice "instala SWL", "quiero usar el sistema SWL", "configura SWL en este proyecto"
+- El usuario menciona perfiles: "necesito el perfil backend-python", "instala perfil completo"
+- Se detecta que el proyecto no tiene componentes SWL instalados (no hay `.claude/.swl-install-state.json`)
+- El usuario pide actualizar SWL: "actualiza SWL", "quiero la última versión"
+
+NO se activa cuando:
+- SWL ya está instalado y el usuario no pidió cambios
+- El usuario está trabajando normalmente con los agentes/skills ya instalados
+
+## Cuándo NO cargar
+
+- SWL está instalado y `npx swl-ses doctor` pasa sin errores; reinstalar no resuelve problemas de uso.
+- El usuario quiere modificar un skill o agente específico; editar los archivos en `habilidades/` o `agentes/` directamente.
+- Se quiere diagnosticar por qué algo del sistema no funciona; usar `/swl:salud` que ejecuta validaciones sin reinstalar.
+- Se quiere incorporar skills de `_userland/` al core del sistema; ese flujo es `/swl:contribuir`, no una reinstalación.
+
+## Paquete npm
+
+```
+@saulwade/swl-ses          (canónico, npmjs.org — recomendado)
+@saul-wade/swl-ses         (mirror, GitHub Packages — requiere token)
+```
+
+Registry canónico: `https://registry.npmjs.org/` (sin auth para instalar)
+Mirror: `https://npm.pkg.github.com` (auth con token de GitHub en `~/.npmrc`)
+Requiere: Node.js >= 22
+
+## Comandos CLI disponibles
+
+| Comando | Función |
+|---------|---------|
+| `npx @saulwade/swl-ses@latest init` | Crea `.planning/` y `_userland/` |
+| `npx @saulwade/swl-ses@latest install --target claude --profile <perfil>` | Instala componentes |
+| `npx @saulwade/swl-ses@latest doctor` | Verifica instalación |
+| `npx @saulwade/swl-ses@latest update` | Actualiza componentes |
+| `npx @saulwade/swl-ses@latest uninstall --target claude` | Desinstala componentes |
+
+## Perfiles
+
+| Perfil | Descripción | Componentes |
+|--------|-------------|-------------|
+| `core` | Mínimo viable | 13 agentes, 20 skills, 9 comandos, 5 reglas, 3 hooks |
+| `backend-python` | Python fullstack | Core + 7 skills Python + 3 skills API + 3 skills datos |
+| `backend-node` | Node.js fullstack | Core + 2 skills Node + 3 skills API |
+| `frontend-react` | React frontend | Core + 2 skills React + 5 skills estilos + 3 skills UX |
+| `frontend-angular` | Angular frontend | Core + 2 skills Angular + 5 skills estilos + 3 skills UX |
+| `fullstack-python-angular` | Python + Angular | Backend Python + Frontend Angular |
+| `fullstack-node-react` | Node + React | Backend Node + Frontend React |
+| `mobile` | Mobile dev | Core + 2 skills mobile + frontend agentes |
+| `devops` | Infraestructura | Core + 6 skills infra + 3 skills seguridad |
+| `completo` | Todo SWL | 37 agentes, 60 skills, 14 comandos, 11 reglas, 6 hooks |
+
+## Flujo de instalación
+
+### Instalación nueva (proyecto sin SWL)
+
+```bash
+# 1. Inicializar estructura
+npx @saulwade/swl-ses@latest init
+
+# 2. Instalar componentes (elegir perfil según necesidad)
+npx @saulwade/swl-ses@latest install --target claude --profile <perfil>
+
+# 3. Verificar
+npx @saulwade/swl-ses@latest doctor
+```
+
+### Actualización (SWL ya instalado)
+
+```bash
+# Re-instala con el mismo perfil, sobrescribiendo archivos
+npx @saulwade/swl-ses@latest install --target claude --profile <perfil> --force
+```
+
+### Cambio de perfil
+
+```bash
+# Instalar con nuevo perfil (sobrescribe)
+npx @saulwade/swl-ses@latest install --target claude --profile <nuevo-perfil> --force
+```
+
+### Instalación global (todos los proyectos)
+
+```bash
+npx @saulwade/swl-ses@latest install --target claude --profile <perfil> --global
+```
+
+## Detección automática de stack tecnológico
+
+El instalador detecta automáticamente los lenguajes presentes en el proyecto y filtra las reglas de lenguaje irrelevantes **antes** de copiarlas a `.claude/rules/`. Esto es crítico porque Claude Code auto-carga todos los `.md` de `.claude/rules/` en cada conversación.
+
+**Lenguajes detectados automáticamente:**
+
+| Lenguaje | Indicadores |
+|----------|-------------|
+| `java` | `pom.xml`, `build.gradle`, `build.gradle.kts`, archivos `.java` |
+| `go` | `go.mod`, archivos `.go` |
+| `rust` | `Cargo.toml`, archivos `.rs` |
+| `csharp` | Archivos `.csproj`, `.sln`, `.cs` |
+| `kotlin` | Archivos `.kt`, `.kts` |
+| `swift` | `Package.swift`, directorio `Sources/`, archivos `.swift` |
+| `php` | `composer.json`, `artisan`, archivos `.php` |
+| `nextjs` | `next.config.js/ts/mjs/cjs` |
+
+**Comportamiento:**
+- En un proyecto Python/Angular/TypeScript: **0 reglas de lenguaje instaladas** (Python/TS/Angular no tienen `reglas/lenguajes/` propias)
+- En un proyecto Java: solo las 5 reglas de `reglas/lenguajes/java/` se instalan
+- Perfil `completo` en proyecto Python: instala `reglas-core` + `reglas-calidad` únicamente (ahorra ~700 líneas de contexto)
+
+**Omitir la detección (instalar todos los lenguajes):**
+```bash
+npx swl-ses install --target claude --profile completo --all-langs
+```
+
+## Qué instala y dónde
+
+| Componente | Destino | Claude Code lo descubre |
+|------------|---------|------------------------|
+| Agentes (.md) | `.claude/agents/` | Si — disponibles como `subagent_type` |
+| Skills (dirs con SKILL.md) | `.claude/skills/` | Si — aparecen en system reminders, auto-activación |
+| Comandos (.md) | `.claude/commands/swl/` | Si — disponibles como `/swl:*` slash commands |
+| Reglas generales (.md) | `.claude/rules/` | Si — cargadas automáticamente en cada conversación |
+| Reglas de lenguaje (.md) | `.claude/rules/LANG/` | Si — solo para lenguajes detectados en el proyecto |
+| Hooks (.js) | `./hooks/` | Si — registrados automáticamente en `.claude/settings.json` |
+| Plantillas | `.planning/` | N/A — templates para planeación |
+
+## Prerrequisitos para instalación remota
+
+Si el usuario no tiene el registry configurado:
+
+```bash
+# Configurar registry de GitHub Packages (una vez por máquina)
+npm config set @saul-wade:registry https://npm.pkg.github.com
+
+# Configurar token en ~/.npmrc (una vez por máquina)
+# Agregar línea: //npm.pkg.github.com/:_authToken=<GITHUB_CLASSIC_PAT>
+```
+
+El token debe ser un **GitHub Classic PAT** con scopes `read:packages`.
+
+## Detección de instalación existente
+
+Para verificar si SWL está instalado:
+
+```bash
+# Verificar archivo de estado
+cat .claude/.swl-install-state.json 2>/dev/null
+
+# Verificar agentes SWL
+ls .claude/agents/*-swl.md 2>/dev/null | head -5
+
+# Verificar hooks registrados
+cat .claude/settings.json 2>/dev/null | grep -c "hooks/"
+```
+
+## Gotchas / Errores comunes no obvios
+
+- **Instalación con perfil `completo` en proyecto Python/TypeScript instala reglas de lenguaje innecesarias**: si no se usa la detección automática de stack, el perfil `completo` instala 5 reglas Java + 5 Go + 5 Rust aunque el proyecto no use esos lenguajes, incrementando el contexto base en ~700 líneas por sesión. Causa: no se activó la detección automática de stack. Solución: dejar que el instalador detecte automáticamente o usar `--all-langs` solo si se trabaja con todos los lenguajes; verificar con `ls .claude/rules/` post-instalación.
+- **`~/.npmrc` sin el token configurado bloquea la instalación silenciosamente**: `npx @saulwade/swl-ses@latest init` falla con `401 Unauthorized` desde GitHub Packages. Causa: el token de GitHub Packages no está en `~/.npmrc`. Solución: configurar el `_authToken` en `~/.npmrc` y verificar con `npm whoami --registry https://npm.pkg.github.com` antes de la primera instalación.
+- **Cambio de perfil sin `--force` no actualiza componentes existentes**: el usuario cambia de `backend-python` a `fullstack-python-angular` pero los nuevos skills de Angular no se instalan porque los archivos ya existen. Causa: el instalador no sobreescribe por defecto. Solución: usar `--force` explícitamente en cambios de perfil: `install --target claude --profile <nuevo-perfil> --force`.
+- **markitdown no instalado detectado tardíamente**: el agente intenta convertir un `.docx` en sesión y falla porque `markitdown` no está disponible, interrumpiendo el flujo de trabajo. Causa: el prerequisito de Python se documenta en el skill pero no se verifica automáticamente durante la instalación. Solución: ejecutar `markitdown --version` como parte del checklist post-instalación; si no está disponible, instalarlo antes de iniciar trabajo con documentos Office.
+- **Scripts o hooks que leen `swl-install-state.json` solo en el proyecto actual fallan silenciosamente en instalaciones globales**: un hook intenta detectar la versión instalada leyendo `.claude/.swl-install-state.json` relativo al cwd o relativo al directorio del hook; en instalaciones SWL **solo globales** (la mayoría), ese archivo solo existe en `~/.claude/.swl-install-state.json` y el check sale sin resultado — ninguna alerta, ninguna detección, falla invisible. Causa: el instalador crea el state file en la ubicación del target (`~/.claude/` para `--global`, `./.claude/` para `--local`), pero los consumidores suelen buscar en una sola de esas ubicaciones. Solución: cualquier script/hook que dependa del state del instalador debe buscar en **7 ubicaciones** y tomar la del `mtime` más reciente cuando haya varias:
+  ```
+  ~/.claude/.swl-install-state.json          (global Claude, mayoría de usuarios)
+  ./.claude/.swl-install-state.json          (local al proyecto)
+  ./.github/.swl-install-state.json          (Copilot)
+  ./.codex/.swl-install-state.json           (Codex CLI)
+  ./.gemini/.swl-install-state.json          (Gemini CLI)
+  ./.opencode/.swl-install-state.json        (OpenCode)
+  <dirname-del-script>/../../.claude/.swl-install-state.json   (hook instalado en .claude/hooks/)
+  ```
+  Ejemplo canónico: `hooks/check-update.js` versión 5.10.3+ implementa esta búsqueda con prioridad por `mtime` y fallback a `package.json` del repo madre. Nunca asumir una sola ubicación de state — el CLI puede instalarse en combinaciones arbitrarias.
+
+## Después de instalar
+
+### Prerequisito Python: markitdown
+
+SWL instala la regla `markitdown.md` en `.claude/rules/` para que los agentes
+sepan convertir archivos `.docx`, `.xlsx`, `.pptx` e `.ipynb` a Markdown.
+La herramienta en sí requiere instalación manual una vez por máquina:
+
+```bash
+pip install markitdown[pdf,docx,pptx,xlsx]
+```
+
+Verificar que quedó correctamente instalada:
+```bash
+markitdown --version
+```
+
+> Sin este prerequisito los agentes pueden pedir al usuario el contenido en texto plano,
+> pero no podrán convertir archivos Office ni Jupyter automáticamente.
+
+### Comandos disponibles tras la instalación
+
+- `/swl:nuevo-proyecto` — iniciar proyecto desde cero
+- `/swl:mapear-codebase` — analizar código existente
+- `/swl:planear-fase` — planificar una fase de trabajo
+- `/swl:ejecutar-fase` — ejecutar plan con commits atómicos
+- `/swl:salud` — diagnóstico profundo del sistema

package/habilidades/java-experto/SKILL.md

@@ -0,0 +1,290 @@
+---
+name: java-experto
+description: >
+  Java moderno con Spring Boot, JPA/Hibernate, records, sealed classes y streams.
+  Cargar cuando se implementen servicios Spring Boot, entidades JPA, repositorios
+  Spring Data, lógica de negocio Java 17+ o se configure application.yml/profiles.
+version: "1.0.0"
+herramientasPermitidas: [Read, Grep]
+exclusiones:
+  - "No cargar para escribir tests JUnit o de integración Spring — para testing cargar `java-testing`."
+  - "No cargar para diseñar patrones Java avanzados (records, sealed classes, pattern matching) — para diseño cargar `java-patrones`."
+  - "No cargar para errores de compilación Java o Maven/Gradle — para build errors cargar `build-errors-java`."
+  - "No cargar para servicios Kotlin/Android — Kotlin tiene patrones distintos (coroutines, Compose); cargar `kotlin-experto`."
+evolvable: true  # default para skill estandar
+---
+# Java Experto — Spring Boot y Java Moderno
+
+Cubre el stack Java moderno: Spring Boot 3, JPA/Hibernate, Spring Data, records,
+sealed classes y Stream API avanzado. Aplica a servicios REST, acceso a datos y
+lógica de dominio en proyectos Java 17+.
+
+## Cuándo cargar este skill
+
+Invoca `Skill("java-experto")` cuando:
+
+- Se implementen controllers, services o repositories Spring Boot
+- Se definan entidades JPA o relaciones Hibernate
+- Se usen records como DTOs o value objects
+- Se configure Spring Profiles o application.yml
+- Se use Stream API con collectors, groupingBy o flatMap complejos
+- Se implemente concurrencia con CompletableFuture
+
+## Cuándo NO cargar
+
+- La tarea es escribir tests JUnit, MockMvc o de integración con TestContainers — para testing cargar `java-testing`.
+- La pregunta es sobre patrones Java modernos (records como value objects, sealed classes, pattern matching) — para diseño cargar `java-patrones`.
+- Los errores son de compilación Java, Maven o Gradle — para build errors cargar `build-errors-java`.
+- El proyecto es Kotlin/Android — Kotlin tiene patrones distintos (coroutines, Hilt, Compose); cargar `kotlin-experto`.
+
+## Conceptos clave
+
+### Spring Boot Autoconfiguration
+
+Spring Boot configura beans automáticamente según el classpath. El desarrollador
+declara dependencias; Spring Boot registra la infraestructura. Sobreescribir solo
+lo necesario con `@Bean` en una `@Configuration`.
+
+### JPA Entity Lifecycle
+
+Ciclo: Transient -> Managed -> Detached -> Removed. Un entity managed dentro de
+una transacción activa se sincroniza automáticamente al flush. Fuera de transacción
+es Detached y los cambios no persisten.
+
+### Records como DTOs
+
+Los records son inmutables, ideales para DTOs de request/response. No mezclar
+records con entidades JPA — las entidades requieren estado mutable y constructor
+sin argumentos.
+
+### Sealed Classes para dominios cerrados
+
+`sealed interface` + `permits` define un conjunto cerrado de subtipos conocidos
+en tiempo de compilación. Permite pattern matching exhaustivo en switch.
+
+## Reglas obligatorias
+
+### Separar entidad de DTO — NUNCA usar entity como DTO
+
+Exponer entidades JPA directamente en la API serializa relaciones no deseadas,
+rompe el encapsulamiento y crea dependencias de schema en el contrato de API.
+
+**Correcto**:
+```java
+// Entidad — solo para persistencia
+@Entity
+public class Pedido {
+    @Id @GeneratedValue UUID id;
+    @ManyToOne(fetch = FetchType.LAZY) Cliente cliente;
+    @OneToMany(mappedBy = "pedido", cascade = CascadeType.ALL)
+    List<ItemPedido> items;
+}
+
+// DTO — solo para transporte
+public record PedidoResponse(UUID id, String clienteNombre, List<ItemResponse> items) {}
+```
+
+### Inyectar por constructor — NUNCA @Autowired en campos
+
+La inyección en campos oculta dependencias, impide tests unitarios sin contenedor
+y viola el principio de inversión de dependencias.
+
+```java
+// MAL
+@Service
+public class PedidoService {
+    @Autowired private PedidoRepository repo; // no testeable sin contexto Spring
+}
+
+// BIEN
+@Service
+@RequiredArgsConstructor
+public class PedidoService {
+    private final PedidoRepository repo; // testeable con mock directo
+}
+```
+
+### Lógica en services — NUNCA en controllers
+
+El controller orquesta HTTP: valida input, delega al service, mapea respuesta.
+No contiene if/else de negocio, cálculos ni acceso directo a repositorios.
+
+### @Transactional solo donde hay escritura
+
+Anotar con `@Transactional(readOnly = true)` los métodos de solo lectura.
+Evitar `@Transactional` en la clase entera — propaga transacciones innecesarias
+y bloquea recursos.
+
+### FetchType.LAZY por defecto en relaciones
+
+`FetchType.EAGER` en `@ManyToOne` y `@OneToMany` ejecuta JOINs automáticos en
+cada query. Usar LAZY y cargar explícitamente con JOIN FETCH cuando se necesite.
+
+## Patrones recomendados
+
+### Controller delgado
+
+```java
+@RestController
+@RequestMapping("/v1/pedidos")
+@RequiredArgsConstructor
+public class PedidoController {
+    private final PedidoService service;
+
+    @PostMapping
+    @ResponseStatus(HttpStatus.CREATED)
+    public PedidoResponse crear(@Valid @RequestBody CrearPedidoRequest req) {
+        return service.crear(req);
+    }
+
+    @GetMapping("/{id}")
+    public PedidoResponse obtener(@PathVariable UUID id) {
+        return service.obtener(id)
+            .orElseThrow(() -> new ResponseStatusException(HttpStatus.NOT_FOUND));
+    }
+}
+```
+
+### Record como DTO con validación
+
+```java
+public record CrearPedidoRequest(
+    @NotNull UUID clienteId,
+    @NotEmpty List<@Valid ItemRequest> items
+) {}
+
+public record ItemRequest(
+    @NotNull UUID productoId,
+    @Positive int cantidad
+) {}
+```
+
+### Sealed interface para resultados de dominio
+
+```java
+public sealed interface ResultadoPago permits ResultadoPago.Aprobado,
+    ResultadoPago.Rechazado, ResultadoPago.Pendiente {
+
+    record Aprobado(String transaccionId) implements ResultadoPago {}
+    record Rechazado(String motivo) implements ResultadoPago {}
+    record Pendiente(Duration tiempoEstimado) implements ResultadoPago {}
+}
+
+// Uso con switch exhaustivo (no requiere default)
+String mensaje = switch (resultado) {
+    case ResultadoPago.Aprobado a -> "Aprobado: " + a.transaccionId();
+    case ResultadoPago.Rechazado r -> "Rechazado: " + r.motivo();
+    case ResultadoPago.Pendiente p -> "Pendiente " + p.tiempoEstimado();
+};
+```
+
+### Stream API con collectors avanzados
+
+```java
+// groupingBy con downstream collector
+Map<String, DoubleSummaryStatistics> estadisticasPorCategoria = productos.stream()
+    .collect(Collectors.groupingBy(
+        Producto::categoria,
+        Collectors.summarizingDouble(Producto::precio)
+    ));
+
+// partitioningBy para bifurcar
+Map<Boolean, List<Pedido>> pedidosPorEstado = pedidos.stream()
+    .collect(Collectors.partitioningBy(p -> p.estatus() == Estatus.COMPLETADO));
+```
+
+### CompletableFuture para operaciones paralelas
+
+```java
+CompletableFuture<Cliente> clienteFuture = CompletableFuture
+    .supplyAsync(() -> clienteService.obtener(clienteId), executor);
+
+CompletableFuture<List<Producto>> productosFuture = CompletableFuture
+    .supplyAsync(() -> productoService.listar(filtro), executor);
+
+return clienteFuture.thenCombine(productosFuture,
+    (cliente, productos) -> new ResumenResponse(cliente, productos))
+    .get(5, TimeUnit.SECONDS);
+```
+
+## Anti-patrones conocidos
+
+### Optional.get() sin verificar — NUNCA hacer esto
+
+```java
+// MAL — lanza NoSuchElementException si esta vacio
+Optional<Usuario> u = repo.findById(id);
+return u.get(); // excepcion silenciosa
+
+// BIEN
+return repo.findById(id)
+    .orElseThrow(() -> new NotFoundException("Usuario no encontrado: " + id));
+```
+
+### Transacción demasiado larga
+
+```java
+// MAL — transaccion abierta durante llamada HTTP externa
+@Transactional
+public void procesarPedido(UUID id) {
+    Pedido pedido = repo.findById(id).orElseThrow();
+    String token = pagoExternoClient.obtenerToken(); // llamada HTTP dentro de tx
+    pedido.marcarEnProceso(token);
+}
+
+// BIEN — llamada externa fuera de transaccion
+public void procesarPedido(UUID id) {
+    String token = pagoExternoClient.obtenerToken(); // fuera de tx
+    guardarToken(id, token);                         // tx minima
+}
+
+@Transactional
+private void guardarToken(UUID id, String token) {
+    Pedido pedido = repo.findById(id).orElseThrow();
+    pedido.marcarEnProceso(token);
+}
+```
+
+### Null en colecciones
+
+```java
+// MAL — NullPointerException en iteracion
+List<String> tags = null;
+tags.forEach(System.out::println);
+
+// BIEN — colecciones vacias en lugar de null
+List<String> tags = Collections.emptyList();
+// o en entidad JPA
+@OneToMany
+List<Tag> tags = new ArrayList<>();
+```
+
+## Checklist de verificación
+
+- [ ] Entidades JPA no se exponen directamente como response body
+- [ ] Toda inyección es por constructor (no @Autowired en campos)
+- [ ] @Transactional solo en métodos de escritura; readOnly=true en consultas
+- [ ] FetchType.LAZY en todas las relaciones; JOIN FETCH explicito cuando se necesite
+- [ ] Controllers sin lógica de negocio: solo validación + delegación + mapeo
+- [ ] Optional usado con orElseThrow o orElse, nunca con .get() directo
+- [ ] Colecciones inicializadas vacías, nunca null
+
+## Referencias
+
+- Spring Boot Reference: https://docs.spring.io/spring-boot/docs/current/reference/html/
+- JPA Spec (Jakarta Persistence 3.1): https://jakarta.ee/specifications/persistence/
+- Java Records JEP 395: https://openjdk.org/jeps/395
+- Sealed Classes JEP 409: https://openjdk.org/jeps/409
+
+## Gotchas / Errores comunes no obvios
+
+**`@Transactional` en un método privado o llamado desde la misma clase no activa la transacción**: Spring implementa `@Transactional` con un proxy AOP — si el método es privado o se llama con `this.metodo()` desde la misma clase, el proxy no intercepta la llamada y no hay transacción. Fix: mover el método anotado a otro bean, o inyectar la misma clase (self-injection) como dependencia para forzar el paso por el proxy.
+
+**`FetchType.LAZY` con serialización JSON lanza `LazyInitializationException` en colecciones no cargadas**: si una entidad con relación lazy se serializa a JSON fuera de una sesión Hibernate abierta (por ejemplo, después de que el método `@Transactional` ya retornó), Jackson intenta acceder a la colección lazy y Hibernate lanza la excepción. Fix: usar DTOs y mapear explícitamente los datos necesarios dentro de la transacción, o configurar `spring.jpa.open-in-view=false` y manejar la carga en el service.
+
+**`Optional.get()` sin `isPresent()` lanza `NoSuchElementException` en lugar de `NullPointerException`**: el propósito de `Optional` es reemplazar null, pero usar `.get()` directamente reproduce el mismo problema con un tipo de excepción diferente. Fix: usar siempre `.orElseThrow(() -> new EntidadNotFoundException(...))` para dar un mensaje de error semántico, nunca `.get()` directo.
+
+**Records no pueden ser entidades JPA**: `@Entity record Producto(String nombre)` compila pero falla en runtime porque JPA requiere un constructor sin parámetros y campos mutables. Cause: los records son inmutables por diseño. Fix: usar records solo como DTOs de transferencia; definir entidades JPA como clases con `@Entity`, `@Id` y campos anotados.
+
+---
+*Skill creado con swl:crear-skill el 2026-03-31. Versión 1.0.0.*