FEAT: Implement Telegram Gateway and Channel-Aware Chat

docs/rca/rca-gateway-telegram.org

@@ -0,0 +1,43 @@
+#+TITLE: Root Cause Analysis: Telegram Gateway & Channel-Aware Chat
+#+DATE: 2026-04-11
+#+FILETAGS: :rca:gateway:telegram:chat:psf:
+
+* Executive Summary
+Successfully implemented the first external communication channel (Telegram) and decoupled the Chat Agent from its Emacs-centric roots. Resolved significant load-order and dependency issues identified during integration.
+
+* 1. Issue: Undefined Foundational Functions
+** Symptoms
+During compilation, `gateway-telegram.lisp` failed with `UNDEFINED-FUNCTION` for `register-actuator` and `kernel-log`.
+** Root Cause
+Poorly scoped foundational functions. These were defined in `core.lisp` (the loop orchestrator), which was loaded *after* the gateways in `org-agent.asd`. This created a "Circular Intention" where the gateways needed the kernel to exist before the kernel could load the gateways.
+** Resolution
+1. **Relocation:** Moved `*actuator-registry*` and `register-actuator` to `protocol.lisp` (the foundation).
+2. **Reordering:** Adjusted `org-agent.asd` to load `core.lisp` (containing the stimulus loop) immediately after the symbolic gates but before the physical sensors (gateways).
+
+* 2. Issue: Hardcoded Chat UI
+** Symptoms
+The `Chat Agent` could only respond via Emacs buffer insertion, rendering it useless for external channels like Telegram.
+** Root Cause
+Architectural myopia. The original chat skill assumed the user was always in front of Emacs.
+** Resolution
+Refactored `org-skill-chat` to be **Channel-Aware**:
+- It now extracts `:channel` and `:chat-id` from the inbound stimulus.
+- It dynamically generates the System 1 mandate, instructing the LLM to use the appropriate `:target` (e.g., `:telegram`) based on the conversation context.
+
+* 3. Side-Issue: UIOP Portability
+** Symptoms
+Tests failed with `Symbol "SETENV" not found in the UIOP/DRIVER package`.
+** Root Cause
+Misinterpretation of the `UIOP` API. `setenv` is not a standard export; the portable way is using `(setf (uiop:getenv ...) ...)`.
+** Resolution
+Updated all test environment setup to use the `setf` accessor.
+
+* 4. PSF Mandate Alignment
+** Sovereign Boundary
+By moving the Telegram API logic to a user-space skill and communicating with the core via standard stimuli, we have respected the microkernel boundary.
+** Homoiconic Memory
+All Telegram interactions are now logged as `:chat-message` events, ensuring the agent's history is unified regardless of the platform.
+
+* 5. Permanent Learnings
+- **Foundation First:** Registries and logging macros must reside in the most foundational layers (`protocol` or `package`) to avoid load-order fragility.
+- **Instruct the Actuator:** When adding new channels, always update the Chat Agent's neural prompt so it knows how to "speak" back through the new interface.