Merge pull request #597 from fsolla/plans/plan-issue-27

plans: OPS31-OPS33 — worktree plan envia /plan-issue, work-issue no paradigma claimado, next claima deterministicamente

docs/plans/work-issue-paradigma-issue-claimada.md

@@ -0,0 +1,74 @@
+# Work-issue no paradigma de Issue já claimada (+ model-selection volta ao cardápio Cursor)
+
+Status: rascunho
+Atualizado em: 2026-08-10
+Issue: #594
+Priority: P2
+Model: composer-2.5
+Impeccable: A — N/A (skills de agente, sem superfície de produto)
+Canvas UI: N/A — sem UI
+Appetite: ~1–1,5 dia; um outcome verificável (sessão /work-issue sem nenhum passo de verificação)
+Responsável: —
+
+## Intenção
+
+Todo `/work-issue` hoje re-executa passos que o contexto já garante: **claim** (é um script determinístico — o próprio fluxo vai rodá-lo antes, no `worktree next`), **verificação de worktree/branch** (a sessão nasce no worktree certo) e **verificação de modelo** (a sessão é sempre DeepSeek V4 Flash na máquina do humano). Isso gasta requests/tokens toda sessão e ainda permitiu o agente-miss #582 (branch criada no main em vez da worktree). No novo paradigma, a skill assume o contrato: Issue já claimada, worktree correto, branch correta, modelo fixo — e vai direto ao trabalho. Desacopla de `agent-work-issue` (que segue sendo a skill dos workers do Cursor Cloud/pool, com suas próprias regras) e simplifica `model-selection`: sem alternativas locais (`model-local`), só o cardápio Cursor como era antes.
+
+## Persona e fluxo
+
+- **Persona / contexto:** o humano na sua máquina, sessão opencode no worktree da Issue (aberta pelo `worktree next` — OPS33). Sessão sempre DeepSeek V4 Flash.
+- **Job principal:** sair do plano de intenção ao PR com gate humano no impl plan — sem overhead de verificação.
+- **Fluxo desejado:**
+  1. `worktree next` claima e abre o opencode com `/work-issue` já informando a Issue;
+  2. a skill identifica a Issue pelo contexto da sessão (prompt/marcador do ambiente) e abre o plano de intenção — **sem** rodar `agent:claim`;
+  3. Plan mode → `*-impl.md` → **pausa** → confirmação humana → execução → `/simplify` → `capture-review-debts` com gate → PR.
+- **Anti-goals:** não virar um guarda-costas que re-verifica o que o ambiente garante; não duplicar a lógica de claim do pool; não inventar um terceiro fluxo de execução (continua havendo: humano = work-issue, pool = agent-work-issue).
+
+## Objetivo e aceite
+
+- `/work-issue` **não** roda `pnpm agent:claim`, não verifica worktree/branch e não checa modelo — assume os três do contexto (se a sessão estiver em outro modelo, segue; o fluxo é da máquina do humano, sempre Flash).
+- A skill recupera o contexto da Issue **deterministicamente**: número/ID vindo do prompt da sessão (OPS33) — se ausente, **uma** pergunta ao humano com validação, nunca um claim por conta própria.
+- O path do plano de intenção é recuperado do **body da Issue** (`Plano: [\`docs/plans/…\`]`— o`agent:register --plan`já grava; sem plano linkado, o body é a spec — mesmo contrato do prompt do pool). Nenhuma mudança no`plan-issue` é necessária para registrar o path: ele já registra.
+- Work-issue deixa de ser "a versão humana de agent-work-issue": fluxo próprio (impl plan → pausa → execução → simplify → débitos → PR), reutilizando só os materiais de engenharia (engineering-brief, implementation-template, decision-quality) como referência.
+- `model-selection` perde a tabela Local/Zed, o frontmatter `model-local:` e o mapeamento canônico `model:` → DeepSeek: volta ao cardápio só-Cursor (Composer 2.5 default; Grok com effort; Kimi K3 Low só exec bipartida). Issues declaram `model:` único.
+- Textos correlatos ajustados (passo de modelo em `agent-work-issue` e no claim brief ficam compatíveis com o cardápio novo; `plan-issue` segue sugerindo um slug único).
+- Resolve o agente-miss #582: o paradigma novo elimina a situação (a skill não cria branch nem claima — a entrega fecha #582).
+
+## Dados (intenção)
+
+- **Vou apresentar dados?** Não — sem superfície de dados.
+
+## Direção no codebase (hipótese)
+
+- **Áreas prováveis:** `.agents/skills/work-issue/SKILL.md` (reescrever: remove claim/modelo/verificações, contexto por parâmetro), `.agents/skills/agent-work-issue/SKILL.md` (referência a "base de work-issue" e passo de modelo), `.agents/skills/model-selection/SKILL.md` (remover ambiente local/`model-local`), `.agents/skills/plan-issue/SKILL.md` (Passo 4 — slug único, sem alternativa local), `scripts/agent-claim.mjs` (brief: texto de modelo sem `model-local`), `AGENTS.md` / `docs/CHANGELOG-AGENTS.md`.
+- **Precedente a olhar:** `scripts/lib/agent-pool-prompt.mjs` — o pool já resolveu "como avisar o agente da Issue claimada" (`buildPoolWorkerPrompt` + `extractPlanPath`): é o molde do contexto que a skill vai consumir.
+- **Risco de acoplamento:** o pool e o `plan-issue` dependem de `model-selection` — remover `model-local` não pode quebrar o spawn do pool (ele usa só `model:`). Work-issue parado (sem OPS33) fica com o claim fora da skill: chamada manual pede o número, não claima.
+
+## Dependências
+
+- Nenhuma (é a fundação do paradigma; OPS33 depende dela).
+- OPS32 é pré-requisito para o ponta a ponta do OPS33 (work-issue aceitar Issue já claimada).
+
+## Fora de escopo
+
+- O claim no `worktree next` (OPS33 — fluxo separado).
+- Mudar o comportamento do pool (claim coordenado, prompt de worker, spawn) — continua intacto.
+- Mecânica fina de como o prompt do launch entrega o número da Issue (OPS33 define; aqui é só consumir o que vier).
+
+## Rabbit holes de produto
+
+- **"Já que é tudo novo, reescrever a skill inteira com novo paradigma de gates"** (ex.: pausas extras, revisão de cada passo). A única mudança pedida é remover verificação/claim/modelo e ajustar a recuperação de contexto — o restante do fluxo (impl plan → pausa → execução → simplify → débitos → PR) já é o que o humano aprova.
+- **"Aproveitar para resolver a fila de agent-miss"** (#582 entra porque é o mesmo defeito; os demais agent-miss da fila são independentes). **Corte:** só o #582, por causalidade direta.
+
+## Questões em aberto (produto)
+
+- **Como o agente descobre a Issue quando o prompt não trouxe o número?** **Decisão (gate 2026-08-10):** pergunta ao humano e valida — chamada manual é exceção e 1 round resolve; claim fora da skill preserva o contrato "quem claima é o script".
+- **`model:` deve sumir do claim brief/work-issue?** **Decisão (gate 2026-08-10):** fica como metadata consultiva — o pool ainda spawna por `model:` e a linha do claim é consulta barata; só a exigência de `model-local` sai.
+
+## Referências
+
+- GitHub Issue #594
+- Canvas UI (gate): N/A
+- `scripts/lib/agent-pool-prompt.mjs` (precedente do contexto claimado + `extractPlanPath`)
+- `docs/plans/opencode-comandos-work-issue-e-plan-issue.md` (OPS25 — origem dos comandos)
+- Issue #582 (agente-miss absorvido)

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

@@ -0,0 +1,73 @@
+# 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)

docs/plans/worktree-plan-abre-opencode-com-plan-issue.md

@@ -0,0 +1,68 @@
+# Worktree plan abre o opencode com /plan-issue já enviado
+
+Status: rascunho
+Atualizado em: 2026-08-10
+Issue: #593
+Priority: P2
+Model: composer-2.5
+Impeccable: A — N/A (CLI/shell, sem superfície de produto)
+Canvas UI: N/A — sem UI
+Appetite: ~0,5 dia; um outcome verificável (o TUI abre já no fluxo de planejamento)
+Responsável: —
+
+## Intenção
+
+Na entrega OPS26 assumimos que o `--prompt` do opencode seria auto-submetido — e é. Só que o `worktree plan` ficou **sem prompt** por uma premissa equivocada: a proposição em `~/Code/propositions/opencode/prefill-prompt-sem-submit.md` queria "abrir com o prompt preenchido sem enviar", e como a CLI não tem isso, deixamos o `plan` abrir o TUI vazio (autocomplete `/plan-`). A revisão da proposição mostra o óbvio que faltou: **a necessidade real era a oposta** — iniciar com o prompt _commitado_ (enviado) — e isso o `--prompt` já faz, como o `next` prova com `/work-issue`. Queremos o mesmo para o `plan`: um comando e já estar dentro do fluxo de planejamento, sem digitar nada.
+
+## Persona e fluxo
+
+- **Persona / contexto:** o humano (dono do repo) no terminal interativo, rodando `worktree plan [bag]` para abrir uma sessão de `/plan-issue` num worktree de planejamento.
+- **Job principal:** cair direto no planejamento — abrir o TUI do opencode já executando a skill de planejamento.
+- **Fluxo desejado:**
+  1. `worktree plan [bag]` cria o worktree de planejamento (branch `plans/plan-issue-…`), provisiona o ambiente e troca o shell para lá;
+  2. o opencode abre no worktree com `/plan-issue` **já enviado** como primeira mensagem;
+  3. a sessão começa o fluxo da skill (parse → gate → registro) sem nenhuma interação extra.
+- **Anti-goals:** não virar um mecanismo de prefill-draft do opencode (isso é feature do opencode, não do Teqo); não mudar o comportamento de `--stay` nem do comando `/worktree` do opencode.
+
+## Objetivo e aceite
+
+- `worktree plan [bag]` no terminal (sem `--stay`) imprime a diretiva `launch opencode <dir> --model <preset> --auto --prompt /plan-issue` antes do `cd <dir>`.
+- O TUI abre com a skill `plan-issue` já carregada e em execução (primeira mensagem enviada), sem digitação.
+- `--stay` continua suprimindo `cd` + launch; o comando `/worktree` do opencode continua sem a diretiva (nunca TUI aninhado).
+- A proposição `~/Code/propositions/opencode/prefill-prompt-sem-submit.md` é revisada e anotada com o desfecho: a necessidade real do fluxo era **auto-envio** (coberto por `--prompt`); prefill-sem-envio segue como gap do opencode, não bloqueio do Teqo.
+- Textos correlatos atualizados (todo lugar que diga "plan sem prompt — autocomplete `/plan-`" passa a dizer "`/plan-issue` enviado").
+
+## Dados (intenção)
+
+- **Vou apresentar dados?** Não — sem superfície de dados.
+
+## Direção no codebase (hipótese)
+
+- **Áreas prováveis:** `scripts/lib/worktree.mjs` (constante `OPENCODE_SKILL_COMMAND_BY_PURPOSE` — `plan` sai de `null` para `/plan-issue`; o comentário de "gap registered for the opencode repo" sai ou muda de tom), `scripts/worktree.mjs` (docblock), `.agents/shell/worktree.sh` (comentário), `.opencode/commands/worktree.md` (doc), `AGENTS.md` / `docs/CHANGELOG-AGENTS.md`.
+- **Precedente a olhar:** plano OPS26 (`docs/plans/worktree-go-abre-opencode-com-presets.md` + `-impl.md`) — o mecanismo de launch já existe; aqui é só o valor do prompt do `plan`.
+- **Risco de acoplamento:** o mesmo mapa de constantes é usado por `next` — não mudar o comportamento do `next`; o valor do `plan` é a única mudança. Proposição opencode fica fora do repo (pasta pessoal `~/Code/propositions/`) — edição local, não commit.
+
+## Dependências
+
+- Nenhuma. (OPS33 mexe no mesmo arquivo de constantes; `serializes: [worktree-cli]` para o pool não rodar os dois em paralelo.)
+
+## Fora de escopo
+
+- Implementar `--prefill` / prefill-sem-submit no opencode (feature upstream; registrar na proposição, não codar aqui).
+- Mudar o launch do `next` (continua `/work-issue` como está).
+- Qualquer mudança no claim ou no fluxo de execução (OPS32/OPS33).
+
+## Rabbit holes de produto
+
+- **"Já que vamos mexer, deixar o plan mais esperto"** (ex.: esperar confirmação antes de enviar). O pedido é simétrico ao `next`: abrir já executando. **Corte:** mudança de valor no mapa + docs + anotação da proposição; nada mais.
+
+## Questões em aberto (produto)
+
+- **E se o opencode ganhar prefill-sem-submit no futuro?** **Decisão (gate 2026-08-10):** manter auto-envio — simetria com `next` e menos fricção; a opção fica registrada na proposição para quando o upstream existir.
+
+## Referências
+
+- GitHub Issue #593
+- Canvas UI (gate): N/A
+- `~/Code/propositions/opencode/prefill-prompt-sem-submit.md` (revisar/anotar)
+- `docs/plans/worktree-go-abre-opencode-com-presets.md` (OPS26 — mecanismo do launch)