@saulwade/swl-ses 2.6.0 → 2.8.0

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

@@ -1,57 +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"
-  ],
-  "_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"]
-    }
-  }
-}
+{
+  "_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.7"
+version: "1.0.9"
 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."
@@ -291,7 +291,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 + agentes de documentación) reportan afirmaciones factuales no verificadas** [CONFIRMADO x7]: 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**:
+- **Sub-agentes (Explore + revisores + agentes de documentación + agentes de implementación) reportan afirmaciones factuales no verificadas** [CONFIRMADO x9]: aplica a `Explore`, `revisor-codigo-swl`, `revisor-seguridad-swl`, `investigador-swl`, `planificador-swl`, `claude-code-guide`, agentes de implementación en `Agent(isolation:"worktree")`, y en general a cualquier sub-agente que reporte hallazgos sobre código o capacidades de herramientas. **Seis 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.
 
@@ -301,6 +301,12 @@ Durante `/swl:aprender`, aplicar estas reglas:
 
   **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.
 
+  **Modo E — agentes de implementación en worktree declaran honestamente una limitación de entorno, pero eso no exime de re-verificar** (caso real 2026-07-11): un agente de implementación en `Agent(isolation:"worktree")` reportó explícitamente "pytest no pudo ejecutarse localmente porque el worktree no tiene el intérprete requerido por `pyproject.toml`; solo verifiqué con `ruff check`/`ruff format`" — a diferencia de los Modos A-D, aquí el agente NO mintió ni infirió mal: describió su limitación con precisión. El riesgo no es la honestidad del agente sino tratar "declaró su limitación" como equivalente a "está verificado". Al re-ejecutar la suite real con el entorno correcto del proyecto principal tras integrar el trabajo, aparecieron 7 fallas reales (mocks con `side_effect` desactualizados por cambios de firma que el agente sí hizo pero no pudo ejercitar). Causa: un worktree nuevo no hereda automáticamente el `.venv`/entorno del checkout principal — puede resolver un intérprete distinto vía el PATH del sistema. Patrón: cualquier declaración de "no pude verificar X" en el reporte de un sub-agente es una BANDERA para verificar X manualmente con la máxima prioridad, nunca una nota informativa a ignorar.
+
+  **Modo F — sub-agente con mandato explícito de SOLO LECTURA ejecuta un comando destructivo** (caso real 2026-07-11): un agente de auditoría lanzado con "PROHIBIDO modificar cualquier archivo o la BD; solo Read/Grep/Glob y SELECT" ejecutó (vía un sub-agente anidado propio) un `rm -f` que borró un PNG de evidencia en la raíz del repo. El archivo estaba SIN TRACKEAR en git → irrecuperable (los tracked se restauran con `git checkout --`; los untracked no tienen red de seguridad). El agente REPORTÓ el incidente con honestidad en su resultado final — pero el daño ya estaba hecho. Causa: el mandato en el prompt es una instrucción, no una contención; los agentes anidados heredan herramientas, no disciplina. Diferencia con el Modo E: allí el riesgo era aceptar un reporte incompleto; aquí es daño colateral directo al workspace. Patrón doble: (1) `git status` comparativo tras CADA agente; (2) ANTES de lanzar agentes sobre un working tree con archivos untracked valiosos, protegerlos primero — commitearlos, moverlos fuera del repo o copiarlos (el trabajo sin commitear es la única víctima sin recuperación posible).
+
+  **Modo G — revisores adversariales en paralelo verifican la LÓGICA de un módulo pero nunca RE-DERIVAN el número que reporta** (caso real 2026-07-17, swl-ses F32-T07): 4 revisores adversariales corriendo en paralelo (incluido un agente `abogado-diablo-swl` con mandato explícito de refutar) auditaron un motor de mutation testing que reportaba mutation score 100% en 7 de 20 módulos críticos. Los 4 revisaron la lógica del clasificador, el manejo de errores y la cobertura de casos — ninguno detectó que esos 7 módulos "100%" nunca corrían un solo mutante real: todos morían por `MODULE_NOT_FOUND` de un entorno mal aislado, y el clasificador contaba esos fallos como kills. El bug solo apareció cuando el orquestador (no un revisor) reprodujo el cómputo en aislamiento (`ejecutarMutationTesting({modulos:[unicoModulo]})`) para cada módulo "100%" y confirmó que fallaban los 7. Causa: revisar código verifica que la LÓGICA sea razonable; no verifica que la CIFRA agregada que esa lógica produjo sea real — son preguntas distintas, y un panel de revisores de código, por más adversarial que sea, responde la primera, no la segunda. Diferencia con el Modo C (ubicaciones/severidades incorrectas): ahí el revisor mira código y se equivoca sobre el código; aquí el revisor mira código, tiene razón sobre el código, y el bug vive en la intersección entre el código y el entorno de ejecución — invisible sin ejecutar.
+
   **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:
@@ -316,6 +322,10 @@ Durante `/swl:aprender`, aplicar estas reglas:
   *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*.
+
+  *Para agentes de implementación en worktree (Modo E)*: cualquier frase tipo "no pude correr X", "el entorno no tenía Y", "solo verifiqué con Z" en el reporte final es una señal de PRIORIDAD MÁXIMA — re-ejecutar exactamente lo que el agente no pudo ejecutar (suite de tests completa, no solo el archivo que tocó) con el entorno correcto del checkout principal ANTES de dar el trabajo por terminado. Nunca degradar esa frase a "nota informativa" solo porque el resto del reporte suena confiado.
+
+  *Para paneles de revisores adversariales sobre un claim NUMÉRICO/AGREGADO (Modo G)*: cuando el artefacto bajo revisión reporta un score, porcentaje o conteo derivado de una corrida (mutation score, cobertura, latencia p95, tasa de éxito), el patrón obligatorio de "verificar 2-3 afirmaciones con Grep/Read" NO alcanza — hay que re-derivar la cifra en un subconjunto aislado y mínimo (un solo módulo, un solo caso) ANTES de aceptar el agregado. Un panel de revisores que solo lee el código del cómputo, sin ejecutar ni un fragmento, no puede detectar bugs que viven en la intersección código↔entorno.
 - **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/feynman-auditor-swl/recursos/preguntas-language-agnostic.md

@@ -1,108 +1,108 @@
-# Preguntas Feynman — Language-Agnostic
-
-28 preguntas organizadas en 7 categorías. Aplicar a cada función no trivial del módulo bajo auditoría.
-
----
-
-## Q1 — Propósito
-
-**Q1.1** ¿Qué hace exactamente esta función y solo esta función? Si no puedo describirla en una oración sin usar "y", ¿tiene demasiadas responsabilidades?
-
-**Q1.2** ¿Cuál es el invariante que esta función garantiza al terminar? ¿El código lo garantiza de verdad o solo en el camino feliz?
-
-**Q1.3** ¿Hay alguna condición en que esta función debería rechazar la operación pero no lo hace? ¿Qué pasa si se la llama dos veces seguidas con los mismos argumentos?
-
-**Q1.4** ¿Esta función asume que el estado del sistema está en alguna condición particular antes de ejecutarse? ¿Dónde se verifica esa condición?
-
----
-
-## Q2 — Orden de operaciones
-
-**Q2.1** ¿Importa el orden en que estas líneas se ejecutan? Si cambio el orden de dos líneas adyacentes, ¿el resultado es el mismo?
-
-**Q2.2** ¿Esta función lee un valor y luego lo modifica? Si algo cambia el valor entre la lectura y la escritura, ¿qué pasa?
-
-**Q2.3** ¿El cálculo de recompensa, crédito, o resultado se hace ANTES o DESPUÉS de actualizar el estado base? ¿Debería ser al revés?
-
-**Q2.4** ¿Si esta función llama a un sistema externo (BD, API, caché), el estado local ya está actualizado en ese momento? ¿El sistema externo puede ver un estado inconsistente?
-
----
-
-## Q3 — Consistencia cross-función
-
-**Q3.1** ¿Qué tienen en común esta función y otra que hace algo similar? ¿Una tiene un guard o una actualización que la otra no tiene?
-
-**Q3.2** ¿Existe una función de "camino normal" y una de "camino de emergencia/admin"? ¿Ambas actualizan exactamente el mismo conjunto de estado?
-
-**Q3.3** ¿Esta función inicializa todos los campos que otras funciones esperan encontrar inicializados? ¿Hay algún campo que se lee antes de ser escrito?
-
-**Q3.4** ¿El path que crea un recurso y el path que lo elimina dejan el sistema en un estado simétrico? ¿O el delete deja huérfanos?
-
----
-
-## Q4 — Asunciones implícitas
-
-**Q4.1** ¿Qué asume este código sobre el tipo o el rango del argumento que recibe? ¿Hay alguna validación que debería existir pero no existe?
-
-**Q4.2** ¿El código asume que el actor que llama esta función tiene permiso para hacerlo? ¿Dónde se verifica ese permiso exactamente?
-
-**Q4.3** ¿El código asume que algún recurso externo (BD, archivo, servicio) está disponible y en un estado consistente? ¿Qué pasa si no lo está?
-
-**Q4.4** ¿El código asume que nunca se llamará con valor cero, lista vacía, o string vacío? ¿Se validó eso?
-
----
-
-## Q5 — Límites y casos de borde
-
-**Q5.1** ¿Qué pasa si el valor es exactamente cero? ¿Y si es el máximo representable? ¿Y si es negativo?
-
-**Q5.2** ¿Qué pasa si la lista o colección está vacía? ¿Y si tiene exactamente un elemento? ¿Y si tiene millones?
-
-**Q5.3** ¿Qué pasa si el recurso ya existe cuando se intenta crear? ¿Y si no existe cuando se intenta modificar o eliminar?
-
-**Q5.4** ¿Qué pasa si dos actores ejecutan esta función al mismo tiempo? ¿Hay condición de carrera? ¿El resultado es determinista?
-
----
-
-## Q6 — Returns y manejo de errores
-
-**Q6.1** ¿Qué devuelve esta función cuando el input es inválido? ¿Lanza excepción, devuelve null, devuelve un error tipado, o silencia el problema?
-
-**Q6.2** ¿Si una operación parcial falla a mitad de camino, el estado queda consistente? ¿Hay rollback? ¿O el sistema queda a medias?
-
-**Q6.3** ¿El caller de esta función verifica el valor de retorno? ¿Un error no verificado puede causar daño silencioso más adelante?
-
-**Q6.4** ¿El código captura excepciones de forma demasiado amplia (`except Exception`, `catch (e)` vacío)? ¿Qué errores legítimos podría estar silenciando?
-
----
-
-## Q7 — Interacciones externas
-
-**Q7.1** ¿Esta función llama a un sistema externo (BD, API, caché, cola)? ¿La llamada puede fallar? ¿Qué pasa con el estado local si falla?
-
-**Q7.2** ¿Esta función persiste datos en más de un lugar (ej: BD + caché + índice)? ¿Qué pasa si la segunda escritura falla después de que la primera tuvo éxito?
-
-**Q7.3** ¿El acumulador o índice que esta función usa se actualiza ANTES de modificar el valor base, o DESPUÉS? ¿El orden importa para la correctitud del cálculo?
-
-**Q7.4** ¿Esta función envía una notificación, evento, o mensaje a otro sistema? ¿Lo hace antes o después de confirmar la operación? ¿El receptor puede actuar sobre un estado que aún no se confirmó?
-
-**Q7.5** ¿Esta función lee un valor de caché y lo trata como fresco? ¿Hay algún path donde la caché puede estar desactualizada respecto a la fuente de verdad?
-
-**Q7.6** ¿Esta función modifica datos de otro actor además de los del actor que la llama? ¿Tiene permiso para hacerlo en todos los casos?
-
-**Q7.7** ¿Existe un patrón de acumulador donde el total acumulado se calcula con base en el estado anterior? Si el estado base cambia (insert/update/delete de otro registro), ¿el acumulador refleja el cambio correctamente?
-
-**Q7.8** ¿Esta función delega a otra función que tiene sus propios efectos secundarios? ¿El caller sabe qué estado modifica el callee internamente?
-
----
-
-## Cómo usar estas preguntas
-
-1. Leer la función completa una vez para entender el propósito.
-2. Para cada pregunta de las categorías Q1–Q7, marcar:
-   - ✓ Respondida claramente por el código
-   - ? Requiere rastrear el caller o el sistema externo para responder
-   - ✗ El código no la responde — sospechoso de bug
-3. Todo `✗` o `?` sin resolver es un **sospechoso** para Fase 3 de síntesis.
-
-<!-- Adaptado de nemesis-auditor-main bajo MIT License (https://github.com/0xiehnnkta/nemesis-auditor) -->
+# Preguntas Feynman — Language-Agnostic
+
+28 preguntas organizadas en 7 categorías. Aplicar a cada función no trivial del módulo bajo auditoría.
+
+---
+
+## Q1 — Propósito
+
+**Q1.1** ¿Qué hace exactamente esta función y solo esta función? Si no puedo describirla en una oración sin usar "y", ¿tiene demasiadas responsabilidades?
+
+**Q1.2** ¿Cuál es el invariante que esta función garantiza al terminar? ¿El código lo garantiza de verdad o solo en el camino feliz?
+
+**Q1.3** ¿Hay alguna condición en que esta función debería rechazar la operación pero no lo hace? ¿Qué pasa si se la llama dos veces seguidas con los mismos argumentos?
+
+**Q1.4** ¿Esta función asume que el estado del sistema está en alguna condición particular antes de ejecutarse? ¿Dónde se verifica esa condición?
+
+---
+
+## Q2 — Orden de operaciones
+
+**Q2.1** ¿Importa el orden en que estas líneas se ejecutan? Si cambio el orden de dos líneas adyacentes, ¿el resultado es el mismo?
+
+**Q2.2** ¿Esta función lee un valor y luego lo modifica? Si algo cambia el valor entre la lectura y la escritura, ¿qué pasa?
+
+**Q2.3** ¿El cálculo de recompensa, crédito, o resultado se hace ANTES o DESPUÉS de actualizar el estado base? ¿Debería ser al revés?
+
+**Q2.4** ¿Si esta función llama a un sistema externo (BD, API, caché), el estado local ya está actualizado en ese momento? ¿El sistema externo puede ver un estado inconsistente?
+
+---
+
+## Q3 — Consistencia cross-función
+
+**Q3.1** ¿Qué tienen en común esta función y otra que hace algo similar? ¿Una tiene un guard o una actualización que la otra no tiene?
+
+**Q3.2** ¿Existe una función de "camino normal" y una de "camino de emergencia/admin"? ¿Ambas actualizan exactamente el mismo conjunto de estado?
+
+**Q3.3** ¿Esta función inicializa todos los campos que otras funciones esperan encontrar inicializados? ¿Hay algún campo que se lee antes de ser escrito?
+
+**Q3.4** ¿El path que crea un recurso y el path que lo elimina dejan el sistema en un estado simétrico? ¿O el delete deja huérfanos?
+
+---
+
+## Q4 — Asunciones implícitas
+
+**Q4.1** ¿Qué asume este código sobre el tipo o el rango del argumento que recibe? ¿Hay alguna validación que debería existir pero no existe?
+
+**Q4.2** ¿El código asume que el actor que llama esta función tiene permiso para hacerlo? ¿Dónde se verifica ese permiso exactamente?
+
+**Q4.3** ¿El código asume que algún recurso externo (BD, archivo, servicio) está disponible y en un estado consistente? ¿Qué pasa si no lo está?
+
+**Q4.4** ¿El código asume que nunca se llamará con valor cero, lista vacía, o string vacío? ¿Se validó eso?
+
+---
+
+## Q5 — Límites y casos de borde
+
+**Q5.1** ¿Qué pasa si el valor es exactamente cero? ¿Y si es el máximo representable? ¿Y si es negativo?
+
+**Q5.2** ¿Qué pasa si la lista o colección está vacía? ¿Y si tiene exactamente un elemento? ¿Y si tiene millones?
+
+**Q5.3** ¿Qué pasa si el recurso ya existe cuando se intenta crear? ¿Y si no existe cuando se intenta modificar o eliminar?
+
+**Q5.4** ¿Qué pasa si dos actores ejecutan esta función al mismo tiempo? ¿Hay condición de carrera? ¿El resultado es determinista?
+
+---
+
+## Q6 — Returns y manejo de errores
+
+**Q6.1** ¿Qué devuelve esta función cuando el input es inválido? ¿Lanza excepción, devuelve null, devuelve un error tipado, o silencia el problema?
+
+**Q6.2** ¿Si una operación parcial falla a mitad de camino, el estado queda consistente? ¿Hay rollback? ¿O el sistema queda a medias?
+
+**Q6.3** ¿El caller de esta función verifica el valor de retorno? ¿Un error no verificado puede causar daño silencioso más adelante?
+
+**Q6.4** ¿El código captura excepciones de forma demasiado amplia (`except Exception`, `catch (e)` vacío)? ¿Qué errores legítimos podría estar silenciando?
+
+---
+
+## Q7 — Interacciones externas
+
+**Q7.1** ¿Esta función llama a un sistema externo (BD, API, caché, cola)? ¿La llamada puede fallar? ¿Qué pasa con el estado local si falla?
+
+**Q7.2** ¿Esta función persiste datos en más de un lugar (ej: BD + caché + índice)? ¿Qué pasa si la segunda escritura falla después de que la primera tuvo éxito?
+
+**Q7.3** ¿El acumulador o índice que esta función usa se actualiza ANTES de modificar el valor base, o DESPUÉS? ¿El orden importa para la correctitud del cálculo?
+
+**Q7.4** ¿Esta función envía una notificación, evento, o mensaje a otro sistema? ¿Lo hace antes o después de confirmar la operación? ¿El receptor puede actuar sobre un estado que aún no se confirmó?
+
+**Q7.5** ¿Esta función lee un valor de caché y lo trata como fresco? ¿Hay algún path donde la caché puede estar desactualizada respecto a la fuente de verdad?
+
+**Q7.6** ¿Esta función modifica datos de otro actor además de los del actor que la llama? ¿Tiene permiso para hacerlo en todos los casos?
+
+**Q7.7** ¿Existe un patrón de acumulador donde el total acumulado se calcula con base en el estado anterior? Si el estado base cambia (insert/update/delete de otro registro), ¿el acumulador refleja el cambio correctamente?
+
+**Q7.8** ¿Esta función delega a otra función que tiene sus propios efectos secundarios? ¿El caller sabe qué estado modifica el callee internamente?
+
+---
+
+## Cómo usar estas preguntas
+
+1. Leer la función completa una vez para entender el propósito.
+2. Para cada pregunta de las categorías Q1–Q7, marcar:
+   - ✓ Respondida claramente por el código
+   - ? Requiere rastrear el caller o el sistema externo para responder
+   - ✗ El código no la responde — sospechoso de bug
+3. Todo `✗` o `?` sin resolver es un **sospechoso** para Fase 3 de síntesis.
+
+<!-- Adaptado de nemesis-auditor-main bajo MIT License (https://github.com/0xiehnnkta/nemesis-auditor) -->

package/habilidades/git-worktrees-paralelo/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: git-worktrees-paralelo
 description: Uso de git worktrees para ejecución paralela de agentes. Crear, usar y limpiar worktrees de forma segura para que múltiples agentes trabajen sin conflictos.
-version: "1.0.0"
+version: "1.0.1"
 herramientasPermitidas: [Read, Bash]
 evolvable: true  # default para skill estandar
 exclusiones:
@@ -268,3 +268,21 @@ git worktree remove --force ../mi-app-agente-1
 **`git stash` en un worktree guarda el stash en el stash global del repositorio compartido, no en el worktree**: si el Agente 1 hace `git stash` en `mi-app-agente-1/` y luego el Agente 2 hace `git stash pop` en `mi-app-agente-2/`, aplica el stash del Agente 1 en la rama incorrecta. Causa: el stash de Git es una referencia global en `.git/refs/stash`, no por worktree. Fix: NUNCA usar `git stash` en flujos con múltiples worktrees. En su lugar, hacer un commit temporal con mensaje `WIP:` y usar `git reset HEAD~1` para deshacer cuando se necesite.
 
 **Eliminar un worktree con `git worktree remove --force` mientras hay un agente activo escribiendo archivos en ese directorio produce corrupción del objeto store de Git**: si el agente tiene archivos en proceso de escritura (commit parcial, `git add` pendiente) y otro proceso ejecuta `remove --force`, Git puede quedar con objetos huérfanos o referencias rotas. Causa: `--force` no verifica si hay procesos con file handles abiertos en el worktree. Fix: el orquestador debe verificar que cada agente emitió su commit final antes de ejecutar `git worktree remove`. Usar `git worktree list --porcelain` para confirmar que la rama del worktree tiene el commit esperado.
+
+**Un worktree creado con `isolation: "worktree"` (Agent tool) puede branchear desde una base desactualizada — no la rama de trabajo activa — si pasó tiempo o hubo compactación de contexto entre sesiones** [CONFIRMADO]: si el mecanismo que crea el worktree resuelve el punto de partida contra una referencia que quedó "congelada" (ej. `main` publicado, 100+ commits detrás de la rama de feature real en la que se trabaja), el agente produce commits legítimos, pero al intentar fusionarlos aparecen decenas de conflictos espurios en archivos que el agente ni siquiera tocó — el diff real es contra una base vieja, no contra el trabajo del agente. Caso real (sesión de 4 agentes en paralelo): 2 de 4 worktrees branchearon desde `main` (un PR ya squash-mergeado, 182 commits detrás de la rama de trabajo activa) en vez de la rama de feature; el merge directo habría arrastrado cientos de líneas de diffs no relacionados, y de hecho generó colisión real de números consecutivos de migración. Causa raíz: el punto de partida del worktree se fijó en un momento donde apuntaba a la rama correcta, pero la rama activa siguió avanzando mientras el worktree quedó anclado a su snapshot original — cuanto más dura la sesión (o si hay compactación de por medio), mayor la ventana de divergencia. Diagnóstico ANTES de fusionar (barato, dos comandos):
+```bash
+git merge-base --is-ancestor <rama-actual> <rama-worktree> && echo "base correcta" || echo "requiere investigar"
+git merge-base <rama-actual> <rama-worktree>   # compara contra el HEAD conocido de cuando se lanzó el agente
+```
+Si la base real está muy por detrás de lo esperado: **no usar `git merge` directo** (arrastraría el diff completo vs. la base vieja) — usar `git cherry-pick` de los commits propios del agente, uno por uno, sobre la punta actual de la rama de trabajo (`git log --reverse --oneline <base-vieja>..<rama-worktree>` para la lista en orden). Los conflictos del cherry-pick son reales y acotados al cambio de ESE commit, no ruido de la divergencia de base.
+
+**Un conflicto de merge/cherry-pick en un archivo SQL con múltiples `CREATE PROCEDURE`/`CREATE FUNCTION` consecutivos y boilerplate similar (`LANGUAGE plpgsql SECURITY INVOKER AS $$ DECLARE ... END; $$;`) puede hacer que el diff de línea de Git "interleave" el contenido de dos objetos distintos** [CONFIRMADO x2]: cuando ambos lados de un conflicto agregan objetos PL/pgSQL nuevos en la misma posición del archivo, git empareja las líneas de cierre genéricas (`)`, `LANGUAGE plpgsql`, `SECURITY INVOKER`, `AS $$`, `DECLARE`) como si fueran contexto compartido sin cambios — el bloque `<<<<<<< / ======= / >>>>>>>` alterna entre la firma de un objeto de un lado y el cuerpo de OTRO objeto del otro lado. Resolver aceptando los hunks tal cual (o con merge automático) borra o duplica el cuerpo de uno de los dos procedimientos/funciones. Diagnóstico antes de resolver: contar cuántos `CREATE OR REPLACE (PROCEDURE|FUNCTION)` hay en cada lado del rango conflictuado (`grep -n "CREATE OR REPLACE"` entre las líneas del `<<<<<<<` y `>>>>>>>`) — si el conteo no cuadra con objetos completos y autocontenidos, hay interleaving. Fix: NO editar los hunks en el sitio; reconstruir manualmente objeto-por-objeto, concatenando cada `CREATE ... COMMENT ON ...` completo de un lado seguido del completo del otro lado, en cualquier orden (son independientes). Verificar al final: `grep -c '\$\$' archivo.sql` debe dar un número PAR, y el conteo de `CREATE OR REPLACE PROCEDURE/FUNCTION` debe coincidir con la suma real esperada de ambos lados sin duplicados.
+
+**Una rama que sigue recibiendo commits DESPUÉS de que su propio PR se squash-mergeó a `main` genera un conflicto espurio de 20+ archivos en el SIGUIENTE PR de esa misma rama** [CONFIRMADO — variante del gotcha anterior]: el caso de "worktree con base desactualizada" cubre una rama que *branchea desde* una base squasheada; este es el caso hermano donde la MISMA rama continúa avanzando tras su propio squash-merge. El historial de commits de la rama nunca queda como descendiente del commit squash en `main` — git no tiene ancestro común que refleje el squash, así que el siguiente PR desde esa rama muestra `mergeStateStatus: CONFLICTING` aunque semánticamente nada choque. Diagnóstico y resolución seguros — **barrido "ours vs theirs" por shortstat ANTES de elegir estrategia**, nunca a ciegas:
+```bash
+git log --oneline -3 main   # confirmar que main NO avanzó desde el squash
+git diff --name-only <rama-local> main   # lista de archivos en conflicto
+# Para CADA archivo conflictuado, comparar tamaño de cambio de cada lado:
+git diff --shortstat :2:<archivo> :3:<archivo>   # :2 = ours/HEAD, :3 = theirs/main
+```
+Si TODOS los archivos muestran que "theirs" (main, congelado en el punto del squash) es subconjunto estricto de líneas de "ours" (la rama que sigue avanzando), y `main` no avanzó desde el squash (paso 1), `git checkout --ours <archivo>` para cada uno es seguro — no se pierde contenido independiente de main. Si algún archivo muestra líneas exclusivas del lado "theirs" que "ours" no tiene, DETENERSE y resolver ese archivo manualmente (no aplica el atajo). Referencia cruzada: `~/.claude/rules/sesiones-paralelas.md`.