@saulwade/swl-ses 1.8.0 → 2.0.0

package/habilidades/estructura-proyecto-claude/recursos/configuracion-y-extensiones.md

@@ -28,41 +28,42 @@ completos de settings.json, .mcp.json, plugins y checklists detallados.
     "PreToolUse": [
       {
         "matcher": "Bash",
-        "type": "command",
-        "command": "node .claude/hooks/lint-check.js"
+        "hooks": [
+          { "type": "command", "command": "node .claude/hooks/lint-check.js" }
+        ]
       }
     ],
     "PostToolUse": [
       {
         "matcher": "Write",
-        "type": "command",
-        "command": "node .claude/hooks/format-on-save.js"
+        "hooks": [
+          { "type": "command", "command": "node .claude/hooks/format-on-save.js" }
+        ]
       }
     ],
     "SessionStart": [
       {
         "matcher": "startup",
-        "type": "command",
-        "command": "node .claude/hooks/load-context.js"
+        "hooks": [
+          { "type": "command", "command": "node .claude/hooks/load-context.js" }
+        ]
       }
     ]
-  },
-  "context": {
-    "rules": [
-      "CLAUDE.md"
-    ]
   }
 }
 ```
 
 ### Jerarquía de settings (mayor a menor prioridad)
 
-1. **Managed** (MDM plist / Registry / Server-managed / `managed-settings.d/`)
+1. **Managed** (MDM plist / Registry / Server-managed / `managed-settings.json`)
 2. **CLI arguments** (solo sesión actual)
 3. **`.claude/settings.local.json`** (personal, git-ignored)
 4. **`.claude/settings.json`** (equipo, commiteado)
 5. **`~/.claude/settings.json`** (global personal)
 
+**Excepción**: los `permissions` (allow/deny) se **fusionan** entre scopes, no se
+sobreescriben por precedencia simple.
+
 ---
 
 ## Settings avanzados y variables de entorno
@@ -90,13 +91,20 @@ Settings poco documentados pero de alto impacto:
 
 | Flag | Efecto |
 |------|--------|
-| `--bare` | Arranque hasta 10x más rápido — omite carga de CLAUDE.md y skills. Útil para scripts |
-| `--add-dir <path>` | Agregar directorio adicional a la sesión — sesiones multi-repo sin copiar archivos |
-| `-w` / `--worktree` | Git worktree aislado — cada sesión en su propia rama |
-| `--agent=<nombre>` | Usar agente custom como agente principal de la sesión |
-| `--effort high` | Nivel de esfuerzo alto para todas las respuestas |
-| `/sandbox` | Reduce 84% los diálogos de permisos — sandbox seguro para exploración |
-```
+| `--bare` | Modo mínimo: omite auto-discovery de hooks, skills, plugins, MCP servers, auto memory y CLAUDE.md — arranque más rápido para scripts |
+| `--add-dir <path>` | Agregar directorio adicional a la sesión — sesiones multi-repo sin copiar archivos. Los CLAUDE.md de esos directorios NO se cargan por defecto (`CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1` para cargarlos) |
+| `-w` / `--worktree` | Git worktree aislado en `<repo>/.claude/worktrees/<nombre>` |
+| `--agent <nombre>` | Usar agente custom como agente principal de la sesión |
+| `--effort <nivel>` | Nivel de esfuerzo de la sesión: `low`, `medium`, `high`, `xhigh`, `max` |
+| `--max-budget-usd <n>` | Tope de gasto en API antes de detenerse (solo print mode) |
+
+### Comando `/sandbox` (Bash sandbox)
+
+Abre el panel del sandbox de Bash: aislamiento de filesystem y red **a nivel de SO**
+(Seatbelt en macOS, bubblewrap en Linux/WSL2 — no soportado en Windows nativo). En modo
+auto-allow, los comandos sandboxeados corren sin diálogos de permiso; los que requieren
+acceso fuera del boundary caen al flujo regular de permisos. Configuración persistente
+vía `sandbox.enabled` y `sandbox.filesystem.*` en settings.json.
 
 ---
 
@@ -110,18 +118,21 @@ Settings poco documentados pero de alto impacto:
       "args": ["-y", "@upstash/context7-mcp@latest"]
     },
     "github": {
-      "command": "npx",
-      "args": ["-y", "@modelcontextprotocol/server-github"],
-      "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "" }
+      "type": "http",
+      "url": "https://api.githubcopilot.com/mcp/"
     },
     "playwright": {
       "command": "npx",
-      "args": ["-y", "@anthropic/mcp-playwright"]
+      "args": ["-y", "@playwright/mcp@latest"]
     }
   }
 }
 ```
 
+> El GitHub MCP server oficial es remoto (`api.githubcopilot.com/mcp/`) — el paquete
+> npm `@modelcontextprotocol/server-github` fue archivado. El de Playwright oficial
+> es `@playwright/mcp` (Microsoft).
+
 Ver catalogo completo en [mcp-json-template.json](mcp-json-template.json).
 
 ---

package/habilidades/estructura-proyecto-claude/recursos/frontmatter-y-hooks-referencia.md

@@ -4,19 +4,23 @@ Fuente: https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overvi
 
 ---
 
-## Frontmatter completo de SKILL.md (12 campos)
+## Frontmatter completo de SKILL.md (16 campos — aplica también a commands, que se fusionaron con skills)
 
 | Campo | Requerido | Tipo | Descripción |
 |-------|-----------|------|-------------|
-| `name` | No* | string | Nombre kebab-case, max 64 chars. Se convierte en `/nombre` para invocación. *Si se omite, usa el nombre del directorio |
-| `description` | Recomendado | string | Max 1024 chars. QUÉ hace + CUÁNDO usar. Guía la auto-activación de Claude |
+| `name` | No* | string | Nombre mostrado en listados. *Si se omite, usa el nombre del directorio |
+| `description` | Recomendado | string | QUÉ hace + CUÁNDO usar. Guía la auto-activación. `description` + `when_to_use` se truncan a 1,536 chars combinados en el listado |
+| `when_to_use` | Opcional | string | Contexto adicional de activación (frases trigger, ejemplos). Se anexa a `description` y cuenta para el tope de 1,536 chars |
 | `argument-hint` | Opcional | string | Hint de autocompletado: `[archivo]`, `[issue-num]`, `[file] [format]` |
-| `allowed-tools` | Opcional | array | Tools que Claude puede usar sin pedir permiso cuando la skill está activa |
+| `arguments` | Opcional | array/string | Argumentos posicionales con nombre para sustitución `$nombre` en el contenido |
+| `allowed-tools` | Opcional | array/string | Tools que Claude puede usar sin pedir permiso cuando la skill está activa |
+| `disallowed-tools` | Opcional | array/string | Tools removidas del pool de Claude mientras la skill está activa |
 | `paths` | Opcional | array/string | Patrones glob: cargar skill SOLO al trabajar con archivos que coinciden |
 | `context` | Opcional | string | `fork` = ejecutar en subagente aislado con su propia conversación |
 | `agent` | Opcional | string | Tipo de subagente si `context: fork` (Explore, Plan, general-purpose) |
-| `model` | Opcional | string | Override de modelo para esta skill |
-| `effort` | Opcional | string | Nivel de esfuerzo: `low`, `medium`, `high`, `max` (Opus only) |
+| `model` | Opcional | string | Override de modelo mientras la skill está activa (mismos valores que `/model`, o `inherit`) |
+| `effort` | Opcional | string | Nivel de esfuerzo: `low`, `medium`, `high`, `xhigh`, `max` (los niveles disponibles dependen del modelo) |
+| `hooks` | Opcional | object | Hooks acotados al ciclo de vida de esta skill |
 | `shell` | Opcional | string | `bash` o `powershell`. Controla bloques `!comando` embebidos |
 | `disable-model-invocation` | Opcional | boolean | `true` = solo el usuario puede invocar (no auto-trigger). Usar para skills con side-effects como `/deploy` |
 | `user-invocable` | Opcional | boolean | `false` = solo Claude la ve (conocimiento de background). No aparece en menú `/` |
@@ -46,21 +50,24 @@ user-invocable: true
 
 | Variable | Valor |
 |----------|-------|
-| `$ARGUMENTS` | Argumentos pasados al invocar la skill |
-| `$0`, `$1`, `$2`... | Argumentos posicionales |
+| `$ARGUMENTS` | Todos los argumentos pasados al invocar la skill (si no aparece, se anexan como `ARGUMENTS: <valor>`) |
+| `$ARGUMENTS[N]` | Argumento específico por índice 0-based |
+| `$0`, `$1`, `$2`... | Shorthand de `$ARGUMENTS[N]` |
+| `$nombre` | Argumento con nombre declarado en `arguments:` del frontmatter |
 | `${CLAUDE_SESSION_ID}` | ID unico de la sesion actual |
+| `${CLAUDE_EFFORT}` | Nivel de esfuerzo activo (`low`...`max`) |
 | `${CLAUDE_SKILL_DIR}` | Path absoluto al directorio de la skill |
-| `${env:VAR_NAME}` | Variable de entorno del sistema |
 
 ---
 
-## 25 Hook Events oficiales
+## 30 Hook Events oficiales
 
 ### Ciclo de vida de sesión
 
 | Evento | Cuándo se dispara | Matchers | Uso típico |
 |--------|-------------------|----------|-----------|
 | `SessionStart` | Al iniciar o resumir sesión | `startup`, `resume`, `clear`, `compact` | Cargar contexto, setup env |
+| `Setup` | Inicialización one-time (`--init-only`, `--maintenance`) | `init`, `maintenance` | Bootstrap de repo, mantenimiento |
 | `SessionEnd` | Al terminar sesión | `clear`, `resume`, `logout`, `other` | Cleanup, archivado |
 | `InstructionsLoaded` | CLAUDE.md o rules/ cargados | `session_start`, `nested_traversal`, `path_glob_match`, `include`, `compact` | Log que instrucciones se cargaron |
 
@@ -71,7 +78,9 @@ user-invocable: true
 | `PreToolUse` | Antes de ejecutar herramienta | Nombre de tool (Bash, Edit, Read, mcp__*) | Bloquear ops inseguras, validar |
 | `PostToolUse` | Después de ejecutar herramienta (éxito) | Nombre de tool | Auto-lint, format, log |
 | `PostToolUseFailure` | Cuando falla herramienta | Nombre de tool | Notificar, reintentar |
+| `PostToolBatch` | Al resolver un batch completo de tool calls paralelos | Ninguno | Métricas de batch |
 | `PermissionRequest` | Se muestra diálogo de permiso | Nombre de tool | Auto-aprobar acciones seguras |
+| `PermissionDenied` | El clasificador de auto mode niega un tool call | Nombre de tool | Log, escalar |
 
 ### Respuesta y control
 
@@ -80,6 +89,8 @@ user-invocable: true
 | `Stop` | Claude termina de responder | Ninguno (siempre se dispara) | Verificar tarea completa |
 | `StopFailure` | Error de API en Stop | `rate_limit`, `authentication_failed`, `billing_error`, `server_error` | Notificar fallos |
 | `UserPromptSubmit` | Usuario envía prompt | Ninguno | Interceptar/enriquecer input |
+| `UserPromptExpansion` | Un comando del usuario se expande a prompt | Ninguno | Transformar input |
+| `MessageDisplay` | Mientras se muestra texto del asistente | Ninguno | Modificar texto en pantalla |
 
 ### Compactación de contexto
 
@@ -135,44 +146,40 @@ user-invocable: true
 
 ## Frontmatter completo de agents (.claude/agents/*.md) — 16 campos
 
-| Campo | Tipo | Descripción |
-|-------|------|-------------|
-| `name` | string | Nombre kebab-case del agente |
-| `description` | string | Cuándo invocarlo — usar `"PROACTIVELY"` para invocación eager |
-| `model` | string | Override de modelo (`sonnet`, `haiku`, `opus`) |
-| `color` | string | Color del agente en terminal (green, blue, red, etc.) |
-| `maxTurns` | number | Máximo de turnos antes de terminar |
-| `permissionMode` | string | `acceptEdits`, `dontAsk`, `plan`, `default` |
-| `memory` | string | `project`, `user`, `local`, `none` |
-| `skills` | array | Skills precargados como conocimiento de background |
-| `isolation` | string | `worktree` = rama git aislada por ejecución |
-| `allowed-tools` | array | Herramientas permitidas sin pedir permiso |
-| `hooks` | object | Hooks específicos del agente (SubagentStop, PreToolUse, etc.) |
-| `stop` | string | Instrucción de cuándo detenerse |
-| `shell` | string | `bash` o `powershell` |
-| `effort` | string | `low`, `medium`, `high`, `max` |
-| `disable-model-invocation` | boolean | Solo invocación manual |
-| `user-invocable` | boolean | Visible en menú o solo invocable por Claude |
-
-**Gotcha**: El evento `Stop` en frontmatter de agente se dispara como `SubagentStop`, no como `Stop`.
+| Campo | Requerido | Tipo | Descripción |
+|-------|-----------|------|-------------|
+| `name` | Sí | string | Identificador único en minúsculas con guiones. Los hooks lo reciben como `agent_type` |
+| `description` | Sí | string | Cuándo Claude debe delegar a este subagente |
+| `tools` | No | array | Tools que el subagente puede usar. Hereda todas si se omite. Para precargar skills usar `skills`, no listar `Skill` aquí |
+| `disallowedTools` | No | array | Tools negadas — se remueven de la lista heredada o especificada |
+| `model` | No | string | `sonnet`, `opus`, `haiku`, `fable`, un model ID completo, o `inherit` (default) |
+| `permissionMode` | No | string | `default`, `acceptEdits`, `auto`, `dontAsk`, `bypassPermissions`, `plan` |
+| `maxTurns` | No | number | Máximo de turnos agénticos antes de detenerse |
+| `skills` | No | array | Skills precargadas al contexto al inicio (se inyecta el contenido completo) |
+| `mcpServers` | No | array/object | MCP servers disponibles para este subagente (nombre de server ya configurado o definición inline) |
+| `hooks` | No | object | Hooks acotados al ciclo de vida del subagente (`Stop` se convierte en `SubagentStop` en runtime) |
+| `memory` | No | string | Memoria persistente cross-sesión: `user`, `project`, `local` |
+| `background` | No | boolean | `true` = siempre corre como background task |
+| `effort` | No | string | `low`, `medium`, `high`, `xhigh`, `max` — override del nivel de sesión |
+| `isolation` | No | string | `worktree` = git worktree temporal aislado (auto-limpiado si no hay cambios) |
+| `color` | No | string | Color en task list/transcript: `red`, `blue`, `green`, `yellow`, `purple`, `orange`, `pink`, `cyan` |
+| `initialPrompt` | No | string | Primer turno auto-enviado cuando el agente corre como agente principal (`--agent`) |
+
+**Gotcha**: El evento `Stop` declarado en `hooks:` de un agente se dispara como `SubagentStop`, no como `Stop`.
 
 ---
 
-## Frontmatter de commands (.claude/commands/*.md) — 13 campos
+## Frontmatter de commands (.claude/commands/*.md)
 
-| Campo | Tipo | Descripción |
-|-------|------|-------------|
-| `name` | string | Se convierte en `/nombre` (o subcarpeta: `/dir:nombre`) |
-| `description` | string | Descripción mostrada en autocompletado |
-| `argument-hint` | string | Hint visual: `[archivo]`, `[issue-num]` |
-| `allowed-tools` | array | Tools permitidos sin pedir permiso |
-| `model` | string | Override de modelo |
-| `effort` | string | Nivel de esfuerzo |
-| `shell` | string | `bash` o `powershell` |
-| `user-invocable` | boolean | Default `true` — commands siempre son user-invocable |
-| `disable-model-invocation` | boolean | `true` = Claude no puede auto-invocar |
+**Los commands se fusionaron con las skills**: un archivo en `.claude/commands/deploy.md`
+y una skill en `.claude/skills/deploy/SKILL.md` crean ambos `/deploy` y funcionan igual.
+Los archivos existentes en `.claude/commands/` siguen funcionando y aceptan el **mismo
+frontmatter de 16 campos de SKILL.md** (ver tabla arriba).
 
-**Diferencia clave**: commands NUNCA se auto-invocan — siempre requieren `/nombre` del usuario.
+Las skills agregan sobre los commands legacy: directorio de archivos de apoyo,
+control de invocación (`disable-model-invocation`, `user-invocable`) y auto-activación
+por relevancia. Para forzar que un comando NUNCA se auto-invoque (comportamiento
+del command clásico), declarar `disable-model-invocation: true`.
 
 ---
 
@@ -195,6 +202,7 @@ porque se ejecuta inline sin el overhead de un subagente.
 | `prompt` | Claude decide qué hacer | `"prompt": "Verifica que el archivo..."` |
 | `agent` | Claude con herramientas propias | `"agent": "Analiza y corrige..."` |
 | `http` | POST a endpoint HTTP | `"url": "https://webhook.example.com/hook"` |
+| `mcp_tool` | Llama una tool de un MCP server configurado | `"server": "slack", "tool": "send_message"` |
 
 ### Códigos de retorno para hooks command
 
@@ -209,22 +217,31 @@ porque se ejecuta inline sin el overhead de un subagente.
 | Opción | Tipo | Descripción |
 |--------|------|-------------|
 | `async` | boolean | Ejecutar en background sin bloquear — fire-and-forget |
-| `timeout` | number | Timeout en ms (default varía por evento) |
-| `once` | boolean | Ejecutar solo la primera vez que el evento ocurre |
-| `asyncRewake` | boolean | Re-despertar al agente cuando el hook async termina |
-| `statusMessage` | string | Mensaje mostrado mientras el hook ejecuta |
-| `if` | string | Condicional (v2.1.85+) — solo ejecutar si la condición se cumple |
+| `timeout` | number | Timeout en **segundos** (defaults: 600 command/http/mcp_tool, 30 prompt, 60 agent) |
+| `once` | boolean | Ejecutar una sola vez por sesión y removerse (solo en hooks de frontmatter de skill) |
+| `asyncRewake` | boolean | Background + re-despertar a Claude si el hook sale con exit code 2 (implica `async`) |
+| `statusMessage` | string | Mensaje del spinner mientras el hook ejecuta |
+| `if` | string | Filtro con sintaxis de regla de permisos: `"Bash(git *)"`, `"Edit(*.ts)"` |
 
 ### Campos JSON de retorno del hook
 
+Campos universales (nivel superior):
+
+| Campo | Tipo | Efecto |
+|-------|------|--------|
+| `continue` | boolean | `false` = detener el procesamiento por completo |
+| `stopReason` | string | Mensaje mostrado cuando `continue: false` |
+| `suppressOutput` | boolean | Ocultar el stdout del hook del transcript |
+| `systemMessage` | string | Mensaje de advertencia mostrado al usuario |
+
+Campos dentro de `hookSpecificOutput` (con `hookEventName` obligatorio):
+
 | Campo | Tipo | Efecto |
 |-------|------|--------|
-| `continue` | boolean | `false` = detener la cadena de hooks |
-| `stopReason` | string | Razón de detención (si `continue: false`) |
-| `suppressOutput` | boolean | No mostrar output del hook al usuario |
-| `systemMessage` | string | Inyectar mensaje al contexto del sistema |
 | `additionalContext` | string | Agregar contexto adicional a la conversación |
-| `updatedInput` | object | Solo PreToolUse — modificar el input de la herramienta antes de ejecución |
+| `updatedInput` | object | Reescribir el input de la herramienta (PreToolUse, PostToolUse) |
+| `updatedToolOutput` | object | Reescribir el output de la herramienta (PostToolUse) |
+| `permissionDecision` | string | Solo PreToolUse: `allow`, `deny`, `ask`, `defer` |
 
 ---
 

package/habilidades/estructura-proyecto-claude/recursos/mcp-json-template.json

@@ -1,77 +1,57 @@
-{
-  "_comentario": "Template de .mcp.json para proyectos Claude-ready. Eliminar los servidores que no se usen. Las variables de entorno con valor vacío deben completarse en .env o exportarse antes de correr claude.",
-  "_instrucciones": [
-    "1. Copiar este archivo a la raíz del proyecto como .mcp.json",
-    "2. Eliminar el bloque _comentario y _instrucciones (no son JSON válido en producción)",
-    "3. Configurar las variables de entorno requeridas por cada servidor activo",
-    "4. Agregar .mcp.json al repositorio (no contiene secretos — los secretos van en env vars)",
-    "5. Agregar a .gitignore cualquier archivo .mcp.local.json con credenciales"
-  ],
-  "mcpServers": {
-    "context7": {
-      "_descripcion": "Documentación actualizada de librerías. Uso: 'use context7' en el prompt.",
-      "command": "npx",
-      "args": ["-y", "@upstash/context7-mcp@latest"]
-    },
-    "github": {
-      "_descripcion": "Acceso a GitHub: issues, PRs, repos, commits. Requiere token con permisos repo.",
-      "command": "npx",
-      "args": ["-y", "@modelcontextprotocol/server-github"],
-      "env": {
-        "GITHUB_PERSONAL_ACCESS_TOKEN": ""
-      }
-    },
-    "filesystem": {
-      "_descripcion": "Acceso a sistema de archivos fuera del directorio de trabajo. Usar con cuidado.",
-      "_activar": "Descomentar solo si se necesita acceso a paths fuera del proyecto",
-      "command": "npx",
-      "args": [
-        "-y",
-        "@modelcontextprotocol/server-filesystem",
-        "/ruta/al/directorio/permitido"
-      ]
-    },
-    "postgres": {
-      "_descripcion": "Acceso de solo lectura a PostgreSQL. Útil para explorar esquemas y datos.",
-      "_activar": "Descomentar si el proyecto usa PostgreSQL y se requiere introspección de BD",
-      "command": "npx",
-      "args": ["-y", "@modelcontextprotocol/server-postgres"],
-      "env": {
-        "POSTGRES_CONNECTION_STRING": "postgresql://usuario:password@localhost:5432/nombre_bd"
-      }
-    },
-    "sqlite": {
-      "_descripcion": "Acceso a base de datos SQLite. Alternativa ligera a postgres para proyectos pequeños.",
-      "_activar": "Descomentar si el proyecto usa SQLite",
-      "command": "npx",
-      "args": ["-y", "@modelcontextprotocol/server-sqlite", "--db-path", "./data.db"]
-    },
-    "brave-search": {
-      "_descripcion": "Búsqueda web con Brave Search API. Útil para investigación técnica durante desarrollo.",
-      "_activar": "Requiere API key de Brave Search (plan gratuito disponible)",
-      "command": "npx",
-      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
-      "env": {
-        "BRAVE_API_KEY": ""
-      }
-    },
-    "memory": {
-      "_descripcion": "Memoria persistente entre sesiones. Almacena entidades y relaciones en grafo.",
-      "_activar": "Útil para proyectos largos donde se quiere persistir contexto entre sesiones",
-      "command": "npx",
-      "args": ["-y", "@modelcontextprotocol/server-memory"]
-    },
-    "puppeteer": {
-      "_descripcion": "Control de navegador. Útil para testing E2E, scraping o automatización web.",
-      "_activar": "Requiere Chrome/Chromium instalado",
-      "command": "npx",
-      "args": ["-y", "@modelcontextprotocol/server-puppeteer"]
-    },
-    "sequential-thinking": {
-      "_descripcion": "Herramienta de razonamiento estructurado para problemas complejos.",
-      "_activar": "Útil para arquitectura, debugging complejo, decisiones de diseño",
-      "command": "npx",
-      "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"]
-    }
-  }
-}
+{
+  "_comentario": "Template de .mcp.json para proyectos Claude-ready. Eliminar los servidores que no se usen. Las variables de entorno con valor vacío deben completarse en .env o exportarse antes de correr claude.",
+  "_instrucciones": [
+    "1. Copiar este archivo a la raíz del proyecto como .mcp.json",
+    "2. Eliminar el bloque _comentario y _instrucciones (no son JSON válido en producción)",
+    "3. Configurar las variables de entorno requeridas por cada servidor activo",
+    "4. Agregar .mcp.json al repositorio (no contiene secretos — los secretos van en env vars)",
+    "5. Agregar a .gitignore cualquier archivo .mcp.local.json con credenciales"
+  ],
+  "_nota_archivados": "Los reference servers @modelcontextprotocol/server-github, server-postgres, server-sqlite, server-brave-search y server-puppeteer fueron ARCHIVADOS por el proyecto MCP. No usarlos en proyectos nuevos — los reemplazos vigentes están abajo (GitHub remoto oficial, Playwright oficial de Microsoft).",
+  "mcpServers": {
+    "context7": {
+      "_descripcion": "Documentación actualizada de librerías. Uso: 'use context7' en el prompt.",
+      "command": "npx",
+      "args": ["-y", "@upstash/context7-mcp@latest"]
+    },
+    "github": {
+      "_descripcion": "GitHub MCP server oficial (remoto): issues, PRs, repos, commits. Reemplaza al archivado @modelcontextprotocol/server-github. Autenticación OAuth al conectar, o PAT vía header.",
+      "type": "http",
+      "url": "https://api.githubcopilot.com/mcp/"
+    },
+    "playwright": {
+      "_descripcion": "Control de navegador con Playwright (oficial de Microsoft). Testing E2E, scraping, automatización web. Reemplaza al archivado server-puppeteer.",
+      "_activar": "Requiere Node 18+ — descarga browsers en el primer uso",
+      "command": "npx",
+      "args": ["-y", "@playwright/mcp@latest"]
+    },
+    "filesystem": {
+      "_descripcion": "Acceso a sistema de archivos fuera del directorio de trabajo. Usar con cuidado.",
+      "_activar": "Descomentar solo si se necesita acceso a paths fuera del proyecto",
+      "command": "npx",
+      "args": [
+        "-y",
+        "@modelcontextprotocol/server-filesystem",
+        "/ruta/al/directorio/permitido"
+      ]
+    },
+    "fetch": {
+      "_descripcion": "Extracción y conversión de contenido web a markdown.",
+      "_activar": "Útil cuando WebFetch nativo no basta (contenido que requiere conversión estructurada)",
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-fetch"]
+    },
+    "memory": {
+      "_descripcion": "Memoria persistente entre sesiones. Almacena entidades y relaciones en grafo.",
+      "_activar": "Útil para proyectos largos donde se quiere persistir contexto entre sesiones",
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-memory"]
+    },
+    "sequential-thinking": {
+      "_descripcion": "Herramienta de razonamiento estructurado para problemas complejos.",
+      "_activar": "Útil para arquitectura, debugging complejo, decisiones de diseño",
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"]
+    }
+  }
+}

package/habilidades/extractor-de-aprendizajes/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: extractor-de-aprendizajes
 description: Convertir errores y patrones descubiertos durante la implementación en nuevas habilidades o reglas. Ciclo de mejora continua del sistema SWL.
-version: "1.0.5"
+version: "1.0.6"
 herramientasPermitidas: [Read]
 exclusiones:
   - "No cargar para actualizar el perfil del usuario — las correcciones explícitas del usuario van a `instintos/perfil-usuario.yaml` vía `perfilador-usuario-swl`, no a APRENDIZAJES.md."
@@ -10,10 +10,10 @@ exclusiones:
   - "No cargar si el aprendizaje no tiene causa raíz identificada — documentar síntoma sin causa produce reglas que no previenen el error real."
 evolvable: true  # default para skill estandar
 evolved: true
-evolved-from: "1.0.4"
-evolved-at: "2026-05-12"
+evolved-from: "1.0.5"
+evolved-at: "2026-06-11"
 evolved-by: "aprender"
-evolved-note: "Backport L-140 SIGM: extender gotcha sub-agentes a Modo C (revisor-codigo-swl reporta ubicaciones incorrectas y severidades subestimadas); CONFIRMADO x4 → x5"
+evolved-note: "Modo D del gotcha sub-agentes (CONFIRMADO x5 → x6): agentes de documentación (claude-code-guide) emiten veredictos NO-SOPORTADO por inferencia del contexto local sin consultar la doc oficial; exigir cita a doc consultada en el turno. Precedente 2026-05-15 (runtimes Cursor/Codex)"
 ---
 # Extractor de Aprendizajes
 
@@ -296,7 +296,7 @@ Durante `/swl:aprender`, aplicar estas reglas:
 - **`rating: HIGH` asignado sin verificar criterio de irreversibilidad**: el agente promueve a CLAUDE.md un aprendizaje "MEDIUM" por el entusiasmo del momento. Causa: no se aplicó el criterio de "decisión irreversible o bug crítico". Solución: antes de asignar HIGH, verificar: ¿cambiar esto en el futuro requeriría refactorizar múltiples archivos o migrar datos? Si no, mantener MEDIUM.
 - **Regla incompleta sobre registro de hooks**: una entrada en memoria dice "registrar en modulos.json" pero omite `hooks-config.json`, y en la siguiente iteración se repite el fallo en CI porque ambos manifiestos son obligatorios. Causa: la regla de la lección anterior no cubrió todos los manifiestos afectados. Solución: al documentar una regla sobre registro en manifiestos, listar EXPLÍCITAMENTE cada manifiesto con su responsabilidad distinta (`modulos.json` = qué copiar; `hooks-config.json` = cómo registrar evento). Evidencia: tres incidentes históricos del mismo patrón incompleto (v5.7.1, v5.7.2/3, v5.11.0).
 - **Inventario estimado a mano en vez de regenerar**: el agente cuenta "28 hooks" visualmente y propaga la cifra a 5 archivos (CLAUDE/README/package/plugin/SALUD); al regenerar con `scripts/generar-inventario.js` el número real es 30. Causa: confiar en la observación directa en vez de la fuente de verdad determinista. Solución: antes de modificar cualquier contador en documentación oficial, ejecutar el script de inventario y usar su salida como ground truth.
-- **Sub-agentes (Explore + revisores) reportan afirmaciones factuales no verificadas sobre el código** [CONFIRMADO x5]: aplica a `Explore`, `revisor-codigo-swl`, `revisor-seguridad-swl`, `investigador-swl`, `planificador-swl`, y en general a cualquier sub-agente que reporte hallazgos sobre código del proyecto destino. **Tres modos de falla observados**:
+- **Sub-agentes (Explore + revisores + agentes de documentación) reportan afirmaciones factuales no verificadas** [CONFIRMADO x6]: aplica a `Explore`, `revisor-codigo-swl`, `revisor-seguridad-swl`, `investigador-swl`, `planificador-swl`, `claude-code-guide`, y en general a cualquier sub-agente que reporte hallazgos sobre código o capacidades de herramientas. **Cuatro modos de falla observados**:
 
   **Modo A — papers académicos** (sesión 2026-04-25): sub-agente Explore propuso 50h+ para implementar SPRT + Lyapunov + compositionality theorem del paper Bhardwaj 2026; costo real validado fue ~5h (solo Drift Score + Recovery Catalog). Causa: el Explore evalúa portabilidad técnica sin aplicar filtro de "datos disponibles" ni "infraestructura zero-deps". Evidencia: 3 papers analizados (evolver, Bhardwaj 2026, Zhang et al. 2026) con descarte sistemático ~70-90% del contenido propuesto.
 
@@ -304,6 +304,8 @@ Durante `/swl:aprender`, aplicar estas reglas:
 
   **Modo C — revisores reportan ubicaciones y severidades incorrectas en código del proyecto** (sesión 2026-05-12 SIGM): `revisor-codigo-swl` ejecutado en `/swl:verificar --until-converge` reportó dos errores factuales: (1) **ubicación incorrecta**: "deferred import en `caja/router.py:545`" cuando la línea real estaba en `caja/service.py:545` — el archivo `caja/router.py` solo tiene 157 líneas (`wc -l caja/router.py = 157`); (2) **severidad subestimada**: reportó "mismatch `CobroConsolidadoResponse` en pantalla de éxito" como MAYOR, mi auditoría manual descubrió que `CobroConsolidadoRequest` también estaba completamente desalineado (más grave, debería ser CRÍTICO bloqueante) — el revisor solo miró el Response. Causa: el revisor analiza código sin re-verificar el path/línea/extensión reportada cuando produce el reporte; sub-agentes basados en LLM hallucinan números de línea con frecuencia ≥15% en archivos grandes.
 
+  **Modo D — agentes de documentación responden por inferencia del contexto local sin consultar la fuente oficial** (sesión 2026-06-11 swl-ses Fase 09; precedente 2026-05-15 con runtimes Cursor/Codex): `claude-code-guide` emitió veredicto categórico "Claude Code NO soporta carga condicional por `paths:` en rules; el frontmatter sería inerte" basándose en que la config local del usuario no usaba ese campo (declinó el WebFetch a docs). Un WebFetch directo a `code.claude.com/docs/en/memory` demostró lo contrario: `paths:` es feature nativa documentada con sintaxis exacta, brace expansion y soporte user-level. Aceptar el veredicto habría descartado un slice completo de la fase. Causa: "ausencia de evidencia en el contexto local" tratada como "evidencia de ausencia en el producto" — mismo patrón del precedente 2026-05-15 ("Cursor no soporta hooks" — falso). Las features recientes nunca aparecen en configs existentes precisamente por ser recientes.
+
   **Solución unificada — protocolo de verificación de afirmaciones factuales antes de aceptar propuesta de CUALQUIER sub-agente**:
 
   *Patrón obligatorio aplicable a TODOS los modos*: extraer 2-3 afirmaciones factuales del reporte del sub-agente y verificar cada una con primitivas baratas (`Grep`/`Read`/`wc -l`/`ls`/`git log`) ANTES de aceptar el plan o acción. Tipos de afirmaciones a verificar:
@@ -317,6 +319,8 @@ Durante `/swl:aprender`, aplicar estas reglas:
   *Para repos externos (Modo B)*: 4 filtros adicionales: (1) ¿qué % es teoría/código no-portable vs portable? — si >70% no-portable, recortar; (2) **¿la propuesta reescribe mecanismos existentes en el proyecto destino?** — VERIFICAR con `Grep`/`Read` 2-3 afirmaciones concretas del agente contra el código real ANTES de aceptar; (3) ¿LOC nuevas estimadas vs reutilizar lo existente? — si la propuesta supera 500 LOC para un solo patrón, hay sobre-ingeniería; (4) ¿el alcance reducido cubre 80% del valor? — Pareto.
 
   *Para revisores de código (Modo C)*: además del patrón obligatorio, **re-clasificar severidad cuando el revisor solo miró parte del flujo**. Si el revisor marca MAYOR un bug del Response, verificar si el Request también está afectado — los happy paths típicamente involucran ambos lados.
+
+  *Para agentes de documentación (Modo D)*: todo veredicto **NO-EXISTE / NO-SOPORTADO** sobre una feature de un producto externo exige cita a la doc oficial consultada EN ese turno (URL + extracto). Si el agente "verifica" solo contra el contexto local (configs del usuario, código del repo), su veredicto es inferencia, no verificación — re-verificar con 1 WebFetch a la doc oficial antes de tomar decisiones de diseño sobre él. Regla mnemónica: *ausencia en mi config ≠ ausencia en el producto*.
 - **Hooks de calidad pre-commit bloquean fixtures de tests como falsos positivos**: el hook `calidad-pre-commit.js` aplica regex `\b(api_key|password|token|secret)\s*[=:]\s*["'][^"'\s]{4,}["']` que matchea fixtures legítimos en archivos de test. Caso real: test que valida que la función `sanitizar()` redacta `api_key="abc12345xyz"` se bloquea. Causa: el hook no distingue contexto de test vs producción. Solución: en archivos de test, construir fixtures con concatenación de strings (`'api' + '_key'`, `'pass' + 'word'`) o agregar marcador placeholder reconocido por el hook (`fake_`, `dummy_`, `placeholder`, `example`, `os.environ`). NUNCA bypassear el hook con `--no-verify` — el detector cumple su función; ajustar el fixture es lo correcto.
 - **Regex de path-matching `/[\\/]<dir>[\\/]/` falla con paths relativos sin slash inicial** [CONFIRMADO x4]: hooks que filtran archivos por directorio (ej: `hooks/extraccion-aprendizajes.js` con `PATRONES_ARCHIVO_SWL_EXCLUIDO`) usan patrones que requieren un separator ANTES del nombre. Caso real: path `scripts/lib/foo.js` (sin slash inicial) eludía el filtro de exclusión y generaba placeholders espurios en APRENDIZAJES.md cada vez que se hacía `Edit` o `Write` sobre archivos del sistema SWL. Causa: el regex `[\\/]` requiere un caracter slash/backslash previo; cuando el path empieza con el nombre del directorio directamente, no matchea. Solución: usar `/(?:^|[\\/])<dir>[\\/]/` para aceptar tanto el inicio del string como un separator previo. Evidencia: 4 placeholders eliminados manualmente entre v1.3.3-v1.3.5 antes de identificar la causa raíz; fix endurecido aplicado en v1.3.5 (Fix I).
 - **`git ls-files` es preferible a `fs.readdir` recursivo para tests anti-regresión que escanean el repo**: usar `execSync('git ls-files')` limita el escaneo a archivos versionados — evita `node_modules/`, `.git/`, `_userland/`, archivos temporales y backups sin enumerar exclusiones. Caso real: `tests/scripts/no-legacy-npx-pattern.test.js` v1.3.6 escanea 1000+ archivos versionados en <200ms; el equivalente con `fs.readdir` recursivo más exclusiones manuales sería más lento y propenso a olvidar paths. Cuando el test es de "calidad del repo" (no de comportamiento), `git ls-files` es la primitiva correcta.

package/habilidades/fastapi-experto/SKILL.md

@@ -5,12 +5,12 @@ description: >
   testing con httpx. Incluye el anti-patrón crítico MissingGreenlet (lazy loading
   en async). Cargar cuando se implementen endpoints FastAPI, schemas Pydantic v2,
   queries SQLAlchemy async, WebSockets, SSE o tests de integración con httpx.
-version: "1.3.0"
+version: "1.3.1"
 evolved: true
-evolved-from: "1.2.0"
-evolved-at: "2026-05-20"
-evolved-by: "aprender"
-evolved-note: "2 gotchas nuevos SIGAF 2026-05-15: setattr con strings inventados en whitelist bypassea persistencia silenciosamente (extiende gotcha getattr); ClassVar[frozenset] como patrón positivo para whitelists de PATCH endpoints"
+evolved-from: "1.3.0"
+evolved-at: "2026-06-04"
+evolved-by: "evolucionar"
+evolved-note: "3 patrones nuevos OIC v1.5 2026-06-04: handler logging defensivo con sesión SQLAlchemy desacoplada (PE-001); tests pytest cuelgan si handler abre engine con pool_pre_ping al startup sin BD + receta conftest (PE-002); tests de endpoint sin BD con dependency_overrides[get_db]=lambda:None + monkeypatch del service (PE-008)"
 herramientasPermitidas: [Read]
 exclusiones:
   - "No cargar para proyectos Django o Flask — los patrones de ORM sync, Class-Based Views y middleware difieren fundamentalmente; cargar `django-experto` o el skill del framework correspondiente."
@@ -267,6 +267,57 @@ Beneficios:
 
 Regla: para cualquier whitelist usada en `setattr` ciego (PATCH endpoints, factory methods, deserializadores manuales), declarar como `ClassVar[frozenset[str]]` de la clase del service. NUNCA como variable local del método. NUNCA como módulo-level constant fuera de la clase (pierde el namespacing).
 
+- **Handler logging que persiste en BD durante manejo de excepciones — SIEMPRE usar sesión SQLAlchemy desacoplada + silenciar fallos** (patrón portable; caso real OIC v1.5 BitacoraErrorHandler 2026-06-04): si un `logging.Handler` custom (audit trail, Sentry-style, métricas async, observabilidad) usa la sesión del request para persistir el evento, durante una excepción HTTP la sesión está en estado roto y `session.add()` falla, perdiendo la excepción original. Patrón correcto:
+```python
+# Engine PROPIO independiente del pool del request (pool=2 suficiente).
+engine = create_engine(settings.DATABASE_URL, pool_pre_ping=True, pool_size=2, max_overflow=2)
+session_factory = sessionmaker(bind=engine, autocommit=False, autoflush=False)
+
+class MiHandler(logging.Handler):
+    def emit(self, record):
+        try:
+            self._emit_unsafe(record)
+        except Exception:  # noqa: BLE001 — silencio defensivo intencional
+            # NUNCA loggear con `logging` desde aquí (riesgo de recursión infinita).
+            pass
+
+    def _emit_unsafe(self, record):
+        sess = session_factory()  # sesión NUEVA, no la del request
+        try:
+            sess.add(entry); sess.commit()
+        finally:
+            sess.close()
+```
+Reglas clave: (a) engine propio; (b) `try/except: pass` agresivo en `emit()`; (c) NUNCA emitir a logger propio; (d) filtrar loggers ruidosos por nombre (`sqlalchemy.*`, `uvicorn.access`, `httpx`, `httpcore`, `asyncio`, `urllib3`); (e) idempotente: verificar si ya está en `root.handlers` antes de registrar. Aplicable a Sentry-style integrations, audit handlers, métricas async, alertas.
+
+- **Tests pytest se cuelgan al importar `app.main` cuando un handler abre engine BD con `pool_pre_ping=True` al startup** (gotcha crítico OIC v1.5 2026-06-04): si un handler de logging custom se instala en `setup_logging()` y construye un engine con `pool_pre_ping=True`, sin PostgreSQL corriendo SQLAlchemy intenta una query de verificación en `socket.connect()` infinito. El test no falla — se cuelga sin output (ni siquiera el header de pytest). Causa: el bloqueo ocurre en la **importación** del módulo `app.main` (que llama `setup_logging()`), no en el test mismo. Síntoma típico: 3+ invocaciones de `pytest` en background sin output, requiere matar `python.exe` manualmente. Solución obligatoria en `backend/tests/conftest.py`:
+```python
+# ANTES de importar app.main
+os.environ.setdefault("ENV", "test")
+os.environ.setdefault("SKIP_DB_HEALTHCHECK", "true")
+# Por CADA handler del proyecto que abre engine al startup:
+os.environ.setdefault("SWL_BITACORA_ERRORES_ENABLED", "false")
+# (sustituir por la env var real del proyecto)
+```
+Regla: cualquier handler con `pool_pre_ping=True` en su engine debe tener un kill-switch env var, y el conftest debe deshabilitarlo. Sin esto, los tests del proyecto serán inviables sin BD real.
+
+- **Tests de endpoint sin BD con `dependency_overrides[get_db]=lambda:None` + monkeypatch del service** (patrón portable validado OIC v1.5 Slice 4 2026-06-04): para tests de endpoint que verifican contrato HTTP (auth, validación de query params, estructura de respuesta, rate-limit, headers de export CSV) sin requerir PostgreSQL. 25 tests en 0.23s.
+```python
+@pytest.fixture
+def client_admin(monkeypatch: pytest.MonkeyPatch) -> TestClient:
+    app.dependency_overrides[requiere_admin] = _fake_admin  # stub user
+    app.dependency_overrides[get_db] = lambda: None  # type: ignore[return-value]
+    # Mock del service: el endpoint llama service.metodo(db, ...) pero `db` es None;
+    # el service no debe ejecutarse — se reemplaza con fake que devuelve schema válido.
+    from app.services import mi_service
+    monkeypatch.setattr(mi_service, "listar_paginado",
+        lambda db, filtros, page, per_page: SchemaPage(items=[], total=0, ...))
+    with TestClient(app) as c:
+        yield c
+    app.dependency_overrides.clear()
+```
+Aplicabilidad: cualquier endpoint que dependa de `get_db` + service mockeable. NO requiere BD real ni fixtures de datos. Tests de integración con BD viven aparte (`@pytest.mark.integration`).
+
 ## Referencias especializadas
 
 | Tema | Archivo |