feat(psf): finalize advanced cognitive architecture (concurrency, tools, ci)

notes/org-skill-inbound-gateway.org

@@ -0,0 +1,75 @@
+#+TITLE: SKILL: Inbound Multi-Channel Gateway (Universal Literate Note)
+#+ID: skill-inbound-gateway
+#+STARTUP: content
+#+FILETAGS: :gateway:sensors:io:psf:
+
+* Overview
+The **Inbound Multi-Channel Gateway** provides the sensory interface for external messaging. It enables the agent to "hear" the user from various platforms (Signal, Telegram, SMS) by normalizing disparate inbound payloads into standard Neurosymbolic Kernel stimuli.
+
+* Phase A: Demand (PRD)
+:PROPERTIES:
+:STATUS: FROZEN
+:END:
+
+** 1. Purpose
+Define a secure and extensible ingress for external communication channels.
+
+** 2. User Needs
+- **Multi-Channel Ingress:** Support Signal (via signal-cli), Telegram (via Bot API), and generic Webhooks.
+- **Payload Normalization:** Convert platform-specific JSON into standard Lisp plists.
+- **Security & Authentication:** Verify sender identity before injecting stimuli into the kernel.
+- **Asynchronous Reception:** Non-blocking monitoring of inbound message queues.
+
+** 3. Success Criteria
+*** TODO Signal-cli message reception and parsing
+*** TODO Telegram Bot API webhook normalization
+*** TODO Sender verification logic (Whitelisting)
+*** TODO Autonomous stimulus injection into the Kernel Bus
+
+* Phase B: Blueprint (PROTOCOL)
+:PROPERTIES:
+:STATUS: SIGNED
+:END:
+
+** 1. Architectural Intent
+Interfaces for external sensory perception. Source of truth is the external API callbacks and local messaging daemons.
+
+** 2. Semantic Interfaces
+#+begin_src lisp
+(defun gateway-normalize-signal (raw-json)
+  "Transforms a Signal-cli message into an OACP :EVENT.")
+
+(defun gateway-normalize-telegram (raw-json)
+  "Transforms a Telegram Bot payload into an OACP :EVENT.")
+
+(defun gateway-verify-sender (sender-id channel)
+  "Ensures the message is from an authorized recipient.")
+#+end_src
+
+* Phase D: Build (Implementation)
+
+** Normalization Logic
+#+begin_src lisp :tangle projects/org-skill-inbound-gateway/src/gateway-logic.lisp
+(defun gateway-verify-sender (sender-id channel)
+  (let ((approved (uiop:getenv "RECIPIENT_ID")))
+    (string= sender-id approved)))
+
+(defun gateway-normalize-signal (raw-json)
+  (let* ((data (cl-json:decode-json-from-string raw-json))
+         (sender (cdr (assoc :source data)))
+         (text (cdr (assoc :message data))))
+    (if (gateway-verify-sender sender :signal)
+        `(:type :EVENT :payload (:sensor :inbound-message :channel :signal :text ,text))
+        (progn
+          (kernel-log "GATEWAY - Rejected message from unauthorized sender: ~a" sender)
+          nil))))
+#+end_src
+
+* Registration
+#+begin_src lisp
+(defskill :skill-inbound-gateway
+  :priority 100 ; High-priority sensory input
+  :trigger (lambda (context) nil) ; Triggered by external sensors (Signal/Web)
+  :neuro (lambda (context) nil)
+  :symbolic (lambda (action context) action))
+#+end_src