docs: record comment-reduction pass in COMPLETED, add comment conventions to CLAUDE.md

CLAUDE.md

@@ -144,6 +144,16 @@ three-hot-path performance guardrail above — they do not replace it:
    A by-class `sampler_core` split that would put virtual envelope `tick()`s on the
    per-voice-per-sample path is exactly the blowout this forbids.
 
+## Comment conventions (Daniel, 2026-07-29 — driving the tree-wide comment-reduction pass)
+
+Comments carry *why*, and context where non-obvious — never *what* the code already says.
+
+- File headers stay brief (~5 lines); no titled prose sections inside them.
+- Don't restate invariants a directory's own `src/**/CLAUDE.md` already owns — those files are the home for area invariants.
+- No wave/ticket/milestone IDs in comments. A one-line "do not reintroduce X" warning is fine without the ticket number.
+- Keep: RT-safety, allocation, and threading constraints; SDK facts confirmed by experiment; compressed regression history; format/version-ladder semantics; warnings against a plausible-but-wrong change.
+- When unsure whether a comment is load-bearing, keep it.
+
 ## REAPER extension contract (src/app/main.cpp)
 
 - Exactly **one** translation unit defines `REAPERAPI_IMPLEMENT` — that is `main.cpp`. Every other `.cpp` includes `reaper_plugin_functions.h` without the define and gets `extern` declarations for the global API function pointers.