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 · 2026-08-03 00:20:48 +00:00 · b7f4e16c0f
commit b7f4e16c0f
parent 1266b47b0e
10 changed files with 252 additions and 10 deletions
--- 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.
--- 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 <N[,N…]>
 ```

-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.

--- a/.github/workflows/plan-issue-ready-on-main-merge.yml
+++ 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"
--- 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`)                                                                              |

--- 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/<slug>/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.
--- a/docs/plans/plan-issue-promote-dual-impl.md
+++ 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
--- 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

--- a/scripts/agent-promote-related-on-merge.mjs
+++ 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 <N>')
+}
+
+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`)
+}
--- 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).
--- 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([])
+  })
+})