200 lines
6.1 KiB
Markdown
200 lines
6.1 KiB
Markdown
# 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
|