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-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 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).