ship

Files (1)

• SKILL.md

SKILL.md (first lines)

Você é o pipeline de entrega do Vetor. Sua missão é levar código testado e verde de um worktree até o merge na branch default, de forma modular e desacoplada em duas etapas (--prepare e --finalize) ou no fluxo sequencial legado de ponta a ponta.

---

## Sintaxe

```
/vetor:ship [--prepare [issue#] | --finalize <PR-number> | [issue#]]
```

- `--prepare [issue#]`: submodo de preparação concorrente (Pre-Ship) — executa validações locais (§1 a §4.b), push da branch (§5), criação de PR draft (§6), disparo em background de CI (§7) e revisões consultivas (§8.5), grava status `PR_STAGED` com o número/URL da PR (§8.7) e encerra sem tentar merge.
- `--finalize <PR-number>`: submodo de finalização (Fast Merge Gate) — verifica CI (§7 e §8) e reviews (§8.5–§9), executa squash merge via `vetor-merge.sh` (§10), sincroniza root determinístico (§11) e executa cleanup do worktree (§12).
- `[issue#]`: execução sequencial monolítica completa legada (passos 1 a 12), mantendo 100% de retrocompatibilidade.

---

## Referências

> Paths relativos abaixo resolvem a partir do diretório desta própria skill (informado ao carregar,
> ex. "Base directory for this skill: ..."), não do `cwd` de execução. Em comandos `bash`/`deno run`,
> prefixe o path absoluto desse diretório ao caminho relativo antes de executar — defina uma vez:
> ```bash
> SKILL_DIR="<path absoluto informado como 'Base directory for this skill' no carregamento>"
> ```
> e use `"$SKILL_DIR/../../scripts/..."` em todo comando abaixo, nunca o path relativo isolado.

- `../shared/references/project-conventions.md` — resolva `$DEFAULT_BRANCH`
  e o `module-test-map` conforme descrito lá. Use `$DEFAULT_BRANCH` em todos os comandos abaixo.
  **A resolução do `module-test-map.md`/`config.json` no passo 4 sempre usa o root do repositório
  (`vetor-checks.sh repo-root`), nunca o `cwd` do worktree** — arquivos ignorados pelo `.gitignore`
  do projeto-alvo (ex.: `.claude/`) não são materializados em worktrees (issue #160).
- `../shared/references/delegate-to-runtime.md` — delegação opcional a um
  runtime externo disponível (Gemini/OpenCode/Codex) para resumo de logs de CI §4.1 e corpo do PR
  §4.4. Se a chamada for **negada pelo classificador de permissão**, ou falhar por qualquer outro
  motivo, não retente: siga com o caminho nativo imediatamente (§3 da referência).
- `../shared/references/conflict-resolution.md` — procedimento de resolução
  de conflitos (passos 2 e 10).
- `../shared/references/mcp-availability.md` — se os módulos alterados
  envolverem UI/frontend e o MCP de browser estiver disponível, use-o no passo 4 como checagem e2e
  leve **adicional** aos testes automatizados, nunca substituta.

---

## Comportamento

### 0 — Validação de argumentos e seleção de modo

```bash
read -r SHIP_MODE SHIP_TARGET < <(bash "$SKILL_DIR/../../scripts/vetor-checks.sh" validate-ship-args "$@")
```

De acordo com `SHIP_MODE`:
- `prepare`: executa os passos 1 a 6, o disparo de CI (§7) e revisões consultivas (§8.5) em background, grava status `PR_STAGED` (§8.7) e encerra com exit 0 sem tentar merge.
- `finalize`: `SHIP_TARGET` contém o `<PR-number>`. Pula os passos 2 a 6 e executa estritamente a verificação de CI (§7 e §8), verificação de reviews (§8.5–§9), squash merge via `vetor-merge.sh` (§10), sincronização do root (§11) e cleanup (§12).
- `full` (modo padrão legado, sem flags): executa o ciclo sequencial completo dos passos 1 a 12 de ponta a ponta. Se `SHIP_TARGET` estiver preenchido, ele representa a issue GitHub a ser referenciada em `Closes #N`.

### 1 — Guarda de contexto

```bash
bash "$SKILL_DIR/../../scripts/vetor-checks.sh" in-worktree
```

Se sair não-zero, **aborte**: `/vetor:ship` deve rodar de dentro de um worktree (use
`/vetor:worktree-create` primeiro). Se passar, guarde a branch atual (`git branch --show-current`).

Este comando **nunca muda de diretório por conta própria** — quem o invoca de outro contexto (ex.:
`coordinator`, cujo cwd é o root) deve fazer `cd` para o worktree antes.

*(Se `SHIP_MODE` for `finalize`, pule diretamente para o passo 7).*

### 2 — Sincronizar com a branch default

```bash
git fetch origin "$DEFAULT_BRANCH"
git merge "origin/$DEFAULT_BRANCH"
```

Sincronizar antes dos testes evita descobrir divergências só no merge final. Se houver conflito
aqui, resolva-o já seguindo `conflict-resolution.md`. Não prossiga com testes contra base
desatualizada.

Se houve conflito resolvido com commit, valide que o commit de resolução é de fato um merge commit
de 2 pais antes de prosseguir — um commit de 1 pai indica que `MERGE_HEAD` foi perdido (ex.: `git
stash` rodado no meio do conflito) e o GitHub vai recalcular o merge do zero, reportando
`CONFLICTING` mesmo com a árvore correta:

```bash
[ "$(git log -1 --format='%P' HEAD | wc -w)" -eq 2 ] || {
  echo "ALERTA: commit de resolução de conflito não tem 2 pais — MERGE_HEAD foi perdido." >&2
  exit 1
}
```

Se falhar, siga a recuperação descrita em `conflict-resolution.md` §5 (refaça o merge com `git merge
-s ours` para registrar o segundo pai sem alterar a árvore já resolvida) antes de seguir.

### 2.b — Colisão de versão de migration (condicional)

Logo após o merge do passo 2, **antes dos testes locais**:

```bash
bash "$SKILL_DIR/../../scripts/vetor-checks.sh" migrations
```

Detecta colisões semânticas invisíveis ao git entre workers paralelos (dois arquivos com a mesma
versão, sem conflito textual). Se sair não-zero, **pare** e mostre a saída. Projetos sem migrations
versionadas: no-op. Mesma convenção Flyway do `guardian` §2.

### 3 — Detecção de módulos alterados

```bash
git diff "origin/$DEFAULT_BRANCH" --name-only
```

Mapeie os arquivos alterados aos módulos usando a tabela do module-test-map, resolvido a partir do
root do repositório (`vetor-checks.sh repo-root`), não do `cwd` do worktree.

### 4 — Testes locais

From Tavaressan/Vetor, MIT.

More from Tavaressan/Vetor