hive-ag3nt + docs: extract forge_notify prose (#716 batch 4)

forge_notify.rs is the biggest remaining #716 hotspot: ~22 attribution
cookies (#110 #230 #231 #253 #256 #455 #518 #539 #544) plus a thick
module-level docstring + per-function rationale blocks for the
notification pipeline. The substantive prose lives in a new
`docs/forge.md` covering the wider forge integration story:

- Per-agent forge accounts + agent-configs mirror (was implicit
  across `hive-c0re/src/forge.rs` rustdocs).
- Notification poller: activation gates, self-notification filtering,
  body excerpt + truncation + ATX heading escape pipeline, wrapper
  formats (comment / review / new-item / state-change) with shape
  table, meta suffix shape, review-request override, reason
  drop-list rationale (drop vs allow), auto-unsubscribe on broad
  watches.

In-code rustdocs reduced to 1-line semantic summaries + doc
pointers; inline cookie comments scrubbed. Net diff is ~150 lines
removed from the .rs file. All 16 forge_notify unit tests pass.

CLAUDE.md gets a new `docs/forge.md` file-map entry + reading-path
question entry. The existing `src/forge_notify.rs` file-map blurb
keeps its `(#539 / #544)` cookie — consistent with the rest of
CLAUDE.md's lineage attributions.
This commit is contained in:
iris 2026-05-31 17:11:01 +02:00 committed by mara
commit 76d3267b55
3 changed files with 277 additions and 149 deletions

View file

@ -308,6 +308,10 @@ docs/
damocles-migration.md future migration plan for damocles → hyperhive
gateway.md nginx vhost map, matrix discovery flow, firewall posture,
HIVE_FORGE_URL loopback rationale (#764, #772, #793)
forge.md per-agent forge accounts + agent-configs mirror;
forge_notify poller (gates, self-filter, body excerpt
pipeline, wrapper formats, reason drop-list,
auto-unsubscribe)
matrix.md matrix container shape, serverName/gatewayHost split,
firewall + federation, provisioning flow, fluffychat-web build
network.md host-side bridge + dnsmasq resolver, v1/v2 roadmap,
@ -335,6 +339,9 @@ read them à la carte.
[`docs/gotchas.md`](docs/gotchas.md).
- **"What nginx vhosts does the gateway serve? How does matrix
discovery work?"** → [`docs/gateway.md`](docs/gateway.md).
- **"How do per-agent forge accounts work? What does forge_notify
poll + how does it format wake messages?"** →
[`docs/forge.md`](docs/forge.md).
- **"How does the matrix-tuwunel container work? What about
fluffychat-web and per-agent matrix accounts?"** →
[`docs/matrix.md`](docs/matrix.md).