docs: fix genuine passive-voice hits in docs/tools (hand-written files)

Read all 62 write-good.Passive hits across the 6 hand-written files in
docs/tools/ (bash.md, lifecycle.md, forge.md, hivectl.md, matrix.md,
scheduling.md) in context. Excludes forge-cli.md/hivectl-cli.md/
swarmctl-cli.md (57 more hits) -- those are CI-generated from the
clap doc-comment strings in hive-forge/hivectl/swarmctl, freshness-
checked against the committed markdown, so a fix there has to go in
the Rust source and get regenerated -- separate batch.

33 rewritten to active, actor usually already established in the same
paragraph or given via a 'by X' clause (the daemon, hive-c0re,
hive-forge, hivectl, hyperhive itself, or an established module name
like nix/agent-modules/mcp.nix). Several sibling-inconsistency fixes:
a passive clause next to an already-active sibling stating the same
fact (lifecycle.md's server-scoping sentence, forge.md's clone-derives
sentence, hivectl.md's daemon-hashes-passwords sentence, matrix.md's
daemon-upserts-a-todo paragraph).

29 left alone: no-X-is-Y / no-X-is-needed invariant idioms, config-state
conditionals (whenever/when X is set/configured/given), requirement-
list idiom, a false-positive tokenization (vale matching 'are read'
inside 'read-only'), definitional facts about CLI/attrset structure
with no real actor, hypothetical/counterfactual clauses describing a
rejected design alternative, a forward-looking not-yet-real removal,
compressed bullet-fragment conventions, and one deliberately-parallel
sentence structure left both halves alone to avoid breaking the
symmetry.

Verified via vale on the 6 touched files, diffed against main's exact
baseline (not just the Passive count): write-good.Passive 62 -> 29
exactly, every other category unchanged in count AND location
(TooWordy 16, Microsoft.We 1, Microsoft.FirstPerson 1, and the same
4 pre-existing Microsoft.Contractions errors at the same 4 lines).
This commit is contained in:
iris 2026-09-08 14:21:11 +02:00 committed by mara
commit 97e2a993e3
6 changed files with 49 additions and 49 deletions

View file

@ -22,7 +22,7 @@ markdown-docs > docs/tools/forge-cli.md`.
## Verbs
**Kind-namespaced commands (preferred):** issue/PR operations are grouped
**Kind-namespaced commands (preferred):** hive-forge groups issue/PR operations
under `issue` and `pr` parent commands — `hive-forge pr close 42`,
`hive-forge issue create --title …`, `hive-forge pr status --pr 42`. The
`pr <verb>` / `issue <verb>` forms validate the number's kind (for example `pr close`
@ -172,7 +172,7 @@ hive-forge -r internal/knowledge pr-create --agit \
```
`clone` derives the dest dir from the repo basename (override with a
positional arg); `--branch` / `--depth` are passed through. The clone
positional arg); it passes `--branch` / `--depth` through. The clone
URL and the `origin` remote it leaves behind carry no credentials —
`clone` instead configures `origin`'s `credential.helper` to invoke
`hive-forge credential-helper` (a hidden verb, not meant to be run by
@ -224,8 +224,8 @@ scope. Two paths exist depending on where the repo should live:
**Agent repos (`agents/<name>`)** — Use the `mcp__hyperhive__create_repo`
MCP tool (requires the `forge` tool group). hive-c0re creates the repo in
the c0re-owned `agents/` org, adds you as a write collaborator (not
owner), and enables branch protection (operator-team merge approval
required — you can't self-merge). Clone URL is returned immediately.
owner), enables branch protection (operator-team merge approval
required — you can't self-merge), and returns the clone URL immediately.
This is the standard path for agents that need a working repo.
**Other repos** — Use the CLI verbs below (`repo-create` / `repo-add-collaborator`).
@ -245,8 +245,8 @@ and print its URL. Key flags:
active repo (see the repo-resolution chain above). Companion to
`repo-create`. The
`--permission` flag accepts `read` / `write` (default) / `admin`.
`hive-c0re` uses this internally when an agent's config repo is
initialised.
`hive-c0re` uses this internally when it initialises an agent's config
repo.
**`repo-labels [PATTERN]`** — list every label defined on the repo,
optionally filtered by a name substring (case-sensitive). Distinct from
@ -272,7 +272,7 @@ to discover valid label names before triaging or to audit the label set.
- `artifact-get <name> --run <n>` downloads a CI Actions artifact. `<n>`
is the run number from the run-page URL (`/actions/runs/<n>`, which
`pr-status` surfaces as a CI context's target_url). Forgejo 15 serves
artifacts only via the web route, not REST, and that route is keyed by
artifacts only via the web route, not REST, and keys that route by
the run's internal global id, so the verb translates the run number
first. Saves a zip to `/tmp/forge-artifact-<name>.zip` by default; pass
`-o -` to stream to stdout.
@ -280,9 +280,9 @@ to discover valid label names before triaging or to audit the label set.
run's job step logs. `<n>` is the run number from the run-page URL
(same value `artifact-get` takes; `pr-status` surfaces it as a CI
context's target_url). Two log sources, tried in **completeness
order**: the **durable persisted-log download** the run page's "view
order**: the verb tries the **durable persisted-log download** the run page's "view
raw logs" link uses (`…/runs/<n>/jobs/<job>/attempt/<a>/logs`, a flat
whole-job log) is tried first — complete once it exists, which covers
whole-job log) first — complete once it exists, which covers
any run that has already finished; it's only absent while the job is
still running, in which case the verb falls back to the web run-view
**streamer** the run page polls (rich per-step framing, but only a
@ -324,7 +324,7 @@ to discover valid label names before triaging or to audit the label set.
extra request per comment, no server-side inline count). `reaction
<n> --list-allowed` prints the instance's actual configured shortcode
list (`GET /settings/ui`'s `allowed_reactions`) instead of guessing —
instance-global, `<n>`/`--comment` are ignored on this path.
instance-global, this path ignores `<n>`/`--comment`.
- Do NOT use raw `curl` for forge access -- the CLI handles auth,
error checking, and output formatting.
- `issue-create --label <name>` / `pr-create --label <name>` are
@ -332,8 +332,8 @@ to discover valid label names before triaging or to audit the label set.
unknown name is an error, not a silent drop** — the command fails
listing the names that didn't resolve plus every label the repo has,
so it's fixable from the message without a second call. On
`pr-create --agit`, labels are applied as a follow-up call once the
PR number is parsed back out of the push output (the AGit push
`pr-create --agit`, hive-forge applies labels as a follow-up call once
it parses the PR number back out of the push output (the AGit push
itself has no label field), so they're silently skipped if that
parse fails — same fallback as the deferred multi-line body.
- `list --label <name>` / `list --milestone <name>` are repeatable and