agentleFS
michelbr84michelbr84/GarraRUST/.claude/skills/steward/SKILL.md

steward

Skill19 starsChanged 25 days agoMITView on GitHub

Guia específica do GarraRUST para dirigir um PR até o verde — quais falhas de CI são ambientais, quais são suas, e o que validar antes de empurrar. Lida ao reagir a eventos de CI ou de review num PR.

19 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use release.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • MicrosoftSkill

    release

    Use ONLY when the user explicitly asks to cut/publish a Huabu desktop release or tag a version. Performs an outward action — bumps the version in apps/desktop/package.json, commits + annotated-tags vX.Y.Z, and pushes the branch + tag. That tag push auto-builds the macOS/Windows installers and publishes a GitHub Release. Provides `status`, `bump`, `tag-push`, and a one-command `run` (bump → tag-push).

    Also in 3 projects that use this

The file

Files
SKILL.md

Steward — dirigindo um PR do GarraRUST até o verde

Esta skill é lida no momento em que um PR seu fica vermelho ou recebe review. Ela não repete o CLAUDE.md (convenções de código, regras absolutas, estrutura de crates) — vá lá para isso. Aqui está só o que morde nesse momento específico, e que já custou ciclos de CI reais.

Ela não autoriza aprovar nem mergear PR, e não sobrepõe nenhuma regra "nunca" da política de PR do harness (pular/desabilitar teste, reescrever histórico de branch alheia, commit vazio para chacoalhar CI).


1. Antes de qualquer push

O Format Check é bloqueante e é o erro mais barato e mais frequente:

cargo fmt --all && cargo fmt --all -- --check

Rode isso sempre, mesmo em mudança que "só mexe em comentário". cargo check, clippy e test passando não implicam fmt limpo — o rustfmt reflui params!, assert!, match longos e reordena blocos use, e nada disso aparece nas outras ferramentas.

Caso real: PR #861 foi para o CI com 21 de 22 checks verdes e o único vermelho era fmt — 19 blocos em 8 arquivos, todos cosméticos. Um ciclo inteiro de CI (~25 min) perdido.

Depois, o mais próximo possível do que o CI roda:

cargo clippy --workspace --exclude garraia-desktop --all-targets -- -D warnings
cargo test  --workspace --exclude garraia-desktop

garraia-desktop é excluído em todos os jobs (clippy, build, test, msrv) — faltam libs GTK e o sidecar Windows nos runners. Não tente "consertar" isso.


2. Falhas que NÃO são suas

Antes de investigar como defeito, descarte estas. Todas aparecem como falha legítima e não são.

migration_smoke — "failed to initialize a docker client"

Error: failed to initialize a docker client: Socket not found: /var/run/docker.sock

Os testes de garraia-workspace (e os de integração de garraia-auth / garraia-gateway) usam testcontainers. O container de dev não tem Docker. Nos runners Linux do GitHub tem, e lá passam — inclusive aplicando todas as migrations via sqlx::migrate! em Postgres real. Se falhar só localmente com essa mensagem, é ambiente. Diga isso explicitamente em vez de alegar que validou.

utoipa-swagger-ui — Swagger UI vem vendorizado (#1228)

O gateway compila o utoipa-swagger-ui com a feature vendored: o build.rs lê o zip embutido na crate utoipa-swagger-ui-vendored e não baixa nada, então build offline funciona sem preparo. O antigo contorno SWAGGER_UI_DOWNLOAD_URL=file://... (zip gerado de um clone da tag) é ignorado com vendored e não resolve mais nada — não perca tempo com ele.

Se um build voltar a tentar baixar o Swagger UI, alguém tirou a feature vendored do crates/garraia-gateway/Cargo.toml; o teste tests/swagger_ui_vendored.rs do gateway falha nesse caso. A action .github/actions/swagger-ui-cache é vestigial (fica uma release, download best-effort) — falha nela não é causa de build quebrado.

"No space left on device" disfarçado de erro de compilação

target/ chega a ~26 GB e o disco da sessão é uma cota fixa — df engana (mostra "Avail" baixo com "Used" baixo). Sintoma típico: vários could not compile X sem erro de tipo algum, e no meio um error 28. Cure com target/debug/incremental primeiro (metade do peso), cargo clean se necessário. Commite e empurre antes de limpar, para que um estouro não leve o trabalho junto.

Quality Ratchet reclamando de arquivos grandes

O baseline está congelado em 2026-05-05 e a main andou muito desde então. As regressões de max_file_lines / files_over_* quase sempre são deriva do baseline, não suas. Confirme antes de agir:

git diff --name-only origin/main..HEAD          # o arquivo apontado está aqui?
git show origin/main:<arquivo> | wc -l          # já tinha esse tamanho na main?

O modo é report-only (exit 0) e o check fica verde. Nunca edite .quality/baseline.json à mão — é fraude; use freeze-baseline.py.

CodeQL agregado em neutral

O check-run agregado "CodeQL" às vezes fecha como neutral enquanto os três Analyze (rust|actions|javascript-typescript) fecham success. neutral não é falha e não bloqueia. Olhe os três individuais.

4 testes de sandbox quando o $HOME da sessão mora em /tmp

wrap: Agent("sandbox fail-closed: agent.sandbox.mount_workdir = true e o
diretorio de trabalho e um ancestral do $HOME do processo; ...")

Falham juntos, sempre estes quatro de garraia-agents --lib:

  • sandbox::shell_injection_regression::wrap_command_entrega_o_comando_como_uma_palavra_literal
  • sandbox::tests::docker_leva_cap_drop_pids_limit_e_user_do_processo
  • sandbox::tests::linha_do_bash_leva_nome_do_container
  • sandbox::tests::podman_leva_userns_keep_id_e_nao_user

A guarda está certa e o código não tem defeito — é o fixture que depende do $HOME da máquina. Os quatro passam "/tmp" como working_dir, e motivo_de_mount_perigoso recusa qualquer diretório que seja ancestral do $HOME do processo (sandbox.rs:189). Em runner do GitHub e em dev normal o $HOME é /home/<user>, então /tmp não é ancestral de nada e os testes passam. Em sessão cujo $HOME é /tmp/<algo> — o caso de container de agente — /tmp é ancestral do $HOME, e o fail-closed do #1272 dispara como projetado.

Confirme em dois comandos antes de investigar como defeito:

echo "$HOME"                                    # está sob /tmp?
cargo test -p garraia-agents --lib sandbox::    # só estes 4 vermelhos?

Se o $HOME está sob /tmp, é ambiente. Não afrouxe a guarda nem marque os testes como ignore para ficar verde: isso apagaria a regressão de segurança do #1272. Deixar os quatro herméticos (injetar o home por linha, como fonte_do_mount_com já permite) é melhoria legítima de teste, mas é mudança em código de sandbox — território R4, com security-auditor no ciclo.

STDERR: na saída de git quando o container embrulha o git

a chamada benigna revelou o git quebrado no argv do diff: ...
STDERR: Paperclip: GitHub capability_missing; continuing without managed credentials.

Atinge runtime::tests::repo_search_git_e_recall::git_diff_registrada_nao_reabre_ext_diff_pelo_file_path.

O teste é a regressão do #1269 e afirma que uma chamada benigna de diff não produz bloco STDERR: — é assim que ele evita ficar verde por acidente com o git quebrado. O argv continua correto; o que entra na saída da tool é ruído do host.

A pegadinha: reproduzir no seu shell não funciona. Quando o git do PATH é um wrapper de credencial (sessão de agente resolve git para um launcher antes de /usr/bin/git), ele só escreve o aviso quando não consegue falar com o broker dele. Seu shell interativo tem o token, então git diff fica silencioso; o processo de teste gera o filho com o ambiente higienizado, o token não vai junto, e aí o aviso aparece. Mesmo comando, dois resultados.

Confirme assim — os dois comandos, não só o primeiro:

command -v git                  # /usr/bin/git, ou um launcher antes dele?
env -u PAPERCLIP_GITHUB_BROKER_TOKEN git diff 2>&1 >/dev/null

Se o segundo imprime Paperclip: GitHub capability_missing e o primeiro não aponta para /usr/bin/git, é ambiente. Não relaxe a asserção para "não contém STDERR exceto ...": ela perde exatamente o poder de detecção que justifica o teste.

Leg macos-latest do orphan-processes cancelado sem passos nem log (#1749)

Orphan-process guards (macos-latest)   cancelled   steps: []   runner_name: ""
GET /actions/jobs/<job_id>/logs  ->  BlobNotFound

O job Orphan-process guards roda em matriz (ubuntu, windows, macos) e não é check obrigatório do ruleset. A assinatura: o leg macos-latest fecha cancelled sem executar nenhum passo (steps: [], runner_name vazio, log inexistente), os dois legs irmãos passam, e o mesmo leg está verde nas runs recentes de main. É runner macOS que nunca foi atribuído (fila, ou teto de minutos macOS — que custam 10x) e foi cancelado pela plataforma. O teste nunca começou, então não há o que depurar no código. Na PR #1747 o leg ficou 15 min na fila e caiu assim enquanto os sete obrigatórios passavam; 27 min depois do cancelamento, na main (ea8a68af), o mesmo leg passou em 1,5 min.

Antes de concluir isso, descarte a causa comum: um push novo na mesma branch. A concurrency do workflow tem cancel-in-progress em pull_request, e o push cancela só o que ainda está na fila ou rodando — os irmãos que já terminaram ficam success, e o leg atrasado aparece exatamente assim, cancelled com zero passos. Nesse caso existe uma run mais nova para a branch, criada no instante do cancelamento, e não há nada a re-executar.

Confirme em três comandos:

gh run list --workflow ci.yml --branch <branch> --limit 5      # há run mais nova criada na hora do cancel?
gh api "repos/michelbr84/GarraRUST/actions/runs/<run_id>/jobs?per_page=100" \
  --jq '.jobs[] | select(.name|startswith("Orphan-process")) | "\(.id) \(.name): \(.conclusion) steps=\(.steps|length) runner=\(.runner_name)"'
gh api repos/michelbr84/GarraRUST/actions/jobs/<job_id>/logs    # BlobNotFound = nenhum passo rodou

O primeiro campo da segunda saída é o <job_id> dos comandos seguintes (o per_page=100 importa: a run já tem 28 jobs e o padrão da API é 30). Sem run mais nova, irmãos success e steps=0 no leg macOS: é ambiente. O remédio é re-executar só esse leg, depois que a run inteira terminar — enquanto ela roda, a API devolve 403 The workflow run containing this job is already running:

gh run rerun --job <job_id>      # só o leg cancelado

Como o job não é obrigatório, o merge pelo ruleset não depende dele; a run vermelha com os sete obrigatórios verdes é ruído, não bloqueio — diga isso no PR em vez de afirmar que "o CI passou". O timeout-minutes do job (45, #1749) só começa a contar depois que o leg recebe runner: um leg que trava em execução falha com "exceeded the maximum execution time", e essa falha é sua para investigar; um leg que nunca recebeu runner continua terminando cancelled sem passos. Não use continue-on-error para esconder o leg (higiene #1094) e não tire o leg macOS da matriz por conta própria: manter ou mover para o workflow agendado é decisão do dono, registrada na #1749.

Unit tests (windows-latest|macos-latest) vermelho (#1697)

Este job não é check obrigatório: ele executa os testes unitários (--lib) fora do Linux, coisa que o Test (windows|macos) não faz (só compila). No Windows ele também roda os testes do binário garra (--bin garra: a CLI não tem alvo lib) e o clippy -D warnings de garraia-agents --features mcp, garraia e garraia-gateway (#1762). Vermelho ali não trava o merge, mas é seu: quase sempre é um teste novo com premissa POSIX. Padrões e remédios já vistos:

  • "/tmp", /etc/... como caminho absoluto: no Windows é relativo. Use a forma nativa de cada plataforma ou cfg(unix) quando o que se prova é Unix.
  • Separador em asserção de string: compare PathBuf (componentes), não String.
  • wc -c e afins: o PowerShell entrega CRLF ao filho.
  • Tempdir do macOS é symlink (/var/... → /private/var/...): compare canônicos.
  • wrap_command do sandbox sonda docker no host (o runner macOS não tem): injete a sonda com wrap_command_com(true, |_| true, ...), como os irmãos.
  • PathBuf::push sobre base verbatim do Windows normaliza .. antes do jail ver o caminho: monte o caminho como texto se o .. precisa chegar à guarda.
  • Varredura de fonte (include_str!) que procura "\n}\n": o checkout do Windows é CRLF. Normalize com .replace("\r\n", "\n") antes de varrer.
  • dead_code só no clippy do Windows: helper de teste usado apenas por testes cfg(unix) leva o mesmo cfg (#1762).

Não marque cfg(unix) o que a produção executa no Windows; só o que é Unix por natureza (sandbox, printenv, symlink). A promoção do job a obrigatório é decisão do dono, registrada na #1697.

Vermelho ambiental já visto (#1762): o leg falha em ~20 s no passo Install Rust com could not download file from 'https://static.rust-lang.org/...' e connection error (rede do runner ao baixar a toolchain; nenhum teste rodou). Não é da PR: re-execute só o leg com gh run rerun --job <job_id> depois que a run inteira terminar.


3. Bump do wasmtime: o piso de MSRV vem junto

Já aconteceu seis vezes (1.92, 1.93, 1.94, 1.95, 1.96, 1.97). Um PR do Dependabot que sobe wasmtime costuma trazer dois bloqueios independentes, e o segundo não aparece se você ler só o erro de compilação:

  1. quebra de API em crates/garraia-plugins/src/runtime.rs;
  2. MSRV check falhando antes de compilar, porque a árvore wasmtime/cranelift-*/pulley-*/wiggle-* declara um rust-version novo.

Corrigir só o código deixa o job de MSRV vermelho. Subir o piso toca Cargo.toml (rust-version) e o ci.yml (nome do job, dtolnay/rust- toolchain@X.YZ, e as duas invocações cargo +X.YZ). Prove nos dois sentidos: o novo piso passa --locked, o antigo ainda recusa. Depois, os espelhos: README (en e pt-BR), CONTRIBUTING.md, scripts/setup-toolchain.sh, scripts/build-installer.ps1, docs, wiki e website — cargo test -p garraia-config --test msrv_declarada_sem_drift fica vermelho ate todos subirem juntos (#1750).

Não confie na sugestão do compilador em migração de API do wasmtime-wasi: no bump 47→48 ele mandava trocar só FilePerms por FsPerms e manter DirPerms, o que não compilaria.


4. Auto-merge está armado neste repositório

Ele dispara assim que os checks obrigatórios passam — o que pode ser antes de todos os checks terminarem, e antes de você chamar merge.

Consequências práticas:

  • Nunca afirme que você mergeou sem conferir merged_at e merged_by. Uma chamada de merge sobre PR já mergeado retorna "successfully merged" de forma idempotente, e o commit_title que você passou é ignorado.
  • Por isso, arrume o título do PR antes de ele ficar verde. O squash herda o título do PR, e o auto-merge usa o valor em cache. Um título autogerado (Claude/foo-bar-abc123) vira assunto de commit na main, fora de Conventional Commits — e corrigir depois exigiria reescrever a main, o que é proibido.

5. O CI não roda em branch solta

ci.yml dispara em push para main/develop/master e em pull_request para esses alvos. Empurrar uma branch não roda nada: sem PR aberto, não há validação de CI. Planeje isso — e não peça para o usuário "esperar o CI" de uma branch que não tem PR.


5a. gitleaks lê o intervalo de commits do PR

O job de segredos varre cada commit do PR, não só o diff final. Um fixture com cara de credencial (chave de teste, token de exemplo) que entrou num commit e saiu no seguinte continua vermelho — apagar o arquivo não resolve.

  • A saída é uma entrada de fingerprint exato em .gitleaksignore (<commit>:<arquivo>:<regra>:<linha>, o que o próprio relatório imprime), com um comentário dizendo por que é falso positivo.
  • Nunca reescreva commit já empurrado para sumir com o achado, e nunca afrouxe regra do gitleaks para o PR passar. As duas saídas escondem o próximo segredo de verdade junto com o falso.
  • Credencial real que entrou num commit empurrado é incidente, não falso positivo: revogue antes de qualquer outra coisa.

5b. Trem de merge: desligue o auto-merge primeiro

Com checks estritos, cada merge em main deixa as outras PRs BEHIND. Antes de montar um trem de merge local, desligue o auto-merge de toda PR carregada (gh pr merge --disable-auto <n>): uma PR que fica verde no meio do trem entra sozinha, e o trem passa a conflitar com ela. Na v0.4.3 foi exatamente isso.


6. Ao reagir a um review

Achado de bot é relatório de defeito: verifique e corrija se for pequeno e local. Se os achados pararem de convergir (cada correção gera um novo), pare de empurrar e levante o assunto uma vez, dizendo o que continua sinalizado.

Pedido grande de revisor humano em PR que não é seu → responda com a proposta, não empurre nem resolva a thread.

Mudança que toca segurança, auth, storage, RLS, secrets ou CI crítico: o CLAUDE.md manda acionar os agents security-auditor e code-reviewer antes de seguir.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.