diff --git a/.cursor/skills/agent-pool/SKILL.md b/.cursor/skills/agent-pool/SKILL.md index 8018f84e..3dffd77a 100644 --- a/.cursor/skills/agent-pool/SKILL.md +++ b/.cursor/skills/agent-pool/SKILL.md @@ -93,7 +93,7 @@ Os wrappers disparam `gh workflow run agent-pool.yml -f action=…`; acompanhe c `ready` → (tick: claim coordenado, flip + marcador) → `in-progress` → worker spawnado com o `model:` da Issue (fallback `composer-2.5` + **`fast=false`** — omitir `fast` na API vira `composer-2.5-fast` no usage) → PR `--base main` com `Closes #N` → CI green → auto-merge → `done`+`in-prod` (flip determinístico do CI) → tick arquiva o agente e repõe o slot. -Issues nascidas de `plan-issue` com `--plan` **não** entram como `ready`: ficam `blocked` até o plano de intenção estar em `main` e `pnpm agent:ready` (OPS17). O tick não promove — só consome `ready`. +Issues nascidas de `plan-issue` com `--plan` **não** entram como `ready`: ficam `blocked` até o plano de intenção estar em `main` e promote dual (OPS17 `pnpm agent:ready` + OPS18 Action no merge com `Related #N`). O tick não promove — só consome `ready`. - **Falha terminal** (run ERROR/CANCELLED/EXPIRED ou fim sem PR): tick comenta, move a Issue para `blocked` e arquiva o agente. **Triage humana**: ler o run em cursor.com/agents, decidir — re-`ready` manual se transitório (o circuit breaker recusa a 3ª tentativa automática), corrigir a spec se sistêmico. - **Worker travado**: archive em cursor.com/agents → o próximo tick reconcilia como falha documentada. diff --git a/.cursor/skills/plan-issue/SKILL.md b/.cursor/skills/plan-issue/SKILL.md index 6a0d1c1a..5bd89714 100644 --- a/.cursor/skills/plan-issue/SKILL.md +++ b/.cursor/skills/plan-issue/SKILL.md @@ -157,7 +157,7 @@ Sem `--plan`: nasce `ready` (use `--blocked` só se quiser não-claimável sem p pnpm agent:ready -- --issue ``` -A Action de merge (OPS18) é safety net se este passo falhar — não pule o promote do agente no caminho feliz. +A Action de merge (`plan-issue-ready-on-main-merge.yml`, OPS18) é safety net se este passo falhar — não pule o promote do agente no caminho feliz. **NÃO faz:** editar `docs/roadmap.md`; implementar código; claim; escrever `*-impl.md`; editar plano de Issue `in-progress`/`done`/`in-prod`; marcar `ready` antes do plano em `main`; registrar/abrir PR antes do gate. diff --git a/.github/workflows/plan-issue-ready-on-main-merge.yml b/.github/workflows/plan-issue-ready-on-main-merge.yml new file mode 100644 index 00000000..64728905 --- /dev/null +++ b/.github/workflows/plan-issue-ready-on-main-merge.yml @@ -0,0 +1,31 @@ +# Safety net OPS18: when a PR merges to main with `Related #N`, promote Issues +# that are still awaiting their intention plan (`blocked` + docs/plans/ link) +# to `ready`. Idempotent with `pnpm agent:ready` (agent happy path). +# +# Does NOT run on open PRs — only after merge — so the claim race stays closed. +name: Promote plan-issue Related on main merge + +on: + pull_request: + types: [closed] + +permissions: + issues: write + pull-requests: read + contents: read + +jobs: + plan-issue-ready: + if: github.event.pull_request.base.ref == 'main' && github.event.pull_request.merged == true + runs-on: ubuntu-latest + timeout-minutes: 5 + env: + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + PR_NUMBER: ${{ github.event.pull_request.number }} + steps: + - uses: actions/checkout@v5 + - uses: actions/setup-node@v5 + with: + node-version: 24 + - name: Promote Related #N awaiting plan → ready + run: node scripts/agent-promote-related-on-merge.mjs --pr "$PR_NUMBER" diff --git a/docs/AGENT-OPS.md b/docs/AGENT-OPS.md index b157e5c6..0861ddce 100644 --- a/docs/AGENT-OPS.md +++ b/docs/AGENT-OPS.md @@ -49,7 +49,7 @@ main → ci.yml full suite → vercel deploy --prod (se verde) → requeue se HE Labels: `ready|in-progress|blocked|done|in-prod`, `prio:*`, `kind:*`, `needs:*`. -**plan-issue (OPS17):** gate pós-overview fecha o lote antes de qualquer Issue/PR; register com `--plan` nasce `blocked` (não entra na fila do claim/pool); após o PR de planos mergear em `main` (`Related #N`), `pnpm agent:ready` promove a `ready`. Chores sem plano continuam nascendo `ready`. +**plan-issue (OPS17 + OPS18):** gate pós-overview fecha o lote antes de qualquer Issue/PR; register com `--plan` nasce `blocked` (não entra na fila do claim/pool); após o PR de planos mergear em `main` (`Related #N`), promote dual idempotente: (A) `pnpm agent:ready` na sessão; (B) Action `plan-issue-ready-on-main-merge.yml` lê `Related #N` e promove Issues ainda “aguardando plano” (`blocked` + link `docs/plans/`). Chores sem plano continuam nascendo `ready`. ## Contrato de PR @@ -63,7 +63,8 @@ Labels: `ready|in-progress|blocked|done|in-prod`, `prio:*`, `kind:*`, `needs:*`. | ------------------------------ | -------------------------------------- | ------------------- | --------------------------------------------------------------------------------------------------------------------- | | `ci-pr.yml` | PR → `main` | service Postgres 17 | Fase 1 barata → fase 2 cara; skips via `ci-scope.mjs`; fail-fast cancela o run no 1º job vermelho; rollup `checks` | | `ci.yml` | push / dispatch `main` | service Postgres | Full sempre; fail-fast cancela o run no 1º job vermelho → `deploy` (`vercel deploy --prod`) → `requeue` se HEAD andou | -| `issue-done-on-main-merge.yml` | PR merged → `main` | — | `in-progress` → `done` + `in-prod` | +| `issue-done-on-main-merge.yml` | PR merged → `main` | — | `Closes`/`Fixes` → `done` + `in-prod` | +| `plan-issue-ready-on-main-merge.yml` | PR merged → `main` | — | `Related #N` aguardando plano → `ready` (OPS18; soft-skip) | | `agent-pr-ready-automerge.yml` | PR `cursor/*` → `main` (open/sync/…) | — | Draft→Ready + `gh pr merge --auto --merge` (safety net; audit incluso) | | `agent-pool.yml` | schedule / PR closed `main` / dispatch | — | Supervisor do pool (`POOL_GITHUB_TOKEN`) | diff --git a/docs/CHANGELOG-AGENTS.md b/docs/CHANGELOG-AGENTS.md index 3a8179e8..020e4852 100644 --- a/docs/CHANGELOG-AGENTS.md +++ b/docs/CHANGELOG-AGENTS.md @@ -4,6 +4,8 @@ Conteúdo movido do `AGENTS.md` em 2026-07-30 (fatiamento do paradigma de agente --- +**Recently resolved (2026-08-03):** **OPS18** (Issue #296) — promote dual plan-issue: Action `plan-issue-ready-on-main-merge.yml` no merge lê `Related #N` e promove Issues ainda aguardando plano (`canPromotePlanIssue`); idempotente com `pnpm agent:ready`. Planos: [`plan-issue-promote-dual.md`](docs/plans/plan-issue-promote-dual.md), impl [`plan-issue-promote-dual-impl.md`](docs/plans/plan-issue-promote-dual-impl.md). + **Recently resolved (2026-08-02):** **OPS17** (Issue #292) — ciclo plan-issue: gate pós-overview antes de Issue/PR; `agent:register --plan` nasce `blocked`; após plano em `main`, `pnpm agent:ready` promove a `ready`. Planos: [`plan-issue-lifecycle-ready.md`](docs/plans/plan-issue-lifecycle-ready.md), impl [`plan-issue-lifecycle-ready-impl.md`](docs/plans/plan-issue-lifecycle-ready-impl.md). Action dual no merge = OPS18 (#296). **Recently resolved (2026-08-02):** **B147** (Issue #330) — rota paralela `/campanha/municipio//v2` com faixa de status (nível · tendência · sinal · classe · frescor) e modal de motivo opcional; soft-dep B134 no write de nível (motivo opcional, sem “voltar atrás”). Intenção [`municipio-v2-shell-status.md`](docs/plans/municipio-v2-shell-status.md); impl [`municipio-v2-shell-status-impl.md`](docs/plans/municipio-v2-shell-status-impl.md). Filhos B148–B152. diff --git a/docs/plans/plan-issue-promote-dual-impl.md b/docs/plans/plan-issue-promote-dual-impl.md new file mode 100644 index 00000000..f5334346 --- /dev/null +++ b/docs/plans/plan-issue-promote-dual-impl.md @@ -0,0 +1,87 @@ +# Impl: Promote plan-issue — agente + Action no merge (dual) + +Status: aprovado +Atualizado em: 2026-08-03 +Issue: #296 +Intenção: docs/plans/plan-issue-promote-dual.md +Appetite restante: ~0,5d (workflow + helper puro + script + pins; sem UI) + +## Leitura da intenção + +- **Outcome:** depois do plano em `main`, a Issue `blocked` aguardando plano vira `ready` mesmo se o agente do plan-issue não rodou `pnpm agent:ready`. +- **O que NÃO negociar:** promote só no **merge** (nunca no CI do PR aberto); não promover `blocked` de produto/deps sem heurística conservadora (`blocked` + link `docs/plans/` + sem gates humanos / estados ativos-terminais). +- **O que reavaliar:** “estender `issue-done-on-main-merge.yml` vs job irmão”; “bash inline vs node reusando `canPromotePlanIssue`”; restrição extra a diff `docs/plans/**`. + +## Abordagem recomendada + +```mermaid +flowchart LR + Merge["PR merge → main"] --> Parse["parseRelatedIssueNumbers(body)"] + Parse --> Fetch["gh issue view #N"] + Fetch --> Gate["canPromotePlanIssue"] + Gate -->|ok| Flip["blocked→ready + comment"] + Gate -->|no-op| Skip["log skip"] + Agent["pnpm agent:ready"] --> Gate +``` + +**Opções consideradas:** A) segundo job no mesmo workflow de `Closes`→`done` · B) workflow irmão dedicado + script node que reusa `canPromotePlanIssue` · C) bash inline reimplementando a heurística +**Recomendação:** B — porque o predicado de promote já vive em `scripts/lib/agent-plan-lifecycle.mjs` (OPS17); duplicar em bash é débito; misturar com o job de `Closes` acopla dois contratos e força checkout/`node` no job que hoje é só `gh`. +**Rejeitadas:** A — checkout + install no workflow de done só para um job; C — diverge do pin unitário e do `agent:ready`. + +### Decisões de engenharia + +1. **Onde vive o parse de `Related #N`?** + Opções: A) `plansOnlyClosesGuard.mjs` · B) `agent-plan-lifecycle.mjs` · C) só no script da Action. + **Recomendação:** B — é o lifecycle de promote; o guard de closes só rejeita keywords de fechamento. + **Rejeitadas:** A (domínio errado); C (sem pin unitário). + +2. **Restringir a PRs que tocam `docs/plans/`?** + Opções: A) sim · B) não — só `Related` + `canPromotePlanIssue`. + **Recomendação:** B — `Related #N` já é o contrato dos PRs de planos (`plans-only-closes`); o predicado conservador evita flip de deps de produto. Restrição de path é rabbit hole (API de files, false negatives em PRs mistos). + **Rejeitada:** A até haver falso positivo real. + +3. **Script da Action vs estender `agent:ready`?** + Opções: A) `agent:ready -- --from-pr N` soft · B) script dedicado `agent-promote-related-on-merge.mjs` soft-skip. + **Recomendação:** B — `agent:ready` continua fail-closed para o humano/agente; a Action precisa soft-skip em Issues Related que não estão “aguardando plano”. + **Rejeitada:** A — mistura UX CLI com safety net. + +4. **`pnpm install` no workflow?** + Opções: A) install frozen · B) só `actions/setup-node` + `node scripts/…` (deps só stdlib). + **Recomendação:** B — a cadeia `agent-plan-lifecycle` → `agent-github` / `agent-pool-eligibility` não importa packages npm. + **Rejeitada:** A — custo sem ganho. + +### Componentes / mudanças + +- **`parseRelatedIssueNumbers(body)`** (`scripts/lib/agent-plan-lifecycle.mjs`): puro; case-insensitive; dedupe; ignora `Closes`/`Fixes`. +- **`scripts/agent-promote-related-on-merge.mjs`:** lê body do PR via `gh`; para cada `#N`, `canPromotePlanIssue`; flip + comentário “Action OPS18”; soft-skip (incl. already-ready). +- **`.github/workflows/plan-issue-ready-on-main-merge.yml`:** `pull_request` closed + merged → `main`; checkout + node 24; sem pnpm. +- **Docs:** `docs/AGENT-OPS.md` (tabela CI + nota OPS17/18); changelog curto; skill `plan-issue` já cita OPS18 — só amarrar o nome do workflow se faltar. +- **Migration / Access / Consent / UI:** N/A. + +## Fases verificáveis + +1. **Tracer** — helper + pins unit + script + workflow. +2. **Docs** — AGENT-OPS + changelog; skill se necessário. +3. **Gates** — `pnpm gate:fast`; entrega com `pnpm push`. + +## Rabbit holes / Não escopo (engenharia) + +- Promover no `ci-pr` / checks do PR aberto. +- Label nova `needs:plan`. +- Matar o promote do agente (`agent:ready`). +- Hoist de `HUMAN_GATE_LABELS` / `issueHasPlanLink` para módulo neutro (ainda 2–3 call sites; defer). +- Batch soft-fail em `agent:ready` CLI. + +## Riscos e mitigação + +- **Flip frouxo de `Related` de dep de produto:** mitiga `canPromotePlanIssue` (exige link `docs/plans/` + `blocked` + sem needs:\*/estados). +- **Segunda execução (agente + Action):** idempotente — already-ready = skip. +- **Workflow só na default branch:** igual aos outros merge triggers; merge em `main` é o evento. + +## Aceite de engenharia + +- [x] Aceite de produto da intenção ainda coberto +- [x] Invariantes AGENTS/engineering-standards (sem schema/access) +- [x] Testes de domínio: unit em `parseRelatedIssueNumbers` + predicado existente + +Self-score decision-quality: 5/5 diff --git a/docs/plans/plan-issue-promote-dual.md b/docs/plans/plan-issue-promote-dual.md index db86c1c5..75b9a6f2 100644 --- a/docs/plans/plan-issue-promote-dual.md +++ b/docs/plans/plan-issue-promote-dual.md @@ -1,13 +1,13 @@ # Promote plan-issue — agente + Action no merge (dual path) -Status: registrado (blocked até plano em main) -Atualizado em: 2026-08-02 +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: — +Responsável: pool ## Intenção diff --git a/scripts/agent-promote-related-on-merge.mjs b/scripts/agent-promote-related-on-merge.mjs new file mode 100644 index 00000000..63c8e950 --- /dev/null +++ b/scripts/agent-promote-related-on-merge.mjs @@ -0,0 +1,75 @@ +/** + * OPS18 safety net — on PR merge to `main`, promote plan-issue Issues cited as + * `Related #N` from `blocked` → `ready` when they are still awaiting a plan. + * + * Soft-skip (never fail the workflow) when an issue is already ready, product- + * blocked without a plan link, gated by needs:*, or otherwise ineligible. + * Idempotent with `pnpm agent:ready`. + * + * node scripts/agent-promote-related-on-merge.mjs --pr 123 + * + * Env: GH_TOKEN (Actions), GITHUB_REPOSITORY (optional — gh uses default remote). + */ + +import { dieAgent, gh, ghJson, labelNames, parseArgs, setLabels } from './lib/agent-github.mjs' +import { canPromotePlanIssue, parseRelatedIssueNumbers } from './lib/agent-plan-lifecycle.mjs' + +const die = dieAgent('promote-related-on-merge') +const { flags } = parseArgs(process.argv.slice(2), new Set(['pr'])) + +if (!flags.pr || !/^\d+$/.test(String(flags.pr))) { + die('Usage: node scripts/agent-promote-related-on-merge.mjs --pr ') +} + +const prNumber = Number(flags.pr) +const pr = ghJson(['pr', 'view', String(prNumber), '--json', 'body,number,url']) +const numbers = parseRelatedIssueNumbers(pr.body) + +if (numbers.length === 0) { + console.log(`[agent:promote-related] PR #${prNumber}: no Related #N — nothing to do`) + process.exit(0) +} + +console.log( + `[agent:promote-related] PR #${prNumber}: Related → ${numbers.map((n) => `#${n}`).join(', ')}`, +) + +for (const number of numbers) { + let issue + try { + issue = ghJson([ + 'issue', + 'view', + String(number), + '--json', + 'number,title,body,state,labels', + ]) + } catch (error) { + console.log( + `[agent:promote-related] #${number}: skip (issue view failed: ${ + error instanceof Error ? error.message : String(error) + })`, + ) + continue + } + + const verdict = canPromotePlanIssue(issue) + if (!verdict.ok) { + if (verdict.reason === 'not-blocked' && labelNames(issue).includes('ready')) { + console.log(`[agent:promote-related] #${number}: already ready — skip`) + continue + } + console.log(`[agent:promote-related] #${number}: skip (${verdict.reason})`) + continue + } + + setLabels(number, { add: ['ready'], remove: ['blocked'] }) + gh([ + 'issue', + 'comment', + String(number), + '--body', + `Promovido a \`ready\` via Action OPS18 — plano de intenção em \`main\` (PR #${prNumber} com \`Related #${number}\`).`, + ]) + console.log(`[agent:promote-related] #${number}: blocked → ready`) +} diff --git a/scripts/lib/agent-plan-lifecycle.mjs b/scripts/lib/agent-plan-lifecycle.mjs index 0510b513..69e2d056 100644 --- a/scripts/lib/agent-plan-lifecycle.mjs +++ b/scripts/lib/agent-plan-lifecycle.mjs @@ -1,8 +1,10 @@ /** - * Plan-issue lifecycle helpers (OPS17): register with `--plan` starts non-claimable; - * promote to `ready` only after the intention plan is on `main`. + * Plan-issue lifecycle helpers (OPS17 + OPS18): register with `--plan` starts + * non-claimable; promote to `ready` only after the intention plan is on `main` + * (agent `pnpm agent:ready` and/or merge Action reading `Related #N`). * - * Pure — no IO. Used by `agent-register` / `agent-ready` and pinned by unit tests. + * Pure — no IO. Used by `agent-register` / `agent-ready` / the OPS18 Action + * script and pinned by unit tests. */ import { labelNames } from './agent-github.mjs' @@ -21,6 +23,29 @@ export const resolveRegisterStateLabel = ({ hasPlan, explicitBlocked = false }) const TERMINAL_OR_ACTIVE = ['in-progress', 'done', 'in-prod'] +/** `Related #N` only — never closing keywords (those are owned by issue-done). */ +const RELATED_ISSUE_RE = /\brelated\s+#(\d+)\b/gi + +/** + * Issue numbers cited as `Related #N` in a PR body (plans-only contract). + * Deduped, stable first-seen order. Ignores Closes/Fixes/Resolves. + * + * @param {string | null | undefined} body + * @returns {number[]} + */ +export const parseRelatedIssueNumbers = (body) => { + if (!body) return [] + const seen = new Set() + const numbers = [] + for (const match of body.matchAll(RELATED_ISSUE_RE)) { + const number = Number(match[1]) + if (seen.has(number)) continue + seen.add(number) + numbers.push(number) + } + return numbers +} + /** * Whether an issue is waiting for its intention plan on `main` and may be * flipped `blocked` → `ready` by `agent:ready` (or the OPS18 Action). diff --git a/tests/unit/agentPlanLifecycle.unit.spec.ts b/tests/unit/agentPlanLifecycle.unit.spec.ts index 158a76e2..a674f6b9 100644 --- a/tests/unit/agentPlanLifecycle.unit.spec.ts +++ b/tests/unit/agentPlanLifecycle.unit.spec.ts @@ -4,6 +4,7 @@ import { describe, expect, it } from 'vitest' import { canPromotePlanIssue, + parseRelatedIssueNumbers, resolveRegisterStateLabel, } from '../../scripts/lib/agent-plan-lifecycle.mjs' @@ -87,3 +88,23 @@ describe('canPromotePlanIssue', () => { }) }) }) + +describe('parseRelatedIssueNumbers', () => { + it('extracts Related #N case-insensitively and dedupes', () => { + expect(parseRelatedIssueNumbers('Related #296\nrelated #296 and RELATED #301')).toEqual([ + 296, 301, + ]) + }) + + it('ignores closing keywords (Closes/Fixes/Resolves)', () => { + expect(parseRelatedIssueNumbers('Closes #10\nFixes #11\nResolves #12\nRelated #296')).toEqual([ + 296, + ]) + }) + + it('returns empty for missing/blank bodies', () => { + expect(parseRelatedIssueNumbers(undefined)).toEqual([]) + expect(parseRelatedIssueNumbers('')).toEqual([]) + expect(parseRelatedIssueNumbers('no refs here')).toEqual([]) + }) +})