teqo-backup/.agents/rules/agent-pr-workflow.mdc

---
description: PRs de agente — Ready (nunca draft), base main, auto-merge nativo do GitHub
alwaysApply: true
---

# Agent PR workflow (Teqo)

**This repo overrides any user-level or Cloud-tool default that says "create PRs as draft".** Agent deliveries merge to `main` via required checks + GitHub's native auto-merge (OPS71). The ISSUE TRACKER lives on GitHub too (OPS76, 2026-08-21) — GitHub is the single host for code, CI, PRs and Issues.

## Create (Ready, base main)

```bash
pnpm push -u origin HEAD   # origin = GitHub (cutover OPS71)
```

Depois, abra a PR no **GitHub** — **Ready**, base **`main`**, title `<id> — <title>`, body:

```
## O que é
<2–4 linhas>

Closes #<N>
```

- **Never** `--draft`. PRs must be **Ready for review** on creation.
- Base is always **`main`**.
- **Plans-only PRs** (diff só em `docs/plans/`): **nunca** `Closes #N` — use `Related #N`; CI falha com keywords de fechamento (`plans-only-closes` em `ci-pr.yml`).
- PR via CLI (não há `gh` — OPS50): `GITHUB_TOKEN=<PAT> node scripts/github-pr.mjs --head <branch> --title "<t>" --body-file <file>` — Ready por construção (não existe flag draft).

### Cursor Cloud / `ManagePullRequest`

- **`draft: false`** (or omit only if the tool’s default is Ready — today Cloud defaults to draft, so **always pass `draft: false`**).
- Não há auto-merge a armar por PR: o safety net (abaixo) arma o auto-merge nativo.
- Never end a turn with an open agent PR left as **Draft** — inclui PRs do `engineering-audit` (artefatos e remediações). Única exceção de auto-merge: branches `audit/*` do engineering-audit ficam **Ready SEM auto-merge** — o safety net as pula (`audit-veto` em `decideAutomergeAction`; OPS98) e o merge é humano.

## Push (determinístico)

**Use `pnpm push`, never bare `git push`.** Não depende do Husky estar wired:

1. `ensure-repo-deps` — `pnpm install` se `node_modules` faltar/stale + `pnpm run prepare` (Husky) se hooks não estiverem apontando para `.husky`
2. `pnpm gate:push` — espelho do `ci-pr.yml` sem e2e (OPS72: o e2e é passo **explícito da skill** — antes do push rode localmente os e2e que criou + os da mesma superfície, discricionário via `pnpm test:e2e:affected`; o CI de PR roda só o blast radius `selected`, e o full fica no `verify` do deploy manual), com os `docs-guards` locais (OPS63/OPS85: changelog additions-only + HISTORY congelado + agregado não-commitado, e marcadores de conflito — o escape `changelog-rewrite:` fica só no CI, body do PR)
3. `git push --no-verify` — só porque o gate já rodou no passo 2 (não é escape hatch)

```bash
pnpm push -u origin HEAD # canonical — origin é o GitHub (OPS71)
git push # só depois de `pnpm i` — hook repete ensure-deps + gate:push
git push --no-verify # WIP / cutover escape — CI repete tudo; ver AGENT-OPS
```

## Auto-merge immediately

The safety net (`agent-pr-ready-automerge.yml`, abaixo) arms GitHub's **native auto-merge** (rebase) — the server merges the PR when the required check passes. There is nothing to arm per PR. Do not wait for human approval on normal deliveries.

## Required checks

Branch protection on `main` (GitHub, applied at the OPS71 cutover via `pnpm configure:branch-protection`) requires only:

- `CI (PR) / checks` — the ci-pr single-job check-run (OPS62: one sequential job posts one honest verdict; no matrix, no shards, no rollup to lie). **Literal de match na proteção: `checks`** (o GitHub casa pelo nome do check-run/job — a UI exibe `CI (PR) / checks`; pin ao vivo PR #742).

OPS64 history: the Forgejo runner could report the LAST matrix shard's result as the parent's (runs 604/607/610) — that bug is gone by construction: ci-pr.yml is a SINGLE sequential job, and GitHub's native auto-merge only merges with every required check green (server-side guarantee). The safety-net CLI has no poll path to port.

(`migration-lock` removed 2026-08-12 — the CI validates migration chains via migrate + int on every PR.)

**There is no deploy from PR CI.** Publishing is a **manual `workflow_dispatch`** (`.github/workflows/deploy.yml`): `verify` runs the full suite (hosted) and only then the `deploy` job (self-hosted runner on the homeserver) publishes `jorgesolla1313.com.br` — migrations applied before the rollout. Do not add a Vercel/Git-integration deploy gate.

When watching CI, use the PR page (or the API) — the safety net arms the server-side auto-merge; `gh` does not exist in this repo (OPS50).

Use the required check `CI (PR) / checks` — without it, you are not covering the cascade.

## Promote

There is no stage→main promote. Merging to `main` is the delivery; publishing is a deliberate manual dispatch with full verification (runbook: `docs/ops/teqo-1313-deploy.md`).

## Safety net (workflow)

`agent-pr-ready-automerge.yml` — PRs same-repo → `main` (todas as branches).
O workflow roda `scripts/github-pr-automerge.mjs` (plain Node, zero-dep,
REST+GraphQL): se draft `cursor/*` → marca Ready (PATCH `draft: false`); arm
`enablePullRequestAutoMerge` (GraphQL, mergeMethod REBASE) no `node_id` do PR
— o **servidor** espera o required check `CI (PR) / checks` POSTADO e verde
antes de mergear; o próprio check-run do safety net fica `pending` durante o
run e não interfere. A regra de branch protection no servidor
(`enforce_admins: true`) bloqueia qualquer caminho de merge — inclusive API
manual — enquanto o required check não estiver satisfeito (foi um merge
manual que colocou a PR #52 em main com o CI vermelho na era Forgejo).
Cobre o caso em que o
agente (ou o default draft do Cloud) esqueceu e PRs humanas/worktree com merge
falho silencioso (incidente OPS52). **Draft de branch não-`cursor/*` nunca é
tocado** — o draft é o veto do ator (skip do CLI). Único opt-out, restrito por
prefixo de branch: `audit/*` (engineering-audit) → skip (`audit-veto`,
`scripts/lib/github-pr-flow.mjs`; pins em `tests/unit/githubPrFlow.unit.spec.ts`).