vinzenz/hyperhive
vinzenz/hyperhive
Watch
0
0
Fork
You've already forked hyperhive
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 2

docs: suppress reviewed write-good.Passive false positives

Browse source 
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
Download patch file Download diff file Expand all files Collapse all files

18
docs/process/gotchas.md
View file

@ -93,6 +93,8 @@ Two things to get right when a daemon needs outbound TCP:
enumerate local addresses before it returns any, so name resolution
fails without it even when the unit allows `AF_INET`.
<!-- vale write-good.Passive = NO -->
**The directive is a claim about what the program does, and nothing
re-checks it when the program changes.** A unit that only served a unix
socket when it was written is correct at `[ "AF_UNIX" ]` and silently wrong
@ -101,6 +103,8 @@ the client — and when narrowing it, prefer a test that derives the required
families from the code (which fails on the _next_ client too) over one that
asserts today's list.
<!-- vale write-good.Passive = YES -->
### `register_agent` is idempotent
Drops any prior socket task before rebinding. Required so a
@ -114,7 +118,7 @@ socket without needing a clean reinstall.
`claude-code` comes from the flake's main `nixpkgs` (nixos-26.05).
It's unfree, so the agent modules set `config.allowUnfreePredicate`
at the container level to allowlist `claude-code` specifically —
scoped, only this one package. This is needed because each per-agent
scoped, only this one package, because each per-agent
`nixosConfiguration` evaluates its own nixpkgs instance and the
operator's host-level `allowUnfree` does **not** propagate in.
Operators don't need to set anything on their side.
@ -138,6 +142,8 @@ reference-less `-source` (so the runtime closure never arrives), and
pure evaluation rejects. `services.hyperhive.agent.docs.source` gets away with being
an input only because a docs tree has no runtime dependencies.
<!-- vale write-good.Passive = NO -->
The `storePath` trap is worth spelling out, because it's not confined
to options the operator writes: **any** option of type `package` fed a
store-path _string_ coerces through `lib.toDerivation`, i.e.
@ -149,6 +155,10 @@ container as text in a real derivation — a symlink farm built from
the interpolated string — before it can go anywhere a package is
expected.
<!-- vale write-good.Passive = YES -->
<!-- vale write-good.Passive = NO -->
The catch is that a path written into a generated flake is text, not a
reference — the container's closure doesn't keep the binary alive.
The **host** does: it interpolates the package into
@ -160,6 +170,8 @@ the hive's `claude` out from under it. The price of the root is that
`nix-collect-garbage` can't reclaim an old `claude-code` until every
agent has rebuilt past it and the old generations are gone.
<!-- vale write-good.Passive = YES -->
### Claude credentials are per-agent
`/var/lib/hyperhive/agents/<name>/claude/` bind-mounts to
@ -315,6 +327,8 @@ CI on drift).
### Split asset derivations away from the rust workspace
<!-- vale write-good.Passive = NO -->
`nix/packages/assets.nix` builds the branding SVG/PNG family + claude
system-prompt template + claude-settings JSON as its own derivation,
separate from the hive-ag3nt / hive-c0re crates. Reason: when the
@ -327,6 +341,8 @@ its own — the split breaks the coupling at the derivation boundary.
build time; librsvg dependency lives here, not in the rust
derivation's `nativeBuildInputs`.
<!-- vale write-good.Passive = YES -->
### `nix fmt` fails in a git worktree with "object not found"
`nix fmt` (and any `nix` command that fetches a `git+file://` flake