From efbfeb39545e05f6a5170b3dca5e633c984a0bfb Mon Sep 17 00:00:00 2001 From: atlas Date: Wed, 2 Sep 2026 22:53:47 +0200 Subject: [PATCH] docs: say what these things are, not where they used to be mara on #3923: "past tense is itself a smell for docs, we dont need any 'used to be somewhere else'" and "any gate we add should not have false positives". Those are one instruction: the entire false-positive set of a repo-path checker was prose naming files that are deliberately gone, so removing the prose is what lets the gate be strict instead of carrying a skip-list nobody maintains. Three sites, and only two of them are past tense: `agent-hierarchy.md` named two removed modules to explain that a code path is gone. A reader cannot act on where it used to live; they can act on where cancellation happens now, which is the half the sentence buried. `term_msg.rs` carried a "Design history" paragraph whose live content was three rules -- classification is server-side, `level` carries styling, four named fields are deliberately absent -- wrapped in narration about a redesign and a pointer to a deleted frontend file. Restated as the rules. `gotchas.md` is NOT past tense: it correctly names a file in the website repo. Qualifying it as `hyperhive/website:nix/options.nix` did not work -- the extractor still matches `nix/options.nix` as a substring, so the fix has to be prose that contains no repo-relative path at all. Naming the file alone does that and reads better. Verified against this tree rather than the default checkout: the audit script takes a directory argument and defaults elsewhere, so its first (unchanged) DEAD:3 was a true statement about a different branch. On this one: DEAD 3 -> 0, 141 distinct paths enumerated, and an injected dead path is still caught. Refs #3923 --- docs/agent-lifecycle/agent-hierarchy.md | 8 +++----- docs/process/gotchas.md | 2 +- hive-agent/src/term_msg.rs | 14 ++++++-------- 3 files changed, 10 insertions(+), 14 deletions(-) diff --git a/docs/agent-lifecycle/agent-hierarchy.md b/docs/agent-lifecycle/agent-hierarchy.md index 425ef6d0..c1afebcb 100644 --- a/docs/agent-lifecycle/agent-hierarchy.md +++ b/docs/agent-lifecycle/agent-hierarchy.md @@ -155,11 +155,9 @@ Manager}` switch picks the MCP tool allow-list claude sees. Both are ancestor/descendant check instead of a manager-name check — see the module docs for `loose_ends.rs`, `stores/broker.rs`, `actions.rs`, and `workers/crash_watch.rs` for the current owner-check logic in - each. (Question/answer routing and its own manager-override cancel - path — formerly `hive-c0re/src/questions.rs` and - `stores/operator_questions.rs` — has been removed entirely; reminder - cancellation is now handled fully in-agent, see the note on - `CancelLooseEndKind::Reminder` in `hive-c0re/src/socket_server/mod.rs`.) + each. (Reminder cancellation is handled fully in-agent — see the note + on `CancelLooseEndKind::Reminder` in + `hive-c0re/src/socket_server/mod.rs`.) None of the above is a stable interface — treat the module doc comments as the source of truth for exactly which checks exist today. diff --git a/docs/process/gotchas.md b/docs/process/gotchas.md index 875ccbdb..a3fb9c33 100644 --- a/docs/process/gotchas.md +++ b/docs/process/gotchas.md @@ -472,7 +472,7 @@ Pipeline: - CommonMark from `nixosOptionsDoc.optionsCommonMark` is the only output — the source of truth, emitted as `.md`. - **HTML + CSS is rendered downstream by the website repo** - (`nix/options.nix` there), which consumes this bundle's `host.md` / + (its own `options.nix`), which consumes this bundle's `host.md` / `agent.md`, renders them with `cmark-gfm`, and shares one stylesheet (`docs.css`) across `/options/` and the prose `/docs/` tree. Keeping rendering in the website means the theme has a single diff --git a/hive-agent/src/term_msg.rs b/hive-agent/src/term_msg.rs index df4da3d7..193d2d75 100644 --- a/hive-agent/src/term_msg.rs +++ b/hive-agent/src/term_msg.rs @@ -10,14 +10,12 @@ //! `stream-json` line) can expand to several: an `assistant` message with //! both a text block and a `tool_use` block produces two rows. //! -//! Design history: mara's terminal-message redesign (six rounds of -//! negotiation on the forge) collapsed what was an 11-field frontend-side -//! row shape (`StreamRow`, `frontend/packages/agent/src/lib/streamRow.ts`) -//! plus raw claude-JSON passthrough into this 6-field shape, with -//! classification moved server-side so the client-side `classifyEvent.ts` — -//! a large per-tool dispatch table — mostly goes away. `kind`, `unread`, -//! `from`, and `expanded_default` were all considered and dropped along the -//! way; `level` replaces free-text CSS-class styling. +//! Six fields, and classification belongs **here**, not in the client: the +//! web UI renders what it is handed and owns no per-tool dispatch table, so +//! a new tool needs no frontend change. `level` carries styling, so a row +//! never names a CSS class. `kind`, `unread`, `from` and `expanded_default` +//! are deliberately absent — adding one back is a design change, not an +//! oversight. use serde::Serialize; use std::collections::HashMap;