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
- btraceio/btracetheir own version, first seen Nov 16, 2026
- fworks-tech/agenthoodtheir own version, first seen Nov 16, 2026
- ForeactLabs/OpenExecutivetheir own version, first seen Nov 15, 2026
- 5thlayer/skillworkstheir own version, first seen Nov 8, 2026
- ElcanoTek/fleettheir own version, first seen Nov 8, 2026
- jmagly/kintsugi-usbtheir own version, first seen Nov 8, 2026
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.
MicrosoftSkillrelease
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
Other versions19 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 19
- btraceio/btrace★ 6ksame name
- ForeactLabs/OpenExecutive★ 5.8ksame name
- SenteLabsAI/OpenExecutive★ 5.8ksame name
- richlander/dotnet-inspect★ 166same name
- mendixlabs/mxcli★ 139same name
- yschimke/compose-ai-tools★ 127same name
- antiv/mate★ 111same name
- jmagly/kintsugi-usb★ 18same name
- jmagly/carbonyl-agent★ 16same name
- itsOmidKarami/kraft★ 13same name
9 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository8 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- esp32Skill
- home-assistantSkill
- matterSkill
- mqttSkill
- serial-arduinoSkill
- zigbeeSkill
The file
Files
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 -- --checkRode 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-desktopgarraia-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.sockOs 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_literalsandbox::tests::docker_leva_cap_drop_pids_limit_e_user_do_processosandbox::tests::linha_do_bash_leva_nome_do_containersandbox::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/nullSe 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 -> BlobNotFoundO 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 rodouO 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 canceladoComo 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 oucfg(unix)quando o que se prova é Unix.- Separador em asserção de string: compare
PathBuf(componentes), nãoString. wc -ce afins: o PowerShell entrega CRLF ao filho.- Tempdir do macOS é symlink (
/var/...→/private/var/...): compare canônicos. wrap_commanddo sandbox sondadockerno host (o runner macOS não tem): injete a sonda comwrap_command_com(true, |_| true, ...), como os irmãos.PathBuf::pushsobre 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_codesó no clippy do Windows: helper de teste usado apenas por testescfg(unix)leva o mesmocfg(#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:
- quebra de API em
crates/garraia-plugins/src/runtime.rs; MSRV checkfalhando antes de compilar, porque a árvorewasmtime/cranelift-*/pulley-*/wiggle-*declara umrust-versionnovo.
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_atemerged_by. Uma chamada de merge sobre PR já mergeado retorna "successfully merged" de forma idempotente, e ocommit_titleque 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 namain, fora de Conventional Commits — e corrigir depois exigiria reescrever amain, 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
gitleakspara 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.
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
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.

