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.

docs/COMPLETED.md

@@ -3,6 +3,18 @@
 Completed milestone entries removed from `PLAN.md`. Each entry preserves its
 original Goal, Verify, and checklist points with boxes marked done.
 
-This file holds the current (1.x) cycle's landed milestones only. Nothing has
-landed in the 1.x cycle yet. For all pre-1.0 (version-0) history, see
-`docs/ARCHIVE.md`.
+This file holds the current (1.x) cycle's landed milestones only. For all
+pre-1.0 (version-0) history, see `docs/ARCHIVE.md`.
+
+### Comment-reduction pass (tree-wide, twelve parallel tracks)
+
+Cut source comment volume tree-wide: 209 files changed, net **−6,493** lines.
+Comment-only lines went from 15,073 to ~8,671, a **~42% cut** — before the
+pass, 37% of all source lines were comment-only. **Zero code drift**, verified
+across all 209 files by comparing comment-stripped hashes; the sole
+intentional exception (Daniel-approved) is two user-facing error strings in
+`src/shell/capture/capture.cpp` that lost internal milestone IDs (`M8`, `M3`,
+`M7+`). Build clean, 61/61 ctest pass. Code review surfaced 2 Major + 8 Minor
+findings — all content cut that should have survived — and all ten were
+remediated and re-gated before merge. Driver: Daniel's instruction — *"Brief
+concise engineering comments. A little why, and maybe context, never WHAT."*