feat(hooks): branch-guard — keep worktree-flow primary clones on a base branch

[AndreJorgeLopes]

TL;DR

Adds a branch-guard PreToolUse(Bash) hook that blocks a git checkout/git switch which would move a worktree-flow repo's PRIMARY clone onto a non-base feature branch, steering to devflow worktree. Also hardens devflow worktree against worktrunk ignoring the configured path.

Why

When an agent parks a repo's main clone on a feature branch (instead of using a worktree), anything symlinked to that clone silently swaps to the branch's code. In practice a local-dev devflow plugin install (symlinked to the clone) served whatever branch a session happened to leave the clone on. A reflog check found 14 such in-clone feature checkouts in a single day. This hook enforces the intended model: the primary clone stays on a base branch, feature work lives in isolated worktrees.

What it does

• Blocks git checkout -b / git switch -c / git checkout <existing-feature-branch> when the target dir is a repo's primary clone (not a linked worktree) and the repo uses the worktree flow.
• Fail-open, never blocks: base branches (main/develop/staging/… + configurable), any checkout inside a linked worktree, path restores (git checkout -- file, .), git checkout -, non-worktree-flow repos, and anything it can't parse.
• "Worktree-flow repo" = has .worktrunk.toml, OR has ≥1 linked worktree, OR lives under a configured enforce-root (so it correctly guards repos like this one that have worktrees but no .worktrunk.toml).
• Governs the agent's git commands only (a Claude hook can't intercept your terminal; git has no blocking pre-checkout hook). Terminal/other-agent coverage would need a git PATH shim — deliberately out of scope here.

Config (optional, personal — not shipped)

~/.config/devflow/branch-guard.json (keep in your own dotfiles/yadm):

{ "off": false, "base_branches": [], "enforce_roots": ["~/dev"] }

Env overrides: DEVFLOW_BRANCH_GUARD_OFF=1, DEVFLOW_BRANCH_GUARD_BASE_BRANCHES=a,b, DEVFLOW_BRANCH_GUARD_ROOTS=/p1:/p2.

Bonus: devflow worktree path hardening

worktrunk sometimes silently ignores its worktree-path template and drops the new worktree as a sibling of the repo. devflow worktree now reads the configured root from worktrunk's config (never hardcodes a personal path), and if the worktree landed elsewhere, moves it to <root>/<repo>/<branch-slug> and reports it.

Changes

Path	Change
lib/hooks/branch-guard.py	Hook logic (parse git checkout/switch, clone-vs-worktree detection, decision)
lib/hooks/branch-guard.sh	Thin wrapper (fail-open if python3 absent)
lib/init.sh	Register branch-guard as a global PreToolUse(Bash) hook
lib/worktree.sh	_expected_worktree_root + _fix_worktree_location
README.md	Branch-guard + config docs

Validation

• 14-case block/allow matrix all pass: blocks feature checkout -b/switch -c/compound/git -C; allows base branches, in-worktree checkouts, path restores, checkout -, non-flow repos, and shell noise (echo git checkout …).
• bash -n + py_compile clean; _register_settings hooks really adds the PreToolUse(Bash) entry; _expected_worktree_root reads the configured root from worktrunk config.
• make skills-check + make flows-check pass.

🤖 Generated with Claude Code

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.