From 1b5e31663ed497473d38cb0e1559cc76ad484379 Mon Sep 17 00:00:00 2001 From: Timmy Time Date: Sat, 4 Apr 2026 22:46:55 +0000 Subject: [PATCH] [COMMS] define Nostur operator edge and Nostr ingress path (#177) --- README.md | 4 + docs/nostur-operator-edge.md | 187 +++++++++++++++++++++++++++++++++++ 2 files changed, 191 insertions(+) create mode 100644 docs/nostur-operator-edge.md diff --git a/README.md b/README.md index c01a70a4..7a5346fe 100644 --- a/README.md +++ b/README.md @@ -51,6 +51,10 @@ The scripts in `bin/` are sidecar-managed operational helpers for the Hermes lay Do NOT assume older prose about removed loops is still true at runtime. Audit the live machine first, then read `docs/automation-inventory.md` for the current reality and stale-state risks. + +For communication-layer truth, read: +- `docs/comms-authority-map.md` +- `docs/nostur-operator-edge.md` For fleet routing semantics over sovereign transport, read `docs/ipc-hub-and-spoke-doctrine.md`. diff --git a/docs/nostur-operator-edge.md b/docs/nostur-operator-edge.md new file mode 100644 index 00000000..9d59a892 --- /dev/null +++ b/docs/nostur-operator-edge.md @@ -0,0 +1,187 @@ +# 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