From 74228789c5ab29b44b54d309ed5b6316e9f16c23 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Francisco=20Ign=C3=A1cio=20Fontoura=20Solla?= Date: Sun, 2 Aug 2026 18:41:41 -0300 Subject: [PATCH 1/2] =?UTF-8?q?docs(plans):=20inten=C3=A7=C3=A3o=20OPS17?= =?UTF-8?q?=20=E2=80=94=20ciclo=20de=20vida=20plan-issue=20antes=20de=20cl?= =?UTF-8?q?aim?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Related #292 --- docs/plans/plan-issue-lifecycle-ready.md | 83 ++++++++++++++++++++++++ 1 file changed, 83 insertions(+) create mode 100644 docs/plans/plan-issue-lifecycle-ready.md diff --git a/docs/plans/plan-issue-lifecycle-ready.md b/docs/plans/plan-issue-lifecycle-ready.md new file mode 100644 index 00000000..d3fc1f84 --- /dev/null +++ b/docs/plans/plan-issue-lifecycle-ready.md @@ -0,0 +1,83 @@ +# Ciclo de vida do plan-issue — colaboração fechada antes de claim + +Status: registrado (blocked até plano em main) +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:** `.cursor/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 +- `.cursor/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` +- `.cursor/skills/agent-pool/SKILL.md` From c3b121c5ec870052c72964a8c1531ab0ba604bf2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Francisco=20Ign=C3=A1cio=20Fontoura=20Solla?= Date: Sun, 2 Aug 2026 18:42:54 -0300 Subject: [PATCH 2/2] style: format OPS17 intention plan with Prettier Related #292 --- docs/plans/plan-issue-lifecycle-ready.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/plans/plan-issue-lifecycle-ready.md b/docs/plans/plan-issue-lifecycle-ready.md index d3fc1f84..9ec3b3dc 100644 --- a/docs/plans/plan-issue-lifecycle-ready.md +++ b/docs/plans/plan-issue-lifecycle-ready.md @@ -11,7 +11,7 @@ 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. +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`. @@ -42,7 +42,7 @@ Omitido — superfície A (processo). - **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* +- **Forma:** _adiada ao plano de implementação_ ## Direção no codebase (hipótese)