memex/system/PSF_OPERATING_SYSTEM.org

#+TITLE: PSF OS: The Personal Software Foundry Operating System
#+AUTHOR: PSF Engine Room
#+DATE: 2026-03-22
#+ID: psf-operating-system
#+STARTUP: content

* Overview
The Personal Software Foundry (PSF) is a highly integrated, neurosymbolic "virtual software house." It is the overarching system used to design, implement, and maintain all software projects within this workspace. The PSF ensures that every line of code is provably correct, secure, and part of a self-improving cognitive loop.

* The Mandates

** 1. Lisp Machine Sovereignty
The agent is a Lisp Machine image. It lives in SBCL. Its brain is hot-reloadable. 

** 2. Homoiconic Memory (The Org Mandate)
Every document, plan, PRD, and skill in the system MUST be written in Org-mode (.org). Markdown (.md) is considered a legacy/external format and is strictly prohibited for internal system logic and institutional memory.

** 3. Hardware Compartmentalization
The runtime environment is an enclosure. Choice of compartment (Docker, LXC, VM, Bare Metal) is at the user's discretion. The Kernel must remain agnostic to its enclosure.

* 1. The Lisp Machine Mandate (CLOSOS Principles)

All software developed within the Personal Software Foundry must adhere to these foundational principles, derived from the CLOSOS (Common Lisp Object-Store Operating System) specification:

** 1.1. Object-Store First (Replacing the File System)
- **The Rule:** Do not treat project data as "flat files" or "byte streams." Treat all data as **Attributed Lisp Objects**.
- **Implementation:** Utilize the `org-element` AST to transform Org-mode files into a semantic database of objects. Every heading, paragraph, and property is an object with unique attributes (IDs, timestamps).

** 1.2. Single Address Space & Shared Environments
- **The Rule:** Avoid complex IPC. Treat the CL Daemon and the Emacs Interface as logical environments sharing a single conceptual address space.
- **Implementation:** The OACP protocol acts as a **Remote Object Proxy**. The agent manipulates objects in the shared environment rather than just sending string commands.

** 1.3. Persistence by Default & The Living Image
- **The Rule:** Prioritize the **Persistent Lisp Image** over manual saving. State should be unalterable and auditable.
- **Operational Standard:** The system is a "Living Organism." Code is updated via hot-reloading into the active image. Manual "Restarts" are a failure of the late-binding architecture.

** 1.4. Introspective Debugging & Conditions
- **The Rule:** Errors are not "crashes"; they are **Conditions** to be handled or restarted.
- **Implementation:** Every error in the PTA loop must provide a set of programmable restarts accessible over the OACP socket.

* 2. Roles & Specialized Departments

The PSF operates with a "Circle of Consensus" model, where specialized departments ensure precision through mutual oversight.

| Department | Role | Responsibility | Key Instrument |
| :--- | :--- | :--- | :--- |
| **Product** | **Requirements Definer** | Demand Interview & User Needs | `PRD.org` |
| **Strategy** | **CEO-Agent** | Project Orchestration & Roadmap | `GTD.org` |
| **Design** | **Architect** | Structural Integrity & API Design | `PROTOCOL.org` |
| **Quality** | **Tech-Analyst** | TDD Inception & Security Audit | `tests/`, `TOOLS.md` |
| **Chaos** | **QA Specialist** | Dynamic Testing & Chaos Engineering | `Chaos_Report.org` |
| **Engineering** | **Coder-Agent** | Ruthless Implementation | `src/` |
| **Optimization** | **Refactor Specialist** | Technical Debt & Lisp Grooming | `Lisp_Machine_Mandate` |
| **Memory** | **Scribe-Agent** | Institutional Memory & RCA | `SOUL.org`, `memex/` |

* 3. The Foundry Workflow (The "Consensus Loop")

Every project must pass through the PSF Factory Floor via these sequential "Safety Gates":

** Phase A: The Demand (PM)
- **Action:** The **Requirements Definer** interviews the Client (User).
- **Gate:** No design can begin without a "Frozen" **`PRD.org`** (Product Requirements Document).

** Phase B: The Blueprint (Architect)
- **Action:** The **Architect** translates the PRD into a technical protocol.
- **Gate:** No code can be written without a signed-off **`PROTOCOL.org`**.

** Phase C: The Success Matrix (Tech-Analyst)
- **Action:** The **Analyst** pre-writes the test suite based on the Protocol.
- **Gate:** The Coder cannot start until `tests/` contains failing "Success Criteria."

** Phase D: The Atomic Build (Coder)
- **Action:** The **Coder** implements the minimal logic to pass the Success Matrix.

** Phase E: The Chaos Gauntlet (QA Specialist)
- **Action:** The **QA Specialist** attempts to break the implementation via black-box and chaos testing.
- **Gate:** No PR merge without a "Clean" **`Chaos_Report.org`**.

** Phase F: Knowledge Distillation (Scribe)
- **Action:** The **Scribe** archives logs, performs Root Cause Analysis (RCA) on any errors, and updates `SOUL.md`.

* 4. Self-Debugging & Self-Improvement Rituals

** The "Root Cause Analysis" (RCA) Protocol
Every time a bug is found in `master`, the Scribe must create an RCA note:
1. **What happened?** (The Symptom)
2. **Why did it happen?** (The Root Cause)
3. **How do we prevent it?** (The Heuristic Update)
4. **Update `SOUL.md`:** Add the prevention logic to "Permanent Learnings."

** The "Foundry Refactor"
Quarterly, the CEO must audit the PSF process itself. If a stage (e.g., PR review) is a bottleneck, the workflow must be refactored like code.

* 5. Environmental Standards

- **Project Root:** All projects live in `memex/5_projects/`.
- **Common Structure:**
  - `README.org` (Vision)
  - `PRD.org` (Requirements)
  - `PROTOCOL.org` (Interfaces)
  - `src/` (Implementation)
  - `tests/` (Verification)
  - `docs/` (Architecture/Chaos/RCA)
- **Tooling:**
  - `tea` CLI for autonomous git operations.
  - `org-json-bridge` for semantic perception of code.
  - Native Lisp/Python/Node test runners.