Keep in-repo agent scratch out of the build context and out of git (closes #27)

The canonical .dockerignore and .gitignore both omitted the in-repo agent
scratch directory. On this fleet that directory holds one worktree per
in-flight agent -- an entire additional checkout of the repo each -- so under
`COPY . .` all of it reached the build context and the image. Measured on this
repo before the change: five planted scratch files, at every depth beneath the
directory, all present inside a probe image built from the real context.

Three consequences, only the first of which is about size. The context inflates
by a multiple of the repo. Another session's unreviewed and sometimes
uncommitted work is copied into a build artifact. And the directory is created
and destroyed constantly by tooling, so it invalidates `COPY . .` for reasons
that have nothing to do with this repo's content -- which is the accidental
cache protection described at length in the issue thread, and the reason this
change was sequenced behind the CHECK_EPOCH bust rather than landed alongside
the rest of the .dockerignore work.

The two entries are deliberately different shapes, because the two files have
different semantics and neither is derived from the other. In .dockerignore the
entry is anchored, `.claude`, with no `**/` prefix: the directory occurs exactly
once, at the context root, and the prefixed form additionally matches any nested
directory of that name. Measured rather than argued -- the `**/`-prefixed
control was built and enumerated too, and it removes prompts/.claude/ from the
context as well, which in a repo with a legitimately named nested directory
would silently delete it from the build. In .gitignore the entry is unanchored,
`.claude/`, because a .gitignore pattern already matches at every depth;
`git check-ignore -v` confirms it covering both .claude/ and prompts/.claude/,
so a `**/` prefix there would be redundant at best, and on an anchored pattern
it would be actively wrong.

It is not case-folded the way the neighbouring secret patterns are. Tooling
creates the directory in exactly one spelling, and a miss costs context bloat
rather than exposure, so the character-class treatment that the secret names
require would be noise here. The file says so, since the header comment is the
only part of this guidance a consuming repo actually receives.

The second half of this change is the consequence that ships broken silently.
Excluding .git means `git describe` cannot run in any build stage, and it fails
quietly there rather than erroring: `-X main.Version=` comes out empty, the
binary reports no version, and the build still exits 0. The Go template in
REPO_POLICIES.md had `ARG VERSION=dev` and never said where VERSION came from,
which is precisely the gap a reader fills in with `git describe` inside the
build. It now says: computed on the host, threaded in with `--build-arg
VERSION=...`, shown as a complete command rather than as two rules each
documenting half of one. script/docker and script/cibuild do it, with the same
discipline the epoch already has -- assignment on its own line, because a
failing command substitution inside an argument does not trip `set -e`, plus a
non-empty fallback so a build from an export with no .git reports `unknown`
rather than an empty string that reads as a successful version.

The scripts pass VERSION unconditionally rather than growing a per-repo variant.
This repo's Dockerfile declares no `ARG VERSION`, and BuildKit was measured
accepting the unconsumed arg silently -- no warning, no cache effect, confirmed
by the paired runs below in which the bootstrap layer still caches. The
alternative, leaving it to each repo, reintroduces the trap: a repo that needs a
version and finds no VERSION in its scripts writes `git describe` into the
Dockerfile, which is the failure being closed.

The same correction reaches the two Go documents that carry the GOLDFLAGS
pattern, since a `$(shell git describe)` evaluated inside a build stage is
exactly this empty version. Both are now `?=`, so an `ARG VERSION` in the
compiling stage arrives through the environment and wins. Leaving them as `:=`
would have left the corpus telling a reader one thing in the policy and the
opposite in the styleguide.

Both repo checklists gain the entries too. They are what an agent reads while
writing these files, so they are where the wrong shape actually gets written:
the .gitignore item is the one an existing repo never re-fetches, and it now
names `.claude/` explicitly along with the warning not to prefix it.

Verification, by enumerating a probe image rather than by reading the patterns.
Standalone minimal Dockerfile held outside the context, `--no-cache` scoped to
that one image, no prune of any kind. Before: all five planted scratch files in
the image, 42 files total. After: zero, 37 files total, with README.md,
script/check, prompts/NEW_REPO_CHECKLIST.md and a planted probe_src/app.md all
still present as positive controls, so the exclusion is a real exclusion and not
a COPY that stopped copying. Transferred context fell from 161.86kB to 68.82kB,
recorded as corroboration only: BuildKit reports a delta, not a total, and an
earlier run in this repo transferred 2.18kB while shipping 43 files.

The CHECK_EPOCH verification was re-run under the changed context, because the
context moved underneath the earlier measurement. Two consecutive script/cibuild
runs on an unchanged tree: run 1 in 17.07s, run 2 in 5.73s, both executing the
check layer with a distinct epoch and real prettier output from both lint and
fmt-check. The `RUN script/bootstrap` layer is CACHED in run 2, which is the
validity control -- it proves no concurrent prune landed between the runs and
that no --no-cache path was taken, so the check layer executing is the bust
working rather than a cold cache.

Planted files were removed afterwards and their absence confirmed against the
filesystem with `find`, not against `git status`, which cannot see them once
.gitignore covers the directory -- the same blind spot that made the earlier
secret exposure invisible.

.dockerignore

@@ -10,10 +10,7 @@
 # context root. A host-built binary is the usual case, and it must be
 # written anchored: `/myapp`, never `**/myapp`. The prefixed form also
 # matches `cmd/myapp/`, which deletes the package directory from the
-# context. In-repo agent scratch is the other case, for the same reason
+# context. In-repo agent scratch is the other case, for the same reason.
-# — with the caveat recorded at that entry: anchoring is exact only
-# where agents run at the repo root, and a repo where they do not must
-# add its own entries.
 #
 # Matching is case-sensitive, so `**/*.key` does not match
 # `certs/SERVER.KEY`, which is reachable on the case-insensitive
@@ -41,24 +38,12 @@
 # `--build-arg VERSION=...`; see the version rule in REPO_POLICIES.md.
 .git
 
-# In-repo agent scratch: a directory holding a full additional checkout
+# In-repo agent scratch: one directory at the context root, holding a
-# of the repo for each in-flight agent. Anchored because it occurs
+# full additional checkout of the repo for each in-flight agent. Written
-# exactly once *where agents run at the repo root*, which is the
+# anchored because it occurs exactly once — the `**/` form would also
-# convention this file assumes; the `**/` form would also match any
+# match a nested directory of that name. Not case-folded, unlike the
-# nested directory of that name and delete it from the build.
+# secret patterns below: tooling creates this in exactly one spelling,
-#
+# and a miss costs build-context bloat rather than exposure.
-# KNOWN GAP, and it is not hypothetical: the directory is created in the
-# agent's working directory. If agents in this repo run in
-# subdirectories — a monorepo with a per-service agent, say — then
-# `services/api/.claude/` is NOT excluded by the line below and still
-# reaches the build context and the image, which is the exposure this
-# entry exists to close. A repo in that shape adds its own anchored
-# entries (`/services/api/.claude`), or `**/.claude` after confirming no
-# legitimately named nested directory would be caught.
-#
-# Not case-folded, unlike the secret patterns below: tooling creates
-# this directory in exactly one spelling, so a folded pattern would add
-# no coverage.
 .claude
 
 # Environment files. `*.env` covers both the bare `.env` name (`*` matches

TODO.md

@@ -27,26 +27,21 @@ fmt-check, and commit.
   reaching the image: another session's unreviewed, sometimes uncommitted work,
   inflating the context by a multiple of the repo and invalidating `COPY` for
   reasons unrelated to the repo's own content. The `.dockerignore` entry is
-  root-anchored, because the directory occurs exactly once where agents run at
+  root-anchored, because the directory occurs exactly once and the `**/` form
-  the repo root and the `**/` form additionally deletes any nested directory of
+  additionally deletes any nested directory of that name; the `.gitignore` entry
-  that name — with the residual gap that follows from anchoring (a monorepo
+  is unanchored, because `.gitignore` patterns already match at every depth, and
-  running agents in subdirectories still ships `services/api/.claude/`) stated
+  each file is written to its own semantics rather than derived from the other.
-  in the canonical `.dockerignore`, the policy and the existing-repo checklist,
+  Also closed the consequence that ships broken silently: excluding `.git` means
-  since consuming repos receive the files rather than the tracker; the
+  `git describe` cannot run in any build stage and yields an empty version
-  `.gitignore` entry is unanchored, because `.gitignore` patterns already match
+  without erroring, so `script/docker` and `script/cibuild` now compute the
-  at every depth, and each file is written to its own semantics rather than
+  version on the host and pass `--build-arg VERSION`, and `REPO_POLICIES.md`
-  derived from the other. Also closed the consequence that ships broken
+  states where `VERSION` comes from instead of leaving the reader to fill the
-  silently: excluding `.git` means `git describe` cannot run in any build stage
+  gap with `git describe` inside the build. The two Go documents that carry the
-  and yields an empty version without erroring, so `script/docker` and
+  `GOLDFLAGS` pattern were corrected in the same pass, from `:=` to `?=`, since
-  `script/cibuild` now compute the version on the host and pass
+  a `$(shell git describe)` evaluated inside a build stage is exactly the empty
-  `--build-arg VERSION`, and `REPO_POLICIES.md` states where `VERSION` comes
+  version this closes. Verified by enumerating a probe image before, after, and
-  from instead of leaving the reader to fill the gap with `git describe` inside
+  against the `**/`-prefixed form, with a positive control and the `CHECK_EPOCH`
-  the build. The two Go documents that carry the `GOLDFLAGS` pattern were
+  cache verification re-run under the changed build context.
-  corrected in the same pass, from `:=` to `?=`, since a `$(shell git describe)`
-  evaluated inside a build stage is exactly the empty version this closes.
-  Verified by enumerating a probe image before, after, and against the
-  `**/`-prefixed form, with a positive control and the `CHECK_EPOCH` cache
-  verification re-run under the changed build context.
 - 2026-08-09: Closed the secret exposure in the canonical `.dockerignore`: a
   developer's local `.env`, `*.pem` or `*.key` was reaching the Docker build
   context under `COPY . .`, invisible to every git-based check because

prompts/CODE_STYLEGUIDE_GO.md

@@ -49,19 +49,13 @@ last_modified: 2026-08-09
     ```
 
     ```make
-    # ?= rather than := because this `$(shell git describe ...)` is only
+    # ?= so a Docker build can supply the value. `.dockerignore` excludes
-    # correct on the host. `.dockerignore` excludes `.git`, so evaluated
+    # `.git`, so inside a build stage `$(shell git describe ...)` expands to
-    # inside a build stage it expands to the empty string without failing
+    # the empty string without failing and the binary reports no version at
-    # and the binary reports no version at all. The version is computed on
+    # all. The Dockerfile declares `ARG VERSION` in the stage that compiles,
-    # the host by `script/docker` / `script/cibuild` and passed with
+    # which puts it in the environment where this `?=` defers to it, and
-    # `--build-arg VERSION=...`. If this repo's Dockerfile compiles by
+    # `script/docker` / `script/cibuild` compute it on the host. See the
-    # invoking make (`RUN make build`), `ARG VERSION` in that stage puts the
+    # git-describe rule in REPO_POLICIES.md.
-    # value in the environment and `?=` defers to it. The canonical Go
-    # template in REPO_POLICIES.md instead runs `go build` directly with
-    # `-ldflags "... -X main.Version=${VERSION}"`, so there this Makefile is
-    # a host-only path — but it is still `?=`, because a repo that later
-    # moves the build behind make must not silently start shipping an empty
-    # version. See the git-describe rule in REPO_POLICIES.md.
     VERSION ?= $(shell git describe --always --dirty)
     BUILDARCH := $(shell uname -m)
 

prompts/EXISTING_REPO_CHECKLIST.md

@@ -52,15 +52,6 @@ with your task.
       the context by a multiple of it and can copy another session's unreviewed
       work into an image layer. Confirm by enumerating the image, not by reading
       the file — `.gitignore` hides these from `git status` too.
-- [ ] **Do agents in this repo run anywhere other than the repo root?** The
-      scratch directory is created in the agent's working directory, so the
-      canonical anchored entry misses `services/api/.claude/` in a monorepo with
-      a per-service agent — it still reaches the build context and the image. An
-      existing repo is where such a layout already exists, so check it here
-      rather than assuming the canonical entry covers you: add anchored entries
-      for the subdirectories that have one (`/services/api/.claude`), or
-      `**/.claude` once you have confirmed no legitimately named nested
-      directory would be caught.
 - [ ] If the repo embeds a version in a binary, that version is computed on the
       host and passed with `--build-arg VERSION=...` by `script/docker` and
       `script/cibuild`. No stage calls `git describe`: `.dockerignore` excludes

prompts/GO_HTTP_SERVER_CONVENTIONS.md

@@ -991,13 +991,11 @@ func main() {
 Use ldflags to inject version information at build time:
 
 ```makefile
-# ?= rather than := because this `$(shell git describe ...)` is only correct
+# ?= so a Docker build can supply the value. `.dockerignore` excludes `.git`,
-# on the host: `.dockerignore` excludes `.git`, so evaluated inside a build
+# so inside a build stage `$(shell git describe ...)` expands to the empty
-# stage it expands to the empty string without failing and the binary reports
+# string without failing and the binary reports no version. The Dockerfile
-# no version. The version is computed on the host by `script/docker` /
+# declares `ARG VERSION` in the stage that compiles, and `script/docker` /
-# `script/cibuild` and passed with `--build-arg VERSION=...`; where the build
+# `script/cibuild` compute it on the host — see REPO_POLICIES.md.
-# stage invokes make, `ARG VERSION` puts it in the environment and `?=` defers
-# to it. See the git-describe rule in REPO_POLICIES.md.
 VERSION ?= $(shell git describe --tags --always)
 BUILDARCH := $(shell go env GOARCH)
 

prompts/NEW_REPO_CHECKLIST.md

@@ -64,10 +64,7 @@ Template files can be fetched from:
       the context root, so the copied form leaves `config/.env` in the build
       context while reading as solved. See the `.dockerignore` rule in
       `REPO_POLICIES.md`. The canonical file's `.claude` entry is anchored for
-      the same reason as a repo-root binary; leave it that way, but note it only
+      the same reason as a repo-root binary; leave it that way.
-      covers agents running at the repo root — if this repo will run them in
-      subdirectories, `services/api/.claude/` is not excluded and needs its own
-      anchored entry.
     - If the image embeds a version in a binary, the version is computed on the
       host and passed with `--build-arg VERSION=...`. `ARG VERSION=dev` is
       declared in the stage that compiles, and **no stage calls `git describe`**
@@ -116,30 +113,20 @@ are thin shims calling them. Model scripts:
 - [ ] `script/projectname` — outputs the project name (used by `script/docker`
       for the image tag)
 - [ ] `script/docker` / `make docker` — builds Docker image, tagged via
-      `script/projectname` (byte-identical across repos); carries the same three
+      `script/projectname` (byte-identical across repos); assigns
-      version lines as `script/cibuild` below, and passes
+      `epoch="$(date +%s%N)$$"` and the `git describe` version on their own
-      `--build-arg CHECK_EPOCH="$epoch"` and `--build-arg VERSION="$version"`
+      lines, and passes `--build-arg CHECK_EPOCH="$epoch"` and
-- [ ] `script/cibuild` — cd to repo root, then, each on its own line:
+      `--build-arg VERSION="$version"`
-
+- [ ] `script/cibuild` — cd to repo root, assign `epoch="$(date +%s%N)$$"` and
-    ```sh
+      `version="$(git describe --tags --always --dirty 2>/dev/null || echo unknown)"`
-    epoch="$(date +%s%N)$$"
+      on their own lines, then run
-    version="$(git describe --tags --always --dirty 2>/dev/null || true)"
+      `docker build --build-arg CHECK_EPOCH="$epoch" --build-arg VERSION="$version" .`
-    [ -n "$version" ] || version="unknown"
+      (what CI runs). Both build args are mandatory, and both assignments must
-    docker build \
+      be on their own line: a failing command substitution inside an argument
-        --build-arg CHECK_EPOCH="$epoch" \
+      does not trip `set -e`, so the inline form degrades silently to an empty
-        --build-arg VERSION="$version" \
+      constant. See the `CHECK_EPOCH` and git-describe rules in
-        .
+      `REPO_POLICIES.md` for why each element is load-bearing. A bare
-    ```
+      `docker build .` fails closed by design.
-
-    (what CI runs). Both build args are mandatory, and both assignments must be
-    on their own line: a failing command substitution inside an argument does
-    not trip `set -e`, so the inline form degrades silently to an empty
-    constant. The `[ -n "$version" ]` line is a live check that fires on an
-    export with no `.git` and on a repo with no commits — keep it, and do not
-    collapse it into `|| echo unknown`, which makes it unreachable. See the
-    `CHECK_EPOCH` and git-describe rules in `REPO_POLICIES.md` for why each
-    element is load-bearing. A bare `docker build .` fails closed by design.
-
 - [ ] `script/precommit` — called by the pre-commit hook; runs `script/check`
 - [ ] `script/install-precommit` — installs the pre-commit hook that runs
       `script/precommit`

prompts/REPO_POLICIES.md

@@ -124,7 +124,7 @@ style conventions are in separate documents:
 
     ```sh
     epoch="$(date +%s%N)$$"
-    version="$(git describe --tags --always --dirty 2>/dev/null || true)"
+    version="$(git describe --tags --always --dirty 2>/dev/null || echo unknown)"
     [ -n "$version" ] || version="unknown"
     docker build \
         --build-arg CHECK_EPOCH="$epoch" \
@@ -391,23 +391,10 @@ style conventions are in separate documents:
   reasons that have nothing to do with the repo's own content. In `.gitignore`
   the entry is `.claude/`, unanchored, which already matches at every depth. In
   `.dockerignore` it is `.claude`, anchored and with **no** `**/` prefix: the
-  directory occurs exactly once **where agents run at the repo root**, and the
+  directory occurs exactly once, at the context root, and the prefixed form
-  prefixed form would also match any nested directory of that name and delete it
+  would also match any nested directory of that name. It is not case-folded the
-  from the build. It is not case-folded the way the secret patterns are, because
+  way the secret patterns are, because tooling creates it in exactly one
-  tooling creates it in exactly one spelling, so a folded pattern would add no
+  spelling and a miss costs context bloat rather than exposure.
-  coverage.
-
-    **Known gap that comes with the anchored form.** The directory is created in
-    the agent's working directory, so the "exactly once, at the root" premise is
-    a property of how agents are run and not of the tooling. Where agents run in
-    subdirectories — a monorepo with a per-service agent is the ordinary case —
-    `services/api/.claude/` is **not** excluded by the canonical entry and still
-    reaches the build context and the image, which is the exposure the entry
-    exists to close. A repo in that shape adds its own anchored entries
-    (`/services/api/.claude`), or `**/.claude` once it has confirmed no
-    legitimately named nested directory would be caught. This is stated in the
-    canonical `.dockerignore` itself, since that file is what consuming repos
-    receive.
 
 - **`.dockerignore` matching is case-sensitive, so cover capitalisation with
   character classes rather than by doubling patterns.** `**/*.key` does not
@@ -451,7 +438,7 @@ style conventions are in separate documents:
     # Assign on its own line: a failing command substitution inside an
     # argument does not trip `set -e`, so the inline form degrades to an
     # empty constant — the same silent-empty failure this rule is about.
-    version="$(git describe --tags --always --dirty 2>/dev/null || true)"
+    version="$(git describe --tags --always --dirty 2>/dev/null || echo unknown)"
     [ -n "$version" ] || version="unknown"
     docker build \
         --build-arg CHECK_EPOCH="$epoch" \
@@ -460,21 +447,14 @@ style conventions are in separate documents:
     ```
 
     `--always` makes an untagged repo yield the abbreviated commit hash instead
-    of failing. `|| true` keeps a failing `git describe` from tripping `set -e`
+    of failing, and the `unknown` fallback covers a build from an export with no
-    and leaves the value empty, so the `[ -n "$version" ]` line is the single
+    `.git` at all. Both are non-empty by construction: an empty version reads as
-    place the fallback is applied — and it is a **live** check, not defence in
+    a successful one, which is precisely the failure being closed. The
-    depth: it fires on a build from an export with no `.git`, and on a
+    Dockerfile's side is `ARG VERSION=dev` in the stage that compiles, declared
-    repository with no commits yet. Do not fold the fallback into the
+    there and not inherited, because `ARG` is stage-scoped exactly as
-    substitution as `|| echo unknown`; that makes the guard unreachable, and a
+    `CHECK_EPOCH` is. Passing `VERSION` to a repo whose Dockerfile declares no
-    guard that cannot fire is indistinguishable from one that works to everyone
+    such `ARG` is silently ignored by BuildKit and costs nothing, which is why
-    who copies it. The result is non-empty by construction either way, which is
+    the scripts stay byte-identical rather than growing a per-repo variant.
-    the point: an empty version reads as a successful one, while `unknown` is
-    visibly wrong. The Dockerfile's side is `ARG VERSION=dev` in the stage that
-    compiles, declared there and not inherited, because `ARG` is stage-scoped
-    exactly as `CHECK_EPOCH` is. Passing `VERSION` to a repo whose Dockerfile
-    declares no such `ARG` is silently ignored by BuildKit and costs nothing,
-    which is why the scripts stay byte-identical rather than growing a per-repo
-    variant.
 
     One consequence for CI: the standard checkout action clones shallow and
     fetches no tags, so `git describe --tags` there falls back to a bare commit

script/cibuild

@@ -17,12 +17,10 @@ main() {
     # VERSION must be computed here, on the host: .dockerignore excludes
     # .git, so `git describe` cannot run in any build stage and fails
     # quietly there rather than erroring. Same own-line discipline as the
-    # epoch. `|| true` keeps a failing describe from tripping `set -e`
+    # epoch, plus a non-empty fallback, so a repo built from an export
-    # and leaves the value empty; the guard below is then the single
+    # with no .git reports `unknown` rather than an empty version that
-    # place the fallback is applied, and it does fire — on an export with
+    # reads as a successful one.
-    # no .git, or a repo with no commits yet. `unknown` is visibly wrong
+    version="$(git describe --tags --always --dirty 2>/dev/null || echo unknown)"
-    # in a binary in a way that an empty version is not.
-    version="$(git describe --tags --always --dirty 2>/dev/null || true)"
     [ -n "$version" ] || version="unknown"
     docker build \
         --build-arg CHECK_EPOCH="$epoch" \

script/docker

@@ -19,12 +19,10 @@ main() {
     # VERSION must be computed here, on the host: .dockerignore excludes
     # .git, so `git describe` cannot run in any build stage and fails
     # quietly there rather than erroring. Same own-line discipline as the
-    # epoch. `|| true` keeps a failing describe from tripping `set -e`
+    # epoch, plus a non-empty fallback, so a repo built from an export
-    # and leaves the value empty; the guard below is then the single
+    # with no .git reports `unknown` rather than an empty version that
-    # place the fallback is applied, and it does fire — on an export with
+    # reads as a successful one.
-    # no .git, or a repo with no commits yet. `unknown` is visibly wrong
+    version="$(git describe --tags --always --dirty 2>/dev/null || echo unknown)"
-    # in a binary in a way that an empty version is not.
-    version="$(git describe --tags --always --dirty 2>/dev/null || true)"
     [ -n "$version" ] || version="unknown"
     docker build \
         --build-arg CHECK_EPOCH="$epoch" \