diff --git a/TODO.md b/TODO.md index 2de93ac..83c8480 100644 --- a/TODO.md +++ b/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 diff --git a/prompts/EXISTING_REPO_CHECKLIST.md b/prompts/EXISTING_REPO_CHECKLIST.md index 556d131..8fe3f42 100644 --- a/prompts/EXISTING_REPO_CHECKLIST.md +++ b/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 diff --git a/prompts/NEW_REPO_CHECKLIST.md b/prompts/NEW_REPO_CHECKLIST.md index a74f3e2..0380f38 100644 --- a/prompts/NEW_REPO_CHECKLIST.md +++ b/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 diff --git a/prompts/REPO_POLICIES.md b/prompts/REPO_POLICIES.md index 442a378..7e9e79f 100644 --- a/prompts/REPO_POLICIES.md +++ b/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`