First doc-directory of hyperhive#4042's Passive pass (705+ hits across
docs/, genuinely mixed unlike TooWordy -- needs a real per-hit read,
not a dictionary shortcut, so this is going doc-directory by
doc-directory in small PRs, per the plan posted on the issue).
Read all 13 flagged hits in this file in context, not just the flagged
word. 3 were genuine catches with a real active-voice improvement and
a nameable actor:
- "the human operator's own forge/matrix account is created via swarm
SSO" -> "swarm SSO creates the human operator's own forge/matrix
account" (x2, identical sentence shape for both accounts) -- swarm
SSO is a nameable, specific actor already named later in the same
sentence, so naming it as the subject too is strictly clearer, not
just different.
- "Do this before anything is pointed at it" -> "Do this before you
point anything at it" -- matches the doc's own established
second-person imperative voice used throughout ("Do this", "Put the
token's value", "Delete the file"); the passive here was the odd one
out, not the house style.
The other 10 are legitimate passives, left alone:
- Generic/unspecified-actor statements ("is needed", "is bound", "is
issued", "been run") where forcing a subject would either invent an
actor the doc never established or read worse than the original.
- Security/architecture invariants ("No forge admin token is stored in
any agent state dir", "Telemetry ingest is authenticated per hive")
-- "No X is Y" / "X is Y" is the standard idiom for a guarantee
statement in security docs, not a clarity problem to fix.
- "operator-only surfaces ... are gated on that group" -- borderline
(could name the group as subject), judged idiomatic access-control
phrasing rather than genuinely clearer active, but flagged as the
closest call in this batch.
Verified: vale docs/getting-started/setup.md before/after -- 13 -> 10
write-good.Passive hits (exactly the 3 rewritten), the pre-existing
unrelated alex.Suicide hit on "hang" (line 51, untouched) still
present and correctly out of scope for this pass.
bfb9636d52