harness: soften two gates that would have taught --no-verify

The test-coupling gate failed comment-only and gofmt-only .go diffs, which
ship no behaviour and owe no test. Bypassing it would have cost every gate at
once, so it now compares added and removed lines with comments, blanks and
whitespace runs stripped: equal sets mean nothing happened. A new .go file is
never exempt.

The exported-doc-comment check is now a warning. No gate can tell
"// Load loads." from a useful sentence, so as a hard failure its cheapest
satisfaction was exactly the noise conventions.md calls worse than nothing.
Package comments and ADR citations in code stay hard.

Also fills in state.md's verified-against line and drops a stray blank line
left in roadmap.md by an earlier gate test.
This commit is contained in:
Claude Opus 5
2026-07-30 01:09:22 +06:00
committed by bdeshi
parent 99f8c730b0
commit 126fdbc861
5 changed files with 28 additions and 9 deletions
+5 -2
View File
@@ -47,11 +47,14 @@ wants splitting.
## Documentation
Written for a maintainer working alone, years from now, with no agent to explain anything. `verify.sh`
enforces presence; only a human can enforce that it says something.
fails on a missing package comment and on a citation naming an ADR that does not exist; a missing doc
comment on an exported identifier is a warning, because no gate can tell `// Load loads.` from a useful
sentence, and a gate whose cheapest satisfaction is noise buys noise.
- **Every package has a package comment.** What it owns, what it does not, and which packages may import
it. For `internal/ext/*` that is the four-line `doc.go` shape in `extensions.md`.
- **Every exported identifier has a doc comment.** The exported surface of a 2000-line core is small, and
- **Every exported identifier has a doc comment** (warned, not gated). The exported surface of a
2000-line core is small, and
`go doc ./...` is the only navigation tool that still works when nothing else does. A comment that
restates the name (`// Load loads.`) is worse than none: say what it returns on absence, what it costs,
what it assumes.