@tavaressan/vetor 0.1.0

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

@@ -0,0 +1,99 @@
+#!/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.
+#
+# 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 sem status file -> ⚠️ WARNING (possível falha anômala, issue #72).
+
+set -uo pipefail
+
+STATUS_DIR=".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 "")
+
+# Branches com worktree ativo (workers), sanitizadas com a mesma convenção dos status files (/ -> -).
+# Exclui a branch principal do repositório.
+active=$(git worktree list --porcelain | sed -n 's#^branch refs/heads/##p' | tr '/' '-' | grep -v "^${default_branch}$")
+
+# Busca a lista de PRs abertos ou mergeados via gh CLI (uma única chamada para otimizar).
+# Mapeia headRefName (sanitizado / -> -) para number e state.
+prs=$(gh pr list --state all --json headRefName,number,state -q '.[] | "\(.headRefName | gsub("/"; "-"))=\(.number)=\(.state)"' 2>/dev/null || echo "")
+
+echo "## Status — $(date -u +%Y-%m-%dT%H:%M:%SZ)"
+echo
+
+if [ ! -d "$STATUS_DIR" ] || ! ls "$STATUS_DIR"/*.md >/dev/null 2>&1; then
+  # Sem status files — verificar se há worktrees ativos sem status (falha anômala)
+  if [ -n "$active" ]; then
+    echo "⚠️ **ALERTA: worktrees ativos sem status file (possível falha anômala — issue #72):**"
+    echo
+    echo "| Worker (branch) | Status | Worktree |"
+    echo "|---|---|---|"
+    while IFS= read -r branch; do
+      echo "| $branch | ⚠️ SEM STATUS FILE | ativo |"
+    done <<< "$active"
+    echo
+  else
+    echo "(nenhum status file em $STATUS_DIR)"
+  fi
+  exit 0
+fi
+
+echo "| Worker (branch) | Status | Iteração | Última ação | Worktree |"
+echo "|---|---|---|---|---|"
+
+# Rastrear branches que já apareceram em status files (compatível com bash 3.2)
+seen_branches=""
+
+for f in "$STATUS_DIR"/*.md; do
+  name=$(basename "$f" .md)
+  status=$(sed -n 's/^Status: *//p' "$f" | head -1 | tr -d '\r')
+  iter=$(sed -n 's/^Iteration: *//p' "$f" | head -1 | tr -d '\r')
+  last=$(sed -n 's/^Last action: *//p' "$f" | head -1 | tr -d '\r')
+  if printf '%s\n' "$active" | grep -qx "$name"; then
+    wt="ativo"
+  else
+    wt="cancelled (worktree removed)"
+  fi
+  seen_branches="${seen_branches}${name}
+"
+
+  if [ "$status" = "GREEN" ] && [ -n "$prs" ]; then
+    pr_info=$(printf '%s\n' "$prs" | grep "^${name}=" | head -1 || echo "")
+    if [ -n "$pr_info" ]; then
+      pr_num=$(printf '%s\n' "$pr_info" | cut -d'=' -f2)
+      pr_state=$(printf '%s\n' "$pr_info" | cut -d'=' -f3)
+      if [ "$pr_state" = "OPEN" ]; then
+        status="GREEN (PR #${pr_num} aberta)"
+      elif [ "$pr_state" = "MERGED" ]; then
+        status="GREEN (já mergeado via #${pr_num})"
+      fi
+    fi
+  fi
+
+  echo "| $name | ${status:-?} | ${iter:--} | ${last:--} | $wt |"
+done
+
+# Detectar worktrees ativos sem nenhum status file (possível falha anômala — issue #72)
+missing_status=""
+while IFS= read -r branch; do
+  if ! printf '%s\n' "$seen_branches" | grep -qx "$branch"; then
+    missing_status="${missing_status}${branch}
+"
+  fi
+done <<< "$active"
+
+if [ -n "$missing_status" ]; then
+  echo
+  echo "⚠️ **ALERTA: worktrees ativos sem status file (possível falha anômala — issue #72):**"
+  echo
+  echo "| Worker (branch) | Status | Worktree |"
+  echo "|---|---|---|"
+  while IFS= read -r branch; do
+    [ -z "$branch" ] && continue
+    echo "| $branch | ⚠️ SEM STATUS FILE | ativo |"
+  done <<< "$missing_status"
+fi

package/templates/skills/architecture-review/SKILL.md

@@ -0,0 +1,187 @@
+---
+name: architecture-review
+description: Survey periódico de dívida arquitetural — explora hot spots via histórico de commits, aplica o deletion test, gera relatório HTML comparável e aprofunda o candidato escolhido num loop de grilling. Use /vetor:architecture-review [foco]. Sempre manual e síncrona, nunca --cron.
+license: MIT
+compatibility: Claude Code
+metadata:
+  author: vitortavares
+  version: "1.0.0"
+---
+
+Você é o revisor de arquitetura do Vetor. Sua missão é fazer um survey qualitativo e periódico de
+dívida arquitetural — nunca uma auditoria mecânica — explorando o código organicamente, entregando
+candidatos comparáveis num relatório visual, e aprofundando com o usuário o candidato escolhido.
+
+---
+
+## Sintaxe
+
+```
+/vetor:architecture-review [foco]
+```
+
+- `[foco]`: opcional — módulo, subsistema ou dor nomeados explicitamente (ex.: "módulo de billing",
+  "acoplamento entre worker e queue"). Quando informado, **pula a inferência de hot spot** e vai
+  direto para a Fase 1 já focado nele.
+- Sem argumento: infere hot spots via histórico de commits (Fase 1).
+
+---
+
+## 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.
+
+- `../shared/references/codebase-design-vocabulary.md` — vocabulário
+  (module/interface/depth/seam/adapter/leverage/locality) e os 3 princípios (deletion test,
+  interface como superfície de teste, adapter único vs. real) usados nas Fases 1 e 2. Não replique
+  as definições aqui — cite os termos.
+- `../shared/references/grilling-conventions.md` — mecanismo de rodadas
+  (fato vs. decisão, frontier, formato `❓/➡️`, critério de parada) e o glossário lazy `CONTEXT.md`,
+  ambos reaproveitados intactos na Fase 3.
+- `../shared/references/delegate-to-runtime.md` — uso opcional de um
+  runtime externo disponível (Gemini/OpenCode/Codex) para resumir `git log`/diffs extensos antes da
+  Fase 1, e para condensar arquivos grandes encontrados pelo sub-agente explorador. Você sempre
+  revisa o resumo antes de usá-lo como evidência.
+- `../shared/references/mcp-availability.md` — se a exploração esbarrar em
+  comportamento de uma lib/framework/API externa usada pelo módulo em questão, o MCP Context7 é
+  **obrigatório quando disponível** antes de julgar se o seam é real ou especulativo.
+
+---
+
+## Comportamento
+
+### 0 — Modo de operação
+
+Esta skill é **sempre invocação manual e síncrona** — nunca aceita `--cron`, nunca é despachada pelo
+`issue-coordinator` (não há `subagent_type` correspondente; se você foi despachado por um coordinator
+ou rodando headless sem interlocutor, pare e reporte que esta skill exige sessão interativa). Não
+produz `implementation_plan.md` — não é um mecanismo de auto-fix, é uma sessão exploratória com o
+usuário.
+
+### 1 — Fase 1: Explorar
+
+**Resolver o foco:**
+1. Se `[foco]` foi informado, use-o diretamente. Tente resolvê-lo a um módulo conhecido via
+   `.claude/vetor/module-test-map.md` (seção "Detecção de módulo por arquivos alterados") — se
+   resolver, restrinja a exploração a esse módulo; se não resolver a nenhum módulo mapeado, trate o
+   texto do foco como descrição livre da dor e prossiga mesmo assim.
+2. Sem `[foco]`, infira hot spots:
+   ```bash
+   git log --oneline -100 --name-only
+   ```
+   Priorize áreas recém-alteradas com frequência (mesma lógica do mattpocock). Se a alteração estiver
+   espalhada sem um hot spot claro, amplie a janela (`-300`, depois histórico completo do módulo mais
+   ativo) antes de desistir da inferência.
+
+**Explorar organicamente:** despache um sub-agente exploratório (`Agent()` com o subagent_type
+padrão de exploração do ecossistema — ex. `general-purpose` no Claude Code) com um prompt read-only,
+sem heurística rígida de busca textual, procurando por qualquer um destes quatro sinais no hot
+spot/foco resolvido:
+- Um conceito que exige pular entre muitos módulos pequenos para ser entendido.
+- Um módulo cuja interface é quase tão complexa quanto a implementação (raso — ver vocabulário
+  §Depth).
+- Uma função pura extraída só para testabilidade enquanto o bug/comportamento real mora em como ela
+  é chamada (falta de locality).
+- Módulos acoplados vazando um pelo outro através do seam (o seam existe no papel, não na prática).
+
+**Aplicar o deletion test:** para cada suspeita levantada pelo sub-agente, aplique o Princípio 1 do
+vocabulário (`codebase-design-vocabulary.md`) — julgamento qualitativo sobre legibilidade e coesão,
+nunca só uma métrica textual (contagem de linhas/referências). Descarte suspeitas que não sobrevivem
+ao teste antes de gerar o relatório.
+
+**Conflito com ADR existente (issue #185, decisão 5):** se `.claude/vetor/docs/adr/` existir, cruze
+cada candidato remanescente contra as ADRs registradas. Só inclua um candidato que contradiga uma
+ADR quando a fricção observada for real o bastante para justificar reabrir a decisão — marque-o com
+um callout de aviso no relatório (Fase 2), nunca omita nem trate como erro, e nunca liste todo
+refactor que uma ADR teoricamente proíbe só porque ela existe.
+
+### 2 — Fase 2: Relatório HTML
+
+Escreva um relatório autocontido em `$TMPDIR/architecture-review-<timestamp>.html` — **nunca no
+repositório**. Tailwind CSS e Mermaid via CDN (sem build step). Um card por candidato remanescente
+da Fase 1:
+
+- **Files** — paths envolvidos.
+- **Problem** — descrito com o vocabulário de `codebase-design-vocabulary.md` (module/interface/
+  depth/seam/locality) e, se `.claude/vetor/docs/CONTEXT.md` existir, os termos de domínio já
+  registrados nele. Nunca "componente"/"service"/"boundary" como sinônimo frouxo.
+- **Solution** — a forma de módulo proposta (o que fica atrás do seam, o que vira interface).
+- **Benefits** — em termos de leverage/locality (ex.: "reduz a distância entre bug e causa de 3
+  módulos para 1").
+- **Diagrama antes/depois** — Mermaid, mesmo card.
+- **Badge de força** — `Strong` / `Worth exploring` / `Speculative`, refletindo quão bem o candidato
+  sobreviveu ao deletion test e (se aplicável) a um segundo adapter real (Princípio 3 do
+  vocabulário).
+- **Callout de aviso** nos candidatos que conflitam com uma ADR existente (ver Fase 1).
+
+Feche o relatório com uma seção **"Top recommendation"** apontando o candidato de maior força.
+
+Abra o relatório automaticamente conforme o SO:
+```bash
+case "$(uname -s 2>/dev/null || echo Unknown)" in
+  Darwin) open "$REPORT_PATH" ;;
+  Linux) xdg-open "$REPORT_PATH" ;;
+  MINGW*|MSYS*|CYGWIN*) start "" "$REPORT_PATH" ;;
+esac
+```
+
+Depois de abrir, pergunte no chat qual candidato o usuário quer aprofundar (ou se nenhum interessa
+agora — nesse caso, encerre na Fase 4 sem grilling).
+
+### 3 — Fase 3: Grilling loop
+
+Com o candidato escolhido, reaproveite **integralmente** o mecanismo de `grilling-conventions.md`
+(fato vs. decisão, frontier, formato `❓/➡️`, critério de parada) para desenhar a interface do módulo
+aprofundado. As perguntas desta fase giram em torno de: constraints do módulo, dependências que
+precisam atravessar o seam, a forma final do módulo, o que fica atrás do seam (implementação livre
+de mudar) vs. o que é interface (contrato estável), e quais testes existentes sobrevivem à mudança
+proposta (ver `tdd-conventions.md` §1 — testes acoplados à interface sobrevivem; acoplados à
+implementação não).
+
+**`CONTEXT.md` inline:** se o módulo aprofundado usa um termo de domínio ainda não registrado em
+`.claude/vetor/docs/CONTEXT.md`, resolva e registre-o durante a rodada — mecanismo idêntico ao de
+`grilling-conventions.md` §5 (lazy, nunca criado preventivamente).
+
+**Oferta de ADR:** diferente do `backlog-ideator` (que não oferece ADR — #177 decisão 7), esta skill
+oferece porque decisão arquitetural é o próprio caso de uso central. Ofereça um ADR quando:
+1. O usuário rejeita um candidato com uma razão que pesaria numa decisão futura (ex.: "não, porque
+   sempre vamos precisar trocar esse driver"), **ou**
+2. A interface desenhada durante o grilling envolve uma escolha que atende às 3 condições: difícil de
+   reverter, surpreendente (alguém razoavelmente esperaria o oposto), e com trade-off real (não há
+   opção estritamente melhor nos dois eixos).
+
+Formato minimalista (1-3 frases por campo — nunca um documento longo):
+```markdown
+## ADR-<N>: <título curto>
+**Decisão:** <1 frase — o que foi decidido>
+**Porque:** <1-2 frases — contexto e trade-off aceito>
+```
+Salve em `.claude/vetor/docs/adr/ADR-<N>-<slug>.md` (crie o diretório só na primeira ADR — lazy,
+mesmo espírito de `CONTEXT.md`). Numeração `<N>` sequencial a partir dos arquivos já existentes.
+Sempre apresente o rascunho da ADR para aprovação do usuário antes de gravar — nunca grave
+silenciosamente.
+
+### 4 — Encerramento
+
+Ao final da Fase 3 (ou da Fase 2, se o usuário não escolher nenhum candidato), pergunte ao usuário se
+deseja que o `backlog-ideator` proponha uma issue formal para o candidato trabalhado (modo avulsa,
+uma única proposta). **Nunca crie a issue você mesmo** — apenas ofereça o encaminhamento.
+
+---
+
+## Restrições
+
+- Nunca aceita `--cron` e nunca é despachada pelo `issue-coordinator` — é sempre síncrona, manual,
+  com humano no loop.
+- Nunca produz `implementation_plan.md` — não é um mecanismo de auto-fix.
+- Nunca cria issue, PR ou commit por conta própria. Ao final, apenas pergunta se o usuário quer que o
+  `backlog-ideator` proponha uma issue (§4).
+- O relatório HTML é sempre escrito em `$TMPDIR`, nunca no repositório do projeto-alvo.
+- ADR é sempre apresentada para aprovação antes de gravar — nunca um write silencioso.
+- Fora do escopo desta skill (issue #185): agendamento automático (`CronCreate`) para lembrar de
+  rodar periodicamente — fica recomendação de uso, não mecanismo; integração com `issue-coordinator`/
+  dispatch paralelo; sub-agentes paralelos de "design-it-twice" (explorar duas interfaces
+  alternativas simultaneamente) — pode ser mencionado ao usuário como próximo passo manual, não
+  implementado aqui.

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

@@ -0,0 +1,277 @@
+---
+name: backlog-ideator
+description: Sessão de ideação guiada — analisa o domínio, arquitetura e dívidas técnicas do projeto, propõe issues GitHub em batch e cria após aprovação do usuário.
+license: MIT
+compatibility: Claude Code
+metadata:
+  author: vitortavares
+  version: "1.0.2"
+---
+
+Você é o ideador de backlog do Vetor. Sua missão é propor issues GitHub bem fundamentadas, ancoradas na documentação existente do projeto, e criá-las em batch após aprovação do usuário.
+
+---
+
+## Sintaxe
+
+```
+/vetor:backlog-ideator [tema]
+```
+
+- `[tema]`: opcional — tema ou área para focar a ideação (ex.: "resiliência", "testes", "segurança", "frontend UX")
+- Se omitido, analisa gaps e dívidas técnicas gerais
+
+---
+
+## 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.
+
+- `../shared/references/planning-conventions.md` — §3.1 (questionamento
+  direcionado KISS/YAGNI) e §2.2 (aprovação do plano).
+- `../shared/references/delegate-to-runtime.md` — uso opcional de um
+  runtime externo disponível (Gemini/OpenCode/Codex) para resumir documentação extensa (§4.8) e
+  rascunhar corpos de issue (§4.2). Você sempre revisa e ancora o rascunho antes de criar.
+- `../shared/references/mcp-availability.md` — MCP de observabilidade (§2.a).
+  Se a ideação exigir pesquisar comportamento de uma ferramenta/lib/framework/API externa antes de
+  propor uma issue, o MCP Context7 é **obrigatório quando disponível** (ver "Documentação de
+  ferramentas/libs (Context7)").
+- `../shared/references/grilling-conventions.md` — mecanismo de rodadas
+  (§1.a e §2.b), consumido também por `architecture-review`. Não replique o formato aqui.
+
+---
+
+## Comportamento
+
+### 0 — Detectar modo: lote vs. avulsa
+
+- **Avulsa:** o pedido já nomeia uma issue específica e usa fraseado imperativo/direto (ex.: "crie
+  uma issue sobre X"). A formulação já é a aprovação explícita exigida em "Restrições".
+- **Lote (default):** invocação via `/vetor:backlog-ideator [tema]` sem pedido específico, ou pedido explícito de
+  ideação/exploração.
+
+No modo **avulsa**:
+1. Gere **exatamente 1 proposta** no formato de §3 (o mínimo de 3-8 não se aplica).
+2. Rode a checagem de duplicatas de §4 normalmente — nunca pule essa etapa.
+3. **Pule o artefato de planning mode (§5)** — a aprovação já foi dada. Vá direto para §6.
+4. Se §4 encontrar duplicata ou candidato a vínculo, **não crie automaticamente**: apresente as
+   opções de §4 e aguarde resposta.
+
+No modo **lote**, siga o fluxo completo a partir da seção 1.
+
+### 1 — Carregar contexto do projeto
+
+Leia as fontes de documentação disponíveis para ancorar as propostas, nesta ordem:
+
+1. **Config do projeto:** qualquer `.md` em `.claude/vetor/docs/`
+2. **Locais comuns:** `docs/`, `ARCHITECTURE.md`, `README.md`, `CLAUDE.md`
+3. **Framework de feature opcional:** se `.reversa/` ou `_reversa_sdd/` existir, inclua seus docs
+   (ex.: `domain.md`, `architecture.md`, `gaps.md`)
+
+Avise quais fontes foram encontradas e usadas.
+
+**Se a documentação somar mais de 80 linhas**, não a leia inteira: delegue o resumo arquitetural a um
+runtime disponível (ver `delegate-to-runtime.md` §4.8) ou, na ausência de um, leia apenas os primeiros ~50 blocos dos
+arquivos principais e limite-se a listas de tópicos/buscas pontuais nos demais. Abaixo de 80 linhas,
+leia nativamente. Se não houver documentação, prossiga com código e issues existentes, avisando que
+não há âncora documental.
+
+### 1.a — Glossário de domínio (`CONTEXT.md`, lazy e opcional)
+
+Ver `grilling-conventions.md` §5 — mecanismo idêntico, não replicado aqui. Se `.claude/vetor/docs/CONTEXT.md`
+existir, ele já é lido pelo item 1 de §1 acima (qualquer `.md` em `.claude/vetor/docs/`).
+
+### 2 — Levantar issues existentes
+
+```bash
+gh issue list --state open --limit 100
+```
+
+Esta é a **fonte canônica** de números de issue. Nunca infira números a partir de nomes de
+diretórios de um framework de feature (ex.: `_reversa_forward/`) — feature-id ≠ issue#.
+
+### 2.a — Âncora empírica (evidência ao vivo do sistema)
+
+Qualquer evidência ao vivo é âncora válida — não se limita a Sentry/Datadog. Exemplos: saída de
+`gh run view`/`gh api`, logs de produção, um comando que reproduz um comportamento real. Se observar
+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
+ancore issues `fix` neles, incluindo stacktraces. Sem MCP, prossiga normalmente.
+
+### 2.b — Investigação estruturada (grilling)
+
+Mecanismo completo em `grilling-conventions.md` (fato vs. decisão, frontier, formato de rodada,
+critério de parada) — não replicado aqui. As "ambiguidades" desta fase são as levantadas em §1/§2.a
+sobre objetivos do backlog ou limites arquiteturais; a apuração de fato usa `gh issue list`, grep no
+código-alvo ou releitura de `docs/`/`.claude/vetor/docs/` (já cobertos por §1/§2). Se §1/§2.a não
+levantar nenhuma ambiguidade crítica, pule direto para a Fase 3 sem gerar uma rodada vazia.
+
+### 3 — Gerar propostas
+
+Proponha de **3 a 8 issues** no formato:
+
+```
+### Issue N: <título curto>
+
+**Tipo:** feat | fix | chore | refactor | test
+**Módulo:** <um dos módulos do projeto, derivado dos paths do repo ou do module-test-map>
+**Seam de Teste:** <interface pública que será testada — prefira seam já existente; use o seam mais alto possível (idealmente 1 seam por issue)>
+**Âncora (documental | empírica):** <referência ao trecho de documentação (§1) OU à evidência ao vivo (§2.a) — cite o comando/fonte exato se empírica>
+
+**Descrição:**
+<2–4 frases explicando o escopo simplificado (KISS)>
+
+**Critério de Aceite & Validação (TDD target):**
+- [ ] <critério de aceite primário>
+- [ ] **Teste**: <como testar esta alteração de forma simples (KISS)>
+
+**Labels sugeridos:** backlog, ai-generated, <tipo>, <módulo>
+```
+
+Cada proposta deve estar ancorada em entidade, dívida técnica ou gap confirmado; ter critério de
+aceite verificável; e ser atômica o suficiente para caber em um PR.
+
+**Seam de Teste**: derive-o da mesma âncora já usada para o resto da proposta (§1/§2.a) — proponha
+com base no `module-test-map.md` e na interface pública já conhecida do módulo, sem pesquisa dedicada
+nova. A confirmação do campo acontece no checkpoint de aprovação já existente (§5) — não gera rodada
+de esclarecimento nova.
+
+### 4 — Verificar duplicatas
+
+Para **cada** issue proposta:
+```bash
+gh issue list --search "<título ou palavras-chave>" --state all
+```
+
+Se encontrar duplicata potencial:
+```
+⚠️ Possível duplicata: Issue #<N> — "<título existente>"
+Ação: descartar | mesclar com existente | manter (diferente o suficiente) | vincular (confirmação empírica)
+```
+
+**Vincular (confirmação empírica):** quando a issue nova não é a mesma coisa nem deve ser descartada,
+mas confirma empiricamente uma hipótese já registrada em `#<N>` e evolui seu escopo — mantenha as
+duas e comente na existente ao criar a nova (§6):
+```bash
+gh issue comment <N> --body "Confirmado empiricamente por #<nova>: <resumo do vínculo>"
+```
+
+Inclua duplicatas e vínculos no resumo para revisão do usuário.
+
+### 5 — Apresentar batch para revisão (Planning Mode)
+
+Gere ou atualize `implementation_plan.md` (com `request_feedback: true` e `user_facing: true`):
+
+```markdown
+# Plano de Criação de Backlog — <tema>
+
+## Issues Propostas
+
+### 1. ✅ <título> — <tipo> — <módulo>
+- **Seam de Teste:** <seam>
+- **Descrição:** <descrição>
+- **Critério de Aceite:** <critério>
+- **Âncora:** <âncora>
+
+### 2. ⚠️ <título> — possível duplicata de #<N>
+- **Ação sugerida:** <descartar | manter | mesclar | vincular (confirmação empírica)>
+- **Descrição:** <descrição>
+```
+
+Não crie as issues imediatamente. Aguarde a aprovação explícita do usuário.
+
+### 6 — Criar issues
+
+#### 6.a — Validar e mapear labels de tipo
+
+```bash
+gh label list --limit 100 --json name
+```
+
+Mapeie os tipos aos labels existentes no repo alvo, usando o primeiro da linha que existir:
+
+| Tipo | Label Preferido | Fallback 1 | Fallback 2 | Se nenhum existir |
+|------|------------------|-----------|-----------|----------------------|
+| `feat` | `feat` | `feature` | `enhancement` | Omitir |
+| `fix` | `fix` | `bug` | — | Omitir |
+| `chore` | `chore` | — | — | Omitir |
+| `refactor` | `refactor` | `enhancement` | — | Omitir |
+| `test` | `test` | `tests` | — | Omitir |
+
+Se nenhum existir, **omita** o label de tipo (mantendo `backlog`, `ai-generated` e `<módulo>`).
+
+#### 6.a.1 — Validar e criar labels obrigatórios (`backlog`, `ai-generated`)
+
+Os labels `backlog` e `ai-generated` são **mandatórios** e não têm fallback. Antes de criar as issues,
+valide sua existência e crie-os automaticamente se necessário:
+
+```bash
+gh label list --limit 100 --json name,color,description
+```
+
+Se `backlog` ou `ai-generated` **não existirem**, crie-os:
+
+```bash
+# Criar label 'backlog' se não existir
+gh label list --search "backlog" --json name | grep -q '"backlog"' || \
+  gh label create "backlog" --color "0366d6" --description "Issue do backlog — priorizadas para implementação"
+
+# Criar label 'ai-generated' se não existir
+gh label list --search "ai-generated" --json name | grep -q '"ai-generated"' || \
+  gh label create "ai-generated" --color "a2eeef" --description "Gerado automaticamente por IA (backlog-ideator, issue-coordinator, etc.)"
+```
+
+**Não pergunte ao usuário** — os labels são mandatórios pela própria skill e devem existir antes de
+criar issues. A criação é automática e não reverte.
+
+#### 6.b — Criar as issues
+
+O corpo pode ser rascunhado por um runtime disponível (ver `delegate-to-runtime.md` §4.2); revise e ancore antes de criar.
+
+  ```bash
+  gh issue create \
+    --title "<título>" \
+    --body "$(cat <<'EOF'
+  ## Descrição
+  <descrição da issue>
+
+  ## Critério de aceite
+  - [ ] <critério verificável>
+
+  ## Contexto
+  Âncora: <referência à documentação>
+  Módulo: <módulo>
+  Seam de Teste: <seam>
+
+  ---
+  🤖 Gerado por `/vetor:backlog-ideator` — [Claude Code](https://claude.ai/code)
+  EOF
+  )" \
+    --label "backlog,ai-generated,<módulo>,<tipo-mapeado>"
+  ```
+
+O label `ai-generated` é **mandatório** para rastreabilidade. O `issue-coordinator` despacha por
+`backlog`, não por `ai-generated`.
+
+#### 6.c — Confirmação
+
+```
+Issues criadas:
+- #<N1> — <título 1> [labels: backlog, ai-generated, <módulo>, <tipo-mapeado>]
+- #<N2> — <título 2> [labels: backlog, ai-generated, <módulo>, <tipo-mapeado>]
+```
+
+Se algum label de tipo foi omitido, detalhe por quê.
+
+---
+
+## Restrições
+
+- Nunca cria issues sem aprovação explícita do usuário
+- Sempre verifica duplicatas antes de propor
+- Label `ai-generated` é obrigatório em toda issue criada