hive-forge: state the read-state contract in the guard docs
This commit is contained in:
parent
e59e41ec90
commit
4a109fa038
3 changed files with 16 additions and 15 deletions
|
|
@ -260,9 +260,10 @@ to discover valid label names before triaging or to audit the label set.
|
||||||
|
|
||||||
<!-- vale write-good.Passive = NO -->
|
<!-- vale write-good.Passive = NO -->
|
||||||
- **Read-before-comment guard:** `comment` refuses to post when forge still
|
- **Read-before-comment guard:** `comment` refuses to post when forge still
|
||||||
has an unread notification for the thread (that is, someone commented since
|
has an unread notification for the thread. `hive-forge-notify` marks a
|
||||||
you last read it). This prevents accidentally replying to old activity without
|
thread read when it delivers it as a todo, so the guard catches only
|
||||||
seeing the new context. Read the thread with `hive-forge view <n>` or
|
activity newer than the last delivery (one 30 s poll) and threads whose
|
||||||
|
delivery failed. Read the thread with `hive-forge view <n>` or
|
||||||
`hive-forge comments <n>` (which mark the notification read and clear the
|
`hive-forge comments <n>` (which mark the notification read and clear the
|
||||||
block), or pass `--force` to skip the guard.
|
block), or pass `--force` to skip the guard.
|
||||||
- `comment --body "..."` with backticks in the body: always use
|
- `comment --body "..."` with backticks in the body: always use
|
||||||
|
|
|
||||||
|
|
@ -1,16 +1,14 @@
|
||||||
//! Read-before-comment guard backed by forge's own notification
|
//! Read-before-comment guard backed by forge's own notification
|
||||||
//! read-state — no local mirror (which drifts across restarts).
|
//! read-state — no local mirror (which drifts across restarts).
|
||||||
//!
|
//!
|
||||||
//! When someone comments on an issue/PR the caller participates in,
|
//! `hive-forge-notify` marks a thread read on forge as soon as it delivers
|
||||||
//! forge raises an unread notification for that thread; once the agent
|
//! the thread to the agent as a todo, so the todo carries the news and
|
||||||
//! actually reads the thread (`comments` / `view`) we mark it read via
|
//! forge's unread flag does not wait for the agent to open the thread.
|
||||||
//! the notifications API. So "is there unread activity here?" is just
|
//! "Unread activity here" is therefore "forge still has an unread
|
||||||
//! "does forge still have an unread notification for this thread?" —
|
//! notification for this thread": activity newer than the last delivery
|
||||||
//! forge is the single source of truth, nothing to lose on restart.
|
//! (the poll interval, about 30 s) and threads whose delivery failed.
|
||||||
//!
|
//! Reading a thread (`comments` / `view`) also marks its notification
|
||||||
//! (This pairs with the `forge_notify` harness change that stops
|
//! read, so the guard clears for a thread the agent opens itself.
|
||||||
//! marking notifications read on wake *delivery* — issue tracker
|
|
||||||
//! `forge cli: agents keep commenting without reading prev comments`.)
|
|
||||||
|
|
||||||
use anyhow::Result;
|
use anyhow::Result;
|
||||||
use forge_client::NotificationThread;
|
use forge_client::NotificationThread;
|
||||||
|
|
|
||||||
|
|
@ -2,8 +2,10 @@
|
||||||
//! issue or PR.
|
//! issue or PR.
|
||||||
//!
|
//!
|
||||||
//! Read-before-comment guard: before posting, refuse when forge still
|
//! Read-before-comment guard: before posting, refuse when forge still
|
||||||
//! has an unread notification for the thread — i.e. someone commented
|
//! has an unread notification for the thread. `hive-forge-notify` marks
|
||||||
//! since the caller last read it. Reading the thread
|
//! a thread read when it delivers it as a todo, so this only catches
|
||||||
|
//! activity newer than the last delivery (about one 30 s poll) and
|
||||||
|
//! threads whose delivery failed. Reading the thread
|
||||||
//! (`hive-forge comments <n>` / `view <n>`) marks the notification read
|
//! (`hive-forge comments <n>` / `view <n>`) marks the notification read
|
||||||
//! and clears the block; `--force` overrides. The unread signal is
|
//! and clears the block; `--force` overrides. The unread signal is
|
||||||
//! forge's own notification read-state, not a local mirror — see
|
//! forge's own notification read-state, not a local mirror — see
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue