wize-dev-kit 0.26.1 → 0.27.2

package/docs/WORKTREES.pt-BR.md

@@ -0,0 +1,150 @@
+# Worktrees e atualizações automáticas
+
+🌐 **Idiomas:** [English](WORKTREES.md) · **Português (pt-BR)**
+
+← [Voltar ao README](../README.pt-BR.md)
+
+Um `git worktree` novo só tem os arquivos que o git rastreia. As skills geradas pelo kit não são rastreadas, então um worktree novo começa sem `/wize` e companhia. Este guia explica como o kit resolve isso sozinho e o que cada comando faz no seu repo enquanto isso acontece.
+
+## O que fica onde
+
+| Tipo | Arquivos | No git? | Quem escreve |
+|---|---|---|---|
+| Rastreado, compartilhado | `.wize/config/project.toml` (guarda o pin `kit_version`), `.wize/config/tea.toml`, `.wize/custom/`, artefatos de planning, solutioning, implementation e knowledge, `AGENTS.md`, o bloco gerenciado do `.gitignore`, `.wize/hooks/hydrate.sh` e as configs de hook do `hooks install` | sim | `install`, `update` e você |
+| Gerado | entradas `wize-*` por target (`.claude/skills/`, `.cursor/rules/`, `.github/skills/`, `.agents/skills/`, `.opencode/`, `.wize/agents/` e os demais), mais o alias `wize` ao lado | não, no `.gitignore` | `hydrate`, `sync` |
+| Por desenvolvedor | `.wize/config/user.toml`, `.wize/scratch/`, `.wize/.local/` (o marcador `hydrated.json`), `.wize/implementation/quick-dev-log.md` | não, no `.gitignore` | `hydrate` (user.toml), você |
+
+`.claude/worktrees/` também está no `.gitignore`, então worktrees que o Claude Code cria dentro do repo não aparecem no `git status`.
+
+## O pin
+
+`kit_version` em `.wize/config/project.toml` é a única fonte de verdade sobre qual kit renderiza o repo. Todo o time renderiza exatamente essa versão, qualquer que seja o `npx` que cada um rodou.
+
+- `hydrate` renderiza o pin. Para pin 0.27.0 ou superior ele se reexecuta como `npx wize-dev-kit@<pin> hydrate` quando o binário é diferente, com uma trava (`WIZE_HYDRATE_DELEGATED`) contra recursão. Se isso falhar (offline, registry fora do ar; cada tentativa tem teto de 45 s e uma tentativa que estoura o tempo não é repetida), renderiza com o binário que tem e avisa. Esse render de fallback vale como atual por uma hora; depois disso o próximo `hydrate --if-needed` tenta o pin exato de novo.
+- Pins anteriores à 0.27.0 não têm `hydrate`. Nesses casos o `version-check` indica `sync` como comando e nunca entra em loop.
+- Pin mais novo que o binário significa cache do `npx` desatualizado. O `update` não rebaixa o pin, a menos que você passe `--allow-downgrade`.
+
+## Checklist de um worktree novo
+
+```bash
+npx wize-dev-kit hydrate
+```
+
+É o checklist inteiro. O `hydrate`:
+
+- acha a raiz do projeto a partir de qualquer subdiretório ou worktree linkado (`--root <dir>` ou `WIZE_PROJECT_ROOT` sobrescrevem);
+- copia `.wize/config/user.toml` do checkout primário, ou deriva um de `git config user.name`, e nunca sobrescreve um existente;
+- renderiza os adapters dos targets configurados, pulando arquivos cujo conteúdo não mudou;
+- grava o marcador `.wize/.local/hydrated.json`;
+- nunca pergunta nada, nunca lê stdin, nunca roda o baseline do document-project e nunca escreve em arquivo rastreado.
+
+Antes de renderizar ele registra o `git ls-files`; uma renderização que sobrescreveria um arquivo rastreado é bloqueada, inclusive quando chegaria a ele por um diretório que é symlink. Se o git não consegue listar os arquivos rastreados (git ausente, ou repositório que o git recusa por segurança), o hydrate não toca em nenhum arquivo existente e avisa. Depois compara o `git status` e avisa se surgiram entradas novas, o que em geral indica um `.gitignore` anterior à 0.27.0.
+
+Para automatizar, instale um hook (próxima seção).
+
+## O ciclo automático
+
+1. **Início de sessão.** Uma skill (`/wize`, `/wize-help`) roda `version-check --json` e segue o campo `action`: `hydrate` e `update` rodam sem perguntar; a única confirmação vem antes do `update --pr`, porque ele faz push. O bloco de bootstrap do `AGENTS.md` leva a mesma instrução para harnesses que não carregam skills primeiro.
+2. **Criação de worktree.** Orca, Cursor e Claude Code podem rodar `.wize/hooks/hydrate.sh` quando um worktree ou sessão começa (veja a matriz de harnesses).
+3. **Toda semana.** Uma GitHub Action abre um PR que atualiza o pin (`hooks install --github-action`).
+4. **Depois do merge.** Cada worktree puxa o pin novo, vê que o marcador está velho e se hidrata sozinho na versão nova.
+
+O `version-check` lê o registry por um cache stale-while-revalidate em `$XDG_CACHE_HOME` (ou `~/.cache`): a resposta em cache volta em qualquer idade, e uma entrada velha dispara um único refresh em segundo plano, no máximo a cada 10 minutos. Nenhum refresh começa em CI, com `WIZE_DISABLE_UPDATE_CHECK=1` ou com `WIZE_NO_BG_REFRESH=1`; a dica de uma linha ao fim de um comando também fica em silêncio sem TTY. As dicas de comando e o `hydrate` nunca esperam pela rede; um `version-check` explícito espera no máximo cerca de 1,5 s pelo registry quando o cache está velho.
+
+### Desligar
+
+`WIZE_DISABLE_UPDATE_CHECK=1` desliga a consulta ao registry e rebaixa a action `update` para `none`. A hidratação continua acontecendo. Ainda não existe chave em nível de time no `project.toml`.
+
+## Atualizando o kit
+
+```bash
+npx wize-dev-kit@latest update          # prepara a branch do bump localmente
+npx wize-dev-kit@latest update --pr     # também faz push e abre o PR
+```
+
+Em um repo git o `update` trabalha num worktree descartável:
+
+1. Faz fetch e cria a branch a partir de `origin/<default>` (ou da branch default local se o fetch falhar, e avisa).
+2. Nesse worktree ele atualiza o `kit_version`, renova o bloco gerenciado do `.gitignore` e o bloco de bootstrap do `AGENTS.md` (só num `AGENTS.md` gerado pelo kit), renova o `hydrate.sh` quando está instalado e gerenciado, e remove do índice os arquivos rastreados sob os 12 caminhos de alias gerados.
+3. Faz o commit em `chore/wize-kit-<versão>` e remove o worktree.
+
+Seu checkout, branch, índice e arquivos não commitados nunca são tocados, e o `update` nunca commita na branch default, então dá para rodar com a árvore suja ou HEAD destacado. O `--pr` faz push sem force (push rejeitado sai com 1 e avisa que a branch remota divergiu) e abre o PR com `gh`, ou imprime a URL de compare do GitHub quando não há `gh`.
+
+| Flag | Efeito |
+|---|---|
+| `--pr` | Faz push da branch e abre um PR. Vale como consentimento para o push. |
+| `--in-place` | Edita o checkout atual, re-renderiza, nunca commita. Sempre o modo fora de um repo git. |
+| `--no-render` | Com `--in-place`: pula a re-renderização dos adapters. |
+| `--check` | Só reporta. Sai com 0 convergido, 11 mudanças pendentes, 12 pin à frente do binário. |
+| `--dry-run` | Imprime o plano, não escreve nada, sai com 0. |
+| `--base <ref>` | Cria a branch a partir desta ref em vez da branch default. |
+| `--allow-downgrade` | Deixa o pin ir para uma versão mais antiga. |
+| `--json` | Um objeto JSON no stdout. |
+
+### Migrando um repo existente
+
+Rode `npx wize-dev-kit@latest update --pr` uma vez por repo e faça o merge do PR. Uma pegadinha: o PR remove do índice os arquivos de alias antigos (por exemplo `.cursor/rules/wize.mdc`) que versões anteriores commitaram sem querer. Quando outro worktree puxa o merge, o git apaga esses arquivos lá. Rode o `hydrate` nesse worktree, ou deixe o ciclo da sessão fazer isso, e eles voltam como arquivos não rastreados e ignorados.
+
+## Matriz de harnesses
+
+`npx wize-dev-kit hooks print <target>` imprime os trechos do Orca, Claude Code, Cursor, Codex e da Action semanal abaixo sem escrever nada (o Copilot cloud agent não tem alvo de print). `hooks install` grava o `.wize/hooks/hydrate.sh` gerenciado (POSIX sh, sempre sai com 0, escreve no stderr) mais a config pedida com `--claude`, `--cursor` ou `--github-action`; exige ao menos uma dessas flags.
+
+| Harness | Configuração |
+|---|---|
+| Orca | No `orca.yaml`: `scripts.setup: sh .wize/hooks/hydrate.sh` e `setupAgentStartupPolicy: wait-for-setup`. Liste `.wize/config/user.toml` no `.worktreeinclude`. Um hook de setup não vazio salvo localmente no Orca sobrescreve o `orca.yaml`, então limpe-o nas configurações do repo. |
+| Claude Code | `hooks install --claude` adiciona uma entrada `SessionStart` (matcher `startup`) ao `.claude/settings.json`, mesclada com seus hooks existentes. Adicione `.wize/config/user.toml` ao `.worktreeinclude` para copiá-lo para os worktrees. |
+| Cursor | `hooks install --cursor` grava `.cursor/worktrees.json` com `setup-worktree: ["sh .wize/hooks/hydrate.sh"]`. |
+| Codex | Defina o script de setup do ambiente local como `sh .wize/hooks/hydrate.sh`. O Codex guarda isso na config própria, então o kit só imprime. |
+| GitHub Copilot cloud agent | Adicione `npx --yes wize-dev-kit hydrate` como um passo em `.github/workflows/copilot-setup-steps.yml`. |
+| PR semanal de bump | `hooks install --github-action` grava `.github/workflows/wize-kit-update.yml`. Habilite "Allow GitHub Actions to create and approve pull requests" nas configurações do repo. PRs abertos com `GITHUB_TOKEN` não disparam outros workflows, então os checks obrigatórios esperam até alguém fazer push na branch. |
+
+Nenhum desses caminhos foi verificado de ponta a ponta em cada produto; veja a última seção.
+
+## O que o `git worktree remove` perde
+
+Tudo que não é rastreado naquele worktree: `user.toml`, `.wize/scratch/`, `.wize/.local/`, `quick-dev-log.md` e os adapters gerados. Tudo isso se regenera com `hydrate`, exceto as notas de scratch e o quick-dev-log, que só existem naquele worktree. Faça commit ou copie antes. Os artefatos de `.wize/` (PRD, stories, knowledge) são rastreados, então viajam com a branch.
+
+## Concorrência
+
+Vários worktrees, ou vários agentes no mesmo worktree, podem renderizar ao mesmo tempo. Toda escrita passa por write-if-changed mais um rename atômico de arquivo temporário, então quem lê nunca vê uma skill pela metade e uma segunda execução reporta todos os arquivos como inalterados. A trava de arquivos rastreados impede que o `hydrate` sobrescreva algo que você commitou. `sync` e `update --in-place` escrevem de forma atômica, mas sem a trava: são os comandos explícitos de regeneração.
+
+## Variáveis de ambiente
+
+| Variável | Efeito |
+|---|---|
+| `WIZE_PROJECT_ROOT` | Raiz do projeto quando você roda um comando fora dela. `--root` tem precedência. |
+| `ORCA_WORKTREE_PATH`, `ORCA_ROOT_PATH` | Lidas só pelo `hydrate`: o worktree a renderizar (usado só quando o diretório atual não está dentro de um projeto) e uma origem para o `user.toml` (usada só se pertencer ao mesmo repositório). |
+| `WIZE_SKIP_BASELINE=1` | Pula o baseline do document-project durante o `install` e faz o `document-project quick` não fazer nada. |
+| `WIZE_HYDRATE_DELEGATED` | Definida pelo `hydrate` ao delegar para o kit do pin. Não defina você mesmo. |
+| `WIZE_DISABLE_UPDATE_CHECK=1` | Sem consulta ao registry; a action `update` vira `none`. |
+| `WIZE_NO_BG_REFRESH=1` | Nunca inicia o refresh do cache em segundo plano. |
+| `WIZE_VERBOSE=1` | Mostra a saída crua do `npx` de um `hydrate` delegado que falhou (normalmente uma linha de fallback). |
+| `CI` | Suprime avisos de update e o refresh em segundo plano. |
+
+## Códigos de saída
+
+Os padrões continuam 0 para não quebrar scripts existentes. As formas estritas são opt-in.
+
+| Comando | Códigos |
+|---|---|
+| `hydrate` | Sempre 0. `--strict` retorna 1 quando não conseguiu hidratar. |
+| `version-check --exit-code` | 0 nada a fazer, 10 `hydrate`, 11 `update`, 12 `use-pin`, 13 `install`. |
+| `update --check` | 0 convergido, 11 mudanças pendentes, 12 pin à frente do binário. |
+| `doctor --strict` | 1 quando existe alguma sugestão de nível erro. |
+
+`doctor --json` e `version-check --json` imprimem um objeto JSON, sem banner.
+
+## Fora da 0.27.0
+
+- Estado `.wize` compartilhado entre worktrees (symlink ou branch de estado); manifestos de sprint, alocação de IDs de ADRs e stories, fragmentos por story do document-project, fragmentos de changelog, um `index.md` determinístico, um gatilho de NFR por epic, e referências a `sprint-status.md` fora do `doctor`.
+- Caminhos relativos no `project-scan-report.json` (ele ainda guarda caminhos absolutos).
+- `wize-release` a partir de um worktree linkado, ou release via PR.
+- Uma política para `.wize/security/` (ignorar ou commitar).
+- Regenerar o `AGENTS.md` além do bloco de bootstrap; um marcador de versão no `AGENTS.md`.
+- Remover skills geradas que um kit mais novo retirou.
+- `update` se reexecutar como `@latest` a partir de um binário antigo fixado pelo pin. A trava de downgrade e o `@latest` nas skills e na Action cobrem isso.
+- Uma chave `[update] auto = false` em nível de time. Só existe a variável de ambiente.
+- Escrever o `orca.yaml` ou a config do Codex. Ambos só imprimem. Sem variante de `hydrate.sh` para Windows.
+- Pin por Renovate ou Dependabot, que criaria uma segunda fonte de verdade para o pin.
+- Recusa dura do `sync` em caso de skew de versão, e saída não zero quando um adapter falha.
+- Verificações de ponta a ponta no Orca (falha de setup, prompt de trust), no timing do `SessionStart` do Claude Code contra o carregamento de skills, e na leitura de rules em worktrees pelo Cursor ou Windsurf.

package/docs/harnesses/antigravity.md

@@ -18,3 +18,5 @@ Antigravity uses the same public Anthropic Skill format as Claude Code and Codex
 ## Setup
 
 Pick **Antigravity** as an IDE target during `npx wize-dev-kit install` (or add it and re-run `npx wize-dev-kit sync`). Restart Antigravity, then run `/wize-orchestrator` or ask it to read `AGENTS.md`.
+
+Fresh clone or new worktree: generated files are gitignored, so run `npx wize-dev-kit hydrate` there (no prompts, touches no tracked file). See [Worktrees and automatic updates](../WORKTREES.md).

package/docs/harnesses/antigravity.pt-BR.md

@@ -18,3 +18,5 @@ O Antigravity usa o mesmo formato público de Skill da Anthropic que o Claude Co
 ## Como ativar
 
 Escolha **Antigravity** como alvo de IDE em `npx wize-dev-kit install` (ou adicione depois e rode `npx wize-dev-kit sync`). Reinicie o Antigravity e rode `/wize-orchestrator` ou peça pra ele ler o `AGENTS.md`.
+
+Clone ou worktree novo: os arquivos gerados estão no `.gitignore`, então rode `npx wize-dev-kit hydrate` ali (sem perguntas, não toca arquivo rastreado). Veja [Worktrees e atualizações automáticas](../WORKTREES.pt-BR.md).

package/docs/harnesses/claude-code.md

@@ -21,3 +21,5 @@ There is no separate "agent" file shape here — personas (Wizer, Shuri, Hawkeye
 ## Setup
 
 Pick **Claude Code** as an IDE target during `npx wize-dev-kit install` (default). Restart Claude Code, then say *"Activate Wizer and brief him on the project"* or run `/wize-orchestrator`.
+
+Fresh clone or new worktree: generated files are gitignored, so run `npx wize-dev-kit hydrate` there (no prompts, touches no tracked file). `npx wize-dev-kit hooks install --claude` hydrates every new session on its own. See [Worktrees and automatic updates](../WORKTREES.md).

package/docs/harnesses/claude-code.pt-BR.md

@@ -21,3 +21,5 @@ Não existe um formato separado de "agente" aqui — personas (Wizer, Shuri, Haw
 ## Como ativar
 
 Escolha **Claude Code** como alvo de IDE em `npx wize-dev-kit install` (padrão). Reinicie o Claude Code e diga *"Ative o Wizer e dê o briefing do projeto a ele"* ou rode `/wize-orchestrator`.
+
+Clone ou worktree novo: os arquivos gerados estão no `.gitignore`, então rode `npx wize-dev-kit hydrate` ali (sem perguntas, não toca arquivo rastreado). `npx wize-dev-kit hooks install --claude` hidrata cada sessão nova automaticamente. Veja [Worktrees e atualizações automáticas](../WORKTREES.pt-BR.md).

package/docs/harnesses/codex.md

@@ -14,8 +14,10 @@ Codex shares the same Anthropic Skill format as Claude Code and Kimi Code.
 ## Notable
 
 - `.agents/skills/` is Codex's documented path for repository-local skills — the kit writes there directly, not to a Codex-specific directory.
-- **History:** 0.7.2 briefly moved this output to `.codex/skills/`, which broke skill loading in real Codex sessions; 0.7.3 reverted it to `.agents/skills/`. If you're on an older install, run `npx wize-dev-kit update` to fix the path.
+- **History:** 0.7.2 briefly moved this output to `.codex/skills/`, which broke skill loading in real Codex sessions; 0.7.3 reverted it to `.agents/skills/`. If you're on an older install, run `npx wize-dev-kit@latest update --pr`, merge the PR, then run `npx wize-dev-kit hydrate` to get the right path.
 
 ## Setup
 
 Pick **Codex** as an IDE target during `npx wize-dev-kit install` (or add it and re-run `npx wize-dev-kit sync`). Restart Codex, then run `/wize-orchestrator` or ask it to read `AGENTS.md`.
+
+Fresh clone or new worktree: generated files are gitignored, so run `npx wize-dev-kit hydrate` there (no prompts, touches no tracked file). `npx wize-dev-kit hooks print codex` shows the setup script to put in a Codex local environment. See [Worktrees and automatic updates](../WORKTREES.md).

package/docs/harnesses/codex.pt-BR.md

@@ -14,8 +14,10 @@ O Codex usa o mesmo formato de Skill da Anthropic que o Claude Code e o Kimi Cod
 ## Destaques
 
 - `.agents/skills/` é o caminho documentado do Codex pra skills locais do repositório — o kit grava lá diretamente, não num diretório específico do Codex.
-- **Histórico:** a 0.7.2 moveu essa saída, por um breve período, para `.codex/skills/`, o que quebrou o carregamento das skills em sessões reais do Codex; a 0.7.3 reverteu para `.agents/skills/`. Se sua instalação é antiga, rode `npx wize-dev-kit update` pra corrigir o caminho.
+- **Histórico:** a 0.7.2 moveu essa saída, por um breve período, para `.codex/skills/`, o que quebrou o carregamento das skills em sessões reais do Codex; a 0.7.3 reverteu para `.agents/skills/`. Se sua instalação é antiga, rode `npx wize-dev-kit@latest update --pr`, faça o merge do PR e rode `npx wize-dev-kit hydrate` pra obter o caminho certo.
 
 ## Como ativar
 
 Escolha **Codex** como alvo de IDE em `npx wize-dev-kit install` (ou adicione depois e rode `npx wize-dev-kit sync`). Reinicie o Codex e rode `/wize-orchestrator` ou peça pra ele ler o `AGENTS.md`.
+
+Clone ou worktree novo: os arquivos gerados estão no `.gitignore`, então rode `npx wize-dev-kit hydrate` ali (sem perguntas, não toca arquivo rastreado). `npx wize-dev-kit hooks print codex` mostra o script de setup para um ambiente local do Codex. Veja [Worktrees e atualizações automáticas](../WORKTREES.pt-BR.md).

package/docs/harnesses/continue.md

@@ -16,6 +16,8 @@
 
 Pick **Continue** as an IDE target during `npx wize-dev-kit install` (or add it and re-run `npx wize-dev-kit sync`). Reload the Continue extension, then run `/wize-orchestrator` from the prompt palette.
 
+Fresh clone or new worktree: generated files are gitignored, so run `npx wize-dev-kit hydrate` there (no prompts, touches no tracked file). See [Worktrees and automatic updates](../WORKTREES.md).
+
 ## Reference
 
 - [docs.continue.dev — Prompts](https://docs.continue.dev/customize/deep-dives/prompts)

package/docs/harnesses/continue.pt-BR.md

@@ -16,6 +16,8 @@
 
 Escolha **Continue** como alvo de IDE em `npx wize-dev-kit install` (ou adicione depois e rode `npx wize-dev-kit sync`). Recarregue a extensão do Continue e rode `/wize-orchestrator` na paleta de prompts.
 
+Clone ou worktree novo: os arquivos gerados estão no `.gitignore`, então rode `npx wize-dev-kit hydrate` ali (sem perguntas, não toca arquivo rastreado). Veja [Worktrees e atualizações automáticas](../WORKTREES.pt-BR.md).
+
 ## Referência
 
 - [docs.continue.dev — Prompts](https://docs.continue.dev/customize/deep-dives/prompts)

package/docs/harnesses/copilot.md

@@ -57,6 +57,8 @@ Generated `wize-*` files are gitignored (regenerate any time with
 `npx wize-dev-kit sync`). Hand-written team skills added next to them should be
 committed.
 
+Fresh clone or new worktree: generated files are gitignored, so run `npx wize-dev-kit hydrate` there (no prompts, touches no tracked file). For the cloud agent, add `npx --yes wize-dev-kit hydrate` as a step in `.github/workflows/copilot-setup-steps.yml`. See [Worktrees and automatic updates](../WORKTREES.md).
+
 ## Headless
 
 `copilot -p "<prompt>"` runs a one-shot session without entering the interactive

package/docs/harnesses/copilot.pt-BR.md

@@ -57,6 +57,8 @@ Arquivos `wize-*` gerados ficam no `.gitignore` (regenere com
 `npx wize-dev-kit sync`). Skills de time escritas à mão ao lado deles devem ser
 commitadas.
 
+Clone ou worktree novo: os arquivos gerados estão no `.gitignore`, então rode `npx wize-dev-kit hydrate` ali (sem perguntas, não toca arquivo rastreado). Para o cloud agent, adicione `npx --yes wize-dev-kit hydrate` como um passo em `.github/workflows/copilot-setup-steps.yml`. Veja [Worktrees e atualizações automáticas](../WORKTREES.pt-BR.md).
+
 ## Headless
 
 `copilot -p "<prompt>"` roda uma sessão one-shot sem entrar na UI interativa — é o

package/docs/harnesses/cursor.md

@@ -17,6 +17,8 @@
 
 Pick **Cursor** as an IDE target during `npx wize-dev-kit install` (or add it and re-run `npx wize-dev-kit sync`). Restart Cursor, then reference `@wize-orchestrator` or ask it to activate Wizer.
 
+Fresh clone or new worktree: generated files are gitignored, so run `npx wize-dev-kit hydrate` there (no prompts, touches no tracked file). `npx wize-dev-kit hooks install --cursor` hydrates every new Cursor worktree on its own. See [Worktrees and automatic updates](../WORKTREES.md).
+
 ## Reference
 
 - [cursor.com/docs/context/rules](https://cursor.com/docs/context/rules)

package/docs/harnesses/cursor.pt-BR.md

@@ -17,6 +17,8 @@
 
 Escolha **Cursor** como alvo de IDE em `npx wize-dev-kit install` (ou adicione depois e rode `npx wize-dev-kit sync`). Reinicie o Cursor e referencie `@wize-orchestrator` ou peça pra ativar o Wizer.
 
+Clone ou worktree novo: os arquivos gerados estão no `.gitignore`, então rode `npx wize-dev-kit hydrate` ali (sem perguntas, não toca arquivo rastreado). `npx wize-dev-kit hooks install --cursor` hidrata cada worktree novo do Cursor automaticamente. Veja [Worktrees e atualizações automáticas](../WORKTREES.pt-BR.md).
+
 ## Referência
 
 - [cursor.com/docs/context/rules](https://cursor.com/docs/context/rules)

package/docs/harnesses/generic.md

@@ -18,3 +18,5 @@ For any AI IDE that isn't one of the [dedicated targets](../../README.md#support
 ## Setup
 
 Pick **Generic fallback** as an IDE target during `npx wize-dev-kit install` — it's on by default alongside your primary target, precisely so an unsupported second tool in the same repo still has something to read.
+
+Fresh clone or new worktree: generated files are gitignored, so run `npx wize-dev-kit hydrate` there (no prompts, touches no tracked file). See [Worktrees and automatic updates](../WORKTREES.md).

package/docs/harnesses/generic.pt-BR.md

@@ -18,3 +18,5 @@ Para qualquer IDE com IA que não esteja entre os [alvos dedicados](../../README
 ## Como ativar
 
 Escolha **Fallback genérico** como alvo de IDE em `npx wize-dev-kit install` — ele já vem ligado por padrão junto do seu alvo principal, justamente pra que uma segunda ferramenta sem suporte dedicado no mesmo repositório ainda tenha algo pra ler.
+
+Clone ou worktree novo: os arquivos gerados estão no `.gitignore`, então rode `npx wize-dev-kit hydrate` ali (sem perguntas, não toca arquivo rastreado). Veja [Worktrees e atualizações automáticas](../WORKTREES.pt-BR.md).

package/docs/harnesses/hermes.md

@@ -21,6 +21,8 @@ Hermes Agent consumes the same public Anthropic Skill format as Claude Code, Cod
 
 Pick **Hermes Agent** as an IDE target during `npx wize-dev-kit install` (or add it and re-run `npx wize-dev-kit sync`). Run `hermes skills trust` in the repo, restart Hermes, then run `/wize-orchestrator`.
 
+Fresh clone or new worktree: generated files are gitignored, so run `npx wize-dev-kit hydrate` there (no prompts, touches no tracked file). See [Worktrees and automatic updates](../WORKTREES.md).
+
 ## Headless
 
 `hermes -z "<prompt>"` runs a one-shot headless session, which the installer's brownfield baseline uses when Hermes is the detected harness CLI.

package/docs/harnesses/hermes.pt-BR.md

@@ -21,6 +21,8 @@ O Hermes Agent consome o mesmo formato público de Skill da Anthropic usado pelo
 
 Escolha **Hermes Agent** como alvo de IDE em `npx wize-dev-kit install` (ou adicione depois e rode `npx wize-dev-kit sync`). Rode `hermes skills trust` no repo, reinicie o Hermes e rode `/wize-orchestrator`.
 
+Clone ou worktree novo: os arquivos gerados estão no `.gitignore`, então rode `npx wize-dev-kit hydrate` ali (sem perguntas, não toca arquivo rastreado). Veja [Worktrees e atualizações automáticas](../WORKTREES.pt-BR.md).
+
 ## Headless
 
 `hermes -z "<prompt>"` roda uma sessão headless de uma execução, usada pelo baseline brownfield do instalador quando o Hermes é o CLI de harness detectado.

package/docs/harnesses/kimi-code.md

@@ -17,3 +17,5 @@ Moonshot's Kimi Code consumes the same public Anthropic Skill format as Claude C
 ## Setup
 
 Pick **Kimi Code** as an IDE target during `npx wize-dev-kit install` (or add it and re-run `npx wize-dev-kit sync`). Restart Kimi Code, then run `/wize-orchestrator`.
+
+Fresh clone or new worktree: generated files are gitignored, so run `npx wize-dev-kit hydrate` there (no prompts, touches no tracked file). See [Worktrees and automatic updates](../WORKTREES.md).

package/docs/harnesses/kimi-code.pt-BR.md

@@ -17,3 +17,5 @@ O Kimi Code, da Moonshot, consome o mesmo formato público de Skill da Anthropic
 ## Como ativar
 
 Escolha **Kimi Code** como alvo de IDE em `npx wize-dev-kit install` (ou adicione depois e rode `npx wize-dev-kit sync`). Reinicie o Kimi Code e rode `/wize-orchestrator`.
+
+Clone ou worktree novo: os arquivos gerados estão no `.gitignore`, então rode `npx wize-dev-kit hydrate` ali (sem perguntas, não toca arquivo rastreado). Veja [Worktrees e atualizações automáticas](../WORKTREES.pt-BR.md).

package/docs/harnesses/kiro.md

@@ -21,6 +21,8 @@ Kiro, the agentic IDE/CLI from AWS, follows the open [Agent Skills standard](htt
 
 Pick **Kiro — AWS** as an IDE target during `npx wize-dev-kit install` (or add it and re-run `npx wize-dev-kit sync`). Restart Kiro, then run `/wize-orchestrator`.
 
+Fresh clone or new worktree: generated files are gitignored, so run `npx wize-dev-kit hydrate` there (no prompts, touches no tracked file). See [Worktrees and automatic updates](../WORKTREES.md).
+
 ## Headless
 
 `kiro-cli chat --no-interactive --trust-all-tools "<prompt>"` runs a one-shot headless session (requires `KIRO_API_KEY`), which the installer's brownfield baseline uses when Kiro CLI is the detected harness.

package/docs/harnesses/kiro.pt-BR.md

@@ -21,6 +21,8 @@ O Kiro, IDE/CLI agêntica da AWS, segue o padrão aberto [Agent Skills](https://
 
 Escolha **Kiro — AWS** como alvo de IDE em `npx wize-dev-kit install` (ou adicione depois e rode `npx wize-dev-kit sync`). Reinicie o Kiro e rode `/wize-orchestrator`.
 
+Clone ou worktree novo: os arquivos gerados estão no `.gitignore`, então rode `npx wize-dev-kit hydrate` ali (sem perguntas, não toca arquivo rastreado). Veja [Worktrees e atualizações automáticas](../WORKTREES.pt-BR.md).
+
 ## Headless
 
 `kiro-cli chat --no-interactive --trust-all-tools "<prompt>"` roda uma sessão headless de uma execução (requer `KIRO_API_KEY`), usada pelo baseline brownfield do instalador quando o Kiro CLI é o harness detectado.

package/docs/harnesses/opencode.md

@@ -25,6 +25,8 @@ This is also the harness the kit's own subagent fan-out pattern (documented in W
 
 Pick **OpenCode** as an IDE target during `npx wize-dev-kit install` (or add it and re-run `npx wize-dev-kit sync`). Restart OpenCode, then say *"Activate Wizer and brief him on the project"* or run `/wize-orchestrator`.
 
+Fresh clone or new worktree: generated files are gitignored, so run `npx wize-dev-kit hydrate` there (no prompts, touches no tracked file). See [Worktrees and automatic updates](../WORKTREES.md).
+
 ## Reference
 
 - [opencode.ai/docs/agents](https://opencode.ai/docs/agents/)

package/docs/harnesses/opencode.pt-BR.md

@@ -25,6 +25,8 @@ Esta também é a harness contra a qual o padrão de fan-out de subagentes do ki
 
 Escolha **OpenCode** como alvo de IDE em `npx wize-dev-kit install` (ou adicione depois e rode `npx wize-dev-kit sync`). Reinicie o OpenCode e diga *"Ative o Wizer e dê o briefing do projeto a ele"* ou rode `/wize-orchestrator`.
 
+Clone ou worktree novo: os arquivos gerados estão no `.gitignore`, então rode `npx wize-dev-kit hydrate` ali (sem perguntas, não toca arquivo rastreado). Veja [Worktrees e atualizações automáticas](../WORKTREES.pt-BR.md).
+
 ## Referência
 
 - [opencode.ai/docs/agents](https://opencode.ai/docs/agents/)

package/docs/harnesses/windsurf.md

@@ -17,6 +17,8 @@
 
 Pick **Windsurf** as an IDE target during `npx wize-dev-kit install` (or add it and re-run `npx wize-dev-kit sync`). Restart Windsurf, review the new rules under **Cascade → Rules**, then ask it to activate Wizer.
 
+Fresh clone or new worktree: generated files are gitignored, so run `npx wize-dev-kit hydrate` there (no prompts, touches no tracked file). See [Worktrees and automatic updates](../WORKTREES.md).
+
 ## Reference
 
 - [docs.windsurf.com — Cascade rules](https://docs.windsurf.com/windsurf/cascade/memories#rules)

package/docs/harnesses/windsurf.pt-BR.md

@@ -17,6 +17,8 @@
 
 Escolha **Windsurf** como alvo de IDE em `npx wize-dev-kit install` (ou adicione depois e rode `npx wize-dev-kit sync`). Reinicie o Windsurf, confira as novas rules em **Cascade → Rules**, e peça pra ativar o Wizer.
 
+Clone ou worktree novo: os arquivos gerados estão no `.gitignore`, então rode `npx wize-dev-kit hydrate` ali (sem perguntas, não toca arquivo rastreado). Veja [Worktrees e atualizações automáticas](../WORKTREES.pt-BR.md).
+
 ## Referência
 
 - [docs.windsurf.com — Cascade rules](https://docs.windsurf.com/windsurf/cascade/memories#rules)

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "wize-dev-kit",
-  "version": "0.26.1",
+  "version": "0.27.2",
   "description": "Full-lifecycle AI-assisted development kit with Test Architect and Whiteport Design Studio embedded. Inspired by BMAD Method and WDS.",
   "keywords": [
     "ai",

package/src/orchestrator-skills/module.yaml

@@ -24,7 +24,7 @@ skills:
     description: "Progress checklist for the demand in flight: done (with evidence), in progress, left, blocked. Read-only — reports, then resumes the interrupted work."
   - code: wize-update
     name: "Update (Wizer)"
-    description: "Checks kit version skew, shows the changelog jump, confirms, then applies `wize-dev-kit update` and reports the result."
+    description: "Kit maintenance: hydrates a checkout whose skills are missing, prepares the kit-bump branch locally, and opens the PR after one push confirmation."
   - code: wize-onboarding
     name: "Onboarding"
     description: "Post-install triage: greenfield vs brownfield, profile, objective. Delegates to specialists."

package/src/orchestrator-skills/wize/skill.md

@@ -97,17 +97,27 @@ When intent is ambiguous or no intent phrase matches, apply this heuristic top-d
 
 See the full intent routing table in `wize-help/skill.md` (Step 2a). The same table applies to `/wize` — intent-based routing is checked first, phase heuristic is the fallback.
 
-## Step 2.5 — version skew (proactive)
+## Step 2.5 — kit state (proactive)
 
-If you have Bash, run `npx wize-dev-kit version-check --json` once — it reads a local 1h cache before touching the network, caps any registry call at ~1.5s, and degrades to `{"latest":null}` silently if offline, so this never blocks the response. Compare its `installed` field against `kit_version` (project.toml):
+If you have Bash, run `npx --yes --fetch-retries=0 wize-dev-kit version-check --json` once per conversation and obey its `action`. Never compare versions by hand. The command reads a local cache and caps its own registry call at about 1.5s. The `--fetch-retries=0` flag turns off npm's own retries, so npx fails quickly when the network refuses connections; it cannot cap a network that silently drops packets, so prefix the command with `timeout 20` where that exists. If npx fails or times out, skip this step.
 
-| Condition | Suggest |
+| `action` | Do |
 |---|---|
-| `installed` > `kit_version` (project.toml) | `/wize-update` |
-| `latest` > `installed` | `/wize-update` |
-| everything matches, or `latest` is `null` | nothing |
+| `hydrate` | Run `commands.hydrate` now, without asking: it writes only git-ignored files. Then one line: restart the harness if the `/wize-*` commands are still missing. |
+| `update` | Run `commands.update` now, without asking (except for `pin-unpublished`, below): it is local, runs in an isolated temp worktree, and never touches this checkout or the default branch. Report the branch in one line, then ask once: *"Abrir PR do bump do kit? (git push)"*. Run `commands.pr` only on a yes. |
+| `use-pin` | Show the exact command `npx wize-dev-kit@<pin>`, with `<pin>` from `project.pin`. Run nothing. |
+| `install` | Show `commands.install` (see `wize-onboarding`). |
+| `none` | Say nothing. |
 
-Phrase as one short line, not a banner — and only the **first time in this conversation**. If you already mentioned it earlier in this session, don't repeat it.
+Exception: when `reason` is `pin-unpublished`, the project pin is newer than the registry's latest, and `commands.update` lowers it (`--allow-downgrade`). Never run it unattended. Ask first: *"O pin do projeto (<pin>) é mais novo que o último publicado (<latest>). Rebaixar o pin?"*, and run it only on a yes. Do not offer the PR as a "bump".
+
+Exception: when `reason` is `kit-not-on-branch` (`action` is `none`), this linked worktree's branch has no kit while `kit_at` does. One line: merge the kit into this branch, or install here with `install --here`. Do not run `install`.
+
+`disabled: true` only turns off update checks: `action` can still be `hydrate`, `use-pin` or `install`, so follow it.
+
+Loop guard: run `version-check` and its follow-up command once per conversation. After a `hydrate` or `update`, do not run `version-check` again to confirm.
+
+No Bash: one line suggesting `/wize-update`.
 
 ## Step 3 — respond
 

package/src/orchestrator-skills/wize-help/skill.md

@@ -79,6 +79,8 @@ If multiple intents match, pick the most specific (longest phrase match). If sti
 
 When intent is ambiguous or no intent phrase matches, apply this heuristic top-down; stop at the first match:
 
+Adapters ausentes (skills or `/wize-*` commands missing in this checkout) → hydrate: route to `wize-update` before any row below.
+
 | # | State | Next step |
 |---|---|---|
 | 1 | No `.wize/` folder | Kit not installed → `npx wize-dev-kit install` |
@@ -203,18 +205,29 @@ Match is case-insensitive, substring-based. Longest match wins. When no intent m
 | "onboarding", "instalar kit", "primeiro uso" | `wize-onboarding` |
 | "party mode", "multi-agent", "reunir agentes" | `wize-party-mode` |
 | "atualizar o kit", "tem atualização", "nova versão do kit", "update the kit", "wize update" | `wize-update` |
+| "skills ausentes", "os comandos /wize sumiram", "comandos /wize sumiram", "worktree nova sem skills", "worktree nova", "hidratar", "hydrate" | `wize-update` (hydrate path) |
 
-## Step 2.5 — version skew (proactive)
+## Step 2.5 — kit state (proactive)
 
-If you have Bash, run `npx wize-dev-kit version-check --json` once — it reads a local 1h cache before touching the network, caps any registry call at ~1.5s, and degrades to `{"latest":null}` silently if offline, so this never blocks the response. Compare its `installed` field against `kit_version` (project.toml):
+If you have Bash, run `npx --yes --fetch-retries=0 wize-dev-kit version-check --json` once per conversation and obey its `action`. Never compare versions by hand. The command reads a local cache and caps its own registry call at about 1.5s. The `--fetch-retries=0` flag turns off npm's own retries, so npx fails quickly when the network refuses connections; it cannot cap a network that silently drops packets, so prefix the command with `timeout 20` where that exists. If npx fails or times out, skip this step.
 
-| Condition | Suggest |
+| `action` | Do |
 |---|---|
-| `installed` > `kit_version` (project.toml) | `/wize-update` |
-| `latest` > `installed` | `/wize-update` |
-| everything matches, or `latest` is `null` | nothing |
+| `hydrate` | Run `commands.hydrate` now, without asking: it writes only git-ignored files. Then one line: restart the harness if the `/wize-*` commands are still missing. |
+| `update` | Run `commands.update` now, without asking (except for `pin-unpublished`, below): it is local, runs in an isolated temp worktree, and never touches this checkout or the default branch. Report the branch in one line, then ask once: *"Abrir PR do bump do kit? (git push)"*. Run `commands.pr` only on a yes. |
+| `use-pin` | Show the exact command `npx wize-dev-kit@<pin>`, with `<pin>` from `project.pin`. Run nothing. |
+| `install` | Show `commands.install` (see `wize-onboarding`). |
+| `none` | Say nothing. |
+
+Exception: when `reason` is `pin-unpublished`, the project pin is newer than the registry's latest, and `commands.update` lowers it (`--allow-downgrade`). Never run it unattended. Ask first: *"O pin do projeto (<pin>) é mais novo que o último publicado (<latest>). Rebaixar o pin?"*, and run it only on a yes. Do not offer the PR as a "bump".
+
+Exception: when `reason` is `kit-not-on-branch` (`action` is `none`), this linked worktree's branch has no kit while `kit_at` does. One line: merge the kit into this branch, or install here with `install --here`. Do not run `install`.
+
+`disabled: true` only turns off update checks: `action` can still be `hydrate`, `use-pin` or `install`, so follow it.
+
+Loop guard: run `version-check` and its follow-up command once per conversation. After a `hydrate` or `update`, do not run `version-check` again to confirm.
 
-Phrase as one short line, not a banner — and only the **first time in this conversation**. If you already mentioned it earlier in this session, don't repeat it.
+No Bash: one line suggesting `/wize-update`.
 
 ## Step 3 — respond
 

package/src/orchestrator-skills/wize-update/skill.md

@@ -1,7 +1,7 @@
 ---
 
 code: wize-update
-description: "Use quando o usuário pedir para atualizar o Wize Dev Kit, perguntar se há uma versão nova, ou quando o Wizer notar version skew (Step 2.5) e ele confirmar o update."
+description: "Use quando o usuário pedir para atualizar o Wize Dev Kit, perguntar se há uma versão nova, notar que as skills ou os comandos /wize sumiram (worktree nova), ou quando o Wizer detectar `action` hydrate ou update no Step 2.5."
 name: Update (Wizer)
 module: orchestrator
 owner: wize-orchestrator
@@ -11,51 +11,57 @@ aliases: []
 
 # Wizer · `/wize-update`
 
-**Goal.** Bring the installed kit up to date safely: check the real version skew, show what changes before anything runs, get a one-line confirmation, apply it, report the result. Never a surprise — this rewrites files under version control.
+**Goal.** Keep the kit healthy in this checkout. Hydrate it when its skills are missing, and prepare a kit bump as a branch and a PR. Hydrate and the isolated update run without asking. The confirmations are the `git push` and any edit to tracked files in the user's own checkout.
 
-## Step 1 — check version skew
+## Step 1 — read the state
 
 If you have Bash, run:
 
 ```
-npx wize-dev-kit version-check --json
+npx --yes --fetch-retries=0 wize-dev-kit version-check --json
 ```
 
-Cheap by design: it reads a local 1h cache before touching the network, caps any registry call at ~1.5s, and degrades to `{"latest":null}` silently if offline — it never blocks this step.
+Obey `action`. Never compare versions by hand. If npx fails (offline), stop and say so.
 
-Read `kit_version` from `.wize/config/project.toml` — that is the version **this project's** rendered skills are on. `version-check`'s `installed` field is the kit version currently resolved by `npx` (it can already be newer than what is rendered here, if someone bumped the resolved package without running `update`).
-
-| Condition | Meaning |
+| `action` | Do |
 |---|---|
-| `latest` (registry) > `installed` | A newer kit exists upstream. |
-| `installed` > project's `kit_version` | This project is behind what npx already resolves. |
-| everything matches, or `latest` is `null` | Nothing to do — say so in one line and stop. Do not continue to Step 2. |
+| `hydrate` | Step 2. |
+| `update` | Step 3. |
+| `use-pin` | Show the exact command `npx wize-dev-kit@<pin>`, with `<pin>` from `project.pin`. Stop. |
+| `install` | No `.wize/` here: show `commands.install` and route to `wize-onboarding`. Stop. |
+| `none` | One line saying the kit is up to date. Stop. When `reason` is `kit-not-on-branch`, say instead: merge the kit into this branch, or install here with `install --here`; run nothing. |
 
-## Step 2 — show the jump, then confirm
+## Step 2 — hydrate
 
-State the version jump plainly (`{from} → {to}`). If you have Bash, `sed -n`/`cat` the relevant excerpt of `CHANGELOG.md` between those versions for a one-line summary of what changed — or trust the excerpt `update` itself prints in Step 3 and summarize that instead.
+Run `commands.hydrate`. It renders the skills and commands for this checkout from `project.toml` and writes only git-ignored files, so it needs no confirmation. This is the path for a new worktree whose `/wize-*` commands are missing.
 
-Ask one line: *"Atualizar o kit de {from} para {to}? Isso vai re-renderizar os adapters instalados (claude-code, generic, …) e regravar `kit_version` em `project.toml`."*
+Then run Step 1 once more. If `action` is now `update`, continue to Step 3; otherwise stop. Do not run it a third time.
 
-Never run Step 3 without this confirmation — it rewrites rendered skill/command files that live under version control, and the resulting diff should land as the user's own reviewed commit, not an unreviewed surprise.
+## Step 3 — update
 
-## Step 3 — run it
+Run `npx --yes wize-dev-kit@latest update`, without asking. It is local: it commits on a `chore/wize-kit-<version>` branch inside a temporary worktree and never touches this checkout, its index, or the default branch. Relay the branch name and the CHANGELOG excerpt it prints. It is idempotent, and it never touches `.wize/config/user.toml`, `.wize/custom/`, or any artifact.
 
-On confirmation:
+## Step 4 — open the PR
 
-```
-npx wize-dev-kit@latest update
-```
+Ask once: *"Abrir PR do bump do kit? (git push)"*. On a yes, run `npx --yes wize-dev-kit@latest update --pr`. On a no, stop after the branch.
+
+Fallbacks:
+
+- No `origin` remote: `update --pr` exits 1 and keeps the branch. Show `git push -u origin chore/wize-kit-<version>` for when a remote exists.
+- No `gh`: relay the compare URL that `update --pr` prints.
+- Not a git repo: `update` already edits in place. Say so and skip this step.
+- The commit fails (a hook rejects it, or changes files outside the update): relay the hook's error and stop. Switching branches and `update --in-place` write into the user's own checkout, next to their uncommitted work, so offer that path and run it only after a yes.
 
-Relay its output — it already reports per-adapter results and a CHANGELOG excerpt. It is idempotent and additive: it never touches `.wize/config/user.toml`, never removes custom agents/skills under `.wize/custom/`, and only rewrites the `kit_version` line in `project.toml`.
+Rules: never commit on the default branch, never force-push, never merge.
 
-## Step 4 — close the loop
+## Step 5 — close the loop
 
-- Flag any adapter the output reported as `skipped` or `error` — those need a manual look.
-- Repeat, in one line, that the IDE/harness needs a restart to pick up refreshed slash commands.
-- Suggest reviewing the diff (`git status` / `git diff`) before committing — this is a real file change, not a no-op.
+- Relay the PR URL, or the branch name when no PR was opened.
+- Other worktrees hydrate themselves after the merge, on their next session.
+- Repeat in one line that the harness needs a restart to pick up refreshed slash commands.
+- Flag any adapter the output reported as `skipped` or `error`; those need a manual look.
 
 ## When NOT to use
 
-- No `.wize/` folder at all → this is a fresh install, not an update. Route to `npx wize-dev-kit install` (see `wize-onboarding`).
-- The user only wants to know whether an update exists, without applying it → Step 1 alone answers that; do not push into Step 2/3 unasked.
+- The user only wants to know whether an update exists: Step 1 alone answers that. Do not push into Step 3 unasked.
+- No `.wize/` folder at all: this is a fresh install, not an update. Route to `npx wize-dev-kit install` (see `wize-onboarding`).