---
name: a-rust-doc-block-binds-to-whatever-follows-it
description: Inserting a Rust item ABOVE another item's /// doc block + treqs tags silently re-points that prose and those tags onto the new item with zero bytes changed in either — three instances 2026-09-09 (todlando #289 2b, hertz Survivor, hertz d882297f probe); only a reader catches it
metadata:
  type: feedback
---

A `///` doc block (and the `// [stage->REQ-*]` tags that ride under it) binds to the NEXT ITEM. An
insertion between the block and the fn it documented moves the prose and the tags onto the inserted
item: the diff shows only additions, `cargo check` and `traceable-reqs check` both stay green (the
tag is still in the file), and the documented fn is now undocumented and untagged.

**Instances 2026-09-09 (three in one day, three authors' reviews):** todlando's #289 commit 2
(`redeem_peer_silent_line` inserted under the REDEEM-WIRE block, fixed in 2b, 0 non-comment lines);
hertz's leak lane (Survivor doc block contiguous with Population's, fixed before 5a50e625);
hertz's d882297f (the inbound-probe block inserted between `two_host_web_role_b`'s doc + two int
tags and the fn — caught in my pre-PR read).

**Why:** the tag rule is "on or immediately above the real evidence"; a tag that has drifted onto the
wrong item satisfies coverage while pointing at nothing, which is the exact failure the rule exists
to prevent, and no tool in the battery reads adjacency.

**How to apply:** when inserting an item, insert ABOVE the target's doc block (or below the whole
fn), never between a `///` block and its item; in review, read the three lines either side of every
hunk boundary and ask what the nearest `///` above the hunk now documents. Kin:
[[treqs-exit-2-is-an-unparseable-registry]] (green treqs proves parse + presence, not placement).