steward

Files (1)

• SKILL.md

SKILL.md (first lines)

# 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:

```bash
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:

```bash
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:

```bash
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

From michelbr84/GarraRUST, MIT.

More from michelbr84/GarraRUST