@saulwade/swl-ses 2.6.0 → 2.6.1

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`.