Files

check / check (push) Successful in 11s

Details

Make the pinned golangci-lint actually reach the host (closes #28 )

REPO_POLICIES.md now carries the canonical script/bootstrap snippet for Go
repos alongside the .golangci.yml bullet, where the pinned linter version
already lives.

The guard it replaces, `if missing golangci-lint; then go install ...; fi`,
tests PATH presence and never version, so on any already-provisioned machine
the pin is inert and a version bump is a no-op. The Dockerfile installs
unconditionally into a clean image, so CI and local then disagree about what
the linter is: a local `make check` green while `make docker` rejects the same
commit, and a container run surfacing findings the host run cannot see.

Comparing versions alone is not enough. `go install` writes to GOBIN (or
GOPATH/bin) while callers resolve through PATH, so a shadowing binary earlier
in PATH lets the install succeed and change nothing a caller ever sees, while
bootstrap prints success. The canonical form therefore compares the installed
version against the pin, re-resolves through PATH after installing and asserts
the pin, and treats any unparseable --version output as a mismatch so the
failure direction is a redundant install rather than a skipped one.

When the assert fails the diagnosis is derived from the resolved path rather
than asserted: a path outside the install directory is shadowing and the
operator is told to remove it or reorder PATH; a path inside it is not, and
saying so would send them after a fault that does not exist; no resolution at
all means the install directory is simply absent from PATH.

The snippet ends with a call site. Two function definitions and no invocation
are a silent no-op with exactly the shape this change exists to close, and the
adoption instructions say to paste the block verbatim.

The version helper ends in `|| true` so a --version that exits non-zero cannot
kill the script through `set -e` under `set -o pipefail` before the diagnostic
is printed, which the styleguide's bash form would otherwise do.

The policy text states each of those as a requirement rather than leaving them
implicit in the code, records why the commit-pinned `go install` ref satisfies
the hash-pinning rule (a commit hash is not a mutable tag, and the checksum
database verifies the fetch; no repo go.sum is consulted, since `go install
pkg@version` ignores the go.mod in the current directory or any parent), and
requires the pin to be a tagged release commit: an untagged pin yields a
pseudo-version that the parser truncates at the first `-`, so no value of
GOLANGCI_LINT_VERSION derived from what --version prints can ever match.

Verification requires two things the previous round lacked: a negative control
against a shadowing binary, and running the controls against the block as a
consuming repo would adopt it, pasted into a script/bootstrap-shaped file and
executed, rather than sourcing it and calling the function directly.

The node and yarn handling described earlier in the document is untouched.

2026-08-09 15:41:09 +00:00

3.3 KiB

Raw Blame History

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-08-09: Made the pinned golangci-lint actually propagate: REPO_POLICIES.md now carries the canonical script/bootstrap snippet for Go repos, which installs when the installed version does not match the pin (the old if missing guard tested PATH presence only, so pins were inert on any provisioned machine and CI silently disagreed with local) and then re-resolves the binary through PATH and fails loudly, naming the shadowing path, when the install did not take effect — the failure mode the naive compare-then-install fix leaves behind while reporting success.
2026-08-09: Fixed the false green in the canonical CI gate: script/cibuild and script/docker now pass a per-invocation CHECK_EPOCH nonce, and the Dockerfile (plus the Go multistage template in REPO_POLICIES.md, in both its lint and builder stages) declares ARG CHECK_EPOCH with a guard that makes a bare docker build . fail closed. Corrected the org-canonical text that asserted a successful build implies all checks pass, across every document carrying it: REPO_POLICIES.md, both repo checklists (which still told agents to write the pre-fix script/cibuild and ended on an acceptance item the guard makes unsatisfiable), and the Go styleguide.
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).