prompts/TODO.md

# Workflow

- branch (from `main`)
- do the work in Next Step
- move Next Step to the top of Completed Steps
- move the top item of Future Steps into Next Step
- commit (`TODO.md` changes in the same commit as the work)
- merge to `main` if the branch is not protected, otherwise open a PR
- push

# Status

pre-1.0

# Next Step

Finish the two draft prompt documents in the working tree and commit them:
prompts/FIXUP_CLEAN.md (currently a near-empty stub) and prompts/FIXUP_REPORT.md
(a rough draft). Write the missing content, run `make fmt` so they pass
fmt-check, and commit.

# Completed Steps

- 2026-10-06: The canonical `.gitea/workflows/check.yml` now sets
  `fetch-depth: 0` on its checkout step (issue 110), so CI fetches the history
  and tags that `git describe --tags --always` needs, and a tagged repository
  stamps the same version in CI as in a local build. `REPO_POLICIES.md` and both
  checklists name `fetch-depth: 0` among what the workflow does, next to
  `persist-credentials: false` and the `concurrency` block, instead of asking
  each tagged repository to add it. Not yet tried on the shared runner, which is
  out of disk space. Repositories pick this up on their next re-vendor.
- 2026-10-06: The canonical `script/bootstrap` now runs `apt-get update` once,
  before the first `apt-get install` of a run (issue 115). The Gitea runner
  image starts with empty package lists, so installing anything it lacks, such
  as Go, failed with `Unable to locate package`. A repository's own section no
  longer needs a refresh of its own; `sneak/bsfirehose` and `sneak/dnswatcher`
  drop theirs at their next re-vendor.
- 2026-10-06: `REPO_POLICIES.md` and both checklists now say that a checkout
  whose `.git` is a file, a linked worktree or a repository checked out as a
  submodule, is the exception to a plain `docker build .` succeeding (issue
  111): that file points to a git directory outside the build context, so the
  build cannot read the version and the version check in the canonical
  `Dockerfile` stops it. Such a build is given its version with
  `--build-arg VERSION=...`, as `script/docker` and `script/cibuild` already do.
  The check itself is unchanged.
- 2026-10-06: The canonical `.gitea/workflows/check.yml` now has a `concurrency`
  block, so a new push cancels the older run on the same branch and no other,
  and its checkout step sets `persist-credentials: false`, so the job's token is
  not left in `.git/config` (issue 107). `REPO_POLICIES.md` and both checklists
  describe the workflow as it now is. Not yet tried on the shared runner, which
  is out of disk space. Repositories pick this up on their next re-vendor.
- 2026-10-06: The canonical `.golangci.yml` now disables `canonicalheader`
  (issue 105). In golangci-lint v2.14.0 it misses findings at random in a
  package that also calls `ResponseWriter.Header()`, so the same tree can fail
  lint on one run and pass on the next. It comes back once a pinned
  golangci-lint release fixes it.
- 2026-10-06: The canonical `.gitignore` and `.editorconfig` now each end with a
  comment saying the repository's own entries go below it and a re-vendor keeps
  them (issue 103, which took in issue 104), as `.dockerignore`'s header already
  does. `.editorconfig` gains a `[*.go]` section with tabs, since `gofmt`
  decides Go indentation everywhere. `REPO_POLICIES.md` and both checklists say
  that each of these two files is the canonical content followed by the
  repository's own entries, which a re-vendor keeps, and the Go styleguide puts
  `*.log`, `*.out`, `*.test` and binaries among those entries. Common outputs
  stay out of the canonical `.gitignore`; each repository lists its own.
- 2026-10-05: `script/cibuild`, `script/docker`, `script/lint` and `script/test`
  now assign the image tag from `script/projectname` on its own line before the
  `docker build` (issue 101), so `set -e` stops the script where
  `script/projectname` fails instead of running `docker build` with a broken
  tag. The comment above it in each script says why, and the snippets in
  `REPO_POLICIES.md` show the same form. Repositories pick this up on their next
  re-vendor.
- 2026-10-04: Went through the fleet findings recorded on 2026-08-09 (issue 62)
  and added the two rules `REPO_POLICIES.md` did not yet state: a new or changed
  check is proven by planting a defect it must catch; and a change to a separate
  workflow limited to `main` is first run from the feature branch, added to that
  workflow's `branches` list and removed again before merging. The other
  findings were already stated, replaced by `--no-cache`, about git worktrees,
  or about how agents work together. The warning against
  `golangci-lint config verify` is dropped because sneak ruled on
  https://git.eeqj.de/sneak/prompts/issues/40 (2026-08-10) that there is no
  config check step and the config is assumed valid; a vendored `.golangci.yml`
  stays byte-identical to the canonical copy. The issue gives each reason.
- 2026-10-04: `REPO_POLICIES.md` now says which `Dockerfile` stages run
  `script/bootstrap` (issue 90). The gate phases and the build stage start from
  their pinned base images and install what those images lack either inline, as
  the canonical Go `Dockerfile` does for `git`, or by running
  `script/bootstrap`, as this repo's own `Dockerfile` does for its yarn
  packages. The development environment stage, the final stage of a non-server
  repo, runs `script/bootstrap`. The new repo checklist says the same.
- 2026-10-04: Added a root `.gitattributes` that merges `TODO.md` with git's
  union merge (issue 98), so two branches that each add an entry at the top of
  Completed Steps merge without a conflict. Git now never reports a conflict in
  `TODO.md`: a real conflict elsewhere keeps both versions of the line, and when
  two new entries share an identical line, one is inserted into the middle of
  the other, which a rebase can do to an entry already on `next`. Read the
  merged entries after every merge or rebase. This applies to this repository
  only; no canonical file changed.
- 2026-10-04: The canonical `.dockerignore` now also keeps out the git `config`
  of a submodule that keeps its own `.git` directory, which still reached the
  image (issue 88): both git patterns now carry the `**/` prefix. A submodule
  whose name has a `config` segment (`config`, `deploy/config`, `config/lib`)
  still loses its whole git directory, so Go's version stamping fails the build;
  the file records this as a `KNOWN GAP:` with the remedy,
  `git submodule add --name`. Closing it would take a wildcard re-include, which
  makes BuildKit walk every excluded directory, such as `node_modules`, on every
  build. `REPO_POLICIES.md` and both checklists say so in the same words.
- 2026-10-04: The note under the canonical Go `Dockerfile` example in
  `REPO_POLICIES.md` now installs lint-phase system libraries with `apt-get`
  under their Debian package names (issue 83). The `golangci/golangci-lint`
  image is Debian-based and has no `apk`, so the old `apk add` instruction
  failed as written. Nothing is pinned or unpinned; that is still open on
  issue 72.
- 2026-10-04: Fixed the server lifecycle example in
  `prompts/GO_HTTP_SERVER_CONVENTIONS.md` (issue 86). Only fx handles SIGINT and
  SIGTERM, and `Run()` in `main` exits with the shutdown's exit code. A listen
  error asks fx to shut down with exit code 1 through `fx.Shutdowner`; a Sentry
  start failure is returned from the server's start hook instead of calling
  `os.Exit` from a goroutine, so the stop hooks of what had started still run.
  The server's stop hook shuts the HTTP server down within 5 seconds and fails
  when requests are still running. A new paragraph says who owns signals and the
  exit code.
- 2026-10-04: `REPO_POLICIES.md` now says how a Go tool a repo needs on the host
  is pinned (issue 37): installed with `go install` pinned to a commit hash,
  never tracked as a `go.mod` tool dependency or through a `tools.go` file.
  golangci-lint is unaffected, since no repo installs it on the host.
- 2026-10-04: The canonical `.gitignore` and `.dockerignore` now also keep out
  `id_ecdsa_sk` and `id_ed25519_sk`, the private key files `ssh-keygen` writes
  for keys backed by a hardware security key (issue 81). Their `.pub` halves
  stay trackable.
- 2026-10-04: `package.json` now has `"license": "MIT"`, matching `LICENSE`, so
  yarn no longer prints "No license field" when `script/bootstrap` runs it
  inside the Docker phases (issue 76). That was the only yarn warning there.
- 2026-10-04: `REPO_POLICIES.md` now states that guidance for coding agents
  lives in one `AGENTS.md` at the repository root, never under a file or
  directory named after one agent tool and never in separate memory files (issue
  31). This retires the rule, still present in older vendored copies, that kept
  agent memory as committed files under `.claude/memory/`. `AGENTS.md` joins the
  list of files allowed in the root, and both checklists say so.
- 2026-10-04: Rewrote the note under the canonical Go `make test` example in
  `REPO_POLICIES.md` (issue 77), which still named the cache-busting build
  argument that `--no-cache` replaced. It now says where Go's test result cache
  can replay a pass: on a developer's machine, where the Makefile target runs,
  and not in the `test` phase of the `Dockerfile`, whose base image and earlier
  steps hold no result for the repo's tests.
- 2026-10-04: The Makefile examples in the Go styleguide and the HTTP server
  conventions now fall back to `dev` when `git describe` prints nothing (outside
  a git checkout, or where git is missing or refuses the checkout), instead of
  stamping an empty version (issue 74). The canonical `Dockerfile` already fails
  on a `dev` version when `.git` is in the build context.
- 2026-10-04: The canonical `.dockerignore` now also keeps out each submodule's
  `config` (issue 75). A submodule's git directory lives under `.git/modules/`,
  nested again for its own submodules, and its `config` can hold a credential
  just like `.git/config`. The pattern `.git/modules/**/config` covers every
  depth and leaves the top-level `.git` that `git describe` reads untouched.
  `REPO_POLICIES.md` and both checklists say so in the same words.
- 2026-10-03: Fixed two defects in the canonical Go `Dockerfile` example (issue
  73). The test phase now uses the Debian Go image, since `-race` needs cgo and
  the alpine image has no C compiler, so the phase failed before running a test.
  The stage that compiles runs `git config --system --add safe.directory /src`,
  because a context sent as a tar stream keeps the sender's file owners and git
  refuses that checkout, leaving the version empty. Both checklists state that
  step in the same words.
- 2026-10-03: Moved the canonical golangci-lint to v2.14.0, built with go1.27,
  because v2.12.2 refuses to lint a module whose `go` directive is 1.27 (issue
  65). Releases from v2.13.0 deprecate `exhaustruct` in favour of
  `exhaustruct_v5`, which `default: all` switches on, so the canonical
  `.golangci.yml` now disables `exhaustruct_v5` beside `exhaustruct`. v2.12.2
  rejects that file, so `REPO_POLICIES.md` and both repo checklists now say a
  repo sets the lint phase digest and re-vendors `.golangci.yml` in one commit.
- 2026-10-03: Brought the canonical `.gitignore` level with `.dockerignore` on
  secrets (issue 38): it now also ignores `prod.env`-style `*.env` files,
  `.envrc`, `*.p12`, `*.pfx` and the extensionless SSH private keys, written to
  `.gitignore`'s own rules (no `**/` prefix) and case-folded with character
  ranges. `example.env` and `sample.env` stay trackable through negations.
- 2026-10-02: The image version now comes from git inside the build (issues 69
  and 71), superseding the 2026-09-08 entry that excluded `.git`. The canonical
  `.dockerignore` sends `.git` but keeps out `.git/config`, which can hold a
  credential. The Dockerfile example in `REPO_POLICIES.md` installs `git`, takes
  the `VERSION` build argument when one is given and otherwise
  `git describe --tags --always`, and fails when `.git` exists but the version
  is empty, `dev` or `unknown`; a plain `docker build .` with no build arguments
  must succeed. This repo's `script/docker` and `script/cibuild` still pass
  `--build-arg VERSION`, since its own `Dockerfile` compiles nothing.
- 2026-09-08: Moved linting and testing into Docker as phases of the main
  `Dockerfile`, per the owner ruling on issue 40. `script/lint` and
  `script/test` build one phase each by name with `--no-cache` — the same answer
  issue 26 got, so no separate cache-busting mechanism survives — and the final
  stage copies a harmless file from both, so the image cannot be built unless
  they pass. This also closes issue 30: a container has its own result cache and
  its own lock, so a lint verdict can no longer belong to another checkout. No
  separate lint Dockerfile, and no `golangci-lint config verify` step.
  `script/check` runs the gates and nothing else, and `script/cibuild`
  bootstraps first, since it is all CI runs and `script/fmt-check` is native.
- 2026-09-08: Kept in-repo agent scratch out of the Docker build context and out
  of version control: `.claude/` is one full checkout of the repo per in-flight
  agent, and under `COPY . .` all of it was reaching the image. Also closed the
  consequence of excluding `.git` — `git describe` yields an empty version
  inside a build stage without failing, so `script/docker` and `script/cibuild`
  now compute the version on the host and pass `--build-arg VERSION`.
- 2026-09-08: Closed the secret exposure in the canonical `.dockerignore`: a
  local `.env`, `*.pem` or `*.key` was reaching the build context under
  `COPY . .`, invisible to every git-based check. The patterns are now written
  to `.dockerignore`'s own semantics — `**/`-prefixed so they hold at every
  depth, case-folded with character ranges — and `REPO_POLICIES.md` requires
  verifying by enumerating the image rather than by reading the file.
- 2026-09-08: Made a pinned tool in `script/bootstrap` actually reach the host.
  `REPO_POLICIES.md` now requires comparing the installed version against the
  pin rather than testing `PATH` presence, and re-resolving the binary through
  `PATH` after installing, so a version bump cannot be a silent no-op and a
  shadowed install cannot report success.
- 2026-09-08: Closed the false green in the canonical CI gate: `script/cibuild`
  and `script/docker` now build with `--no-cache`, so the Dockerfile's check
  layers cannot be served from cache on an unchanged tree, and the text claiming
  a bare `docker build .` proves the checks ran is corrected in
  `REPO_POLICIES.md`, both checklists and the Go styleguide.
- 2026-09-03: Added `-count=1` to both `go test` invocations in the canonical Go
  `make test` example in `REPO_POLICIES.md`, so the target cannot report a
  cached pass it did not earn, and documented that Go's test-result cache is a
  second, independent cache stacked below the Docker layer cache.
- 2026-08-31: Migrated the canonical `.golangci.yml` from the deprecated
  `gomodguard` to `gomodguard_v2`: the old linter is disabled by name (which is
  what silences the deprecation warning), the successor is named explicitly in
  `linters.enable`, and it carries a `blocked` module list drawn only from
  decisions already recorded in the Go package defaults.
- 2026-08-07: Set the canonical `.golangci.yml` to the org-standard v2-schema
  config already deployed byte-identical across the org's Go repos (settings
  under `linters.settings` so thresholds like lll/funlen/cyclop/dupl actually
  apply under golangci-lint v2). Recorded the canonical golangci-lint version
  (v2.12.2, commit-pinned) in REPO_POLICIES.md.
- 2026-03-20: Strengthened constructor naming and Params struct rules in the Go
  styleguide.
- 2026-03-18: Documented fail-fast Dockerfile lint stage and conditional -v test
  rerun patterns in REPO_POLICIES.md.
- 2026-03-11: Added HTTP service hardening policy for 1.0 releases.
- 2026-03-10: Added policy: no build artifacts in repos.
- 2026-03-04: Added LLM prose tells reference and copyediting checklist, then
  several self-applied revision passes.
- 2026-02-28: Expanded the pre-1.0 schema migration rule; added clawpub
  reference.
- 2026-02-23: Added Go style rules (no type-only packages, Stringer for
  string-based types); template repos section in README.
- 2026-02-22: Initial policy corpus: REPO_POLICIES.md, code styleguides
  (general, Go, JS, Python), repo checklists, CI policy, hash pinning, Go HTTP
  server conventions, repo scaffolding.

# Future Steps

- Finish, format, and commit FIXUP_CLEAN.md and FIXUP_REPORT.md (the Next Step).
- Commit this TODO.md at the repo root; it is the last missing policy file.
- Decide the fate of untracked resume.sh: commit it or delete it.
- Add more prompt templates for common development tasks (from README TODO).