From 7ecce3024f16f4913b9f721b09f16850bf6d6c2d Mon Sep 17 00:00:00 2001 From: Jan Rose Date: Wed, 9 Sep 2026 11:01:16 +0000 Subject: [PATCH 1/2] docs: tell agents how to unblock golangci-lint cross-worktree cache contamination golangci-lint's results cache is machine-global and shared across worktrees. It keys entries on file contents but stores each issue's absolute path, so a worktree with byte-identical packages (usually the near-static tools/ module) gets a cross-worktree cache hit and inherits another worktree's paths. When that worktree was deleted, the //nolint post-processor can't reopen the paths to apply suppressions, so suppressed issues leak through as phantom lint failures pointing at a gone path. This is a rare, known upstream trade-off (golangci/golangci-lint#6656, won't-fix). Rather than working around it in the Taskfile, document the symptom and the one-line fix (`golangci-lint cache clean`) in AGENTS.md so an agent that hits it recognizes it immediately instead of investigating the phantom issues as a real problem. Co-authored-by: Isaac --- AGENTS.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 75db4c91935..f736a3af4ea 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -93,6 +93,12 @@ GIT_EDITOR=true GIT_SEQUENCE_EDITOR=true VISUAL=true GIT_PAGER=cat git rebase or - Use `./task test-update` to regenerate acceptance test outputs after changes. - The CLI binary supports both `databricks` and `pipelines` command modes based on executable name. +**If `task lint` reports issues in files from a *different* worktree — paths under another `*.worktrees/*` directory, often one that no longer exists, typically alongside `no such file or directory` warnings — it is stale-cache contamination, not a real problem with your code. Clear the cache and re-run; do not investigate the reported issues.** golangci-lint's results cache is machine-global (`~/.cache/golangci-lint` on Linux, `~/Library/Caches/golangci-lint` on macOS) and shared across every worktree. It keys entries on file *contents* but stores each cached issue's *absolute* path, so a worktree whose packages are byte-identical to another's (usually the near-static `tools/` module) gets a cross-worktree cache hit and inherits the other worktree's paths. When that worktree was deleted, the `//nolint` post-processor can't reopen those paths to apply suppressions, so suppressed issues (e.g. `dupword`) leak through as phantom failures. This is [golangci/golangci-lint#6656](https://github.com/golangci/golangci-lint/issues/6656), closed as an accepted trade-off (won't-fix) of the shared-cache work in #6445. To unblock yourself: + +```sh +go tool -modfile=tools/go.mod golangci-lint cache clean +``` + # Common Mistakes **RULE: When adding a direct Go dependency, annotate its license in `go.mod` and update `NOTICE`.** Before picking the SPDX identifier, read `internal/build/license_test.go` to see the current allowlist (the `spdxLicenses` map). That test is the source of truth and will fail CI if a direct `require` line lacks a matching SPDX suffix comment (e.g. `// MIT`). Also add a corresponding entry to `NOTICE` under the matching license section. If a dep's license isn't on the allowlist, discuss before adding. From 643e121c72befe92a1fcc420c5e3e20fcf7e8f9c Mon Sep 17 00:00:00 2001 From: Jan Rose Date: Wed, 9 Sep 2026 11:48:20 +0000 Subject: [PATCH 2/2] docs: slim the lint-cache note to trigger + fix only AGENTS.md is always in context, so drop the background (cause, upstream issue link) and keep just what an agent needs: what surfaces the phantom failures and the one-line command to clear the cache. Co-authored-by: Isaac --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index f736a3af4ea..f22479a7bf3 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -93,7 +93,7 @@ GIT_EDITOR=true GIT_SEQUENCE_EDITOR=true VISUAL=true GIT_PAGER=cat git rebase or - Use `./task test-update` to regenerate acceptance test outputs after changes. - The CLI binary supports both `databricks` and `pipelines` command modes based on executable name. -**If `task lint` reports issues in files from a *different* worktree — paths under another `*.worktrees/*` directory, often one that no longer exists, typically alongside `no such file or directory` warnings — it is stale-cache contamination, not a real problem with your code. Clear the cache and re-run; do not investigate the reported issues.** golangci-lint's results cache is machine-global (`~/.cache/golangci-lint` on Linux, `~/Library/Caches/golangci-lint` on macOS) and shared across every worktree. It keys entries on file *contents* but stores each cached issue's *absolute* path, so a worktree whose packages are byte-identical to another's (usually the near-static `tools/` module) gets a cross-worktree cache hit and inherits the other worktree's paths. When that worktree was deleted, the `//nolint` post-processor can't reopen those paths to apply suppressions, so suppressed issues (e.g. `dupword`) leak through as phantom failures. This is [golangci/golangci-lint#6656](https://github.com/golangci/golangci-lint/issues/6656), closed as an accepted trade-off (won't-fix) of the shared-cache work in #6445. To unblock yourself: +**Stale golangci-lint cache across worktrees.** Triggered by `task lint` or a direct `go tool ... golangci-lint` run reporting issues in files under a *different* or deleted worktree, often with `no such file or directory` warnings. Fix — clear the cache and re-run, don't investigate the reported issues: ```sh go tool -modfile=tools/go.mod golangci-lint cache clean