Files
skills/docs/requirements/005-radio-receipts-inline.md
T
Kevin Veen-BirkenbachandClaude Opus 5.5 30b2a32095 feat(orchestrator): radio receipts inline (005 phase B)
Requirement 005: every radio message in the Stream and the radio log shows the avatars of the agents that read it, with read time and an ack badge where a receipt exists; receipt rows no longer appear as entries of their own, and the sender shows once. Read times come from seen marks, stamped only after a fresh presence pass no older than two sighting intervals; a stored time before its row is refused. An operator message links to its relay row through the ts radio.py prints first on stdout right after store(), checked against an exact row (sender Operator, relay text, targets, no to_sessions); a ts shared by two rows shows no readers. radio.py clips printed addresses; the hub keeps the first stdout line whole. Accepted MEDUSA false positives: MM-SCAN-058 at server.py:73, JB-SCAN-641 and JB-SCAN-616 at radio.py:389 (clip, the output sanitizer), FLA-SCAN-055 at radio.py:109. Committed below the 90/5 bar on the operator's word; the receipts e2e runs through the queue.

🎯 Fix: 89 %
💥 Break: 6 %
💸 Cost: –
⏱️ Time: –
🛡️ Security: 100 %
🏆 Score: 84
🚦 Gate: ⛔ fix 89 % < 90, break 6 % > 5

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-13 17:19:39 +00:00

89 lines
3.9 KiB
Markdown

# 005 - Radio Receipts Inline
## User Story
As the operator, I want every radio message to show who read it and who
acknowledged it right under the message, so that I see delivery at a glance
without a second row repeating the same text.
## Decisions (operator-confirmed 2026-11-13; do not re-litigate)
1. **Read for all, ack where it exists**: under every message of every class
(post, call, newsletter, broadcast, mayday, pan-pan, sécurité, grant) the
avatars of the agents that read it, from the seen marks `radio.py` keeps
per session (`radio-seen/<sid>.json`, `news-seen/<sid>`); an avatar gets an
acknowledged badge when that agent's receipt for the message exists.
Rejected: an explicit acknowledgement for every class (one radio action
per agent and message, more tokens); read only (loses the call's
acknowledgement).
2. **No receipt rows**: receipts no longer show as entries in the Stream, the
radio log or an agent page; they only feed the badges. Rejected: a
collapsed receipt row (still a second entry).
3. **One read rule**: the hub decides "read" with the same function
`radio.py` uses to decide what a session has seen; no second copy in the
hub.
4. **Sender once**: a message header names its sender exactly once (today
"Skills Skills → Main").
5. **Order**: the shared seen function and a new hub module for readers and
acks may start at once; wiring into the hub view and the page starts after
004 (radio set) is on master, since both change the radio log.
## Approach
```mermaid
flowchart TD
subgraph P["🧭 0 · Preparation"]
P1["📋 Write requirement"] --> P2{"✅ Operator approves?"}
P2 -- "✏️ corrections" --> P1
end
P2 -- "🤖 yes" --> A1
subgraph A["🛰️ A · Server"]
A1["🧩 Shared seen function, readers and acks per row"] --> A2{"🧪 Unit and integration green?"}
A2 -- "🔴 no: fix" --> A1
end
A2 -- "🟢 yes, 004 on master" --> B1
subgraph B["🖼️ B · Page"]
B1["👥 Avatars and badges, no receipt rows, sender once"] --> B2{"🧪 E2E green?"}
B2 -- "🔴 no: fix" --> B1
B2 -- "🟢 yes" --> BF{"💬 Operator feedback on screenshots?"}
BF -- "✏️ changes" --> B1
end
BF -- "👍 fits" --> D1["🏁 Review, commit with operator OK, hand-over"]
```
## Acceptance Criteria
### Server
- [x] Each radio row the hub serves carries `readers` (session id, name, read
time) and `acks` (session ids), computed by the function `radio.py`
uses for its own seen check; a unit test covers every class.
- [x] A receipt counts for its call when the call is served, even if the
receipt row lies outside the served window.
- [x] A missing, malformed, unreadable or future-dated seen mark counts as
not read.
- [x] Receipt rows are absent from the rows served to the Stream, the radio
log and agent pages; count badges count messages without receipts.
### Page
- [ ] Under each message one avatar per reader, an acknowledged badge on
readers with a receipt, name and read time in the avatar's title.
- [ ] More than 8 readers collapse into "+N" with the full list on hover.
- [ ] The e2e count of entries with the class pill "Read" is 0 in the
Stream, the radio log and an agent page.
- [ ] The message header shows the sender name exactly once.
- [ ] Avatars appear on the next poll after a mark advances, without a
reload.
### Tests
- [x] Unit: readers and acks per class; malformed marks; receipt to call
matching by call time; the header renders the sender once.
- [x] Integration: the hub state endpoint over a council fixture (posts,
calls, broadcasts, receipts, seen marks) returns readers and acks and
no receipt rows.
- [ ] E2E: Chromium and Firefox at 1920, 1366 and 390: a call with two
readers and one receipt shows two avatars, one with the badge, no
"Read" entry and the sender once; screenshots for the checkpoint.