Worktree + Isolamento de Tarefas

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

"Cada um trabalha em seu próprio diretório, sem interferência" -- tarefas gerenciam objetivos, worktrees gerenciam diretórios, vinculados por ID.

Problema

No s11, agentes podem reclamar e completar tarefas autonomamente. Mas toda tarefa roda em um diretório compartilhado. Dois agentes refatorando módulos diferentes ao mesmo tempo vão colidir: agente A edita config.py, agente B edita config.py, alterações não stageadas se misturam, e nenhum pode fazer rollback cleanly.

O quadro de tarefas rastreia o que fazer mas não tem opinião sobre onde fazer. A solução: dar a cada tarefa seu próprio diretório git worktree. Tarefas gerenciam objetivos, worktrees gerenciam contexto de execução. Vincule-os por ID de tarefa.

Solução

Plano de controle (.tasks/)             Plano de execução (.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)

State machines:
  Task:     pending -> in_progress -> completed
  Worktree: absent  -> active      -> removed | kept

Como Funciona

1. Crie uma tarefa. Persista o objetivo primeiro.

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

1. Crie um worktree e vincule à tarefa. Passar task_id auto-avança a tarefa para 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"

O vínculo escreve estado em ambos os 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. Execute comandos no worktree. cwd aponta para o diretório isolado.

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

1. Encerrar. Duas escolhas:
   • worktree_keep(name) -- preservar o diretório para depois.
   • worktree_remove(name, complete_task=True) -- remover diretório, completar a tarefa vinculada, emitir evento. Uma chamada gerencia teardown + conclusão.

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. Fluxo de eventos. Cada etapa do ciclo de vida emite para .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.

Após uma crash, o estado é reconstruído de .tasks/ + .worktrees/index.json em disco. Memória de conversa é volátil; estado de arquivo é durável.

O Que Mudou Desde s11

Componente	Antes (s11)	Depois (s12)
Coordenação	Quadro de tarefas (owner/status)	Quadro de tarefas + vínculo explícito de worktree
Escopo de execução	Diretório compartilhado	Diretório isolado por tarefa
Recuperabilidade	Apenas status da tarefa	Status da tarefa + índice de worktree
Teardown	Conclusão da tarefa	Conclusão da tarefa + keep/remove explícito
Visibilidade do ciclo de vida	Implícito nos logs	Eventos explícitos em .worktrees/events.jsonl

Experimente

python agents/s12_worktree_task_isolation.py

1. Crie tarefas para backend auth e página de login de frontend, depois liste tarefas.
2. Crie worktree "auth-refactor" para tarefa 1, depois vincule tarefa 2 a um novo worktree "ui-login".
3. Execute "git status --short" no worktree "auth-refactor".
4. Keep worktree "ui-login", depois liste worktrees e inspecione eventos.
5. Remova worktree "auth-refactor" com complete_task=true, depois liste tarefas/worktrees/eventos.