TODO.md

@@ -21,6 +21,11 @@ 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

prompts/EXISTING_REPO_CHECKLIST.md

@@ -1,6 +1,6 @@
 ---
 title: Existing Repo Checklist
-last_modified: 2026-11-04
+last_modified: 2026-11-06
 ---
 
 Use this checklist when beginning work in a repo that may not yet conform to our
@@ -267,14 +267,14 @@ with your task.
 
 - [ ] Pre-commit hook is installed (`make hooks`)
 - [ ] No secrets in the repo (`.env`, keys, credentials)
-- [ ] 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
+- [ ] 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
 - [ ] 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

prompts/NEW_REPO_CHECKLIST.md

@@ -1,6 +1,6 @@
 ---
 title: New Repo Checklist
-last_modified: 2026-11-04
+last_modified: 2026-11-06
 ---
 
 Use this checklist when creating a new repository from scratch. Follow the steps
@@ -285,12 +285,13 @@ 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 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
+- [ ] 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
 - [ ] 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

prompts/REPO_POLICIES.md

@@ -1,6 +1,6 @@
 ---
 title: Repository Policies
-last_modified: 2026-11-04
+last_modified: 2026-11-06
 ---
 
 This document covers repository structure, tooling, and workflow standards. Code
@@ -21,13 +21,28 @@ 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 everything fetched from
-  a remote source, including:
+  single most important rule in this document. It covers what we download and
+  install ourselves in scripts and Dockerfiles:
     - Docker base images
     - Go modules
-    - Python packages
+    - Python packages from PyPI
     - 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
@@ -44,17 +59,6 @@ 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
@@ -79,9 +83,6 @@ style conventions are in separate documents:
     - 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`