wt — runtime canônico de Git worktrees

wt é um motor operacional para criar, verificar, reconciliar e remover worktrees com sequência rígida, parâmetros explícitos e idempotência. Ele não é a autoridade do DAG ou do tracker: recebe uma intenção já resolvida e garante que a operação Git siga o contrato.

O repositório canônico é welabs-io/worktree. O nome do repositório não muda a interface pública: o executável continua sendo wt e o contrato Python continua sendo wt_runtime.contracts.WorktreeSpec na versão 1.

Identidade e migração

repository-migration.json registra o destino canônico e fixa o commit e a árvore da origem usados para preservar o histórico. A origem imagineapps-team/gh-worktree aparece apenas como proveniência reversível enquanto o cutover não foi concluído; não é uma URL operacional nova nem altera a resolução de paths do runtime.

O pin, a ancestralidade, o $id do schema, o remote local e as interfaces públicas podem ser auditados sem rede e sem mutação persistente:

python3 scripts/verify_repository_migration.py

Na fase prepared, o verificador aceita o remote legado ou o canônico. Na fase active, aceita somente o canônico. Essa transição explícita permite trocar o remote no cutover e revertê-lo sem mudar manifests, branches, stable_work_key ou o comportamento de wt.

O bloco installation permanece pending_commit e com bootstrap desabilitado enquanto não existir um commit que contenha as mudanças validadas. Depois do commit, o SHA candidato deve passar por:

python3 scripts/verify_repository_migration.py --installation-pin <sha-completo>

O gate exige campos tipados, ancestralidade, modo executável 100755 e valida o conteúdo do SHA em uma worktree detached temporária, incluindo launcher, completion e pytest; o checkout é removido ao final. Somente então a versão, validated_commit, validated_tree e os manifests externos do bootstrap podem ser promovidos. A fonte de instalação é sempre welabs-io/worktree; a origem legada permanece apenas como pin de proveniência para rollback reversível e nunca como fallback automático de instalação.

Contrato

Uma spec JSON contém obrigatoriamente repositórios, raiz externa, nome da worktree, branch, base, ticket e stable_work_key:

{
  "contract_version": 1,
  "repo_paths": ["/home/user/code/app"],
  "worktree_root": "/home/user/.local/state/worktrees/app",
  "worktree_name": "CLA-433-runtime",
  "branch": "feat/CLA-433-runtime",
  "base_ref": "main",
  "ticket": "CLA-433",
  "stable_work_key": "worktree-runtime-neutral",
  "policy": {
    "layout": "auto",
    "branch_prefixes": ["feat", "fix", "chore", "hotfix"],
    "require_ticket_in_branch": true,
    "require_clean_source": true,
    "allow_force_remove": false,
    "delete_branch_by_default": false
  }
}

policy possui allowlist. Valores desconhecidos ou tipos inválidos falham antes de qualquer mutação. auto usa uma pasta única para um repositório e uma pasta agrupada para múltiplos repositórios. A raiz é sempre fornecida pelo chamador; o runtime não cria namespace ring nem worktree dentro do checkout.

Sequência

Toda aplicação segue estados monotônicos:

RECEIVED → NORMALIZED → VALIDATED → PLANNED → PREPARED
  → APPLIED → VERIFIED → COMMITTED

O runtime faz preflight de todos os repositórios antes da primeira criação, usa chave SHA-256 derivada da spec canônica, serializa operações concorrentes com lock local e persiste manifest atomicamente. Repetir a mesma spec devolve o manifest existente. A mesma stable_work_key com outra intenção é conflito.

Em falha durante a aplicação, somente os recursos criados naquela tentativa são revertidos. O runtime não copia arquivos não rastreados, não usa skip-worktree, não altera ponteiros internos de .git, não executa RVM e não remove branches por padrão.

CLI

./wt discover /home/user/code
./wt bases /home/user/code
./wt --state-root /home/user/.local/state/wt plan spec.json
./wt --state-root /home/user/.local/state/wt apply spec.json
./wt --state-root /home/user/.local/state/wt apply spec.json --dry-run
./wt status /home/user/.local/state/wt/<idempotency-key>.json
./wt reconcile /home/user/.local/state/wt/<idempotency-key>.json
./wt remove /home/user/.local/state/wt/<idempotency-key>.json

apply, remove e demais comandos não são interativos. Um MCP ou API pode ser adicionado como adapter fino sobre WorktreeRuntime; não deve duplicar a máquina de estados.

Compatibilidade do launcher no WSL

Os comandos discover, bases, plan, apply, status, reconcile e remove, além das opções iniciadas por -, pertencem sempre ao runtime canônico. Somente wt bash é delegado ao executável wt.exe disponível no PATH do WSL. Outros tokens posicionais são rejeitados localmente, mesmo que wt.exe exista. O launcher usa argv literal e nunca avalia o comando ou seus argumentos em um shell.

O contrato existente de shell continua válido:

eval "$(wt --completions bash)"

A saída é estática e completa apenas os sete subcomandos canônicos. Se wt.exe não existir, wt bash encerra com código 2 e informa os comandos suportados. Em sessões que não inicializam pyenv, WT_PYTHON pode apontar para um executável Python 3.11+ usado somente pelo runtime canônico.

Desenvolvimento

PYTHONPATH=. pytest -q