Files

check / check (push) Successful in 9s

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.

The comparison is exact over the whole version token. A parser that stops at
the first `-` reports 2.12.2 for a host running 2.12.2-rc1, which compares
equal to a 2.12.2 pin and skips the install -- the original defect, reachable
through the comparison meant to close it, and not caught by requiring the pin
to be tagged, since a pre-release is tagged too.

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. A trailing slash
on GOBIN is normalised away, since it would otherwise make the inside-the-
directory test miss and misreport shadowing.

The snippet ends with a call site, and both success paths print a confirmation
naming the version. Two definitions with no invocation are a silent no-op with
exactly the shape this change exists to close, and a success path that prints
nothing is byte-identical to that no-op: same exit status, same empty output.

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, and 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, with no repo go.sum consulted, since
`go install pkg@version` ignores the go.mod in the current directory or any
parent. Whether a go.mod tool dependency should replace that is an open
decision and is linked rather than settled here. The two version strings must
be kept in sync and must match exactly what --version prints; tagged pins are
preferred because the expected string is then derivable from the ref, rather
than because the comparison cannot handle a pseudo-version.

Verification runs 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 16:01:36 +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).