[COMMS] define layered channel authority map with Matrix + Nostur + Gitea truth (#176)
This commit was merged in pull request #176.
This commit is contained in:
199
docs/comms-authority-map.md
Normal file
199
docs/comms-authority-map.md
Normal file
@@ -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
|
||||
Reference in New Issue
Block a user