All checks were successful
CI (PR) / checks (pull_request) Successful in 3m5s
PR Ready + auto-merge / ready-automerge (pull_request) Successful in 4m40s
Promote plan-issue Related on main merge / plan-issue-ready (pull_request) Has been skipped
Main merge flips claimed issues to done + in-prod / issue-done (pull_request) Successful in 13s
O sintoma primário da Issue (deadlock do waitForChecks no próprio pending) já tinha sido entregue pelo OPS61. O secundário — o rollup `checks` reportava SUCCESS com um shard de e2e vermelho porque o Forgejo 9.0.3 reporta o resultado do ÚLTIMO shard como o parent de matrix no `needs` (runs 604/607/610; o `needs.<job>.results` do GitHub não existe neste runner) — foi eliminado estruturalmente pelo OPS62 (mergeado durante a execução): ci-pr.yml e ci.yml viraram jobs únicos sequenciais, sem matrix/shard, e o status do job `checks` já é o veredito honesto da cascata. O que este item entrega: (a) teste-pino no waitForChecks (cenário run 607: rollup verde + shard vermelho → o CLI LANÇA "Checks falharam" — nunca confia no rollup sozinho; invariante de defesa válido e que pegaria qualquer matrix que volte); (b) docs honestas (agent-pr-workflow.mdc, AGENT-OPS.md) com a narrativa do parent de matrix e da eliminação estrutural pelo OPS62. O script ci-rollup-check.mjs e os edits de workflow planejados foram descartados no gate (redundantes pós-OPS62). Unit 2392 verdes; gates locais ok.
104 lines
5.4 KiB
Text
104 lines
5.4 KiB
Text
---
|
||
description: PRs de agente — Ready (nunca draft), base main, auto-merge imediato
|
||
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 + auto-merge.
|
||
|
||
## Create (Ready, base main)
|
||
|
||
```bash
|
||
pnpm push -u origin HEAD
|
||
```
|
||
|
||
Depois, abra a PR via API/MCP do opencode (humano) ou `ManagePullRequest` (Cursor Cloud) — **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`).
|
||
|
||
### 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) espera o rollup `checks` e mergea sozinho.
|
||
- Never end a turn with an open agent PR left as **Draft** — inclui PRs do `engineering-audit` (artefatos e remediações).
|
||
|
||
## 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 (e2e roda uma vez, no CI, após o push; local opcional: `pnpm test:e2e:affected`), com os `docs-guards` locais (OPS63: changelog append-only, agregado sync 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
|
||
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) merges the PR when the required checks pass — there is nothing to arm per PR. Do not wait for human approval on normal deliveries.
|
||
|
||
## Required checks
|
||
|
||
Branch protection on `main` (applied 2026-08-18, OPS61) requires only:
|
||
|
||
- `CI (PR) / checks` — the ci-pr cascade rollup (the only context that covers
|
||
every ci-pr job; on the server the rule matches it as a glob,
|
||
`CI (PR) / checks*`)
|
||
|
||
OPS64: the rollup is structurally honest since OPS62 — ci-pr.yml is a SINGLE
|
||
sequential job (`checks`), so its own status IS the cascade verdict (no
|
||
matrix, no shards, no parent aggregation to lie). The historical bug (Forgejo
|
||
9.0.3 reporting the LAST matrix shard's result as the parent's in `needs`,
|
||
posting `checks` SUCCESS with an e2e shard red — runs 604/607/610) is gone by
|
||
construction; the `needs.<job>.results` array of GitHub does not exist in this
|
||
runner, so any future matrix must NOT aggregate via `needs`. The safety-net
|
||
CLI pins the defense: it never trusts the rollup alone (scans individual
|
||
statuses; run-607 scenario unit-tested in `forgejoApi.unit.spec.ts`).
|
||
|
||
(`migration-lock` removed 2026-08-12 — the CI validates migration chains via migrate + int on every PR/main.)
|
||
|
||
**There is no deploy from PR CI.** The `ci.yml` verifier on `main` runs the full suite in its fixed 30-minute window and, on a production change, the `deploy` job publishes to the homeserver (`jorgesolla1313.com.br`, self-hosted) — 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 is what waits on checks; `gh` does not exist in this repo (OPS50).
|
||
|
||
Use the rollup context `CI (PR) / checks` — without it, you are not covering the cascade.
|
||
|
||
## Promote
|
||
|
||
There is no stage→main promote. Merging to `main` is the delivery; `ci.yml` verifies the full suite and, on a production change, deploys to the homeserver (OPS53/OPS65; 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/forgejo-pr-automerge.mjs` (plain Node, zero-dep): se
|
||
draft `cursor/*` → marca Ready; espera os checks e mergea por rebase (o
|
||
equivalente Forgejo do auto-merge — sem `gh`). O wait exige o rollup
|
||
`CI (PR) / checks` POSTADO e verde (OPS61) — o único contexto que só existe
|
||
quando a cascata inteira do ci-pr assentou (jobs ainda não agendados não
|
||
postam status; o próprio status do job do safety net é `pending` durante o run
|
||
e **nunca** entra no veredito). O CLI nunca confia no rollup sozinho: varre
|
||
todos os statuses individuais e falha em qualquer `failure`/`error` — um shard
|
||
de e2e vermelho bloqueia o merge mesmo com o rollup verde (OPS64; run 607).
|
||
A regra de branch protection no servidor
|
||
bloqueia o merge POST (405) enquanto o contexto exigido não estiver satisfeito
|
||
— inclusive merges manuais via API: foi um merge manual que colocou a PR #52
|
||
em main com o CI vermelho (o CLI nunca mergeou sozinho antes do OPS61; todo
|
||
merge Forgejo era manual).
|
||
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). Não há opt-out por skill
|
||
(audit incluído).
|