Rewrite REPO_POLICIES.md sentence by sentence (closes #136 )

Every sentence of prompts/REPO_POLICIES.md is rewritten against the sentence rules: one idea per sentence, about 30 words at most, lists as bulleted lists, subject and verb early, the main rule before any exception. No rule's meaning changed: nothing is added, removed, loosened or tightened, every reason stays, and code blocks, digests, URLs, file names, commands and quoted strings are unchanged. Both repo checklists carry the same rewrite of the sentences they quote word for word. Model: fable-5-1
Update the canonical .golangci.yml for golangci-lint v2.15.0 (closes #142 )
2026-11-04 01:18:41 +00:00 · 2026-11-04 01:28:09 +01:00 · 2026-11-04 00:28:23 +01:00 · 2026-11-03 23:08:23 +01:00
5 changed files with 712 additions and 443 deletions
@@ -3,6 +3,9 @@ version: "2"
 # Config schema uses the golangci-lint v2 layout (settings live under
 # linters.settings, not top-level linters-settings) so that the
 # thresholds below are actually applied by golangci-lint >= v2.
+#
+# This file has no formatters section, so golangci-lint run does not run
+# gofmt. A repository's script/fmt-check runs it, on the host.

 run:
  timeout: 5m
@@ -16,17 +19,15 @@ linters:
    - gomodguard_v2
  disable:
    # Genuinely incompatible with project patterns
-    - exhaustruct      # Requires all struct fields
-    - exhaustruct_v5   # Requires all struct fields (successor to exhaustruct)
+    - exhaustruct_v5   # Requires all struct fields
    - godot            # Requires comments to end with periods
    - wrapcheck        # Too verbose for internal packages
    - varnamelen       # Short names like db, id are idiomatic Go
    # Deprecated: the warning is attached to the old name, so it is
    # silenced by disabling that name, not by enabling the successor.
+    - exhaustruct      # Deprecated, replaced by exhaustruct_v5
    - wsl              # Deprecated, replaced by wsl_v5
    - gomodguard       # Deprecated, replaced by gomodguard_v2
-    # Misses findings at random in v2.14.0; back once a pinned release fixes it
-    - canonicalheader
  settings:
    lll:
      line-length: 88
@@ -42,7 +43,10 @@ linters:
      # test-support package exists to hand a test privileges the program
      # itself must never have, so a file that is not a test must not import
      # one. Test files, and the files inside a package whose directory name
-      # ends in `test`, are where that code belongs, and are exempt.
+      # ends in `test`, are where that code belongs, and are exempt. A package
+      # in a subdirectory of that directory is not exempt. `${base-path}` is
+      # the directory holding this file, so the name of the directory a
+      # repository is cloned into does not count.
      #
      # The deny list below is the one part of this file a repository is
      # expected to extend, and the only part it may. depguard matches an
@@ -57,24 +61,25 @@ linters:
          files:
            - "$all"
            - "!$test"
-            - "!**/*test/**"
+            - "!${base-path}**/*test/*"
          deny:
            - pkg: net/http/httptest
              desc: >-
                Test-support code belongs in test files and in packages whose
                directory name ends in test, not in the shipped binary.
-    # Only decisions already recorded in the Go package defaults are
-    # listed here. Every entry matches the module path exactly.
+    # Each entry names a module not to use and what to use instead. Every
+    # entry matches the module path exactly.
    gomodguard_v2:
      blocked:
        - module: github.com/rs/zerolog
          recommendations:
            - log/slog
          reason: "Structured logging is stdlib log/slog."
-        # One entry per pre-fork module path, because the later releases
-        # are separate paths. A prefix match would be shorter but would
-        # also reach github.com/go-redis/redismock, the test double for
-        # the successor these entries recommend.
+        # These entries cover only the github.com/go-redis/redis module paths,
+        # one entry per path, because the later releases are separate paths.
+        # A prefix match would be shorter but would also reach
+        # github.com/go-redis/redismock/v9, the test double for the successor
+        # these entries recommend.
        - module: github.com/go-redis/redis
          recommendations:
            - github.com/redis/go-redis/v9
@@ -87,6 +92,10 @@ linters:
          recommendations:
            - github.com/redis/go-redis/v9
          reason: "Pre-fork module; use the maintained go-redis v9."
+        - module: github.com/go-redis/redis/v9
+          recommendations:
+            - github.com/redis/go-redis/v9
+          reason: "Pre-fork module; use the maintained go-redis v9."
        - module: github.com/sergi/go-diff
          recommendations:
            - github.com/aymanbagabas/go-udiff
@@ -110,3 +119,4 @@ linters:
 issues:
  max-issues-per-linter: 0
  max-same-issues: 0
+  uniq-by-line: false
@@ -21,6 +21,53 @@ fmt-check, and commit.

 # Completed Steps

+- 2026-11-04: Rewrote `prompts/REPO_POLICIES.md` sentence by sentence
+  (https://git.eeqj.de/sneak/prompts/issues/136), on sneak's yes at
+  https://git.eeqj.de/sneak/prompts/issues/136#issuecomment-165193. Every rule
+  keeps its meaning and its place, and `must` and `should` stay as they were.
+  Long sentences are split, comma-chained lists are now bulleted lists, and
+  every reason stays. Code blocks, digests, URLs, file names, commands and
+  quoted strings are unchanged.
+- 2026-11-03: The canonical golangci-lint is now v2.15.0, still built with
+  go1.27.0, so the `go` directive rule is unchanged (issue 142). Repositories
+  pick this up on their next re-vendor. Each item in the canonical
+  `.golangci.yml` was tried on a scratch module. These changed:
+    - `canonicalheader` is enabled again, because v2.15.0 fixes the random
+      misses behind issue 105.
+    - The `depguard` exemption covers only the files directly inside a directory
+      whose name ends in `test`. It used to reach every directory below that one
+      too. The name of the directory a repository is cloned into no longer
+      counts.
+    - `gomodguard_v2` also blocks `github.com/go-redis/redis/v9`, whose
+      pre-releases can still be imported under that path.
+    - `uniq-by-line` is now `false`, so a line that trips two linters reports
+      both findings.
+    - Three comments are corrected:
+        - `exhaustruct` is listed as deprecated.
+        - The test double is named `github.com/go-redis/redismock/v9`.
+        - The claim that every blocked module is in the Go package defaults is
+          gone.
+    - A comment says the file has no `formatters` section, so
+      `golangci-lint run` does not run `gofmt`.
+- 2026-11-03: A package from the distribution's own package index now needs no
+  version and no hash, and pulling that index is allowed
+  (https://git.eeqj.de/sneak/prompts/issues/72), on sneak's answer at
+  https://git.eeqj.de/sneak/prompts/issues/72#issuecomment-165196. The
+  distribution is the pinned base image's in a `Dockerfile` and the host's on a
+  host. It is trusted, and everything else stays pinned by hash. A package
+  source that a `Dockerfile` adds itself does not get the exception. The pinning
+  rule of `REPO_POLICIES.md` and both checklists say so, and the canonical Go
+  `Dockerfile`'s `apk add` line has a comment saying why it is allowed.
+- 2026-11-03: A first test run that timed out now gets no verbose rerun
+  (https://git.eeqj.de/sneak/prompts/issues/61), on sneak's approval at
+  https://git.eeqj.de/sneak/prompts/issues/61#issuecomment-165195. The Go recipe
+  in `REPO_POLICIES.md` looks in the first run's output for
+  `panic: test timed out` or `*** Test killed`, and exits 1 when either is
+  there. The Python `make test` example takes the same `timeout 90 sh -c`
+  wrapper as its `Dockerfile` example. The 60 and 90 second rule and the
+  5-minute rule now say a hung package uses the backstop once. The Go item in
+  both repo checklists now asks for this, so a repository with the old recipe
+  fails it.
 - 2026-10-27: Added `prompts/API_POLICIES.md`
  (https://git.eeqj.de/sneak/prompts/issues/137). It holds sneak's rule from
  https://git.eeqj.de/sneak/routewatch/issues/199 that a value in an API
@@ -1,6 +1,6 @@
 ---
 title: Existing Repo Checklist
-last_modified: 2026-10-26
+last_modified: 2026-11-04
 ---

 Use this checklist when beginning work in a repo that may not yet conform to our
@@ -70,8 +70,9 @@ with your task.
      (`--mount=type=cache,target=/root/.cache/go-build`), `golangci-lint run`
      also mounts golangci-lint's
      (`--mount=type=cache,target=/root/.cache/golangci-lint`), and no step
-      mounts anything else; both `go test` runs carry `-count=1`, as in the
-      canonical Go `Dockerfile` in `REPO_POLICIES.md`
+      mounts anything else; both `go test` runs carry `-count=1`; a first run
+      that timed out gets no rerun, as in the canonical Go `Dockerfile` in
+      `REPO_POLICIES.md`
 - [ ] Python: a `test` phase that installs its packages from `Pipfile.lock` does
      it above `ARG CACHEBUST`, with `COPY script/ script/`,
      `COPY Pipfile Pipfile.lock ./` and `RUN script/bootstrap`. When
@@ -104,37 +105,43 @@ with your task.
      `services/api/.claude/`: add anchored entries for those directories.
 - [ ] If the repo embeds a version in a binary: `.dockerignore` lets `.git` into
      the build context. It keeps out every git `config` at any depth
-      (`**/.git/config`, `**/.git/modules/**/config`): the repository's own,
-      each submodule's under `.git/modules/`, and that of a submodule keeping
-      its own `.git` directory. `git describe` does not need them, and each can
-      hold a credential: a password in a remote URL, or the token the CI
-      checkout step stores there. A submodule whose name has a `config` segment
-      (`config`, `deploy/config`, `config/lib`) loses its whole git directory to
-      `**/.git/modules/**/config`, and Go's version stamping then fails the
-      build: give it a name without that segment (`git submodule add --name`).
-      The stage that compiles has `git` (the Debian Go image has it; an alpine
-      one needs `apk add --no-cache git`) and takes the version from the
-      `VERSION` build argument when one is given, otherwise from
-      `git describe --tags --always`. That gives the tag on a tagged commit; on
-      a later commit, the tag, the number of commits since it and the short
-      commit (`v1.2.3-4-gabc1234`); and the short commit when no tag is
-      reachable. The stage that compiles also marks its working directory safe
-      for git (`git config --system --add safe.directory /src`): a context sent
-      as a tar stream keeps the sender's file owners, and git refuses a checkout
-      owned by another user, so the version would come out empty. `ARG VERSION`
-      has no default, and the build fails if the context carries `.git` and the
-      version still comes out empty, `dev` or `unknown`. A plain
-      `docker build .` with no build arguments must succeed; a Dockerfile that
-      refuses an empty build argument drops that refusal and keeps the argument.
-      A checkout whose `.git` is a file (a linked worktree, or a repository
-      checked out as a submodule) is the exception: that file points to a git
-      directory outside the build context, so the build cannot read the version
-      and a plain `docker build .` fails; pass the version with
-      `--build-arg VERSION=...`. `script/docker` and `script/cibuild` already
-      pass the version they compute on the host; it takes precedence. The
-      canonical `.gitea/workflows/check.yml` sets `fetch-depth: 0` on its
-      checkout step, which otherwise clones shallow and fetches no tags, so a CI
-      build finds the tag too.
+      (`**/.git/config`, `**/.git/modules/**/config`):
+    - the repository's own
+    - each submodule's under `.git/modules/`
+    - that of a submodule keeping its own `.git` directory
+
+    `git describe` does not need them, and each can hold a credential: a
+    password in a remote URL, or the token the CI checkout step stores there. A
+    submodule name may have a `config` segment, as in `config`, `deploy/config`
+    or `config/lib`. Such a submodule loses its whole git directory to
+    `**/.git/modules/**/config`, and Go's version stamping then fails the build.
+    Give it a name without that segment (`git submodule add --name`). The stage
+    that compiles has `git`: the Debian Go image has it, and an alpine one needs
+    `apk add --no-cache git`. That stage takes the version from the `VERSION`
+    build argument when one is given, otherwise from
+    `git describe --tags --always`. That gives:
+    - the tag, on a tagged commit
+    - the tag, the number of commits since it and the short commit
+      (`v1.2.3-4-gabc1234`), on a later commit
+    - the short commit, when no tag is reachable
+
+    The stage that compiles also marks its working directory safe for git
+    (`git config --system --add safe.directory /src`). A context sent as a tar
+    stream keeps the sender's file owners, and git refuses a checkout owned by
+    another user, so the version would come out empty. `ARG VERSION` has no
+    default. The build fails if the context carries `.git` and the version still
+    comes out empty, `dev` or `unknown`. A plain `docker build .` with no build
+    arguments must succeed; a Dockerfile that refuses an empty build argument
+    drops that refusal and keeps the argument. A checkout whose `.git` is a file
+    is the exception: a linked worktree, or a repository checked out as a
+    submodule. That file points to a git directory outside the build context, so
+    the build cannot read the version and a plain `docker build .` fails. Pass
+    the version with `--build-arg VERSION=...`. `script/docker` and
+    `script/cibuild` already pass the version they compute on the host; it takes
+    precedence. The canonical `.gitea/workflows/check.yml` sets `fetch-depth: 0`
+    on its checkout step, which otherwise clones shallow and fetches no tags, so
+    a CI build finds the tag too.
+
 - [ ] Gitea Actions workflow in `.gitea/workflows/` runs `script/cibuild` on
      push, checks out with `persist-credentials: false` and with
      `fetch-depth: 0` (which fetches the tags `git describe` needs), carries
@@ -215,7 +222,12 @@ 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
+      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. A package source that a `Dockerfile` adds itself does not
+      get this exception
 - [ ] Using `yarn`, not `npm` (JS projects)

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

 Use this checklist when creating a new repository from scratch. Follow the steps
@@ -75,34 +75,42 @@ Template files can be fetched from:
      anchored entry.
    - If the image embeds a version in a binary: `.dockerignore` lets `.git`
      into the build context. It keeps out every git `config` at any depth
-      (`**/.git/config`, `**/.git/modules/**/config`): the repository's own,
-      each submodule's under `.git/modules/`, and that of a submodule keeping
-      its own `.git` directory. `git describe` does not need them, and each can
-      hold a credential: a password in a remote URL, or the token the CI
-      checkout step stores there. A submodule whose name has a `config` segment
-      (`config`, `deploy/config`, `config/lib`) loses its whole git directory to
-      `**/.git/modules/**/config`, and Go's version stamping then fails the
-      build: give it a name without that segment (`git submodule add --name`).
-      The stage that compiles has `git` (the Debian Go image has it; an alpine
-      one needs `apk add --no-cache git`) and takes the version from the
-      `VERSION` build argument when one is given, otherwise from
-      `git describe --tags --always`. That gives the tag on a tagged commit; on
-      a later commit, the tag, the number of commits since it and the short
-      commit (`v1.2.3-4-gabc1234`); and the short commit when no tag is
-      reachable. The stage that compiles also marks its working directory safe
-      for git (`git config --system --add safe.directory /src`): a context sent
-      as a tar stream keeps the sender's file owners, and git refuses a checkout
-      owned by another user, so the version would come out empty. `ARG VERSION`
-      has no default, and the build fails if the context carries `.git` and the
-      version still comes out empty, `dev` or `unknown`. A plain
-      `docker build .` with no build arguments must succeed; a Dockerfile that
-      refuses an empty build argument drops that refusal and keeps the argument.
-      A checkout whose `.git` is a file (a linked worktree, or a repository
-      checked out as a submodule) is the exception: that file points to a git
-      directory outside the build context, so the build cannot read the version
-      and a plain `docker build .` fails; pass the version with
-      `--build-arg VERSION=...`, as `script/docker` and `script/cibuild` already
-      do.
+      (`**/.git/config`, `**/.git/modules/**/config`):
+        - the repository's own
+        - each submodule's under `.git/modules/`
+        - that of a submodule keeping its own `.git` directory
+
+        `git describe` does not need them, and each can hold a credential: a
+        password in a remote URL, or the token the CI checkout step stores
+        there. A submodule name may have a `config` segment, as in `config`,
+        `deploy/config` or `config/lib`. Such a submodule loses its whole git
+        directory to `**/.git/modules/**/config`, and Go's version stamping then
+        fails the build. Give it a name without that segment
+        (`git submodule add --name`). The stage that compiles has `git`: the
+        Debian Go image has it, and an alpine one needs
+        `apk add --no-cache git`. That stage takes the version from the
+        `VERSION` build argument when one is given, otherwise from
+        `git describe --tags --always`. That gives:
+        - the tag, on a tagged commit
+        - the tag, the number of commits since it and the short commit
+          (`v1.2.3-4-gabc1234`), on a later commit
+        - the short commit, when no tag is reachable
+
+        The stage that compiles also marks its working directory safe for git
+        (`git config --system --add safe.directory /src`). A context sent as a
+        tar stream keeps the sender's file owners, and git refuses a checkout
+        owned by another user, so the version would come out empty.
+        `ARG VERSION` has no default. The build fails if the context carries
+        `.git` and the version still comes out empty, `dev` or `unknown`. A
+        plain `docker build .` with no build arguments must succeed; a
+        Dockerfile that refuses an empty build argument drops that refusal and
+        keeps the argument. A checkout whose `.git` is a file is the exception:
+        a linked worktree, or a repository checked out as a submodule. That file
+        points to a git directory outside the build context, so the build cannot
+        read the version and a plain `docker build .` fails. Pass the version
+        with `--build-arg VERSION=...`, as `script/docker` and `script/cibuild`
+        already do.
+
    - The Dockerfile carries a `lint` phase and a `test` phase, each invoking
      its tool directly rather than through `make` or `script/`, and the final
      stage carries a `COPY --from=` of a harmless file from each so the image
@@ -129,8 +137,9 @@ Template files can be fetched from:
      (`--mount=type=cache,target=/root/.cache/go-build`), `golangci-lint run`
      also mounts golangci-lint's
      (`--mount=type=cache,target=/root/.cache/golangci-lint`), and no step
-      mounts anything else; both `go test` runs carry `-count=1`, as in the
-      canonical Go `Dockerfile` in `REPO_POLICIES.md`
+      mounts anything else; both `go test` runs carry `-count=1`; a first run
+      that timed out gets no rerun, as in the canonical Go `Dockerfile` in
+      `REPO_POLICIES.md`
    - Python: a `test` phase that installs its packages from `Pipfile.lock` does
      it above `ARG CACHEBUST`, with `COPY script/ script/`,
      `COPY Pipfile Pipfile.lock ./` and `RUN script/bootstrap`. When
@@ -146,6 +155,7 @@ Template files can be fetched from:
    - Server: the final stage builds and runs the application
    - Non-server: the final stage brings up the dev environment
    - Image pinned by sha256 hash with version/date comment
+
 - [ ] Gitea Actions workflow at `.gitea/workflows/check.yml` that runs
      `script/cibuild` on push, checks out with `persist-credentials: false` and
      with `fetch-depth: 0` (which fetches the tags `git describe` needs),
@@ -242,7 +252,11 @@ 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
+- [ ] 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. A package source
+      that a `Dockerfile` adds itself does not get this exception
 - [ ] No unnecessary files in repo root
 - [ ] All dates written as YYYY-MM-DD
Author	SHA1	Message	Date
sneak	36e6329602	Rewrite REPO_POLICIES.md sentence by sentence (closes #136 ) check / check (push) Canceled after 0s Details Every sentence of prompts/REPO_POLICIES.md is rewritten against the sentence rules: one idea per sentence, about 30 words at most, lists as bulleted lists, subject and verb early, the main rule before any exception. No rule's meaning changed: nothing is added, removed, loosened or tightened, every reason stays, and code blocks, digests, URLs, file names, commands and quoted strings are unchanged. Both repo checklists carry the same rewrite of the sentences they quote word for word. Model: fable-5-1	2026-11-04 01:18:41 +00:00
clawbot	8400e4cd1f	Update the canonical .golangci.yml for golangci-lint v2.15.0 (closes #142 ) check / check (push) Canceled after 0s Details Moves the pin to v2.15.0 and enables canonicalheader again, because that release fixes the random misses behind #105. The depguard exemption reached every directory below one ending in test, and a whole checkout under such a directory. It now covers only the files directly inside, and the directory a repository is cloned into does not count. gomodguard_v2 also blocks github.com/go-redis/redis/v9, whose pre-releases can still be imported. uniq-by-line is now false, so a line that trips two linters reports both findings. Three comments are corrected. A new comment says the file has no formatters section, so golangci-lint run does not run gofmt. Model: opus-5-5	2026-11-04 01:28:09 +01:00
clawbot	b656617183	Allow packages from the distribution's own package index unpinned (closes #72 ) check / check (push) Canceled after 0s Details A package from the distribution's own package index now needs no version and no hash, and pulling that index is allowed, on sneak's answer at #72 (comment). The distribution is the pinned base image's in a Dockerfile and the host's on a host. It is trusted, and everything else stays pinned by hash. A package source that a Dockerfile adds itself does not get the exception. The pinning rule of REPO_POLICIES.md and both checklists say so, and the canonical Go Dockerfile's apk add line has a comment saying why it is allowed. Model: opus-5-5	2026-11-04 00:28:23 +01:00
clawbot	229ea67434	Skip the verbose test rerun after a timeout (closes #61 ) check / check (push) Canceled after 0s Details A hung test used the 90-second backstop twice, because the verbose rerun waited for the same hang. The Go recipe now looks in the first run's output for the lines Go prints for a hang, and exits 1 with no rerun. A failure with neither line in its output still reruns with -v. The Python make test example takes the same timeout wrapper as its Dockerfile example. The 60 and 90 second rule and the 5-minute rule say a hung package uses the backstop once. The Go item in both repo checklists now asks for this. Model: opus-5-5	2026-11-03 23:08:23 +01:00