Seven files still opened with a paragraph about how they came to be -- "the first
version cleared the same bit four times", "the older repeated-subtraction divmod
needed 1.48M steps", "last round rejected shift-and-add because it was longer",
nested with measured step counts. None of that tells a caller how to use the
macro, and it is exactly the material that goes stale (raw_sub's figure had been
retracted, and the numbers are SPEC's job now). The stories already live in
docs/divmod.md and docs/byte-ops.md, so:
digits 119 -> 80 lines mul 125 -> 98
divmod 106 -> 80 inc_ip 81 -> 72
undigits 95 -> 73 raw_sub 52 -> 38
dec_ip 21 -> 18
Each now opens with two lines: what the macro computes and where the contract
lives (SPEC section, plus docs/ when there is a design write-up). Everything
from the `; Macro <name>` block down -- parameter types, preconditions,
what-is-eaten, the non-obvious invariants -- is untouched, which is what
r8forge_macro_docs_test checks and what a caller actually reads.
Baseline unchanged: tape 64513, 21 byte-op items, 15 examples, 48 macros.