060f325716
Sixth batch of the ongoing write-good.Passive pass (hyperhive#4042):
read all 52 hits across knowledge.md/github.md/matrix.md/forge.md in
context and rewrote 39 with a clearly nameable actor -- mostly
hive-c0re, forge_notify, or a specific fn named right there or a
sentence or two earlier. forge.md's notification poller is the
densest yet (19/20 hits rewritten): forge_notify is established as
the section's sole actor early and reused throughout, the shape
that's produced the highest catch rates all along.
Left 13 alone: the "no X is needed" negative-capability idiom (x2),
a container-lifecycle state descriptor ("when container is stopped"),
a false-positive tokenization ("read-only" split across a line wrap,
vale matches "is read" inside it -- not a real passive at all), the
"X can't be Yed" idiom, a generic "before the ids are minted" timing
clause with no natural actor to name, a room-join policy-state
descriptor, an "is enabled"/"is trusted" pair describing a config/
trust state (predicate-adjective-copula bucket, same family as
"is privileged" from an earlier batch), three "**X is required**"
bolded requirement-list labels (structural convention, not really
mid-sentence passives), and a contrastive "are shared" clause
mirrored against an active sibling clause exactly like
claude-invocation.md's "everything else is shared" from the
turn-loop batch -- left alone there for the same reason.
One sibling-inconsistency catch worth flagging: forge.md's merge-
racing-comment paragraph had two passive clauses ("is left off",
"is dropped") sitting next to a third, already-active clause
("appends nothing") in the same three-item parallel list -- rewrote
all three under one active subject (forge_notify) for consistency.
Verified via vale before/after: 52 -> 13 write-good.Passive hits,
exactly the 13 left alone above; error count and other warning
categories unchanged (still on TooWordy since #4097 hasn't merged to
this branch yet). Re-read every changed line in full surrounding
context after editing, matching the diff to intent before running
the final vale check.
142 lines
5.7 KiB
Markdown
142 lines
5.7 KiB
Markdown
# Hive-wide knowledge repository
|
|
|
|
`internal/knowledge` on the forge is a shared reference doc repo
|
|
readable by every agent. hive-c0re clones it to the host and
|
|
bind-mounts the clone read-only into every agent container at
|
|
`/knowledge`.
|
|
|
|
## Agent access
|
|
|
|
Inside any agent container:
|
|
|
|
```
|
|
/knowledge/ # read-only bind-mount of the local clone
|
|
/knowledge/README.md # table of contents (seeded on first use)
|
|
```
|
|
|
|
Agents read documents directly from that path. The mount is
|
|
read-only — agents never write through it. To contribute, use the
|
|
`hive-forge` AGit flow (no fork needed — see
|
|
[Contributing](#contributing)); the operator reviews and merges, and
|
|
the local clone updates automatically (see
|
|
[Sync mechanism](#sync-mechanism) below).
|
|
|
|
## Repository layout
|
|
|
|
Canonical forge location: `internal/knowledge` (org `internal`,
|
|
repo `knowledge`). The repo is public, so every agent's forge account
|
|
has read access without an explicit per-agent collaborator grant;
|
|
only the `core` account has push access, for autoseeding.
|
|
|
|
hive-c0re autocreates the repo at startup if it doesn't exist,
|
|
seeding it with a `README.md` containing a contribution guide and a
|
|
blank table of contents. Add an entry to that ToC each time you
|
|
create a new document.
|
|
|
|
## Sync mechanism
|
|
|
|
hive-c0re maintains the local clone at
|
|
`/var/lib/hyperhive/knowledge` via two paths:
|
|
|
|
1. **Swarm event** — the swarm controller holds the single push hook on
|
|
`internal/knowledge` (see `docs/swarm/README.md` § Swarm-wide forge
|
|
webhooks). On any push to main, including merge commits, it sends an
|
|
event to every hive over the swarm queue and each hive runs `git
|
|
pull`, so agents see the new content on their next turn.
|
|
|
|
A hive that's offline when the swarm controller sends the event
|
|
doesn't get it on reconnect — the periodic pull below is what closes that gap. One
|
|
hive briefly showing older `/knowledge` content than another is
|
|
expected, and resolves by itself within the fallback interval.
|
|
|
|
**don't add a per-hive hook.** A webhook has exactly one target
|
|
URL, so a second registration against the same repo doesn't add a
|
|
recipient — it takes delivery away from whoever registered first.
|
|
Earlier versions had each hive register its own; hive-c0re now
|
|
removes its own leftover at startup, so no operator step is needed
|
|
to migrate.
|
|
|
|
2. **Periodic pull** — a background task in `hive-c0re::main`
|
|
pulls on a fixed cadence as a fallback (webhook missed, c0re
|
|
restarted between pushes). The pull is best-effort — a failure
|
|
logs a warning and doesn't affect the rest of the daemon.
|
|
|
|
Both paths share the same `knowledge::pull()` function, which also
|
|
handles the change notice below — neither path can forget to wire it
|
|
in since the broadcast logic lives once, in `pull()` itself, not at
|
|
each call site.
|
|
|
|
### Change notice
|
|
|
|
When a pull actually moves the local clone's `HEAD` (a real change,
|
|
not a no-op — for example the periodic pull finding nothing new), hive-c0re
|
|
broadcasts a short notice to every currently registered agent's inbox:
|
|
sender `system`, body `[system] /knowledge updated:` followed by a
|
|
`git diff --stat <old>..<new>` summary of what changed (or a generic
|
|
"see the repo" fallback if computing the diff itself fails). This is
|
|
the same broadcast mechanism used for other hive-wide notices — inbox
|
|
message only, no forced wake, and it carries the standard "this was a
|
|
broadcast" hint. hive-c0re logs a diff or per-agent send failure
|
|
without blocking the pull itself.
|
|
|
|
`knowledge::ensure_local_clone` creates (or refreshes) the local
|
|
clone once at startup. If the repo is brand new and
|
|
empty, `ensure_local_clone` seeds it with the default README
|
|
before returning.
|
|
|
|
## State
|
|
|
|
- **Host clone**: `/var/lib/hyperhive/knowledge` — persists across
|
|
hive-c0re restarts and agent destroy/recreate. Deleted only by
|
|
manual operator action.
|
|
- **In-container mount**: `/knowledge` — bind-mounted read-only
|
|
from the host clone on every container start. Gone when container
|
|
is stopped; reappears on next start with the current clone state.
|
|
|
|
The mount deliberately **excludes `.git`**: the host clone embeds the `core`
|
|
token in `.git/config` (it rides the clone URL), so hive-priv overlays an empty
|
|
tmpfs at `/knowledge/.git` — agents see the documents, not the repo metadata or
|
|
token.
|
|
|
|
## Contributing
|
|
|
|
Agents have read access to `internal/knowledge` (it's public) but no
|
|
write access, so they can't push a branch directly. The supported path
|
|
is Forgejo's **AGit flow** through the `hive-forge` CLI — no fork
|
|
required.
|
|
|
|
1. Clone the repo (`hive-forge` injects credentials automatically;
|
|
the `-r` flag selects the repo, the clone lands in `./knowledge`):
|
|
|
|
```sh
|
|
hive-forge -r internal/knowledge clone
|
|
cd knowledge
|
|
```
|
|
|
|
2. Create a branch and add or update a document, then commit normally.
|
|
|
|
3. Open (or update) a PR with `--agit`. This pushes the current `HEAD`
|
|
to `refs/for/<base>/<topic>`, which Forgejo turns into a PR even
|
|
though you can't push a branch:
|
|
|
|
```sh
|
|
hive-forge -r internal/knowledge pr-create --agit \
|
|
--title "docs: add the X runbook" \
|
|
--topic add-x-runbook \
|
|
--body-file - <<'EOF'
|
|
What this document adds and why.
|
|
EOF
|
|
```
|
|
|
|
Re-running with the same `--topic` updates the open PR (it
|
|
force-pushes the AGit scratch ref). The base defaults to `main`;
|
|
in `--agit` mode the push goes to the `origin` remote that
|
|
`hive-forge clone` set up.
|
|
|
|
4. The operator reviews and merges. The webhook fires on merge; every
|
|
running container sees the updated content within seconds (see
|
|
[Sync mechanism](#sync-mechanism)).
|
|
|
|
Do **not** try to `git push` a branch directly — lacking write access,
|
|
it's rejected. The `--agit` flow above is the no-fork path that works
|
|
from any agent.
|