# Nostur Operator Edge

Status: doctrine and implementation path for #174
Parent epic: #173
Related issues:
- #166 Matrix/Conduit primary operator surface
- #175 Communication authority map
- #165 NATS internal bus
- #163 sovereign keypairs / identity

## Goal

Make Nostur a real operator-facing layer for Alexander without letting Nostr become a shadow task system.

Nostur is valuable because it gives the operator a sovereign, identity-linked mobile surface.
That does not mean Nostr should become the place where work lives.

## Design rule

Nostur is an ingress layer.
Gitea is execution truth.
Matrix is the private conversation surface.
NATS is internal transport.

If a command originates in Nostur and matters to the fleet, it must be normalized into Gitea before it is treated as active work.

## What Nostur is for

Use Nostur for:
- sovereign mobile operator access
- identity-linked quick commands
- acknowledgements and nudges
- emergency ingress when Matrix is unavailable or too heavy
- public or semi-public notes when intentionally used that way

Do not use Nostur for:
- hidden task queues
- final assignment truth
- long private operator/fleet discussion when Matrix is available
- routine agent-to-agent transport

## Operator path

### Path A: quick command from Nostur

Example intents:
- "open issue for this"
- "reassign this to Allegro"
- "summarize status"
- "mark this blocked"
- "create follow-up from this note"

Required system behavior:
1. accept Nostur event / DM from an authorized operator identity
2. verify identity against the allowed sovereign key set
3. classify message as one of:
   - advisory only
   - actionable command
   - ambiguous / requires clarification
4. if actionable, translate it into one canonical Gitea object:
   - new issue
   - comment on existing issue
   - explicit state mutation on an existing issue/PR
5. send acknowledgement back through Nostur with a link to the Gitea object
6. if private discussion is needed, continue in Matrix and point both sides at the same Gitea object

### Path B: status read from Nostur

For simple mobile reads, allow:
- current priority queue summary
- open blockers
- review queue summary
- health summary
- links to active epic/issues/PRs

These are read-only responses.
They do not mutate work state.

### Path C: public or semi-public edge

If Nostr is used publicly:
- never expose hidden internal queue truth
- publish only intentional summaries, announcements, or identity proofs
- public notes must not become a side-channel task system

## Ingress contract

For every actionable Nostur message, the bridge must emit a normalized ingress record with:
- source: nostr
- operator identity: npub or mapped principal identity
- received_at timestamp
- original event id
- normalized intent classification
- linked Gitea object id after creation or routing
- acknowledgement state

This record may live in logs or a small bridge event store, but the work itself must live in Gitea.

## Auth and identity

Nostur ingress should rely on sovereign key identity, not platform-issued bot identity.

Minimum model:
- allowlist of operator npubs
- optional challenge/response for higher-trust actions
- explicit mapping from operator identity to allowed command classes

Suggested command classes:
- read-only
- issue creation
- issue comment / note append
- assignment / routing request
- high-authority mutation requiring confirmation

The bridge must fail closed for unknown keys.

## Bridge behavior

The Nostur bridge should be small and stupid.

Responsibilities:
- receive event / DM
- authenticate sender
- normalize intent
- write/link Gitea truth
- optionally mirror conversation into Matrix
- return acknowledgement

Responsibilities it must NOT take on:
- hidden queue management
- second task database
- silent assignment logic outside coordinator doctrine
- freeform agent orchestration directly from relay chatter

## Recommended implementation sequence

### Step 1
Build read-only Nostur status responses.

Acceptance:
- Alexander can ask for status from Nostur
- response comes back with links to the canonical Gitea objects
- no queue mutation yet

### Step 2
Add explicit issue/comment creation from Nostur.

Acceptance:
- a Nostur command can create a new Gitea issue or append to an existing one
- acknowledgement message includes the issue URL
- no hidden state remains only in Nostr

### Step 3
Add Matrix handoff for private follow-up.

Acceptance:
- after Nostur ingress, the system can point the operator into Matrix for richer back-and-forth while preserving the same Gitea work object

### Step 4
Add authority tiers and confirmations.

Acceptance:
- low-risk actions can run directly
- higher-risk actions require explicit confirmation
- command classes are keyed to operator identity policy

## Non-goals

- replacing Matrix with Nostur for all private operator conversation
- using Nostr for the internal fleet bus
- letting relay notes replace issues, PRs, or review artifacts

## Operational rule

Nostur should make the system more sovereign and more convenient.
It must not make the system more ambiguous.

If Nostur ingress creates ambiguity, the bridge is wrong.
If it creates a clean Gitea-linked work object and gives Alexander a mobile sovereign edge, the bridge is right.

## Acceptance criteria

- [ ] Nostur has an explicit role in the stack
- [ ] Nostr ingress is mapped to Gitea execution truth
- [ ] read-only versus mutating commands are separated
- [ ] the bridge is defined as small and transport/ingress-focused
- [ ] the doc makes it impossible to justify shadow task state in Nostr
