| name | worktree-venv |
| description | Provisions a Python venv inside every freshly created worktree — infrastructure only, no agent-side decision logic |
| ai_hats | {"worktree":{"wt_in":["[Truncated]"]}} |
| license | MIT |
worktree-venv
hooks/provision-venv.sh runs after git worktree add and mints a .venv in
the new worktree: uv venv, then one editable uv pip install over the root
project and every packages/**/pyproject.toml.
Without it the worktree's sys.executable is the main checkout's, whose
editable install points at main — so the e2e tier (which strips PYTHONPATH by
design, HATS-685) tests the wrong source and the HATS-1242 guard blocks the
first commit. The paired half is the git-mastery smoke hook preferring
<git-toplevel>/.venv/bin/pytest; neither half works alone (HATS-1245).
Conventions
- Warn-continue (ADR-0012 D3/D7). Every declining path exits 0: no root
pyproject.toml, .venv/bin/python already present (idempotent), no uv on
PATH, or a failed install. Each leaves a worktree without .venv — the
pre-HATS-1291 status quo, never worse.
- Bounded by the 45s
wt_in budget; a timeout is a WARN, not a failed
create. Cost when it runs: ~1–2s on a warm uv cache.
- Unpinned by necessity — the repo gitignores
uv.lock, so the install
resolves fresh and a worktree venv may carry newer dev tools than an older
main venv.
References
- Rationale, measurements and the rejected designs:
.agent/ai-hats/tracker/backlog/tasks/HATS-1291/plan.md
- Paired hook:
library/core/skills/git-mastery/git_hooks/pre-commit-smoke.sh
- Hook contract:
docs/how-to-extend.md#worktree-lifecycle-hooks
