[cayossarian]

Worktrees of this repository have been created with scripts/new-worktree.sh, from a branch that never reached main or a pre-release branch. This brings the script in, with the setup-hooks.sh fix it depends on and the instructions for both.

The fix matters on its own. Git hooks live in the repository's common directory and every worktree shares them, and pre-commit install writes the interpreter that runs it into the hook. setup-hooks.sh ran it wherever it was invoked, so running it in a worktree bound every checkout's commits to that worktree's virtual environment, and once the worktree was removed every commit failed with "pre-commit not found".

Change

• setup-hooks.sh:
  • Installs the pre-commit hook only in the primary checkout. In a worktree it syncs that worktree's own environment and checks the shared hook, saying how to rebind it if it is not bound to the primary checkout, and leaves it alone either way.
  • --check-hook only checks, and exits non-zero when the hook is missing, bound to another environment, or bound to an interpreter that no longer exists.
  • Every run syncs. The .deps-installed stamp it gated on had been committed, so whether a fresh worktree got an environment at all depended on the order in which checkout wrote files. The stamp is removed from the repository and ignored.
• scripts/new-worktree.sh <name> [<branch>]:
  • Fetches origin, fast-forwards local main where that is safe, and refuses when main holds commits origin/main lacks.
  • Installs the shared hook from the primary checkout first when it is missing or bound elsewhere, and refuses to create the worktree if it is still not bound.
  • Creates ../span-panel-api-<name> on a branch that tracks no remote, so a bare git push can never land on main, and links .env.
  • Prepares the worktree with the setup-hooks.sh beside the script rather than the worktree's own copy, because origin/main can predate the worktree-aware one and running that would rebind the shared hook.
• DEVELOPMENT.md: the Git Hooks section describes both modes and --check-hook, and a new Worktrees section describes the script.
• AGENTS.md: a Worktrees section. CLAUDE.md already imports AGENTS.md.

The integration's script comes in with SpanPanel/span#333.

Checks

• --check-hook, exercised in a throwaway repository:
  • Exits 1 with its own message when no hook is installed (run from the primary checkout and from a worktree), when the hook is bound to another environment, when it is bound to the worktree's own environment, and when it is bound to the primary checkout's interpreter after that is gone.
  • Exits 0 when the hook is bound to the primary checkout, with the path quoted or not.
  • An unknown argument exits 2.
• new-worktree.sh refusals: a name with a space and a call with no arguments exit 2. An existing target directory and an existing branch exit 1, before anything is fetched or created.
• This branch's worktree was created by this script, which found the shared hook bound to the primary checkout and left it alone. --check-hook from the worktree agrees.
• The scripts are byte-identical to the copies every worktree here has been created with since 2026-09-14.
• shellcheck is clean on both scripts. All hooks pass over the branch: 1857 passed, 7 skipped, 9 xfailed.

Not covered

• The branch always starts from origin/main. Work for a pre-release branch, this one included, is reset onto it by hand after the script runs.
• Nothing tests the scripts automatically. The checks above were run by hand.