go-ldd v2.9.0: empathy test, decoder-ring refs, repo-idiom, when-in-Rome check

[buzzdan]

Why

A repo owner reviewing a large generated PR gave hard, fair feedback: he could merge the code but "could not reasonably ask another human to maintain the result". His two themes: "if you actually try to read the commentary, you will find that you need to read the code to understand the comments" (plus cross references to internal plan/test IDs that mean nothing to a reader), and a feature PR that silently adopted new engineering practices ("when in Rome"). His coding standards state "Empathy is a core engineering value."

The v2.8.0 three-test standard already catches about half of that (budget overruns, PR-number provenance, fancy vocabulary). This release closes the four confirmed gaps and adds a review check for the non-comment failure mode.

What changed

R9 comment policy (the doctrine, pasted as critic payload)

• Test 3 is now the plain-English/empathy test. Persona anchor: a fresh graduate whose first language may not be English. Unexplained acronyms and insider jargon fail — in comments and in the symbol names they document. New second half, self-standing: the comment must be understandable BEFORE reading the code; if the reader must read the code — or another comment — to understand it, it has negative value.
• Decoder-ring references join the provenance anti-toolbox: plan/decision/test-plan IDs ("T-04-02", "D-07"), requirement tags ("REQ-SVC-01"), spec sections ("spec §4"). They fail even when they resolve inside a repo doc — the fact goes in the comment as plain prose, the doc through one See-edge.
• Restated repo idiom is a new floor failure mode. A comment justifying a convention the repo applies everywhere (pointer field = "omitted vs explicit zero") is noise even though it is technically a WHY — under the old standard the critic would have kept it. The convention lives once at rung 2.
• See-edge placement: the See docs/<feature>.md line is budget-free ONLY as its own trailing line, never braided into the summary sentence.

comment-critic agent

• Protocol now starts by reading the comment BEFORE the surrounding code, making the self-standing check mechanical.
• Decoder-ring and repo-idiom sections added; the idiom check greps the repo for the same pattern before crediting a WHY.
• When the jargon lives in the symbol name itself, the verdict block carries a rename recommendation for the caller to route (renames are not the critic's to order). Added after a live run where the critic rewrote a comment but left the jargon name unremarked.

pre-commit-review

• When-in-Rome check (step 1, in-context): anything the diff introduces that the host repo does not already use — test mechanisms (golden files), dependencies, tools, config conventions, repo-level file edits bundled into a feature diff — is flagged. Detection is comparative: grep the repo outside the diff for prior use.
• New report category: 🟠 New Practice (when in Rome) — adoption decisions belong to the repo owner; the fix is a discussion or a separate PR, never silent inclusion. The reviewer's three hardest rejections were all in this category, not code quality.

Catalog + maxims

• Toolbox catalog: worked ❌/✅ examples for decoder-ring refs and repo idiom; comments checklist extended.
• Two new maxims: "Empathy is a core engineering value" and "When in Rome, code as the Romans do".

Verification

• Doctrine restated in exactly one place each: R9 owns the tests, reference.md owns the worked examples, the critic cites both as payload.
• Live field test: the critic ran with this payload against the reviewed PR's five comment-heaviest files — 49 comments reviewed, 7 KEEP / 19 TRIM / 19 REWRITE / 4 DELETE. It caught every comment the human reviewer flagged (decoder-ring package doc, the unreadable request/response-shape godocs, the forward-reference comments, the repo-idiom pointer note, the provenance tails), plus ~20 more with the same diseases he described as "throughout this PR". One observed miss (jargon in a symbol name went unremarked) became the critic's rename-note addition above.
• Changelog entry added; plugin version bumped to 2.9.0.

🤖 Generated with Claude Code