teqo-backup/docs/plans/worktree-next-claima-issue-deterministicamente.md

Worktree next claima deterministicamente a Issue e abre o opencode com /work-issue já informado

Status: rascunho Atualizado em: 2026-08-10 Issue: #595 Priority: P2 Model: composer-2.5 Impeccable: A — N/A (CLI/shell, sem superfície de produto) Canvas UI: N/A — sem UI Appetite: ~1 dia; um outcome verificável (de worktree next ao TUI já na Issue certa, sem claim do agente) Responsável: —

Intenção

Todo agente que executa /work-issue gasta o primeiro passo com pnpm agent:claim — e o claim já é um script determinístico. Em vez de deixar o agente fazê-lo (e poder errar — #582 nasceu de claim/branch divergentes), o fluxo faz o claim antes, como primeiro passo do worktree next: falhou (fila vazia, race, --issue inválido) → avisa o humano e para; sucesso → cria o worktree da Issue já claimada, troca o shell para lá e abre o opencode com /work-issue sabendo qual Issue é — sem nenhum re-claim nem verificação.

Persona e fluxo

• Persona / contexto: o humano no terminal interativo; uma sessão de trabalho por comando.
• Job principal: do comando ao TUI do opencode já em execução na Issue certa, sem passo manual.
• Fluxo desejado:
  1. worktree next [--issue N] → claim determinístico (mesma fila/ordem do agent:claim, mesmo lock otimista);
  2. falhou → imprime o motivo (fila vazia / Issue não claimável / race) e para — nada de worktree órfão;
  3. sucesso → cria (ou reutiliza) o worktree da Issue claimada, provisiona o ambiente, imprime o brief do claim;
  4. cd para o worktree e launch opencode … com /work-issue já informando a Issue (ex.: comando com o número, ou prompt com o brief) — o agente nunca roda agent:claim.
• Anti-goals: não virar um executor de Issues em lote; não desfazer claims (reverter in-progress → ready é outra entrega); não mexer no claim coordenado do pool.

Objetivo e aceite

• worktree next claima antes de criar o worktree; claim falhou → motivo no stdout e saída sem worktree.
• A Issue do worktree é exatamente a claimada (mesmo pick da fila; --issue N repassado ao claim).
• O launch comunica a Issue ao agente de forma determinística, e o texto de saída avisa explicitamente "já claimada — não rodar agent:claim".
• Reutilizar worktree já existente da mesma Issue continua idempotente; abrir de novo uma Issue já claimada não re-claima (ver questão em aberto).
• --stay continua suprimindo cd + launch (o claim ainda acontece). O comando /worktree do opencode roda o mesmo script (claim incluso); a única diferença de superfície segue sendo a diretiva launch (só no terminal interativo).
• Fluxo ponta a ponta dependente de OPS32 (work-issue aceita Issue claimada sem re-claim).

Dados (intenção)

• Vou apresentar dados? Não — sem superfície de dados.

Direção no codebase (hipótese)

• Áreas prováveis: scripts/worktree.mjs (cmdNext: claim no primeiro passo — reutilizar/invocar a lógica de scripts/agent-claim.mjs, capturar o brief e o número da Issue claimada antes do pick/branch; a linha "Issue NÃO claimada — claim continua sendo pnpm agent:claim" sai), scripts/lib/worktree.mjs (diretiva launch ganha a Issue no prompt), .agents/shell/worktree.sh + .opencode/commands/worktree.md (textos), AGENTS.md / docs/CHANGELOG-AGENTS.md.
• Precedente a olhar: scripts/lib/agent-pool-prompt.mjs — o pool já entrega a Issue claimada ao agente com buildPoolWorkerPrompt (número, título, path do plano via extractPlanPath): é o molde do conteúdo do launch.
• Risco de acoplamento: mesmo arquivo de constantes do OPS31 (serializes: [worktree-cli]); claim do pool usa o mesmo lock otimista — um claim humano não pode desestabilizar o do pool (e vice-versa), o lock já cobre.

Dependências

• OPS32 (work-issue no paradigma claimado) — direção proposital: a skill é a receptora do contrato ("a Issue chega claimada"), este item é o produtor do claim automático. Produtor antes do receptor quebra: com a skill antiga, o Passo 1 hardcoded pnpm agent:claim rodaria no launch e pegaria o topo da fila (a claimada virou in-progress e saiu) → Issue errada. Receptor primeiro é seguro: na transição o produtor é o humano (pnpm agent:claim standalone), coberto pelo fallback de OPS32. (Alternativa sem janela: fundir 32+33 — não escolhida.)

Fora de escopo

• Reverter claim / devolver Issue à fila (ex.: humano decide não trabalhar a Issue) — outra entrega.
• Claim do pool (supervisor, worker UUID) — intacto.
• O conteúdo da skill /work-issue em si (OPS32 define; aqui é só entregar o contexto).

Rabbit holes de produto

• "Já que claima, validar o worktree, o env, o modelo, o plano…" — o script deve fazer o claim e o que já faz (worktree + provisionamento); toda validação extra que o contexto já garante é o overhead que OPS32 está removendo do outro lado.
• "Tratar falha pós-claim" (ex.: git worktree add quebra depois do claim): o claim não deve ser desfeito automaticamente — reportar e deixar o humano decidir (desfazer claim é outra entrega).

Questões em aberto (produto)

• Reabrir a sessão de uma Issue já claimada (worktree existe)? Decisão (gate 2026-08-10): detecta e segue ao launch sem re-claim (idempotente, "já claimada — reabrindo") — reabrir sessão é o caso comum e não pode exigir cerimônia.
• Como o launch entrega a Issue ao agente? Decisão (gate 2026-08-10): comando com argumento (/work-issue --issue <N>) — a skill lê o resto do GitHub; fonte única de verdade é a Issue, sem duplicar brief.
• worktree next --issue <N> deve existir? Decisão (gate 2026-08-10): sim — claim direcionado, mesmo contrato do agent:claim.

Referências

• GitHub Issue #595 (depends OPS32)
• Canvas UI (gate): N/A
• scripts/agent-claim.mjs (lógica do claim a reutilizar), scripts/lib/agent-pool-prompt.mjs (molde do contexto ao agente)
• docs/plans/worktree-go-abre-opencode-com-presets.md (OPS26 — mecanismo do launch)