teqo-backup/docs/plans/plan-issue-promote-dual.md

Promote plan-issue — agente + Action no merge (dual path)

Status: em execução Atualizado em: 2026-08-03 Issue: #296 Priority: P1 Model: cursor-grok-4.5-medium Impeccable: A — N/A (workflow + skill; sem UI) Appetite: ~0,5 dia eng; um outcome verificável Responsável: pool

Intenção

A OPS17 fecha o ciclo “colaborar → register não-claimável → plano em main → ready”. O promote blocked→ready ainda pode ficar só na sessão do agente (como no registro do #292/#293). Se a sessão cair ou o Passo 6 pular o flip, a Issue fica blocked para sempre com plano já em main.

Queremos o promote robusto: caminho feliz no agente e caminho determinístico no merge, sem reabrir a race de claim antes do plano existir em main.

Persona e fluxo

• Persona / contexto: humano/agente no /plan-issue; pool claimando Issues ready.
• Job principal: depois do plano mergeado, a Issue vira claimável mesmo se o agente do plan-issue não promoveu.
• Fluxo desejado:
  1. Register com plano → Issue blocked (contrato OPS17).
  2. PR de planos com Related #N → merge em main.
  3. Agente (Passo 6) tenta blocked→ready (idempotente).
  4. Action no merge também lê Related #N e promove se a Issue ainda estiver aguardando plano.
• Anti-goals de produto: não promover no CI do PR aberto (Issue ready antes do merge); não promover qualquer blocked citado em Related (deps de produto).

Esboço de fluxo (B/C/D)

Omitido — superfície A.

Objetivo e aceite

• Action (ou job irmão de issue-done-on-main-merge.yml) roda só quando o PR mergeia em main.
• Body com Related #N: se a Issue alvo está no estado “aguardando plano” (blocked + link docs/plans/ no body, ou heurística equivalente conservadora) → remove blocked, adiciona ready, comenta o motivo.
• Idempotente com o promote do agente (segunda execução é no-op / seguro).
• Skill plan-issue Passo 6 documenta o promote do agente e aponta o safety net da Action.
• Critério verificável: Issue blocked+plano, PR só-planos com Related #N mergeado sem flip do agente → Issue fica ready via Action.

Dados (intenção)

• Vou apresentar dados? Não
• Decisões desbloqueadas: N/A
• Forma: adiada ao plano de implementação

Direção no codebase (hipótese)

• Áreas prováveis: novo workflow (ou extensão cuidadosa de issue-done-on-main-merge.yml), helper puro testável para parse de Related #N + regra de promote, .agents/skills/plan-issue/SKILL.md (Passo 6), nota em docs/AGENT-OPS.md.
• Precedente a olhar: issue-done-on-main-merge.yml (Closes→done); OPS12 plans-only-closes; OPS17 #292 / docs/plans/plan-issue-lifecycle-ready.md.
• Risco de acoplamento: flip frouxo promove Issue blocked por dependência de produto; misturar com o job de Closes sem cuidado.

Dependências

• Soft/dura: OPS17 (#292) — o contrato “register com --plan → blocked” é o que a Action consome. Pode aterrissar em paralelo se a Action for no-op até esse contrato existir; preferir depends: [OPS17] para não claimar promote sem o ciclo de register.

Fora de escopo

• Reabrir / reescrever o plano da OPS17 (intenção congelada para quem já claimou).
• Promover no job ci-pr enquanto o PR está aberto.
• Exigir plano em arquivo para Issues sem --plan.
• UI / Projects board.

Rabbit holes de produto

• Promover todo Related #N. Corte: heurística conservadora (link de plano e/ou estado inequívoco de “aguardando plano”).
• Só Action, matar promote do agente. Corte: manter os dois — sessão feliz + safety net.

Questões em aberto (produto)

• Heurística do flip? Opções: A) blocked + link docs/plans/ no body · B) label needs:plan · C) qualquer blocked em Related. Recomendação: A. (assumido — validar)
• Depends duro em OPS17? Opções: A) sim (depends: [OPS17]) · B) soft / paralelo. Recomendação: A. (assumido — validar)

Referências

• GitHub Issue #296
• GitHub Issue OPS17 #292
• .github/workflows/issue-done-on-main-merge.yml
• .agents/skills/plan-issue/SKILL.md
• docs/plans/plan-issue-lifecycle-ready.md