#+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.