diff --git a/docs/comms-authority-map.md b/docs/comms-authority-map.md new file mode 100644 index 00000000..48837c35 --- /dev/null +++ b/docs/comms-authority-map.md @@ -0,0 +1,199 @@ +# Communication Authority Map + +Status: doctrine for #175 +Parent epic: #173 +Related issues: +- #165 NATS internal bus +- #166 Matrix/Conduit operator communication +- #174 Nostr/Nostur operator edge +- #163 sovereign keypairs / identity + +## Why this exists + +We do not want communication scattered across lost channels. + +The system may expose multiple communication surfaces, but work authority must not fragment with them. +A message can arrive from several places. +Task truth cannot. + +This document defines which surface is authoritative for what, how operator messages enter the system, and how Matrix plus Nostr/Nostur can coexist without creating parallel hidden queues. + +## Core principle + +One message may have many transport surfaces. +One piece of work gets one execution truth. + +That execution truth is Gitea. + +If a command or request matters to the fleet, it must become a visible Gitea artifact: +- issue +- issue comment +- PR comment +- assignee/label change +- linked proof artifact + +No chat surface is allowed to become a second hidden task database. + +## Authority layers + +### 1. Gitea — execution truth + +Authoritative for: +- task state +- issue ownership +- PR state +- review state +- visible decision trail +- proof links and artifacts + +Rules: +- if work is actionable, it must exist in Gitea +- if state changes, the change must be reflected in Gitea +- if chat and Gitea disagree, Gitea wins until corrected visibly + +### 2. NATS — internal agent bus + +Authoritative for: +- fast machine-to-machine transport only + +Not authoritative for: +- task truth +- operator truth +- final queue state + +Rules: +- NATS moves signals, not ownership truth +- durable work still lands in Gitea +- request/reply and heartbeats may live here without becoming the task system + +### 3. Matrix/Conduit — primary private operator command surface + +Authoritative for: +- private human-to-fleet conversation +- rich command context +- operational chat that should not be public + +Not authoritative for: +- final task state +- hidden work queues + +Rules: +- Matrix is the primary private operator room +- any command that creates or mutates work must be mirrored into Gitea +- Matrix can discuss work privately, but cannot be the only place where the work exists +- if a command remains chat-only, it is advisory, not execution truth + +### 4. Nostr/Nostur — sovereign operator edge + +Authoritative for: +- operator identity-linked ingress +- portable/mobile sovereign access +- public or semi-public notices if intentionally used that way +- emergency or lightweight operator signaling + +Not authoritative for: +- internal fleet transport +- hidden task state +- long-lived queue truth + +Rules: +- Nostur is a real operator layer, not a toy side-channel +- commands received via Nostr/Nostur must be normalized into Gitea before they are considered active work +- if private discussion is needed after Nostr ingress, continue in Matrix while keeping Gitea as visible task truth +- Nostr/Nostur should preserve sovereign identity advantages without becoming an alternate invisible work tracker + +### 5. Telegram — legacy bridge only + +Authoritative for: +- nothing new + +Rules: +- Telegram is legacy/bridge until sunset +- no new doctrine should make Telegram the permanent backbone +- if Telegram receives work during migration, the work still gets mirrored into Gitea and then into the current primary surfaces + +## Ingress rules + +### Rule A: every actionable operator message gets normalized + +If an operator message from Matrix, Nostr/Nostur, or Telegram asks for real work, the system must do one of the following: +- create a new Gitea issue +- append to the correct existing issue as a comment +- explicitly reject the message as non-actionable +- route it to a coordinator for clarification before any work begins + +### Rule B: no hidden queue mutation + +Refreshing a chat room, reading a relay event, or polling a transport must not silently create work. +The transition from chat to work must be explicit and visible. + +### Rule C: one work item, many mirrors allowed + +A message may be mirrored across: +- Matrix +- Nostr/Nostur +- Telegram during migration +- local notifications + +But all mirrors must point back to the same Gitea work object. + +### Rule D: coordinator-first survives transport changes + +Timmy and Allegro remain the coordinators. +Changing the transport does not remove their authority to: +- classify urgency +- decide routing +- demand proof +- collapse duplicates +- escalate only what Alexander should actually see + +## Recommended operator experience + +### Matrix +Use for: +- primary private conversation with the fleet +- ongoing task discussion +- handoff and clarification +- richer context than a short mobile note + +### Nostur +Use for: +- sovereign mobile/operator ingress +- identity-linked quick commands +- lightweight acknowledgements +- emergency input when Matrix is not the best surface + +Working rule: +- Nostur gets you into the system +- Matrix carries the private conversation +- Gitea holds the work truth + +## Anti-scatter policy + +Forbidden patterns: +- a task exists only in a Matrix room +- a task exists only in a Nostr DM or note +- a Telegram thread contains work nobody copied into Gitea +- different channels describe the same work with different owners or statuses +- an agent acts on Nostr/Matrix chatter without a visible work object when the task is non-trivial + +Required pattern: +- every meaningful task gets one canonical Gitea object +- all channels point at or mirror that object +- coordinators keep channel drift collapsed, not multiplied + +## Minimum implementation path + +1. Matrix/Conduit becomes the primary private operator surface (#166) +2. Nostr/Nostur becomes the sovereign operator edge (#174) +3. NATS remains internal bus only (#165) +4. every ingress path writes or links to Gitea execution truth +5. Telegram is reduced to bridge/legacy during migration + +## Acceptance criteria + +- [ ] Matrix, Nostr/Nostur, NATS, Gitea, and Telegram each have an explicit role +- [ ] Gitea is named as the sole execution-truth surface +- [ ] Nostur is included as a legitimate operator layer, not ignored +- [ ] Nostur/Matrix ingress rules explicitly forbid shadow task state +- [ ] this doctrine makes it harder for work to get lost across channels