Orchestrata Ultimate › Gates › worktree-envs

Gate: worktree-envs

At a glance

What it refuses

In the battery: a non-primary worktree whose .venv is a symlink into another checkout's virtualenv — the one failure mode that poisons every other checkout too. The standalone script checks more (below).

Why it exists

Module docstring, quoting the ruling verbatim and the incident:

"Worktree-environment gate — RUL-021 ('every damn feature branch gets a full env until we merge then it gets deleted', verbatim, 2026-07-27).

See ~/workspace/knowledge-wiki/rulings/RUL-021-worktree-owns-its-env.md for the ruling text and the incident (wt-QWEN's .venv was a symlink to the main checkout's virtualenv, and its vendor/wheels/ was empty, so the relative [tool.uv.sources] grpcio pin resolved to nothing and uv fell back to a from-sdist build — one that re-enables the GIL process-wide on import, a SPEC-023 violation, in a virtualenv every other checkout used)."

Why it entered the battery at all (gates.py registry comment): "The detector existed but was wired into NOTHING, which is how the incident escaped: a gate nobody runs is not a gate."

How it runs

• Battery command: python scripts/check_worktree_envs.py --checks venv-symlink
• Full standalone checks (docstring) — for every NON-PRIMARY worktree in git worktree list --porcelain:
  1. .venv is a symlink → violation ("must be a real, independently-owned virtualenv").
  2. .venv missing while a branch is checked out → violation.
  3. A relative [tool.uv.sources] vendor path not resolving inside THAT worktree's own pyproject.toml → violation ("branches differ, so each worktree's own file is read, never the primary's").
  4. Branch already merged into master → violation ("stale, worktree and env are due for deletion"); detached HEAD is informational only.
• Why the battery restricts to check 1 (registry comment): "venv-missing / env-missing are normal transient states for an agent worktree between git worktree add and its uv sync, and a battery run racing that window must not flake."
• When it fires: the scripts/gates.py battery (registered as worktree-envs) and scripts/health_check.py.
• Inputs / caching: never cached — the root is the !always sentinel: "worktree state is invisible to the content fingerprint" (worktrees appear and vanish with zero tracked-file change), so a cached PASS "would be a statement about a world that no longer exists."
• Flags: --fix-wheels ("Populate missing vendored wheels by HARDLINK from the primary worktree… The only auto-fix: creating virtualenvs and deleting worktrees stay manual, per the ruling"), --json, --repo-root ("Never hardcode an absolute path here — the primary worktree is always derived from git worktree list").

Typical failures and how to fix them

• Exit codes: "Exit 0 clean, exit 1 on any violation. A directory that is not a git repository (or has no worktrees) is a SKIP (exit 0, reason printed) — same honesty rule as rulings_lint.py's missing-RULINGS_DIR skip."
• What a failure looks like (representative): the offending worktree path with its violation class (venv-symlink in the battery) and the target the symlink resolves to.
• Un-blocking: give the worktree its own real virtualenv (uv sync inside it); for the standalone checks, populate wheels via --fix-wheels or delete a merged worktree (scripts/worktrees.py gc).
• A worktree that passes this gate but still imports another checkout's code. This gate checks only the .venv symlink. A leaked PYTHONPATH or a venv whose editable install points at a different checkout is caught by source-provenance in the suite preflight, not here.
• A transient failure right after git worktree add. The battery restricts itself to venv-symlink so a worktree that has not run uv sync yet does not fail it; the standalone run with all checks will report .venv missing until the sync finishes.

Wiring

• Invokers: scripts/gates.py (battery), scripts/health_check.py; worktree lifecycle tooling lives in scripts/worktrees.py (creation with a full private env, tracking, gc) and the worktree-gc.sh SessionStart hook cleans merged ones.
• Tests: tests/scripts/test_check_worktree_envs.py, plus tests/scripts/test_worktrees.py / test_worktrees_provision.py for the lifecycle side.

Related

• Gates master index
• Development workflow
• RUL-021 — A worktree owns its env
• source-provenance — the import-path half of the same ownership problem
• prod-separation — the same PYTHONPATH/ownership trap, hit by systemd units instead of worktrees
• generated-artifacts — the other !always gate, for the same "no content hash can see it" reason