[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 and its instructions in.

Change

• 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. main is moved with update-ref rather than branch --force, which would also rewrite its upstream, and a checked-out main is fast-forwarded only when it has no uncommitted tracked changes.
  • Creates ../span-<name> on a branch that tracks no remote, so a bare git push can never land on main, links .env from the primary checkout, and runs the worktree's setup-hooks.sh.
  • The worktree gets a virtual environment of its own. Editable installs record one checkout's source path, so a shared environment imports whichever checkout synced last. From beside the primary checkout, ../../span/span-panel-api still resolves to the library, so no bridge is needed.
  • When a library worktree of the same name exists, the script prints the three-distribution uv pip install -e command rather than running it, because the next uv sync silently undoes that override.
• developer.md: a Worktrees section.
• AGENTS.md: a Worktrees section, and the script among the permitted operations.
• CLAUDE.md: imports AGENTS.md, for agents that read only CLAUDE.md.

Checks

• 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. The script is byte-identical to the copy every worktree here has been created with since 2026-09-13.
• shellcheck is clean. All hooks pass over the branch: 2470 passed, 1 skipped, against the published span-panel-api 3.8.0b1, schema-0 1.3.0b1 and schema-1 1.4.0b2 this branch pins.

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.
• When no pre-commit hook is installed, setup-hooks.sh installs it from whichever checkout runs first, and the hook records the path of the prek that installed it. If that was a worktree's environment, the hook breaks once the worktree is removed. The library's companion change guards against this for pre-commit (feat(scripts): create worktrees with new-worktree.sh and keep the shared hook bound to the primary checkout span-panel-api#218). The hook here currently runs a system prek.
• Nothing tests the script automatically. The checks above were run by hand.