* ci(lint,scripts): fold duplicate Lint job; matrix PR Lint and scripts-go-checks (F5) Lint (golangci-lint-action, only-new-issues) was functionally identical to pr-lint-wrapper's native leg (H7): same pinned binary, config, flags, and diff scope. Fold it into the wrapper in both pr.yml and main.yml, and drop LINT from pr.yml's ci-gate. pr-lint-wrapper becomes a 3-leg matrix (native/windows/darwin, fail-fast: false) under the same PR_LINT_WRAPPER gate id, installing golangci-lint v2.10.1 from a pinned, sha256-verified release binary (scripts/ci/install-golangci-lint.sh) instead of go install/the Action, with a per-leg golangci-lint cache (pr.yml restores only; main.yml's matrix is the sole saver). scripts-go-checks becomes a 3-leg matrix (scripts-test/vet/allowlisted, fail-fast: false) under the same SCRIPTS_GO_CHECKS gate id, giving go vet its own build cache instead of sharing the race build cache. main.yml gains a go-vet-cache job to warm that cache on push; build-artifacts remains the Go module cache's sole saver. Splitting each job's previously-sequential passes into parallel matrix legs, combined with removing the duplicate Lint job outright, takes wall-clock time off the PR gate's critical path. Updates scripts/ci_workflow_test.go and scripts/pr_lanes_bazel_coverage_test.go for the new matrices, cache topology, and the removed LINT id; adds TestGolangciLintInstallScriptPinned. Updates engdocs/LINTING.md and the live prose in engdocs/CI_REQUIRED_CHECK_TOPOLOGY.md (its disclaimed "historical snapshot" gate-wiring block is left as-is). Verified: go test ./scripts/..., bazel --nohome_rc test //scripts:scripts_test (after adding engdocs/LINTING.md and .githooks/pre-commit as scripts_test data), actionlint, shellcheck, make ci-pr-policy, make bazel-sync-check. Confirmed lint-leg parity against current main with the pinned binary (0 issues PR-scoped; the same two pre-existing unparam findings full-tree, unchanged) and scripts-go-checks leg parity standalone. Mutation-tested the new/updated policy assertions with six deliberate breaks (dropped matrix leg, reintroduced LINT, corrupted the pinned sha256, removed a cache-save step, dropped the vet leg, reintroduced the lint job); each was caught with an on-target failure. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> * fix(ci): review-fix pass on F5's lint/scripts-go-checks matrix (SF-1..SF-5, N-1..N-8) Addresses all SHOULD-FIX and NIT findings from the review of 7e858e2714 (no BLOCKERs): - SF-1: lint/vet cache saves now run on !cancelled() instead of bare cache-miss, so a red lint/vet run (main is currently lint-red on two pre-existing, unrelated unparam findings) still warms the cache for PR legs. - SF-2: ci-measurements.yml now exports golangci-lint's install dir onto PATH in the same step, since $GITHUB_PATH only takes effect in later steps. - SF-3: adds a behavioral test (fake curl/tar) proving the install script's sha256 verification fails closed. - SF-4: drops the commit sha from the golangci-lint cache key (saves only on config/dependency change, not every push) and trims the windows/darwin legs to cache only the small golangci-lint result cache, not their large GOCACHE. - SF-5: removes the vet cache's dead non-race-build-cache fallback restore key (different path list, can never hit) in both pr.yml and main.yml. - N-1..N-8: doc/comment accuracy fixes, restores the "moved code reads as new" caveat, adds a module-cache restore step and timeout-minutes to pr-lint-wrapper/go-vet-cache, pins fetch-depth/GOCACHE via new policy-test assertions, and flags a superseded doc snapshot. New commit on top of 7e858e2714; existing commit trailers are left untouched per explicit instruction. Not pushed, no PR opened. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> * build(bazel): auto-sync BUILD files Applied from the bazel-sync-patch artifact of https://github.com/gastownhall/beads/actions/runs/37105481015 (`make bazel-sync`: gazelle, tools/bazel/go_srcs.py, bazel mod tidy). Only BUILD.bazel, MODULE.bazel and MODULE.bazel.lock are ever pushed; see scripts/bazel-autofix-push.sh. --------- Co-authored-by: Gas City Adopt-PR <adopt-pr@gascity.local> Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
5.8 KiB
Linting Policy
Last reviewed: 2026-10-03
Freshness source: .golangci.yml, scripts/ci/pr-lint.sh, scripts/pr-lint/,
Makefile, .github/workflows/pr.yml, and .github/workflows/main.yml.
This document explains the required Go lint gate for this codebase.
Current Status
Lint is a required CI gate: ONE job per lane (pr-lint-wrapper), over the same
pinned golangci-lint v2.10.1 release and the same .golangci.yml. Each lane
must pass with zero issues in its own scope.
- The PR lane reports only what the PR introduces.
pr-lint-wrapperruns the repository-ownedci-pr-lintwrapper withBD_LINT_NEW_FROM_MERGE_BASEset to the diff against the merge base withmain. A finding in code the PR did not touch does not block it. "New" is measured off the diff, so MOVED CODE READS AS NEW: a pre-existing violation carried into a PR by a move or a rename is reported against that PR and blocks it. Fix it or//nolintit there — that is the accepted cost of the diff-scoped trade. - The main lane sweeps the whole tree. The same job runs on every push to
mainwithBD_LINT_NEW_FROM_MERGE_BASEunset, so a finding that lands there reds main's own run rather than every open PR.
pr-lint-wrapper is a 3-leg matrix, matrix.target: [native, windows, darwin]
(fail-fast: false), one leg per scripts/pr-lint pass (see below); the gate
requires the matrix's aggregate result under the same PR_LINT_WRAPPER id as
before. A former separate Lint job (the golangci-lint-action with
only-new-issues) was functionally identical to this matrix's native leg
(same binary, config, flags and diff scope) and was folded into it; see #5629.
Each leg installs golangci-lint from the pinned release binary
(scripts/ci/install-golangci-lint.sh, sha256-verified) instead of
go install, and restores a per-leg cache
(~/.cache/golangci-lint plus a leg-specific GOCACHE) keyed on
.golangci.yml, go.sum and the leg. A miss on the exact content key falls
back to the leg's most recent entry; golangci-lint revalidates it against the
current config and inputs, so a stale restore cannot mask an issue. pr.yml
only ever restores; main.yml's matrix is the only saver, on an exact-key miss.
Run the wrapper locally with:
make ci-pr-lint
That is the MAIN lane's contract, not the PR lane's: with
BD_LINT_NEW_FROM_MERGE_BASE unset it sweeps the whole tree, so it is
deliberately STRICTER than the gate your PR has to clear and may report findings
you are not required to fix. Fix the ones that are yours; the PR gate is the
authority on what blocks a merge, and main's own run is where the rest is
answered.
The wrapper runs:
- the shared
scripts/ci/fmt-check.shformatting check; and - the checkout-owned
scripts/pr-lintGo driver, which runs golangci-lint with.golangci.yml, readonly module downloads, a five-minute timeout, thegms_pure_gobuild tag, and--new-from-merge-basewhenBD_LINT_NEW_FROM_MERGE_BASEnames a ref, then runs the same scope for the non-CGO Windows target and the non-CGO darwin (arm64) target when the native host does not already cover them, so//go:build windows && !cgoand//go:build darwinfiles are linted from the Linux runner.
The shell wrapper records one aggregate timing for the Go lint driver. The driver prints a heading and result for each native or cross-target pass so failures remain attributable without duplicating target-selection policy in Bash.
The shared driver owns the lint passes used by scripts/ci/pr-lint.sh and
Beads-source bd preflight. The pre-commit hook does not call it: the hook
uses changed-lines scope, adds --fix, and omits the Windows cross-lint pass.
The driver honors BD_LINT_TARGETS (a comma list of native, windows and
darwin; default all three) so each CI matrix leg can run just its own pass;
make ci-pr-lint and bd preflight both leave it unset and keep running all
three.
The driver matches .buildflags when preparing GOFLAGS: appending
-tags=gms_pure_go can override an inherited bare-Go tags value; it does not
merge tag lists. Each lint process has a six-minute context and a five-minute
golangci-lint timeout. Cancelling preflight's outer go run command does not
guarantee immediate descendant cleanup.
On Windows, the driver checks each pass's selected Go SDK and prefers its
bin directory only in that linter child's PATH. This avoids an extra Go
auto-selection process surviving cancellation. Discovery shares the existing
30-second probe budget; custom SDKs that cannot be verified retain the original
PATH. Toolchain requests, formatting, and lint deadlines are unchanged. This
does not guarantee cleanup of compiler descendants or fix slow package loading.
Policy
Treat new lint findings as defects to fix before merge. Do not add a tolerated
failing baseline, and do not configure CI with --issues-exit-code=0.
When a linter reports an intentional or false-positive pattern:
- Prefer a narrow
.golangci.ymlexclusion tied to a path, linter, and message. - Use
//nolint:<linter>only when the reason is local to a specific line and the comment explains why the warning is not actionable. - Keep broad linter disables as a last resort.
The current configuration already encodes accepted exclusions for intentional patterns such as deferred cleanup errors, controlled subprocess execution, test-fixture file reads, and documented security false positives.
CI Cleanup Decision
pr-lint stays separate from pr-policy and pr-core so failures are easy to
identify and rerun. Its repository-owned wrapper is
scripts/ci/pr-lint.sh, exposed as make ci-pr-lint; its lint policy is owned
by the shell-free scripts/pr-lint Go driver.
See CI_CLEANUP_PLAN.md for the full CI tier policy.
Future Work
- Periodically audit
.golangci.ymlexclusions and remove entries that are no longer needed.