Agents diferentes não podem brigar pela mesma árvore

O problema oculto dos agents paralelos

O s09-s11 permite rodar múltiplos teammates ao mesmo tempo, mas há uma armadilha: todos trabalham no mesmo diretório. Alice modifica auth.py, bob também modifica auth.py simultaneamente — conflitos de git, arquivos corrompidos, testes se contaminando mutuamente.

A solução do s12 é o git worktree: o mesmo repositório, com git worktree add, pode ter checkouts em branches diferentes em diretórios diferentes. Cada agent recebe seu próprio worktree, trabalha no seu diretório e não enxerga o outro.

my-repo/                           # workspace principal (usado pelo lead)
.worktrees/
  alice-auth/                      # diretório isolado de alice
    (branch: wt/alice-auth)
  bob-api/                         # diretório isolado de bob
    (branch: wt/bob-api)
  index.json                       # registro de worktrees
  events.jsonl                     # log de eventos do ciclo de vida

Divisão em dois planos

O s12 divide explicitamente o sistema em dois planos:

• Plano de controle (control plane): arquivos JSON em .tasks/. A task é a unidade abstrata de "o que fazer", com dependências, owner e status.
• Plano de execução (execution plane): diretórios em .worktrees/. O worktree é o contêiner físico do "onde fazer" — um diretório + um branch.

Os dois são vinculados bidirecionalmente via task.worktree e worktree.task_id.

Esse desacoplamento permite: reutilizar o mecanismo de gestão de tasks trocando o ambiente de execução (por exemplo, containers Docker em vez de git worktree). Ou trocar o mecanismo de tasks mantendo o worktree (por exemplo, banco de dados em vez de arquivos JSON).

Demonstração do ciclo de vida

Percorra o fluxo completo: create task → create worktree → run commands → keep ou remove. Cada passo gera um registro no log de eventos (events.jsonl), que em produção serve para observabilidade.

keep vs remove

Quando o worktree cumpre sua missão, há dois desfechos possíveis:

• remove: git worktree remove --force — o diretório é excluído, e o branch geralmente também é limpo. Equivale a "essa exploração não presta".
• keep: apenas marca status: kept no .worktrees/index.json; o diretório físico é preservado. Equivale a "esse resultado vai ser aproveitado, espera eu fazer o merge".

Padrão comum: subagent roda um refactor experimental → resultado bom → keep → humano revisa → merge na branch principal → remove manual. Resultado ruim? Remove direto.