Worktree + Aislamiento de Tareas

s01 > s02 > s03 > s04 > s05 > s06 | s07 > s08 > s09 > s10 > s11 > [ s12 ]

"Cada uno trabaja en su propio directorio, sin interferencia" -- las tareas gestionan objetivos, los worktrees gestionan directorios, vinculados por ID.

Problema

En s11, los agentes pueden reclamar y completar tareas de manera autónoma. Pero cada tarea se ejecuta en un directorio compartido. Dos agentes refactorizando diferentes módulos al mismo tiempo colisionarán: el agente A edita config.py, el agente B edita config.py, los cambios sin stage se mezclan, y ninguno puede volver atrás limpiamente.

El tablero de tareas rastrea qué hacer pero no tiene opinión sobre dónde hacerlo. La solución: dar a cada tarea su propio directorio git worktree. Las tareas gestionan objetivos, los worktrees gestionan contexto de ejecución. Vincúlalos por ID de tarea.

Solución

Plan de control (.tasks/)             Plan de ejecución (.worktrees/)
+------------------+                +------------------------+
| task_1.json      |                | auth-refactor/         |
|   status: in_progress  <------>   branch: wt/auth-refactor
|   worktree: "auth-refactor"   |   task_id: 1             |
+------------------+                +------------------------+
| task_2.json      |                | ui-login/              |
|   status: pending    <------>     branch: wt/ui-login
|   worktree: "ui-login"       |   task_id: 2             |
+------------------+                +------------------------+
                                    |
                          index.json (worktree registry)
                          events.jsonl (lifecycle log)

Máquinas de estado:
  Tarea:     pending -> in_progress -> completed
  Worktree:  absent  -> active      -> removed | kept

Cómo Funciona

1. Crear una tarea. Persistir el objetivo primero.

TASKS.create("Implement auth refactor")
# -> .tasks/task_1.json  status=pending  worktree=""

1. Crear un worktree y vincular a la tarea. Pasar task_id hace avanzar automáticamente la tarea a in_progress.

WORKTREES.create("auth-refactor", task_id=1)
# -> git worktree add -b wt/auth-refactor .worktrees/auth-refactor HEAD
# -> index.json gets new entry, task_1.json gets worktree="auth-refactor"

El vínculo escribe estado en ambos lados:

def bind_worktree(self, task_id, worktree):
    task = self._load(task_id)
    task["worktree"] = worktree
    if task["status"] == "pending":
        task["status"] = "in_progress"
    self._save(task)

1. Ejecutar comandos en el worktree. cwd apunta al directorio aislado.

subprocess.run(command, shell=True, cwd=worktree_path,
               capture_output=True, text=True, timeout=300)

1. Cerrar. Dos opciones:
   • worktree_keep(name) -- preservar el directorio para más tarde.
   • worktree_remove(name, complete_task=True) -- eliminar directorio, completar la tarea vinculada, emitir evento. Una llamada maneja拆卸 + completación.

def remove(self, name, force=False, complete_task=False):
    self._run_git(["worktree", "remove", wt["path"]])
    if complete_task and wt.get("task_id") is not None:
        self.tasks.update(wt["task_id"], status="completed")
        self.tasks.unbind_worktree(wt["task_id"])
        self.events.emit("task.completed", ...)

1. Flujo de eventos. Cada paso del ciclo de vida emite a .worktrees/events.jsonl:

{
  "event": "worktree.remove.after",
  "task": { "id": 1, "status": "completed" },
  "worktree": { "name": "auth-refactor", "status": "removed" },
  "ts": 1730000000
}

Eventos emitidos: worktree.create.before/after/failed, worktree.remove.before/after/failed, worktree.keep, task.completed.

Después de un crash, el estado se reconstruye desde .tasks/ + .worktrees/index.json en disco. La memoria de conversación es volátil; el estado de archivo es durable.

Qué Cambió Respecto a s11

Componente	Antes (s11)	Después (s12)
Coordinación	Tablero de tareas (owner/estado)	Tablero de tareas + vínculo worktree explícito
Alcance de ejecución	Directorio compartido	Directorio aislado por tarea
Recuperabilidad	Solo estado de tarea	Estado de tarea + índice worktree
Cierre	Completación de tarea	Completación de tarea + keep/remove explícito
Visibilidad de ciclo	Implícita en logs	Eventos explícitos en .worktrees/events.jsonl

Pruébalo

python agents/s12_worktree_task_isolation.py

1. Crear tareas para auth de backend y página de login de frontend, luego listar tareas.
2. Crear worktree "auth-refactor" para tarea 1, luego vincular tarea 2 a un nuevo worktree "ui-login".
3. Ejecutar "git status --short" en worktree "auth-refactor".
4. Mantener worktree "ui-login", luego listar worktrees e inspeccionar eventos.
5. Eliminar worktree "auth-refactor" con complete_task=true, luego listar tareas/worktrees/eventos.