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.

Anchoring buys that at the cost of a residual exposure, and the vendored files
now say so rather than only asserting the reason to anchor. "Occurs exactly
once, at the context root" is a property of how agents are run, not of the
tooling: the directory is created in the agent's working directory, so a
monorepo running a per-service agent in services/api/ still ships
services/api/.claude/ into the context and the image -- the exact exposure this
change exists to close, left open in the repo shape where it is likeliest. The
.dockerignore header block, the REPO_POLICIES.md bullet and both checklists
state the gap and the remedy (anchored entries for the subdirectories that have
one, or `**/.claude` once no legitimately named nested directory would be
caught). Consuming repos receive the files and not the tracker, so a caveat that
lives only in a PR body is not a caveat.

It is not case-folded the way the neighbouring secret patterns are: tooling
creates the directory in exactly one spelling, so a folded pattern would add no
coverage. The earlier justification -- that a miss costs bloat rather than
exposure -- is gone, because it contradicted this issue's own framing, in which
the cost of a miss is unreviewed work in an image layer.

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.

That fallback is applied in exactly one place, and that place can actually
execute. `git describe ... || true` leaves the value empty when it fails, and
the `[ -n "$version" ]` line is what substitutes `unknown`. Folding the fallback
into the substitution as `|| echo unknown` would have left the guard unreachable
-- harmless in itself, but a guard that cannot fire is indistinguishable from
one that works to every repo that copies it, and canonical text should not carry
a check that is decorative. Measured firing in both sh and dash: not a git
repository -> unknown, repository with no commits yet -> unknown, this
repository -> the describe output. The checklist now carries the guard line as
well, so the vendored guidance and the vendored script no longer disagree.

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 `?=`, and their comments say precisely
when that matters: where a build stage compiles by invoking make, `ARG VERSION`
puts the value in the environment and `?=` defers to it, whereas the canonical
Go template compiles with `go build` directly and uses the Makefile on the host
only -- still `?=`, so that a repo which later moves its build behind make does
not silently start shipping an empty version. 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,7 +10,10 @@
 # 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
@@ -38,12 +41,24 @@
 # `--build-arg VERSION=...`; see the version rule in REPO_POLICIES.md.
 .git
 
-# In-repo agent scratch: one directory at the context root, holding a
-# full additional checkout of the repo for each in-flight agent. Written
-# anchored because it occurs exactly once — the `**/` form would also
-# match a nested directory of that name. Not case-folded, unlike the
-# secret patterns below: tooling creates this in exactly one spelling,
-# and a miss costs build-context bloat rather than exposure.
+# In-repo agent scratch: a directory holding a full additional checkout
+# of the repo for each in-flight agent. Anchored because it occurs
+# exactly once *where agents run at the repo root*, which is the
+# convention this file assumes; the `**/` form would also match any
+# nested directory of that name and delete it from the build.
+#
+# 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,21 +27,26 @@ 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 and the `**/` form
-  additionally deletes any nested directory of that name; the `.gitignore` entry
-  is unanchored, because `.gitignore` patterns already match at every depth, and
-  each file is written to its own semantics rather than derived from the other.
-  Also closed the consequence that ships broken silently: excluding `.git` means
-  `git describe` cannot run in any build stage and yields an empty version
-  without erroring, so `script/docker` and `script/cibuild` now compute the
-  version on the host and pass `--build-arg VERSION`, and `REPO_POLICIES.md`
-  states where `VERSION` comes from instead of leaving the reader to fill the
-  gap with `git describe` inside the build. The two Go documents that carry the
-  `GOLDFLAGS` pattern were 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.
+  root-anchored, because the directory occurs exactly once where agents run at
+  the repo root and the `**/` form additionally deletes any nested directory of
+  that name — with the residual gap that follows from anchoring (a monorepo
+  running agents in subdirectories still ships `services/api/.claude/`) stated
+  in the canonical `.dockerignore`, the policy and the existing-repo checklist,
+  since consuming repos receive the files rather than the tracker; the
+  `.gitignore` entry is unanchored, because `.gitignore` patterns already match
+  at every depth, and each file is written to its own semantics rather than
+  derived from the other. Also closed the consequence that ships broken
+  silently: excluding `.git` means `git describe` cannot run in any build stage
+  and yields an empty version without erroring, so `script/docker` and
+  `script/cibuild` now compute the version on the host and pass
+  `--build-arg VERSION`, and `REPO_POLICIES.md` states where `VERSION` comes
+  from instead of leaving the reader to fill the gap with `git describe` inside
+  the build. The two Go documents that carry the `GOLDFLAGS` pattern were
+  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,13 +49,19 @@ last_modified: 2026-08-09
     ```
 
     ```make
-    # ?= so a Docker build can supply the value. `.dockerignore` excludes
-    # `.git`, so inside a build stage `$(shell git describe ...)` expands to
-    # the empty string without failing and the binary reports no version at
-    # all. The Dockerfile declares `ARG VERSION` in the stage that compiles,
-    # which puts it in the environment where this `?=` defers to it, and
-    # `script/docker` / `script/cibuild` compute it on the host. See the
-    # git-describe rule in REPO_POLICIES.md.
+    # ?= rather than := because this `$(shell git describe ...)` is only
+    # correct on the host. `.dockerignore` excludes `.git`, so evaluated
+    # inside a build stage it expands to the empty string without failing
+    # and the binary reports no version at all. The version is computed on
+    # the host by `script/docker` / `script/cibuild` and passed with
+    # `--build-arg VERSION=...`. If this repo's Dockerfile compiles by
+    # invoking make (`RUN make build`), `ARG VERSION` in that stage puts the
+    # 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,6 +52,15 @@ 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,11 +991,13 @@ func main() {
 Use ldflags to inject version information at build time:
 
 ```makefile
-# ?= so a Docker build can supply the value. `.dockerignore` excludes `.git`,
-# so inside a build stage `$(shell git describe ...)` expands to the empty
-# string without failing and the binary reports no version. The Dockerfile
-# declares `ARG VERSION` in the stage that compiles, and `script/docker` /
-# `script/cibuild` compute it on the host — see REPO_POLICIES.md.
+# ?= rather than := because this `$(shell git describe ...)` is only correct
+# on the host: `.dockerignore` excludes `.git`, so evaluated inside a build
+# stage it expands to the empty string without failing and the binary reports
+# no version. The version is computed on the host by `script/docker` /
+# `script/cibuild` and passed with `--build-arg VERSION=...`; where the build
+# 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,7 +64,10 @@ 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.
+      the same reason as a repo-root binary; leave it that way, but note it only
+      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`**
@@ -113,20 +116,30 @@ 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); assigns
-      `epoch="$(date +%s%N)$$"` and the `git describe` version on their own
-      lines, and passes `--build-arg CHECK_EPOCH="$epoch"` and
-      `--build-arg VERSION="$version"`
-- [ ] `script/cibuild` — cd to repo root, assign `epoch="$(date +%s%N)$$"` and
-      `version="$(git describe --tags --always --dirty 2>/dev/null || echo unknown)"`
-      on their own lines, then run
-      `docker build --build-arg CHECK_EPOCH="$epoch" --build-arg VERSION="$version" .`
-      (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. 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/projectname` (byte-identical across repos); carries the same three
+      version lines as `script/cibuild` below, and passes
+      `--build-arg CHECK_EPOCH="$epoch"` and `--build-arg VERSION="$version"`
+- [ ] `script/cibuild` — cd to repo root, then, each on its own line:
+
+    ```sh
+    epoch="$(date +%s%N)$$"
+    version="$(git describe --tags --always --dirty 2>/dev/null || true)"
+    [ -n "$version" ] || version="unknown"
+    docker build \
+        --build-arg CHECK_EPOCH="$epoch" \
+        --build-arg VERSION="$version" \
+        .
+    ```
+
+    (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 || echo unknown)"
+    version="$(git describe --tags --always --dirty 2>/dev/null || true)"
     [ -n "$version" ] || version="unknown"
     docker build \
         --build-arg CHECK_EPOCH="$epoch" \
@@ -391,10 +391,23 @@ 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, at the context root, and the prefixed form
-  would also match any nested directory of that name. It is not case-folded the
-  way the secret patterns are, because tooling creates it in exactly one
-  spelling and a miss costs context bloat rather than exposure.
+  directory occurs exactly once **where agents run at the repo root**, and the
+  prefixed form would also match any nested directory of that name and delete it
+  from the build. It is not case-folded the way the secret patterns are, because
+  tooling creates it in exactly one spelling, so a folded pattern would add no
+  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
@@ -438,7 +451,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 || echo unknown)"
+    version="$(git describe --tags --always --dirty 2>/dev/null || true)"
     [ -n "$version" ] || version="unknown"
     docker build \
         --build-arg CHECK_EPOCH="$epoch" \
@@ -447,14 +460,21 @@ style conventions are in separate documents:
     ```
 
     `--always` makes an untagged repo yield the abbreviated commit hash instead
-    of failing, and the `unknown` fallback covers a build from an export with no
-    `.git` at all. Both are non-empty by construction: an empty version reads as
-    a successful one, which is precisely the failure being closed. 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.
+    of failing. `|| true` keeps a failing `git describe` from tripping `set -e`
+    and leaves the value empty, so the `[ -n "$version" ]` line is the single
+    place the fallback is applied — and it is a **live** check, not defence in
+    depth: it fires on a build from an export with no `.git`, and on a
+    repository with no commits yet. Do not fold the fallback into the
+    substitution as `|| echo unknown`; that makes the guard unreachable, and a
+    guard that cannot fire is indistinguishable from one that works to everyone
+    who copies it. The result is non-empty by construction either way, which is
+    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,10 +17,12 @@ 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, plus a non-empty fallback, so a repo built from an export
-    # with no .git reports `unknown` rather than an empty version that
-    # reads as a successful one.
-    version="$(git describe --tags --always --dirty 2>/dev/null || echo unknown)"
+    # epoch. `|| true` keeps a failing describe from tripping `set -e`
+    # and leaves the value empty; the guard below is then the single
+    # place the fallback is applied, and it does fire — on an export with
+    # no .git, or a repo with no commits yet. `unknown` is visibly wrong
+    # 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,10 +19,12 @@ 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, plus a non-empty fallback, so a repo built from an export
-    # with no .git reports `unknown` rather than an empty version that
-    # reads as a successful one.
-    version="$(git describe --tags --always --dirty 2>/dev/null || echo unknown)"
+    # epoch. `|| true` keeps a failing describe from tripping `set -e`
+    # and leaves the value empty; the guard below is then the single
+    # place the fallback is applied, and it does fire — on an export with
+    # no .git, or a repo with no commits yet. `unknown` is visibly wrong
+    # 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" \