#+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-23] Undefined Function in Test Suite
- **Symptom:** `cognitive-suite` tests failed with `UNDEFINED-FUNCTION` for `perceive` and `decide`.
- **Root Cause:** Refactored functions were not added to `package.lisp` exports.
- **Prevention:** Any function defined as part of a PSF PROTOCOL or PRD must be explicitly exported in the package definition.