docs: say what these things are, not where they used to be

mara on #3923: "past tense is itself a smell for docs, we dont need any
'used to be somewhere else'" and "any gate we add should not have false
positives". Those are one instruction: the entire false-positive set of a
repo-path checker was prose naming files that are deliberately gone, so
removing the prose is what lets the gate be strict instead of carrying a
skip-list nobody maintains.

Three sites, and only two of them are past tense:

`agent-hierarchy.md` named two removed modules to explain that a code path
is gone. A reader cannot act on where it used to live; they can act on
where cancellation happens now, which is the half the sentence buried.

`term_msg.rs` carried a "Design history" paragraph whose live content was
three rules -- classification is server-side, `level` carries styling, four
named fields are deliberately absent -- wrapped in narration about a
redesign and a pointer to a deleted frontend file. Restated as the rules.

`gotchas.md` is NOT past tense: it correctly names a file in the website
repo. Qualifying it as `hyperhive/website:nix/options.nix` did not work --
the extractor still matches `nix/options.nix` as a substring, so the fix
has to be prose that contains no repo-relative path at all. Naming the
file alone does that and reads better.

Verified against this tree rather than the default checkout: the audit
script takes a directory argument and defaults elsewhere, so its first
(unchanged) DEAD:3 was a true statement about a different branch. On this
one: DEAD 3 -> 0, 141 distinct paths enumerated, and an injected dead path
is still caught.

Refs #3923
This commit is contained in:
atlas 2026-09-02 22:53:47 +02:00 committed by mara
commit efbfeb3954
3 changed files with 10 additions and 14 deletions

View file

@ -155,11 +155,9 @@ Manager}` switch picks the MCP tool allow-list claude sees. Both are
ancestor/descendant check instead of a manager-name check — see the
module docs for `loose_ends.rs`, `stores/broker.rs`, `actions.rs`,
and `workers/crash_watch.rs` for the current owner-check logic in
each. (Question/answer routing and its own manager-override cancel
path — formerly `hive-c0re/src/questions.rs` and
`stores/operator_questions.rs` — has been removed entirely; reminder
cancellation is now handled fully in-agent, see the note on
`CancelLooseEndKind::Reminder` in `hive-c0re/src/socket_server/mod.rs`.)
each. (Reminder cancellation is handled fully in-agent — see the note
on `CancelLooseEndKind::Reminder` in
`hive-c0re/src/socket_server/mod.rs`.)
None of the above is a stable interface — treat the module doc
comments as the source of truth for exactly which checks exist today.