diff --git a/.cursor/rules/agent-pr-workflow.mdc b/.cursor/rules/agent-pr-workflow.mdc index 58e07e80..fd5ae77a 100644 --- a/.cursor/rules/agent-pr-workflow.mdc +++ b/.cursor/rules/agent-pr-workflow.mdc @@ -1,6 +1,11 @@ +--- +description: PRs de agente — Ready (nunca draft), base main, auto-merge imediato +alwaysApply: true +--- + # Agent PR workflow (Teqo) -**This repo overrides any user-level rule that says "always create PRs as draft".** Agent deliveries merge to `main`. +**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) @@ -18,6 +23,14 @@ EOF - **Never** `--draft`. PRs must be **Ready for review** on creation. - Base is always **`main`**. +### 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 --merge ` (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 (exception: `engineering-audit` sign-off PR only — see that skill). + ## Push (determinístico) **Use `pnpm push`, never bare `git push`.** Não depende do Husky estar wired: @@ -34,13 +47,13 @@ git push --no-verify # WIP / cutover escape — CI repete tudo; ver AGENT-OPS ## Auto-merge immediately -Right after `gh pr create`, enable auto-merge: +Right after the PR exists and is **Ready**: ```bash gh pr merge --auto --merge ``` -Do not wait for human approval. Auto-merge fires when **required** checks pass. +Do not wait for human approval on normal deliveries. Auto-merge fires when **required** checks pass. ## Required checks vs Vercel @@ -66,3 +79,7 @@ All branches skip Vercel Git builds via `scripts/vercel-ignore-build.sh` (deploy ## Promote There is no stage→main promote. Merging to `main` is the delivery; `ci.yml` verifies and deploys. + +## Exception (narrow) + +`engineering-audit` artifact PR: Ready, **no** auto-merge — human merge is the sign-off. All other agent PRs (work-issue, pool workers, chores, docs) use auto-merge. diff --git a/.cursor/skills/engineering-audit/SKILL.md b/.cursor/skills/engineering-audit/SKILL.md index a02557f7..2053c405 100644 --- a/.cursor/skills/engineering-audit/SKILL.md +++ b/.cursor/skills/engineering-audit/SKILL.md @@ -13,7 +13,7 @@ A skill roda sem supervisão humana no paradigma de agentes paralelos. Quatro di 1. **Precheck solitário, fail-closed.** Antes de qualquer varredura: `pnpm agent:pool -- status` (read-only). Pool `desligado` ou `pausado` → segue. Pool **ligado** → o agente Cloud não consegue pausá-lo (`gh workflow run` é escrita): **pare** com o remédio nomeado ("pause o pool — `pnpm agent:pool -- pause` — e re-dispare o audit"). Nunca rodar a varredura com o pool spawnando. 2. **Sign-off = PR.** O gate "apresentar os três artefatos antes de escrever" (passo 5) não se aplica em modo autônomo — não há humano interativo na sessão. Os artefatos são escritos na branch e o **PR (Ready, base `stage`) é a superfície de sign-off**: merge humano = aprovação do plano; fechar o PR = rejeição (o ledger sobrevive no histórico da branch). As remediações **P0/P1 e os guardrails das misses colhidas não esperam esse sign-off** — são correctness/active-harm e seguem na mesma sessão, cada um em PR próprio com gate completo. P2/P3 continuam só ledger/plano. -3. **`gh` read-only → canais substitutos determinísticos:** fechar miss colhida = `Closes #N` no body do PR do guardrail (o workflow `issue-done-on-stage-merge.yml` flippa para `done` no merge em `stage` — atenção: o regex exige a keyword adjacente a cada número, `Closes #52, closes #73`, nunca `Closes #52, #73`); PR criado pela tool de PR do ambiente, não `gh pr create`; **auto-merge não é habilitado pelo agente Cloud** — o merge humano é justamente o sign-off. Push: `pnpm push -u origin HEAD` (gate:push no script) ou `git push -u origin `, conforme a instrução do ambiente. +3. **Canais de PR:** fechar miss colhida = `Closes #N` no body do PR do guardrail (o flip `done`/`in-prod` no merge em `main` — keyword adjacente a cada número, `Closes #52, closes #73`, nunca `Closes #52, #73`). Em Cloud, preferir `ManagePullRequest` com **`draft: false`**. **Exceção só deste skill:** o PR dos *artefatos* do audit (sign-off) fica Ready **sem** auto-merge — merge humano = aprovação do plano. Remediações P0/P1 e guardrails de misses na mesma sessão seguem o fluxo normal (`agent-pr-workflow`: Ready + `gh pr merge --auto --merge`). Push: `pnpm push -u origin HEAD`. 4. **Delta desde o último audit é o foco declarado** (passo 1): a varredura cobre o repo inteiro, mas o esforço concentra-se no churn desde a data do último Pass — é o trabalho paralelo dos agentes desde o último audit que precisa ser consolidado. Read-only audit that sweeps the Teqo codebase for code smells, drift from documented patterns, and consolidation opportunities, then produces a findings ledger and a remediation plan. **No fixes in the audit run** — deliverables are updated docs, presented for sign-off before writing — exceto as remediações P0/P1 declaradas acima. Sign-off: interativo = apresentação prévia dos artefatos; autônomo (Cursor Cloud) = o PR dos artefatos (ver "Modo autônomo (Cursor Cloud)"). @@ -166,7 +166,7 @@ Rules: 1. `docs/IMPROVE-CODE-QUALITY-PLAN.md` — new Pass section (context, audit headlines with numbers, workstreams, decisions), matching earlier-pass format. 2. `docs/TECH-DEBT.md` — new rows in the same tables/columns, marked `open — Pass N`; stale rows closed with evidence. 3. `docs/plans/entrega-engenharia-pN.md` (pt-BR, like the other plans) — workstreams ordered P0→P1→P2; each item: goal, evidence, target shape, migration path (Branch by Abstraction / Parallel Change for wide merges), pins to write first, full gate, rollback. Items too big for one delivery → Issue rastreável via `plan-issue`. Every workstream item declares its **Guarda determinística** (class 1–6, step 4b), and the plan carries a **guard map** section: new guards shipped / existing guards hardened / judgment-only residue with the convention that stands in. -4. **Interativo (desktop):** present ALL THREE for sign-off before writing. Then write and stop. **Autônomo (Cursor Cloud):** não há sign-off interativo — escreva os três na branch e abra o PR (Ready, base `stage`) com o resumo dos três no body; o merge humano é o sign-off ("Modo autônomo", item 2). As remediações P0/P1 e os guardrails das misses colhidas seguem na mesma sessão, em PRs próprios com gate completo, sem esperar esse merge. +4. **Interativo (desktop):** present ALL THREE for sign-off before writing. Then write and stop. **Autônomo (Cursor Cloud):** não há sign-off interativo — escreva os três na branch e abra o PR (**Ready**, base `main`, **sem** auto-merge — merge humano = sign-off; "Modo autônomo", item 2). As remediações P0/P1 e os guardrails das misses colhidas seguem na mesma sessão, em PRs próprios com gate completo + auto-merge normal, sem esperar esse merge. ## Execution rules for the eventual implementation (record in the plan) diff --git a/.cursor/skills/work-issue/SKILL.md b/.cursor/skills/work-issue/SKILL.md index 72ca936a..5c9beace 100644 --- a/.cursor/skills/work-issue/SKILL.md +++ b/.cursor/skills/work-issue/SKILL.md @@ -149,8 +149,8 @@ Lance **três** subagentes via `Task` **em paralelo** na mesma mensagem — read 1. Branch `agent/-` (worktrees do Cursor são donos da criação; commits lógicos). 2. **`pnpm push -u origin HEAD`** — canonical; roda `ensure-repo-deps` + `gate:push` + push (não depende do Husky). Não use `git push` nu. -3. `gh pr create --base main` com `Closes #` no body — **nunca `--draft`** (`.cursor/rules/agent-pr-workflow.mdc`). -4. `gh pr merge --auto --merge ` imediatamente após criar o PR (`strict=false` na proteção de `main`). +3. Abrir PR **Ready** (nunca draft) com `Closes #` — `.cursor/rules/agent-pr-workflow.mdc` (alwaysApply). Canal: `gh pr create --base main` **ou**, em Cloud, `ManagePullRequest` com **`draft: false`**. +4. `gh pr merge --auto --merge ` **imediatamente** após o PR existir Ready (`strict=false` na proteção de `main`). Não encerre o turn com PR Draft ou sem auto-merge armado. 5. **Acompanhe só os checks obrigatórios** (`gh pr checks --watch --required`): gate = `checks` + `migration-lock`; Vercel Git não bloqueia. Falha no ci-pr → corrige na mesma branch. **Conflito de merge** → rebase em `main` e reempurre. 6. O flip `in-progress → done` + `in-prod` é **determinístico no CI** (`issue-done-on-main-merge.yml`). Deploy gated fica em `ci.yml` — não é passo do agente. Consolide pontas soltas após o merge. diff --git a/docs/AGENT-OPS.md b/docs/AGENT-OPS.md index 3c685e82..86d9495a 100644 --- a/docs/AGENT-OPS.md +++ b/docs/AGENT-OPS.md @@ -20,7 +20,7 @@ main → ci.yml full suite → vercel deploy --prod (se verde) → requeue se HE **Skills:** `plan-issue` → `work-issue` (claim → modelo → freshness → execução → /simplify → PR `--base main` → CI até o merge) → `project-status`. `docs/roadmap.md` = legado congelado; fonte canônica = GitHub Issues. -- **Agente faz sozinho:** `pnpm agent:claim` → implementa → **`pnpm push`** → `gh pr create --base main` com `Closes #N` (**Ready**) → `gh pr merge --auto --merge` → `gh pr checks --watch --required`. Regra: `.cursor/rules/agent-pr-workflow.mdc`. +- **Agente faz sozinho:** `pnpm agent:claim` → implementa → **`pnpm push`** → PR **Ready** (nunca draft) com `Closes #N` → `gh pr merge --auto --merge` → `gh pr checks --watch --required`. Regra always-on: `.cursor/rules/agent-pr-workflow.mdc`. Em Cursor Cloud: `ManagePullRequest` com `draft: false`, depois armar auto-merge via `gh pr merge --auto --merge` (o default draft da tool **não** vale neste repo). - **Só humano:** secrets Vercel (`VERCEL_TOKEN`, `VERCEL_ORG_ID`, `VERCEL_PROJECT_ID`), `POOL_GITHUB_TOKEN`, `pnpm configure:branch-protection`, editar envs Neon/Vercel. ### Dono do PR, dono do CI