# 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
