teqo-backup/docs/plans/plan-issue-lifecycle-ready.md

# Ciclo de vida do plan-issue — colaboração fechada antes de claim

Status: em execução (impl em andamento)
Atualizado em: 2026-08-02
Issue: #292
Priority: P1
Model: cursor-grok-4.5-medium
Impeccable: A — N/A (processo/skills + tooling do paradigma; sem UI)
Appetite: ~0,5–1 dia eng; um outcome verificável
Responsável: —

## Intenção

Enquanto se colabora no `/plan-issue`, o agente às vezes registra Issues e abre o PR de planos **antes** do lote estar fechado. Como `agent:register` nasce com label `ready`, o pool (ou outro claim) pode pegar a Issue — e o humano ainda está mudando a intenção. Pior: a ordem atual (Issue `ready` → depois PR do plano) permite claim **antes** do plano existir em `main`; o link de plano hoje é só _warn_, não bloqueio.

Queremos um ciclo em que colaborar é barato de reverter, e só vira trabalho claimável quando a intenção está confirmada **e** o plano de intenção está em `main`.

## Persona e fluxo

- **Persona / contexto:** humano moldando um lote com o agente; pool autônomo rodando em paralelo.
- **Job principal:** fechar intenção sem medo de que o pool já esteja executando a versão errada.
- **Fluxo desejado:**
  1. Explorar / fatiar / rascunhar planos locais (`Issue: —`).
  2. Overview do lote (gate) → iterar até o humano **confirmar explicitamente**.
  3. Só então: registrar Issues **ainda não claimáveis**, commit + PR dos planos (`Related #N`), merge em `main`.
  4. Só então: Issues passam a `ready` e entram na fila.
- **Anti-goals de produto:** não inventar um segundo tracker fora do GitHub; não exigir revisão humana no PR de planos além do auto-merge já existente; não travar chores sem plano (`agent:file-miss`, débitos triviais).

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

Omitido — superfície A (processo).

## Objetivo e aceite

- Colaborar no lote **não** cria Issue no GitHub nem PR até confirmação explícita do humano após o overview.
- Issue nascida de `plan-issue` com plano **não** é claimável (`ready`) enquanto o plano de intenção não estiver em `main`.
- Depois do plano em `main`, a Issue fica claimável sem passo humano extra opaco (promote determinístico no fim do registro / pós-merge).
- Chores/specs sem `--plan` continuam podendo nascer `ready` (comportamento atual preservado onde não há plano).
- Critério verificável: com pool ligado, uma Issue recém-registrada com plano linkado **não** aparece na fila elegível até o promote pós-plano-em-`main`.

## Dados (intenção)

- **Vou apresentar dados?** Não
- **Decisões desbloqueadas:** N/A — processo do paradigma, não métrica de campanha.
- **Forma:** _adiada ao plano de implementação_

## Direção no codebase (hipótese)

- **Áreas prováveis:** `.agents/skills/plan-issue/` (SKILL + checklist Passo 5/6), `scripts/agent-register.mjs`, elegibilidade do pool (`scripts/lib/agent-pool-eligibility.mjs` + pins em `tests/unit/agentPoolEligibility.unit.spec.ts`), menção curta em `docs/AGENT-OPS.md` / skill `agent-pool` se o contrato de labels mudar.
- **Precedente a olhar:** gate Passo 5 já escrito na skill (hoje só soft); `needs:consent` / `requirements-changed` como “não claimar”; OPS12 `plans-only-closes` (`Related #N`).
- **Risco de acoplamento:** fila `ready` é o contrato compartilhado de `agent:claim` e do pool — mudar o momento do flip afeta os dois.

## Dependências

- Nenhuma dura. Soft: pool ativo torna a race visível; o contrato vale mesmo com pool parado.

## Fora de escopo

- Reescrever o paradigm inteiro / bipartir plan-exec.
- UI de board / segundo estado visual no GitHub Projects.
- Exigir plano em arquivo para **toda** Issue (chores body-only continuam ok).
- Safety net Action “no merge de `docs/plans/**` promove Issues” — nice-to-have; v1 pode ser o próprio Passo 6 pós-merge do PR de planos.

## Rabbit holes de produto

- **Novo label `spec`/`planning`.** Se alguém “só completar”: proliferação de estados. **Corte neste item:** reusar `blocked` (ou um `needs:*` já no vocabulário de gate humano) até o promote → `ready`; só criar label nova se `blocked` confundir demais com dep bloqueada.
- **Verificar blob do plano no tick do pool (IO no GitHub a cada 10 min).** **Corte neste item:** preferir “não nasce `ready` até promote”; checagem de arquivo em `main` só se o promote sozinho não fechar o buraco.
- **Frase mágica rígida demais.** **Corte:** confirmação explícita após o overview (ex. “confirma o lote” / “pode registrar”); não exigir token cerimonial único se o humano já disse claramente para registrar.

## Questões em aberto (produto)

- **Enquanto espera o plano em `main`, a Issue fica com qual label?** **Opções:** A) `blocked` (já exclui claim/pool) · B) novo `needs:plan` no conjunto human-gate · C) sem Issue até o plano mergear (inverte ordem; complica `Related #N`). **Recomendação:** A — register com `--plan` implica não-`ready` (`blocked`); promote `blocked`→`ready` quando o plano estiver em `main`. _(assumido — validar)_
- **Quem promove para `ready`?** **Opções:** A) fim do Passo 6 na mesma sessão (após merge do PR de planos) · B) Action no merge de `docs/plans/**` · C) sempre humano. **Recomendação:** A no v1; B fora de escopo salvo se A falhar na prática. _(assumido — validar)_
- **Confirmção do gate:** basta overview + “pode registrar”, ou o agente pode registrar se o humano só disser “ok” ambíguo no meio da edição? **Opções:** A) só após overview apresentado + OK explícito ao lote · B) qualquer “ok” conta. **Recomendação:** A. _(assumido — validar)_

## Referências

- GitHub Issue #292
- `.agents/skills/plan-issue/SKILL.md` (Passo 5 gate / Passo 6 register)
- `scripts/agent-register.mjs` (default `ready`)
- `scripts/lib/agent-pool-eligibility.mjs` (`issueHasPlanLink` = warn)
- `docs/AGENT-OPS.md`
- `.agents/skills/agent-pool/SKILL.md`