docs: govulncheck discriminating-stderr pattern

[bborbe]

Summary

Document the panic-safe vulncheck pattern that landed in templates/Makefile.{service,library} + go-skeleton's Makefile.precommit after the 2026-06-20 12-PR Makefile-modernization batch.

• Explains the false-negative trap of 2>/dev/null (real motivation)
• Walks the pattern: mktemp + trap + exit-code + content discrimination + robust grep alternation on stack-frame name OR message
• "Adding a new known-benign panic" recipe (rare, but documents the matcher-stability convention)
• "Adding a transient stdlib OSV ignore" recipe (e.g. GO-2026-5037/5038/5039 cleared by Go 1.26.4)

Doc-only. Closes the gap where the canonical template carried the code but go-tools-versioning-guide.md carried only the tools.env rationale.

[ben-s-pull-request-reviewer]

Reviewed by ben-s-pull-request-reviewer[bot] — no concerns flagged.

[ben-s-pull-request-reviewer]

Based on my review of the diff, here is my consolidated report:

---

PR Review: docs: govulncheck discriminating-stderr pattern

Scope: 1 file changed (docs/go-tools-versioning-guide.md), +62 lines

Must Fix (Critical)

1. Missing README.md update

• File: docs/go-tools-versioning-guide.md (new section)
• Issue: Per CLAUDE.md § Adding a new guide, step 2: "Add to README.md in appropriate table." The guide is a new top-level section in go-tools-versioning-guide.md but is not listed in any README table under the Guides section.
• Fix: Add go-tools-versioning-guide.md to the appropriate category table in README.md (likely under "Go — Infrastructure" or "Go — Code Quality").

Should Fix (Important)

2. Missing llms.txt update

• File: docs/go-tools-versioning-guide.md (new section)
• Issue: Per CLAUDE.md § Adding a new guide, step 3: "Update llms.txt." The new section is not indexed in llms.txt, meaning AI tools consuming this plugin will not surface this guidance.
• Fix: Regenerate llms.txt or add the new govulncheck: Discriminating Stderr Pattern section entry.

3. Template consistency — GO-2026-5037/5038/5039 comment vs doc

• File: docs/go-tools-versioning-guide.md:265 and templates/Makefile.service / templates/Makefile.library
• Issue: The doc's recipe (line 265–268) describes adding an OSV ignore "when Go ships a stdlib vuln ... whose fix lands in the next patch release." The actual templates already have GO-2026-5037 GO-2026-5038 GO-2026-5039 with a more specific comment: "fixed in 1.26.4 — remove from this list once all CI runners and base images are on 1.26.4+." The doc recipe doesn't mention the existing Go 1.26.3 vulns or the explicit removal trigger.
• Fix: Update the "Adding a transient stdlib OSV ignore" subsection to reference the actual template comment style and the specific already-tracked IDs.

Nice to Have (Optional)

• The doc says the pattern "lives in coding/templates/Makefile.service and Makefile.library" — correct, but these paths use the bborbe absolute path convention (~/Documents/workspaces/coding/...). Per CLAUDE.md "Self-Contained" rules, these should use a path relative to the plugin install dir or a generic reference.
• The doc at line 251 says "The package + function name in the stack trace is stable across x/tools releases" — this is an assertion that could drift if upstream refactors. The "Adding a new known-benign panic" section (line 256–261) partially mitigates this with instructions for when it happens.

---

Manual Review Notes

• Step 4 skipped: ast-grep not available in this environment (toolchain gap).
• Step 3b skipped: make precommit not run (selector mode); CI covers lint+test.
• The govulncheck pattern itself is correct: temp-file stderr capture + content discrimination is sound, and the trap cleanup is properly placed before mktemp. The typesinternal.ForEachElement grep is the right stable anchor (package-qualified, not free-text).

---

{
  "verdict": "request-changes",
  "summary": "The govulncheck discriminating-stderr documentation is technically sound and accurately reflects the template implementation. However, two procedural violations of CLAUDE.md's 'Adding a new guide' process must be resolved before merge: the new section is missing from README.md and llms.txt. Additionally, a minor consistency gap exists between the doc's generic OSV-ignore recipe and the more specific template comments already tracking GO-2026-5037/5038/5039.",
  "comments": [
    {
      "file": "docs/go-tools-versioning-guide.md",
      "line": 1,
      "severity": "critical",
      "message": "Must Fix: README.md not updated. Per CLAUDE.md § Adding a new guide step 2, the new 'govulncheck: Discriminating Stderr Pattern' section must be added to the appropriate Guides table in README.md."
    },
    {
      "file": "docs/go-tools-versioning-guide.md",
      "line": 1,
      "severity": "critical",
      "message": "Must Fix: llms.txt not updated. Per CLAUDE.md § Adding a new guide step 3, the new section must be added to llms.txt so it is indexed for AI consumers of the plugin."
    },
    {
      "file": "docs/go-tools-versioning-guide.md",
      "line": 265,
      "severity": "major",
      "message": "Should Fix: Template consistency gap — the 'Adding a transient stdlib OSV ignore' recipe describes a generic pattern, but templates/Makefile.service and Makefile.library already track GO-2026-5037/5038/5039 with a more specific comment (fixed in Go 1.26.4). The doc should reference the existing IDs and removal trigger to stay consistent with the canonical templates."
    }
  ],
  "concerns_addressed": [
    "correctness: Pattern relies on matching specific panic stack frames (typesinternal.ForEachElement) — acknowledged in doc at line 251, with guidance on stable matcher selection. Not a blocking issue.",
    "correctness: No automated enforcement for stale OSV ignores — doc at line 267-268 describes manual removal on Go bump, consistent with template comment style. Not a blocking issue."
  ]
}

[ben-s-pull-request-reviewer]

Reviewed by ben-s-pull-request-reviewer[bot] — no concerns flagged.