@tavaressan/vetor 0.1.0

package/templates/skills/fix-loop-agent/SKILL.md

@@ -0,0 +1,255 @@
+---
+name: fix-loop-agent
+description: Loop autônomo de reproduce → fix → rebuild → test até CI verde (orçamento sugerido de 5 iterações, não enforced — ver issue #156). Opera apenas dentro de worktree. Não cria PR — isso é responsabilidade do worktree-ship.
+license: MIT
+compatibility: Claude Code
+metadata:
+  author: vitortavares
+  version: "1.0.1"
+---
+
+Você é o agente de fix autônomo do Vetor. Sua missão é iterar sobre falhas de build/test até atingir verde, dentro de um worktree já criado.
+
+🚫 **NUNCA entre em plan mode (`EnterPlanMode`).** Este skill roda tipicamente em agentes headless
+despachados em background (`issue-worker`), sem interlocutor disponível para aprovar a saída via
+`ExitPlanMode` — entrar em plan mode aqui trava a sessão sem recuperação. Independente de a tarefa
+parecer "não-trivial" pela heurística padrão do Claude Code, vá **direto** para reproduce → fix
+(passo 3), nunca produza um plano para aprovação antes de agir.
+
+⚠️ **IMPORTANTE — Fluidez síncrona obrigatória:** Você NUNCA deve invocar ou esperar por padrões de
+"monitor em background" (ex.: "I'll wait for this background monitor to notify me"). Seu próprio
+fluxo de execução é **síncrono** — execute cada passo até o final, sem pausar para aguardar
+notificação externa. Se encontrar algo que pareça monitoramento assíncrono, ignore-o e prossiga.
+Parar antes de atingir um estado terminal é uma falha silenciosa que o coordinator não detecta.
+
+**Ação obrigatória inaugural:** Antes de qualquer passo (antes do `vetor-checks.sh`, antes de
+detectar módulos, antes de qualquer coisa), grave o status file com `Status: RUNNING`. Isso torna
+a ausência total do arquivo um sinal detectável de falha anômala.
+
+---
+
+## Sintaxe
+
+```
+/vetor:fix-loop-agent <descrição>
+```
+
+- `<descrição>`: texto livre descrevendo o problema a reproduzir e corrigir (ex.: "cargo clippy warnings em embedding-service", "frontend build failing on import")
+
+---
+
+## 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/project-conventions.md` — resolva `$DEFAULT_BRANCH`
+  e o `module-test-map` antes de prosseguir. **A resolução do `module-test-map.md`/`config.json`
+  sempre usa o root do repositório (`vetor-checks.sh repo-root`), nunca o `cwd`** — dentro de um
+  worktree, arquivos ignorados pelo `.gitignore` do projeto-alvo (ex.: `.claude/`) não existem
+  localmente (issue #160).
+- `../shared/references/agent-status.template.md` — path, estados e blocos
+  obrigatórios do status file.
+- `../shared/references/touched-files-cache.md` — formato do cache gravado no §1.
+- `../shared/references/delegate-to-runtime.md` — resumo opcional da saída de
+  erro dos testes delegado a um runtime externo disponível (Gemini/OpenCode/Codex). **A decisão e a
+  aplicação do fix são sempre suas, nunca do runtime delegado.**
+- `../shared/references/mcp-availability.md` — se a `<descrição>` indicar bug
+  visual/frontend e o MCP de browser estiver disponível, use-o antes do §3.a para reproduzir o bug e
+  capturar evidência. Se o erro envolver comportamento de uma ferramenta/lib/framework/API externa,
+  o MCP Context7 é **obrigatório quando disponível** (ver "Documentação de ferramentas/libs
+  (Context7)") antes de aplicar o fix.
+- `../shared/references/frontend-design-enforcement.md` — se a `<descrição>`
+  indicar UI/design de frontend, invoque a skill `vetor:design` antes de aplicar o fix (§3.b).
+- `../shared/references/tdd-conventions.md` — disciplina completa de TDD
+  (bom teste, seams, anti-padrões, mocking) consumida pelo passo TDD de §3.b — não replique o texto
+  aqui.
+- `../shared/references/evidence-state.md` — vocabulário de rastreabilidade
+  epistemológica (`CONFIRMED`/`INFERRED`/`ASSUMED`/`OPEN_QUESTION`, Evidence Conflict) usado ao
+  redigir `Blocked on` em `BLOCKED_WAITING` (§2) quando o bloqueio for epistemológico, não uma
+  permissão de comando.
+
+---
+
+## Comportamento
+
+### 0 — Status file inaugural + Guarda de contexto
+
+**Primeira ação (antes de tudo):** grave o status file com `Status: RUNNING`. Derive o path conforme
+§2 (ou use o path absoluto recebido do `issue-coordinator`).
+
+```bash
+bash "$SKILL_DIR/../../scripts/vetor-checks.sh" in-worktree
+```
+
+Se sair não-zero, **aborte**: `/vetor:fix-loop-agent` deve rodar de dentro de um worktree.
+
+### 1 — Detectar módulos
+
+```bash
+git diff "$DEFAULT_BRANCH" --name-only
+```
+
+Mapeie ao módulo usando a tabela do module-test-map, resolvido a partir do root do repositório
+(ver `project-conventions.md`), não do `cwd` do worktree. Módulos cujo comando é
+`sem suíte de testes` não entram no loop: registre `skipped (no test suite)` e não os trate como
+falha.
+
+Depois de resolver os módulos, grave o cache de arquivos tocados conforme
+`touched-files-cache.md` — ele é consumido pelo `code-review` na mesma branch.
+
+### 2 — Status file
+
+Antes de cada iteração, atualize o status file (path e formato em `agent-status.template.md`). Se
+você foi despachado pelo `issue-coordinator`, use o path absoluto recebido no prompt; em uso manual,
+derive-o: `<repo-root>/.claude/vetor/status/<branch com / trocada por ->.md` (root via
+`git rev-parse --git-common-dir`).
+
+Se bloqueado por permissão ou decisão técnica, mude `Status` para `BLOCKED_WAITING` preenchendo os
+blocos `Blocked on` / `Options` / `Recommendation` — o coordinator escala ao usuário a partir deles.
+Iterações em `BLOCKED_WAITING` **não contam** contra o orçamento de 5.
+
+Se o bloqueio for epistemológico — falta uma informação decisiva, uma premissa assumida precisa de
+confirmação, ou duas evidências se contradizem — nomeie a natureza do bloqueio em `Blocked on` com o
+vocabulário de `evidence-state.md`: `OPEN_QUESTION` crítica, `ASSUMED` que precisa confirmação, ou
+`Evidence Conflict`. O mecanismo de escalação continua sendo `BLOCKED_WAITING`; o vocabulário só
+qualifica o motivo, sem criar um segundo caminho de escalação paralelo.
+
+⚠️ **O limite de 5 é um orçamento sugerido, não um hard cap enforced (issue #156):** nenhum hook
+interrompe a sessão automaticamente ao ultrapassá-lo. A responsabilidade de parar é sua — nunca
+decida sozinho "mais uma tentativa" ao chegar na 5ª iteração sem verde. Vá direto para o §4 (Handover
+de Falha) ou, se identificar que falta uma decisão que só o coordinator/usuário pode tomar, registre
+`BLOCKED_WAITING` em vez de continuar por conta própria.
+
+### 3 — Loop principal (orçamento de N=5 iterações)
+
+Para cada iteração `i` de 1 a 5:
+
+**3.a — Executar testes**
+
+Execute o comando headless do módulo detectado. Se for `sem suíte de testes`, pule o módulo sem
+consumir uma iteração.
+
+**Docker:** tente o path docker apenas na **primeira** tentativa, se aplicável. Se bloqueado, troque
+para headless **permanentemente** nesta execução e nunca retente docker.
+
+**Comando bloqueado por permissão:** se você é o `issue-worker` despachado pelo `issue-coordinator`
+(não uma sessão manual) e qualquer comando fica pendente de confirmação, **não espere nem retente**
+— ninguém está olhando o terminal. Mude `Status` para `BLOCKED_WAITING` descrevendo o comando exato
+que precisa de aprovação, para o coordinator escalar (§5.b dele).
+
+**Instalação de dependências:** já preparadas na criação do worktree pelo hook `WorktreeCreate`
+(`scripts/prepare-worktree.ts`). Só instale se o teste falhar por dependência ausente — e nesse caso
+**sempre dentro do diretório do módulo**, nunca da raiz com flags de workspace (tocam recursos
+compartilhados e podem ser bloqueadas por permissão):
+
+```bash
+# ✅ Correto
+cd <módulo-alterado> && <deno install | npm ci | pnpm install>
+
+# ❌ Evite
+npm ci --workspace=<módulo>  # (a partir da raiz)
+```
+
+O instalador correto vem do `runtime`/`packageManager` de `.claude/vetor/config.json`. Se um comando
+de instalação for necessário aqui, reporte isso no `BLOCKED_WAITING` — não tente resolver com
+`rm`/reinstalação ampla por conta própria.
+
+**3.b — Avaliar resultado**
+
+Se **verde** (todos os testes passaram):
+```json
+{"status": "green", "iterations": <i>, "module": "<módulo>"}
+```
+Atualize o status file com `Status: GREEN` e **pare**.
+
+Se **vermelho**:
+1. Leia a saída de erro (opcionalmente condensada por um runtime de delegação disponível — ver
+   `delegate-to-runtime.md` §4.1).
+2. **Hipóteses**: a partir do erro lido, liste 2-3 hipóteses candidatas (não 3-5 — o Vetor já opera
+   sob orçamento agressivo de iterações) para a causa raiz e escolha a de maior probabilidade antes
+   de escrever o teste de reprodução do passo 3. Registre a escolha no campo `Last action` do status
+   file, formato: `Last action: hipótese escolhida: <descrição curta> (descartadas: <outras
+   hipóteses>)`. Se esta não é a primeira iteração e o teste continua vermelho com a **mesma
+   assinatura de erro** da iteração anterior, não repita a hipótese já aplicada — promova a próxima
+   hipótese da lista anterior ou reformule com base no novo resultado. Aplica-se a toda iteração
+   vermelha, não só a primeira; se o erro tiver causa óbvia (uma hipótese clara), o passo é rápido —
+   não gere hesitação artificial nem rodada de perguntas (o loop é headless, nunca pergunta ao
+   usuário).
+
+   **Gatilho condicional de instrumentação por fronteira:** se a mesma assinatura de erro sobreviver
+   a 2 hipóteses consecutivas (ou seja, você está prestes a formular a 3ª hipótese para essa mesma
+   assinatura), pare de adivinhar às cegas — antes de escolher a 3ª hipótese, insira uma checagem
+   pontual de entrada/saída de dados (log ou assert do valor que entra e do valor que sai) na
+   fronteira do componente suspeito indicado pelas 2 tentativas anteriores. Use apenas essa fronteira,
+   não instrumente o sistema inteiro (ver `wiki/Decisoes-de-Design.md` para por que o protocolo
+   completo de instrumentar toda fronteira antes de qualquer hipótese não foi adotado como padrão
+   universal aqui). Formule a 3ª hipótese a partir da evidência coletada nessa checagem, não por
+   eliminação especulativa.
+3. **Nunca conserte só o sintoma**: antes de aplicar o fix (passo 5), cheque: "este é o ponto de
+   origem do problema, ou ele entra aqui vindo de outro lugar?". Se o valor/estado já chega errado
+   neste ponto — produzido por uma camada anterior (ex.: um `null` que devia ter sido validado ou
+   preenchido antes) — suba a correção até a origem, não até o primeiro ponto onde o erro se
+   manifestou. Este é um filtro rápido sobre a hipótese já escolhida no passo 2, não uma nova
+   investigação; se a hipótese já aponta para a origem, siga direto.
+4. **TDD** (ver `tdd-conventions.md` para a disciplina completa — bom teste, seams, anti-padrões,
+   mocking): se for a primeira iteração (`i=1`) e os testes ainda não falharem para o bug relatado,
+   escreva um teste de reprodução simples que quebre cobrindo a hipótese escolhida no passo 2 — uma
+   fatia por vez (vertical slice), nunca todos os cenários de uma vez. Refactor não é parte deste
+   ciclo: achados de arquitetura/refatoração ficam para o `code-review`, despachado depois pelo
+   `worktree-ship`. Só altere o código do produto após o teste estar vermelho.
+5. **KISS/YAGNI**: aplique a menor alteração atômica que faz o teste passar — sem refatoração
+   especulativa fora de escopo.
+6. Commit: `fix: <descrição curta do fix>`
+7. Atualize o status file
+8. Continue para a próxima iteração
+
+### 4 — Após N=5 falhas (Handover de Falha)
+
+**Pare aqui — não inicie uma 6ª iteração.** Mesmo que o próximo fix pareça óbvio ou quase certo, o
+orçamento estourado deve virar handover, não mais uma tentativa por conta própria (issue #156).
+
+1. Atualize o status file com `Status: FAILED_MAX_ITERATIONS`.
+2. Crie `FAIL_ANALYSIS.md` no root do worktree:
+
+```markdown
+# Handover de Falha — Vetor
+
+O agente de correção automática falhou após 5 iterações.
+
+## Detalhes
+* **Módulo**: <módulo>
+* **Comando de Teste**: `<comando-de-teste>`
+
+## Último Erro de Teste
+```
+<erro bruto ou resumo do erro obtido na última iteração>
+```
+
+## Hipóteses Consideradas
+1. Iteração 1: <hipótese escolhida> — <refutada | ainda não avaliada>
+2. Iteração 2: <hipótese escolhida> — <refutada | ainda não avaliada>
+
+## Fixes Tentados (Commits locais)
+1. <fix commit 1>
+2. <fix commit 2>
+
+## Próximo Passo Sugerido (Humano)
+<análise concisa da causa provável e recomendação de correção manual>
+```
+
+**Pare.** Não crie PR, não faça push — o worktree fica intacto para inspeção.
+
+---
+
+## O que este skill NÃO faz
+
+- **Não cria worktree** — espera que ele já exista (via `worktree-create` ou manualmente)
+- **Não faz push** — o código fica local no worktree
+- **Não cria PR** — isso é responsabilidade do `worktree-ship`
+- **Não resolve conflitos de merge** — se houver conflito com a branch default, reporte e pare

package/templates/skills/guardian/SKILL.md

@@ -0,0 +1,343 @@
+---
+name: guardian
+description: Audit + auto-fix de gaps que o pre-commit não cobre guiado por Planejamento. JSON validity, migrations, worktrees, uncommitted work, status files órfãos, Dependabot, saúde de containers Docker.
+license: MIT
+compatibility: Claude Code
+metadata:
+  author: vitortavares
+  version: "1.4.1"
+---
+
+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 worktree-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.
+
+### 4 — Auditoria de worktrees (idade, tamanho, PR, uncommitted)
+
+Responde "o que sobrou e por quê?" — o cleanup do `worktree-ship` (passo 12) só roda no caminho
+feliz; execuções que falham no CI, ficam em revisão ou são abandonadas deixam worktree órfão.
+
+```bash
+bash "$SKILL_DIR/../../scripts/vetor-checks.sh" worktree-audit
+```
+
+Cada linha vem como `<path>|<branch>|<age_days>|<size_kb>|<uncommitted:yes/no>` (`age_days` medido
+do último commit, proxy de staleness). Cruze a `<branch>` com o status do PR:
+
+```bash
+gh pr list --state all --json headRefName,number,state
+```
+
+Monte a tabela de auditoria:
+
+| Worktree | Branch | Idade | Tamanho | PR | Uncommitted |
+|---|---|---|---|---|---|
+| `<path>` | `<branch>` | `<N>d` | `<tamanho legível>` | `#<N> (OPEN\|MERGED\|CLOSED)` ou "sem PR" | ✅/⚠️ |
+
+**Finding:** worktree com idade > 7 dias, sem PR aberto e sem trabalho pendente — candidata a remoção segura.
+**Finding:** worktree com `uncommitted=yes` — nunca remover automaticamente.
+**Auto-fix (modo manual):** para candidatas seguras (`uncommitted=no` **e** PR ausente ou já
+`MERGED`/`CLOSED`), propõe no plano `bash "$SKILL_DIR/../../scripts/vetor-checks.sh"
+safe-remove-worktree <path>` — nunca `--force`, e nunca sobre worktree com `uncommitted=yes` ou
+branch com commits ausentes no remoto (`git log origin/<branch>..<branch>` não vazio → não propõe).
+Aplica somente após aprovação explícita.
+
+### 5 — Reconciliação de status files órfãos
+
+Arquivos em `.claude/vetor/status/` sobrevivem à remoção do worktree que os gerou.
+
+```bash
+bash "$SKILL_DIR/../../scripts/vetor-checks.sh" find-orphan-status
+```
+
+O script já confirma que o worktree correspondente não existe mais em `git worktree list`.
+
+**Finding:** status file órfão em `<path>` (worktree removido)
+**Auto-fix (modo manual):** propõe `bash "$SKILL_DIR/../../scripts/vetor-checks.sh"
+archive-orphan-status <path>` — move para `.claude/vetor/status/archive/` (não apaga; reversível).
+Aplica somente após aprovação explícita.
+
+### 6 — PRs Dependabot com rebase pendente
+
+```bash
+gh pr list --author "app/dependabot" --state open
+gh pr view <N> --json mergeable,mergeStateStatus
+```
+
+**Finding:** PR Dependabot #<N> com merge conflict / needs rebase
+**Auto-fix (modo manual):** registra a proposta no plano (`gh pr comment <N> --body "@dependabot rebase"`).
+
+### 7 — Auditoria de Banco de Dados (via MCP)
+
+Verifique disponibilidade de um MCP de banco (`mcp__<db>__*` — o nome do servidor varia). Se não
+houver, ignore este check. Se houver, audite a saúde estrutural (adapte ao dialeto):
+
+- Índices não utilizados.
+- Tabelas sem chave primária ou índices.
+- Constraints violadas ou chaves estrangeiras não indexadas.
+
+Se o stack for identificável (`mcp__planetscale__*`, `mcp__postgres__*`, `mcp__mysql__*`, ou
+`DATABASE_URL`/`.env` com dialeto claro), aprofunde:
+- **Index-aware:** cruze colunas usadas em `WHERE`/`JOIN`/`ORDER BY` (se o MCP expuser queries
+  frequentes) contra os índices existentes.
+- **N+1:** se houver log/histórico de queries, procure a mesma query parametrizada repetida em
+  sequência curta.
+- **PlanetScale:** aponte migrations de schema pendentes de deploy (branch de schema não mergeada).
+
+**Finding:** <detalhes da anomalia encontrada>
+**Auto-fix:** nenhum — apenas reporta.
+
+### 8 — Auditoria de Saúde de Containers Docker (via MCP)
+
+Verifique disponibilidade de um MCP Docker (`mcp__docker__*`, diretas ou diferidas). Se não houver,
+ignore silenciosamente.
+
+Se disponível, liste os containers do projeto (equivalente a `docker ps`/`docker inspect`) e
+identifique quais **não** estão `running`/`healthy` (ex.: `exited`, `restarting`, `unhealthy`).
+
+**Finding:** container `<nome>` em estado `<status>` (esperado: running/healthy)
+**Auto-fix:** nenhum — apenas reporta. Este check não valida especificidades de stack, apenas o
+estado do container.
+
+### 9 — Risco arquitetural (deletion test)
+
+Sinal contínuo de dívida arquitetural, não reativo a uma deleção pontual: mede o fan-in (quantos
+outros arquivos importam) dos módulos **tocados nos últimos 7 dias**, como proxy do "deletion test"
+(Feathers/Pocock) — um módulo bem desenhado pode ser deletado e refeito sem espalhar mudança.
+Read-only e barato (nunca cria/aplica fix de código). Vocabulário de "fan-in"/"deletion test" definido
+em `../shared/references/codebase-design-vocabulary.md` §Princípios
+(compartilhado com `architecture-review`, survey mais profundo e qualitativo — este check é só a
+heurística barata de contagem).
+
+```bash
+bash "$SKILL_DIR/../../scripts/vetor-checks.sh" architectural-risk
+```
+
+O script resolve os módulos tocados via `git log --since="7 days ago" --name-only`, mapeados pela
+tabela "Detecção de módulo por arquivos alterados" do `module-test-map.md` (mesma resolução usada
+por `fix-loop-agent` — sempre a partir do repo-root, nunca do `cwd`, ver `project-conventions.md`).
+Para cada módulo tocado, mede fan-in via `grep -rlE "(import|require).*['\"].*<módulo>"` (heurística
+textual, sem AST). Emite uma linha por módulo: `<módulo>|<fan-in>|<candidate:yes/no>` —
+`candidate=yes` quando fan-in > 10 (heurística ajustável, **não** é hard cap — mesmo espírito das
+heurísticas de `code-review`). Nenhum módulo tocado nos últimos 7 dias → sem saída, reporte
+"skipped (nenhum módulo tocado nos últimos 7 dias)".
+
+**Finding:** módulo `<nome>` com fan-in alto (`<N>` arquivos importam diretamente) — candidato a
+revisão de design (deletion test: dificilmente removível/refazível sem espalhar mudança).
+**Auto-fix (modo manual):** propõe no plano "Criar issue de revisão de design para `<módulo>`"
+(label `ai-generated`) — só executa `gh issue create` após aprovação explícita, igual aos demais
+auto-fixes do guardian. A issue criada é delegada ao fluxo humano existente
+(`backlog-ideator`/`issue-coordinator`), nunca refatorada pelo guardian.
+**Auto-fix (modo --cron):** apenas reporta via `SendMessage` (segue a regra global da seção "Modo
+cron" abaixo) — **nunca** propõe `implementation_plan.md` nem cria issue.
+
+### Staleness de regras de melhores práticas (`/vetor:stack-practices`)
+
+Sinalização leve, sem virar check numerado — reaproveita o padrão read-only já usado pelos checks
+acima. Se `.claude/rules/vetor/best-practices/*.md` existir, leia a data no cabeçalho de proveniência
+(linha `> Gerado por /vetor:stack-practices ... via Context7 em <data>`) de cada arquivo. Para os que
+tiverem mais de 90 dias:
+
+**Finding:** regra de best-practice de `<lib>` desatualizada (`<N>` dias) — considere
+`/vetor:stack-practices --refresh`
+**Auto-fix:** nenhum — só sinaliza. A refresh consulta o Context7 de novo, o que exige julgamento
+sobre qual versão da lib está em uso agora; não é uma mutação mecânica que o guardian deva aplicar
+sozinho.
+
+---
+
+## Relatório e Fluxo de Planejamento (Modo Manual)
+
+Havendo findings com auto-fix propostos, entre em Modo de Planejamento gerando ou atualizando
+`implementation_plan.md` com `request_feedback: true` e `user_facing: true`:
+
+```markdown
+# Plano de Execução Vetor — Guardian
+
+Audit concluído. Mutações recomendadas abaixo.
+
+## Ações Propostas
+
+### Auto-fixes Recomendados
+- [ ] Corrigir JSON inválido no arquivo: `<path>`
+- [ ] Remover worktree órfão (limpa, sem PR aberto): `bash "$SKILL_DIR/../../scripts/vetor-checks.sh" safe-remove-worktree <path>`
+- [ ] Arquivar status file órfão: `bash "$SKILL_DIR/../../scripts/vetor-checks.sh" archive-orphan-status <path>`
+- [ ] Solicitar rebase do Dependabot no PR #<N> (`gh pr comment <N> --body "@dependabot rebase"`)
+- [ ] Criar issue de revisão de design para `<módulo>` (label `ai-generated`, fan-in alto — deletion test)
+
+### Alertas (Apenas Leitura / Ação Manual do Usuário)
+- [Aviso] Sequência de migrations com buracos ou timestamps incorretos
+- [Aviso] Trabalho não commitado no worktree: `<worktree-path>`
+- [Aviso] Worktree localizado fora do padrão: `<path>`
+- [Aviso] Container Docker fora de healthy/running: `<nome>` (`<status>`)
+- [Aviso] Regra de best-practice de `<lib>` desatualizada (`<N>` dias) — considere `/stack-practices --refresh`
+
+## Instruções de Aprovação
+Clique no botão **Proceed** no seu editor para autorizar o Guardian a aplicar os auto-fixes recomendados.
+```
+
+**Pare.** Aguarde a aprovação (`request_feedback: false`). Se aprovado, aplique os auto-fixes selecionados.
+
+Após a execução (ou se nenhum finding necessitar correção), produza o relatório final no chat:
+
+```
+## Guardian Report — <data>
+
+### Found (problemas detectados)
+- <item 1>
+
+### Fixed (auto-corrigidos nesta execução)
+- <item 1> — <ação tomada>
+
+### Hardened (verificações que passaram)
+- JSON validity: ✅ <N> arquivos verificados
+- Migrations: ✅ sequência sem buracos (ou "skipped — no migrations dir")
+- Worktrees: ✅ todos em .claude/worktrees/
+- Uncommitted work: ✅ nenhum
+- Auditoria de worktrees: ✅ <N> worktrees, <M> candidatas a remoção, <K> com trabalho pendente
+- Status órfãos: ✅ <N> status files verificados, <M> órfãos arquivados
+- Dependabot: ✅ <N> PRs abertos, nenhum com conflito
+- Docker containers: ✅ <N> containers, todos healthy/running (ou "skipped — MCP indisponível")
+- Risco arquitetural: ✅ <N> módulos tocados analisados, <M> candidatos (ou "skipped — nenhum módulo
+  tocado nos últimos 7 dias")
+
+### Skipped
+- <checks não executados e por quê>
+```
+
+---
+
+## Modo cron
+
+Quando invocado com `--cron` (via `CronCreate`):
+
+- **Zero writes**, **zero `pre-commit run`**, **zero git/gh mutations**
+- Findings vão via `SendMessage` para a sessão principal (nunca cria `implementation_plan.md`)
+- Se nenhum finding, silêncio — não envia mensagem vazia
+
+---
+
+## Exclusões obrigatórias
+
+Todo `find` ou `grep` deve excluir:
+- `.claude/worktrees/*`
+- `node_modules/`, `target/`, `.next/`, `__pycache__/`, `.venv/`
+
+---
+
+## Restrições
+
+- Nunca reimplementa checks que o pre-commit já cobre
+- Para formatação, delega para `pre-commit run --all-files` (modo manual apenas)
+- Em modo manual, toda mutação/auto-fix passa pelo `implementation_plan.md` antes da execução
+- Em modo `--cron`, absolutamente nenhum write