docs: fix genuine passive-voice hits in docs/process

Fourth batch of hyperhive#4042's Passive pass (see #4098/#4099/#4100
for the first three and the read-every-hit discipline this pass
uses). 44 hits across pr-review-gate.md (4), conventions.md (18), and
gotchas.md (22) -- highest genuine-catch rate so far, 23/44 (~52%),
because this architecture/mechanism documentation has a lot of "X
does Y via Z" sentences where the actor is already named
parenthetically or in a nearby clause -- the single most productive
rewrite shape across every batch so far.

Recurring rewrite shapes this batch:
- Actor already named in the same sentence, just not as the
  grammatical subject: "X is configured per repo in its
  branch-protection settings" -> "Each repo's branch-protection
  settings configure X" (pr-review-gate.md); "the broker" (reserved
  names), "rsvg-convert" (PNG rendering), "the website repo" (HTML/CSS
  rendering), "systemd.globalEnvironment" (D-Bus address export), and
  several more -- all the same shape.
- Subject already established one clause or one sentence earlier,
  just needs continuing rather than restarting with a new passive
  subject: "the harness reads HIVE_TOOL_GROUPS (...). Unrecognised
  tokens are logged and skipped." -> "...logging and skipping
  unrecognised tokens" (continues "the harness"), same pattern twice
  more (job_queue::templates::rebuild, HIVE_CAPABILITIES resolution).
- Sibling-inconsistency: a bolded lead-in bullet was the one passive
  sentence in an otherwise-active paragraph/table (the
  read_host_journal capability row sat between two "may X" rows; the
  HTML+CSS bullet's own tail clauses were already active voice around
  the one passive lead phrase).
- One caught-and-fixed authoring mistake worth noting for future
  passes: the first attempt at the "Nix treats X as a package" rewrite
  landed in the wrong sentence (a similarly-worded but unrelated
  passage two paragraphs up) -- caught by re-reading the diff before
  running vale, not by vale itself (which would have shown 0 remaining
  hits either way, since the intended sentence's hit just wouldn't
  have been touched -- a silently-wrong edit vale's own count can't
  catch). Re-reading the actual diff, not just trusting the before/
  after hit count, is what caught it.

21 of 44 left alone -- same recurring legitimate shapes as prior
batches (predicate-adjective copulas, quoted/literal text, generic-
actor statements, negative-capability invariants, "is tracked/rooted/
scoped at X" property-description idioms, and two more thesis-
statement headings matching the "Ownership is declared, not repaired"
precedent from #4100).

Verified: vale docs/process before/after -- 44 -> 21 write-good.Passive
hits, exactly the 23 rewritten, re-read every changed line's full
surrounding context after editing (not just the vale count) to catch
exactly the kind of misplaced-edit mistake described above.
This commit is contained in:
iris 2026-09-08 12:24:03 +02:00
commit c41c67c949
3 changed files with 37 additions and 38 deletions

View file

@ -6,9 +6,9 @@ human review that already happened.
## The gate has (up to) three parts, and they're per-repo settings
Whether a PR can merge, and what counts toward "can," is configured
per repo in its branch-protection settings — not a fact true of every
hive or every repo. The pieces a repo _can_ require:
Each repo's branch-protection settings configure whether a PR can
merge, and what counts toward "can" — not a fact true of every hive or
every repo. The pieces a repo _can_ require:
- **CI is green** — the repo's required status checks pass on the
PR's current head commit, if the repo requires any.
@ -21,7 +21,7 @@ hive or every repo. The pieces a repo _can_ require:
(merges automatically the moment the other required conditions are
met).
Where these are required, they're independent of each other. A
Where a repo requires these, they're independent of each other. A
reviewer only ever owns the review-approval piece — CI resolves (or
doesn't) on its own regardless of what a review says, and merge-arming
is someone else's call.