fsolla/teqo-backup
1
0
Fork 0
mirror of https://github.com/fsolla/teqo.git synced 2026-11-15 10:43:07 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions
teqo-backup/docs/plans/plan-issue-promote-dual.md
Cursor Agent b7f4e16c0f
feat(ops): OPS18 — Action promote Related #N no merge 
Safety net dual com agent:ready: no merge em main, workflow lê Related #N
e promove Issues ainda aguardando plano (canPromotePlanIssue), soft-skip
idempotente. Helper parseRelatedIssueNumbers + pins unitários.

Co-authored-by: Francisco Solla <fsolla@users.noreply.github.com>
2026-08-03 00:20:48 +00:00

4.2 KiB
Raw Blame History

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, .cursor/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
  • .cursor/skills/plan-issue/SKILL.md
  • docs/plans/plan-issue-lifecycle-ready.md