From a64269852a1138b794d1a27603e6a5d3c96c4e49 Mon Sep 17 00:00:00 2001
From: Marius1311 <marius.lange@bsse.ethz.ch>
Date: Mon, 12 Oct 2026 16:29:37 +0200
Subject: [PATCH 1/2] Say that a worktree's src/ edits don't reach the main
 environment

The main checkout's environment installs the repo's package and editable code repos from the main
checkouts, so edits made in a worktree are invisible to it until merged and pulled.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 skills/analysis-workflow/SKILL.md | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/skills/analysis-workflow/SKILL.md b/skills/analysis-workflow/SKILL.md
index 85a22f7..c06263d 100644
--- a/skills/analysis-workflow/SKILL.md
+++ b/skills/analysis-workflow/SKILL.md
@@ -100,6 +100,9 @@ into the human lane.
 - The root `pixi.toml` is shared; reusability decides what goes in. A benchmark's candidates go task-local.
 - A worktree runs on the main checkout's environment: `pixi run --manifest-path <main>/pixi.toml …`.
   `pixi install`/`add`/`lock` run only in the main checkout, by the human, one session at a time.
+- That environment imports the repo's own package and any editable code repo from their main checkouts, so `src/`
+  edits made in a worktree reach it only once merged and pulled into main. Test a code-repo change in that repo's
+  own environment.
 - Verify an environment change with import smoke tests and `--help`, not by re-running analyses.
 
 ## Review

From f8fe9996744a608ad7d45237acb7b1450bb1c57e Mon Sep 17 00:00:00 2001
From: Marius1311 <marius.lange@bsse.ethz.ch>
Date: Tue, 13 Oct 2026 11:02:24 +0200
Subject: [PATCH 2/2] Environments: relock beside main, PYTHONPATH for worktree
 src, kernels; code-repo worktrees; rapids

A task that changes pixi.toml relocks in a temporary checkout beside the main one; only the human
installs. A worktree's src/ runs via PYTHONPATH. Kernels skip pixi activation. Code-repo changes get
their own worktree from the same session. Large single-cell compute uses rapids-singlecell.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 hooks/guard_worktree_pixi.py      |  4 ++--
 hooks/session_context.md          |  2 +-
 skills/analysis-workflow/SKILL.md | 20 +++++++++++++++-----
 3 files changed, 18 insertions(+), 8 deletions(-)

diff --git a/hooks/guard_worktree_pixi.py b/hooks/guard_worktree_pixi.py
index 2b00758..4066273 100644
--- a/hooks/guard_worktree_pixi.py
+++ b/hooks/guard_worktree_pixi.py
@@ -66,8 +66,8 @@ def main() -> int:
         "The root manifest's editable self-dependency (`path = \".\"`) would rebase the repo's package,\n"
         "and every path it resolves, into this worktree.\n"
         "  - to run something: pixi run --manifest-path <main checkout>/pixi.toml python <script>\n"
-        "  - to change the environment: do it in the MAIN checkout, one session at a time;\n"
-        "    from a worktree, hand the command to the human.",
+        "  - to change the environment: relock in a temporary checkout beside the main one (skill, Environments);\n"
+        "    installing is the human's, in the MAIN checkout.",
         file=sys.stderr,
     )
     return 2
diff --git a/hooks/session_context.md b/hooks/session_context.md
index 8ccbd60..f485e29 100644
--- a/hooks/session_context.md
+++ b/hooks/session_context.md
@@ -9,4 +9,4 @@ analysis code, outputs or data. Always:
 4. Shared objects grow by addition only (`commit_adata`), and only after sign-off on the dry run.
 5. Agents never write to `data/<dataset>/results/` or the central `figures/`; those are the human lane.
 6. A worktree, and every batch job submitted from it, runs on the main checkout's environment
-   (`pixi run --manifest-path <main>/pixi.toml ...`); environment changes happen in the main checkout.
+   (`pixi run --manifest-path <main>/pixi.toml ...`); only the human installs it, in the main checkout.
diff --git a/skills/analysis-workflow/SKILL.md b/skills/analysis-workflow/SKILL.md
index c06263d..5de40b7 100644
--- a/skills/analysis-workflow/SKILL.md
+++ b/skills/analysis-workflow/SKILL.md
@@ -26,6 +26,8 @@ Elsewhere:
 
 - Science code that several tasks need goes to a code repo, plotting code included. Figure code is copied only
   between versions of one task. The analysis repo's own package holds `FilePaths`, dataset versioning and a CLI.
+- A task that changes a code repo does so in a worktree of that repo, added from the same session:
+  `git -C <code repo> worktree add .claude/worktrees/<task> -b <branch>`.
 - Look before writing: existing packages (scverse, then its ecosystem), sibling code repos, earlier task directories.
 - A value becomes a constant in `_constants.py` when it is a stable project fact that several scripts would
   otherwise hardcode (a dataset root, a registered resource). Not task outputs, not the current working object
@@ -65,6 +67,8 @@ into the human lane.
 - Batch-job scripts sit in `scripts/` beside the code they run. They get the main checkout as `$MAIN` from the
   submit command, never hardcoded, run `pixi run --manifest-path "$MAIN/pixi.toml"`, and log to `PATHS.logs`. How
   to submit them is the cluster's skill.
+- Large single-cell computations (neighbors, UMAP, clustering on ≳100k cells) use rapids-singlecell over scanpy, in
+  a GPU job.
 - A figure that prints a number may carry `scripts/verify.py` re-deriving it. A code package's invariants belong in
   that package's tests.
 
@@ -98,11 +102,17 @@ into the human lane.
 ## Environments
 
 - The root `pixi.toml` is shared; reusability decides what goes in. A benchmark's candidates go task-local.
-- A worktree runs on the main checkout's environment: `pixi run --manifest-path <main>/pixi.toml …`.
-  `pixi install`/`add`/`lock` run only in the main checkout, by the human, one session at a time.
-- That environment imports the repo's own package and any editable code repo from their main checkouts, so `src/`
-  edits made in a worktree reach it only once merged and pulled into main. Test a code-repo change in that repo's
-  own environment.
+- A worktree runs on the main checkout's environment: `pixi run --manifest-path <main>/pixi.toml …`. Only the human
+  installs it, in the main checkout, one session at a time. `pixi install` rewrites the path-dependency entries in
+  `pixi.lock`; that local diff is noise, so `git checkout pixi.lock` before pulling.
+- A task that changes `pixi.toml` relocks without installing. Commit `pixi.toml`, then lock in a temporary checkout
+  beside the main one, where the relative path dependencies resolve: `git worktree add --detach <main>/../<repo>-lock
+  HEAD`, `pixi lock --manifest-path <that checkout>/pixi.toml`, copy its `pixi.lock` into the task's worktree and
+  commit it, then `git worktree remove` the temporary checkout. The human installs after the merge.
+- That environment imports the repo's own package and any editable code repo from their main checkouts, so a
+  worktree's `src/` edits don't reach it. To run them, prepend that worktree's `src/` to `PYTHONPATH`.
+- A Jupyter kernel, or a direct call to an environment's `python`, skips pixi's activation: variables the
+  environment sets (such as `CONDA_PREFIX`) are missing unless the kernelspec passes them.
 - Verify an environment change with import smoke tests and `--help`, not by re-running analyses.
 
 ## Review