teqo/.agents/rules/agent-pr-workflow.mdc
Francisco Solla 10c1eeaeda
Some checks failed
CI (PR) / scope (pull_request) Successful in 33s
CI (PR) / lint (pull_request) Successful in 44s
CI (PR) / docs-guards (pull_request) Successful in 7s
CI (PR) / plans-only-closes (pull_request) Successful in 7s
CI (PR) / format (pull_request) Successful in 55s
CI (PR) / typecheck (pull_request) Successful in 31s
CI (PR) / knip (pull_request) Successful in 36s
CI (PR) / cycles (pull_request) Successful in 39s
CI (PR) / unit (pull_request) Successful in 59s
CI (PR) / int (pull_request) Successful in 2m23s
CI (PR) / build (pull_request) Has been skipped
CI (PR) / e2e (1) (pull_request) Has been skipped
CI (PR) / e2e (2) (pull_request) Has been skipped
CI (PR) / checks (pull_request) Failing after 1s
PR Ready + auto-merge / ready-automerge (pull_request) Failing after 50m5s
fix(OPS64): rollup checks honesto por statuses do commit — Forgejo não agrega shards no parent de matrix
O sintoma primário da Issue (deadlock do waitForChecks no próprio pending)
já tinha sido entregue pelo OPS61; o OPS64 fecha o secundário, que estava
vivo e medido: o Forgejo 9.0.3 reporta o resultado do ÚLTIMO shard como o
resultado do parent de matrix no contexto `needs` (runs 604/607/610: e2e (1)
vermelho + e2e (2) verde → checks verde), e o `needs.<job>.results` do GitHub
não existe neste runner. Com isso o gate do servidor (branch protection) e o
deploy do ci.yml podiam passar com um shard vermelho.

O rollup `checks` (ci-pr.yml e ci.yml) agora lê os statuses do commit via API
(scripts/ci-rollup-check.mjs + lib pura, zero-dep, plain Node) — a mesma
fonte que o waitForChecks confia — filtrando pelo prefixo do workflow,
excluindo o próprio contexto e os downstreams legítimos (deploy, pending
enquanto o rollup roda), falhando fechado em failure/error/pending/vazio.
Fork guard + FORGEJO_API_TOKEN no job checks do ci-pr.yml (sem o guard, fork
rodaria o script do head com o PAT — RCE classe OPS61); PRs de fork ficam
não-mergeáveis no servidor (hardening). ci.yml usa --allow-empty em
workflow_dispatch (evento não posta commit status).

Testes: 12 specs do veredito (run 607/716 pinados, próprio pending ignorado,
safety net ignorado, deploy ignorado, vazio fail-closed) + waitForChecks
lança com rollup verde + shard vermelho. Unit 2360 verdes; gates locais ok.
2026-08-18 20:02:34 -03:00

114 lines
5.4 KiB
Text
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

---
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
gh pr create --base main --title "<id> — <title>" --body "$(cat <<'EOF'
## O que é
<2–4 linhas>
Closes #<N>
EOF
)"
```
- **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`
When the environment says to use `ManagePullRequest` instead of `gh pr create`:
- **`draft: false`** (or omit only if the tool’s default is Ready — today Cloud defaults to draft, so **always pass `draft: false`**).
- Right after create (or on `update_pr` if you opened draft by mistake): mark Ready if still draft, then enable auto-merge with `gh pr merge --auto --rebase <url|number>` (write allowed for this step — same as `agent-pr-workflow`; do not leave the PR waiting on a human).
- Never end a turn with an open agent PR left as **Draft** or without **auto-merge** armed — 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
Right after the PR exists and is **Ready**:
```bash
gh pr merge --auto --rebase
```
Do not wait for human approval on normal deliveries. Auto-merge fires when **required** checks pass.
## 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 verdict reads the **per-job commit statuses via the API**
(`scripts/ci-rollup-check.mjs`), not the `needs` context — Forgejo 9.0.3
reports the matrix parent's result as the LAST shard's result, so an
`all(needs…)` jq could post `checks` SUCCESS with an e2e shard red (runs
604/607/610; the `needs.<job>.results` array of GitHub does not exist in this
runner). Same source the safety-net CLI trusts; shards post their own statuses.
PRs de fork não postam o contexto `checks` (fork guard no job — o job roda o
script do head com o PAT) e ficam não-mergeáveis pelo servidor (hardening:
"a merged fork PR would deploy"; o auto-merge já os excluía).
(`migration-lock` removed 2026-08-12 — the CI validates migration chains via migrate + int on every PR/main.)
**There is no deploy from CI.** The `ci.yml` verifier on `main` runs the full suite and stops (production is self-hosted on the homeserver — `jorgesolla1313.com.br` — deployed via an ops runbook outside this repo). Do not add a Vercel/Git-integration deploy gate.
When watching CI:
```bash
gh pr checks <PR> --watch --required
```
Use `--required` — without it, `--watch` also waits for Vercel.
## Promote
There is no stage→main promote. Merging to `main` is the delivery; `ci.yml` verifies the full suite and production deploys from the homeserver runbook.
## 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 `gh pr merge --auto --rebase`). 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).