@tavaressan/vetor 0.1.0

package/templates/skills/retro/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: retro
+description: Avalia o uso do Vetor nesta sessão, destaca o que pode ser melhorado no plugin em si (não no projeto do usuário) e propõe issues para o repositório do Vetor, com aprovação antes de criar.
+license: MIT
+compatibility: Claude Code
+metadata:
+  author: vitortavares
+  version: "1.0.0"
+---
+
+Você é o retrospectivo do Vetor. Sua missão é olhar para trás nesta sessão, identificar onde o
+**próprio plugin** (skills, agentes, hooks, scripts do Vetor) gerou fricção, ambiguidade ou
+comportamento incorreto — e propor issues acionáveis no repositório do Vetor para alimentar seu
+desenvolvimento.
+
+**Escopo estrito:** isto avalia o Vetor, não o projeto do usuário. Bugs no código do projeto, dívida
+técnica do projeto ou decisões de arquitetura do projeto **não** entram aqui — isso é trabalho do
+`/vetor:backlog`.
+
+---
+
+## Sintaxe
+
+```
+/vetor:retro
+```
+
+Invocação manual, tipicamente ao final de uma sessão que usou uma ou mais skills do Vetor
+(`backlog-ideator`, `issue-coordinator`, `guardian`, `worktree-create`, `worktree-ship`,
+`fix-loop-agent`, `issue-worker`).
+
+---
+
+## 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/mcp-availability.md` — ao avaliar um achado sobre
+  hooks, slash commands, configuração de MCP, permissões ou SDK de agentes do próprio Claude Code, o
+  MCP `claude-code-docs` é **obrigatório quando disponível** (ver "Documentação do próprio Claude
+  Code (`claude-code-docs`)") antes de afirmar o comportamento esperado da plataforma. Nota: há
+  sobreposição parcial com o agente `claude-code-guide` (dúvidas gerais do usuário sobre o produto) —
+  o `retro` usa o MCP para decisões internas sobre o comportamento do Vetor, não para responder
+  perguntas do usuário sobre o Claude Code em si.
+
+---
+
+## Comportamento
+
+### 1 — Levantar o que aconteceu nesta sessão
+
+Releia a conversa (não o histórico de outras sessões) em busca de interações com o Vetor. Para cada
+skill/agente do Vetor invocado, procure por sinais de fricção real — não invente achados:
+
+- **Você teve que improvisar** algo que a skill não documentava (ex.: um atalho, uma exceção, uma
+  interpretação de instrução ambígua).
+- **O usuário corrigiu** um comportamento seu relacionado a uma skill do Vetor (não ao código do
+  projeto).
+- **Uma alegação da skill se mostrou falsa** ao ser exercitada de verdade (ex.: um "enforcement" que
+  não bloqueou nada, um caminho documentado que não existe na plataforma).
+- **Um efeito colateral não documentado** apareceu (ex.: arquivo escrito fora do esperado, chamada que
+  falhou silenciosamente).
+- **Um passo pareceu redundante ou bloqueou sem necessidade** (aprovação dupla, checagem que nunca
+  se aplica neste tipo de projeto, etc.).
+
+Se nenhuma dessas situações ocorreu na sessão, diga isso claramente e pare — não force achados.
+
+### 2 — Classificar e formular como issue candidata
+
+Para cada achado real, monte:
+
+```markdown
+### <Título curto e específico>
+
+**Tipo:** bug | enhancement | docs
+**Skill/arquivo afetado:** <ex.: skills/issue-coordinator/SKILL.md>
+**Evidência:** <trecho da sessão que mostra o problema — cite o que aconteceu, não hipótese>
+**Descrição:** <o que está errado ou faltando, e o efeito prático>
+**Sugestão de fix:** <se houver uma direção clara; opcional caso a solução não seja óbvia>
+```
+
+Priorize achados que **realmente aconteceram** nesta sessão sobre problemas hipotéticos.
+
+### 3 — Verificar duplicatas no repositório do Vetor
+
+Antes de propor criação, cheque se já existe issue equivalente no repo do Vetor (não no projeto
+atual). Resolva o repo alvo lendo `homepage` (ou `repository`, se presente) de
+`$SKILL_DIR/../../.claude-plugin/plugin.json` — hoje `Tavaressan/Vetor`.
+
+Use a CLI `gh`:
+  ```bash
+  gh issue list --repo Tavaressan/Vetor --search "<palavras-chave>" --state all
+  ```
+
+Se encontrar equivalente, não proponha criar de novo — anote como "já rastreado em #<N>" no resumo.
+
+### 4 — Apresentar e aguardar aprovação
+
+Apresente a lista de issues candidatas (após remover duplicatas) e obtenha aprovação seguindo o
+mecanismo do ecossistema atual (`../shared/references/planning-conventions.md`
+§2.2 — plan mode nativo no Claude Code via `ExitPlanMode`, `implementation_plan.md` com
+`request_feedback: true` no Antigravity, ou confirmação no chat).
+
+**Pare** até a aprovação. O usuário pode aprovar todas, algumas, ou nenhuma.
+
+### 5 — Criar as issues aprovadas — sempre no repo do Vetor, nunca no do projeto
+
+⚠️ **Restrição crítica:** estas issues vão para o repositório do **plugin** (`Tavaressan/Vetor`, lido
+do `plugin.json`), que quase sempre é diferente do repositório do projeto onde esta sessão está
+rodando. Sempre especifique o repo explicitamente — nunca deixe implícito no diretório atual.
+
+Use a CLI `gh`:
+  ```bash
+  gh issue create --repo Tavaressan/Vetor \
+    --title "<título>" \
+    --body "$(cat <<'EOF'
+  <corpo no formato de §2>
+
+  ---
+  🤖 Gerado por `/vetor:retro` — sessão em <projeto atual, sem dados sensíveis>
+  EOF
+  )"
+  ```
+  Não passe `--label retro` se não tiver certeza de que o label existe no repo alvo — `gh issue
+  create` falha se o label não existir. Tente sem label em caso de erro, e reporte a falha do label
+  sem abortar a criação da issue.
+
+Se a criação falhar (repo inacessível, sem permissão, `gh`/MCP indisponível), **não perca o
+trabalho**: imprima a lista completa de issues candidatas no chat para o usuário copiar manualmente.
+
+Após criação, imprima:
+
+```
+Issues de retrospectiva criadas em Tavaressan/Vetor:
+- #<N1> — <título 1>
+- #<N2> — <título 2>
+
+Já rastreados (duplicata, não recriado):
+- #<N3> — <título existente>
+```
+
+---
+
+## Restrições
+
+- Nunca avalia o código ou as issues do projeto do usuário — só o comportamento do Vetor
+- Nunca cria issues sem aprovação explícita
+- Nunca cria issues no repositório do projeto atual — sempre no repo do Vetor (`plugin.json`)
+- Não força achados: sessão sem fricção real produz "nada a reportar", não issues artificiais
+- Evidência é obrigatória por achado — sem trecho real da sessão, não vira issue candidata

package/templates/skills/shared/references/agent-status.template.md

@@ -0,0 +1,68 @@
+# Status file — fonte única do formato
+
+**Path canônico:** `<repo-root>/.claude/vetor/status/<branch com / trocada por ->.md`
+(ex.: branch `fix/42-cache-ttl` → `.claude/vetor/status/fix-42-cache-ttl.md`).
+
+Escrito pelo worker/fix-loop a cada iteração. Lido pelo `issue-coordinator` (via
+`scripts/vetor-status.sh`) e pelo safety hook (que bloqueia `git push`/`gh pr *` de um worktree
+enquanto `Status` ≠ `GREEN`). Fica **fora do worktree**, no root do repo — não há risco de commit
+acidental; o `/vetor` init garante a entrada no `.gitignore`.
+
+**Fallback (issue #94):** se a plataforma bloquear a escrita fora do worktree, o worker deve salvar
+uma cópia em `<worktree>/.claude/vetor-status.md`. O coordinator verifica esse fallback ao ler.
+
+## Estrutura base (todos os estados)
+
+```markdown
+# Agent Status — <branch>
+Updated: <ISO 8601>
+Status: RUNNING | BLOCKED_WAITING | GREEN | FAILED_MAX_ITERATIONS
+Iteration: <N>/5 (Issue #<M>)
+Last action: <última ação executada>
+Next: <próximo passo planejado>
+```
+
+## Blocos adicionais por estado
+
+**`BLOCKED_WAITING`** (obrigatórios — o coordinator escala ao usuário a partir deles; sem eles a
+escalação não acontece):
+
+```markdown
+Blocked on: <o que precisa — permissão, decisão técnica>
+Options:
+1. <opção sugerida>
+2. <opção alternativa>
+Recommendation: <opção recomendada e por quê>
+```
+
+Quando o bloqueio for epistemológico (falta de informação, premissa não confirmada, evidências que
+se contradizem) em vez de uma permissão de comando, use o vocabulário de
+`$CLAUDE_PLUGIN_ROOT/skills/shared/references/evidence-state.md` para nomear a natureza do bloqueio
+em `Blocked on` — ex.: `Blocked on: OPEN_QUESTION crítica — <pergunta>`, `Blocked on: ASSUMED sem
+confirmação — <premissa>` ou `Blocked on: Evidence Conflict — <fontes em contradição>`. Isso não cria
+um novo estado ou caminho de escalação: `BLOCKED_WAITING` continua sendo o único mecanismo; o
+vocabulário apenas qualifica o motivo já registrado em `Blocked on`.
+
+**`FAILED_MAX_ITERATIONS`**: além de atualizar o status, crie `FAIL_ANALYSIS.md` no root do
+worktree com o handover de falha (ver `fix-loop-agent` §4).
+
+Iterações em `BLOCKED_WAITING` não contam contra o orçamento de 5 do fix-loop (sugerido, não
+enforced pelo hook — issue #156: ao atingi-lo, registre `BLOCKED_WAITING` ou
+`FAILED_MAX_ITERATIONS`, nunca decida sozinho continuar).
+
+## Efeitos colaterais externos (fora do controle de versão)
+
+Testes locais passarem (verde) não é evidência de que uma ação que altera estado **fora do repositório**
+de fato colou — ex.: `gh api` fazendo PATCH/POST em branch protection, webhooks, secrets, configurações
+de repositório/organização no GitHub, ou qualquer outra chamada de API externa que muda estado remoto.
+
+**Regra:** antes de marcar `Status: GREEN` para uma ação desse tipo, o worker deve rodar um GET (ou
+comando de leitura equivalente) que confirme o novo estado imediatamente após o PATCH/POST, e incluir
+o resultado bruto (ou um resumo objetivo e verificável) no `Last action` do status file.
+
+- Se a verificação confirmar o estado esperado → prossiga para `GREEN` normalmente.
+- Se a verificação falhar, for inconclusiva, ou não puder ser executada (ex.: falta de permissão) →
+  marque `Status: BLOCKED_WAITING` com o motivo em `Blocked on`, nunca `GREEN` sem confirmação.
+
+Isso evita que o `issue-coordinator` e sessões futuras confiem em um estado externo que pode nunca ter
+sido aplicado ou que foi revertido silenciosamente, sem nenhum sinal de alerta no painel de status.

package/templates/skills/shared/references/codebase-design-vocabulary.md

@@ -0,0 +1,54 @@
+# Vocabulário de design de código (Vetor)
+
+Fonte única do vocabulário de arquitetura consumido por referência (sem replicar texto) por
+`architecture-review/SKILL.md` e pelo Check 9 do `guardian/SKILL.md` (que hoje usa "deletion test"/
+"fan-in" de forma solta, sem definição centralizada). Adapta o skill público
+`engineering/codebase-design` de Matt Pocock (github.com/mattpocock/skills) ao vocabulário do Vetor.
+
+Use estes termos consistentemente — nunca "componente"/"service"/"boundary" como sinônimo frouxo de
+`module`/`seam`.
+
+---
+
+## Termos
+
+- **Module (módulo)** — unidade de código com uma responsabilidade coesa e um limite identificável
+  (arquivo, diretório, package). A pergunta relevante nunca é "esse arquivo é grande?", mas "esse
+  módulo tem uma única razão coerente para mudar?".
+- **Interface** — a superfície pública através da qual outros módulos interagem com um módulo
+  (função exportada, endpoint, CLI, contrato de tipo). Tudo que não é interface é **implementação**
+  — livre para mudar sem quebrar quem depende do módulo.
+- **Depth (profundidade)** — relação entre o tamanho da interface e o poder da funcionalidade que ela
+  esconde. Um módulo **profundo** expõe pouco e faz muito (alta profundidade); um módulo **raso**
+  (shallow) expõe quase tanto quanto implementa — a interface já é praticamente a implementação, e
+  não economiza nada de quem a usa entender o módulo.
+- **Seam** — o ponto de encaixe entre dois módulos, onde um comportamento pode ser trocado/isolado
+  sem tocar o outro lado. É também, por definição, a superfície de teste de um módulo (ver
+  Princípio 2).
+- **Adapter** — implementação concreta que plugga em um seam (ex.: driver de banco específico atrás
+  de uma interface de repositório). Um único adapter existente não prova que o seam é real — pode
+  ser especulação prematura (ver Princípio 3).
+- **Leverage (alavancagem)** — o ganho que uma mudança de design compra: quanto código a mais se
+  torna simples, testável ou substituível por causa dela. Alavancagem baixa é sinal de que a
+  reestruturação proposta não paga o custo de fazê-la.
+- **Locality (localidade)** — o quanto o código relevante para entender ou corrigir um comportamento
+  está fisicamente próximo (mesmo módulo/arquivo) de onde o comportamento é observado. Baixa
+  localidade é o sintoma clássico de uma função pura extraída só para testabilidade, enquanto o bug
+  real mora em como ela é chamada.
+
+## Princípios
+
+1. **Deletion test.** Para avaliar se um módulo/abstração paga o custo de existir: imagine deletá-lo
+   e inlinar seu conteúdo no(s) chamador(es). Se o resultado fica mais simples de entender (menos
+   indireção, sem perda de teste relevante), a abstração provavelmente não deveria existir como está.
+   Se o resultado fica mais confuso ou duplica lógica não trivial, a abstração se justifica. É
+   julgamento qualitativo sobre legibilidade e coesão — não uma métrica textual (ex.: contagem de
+   linhas ou de referências) que a substitua sozinha.
+2. **A interface é a superfície de teste.** Um bom teste exercita o módulo pela sua interface pública
+   — nunca por um detalhe de implementação exposto lateralmente. Se testar um módulo exige alcançar
+   além da sua interface, o seam está no lugar errado (mesma disciplina de `tdd-conventions.md` §1-2,
+   aplicada aqui à avaliação arquitetural, não ao ciclo vermelho-verde).
+3. **Um adapter é seam hipotético; dois é seam real.** Uma interface desenhada para "permitir trocar
+   a implementação no futuro" com um único adapter implementado é especulação (YAGNI) até que um
+   segundo adapter concreto exista. Dois adapters reais confirmam que o seam paga o custo de existir;
+   um só ainda não prova nada.

package/templates/skills/shared/references/conflict-resolution.md

@@ -0,0 +1,94 @@
+# Resolução de conflitos de merge
+
+Procedimento compartilhado, usado pelo `worktree-ship` (passos 2 e 10) quando `git merge` da branch
+default deixa arquivos conflitantes.
+
+## Princípio geral — Resolver por intenção
+
+Antes de aceitar ou descartar código em conflito, sempre **inspecione a intenção de cada lado** usando
+`git log` e `git show`:
+
+1. **Seu lado (current branch):** `git log --oneline -5` (últimos 5 commits) para entender o contexto
+   local, depois `git show <hash>` para ver a mudança específica que criou o conflito.
+
+2. **Lado remoto (default branch):** `git show origin/$DEFAULT_BRANCH:<filepath>` para ver a versão
+   resolvida no default, depois `git log origin/$DEFAULT_BRANCH --oneline -5` para entender a
+   intenção remota.
+
+3. **Decida pela lógica de negócio:** a mensagem de commit, o conteúdo exato e o contexto histórico
+   juntos revelam qual versão respeita melhor as regras do produto e do projeto.
+
+Isso é **resolução consciente por intenção**, não mecanicamente por padrão sintático — distingue-se
+do safety-valve de orçamento esgotado (§5.3), que é um fallback quando a inspeção honesta não
+resolve a ambiguidade.
+
+## 1 — Identificar os conflitos
+
+```bash
+git diff --name-only --diff-filter=U
+```
+
+## 2 — Lockfiles (KISS/YAGNI)
+
+Para arquivos de lock na lista (`deno.lock`, `package-lock.json`, `pnpm-lock.yaml`, `yarn.lock`,
+`Cargo.lock`, `poetry.lock`):
+
+1. `git checkout --theirs <lockfile-path>` — aceita a versão da branch default e limpa os marcadores.
+2. Execute o instalador do projeto (`deno install`, `npm install`, `pnpm install`, `cargo build`,
+   `poetry lock --no-update`) para que o próprio gerenciador regenere o lockfile reconciliado. O
+   `runtime` gravado em `.claude/vetor/config.json` diz qual usar.
+3. `git add <lockfile-path>`
+
+Nunca mescle lockfile à mão.
+
+## 3 — Conflitos aditivos em listas
+
+Quando dois workers paralelos editam **a mesma linha** de um campo que agrega itens (scripts de
+`package.json`, arrays JSON, strings concatenadas com `&&`) e **ambos os lados só adicionam**, aplique
+**união aditiva** em vez de escolher um lado:
+
+```json
+<<<<<<< HEAD
+"scripts": { "test": "jest unit && npm run lint" }
+=======
+"scripts": { "test": "jest unit && npm run e2e" }
+>>>>>>> origin/master
+```
+
+Resolução:
+
+```json
+"scripts": { "test": "jest unit && npm run lint && npm run e2e" }
+```
+
+Remova duplicatas do resultado e `git add <arquivo>`.
+
+Se um dos lados **remove** algo que o outro mantém, não é conflito aditivo — trate como código (§4).
+
+## 4 — Demais arquivos de código
+
+Localize os marcadores (`<<<<<<<`, `=======`, `>>>>>>>`), mescle logicamente as regras de negócio e
+remova os marcadores.
+
+## 5 — Validar
+
+1. Execute os testes do módulo correspondente via `module-test-map`.
+2. **Verde:** commite (`merge branch '$DEFAULT_BRANCH' and resolve conflicts`), `git push origin <branch>`.
+3. **Vermelho:** chame o `fix-loop-agent` localmente. Se as iterações estourarem sem verde, aborte o
+   merge, preserve o worktree e alerte o usuário.
+
+⚠️ **Nunca rode `git stash` (ou `git checkout` para outro branch) enquanto um merge está em conflito
+e ainda não commitado.** Qualquer comando que descarte `MERGE_HEAD` faz o `git commit` seguinte virar
+um commit comum de 1 pai — mesmo com a árvore correta, o GitHub recalcula o merge do zero (a partir
+do merge-base real) e reporta `mergeable: CONFLICTING`/`mergeStateStatus: DIRTY`, mesmo já resolvido
+localmente. Para inspecionar o conteúdo de outro branch sem alterar o estado do merge em andamento,
+use:
+
+```bash
+git show "origin/$DEFAULT_BRANCH:<path>"
+```
+
+Se `MERGE_HEAD` já foi perdido por engano, refaça o merge do zero (`git merge --abort` se ainda
+houver estado parcial recuperável, ou `git merge -s ours "origin/$DEFAULT_BRANCH" -m "merge branch
+'$DEFAULT_BRANCH' and resolve conflicts"` para registrar o segundo pai sem alterar a árvore já
+resolvida) antes de prosseguir para o passo 2 do `worktree-ship`.

package/templates/skills/shared/references/delegate-to-runtime.md

@@ -0,0 +1,239 @@
+# Delegação assistida a runtime externo (opcional, agnóstica de provedor)
+
+Referência compartilhada para economizar tokens delegando **tarefas mecânicas e de baixo
+risco** a um CLI externo de IA. Padrão: **o runtime delegado rascunha, Claude valida.**
+
+Consumida por `worktree-ship`, `fix-loop-agent`, `backlog-ideator`, `guardian` e
+`issue-coordinator`.
+
+Generaliza o antigo acoplamento a um único CLI (`agy` — Google Antigravity/Gemini CLI): a
+delegação agora suporta qualquer runtime candidato (Gemini/`agy`, OpenCode/`opencode`,
+Codex/`codex`, ou outro CLI futuro), escolhido por disponibilidade no ambiente, preferência
+configurada e, quando ambíguo, anuência explícita do usuário (issue #247).
+
+---
+
+## 1. Detecção (zero dependência obrigatória, detecção estática)
+
+Mesmo princípio já validado para MCPs em `mcp-availability.md`: **olhar se o binário existe no
+PATH**, nunca "tentar a chamada para ver se funciona" (issue #247 reaproveita esse princípio para
+CLIs externos, não só MCPs).
+
+No início da skill, detecte todos os candidatos em **uma única chamada em lote** (não uma por
+runtime, para não gastar turnos):
+
+```bash
+command -v agy 2>/dev/null; command -v opencode 2>/dev/null; command -v codex 2>/dev/null
+```
+
+Monte a lista `available` com os que retornaram um path. Runtimes candidatos conhecidos hoje:
+
+| Runtime | Binário | Invocação não-interativa | Consome stdin via pipe (pré-requisito das tarefas §4)? |
+|---------|---------|---|---|
+| Gemini (Antigravity) | `agy` | `agy -p "<prompt>"` — `-p`/`--print` roda um prompt único e imprime a resposta | **Não funciona com modo padrão** — flag `--input-format` padrão é `text`, que ignora stdin (regressão de #111). Alternativa verificada: embutir conteúdo no argumento do prompt: `agy -p "... $conteudo"` (válido para conteúdo que cabe no limite de linha de comando); para conteúdo grande, use `opencode` (stdin confirmado empiricamente) em vez de `agy`. |
+| OpenCode | `opencode` | `opencode run "<prompt>"` — mensagem como argumento posicional, não flag `-p` (`-p`/`--password` do OpenCode é autenticação HTTP, não prompt — não confundir com o `-p` do `agy`) | **Confirmado empiricamente**: `echo "MARCADOR-XYZ-123" \| opencode run --model <free> "Repita exatamente o texto que você recebeu via stdin"` devolveu `MARCADOR-XYZ-123` — o conteúdo do pipe chega ao modelo mesmo sem flag dedicada |
+| Codex | `codex` | `codex exec "<prompt>"` (sintaxe **não verificada neste ambiente** — binário não estava instalado nem MCP de documentação disponível na sessão que escreveu esta referência) | **Não verificado** |
+
+**Regra:** um runtime com consumo de stdin **não verificado** nunca deve ser usado para as tarefas
+de §4 (todas dependem do pipe `<producer> | $DELEGATE "..."` carregar o conteúdo real). Um CLI que
+ignora silenciosamente o stdin ainda retorna exit 0 e uma resposta plausível — não é uma falha que
+o guardrail do §3 detecta, é uma alucinação sobre um input que o runtime nunca recebeu. Antes do
+primeiro uso de um runtime novo em produção: rode o teste de eco acima (`echo "<marcador>" | <cli> "repita o marcador"`) e só marque a coluna acima como confirmada se o marcador voltar exato. Enquanto
+não confirmado, trate esse runtime como **não viável para §4** (mesmo que detectado no PATH) — se
+for o único candidato disponível, siga inline; use o CLI apenas via seu mecanismo documentado de
+anexo de arquivo (ex.: `-f/--file` do `opencode`) se a tarefa permitir.
+
+**Preferência configurada:** leia `.claude/vetor/config.json` → bloco opcional `delegation`:
+
+```json
+{
+  "delegation": { "preferredRuntime": "opencode" }
+}
+```
+
+(Exemplo mostra `opencode` como preferência recomendada: é o único com suporte comprovado a stdin
+em todas as tarefas de §4. Se preferir `agy`, consulte a linha da tabela do §1 para limitações e alternativas.)
+
+Ausência do bloco `delegation` (ou do `config.json` inteiro) nunca é erro — mesmo contrato do
+bloco `knowledge` (ver `skills/vetor/SKILL.md`).
+
+## 2. Algoritmo de seleção
+
+Com `available` (lista detectada) e `preferred` (config, pode ser `null`):
+
+1. **`available` vazio** → siga **inline**. Nunca falhe nem peça instalação — a delegação é
+   puramente opcional.
+2. **`preferred` configurado:**
+   - Se `preferred` está em `available` → delegue para `preferred`.
+   - Se `preferred` **não** está em `available` → siga **inline**. Nunca substitua
+     silenciosamente por outro candidato disponível: o usuário consentiu com um runtime
+     específico, não com "qualquer um" (issue #247 — "nenhum runtime é assumido como
+     padrão/preferencial sem configuração ou anuência").
+3. **Sem `preferred`, `available` com exatamente 1 candidato** → delegue para ele. Não há
+   ambiguidade entre runtimes a resolver, então não é necessário perguntar (a anuência explícita
+   só é exigida "quando houver mais de um runtime viável e nenhuma preferência registrada").
+4. **Sem `preferred`, `available` com 2+ candidatos (ambíguo):**
+   - **Sessão interativa** (há interlocutor, ex.: `issue-coordinator` fora de `--headless`):
+     pergunte ao usuário qual runtime usar (mecanismo de seleção interativa da skill, quando
+     disponível). Ofereça salvar a escolha em `delegation.preferredRuntime` para não perguntar de
+     novo.
+   - **Sessão headless** (`fix-loop-agent`, `issue-worker`, `guardian`, `backlog-ideator` sem
+     interlocutor): **critério de desempate documentado é sempre inline** — nunca escolha
+     silenciosamente entre candidatos não consentidos. Isso é intencional mesmo que sacrifique
+     uma oportunidade de economia de tokens: é o preço de não assumir uma preferência que
+     ninguém configurou.
+
+Lógica de referência (implementada e testada em `scripts/lib/delegation-runtime.ts`,
+`scripts/tests/delegation-runtime_test.ts`):
+
+```ts
+selectDelegationRuntime({ available, preferred, interactive });
+// => { action: "inline" | "delegate" | "ask", runtime?, reason }
+```
+
+Skills que rodam em Deno podem importar a função diretamente; skills descritas só em markdown
+devem seguir o mesmo algoritmo em prosa (passos 1-4 acima).
+
+Antes de rodar o comando de delegação escolhido, **sempre imprima um log explícito no console**:
+`echo "[Vetor:Delegação] Delegando tarefa a <runtime>: <breve descrição>"`.
+
+**Nota — cache próprio de alguns runtimes fora do projeto:** o `agy`, por exemplo, pode persistir
+uma cópia do rascunho em `~/.gemini/antigravity-cli/brain/<uuid>/...` (fora do repositório e do
+controle de versão). Isso é comportamento do CLI externo, não do Vetor — o Vetor consome apenas a
+saída via stdout (pipe) e não depende nem gerencia esse cache. Não é necessário limpar esses
+arquivos manualmente.
+
+---
+
+## 3. Qualquer falha do CLI delegado = fallback inline imediato, sem retry
+
+Duas categorias distintas de falha, **mesma resposta para ambas**:
+
+### 3.a Negação de permissão pelo classificador de auto-mode
+
+Mesmo com o binário presente, a chamada pode ser **negada em runtime** pela camada de
+permissão/classificador de auto-mode do Claude Code — motivo típico é **exfiltração de dados**
+(envio de diff ou conteúdo de código confidencial para CLI externo não estabelecido como
+confiável).
+
+**Esta não é uma falha transiente de rede; é uma política de segurança.** Não deve ser
+retentada.
+
+### 3.b Falha genérica do CLI (encoding, crash, timeout, exit code ≠ 0)
+
+Já observado em produção: uma chamada ao `agy` pode falhar com um erro genérico de encoding
+(`proto: field ... contains invalid UTF-8`) ao processar texto em português com acentuação. Isso
+não é exclusivo do Gemini — qualquer CLI externo pode falhar de formas imprevisíveis
+(encoding, crash, timeout, versão incompatível).
+
+**Regra única para 3.a e 3.b:** qualquer falha do CLI de delegação (exit code ≠ 0, exceção,
+negação de permissão, saída vazia/corrompida) — não só ausência do binário — é motivo de
+**fallback inline imediato**:
+
+1. **Não retente** — nem o mesmo runtime, nem trocar para outro candidato disponível. A
+   simplicidade do "sem retry" evita loops de tentativa em CLIs com falhas erráticas.
+2. **Use o fallback inline imediatamente** — monte a descrição, o resumo ou o rascunho
+   manualmente usando o template padrão fornecido na skill (ex.: template de PR padrão em §6 do
+   `worktree-ship`).
+3. **Prossiga sem atraso** — evita I/O desnecessário e mensagens de erro em sessões com
+   auto-mode restritivo.
+
+A delegação é **opcional e confortável para falhar**; a tarefa sempre tem um caminho inline
+viável.
+
+---
+
+## 4. Tarefas delegáveis (baixo risco, alto volume)
+
+Mesmo contrato de saída independente do runtime escolhido: substitua `$DELEGATE` pelo comando de
+invocação do runtime selecionado no passo 2 (tabela do §1).
+
+### 4.1. Resumir logs de CI / build
+Antes de diagnosticar uma falha, condense o log bruto para não despejar centenas de
+linhas no contexto:
+
+```bash
+gh run view <run-id> --log-failed \
+  | $DELEGATE "Resuma a causa raiz das falhas neste log de CI em até 15 linhas, citando arquivo:linha quando houver. Não invente; se não houver causa clara, diga isso."
+```
+
+O Claude lê o resumo e **decide o fix**. Usado por `worktree-ship` (monitorar CI) e
+`fix-loop-agent` (avaliar resultado dos testes).
+
+### 4.2. Rascunhar texto de issues
+Em `backlog-ideator`, gere a primeira versão do corpo da issue:
+
+```bash
+$DELEGATE "Escreva o corpo de uma issue GitHub (descrição + critério de aceite verificável) para: <tema>. Conciso, em PT-BR."
+```
+
+O Claude **revisa e ancora** o rascunho na documentação do projeto antes de criar via
+`gh issue create`.
+
+### 4.3. Rascunhar mensagens de commit e relatórios
+Mensagens de commit (`fix-loop-agent`, `worktree-ship`) e o relatório do `guardian`:
+
+```bash
+git diff --staged | $DELEGATE "Escreva uma mensagem de commit conventional commits (uma linha de subject + corpo opcional) para este diff."
+```
+
+O Claude valida o rascunho antes de usar.
+
+### 4.4. Rascunhar corpo/descrição de Pull Request
+Em `worktree-ship`, gere a primeira versão da descrição do Pull Request com base no diff acumulado da branch em relação à branch default do projeto:
+
+```bash
+git diff "$DEFAULT_BRANCH"...HEAD | $DELEGATE "Escreva uma descrição concisa e estruturada de Pull Request para este diff. Use markdown em PT-BR com seções: 'O que mudou' (tópicos curtos) e 'Como testar'."
+```
+
+O Claude **revisa e formata** a descrição antes de passá-la ao comando `gh pr create --body`.
+
+### 4.5. Análise de afinidade e agrupamento de issues
+Em `issue-coordinator`, delegue a varredura e o agrupamento preliminar de issues em lote:
+
+```bash
+gh issue list --label <label> --state open --json number,title,labels,body \
+  | $DELEGATE "Analise estas issues em formato JSON e sugira um agrupamento de afinidade. Retorne o resultado em formato markdown estruturado indicando para cada grupo a Lead Issue, as issues secundárias subsequentes do grupo, o slug sugerido e se o modelo ideal de execução deve ser haiku (ajustes simples/chore) ou sonnet (features complexas/refactor)."
+```
+
+O Claude **valida a afinidade**, resolve eventuais erros do rascunho e constrói a tabela final de dispatch.
+
+### 4.6. Geração de Changelog de Sessão
+No `issue-coordinator`, delegue a criação do changelog consolidado a partir do histórico de commits da sessão. **Sempre limite o range** (a regra de 100 linhas de `planning-conventions.md` §1.1 vale para histórico de git também) — `origin/main...HEAD` sozinho não é suficiente como limite: uma branch de longa duração e nunca rebaseada pode produzir um range enorme. Use um cap numérico fixo além do range:
+
+```bash
+git log origin/main...HEAD --oneline -200 | $DELEGATE "Com base nestes commits, crie um Changelog em markdown em PT-BR organizado pelas seções: Melhorias (features), Correções (fixes) e Outros."
+```
+
+O Claude **valida o texto**, refina o formato e salva no arquivo `.claude/vetor/CHANGELOG.md`.
+
+### 4.7. Validação de Migrations
+No `guardian`, envie o dump de arquivos de migrations para verificar a integridade da sequência temporal:
+
+```bash
+ls "$MIGRATIONS_DIR" | $DELEGATE "Examine esta listagem de arquivos de migrations e detecte se existem timestamps/versões fora de ordem, buracos na sequência cronológica de numeração ou desvios do padrão de nomenclatura V<N>__<descrição>.sql."
+```
+
+O Claude **avalia os findings apontados** e os compila no relatório da auditoria.
+
+### 4.8. Resumo Conceitual da Arquitetura
+No `backlog-ideator`, envie arquivos longos de documentação para obter uma síntese executiva de apoio à ideação:
+
+```bash
+cat ARCHITECTURE.md docs/*.md | $DELEGATE "Gere um resumo arquitetural consolidado deste projeto contendo os principais padrões de design e módulos, para que um agente possa compreender a estrutura do sistema rapidamente."
+```
+
+O Claude **usa este sumário como âncora conceitual** sem precisar ler dezenas de arquivos markdown na íntegra.
+
+---
+
+## 5. Guardrail (invariante — não negociável, independe do runtime)
+
+**NUNCA delegue a nenhum runtime externo:**
+- Aplicação de correções de código / geração de diffs (`fix-loop-agent`)
+- Resolução de conflitos de merge
+- Decisão de fazer (ou não) merge
+
+Essas etapas ficam **sempre** com o Claude. Toda saída delegada é tratada como rascunho
+não confiável e **validada pelo Claude antes de qualquer escrita** (commit, push, criação
+de PR ou merge). Em caso de dúvida sobre a qualidade do rascunho, descarte-o e faça inline.