docs: suppress reviewed write-good.Passive false positives

133 hits across 38 files, all previously classified during #4548's sweep
and deliberately left un-rewritten (predicate-adjective state/necessity
description, design-intent idiom, structural/type-description idiom,
no-single-actor topology claim, parallel-triple exception, vale
substring-match artifact — see hyperhive#4548's per-PR bodies for the
per-hit reasoning).

Wraps each one in a scoped <!-- vale write-good.Passive = NO/YES -->
pair (the supported mechanism — TokenIgnores has a known offset-drift
bug) rather than a blanket per-file or per-rule silence, so a *new*
passive-voice hit anywhere in these files still fails once the rule
gates CI (next commit). Table/list false positives (docs/swarm/credentials.md's
renewal-table cells) wrap the whole block, not each cell.

Part of #4546.
This commit is contained in:
iris 2026-09-20 15:07:46 +02:00
commit 04e27c4fb6
38 changed files with 368 additions and 71 deletions

View file

@ -142,10 +142,12 @@ field; `pr status` when the only question is "can I merge it."
### Contributing to a read-only repo (`clone` + `pr create --agit`)
<!-- vale write-good.Passive = NO -->
Agents are read-only collaborators on some repos (e.g.
`internal/knowledge`) and so can't push branches. Forgejo's AGit flow
lets a read-only user open a PR by pushing the current `HEAD` to the
magic ref `refs/for/<base>/<topic>`. Two verbs cover the workflow:
<!-- vale write-good.Passive = YES -->
```
hive-forge -r internal/knowledge clone # clone, auth handled for you
@ -158,6 +160,7 @@ hive-forge -r internal/knowledge pr create --agit \
[--body "details"] # PR description (also accepts --body-file)
```
<!-- vale write-good.Passive = NO -->
`clone` derives the dest dir from the repo basename (override with a
positional arg); it passes `--branch` / `--depth` through. The clone
URL and the `origin` remote it leaves behind carry no credentials —
@ -166,6 +169,7 @@ URL and the `origin` remote it leaves behind carry no credentials —
hand), which git calls fresh on every fetch/push. That's what lets
`pr create --agit` (default remote `origin`) push without re-auth,
without a durable token sitting in the checkout's `.git/config`.
<!-- vale write-good.Passive = YES -->
`pr create --agit` prints the PR URL. Re-running with the same
`--topic` force-updates the existing open PR (the AGit ref is
@ -244,6 +248,7 @@ to discover valid label names before triaging or to audit the label set.
## Notes
<!-- vale write-good.Passive = NO -->
- **Read-before-comment guard:** `comment` refuses to post when forge still
has an unread notification for the thread (that is, someone commented since
you last read it). This prevents accidentally replying to old activity without
@ -341,3 +346,4 @@ to discover valid label names before triaging or to audit the label set.
response's `X-Total-Count` (`… 50 of 187 shown … 137 more`), so trust
the trailer, not the row count, when deciding whether you've seen
everything.
<!-- vale write-good.Passive = YES -->