harness: a standing advisory is a defect

The %w advisory counted every fmt.Errorf without %w, including calls that create
an error rather than wrap one — so it fired permanently on correct code. It now
looks for a call that passes an err and drops the %w, which is the actual rule.

Recorded the general form in the loop's Verify step and in HARNESS.md: a warning
that fires on correct code and keeps firing is a defect in the check or the code,
resolved in that change. Two advisories have now been narrowed after firing on
code the harness itself mandates, and the count creeping from one to two was the
only signal either time.

verify.sh is at zero warnings, which is what makes the next one legible.
This commit is contained in:
2026-08-01 02:23:34 +06:00
parent b3ffa21fdf
commit 97b01bea05
4 changed files with 12 additions and 2 deletions
@@ -104,6 +104,10 @@ of real generated markup, or benchmark numbers.
Budget failure: shrink the change, or stop and propose an ADR raising it. Never raise it silently.
**A standing advisory is a defect.** If a warning fires on correct code and will keep firing, either the
check is wrong or the code is — resolve which, in that change. Tolerated warnings are how the whole
channel stops being read, and the count creeping from one to two is the only signal you get.
Never write "should work", "this will now…", or your own diff summarised as a result. If you could
not run something, say which and why.
+4
View File
@@ -124,6 +124,10 @@ is a codebase still navigable by `go doc` and `git log` alone, years from now, w
instead of `log/slog`, `panic()` outside `cmd/`, and `time.Now()` outside a `clock.go` are stated
absolutely in `conventions.md`, so they exit non-zero. That last one exists because a Stage that reads
the clock without an expiry would serve staleness invisibly. A rule enforced as a suggestion teaches the agent to read every rule as one.
A green run has **no** warnings once code exists. An advisory that fires on correct code gets fixed —
either the check or the code — because a warning nobody can act on trains you to skim the ones you can.
Two of these have already been narrowed after firing on code the harness itself mandates.
Softer signals stay advisory: `fmt.Errorf` without `%w`, nesting past 4, exported-and-referenced-once,
and `any` in an **exported** signature — only exported, because ADR-0002 mandates an open page object,
so unexported code reading frontmatter takes `any` legitimately and forever.
+1 -1
View File
@@ -1,6 +1,6 @@
# State
**Verified against:** `37ccf94` on 2026-07-30 — update this line every change.
**Verified against:** `8a6857b` on 2026-07-30 — update this line every change.
If this file disagrees with the code, the code is right and this file is a bug.
## Inventory
+3 -1
View File
@@ -377,7 +377,9 @@ panics=$(echo "$gofiles" | grep -v '_test\.go$' | grep -v '^\./cmd/' | xargs gre
if [ -n "$panics" ]; then bad "panic() outside cmd/ — request-time failure degrades (conventions.md): $(echo "$panics" | tr '\n' ' ')"; else pass "no panic outside cmd"; fi
head_ "smells (advisory)"
nowrap=$(echo "$gofiles" | xargs grep -n 'fmt\.Errorf(' 2>/dev/null | grep -v '%w' | wc -l | tr -d ' ')
# Only calls that actually wrap: fmt.Errorf without an err argument is creating an error, not losing one.
nowrap=$(echo "$gofiles" | xargs grep -hn 'fmt\.Errorf(' 2>/dev/null |
grep -v '%w' | grep -cE '\berr\b' || true)
[ "${nowrap:-0}" -gt 0 ] && note "$nowrap fmt.Errorf without %w (wrap at package boundaries)"
# Only exported signatures: conventions.md bans interface{} as an API escape hatch, but ADR-0002 mandates
# an open page object, so unexported code reading Extra legitimately takes any and always will.