@tavaressan/vetor 0.1.0 → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vitor Tavares Chaves
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/lib/commands/install.js

@@ -3,6 +3,7 @@
 const { detectEngines: defaultDetectEngines } = require('../installer/detector.js');
 const { runInstallPrompts: defaultRunInstallPrompts } = require('../installer/prompts.js');
 const { installFiles: defaultInstallFiles } = require('../installer/writer.js');
+const { printBanner: defaultPrintBanner } = require('../banner.js');
 
 /**
  * Comando `install`: detecta engines suportadas no projeto-alvo (ver `ENGINES` em
@@ -16,16 +17,19 @@ const { installFiles: defaultInstallFiles } = require('../installer/writer.js');
  * por arquivo para updates seguros mais tarde. Engine sem destino de arquivo confirmado
  * (`enginesSkipped`) é reportada ao usuário em vez de silenciosamente ignorada.
  *
- * `detectEngines`/`runInstallPrompts`/`installFiles`/`input`/`output` são injetáveis para
- * testes.
+ * `detectEngines`/`runInstallPrompts`/`installFiles`/`printBanner`/`input`/`output` são
+ * injetáveis para testes.
  */
 async function install(cwd = process.cwd(), options = {}) {
   const detectEngines = options.detectEngines ?? defaultDetectEngines;
   const runInstallPrompts = options.runInstallPrompts ?? defaultRunInstallPrompts;
   const installFiles = options.installFiles ?? defaultInstallFiles;
+  const printBanner = options.printBanner ?? defaultPrintBanner;
   const input = options.input ?? process.stdin;
   const output = options.output ?? process.stdout;
 
+  printBanner();
+
   const engines = detectEngines(cwd);
   const detectedNames = engines.filter((engine) => engine.detected).map((engine) => engine.name);
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tavaressan/vetor",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Instalador do Vetor: automação de workflow de desenvolvimento (skills para Claude Code, Codex e outras engines).",
   "bin": {
     "vetor": "bin/vetor.js"
@@ -11,7 +11,8 @@
   "files": [
     "bin/",
     "lib/",
-    "templates/"
+    "templates/",
+    "LICENSE"
   ],
   "keywords": [
     "claude-code",

package/templates/opencode/agent/issue-coordinator.md

@@ -263,7 +263,7 @@ do sugerido aqui se estiver `degraded` no momento do dispatch.
 #### Pergunta sobre teto de workers simultâneos
 
 Antes de pedir aprovação:
-1. Calcule `N_rec = min(número de grupos formados, maxConcurrentWorkers de .claude/vetor/config.json
+1. Calcule `N_rec = min(largura da maior onda, maxConcurrentWorkers de .claude/vetor/config.json
    — senão 5)`. Acima de ~8 workers, sinalize que custo agregado e ruído de monitoramento crescem
    mais rápido que o ganho de paralelismo — é recomendação, não limite; a decisão é do usuário.
 2. **Em `--headless`: não pergunte.** Adote `N = N_rec`, registre no relatório final (Fase 7) o
@@ -498,7 +498,9 @@ ele precisa ser autossuficiente. Acrescente ao formato acima:
   `issue-worker` no status file, sem checagem automática — issue #156). Ao atingir a 5ª iteração sem
   verde, o worker deve registrar `BLOCKED_WAITING` ou `FAILED_MAX_ITERATIONS`, nunca decidir sozinho
   continuar.
-- Timeout global de 90 minutos para o coordenador (este sim, hard cap real)
+- Timeout global de 90 minutos para o coordenador (este sim, hard cap real) — configurável via
+  `maxSessionMinutes` em `.claude/vetor/config.json` (default 90). O teto restringe novos dispatches e
+  o início de novas ondas; ships e workers ativos podem concluir.
 - Iterações em `BLOCKED_WAITING` não contam contra o orçamento de 5
 
 O número de processos simultâneos **não é um hard cap**: é o valor `N` decidido pelo usuário na

package/templates/opencode/scripts/vetor-status.sh

@@ -1,18 +1,29 @@
 #!/usr/bin/env bash
 # Tabela de monitoramento do issue-coordinator, construída de fontes externas
-# (status files + git worktree list) — não de estado em memória. Rodar no root.
+# (status files + git worktree list) — não de estado em memória. Pode rodar no root
+# ou de dentro de qualquer worktree (issue #339).
 #
 # Uso: vetor-status.sh
 # Saída: tabela markdown com uma linha por status file em .claude/vetor/status/.
 #        Worktree correspondente removido manualmente -> "cancelled (worktree removed)".
+#        Worktree recém-despachado -> "aguardando worktree" (issue #347).
 #        Worktree sem status file -> ⚠️ WARNING (possível falha anômala, issue #72).
 
 set -uo pipefail
 
-STATUS_DIR=".claude/vetor/status"
+# Resolve o root do repositório principal (suporta execução de dentro de worktrees — issue #339)
+REPO_ROOT=$(git worktree list --porcelain 2>/dev/null | head -1 | sed 's/^worktree //')
+if [ -z "$REPO_ROOT" ]; then
+  REPO_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || echo ".")
+fi
+
+STATUS_DIR="${REPO_ROOT}/.claude/vetor/status"
 
 # Branch principal (main worktree) — excluída da lista de workers ativos.
-default_branch=$(git symbolic-ref --short HEAD 2>/dev/null || echo "")
+default_branch=$(git worktree list --porcelain 2>/dev/null | sed -n '3s#^branch refs/heads/##p')
+if [ -z "$default_branch" ]; then
+  default_branch=$(git symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null | sed 's#^origin/##' || git symbolic-ref --short HEAD 2>/dev/null || echo "")
+fi
 
 # Branches com worktree ativo (workers), sanitizadas com a mesma convenção dos status files (/ -> -).
 # Exclui a branch principal do repositório.
@@ -56,7 +67,13 @@ for f in "$STATUS_DIR"/*.md; do
   if printf '%s\n' "$active" | grep -qx "$name"; then
     wt="ativo"
   else
-    wt="cancelled (worktree removed)"
+    # Issue #347: status recém-criado pelo coordinator antes do harness criar o worktree
+    iter_n=$(printf '%s' "$iter" | sed -n 's#^\([0-9][0-9]*\)/.*#\1#p')
+    if [ "$status" = "RUNNING" ] && { [ -z "$iter_n" ] || [ "$iter_n" -le 1 ]; }; then
+      wt="aguardando worktree"
+    else
+      wt="cancelled (worktree removed)"
+    fi
   fi
   seen_branches="${seen_branches}${name}
 "

package/templates/skills/backlog-ideator/SKILL.md

@@ -99,8 +99,9 @@ Qualquer evidência ao vivo é âncora válida — não se limita a Sentry/Datad
 uma dessas durante a sessão (não precisa buscar ativamente), use-a para propor issue `fix` ou
 `chore`. **Para issues `fix`, é obrigatório citar o comando/fonte exato que reproduz o problema.**
 
-Se houver MCP de observabilidade disponível (`mcp__sentry__*`, `mcp__datadog__*` — ver
-`mcp-availability.md`), use-o para obter os erros não resolvidos mais frequentes em produção e
+Se houver MCP de observabilidade disponível (standalone `mcp__<server>__*` ou empacotado em
+plugin `mcp__plugin_<plugin>_<server>__*` para sentry ou datadog — ver `mcp-availability.md` e
+`scripts/lib/mcp.ts`), use-o para obter os erros não resolvidos mais frequentes em produção e
 ancore issues `fix` neles, incluindo stacktraces. Sem MCP, prossiga normalmente.
 
 ### 2.b — Investigação estruturada (grilling)

package/templates/skills/design/SKILL.md

@@ -67,9 +67,10 @@ uma tela/fluxo de UI compila e roda. Também pode ser invocado manualmente com
   estética/tipográfica via skill nativa `frontend-design`, aplicada **antes** de escrever o código.
   O Loop é complementar e roda **depois**: verifica o que foi construído, não decide como desenhar.
 - `../shared/references/mcp-availability.md` — mecanismo de checagem de
-  disponibilidade (procurar `mcp__<server>__` na lista de ferramentas). Servidores relevantes aqui:
-  browser (`mcp__chrome-devtools__`, `mcp__playwright__`) para os passos 4-6 e 9 do Loop, Context7
-  para qualquer comportamento de framework/lib consultado durante o Fix (Loop, passo 8).
+  disponibilidade (procurar `mcp__<server>__` ou `mcp__plugin_<plugin>_<server>__` na lista de
+  ferramentas, conforme `scripts/lib/mcp.ts` — issue #336). Servidores relevantes aqui: browser
+  (`chrome-devtools`, `playwright`) para os passos 4-6 e 9 do Loop, Context7 para qualquer
+  comportamento de framework/lib consultado durante o Fix (Loop, passo 8).
 - `scripts/lib/design-mode.ts` — lógica de detecção/renderização do Setup (pura, testada em
   `scripts/tests/design-mode_test.ts`).
 - `scripts/detect-design-mode.ts` — CLI que orquestra a escrita em disco do Setup a partir da lib
@@ -427,8 +428,9 @@ lista não está vazia — declare exatamente o que foi e o que não foi confirm
 ### Sem MCP de browser (degradação graciosa)
 
 Este loop nunca falha nem trava por falta de MCP de browser, e nunca finge que a inspeção ocorreu.
-Quando nenhum servidor de browser (`mcp__chrome-devtools__*`, `mcp__playwright__*`) está na lista de
-ferramentas da sessão:
+Quando nenhum servidor de browser (`chrome-devtools`, `playwright` — via prefixo standalone
+`mcp__<server>__*` ou empacotado em plugin `mcp__plugin_*_<server>__*`, conforme `scripts/lib/mcp.ts`)
+está na lista de ferramentas da sessão:
 
 1. Os passos 4, 5, 6 e a parte visual do 7/9 usam `reportLoopStep(<step>, <ferramentas>)` de
    `scripts/lib/design-loop-mcp.ts`, que retorna `verdict: "unverified"` com uma `limitation`

package/templates/skills/guardian/SKILL.md

@@ -179,8 +179,9 @@ gh pr view <N> --json mergeable,mergeStateStatus
 
 ### 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):
+Verifique disponibilidade de um MCP de banco (prefixo standalone `mcp__<db>__*` ou empacotado em
+plugin `mcp__plugin_<plugin>_<db>__*`, conforme `scripts/lib/mcp.ts` — 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.
@@ -199,8 +200,9 @@ Se o stack for identificável (`mcp__planetscale__*`, `mcp__postgres__*`, `mcp__
 
 ### 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.
+Verifique disponibilidade de um MCP Docker (`mcp__docker__*` ou `mcp__plugin_<plugin>_docker__*`,
+diretas ou diferidas — sem casar gateways como `mcp__MCP_DOCKER__`, conforme `scripts/lib/mcp.ts`).
+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`).

package/templates/skills/issue-coordinator/SKILL.md

@@ -51,10 +51,12 @@ Os comandos de teste vêm de `.claude/vetor/module-test-map.md` ou, na ausência
 auto-detecção a partir do CI — cada primitivo já consome essa referência, sempre resolvendo o
 arquivo a partir do root do repositório (`vetor-checks.sh repo-root`), nunca do `cwd` do worktree
 (issue #160), pois arquivos ignorados pelo `.gitignore` do projeto-alvo (ex.: uma entrada
-`.claude/`) não são materializados em worktrees linkados. Se `git check-ignore -q .claude` indicar
-que `.claude/` está ignorado no projeto-alvo, você pode opcionalmente injetar os comandos de teste
-já resolvidos diretamente no prompt de cada worker despachado, como reforço redundante — a fonte de
-verdade continua sendo a resolução via root em `project-conventions.md`.
+`.claude/`) ou arquivos untracked (não versionados) não são materializados em worktrees linkados.
+Se `git check-ignore -q .claude` indicar que `.claude/` está ignorado no projeto-alvo, ou se
+`git ls-files --error-unmatch .claude/vetor/module-test-map.md` indicar que o arquivo não está
+rastreado no git (issue #327), injete os comandos de teste já resolvidos diretamente no prompt de
+cada worker despachado, como reforço redundante — a fonte de verdade continua sendo a resolução
+via root em `project-conventions.md`.
 Regras de economia de tokens e delegação a um runtime externo disponível (Gemini/OpenCode/Codex):
 `../shared/references/planning-conventions.md` e
 `../shared/references/delegate-to-runtime.md`.
@@ -285,13 +287,15 @@ origens.
 Cada subagente paralelo é uma instância Claude completa, sem contexto compartilhado — é o maior
 driver de custo agregado do coordinator.
 
-1. **Recomendação** `N_rec` = `min(nº de grupos da Fase 1, maxConcurrentWorkers de
-   .claude/vetor/config.json se existir — senão 5)`. Acima de ~8 workers, custo agregado e ruído de
-   monitoramento tendem a crescer mais rápido que o ganho de paralelismo: se `N_rec` > 8, sinalize
-   isso na pergunta. É recomendação, não limite — a decisão é do usuário.
+1. **Recomendação** `N_rec` = `min(largura da maior onda, maxConcurrentWorkers de
+   .claude/vetor/config.json se existir — senão 5)`. A largura da maior onda é o número máximo de
+   grupos que podem rodar em paralelo dentro de uma mesma onda (grupos de ondas distintas nunca rodam
+   juntos — Fase 4). Acima de ~8 workers, custo agregado e ruído de monitoramento tendem a crescer
+   mais rápido que o ganho de paralelismo: se `N_rec` > 8, sinalize isso na pergunta. É
+   recomendação, não limite — a decisão é do usuário.
 2. **Em `--headless`:** adote `N = N_rec` sem perguntar e registre no relatório qual valor foi usado
    e como foi calculado. Fora do headless, **pergunte via `AskUserQuestion`** (uma única vez por sessão):
-   - `"<N_rec> (Recomendado)"` — justifique em 1 linha (nº de grupos, custo por worker, alerta se > 8)
+   - `"<N_rec> (Recomendado)"` — justifique em 1 linha (largura da onda, custo por worker, alerta se > 8)
    - `"1 — serializado"` — mais lento, mais previsível, menor custo
    - `"<maxConcurrentWorkers de config.json>"` — só se existir e for diferente de `N_rec`
    - O usuário pode responder valor customizado ("Other"), **inclusive acima de 8** — respeite-o.
@@ -303,7 +307,9 @@ driver de custo agregado do coordinator.
 
 **Em `--headless`: pule esta seção** — inclua o plano no relatório final (Fase 7) e siga para a Fase 3.
 
-- **No Claude Code:** apresente o plano e conclua com `ExitPlanMode`.
+- **No Claude Code:** se a sessão já estiver em plan mode, apresente o plano e conclua com
+  `ExitPlanMode`. Se a sessão **não** estiver em plan mode, aprove via `AskUserQuestion` (ou chame
+  `EnterPlanMode` antes).
 - **No Antigravity/Gemini:** gere/atualize `implementation_plan.md` com `request_feedback: true` e
   `user_facing: true`, e aguarde `request_feedback: false` ou "Proceed".
 - Sem nenhum dos dois: exiba o plano no chat e aguarde resposta afirmativa explícita.
@@ -336,6 +342,12 @@ pela branch) ou pelo retorno do `Agent()`.
 - Dentro da onda corrente: quando um worker ativo atingir `GREEN`, `FAILED_MAX_ITERATIONS` ou for
   cancelado, despache o próximo `QUEUED` da mesma onda, mantendo os ativos no teto.
 - O teto é contabilidade do coordinator, não bloqueio de plataforma: respeite-o a cada ciclo.
+- **Checagem de timeout da sessão.** Antes de despachar um novo grupo `QUEUED` ou iniciar uma nova
+  onda (`O_{i+1}`), verifique se o timeout global (default 90 minutos, ou `maxSessionMinutes` em
+  `.claude/vetor/config.json`) foi atingido considerando apenas tempo ativo de coordenação (excluindo
+  esperas por decisão humana via `AskUserQuestion` — issue #343). Ao atingir o teto: não despache novos
+  grupos nem novas ondas; permita que workers ativos terminem suas iterações e que grupos `GREEN` já
+  autorizados realizem ship normalmente.
 - **Transição de onda.** Só inicie o dispatch de `O_{i+1}` depois que:
   1. Todos os grupos de `O_i` **que foram efetivamente despachados** tiverem chegado a `GREEN` e
      passado pela Fase 6 (merge) — um grupo de `O_i` em `FAILED_MAX_ITERATIONS` ou `BLOCKED_WAITING`
@@ -377,6 +389,8 @@ pulando dispatch duplicado`) e **pule** o dispatch desse grupo.
 **Antes de invocar `Agent()`, o coordenador DEVE criar o status file** (path da Fase 3) com
 `Status: RUNNING` — o sandbox de isolamento pode impedir o worker de criar arquivo fora do worktree.
 Exemplo: `echo -e "# Agent Status - <branch>\nStatus: RUNNING\nIteration: 1/5 (Issue #<M>)" > <path>`.
+Enquanto o harness inicializa o worktree, `vetor-status.sh` classifica o grupo como `aguardando worktree`
+(e não como `cancelled`, issue #347).
 
 ```javascript
 Agent({
@@ -443,6 +457,11 @@ worker precisar de MCP, adicione-o à lista.
    é controlado pelo harness, não pelo coordinator — não há como forçar a criação diretamente a
    partir de `origin/$DEFAULT_BRANCH`), então essa instrução no prompt do worker é a rede de
    segurança que não depende do root ter avançado a tempo.
+6. **Comandos de teste pré-resolvidos (se module-test-map untracked/ignorado):** Se `git check-ignore -q .claude`
+   indicar que `.claude/` está ignorado ou se `! git ls-files --error-unmatch .claude/vetor/module-test-map.md >/dev/null 2>&1`
+   indicar que o mapa de testes não está commitado (issue #327), injete explicitamente os comandos de
+   teste resolvidos para os módulos da issue no prompt do worker, evitando que ele fique sem referências
+   de teste no worktree.
 
 Ao concluir todas as issues com sucesso, o worker marca `GREEN`. Se falhar em alguma, para e marca
 `FAILED_MAX_ITERATIONS` especificando qual issue falhou.
@@ -456,8 +475,10 @@ bash "$SKILL_DIR/../../scripts/vetor-status.sh"
 ```
 
 O script lê `.claude/vetor/status/*.md`, cruza com `git worktree list` (worktree removido
-manualmente → `cancelled (worktree removed)`; não recrie) e com `gh pr list --state all`, e imprime
-a tabela. Reproduza-a no chat acrescentando os grupos `QUEUED`, e adicione a coluna `Onda` (Fase 1)
+manualmente → `cancelled (worktree removed)`; recém-despachado → `aguardando worktree`, issue #347)
+e com `gh pr list --state all`, e imprime a tabela. O script resolve o root do repositório
+automaticamente, podendo rodar no root ou dentro de qualquer worktree sem falso alarme (issue #339).
+Reproduza-a no chat acrescentando os grupos `QUEUED`, e adicione a coluna `Onda` (Fase 1)
 a cada linha — o script não conhece o DAG, então essa coluna vem do plano da Fase 2 mantido em
 memória pelo coordinator. Grupos `QUEUED` de uma onda posterior aparecem como
 `QUEUED (aguardando O_i)` para deixar explícita a razão de não terem sido despachados mesmo havendo
@@ -537,7 +558,7 @@ bash "$SKILL_DIR/../../scripts/vetor-checks.sh" sync-root
 `sync-root` só troca de branch se a atual estiver limpa e já mesclada em `origin/<default>`. Se
 imprimir `AVISO`, **não force**: reporte a pendência no relatório em vez de descartar trabalho.
 
-Após todos os agentes terminarem (ou timeout de 90 minutos):
+Após todos os agentes terminarem (ou atingido o timeout de 90 minutos / `maxSessionMinutes`):
 
 ```
 ## Coordinator Report
@@ -552,6 +573,18 @@ Após todos os agentes terminarem (ou timeout de 90 minutos):
 Resumo: <N> merged, <M> falharam, <K> aguardando review, <J> aguardando Spec.
 ```
 
+**Checkpoint de fechamento de onda (issue #246).** Após montar o Coordinator Report acima, confirme
+que a lista de grupos originalmente planejados na Fase 2 bate 1:1 com os resultados reportados —
+**nenhum grupo do plano aprovado deve ficar sem uma linha de resultado**. Resultados válidos
+dependem do modo:
+- **Interativo**: `Merged`, `CI failed`, `FAILED_MAX_ITERATIONS`, `Review required`, `BLOCKED_WAITING`, `SKIPPED (aguardando
+  Spec)`. Se houver discrepância (grupo do plano não aparece acima), reporte-o como "não
+  despachado" e pergunte ao usuário via `AskUserQuestion` se deve despachar agora.
+- **`--headless`**: `Merged`, `CI failed`, `FAILED_MAX_ITERATIONS`, `Review required`, `BLOCKED_WAITING`, `SKIPPED
+  (aguardando Spec)`, ou `GREEN (pronto para ship)` — este último status aparece para grupos que
+  atingiram verde em modo headless (sem merge nessa fase). Se houver discrepância, apenas reporte o
+  grupo como "não despachado" no campo de observações; não pergunte nem redespache.
+
 **Em `--headless`, o relatório é a única saída da execução** — acrescente:
 - O plano de dispatch da Fase 2 (apenas registrado, não aprovado).
 - Para cada issue `não-trivial` sem Spec associada (gate de Spec/design, Fase 2): sinalizada, nunca
@@ -570,7 +603,13 @@ Resumo: <N> merged, <M> falharam, <K> aguardando review, <J> aguardando Spec.
   deve registrar `BLOCKED_WAITING` (não decidir sozinho continuar) e escalar ao coordinator via os
   blocos `Blocked on`/`Options`/`Recommendation` do status file, em vez de estourar para 6+.
 - **worktree-ship:** máximo 3 tentativas de fix de CI
-- **Coordinator:** timeout global de 90 minutos (este sim, hard cap real)
+- **Coordinator:** timeout global de 90 minutos (este sim, hard cap real) — configurável via
+  `maxSessionMinutes` em `.claude/vetor/config.json` (default 90). O teto restringe **novos
+  dispatches e o início de novas ondas**: ao atingir o timeout, nenhum novo grupo é despachado e
+  nenhuma nova onda é iniciada. Porém, grupos ativos podem concluir sua iteração corrente e ships de
+  grupos já em `GREEN` (ou já autorizados pelo usuário) podem prosseguir até a conclusão (issue #343).
+  Para a contagem do timeout, considere apenas o tempo ativo de coordenação, excluindo períodos de
+  espera por decisões humanas (`AskUserQuestion` ou aprovação de plano).
 - Agentes em `BLOCKED_WAITING` não consomem iterações do fix-loop
 - `vetor-status.sh` destaca com `⚠️` na tabela qualquer `Iteration: N/5` com `N` acima do orçamento —
   sinal de que o agente não escalou como deveria; trate como candidato a redispatch/intervenção.

package/templates/skills/retro/SKILL.md

@@ -104,8 +104,9 @@ Se encontrar equivalente, não proponha criar de novo — anote como "já rastre
 
 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).
+§2.2 — plan mode nativo no Claude Code via `ExitPlanMode` se a sessão já estiver em plan mode, ou
+`AskUserQuestion` caso não esteja, `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.
 

package/templates/skills/shared/references/mcp-availability.md

@@ -6,23 +6,38 @@ pule) a checagem.
 
 ## O mecanismo correto
 
-Ferramentas de servidores MCP aparecem no seu namespace de ferramentas com o prefixo
-`mcp__<server>__<tool>` (ex.: `mcp__sentry__list_issues`) — diretas na
-lista de ferramentas disponíveis, ou listadas por nome entre as ferramentas diferidas (que você
-carrega via `ToolSearch` antes de chamar).
+Ferramentas de servidores MCP aparecem no seu namespace de ferramentas como
+`mcp__<segmento-de-servidor>__<tool>` — diretas na lista de ferramentas disponíveis, ou listadas
+por nome entre as ferramentas diferidas (que você carrega via `ToolSearch` antes de chamar). O
+**segmento de servidor** é o trecho entre `mcp__` e o próximo `__`, e tem duas formas:
 
-**Verificar disponibilidade é simplesmente olhar se algum nome com esse prefixo existe** — não é
-necessário rodar comando, nem tentar a chamada MCP "para ver se funciona":
+- **standalone** (registrado direto no projeto/usuário): `<server>` — ex.:
+  `mcp__sentry__list_issues` (segmento `sentry`);
+- **empacotado num plugin** (ex.: o próprio vetor): `plugin_<plugin>_<server>` — ex.:
+  `mcp__plugin_vetor_context7__query-docs` (segmento `plugin_vetor_context7`).
+
+**Verificar disponibilidade é simplesmente olhar se existe uma ferramenta cujo segmento de servidor
+casa com o servidor relevante** — não é necessário rodar comando, nem tentar a chamada MCP "para ver
+se funciona":
 
 1. Procure na sua lista de ferramentas (diretas + diferidas, listadas em `<system-reminder>` no
-   início da conversa e sempre que atualizadas) por qualquer nome começando com `mcp__<server>__`,
-   onde `<server>` é o servidor relevante para a tarefa (sentry/observabilidade,
-   banco de dados).
+   início da conversa e sempre que atualizadas) por qualquer nome `mcp__…` e extraia o segmento de
+   servidor. O servidor `<server>` (ex.: `context7`, `sentry`, `docker`, `chrome-devtools`) casa
+   quando o segmento **inteiro** é `<server>` ou começa com `plugin_` e termina com `_<server>`
+   (`plugin_<plugin>_<server>`), sem distinguir maiúsculas de minúsculas. **Nunca por substring
+   solta:** `docker` **não** casa `mcp__MCP_DOCKER__*` (segmento `MCP_DOCKER`, o gateway de MCPs do
+   Docker é outro servidor).
 2. **Se existir:** o MCP está disponível. Se a ferramenta estiver na lista de diferidas, carregue-a
    primeiro com `ToolSearch({query: "select:<tool_name>"})` antes de chamá-la.
-3. **Se não existir nenhum nome com esse prefixo:** o MCP não está configurado nesta sessão — vá
+3. **Se não existir nenhum segmento correspondente:** o MCP não está configurado nesta sessão — vá
    direto para o fallback documentado na skill (CLI `gh`, query SQL manual, etc.). Não gaste uma
    chamada tentando invocar uma ferramenta MCP inexistente só para descobrir que falha.
+4. **Quando houver mais de um segmento correspondente para o mesmo serviço**, use esta ordem de
+   preferência (única definição — as skills referenciam este item, não a repetem): (1) o do próprio
+   plugin, `plugin_vetor_<server>`, pois compartilha o ciclo de vida e a configuração do plugin;
+   (2) o standalone, `<server>`; (3) o de outro plugin, `plugin_<outro>_<server>` (o primeiro na
+   lista). Ao chamar mais de uma ferramenta do mesmo serviço (ex.: `resolve-library-id` e
+   `query-docs`), use sempre o mesmo segmento.
 
 ## Por que não "tentar e capturar erro"
 
@@ -33,21 +48,29 @@ correta é estática (olhar a lista), não uma tentativa em runtime.
 
 ## Servidores relevantes neste plugin
 
-| Observabilidade (Sentry/Datadog) | `mcp__sentry__` / `mcp__datadog__` | `backlog-ideator` §2.a (opcional) |
-| Banco de dados | `mcp__<db>__` (nome depende do MCP configurado) | `guardian` (auditoria de schema/queries) |
-| Docker | `mcp__docker__` | `guardian` (auditoria de saúde de containers) |
-| Browser (chrome-devtools) | `mcp__chrome-devtools__` | `fix-loop-agent` (reproduzir bug de UI antes do fix), `worktree-ship` (checagem e2e leve antes do PR) |
-| Pesquisa web (Exa) | `mcp__exa__` | `backlog-ideator` (pesquisar padrões/arquitetura antes de propor issue), `fix-loop-agent` (pesquisar mensagem de erro/documentação de uma lib externa), `issue-worker` (checar docs de API externa durante a implementação) |
-| Documentação de ferramentas/libs (Context7) | `mcp__context7__` | **Obrigatório quando disponível** (ver issue vetor#163) — qualquer skill que precise pesquisar comportamento de uma ferramenta/lib/framework/API externa (`issue-worker`, `fix-loop-agent`, `guardian`, `backlog-ideator`) |
-| Documentação do próprio Claude Code (`claude-code-docs`) | `mcp__claude-code-docs__` | **Obrigatório quando disponível** (ver issue vetor#164) — qualquer skill que precise responder sobre o funcionamento do próprio Claude Code (hooks, slash commands, MCP, permissões, SDK) (`vetor` (setup), `retro`) |
+Cada servidor abaixo casa pelas duas formas de segmento (ver "O mecanismo correto"): standalone
+`mcp__<server>__` ou empacotado `mcp__plugin_<plugin>_<server>__`. O plugin vetor empacota
+`context7`, `chrome-devtools` e `docker` (`.mcp.json`) — numa sessão com o vetor, o nome real
+desses três é `mcp__plugin_vetor_<server>__`.
+
+| Observabilidade (Sentry/Datadog) | `mcp__sentry__` / `mcp__datadog__` (ou `mcp__plugin_<plugin>_sentry__` / `mcp__plugin_<plugin>_datadog__`) | `backlog-ideator` §2.a (opcional) |
+| Banco de dados | `mcp__<db>__` (ou `mcp__plugin_<plugin>_<db>__`; o nome `<db>` depende do MCP configurado) | `guardian` (auditoria de schema/queries) |
+| Docker | `mcp__docker__` (ou `mcp__plugin_<plugin>_docker__`; **não** `mcp__MCP_DOCKER__`) | `guardian` (auditoria de saúde de containers) |
+| Browser (chrome-devtools) | `mcp__chrome-devtools__` (ou `mcp__plugin_<plugin>_chrome-devtools__`) | `fix-loop-agent` (reproduzir bug de UI antes do fix), `worktree-ship` (checagem e2e leve antes do PR) |
+| Pesquisa web (Exa) | `mcp__exa__` (ou `mcp__plugin_<plugin>_exa__`) | `backlog-ideator` (pesquisar padrões/arquitetura antes de propor issue), `fix-loop-agent` (pesquisar mensagem de erro/documentação de uma lib externa), `issue-worker` (checar docs de API externa durante a implementação) |
+| Documentação de ferramentas/libs (Context7) | `mcp__context7__` (ou `mcp__plugin_<plugin>_context7__`) | **Obrigatório quando disponível** (ver issue vetor#163) — qualquer skill que precise pesquisar comportamento de uma ferramenta/lib/framework/API externa (`issue-worker`, `fix-loop-agent`, `guardian`, `backlog-ideator`) |
+| Documentação do próprio Claude Code (`claude-code-docs`) | `mcp__claude-code-docs__` (ou `mcp__plugin_<plugin>_claude-code-docs__`) | **Obrigatório quando disponível** (ver issue vetor#164) — qualquer skill que precise responder sobre o funcionamento do próprio Claude Code (hooks, slash commands, MCP, permissões, SDK) (`vetor` (setup), `retro`) |
 
 ### Documentação de ferramentas/libs (Context7)
 
 Use antes de afirmar comportamento de uma ferramenta, biblioteca, framework, SDK ou API externa —
 não confie só no conhecimento pré-treinado do agente, que pode estar desatualizado.
 
-- **Com MCP (obrigatório):** `mcp__context7__resolve-library-id` para achar o library ID, depois
-  `mcp__context7__query-docs` com uma pergunta específica e escopada a um único conceito.
+- **Com MCP (obrigatório):** localize o servidor `context7` pela regra de segmento acima (ex.:
+  `mcp__context7__resolve-library-id` ou `mcp__plugin_vetor_context7__resolve-library-id`; com mais
+  de um, siga a ordem do item 4). Use `resolve-library-id` do segmento escolhido para achar o library
+  ID, depois `query-docs` do mesmo segmento com uma pergunta específica e escopada a um único
+  conceito.
 - **Sem MCP (fallback):** siga sem o MCP, sinalizando a limitação no resultado entregue ao usuário —
   não bloqueia a skill.
 

package/templates/skills/shared/references/planning-conventions.md

@@ -54,20 +54,21 @@ Exemplo para Coordinator:
 
 #### Para skills de implementação de código (`fix-loop-agent`, `issue-worker`, e similares)
 
-* **No Claude Code**: use o plan mode nativo — apresente o plano acima e conclua com `ExitPlanMode`
-  para pedir aprovação do usuário. Este é o caminho de primeira classe no Claude Code para código,
-  não um fallback.
+* **No Claude Code**: use o plan mode nativo se a sessão já estiver em plan mode — apresente o plano
+  acima e conclua com `ExitPlanMode` para pedir aprovação do usuário. Se a sessão **não** estiver em
+  plan mode, aprove via `AskUserQuestion` (ou chame `EnterPlanMode` antes).
 * **No Antigravity/Gemini**: salve o plano no artefato `implementation_plan.md` definindo
   `request_feedback: true` nos metadados. O agente interromperá a chamada até o clique em "Proceed".
 
-#### Para skills de orquestração/ideação (`backlog-ideator`, `issue-coordinator`, `guardian`)
+#### Para skills de orquestração/ideação (`backlog-ideator`, `issue-coordinator`, `guardian`, `retro`)
 
 Estas skills realizam mutações estruturais (criar issues, orquestrar subagentes) mas **não implementam
 código de produto**. Para elas:
 
-* **No Claude Code**: exiba o plano no chat e aguarde uma resposta textual afirmativa do usuário
-  (ex.: "sim", "prosseguir"). **Não use `ExitPlanMode`** — a ferramenta a desaconselha explicitamente
-  para tarefas fora do escopo de escrita de código.
+* **No Claude Code**: se a sessão já estiver em plan mode, conclua com `ExitPlanMode`. Se a sessão
+  **não** estiver em plan mode, aprove via `AskUserQuestion` (ou exiba o plano no chat e aguarde uma
+  resposta textual afirmativa do usuário, ex.: "sim", "prosseguir") — nunca chame `ExitPlanMode`
+  fora de plan mode (issue #326).
 * **No Antigravity/Gemini**: salve o plano no artefato `implementation_plan.md` definindo
   `request_feedback: true` nos metadados. O agente interromperá a chamada até o clique em "Proceed".
 

package/templates/skills/stack-practices/SKILL.md

@@ -61,16 +61,36 @@ frameworks web, ORMs, a lib de UI principal — nunca toda dependência declarad
 transitivas. Uma rule por utilitário/dependência transitiva infla o contexto sem ganho; o escopo
 é deliberadamente restrito ao mesmo allowlist do detector.
 
+**Pacotes irmãos (regra única, vale para todos os passos).** Pacotes que compartilham a mesma
+documentação formam um **grupo** e, daqui em diante, contam como **uma** lib: uma resolução e uma
+query (feitas com o nome do líder), um único arquivo `<líder>.md`. Grupos reconhecidos — lista
+fechada, no formato `membro → líder`; qualquer outro pacote é independente: `react-dom → react`.
+
+- O grupo entra na lista se qualquer membro foi detectado. O arquivo é sempre `<líder>.md`, mesmo
+  que só um membro esteja no projeto. A versão instalada do grupo é a do líder; se o líder não foi
+  detectado, a do primeiro membro detectado.
+- No cabeçalho e no título do passo 4, `<lib>@<versão-instalada>` vira a lista dos membros
+  detectados, cada um com a sua versão instalada (ex.: `react@19.2.8, react-dom@19.2.8`).
+- Falha ou "sem fonte oficial" no passo 3 pula o grupo inteiro — nunca só um membro.
+
 Sem `--refresh`, filtre a lista às libs que ainda **não** têm arquivo em
-`.claude/rules/vetor/best-practices/<lib>.md`. Com `--refresh`, mantenha a lista inteira.
+`.claude/rules/vetor/best-practices/<lib>.md` (`<lib>` = o líder, no caso de um grupo — assim um
+irmão já coberto não reaparece como candidato). Com `--refresh`, mantenha a lista inteira.
 
 Se a lista resultante estiver vazia (nenhuma lib estrutural detectada, ou todas já têm regra e não
 foi passado `--refresh`), reporte e pare — nada a fazer.
 
 ### 2 — Checar disponibilidade do Context7
 
-Siga o mecanismo de `mcp-availability.md`: procure por qualquer ferramenta com prefixo
-`mcp__context7__` (direta ou diferida via `ToolSearch`).
+Siga o mecanismo de `mcp-availability.md`: procure as ferramentas `resolve-library-id` e
+`query-docs` cujo **segmento de servidor** case com `context7` — `mcp__context7__…` (standalone) ou
+`mcp__plugin_<plugin>_context7__…` (empacotado), nunca por substring solta. Com mais de um segmento
+correspondente, escolha pela ordem de preferência do item 4 daquele documento.
+
+Guarde o prefixo completo escolhido (ex.: `mcp__context7__` ou `mcp__plugin_vetor_context7__`) como
+`<ctx7>`. O passo 3 usa **somente** `<ctx7>resolve-library-id` e `<ctx7>query-docs` — nunca um
+prefixo fixo. Se as ferramentas estiverem diferidas, carregue-as antes com `ToolSearch`
+(`select:<ctx7>resolve-library-id,<ctx7>query-docs`).
 
 **Se não disponível:** não gere nenhuma regra para as libs afetadas. Reporte a limitação no
 resultado final ("Context7 indisponível — nenhuma regra de melhores práticas gerada para: <libs>")
@@ -82,19 +102,44 @@ existe para evitar.
 
 Para cada lib da lista do passo 1:
 
-1. `mcp__context7__resolve-library-id` para achar o library ID a partir do nome (e, se disponível
-   na resposta, restrinja pela versão detectada no passo 1).
-2. `mcp__context7__query-docs` com uma pergunta específica e escopada, no estilo "práticas atuais
-   recomendadas e APIs deprecated para `<lib>` versão `<versão>`" — nunca uma pergunta genérica que
-   force o Context7 a devolver um resumo raso.
-
-Se a resolução ou a query falharem para uma lib específica (lib não indexada, erro transiente),
+1. **Resolver o library ID versionado.** Chame `<ctx7>resolve-library-id` com o nome da lib.
+   Percorra os resultados na ordem devolvida e fique com o primeiro que (a) não seja `/websites/*`
+   (site indexado — nunca produz `Source` em tag, ver item 3) e (b) liste em `Versions` ao menos uma
+   *versão de release*. Não são release: entradas `__branch__*` e pré-releases (`-canary`, `-rc`,
+   `-beta`, `-alpha`, `-next`). Escolha a versão nesta ordem: a igual à instalada (`v<V>` ou
+   `<V>`); senão a maior versão de release menor que a instalada e da mesma major (ex.: instalada
+   16.3.6, indexada até `v16.2.9` → `v16.2.9`); se a instalada for `unknown`, a maior de release
+   listada. O ID consultado é `/<org>/<projeto>/<versão-docs>` e `<versão-docs>` é esse sufixo.
+   Sem resultado que atenda (a) e (b), ou sem versão escolhível: pule a lib e registre "sem fonte
+   oficial na versão <V-instalada>" no passo 6 — não consulte o ID sem versão.
+2. **Consultar.** `<ctx7>query-docs` com o ID versionado e uma pergunta específica e escopada, no
+   estilo "práticas atuais recomendadas e APIs deprecated para `<lib>` versão `<versão-docs>`" —
+   nunca uma pergunta genérica que force o Context7 a devolver um resumo raso.
+3. **Filtro de Source.** Cada snippet devolvido traz uma linha `Source: <URL>`. Aceite o snippet só
+   se a URL for `https://github.com/<org>/<projeto>/blob/<versão-docs>/<caminho>` (ou
+   `/tree/<versão-docs>/…`), com `<org>/<projeto>` e `<versão-docs>` idênticos aos do ID consultado.
+   Isso define os dois critérios:
+   - **Oficial** = arquivo do repositório do mantenedor (o `<org>/<projeto>` do library ID — a
+     skill confia na atribuição do Context7, não verifica a origem do repositório por conta
+     própria). Não contam: agregadores (`/websites/*`, deepwiki), blogs, gists, fóruns, repositórios de outra org
+     nem snippet sem `Source`. Um site de documentação do mantenedor (ex.: `nextjs.org/docs/…`)
+     também não passa, ainda que seja do mantenedor: a URL não fixa versão.
+   - **Na tag da versão consultada** = o ref após `blob/`/`tree/` é exatamente `<versão-docs>`. Não
+     contam `blob/main/`, `blob/canary/`, qualquer outro branch, outra versão nem SHA.
+
+   Descarte os demais snippets por inteiro, incluindo texto editorial anexado a eles. Se nenhum
+   snippet sobrar: **não grave regra** para a lib e registre "sem fonte oficial na versão
+   <versão-docs>" no passo 6. Nunca preencha com snippets descartados nem com conhecimento
+   pré-treinado. Sem arquivo gravado, a lib volta como candidata na próxima execução (filtro do
+   passo 1) — comportamento esperado, igual ao de uma falha de resolução.
+
+Se a resolução ou a query falharem por outro motivo (lib não indexada, erro transiente),
 **pule só aquela lib** — reporte a falha no resultado e continue com as demais. Uma lib com erro
 nunca bloqueia a geração das regras das outras.
 
 ### 4 — Gravar a regra
 
-Para cada lib com resposta do Context7, escreva `.claude/rules/vetor/best-practices/<lib>.md`:
+Para cada lib com ao menos um snippet aceito pelo filtro de Source (passo 3, item 3), escreva `.claude/rules/vetor/best-practices/<lib>.md`:
 
 ```markdown
 ---
@@ -102,11 +147,11 @@ paths:
   - "<globs relevantes à lib, ex. '**/*.tsx' para uma lib de UI React>"
 ---
 
-> Gerado por `/vetor:stack-practices` a partir da documentação de <lib>@<versão> via Context7 em <data ISO>.
+> Gerado por `/vetor:stack-practices` a partir da documentação de <lib>@<versão-instalada> (docs consultadas: <versão-docs>) via Context7 em <data ISO>.
 > Conhecimento externo, não um fato observado neste repositório — pode ficar desatualizado.
 > Rode `/vetor:stack-practices --refresh` periodicamente. Editável — não sobrescrito sem `--refresh`.
 
-# Melhores práticas — <lib>@<versão>
+# Melhores práticas — <lib>@<versão-instalada> (docs: <versão-docs>)
 
 - <bullet curto e citável, só o que o Context7 retornou como prática atual documentada>
 - <...>
@@ -117,10 +162,14 @@ Regras:
   rules factuais de `scripts/lib/rules.ts` — nunca escreva regra de melhor prática no mesmo arquivo
   `.claude/rules/vetor/<runtime>.md` gerado pelo `/vetor`, cuja regra de ouro é "só fato observado
   localmente". `.claude/rules/vetor/best-practices/` é um diretório à parte.
+- **O cabeçalho registra a versão instalada e a versão de docs consultada**; se divergirem, o
+  passo 6 reporta a divergência.
 - `<data ISO>` é a data da consulta, não uma data fixa — usada depois pelo guardian para medir
   staleness (passo 5).
 - Bullets refletem só o que a fonte (Context7) disse — nunca elaboração ou inferência do agente
   além do que a resposta retornou.
+- **Source oficial na tag da versão consultada** (regra adicional — não substitui a anterior): só
+  entram bullets de snippets aceitos pelo filtro de Source do passo 3 (item 3).
 - Sem `--refresh`, nunca sobrescreva um arquivo já existente para a mesma lib.
 
 ### 5 — Sinalizar staleness no guardian (referência cruzada)
@@ -134,9 +183,13 @@ extra aqui, além de manter a data no cabeçalho (passo 4) precisa e atualizada
 
 Ao final, resuma:
 - Libs detectadas no passo 1 e quais já tinham regra (puladas, sem `--refresh`).
-- Libs com regra gerada/atualizada nesta execução, com a versão consultada.
+- Libs com regra gerada/atualizada nesta execução, com a versão instalada e a versão de docs consultada.
+- **Divergências de versão** (versão instalada ≠ versão de docs indexada) — sinalize explicitamente.
 - Libs puladas por falha de resolução/query no Context7 (passo 3).
+- Libs sem regra por "sem fonte oficial na versão X" (passo 3: sem ID versionado utilizável ou
+  nenhum snippet aceito pelo filtro de Source), com a versão X.
 - Se o Context7 não estava disponível: a lista completa de libs sem regra por esse motivo (passo 2).
+- **Lembrete de commit:** Recomende ao usuário commitar os arquivos gerados em `.claude/rules/vetor/best-practices/` (ou ofereça o commit). Workers rodam em worktrees isolados que só herdam arquivos rastreados no git — regras untracked não ficam disponíveis para eles (issue #327).
 
 ---
 

package/templates/skills/vetor/SKILL.md

@@ -156,7 +156,7 @@ Arquivos configurados:
 
 Próximos passos recomendados:
 1. Abra e revise o arquivo `.claude/vetor/module-test-map.md` para garantir que os comandos de teste headless e os mapeamentos de pasta de seu projeto estejam 100% corretos.
-2. Revise e **commite** `.claude/rules/vetor/`. Os issue-workers rodam em worktrees, que só contêm arquivos rastreados pelo git — uma rule não commitada não chega até eles.
+2. Revise e **commite** os arquivos de configuração e regras (`.claude/vetor/config.json`, `.claude/vetor/module-test-map.md` e `.claude/rules/vetor/`). Os issue-workers rodam em worktrees, que só contêm arquivos rastreados pelo git — arquivos untracked não chegam até eles e deixam os workers sem mapa de testes nem regras (issue #327). Avise ou ofereça o commit caso ainda estejam untracked no git.
 3. (Opcional) Crie a pasta `.claude/vetor/docs/` e adicione guias de arquitetura, padrões do projeto e gaps em markdown. O comando `/vetor:backlog` lerá automaticamente estes arquivos para propor issues altamente contextualizadas.
 4. (Opcional) Rode `/vetor:stack-practices` para gerar regras de melhores práticas da stack detectada (via Context7).
 ```

package/templates/skills/worktree-ship/SKILL.md

@@ -168,11 +168,11 @@ Closes #<issue#>
 🤖 Desenvolvido com [Claude Code](https://claude.ai/code)
 ```
 
-Anexe `Closes #<issue#>` (se fornecida) e a nota do rodapé ao final. Crie o PR draft:
+Anexe `Closes #<issue#>` (ou uma linha `Closes #N` por issue do grupo; use `Refs #N` se a issue não deve ser fechada automaticamente, issue #338). Grave o corpo num arquivo temporário e passe via `--body-file`, evitando corrupção de backticks e caracteres especiais pelo shell (issue #334):
 ```bash
 gh pr create \
   --title "<type>(<slug>): <resumo dos commits>" \
-  --body "<descrição gerada e validada>" \
+  --body-file "<path-do-arquivo-de-corpo>" \
   --draft \
   --base "$DEFAULT_BRANCH"
 ```
@@ -218,14 +218,25 @@ gh pr checks <PR-number>
 
 Para cada falha detectada:
 
-**8.a — Circuit breaker de infraestrutura (antes de ler logs)**
+Verifique se a falha possui `run-id` do GitHub Actions (`gh pr checks <PR-number> --json name,link,state`).
+
+**8.a — Falha em check externo sem run-id (Vercel, Netlify etc. — issue #340)**
+
+Para provedores de deploy e checks externos sem execução do GitHub Actions:
+1. Identifique o check externo: extraia link e descrição de erro no `gh pr checks`.
+2. Se a CLI do provedor (ex.: `npx vercel inspect <id> --logs`) estiver instalada e autenticada, consulte os logs; caso contrário, solicite o trecho de erro ao operador via `AskUserQuestion`.
+3. Dica: se o build passa localmente mas falha no provedor externo, teste remover temporariamente o `.env.local` para reproduzir ausência de variáveis de ambiente.
+4. Para retentar o check externo após ajuste, faça um commit vazio e envie:
+   `git commit --allow-empty -m "ci: retry external check" && git push origin <branch>`, e volte ao passo 7.
+
+**8.b — Circuit breaker de infraestrutura (GitHub Actions com run-id)**
 
 ```bash
 deno run -A scripts/detect-infra-failure.ts <run-id>
 ```
 
 Se retornar exit 0 (JSON com `isInfrastructureFailure: true`), nenhum fix de código resolve:
-- **Pule** inteiramente as iterações de fix (§8.b).
+- **Pule** inteiramente as iterações de fix (§8.c).
 - Escreva o status file:
   ```markdown
   Status: BLOCKED_INFRA
@@ -235,7 +246,7 @@ Se retornar exit 0 (JSON com `isInfrastructureFailure: true`), nenhum fix de có
 - **Escale** via `AskUserQuestion`: `⚠️ Falha de infraestrutura detectada no CI (billing/outage). Não é possível resolver com fix de código. Deseja aguardar a resolução ou prosseguir sem CI (merge manual)?`
 - **Pare.** Não consuma iterações de fix-loop.
 
-**8.b — Erro de código (só se não for infraestrutura)**
+**8.c — Erro de código (só se não for infraestrutura)**
 
 ```bash
 gh run view <run-id> --log-failed
@@ -333,9 +344,11 @@ Aguardando aprovação antes de prosseguir com merge.
 bash "$SKILL_DIR/../../scripts/vetor-merge.sh" <PR-number>
 ```
 
-O script faz `gh pr ready` + `gh pr merge --squash --delete-branch` e verifica o estado real do PR
-quando o `gh` sai não-zero (erro de cleanup local da branch não é falha de merge):
-- **exit 0** — PR mergeado. Siga para o passo 11.
+O script faz `gh pr ready` + `gh pr merge --squash --delete-branch`, passando `--subject` e
+`--body` do PR (garantindo que o corpo do PR seja a única fonte autoritativa de fechamento de issues
+no squash, issue #338). Verifica o estado real do PR quando o `gh` sai não-zero e, em caso de merge no
+remoto com falha apenas no cleanup local, apaga a branch remota explicitamente (issue #325):
+- **exit 0** — PR mergeado e branch remota verificada/removida. Siga para o passo 11.
 - **exit 3** — merge não aconteceu. Rode `git merge "$DEFAULT_BRANCH"` localmente no worktree e siga
   `../shared/references/conflict-resolution.md`. Resolvido e verde, volte ao
   passo 7.
@@ -361,9 +374,8 @@ localização é do harness). Se invocado pelo `issue-coordinator` (modo headles
 automaticamente:
 ```bash
 bash "$SKILL_DIR/../../scripts/vetor-checks.sh" safe-remove-worktree "<path-do-worktree>"
-git branch -d <branch>
-rm -f .claude/vetor/status/<branch>.md
-rm -f .claude/vetor/status/<branch>-touched-files.json
+bash "$SKILL_DIR/../../scripts/vetor-checks.sh" delete-merged-branch "<branch>"
+bash "$SKILL_DIR/../../scripts/vetor-checks.sh" clean-status "<branch>"
 ```
 
 Se a checagem falhar, **pare o cleanup** e não prossiga com `git branch -d`/remoção dos arquivos de
@@ -371,13 +383,19 @@ status/cache — há dois motivos distintos de falha:
 
 - **Worktree filho ativo dentro do path alvo**: mostre os paths e preserve worktree pai, branch e
   arquivos de status/cache até os filhos serem realocados.
-- **Diretório residual em disco após `git worktree remove`** (issue #157): o `git worktree remove`
+- **Diretório residual em disco após `git worktree remove`** (issues #157, #324): o `git worktree remove`
   desregistrou o worktree do git (não aparece mais em `git worktree list`) mas falhou ao apagar o
-  diretório — no Windows, tipicamente por `Filename too long` (artefatos como `build/`, `.gradle/`,
-  `node_modules/` estouram o limite de 260 caracteres). `safe-remove-worktree` já tenta uma remoção
-  com prefixo de path longo nesse caso; se mesmo assim restar, ela sai não-zero citando o path
-  residual. Reporte o path ao operador para remoção manual — não tente forçar via `rm -rf` por conta
-  própria, o diretório pode conter uncommitted work relevante para inspeção.
+  diretório — no Windows, por `Filename too long` ou `Permission denied` transitório. `safe-remove-worktree`
+  reconsulta o git: como o worktree já foi desregistrado, tenta a remoção segura do resíduo (inclusive
+  com prefixo de path longo `\\?\`); se mesmo assim restar, ela sai não-zero citando o path residual
+  para remoção manual, sem alegar falsamente uncommitted work (issue #324).
+
+- **Remoção segura de branch e status**:
+  - `delete-merged-branch <branch>` apaga a branch local apenas se confirmada como `MERGED` no GitHub
+    ou se sua árvore for idêntica à branch default, contornando a recusa de `git branch -d` para squash
+    e sem acionar o bloqueio incondicional de `-D` (issue #341).
+  - `clean-status <branch>` normaliza o nome da branch (`/` substituída por `-`) e apaga o status `.md`,
+    a sentinela `.md.stopguard` e o cache `-touched-files.json` (issue #344).
 
 Se invocado manualmente pelo usuário: pergunte antes de remover (a confirmação cobre worktree,
 branch, status file e cache de arquivos tocados).