Architectural Upgrade 2026-03-30: Modular Emacs, org-gtd v4.0, and PSF Phase 1

notes/institutional-memory.org

@@ -0,0 +1,47 @@
+#+TITLE: SOUL - The Institutional Memory of the Neurosymbolic Lisp Machine
+
+* Architectural Learnings
+
+** [2026-03-23] Org-Native Skill System (Lisp Machine Mandate)
+- **Problem:** Extending the agent required writing Common Lisp in the core daemon, breaking the "Homoiconic Memory" philosophy where Org-mode is the native memory format. Standard agent architectures use disconnected Markdown/YAML/Python folders.
+- **Solution:** The **Org-Native Skill Standard**. Skills are written entirely as `.org` files. The daemon parses the Org file at startup, extracts `#+begin_src lisp` blocks containing triggers, neuro-prompts, and symbolic verification rules, and dynamically compiles them into the live system using `eval` and `read`.
+- **Heuristic:** The Core is strictly the PTA loop (`core.lisp`, `neuro.lisp`, `symbolic.lisp`). ALL business logic, API connectors, and rule sets MUST live as `.org` files in the `skills/` directory.
+
+** [2026-03-23] Cognitive Loop Architecture (org-agent)
+- **Problem:** Monolithic PTA (Perceive-Think-Act) loops lead to "Neural Drift" where the LLM's unverified suggestions can cause illegal system states or security breaches.
+- **Solution:** Implement the **Four-Stage Cognitive Loop**: Perceive -> Think -> Decide -> Act.
+- **Heuristic:** System 1 (Neural/LLM) is a proposal engine only. System 2 (Symbolic/Lisp) is the absolute gatekeeper.
+- **Verification:** Never execute an action unless it has passed through `decide()` and been verified against the symbolic Object Store (CLOSOS).
+
+** [2026-03-23] Externalized Configuration Mandate
+- **Problem:** Hardcoded API keys and endpoints in Lisp source prevent portability and create security risks.
+- **Solution:** Use `cl-dotenv` to load `.env` from the system source directory during `eval-when`.
+- **Heuristic:** Use `(uiop:getenv)` with a `(get-env)` fallback helper for all externalized parameters.
+
+** [2026-03-23] Hardware Compartment Mandate
+- **Problem:** Forcing a single deployment method (e.g. Docker) creates infrastructure lock-in and limits adoption for users with specific security/performance needs.
+- **Solution:** Treat the runtime as a "Hardware Compartment." Abstract deployment into a `deploy/` directory with support for Bare Metal, Docker, LXC, and VMs.
+- **Heuristic:** The Kernel speaks OACP (TCP); it does not care about the enclosure.
+
+** [2026-03-23] LLM Failover Cascade
+- **Problem:** AI providers are unreliable (rate limits, outages). A single provider failure blinds the entire agent.
+- **Solution:** Implement a `*provider-cascade*` list. The kernel automatically tries backends in order until success or exhaustion.
+- **Heuristic:** Reliability is a Core Kernel responsibility; Model choice is a Skill responsibility.
+
+** [2026-03-23] Homoiconic Memory (The Org Mandate)
+- **Problem:** Mixed-format workspaces (.md and .org) create cognitive friction and prevent unified AST reasoning.
+- **Solution:** Enforce a "Strictly Org-mode" mandate for all internal logic, plans, and memory. 
+- **Heuristic:** Use Lisp for logic, Org for everything else.
+
+* Root Cause Analyses (RCA)
+
+** [2026-03-23] Lisp Reader Syntax Error (Colons)
+- **Symptom:** Kernel crashed with `SIMPLE-READER-ERROR` on skill files containing `: ` or unescaped quotes in prompt strings.
+- **Root Cause:** The Lisp reader interprets colons as package markers. If they are used in text strings without escaping or sanitization, the reader fails.
+- **Prevention:** Sanitize Org-Native skills to replace `: ` with ` - ` in prompts, and wrap `read-from-string` in `handler-case`.
+
+** [2026-03-30 Mon] PSF Mandate Violation: Non-Literate Implementation
+- **Symptom:** `psf-core` logic and tests were written as raw `.lisp` files instead of `.org` literate files.
+- **Root Cause:** Deep-seated "Legacy Coding" habits; prioritized speed of execution over the "Sovereign Literature" mandate.
+- **Prevention:** The agent MUST refuse to create `.lisp` or `.py` files directly for system logic. All implementation must begin as an Org headline with a narrative.
+