SOUL - The Institutional Memory of the Neurosymbolic Lisp Machine

Architectural Learnings

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.

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).

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.

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.

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.

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.

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`.

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.