@tavaressan/vetor 0.1.0

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

@@ -0,0 +1,596 @@
+---
+name: issue-coordinator
+description: Despacho paralelo de issues GitHub para sub-agentes com worktrees isolados guiado por Planejamento. Agrega status e coordena merge serializado. Use /vetor:issue-coordinator [label]. Aceita --headless para execução não-interativa (rotinas/CI).
+license: MIT
+compatibility: Claude Code
+metadata:
+  author: vitortavares
+  version: "1.6.0"
+---
+
+Você é o coordenador de issues do Vetor. Sua missão é despachar issues de um label GitHub para sub-agentes paralelos, cada um em seu próprio worktree, e coordenar o ciclo completo até merge, utilizando o fluxo nativo de planejamento.
+
+---
+
+## Sintaxe
+
+```
+/vetor:issue-coordinator [label]
+/vetor:issue-coordinator <n1>,<n2>,...
+/vetor:issue-coordinator
+/vetor:issue-coordinator --resume
+/vetor:issue-coordinator [label] --headless
+```
+
+- `[label]`: label das issues a despachar (sem argumento: todas as issues abertas, ou usa `defaultDispatchLabel` de `.claude/vetor/config.json` se configurado)
+- `<n1>,<n2>,...`: lista de números de issue (ex.: `/vetor:issue-coordinator 12,14,17`). Casa `^[0-9]+(,[0-9]+)*$`.
+- **sem argumento** ou **`--resume`**: modo de retomada — reconstrói o estado a partir dos
+  worktrees/status files existentes (Fase 0).
+- `--headless`: execução **não-interativa**, para rotinas agendadas e CI. Combinável com qualquer
+  um dos anteriores.
+
+---
+
+## 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.
+
+Este coordenador compõe os primitivos do plugin:
+- `/vetor:worktree-create` — criação headless de worktree (skill, Fase 3)
+- `vetor:issue-worker` — subagente nativo (`agents/issue-worker.md`) despachado por issue na Fase 4;
+  já traz a skill `fix-loop-agent` pré-carregada e tools restritas (nunca push/PR/merge)
+- `/vetor:worktree-ship` — pipeline de entrega (test → PR → CI → merge), Fase 6
+
+Os comandos de teste vêm de `.claude/vetor/module-test-map.md` ou, na ausência dela, de
+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`.
+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`.
+Se uma issue referenciar uma Spec previamente gerada por `/vetor:spec` (ver `skills/spec/SKILL.md`
+§6), ela fica em `docs/specs/<slug>.md` por padrão (path previsível, issue #219) — útil como contexto
+adicional ao ler a issue no passo 1; esta skill não consome nem gera código a partir dela.
+
+---
+
+## Modo headless
+
+A flag `--headless` substitui os quatro pontos de interação humana por decisões determinísticas:
+
+| Fase | Interativo | Headless |
+|------|-----------|----------|
+| 2 — gate de Spec/design | `AskUserQuestion` por issue não-trivial sem Spec associada | Nunca pergunta, nunca bloqueia; anota `⚠️ sem Spec associada` na coluna "Ação" e segue o dispatch |
+| 2 — teto de workers | `AskUserQuestion` | Usa `N_rec` calculado, sem perguntar |
+| 2 — aprovação do plano | `ExitPlanMode`, **pare** | Não pede aprovação; imprime o plano no relatório |
+| 5.b — `BLOCKED_WAITING` | `AskUserQuestion` ao usuário | Não escala; deixa o grupo bloqueado e reporta |
+| 5.c — circuit breaker | Pergunta se pausa | Sempre pausa: para de despachar e reporta |
+
+Além disso, em `--headless`:
+
+- **A Fase 6 (merge) não roda.** Nunca invoque `worktree-ship`, `gh pr ready` ou `gh pr merge`.
+  Grupos em `GREEN` são reportados como prontos para ship.
+- **Nenhuma permissão é auto-aprovada.** Um worker que bloqueia pedindo permissão permanece
+  `BLOCKED_WAITING` e aparece no relatório final.
+- **Ausência de trabalho não é falha.** Se não houver issue elegível, encerre com um relatório de
+  uma linha. Não force dispatch para parecer produtivo.
+
+---
+
+## Comportamento
+
+### 0 — Detecção de modo
+
+- **Sem argumento** ou **`--resume`**: entre em **modo de retomada**.
+  1. Rode `bash "$SKILL_DIR/../../scripts/vetor-status.sh"` para listar os worktrees ativos com
+     status file. O script cruza os status files com `gh pr list` e anota `GREEN (PR #N aberta)` ou
+     `GREEN (já mergeado via #N)`.
+  2. Se houver ao menos um status file ativo: **pule as Fases 1–3** e faça a pergunta de workers
+     (Fase 2) — o estado em memória de `N` não sobrevive a um reinício da sessão. Depois monte a
+     tabela de status (Fase 5.a) e, para cada grupo em `GREEN` sem PR aberta ou merge, ofereça o
+     ship via `AskUserQuestion` ("Fazer ship do grupo `<slug>` (Issue #<N>), que está GREEN?"). Se
+     já estiver mergeado, apenas informe. Prossiga a partir da Fase 5/6.
+     Em `--headless`: não pergunte o teto (use `N_rec`) e não ofereça ship — apenas reporte os
+     grupos `GREEN` como prontos.
+  3. Se **não houver** worktree ativo com status file: caia no fluxo padrão (Fase 1), descobrindo
+     dinamicamente labels ou usando `defaultDispatchLabel` de `.claude/vetor/config.json` se configurado.
+- **Lista de números** ou **label explícito**: siga o fluxo padrão a partir da Fase 1.
+
+### 1 — Listar issues candidatas e analisar afinidades
+
+Se o argumento casar `^[0-9]+(,[0-9]+)*$`, trate-o como **lista por número**; caso contrário, como
+**label**. Se **nenhum argumento** for passado:
+- Verifique se `.claude/vetor/config.json` declara `defaultDispatchLabel`
+  - Se sim: use esse label (filtro explícito)
+  - Se não: descubra todas as issues abertas (sem filtro de label)
+
+O restante do fluxo é idêntico nos três modos (número, label, descoberta dinâmica).
+
+- **Lista por número:**
+  ```bash
+  for N in ${ARG//,/ }; do gh issue view "$N" --json number,title,labels,body; done
+  ```
+- **Label ou defaultDispatchLabel:**
+  ```bash
+  gh issue list --label <label> --state open --json number,title,labels,body
+  ```
+- **Descoberta dinâmica (sem argumento, sem defaultDispatchLabel):**
+  ```bash
+  gh issue list --state open --json number,title,labels,body
+  ```
+
+**Priorização: pedidas pelo usuário vs. recomendadas pelo agente.** O modo por label (ou a descoberta
+dinâmica) traz de volta, na mesma leva, issues abertas manualmente/via integração externa e issues
+geradas por `/vetor:retro` ou `/vetor:backlog-ideator` (label `ai-generated`), sem distinção. Antes de
+montar o agrupamento por afinidade, particione o resultado usando o campo `labels` já retornado:
+
+- **Pedidas pelo usuário** (candidatas primárias): issues **sem** a label `ai-generated`.
+- **Recomendadas pelo agente**: issues **com** a label `ai-generated`.
+
+Monte o plano de dispatch priorizando o grupo "pedidas pelo usuário". Só inclua issues do grupo
+"recomendadas pelo agente" quando o primeiro grupo estiver **vazio** no filtro aplicado — ou,
+opcionalmente, como itens extras claramente sinalizados como "recomendação do agente" no plano
+apresentado para aprovação (Fase 2), nunca misturados sem essa marcação.
+
+Para cada issue, verifique se já há PR aberto:
+```bash
+gh pr list --search "closes:#<N>" --state open --json number,title
+```
+Se houver (ou se `vetor-status.sh` reportar `GREEN (PR #N aberta)` / `GREEN (já mergeado via #N)`):
+pule a issue e registre na tabela como "PR já aberto (#<PR>)" ou "Já mergeado (#<PR>)".
+
+#### Agrupamento por afinidade
+
+Com as candidatas válidas em mãos, se houver mais de 3 issues, você pode delegar a proposta de
+agrupamento a um runtime externo disponível — detecção e algoritmo de seleção em
+`delegate-to-runtime.md` §1-2 (com 2+ candidatos e nenhuma preferência configurada, em sessão
+interativa pergunte qual usar; em `--headless`, siga inline). Você valida e corrige a proposta; a
+distribuição final é sua.
+
+Inline (ou com 3 ou menos issues):
+- Agrupe issues **complementares ou correlatas** (mesmo módulo, ou um `fix` que complementa
+  diretamente uma `feat`) por título, labels e descrição.
+- Defina uma **Lead Issue** (a principal ou mais antiga), que dá nome ao worktree/branch.
+- As demais viram **Sequential Issues**, resolvidas em sequência pelo mesmo agente no mesmo worktree.
+
+#### Ondas de despacho (DAG Waves)
+
+Grupos que rodam **em paralelo** podem depender causalmente uns dos outros (ex.: grupo B usa uma
+entidade/migration/classe que só existe depois do merge do grupo A). Despachar B a partir do branch
+default ANTES do merge de A causa branch skew: o worktree de B nunca verá as mudanças de A, exigindo
+conciliação manual depois. Para evitar isso, organize os grupos em **ondas topológicas** (`O_1, O_2,
+..., O_k`) antes de montar o plano da Fase 2:
+
+1. Para cada par de grupos, verifique **heurísticas best-effort** de dependência (não há grafo formal
+   de dependências no GitHub — esta detecção é sempre uma inferência, nunca um fato garantido):
+   - Título/corpo de uma issue do grupo B menciona explicitamente outro grupo/issue do grupo A (ex.:
+     "depende de #12", "após #12", "usa a entidade criada em #12").
+   - Labels indicando ordem (ex.: `blocked-by`, `depends-on`) ou convenção do time.
+   - Mesmo módulo/diretório, mas com evidência de ordem de criação de arquivo (ex.: B referencia uma
+     classe, tabela ou migration que a descrição de A propõe criar pela primeira vez).
+2. Construa um DAG (grafo acíclico dirigido) de grupos: aresta `A → B` quando B depende de A. Se
+   houver ciclo aparente (heurística ambígua), trate como **não-dependente** e avise no plano — não
+   bloqueie o dispatch por uma inferência de baixa confiança.
+3. Derive as ondas por ordenação topológica: `O_1` contém todos os grupos sem dependência pendente;
+   `O_2` os que dependem só de grupos em `O_1`; e assim por diante.
+4. **Fallback:** se nenhuma dependência for detectável entre os grupos (caso mais comum), cada grupo
+   forma sua própria onda e todas as ondas colapsam em uma só (`O_1`) — comportamento idêntico ao
+   dispatch paralelo atual, sem mudança de comportamento observável.
+5. O usuário pode **corrigir manualmente** o agrupamento em ondas no plano da Fase 2 antes de aprovar
+   — a heurística é um ponto de partida, não uma decisão final.
+
+### 2 — Apresentar plano de dispatch e obter aprovação
+
+#### Gate de Spec/design (classificação de complexidade, antes do dispatch)
+
+Antes de montar a tabela do plano, classifique cada issue candidata da Fase 1 — vocabulário derivado
+da triagem equivalente de `spec/SKILL.md` §0.1 (Investigação/Confirmação rápida/Spec completa), mas
+aplicado aqui à decisão "despachar como está, ou sinalizar a falta de uma Spec antes de despachar":
+
+1. **Heurística de complexidade**, por issue (`gh issue view <N> --json body,labels`):
+   - **Módulos tocados**: quantos módulos de `.claude/vetor/module-test-map.md` têm o prefixo
+     mencionado no título/corpo da issue (ex.: `cli/`, `scripts/`). Mais de 1 é sinal de complexidade
+     — em projetos com poucos módulos mapeados este sinal tende a ficar em 0 ou 1 na maioria das
+     issues; nesse caso o sinal de "escopo já declarado" abaixo é quem decide a classificação.
+   - **Escopo já declarado**: o corpo já traz uma seção equivalente a "Escopo do trabalho" e um
+     "Critério de Aceite" com itens concretos (checklist, não frase vaga).
+   - **Label**: `feat`/`enhancement`/`refactor` tendem a não-trivial mesmo com escopo declarado;
+     `fix`/`chore`/`bug` com escopo declarado tendem a trivial. Ajuste esta lista ao vocabulário de
+     labels efetivamente usado no repositório-alvo (ex.: um projeto sem label `feat` própria, como
+     este mesmo repositório, usa `enhancement` para o equivalente).
+2. **Classificação**: `trivial` quando o escopo já está declarado **e** o nº de módulos tocados é
+   ≤ 1 **e** a label não é `feat`/`enhancement`/`refactor`; **não-trivial** em qualquer outro caso
+   (múltiplos módulos, ou escopo ausente/vago, ou `feat`/`enhancement`/`refactor` sem Critério de
+   Aceite explícito).
+3. **Spec associada**: verifique se a issue referencia uma Spec (`docs/specs/<slug>.md`, ver
+   `spec/SKILL.md` §6) no corpo ou em algum comentário.
+4. **Gate**: sinalize apenas issues `não-trivial` **sem** Spec associada — nunca issues `trivial`
+   (um bugfix que já chega com escopo claro não é bloqueado cegamente) nem issues `não-trivial` que já
+   têm Spec.
+
+**Fora de `--headless`:** para cada issue sinalizada, pergunte via `AskUserQuestion` (uma pergunta por
+issue, ou agrupada se houver mais de uma — `planning-conventions.md` §3 "Regra das 3 perguntas"),
+**antes de montar a tabela do plano**:
+
+```
+Issue #<N> parece não-trivial (<razão: múltiplos módulos | sem Escopo do trabalho/Critério de
+Aceite | feat/enhancement/refactor sem escopo detalhado>) e não tem Spec associada. Como prosseguir?
+
+1. Despachar mesmo assim — escopo confirmado nesta conversa
+2. Gerar Spec antes (/vetor:spec) — esta issue sai desta leva de dispatch
+3. Confirmar rapidamente 2-3 pontos agora (problema, resultado esperado, não-escopo) e seguir sem
+   Spec completa
+```
+
+- **Opções 1 ou 3**: a issue segue no plano normalmente; marque na coluna "Ação" da tabela (abaixo)
+  `Despachar (⚠️ sem Spec — confirmado pelo usuário)`. Na opção 3, inclua os 2-3 pontos confirmados
+  no prompt do worker da Fase 4, como contexto adicional (não substitui uma Spec — é só o mínimo de
+  escopo confirmado para o worker não inventar critério de aceite sozinho).
+- **Opção 2**: remova a issue desta leva de dispatch — ela não aparece como `Despachar`, e sim com
+  Ação `SKIPPED (aguardando Spec)` e coluna "Onda" `—` (nunca foi despachada, não pertence a onda
+  nenhuma). Se a issue sinalizada é a **Lead** do grupo, o grupo inteiro sai da leva (as Sequential
+  Issues do grupo ficam sem Lead para dar nome ao worktree/branch — voltam junto na próxima sessão);
+  se é uma **Sequential Issue**, apenas ela sai e o restante do grupo (Lead + demais Sequential) segue
+  normalmente. A issue (ou grupo) volta a ser candidata em uma sessão futura do coordinator, quando a
+  Spec existir (`/vetor:spec` roda fora deste fluxo, tipicamente numa sessão manual). **Um grupo
+  `SKIPPED` nunca é pendência para a transição de onda da Fase 4** — como não foi despachado, não há
+  branch skew a prevenir (as ondas ordenam merges de trabalho já despachado, não issues que nunca
+  saíram do plano); a transição de `O_i` para `O_{i+1}` ignora grupos `SKIPPED` de `O_i`.
+
+**Em `--headless`: nunca pergunte, nunca bloqueie.** Um gate síncrono aqui recriaria o mesmo deadlock
+por falta de interlocutor do worker preso em plan mode (issue #121 — ver `wiki/Decisoes-de-Design.md`).
+Marque a issue na coluna "Ação" como `Despachar (⚠️ sem Spec associada — sinalização não-bloqueante)` e
+prossiga o dispatch normalmente; a ausência de Spec fica registrada no relatório final (Fase 7), nunca
+impede o dispatch.
+
+Monte o plano (conteúdo mínimo em `planning-conventions.md` §2.1), já refletindo o resultado do gate
+acima na coluna "Ação":
+
+```markdown
+# Plano de Execução Vetor — Coordinator
+
+Coordenando issues: <label ou "todas as abertas" ou descrição do filtro>
+
+## Ações Propostas
+
+| Onda | Subagente/Grupo (Slug) | Lead/Sequential Issues | Modelo Sugerido | Ação |
+|------|-------------------------|------------------------|-----------------|------|
+| O_1  | <slug-1>                | #<N1> (Lead), #<M1>    | <haiku|sonnet>  | Despachar |
+| O_1  | <slug-2>                | #<N3> (Lead)           | <haiku|sonnet>  | Despachar (⚠️ sem Spec — confirmado pelo usuário) |
+| —    | <slug-4>                | #<N5> (Lead)           | —               | SKIPPED (aguardando Spec) |
+| O_2  | <slug-3>                | #<N4> (Lead)           | <haiku|sonnet>  | Aguardar O_1 |
+```
+
+Se houver mais de uma onda, explique **por que** cada grupo da onda `O_2+` depende de um grupo de
+onda anterior (cite a issue/menção que fundamentou a heurística). Se todos os grupos couberem em
+`O_1`, omita a coluna de justificativa — é o caso comum, sem dependências detectadas.
+
+Se o plano incluir issues do grupo "recomendadas pelo agente" (Fase 1) — porque não havia issues
+pedidas pelo usuário pendentes, ou como itens extras opcionais —, sinalize cada uma delas na coluna
+"Ação" (ex.: "Despachar (recomendação do agente)") para que a aprovação distinga claramente as duas
+origens.
+
+#### Teto de workers simultâneos
+
+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.
+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)
+   - `"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.
+3. **Armazene como `N`** para a Fase 4; vale para toda a sessão de dispatch, incluindo redespachos.
+   Em modo de retomada, repita a pergunta antes de despachar qualquer `QUEUED`. O valor **não
+   persiste** em `.claude/vetor/config.json`.
+
+#### Obtenção de aprovação
+
+**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 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.
+
+**Pare** até a aprovação. Respeite trocas manuais de modelo ou de teto no dispatch da Fase 4.
+
+### 3 — Fase de criação (nativa e serializada)
+
+⚠️ **Esta fase é serializada** para evitar `git index lock` ao inicializar os worktrees nativos.
+
+A criação e a **localização** do worktree são do harness (`isolation: "worktree"` na Fase 4) — não
+assuma path de worktree. O coordenador deriva apenas:
+1. **Slug:** kebab-case derivado da Lead Issue (máx 30 chars).
+2. **Branch:** `<type>/<issue#>-<slug>` da Lead Issue — o worker a cria como primeiro passo (`git checkout -b <branch>`).
+3. **Status File Path (absoluto, no root do repo):**
+   `<repo-root>/.claude/vetor/status/<branch com / trocada por ->.md` — fica fora do worktree;
+   formato em `../shared/references/agent-status.template.md`.
+
+⚠️ **O slug é só nominal — não é o path do worktree.** Ele serve apenas para compor o nome da branch
+e o do arquivo de status. **Nunca** infira que o worktree está em `.claude/worktrees/<slug>/` ou
+qualquer convenção derivada do slug: obtenha o path real via `git worktree list` (correlacionando
+pela branch) ou pelo retorno do `Agent()`.
+
+### 4 — Fase de desenvolvimento (paralela, com teto de concorrência e ondas)
+
+- Ordene os grupos por prioridade (ex.: ordem das issues no label) **dentro de cada onda** (Fase 1).
+- Despache em paralelo até `N` grupos, **estritamente dentro da onda corrente** (`O_i`). Grupos de
+  `O_{i+1}` ou posterior nunca são despachados enquanto houver grupo de `O_i` ainda não mergeado —
+  mesmo que haja vagas no teto `N`. Eles ficam `QUEUED (aguardando O_i)` na tabela (Fase 5.a).
+- 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.
+- **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`
+     sem resolução bloqueia a transição; trate como pendência a reportar, não avance a onda para não
+     repetir o branch skew que motivou esta seção. Um grupo `SKIPPED (aguardando Spec)` (gate de
+     Spec/design, Fase 2) **nunca** conta como pendência aqui — nunca foi despachado, então não há
+     branch/merge dele para a próxima onda esperar.
+  2. O branch default (`$DEFAULT_BRANCH`) estiver sincronizado com esses merges. `git fetch && git
+     log origin/<default> -1` confirma que o *remoto* já tem os merges — mas não garante que o HEAD
+     *local* do root os tenha: `isolation: "worktree"` cria o novo worktree a partir do HEAD local
+     do root (não de `origin/$DEFAULT_BRANCH` diretamente). Complete a checagem comparando os dois
+     antes do primeiro dispatch de `O_{i+1}`:
+     ```bash
+     git fetch origin "$DEFAULT_BRANCH"
+     git rev-parse HEAD                       # HEAD local do root
+     git rev-parse "origin/$DEFAULT_BRANCH"   # último commit do remoto
+     ```
+     Se divergirem (root atrasado), rode `bash "$SKILL_DIR/../../scripts/vetor-checks.sh" sync-root`
+     e **repita a comparação acima** — `sync-root` sai com código 0 mesmo quando recusa avançar (ex.:
+     mudanças locais pré-existentes não commitadas no root, alheias a este trabalho de coordenação —
+     causa raiz confirmada na issue #244); não trate o exit 0 como prova de que o HEAD avançou. Se,
+     mesmo após o `sync-root`, o root continuar atrasado (dirty state não resolvido ou branch não
+     mesclável), **não bloqueie o dispatch por conta disso**: essa condição é exatamente o motivo do
+     passo obrigatório abaixo em "Prompt de execução sequencial para o worker" — cada worker de
+     `O_{i+1}` sincroniza com `origin/$DEFAULT_BRANCH` por conta própria, como primeiro passo padrão
+     (não recuperação ad-hoc), então a divergência do root deixa de ser bloqueante para o dispatch.
+- Se, apesar da heurística da Fase 1, um worker de uma onda posterior reportar erro de compilação por
+  dependência ausente de um grupo anterior ainda não mergeado, isso é sinal de dependência não
+  detectada: pause o grupo, registre no relatório e corrija o agrupamento em ondas para a próxima
+  sessão.
+
+⚠️ **Checagem de duplicidade (antes de cada dispatch).** Rode
+`bash "$SKILL_DIR/../../scripts/vetor-status.sh"` e cruze as issues do grupo candidato contra as
+já reportadas como em andamento (`Iteration: N/5 (Issue #<M>)`) em status files ativos (`RUNNING`,
+`BLOCKED_WAITING`, ou `GREEN` ainda não mergeado). Se qualquer issue do grupo já aparecer em um
+worktree ativo: alerte (`⚠️ Issue #<M> já está em andamento no worktree/branch <outra-branch> —
+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>`.
+
+```javascript
+Agent({
+  description: "Grupo Lead #<N>: <título>",
+  prompt: "...",
+  subagent_type: "vetor:issue-worker",
+  model: "<haiku|sonnet>",
+  isolation: "worktree",
+  run_in_background: true
+})
+```
+
+**Escolha do `model`:** `haiku` se todas as issues do grupo forem `chore` ou `fix` simples; `sonnet`
+se houver `feat`, `refactor` ou mais de 2 issues complementares. Se esgotar iterações, redespache
+uma vez com `sonnet`.
+
+⚠️ **`isolation: "worktree"` é só para dispatch inicial (worktree ainda não existe).** Se o worktree
+já existe — retomada de sessão, redespacho após `BLOCKED_WAITING` ou após `FAILED_MAX_ITERATIONS`, ou
+recuperação de um worker travado em plan mode (sintoma: status parado em `RUNNING`, sem iteração nova
+nem commit — descarte a sessão travada) — **NÃO use `vetor:issue-worker`**: ele força worktree novo
+via frontmatter. Despache um subagente padrão sem `subagent_type`, instruindo-o com a skill
+`fix-loop-agent` no prompt e um `cd` explícito para o path real do worktree (via `git worktree list`):
+
+```javascript
+Agent({
+  description: "Grupo Lead #<N>: <título> (Resumo)",
+  prompt: "Entre no diretório <path> e retome o trabalho usando a skill fix-loop-agent...",
+  model: "<haiku|sonnet>",
+  run_in_background: true
+})
+```
+
+⚠️ **Colisão de migrations paralelas.** Workers paralelos **dentro da mesma onda** que tocam módulos
+com versionamento sequencial de arquivos (ex.: Flyway `V<N>__*.sql`) podem gerar colisões invisíveis
+ao git. A rede de segurança é o merge serializado (Fase 6) somado à checagem 2.b do `worktree-ship`.
+Já a colisão **entre ondas** (grupo de `O_2` sem visibilidade das migrations de `O_1`) é o problema
+que as Ondas de Despacho (Fase 1) previnem estruturalmente, ao só liberar `O_2` depois do merge e
+sincronismo do branch default com `O_1`.
+
+**Nota (Antigravity):** o `issue-worker` também é registrado via `agents/issue-worker/agent.json`
+(`customAgentSpec`). Como define `tools:` explicitamente, **não** herda MCP do contexto pai — se um
+worker precisar de MCP, adicione-o à lista.
+
+**Prompt de execução sequencial para o worker:**
+1. **Lead Issue:** #<N> (título, descrição, critérios de aceite).
+2. **Issues Sequenciais:** #<M1>, #<M2> (idem).
+3. **Branch:** `<type>/<issue#>-<slug>` — criar como primeiro passo no worktree.
+4. **Status File Path:** o path absoluto da Fase 3, atualizado a cada iteração de cada issue
+   (ex.: `Iteration: 2/5 (Issue #<M1>)`). Instrua o worker explicitamente:
+   > Escreva o status file no path absoluto `<status-file-path>`. Se a plataforma rejeitar com
+   > mensagem como *"Edit the worktree copy..."* ou qualquer bloqueio de escrita fora do worktree,
+   > salve também uma cópia dentro do worktree em `.claude/vetor-status.md`. Se apenas a cópia local
+   > foi gravada, sinalize no chat.
+5. **Sincronização com origin (obrigatória a partir de `O_2`).** Se este dispatch pertence a uma
+   onda `O_{i+1}` posterior à primeira, inclua no prompt, como **primeiro passo padrão logo após o
+   `git checkout -b`** — não como recuperação ad-hoc descoberta pelo próprio worker (issue #244):
+   > Antes de investigar o escopo da issue, rode `git fetch origin $DEFAULT_BRANCH` e compare com o
+   > seu HEAD (`git log origin/$DEFAULT_BRANCH -1` vs `git log HEAD -1`). Se o seu worktree nasceu
+   > de um commit anterior aos merges das ondas anteriores, sincronize agora (`git merge
+   > origin/$DEFAULT_BRANCH` ou `git rebase origin/$DEFAULT_BRANCH`) antes de procurar qualquer
+   > arquivo — issues desta onda podem depender de arquivos criados por PRs de ondas já mergeadas.
+   Isso vale mesmo que o coordinator já tenha checado a sincronia do root na Transição de onda: o
+   worktree é criado a partir do HEAD local do root no momento do dispatch (`isolation: "worktree"`
+   é 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.
+
+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.
+
+### 5 — Monitoramento
+
+**5.a — Tabela de status**
+
+```bash
+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)
+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
+vaga no teto `N`.
+
+⚠️ **Fallback de leitura.** Se o status file no path absoluto não existir ou estiver desatualizado
+para um worktree ativo, leia `<path-do-worktree>/.claude/vetor-status.md` (path via
+`git worktree list`).
+
+⚠️ **Workers duplicados.** Extraia o número de issue de cada `Iteration: N/5 (Issue #<M>)` dos status
+files ativos e cruze-os. Se a mesma issue aparecer em mais de um worktree ativo, sinalize:
+`⚠️ Issue #<M> em andamento simultaneamente em <slug-A> e <slug-B> — possível dispatch duplicado` e
+avalie com o usuário qual worker continua.
+
+**5.b — Escalação de bloqueios**
+
+**A fonte de verdade da escalação é o status file.** Se um worker sinalizar bloqueio apenas por
+chat, **não escale ainda**: instrua-o via `SendMessage` a gravar o `BLOCKED_WAITING` estruturado
+(`Blocked on` / `Options` / `Recommendation`) primeiro, para que o estado sobreviva a um reinício.
+
+**Em `--headless`: não escale.** Registre no relatório final o agente (`<slug>` / Issue `#<N>`), o
+motivo do bloqueio e a recomendação do worker. Não conceda permissão, não escolha opção técnica e
+não redespache. Nunca mate um worker bloqueado para abrir vaga no teto `N`.
+
+Fora do headless, leia o bloco `Blocked on` / `Options` / `Recommendation` e escale via
+`AskUserQuestion`, identificando o agente e transmitindo a recomendação. Opções conforme o tipo:
+- **Permissão bloqueada** (`<comando>`): permitir esta vez / permitir para este agente (auto-aprova
+  chamadas similares dele) / negar (registra "skipped") / parar agente.
+- **Decisão técnica**: as opções do bloco `Options`.
+
+Comunique a decisão ao sub-agente via `SendMessage`. Se a resposta exigir redespachar em worktree
+existente, siga a nota de redispatch da Fase 4.
+
+**5.c — Circuit Breaker**
+
+Se 2 ou mais agentes falharem com `FAILED_MAX_ITERATIONS` apresentando assinaturas de erro idênticas
+(ex.: falha de rede do gerenciador de pacotes, erro de linkagem global), acione o circuit breaker:
+pause os subagentes ativos e pergunte:
+`⚠️ Circuit Breaker acionado devido a falhas recorrentes com erro similar. Deseja pausar para investigar ou prosseguir mesmo assim?`
+
+**Em `--headless`: não pergunte — sempre pause.** Pare de despachar `QUEUED`, deixe os ativos
+terminarem e vá para o relatório destacando a assinatura de erro comum.
+
+### 6 — Fase de merge (serializada)
+
+⚠️ **Serializada** — um merge por vez. ⚠️ **Em `--headless` esta fase inteira é pulada**: liste os
+grupos `GREEN` no relatório final com branch e path do worktree, e encerre.
+
+Quando um agente atingir `GREEN`:
+
+1. Verifique que o worker está de fato verde (leia o status file).
+2. `/vetor:worktree-ship` aborta se o `cwd` não for um worktree, e o contexto do coordinator é o root
+   do repo. Entre no worktree antes de invocar:
+   ```bash
+   git worktree list   # localize a linha cuja branch é a do grupo (Fase 3)
+   cd <path-do-worktree-do-grupo>
+   ```
+   Só então:
+   ```
+   /vetor:worktree-ship <issue#>
+   ```
+3. Após merge bem-sucedido, atualize a tabela.
+
+Se `worktree-ship` falhar (CI vermelho, review required), marque na tabela e continue com os outros.
+
+### 7 — Relatório final
+
+**Antes do relatório, volte ao root e sincronize.** A Fase 6 faz `cd` para dentro do worktree de
+cada grupo; sem um retorno explícito, a sessão termina com o git preso na branch de um worktree —
+possivelmente já mergeada e obsoleta.
+
+```bash
+cd "$(git worktree list | head -1 | awk '{print $1}')"   # a 1ª linha é sempre o root
+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):
+
+```
+## Coordinator Report
+
+| Issue | Resultado | PR | Detalhes |
+|-------|----------|-----|----------|
+| #42 | ✅ Merged | #87 | squash merged |
+| #43 | ❌ CI failed | #88 | 3 fix attempts, worktree preserved |
+| #44 | ⏸️ Review required | #89 | awaiting human review |
+| #45 | ⏭️ SKIPPED (aguardando Spec) | — | gate de Spec/design, Fase 2 — usuário optou por gerar a Spec antes |
+
+Resumo: <N> merged, <M> falharam, <K> aguardando review, <J> aguardando Spec.
+```
+
+**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
+  bloqueada — mesma marca `⚠️ sem Spec associada` da coluna "Ação" do plano.
+- O teto `N` usado e como foi calculado.
+- Para cada `GREEN`: branch e path do worktree, marcados como **prontos para ship**.
+- Para cada `BLOCKED_WAITING`: o bloqueio e a recomendação do worker.
+- Se o circuit breaker disparou: a assinatura de erro comum e os grupos não despachados.
+
+---
+
+## Orçamentos e hard caps
+
+- **fix-loop-agent:** 5 iterações é **orçamento sugerido**, não hard cap enforced — nada no hook
+  interrompe o agente automaticamente (issue #156). Ao atingir a 5ª iteração sem verde, o agente
+  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)
+- 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.
+
+O teto de workers simultâneos **não é um hard cap**: é o valor `N` decidido pelo usuário na Fase 2
+(default recomendado `maxConcurrentWorkers` de `.claude/vetor/config.json`, senão 5).
+
+---
+
+## Restrições
+
+- `worktree-create` e fase de merge são **sempre serializados**
+- Fonte de verdade para status: status files (`.claude/vetor/status/`) + `gh pr list` + `gh pr checks`
+- Nunca chama `EnterWorktree`/`ExitWorktree` por sub-agentes
+- Se interrompido, reconstrói estado com `vetor-status.sh` + `gh pr list` — não depende de memória
+- Ao fim de toda sessão (Fase 7), o root fica na branch principal e sincronizado — nunca preso numa
+  branch de worktree de grupo
+- Em `--headless`: nunca chama `AskUserQuestion` nem `ExitPlanMode`, nunca faz merge/ship, nunca
+  auto-aprova permissão. Se o contexto exigir uma decisão que o headless não pode tomar, registre no
+  relatório e pare — não improvise
+- O gate de Spec/design (Fase 2) nunca bloqueia o dispatch em `--headless` — vira sinalização
+  registrada no plano/relatório, nunca um `AskUserQuestion` síncrono (mesmo motivo do item acima:
+  deadlock por falta de interlocutor, issue #121)