docs: drop internal CLAUDE.md §N references — state the rule directly

[eschizoid]

Summary

Seven source files used internal CLAUDE.md section numbers (§12, §17, §18) as a shorthand for the rule they were encoding. Three problems with that pattern:

• Section numbers renumber when CLAUDE.md is reorganized, so the in-source pointer rots silently.
• The reader of the source code can't see the rule — they'd have to context-switch out to a separate doc to find it.
• It builds in an "insider shorthand" that gets in the way when the comment is the first thing someone reads after a stack trace.

Each reference is replaced with the rule itself, stated in plain prose where the reader actually needs it.

Files changed

• lib/kpipe-core/.../Result.java — name the protobuf decode bug that motivated the sealed-result shape and the compile-time guarantee it provides.
• lib/kpipe-core/.../PipelineDiagnostics.java — describe the burn directly (wrong envelope size = silent decode failures) without the §12 label.
• lib/kpipe-api/.../Stream.java — explain when to attach onFailed by symptom ("processed counter rises, sink stays at 0") rather than pointing at a section.
• lib/kpipe-consumer/.../BatchPipelineWrapper.java — state the rule the dispatch enforces (uncovered batch positions become synthetic failures so a misreported BatchResult can't silently mark them processed).
• lib/kpipe-consumer/.../KPipeConsumer.java — spell out the dispatcher-before-offset-manager shutdown order in terms of what would break if it changed.
• lib/kpipe-consumer/.../KPipeReporterThreadTest.java — drop the §17 reference and cite docs/escape-hatches.md directly, since that's the actual gate the test is pinning against.
• README.md ×2 — a self-reference "§2 chain" replaced with a phrase pointing at the prior section by title; a §12 burn description replaced with the underlying symptom.

Deliberately kept

External W3C §3.2 references in tracing tests stay — those cite an actual external standard, not an internal architecture chapter.

Test plan

• ./gradlew compileJava compileTestJava spotlessCheck — green locally
• Repo-wide grep for §[0-9] outside the excluded set returns zero matches
• CI green

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 76.48%. Comparing base (f3c56d7) to head (603a571).
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@             Coverage Diff              @@
##               main     #152      +/-   ##
============================================
- Coverage     76.52%   76.48%   -0.04%     
+ Complexity      761      760       -1     
============================================
  Files            75       75              
  Lines          2871     2871              
  Branches        357      357              
============================================
- Hits           2197     2196       -1     
  Misses          503      503              
- Partials        171      172       +1     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.