wt 0.2.0: worktree lifecycle — new, switch, list, rm, merge

[VSN2015]

Adds a worktree-lifecycle layer to wt, so a worktree can be created, found, merged, and fully torn down — reclaiming the server, database, Redis slot, and state files the kit provisioned for it.

Inspired by worktrunk, which solves the complementary half: it creates and destroys worktrees but knows nothing about databases, servers, or isolation, so its remove leaks every resource wt provisions.

New commands

wt new <branch> [--from <base>] [--server]     create a branch + worktree, run the prepare hook
wt switch [<branch>]                            cd to a worktree; no argument opens a picker
wt list [--all]                                 branch, slug, status, server, isolation
wt rm [<branch>] [--keep-branch] [--force]      full teardown, then remove
wt merge [<branch>] [--into <trunk>] [-m <msg>] [--no-remove] [--force]
wt shell-init [bash|zsh|fish]                   the shell function that makes switch cd

Plus wt doctor checks for the path template, fzf, and shell integration; worktrees.path/worktrees.trunk and isolation.db_drop/isolation.redis_flush across all ten stack templates; README documentation; and a bump to 0.2.0.

Design

• The lifecycle commands need only git. require_config is split into load_config_soft (never exits, sets HAS_CONFIG) and the existing strict wrapper. The ten pre-existing commands keep the strict wrapper and behave identically — verified by tracing every call site.
• Stdout is a dedicated "cd channel". Lifecycle commands print a path there and nothing else; all human output goes to stderr, so the shell wrapper can cd to it.
• The path template's last segment becomes the slug, and the slug determines the port, the Redis DB number, and the database name. Slug derivation itself is unchanged, so existing worktrees keep their identity.
• Lookup is always git worktree list --porcelain, never a recomputed template — so it finds worktrees created by hand or by other tooling.

Safety

wt rm and wt merge stop servers, drop databases, flush Redis slots, and delete branches. wt merge also rewrites history and does not prompt.

• wt merge writes refs/wt/premerge/<slug> before the first mutation; every failure path restores the branch and names that ref.
• Rebase conflicts force the branch ref back explicitly — a mid-rebase HEAD is detached, so rebase --abort alone is not enough.
• Trunk advances via --ff-only, so a merge commit is structurally unreachable.
• A database is dropped only when a .dbowned provenance marker proves the kit bootstrapped it. Databases merely adopted by db_check — including every database created before 0.2.0 — are left in place with a notice. This errs toward keeping data.

Testing

New test/lifecycle.sh: 110 assertions, git-only (no docker, no YAML backend required). Runs on macOS and is wired into the Debian and Alpine container suites.

Verified on macOS under both the system shell and dash, including dash executing bin/wt itself.

Not yet verified: the container suites (./test/linux.sh) could not run — no docker daemon on the development machine. CONTEXT.md §5 records that three of this codebase's eight historical bugs surfaced under BusyBox ash first. Please run ./test/linux.sh before merging. Two tests derive a docker-free PATH and are the most likely to need adjustment on a Linux layout.

Also unexercised: both picker branches (fzf is not installed; the sandbox has no controlling terminal) and the emitted fish wrapper.

Note on docs/

Commits 18c11f5 and f936d19 add docs/superpowers/{specs,plans}/ — the design spec and implementation plan, ~1,900 lines. These were previously untracked. If you would rather keep them out of the repo, they can be dropped without touching any code.

Review pointers

The changes most worth a careful look:

• remove_worktree_and_branch and teardown_worktree (bin/wt) — shared by both destructive commands; teardown borrows and restores the SLUG/N/WT_PATH globals deliberately.
• cmd_merge's failure paths — the restore ordering is load-bearing.
• expand_path's _esc helper — path values become sed replacement text, where & would otherwise mean "the whole match".
• ensure_own_db — the one change to pre-existing code, adding the provenance marker.

🤖 Generated with Claude Code