Install node, yarn and python from the distribution (closes #146 )

Follows sneak's ruling at #146 (comment). Runtimes and the installer tools bundled with python come from the distribution, with no version and no hash. Third-party packages stay pinned by hash. script/bootstrap drops nvm and corepack. It installs node, yarn and the node packages only when yarn.lock is in the tree, and stops there when yarn's major version is not 1. This repository's Dockerfile starts from Alpine 3.24. The Python example starts from debian:trixie-slim, keeps pipenv at $HOME/.pipenv on a host and in an image, and sets PIP_ONLY_BINARY=:all:, so pip downloads no build tools without a hash check. Model: opus-5-5
2026-11-04 06:24:24 +00:00
16 changed files with 138 additions and 1303 deletions
@@ -35,12 +35,6 @@
 # `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`.
@@ -2,6 +2,3 @@
 # 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
@@ -19,12 +19,10 @@ Thumbs.db

 # Node
 node_modules/
-.yarn/*
-!.yarn/releases

-# 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`.
+# 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`.

 # Environment files. `*.env` covers bare `.env` and the `prod.env`
 # convention. Only the templates `example.env` and `sample.env` are
@@ -1,3 +1,2 @@
 node_modules/
-.yarn/
 yarn.lock
@@ -1,5 +0,0 @@
-enableTelemetry: false
-
-nodeLinker: node-modules
-
-yarnPath: .yarn/releases/yarn-4.18.1.cjs
@@ -6,20 +6,17 @@
 # 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.
+# so they need no version and no hash.
 #
 # alpine 3.24.3, 2026-11-04
 FROM alpine@sha256:be2656061b536c1883c4034790e21d0a09c5aaaf51968b89368a3c0371ea2c9a AS lint
-RUN apk add --no-cache git make nodejs-current yarn
+RUN apk add --no-cache git make nodejs yarn
 ARG CACHEBUST

 WORKDIR /app

 COPY script/ script/
-COPY package.json yarn.lock .yarnrc.yml ./
-COPY .yarn/releases/ .yarn/releases/
+COPY package.json yarn.lock ./
 RUN script/bootstrap

 COPY . .
@@ -30,14 +27,13 @@ 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-current yarn
+RUN apk add --no-cache git make nodejs yarn
 ARG CACHEBUST

 WORKDIR /app

 COPY script/ script/
-COPY package.json yarn.lock .yarnrc.yml ./
-COPY .yarn/releases/ .yarn/releases/
+COPY package.json yarn.lock ./
 RUN script/bootstrap

 COPY . .
@@ -52,7 +48,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-current yarn
+RUN apk add --no-cache git make nodejs yarn
 ARG CACHEBUST

 WORKDIR /app
@@ -63,8 +59,7 @@ 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 .yarnrc.yml ./
-COPY .yarn/releases/ .yarn/releases/
+COPY package.json yarn.lock ./
 RUN script/bootstrap

 COPY . .
@@ -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 --immutable`)
+- `script/bootstrap` — install all dependencies (yarn install)
 - `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
@@ -21,33 +21,6 @@ fmt-check, and commit.

 # Completed Steps

- 2026-11-06: The pinning rule in `prompts/REPO_POLICIES.md` now opens with its
-  scope: what we download and install ourselves in scripts and Dockerfiles
-  (https://git.eeqj.de/sneak/prompts/issues/154). Distribution packages are
-  outside the rule, and updating and upgrading them is allowed. Both checklists
-  say the same.
- 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
@@ -2,6 +2,5 @@
  "private": true,
  "devDependencies": {
    "prettier": "3.8.1"
-  },
-  "packageManager": "yarn@4.18.1"
+  }
 }
@@ -8,8 +8,7 @@ last_modified: 2026-11-04

 1. Use yarn for package management, avoid using npm.

-1. Install node from the distribution. If its version is too old, use a newer
-   distribution.
+1. Install node from the distribution, in whatever version it packages.

 1. Use `prettier` for code formatting, with four spaces for indentation.

@@ -1,6 +1,6 @@
 ---
 title: Existing Repo Checklist
-last_modified: 2026-11-06
+last_modified: 2026-11-04
 ---

 Use this checklist when beginning work in a repo that may not yet conform to our
@@ -88,12 +88,12 @@ with your task.
    `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`
+    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. `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`

 - [ ] The gate phases invoke their tools directly, never through `make lint` or
      `script/test` — those are themselves a `docker build` and would recurse
@@ -164,39 +164,10 @@ 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`, `.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.
+    - [ ] 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`)
    - [ ] Python: `pyproject.toml`
    - [ ] Docs/writing: `.prettierrc`, `.prettierignore` (same URLs as above)

@@ -233,18 +204,15 @@ with your task.
      installed.
 - [ ] `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.
+      they are missing. With `yarn.lock` in the tree, `script/bootstrap` stops
+      with a one-line message when yarn's major version is not 1.
+- [ ] A `Dockerfile` stage copies `yarn.lock` before it runs `script/bootstrap`
+      only if that stage needs yarn. A stage that needs yarn starts from an
+      image whose distribution packages yarn 1, which today means Alpine.
 - [ ] `script/bootstrap`, `script/fmt` and `script/fmt-check` run yarn by
      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.
+      neither name on `PATH`, they 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
@@ -267,21 +235,17 @@ with your task.

 - [ ] Pre-commit hook is installed (`make hooks`)
 - [ ] No secrets in the repo (`.env`, keys, credentials)
- [ ] No mutable references (tags, `@latest`) to what the repo downloads and
-      installs itself in scripts and Dockerfiles — all pinned by cryptographic
-      hash with version/date comment. Distribution packages are outside this
-      rule. They need no version and no hash, and updating and upgrading them is
-      fine too. In a `Dockerfile`, the distribution is the pinned base image's.
-      On a host, it is the host's, and the host's package manager stands for it,
-      nix and brew included. A package source that a `Dockerfile` adds itself is
-      not the distribution's own, so its packages are pinned
+- [ ] No mutable references in Dockerfiles or scripts (tags, `@latest`) — all
+      pinned by cryptographic hash with version/date comment. The one exception
+      is a package from the distribution's own package index, which needs no
+      version and no hash. Pulling that index is also allowed. In a
+      `Dockerfile`, the distribution is the pinned base image's. On a host, it
+      is the host's, and the host's package manager stands for it, nix and brew
+      included. A package source 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. 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`)
+      distribution's version is too old, use a newer distribution
 - [ ] Using `yarn`, not `npm` (JS projects)

 # Directory Structure
@@ -1,6 +1,6 @@
 ---
 title: New Repo Checklist
-last_modified: 2026-11-06
+last_modified: 2026-11-04
 ---

 Use this checklist when creating a new repository from scratch. Follow the steps
@@ -156,12 +156,12 @@ Template files can be fetched from:
        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`
+        for the image stops the install. It installs no Python there, because
+        the tests use the distribution's, which a step above it installs.
+        `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
@@ -179,22 +179,7 @@ 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, 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.
+    - [ ] JS: `yarn init`, `yarn add --dev prettier`
    - [ ] Python: `pyproject.toml`

 ## Configure script/ Entrypoints and Makefile
@@ -211,17 +196,15 @@ are thin shims calling them. Model scripts:
    - 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.
+    - With `yarn.lock` in the tree, it stops with a one-line message 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.
- [ ] 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.
+- [ ] A `Dockerfile` stage copies `yarn.lock` before it runs `script/bootstrap`
+      only if that stage needs yarn. A stage that needs yarn starts from an
+      image whose distribution packages yarn 1, which today means Alpine.
 - [ ] `script/setup` / `make setup` — readies a fresh clone: runs `bootstrap`,
      then `install-precommit`, plus repo-specific init
 - [ ] `script/test` / `make test` —
@@ -253,8 +236,8 @@ are thin shims calling them. Model scripts:
      `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. With
-      neither name on `PATH`, `script/fmt` and `script/fmt-check` print one line
-      saying to run `script/bootstrap`, and exit 1.
+      neither name on `PATH`, they 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
@@ -285,20 +268,15 @@ are thin shims calling them. Model scripts:
      final stage is missing its `COPY --from=` edge to the gate phases.
 - [ ] No secrets in repo, and none in the build context: enumerate a probe image
      rather than reading `.dockerignore`
- [ ] No mutable references to what the repo downloads and installs itself in
-      scripts and Dockerfiles. Distribution packages are outside this rule. They
-      need no version and no hash, and updating and upgrading them is fine too.
-      In a `Dockerfile`, the distribution is the pinned base image's. On a host,
-      it is the host's, and the host's package manager stands for it, nix and
-      brew included. A package source that a `Dockerfile` adds itself is not the
-      distribution's own, so its packages are pinned
+- [ ] No mutable image/package references. The one exception is a package from
+      the distribution's own package index, which needs no version and no hash.
+      Pulling that index is also allowed. In a `Dockerfile`, the distribution is
+      the pinned base image's. On a host, it is the host's, and the host's
+      package manager stands for it, nix and brew included. A package source
+      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. 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`)
+      distribution's version is too old, use a newer distribution
 - [ ] No unnecessary files in repo root
 - [ ] All dates written as YYYY-MM-DD

@@ -1,6 +1,6 @@
 ---
 title: Repository Policies
-last_modified: 2026-11-06
+last_modified: 2026-11-04
 ---

 This document covers repository structure, tooling, and workflow standards. Code
@@ -21,28 +21,13 @@ style conventions are in separate documents:
  with the authoritative source as policies evolve.

 - **External references must be pinned by cryptographic hash.** This is the
-  single most important rule in this document. It covers what we download and
-  install ourselves in scripts and Dockerfiles:
+  single most important rule in this document. It covers everything fetched from
+  a remote source, including:
    - Docker base images
    - Go modules
-    - Python packages from PyPI
+    - Python packages
    - npm packages
    - GitHub Actions
-    - release archives fetched with `curl` or `wget`
-
-    Packages from the distribution's own package manager are outside this rule.
-    They need no version and no hash, because the distribution is trusted. In a
-    `Dockerfile`, it is the pinned base image's distribution. On a host, it is
-    the host's. The host's package manager stands for its distribution, and that
-    includes nix and brew. Updating the package index and upgrading installed
-    packages are fine too. This command, for example, is allowed:
-
-    ```sh
-    apt update && apt upgrade -y && apt install -y build-essential
-    ```
-
-    A package source that a `Dockerfile` adds itself is not the distribution's
-    own, so its packages are pinned like any other download.

    A version tag such as `@v4`, `@latest` or `:3.21` is server-mutable, and
    therefore a remote code execution vulnerability. Reference an external
@@ -50,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 `checksum` in `yarn.lock`
+    - npm: the integrity hash in the lockfile
    - GitHub Actions: `@<commit-sha>`

    This also means never `curl | bash` to install a tool such as rustup.
@@ -59,9 +44,19 @@ style conventions are in separate documents:
    Unverified install scripts are arbitrary remote code execution. Double-check
    every external reference in every file before committing.

+    There is one exception: a package from the distribution's own package index
+    needs no version and no hash. Pulling that index is also allowed. The
+    distribution is trusted. In a `Dockerfile`, it is the pinned base image's
+    distribution. On a host, it is the host's. The host's package manager stands
+    for its distribution, and that includes nix and brew. These commands are
+    examples:
+    - `apt-get update`
+    - `apt-get install`
+    - `apk update`
+    - `apk add`
+
    These come from the distribution wherever possible:
-    - node, meaning the distribution's newest Node package, such as
-      `nodejs-current` on Alpine 3.24
+    - node
    - yarn
    - npm
    - python
@@ -74,15 +69,15 @@ 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
    - the npm registry
    - `go get`

+    A package source that a `Dockerfile` adds itself is not the distribution's
+    own, so the exception does not cover it.
+
 - Every repo with software must have a root `Makefile` with these targets:
    - `make bootstrap`
    - `make setup`
@@ -128,51 +123,25 @@ style conventions are in separate documents:

    `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.
+    yarn, and it does not check yarn's version.

    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. With neither name on `PATH`, `script/fmt`
-    and `script/fmt-check` print one line saying to run `script/bootstrap`, and
-    exit 1.
+    runs whichever name is present. With neither name on `PATH`, the function
+    prints one line saying to run `script/bootstrap`, and exits 1.

-    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 `yarn.lock` in the tree, `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 in its own format, with its own hashes in place of
+    these. Alpine and Ubuntu 24.04 package yarn 1, so a host uses one of those.

-    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.
+    A `Dockerfile` stage copies `yarn.lock` before it runs `script/bootstrap`
+    only if that stage needs yarn. A stage that needs yarn starts from an image
+    whose distribution packages yarn 1, which today means Alpine. The Python and
+    Go stages below need no yarn, so they copy no `yarn.lock` before that step
+    and never reach the stop.

    `script/cibuild` runs the CI build, and the Gitea workflow calls it. The
    script changes to the repo root, runs `script/bootstrap`, runs
@@ -200,16 +169,9 @@ style conventions are in separate documents:
    README must document the provided scripts in an **Entrypoints** section (see
    the README requirements below).

- Run the repo's own entrypoints, never the underlying tools directly. The
-  `script/` scripts are the single source of truth for how each operation runs.
-  Calling them directly is fine, and so is calling the Makefile targets. The
-  Makefile targets must still exist, as the thin shims described above.
-
-    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 the entrypoints. A run while iterating is not a gate, so the full
-    `make check` is still required before every push.
+- Always use Makefile targets (`make fmt`, `make test`, `make lint`, etc.)
+  instead of invoking the underlying tools directly. The Makefile is the single
+  source of truth for how these operations are run.

 - The Makefile is authoritative documentation for how the repo is used. Beyond
  the required targets above, it should have targets for every common operation:
@@ -239,13 +201,12 @@ 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 it needs before running it. These are examples:
-    - `package.json`, `yarn.lock`, `.yarnrc.yml` and `.yarn/releases/`
-    - `go.mod` and `go.sum`
+    and the dependency manifests it needs (`package.json` + `yarn.lock`,
+    `go.mod` + `go.sum`, etc.) before running it.

- **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:
+- **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:

    ```sh
    docker build --build-arg CACHEBUST="$(date +%s)-$$" \
@@ -591,9 +552,9 @@ style conventions are in separate documents:
      A cache mount is shared by every build on the host, and nothing checks its
      files again.

-    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:
+    A Python repository's `script/bootstrap` adds these lines. 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
@@ -607,13 +568,6 @@ style conventions are in separate documents:
    "$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.
@@ -629,7 +583,7 @@ 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-venv \
+            python3 python3-pip python3-venv \
        && rm -rf /var/lib/apt/lists/*
    # script/bootstrap installs pipenv in a virtual environment at
    # $HOME/.pipenv, and the tests below run that pipenv.
@@ -801,7 +755,6 @@ 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
@@ -823,16 +776,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`, `.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
+  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
  `https://git.eeqj.de/sneak/prompts/raw/branch/main/.dockerignore` and extend
  it with the repo's own artifacts.

@@ -1136,8 +1089,7 @@ style conventions are in separate documents:
    - `Dockerfile`, `.dockerignore`
    - `.gitea/workflows/check.yml`
    - Go: `go.mod`, `go.sum`, `.golangci.yml`
-    - JS: `package.json`, `yarn.lock`, `.yarnrc.yml`, `.yarn/releases/`,
-      `.gitattributes`, `.prettierrc`, `.prettierignore`
+    - JS: `package.json`, `yarn.lock`, `.prettierrc`, `.prettierignore`
    - Python: `pyproject.toml`

 - Guidance for coding agents lives in one `AGENTS.md` at the repository root. It
@@ -4,10 +4,8 @@
 # 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. 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.
+# the node packages only when yarn.lock is in the tree. Assumes nothing
+# is present.
 set -eu

 ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
@@ -80,12 +78,21 @@ main() {

    # 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 node; then pkg_install nodejs nodejs node nodejs; fi
        if missing yarn && missing yarnpkg; then
            pkg_install yarn yarnpkg yarn yarn
        fi

-        run_yarn install --immutable
+        # Debian 13 and Ubuntu 26.04 package yarn 4, which refuses a yarn 1
+        # yarn.lock, or rewrites it in its own format.
+        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
+
+        run_yarn install --frozen-lockfile
    fi

    echo "bootstrap complete"
@@ -1,23 +1,8 @@
-# This file is generated by running "yarn install" inside your project.
-# Manual changes might be lost - proceed with caution!
+# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY.
+# yarn lockfile v1

-__metadata:
-  version: 10
-  cacheKey: 10c0

-"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
+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==