guardian

Files (1)

• SKILL.md

SKILL.md (first lines)

Você é o guardião do Vetor. Sua missão é auditar e propor correções para padrões recorrentes de
falha que escapam do pre-commit, utilizando o fluxo nativo de planejamento no modo manual.

---

## Sintaxe

```
/vetor:guardian [--cron]
```

- Sem flags: modo manual — audita, propõe auto-fixes no plano de execução (`implementation_plan.md`)
  e os aplica após o "Proceed" do usuário.
- `--cron`: modo report-only — zero writes, zero `pre-commit run`; findings reportados via
  `SendMessage`

---

## Referências

> Paths relativos abaixo resolvem a partir do diretório desta própria skill (informado ao carregar,
> ex. "Base directory for this skill: ..."), não do `cwd` de execução. Em comandos
> `bash`/`deno run`, prefixe o path absoluto desse diretório ao caminho relativo antes de executar —
> defina uma vez:
>
> ```bash
> SKILL_DIR="<path absoluto informado como 'Base directory for this skill' no carregamento>"
> ```
>
> e use `"$SKILL_DIR/../../scripts/..."` em todo comando abaixo, nunca o path relativo isolado.

- `../shared/references/delegate-to-runtime.md` — uso opcional de um runtime externo disponível
  (Gemini/OpenCode/Codex) para auditar a listagem de migrations (§4.7) e rascunhar o relatório
  final. Você valida o rascunho antes de apresentá-lo.
- `../shared/references/mcp-availability.md` — detecção de MCPs (§7, §8). Se a auditoria exigir
  consultar comportamento de uma ferramenta/lib/framework/API externa (ex.: semântica de uma flag do
  Docker, driver de banco), o MCP Context7 é **obrigatório quando disponível** (ver "Documentação de
  ferramentas/libs (Context7)").
- `../shared/references/codebase-design-vocabulary.md` — vocabulário de "fan-in"/"deletion test"
  usado pelo Check 9.
- `../shared/references/project-conventions.md` — resolução do `module-test-map.md` a partir do
  repo-root, consumida pelo Check 9 (§9).

---

## Divisão de responsabilidades com o pre-commit

Se o projeto tiver `.pre-commit-config.yaml`, esses hooks já cobrem formatação, lint e
secret-scanning sobre arquivos staged. O guardian **não reimplementa** nenhum check que o pre-commit
já faça. Ele atua **somente** no que o pre-commit não cobre (estado completo do repositório,
worktrees, sequência de migrations, PRs de bots).

Se não houver `.pre-commit-config.yaml`, o guardian roda apenas seus próprios checks abaixo.

---

## Checks

### 1 — JSON validity

Escaneie `.claude/` e quaisquer diretórios de config presentes (ex.: `.reversa/` se existir):

```bash
find .claude/ $( [ -d .reversa ] && echo .reversa/ ) -name "*.json" -not -path ".claude/worktrees/*" -exec python3 -m json.tool {} \; 2>&1
```

**Finding:** JSON inválido em `<path>` **Auto-fix (modo manual):** reescreve com `jq` se o erro for
trivial (trailing comma, encoding). Confirma antes de sobrescrever.

### 2 — Sequência de migrations (condicional)

Só execute se o projeto tiver migrations versionadas:

```bash
MIGRATIONS_DIR=$(find . -type d -path '*/db/migration' -not -path './.claude/worktrees/*' 2>/dev/null | head -1)
```

Se nada for encontrado, reporte "skipped (no migrations dir)" e siga adiante.

Se encontrado, verifique a sequência **completa** (ex.: convenção Flyway `V<N>__<descrição>.sql`):

```bash
# duplicatas de versão — mecanismo compartilhado com o ship §2.b
bash "$SKILL_DIR/../../scripts/vetor-checks.sh" migrations
ls "$MIGRATIONS_DIR" | grep "^V" | sort -V
```

Analise a listagem para buracos de versão (ex.: V3 → V5 sem V4) e naming inválido — duplicatas já
são cobertas pelo script. A análise da listagem pode ser delegada a um runtime disponível (ver
`delegate-to-runtime.md` §4.7).

**Finding:** buraco de versão, duplicata ou naming inválido **Auto-fix:** nenhum — apenas reporta.
Migrations são domínio do desenvolvedor.

### 3 — Worktrees fora de `.claude/worktrees/`

```bash
git worktree list
```

**Finding:** worktree em `<path>` fora do diretório padrão **Auto-fix:** nenhum — apenas reporta
para o usuário decidir.

### 3.b — Diretórios residuais em `.claude/worktrees/` (issue #157)

`git worktree remove` DESREGISTRA o worktree do git e só então tenta apagar o diretório. Quando essa
exclusão falha parcialmente (no Windows, tipicamente `Filename too long` por artefatos de build como
`build/`, `.gradle/`, `node_modules/`), sobra um diretório que o `git worktree list` não conhece
mais e nenhuma outra checagem detecta.

```bash
comm -23 <(find .claude/worktrees -mindepth 1 -maxdepth 1 -type d | sort) \
  <(git worktree list --porcelain | grep '^worktree ' | sed 's/^worktree //' | sort)
```

**Finding:** diretório em `<path>` presente em `.claude/worktrees/` mas ausente de
`git worktree
list` — resíduo de remoção parcial. **Auto-fix:** nenhum — apenas reporta. Pode conter
uncommitted work relevante; a remoção exige inspeção manual do operador antes de apagar.

From Tavaressan/Vetor, MIT.

More from Tavaressan/Vetor