FEAT: Implement Matrix Gateway and complete Communication Track

docs/rca/rca-gateway-matrix.org

@@ -0,0 +1,40 @@
+#+TITLE: Root Cause Analysis: Matrix Gateway & Communication Track Completion
+#+DATE: 2026-04-11
+#+FILETAGS: :rca:gateway:matrix:chat:psf:
+
+* Executive Summary
+Successfully implemented the third and final external communication channel (Matrix) for Org-agent v1.0. Resolved integration issues related to case-sensitivity in JSON keys and strict header requirements in `dexador`.
+
+* 1. Issue: Symbol Casing in JSON Keys
+** Symptoms
+The `TEST-MATRIX-INBOUND-NORMALIZATION` test failed because `room-id` was being extracted as `"!ROOM:HS.ORG"` (uppercase) instead of `"!room:hs.org"`.
+** Root Cause
+Common Lisp's default reader converts symbol names to uppercase. When `(string car-of-alist)` was called on a symbol generated by `cl-json`, it produced an uppercase string.
+** Resolution
+Updated the implementation to use `(string-downcase (string ...))` for room IDs and other case-sensitive Matrix identifiers.
+
+* 2. Issue: Since Token Extraction Failure
+** Symptoms
+The sync loop failed to update the `*matrix-since-token*`, causing duplicate message processing risk.
+** Root Cause
+Anticipating `:next-batch` but receiving `:next--batch` (or vice versa) due to inconsistent `cl-json` behavior across different environments or structures.
+** Resolution
+Implemented a robust `(or (cdr (assoc :next-batch json)) (cdr (assoc :next--batch json)))` lookup to handle both hyphenation styles.
+
+* 3. Issue: Type Error in Authorization Headers
+** Symptoms
+`dex:put` crashed with a `TYPE-ERROR`.
+** Root Cause
+I was passing a single string or an incorrectly nested list where `dexador` expected a strict alist of header pairs `(("Key" . "Value") ...)`.
+** Resolution
+Standardized all gateway HTTP calls to use proper alist nesting for headers.
+
+* 4. Completion: Communication Track
+With Telegram, Signal, and Matrix gateways now verified and passing tests, the Org-agent has achieved full multi-channel parity.
+- **Telegram:** Polling via Bot API.
+- **Signal:** Wrapping `signal-cli`.
+- **Matrix:** Polling via `/sync` Client API.
+
+* 5. Permanent Learnings
+- **Case Sensitivity:** Matrix IDs (rooms, users) are case-sensitive; Lisp symbols are not. Always force downcasing or use strings for storage.
+- **Header Alists:** Always use dotted pairs `("Key" . "Value")` for `dexador` headers.