wize-dev-kit 0.26.1 → 0.27.2

package/ARCH.md

@@ -205,7 +205,8 @@ wize-dev-kit install
   ├─ Se brownfield: oferece `wize-document-project`
   └─ Se ok: dispara onboarding (Wizer → Pepper/Mantis/Tony)
 
-wize-dev-kit update   # diff + preserva customizações
+wize-dev-kit update   # converge: pin + .gitignore + bloco AGENTS, via branch isolada/PR
+wize-dev-kit hydrate  # renderiza um checkout/worktree a partir do pin, sem tocar arquivos rastreados
 wize-dev-kit uninstall # remove kit, preserva código
 wize-dev-kit agent create | edit | list
 wize-dev-kit workflow create

package/CHANGELOG.md

@@ -7,6 +7,70 @@ Format inspired by [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 > **0.10.0 and earlier are in Brazilian Portuguese** and are kept verbatim as a
 > historical record (not back-translated).
 
+## [0.27.2] — 2026-10-19
+
+### Fixed
+
+- **Publish smoke test** cleared the job-level `WIZE_SKIP_BASELINE` for its explicit `document-project quick` step, which honors that variable since 0.27.0. Neither 0.27.0 nor 0.27.1 reached npm; 0.27.2 is the first published release with the worktree-safe hydrate and automatic updates.
+
+## [0.27.1] — 2026-10-19
+
+### Fixed
+
+- **`update` in a repo with no commits yet** (`git init`, nothing committed) failed with "cannot determine default branch". With no history there is no base to branch from and nothing committed to protect, so it now updates in place, like a non-git project. `--pr` still refuses. This failure blocked the 0.27.0 publish.
+
+## [0.27.0] — 2026-10-19
+
+**0.27.0: worktree-safe hydrate and automatic updates.** A new `git worktree` used to start without `/wize` because the generated skills are gitignored, and `update` edited whatever checkout you ran it from. Now `hydrate` renders any checkout from the `kit_version` pin, agents and hooks run it on their own, and `update` prepares the bump on an isolated branch. Guide: [`docs/WORKTREES.md`](docs/WORKTREES.md).
+
+### Added
+
+- **`hydrate`**: renders the current checkout from `.wize/config/project.toml`. No prompts, no stdin, no baseline, no mutating git command. Copies `user.toml` from the primary checkout (or `$ORCA_ROOT_PATH` when it belongs to the same repository) and, when no source has one, generates it from git `user.name` / `$USER`; delegates to `npx wize-dev-kit@<pin>` for pins from 0.27.0 so every worktree renders exactly the pin, and writes `.wize/.local/hydrated.json`. Always exits 0; `--strict` exits 1 on failure. Flags: `--root`, `--json`, `--quiet`, `--if-needed`, `--no-delegate`, `--no-notice`.
+  - **Safe writes.** It refuses any write that resolves outside the project (a skills directory symlinked elsewhere in the repository or into another repository) and any file git tracks, listing the whole repository, and refuses every existing file when git cannot list tracked files. Vetoed directories are not created. Read-only git calls use `GIT_OPTIONAL_LOCKS=0`, so a session-start hydrate never takes `index.lock` next to your own git commands.
+  - **Root.** `--root` > `WIZE_PROJECT_ROOT` > the project found from the current directory > `ORCA_WORKTREE_PATH` (used only when the current directory is in no project). A shell in worktree B never renders worktree A because of an inherited Orca variable.
+  - **Delegation.** The child receives `WIZE_PROJECT_ROOT`. The `npx` call uses `--prefer-offline` for an exact pin, turns npm's fetch retries off, sets a 20 s fetch timeout and is capped at 45 s; an attempt killed by its cap is not retried. A failed delegation prints one fallback line instead of npm's raw error (`WIZE_VERBOSE=1` shows it) and renders with the local binary. That fallback render records the targeted pin next to the binary version and a `fallback` flag, so `version-check` and `--if-needed` do not report it stale for an hour; after that the next `hydrate --if-needed` (and the managed hook) tries the exact pin again. `--if-needed` also notices a missing `wize` alias entrypoint.
+- **`version-check` next action**: `--json` (schema 2) now carries the project pin, hydration state, `action` (`none|hydrate|update|use-pin|install`) and the exact `commands` to run, so agents never compare versions. `--exit-code` maps the action to 0/10/11/12/13. `--refresh --quiet` is the background cache refresher. A pin must be plain `N.N.N[-pre]` to appear in a command; otherwise the unpinned command is used and `pin_status` is `invalid` (`action: update`, `reason: pin-invalid`). A pin newer than the registry is judged on a fresh answer only: `pin-unpublished` (and the downgrade it suggests) needs a registry answer fetched just now whose published-versions list lacks the pin (a prerelease published under another dist-tag is not unpublished); a cached `latest` yields `use-pin`. `/wize`, `/wize-help` and the `AGENTS.md` bootstrap block ask before running it, phrased as a downgrade, and the commit subject says `downgrade kit`. The skills and the bootstrap block run `version-check` with `--fetch-retries=0` and skip the step when npx fails.
+- **`update` modes**: `--pr` (push the branch, open the PR with `gh` or print the compare URL; when `origin` already carries the update branch it is reused and `update` goes straight to the PR step, so the weekly Action also works after its first run), `--in-place` (edit the checkout, never commit; `--no-render` skips the adapter re-render), `--check` (exit 0/11/12), `--dry-run`, `--base <ref>`, `--allow-downgrade`, `--json`. `update` compares semver properly (`0.27.0-rc.1` sorts below `0.27.0`), refuses to downgrade without `--allow-downgrade`, and re-reads `project.toml` before reporting success. `--in-place` also refuses (exit 1, nothing written) when a tracked generated file its re-render would overwrite has uncommitted edits; commit or stash them, or pass `--no-render`.
+- **`hooks install|print`**: opt-in automation. `install` writes the managed `.wize/hooks/hydrate.sh` plus the config for `--claude` (SessionStart), `--cursor` (`worktrees.json`) and `--github-action` (weekly bump PR). `print` shows snippets for Orca, Claude Code, Cursor, Codex and the Action without writing anything. The script accepts only `N.N.N[-pre]` pins (anything else, such as `1.2.3.4:host/repo` that npm reads as a git spec, falls back to `@latest`), uses `--prefer-offline` for an exact pin, caps each attempt at 55 s when `timeout` exists (a capped attempt is not retried, so an offline session stays within the 180 s SessionStart timeout), and stops retrying when the registry answers `ETARGET` (the pin is not published). Like the CLI, it hydrates `CLAUDE_PROJECT_DIR`, else the project found from its working directory (up to the git boundary), and only then `ORCA_WORKTREE_PATH`; a prerelease pin of 0.27.0 counts as older than 0.27.0 and runs `sync`.
+- **`doctor --json` and `--strict`**: new hydration section (marker, pin, `user.toml`, per-target status), leak checks (tracked alias files, `.gitignore` drift), directional version skew, primary-checkout or linked-worktree facts. `--strict` exits 1 on any error-level suggestion. Without a TTY `doctor` starts no background registry refresh.
+- **`AGENTS.md` bootstrap block**: version-agnostic, tells any harness to run `version-check --json` and follow `action`. New `AGENTS.md` files get it; `update` adds it to a kit-generated file and never edits a foreign one.
+- **Root and name flags**: `--root <dir>` and `WIZE_PROJECT_ROOT` for `sync`, `update`, `doctor`, `agent`, `document-project` and `version-check`; `install --here`, `--user-name`, `--project-name`, `--baseline`; `document-project --force`; `WIZE_SKIP_BASELINE=1` also skips `document-project quick`.
+- **Docs**: `docs/WORKTREES.md` and `docs/WORKTREES.pt-BR.md`, a "Worktrees & automatic updates" section in the three READMEs, and a hydrate line in every harness doc.
+
+### Changed
+
+- **`update` prepares an isolated branch by default.** In a git repo it fetches, works in a temporary worktree off `origin/<default>`, commits `chore/wize-kit-<version>` there (pin, managed `.gitignore` block, `AGENTS.md` block, `hydrate.sh`, untracked alias files) and removes the worktree. The worktree is a full checkout of the base with hooks disabled for the checkout step and LFS objects not downloaded (pointer files stay pointers). The commit still runs the project's hooks, and `update` aborts without creating or moving the branch if a hook changes files outside the plan. It removes only its own worktree registration and never runs a repo-wide `git worktree prune`. It never touches your checkout, index or branch and never commits on the default branch. Outside git it keeps editing in place. `--in-place` refuses, writing nothing, when a tracked file it would overwrite has uncommitted edits: the files it edits and every directory the configured adapters render into (including `.github/agents/` and `.opencode/commands/`); `--no-render` skips the second check. It also asks the renderer which paths it would write (a probe that writes nothing) and refuses when one resolves, through a symlinked output directory, to a tracked file with uncommitted edits, and it refuses when git cannot report status (failing closed). The PR title and body use the same verb as the commit (`bump`, `downgrade` or `converge`).
+- **`install` is idempotent.** On a project that already has `project.toml` it hydrates and exits 0; conflicting `--profiles`, `--targets` or `--lang` exit 1 with a pointer to `project.toml`, before anything is printed. From a subdirectory of an installed project it refuses (`--here` overrides); with no `project.toml` and a cwd that is not the repo root, `--yes` refuses unless `--here`. In a linked worktree whose branch has no `project.toml` while the primary checkout does, `install --yes` skips quietly (exit 0) and interactive `install` exits 1, with a pointer to merge the kit or pass `--here`; in a bare repository with worktrees the kit is looked up in the default-branch worktree, then any other non-bare worktree. `version-check` and `doctor` report that situation as `action: none`, `reason: kit-not-on-branch` (a doctor warning, no `install` suggestion). Hooks that run `install --yes` never start a second install. In a linked worktree the default project name is the primary checkout's.
+- **`uninstall` resolves the project root**, prints `uninstalling from <root>` and refuses from a subdirectory (exit 1) unless you pass `--root` or set `WIZE_PROJECT_ROOT`.
+- **The document-project baseline is non-destructive.** `quick` and `initial_scan` keep existing files (a dated bullet survives); `--force` overwrites; `full_rescan` still rewrites. A fresh install skips the baseline when docs already exist. `doctor`'s "no scan state" hint now points at `initial_scan`, the mode that writes state.
+- **`.gitignore` managed block**: each generated location gets its `wize-*` glob plus an explicit alias line (`wize/`, `wize.mdc`, `wize.md`, `wize.prompt`), and `.claude/worktrees/` is ignored. `uninstall` removes alias entries by exact path for the configured targets only.
+- **Version hints never wait on the network.** The registry answer is stale-while-revalidate: cached at any age, TTL from `fetched_at`, one detached refresh per 10 minutes, none in CI, without a TTY, with `WIZE_DISABLE_UPDATE_CHECK=1` or with `WIZE_NO_BG_REFRESH=1`. The hint line itself stays silent without a TTY. `WIZE_DISABLE_UPDATE_CHECK=1` also turns the `update` action into `none`.
+- **Renders write only what changed**, through atomic temp-file renames, so concurrent worktrees and agents cannot corrupt each other. `sync` and `update --in-place` write atomically but unguarded. `hydrate` and in-place `update` print "N written, M unchanged"; `sync` keeps "N file(s) emitted". A fresh `install` writes the hydration marker too.
+- **`sync`** warns on skew in both directions, writes the hydration marker, never writes `user.toml`, `.gitignore` or `kit_version`, and suggests `hydrate` when the pin is 0.27.0 or later.
+- **`/wize` and `/wize-help` Step 2.5** follow the `action` table: hydrate and the local update branch run without asking, with one confirmation before `update --pr`. **`/wize-update`** is now kit maintenance in five steps instead of a confirm-then-apply flow.
+- **Root detection** walks up to the enclosing git checkout, so commands run from a subdirectory or a linked worktree find `project.toml`.
+
+### Fixed
+
+- **`update` could write through a tracked symlink.** A symlinked `.gitignore` (common in dotfiles setups) read back as its target path and the managed block was written through the link into the user's real file. Plan sources now treat a symlink or gitlink as not a file: a symlinked `.gitignore` is left alone, and the write step refuses (exit 1, nothing written) any target, or directory above it, that is a symlink.
+- **`<command> --help` ran the command.** `update --help` ran the update and `install --help` ran an install. `--help` and `-h` now print the help for every command and run nothing.
+- **`update` could lower the pin and print success** when `kit_version` was not written. See the `update` modes above for the semver comparison, the downgrade guard and the verified write.
+- **`doctor` in linked worktrees** treated a `.git` file as no repository and suggested `git init`; it now reads the real repository, including detached HEADs. The `head: ?` line shows the SHA.
+- **`doctor` and sprint status**: `sprint-status.yaml` is recognized (the `.md` name stays as a fallback), and OpenCode counts both `.opencode/agents` and `.opencode/commands`.
+- **CLI parsing**: `--key=value` keeps a value that contains `=`. **TOML**: `#` inside a quoted string is no longer read as a comment.
+
+### Migration
+
+1. In each repo, run `npx wize-dev-kit@latest update --pr` once and merge the PR.
+2. The PR untracks the alias files earlier versions committed by accident (for example `.cursor/rules/wize.mdc`). Other worktrees lose them when they pull the merge until `hydrate` runs; the session loop or a hook does that on its own, or run `npx wize-dev-kit hydrate`.
+3. Optional: `npx wize-dev-kit hooks install --claude --cursor --github-action` for hydrate on worktree creation and a weekly bump PR.
+
+### Breaking notes
+
+- In a git repo `update` no longer edits the checkout unless you pass `--in-place`. Scripts that relied on that must pass the flag or merge the branch it prepares.
+- `install` on an installed project is `hydrate`; flags that conflict with `project.toml` are rejected instead of ignored.
+- `sync` output counts changed as well as unchanged files ("emitted"); parse `--json` outputs of `hydrate`, `update` and `version-check` instead of human text.
+
 ## [0.26.1] — 2026-10-19
 
 ### Fixed

package/README.es.md

@@ -158,8 +158,9 @@ Transversales:
     /wize-check                 Checklist de avance de la demanda en vuelo: hecho
                                 (con evidencia), en curso, lo que falta — luego
                                 retoma el trabajo interrumpido.
-    /wize-update                Revisa si el kit está desactualizado, muestra el
-                                changelog, confirma y aplica la actualización.
+    /wize-update                Mantenimiento del kit: hidrata un checkout sin skills,
+                                prepara la rama del bump localmente y abre el PR
+                                tras una confirmación de push.
     /wize-grill                 Entrevista-hasta-entendimiento antes de cualquier
                                 paso de autoría.
     /wize-no-ai-slop            Higiene de escrita para texto de usuario final:
@@ -239,11 +240,31 @@ Con el perfil **Wize Security** instalado, **Natasha Romanoff** (`wize-sec-red-t
 
 ---
 
+## Worktrees y actualizaciones automáticas
+
+Un `git worktree` nuevo no tiene las skills generadas (están en el `.gitignore`). Un comando lo resuelve:
+
+```bash
+npx wize-dev-kit hydrate    # renderiza este checkout desde project.toml; no escribe en archivos rastreados
+```
+
+- El pin `kit_version` en `.wize/config/project.toml` decide qué kit renderiza el repo, para todo el equipo.
+- `/wize` lee el pin e hidrata un checkout vacío sin preguntar. `hooks install` (Claude Code, Cursor) y `hooks print` (Orca, Codex) hacen lo mismo al crear el worktree. Una GitHub Action semanal abre el PR de bump.
+- `update` prepara `chore/wize-kit-<versión>` en un worktree desechable. Nunca toca tu checkout ni la rama por defecto; `--pr` hace push y abre el PR. En un repo existente, ejecuta `npx wize-dev-kit@latest update --pr` una vez y haz el merge.
+- Para desactivar la consulta al registry, usa `WIZE_DISABLE_UPDATE_CHECK=1`.
+
+Guía completa: [`docs/WORKTREES.md`](docs/WORKTREES.md) (en inglés; también en [pt-BR](docs/WORKTREES.pt-BR.md)).
+
+---
+
 ## Comandos de la CLI
 
 ```bash
 npx wize-dev-kit install         # setup interactivo
-npx wize-dev-kit update          # actualiza un kit instalado a la versión actual
+npx wize-dev-kit update          # prepara la rama de bump del kit en un worktree temporal (--pr, --check, --in-place)
+npx wize-dev-kit update --pr     # también hace push de la rama y abre el PR
+npx wize-dev-kit hydrate         # renderiza un checkout/worktree nuevo desde el pin; nunca toca archivos rastreados
+npx wize-dev-kit hooks <install|print>  # automatización opt-in: hydrate al crear worktree/sesión, PR semanal de bump
 npx wize-dev-kit sync            # re-renderiza los adapters de IDE tras editar la config
 npx wize-dev-kit list            # lista agentes, skills y workflows instalados
 npx wize-dev-kit agent list      # lista agentes nativos + personalizados
@@ -251,13 +272,13 @@ npx wize-dev-kit agent create    # crea un nuevo agente personalizado (validado
 npx wize-dev-kit agent edit <code>  # sobrescribe un agente nativo
 npx wize-dev-kit workflow list   # lista workflows nativos + personalizados
 npx wize-dev-kit workflow create # crea un nuevo workflow personalizado
-npx wize-dev-kit doctor          # diagnostica kit / proyecto / adapters / gates
+npx wize-dev-kit doctor [--json] [--strict]  # diagnostica kit / proyecto / hidratación / adapters / gates
 npx wize-dev-kit validate        # chequeos estructurales en los assets del kit
-npx wize-dev-kit document-project [quick|initial_scan|full_rescan|deep_dive] [--resume] [--target <path>]
+npx wize-dev-kit document-project [quick|initial_scan|full_rescan|deep_dive] [--resume] [--force] [--target <path>]
 npx wize-dev-kit uninstall       # elimina .wize/ (tu código queda intacto)
 npx wize-dev-kit help            # referencia de comandos
 npx wize-dev-kit version         # imprime la versión instalada del kit
-npx wize-dev-kit version-check [--json]  # instalada vs. más reciente (con caché; scriptable; nunca bloquea)
+npx wize-dev-kit version-check [--json] [--exit-code]  # pin, hidratación y registry; indica la siguiente acción (con caché; como máximo ~1,5 s de espera del registry)
 ```
 
 ---
@@ -269,6 +290,7 @@ npx wize-dev-kit version-check [--json]  # instalada vs. más reciente (con cach
 - [`AGENTS.md`](AGENTS.md) — el roster generado + el contexto operativo que las IDEs leen en la raíz del repo.
 - [`DECISIONS.md`](DECISIONS.md) — registro de decisiones.
 - [`CHANGELOG.md`](CHANGELOG.md) — historial de releases.
+- [`docs/WORKTREES.md`](docs/WORKTREES.md) — worktrees, hydrate, hooks y el flujo de update (en inglés; también en [pt-BR](docs/WORKTREES.pt-BR.md)).
 - [`docs/harnesses/`](docs/harnesses/) — un doc por [harness soportado](#harnesses-soportados), en inglés + [pt-BR](README.pt-BR.md#harnesses-suportadas).
 
 ---

package/README.md

@@ -156,8 +156,9 @@ Cross-cutting:
     /wize-check                 Progress checklist for the demand in flight:
                                 done (with evidence), in progress, what's left —
                                 then resumes the interrupted work.
-    /wize-update                Checks kit version skew, shows the changelog
-                                jump, confirms, then applies the update.
+    /wize-update                Kit maintenance: hydrates a checkout with missing
+                                skills, prepares the kit-bump branch locally, and
+                                opens the PR after one push confirmation.
     /wize-grill                 Interview-to-understanding before any authoring step.
     /wize-eli5                  Explain anything to anyone — vocabulary, analogies,
                                 tone, depth and framing calibrated to the audience
@@ -238,24 +239,44 @@ When the **Wize Security** profile is installed, **Natasha Romanoff** (`wize-sec
 
 ---
 
+## Worktrees & automatic updates
+
+A new `git worktree` has no generated skills (they are gitignored). One command fixes it:
+
+```bash
+npx wize-dev-kit hydrate    # render this checkout from project.toml; writes no tracked file
+```
+
+- The `kit_version` pin in `.wize/config/project.toml` decides which kit renders the repo, for everyone.
+- `/wize` reads the pin and hydrates a bare checkout without asking. `hooks install` (Claude Code, Cursor) and `hooks print` (Orca, Codex) do the same when a worktree is created. A weekly GitHub Action opens the bump PR.
+- `update` prepares `chore/wize-kit-<version>` in a throwaway worktree. It never touches your checkout or the default branch; `--pr` pushes it and opens the PR. In an existing repo, run `npx wize-dev-kit@latest update --pr` once and merge.
+- Opt out of registry checks with `WIZE_DISABLE_UPDATE_CHECK=1`.
+
+Full guide: [`docs/WORKTREES.md`](docs/WORKTREES.md).
+
+---
+
 ## CLI commands
 
 ```bash
 npx wize-dev-kit install         # interactive setup
-npx wize-dev-kit update          # bring an installed kit up to the current version
+npx wize-dev-kit update          # prepare the kit-bump branch in a temp worktree (--pr, --check, --in-place)
+npx wize-dev-kit update --pr     # also push the branch and open the PR
+npx wize-dev-kit hydrate         # render a fresh checkout/worktree from the pin; never touches tracked files
+npx wize-dev-kit hooks <install|print>  # opt-in automation: hydrate on worktree/session start, weekly bump PR
 npx wize-dev-kit sync            # re-render IDE adapters after editing config
 npx wize-dev-kit list            # list installed agents, skills and workflows
 npx wize-dev-kit agent list      # list built-in + custom agents
 npx wize-dev-kit agent create    # scaffold a new custom agent (validated + dry-run)
 npx wize-dev-kit agent edit <code>  # override a built-in agent
 npx wize-dev-kit workflow <create|list>  # scaffold or list custom workflows
-npx wize-dev-kit doctor          # diagnose kit / project / adapters / gates
+npx wize-dev-kit doctor [--json] [--strict]  # diagnose kit / project / hydration / adapters / gates
 npx wize-dev-kit validate        # structural checks on the kit assets
-npx wize-dev-kit document-project [quick|initial_scan|full_rescan|deep_dive] [--resume] [--target <path>]
+npx wize-dev-kit document-project [quick|initial_scan|full_rescan|deep_dive] [--resume] [--force] [--target <path>]
 npx wize-dev-kit uninstall       # remove .wize/ (your code is left untouched)
 npx wize-dev-kit help            # command reference
 npx wize-dev-kit version         # print the installed kit version
-npx wize-dev-kit version-check [--json]  # installed vs latest (cached; scriptable; never blocks)
+npx wize-dev-kit version-check [--json] [--exit-code]  # pin, hydration and registry; names the next action (cached; at most ~1.5 s registry wait)
 ```
 
 ---
@@ -267,6 +288,7 @@ npx wize-dev-kit version-check [--json]  # installed vs latest (cached; scriptab
 - [`AGENTS.md`](AGENTS.md) — the generated roster + operating context IDEs read at the repo root.
 - [`DECISIONS.md`](DECISIONS.md) — decisions log.
 - [`CHANGELOG.md`](CHANGELOG.md) — release history.
+- [`docs/WORKTREES.md`](docs/WORKTREES.md) — worktrees, hydrate, hooks and the update flow.
 - [`docs/harnesses/`](docs/harnesses/) — one doc per [supported harness](#supported-harnesses), in English + [pt-BR](README.pt-BR.md#harnesses-suportadas).
 
 ---

package/README.pt-BR.md

@@ -157,8 +157,9 @@ Transversais:
     /wize-check                 Checklist de acompanhamento da demanda em voo:
                                 feito (com evidência), em andamento, o que falta —
                                 depois retoma o trabalho interrompido.
-    /wize-update                Verifica se o kit está desatualizado, mostra o
-                                changelog, confirma e aplica o update.
+    /wize-update                Manutenção do kit: hidrata um checkout sem skills,
+                                prepara a branch do bump localmente e abre o PR
+                                após uma confirmação de push.
     /wize-grill                 Entrevista-até-entendimento antes de qualquer passo
                                 de autoria.
     /wize-eli5                  Explique qualquer coisa a qualquer um — vocabulário,
@@ -241,24 +242,44 @@ Com o perfil **Wize Security** instalado, **Natasha Romanoff** (`wize-sec-red-te
 
 ---
 
+## Worktrees & atualizações automáticas
+
+Um `git worktree` novo não tem as skills geradas (elas estão no `.gitignore`). Um comando resolve:
+
+```bash
+npx wize-dev-kit hydrate    # renderiza este checkout a partir do project.toml; não escreve em arquivo rastreado
+```
+
+- O pin `kit_version` em `.wize/config/project.toml` decide qual kit renderiza o repo, para todo o time.
+- O `/wize` lê o pin e hidrata um checkout vazio sem perguntar. O `hooks install` (Claude Code, Cursor) e o `hooks print` (Orca, Codex) fazem o mesmo na criação do worktree. Uma GitHub Action semanal abre o PR de bump.
+- O `update` prepara `chore/wize-kit-<versão>` num worktree descartável. Nunca toca seu checkout nem a branch default; `--pr` faz push e abre o PR. Num repo existente, rode `npx wize-dev-kit@latest update --pr` uma vez e faça o merge.
+- Para desligar a consulta ao registry, use `WIZE_DISABLE_UPDATE_CHECK=1`.
+
+Guia completo: [`docs/WORKTREES.pt-BR.md`](docs/WORKTREES.pt-BR.md).
+
+---
+
 ## Comandos da CLI
 
 ```bash
 npx wize-dev-kit install         # setup interativo
-npx wize-dev-kit update          # atualiza um kit instalado para a versão atual
+npx wize-dev-kit update          # prepara a branch de bump do kit num worktree temporário (--pr, --check, --in-place)
+npx wize-dev-kit update --pr     # também faz push da branch e abre o PR
+npx wize-dev-kit hydrate         # renderiza um checkout/worktree novo a partir do pin; nunca toca arquivos rastreados
+npx wize-dev-kit hooks <install|print>  # automação opt-in: hydrate ao criar worktree/sessão, PR semanal de bump
 npx wize-dev-kit sync            # re-renderiza os adapters de IDE após editar a config
 npx wize-dev-kit list            # lista agentes, skills e workflows instalados
 npx wize-dev-kit agent list      # lista agentes nativos + customizados
 npx wize-dev-kit agent create    # cria um novo agente customizado (validado + dry-run)
 npx wize-dev-kit agent edit <code>  # sobrescreve um agente nativo
 npx wize-dev-kit workflow <create|list>  # cria ou lista workflows customizados
-npx wize-dev-kit doctor          # diagnostica kit / projeto / adapters / gates
+npx wize-dev-kit doctor [--json] [--strict]  # diagnostica kit / projeto / hidratação / adapters / gates
 npx wize-dev-kit validate        # checagens estruturais nos assets do kit
-npx wize-dev-kit document-project [quick|initial_scan|full_rescan|deep_dive] [--resume] [--target <path>]
+npx wize-dev-kit document-project [quick|initial_scan|full_rescan|deep_dive] [--resume] [--force] [--target <path>]
 npx wize-dev-kit uninstall       # remove .wize/ (seu código permanece intacto)
 npx wize-dev-kit help            # referência de comandos
 npx wize-dev-kit version         # imprime a versão instalada do kit
-npx wize-dev-kit version-check [--json]  # instalada vs. mais recente (com cache; scriptável; nunca bloqueia)
+npx wize-dev-kit version-check [--json] [--exit-code]  # pin, hidratação e registry; indica a próxima ação (com cache; no máximo ~1,5 s de espera pelo registry)
 ```
 
 ---
@@ -270,6 +291,7 @@ npx wize-dev-kit version-check [--json]  # instalada vs. mais recente (com cache
 - [`AGENTS.md`](AGENTS.md) — o roster gerado + contexto operacional que as IDEs leem na raiz do repo.
 - [`DECISIONS.md`](DECISIONS.md) — log de decisões.
 - [`CHANGELOG.md`](CHANGELOG.md) — histórico de releases.
+- [`docs/WORKTREES.pt-BR.md`](docs/WORKTREES.pt-BR.md) — worktrees, hydrate, hooks e o fluxo de update.
 - [`docs/harnesses/`](docs/harnesses/) — um doc por [harness suportada](#harnesses-suportadas), em português + [English](README.md#supported-harnesses).
 
 ---

package/adapters/continue/render.js

@@ -5,9 +5,8 @@
 
 'use strict';
 
-const fs = require('node:fs');
 const path = require('node:path');
-const { collectAssets, escapeYamlDouble, clipOneLine, ensureDir } = require('../../tools/installer/render-shared.js');
+const { collectAssets, escapeYamlDouble, clipOneLine, ensureDir, writeFileIfChanged } = require('../../tools/installer/render-shared.js');
 
 function render(kitRoot, projectRoot, opts = {}) {
   const targetDir = path.join(projectRoot, '.continue', 'prompts');
@@ -33,7 +32,7 @@ function render(kitRoot, projectRoot, opts = {}) {
     if (opts.dryRun) {
       written.push(`[dry-run] ${a.code}.prompt`);
     } else {
-      fs.writeFileSync(path.join(targetDir, `${a.code}.prompt`), content, 'utf-8');
+      writeFileIfChanged(path.join(targetDir, `${a.code}.prompt`), content);
       written.push(`${a.code}.prompt`);
     }
   }

package/adapters/copilot/render.js

@@ -20,14 +20,14 @@
 
 'use strict';
 
-const fs = require('node:fs');
 const path = require('node:path');
 const {
   collectAssets,
   renderAnthropicSkills,
   escapeYamlDouble,
   clipOneLine,
-  ensureDir
+  ensureDir,
+  writeFileIfChanged
 } = require('../../tools/installer/render-shared.js');
 
 function render(kitRoot, projectRoot, opts = {}) {
@@ -67,7 +67,7 @@ function render(kitRoot, projectRoot, opts = {}) {
       written.push(`[dry-run] ${a.code}.agent.md`);
       continue;
     }
-    fs.writeFileSync(path.join(agentsDir, `${a.code}.agent.md`), content, 'utf-8');
+    writeFileIfChanged(path.join(agentsDir, `${a.code}.agent.md`), content);
     written.push(`${a.code}.agent.md`);
   }
 

package/adapters/cursor/render.js

@@ -5,9 +5,8 @@
 
 'use strict';
 
-const fs = require('node:fs');
 const path = require('node:path');
-const { collectAssets, escapeYamlDouble, clipOneLine, ensureDir } = require('../../tools/installer/render-shared.js');
+const { collectAssets, escapeYamlDouble, clipOneLine, ensureDir, writeFileIfChanged } = require('../../tools/installer/render-shared.js');
 
 function render(kitRoot, projectRoot, opts = {}) {
   const targetDir = path.join(projectRoot, '.cursor', 'rules');
@@ -39,7 +38,7 @@ function render(kitRoot, projectRoot, opts = {}) {
     if (opts.dryRun) {
       written.push(`[dry-run] ${a.code}.mdc`);
     } else {
-      fs.writeFileSync(path.join(targetDir, `${a.code}.mdc`), content, 'utf-8');
+      writeFileIfChanged(path.join(targetDir, `${a.code}.mdc`), content);
       written.push(`${a.code}.mdc`);
     }
   }

package/adapters/generic/render.js

@@ -4,9 +4,8 @@
 
 'use strict';
 
-const fs = require('node:fs');
 const path = require('node:path');
-const { collectAssets, renderAgentsMd, clipOneLine, ensureDir } = require('../../tools/installer/render-shared.js');
+const { collectAssets, renderAgentsMd, clipOneLine, ensureDir, writeFileIfChanged } = require('../../tools/installer/render-shared.js');
 
 function render(kitRoot, projectRoot, opts = {}) {
   const targetDir = path.join(projectRoot, '.wize', 'agents');
@@ -21,7 +20,7 @@ function render(kitRoot, projectRoot, opts = {}) {
     if (opts.dryRun) {
       written.push(`[dry-run] ${a.code}.md`);
     } else {
-      fs.writeFileSync(path.join(targetDir, `${a.code}.md`), content, 'utf-8');
+      writeFileIfChanged(path.join(targetDir, `${a.code}.md`), content);
       written.push(`${a.code}.md`);
     }
   }

package/adapters/opencode/render.js

@@ -10,9 +10,8 @@
 
 'use strict';
 
-const fs = require('node:fs');
 const path = require('node:path');
-const { collectAssets, escapeYamlDouble, clipOneLine, ensureDir } = require('../../tools/installer/render-shared.js');
+const { collectAssets, escapeYamlDouble, clipOneLine, ensureDir, writeFileIfChanged } = require('../../tools/installer/render-shared.js');
 
 // `owner:` in workflow/skill frontmatter is written for humans (agent code,
 // display name, "X + Y" pairings, trailing "# comment"). Resolve it to a
@@ -63,7 +62,7 @@ function render(kitRoot, projectRoot, opts = {}) {
       if (opts.dryRun) {
         written.push(`[dry-run] agents/${a.code}.md`);
       } else {
-        fs.writeFileSync(path.join(agentsDir, `${a.code}.md`), content, 'utf-8');
+        writeFileIfChanged(path.join(agentsDir, `${a.code}.md`), content);
         written.push(`agents/${a.code}.md`);
       }
     } else {
@@ -85,7 +84,7 @@ function render(kitRoot, projectRoot, opts = {}) {
       if (opts.dryRun) {
         written.push(`[dry-run] commands/${a.code}.md`);
       } else {
-        fs.writeFileSync(path.join(commandsDir, `${a.code}.md`), content, 'utf-8');
+        writeFileIfChanged(path.join(commandsDir, `${a.code}.md`), content);
         written.push(`commands/${a.code}.md`);
       }
     }

package/adapters/windsurf/render.js

@@ -5,9 +5,8 @@
 
 'use strict';
 
-const fs = require('node:fs');
 const path = require('node:path');
-const { collectAssets, clipOneLine, ensureDir } = require('../../tools/installer/render-shared.js');
+const { collectAssets, clipOneLine, ensureDir, writeFileIfChanged } = require('../../tools/installer/render-shared.js');
 
 function render(kitRoot, projectRoot, opts = {}) {
   const targetDir = path.join(projectRoot, '.windsurf', 'rules');
@@ -30,7 +29,7 @@ function render(kitRoot, projectRoot, opts = {}) {
     if (opts.dryRun) {
       written.push(`[dry-run] ${a.code}.md`);
     } else {
-      fs.writeFileSync(path.join(targetDir, `${a.code}.md`), content, 'utf-8');
+      writeFileIfChanged(path.join(targetDir, `${a.code}.md`), content);
       written.push(`${a.code}.md`);
     }
   }

package/docs/WORKTREES.md

@@ -0,0 +1,150 @@
+# Worktrees and automatic updates
+
+🌐 **Languages:** **English** · [Português (pt-BR)](WORKTREES.pt-BR.md)
+
+← [Back to README](../README.md)
+
+A fresh `git worktree` has only the files git tracks. The kit's generated skills are not tracked, so a new worktree starts without `/wize` and friends. This guide covers how the kit fixes that on its own, and what each command does to your repo while it happens.
+
+## What lives where
+
+| Kind | Files | In git? | Who writes it |
+|---|---|---|---|
+| Tracked, shared | `.wize/config/project.toml` (holds the `kit_version` pin), `.wize/config/tea.toml`, `.wize/custom/`, planning, solutioning, implementation and knowledge artifacts, `AGENTS.md`, the managed `.gitignore` block, `.wize/hooks/hydrate.sh` and the hook configs from `hooks install` | yes | `install`, `update`, and you |
+| Generated | `wize-*` entries per target (`.claude/skills/`, `.cursor/rules/`, `.github/skills/`, `.agents/skills/`, `.opencode/`, `.wize/agents/`, and the rest), plus the `wize` alias beside them | no, gitignored | `hydrate`, `sync` |
+| Per developer | `.wize/config/user.toml`, `.wize/scratch/`, `.wize/.local/` (the `hydrated.json` marker), `.wize/implementation/quick-dev-log.md` | no, gitignored | `hydrate` (user.toml), you |
+
+`.claude/worktrees/` is gitignored too, so worktrees that Claude Code creates inside the repo never show up in `git status`.
+
+## The pin
+
+`kit_version` in `.wize/config/project.toml` is the single source of truth for which kit renders this repo. Everyone on the team renders exactly that version, whichever `npx` they happened to run.
+
+- `hydrate` renders the pin. For a pin of 0.27.0 or later it re-runs itself as `npx wize-dev-kit@<pin> hydrate` when the binary differs, with a guard (`WIZE_HYDRATE_DELEGATED`) against recursion. If that fails (offline, registry down; an attempt is capped at 45 s and a timed-out attempt is not retried) it renders with the binary it has and prints a warning. That fallback render counts as current for an hour, then the next `hydrate --if-needed` tries the exact pin again.
+- Pins older than 0.27.0 have no `hydrate`. For those, `version-check` names `sync` as the command and never loops.
+- A pin newer than the binary means your `npx` cache is stale. `update` refuses to downgrade the pin unless you pass `--allow-downgrade`.
+
+## New worktree checklist
+
+```bash
+npx wize-dev-kit hydrate
+```
+
+That is the whole checklist. `hydrate`:
+
+- finds the project root from any subdirectory or linked worktree (`--root <dir>` or `WIZE_PROJECT_ROOT` override it);
+- copies `.wize/config/user.toml` from the primary checkout, or derives one from `git config user.name`, and never overwrites an existing one;
+- renders the adapters for the configured targets, skipping files whose content is unchanged;
+- writes the marker `.wize/.local/hydrated.json`;
+- never prompts, never reads stdin, never runs the document-project baseline, and never writes a tracked file.
+
+Before rendering it records `git ls-files`; a render that would overwrite a tracked file is blocked, including one that would reach it through a symlinked directory. If git cannot list tracked files (git missing, or a repository git refuses as unsafe), hydrate leaves every existing file alone and warns. After rendering it compares `git status` and warns if new entries appeared, which usually means the repo's `.gitignore` predates 0.27.0.
+
+To make it automatic, install a hook (next section).
+
+## The automatic loop
+
+1. **Session start.** An agent skill (`/wize`, `/wize-help`) runs `version-check --json` and follows its `action`: `hydrate` and `update` run without asking; the only confirmation is before `update --pr`, because that pushes. The `AGENTS.md` bootstrap block carries the same instruction for harnesses that do not load skills first.
+2. **Worktree creation.** Orca, Cursor and Claude Code can run `.wize/hooks/hydrate.sh` when a worktree or session starts (see the harness matrix).
+3. **Weekly.** A GitHub Action opens a PR that bumps the pin (`hooks install --github-action`).
+4. **After merge.** Each worktree pulls the new pin, sees that its marker is stale, and hydrates itself to the new version.
+
+`version-check` reads the registry through a stale-while-revalidate cache in `$XDG_CACHE_HOME` (or `~/.cache`): the cached answer is returned at any age, and a stale entry starts one detached refresh, at most every 10 minutes. No refresh starts in CI, with `WIZE_DISABLE_UPDATE_CHECK=1` or with `WIZE_NO_BG_REFRESH=1`; the one-line hint after a command also stays silent without a TTY. Command hints and `hydrate` never wait on the network; an explicit `version-check` waits at most about 1.5 s for the registry when the cache is stale.
+
+### Opt out
+
+`WIZE_DISABLE_UPDATE_CHECK=1` turns off the registry lookup and downgrades an `update` action to `none`. Hydration still happens. There is no team-level switch in `project.toml` yet.
+
+## Updating the kit
+
+```bash
+npx wize-dev-kit@latest update          # prepare the bump branch locally
+npx wize-dev-kit@latest update --pr     # also push it and open the PR
+```
+
+In a git repo `update` works in a throwaway worktree:
+
+1. It fetches and branches off `origin/<default>` (or the local default branch if the fetch fails, and says so).
+2. In that worktree it bumps `kit_version`, refreshes the managed `.gitignore` block and the `AGENTS.md` bootstrap block (only in a kit-generated `AGENTS.md`), refreshes `hydrate.sh` when it is installed and managed, and untracks any tracked files under the 12 generated alias paths.
+3. It commits on `chore/wize-kit-<version>` and removes the worktree.
+
+Your checkout, branch, index and uncommitted files are never touched, and `update` never commits on the default branch, so you can run it from a dirty tree or a detached HEAD. `--pr` pushes without force (a rejected push exits 1 and tells you the remote branch diverged) and opens the PR with `gh`, or prints the GitHub compare URL when `gh` is missing.
+
+| Flag | Effect |
+|---|---|
+| `--pr` | Push the branch and open a PR. Counts as consent to push. |
+| `--in-place` | Edit the current checkout instead, re-render, never commit. Always the mode outside a git repo. |
+| `--no-render` | With `--in-place`: skip the adapter re-render. |
+| `--check` | Report only. Exit 0 converged, 11 changes pending, 12 pin ahead of the binary. |
+| `--dry-run` | Print the plan, write nothing, exit 0. |
+| `--base <ref>` | Branch off this ref instead of the default branch. |
+| `--allow-downgrade` | Let the pin move to an older version. |
+| `--json` | One JSON object on stdout. |
+
+### Migrating an existing repo
+
+Run `npx wize-dev-kit@latest update --pr` once per repo and merge the PR. One gotcha: the PR untracks the old alias files (for example `.cursor/rules/wize.mdc`) that earlier versions committed by accident. When another worktree pulls the merge, git deletes those files there. Run `hydrate` in that worktree, or let the session loop do it, and they come back as untracked, gitignored files.
+
+## Harness matrix
+
+`npx wize-dev-kit hooks print <target>` prints the Orca, Claude Code, Cursor, Codex and weekly-Action snippets below without writing anything (the Copilot cloud agent has no print target). `hooks install` writes the managed `.wize/hooks/hydrate.sh` (POSIX sh, always exits 0, prints to stderr) plus the config you ask for with `--claude`, `--cursor` or `--github-action`; it needs at least one of those flags.
+
+| Harness | Setup |
+|---|---|
+| Orca | In `orca.yaml`: `scripts.setup: sh .wize/hooks/hydrate.sh` and `setupAgentStartupPolicy: wait-for-setup`. List `.wize/config/user.toml` in `.worktreeinclude`. A non-empty setup hook saved locally in Orca overrides `orca.yaml`, so clear it in the repo settings. |
+| Claude Code | `hooks install --claude` adds a `SessionStart` entry (matcher `startup`) to `.claude/settings.json`, merged with your existing hooks. Add `.wize/config/user.toml` to `.worktreeinclude` to copy it into worktrees. |
+| Cursor | `hooks install --cursor` writes `.cursor/worktrees.json` with `setup-worktree: ["sh .wize/hooks/hydrate.sh"]`. |
+| Codex | Set the local environment's setup script to `sh .wize/hooks/hydrate.sh`. Codex keeps this in its own config, so the kit only prints it. |
+| GitHub Copilot cloud agent | Add `npx --yes wize-dev-kit hydrate` as a step in `.github/workflows/copilot-setup-steps.yml`. |
+| Weekly bump PR | `hooks install --github-action` writes `.github/workflows/wize-kit-update.yml`. Enable "Allow GitHub Actions to create and approve pull requests" in the repo settings. PRs opened with `GITHUB_TOKEN` do not trigger other workflows, so required checks wait until someone pushes to the branch. |
+
+None of these has been verified end to end in each product; see the last section.
+
+## What `git worktree remove` loses
+
+Everything untracked in that worktree: `user.toml`, `.wize/scratch/`, `.wize/.local/`, `quick-dev-log.md`, and the generated adapters. All of it regenerates with `hydrate` except scratch notes and the quick-dev log, which exist only in that worktree. Commit or copy those first. `.wize/` artifacts (PRD, stories, knowledge) are tracked, so they travel with the branch.
+
+## Concurrency
+
+Several worktrees, or several agents in one worktree, can render at once. Every write goes through write-if-changed plus an atomic temp-file rename, so a reader never sees a half-written skill and a second run reports every file as unchanged. The tracked-file guard means `hydrate` cannot overwrite something you committed. `sync` and `update --in-place` write atomically but unguarded: they are the explicit regenerate commands.
+
+## Environment variables
+
+| Variable | Effect |
+|---|---|
+| `WIZE_PROJECT_ROOT` | Project root when you run a command outside it. `--root` wins over it. |
+| `ORCA_WORKTREE_PATH`, `ORCA_ROOT_PATH` | Read by `hydrate` only: the worktree to render (used only when the current directory is not inside a project), and a source for `user.toml` (used only when it belongs to the same repository). |
+| `WIZE_SKIP_BASELINE=1` | Skip the document-project baseline during `install`, and make `document-project quick` a no-op. |
+| `WIZE_HYDRATE_DELEGATED` | Set by `hydrate` when it delegates to the pinned kit. Do not set it yourself. |
+| `WIZE_DISABLE_UPDATE_CHECK=1` | No registry lookup; `update` action becomes `none`. |
+| `WIZE_NO_BG_REFRESH=1` | Never start the background cache refresh. |
+| `WIZE_VERBOSE=1` | Show the raw `npx` output of a failed delegated `hydrate` (normally one fallback line). |
+| `CI` | Suppresses update hints and background refresh. |
+
+## Exit codes
+
+Defaults stay 0 so existing scripts keep working. The strict forms are opt-in.
+
+| Command | Codes |
+|---|---|
+| `hydrate` | 0 always. `--strict` returns 1 when it could not hydrate. |
+| `version-check --exit-code` | 0 nothing to do, 10 `hydrate`, 11 `update`, 12 `use-pin`, 13 `install`. |
+| `update --check` | 0 converged, 11 changes pending, 12 pin ahead of the binary. |
+| `doctor --strict` | 1 when any error-level suggestion exists. |
+
+`doctor --json` and `version-check --json` print one JSON object, with no banner.
+
+## Not in 0.27.0
+
+- Shared `.wize` state across worktrees (symlink or state branch); sprint manifests, ID allocation for ADRs and stories, per-story document-project fragments, changelog fragments, a deterministic `index.md`, an epic NFR trigger, and `sprint-status.md` references outside `doctor`.
+- Relative paths in `project-scan-report.json` (it still stores absolute paths).
+- `wize-release` from a linked worktree, or release through a PR.
+- A policy for `.wize/security/` (ignore or commit).
+- Regenerating `AGENTS.md` beyond the bootstrap block; an `AGENTS.md` version marker.
+- Pruning generated skills that a newer kit removed.
+- `update` re-running itself as `@latest` from a stale pinned binary. The downgrade guard and `@latest` in the skills and the Action cover it.
+- A team-level `[update] auto = false` knob. Only the environment variable exists.
+- Writing `orca.yaml` or the Codex config. Both are print-only. No Windows variant of `hydrate.sh`.
+- Renovate or Dependabot pinning, which would add a second source of truth for the pin.
+- A hard refusal from `sync` on version skew, and a nonzero exit when an adapter fails.
+- End-to-end checks in Orca (setup failure, trust prompt), Claude Code `SessionStart` timing against skill loading, and Cursor or Windsurf reading rules in worktrees.