docs: give each explanation one home, compress the core comments

[sshaplygin]

Four explanations were repeated between the core's comments and docs/, and
each repetition was a place they could drift apart. They now live in one place
each, and the comments state the invariant instead of re-arguing it.

Explanation → canonical anchor

Explanation	Now lives in	Was also in
Why a shadow must fill itself on a miss, and what it costs when it does not	docs/design.md (Idea, step 3)	shadow.go fanOutReadLocked
What demotion costs SIEVE and S3-FIFO	docs/policies.md	shadow.go demoteLocked
MinEpochRequests counts sampled, not real, requests	docs/configuration.md	settings.go godoc only
MinShadowCapacity raises the effective rate	docs/configuration.md	settings.go godoc only
Miniature capacity, single sampled substream	docs/design.md + sampling.go (the arithmetic)	settings.go, shadow.go
Zero value never reaches a caller	docs/design.md	restated as an invariant at each site that could break it

The two marked only were in godoc and nowhere else, so a reader of the
configuration guide could set either wrong. At a 0.05 sample rate a
MinEpochRequests of 100 is reached after roughly 2000 real requests, not 100.

Invariants recovered from outside the repository

docs/policies.md gains the three rules an arm has to honour, each broken by a
real implementation: never return a zero value with true, keep Keys() and
Values() aligned, read size 0 as empty rather than unlimited (and do not
start a goroutine with no way to stop it). The first is why policies.NewTTL
is written over a plain LRU rather than wrapping expirable.

Comment density

cache.go      109/361 = 30%  ->  100/352 = 28%
epoch.go       65/207 = 31%  ->   64/206 = 31%
shadow.go     114/215 = 53%  ->   56/157 = 35%
sampling.go    53/129 = 41%  ->   41/117 = 35%
migration.go   47/137 = 34%  ->   43/133 = 32%
settings.go    91/196 = 46%  ->   61/166 = 36%
total         479/1245 = 38% ->  365/1131 = 32%

It stops at 32%, not the 25% the stage asked for. What remains is
invariants, lock preconditions, and godoc on exported API. Reaching the number
would mean deleting documentation whose absence lets someone break correctness
by editing nearby — the switchLocked ordering rule, the three roles during a
gradual window, why Peek and not Contains. The target and the rule that no
removed comment may describe a load-bearing invariant conflict on these files,
and the invariant wins. Flagging rather than quietly missing it.

The README needed no work: 56 lines against a target of 90.

Verification

make all                    -> Release checks passed, nine modules
gofmt -l *.go               -> empty
documentation link check    -> every internal .md link resolves
                               180 insertions(+), 248 deletions(-)

Class G — please read before merging: README.md (unchanged), and the
diffs of shadow.go and epoch.go. Those two are where a deleted comment
could have taken an invariant with it.