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:
parent
3ff61e49b8
commit
97e2a993e3
6 changed files with 49 additions and 49 deletions
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Reference in a new issue