Add cargo xtask create-worktree

[cderv]

Setting up a new worktree in this repo currently means running git worktree add, hand-creating .beads/redirect with a fragile relative path, and writing a CLAUDE.local.md context stub by copy-paste from .claude/rules/worktrees.md. The relative-path arithmetic is easy to get wrong, and the three skills that drive most worktree creation (/investigate-beads, /triage, /upgrade-cargo-deps) all carried near-identical bash recipes for it.

cargo xtask create-worktree does the whole sequence in one shot for the three worktree types this project actually creates:

cargo xtask create-worktree <bd-id>     # beads issue
cargo xtask create-worktree --issue N   # GitHub issue triage
cargo xtask create-worktree --upgrade   # cargo dependency upgrade (date-based branch)

A cargo create-worktree cargo alias is also wired up (same precedent as cargo dev-setup), so the shorter form works everywhere too:

cargo create-worktree bd-XXXX
cargo create-worktree --issue 184
cargo create-worktree --upgrade

Each mode populates CLAUDE.local.md with a managed BEGIN/END section so a fresh Claude session lands with the right context — beads ID, GitHub link, plan placeholder, and the slash-command to continue the work. The xtask anchors worktrees at the main repo root regardless of cwd, validates --slug grammar to keep path-traversal mistakes out of .worktrees/, and rolls back cleanly if anything after git worktree add fails.

The three skills now call the xtask instead of duplicating the bash recipe, and .claude/rules/worktrees.md was rewritten to point at the xtask first with a manual bootstrap as fallback for fresh clones.

End-to-end verification

All three modes, four failure cases, and the anchor-to-repo-root invariant verified on Windows (Git Bash + PowerShell) per the Phase E smoke test in claude-notes/plans/2026-05-11-implement-create-worktree-xtask.md. 58 unit tests pass (cargo nextest run -p xtask).

Smoke test transcript

--help

$ cargo xtask create-worktree --help
Create a new git worktree with beads redirect and CLAUDE.local.md context stub.

Modes (exactly one required):
  <bd-id>      — beads issue (positional)
  --issue N    — GitHub issue triage
  --upgrade    — cargo dependency upgrade (date-based branch)

Usage: xtask.exe create-worktree [OPTIONS] <BEADS_ID|--issue <ISSUE>|--upgrade>

Arguments:
  [BEADS_ID]
          Beads issue ID, e.g. `bd-1d3e`. Reads `br show <id>` for title and external_ref

Options:
      --issue <ISSUE>
          GitHub issue number, e.g. `157`. Reads `gh issue view`

      --upgrade
          Cargo dependency upgrade — uses today's date for branch name

      --slug <SLUG>
          Override auto-derived slug. In beads mode replaces the derived slug;
          in issue/upgrade modes appended as a suffix (for parallel-worktree workflows)

      --base <BASE>
          Base branch

          [default: main]

  -h, --help
          Print help (see a summary with '-h')

Beads mode + anchor-to-root verification

Invoked from crates/xtask/ to confirm the worktree lands at the main-repo root regardless of cwd:

$ cd crates/xtask
$ cargo xtask create-worktree bd-spsv --slug anchor-test
Created worktree: C:\Users\chris\Documents\DEV_R\q2\.worktrees\bd-spsv-anchor-test/
  Branch:  beads/bd-spsv-anchor-test
  Beads:   bd-spsv — Add cargo xtask create-worktree command with CLAUDE.local.md stub

Next:
  cd C:\Users\chris\Documents\DEV_R\q2\.worktrees\bd-spsv-anchor-test

  Open a Claude Code session there — CLAUDE.local.md gives it the
  worktree context (branch, beads/GitHub link, base). Copy whichever of
  the prep commands below apply:

  # Once per machine (skip if already done)
  cargo xtask dev-setup                       # installs cargo-nextest, wasm-bindgen-cli

  # Per worktree
  cargo xtask verify --skip-hub-build         # confirm HEAD is green (Rust only)
  npm install                                 # only if hub-client work is in scope

  # Per beads issue (this worktree)
  br update bd-spsv --status in_progress      # claim it
  # `/investigate-beads` reloads context if you need it.

Issue mode

$ cargo xtask create-worktree --issue 184 --slug ts-issue
Created worktree: C:\Users\chris\Documents\DEV_R\q2\.worktrees\issue-184-ts-issue/
  Branch:  issue-184-ts-issue
  Issue:   #184 — Indented (4-space) code blocks are parsed as paragraphs, and re-emitted unindented
  URL:     https://github.com/quarto-dev/q2/issues/184

Next:
  cd C:\Users\chris\Documents\DEV_R\q2\.worktrees\issue-184-ts-issue

  # ...same Per worktree setup as above...

  # `/triage` continues the investigation — it files a beads issue
  # when concrete work surfaces.

Upgrade mode

$ cargo xtask create-worktree --upgrade --slug ts-upgrade
Created worktree: C:\Users\chris\Documents\DEV_R\q2\.worktrees\cargo-upgrade-2026-05-12-ts-upgrade/
  Branch:  cargo-upgrade-2026-05-12-ts-upgrade
  Task:    Cargo dependency upgrade — 2026-05-12

Next:
  # ...same Per worktree setup as above...

  # `/upgrade-cargo-deps` continues this worktree's work.

Failure cases

• Existing directory collision — pre-created .worktrees/bd-spsv-collision-test/; xtask errored before git worktree add ran, no branch leaked.
• Invalid --slug grammar — foo/bar (path separator) and .. (traversal) both rejected by validate_slug with no FS or git side effects.
• Re-run on existing worktree — fails with worktree directory already exists: <path> (by design — file-level idempotency only).
• Rollback path — Q2_CREATE_WORKTREE_INJECT_FAIL=after_worktree_add injects a synthetic failure between git worktree add and the post-add steps:

$ Q2_CREATE_WORKTREE_INJECT_FAIL=after_worktree_add \
    cargo xtask create-worktree bd-spsv --slug rollback-test
error after worktree creation: Q2_CREATE_WORKTREE_INJECT_FAIL=after_worktree_add (test hook)
rolling back worktree C:\Users\chris\Documents\DEV_R\q2\.worktrees\bd-spsv-rollback-test and branch beads/bd-spsv-rollback-test ...
rollback complete.
Error: Q2_CREATE_WORKTREE_INJECT_FAIL=after_worktree_add (test hook)

The injected failure fires after git worktree add succeeds, rollback cleans up both the directory and the branch, and the original error propagates as the final exit error. Post-run verification confirmed no leftover dir or branch.