Commit yarn 4 in the tree and install with --immutable (closes #149)

Follows sneak's ruling at
#149 (comment). This
repository now carries yarn 4.18.1 under .yarn/releases. The
distribution's yarn only starts that file, and that file does the work.
yarn.lock is converted once, and script/bootstrap installs with
--immutable instead of stopping on yarn's major version. Node is the
distribution's newest Node package: nodejs-current on Alpine and
nodejs_latest on nix. Every Dockerfile stage that needs yarn also copies
.yarnrc.yml and .yarn/releases/. The policies and both checklists say
so, with the steps for converting and for a new repository.

Model: opus-5-5

.dockerignore

@@ -35,6 +35,12 @@
 # `services/api/.claude/` and must add its own anchored entry.
 .claude
 
+# yarn's install state and cache stay out, and its release file stays
+# in. Docker obeys the last matching line, so these two lines sit above
+# the secret patterns, which must win under .yarn/releases/.
+.yarn/*
+!.yarn/releases
+
 # Environment files. `*.env` covers bare `.env` and the `prod.env`
 # convention. Re-include a committed template with a negation if the
 # build needs one: `!docs/example.env`.

.gitattributes

@@ -2,3 +2,6 @@
 # both sides instead of conflicting. Git never reports a conflict here: read
 # the merged entries after every merge or rebase.
 TODO.md merge=union
+
+# yarn's release file is one opaque file in diffs and merges.
+.yarn/releases/** binary

.gitignore

@@ -19,10 +19,12 @@ Thumbs.db
 
 # Node
 node_modules/
+.yarn/*
+!.yarn/releases
 
-# Secrets. Unanchored like every entry above, so each matches at every
-# depth. Matching is case-sensitive on Linux, so names use character
-# ranges rather than a lowercase form that misses `Server.Key`.
+# Secrets. Unanchored, so each matches at every depth. Matching is
+# case-sensitive on Linux, so names use character ranges rather than a
+# lowercase form that misses `Server.Key`.
 
 # Environment files. `*.env` covers bare `.env` and the `prod.env`
 # convention. Only the templates `example.env` and `sample.env` are

.prettierignore

@@ -1,2 +1,3 @@
 node_modules/
+.yarn/
 yarn.lock

.yarnrc.yml

@@ -0,0 +1,5 @@
+enableTelemetry: false
+
+nodeLinker: node-modules
+
+yarnPath: .yarn/releases/yarn-4.18.1.cjs

Dockerfile

@@ -3,20 +3,23 @@
 # recurse into a daemon that does not exist in a build step.
 #
 # In every stage, ARG CACHEBUST comes right after the step that installs
-# system packages: script/ passes a new value on every build, which
-# reruns every RUN step after it and keeps that step's layer. node and
-# yarn come from the distribution, which is trusted, so they need no
-# version and no hash.
+# system packages. script/ passes a new value on every build. That value
+# reruns every RUN step below the ARG line, and the install step keeps
+# its layer. node and yarn come from the distribution, which is trusted,
+# so they need no version and no hash. That yarn only starts the release
+# file in .yarn/releases/, so every stage copies that file and
+# .yarnrc.yml before it runs script/bootstrap.
 #
 # alpine 3.24.3, 2026-11-04
 FROM alpine@sha256:be2656061b536c1883c4034790e21d0a09c5aaaf51968b89368a3c0371ea2c9a AS lint
-RUN apk add --no-cache git make nodejs yarn
+RUN apk add --no-cache git make nodejs-current yarn
 ARG CACHEBUST
 
 WORKDIR /app
 
 COPY script/ script/
-COPY package.json yarn.lock ./
+COPY package.json yarn.lock .yarnrc.yml ./
+COPY .yarn/releases/ .yarn/releases/
 RUN script/bootstrap
 
 COPY . .
@@ -27,13 +30,14 @@ RUN yarn run prettier --check '**/*.md' --tab-width 4 --prose-wrap always
 #
 # alpine 3.24.3, 2026-11-04
 FROM alpine@sha256:be2656061b536c1883c4034790e21d0a09c5aaaf51968b89368a3c0371ea2c9a AS test
-RUN apk add --no-cache git make nodejs yarn
+RUN apk add --no-cache git make nodejs-current yarn
 ARG CACHEBUST
 
 WORKDIR /app
 
 COPY script/ script/
-COPY package.json yarn.lock ./
+COPY package.json yarn.lock .yarnrc.yml ./
+COPY .yarn/releases/ .yarn/releases/
 RUN script/bootstrap
 
 COPY . .
@@ -48,7 +52,7 @@ RUN echo "No tests defined."
 #
 # alpine 3.24.3, 2026-11-04
 FROM alpine@sha256:be2656061b536c1883c4034790e21d0a09c5aaaf51968b89368a3c0371ea2c9a
-RUN apk add --no-cache git make nodejs yarn
+RUN apk add --no-cache git make nodejs-current yarn
 ARG CACHEBUST
 
 WORKDIR /app
@@ -59,7 +63,8 @@ COPY --from=test /app/package.json /dev/null
 # script/bootstrap finds the system packages above and installs the node
 # packages.
 COPY script/ script/
-COPY package.json yarn.lock ./
+COPY package.json yarn.lock .yarnrc.yml ./
+COPY .yarn/releases/ .yarn/releases/
 RUN script/bootstrap
 
 COPY . .

README.md

@@ -111,7 +111,7 @@ development workflow, and the Makefile targets are thin shims that call them.
 The scripts are POSIX sh (not bash) so they run in minimal containers such as
 alpine. We provide:
 
-- `script/bootstrap` — install all dependencies (yarn install)
+- `script/bootstrap` — install all dependencies (`yarn install --immutable`)
 - `script/setup` — set up the repo for development after a fresh clone: runs
   `script/bootstrap`, then `script/install-precommit`
 - `script/projectname` — output the project name (our own extension); used by

TODO.md

@@ -21,6 +21,28 @@ fmt-check, and commit.
 
 # Completed Steps
 
+- 2026-11-04: Each repository now commits yarn 4 and installs with
+  `yarn install --immutable` (https://git.eeqj.de/sneak/prompts/issues/149), on
+  sneak's ruling at
+  https://git.eeqj.de/sneak/prompts/issues/149#issuecomment-167558. Product
+  repositories convert when they next have work. These changed:
+    - This repository carries `.yarn/releases/yarn-4.18.1.cjs`, and its
+      `yarn.lock` is in yarn 4's format.
+    - `script/bootstrap` no longer stops on yarn's major version.
+    - Node comes from the distribution's newest Node package, which on Alpine
+      3.24 is `nodejs-current`.
+    - A `Dockerfile` stage that needs yarn also copies `.yarnrc.yml` and
+      `.yarn/releases/`, and may start from any distribution that packages node
+      and yarn.
+    - Both checklists give the steps, and the ignore files keep yarn's install
+      state out of git and the build context.
+- 2026-11-04: An agent whose work is confined to one package may run `go test`
+  directly on that package's suite, or on individual tests in it, while
+  iterating (https://git.eeqj.de/sneak/prompts/issues/51), on sneak's ruling at
+  https://git.eeqj.de/sneak/prompts/issues/51#issuecomment-167600. The full
+  `make check` is still required before every push, and the `Makefile` gains
+  nothing. The rule on Docker now names the lint and test gates, because a run
+  while iterating is not one.
 - 2026-11-04: node, yarn, npm, python, pip and venv now come from the
   distribution with no version and no hash
   (https://git.eeqj.de/sneak/prompts/issues/146), on sneak's ruling at
@@ -28,10 +50,14 @@ fmt-check, and commit.
   packages stay pinned by hash. These changed:
     - `script/bootstrap` no longer uses nvm or corepack, and stops when yarn's
       major version is not 1.
+    - `script/bootstrap` installs node, yarn and the node packages only when
+      `yarn.lock` is in the tree.
     - `script/bootstrap`, `script/fmt` and `script/fmt-check` run `yarn` or
       `yarnpkg`, whichever is present.
     - This repository's `Dockerfile` starts from Alpine 3.24.
     - The Python `test` phase example starts from `debian:trixie-slim`.
+    - A Python repository's `script/bootstrap` creates its virtual environment
+      at `$HOME/.pipenv`, so it works on a host and in a `Dockerfile`.
     - `PIP_ONLY_BINARY=:all:` stops a package with no wheel, so pip downloads no
       build tools without a hash check.
 - 2026-11-04: Rewrote `prompts/REPO_POLICIES.md` sentence by sentence

package.json

@@ -2,5 +2,6 @@
   "private": true,
   "devDependencies": {
     "prettier": "3.8.1"
-  }
+  },
+  "packageManager": "yarn@4.18.1"
 }

prompts/CODE_STYLEGUIDE_JS.md

@@ -1,6 +1,6 @@
 ---
 title: Code Styleguide — JavaScript
-last_modified: 2026-02-22
+last_modified: 2026-11-04
 ---
 
 1. Use `const` for everything. If you need to reassign, use `let`. Never use
@@ -8,7 +8,8 @@ last_modified: 2026-02-22
 
 1. Use yarn for package management, avoid using npm.
 
-1. Use LTS node versions.
+1. Install node from the distribution. If its version is too old, use a newer
+   distribution.
 
 1. Use `prettier` for code formatting, with four spaces for indentation.
 

prompts/EXISTING_REPO_CHECKLIST.md

@@ -81,13 +81,17 @@ with your task.
     - pipenv and its dependencies
     - the packages from `Pipfile.lock`
 
-    It installs pipenv and its dependencies by hash, with
+    It creates a virtual environment at `$HOME/.pipenv` with `python3 -m venv`
+    when it is missing, then uses that environment's `pip` and `pipenv`. On a
+    host, it first installs the distribution's python and venv packages when
+    they are missing. It installs pipenv and its dependencies by hash, with
     `pip install --require-hashes`. It installs the packages from `Pipfile.lock`
     with `pipenv install --deploy`, plus `--dev` when the tests need the
     development packages. It sets `PIP_ONLY_BINARY=:all:` for both installs, so
-    a package with no wheel for the image stops the install. It installs no
-    Python there, because the tests use the distribution's, which a step above
-    it installs. The tests run after `ARG CACHEBUST`, and every other stage
+    a package with no wheel for the image stops the install. In that step it
+    installs no Python, because a step above it already did. `Pipfile` names no
+    `python_version`, because `--deploy` stops when the distribution's Python
+    differs from it. The tests run after `ARG CACHEBUST`, and every other stage
     installs its Python packages after it, as in the Python `test` phase example
     in `REPO_POLICIES.md`
 
@@ -160,10 +164,39 @@ with your task.
           `https://git.eeqj.de/sneak/prompts/raw/branch/main/.golangci.yml` and,
           in the same commit, set the lint phase digest to the one named in the
           `.golangci.yml` paragraph of `REPO_POLICIES.md`)
-    - [ ] JS: `package.json`, `yarn.lock`, `.prettierrc`, `.prettierignore`
-          (fetch from
-          `https://git.eeqj.de/sneak/prompts/raw/branch/main/.prettierrc` and
-          `https://git.eeqj.de/sneak/prompts/raw/branch/main/.prettierignore`)
+    - [ ] JS: `package.json`, `yarn.lock`, `.yarnrc.yml`, `.yarn/releases/`,
+          `.gitattributes`, `.prettierrc`, `.prettierignore` (fetch the last two
+          from `https://git.eeqj.de/sneak/prompts/raw/branch/main/.prettierrc`
+          and
+          `https://git.eeqj.de/sneak/prompts/raw/branch/main/.prettierignore`).
+    - [ ] Any repository with `yarn.lock`: that file is in yarn 4's format. If
+          its second line says `yarn lockfile v1`, convert it with the steps
+          below. Do them in one commit with the re-vendored scripts, because
+          yarn 1 ignores `--immutable` and exits 0 on a tree with no
+          `.yarnrc.yml`. Run them with any distribution's node and yarn, and use
+          `yarnpkg` on Debian and Ubuntu.
+        1. Read the version from `yarnPath` in
+           `https://git.eeqj.de/sneak/prompts/raw/branch/main/.yarnrc.yml`.
+        2. Run `yarn set version <version>`. It writes
+           `.yarn/releases/yarn-<version>.cjs`, `yarnPath` in `.yarnrc.yml`, and
+           `packageManager` in `package.json`.
+        3. Add `nodeLinker: node-modules` and `enableTelemetry: false` to
+           `.yarnrc.yml`.
+        4. Run `yarn install` once. It converts `yarn.lock`, and each package
+           keeps its version and gains a `checksum`.
+        5. Delete `approvedGitRepositories`, `enableScripts` and
+           `npmMinimalAgeGate` from `.yarnrc.yml`. The conversion wrote them.
+           They allow install scripts, any git repository and packages of any
+           age, which yarn otherwise refuses.
+        6. In `package.json`, name any package that must run its install script,
+           as `"dependenciesMeta": { "<name>": { "built": true } }`, and run
+           `yarn install` again.
+        7. Add `.yarn/*` and `!.yarn/releases` above the secret patterns in
+           `.gitignore` and `.dockerignore`. Docker obeys the last matching
+           line, and the secret patterns must win. Add `.yarn/` to
+           `.prettierignore`, and `.yarn/releases/** binary` to
+           `.gitattributes`.
+        8. Run `yarn install --immutable`. It must pass and change nothing.
     - [ ] Python: `pyproject.toml`
     - [ ] Docs/writing: `.prettierrc`, `.prettierignore` (same URLs as above)
 
@@ -198,11 +231,20 @@ with your task.
       `docker build` in `script/`. Without the bootstrap the CI run dies in
       `script/fmt-check`, which runs the formatter on the host and finds nothing
       installed.
-- [ ] `script/bootstrap` installs node and yarn from the distribution when they
-      are missing, and stops with a one-line message when yarn's major version
-      is not 1.
+- [ ] `script/bootstrap` installs node, yarn and the node packages only when
+      `yarn.lock` is in the tree. node and yarn come from the distribution when
+      they are missing. It installs the node packages with
+      `yarn install --immutable`. The distribution's yarn only starts the
+      release file that `yarnPath` in `.yarnrc.yml` names, and that file does
+      the work.
+- [ ] A `Dockerfile` stage that needs yarn may start from any distribution that
+      packages node and yarn. It copies `package.json`, `yarn.lock`,
+      `.yarnrc.yml` and `.yarn/releases/` before it runs `script/bootstrap`. A
+      stage that needs no yarn copies none of them.
 - [ ] `script/bootstrap`, `script/fmt` and `script/fmt-check` run yarn by
-      whichever name is present: `yarn`, or `yarnpkg` on Debian and Ubuntu.
+      whichever name is present: `yarn`, or `yarnpkg` on Debian and Ubuntu. With
+      neither name on `PATH`, `script/fmt` and `script/fmt-check` print one line
+      saying to run `script/bootstrap`, and exit 1.
 - [ ] `script/bootstrap` installs no linter of its own — delete the block, its
       version variables and its call site. A JS repo's `yarn install` stays; it
       brings a linter along with every other dependency, and no verdict is taken
@@ -235,7 +277,11 @@ with your task.
       this exception
 - [ ] node, yarn, npm, python, pip and venv come from the distribution wherever
       possible, never from nvm, pyenv, corepack or `npm install -g yarn`. If the
-      distribution's version is too old, use a newer distribution
+      distribution's version is too old, use a newer distribution. node means
+      the distribution's newest Node package, such as `nodejs-current` on Alpine
+      3.24
+- [ ] yarn's release file is in git under `.yarn/releases/`, written once by
+      `yarn set version` with an exact version (repositories with `yarn.lock`)
 - [ ] Using `yarn`, not `npm` (JS projects)
 
 # Directory Structure
@@ -264,12 +310,13 @@ with your task.
 # Final
 
 - [ ] `make check` passes
-- [ ] `script/cibuild` succeeds in a fresh clone on a host carrying what CI has
-      (the runner image `docker.gitea.com/runner-images:ubuntu-latest`: docker,
-      git and node 24), with any yarn first taken off `PATH`, and demonstrably
-      executed the checks — a sub-second build, or `CACHED` on a step that lints
-      or tests, one of the `RUN` steps below `ARG CACHEBUST`, means nothing ran.
-      Above that line, these steps are expected to show `CACHED`:
+- [ ] `script/cibuild` succeeds in a fresh clone on a host carrying what CI has.
+      That host is the runner image
+      `docker.gitea.com/runner-images:ubuntu-latest`, which has docker, git and
+      node 24. Take any yarn off `PATH` first. The run must show that the checks
+      executed. A sub-second build means nothing ran. So does `CACHED` on a step
+      that lints or tests, one of the `RUN` steps below `ARG CACHEBUST`. Above
+      that line, these steps are expected to show `CACHED`:
     - the steps that install system packages
     - the steps that download Go's modules
     - the step that runs `script/bootstrap` to install a Python `test` phase's

prompts/NEW_REPO_CHECKLIST.md

@@ -148,15 +148,20 @@ Template files can be fetched from:
         - pipenv and its dependencies
         - the packages from `Pipfile.lock`
 
-        It installs pipenv and its dependencies by hash, with
-        `pip install --require-hashes`. It installs the packages from
-        `Pipfile.lock` with `pipenv install --deploy`, plus `--dev` when the
-        tests need the development packages. It sets `PIP_ONLY_BINARY=:all:` for
-        both installs, so a package with no wheel for the image stops the
-        install. It installs no Python there, because the tests use the
-        distribution's, which a step above it installs. The tests run after
-        `ARG CACHEBUST`, and every other stage installs its Python packages
-        after it, as in the Python `test` phase example in `REPO_POLICIES.md`
+        It creates a virtual environment at `$HOME/.pipenv` with
+        `python3 -m venv` when it is missing, then uses that environment's `pip`
+        and `pipenv`. On a host, it first installs the distribution's python and
+        venv packages when they are missing. It installs pipenv and its
+        dependencies by hash, with `pip install --require-hashes`. It installs
+        the packages from `Pipfile.lock` with `pipenv install --deploy`, plus
+        `--dev` when the tests need the development packages. It sets
+        `PIP_ONLY_BINARY=:all:` for both installs, so a package with no wheel
+        for the image stops the install. In that step it installs no Python,
+        because a step above it already did. `Pipfile` names no
+        `python_version`, because `--deploy` stops when the distribution's
+        Python differs from it. The tests run after `ARG CACHEBUST`, and every
+        other stage installs its Python packages after it, as in the Python
+        `test` phase example in `REPO_POLICIES.md`
 
     - Server: the final stage builds and runs the application
     - Non-server: the final stage brings up the dev environment
@@ -174,7 +179,22 @@ Template files can be fetched from:
           `https://git.eeqj.de/sneak/prompts/raw/branch/main/.golangci.yml` and,
           in the same commit, set the lint phase digest to the one named in the
           `.golangci.yml` paragraph of `REPO_POLICIES.md`)
-    - [ ] JS: `yarn init`, `yarn add --dev prettier`
+    - [ ] JS, or any repository that runs prettier through yarn: make the first
+          `yarn.lock` with the steps below. `script/bootstrap` installs no yarn
+          until `yarn.lock` exists, so run them with any distribution's node and
+          yarn, such as Alpine's (`apk add nodejs-current yarn`). Use `yarnpkg`
+          on Debian and Ubuntu.
+        1. Read the version from `yarnPath` in
+           `https://git.eeqj.de/sneak/prompts/raw/branch/main/.yarnrc.yml`.
+        2. Run `yarn set version <version>`. It writes
+           `.yarn/releases/yarn-<version>.cjs`, `.yarnrc.yml` and
+           `package.json`.
+        3. Add `nodeLinker: node-modules` and `enableTelemetry: false` to
+           `.yarnrc.yml`.
+        4. Add `"private": true` to `package.json`.
+        5. Run `yarn add --dev prettier`. It writes `yarn.lock`.
+        6. Add `.yarn/releases/** binary` to `.gitattributes`.
+        7. Run `yarn install --immutable`. It must pass and change nothing.
     - [ ] Python: `pyproject.toml`
 
 ## Configure script/ Entrypoints and Makefile
@@ -185,13 +205,23 @@ are thin shims calling them. Model scripts:
 
 - [ ] scripts are POSIX sh (`#!/bin/sh`, `set -eu`, no bashisms) so they run on
       alpine images without bash
-- [ ] `script/bootstrap` / `make bootstrap` — installs all dependencies,
-      idempotently, assuming nothing (pkg manager detection nix/apt/brew/apk;
-      node and yarn from that package manager when they are missing; a one-line
-      message and a stop when yarn's major version is not 1); a non-server
-      repo's development environment stage runs it, with only system packages
-      installed inline above it; a gate phase or the build stage installs what
-      its base image lacks either inline or by running it
+- [ ] `script/bootstrap` / `make bootstrap` installs all dependencies,
+      idempotently, and assumes nothing is present:
+    - It detects the package manager: nix, apt, brew or apk.
+    - It installs node, yarn and the node packages only when `yarn.lock` is in
+      the tree. node and yarn come from that package manager when they are
+      missing.
+    - It installs the node packages with `yarn install --immutable`. The
+      distribution's yarn only starts the release file that `yarnPath` in
+      `.yarnrc.yml` names, and that file does the work.
+    - A non-server repo's development environment stage runs it, with only
+      system packages installed inline above it.
+    - A gate phase or the build stage installs what its base image lacks, either
+      inline or by running it.
+- [ ] A `Dockerfile` stage that needs yarn may start from any distribution that
+      packages node and yarn. It copies `package.json`, `yarn.lock`,
+      `.yarnrc.yml` and `.yarn/releases/` before it runs `script/bootstrap`. A
+      stage that needs no yarn copies none of them.
 - [ ] `script/setup` / `make setup` — readies a fresh clone: runs `bootstrap`,
       then `install-precommit`, plus repo-specific init
 - [ ] `script/test` / `make test` —
@@ -222,7 +252,9 @@ are thin shims calling them. Model scripts:
       The bootstrap is required: CI checks out and runs this alone, and
       `script/fmt-check` runs the formatter on the host.
 - [ ] `script/bootstrap`, `script/fmt` and `script/fmt-check` run yarn by
-      whichever name is present: `yarn`, or `yarnpkg` on Debian and Ubuntu.
+      whichever name is present: `yarn`, or `yarnpkg` on Debian and Ubuntu. With
+      neither name on `PATH`, `script/fmt` and `script/fmt-check` print one line
+      saying to run `script/bootstrap`, and exit 1.
 - [ ] No `docker build` in `script/` leaves a dangling image behind:
       `script/lint` and `script/test` write no image, and `script/docker` and
       `script/cibuild` tag theirs
@@ -237,12 +269,13 @@ are thin shims calling them. Model scripts:
 
 - [ ] `make check` passes
 - [ ] `make docker` succeeds
-- [ ] `script/cibuild` succeeds in a fresh clone on a host carrying what CI has
-      (the runner image `docker.gitea.com/runner-images:ubuntu-latest`: docker,
-      git and node 24), with any yarn first taken off `PATH`, and demonstrably
-      executed the checks — a sub-second build, or `CACHED` on a step that lints
-      or tests, one of the `RUN` steps below `ARG CACHEBUST`, means nothing ran.
-      Above that line, these steps are expected to show `CACHED`:
+- [ ] `script/cibuild` succeeds in a fresh clone on a host carrying what CI has.
+      That host is the runner image
+      `docker.gitea.com/runner-images:ubuntu-latest`, which has docker, git and
+      node 24. Take any yarn off `PATH` first. The run must show that the checks
+      executed. A sub-second build means nothing ran. So does `CACHED` on a step
+      that lints or tests, one of the `RUN` steps below `ARG CACHEBUST`. Above
+      that line, these steps are expected to show `CACHED`:
     - the steps that install system packages
     - the steps that download Go's modules
     - the step that runs `script/bootstrap` to install a Python `test` phase's
@@ -260,7 +293,11 @@ are thin shims calling them. Model scripts:
       that a `Dockerfile` adds itself does not get this exception
 - [ ] node, yarn, npm, python, pip and venv come from the distribution wherever
       possible, never from nvm, pyenv, corepack or `npm install -g yarn`. If the
-      distribution's version is too old, use a newer distribution
+      distribution's version is too old, use a newer distribution. node means
+      the distribution's newest Node package, such as `nodejs-current` on Alpine
+      3.24
+- [ ] yarn's release file is in git under `.yarn/releases/`, written once by
+      `yarn set version` with an exact version (repositories with `yarn.lock`)
 - [ ] No unnecessary files in repo root
 - [ ] All dates written as YYYY-MM-DD
 

prompts/REPO_POLICIES.md

@@ -35,7 +35,7 @@ style conventions are in separate documents:
     - Docker: `@sha256:...`
     - Go: the module hash in `go.sum`
     - Python: the package hash in `Pipfile.lock`
-    - npm: the integrity hash in the lockfile
+    - npm: the `checksum` in `yarn.lock`
     - GitHub Actions: `@<commit-sha>`
 
     This also means never `curl | bash` to install a tool such as rustup.
@@ -56,7 +56,8 @@ style conventions are in separate documents:
     - `apk add`
 
     These come from the distribution wherever possible:
-    - node
+    - node, meaning the distribution's newest Node package, such as
+      `nodejs-current` on Alpine 3.24
     - yarn
     - npm
     - python
@@ -69,6 +70,9 @@ style conventions are in separate documents:
     - corepack
     - `npm install -g yarn`
 
+    yarn's release file is third-party code, and git pins it. `yarn set version`
+    writes it to `.yarn/releases/` once, given an exact version.
+
     These are not trusted, so everything from them stays pinned by hash:
     - Docker Hub
     - PyPI
@@ -121,15 +125,53 @@ style conventions are in separate documents:
     only when it is missing. A tool from outside the distribution is never
     installed as "latest" or "lts"; it is always an exact version.
 
+    `script/bootstrap` installs node, yarn and the node packages only when
+    `yarn.lock` is in the tree. With no `yarn.lock`, it installs no node and no
+    yarn. It installs the node packages with `yarn install --immutable`. That
+    install fails when a package's `checksum` is wrong, or when `package.json`
+    is out of step with `yarn.lock`.
+
+    Each repository commits the yarn that runs. `yarnPath` in `.yarnrc.yml`
+    points at the release file in `.yarn/releases/`. The distribution's yarn
+    only starts that file, and that file does the work. Alpine packages yarn 1,
+    and Debian 13 packages yarn 4.1. The same committed yarn does the work on
+    both. Corepack never runs, and no yarn is downloaded.
+
+    `.yarnrc.yml` holds these settings:
+    - `yarnPath`
+    - `nodeLinker: node-modules`
+    - `enableTelemetry: false`, because yarn otherwise sends usage reports from
+      any host that is not CI
+
+    By default, yarn runs no dependency's install script. A dependency that must
+    run one is named in `package.json`, as
+    `"dependenciesMeta": { "<name>": { "built": true } }`.
+
+    `.gitattributes` carries `.yarn/releases/** binary`, so diffs and merges
+    treat the release file as one opaque file.
+
+    yarn 1 ignores `--immutable` and exits 0, so on a tree with no `.yarnrc.yml`
+    the install is not frozen. A repository therefore re-vendors
+    `script/bootstrap` and converts its `yarn.lock` in one commit.
+
     Debian and Ubuntu name the yarn command `yarnpkg`. `script/bootstrap`,
     `script/fmt` and `script/fmt-check` each carry the same small function that
-    runs whichever name is present.
+    runs whichever name is present. With neither name on `PATH`, `script/fmt`
+    and `script/fmt-check` print one line saying to run `script/bootstrap`, and
+    exit 1.
 
-    `script/bootstrap` stops with a one-line message when yarn's major version
-    is not 1, before it installs any node packages. Debian 13 and Ubuntu 26.04
-    package yarn 4. With `--frozen-lockfile`, yarn 4 refuses a yarn 1
-    `yarn.lock`. Without that flag, it rewrites the file and drops the hashes.
-    Alpine and Ubuntu 24.04 package yarn 1, so use one of those.
+    A `Dockerfile` stage that needs yarn may start from any distribution that
+    packages node and yarn. It copies all of these before it runs
+    `script/bootstrap`:
+    - `package.json`
+    - `yarn.lock`
+    - `.yarnrc.yml`
+    - `.yarn/releases/`
+
+    With only `package.json` and `yarn.lock`, the install fails. Alpine's yarn 1
+    then says to enable corepack; never do that, and copy the missing files
+    instead. The Python and Go stages below need no yarn and copy no
+    `yarn.lock`, so `script/bootstrap` installs no node and no yarn there.
 
     `script/cibuild` runs the CI build, and the Gitea workflow calls it. The
     script changes to the repo root, runs `script/bootstrap`, runs
@@ -161,6 +203,12 @@ style conventions are in separate documents:
   instead of invoking the underlying tools directly. The Makefile is the single
   source of truth for how these operations are run.
 
+    An agent whose work is confined to one package may run `go test` directly on
+    that package's suite, or on individual tests in it, while iterating. This is
+    the only exception to this rule. `go build`, `go vet` and the linter still
+    go through make targets. A run while iterating is not a gate, so the full
+    `make check` is still required before every push.
+
 - The Makefile is authoritative documentation for how the repo is used. Beyond
   the required targets above, it should have targets for every common operation:
     - running a local development server (`make run`, `make dev`)
@@ -189,12 +237,13 @@ style conventions are in separate documents:
     running `script/bootstrap`. Only system packages may be installed inline
     above it, so that check builds keep them; the `prompts` repo's own
     `Dockerfile` does this. A stage that runs `script/bootstrap` COPYs `script/`
-    and the dependency manifests (`package.json` + `yarn.lock`, `go.mod` +
-    `go.sum`, etc.) before running it.
+    and the dependency manifests it needs before running it. These are examples:
+    - `package.json`, `yarn.lock`, `.yarnrc.yml` and `.yarn/releases/`
+    - `go.mod` and `go.sum`
 
-- **Linting and testing run in Docker, as phases of the `Dockerfile`.** There is
-  no separate lint file. `script/lint` and `script/test` each build one phase
-  and nothing else:
+- **The lint and test gates run in Docker, as phases of the `Dockerfile`.**
+  There is no separate lint file. `script/lint` and `script/test` each build one
+  phase and nothing else:
 
     ```sh
     docker build --build-arg CACHEBUST="$(date +%s)-$$" \
@@ -507,6 +556,14 @@ style conventions are in separate documents:
         distribution's Python, which a step above it installs. If it installs
         anything else there, the step goes after `ARG CACHEBUST`.
 
+    - Debian's Python refuses a system-wide `pip install`, so pipenv goes in a
+      virtual environment at `$HOME/.pipenv`. `script/bootstrap` creates it with
+      `python3 -m venv` when it is missing, then uses that environment's `pip`
+      and `pipenv`. On a host, it first installs the distribution's python and
+      venv packages when they are missing. One script then works on a host and
+      in a `Dockerfile`. `Pipfile` names no `python_version`, because
+      `pipenv install --deploy` stops when the distribution's Python differs
+      from it.
     - PyPI is not trusted, so `script/bootstrap` installs pipenv and its
       dependencies by hash. It does so with `pip install --require-hashes -r`
       and a requirements file in `script/` that lists each of them with `==` and
@@ -532,11 +589,32 @@ style conventions are in separate documents:
       A cache mount is shared by every build on the host, and nothing checks its
       files again.
 
-    In the example below, `script/bootstrap` does all of these:
-    - finds `make` and `git` already installed
-    - sets `PIP_ONLY_BINARY=:all:`
-    - installs pipenv and its dependencies by hash
-    - runs `pipenv install --dev --deploy`
+    A Python repository's `script/bootstrap` adds these lines in `main`, above
+    the last `echo`. The `ensurepip` test fails when python is missing, and also
+    when Debian's venv package is missing:
+
+    ```sh
+    if [ ! -x "$HOME/.pipenv/bin/pip" ]; then
+        if ! python3 -m ensurepip --version >/dev/null 2>&1; then
+            pkg_install python3 python3-venv python3 python3
+        fi
+        python3 -m venv "$HOME/.pipenv"
+    fi
+    export PIP_ONLY_BINARY=:all:
+    "$HOME/.pipenv/bin/pip" install --require-hashes -r script/requirements.txt
+    "$HOME/.pipenv/bin/pipenv" install --dev --deploy
+    ```
+
+    Make `script/requirements.txt` once, with
+    `echo pipenv | pip-compile --generate-hashes --allow-unsafe -o script/requirements.txt -`.
+    `pip-compile` comes from Alpine's `py3-pip-tools` package; Debian and Ubuntu
+    do not package `pip-tools`. Make the first `Pipfile.lock` with
+    `$HOME/.pipenv/bin/pipenv lock`, after the `pip install` line has installed
+    pipenv.
+
+    In the example below, `script/bootstrap` finds `make`, `git`, python and
+    venv already installed. The example copies no `yarn.lock`, so
+    `script/bootstrap` installs no node and no yarn.
 
     ```dockerfile
     # Test phase. Both pytest runs share one 90-second timeout, so a hang
@@ -549,13 +627,11 @@ style conventions are in separate documents:
     # stay in their own layer when script/ changes.
     RUN apt-get update \
         && apt-get install -y --no-install-recommends ca-certificates make git \
-            python3 python3-pip python3-venv \
+            python3 python3-venv \
         && rm -rf /var/lib/apt/lists/*
-    # Debian's Python refuses a system-wide pip install, so pipenv goes in a
-    # virtual environment. pipenv is not bundled with Python, so
-    # script/bootstrap installs it by hash, with the pip this puts on PATH.
-    RUN python3 -m venv /opt/pipenv
-    ENV PATH=/opt/pipenv/bin:$PATH
+    # script/bootstrap installs pipenv in a virtual environment at
+    # $HOME/.pipenv, and the tests below run that pipenv.
+    ENV PATH=/root/.pipenv/bin:$PATH
     WORKDIR /app
     COPY script/ script/
     COPY Pipfile Pipfile.lock ./
@@ -690,16 +766,16 @@ style conventions are in separate documents:
 
     ```makefile
     test:
-    	@timeout 90 sh -c 'python -m pytest || { \
+    	@timeout 90 sh -c 'pipenv run pytest || { \
     		echo "--- Rerunning with -v for details ---"; \
-    		python -m pytest -v; exit 1; }'
+    		pipenv run pytest -v; exit 1; }'
     ```
 
     Both pytest runs share that one 90-second timeout, as in the `Dockerfile`
     example above, so a hang uses it once and gets no rerun. Ctrl-C does not
     stop a running `make test`, which goes on until the tests end or the 90
     seconds run out. On a Mac without `timeout`, the target fails until it is
-    installed.
+    installed. On a host, the target needs `$HOME/.pipenv/bin` on `PATH`.
 
     The `exit 1` ensures the target always fails after a rerun. The first run
     already proved the tests are broken, so the build must not pass even if a
@@ -723,6 +799,7 @@ style conventions are in separate documents:
     - editor files (`.swp`, `*~`)
     - in-repo agent scratch directories (`.claude/`)
     - `node_modules/`
+    - `.yarn/*`, with `!.yarn/releases` so that git keeps yarn's release file
     - the repo's own build outputs
 
     Fetch the standard `.gitignore` from
@@ -744,16 +821,16 @@ style conventions are in separate documents:
   Such a `.dockerignore` is more dangerous than a short file with no secret
   patterns at all, because it reads as solved and stops anyone looking. Give
   every depth-independent pattern the `**/` prefix, and leave only genuinely
-  root-anchored entries unprefixed. Those are `.claude`, and the repo's own
-  host-built binary. The binary is written `/myapp` and never `**/myapp`, which
-  would also match `cmd/myapp/` and delete the package directory from the
-  context. Matching is case-sensitive, and an all-caps copy of each pattern
-  still misses `Server.Key`. So secret names use character ranges:
-  `**/*.[kK][eE][yY]`, `**/*.[pP][eE][mM]`, and likewise for `.envrc` and the
-  extensionless SSH keys. Where such a pattern also catches something the build
-  needs, re-include it with a negation (`!docs/example.env`). Deleting the
-  pattern reopens the exposure for every other file it covers. Fetch the
-  standard `.dockerignore` from
+  root-anchored entries unprefixed. Those are `.claude`, `.yarn/*`,
+  `!.yarn/releases`, and the repo's own host-built binary. The binary is written
+  `/myapp` and never `**/myapp`, which would also match `cmd/myapp/` and delete
+  the package directory from the context. Matching is case-sensitive, and an
+  all-caps copy of each pattern still misses `Server.Key`. So secret names use
+  character ranges: `**/*.[kK][eE][yY]`, `**/*.[pP][eE][mM]`, and likewise for
+  `.envrc` and the extensionless SSH keys. Where such a pattern also catches
+  something the build needs, re-include it with a negation
+  (`!docs/example.env`). Deleting the pattern reopens the exposure for every
+  other file it covers. Fetch the standard `.dockerignore` from
   `https://git.eeqj.de/sneak/prompts/raw/branch/main/.dockerignore` and extend
   it with the repo's own artifacts.
 
@@ -1057,7 +1134,8 @@ style conventions are in separate documents:
     - `Dockerfile`, `.dockerignore`
     - `.gitea/workflows/check.yml`
     - Go: `go.mod`, `go.sum`, `.golangci.yml`
-    - JS: `package.json`, `yarn.lock`, `.prettierrc`, `.prettierignore`
+    - JS: `package.json`, `yarn.lock`, `.yarnrc.yml`, `.yarn/releases/`,
+      `.gitattributes`, `.prettierrc`, `.prettierignore`
     - Python: `pyproject.toml`
 
 - Guidance for coding agents lives in one `AGENTS.md` at the repository root. It

script/bootstrap

@@ -3,7 +3,11 @@
 # this repo. Idempotent: every install is guarded by a check so already
 # installed tools are skipped. Base tools, node and yarn come from nix,
 # apt, brew, or apk (detected in that order), with no version and no
-# hash, because the distribution is trusted. Assumes nothing is present.
+# hash, because the distribution is trusted. It installs node, yarn and
+# the node packages only when yarn.lock is in the tree. The
+# distribution's yarn only starts the release file that yarnPath in
+# .yarnrc.yml names, and that file does the work. So git pins the yarn
+# that runs. Assumes nothing is present.
 set -eu
 
 ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
@@ -60,8 +64,11 @@ missing() {
 run_yarn() {
     if command -v yarn >/dev/null 2>&1; then
         yarn "$@"
-    else
+    elif command -v yarnpkg >/dev/null 2>&1; then
         yarnpkg "$@"
+    else
+        echo "no yarn; run script/bootstrap first" >&2
+        exit 1
     fi
 }
 
@@ -70,21 +77,16 @@ main() {
 
     if missing make; then pkg_install gnumake make make make; fi
     if missing git; then pkg_install git git git git; fi
-    if missing node; then pkg_install nodejs nodejs node nodejs; fi
-    if missing yarn && missing yarnpkg; then
-        pkg_install yarn yarnpkg yarn yarn
-    fi
 
-    # Debian 13 and Ubuntu 26.04 package yarn 4, which refuses a yarn 1
-    # yarn.lock, or rewrites it and drops its hashes.
-    yarn_version="$(run_yarn --version)"
-    if [ "${yarn_version%%.*}" != "1" ]; then
-        echo "bootstrap: yarn $yarn_version refuses this yarn 1 yarn.lock;" \
-            "use a distribution that packages yarn 1" >&2
-        exit 1
-    fi
+    # A Dockerfile stage that needs no yarn copies no yarn.lock.
+    if [ -f yarn.lock ]; then
+        if missing node; then pkg_install nodejs_latest nodejs node nodejs-current; fi
+        if missing yarn && missing yarnpkg; then
+            pkg_install yarn yarnpkg yarn yarn
+        fi
 
-    run_yarn install --frozen-lockfile
+        run_yarn install --immutable
+    fi
 
     echo "bootstrap complete"
 }

script/fmt

@@ -8,8 +8,11 @@ ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
 run_yarn() {
     if command -v yarn >/dev/null 2>&1; then
         yarn "$@"
-    else
+    elif command -v yarnpkg >/dev/null 2>&1; then
         yarnpkg "$@"
+    else
+        echo "no yarn; run script/bootstrap first" >&2
+        exit 1
     fi
 }
 

script/fmt-check

@@ -8,8 +8,11 @@ ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
 run_yarn() {
     if command -v yarn >/dev/null 2>&1; then
         yarn "$@"
-    else
+    elif command -v yarnpkg >/dev/null 2>&1; then
         yarnpkg "$@"
+    else
+        echo "no yarn; run script/bootstrap first" >&2
+        exit 1
     fi
 }
 

yarn.lock

@@ -1,8 +1,23 @@
-# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY.
-# yarn lockfile v1
+# This file is generated by running "yarn install" inside your project.
+# Manual changes might be lost - proceed with caution!
 
+__metadata:
+  version: 10
+  cacheKey: 10c0
 
-prettier@3.8.1:
-  version "3.8.1"
-  resolved "https://registry.yarnpkg.com/prettier/-/prettier-3.8.1.tgz#edf48977cf991558f4fcbd8a3ba6015ba2a3a173"
-  integrity sha512-UOnG6LftzbdaHZcKoPFtOcCKztrQ57WkHDeRD9t/PTQtmT0NHSeWWepj6pS0z/N7+08BHFDQVUrfmfMRcZwbMg==
+"prettier@npm:3.8.1":
+  version: 3.8.1
+  resolution: "prettier@npm:3.8.1"
+  bin:
+    prettier: bin/prettier.cjs
+  checksum: 10c0/33169b594009e48f570471271be7eac7cdcf88a209eed39ac3b8d6d78984039bfa9132f82b7e6ba3b06711f3bfe0222a62a1bfb87c43f50c25a83df1b78a2c42
+  languageName: node
+  linkType: hard
+
+"root-workspace-0b6124@workspace:.":
+  version: 0.0.0-use.local
+  resolution: "root-workspace-0b6124@workspace:."
+  dependencies:
+    prettier: "npm:3.8.1"
+  languageName: unknown
+  linkType: soft