From 821db8278b2e76edf98a6a70059253b32af20a0d Mon Sep 17 00:00:00 2001 From: Francisco Solla Date: Wed, 16 Sep 2026 10:29:41 -0300 Subject: [PATCH] =?UTF-8?q?docs(OPS121):=20plano=20de=20verifica=C3=A7?= =?UTF-8?q?=C3=A3o=20p=C3=B3s-deploy=20em=20staging=20no=20work-issue=20(R?= =?UTF-8?q?elated=20#1079)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ...rificacao-pos-deploy-staging-work-issue.md | 86 +++++++++++++++++++ 1 file changed, 86 insertions(+) create mode 100644 docs/plans/ops121-verificacao-pos-deploy-staging-work-issue.md diff --git a/docs/plans/ops121-verificacao-pos-deploy-staging-work-issue.md b/docs/plans/ops121-verificacao-pos-deploy-staging-work-issue.md new file mode 100644 index 00000000..639a8162 --- /dev/null +++ b/docs/plans/ops121-verificacao-pos-deploy-staging-work-issue.md @@ -0,0 +1,86 @@ +# Verificação pós-deploy em staging no fluxo `work-issue` + +Status: rascunho +Atualizado em: 2026-09-16 +Issue: #1079 +Priority: P2 +Impeccable: A — N/A sem UI +Design UI: N/A — sem UI +Appetite: ~0,5–1 dia eng; um outcome verificável +Responsável: — + +## Intenção + +O fluxo `work-issue` termina no auto-merge e no flip `done` (`execution-pipeline.md:112-129`, `work-issue/SKILL.md:179-183`): ninguém olha o que o deploy de staging publicou. O merge em `main` já dispara `deploy.yml` sozinho (OPS104), o staging publica sem reviewer e a única validação pós-deploy existente é manual e do `bug-fix` (`bug-fix/SKILL.md:109`), focada em produção — não há dono de verificar funcionalmente a feature recém-entregue em staging. + +Esta entrega fecha o loop: depois do merge, o agente espera o run de staging ficar verde e abre o navegador contra `https://staging.jorgesolla1313.com.br` para testar a funcionalidade que acabou de entregar; problemas encontrados viram Issues de correção. É a camada que as suítes locais e o `verify` do deploy não cobrem. + +**Por que classe A:** o item só edita skills/docs de agente (markdown). O navegador é ferramenta de teste da feature entregue, não superfície de UI desenhada aqui — não há tela nova, novo estado visual nem artefato de design. + +## Persona e fluxo + +- **Persona / contexto:** o agente executor (work-issue) na máquina do humano, logo após o merge; humano presente mas não pilotando o teste. +- **Job principal:** confirmar, no ambiente real, que a feature entregue funciona — e transformar qualquer falha em Issue acionável. +- **Fluxo desejado:** merge verde → aguardar o run de deploy → abrir staging → exercitar só a funcionalidade entregue (390/1280, console/network) → se tudo ok, encerrar com o desfecho registrado; se falhar, abrir Issues e reportar. +- **Anti-goals de produto:** não é e2e automatizado de regressão contra staging (decidido fora de escopo no OPS103); não testa produção; não vira watchdog de deploy nem monitoramento contínuo. + +## Objetivo e aceite + +- Após o merge, o fluxo verifica funcionalmente a feature entregue em staging e registra o desfecho. +- A espera pelo deploy é limitada: em timeout, reporta e para — nunca segue em silêncio nem aguarda indefinidamente. +- Defeitos encontrados geram Issues de correção com o estado de fila correto (claimável quando cabível), sem editar a Issue original em `in-progress`. +- Nenhum passo toca o homeserver, o DB de produção ou aprova a produção; produção continua com approval humano. + +## Dados (intenção) + +- **Vou apresentar dados?** Não — é item de processo/skill; nada de superfície de dados. +- **Decisões desbloqueadas:** N/A (sem métrica); o "resultado" é o desfecho registrado na Issue/PR. +- **Forma:** _adiada ao plano de implementação._ + +## Dados da decisão (literais) + +- ID reservado: **OPS121**; kind **chore**; prio **P2**; slug `ops121-verificacao-pos-deploy-staging-work-issue`; sem UI (Impeccable A). +- Staging: `https://staging.jorgesolla1313.com.br` (noindex); container `teqo-staging`; DB `teqo_staging`; porta `127.0.0.1:1314`; bucket `teqo-media-staging`. +- Workflow: `deploy.yml` — jobs `preflight` → `verify` (hosted, full, ~50 min) → `deploy-staging` (`environment: staging`, sem reviewer) → `requeue` + `deploy-production` (`environment: production`, required reviewer). +- Consulta a runs: `scripts/lib/github-api.mjs` — `listWorkflowRuns(workflowFile, {status, branch, limit})` (:326-342), `getWorkflowRunJobs(runId)` (:349-365), `getBranchHead` (:398); token `GITHUB_TOKEN` (:80). Não existe função de poll/watch. +- Criar Issue claimável: `pnpm agent:register` — label de estado `ready` (claimável; `resolveRegisterStateLabel`, `agent-register.mjs:53-71`). Observação/guardrail: `pnpm agent:file-miss --kind defect` — `kind:defect` + `prio:P2`, **sem** `ready` ⇒ não claimável (`agent-file-miss.mjs:24,37`). +- Browser: Playwright MCP já configurado (`~/.config/opencode/opencode.jsonc`, `@playwright/mcp`, chromium). +- Skills do fluxo: `.agents/skills/work-issue/SKILL.md`, `agent-work-issue/SKILL.md`, `work-issue/execution-pipeline.md`, `browser-testing-with-devtools/SKILL.md`, `bug-fix/SKILL.md`. + +## Direção no codebase (hipótese) + +- **Áreas prováveis:** `.agents/skills/work-issue/execution-pipeline.md` (dono da mecânica de fechamento compartilhada) ganha §Verificação pós-deploy (staging); `work-issue/SKILL.md` (Passo 7 + checklist) e `agent-work-issue/SKILL.md` (Passo 6 + checklist) declaram o delta do ator. +- **Precedente a olhar:** `bug-fix/SKILL.md:109` (validação pós-deploy, versão manual/prod); `deploy-preflight.mjs` / `auto-unblock.mjs` (consumo de `github-api.mjs` e gate do `verify`). +- **Risco de acoplamento:** a espera deve ser limitada e não pode aprovar produção nem tocar o homeserver; o `verify` full pode levar ~50 min, então a espera precisa de teto explícito. + +## Dependências + +- Nenhuma dura. Contexto: OPS103 (staging), OPS104 (trigger no merge), OPS107 (aprovação) — todos já entregues. + +## Fora de escopo + +- E2E automatizado de regressão contra staging (decidido fora no OPS103: `ops103-staging-homeserver.md:69,80,87`) — destino: item próprio se houver evidência. +- Verificação/approve de produção — permanece humano; `bug-fix` mantém sua confirmação manual em prod. +- Watchdog/monitoramento contínuo do deploy. + +## Rabbit holes de produto + +- **Virar suíte e2e contra staging.** Se alguém "só completar": duplicates de cobertura, flaky e manutenção de ambiente. **Corte neste item:** teste manual via navegador limitado à funcionalidade entregue. +- **Esperar o deploy indefinidamente.** Se alguém "só completar": sessão pendurada ~50 min+ por run. **Corte neste item:** teto de tempo + timeout que reporta e para. +- **Absorver o passo do bug-fix.** Se alguém "só completar": duas fontes de verdade sobre pós-deploy. **Corte neste item:** donos separados (staging funcional aqui; prod manual no bug-fix). + +## Questões em aberto (produto) + +- **Escopo do passo: só `work-issue` ou também `agent-work-issue`?** **Opções:** A só `work-issue` | B ambos via pipeline | C pipeline declara a mecânica e o pool declara delta "sem browser no Cloud". **Recomendação:** C — dono é `execution-pipeline.md`; `work-issue` executa; `agent-work-issue` (autônomo, dormente, Cloud sem browsers) registra justificativa/defer no delta em vez de fingir o passo. _(assumido — validar com produto)_ +- **Espera pelo deploy (tempo/polling e timeout)?** **Opções:** A poll curto + teto ~60 min | B só reportar o run ao humano e não esperar | C espera infinita. **Recomendação:** A — polling do run do `deploy-staging` pelo head SHA, teto explícito (~60 min, `verify` ~50 min); em timeout, reportar e parar. _(assumido — validar com produto)_ +- **O que testar e como tratar backend-only?** **Opções:** A test plan derivado dos critérios de aceite + `*-impl.md`, 390/1280, console/network | B testar tudo que a página oferece. **Recomendação:** A limitado à funcionalidade entregue; sem superfície de browser (backend-only), registrar smoke HTTP/API mínimo ou N/A justificado, sem inventar UI. _(assumido — validar com produto)_ +- **Mecanismo para defeitos: claimável vs triage, e reabrir a Issue original?** **Opções:** A `agent:register` com `ready` para defeito funcional no escopo e `agent:file-miss --kind defect` para observações | B só `file-miss`. **Recomendação:** A; a Issue original (já `done`) **não** reabre — recebe um comentário linkando a Issue nova. _(assumido — validar com produto)_ +- **Relação com `bug-fix` (que tem passo pós-deploy manual)?** **Opções:** A unificar | B manter separados e cruzados. **Recomendação:** B — `bug-fix` é dono da confirmação manual em prod de um bug; OPS121 é dono da verificação funcional em staging de uma feature; compartilham nomenclatura/links, não código. + +## Referências + +- GitHub Issue #1079 +- Design UI (gate): N/A +- `.agents/skills/work-issue/execution-pipeline.md` (§Fechar em main), `.agents/skills/work-issue/SKILL.md` (Passo 7), `.agents/skills/agent-work-issue/SKILL.md` (Passo 6), `.agents/skills/bug-fix/SKILL.md:106-109`, `.agents/skills/browser-testing-with-devtools/SKILL.md` +- `scripts/lib/github-api.mjs`, `scripts/agent-register.mjs`, `scripts/agent-file-miss.mjs`, `.github/workflows/deploy.yml` +- `docs/ops/teqo-1313-deploy.md:193-200` (limites de staging: WebAuthn/OAuth/Resend não validados)