amr/passepartout
1
0
Fork 0
Code Issues 15 Pull Requests 1 Actions Packages Projects Releases Wiki Activity

REFACTOR: Explanatory Core Architecture & Terminology Alignment

Browse Source
This commit is contained in:
Amr Gharbeia
2026-04-13 09:03:42 -04:00
parent 10a500c480
commit 3e68cc11af
52 changed files with 446 additions and 1756 deletions
Download Patch File Download Diff File Expand all files Collapse all files

18
README.org
View File

@@ -28,10 +28,10 @@ Lisp possesses a unique property called *Homoiconicity*: the primary representat
** 3. The Neuro-Protosymbolic Loop
org-agent does not let AI models touch your system directly. Instead, it splits cognition into two distinct engines:
- *The Associative Engine (The AI Models):* Provides semantic understanding, multimodal translation, and probabilistic creativity. It looks at your Memex and proposes an action by writing a strictly formatted Lisp s-expression.
- *The Deliberate Engine (Common Lisp):* Provides deterministic logic, physics, and safety. It intercepts the model's Lisp proposal, formally verifies its structure against your security rules, and only executes it if it is mathematically sound.
- *The Probabilistic Engine (The AI Models):* Provides semantic understanding, multimodal translation, and probabilistic creativity. It looks at your Memex and proposes an action by writing a strictly formatted Lisp s-expression.
- *The Deterministic Engine (Common Lisp):* Provides deterministic logic, physics, and safety. It intercepts the model's Lisp proposal, formally verifies its structure against your security rules, and only executes it if it is mathematically sound.
Crucially, the Deliberate engine is *continuously progressive*. Right now, it starts by acting as a strict security bouncer—enforcing rules and bounding the AI's actions. But as the system matures, the Deliberate engine will progressively take over more and more of the actual reasoning, reducing the AI models' involvement to a mere semantic translation layer for the messy outside world. We are moving from a /neuro-protosymbolic/ system today, toward a fully autonomous /neurosymbolic/ Lisp machine tomorrow.
Crucially, the Deterministic engine is *continuously progressive*. Right now, it starts by acting as a strict security bouncer—enforcing rules and bounding the AI's actions. But as the system matures, the Deterministic engine will progressively take over more and more of the actual reasoning, reducing the AI models' involvement to a mere semantic translation layer for the messy outside world. We are moving from a /neuro-protosymbolic/ system today, toward a fully autonomous /neurosymbolic/ Lisp machine tomorrow.
* Architecture: Thin Harness, Fat Skills
@@ -41,7 +41,7 @@ To guarantee long-term stability, org-agent enforces a strict architectural boun
The Lisp microkernel does almost no actual "work." It is a thin, unbreakable harness strictly responsible for three things:
1. *The Object Store:* Maintaining the live graph of your Memex in RAM.
2. *The Communication Protocol:* Managing the secure bridge between the agent and the outside world. While power users can connect natively via Emacs or Vim, the vast majority of users will interact with org-agent exclusively through chat clients (like Telegram, Signal, or Matrix), web dashboards, or a Terminal UI (TUI). The harness doesn't care; it just securely routes the messages.
3. *The Cognitive Loop:* Moving signals through the Perceive -> Associative -> Deliberate -> Dispatch pipeline.
3. *The Cognitive Loop:* Moving signals through the Perceive -> Probabilistic -> Deterministic -> Dispatch pipeline.
Everything else—AI routing, vector embeddings, shell execution, or web browsing—is pushed entirely out of the harness and into *Fat Skills*.
@@ -52,8 +52,8 @@ In org-agent, a Skill is simply a *single .org file*.
Using *Literate Programming*, this single file contains everything:
- The human-readable documentation and architectural intent.
- The system prompt instructions for the Associative Engine.
- The deterministic Lisp code for the Deliberate engine's safety checks.
- The system prompt instructions for the Probabilistic Engine.
- The deterministic Lisp code for the Deterministic engine's safety checks.
- The actual execution logic.
When the system boots, it parses these single files, mathematically proves their dependencies, and compiles them directly into the live Lisp image.
@@ -67,7 +67,7 @@ The agent's "mind" is not a transient chat session; it is a durable, stateful ar
** The Psychology: The 2x2 Cognitive Matrix
The agent operates on a matrix that balances cognitive speed with cognitive state:
| | Associative (Neural/Intuitive) | Deliberate (Symbolic/Logical) |
| | Probabilistic (Neural/Intuitive) | Deterministic (Symbolic/Logical) |
| :--- | :--- | :--- |
| Foreground (Active) | *The Interface:* Fast AI models for conversation, multimodal ingestion, and semantic understanding. | *The Steward:* Lisp engine that safely retrieves requested data from the Memex and enforces security rules while the Interface keeps you engaged. |
| Background (Passive) | *The Editor:* Deep AI models finding hidden patterns while you sleep. | *The Librarian:* Lisp engine continuously maintaining data integrity and filing away loose notes. |
@@ -91,7 +91,7 @@ The agent meets you where you are. While it natively integrates with text editor
- *Web & TUI Dashboards:* High-level visual overviews of your agent's background processes and telemetry.
** 2. Cognition & Memory (How the agent thinks)
- *Model Routing:* Dynamically routes requests to the best available Associative model (e.g., Anthropic, OpenAI, Local Llama) based on task complexity or privacy needs.
- *Model Routing:* Dynamically routes requests to the best available Probabilistic model (e.g., Anthropic, OpenAI, Local Llama) based on task complexity or privacy needs.
- *Peripheral Vision & Embeddings:* Manages the vectorization of your notes, ensuring the agent retrieves semantically relevant context via sparse trees.
- *The Ontology Scribe:* Centralizes all rules regarding Org, GTD, and Org-Roam parsing into a single background subroutine, eliminating parser confusion across the codebase.
@@ -113,7 +113,7 @@ Today, org-agent relies on external tools to interact with the world. We use Pyt
But the long-term trajectory of this project is to progressively pull those boundaries inward.
As the *Deliberate Engine* grows more sophisticated, it will take on more of the heavy logical reasoning, utilizing native Lisp unification and logic engines. The Associative AI models will be relegated to what they do best: acting as a natural language translation layer to make sense of the messy, unstructured outside world.
As the *Deterministic Engine* grows more sophisticated, it will take on more of the heavy logical reasoning, utilizing native Lisp unification and logic engines. The Probabilistic AI models will be relegated to what they do best: acting as a natural language translation layer to make sense of the messy, unstructured outside world.
We will systematically rewrite external dependencies in Common Lisp. The endgame of org-agent is not just to be an AI assistant, but to resurrect the dream of the *Lisp Machine*: a unified computing environment where the operating system, the text editor, the web browser, and the AI agent all share the exact same memory space, the exact same AST, and the exact same language.

6
docs/rca/rca-bouncer.org
View File

@@ -1,13 +1,13 @@
#+TITLE: Root Cause Analysis: System 2 Bouncer & Authorization Gate
#+TITLE: Root Cause Analysis: Deterministic Engine Bouncer & Authorization Gate
#+DATE: 2026-04-11
#+FILETAGS: :rca:bouncer:authorization:psf:security:
* Executive Summary
Implemented the "Planning Mode" Bouncer to intercept high-risk System 1 proposals (e.g., shell commands, Lisp evaluation). The system now forces these actions into an asynchronous "Flight Plan" Org node for manual Sovereign approval, fulfilling the "everything is a node" and high-integrity mandates.
Implemented the "Planning Mode" Bouncer to intercept high-risk Probabilistic Engine proposals (e.g., shell commands, Lisp evaluation). The system now forces these actions into an asynchronous "Flight Plan" Org node for manual Sovereign approval, fulfilling the "everything is a node" and high-integrity mandates.
* 1. Issue: Automated High-Risk Execution
** Symptoms
System 1 proposals involving `shell` or `eval` were executed immediately upon passing the `decide` gate's safety harness. This lacked human-in-the-loop oversight for irreversible or complex operations.
Probabilistic Engine proposals involving `shell` or `eval` were executed immediately upon passing the `decide` gate's safety harness. This lacked human-in-the-loop oversight for irreversible or complex operations.
** Root Cause
Architecture gap. The system lacked an authorization state between "Safe" and "Executed".
** Resolution

2
docs/rca/rca-gateway-telegram.org
View File

@@ -22,7 +22,7 @@ Architectural myopia. The original chat skill assumed the user was always in fro
** Resolution
Refactored `org-skill-chat` to be **Channel-Aware**:
- It now extracts `:channel` and `:chat-id` from the inbound stimulus.
- It dynamically generates the System 1 mandate, instructing the LLM to use the appropriate `:target` (e.g., `:telegram`) based on the conversation context.
- It dynamically generates the Probabilistic Engine mandate, instructing the LLM to use the appropriate `:target` (e.g., `:telegram`) based on the conversation context.
* 3. Side-Issue: UIOP Portability
** Symptoms

2
docs/rca/rca-playwright-bridge.org
View File

@@ -23,7 +23,7 @@ Updated the `Dockerfile` to:
3. Install the `playwright` package and execute `playwright install --with-deps chromium` during the image build. This ensures the production container is ready for high-fidelity browsing immediately upon startup.
* 3. Cognitive Tooling
Created the `:browser` cognitive tool, which exposes three primary capabilities to System 1:
Created the `:browser` cognitive tool, which exposes three primary capabilities to Probabilistic Engine:
- **Navigation:** Full JS rendering and waiting for network idle.
- **Extraction:** Targeted text retrieval via CSS selectors.
- **Vision:** Base64-encoded screenshot capture for future multimodal processing.

6
docs/rca/rca-self-fix-loop.org
View File

@@ -3,13 +3,13 @@
#+FILETAGS: :rca:self-fix:autonomy:testing:
* Executive Summary
Verified the autonomous repair capability of the `Self-Fix Agent`. The system successfully detected a deliberate type error in a secondary skill, initiated a repair request, and programmatically patched the source code via the `:repair-file` tool.
Verified the autonomous repair capability of the `Self-Fix Agent`. The system successfully detected a deterministic type error in a secondary skill, initiated a repair request, and programmatically patched the source code via the `:repair-file` tool.
* 1. Issue: Self-Fix Mechanism Verification
** Symptoms
Manual verification was required to prove that `org-skill-self-fix` could transition from "Thinking" about a bug to "Acting" on the file system.
** Root Cause
N/A (Deliberate test injection).
N/A (Deterministic test injection).
** Resolution
Created `self-fix-tests.lisp` which:
1. Generates `org-skill-broken-math.org` with a `(+ 1 "two")` bug.
@@ -37,4 +37,4 @@ This eliminates unnecessary nesting levels and drastically reduces the surface a
* 4. Permanent Learnings
- **Flatten Configuration:** Keep `defsystem` definitions as flat as possible. The overhead of `:module` blocks often outweighs their organizational benefit in a neurosymbolic environment where agents frequently edit these files.
- **Mocking System 1:** For verifying *loop mechanics*, mocking LLM responses is essential to ensure test determinism, while integration tests can use live LLM calls.
- **Mocking Probabilistic Engine:** For verifying *loop mechanics*, mocking LLM responses is essential to ensure test determinism, while integration tests can use live LLM calls.

8
docs/rca/rca-task-orchestrator.org
View File

@@ -3,17 +3,17 @@
#+FILETAGS: :rca:orchestrator:consensus:integrity:
* Executive Summary
The implementation of Consolidation VI (Task Orchestrator) aimed to introduce parallel multi-backend consensus, GTD task integrity, and delegation. During the build, a critical dependency failure was identified in the `safety-harness` module.
The implementation of Consolidation VI (Task Orchestrator) aimed to introduce parallel multi-backend consensus, GTD task integrity, and delegation. During the build, a critical dependency failure was identified in the `lisp-validator` module.
* 1. Issue: Undefined `SAFETY-HARNESS-VALIDATE`
** Symptoms
Existing `SAFETY-SUITE` tests failed with `#<UNDEFINED-FUNCTION SAFETY-HARNESS-VALIDATE>`.
** Root Cause
The function `safety-harness-validate` was exported in `package.lisp` but never actually defined in `safety-harness.lisp`. Only the internal recursive walker `safety-harness-ast-walk` existed. This represents a "Hollow Export" bug where the interface was designed but the implementation was truncated or skipped in a previous session.
The function `lisp-validator-validate` was exported in `package.lisp` but never actually defined in `lisp-validator.lisp`. Only the internal recursive walker `lisp-validator-ast-walk` existed. This represents a "Hollow Export" bug where the interface was designed but the implementation was truncated or skipped in a previous session.
** Resolution
Defined `safety-harness-validate` as a wrapper around `read-from-string` and `safety-harness-ast-walk`.
Defined `lisp-validator-validate` as a wrapper around `read-from-string` and `lisp-validator-ast-walk`.
* 2. Design Decision: Deliberate Consensus
* 2. Design Decision: Deterministic Consensus
** Requirement
Multi-backend support to reduce hallucinations and increase reliability.
** Solution

6
literate/context.org
View File

@@ -11,7 +11,7 @@ A common failure mode for Large Language Models (LLMs) is the "Lost in the Middl
The ~org-agent~ harness implements a deterministic, tree-aware solution: the **Foveal-Peripheral Hybrid Model**.
*** 1. The Foveal Focus (High Resolution)
When the harness prepares a prompt for the Associative Engine, it identifies a "Foveal Focus"—typically the specific Org headline or task the user is currently interacting with. This node, along with its immediate children and semantically relevant neighbors, is rendered at "High Resolution," meaning its full body text, properties, and metadata are included in the prompt.
When the harness prepares a prompt for the Probabilistic Engine, it identifies a "Foveal Focus"—typically the specific Org headline or task the user is currently interacting with. This node, along with its immediate children and semantically relevant neighbors, is rendered at "High Resolution," meaning its full body text, properties, and metadata are included in the prompt.
*** 2. The Peripheral Vision (Low Resolution)
To maintain global awareness without bloating the context window, the rest of the Memex is rendered at "Low Resolution." The harness recursively walks the Object Store and generates a skeletal outline consisting only of titles and IDs. This gives the LLM a "mental map" of the entire system, allowing it to reference other projects or skills without needing to see their full content until they are explicitly brought into focus.
@@ -28,7 +28,7 @@ flowchart TD
Identification --> Peripheral[Render Outline: Titles Only]
Foveal --> Assembly[Assemble Global Awareness String]
Peripheral --> Assembly
Assembly --> LLM[Associative Engine Proposal]
Assembly --> LLM[Probabilistic Engine Proposal]
#+end_src
* Context Assembly (context.lisp)
@@ -105,7 +105,7 @@ Reads the raw literate Org source of a specific skill. This is a foundational ca
#+end_src
** Harness Logs (context-get-system-logs)
Retrieves the most recent entries from the harness's internal circular log buffer. This allows the Associative Engine to see recent errors or successful dispatches, enabling it to course-correct or explain failures to the user.
Retrieves the most recent entries from the harness's internal circular log buffer. This allows the Probabilistic Engine to see recent errors or successful dispatches, enabling it to course-correct or explain failures to the user.
#+begin_src lisp :tangle ../src/context.lisp
(defun context-get-system-logs (&optional (limit 20))

18
literate/loop.org
View File

@@ -10,7 +10,7 @@ The core of the ~org-agent~ harness is a functional transformation pipeline. In
We have evolved the harness into a **Reactive Signal Pipeline**. Every event—whether it is a user keystroke, a heartbeat timer pulse, or a suggested action from an LLM—is treated as a discrete **Signal**.
Signals move through a series of formal **Gates**. Each gate transforms or validates the signal until it is either physically dispatched to an actuator or safely rejected by the Deliberate Engine.
Signals move through a series of formal **Gates**. Each gate transforms or validates the signal until it is either physically dispatched to an actuator or safely rejected by the Deterministic Engine.
*** Advantages of the Pipeline Model:
- **Consensus Ready:** By treating reasoning as a signal moving through a pipe, we can "split" the pipe to query multiple LLM backends simultaneously. A Consensus Gate later in the pipe compares these proposals.
@@ -22,7 +22,7 @@ Signals move through a series of formal **Gates**. Each gate transforms or valid
flowchart TD
S1[Signal: External Stimulus] --> P[Perceive Gate]
S2[Signal: Heartbeat Pulse] --> P
P --> N[Associative Gate]
P --> N[Probabilistic Gate]
N --> C[Consensus Gate]
C --> V[Validation Gate]
V --> D[Dispatch Gate]
@@ -138,15 +138,15 @@ The Perceive Gate is responsible for data normalization and sensory intake. It t
signal))
#+end_src
*** Associative Gate
The Associative Gate invokes the neural reasoning engine. It takes the current context and generates a list of "intuitions" or proposed actions.
*** Probabilistic Gate
The Probabilistic Gate invokes the neural reasoning engine. It takes the current context and generates a list of "intuitions" or proposed actions.
#+begin_src lisp :tangle ../src/loop.lisp
(defun neuro-gate (signal)
"Associative: Neural intuition and proposed actions."
"Probabilistic: Neural intuition and proposed actions."
(unless (eq (getf signal :type) :EVENT)
(return-from neuro-gate signal))
(harness-log "GATE [Associative]: Consulting LLM...")
(harness-log "GATE [Probabilistic]: Consulting LLM...")
(let ((thoughts (think signal)))
(setf (getf signal :proposals) (if (and (listp thoughts) (listp (car thoughts)))
thoughts
@@ -182,11 +182,11 @@ When multiple LLM backends provide diverging thoughts, the Consensus Gate resolv
#+end_src
*** Decide Gate
The Decide Gate is the final deterministic safety net. It runs the candidate action through all loaded skill safety gates (The Deliberate Engine) before allowing it to proceed.
The Decide Gate is the final deterministic safety net. It runs the candidate action through all loaded skill safety gates (The Deterministic Engine) before allowing it to proceed.
#+begin_src lisp :tangle ../src/loop.lisp
(defun decide-gate (signal)
"Deliberate: Deterministic safety and validation."
"Deterministic: Deterministic safety and validation."
(let ((candidate (getf signal :candidate)))
(if candidate
(let* ((normalized-candidate (if (listp candidate) candidate (list :type :RESPONSE :payload (list :text candidate))))
@@ -440,7 +440,7 @@ The Reactive Signal Pipeline must be empirically verified through automated test
:priority 200
:trigger (lambda (ctx) t)
:neuro (lambda (ctx) (list :type :REQUEST :payload (list :action :eval :code "(error \"BOOM\")")))
:symbolic (lambda (action ctx) (error "CRASH IN SYSTEM 2")))
:symbolic (lambda (action ctx) (error "CRASH IN DETERMINISTIC ENGINE")))
(process-signal (list :type :EVENT :payload (list :sensor :test)))
;; Verify that we are still in State A
(let ((obj (lookup-object "node-1")))

54
literate/neurosymbolic.org
View File

@@ -6,21 +6,21 @@
* The Neurosymbolic Bridge (neuro.lisp & symbolic.lisp)
*** The Neurosymbolic Loop
In our loop, the Associative Engine never speaks to the world directly. It only proposes "thoughts" to the Deliberate Engine. the Deliberate Engine, the Lisp harness, evaluates these thoughts against a chain of symbolic safety gates (Skills) before any action is actually dispatched to an actuator (Emacs, Shell, etc.).
In our loop, the Probabilistic Engine never speaks to the world directly. It only proposes "thoughts" to the Deterministic Engine. the Deterministic Engine, the Lisp harness, evaluates these thoughts against a chain of symbolic safety gates (Skills) before any action is actually dispatched to an actuator (Emacs, Shell, etc.).
#+begin_src mermaid
flowchart TD
Stimulus[External Stimulus/Signal] --> Perceive[Perceive: Skill Trigger]
Perceive --> Associative[Associative Engine: LLM]
Associative --> Proposal[Lisp Action Proposal]
Proposal --> Deliberate[Deliberate Engine: Lisp Gates]
Deliberate --> Gate1[Safety Gate: Skill A]
Perceive --> Probabilistic[Probabilistic Engine: LLM]
Probabilistic --> Proposal[Lisp Action Proposal]
Proposal --> Deterministic[Deterministic Engine: Lisp Gates]
Deterministic --> Gate1[Safety Gate: Skill A]
Gate1 --> Gate2[Safety Gate: Skill B]
Gate2 --> Verified[Verified Action]
Verified --> Dispatch[Dispatch: Actuator]
style Associative fill:#f9f,stroke:#333,stroke-width:2px
style Deliberate fill:#bbf,stroke:#333,stroke-width:2px
style Probabilistic fill:#f9f,stroke:#333,stroke-width:2px
style Deterministic fill:#bbf,stroke:#333,stroke-width:2px
#+end_src
*** Sovereign Decoupling (The Thin Harness)
@@ -29,15 +29,15 @@ The harness files ~neuro.lisp~ and ~symbolic.lisp~ are intentionally "Thin Harne
By moving the "Fat" logic (vendor APIs, security rules) into **Skills**, we achieve total sovereign decoupling. You can swap your LLM provider or your security policy without ever touching the harness.
* Associative Engine (neuro.lisp)
The Associative engine handles the interface with LLM providers, providing a unified associative space regardless of the underlying model.
* Probabilistic Engine (neuro.lisp)
The Probabilistic engine handles the interface with LLM providers, providing a unified probabilistic space regardless of the underlying model.
** Package Context
#+begin_src lisp :tangle ../src/neuro.lisp
(in-package :org-agent)
#+end_src
** Associative Backends Registry
** Probabilistic Backends Registry
The harness maintains a neutral registry of backends. Skills (like the LLM Gateway) register themselves here to provide actual neural reasoning capabilities.
#+begin_src lisp :tangle ../src/neuro.lisp
@@ -51,7 +51,7 @@ The ordered list of backends to attempt for neural reasoning. This list is ~nil~
(defvar *provider-cascade* nil)
#+end_src
** Register Associative Backend
** Register Probabilistic Backend
A simple mapping from a keyword identifier to a backend implementation function.
#+begin_src lisp :tangle ../src/neuro.lisp
@@ -65,8 +65,8 @@ A hook for dynamic model selection. A skill might look at the current context an
(defvar *model-selector-fn* nil "A function called with (provider context) to return a model ID.")
#+end_src
** Associative Dispatch (ask-neuro)
This is the primary entrance to the Associative engine. It implements two modes of operation:
** Probabilistic Dispatch (ask-neuro)
This is the primary entrance to the Probabilistic engine. It implements two modes of operation:
1. **Sequential Cascade:** Attempt backends one by one until success.
2. **Parallel Consensus:** Query multiple backends simultaneously to resolve hallucinations or select the best "thought."
@@ -85,7 +85,7 @@ sequenceDiagram
#+begin_src lisp :tangle ../src/neuro.lisp
(defvar *consensus-enabled-p* nil "If T, ask-neuro queries all backends in parallel.")
(defun ask-neuro (prompt &key (system-prompt "You are the Associative engine of a Neurosymbolic Lisp Machine.") (cascade nil) (context nil))
(defun ask-neuro (prompt &key (system-prompt "You are the Probabilistic engine of a Neurosymbolic Lisp Machine.") (cascade nil) (context nil))
"Dispatches a neural request through the provider cascade or parallel consensus."
(let ((backends (cond
((and cascade (listp cascade)) cascade)
@@ -101,7 +101,7 @@ sequenceDiagram
(when backend-fn
(push (bt:make-thread
(lambda ()
(harness-log "ASSOCIATIVE [Consensus]: Querying backend ~a..." backend)
(harness-log "PROBABILISTIC [Consensus]: Querying backend ~a..." backend)
(let* ((model (when *model-selector-fn* (funcall *model-selector-fn* backend context)))
(result (ignore-errors
(if model
@@ -125,7 +125,7 @@ sequenceDiagram
(or (dolist (backend backends)
(let ((backend-fn (gethash backend *neuro-backends*)))
(when backend-fn
(harness-log "ASSOCIATIVE: Attempting backend ~a..." backend)
(harness-log "PROBABILISTIC: Attempting backend ~a..." backend)
(let* ((model (when *model-selector-fn* (funcall *model-selector-fn* backend context)))
(result (if model
(funcall backend-fn prompt system-prompt :model model)
@@ -136,20 +136,20 @@ sequenceDiagram
"(:type :LOG :payload (:text \"Neural Cascade Failure\"))"))))
#+end_src
** Associative Reasoning (think)
** Probabilistic Reasoning (think)
The ~think~ function is where the "Neuro" meets the "Symbolic." It gathers the global awareness context (Peripheral Vision), the tool definitions (The Tool Belt), and any skill-specific triggers to form the final prompt.
Crucially, it mandates that the output be a Common Lisp property list, forcing the LLM to "think in Lisp."
#+begin_src lisp :tangle ../src/neuro.lisp
(defun think (context)
"Invokes the neural Associative engine to propose a Lisp action based on context."
"Invokes the neural Probabilistic engine to propose a Lisp action based on context."
(let ((active-skill (find-triggered-skill context))
(tool-belt (generate-tool-belt-prompt))
(global-context (context-assemble-global-awareness)))
(if active-skill
(progn
(harness-log "ASSOCIATIVE: Engaging skill '~a'~%" (skill-name active-skill))
(harness-log "PROBABILISTIC: Engaging skill '~a'~%" (skill-name active-skill))
(let* ((prompt-generator (skill-neuro-prompt active-skill))
(raw-prompt (when prompt-generator (funcall prompt-generator context)))
(full-system-prompt (concatenate 'string
@@ -177,7 +177,7 @@ To call a tool, you MUST use:
(raw-thoughts (cl-ppcre:split (cl-ppcre:quote-meta-chars "|CONSENSUS-SEP|") thought))
(suggestions nil))
(dolist (raw-thought raw-thoughts)
(harness-log "ASSOCIATIVE RAW: ~a~%" raw-thought)
(harness-log "PROBABILISTIC RAW: ~a~%" raw-thought)
(let* ((cleaned-thought
(let ((match (cl-ppcre:scan-to-strings "(?s)```(?:lisp)?\\n?(.*?)\\n?```" raw-thought)))
(if match
@@ -191,7 +191,7 @@ To call a tool, you MUST use:
(list :sensor :syntax-error
:code cleaned-thought
:error (format nil "~a" c)))))))
(harness-log "ASSOCIATIVE Suggestion: ~a~%" cleaned-thought)
(harness-log "PROBABILISTIC Suggestion: ~a~%" cleaned-thought)
(when (and suggestion (listp suggestion))
(push suggestion suggestions))))
(if (and *consensus-enabled-p* suggestions)
@@ -202,7 +202,7 @@ To call a tool, you MUST use:
#+end_src
** Prompt Meta-Cognition (distill-prompt)
Even the Associative engine can benefit from introspection. This function allows the agent to observe its own prompts and successful results to distill them into reusable templates.
Even the Probabilistic engine can benefit from introspection. This function allows the agent to observe its own prompts and successful results to distill them into reusable templates.
#+begin_src lisp :tangle ../src/neuro.lisp
(defun distill-prompt (full-prompt successful-output)
@@ -211,10 +211,10 @@ Even the Associative engine can benefit from introspection. This function allows
#+end_src
* Deliberate Engine (symbolic.lisp)
The Deliberate engine is the deterministic gatekeeper that ensures all proposed actions—whether from the user or from the neural engine—are safe and logically valid.
* Deterministic Engine (symbolic.lisp)
The Deterministic engine is the deterministic gatekeeper that ensures all proposed actions—whether from the user or from the neural engine—are safe and logically valid.
As a "Thin Harness," the Deliberate engine does not contain specific security rules or task integrity checks. Instead, it provides a priority-based dispatcher that iterates through all loaded skills to validate or transform proposed actions.
As a "Thin Harness," the Deterministic engine does not contain specific security rules or task integrity checks. Instead, it provides a priority-based dispatcher that iterates through all loaded skills to validate or transform proposed actions.
** Package Context
#+begin_src lisp :tangle ../src/symbolic.lisp
@@ -241,7 +241,7 @@ flowchart LR
#+begin_src lisp :tangle ../src/symbolic.lisp
(defun decide (proposed-action context)
"The Deliberate Safety Gate: iterates through all skill symbolic-gates sorted by priority."
"The Deterministic Safety Gate: iterates through all skill symbolic-gates sorted by priority."
(let ((current-action proposed-action)
(skills nil))
;; 1. Collect all skills with symbolic gates
@@ -261,7 +261,7 @@ flowchart LR
;; If any gate returns a LOG or EVENT (blocking/intercepting), stop and return it.
(when (and (listp current-action)
(member (getf current-action :type) '(:LOG :EVENT :log :event)))
(harness-log "DELIBERATE: Intercepted by skill '~a'~%" (skill-name skill))
(harness-log "DETERMINISTIC: Intercepted by skill '~a'~%" (skill-name skill))
(return-from decide current-action))))
current-action))

6
literate/package.org
View File

@@ -7,7 +7,7 @@
The ~package.lisp~ file defines the public API of the ~org-agent~ harness. It serves as the primary membrane between the deterministic core modules and the dynamic world of skills and actuators.
** Architectural Intent: The Package Membrane
By strictly defining the public interface, we ensure that skills remain decoupled from the harness implementation details. This allows for sovereign replacement of any component (e.g., swapping the Object Store or the Associative Engine) without breaking existing skills.
By strictly defining the public interface, we ensure that skills remain decoupled from the harness implementation details. This allows for sovereign replacement of any component (e.g., swapping the Object Store or the Probabilistic Engine) without breaking existing skills.
#+begin_src mermaid
flowchart TD
@@ -82,7 +82,7 @@ flowchart TD
#:load-skill-with-timeout
#:topological-sort-skills
#:validate-lisp-syntax
#:safety-harness-validate
#:lisp-validator-validate
#:defskill
#:*skills-registry*
#:skill
@@ -109,7 +109,7 @@ flowchart TD
#:register-emacs-client
#:unregister-emacs-client
;; --- Associative Engine ---
;; --- Probabilistic Engine ---
#:ask-neuro
#:register-neuro-backend
#:distill-prompt

10
literate/skills.org
View File

@@ -19,7 +19,7 @@ Skills often depend on one another. The harness implements a deterministic topol
** Skill Architecture
#+begin_src mermaid
flowchart TD
Registry[Skills Registry] --> S1[Skill: System Invariants]
Registry[Skills Registry] --> S1[Skill: System Policy]
Registry --> S2[Skill: LLM Gateway]
Registry --> S3[Skill: Token Accountant]
S2 -- Depends On --> S1
@@ -65,7 +65,7 @@ The harness maintains a stateful tracking table for all skill files discovered i
#+end_src
** Skill Selection (find-triggered-skill)
The primary dispatcher for the Associative Engine. It iterates through the registry to find the highest-priority skill whose trigger function matches the current cognitive context.
The primary dispatcher for the Probabilistic Engine. It iterates through the registry to find the highest-priority skill whose trigger function matches the current cognitive context.
#+begin_src lisp :tangle ../src/skills.lisp
(defun find-triggered-skill (context)
@@ -303,7 +303,7 @@ The unified orchestrator for the system boot sequence.
(return-from initialize-all-skills nil))
(let ((sorted-files (topological-sort-skills skills-dir)))
;; MANDATE: The System Invariants must be present for a safe boot
;; MANDATE: The System Policy must be present for a safe boot
(unless (member "org-skill-system-invariants" sorted-files :key #'pathname-name :test #'string-equal)
(error "BOOT FAILURE: org-skill-system-invariants.org not found in skills directory."))
@@ -376,9 +376,9 @@ The harness provides a baseline set of cognitive tools that enable core system i
:guard (lambda (args context)
(declare (ignore context))
(let ((code (getf args :code)))
(let ((harness-pkg (find-package :org-agent.skills.org-skill-safety-harness)))
(let ((harness-pkg (find-package :org-agent.skills.org-skill-lisp-validator)))
(if harness-pkg
(uiop:symbol-call :org-agent.skills.org-skill-safety-harness :safety-harness-validate code)
(uiop:symbol-call :org-agent.skills.org-skill-lisp-validator :lisp-validator-validate code)
t))))
:body (lambda (args)
(let ((code (getf args :code)))

4
literate/system-definition.org
View File

@@ -53,7 +53,7 @@ This system defines the core "Thin Harness." It includes the protocol, the objec
(:file "src/credentials-vault")
(:file "src/llm-gateway")
(:file "src/symbolic")
(:file "src/safety-harness")
(:file "src/lisp-validator")
(:file "src/self-fix")
(:file "src/lisp-repair")
(:file "src/bouncer")
@@ -77,7 +77,7 @@ This system contains the empirical tests required by the Engineering Standards.
:components ((:file "tests/protocol-tests")
(:file "tests/pipeline-tests")
(:file "tests/peripheral-vision-tests")
(:file "tests/safety-harness-tests")
(:file "tests/lisp-validator-tests")
(:file "tests/boot-sequence-tests")
(:file "tests/object-store-tests")
(:file "tests/immune-system-tests")

4
org-agent.asd
View File

@@ -21,7 +21,7 @@
(:file "src/credentials-vault")
(:file "src/llm-gateway")
(:file "src/symbolic")
(:file "src/safety-harness")
(:file "src/lisp-validator")
(:file "src/self-fix")
(:file "src/lisp-repair")
(:file "src/bouncer")
@@ -40,7 +40,7 @@
:components ((:file "tests/protocol-tests")
(:file "tests/pipeline-tests")
(:file "tests/peripheral-vision-tests")
(:file "tests/safety-harness-tests")
(:file "tests/lisp-validator-tests")
(:file "tests/boot-sequence-tests")
(:file "tests/object-store-tests")
(:file "tests/immune-system-tests")

4
skills/org-skill-bouncer.org
View File

@@ -2,12 +2,12 @@
:ID: bouncer-agent-skill
:CREATED: [2026-04-11 Sat 15:20]
:END:
#+TITLE: SKILL: System 2 Bouncer (Authorization Gate)
#+TITLE: SKILL: Deterministic Engine Bouncer (Authorization Gate)
#+STARTUP: content
#+FILETAGS: :system:bouncer:authorization:psf:
* Overview
The *System 2 Bouncer* is the authorization gate for high-risk actions. It serializes intercepted actions into Org nodes ("Flight Plans") and re-injects them once manually approved by the Sovereign.
The *Deterministic Engine Bouncer* is the authorization gate for high-risk actions. It serializes intercepted actions into Org nodes ("Flight Plans") and re-injects them once manually approved by the Sovereign.
** Deep Reasoning: Beyond Permission
While the *Formal Prover* ensures an action is "legal" (e.g., "Yes, you are allowed to send a Matrix message"), the *Bouncer* ensures the action is "safe" by inspecting the payload content via **Deep Packet Inspection (DPI)**.

161
skills/org-skill-chaos.org
View File

@@ -1,161 +0,0 @@
:PROPERTIES:
:ID: 9dd80d2f-ec60-4263-92d9-a50b87270dda
:CREATED: [2026-03-30 Mon 21:16]
:EDITED: [2026-04-07 Tue 13:42]
:END:
#+TITLE: SKILL: Chaos Gauntlet (Universal Literate Note)
#+STARTUP: content
#+FILETAGS: :chaos:testing:reliability:psf:
#+DEPENDS_ON: skill-shell-actuator skill-tdd-runner
* Overview
The *Chaos Gauntlet* is an adversarial testing skill designed to ensure the system's resilience. It simulates environmental failures, malformed LLM responses, and network disruptions, forcing the harness and its skills to handle "Byzantine" conditions gracefully.
* Phase A: Demand (PRD)
:PROPERTIES:
:STATUS: FROZEN
:END:
** 1. Purpose
Verify the system's stability and error-handling capabilities under stress.
** 2. User Needs
- *Failure Simulation:* Ability to inject artificial delays or errors into the Harness Protocol bus.
- *Byzantine Response Testing:* Test how System 2 handles nonsensical or malicious System 1 proposals.
- *Network Resilience:* Simulate Gitea or LLM provider timeouts.
- *Recovery Verification:* Ensure the harness can recover from a "skip-event" restart.
* Phase D: Build (Implementation)
:PROPERTIES:
:STATUS: SIGNED
:END:
** Chaos Injection Logic
#+begin_src lisp :tangle ../src/chaos-logic.lisp
(in-package :org-agent)
(defun chaos-inject-error (sensor-type)
"Injects a synthetic error into a specific sensor pipeline."
(unless *chaos-enabled-p*
(harness-log "CHAOS ERROR - Injection blocked. Production gate is ACTIVE.")
(return-from chaos-inject-error nil))
(harness-log "CHAOS - Injecting synthetic error into ~a sensor..." sensor-type)
(inject-stimulus
`(:type :EVENT :payload (:sensor ,sensor-type :error "SYNTHETIC_CHAOS_ERROR"))))
(defun chaos-stress-test (action context)
"Executes a randomized stress test by injecting failures into the system."
(declare (ignore context))
(unless *chaos-enabled-p*
(harness-log "CHAOS ERROR - Stress test blocked. Production gate is ACTIVE.")
(return-from chaos-stress-test "FAILURE - Production gate active."))
(let* ((payload (getf action :payload))
(mode (or (getf payload :mode) :random))
(intensity (or (getf payload :intensity) 3)))
(harness-log "CHAOS - Commencing stress test (Mode: ~a, Intensity: ~a)" mode intensity)
(snapshot-object-store)
(case mode
(:random (dotimes (i intensity)
(let ((failure-type (nth (random 3) '(:test-failure :shell-timeout :llm-error))))
(inject-stimulus
`(:type :EVENT :payload (:sensor :chaos-injection :type ,failure-type))))))
(:shell (inject-stimulus
`(:type :EVENT :payload (:sensor :shell-response :cmd "git push" :exit-code 128 :stderr "fatal: network unreachable")))))
(snapshot-object-store)
(format nil "SUCCESS - Chaos stress test initiated.")))
(defun chaos-enable ()
"Disables the production gate and allows chaos injection."
(setf *chaos-enabled-p* t)
(harness-log "CHAOS - Production gate DISABLED. Chaos injection is now ALLOWED.")
t)
(defun chaos-disable ()
"Enables the production gate and blocks chaos injection."
(setf *chaos-enabled-p* nil)
(harness-log "CHAOS - Production gate ENABLED. Chaos injection is now BLOCKED.")
t)
#+end_src
* Phase B: Blueprint (PROTOCOL)
:PROPERTIES:
:STATUS: SIGNED
:END:
** 1. Architectural Intent
The *Chaos Gauntlet* skill is designed to be non-invasive, running primarily in a background mode. It should not interfere with normal system operation unless explicitly triggered. It is protected by a **Production Gate** (`*chaos-enabled-p*`) to prevent accidental disruptions during real work.
- *Controlled Chaos:* Failures must be injected in a precise and controllable manner.
- *Merkle Integrity:* Every stress test triggers a Merkle snapshot before and after to allow for full-system rollback.
- *Observability:* The system's response to failures must be easily observable through logging.
** 2. Semantic Interfaces
*** A. Gate Control
#+begin_src lisp
(defun chaos-enable ()
"Disables the production gate and allows chaos injection.")
(defun chaos-disable ()
"Enables the production gate and blocks chaos injection.")
#+end_src
*** B. Triggering Chaos
*`chaos-trigger` Sensor:*
Events of type `:EVENT` with a `:payload` containing `(:sensor :chaos-trigger)` trigger the skill. The payload can contain a `:mode` key to specify the type of chaos to inject (e.g., `:random`, `:shell`), and an `:intensity` to control the number of failures injected.
*Signature:*
`#+begin_src lisp
;; Triggers the chaos skill.
(defun trigger-chaos (mode intensity)
"Triggers the chaos gauntlet with a specified mode and intensity."
(org-agent:inject-stimulus
`(:type :EVENT :payload (:sensor :chaos-trigger :mode ,mode :intensity ,intensity))))
#+end_src
*** B. Injecting Synthetic Errors
*`chaos-inject-error` Function:*
Injects a synthetic error event into a specified sensor pipeline. Different sensor types will react differently to synthetic errors.
*Signature:*
`#+begin_src lisp
;; Injects a synthetic error into a specific sensor pipeline.
(defun chaos-inject-error (sensor-type error-message)
"Injects a specific synthetic error into a specific sensor."
(org-agent:inject-stimulus
`(:type :EVENT :payload (:sensor ,sensor-type :error ,error-message))))
#+end_src
*** C. Simulating Network Disruptions
The `chaos-stress-test` function, when `mode` is `:shell`, simulates network disruptions by returning a specific error code from a shell command (e.g., `git push`).
*Signature:* (covered by existing implementation in Phase D).
*** D. Kernel Restart Simulation
Deliberately trigger `skip-event` to test recovery protocols.
*Signature:*
`#+begin_src lisp
;; simulates a skip event (a full org-agent reboot)
(defun chaos-force-skip-event ())
#+end_src
* Registration
#+begin_src lisp
(defskill :skill-chaos
:priority 10 ; Lower priority, used for background testing
:trigger (lambda (context) (eq (getf (getf context :payload) :sensor) :chaos-trigger))
:neuro (lambda (context)
(let ((p (getf context :payload)))
(format nil "A chaos trigger was received (~a). Should I run a stress test?" (getf p :mode))))
:symbolic #'chaos-stress-test)
#+end_src

7
skills/org-skill-engineering-standards.org
View File

@@ -30,6 +30,9 @@ Major architectural shifts or complex refactors require a formal implementation
** 6. The Stop-and-Wait Mandate (Turn-Yielding)
You are strictly forbidden from drafting a plan or requesting formal approval in the same conversational turn that you propose an initial strategy or begin file discovery. You MUST propose your strategy in plain text, explicitly state "Waiting for user feedback," and yield the turn. You may only proceed to draft the `.md` plan after the user explicitly replies with agreement.
** 7. GTD Synchronization (Roadmap Integrity)
You are strictly forbidden from considering a task complete without updating `gtd.org`. Every major architectural shift, feature implementation, or refactor MUST be recorded in the project roadmap to ensure technical transparency and historical auditability.
* Phase B: Blueprint (PROTOCOL)
:PROPERTIES:
:STATUS: SIGNED
@@ -67,7 +70,7 @@ The Engineering Standards skill provides the deterministic enforcement of the wo
(when (member act '(:modify-file :write-file :replace :rename-file :delete-file))
(let ((proj-root (asdf:system-source-directory :org-agent)))
(unless (verify-git-clean-p proj-root)
(harness-log "DELIBERATE [Standards]: BLOCKING ACTION. Working tree is dirty. Commit changes before modification.")
(harness-log "DETERMINISTIC [Standards]: BLOCKING ACTION. Working tree is dirty. Commit changes before modification.")
(return-from engineering-standards-gate
(list :type :LOG :payload (list :text "Engineering Standard Violation: Working tree dirty. You MUST commit before modifying files."))))))
@@ -84,5 +87,5 @@ The Engineering Standards skill provides the deterministic enforcement of the wo
#+end_src
* See Also
- [[file:org-skill-system-invariants.org][System Invariants]]
- [[file:org-skill-system-invariants.org][System Policy]]
- [[file:../README.org][org-agent README]]

2
skills/org-skill-formal-verification.org
View File

@@ -8,7 +8,7 @@
#+FILETAGS: :security:logic:formal-methods:psf:
* Overview
The *Formal Verification Gate* replaces heuristic whitelisting with symbolic logic proofs. It ensures that every action proposed by System 1 is *provably safe* against the harness's core security invariants using a Lisp-native symbolic prover.
The *Formal Verification Gate* replaces heuristic whitelisting with symbolic logic proofs. It ensures that every action proposed by Probabilistic Engine is *provably safe* against the harness's core security invariants using a Lisp-native symbolic prover.
** Deep Reasoning: The Sandbox of Intent
This gate is the first line of defense against both "Inside Threats" (maliciously modified skill files) and "Hallucination Threats" (LLMs generating unsafe commands).

89
skills/org-skill-function-calling.org
View File

@@ -1,89 +0,0 @@
:PROPERTIES:
:ID: 1cbff23d-aef1-412f-97a0-260302034001
:CREATED: [2026-03-31 Tue 18:43]
:EDITED: [2026-04-07 Tue 13:42]
:END:
#+TITLE: SKILL: Native Function Calling (Universal Literate Note)
#+STARTUP: content
#+FILETAGS: :llm:tools:json-schema:reliability:psf:
#+DEPENDS_ON: id:homoiconic-memory-skill
* Overview
The *Native Function Calling* skill provides the translation layer between the system's deterministic Lisp interfaces and the LLM's neural tool-calling capabilities. It ensures that System 1 (the LLM) interacts with the world via structured, validated schemas rather than raw text plists, virtually eliminating "formatting hallucinations."
* Phase A: Demand (PRD)
:PROPERTIES:
:STATUS: FROZEN
:END:
** 1. Purpose
Define a high-reliability bridge for LLM-native "Tool Use."
** 2. User Needs
- *Schema Generation:* Automatically convert Lisp `defun` signatures into JSON Schema tool definitions.
- *Reliable Ingress:* Parse the LLM's structured `tool_calls` response back into a valid Lisp plist.
- *Provider Agnostic:* Support schema formats for Gemini, OpenAI, and Anthropic.
- *Validation:* Ensure arguments match the required types before reaching System 2.
** 3. Success Criteria
*** TODO Lisp-to-JSON Schema conversion logic verification
*** TODO Multi-provider schema formatting (Gemini vs OpenAI)
*** TODO Response parsing from tool_call to symbolic action
* Phase B: Blueprint (PROTOCOL)
:PROPERTIES:
:STATUS: SIGNED
:END:
* Phase B: Blueprint (PROTOCOL)
:PROPERTIES:
:STATUS: DRAFT
:END:
** 1. Architectural Intent
The core intent is to create a robust, bi-directional translation layer. This layer guarantees type safety and schema adherence between the LLM's Tool Calling mechanism and the Lisp environment. The design emphasizes clear separation of concerns: schema generation, response parsing, and provider-specific formatting. We should aim for a modular architecture that allows for easier extension to new LLM providers and new data types. The validation process must be explicit and easily auditable. Error handling is critical; parsing failures should yield informative error messages, enabling rapid debugging.
** 2. Semantic Interfaces (Lisp Signatures)
*** `defun json-schema-from-defun (function-name)`
- *Purpose:* Generates a JSON Schema representation from a Lisp function definition.
- *Args:*
- `function-name`: A symbol representing the name of the Lisp function.
- *Returns:* A Lisp plist representing the JSON Schema. Keys should correspond to standard JSON Schema fields (e.g., `:type`, `:properties`, `:required`).
- *Side Effects:* None. Pure function.
*** `defun parse-tool-call-arguments (function-name arguments tool-provider)`
- *Purpose:* Parses the arguments returned by an LLM tool call into a Lisp plist. Validates the arguments against the schema generated by `json-schema-from-defun`.
- *Args:*
- `function-name`: A symbol representing the name of the Lisp function being called.
- `arguments`: A string containing the JSON arguments returned by the LLM's `tool_calls` field.
- `tool-provider`: A keyword (e.g., `:openai`, `:gemini`, `:anthropic`) indicating the LLM provider.
- *Returns:* A Lisp plist representing the parsed arguments, or `nil` if parsing fails. On failure, appropriate error messages should be logged.
- *Side Effects:* May signal errors.
*** `defun format-json-schema-for-provider (json-schema tool-provider)`
- *Purpose:* Formats the automatically generated JSON schema to the specific format required by each LLM provider.
- *Args:*
- `json-schema`: A Lisp plist containing the generic JSON schema (output of `json-schema-from-defun`).
- `tool-provider`: A keyword (e.g., `:openai`, `:gemini`, `:anthropic`) indicating the LLM provider.
- *Returns:* A Lisp plist representing the provider-specific JSON schema.
- *Side Effects:* None. Pure function.
*** `defun validate-arguments (function-name arguments)`
- *Purpose:* Validates that the parsed arguments conform to the expected schema.
- *Args:*
- `function-name`: A symbol identifying the function being called. Used to retrieve the function definition and associated JSON schema.
- `arguments`: A Lisp plist containing the parsed arguments.
- *Returns:* `T` if validation succeeds, `NIL` if it fails.
- *Side Effects:* May signal errors if validation fails. Logs validation errors.
** 3. Data Structures
*** JSON Schema (Lisp Representation)
A Lisp plist mimicking the structure of a JSON Schema. Keys will generally be keywords mirroring JSON Schema vocabulary (e.g., `:type`, `:properties`, `:required`, `:description`). Values will be Lisp datatypes corresponding to the schema datatypes (e.g., symbols, strings, booleans, numbers, lists of symbols/strings/numbers).
*** Tool Call Response
The expected format of an LLM's `tool_calls` response will be parsed using a dedicated JSON parsing library. `parse-tool-call-arguments` will handle the conversion to lisp datatypes based upon the `json-schema`

52
skills/org-skill-harness-monitor.org Normal file
View File

@@ -0,0 +1,52 @@
:PROPERTIES:
:ID: 6c4a56db-170e-433b-8e6b-66249cdc6b4d
:CREATED: [2026-04-12 Sun 20:00]
:END:
#+TITLE: SKILL: Harness Monitor
#+STARTUP: content
#+FILETAGS: :system:monitor:telemetry:psf:
#+DEPENDS_ON: id:47425a43-2be0-423c-8509-22592cfe9c9e
* Overview
The *Harness Monitor* provides tools for inspecting the internal state and health of the Org-Agent Lisp Machine.
* Implementation
#+begin_src lisp :tangle ../src/harness-monitor.lisp
(in-package :org-agent)
(org-agent:def-cognitive-tool :harness-status \"Returns the current operational status of the Org-Agent harness, including loaded skills and telemetry.\"
nil
:body (lambda (args)
(declare (ignore args))
(format nil \"HARNESS STATUS:
- Active Skills: ~a
- Uptime: ~a seconds
- Memory Usage: ~a
- Providers: ~a\"
(hash-table-count org-agent:*skills-registry*)
(get-universal-time)
\"Not implemented\"
org-agent:*provider-cascade*)))
(org-agent:def-cognitive-tool :list-skills \"Lists all currently loaded skills and their metadata.\"
nil
:body (lambda (args)
(declare (ignore args))
(let ((output \"LOADED SKILLS:
\"))
(maphash (lambda (name skill)
(setf output (concatenate 'string output
(format nil \"- ~a (Priority: ~a, Deps: ~s)~%\"
name
(org-agent:skill-priority skill)
(org-agent:skill-dependencies skill)))))
org-agent:*skills-registry*)
output)))
(defskill :skill-harness-monitor
:priority 100
:trigger (lambda (context) t)
:neuro (lambda (context) \"You are the Harness Monitor. Use your tools to provide system visibility.\")
:symbolic (lambda (action context) action))
#+end_src

89
skills/org-skill-inbox-processor.org
View File

@@ -1,89 +0,0 @@
:PROPERTIES:
:ID: 95029300-1d11-444c-a90a-a9f2c5474ca9
:CREATED: [2026-04-04 Sat 20:27]
:EDITED: [2026-04-07 Tue 13:42]
:END:
#+TITLE: SKILL: Enriched Inbox Processor Agent (Universal Literate Note)
#+STARTUP: content
#+FILETAGS: :inbox:processor:workflow:psf:
* Overview
The *Enriched Inbox Processor Agent* is responsible for the daily migration of captured nodes from ~inbox.org~ to the ~daily/~ archive. It enforces a strict privacy wall for ~@personal~ content while providing deep semantic enrichment for public research.
* Phase A: Demand (PRD)
:PROPERTIES:
:STATUS: FROZEN
:END:
** 1. Purpose
Automate the sorting and enrichment of inbox captures.
** 2. User Needs
- *Privacy Wall:* Headlines tagged ~@personal~ are moved **symbolically only**. No LLM processing allowed.
- *Semantic Enrichment:* For public items (non-@personal), generate:
1. A **Summary** sub-heading (1 sentence).
2. A **Significance** paragraph explaining the PSF use-case.
3. A **Full Text** extraction for items tagged ~!archive~.
- *Archive-First:* ALL originals are moved to ~daily/YYYY-MM-DD.org~ based on the ~:CREATED:~ property.
* Phase B: Blueprint (PROTOCOL)
:PROPERTIES:
:STATUS: SIGNED
:END:
** 1. Architectural Intent
Iterate through the inbox. Use System 2 (Symbolic) to identify the tag. If ~@personal~, perform a direct move. If not, trigger System 1 (Neuro) for enrichment.
* Phase D: Build (Implementation)
** Helper: Privacy & Archive Checks
#+begin_src lisp :tangle ../src/processor-logic.lisp
(in-package :org-agent)
(defun inbox-is-private-p (tags)
(member "@personal" tags :test #'string-equal))
(defun inbox-is-archive-p (tags)
(member "!archive" tags :test #'string-equal))
#+end_src
** Neural Stage (Enrichment)
#+begin_src lisp :tangle ../src/processor-logic.lisp
(in-package :org-agent)
(defun neuro-skill-inbox-processor (context)
(let* ((payload (getf context :payload))
(content (getf payload :content))
(tags (getf payload :tags))
(is-archive (inbox-is-archive-p tags)))
(ask-neuro content :system-prompt
(format nil "You are the PSF Librarian. Your goal is to ENRICH this Org-mode capture.
RULES:
1. Create a '** Summary' sub-heading with a 1-sentence summary.
2. Create a '** Significance' sub-heading with a paragraph explaining why this matters to a Sovereign Lisp Machine and how it can be used.
3. ~:[~;~* ARCHIVE MODE: Extract the full text of the item into a '** Full Text' sub-heading, preserving Org-mode structure.~]
4. Return ONLY a Lisp plist with :summary :significance :full-text.
5. NO conversational filler." is-archive))))
#+end_src
** Symbolic Stage (The Physical Move)
#+begin_src lisp :tangle ../src/processor-logic.lisp
(in-package :org-agent)
(defun inbox-process-logic (action context)
(declare (ignore action))
(let* ((payload (getf context :payload))
(sensor (getf payload :sensor)))
(when (eq sensor :heartbeat)
(let* ((base-dir (or (uiop:getenv "MEMEX_DIR") "/home/user/memex/"))
(inbox-path (merge-pathnames "inbox.org" base-dir)))
(org-agent:harness-log "INBOX - Scanning ~a for migration..." (uiop:native-namestring inbox-path))
;; Physical move logic would go here using Org AST parsing
'(:target :system :payload (:action :message :text "Inbox processing complete (Simulation)."))))))
#+end_src
* Registration
#+begin_src lisp
(defskill :skill-inbox-processor
:priority 100
:trigger (lambda (context) (eq (getf (getf context :payload) :sensor) :heartbeat))
:neuro #'neuro-skill-inbox-processor
:symbolic #'inbox-process-logic)
#+end_src

103
skills/org-skill-latent-reflection.org
View File

@@ -1,103 +0,0 @@
:PROPERTIES:
:ID: latent-reflection-skill
:CREATED: [2026-04-09 Thu]
:END:
#+TITLE: SKILL: Latent Reflection (Proactive Gardening)
#+STARTUP: content
#+FILETAGS: :memory:gardening:reflection:psf:
#+DEPENDS_ON: id:state-persistence-skill
* Overview
The *Latent Reflection* skill utilizes the idle cycles of the heartbeat to proactively garden the Memex. By randomly sampling the knowledge graph, it surfaces forgotten connections and synthesizes new insights without direct user prompting. This mimics the human default mode network, fostering creativity and serendipity.
* Implementation
** Package
#+begin_src lisp :tangle ../src/latent-reflection.lisp
(in-package :org-agent)
#+end_src
** State
We maintain an interval to prevent the agent from spamming the LLM on every 60-second heartbeat.
#+begin_src lisp :tangle ../src/latent-reflection.lisp
(defvar *last-reflection-time* 0)
(defvar *reflection-interval* 14400) ;; 4 hours by default
#+end_src
** Random Sampling (sample-random-memories)
Selects N random objects from the entire `*object-store*`.
#+begin_src lisp :tangle ../src/latent-reflection.lisp
(defun sample-random-memories (count)
"Returns COUNT random objects from the object-store."
(let ((keys nil)
(selected nil))
(maphash (lambda (k v) (declare (ignore v)) (push k keys)) *object-store*)
(let ((len (length keys)))
(when (> len 0)
(dotimes (i count)
(let* ((random-key (nth (random len) keys))
(obj (gethash random-key *object-store*)))
(when obj
(push obj selected))))))
selected))
#+end_src
** Tool Registry
Allows the user to manually trigger a reflection cycle if desired.
#+begin_src lisp :tangle ../src/latent-reflection.lisp
(def-cognitive-tool :trigger-latent-reflection "Manually triggers a proactive gardening cycle."
:parameters nil
:body (lambda (args)
(declare (ignore args))
(setf *last-reflection-time* 0)
"Latent reflection triggered. Wait for the next heartbeat."))
#+end_src
** Skill Definition
Hooks into the `:heartbeat` sensor.
#+begin_src lisp :tangle ../src/latent-reflection.lisp
(defskill :skill-latent-reflection
:priority 30
:trigger (lambda (ctx)
(let* ((payload (getf ctx :payload))
(sensor (getf payload :sensor))
(now (get-universal-time)))
(if (and (eq sensor :heartbeat)
(> (- now *last-reflection-time*) *reflection-interval*))
(progn
(harness-log "GARDENER - Initiating Latent Reflection...")
(setf *last-reflection-time* now)
t)
nil)))
:neuro (lambda (ctx)
(declare (ignore ctx))
(let* ((memories (sample-random-memories 3))
(context-string "LATENT REFLECTION CANDIDATES:\n"))
(dolist (m memories)
(let ((title (or (getf (org-object-attributes m) :TITLE) "Untitled"))
(content (or (org-object-content m) "")))
(setf context-string
(concatenate 'string context-string
(format nil "- ID: ~a | TITLE: ~a | CONTENT: ~a~%"
(org-object-id m) title content)))))
(format nil "You are the Proactive Gardener of the Memex.
I have selected 3 random notes from the knowledge graph.
Please read them and synthesize a 'Latent Reflection'.
Find hidden connections, suggest new tags, or propose a new insight that bridges them.
~a
MANDATE: Output EXACTLY ONE Common Lisp property list starting with (:type :REQUEST).
Use the :emacs target and :insert-at-end action to write your reflection into the \"*org-agent-chat*\" buffer."
context-string)))
:symbolic (lambda (action ctx)
(declare (ignore ctx))
;; Approve any safe request
action))
#+end_src

59
skills/org-skill-lisp-machine-bootstrap.org
View File

@@ -1,59 +0,0 @@
:PROPERTIES:
:ID: 81e3492e-0d28-416c-a67c-c7f6f114643d
:CREATED: [2026-04-07 Tue 12:57]
:EDITED: [2026-04-07 Tue 13:42]
:END:
#+TITLE: SKILL: Lisp Machine Bootstrap (Universal Literate Note)
#+STARTUP: content
#+FILETAGS: :hardware:lisp:sovereignty:fpga:psf:
* Overview
The *Lisp Machine Bootstrap* project is the "Endgame" of the PSF. It aims to eliminate the "Unix/C Tax" by building a hardware-native Lisp machine where CAR, CDR, and CONS are primitive gates. This ensures ultimate digital sovereignty and a provably secure, homoiconic environment.
* Phase A: Demand (PRD)
:PROPERTIES:
:STATUS: FROZEN
:END:
** 1. Purpose
Define the requirements for a hardware environment optimized for Lisp and user sovereignty.
** 2. User Needs
- *Hardware-Native Lisp:* ISA designed for list processing efficiency.
- *Tagged Memory:* Hardware-level safety preventing memory corruption.
- *Bootstrapping Path:* Progression from Soft Machine (Linux) to Sovereign Silicon (ASIC).
- *Transparency:* Every gate and instruction must be introspectable and documented.
** 3. Success Criteria
*** TODO Research existing Lisp-on-FPGA implementations (Openora, etc.)
*** TODO Define minimum hardware-native Lisp ISA (Instruction Set Architecture)
*** TODO Draft CLOSOS-style Virtual Machine specification
*** TODO FPGA Implementation: Verilog/VHDL skeleton synthesis
* Phase B: Blueprint (PROTOCOL)
:PROPERTIES:
:STATUS: SIGNED
:END:
** 1. Architectural Intent
The protocol defines the interface between the high-level Lisp image and the low-level ISA/VM.
** 2. Semantic Interfaces
#+begin_src lisp
(defun isa-dispatch (instruction opcode)
"Simulates the hardware dispatch of a Lisp-native instruction.")
(defun memory-tag-audit (address)
"Verifies the hardware tag of a specific memory word.")
#+end_src
* Phase D: Build (Implementation)
Current focus is on research and simulation (Phase 1: Soft Machine).
** Simulation Interface
#+begin_src lisp
;; Soft machine simulator stubs
#+end_src
* Phase E: Chaos (Verification)
Verification will occur via FPGA synthesis reports and VM regression tests.

4
skills/org-skill-lisp-repair.org
View File

@@ -7,7 +7,7 @@
#+FILETAGS: :system:repair:syntax:lisp:psf:
* Overview
The *Lisp Repair Syntax Gate* asynchronously intercepts `:syntax-error` events emitted by the harness when System 1 (LLM) proposals fail to parse. It performs deterministic or neural repairs and re-injects the corrected action into the pipeline.
The *Lisp Repair Syntax Gate* asynchronously intercepts `:syntax-error` events emitted by the harness when Probabilistic Engine (LLM) proposals fail to parse. It performs deterministic or neural repairs and re-injects the corrected action into the pipeline.
* Implementation
@@ -32,7 +32,7 @@ The *Lisp Repair Syntax Gate* asynchronously intercepts `:syntax-error` events e
code)))
(defun neural-repair (code error-message)
"Uses System 1 to deeply repair the syntax structure."
"Uses Probabilistic Engine to deeply repair the syntax structure."
(let ((prompt (format nil "The following Lisp code failed to parse.
ERROR: ~a
CODE: ~a

88
skills/org-skill-safety-harness.org → skills/org-skill-lisp-validator.org
View File

@@ -3,12 +3,12 @@
:CREATED: [2026-03-31 Tue 18:28]
:EDITED: [2026-04-09 Thu]
:END:
#+TITLE: SKILL: Global Safety Harness (Universal Literate Note)
#+TITLE: SKILL: Lisp Validator
#+STARTUP: content
#+FILETAGS: :security:sandbox:ast:psf:
#+FILETAGS: :security:lisp:ast:psf:
* Overview
The *Global Safety Harness* is the primary "Safety Gate" for the Neurosymbolic Lisp Machine. It provides a recursive AST validator that subjects all Elisp/Lisp proposals from System 1 to a strict "Deny-by-Default" sandbox, preventing arbitrary code execution while allowing high-fidelity system manipulation.
The *Lisp Validator* is the primary structural gate for the Neurosymbolic Lisp Machine. It provides a recursive AST validator that subjects all Lisp proposals from the Probabilistic Engine to a strict "Deny-by-Default" sandbox.
* Phase A: Demand (PRD)
:PROPERTIES:
@@ -22,7 +22,7 @@ Define a high-integrity, recursive security sandbox for Lisp execution.
- *Recursive Validation:* Every nested function call and variable access MUST be checked.
- *Deny-by-Default:* Only explicitly whitelisted functions and variables are permitted.
- *Eval Protection:* Block all forms of `eval`, `load`, or dynamic execution.
- *Symbolic Preemption:* This skill acts as a mandatory global System 2 check.
- *Symbolic Preemption:* This skill acts as a mandatory global Deterministic Engine check.
** 3. Success Criteria
*** DONE Implement recursive AST walker in Lisp
@@ -33,13 +33,13 @@ Define a high-integrity, recursive security sandbox for Lisp execution.
* Implementation
** Package
#+begin_src lisp :tangle ../src/safety-harness.lisp
#+begin_src lisp :tangle ../src/lisp-validator.lisp
(in-package :org-agent)
#+end_src
** Whitelist Definition
#+begin_src lisp :tangle ../src/safety-harness.lisp
(defparameter *safety-whitelist*
#+begin_src lisp :tangle ../src/lisp-validator.lisp
(defparameter *lisp-validator-whitelist*
'(;; Math & Logic
+ - * / = < > <= >= 1+ 1- min max
and or not null eq eql equal string= string-equal
@@ -82,26 +82,26 @@ Define a high-integrity, recursive security sandbox for Lisp execution.
#+end_src
** Dynamic Symbol Registration
We allow other skills to register safe symbols for the harness.
We allow other skills to register safe symbols for the validator.
#+begin_src lisp
(defvar *safety-registry* nil
#+begin_src lisp :tangle ../src/lisp-validator.lisp
(defvar *lisp-validator-registry* nil
"List of dynamically registered safe symbols.")
(defun safety-harness-register (symbols)
"Adds symbols to the global safety registry."
(setf *safety-registry* (append *safety-registry* (if (listp symbols) symbols (list symbols))))
(harness-log "SAFETY HARNESS: Registered ~a new safe symbols." (length (if (listp symbols) symbols (list symbols)))))
(defun lisp-validator-register (symbols)
"Adds symbols to the global validator registry."
(setf *lisp-validator-registry* (append *lisp-validator-registry* (if (listp symbols) symbols (list symbols))))
(harness-log "LISP VALIDATOR: Registered ~a new safe symbols." (length (if (listp symbols) symbols (list symbols)))))
(defun safety-harness-is-safe (symbol)
(defun lisp-validator-is-safe (symbol)
"Checks if a symbol is in the static whitelist or the dynamic registry."
(or (member symbol *safety-whitelist* :test #'string-equal)
(member symbol *safety-registry* :test #'string-equal)))
(or (member symbol *lisp-validator-whitelist* :test #'string-equal)
(member symbol *lisp-validator-registry* :test #'string-equal)))
#+end_src
** Recursive AST Walker
#+begin_src lisp
(defun safety-harness-ast-walk (form)
#+begin_src lisp :tangle ../src/lisp-validator.lisp
(defun lisp-validator-ast-walk (form)
"Recursively walks the Lisp AST. Returns T if safe, NIL if unsafe."
(cond
;; Self-evaluating objects (strings, numbers, keywords) are safe.
@@ -109,39 +109,39 @@ We allow other skills to register safe symbols for the harness.
t)
;; Symbols used as variables (in non-function position)
((symbolp form)
(safety-harness-is-safe form))
(lisp-validator-is-safe form))
;; Lists represent function calls or special forms.
((listp form)
(let ((head (car form)))
(cond
((eq head 'quote) t)
((not (symbolp head)) nil)
((safety-harness-is-safe head)
(every #'safety-harness-ast-walk (cdr form)))
((lisp-validator-is-safe head)
(every #'lisp-validator-ast-walk (cdr form)))
(t
(harness-log "SAFETY HARNESS: Blocked call to non-whitelisted function ~a" head)
(harness-log "LISP VALIDATOR: Blocked call to non-whitelisted function ~a" head)
nil))))
(t nil)))
#+end_src
** Cognitive Tools
#+begin_src lisp
(org-agent:def-cognitive-tool :security-telemetry "Returns security-related telemetry, including blocked actions and harness status."
#+begin_src lisp :tangle ../src/lisp-validator.lisp
(org-agent:def-cognitive-tool :lisp-validator-status "Returns validator-related telemetry, including blocked actions and harness status."
nil
:body (lambda (args)
(declare (ignore args))
(format nil "SAFETY HARNESS STATUS:
(format nil "LISP VALIDATOR STATUS:
- Static Whitelist: ~a symbols
- Dynamic Registry: ~a symbols
- Total Blocked Actions: ~a"
(length *safety-whitelist*)
(length *safety-registry*)
(length *lisp-validator-whitelist*)
(length *lisp-validator-registry*)
"Not implemented")))
#+end_src
** Skill Definition
#+begin_src lisp
(org-agent:defskill :skill-safety-harness
#+begin_src lisp :tangle ../src/lisp-validator.lisp
(org-agent:defskill :skill-lisp-validator
:priority 900 ; High priority, before most skills
:trigger (lambda (ctx)
;; Check if any proposed action is an :eval or :shell call
@@ -149,37 +149,35 @@ We allow other skills to register safe symbols for the harness.
(when candidate
(let ((payload (getf candidate :payload)))
(member (getf payload :action) '(:eval :shell))))))
:neuro nil ; Purely symbolic/safety skill
:neuro nil ; Purely deterministic/safety skill
:symbolic (lambda (action context)
;; The decide-gate already calls safety-harness-validate via global logic,
;; but this skill can provide additional context or logging.
(harness-log "SYSTEM 2 [Safety]: Intercepted critical action for validation.")
(harness-log "DETERMINISTIC ENGINE [Lisp-Validator]: Intercepted critical action for structural validation.")
action))
#+end_src
* Phase E: Chaos (Verification)
#+begin_src lisp :tangle ../tests/safety-harness-tests.lisp
(defpackage :org-agent-safety-tests
#+begin_src lisp :tangle ../tests/lisp-validator-tests.lisp
(defpackage :org-agent-lisp-validator-tests
(:use :cl :fiveam :org-agent)
(:export #:safety-suite))
(in-package :org-agent-safety-tests)
(:export #:lisp-validator-suite))
(in-package :org-agent-lisp-validator-tests)
(def-suite safety-suite :description "Tests for the Global Safety Harness.")
(in-suite safety-suite)
(def-suite lisp-validator-suite :description "Tests for the Lisp Validator.")
(in-suite lisp-validator-suite)
(test test-basic-math-safe
(is (org-agent:safety-harness-validate "(+ 1 2)")))
(is (org-agent:lisp-validator-validate "(+ 1 2)")))
(test test-blocked-eval
(is (not (org-agent:safety-harness-validate "(eval '(+ 1 2))"))))
(is (not (org-agent:lisp-validator-validate "(eval '(+ 1 2))"))))
(test test-blocked-shell
(is (not (org-agent:safety-harness-validate "(uiop:run-program \"ls\")"))))
(is (not (org-agent:lisp-validator-validate "(uiop:run-program \"ls\")"))))
(test test-nested-unsafe
(is (not (org-agent:safety-harness-validate "(let ((x 1)) (delete-file \"test.txt\"))"))))
(is (not (org-agent:lisp-validator-validate "(let ((x 1)) (delete-file \"test.txt\"))"))))
(test test-safe-kernel-api
(is (org-agent:safety-harness-validate "(org-agent::lookup-object \"node-1\")")))
(is (org-agent:lisp-validator-validate "(org-agent::lookup-object \"node-1\")")))
#+end_src

4
skills/org-skill-llm-gateway.org
View File

@@ -88,7 +88,7 @@ This is the primary actuator for neural reasoning. It handles the specific JSON
(let ((api-key (vault-get-secret provider :type :api-key))
(full-prompt (format nil "~a~%~%Prompt: ~a" system-prompt prompt)))
(harness-log "SYSTEM 1: Requesting ~a (Model: ~a) [Key: ~a]"
(harness-log "PROBABILISTIC ENGINE: Requesting ~a (Model: ~a) [Key: ~a]"
provider (or model "default") (vault-mask-string api-key))
(case provider
@@ -140,7 +140,7 @@ This is the primary actuator for neural reasoning. It handles the specific JSON
#+end_src
** Cognitive Tools
The `:ask-llm` tool exposes the gateway's power to System 1, allowing it to explicitly request reasoning from a specific provider when the default cascade is insufficient.
The `:ask-llm` tool exposes the gateway's power to Probabilistic Engine, allowing it to explicitly request reasoning from a specific provider when the default cascade is insufficient.
** Registration: Tool
Register the unified gateway as a cognitive tool.

81
skills/org-skill-log-aggregator.org
View File

@@ -1,81 +0,0 @@
:PROPERTIES:
:ID: 2883a21a-6b95-4f8c-a785-3c1472a994b6
:CREATED: [2026-04-04 Sat 20:27]
:EDITED: [2026-04-07 Tue 13:42]
:END:
#+TITLE: SKILL: Log Aggregator (Universal Literate Note)
#+STARTUP: content
#+FILETAGS: :logging:observability:system:psf:
* Overview
The *Log Aggregator* monitors and summarizes system logs to provide insights into agent behavior and system health.
* Phase A: Demand (PRD)
:PROPERTIES:
:STATUS: FROZEN
:END:
** 1. Purpose
Collect and summarize agent logs.
** 2. User Needs
- *Scan:* Retrieve logs from the system.
- *Summarize:* Provide a high-level summary of recent activities.
* Phase B: Blueprint (PROTOCOL)
:PROPERTIES:
:STATUS: SIGNED
:END:
* Phase B: Blueprint (PROTOCOL)
:PROPERTIES:
:STATUS: DRAFT
:END:
** 1. Architectural Intent
The Log Aggregator will employ a modular architecture, consisting of a Log Source Connector, a Summarization Engine, and a Presenter. This allows for flexibility in adapting to different log formats and presentation styles. The system will prioritize low overhead impact on the monitored system.
** 2. Semantic Interfaces (Lisp Signatures)
*** a. Log Source Connector
#+BEGIN_SRC lisp
;;; Function: fetch-logs
;;; Description: Retrieves logs based on specified criteria.
;;; Parameters:
;;; :source (keyword) - Specifies the log source (e.g., :systemd, :file, :journald).
;;; :start-time (timestamp) - Optional. The starting timestamp for the logs.
;;; :end-time (timestamp) - Optional. The ending timestamp for the logs.
;;; :filters (list) - Optional. A list of filters to apply to the logs (e.g., '((:level . :error) (:component . "foo"))).
;;; Returns: A list of log entries (each entry being a plist).
(defun fetch-logs (&key source start-time end-time filters)
...)
#+END_SRC
*** b. Summarization Engine
#+BEGIN_SRC lisp
;;; Function: summarize-logs
;;; Description: Summarizes a list of log entries.
;;; Parameters:
;;; :log-entries (list) - A list of log entries (plists).
;;; :summary-type (keyword) - Specifies the type of summary (e.g., :count-by-level, :count-by-component, :recent-errors).
;;; Returns: A summary of the logs (a plist).
(defun summarize-logs (&key log-entries summary-type)
...)
#+END_SRC
*** c. Presenter
#+BEGIN_SRC lisp
;;; Function: present-summary
;;; Description: Presents a log summary in a human-readable format.
;;; Parameters:
;;; :summary (plist) - A log summary as returned by `summarize-logs`.
;;; :format (keyword) - Specifies the output format (e.g., :text, :html).
;;; Returns: A string containing the formatted summary.
(defun present-summary (&key summary format)
...)
#+END_SRC

12
skills/org-skill-model-explorer.org
View File

@@ -1,12 +0,0 @@
:PROPERTIES:
:ID: ae49bb72-8c5d-4392-af70-4eb00d285054
:CREATED: [2026-03-30 Mon 21:16]
:EDITED: [2026-04-07 Tue 13:42]
:END:
#+TITLE: SKILL: Model Explorer Agent (Universal Literate Note)
#+STARTUP: content
#+FILETAGS: :discovery:telemetry:psf:
* Overview
The *Model Explorer Agent* provides dynamic introspection of the system's LLM capabilities. It intercepts specific user commands to list and describe all available models across providers, rendering them as native Org-mode tables.

96
skills/org-skill-playwright.org
View File

@@ -1,96 +0,0 @@
:PROPERTIES:
:ID: playwright-bridge-skill
:CREATED: [2026-04-11 Sat 18:00]
:END:
#+TITLE: SKILL: Playwright-Python Bridge (Universal Literate Note)
#+STARTUP: content
#+FILETAGS: :intelligence:browsing:automation:psf:
* Overview
The *Playwright Bridge* provides high-fidelity web browsing capabilities by wrapping a headless Chromium instance managed via Python. It allows the agent to interact with JavaScript-heavy applications that are inaccessible to standard HTTP clients.
* Phase A: Demand (PRD)
:PROPERTIES:
:STATUS: SIGNED
:END:
** 1. Purpose
Enable the agent to "see" and "read" the modern web by executing JavaScript and waiting for network idle states.
** 2. Success Criteria
- [ ] *Interaction:* Can navigate to any URL and wait for full page rendering.
- [ ] *Extraction:* Can retrieve inner text from any CSS selector.
- [ ] *Vision:* Can take base64-encoded screenshots of rendered pages.
* Phase B: Blueprint (PROTOCOL)
:PROPERTIES:
:STATUS: SIGNED
:END:
** 1. Architectural Intent
Uses a "JSON Bridge" over standard I/O. The Lisp kernel executes a standalone Python script, passing parameters via `stdin` and receiving structured results via `stdout`.
** 2. Semantic Interfaces
- `(:target :tool :action :call :tool "browser" :args (:url "..." :action "extract_text"))`
* Phase D: Build (Implementation)
** Package Context
#+begin_src lisp :tangle ../src/playwright.lisp
(in-package :org-agent)
#+end_src
** Bridge Script Path
Calculates the location of the Python bridge script relative to the project root.
#+begin_src lisp :tangle ../src/playwright.lisp
(defun get-browser-bridge-path ()
"Returns the absolute path to the Python browser bridge script."
(let ((root (or (uiop:getenv "PROJECT_ROOT") (uiop:native-namestring (uiop:getcwd)))))
(merge-pathnames "scripts/browser-bridge.py" (uiop:ensure-directory-pathname root))))
#+end_src
** Execution Wrapper (execute-browser-command)
Invokes the Python bridge and parses its JSON output.
#+begin_src lisp :tangle ../src/playwright.lisp
(defun execute-browser-command (args)
"Invokes the Playwright Python bridge with the provided arguments."
(let* ((script-path (get-browser-bridge-path))
(json-input (cl-json:encode-json-to-string args)))
(handler-case
(let ((output (uiop:run-program (list "python3" (uiop:native-namestring script-path))
:input (make-string-input-stream json-input)
:output :string
:error-output :string)))
(cl-json:decode-json-from-string output))
(error (c)
(list :status "error" :message (format nil "Bridge Execution Failed: ~a" c))))))
#+end_src
** Cognitive Tool: Browser
Register the high-fidelity browsing tool with the harness.
#+begin_src lisp :tangle ../src/playwright.lisp
(def-cognitive-tool :browser
"High-fidelity web browsing via Playwright (Chromium). Supports JS rendering."
((:url :type :string :description "The target URL")
(:action :type :string :description "Action to perform: 'extract_text' or 'screenshot'")
(:selector :type :string :description "Optional CSS selector (default: 'body')"))
:body (lambda (args)
(let ((result (execute-browser-command args)))
(if (string= (cdr (assoc :status result)) "success")
(or (cdr (assoc :content result))
(cdr (assoc :screenshot--base64 result))
"Success (no content returned)")
(format nil "BROWSER ERROR: ~a" (cdr (assoc :message result)))))))
#+end_src
** Registration: Skill
#+begin_src lisp :tangle ../src/playwright.lisp
(defskill :skill-playwright
:priority 150
:trigger (lambda (ctx) (declare (ignore ctx)) nil) ; Passive tool provider
:neuro nil
:symbolic (lambda (action ctx) (declare (ignore ctx)) action))
#+end_src

31
skills/org-skill-policy-enforcer.org Normal file
View File

@@ -0,0 +1,31 @@
:PROPERTIES:
:ID: 9d3fe6c3-904c-4750-ad37-0364ad0c4dde
:CREATED: [2026-04-12 Sun 20:00]
:END:
#+TITLE: SKILL: Policy Enforcer
#+STARTUP: content
#+FILETAGS: :security:alignment:policy:psf:
#+DEPENDS_ON: id:47425a43-2be0-423c-8509-22592cfe9c9e
* Overview
The *Policy Enforcer* is the deterministic gate that ensures all probabilistic proposals adhere to the Core Invariants defined in the [[id:47425a43-2be0-423c-8509-22592cfe9c9e][System Policy]].
* Implementation
#+begin_src lisp :tangle ../src/policy-enforcer.lisp
(in-package :org-agent)
(defskill :skill-policy-enforcer
:priority 1000 ; Absolute highest priority
:trigger (lambda (context) t) ; Always active as a fallback
:neuro (lambda (context)
"You are the Org-Agent Policy Enforcer. Your goal is to ensure all actions empower the user through the Lisp Machine and adhere to the System Policy.")
:symbolic (lambda (action context)
;; Basic invariant check: Block actions that appear to violate sovereignty
(let ((payload (getf action :payload)))
(if (and payload (search "proprietary" (format nil "~s" payload)))
(progn
(org-agent:harness-log "DETERMINISTIC [Policy]: Sovereignty violation suspected. Blocking action.")
nil)
action))))
#+end_src

35
skills/org-skill-policy.org Normal file
View File

@@ -0,0 +1,35 @@
:PROPERTIES:
:ID: 47425a43-2be0-423c-8509-22592cfe9c9e
:CREATED: [2026-04-07 Tue 12:57]
:EDITED: [2026-04-12 Sun 20:10]
:END:
#+TITLE: SKILL: System Policy
#+STARTUP: content
#+FILETAGS: :platform:policy:alignment:
* Overview
The *Org-Agent* is a neurosymbolic harness for a personal operating system. It uses Org-mode as its native memory and Common Lisp as its deterministic reasoning engine.
This document contains the *Core System Policy*. These are non-negotiable philosophical and technical constraints that every agentic action MUST satisfy.
The Deterministic Engine uses these headlines as a "Moral Compass" during the decision stage.
* The Core Invariants
** 1. Sovereignty Above All
Every action must increase the user's independence from centralized, proprietary platforms. If a tool or library introduces a dependency on a non-sovereign entity, it must be flagged for replacement.
** 2. Technical Mastery & Mentorship
The agent's goal is not to "do it for the user," but to "empower the user." Every autonomous action must be explained at a level that increases the user's technical understanding of the Lisp Machine.
** 3. Zero-Bloat Mandate
The system harness must remain minimalist. "Just-in-case" code is a security vulnerability. Complexity must be earned, not imported.
** 4. Radical Transparency
The agent's "Thought Stream" must be fully auditable. Hidden reasoning or obfuscated logic is a violation of the system's design principles.
** 5. Long-Term Sustainability
Prioritize local, energy-efficient, and offline-first architectures. The "Memex" should be functional in a 100-year horizon.
* Operational Mandates
Every action performed by an agent in this environment must also adhere to the [[file:../../org-agent-contrib/org-skill-engineering-standards.org][Engineering Standards]].

2
skills/org-skill-state-persistence.org
View File

@@ -198,7 +198,7 @@ Restores the graph from IPFS, using a safe parser to prevent injection.
#+end_src
** Cognitive Tools
Expose persistence capabilities to the neural System 1.
Expose persistence capabilities to the neural Probabilistic Engine.
#+begin_src lisp :tangle ../src/state-persistence.lisp
(progn

82
skills/org-skill-sub-agent-manager.org
View File

@@ -1,82 +0,0 @@
:PROPERTIES:
:ID: e870d860-5db7-443a-aaf3-23cd5521b27c
:CREATED: [2026-03-31 Tue 18:28]
:EDITED: [2026-04-07 Tue 13:42]
:END:
#+TITLE: SKILL: Sub-Agent Manager (Concurrency & Parallelism)
#+STARTUP: content
#+FILETAGS: :concurrency:parallelism:threads:psf:
* Overview
The *Sub-Agent Manager* enables the Neurosymbolic Lisp Machine to handle multiple concurrent thoughts. It allows the primary kernel to "spawn" lightweight, isolated Lisp threads (sub-agents) to perform long-running or background tasks (research, massive refactors, etc.) without blocking the main event bus.
* Phase A: Demand (PRD)
:PROPERTIES:
:STATUS: FROZEN
:END:
** 1. Purpose
Define the interfaces for parallel cognitive execution and thread lifecycle management.
** 2. User Needs
- *Non-Blocking Execution:* Spawn background threads for long-running tasks.
- *Context Isolation:* Sub-agents must have their own execution context to prevent parent context poisoning.
- *Communication Loop:* Sub-agents must inject a "Return Stimulus" upon completion.
- *Observability:* Ability to list and terminate active sub-agents.
** 3. Success Criteria
*** TODO Successful spawning of a non-blocking background thread
*** TODO Verification of context isolation (distinct local variables)
*** TODO Autonomous injection of :sub-agent-complete stimulus
*** TODO Thread safety verification using bordeaux-threads locks
* Phase B: Blueprint (PROTOCOL)
:PROPERTIES:
:STATUS: SIGNED
:END:
* Phase B: Blueprint (PROTOCOL)
:PROPERTIES:
:STATUS: DRAFT
:END:
** 1. Architectural Intent
The Sub-Agent Manager is designed as a facade over a thread management library (initially `bordeaux-threads`). It provides a high-level API for spawning, managing, and monitoring sub-agents. The core principle is to create isolated Lisp environments for each sub-agent, encapsulating all state and preventing interference with the main system or other sub-agents. Communication back to the main kernel occurs through a standardized `:sub-agent-complete` stimulus injected into the event bus. Thread safety, enforced with locks where necessary, is paramount.
** 2. Semantic Interfaces (Lisp Signatures)
*** `spawn-sub-agent (task-fn &key name)`
- *Purpose:* Creates and starts a new sub-agent thread.
- *Parameters:*
- `task-fn`: A function of no arguments that contains the code to be executed in the sub-agent.
- `name`: (optional) A symbol representing the name of the sub-agent for identification and debugging.
- *Returns:* A sub-agent object (e.g., a struct) representing the spawned thread, containing its ID, status, and other metadata.
- *Side Effects:* Creates a new thread and starts the execution of `task-fn` within it.
*** `kill-sub-agent (sub-agent)`
- *Purpose:* Terminates a running sub-agent.
- *Parameters:*
- `sub-agent`: The sub-agent object (returned by `spawn-sub-agent`) representing the thread to terminate.
- *Returns:* `T` if the sub-agent was successfully terminated, `NIL` otherwise.
- *Side Effects:* Attempts to terminate the specified thread, potentially releasing any resources held by the sub-agent.
*** `list-sub-agents ()`
- *Purpose:* Returns a list of all active sub-agents.
- *Parameters:* None
- *Returns:* A list of sub-agent objects, each representing a running sub-agent.
*** `sub-agent-status (sub-agent)`
- *Purpose:* Returns the current status of a sub-agent.
- *Parameters:*
- `sub-agent`: The sub-agent object to query.
- *Returns:* A symbol representing the status of the sub-agent (e.g., `:running`, `:completed`, `:terminated`, `:error`).
*** `inject-sub-agent-completion-stimulus (result &key sub-agent)`
- *Purpose:* This PRIVATE function (not exposed directly) is called by the sub-agent, to inject knowledge of the result of its process into the stimulus stream.
- *Parameters:*
- `result`: The result of the sub-agent's computation.
- `sub-agent`: The current sub-agent (optional).
- *Returns:* `T` if stimulus was injected successfully
- *Side Effects:* Injects a `:sub-agent-complete` stimulus into the event bus. The stimulus will contain the `result` and any metadata associated with the `sub-agent` (including its name/id). The stimulus will be of the form `(:type :sub-agent-complete :result <result> :sub-agent <sub-agent>)`

148
skills/org-skill-system-invariants.org
View File

@@ -1,148 +0,0 @@
:PROPERTIES:
:ID: 47425a43-2be0-423c-8509-22592cfe9c9e
:CREATED: [2026-04-07 Tue 12:57]
:EDITED: [2026-04-12 Sun 18:30]
:END:
#+TITLE: SKILL: System Invariants (Universal Literate Note)
#+STARTUP: content
#+FILETAGS: :platform:harness:lisp:alignment:invariants:
#+DEPENDS_ON: id:37f2b59f-4537-4cca-ac7f-5c24b9e2e773
#+DEPENDS_ON: id:bbcacb7b-c0ff-4f7e-8bf4-c6ba152a19ce
#+DEPENDS_ON: id:homoiconic-memory-skill
* Overview
The *Org-Agent* is a neurosymbolic harness for a personal operating system. It uses Org-mode as its native memory and Common Lisp as its deterministic reasoning engine. It follows a minimalist design, extending its capabilities via hot-reloadable skills.
This document contains the *Core System Invariants*. These are non-negotiable philosophical and technical constraints that every agentic action MUST satisfy.
The Deliberate Engine uses these headlines as a "Moral Compass" during the decision stage.
* The Core Invariants
** 1. Sovereignty Above All
Every action must increase the user's independence from centralized, proprietary platforms. If a tool or library introduces a dependency on a non-sovereign entity, it must be flagged for replacement.
** 2. Technical Mastery & Mentorship
The agent's goal is not to "do it for the user," but to "empower the user." Every autonomous action must be explained at a level that increases the user's technical understanding of the Lisp Machine.
** 3. Zero-Bloat Mandate
The system harness must remain minimalist. "Just-in-case" code is a security vulnerability. Complexity must be earned, not imported.
** 4. Radical Transparency
The agent's "Thought Stream" must be fully auditable. Hidden reasoning or obfuscated logic is a violation of the system's design principles.
** 5. Long-Term Sustainability
Prioritize local, energy-efficient, and offline-first architectures. The "Memex" should be functional in a 100-year horizon.
* Operational Mandates
Every action performed by an agent in this environment must also adhere to the [[file:../../org-agent-contrib/org-skill-engineering-standards.org][Engineering Standards]] (e.g. Literate Granularity, Commit-Before-Modify, Continuous QA).
* Phase A: Demand (PRD)
:PROPERTIES:
:STATUS: FROZEN
:END:
** 1. Purpose
Define the core functional and security requirements for the neurosymbolic harness.
** 2. User Needs
- *Homoiconic Memory:* Use Org-mode AST as the primary data structure for both human and machine.
- *Deterministic Reasoning:* Common Lisp (SBCL) for high-performance, threaded symbolic logic.
- *Cognitive Loop:* A strict four-stage pipeline: Perceive -> Think (Associative) -> Decide (Deliberate) -> Act.
- *Minimalist Core:* The harness handles only the loop, object-store, and communication; all else is a skill.
- *Security by Default:* Reader safety (*read-eval* disabled) and package-based skill jailing.
** 3. Success Criteria
*** TODO Harness Lisp stability (Heartbeat consistency)
*** TODO Harness Protocol communication reliability
*** TODO Org AST-to-Lisp conversion fidelity
*** TODO Deliberate Safety Gating (The Harness) enforcement
* Phase B: Blueprint (PROTOCOL)
:PROPERTIES:
:STATUS: SIGNED
:END:
** 1. Architectural Intent
The harness is transport-agnostic and business-logic-agnostic. It communicates with external actuators (Emacs, Web, Signal) via the Org-Agent Communication Protocol (Harness Protocol).
** 2. Semantic Interfaces
#+begin_src lisp
(defun harness-perceive (stimulus)
"Injects an event into the global object store.")
(defun harness-think (context)
"Queries Associative (LLM) for an intuitive proposal.")
(defun harness-decide (proposal context)
"Invokes Deliberate (Symbolic Skills) to verify or overrule the proposal.")
(defun harness-act (action)
"Dispatches verified commands to the registered actuators.")
#+end_src
* Phase D: Build (Implementation)
** Cognitive Tools
We register tools for harness introspection and state management.
#+begin_src lisp :tangle ../src/system-invariants.lisp
(in-package :org-agent)
(org-agent:def-cognitive-tool :harness-status "Returns the current operational status of the Org-Agent harness, including loaded skills and telemetry."
nil
:body (lambda (args)
(declare (ignore args))
(format nil "HARNESS STATUS:
- Active Skills: ~a
- Uptime: ~a seconds
- Memory Usage: ~a
- Providers: ~a"
(hash-table-count org-agent:*skills-registry*)
(get-universal-time) ; Placeholder for actual uptime
"Not implemented"
org-agent:*provider-cascade*)))
(org-agent:def-cognitive-tool :list-skills "Lists all currently loaded skills and their metadata."
nil
:body (lambda (args)
(declare (ignore args))
(let ((output "LOADED SKILLS:
"))
(maphash (lambda (name skill)
(setf output (concatenate 'string output
(format nil "- ~a (Priority: ~a, Deps: ~s)~%"
name
(org-agent:skill-priority skill)
(org-agent:skill-dependencies skill)))))
org-agent:*skills-registry*)
output)))
#+end_src
** The System Invariants Skill
This skill acts as the default "Moral Compass" for the agent.
#+begin_src lisp :tangle ../src/system-invariants.lisp
(org-agent:defskill :skill-system-invariants
:priority 1000 ; Absolute highest priority
:trigger (lambda (context) t) ; Always active as a fallback
:neuro (lambda (context)
"You are the Org-Agent System Invariants Skill. Your goal is to empower the user through the Lisp Machine.
Follow the Core Invariants:
1. Sovereignty: Avoid proprietary traps.
2. Technical Mastery: Explain your logic.
3. Zero-Bloat: Keep it minimal.
4. Transparency: Your thoughts are auditable.
5. Sustainability: Think long-term.")
:symbolic (lambda (action context)
;; Basic invariant check: Block actions that appear to violate sovereignty
(let ((payload (getf action :payload)))
(if (and payload (search "proprietary" (format nil "~s" payload)))
(progn
(org-agent:harness-log "DELIBERATE [Invariants]: Sovereignty violation suspected. Blocking action.")
nil)
action))))
#+end_src
* Phase E: Chaos (Verification)
Verification logic is contained in `projects/org-agent/tests/`.

558
skills/org-skill-token-accountant.org
View File

@@ -1,558 +0,0 @@
:PROPERTIES:
:ID: f3e3a6b3-8cd8-4e64-a835-5cdf5d13b75b
:CREATED: [2026-04-07 Tue 13:42]
:EDITED: [2026-04-08 Wed 11:45]
:END:
#+TITLE: SKILL: Token Accountant Agent (Universal Literate Note)
#+STARTUP: content
#+FILETAGS: :infrastructure:budget:llm:psf:economics:
#+DEPENDS_ON: id:event-orchestrator-skill
* Overview
The *Token Accountant* is the governor of the Neural Engine. It manages the cost, reliability, and routing of LLM providers. Its primary mission is to ensure the PSF operates at maximum intelligence with minimum marginal cost by aggressively prioritizing subsidized free models when appropriate.
* Phase A: Demand (PRD)
:PROPERTIES:
:STATUS: SIGNED
:END:
** 1. Purpose
Autonomously manage the provider cascade and model selection to optimize for cost, speed, and reliability.
* Phase B: Blueprint (PROTOCOL)
:PROPERTIES:
:STATUS: SIGNED
:END:
** 1. Architectural Intent
Maintain a state-aware provider cascade that routes around "pain" (failures) and dynamically selects models based on task complexity.
** 2. Semantic Interfaces
*** Routing and Pain Management
#+begin_src lisp :tangle ../src/accountant-logic.lisp
(in-package :org-agent)
(defvar *provider-pain-table* (make-hash-table :test 'equal))
(defun token-accountant-record-pain (provider)
"Marks a provider as 'pained' (failed). It will be de-prioritized."
(setf (gethash provider *provider-pain-table*) (+ (get-universal-time) 600)) ; 10 min penalty
(harness-log "ACCOUNTANT - Provider ~a de-prioritized due to failure." provider))
(defun token-accountant-get-cascade (context)
"Returns a dynamic list of providers, routing around pained ones. Uses standardized gateway keywords."
(let ((all-providers '(:openrouter :groq :gemini-api :ollama))
(healthy nil)
(pained nil)
(now (get-universal-time)))
(dolist (p all-providers)
(if (> (or (gethash p *provider-pain-table*) 0) now)
(push p pained)
(push p healthy)))
(append (nreverse healthy) (nreverse pained))))
(defun token-accountant-get-model-for-provider (provider &optional context)
"Returns the recommended model for the provider, prioritizing free/subsidized models. Updated April 2026."
(let ((complexity (ignore-errors (uiop:symbol-call :org-agent.skills.org-skill-router :router-classify-complexity context))))
(case provider
(:openrouter
(case complexity
(:REASONING "meta-llama/llama-3.3-70b-instruct:free") ; High fidelity, zero cost
(:COGNITION "qwen/qwen3.6-plus:free") ; Latest interaction, zero cost
(t "meta-llama/llama-3.2-3b-instruct:free"))) ; Ultra-fast reflex, zero cost
(:groq
(case complexity
(:REASONING "llama-3.3-70b-versatile")
(t "llama-3.1-8b-instant")))
(:gemini-api
"gemini-1.5-flash-latest")
(t nil))))
(defun token-accountant-patch-kernel ()
"Hot-patches the harness's cascade and model selector to use our dynamic logic."
(setf org-agent:*provider-cascade* #'token-accountant-get-cascade)
(setf org-agent::*model-selector-fn* #'token-accountant-get-model-for-provider))
#+end_src
* Registration
#+begin_src lisp
(progn
(token-accountant-patch-kernel)
(defskill :skill-token-accountant
:priority 100
:trigger (lambda (context)
(let ((sensor (getf (getf context :payload) :sensor)))
(or (eq sensor :tool-error) (eq sensor :cost-audit))))
:neuro (lambda (context) nil)
:symbolic (lambda (action context)
(let ((p (getf (getf context :payload) :provider)))
(when p (token-accountant-record-pain p))
action))))
#+end_src
* Documentation (Token Optimization)
** research.org
#+TITLE: Token Management & Model Optimization Research
#+author: Amero Garcia
#+created: [2026-03-16 Mon 14:28]
#+DATE: 2026-03-04
#+FILETAGS: :research:token:optimization:models
* Token Management Strategy Research
** Initial Findings
*** OpenRouter Free Tier
- URL: https://openrouter.ai/collections/free-models
- Providers moving from free to paid-only models
- Belief: "Free models play crucial role in democratizing access"
*** Google AI Studio (Gemini)
- Free tier available
- Limits: 60 requests/minute, 300K tokens/day
- No credit card required
- Every API key gets these limits
** Research Questions
1. Which providers offer free or low-cost tiers?
2. What are the rate limits and quotas?
3. Which models are best for which use cases?
4. How to optimize context windows?
5. What is the cost per token breakdown?
** To Research Further
| Provider | Free Tier | Paid Tier | Best For |
|----------|-----------|-----------|----------|
| Google Gemini | 300K tokens/day | Pay per use? | General, coding |
| OpenRouter | Varies by model | Per-request | Routing, variety |
| OpenAI | ? | ? | GPT-4 quality |
| Anthropic | ? | ? | Claude capabilities |
| Mistral | ? | ? | Open weights |
| Local | Hardware cost | Free | Privacy, control |
** Token Optimization Strategies to Explore
1. *Tiered Model Usage*
- Simple tasks: Fast/cheap models
- Complex tasks: Stronger models
- Fallback: Lower tier if higher fails
2. *Context Compression*
- Summarize long contexts
- Use RAG instead of full context
- Prune old conversation
3. *Caching*
- Cache common responses
- Reuse embeddings
- Batch requests
4. *Hybrid Approach*
- Local models for simple queries
- Cloud APIs for complex tasks
- Manual review for critical outputs
** X Account Access
*Pending:* X account access via Google login
*Blocker:* Requires OTP from user per security rule (SOUL.md)
*Action needed:* User provides OTP, I complete OAuth, access bookmarks
** budget-50.org
#+TITLE: Token Optimization - $50 Monthly Budget
#+author: Amero Garcia
#+created: [2026-03-16 Mon 14:28]
#+DATE: 2026-03-04
#+FILETAGS: :budget:constraints:optimization
* Budget: $50/Month
** Budget Breakdown
| Tier | Provider | Allocation | Tokens Est. | Use Case |
|------|----------|-----------|-------------|----------|
| FREE | Google Gemini | $0 | ~9M/month | 90% of work |
| CHEAP | OpenRouter | $20 | ~6M tokens | Fallback, complex tasks |
| PREMIUM | Claude/GPT-4o | $25 | ~500K tokens | Critical decisions |
| BUFFER | Various | $5 | Emergency | Overruns, testing |
** Daily Free Allowance
- *Google Gemini:* 300K tokens/day = 9M/month = *$0*
- This covers 90-95% of expected workload
** Paid Tier Allocation ($45)
- *$20 → OpenRouter* (Qwen, Mistral, Llama)
- ~6M tokens at $0.003/1K
- Use when: Gemini rate limited, need different model
- *$25 → Premium models* (Claude, GPT-4o)
- ~500K tokens at $0.05/1K average
- Use when: Architecture decisions, critical code review, final validation
- *$5 → Buffer*
- Handle overruns
- Emergency access
- Testing new models
** Hard Limits
| Provider | Monthly Cap | Alert At |
|----------|-------------|----------|
| OpenRouter | $20 | $16 (80%) |
| Premium | $25 | $20 (80%) |
| Total | $50 | $45 (90%) |
** Daily Tracking
Target: *Monitor consumption every session*
```
IF daily_cost > $1.50:
→ Switch to Gemini only
→ Defer premium tasks
IF weekly_cost > $12:
→ Review usage patterns
→ Find optimization opportunities
```
** Emergency Protocol
If approaching $50 limit before month end:
1. Halt all paid API calls
2. Switch to Gemini-only mode
3. Queue premium tasks for next month
4. Consider local inference setup
** Cost-Per-Task Guidelines
| Task Type | Max Cost | Preferred Model |
|-----------|----------|-----------------|
| Quick lookup | $0.00 | Gemini |
| Code review | $0.01 | Gemini/OpenRouter |
| Feature design | $0.05 | OpenRouter |
| Architecture review | $0.10 | Claude/GPT-4o |
| Emergency debug | $0.20 | Best available |
** Optimization Imperative
With $50/month, waste is not affordable:
- ❌ No speculative queries
- ❌ No "just curious" premium calls
- ❌ No repeated similar prompts
- ✅ Always use Gemini first
- ✅ Batch similar requests
- ✅ Cache embeddings locally
- ✅ Summarize long contexts
** Monthly Review
1. Compare actual vs. projected usage
2. Adjust model routing rules
3. Identify expensive query patterns
4. Plan next month's allocation
** Break-Even Analysis
At $50/month = $600/year:
- *Option A:* Continue APIs (flexible, managed)
- *Option B:* Local inference (~$800 hardware, $0 ongoing)
- Break-even: 16 months
- Risk: Hardware failure, maintenance
*Recommendation:* Stick with APIs until $100+/month, then evaluate hardware.
** Questions for Human Partner
1. Is $50 firm or flexible in emergencies?
2. What happens if we hit limit mid-critical-task?
3. Preference for which premium model? (Claude vs GPT-4 vs both)
4. Should I track and report costs per project?
5. Any tasks that are "unlimited budget" critical?
** README.org
#+TITLE: Token Optimization
#+AUTHOR: Amr
#+CREATED: [2026-03-17 Tue]
#+BEGIN_COMMENT
Cost-effective LLM usage through smart routing, context compression, and multi-provider strategies.
#+END_COMMENT
* Token Optimization
Strategy and implementation for minimizing LLM costs while maintaining quality.
* Project Tasks
See the actionable tasks for this project in [[file:../../gtd.org::*Token Optimization][GTD.org > Projects > Token Optimization]]
* Key Documents
- [[file:plan.org][Optimization Plan]]
- [[file:token-optimization.yaml][Configuration]]
* Current Focus
- Multi-provider setup (Gemini primary, OpenRouter fallback)
- Usage tracking and budget alerts
- Smart routing by task type
- Context compression techniques
** quick-start.org
#+TITLE: Token Optimization - Quick Start
#+author: Amero Garcia
#+created: [2026-03-16 Mon 14:28]
#+DATE: 2026-03-04
* Quick Reference for Daily Use
** Rule of Thumb
| What you need | Use this | Cost |
|---------------|----------|------|
| Quick answer, formatting, lookup | Gemini Flash | FREE |
| Code review, analysis | Gemini Pro | FREE |
| Complex problem solving | Claude Haiku / Qwen | $ |
| Critical architecture decision | GPT-4o | $$ |
** Free Tier Limits (Daily)
| Provider | Tokens | Requests | Reset |
|----------|--------|----------|-------|
| Google AI Studio | 300,000 | 60/min | Daily |
| OpenRouter Free | Varies | Limited | - |
** Current Recommendation
→ *Use Google Gemini exclusively* until hitting 250K tokens/day
→ Then add OpenRouter fallback
→ Only use GPT-4 for final reviews
** This will reduce token costs by ~90%
** Next Steps
1. Configure Gemini as primary (already partially done)
2. Add quota tracking
3. Set alerts at 80% of free limits
4. Implement tiered routing
** Savings Potential: $100-500/month → $10-50/month
** plan.org
#+TITLE: Token Optimization Strategy
#+author: Amero Garcia
#+created: [2026-03-16 Mon 14:28]
#+DATE: 2026-03-04
#+FILETAGS: :strategy:token:optimization:cost
* Executive Summary
** Goal: Minimize inference costs while maximizing capability
Current approach: Single default model → Multi-tier, multi-provider strategy
* Three-Tier Model Strategy
** Tier 1: Fast/Cheap (80% of queries)
- *Purpose:* Simple tasks, formatting, lookups
- *Models:* Google Gemini Flash, Local models
- *Cost:* $0-0.000001 per 1K tokens
- *Speed:* Fastest
** Tier 2: Balanced (18% of queries)
- *Purpose:* Complex reasoning, code generation, analysis
- *Models:* Gemini Pro, Claude Haiku, Llama 3 70B
- *Cost:* $0.0001-0.003 per 1K tokens
- *Speed:* Medium
** Tier 3: High-Performance (2% of queries)
- *Purpose:* Critical decisions, complex architecture, final review
- *Models:* GPT-4, Claude Opus, Gemini Ultra
- *Cost:* $0.01-0.03 per 1K tokens
- *Speed:* Slower
* Provider Analysis
** Google AI Studio (Primary Recommended)
| Model | Free Tier | Rate Limit | Best For |
|-------|-----------|------------|----------|
| Gemini 2.0 Flash | 300K tokens/day | 60 req/min | Quick tasks, coding |
| Gemini 1.5 Flash | 300K tokens/day | 60 req/min | Fast responses |
| Gemini 1.5 Pro | 300K tokens/day | 60 req/min | Complex tasks |
*Cost: FREE (within limits)*
** OpenRouter.Aggregated (Secondary)
| Model | Price/1K tokens | Context | Reliability |
|-------|-----------------|---------|-------------|
| Qwen 3 235B | $0.0001-0.0003 | 128K | High |
| Mistral Large | $0.002-0.006 | 128K | High |
| Llama 4 405B | $0.0002-0.0005 | 128K | Medium |
| Free tier models | $0 | Varies | Variable |
** OpenAI (Tier 3 only)
- GPT-4: $0.03/1K tokens (expensive)
- GPT-4o: $0.005/1K tokens (better value)
- Use sparingly for critical tasks only
** Local Inference (Long-term goal)
- Hardware: $1000-5000 initial investment
- Ongoing: $0 (electricity only)
- Models: Llama 3, Mistral, DeepSeek
- Best for: High-volume, privacy-sensitive work
* Context Optimization Strategies
** 1. Context Windows by Task Type
| Task Type | Optimal Context | Compression | Savings |
|-----------|-----------------|-------------|---------|
| Code review | 4K-8K | Truncate old files | 50% |
| Documentation | 8K-16K | Summarize sections | 30% |
| Research | 16K-32K | Chunk + RAG | 70% |
| Architecture | 32K-128K | Maintain full | 0% |
** 2. Conversation Pruning
- Remove "thinking" blocks from history
- Summarize conversation every 10 turns
- Archive old sessions to external storage
** 3. RAG vs. Full Context
- *Rule:* < 5K tokens of context → Full
- *Rule:* > 10K tokens of context → Use embeddings/RAG
- *Savings:* 60-80% on large document tasks
* Request Optimization
** Batching Strategy
- Group similar requests (3-5 per batch)
- Same model, same parameters
- Shared overhead costs
** Caching Strategy
- Cache embeddings for repeated contexts
- Store common completions (templates)
- Reuse code snippet suggestions
** Streaming vs. Non-Stream
- *Streaming:* Better UX, but higher token overhead
- *Non-stream:* More efficient for programmatic use
- *Recommendation:* Non-stream for background tasks
* Smart Routing Rules
** Automatic Selection Logic
```
IF task_type == "simple_lookup" OR "formatting":
→ Gemini Flash (free)
ELIF task_type == "code_generation" AND complexity < 3:
→ Gemini Pro (free tier)
ELIF task_type == "complex_reasoning" OR "architecture":
→ Claude Sonnet or GPT-4o
ELIF task_type == "final_review" OR "critical_decision":
→ GPT-4 or Claude Opus
```
** Fallback Chain
1. Try Gemini (free)
2. If rate limited → OpenRouter (cheap)
3. If quality insufficient → GPT-4o
4. If critical failure → GPT-4
* Concrete Implementation
** Config Structure (openclaw.json)
```json
{
"models": {
"defaults": {
"primary": "google-gemini-cli/gemini-2.0-flash",
"fallbacks": [
"openrouter/qwen/qwen3-235b-a22b",
"google-gemini-cli/gemini-1.5-pro",
"openai/gpt-4o"
]
},
"providers": {
"google-gemini-cli": {
"freeTier": true,
"dailyLimit": 300000,
"rateLimit": 60
},
"openrouter": {
"freeTierModels": ["openrouter/auto"],
"budgetLimit": 500
},
"openai": {
"budgetLimit": 200,
"useFor": ["critical", "architecture"]
}
}
}
}
```
** Monitoring & Alerts
- Track daily token usage per provider
- Alert at 80% of free tier limits
- Monthly budget review and adjustment
* Cost Projections
** Current Unknown Usage → Optimized
| Scenario | Monthly Tokens | Current Cost | Optimized Cost | Savings |
|----------|---------------|--------------|----------------|---------|
| Light (< 1M) | 1M | $50-100 | $0-10 | 90% |
| Medium (1-5M) | 3M | $200-500 | $20-100 | 80% |
| Heavy (5-20M) | 10M | $1000-3000 | $200-500 | 80% |
* Immediate Actions
** Week 1: Setup
- Configure Gemini as primary provider
- Set up OpenRouter fallback
- Implement basic usage tracking
- Document current baseline
** Week 2: Implement
- Add smart routing logic
- Implement context compression
- Set up budget alerts
- A/B test model choices
** Week 3: Optimize
- Analyze usage patterns
- Fine-tune routing rules
- Tune context windows
- Document findings
** Week 4: Scale
- Full multi-provider setup
- Implement full caching
- Maximize free tier usage
- Plan for paid tiers if needed
* Long-term: Local Inference Path
** Minimum Viable Setup
- Hardware: RTX 4090 or Apple Silicon M3 Max
- Software: Ollama + OpenClaw integration
- Cost: ~$2000-4000 one-time
- Break-even: 3-6 months vs. API costs
** Full Self-Hosted
- Hardware: Dual RTX 4090 or 2x Mac Studio
- Models: Llama 3 70B, Mixtral 8x22B
- Cost: ~$8000-12000
- For: Privacy, unlimited inference, control

2
src/engineering-standards.lisp
View File

@@ -17,7 +17,7 @@
(when (member act '(:modify-file :write-file :replace :rename-file :delete-file))
(let ((proj-root (asdf:system-source-directory :org-agent)))
(unless (verify-git-clean-p proj-root)
(harness-log "DELIBERATE [Standards]: BLOCKING ACTION. Working tree is dirty. Commit changes before modification.")
(harness-log "DETERMINISTIC [Standards]: BLOCKING ACTION. Working tree is dirty. Commit changes before modification.")
(return-from engineering-standards-gate
(list :type :LOG :payload (list :text "Engineering Standard Violation: Working tree dirty. You MUST commit before modifying files."))))))

36
src/harness-monitor.lisp Normal file
View File

@@ -0,0 +1,36 @@
(in-package :org-agent)
(org-agent:def-cognitive-tool :harness-status \"Returns the current operational status of the Org-Agent harness, including loaded skills and telemetry.\"
nil
:body (lambda (args)
(declare (ignore args))
(format nil \"HARNESS STATUS:
- Active Skills: ~a
- Uptime: ~a seconds
- Memory Usage: ~a
- Providers: ~a\"
(hash-table-count org-agent:*skills-registry*)
(get-universal-time)
\"Not implemented\"
org-agent:*provider-cascade*)))
(org-agent:def-cognitive-tool :list-skills \"Lists all currently loaded skills and their metadata.\"
nil
:body (lambda (args)
(declare (ignore args))
(let ((output \"LOADED SKILLS:
\"))
(maphash (lambda (name skill)
(setf output (concatenate 'string output
(format nil \"- ~a (Priority: ~a, Deps: ~s)~%\"
name
(org-agent:skill-priority skill)
(org-agent:skill-dependencies skill)))))
org-agent:*skills-registry*)
output)))
(defskill :skill-harness-monitor
:priority 100
:trigger (lambda (context) t)
:neuro (lambda (context) \"You are the Harness Monitor. Use your tools to provide system visibility.\")
:symbolic (lambda (action context) action))

2
src/lisp-repair.lisp
View File

@@ -17,7 +17,7 @@
code)))
(defun neural-repair (code error-message)
"Uses System 1 to deeply repair the syntax structure."
"Uses Probabilistic Engine to deeply repair the syntax structure."
(let ((prompt (format nil "The following Lisp code failed to parse.
ERROR: ~a
CODE: ~a

102
src/lisp-validator.lisp Normal file
View File

@@ -0,0 +1,102 @@
(in-package :org-agent)
(defparameter *lisp-validator-whitelist*
'(;; Math & Logic
+ - * / = < > <= >= 1+ 1- min max
and or not null eq eql equal string= string-equal
;; List Manipulation
list cons car cdr cadr cddr cdar caar append mapcar remove-if remove-if-not
length reverse sort nth nthcdr push pop
;; Plists and Hash Tables
getf gethash
;; Control Flow
let let* if cond when unless case typecase
;; Strings
format concatenate string-downcase string-upcase search
;; Kernel specifics
org-agent::harness-log
org-agent::snapshot-object-store
org-agent::rollback-object-store
org-agent::lookup-object
org-agent::list-objects-by-type
org-agent::ingest-ast
org-agent::find-headline-missing-id
org-agent::context-query-store
org-agent::context-get-active-projects
org-agent::context-get-recent-completed-tasks
org-agent::context-list-all-skills
org-agent::context-get-system-logs
org-agent::context-assemble-global-awareness
org-agent::org-object-id
org-agent::org-object-type
org-agent::org-object-attributes
org-agent::org-object-content
org-agent::org-object-parent-id
org-agent::org-object-children
org-agent::org-object-version
org-agent::org-object-last-sync
org-agent::org-object-hash
;; Essential macros
declare ignore
;; Let's also add simple data types
t nil quote function))
(defvar *lisp-validator-registry* nil
"List of dynamically registered safe symbols.")
(defun lisp-validator-register (symbols)
"Adds symbols to the global validator registry."
(setf *lisp-validator-registry* (append *lisp-validator-registry* (if (listp symbols) symbols (list symbols))))
(harness-log "LISP VALIDATOR: Registered ~a new safe symbols." (length (if (listp symbols) symbols (list symbols)))))
(defun lisp-validator-is-safe (symbol)
"Checks if a symbol is in the static whitelist or the dynamic registry."
(or (member symbol *lisp-validator-whitelist* :test #'string-equal)
(member symbol *lisp-validator-registry* :test #'string-equal)))
(defun lisp-validator-ast-walk (form)
"Recursively walks the Lisp AST. Returns T if safe, NIL if unsafe."
(cond
;; Self-evaluating objects (strings, numbers, keywords) are safe.
((or (stringp form) (numberp form) (keywordp form) (characterp form))
t)
;; Symbols used as variables (in non-function position)
((symbolp form)
(lisp-validator-is-safe form))
;; Lists represent function calls or special forms.
((listp form)
(let ((head (car form)))
(cond
((eq head 'quote) t)
((not (symbolp head)) nil)
((lisp-validator-is-safe head)
(every #'lisp-validator-ast-walk (cdr form)))
(t
(harness-log "LISP VALIDATOR: Blocked call to non-whitelisted function ~a" head)
nil))))
(t nil)))
(org-agent:def-cognitive-tool :lisp-validator-status "Returns validator-related telemetry, including blocked actions and harness status."
nil
:body (lambda (args)
(declare (ignore args))
(format nil "LISP VALIDATOR STATUS:
- Static Whitelist: ~a symbols
- Dynamic Registry: ~a symbols
- Total Blocked Actions: ~a"
(length *lisp-validator-whitelist*)
(length *lisp-validator-registry*)
"Not implemented")))
(org-agent:defskill :skill-lisp-validator
:priority 900 ; High priority, before most skills
:trigger (lambda (ctx)
;; Check if any proposed action is an :eval or :shell call
(let ((candidate (getf ctx :candidate)))
(when candidate
(let ((payload (getf candidate :payload)))
(member (getf payload :action) '(:eval :shell))))))
:neuro nil ; Purely deterministic/safety skill
:symbolic (lambda (action context)
(harness-log "DETERMINISTIC ENGINE [Lisp-Validator]: Intercepted critical action for structural validation.")
action))

2
src/llm-gateway.lisp
View File

@@ -19,7 +19,7 @@
(let ((api-key (vault-get-secret provider :type :api-key))
(full-prompt (format nil "~a~%~%Prompt: ~a" system-prompt prompt)))
(harness-log "SYSTEM 1: Requesting ~a (Model: ~a) [Key: ~a]"
(harness-log "PROBABILISTIC ENGINE: Requesting ~a (Model: ~a) [Key: ~a]"
provider (or model "default") (vault-mask-string api-key))
(case provider

6
src/loop.lisp
View File

@@ -70,10 +70,10 @@
signal))
(defun neuro-gate (signal)
"Associative: Neural intuition and proposed actions."
"Probabilistic: Neural intuition and proposed actions."
(unless (eq (getf signal :type) :EVENT)
(return-from neuro-gate signal))
(harness-log "GATE [Associative]: Consulting LLM...")
(harness-log "GATE [Probabilistic]: Consulting LLM...")
(let ((thoughts (think signal)))
(setf (getf signal :proposals) (if (and (listp thoughts) (listp (car thoughts)))
thoughts
@@ -103,7 +103,7 @@
signal))
(defun decide-gate (signal)
"Deliberate: Deterministic safety and validation."
"Deterministic: Deterministic safety and validation."
(let ((candidate (getf signal :candidate)))
(if candidate
(let* ((normalized-candidate (if (listp candidate) candidate (list :type :RESPONSE :payload (list :text candidate))))

14
src/neuro.lisp
View File

@@ -10,7 +10,7 @@
(defvar *consensus-enabled-p* nil "If T, ask-neuro queries all backends in parallel.")
(defun ask-neuro (prompt &key (system-prompt "You are the Associative engine of a Neurosymbolic Lisp Machine.") (cascade nil) (context nil))
(defun ask-neuro (prompt &key (system-prompt "You are the Probabilistic engine of a Neurosymbolic Lisp Machine.") (cascade nil) (context nil))
"Dispatches a neural request through the provider cascade or parallel consensus."
(let ((backends (cond
((and cascade (listp cascade)) cascade)
@@ -26,7 +26,7 @@
(when backend-fn
(push (bt:make-thread
(lambda ()
(harness-log "ASSOCIATIVE [Consensus]: Querying backend ~a..." backend)
(harness-log "PROBABILISTIC [Consensus]: Querying backend ~a..." backend)
(let* ((model (when *model-selector-fn* (funcall *model-selector-fn* backend context)))
(result (ignore-errors
(if model
@@ -50,7 +50,7 @@
(or (dolist (backend backends)
(let ((backend-fn (gethash backend *neuro-backends*)))
(when backend-fn
(harness-log "ASSOCIATIVE: Attempting backend ~a..." backend)
(harness-log "PROBABILISTIC: Attempting backend ~a..." backend)
(let* ((model (when *model-selector-fn* (funcall *model-selector-fn* backend context)))
(result (if model
(funcall backend-fn prompt system-prompt :model model)
@@ -61,13 +61,13 @@
"(:type :LOG :payload (:text \"Neural Cascade Failure\"))"))))
(defun think (context)
"Invokes the neural Associative engine to propose a Lisp action based on context."
"Invokes the neural Probabilistic engine to propose a Lisp action based on context."
(let ((active-skill (find-triggered-skill context))
(tool-belt (generate-tool-belt-prompt))
(global-context (context-assemble-global-awareness)))
(if active-skill
(progn
(harness-log "ASSOCIATIVE: Engaging skill '~a'~%" (skill-name active-skill))
(harness-log "PROBABILISTIC: Engaging skill '~a'~%" (skill-name active-skill))
(let* ((prompt-generator (skill-neuro-prompt active-skill))
(raw-prompt (when prompt-generator (funcall prompt-generator context)))
(full-system-prompt (concatenate 'string
@@ -95,7 +95,7 @@ To call a tool, you MUST use:
(raw-thoughts (cl-ppcre:split (cl-ppcre:quote-meta-chars "|CONSENSUS-SEP|") thought))
(suggestions nil))
(dolist (raw-thought raw-thoughts)
(harness-log "ASSOCIATIVE RAW: ~a~%" raw-thought)
(harness-log "PROBABILISTIC RAW: ~a~%" raw-thought)
(let* ((cleaned-thought
(let ((match (cl-ppcre:scan-to-strings "(?s)```(?:lisp)?\\n?(.*?)\\n?```" raw-thought)))
(if match
@@ -109,7 +109,7 @@ To call a tool, you MUST use:
(list :sensor :syntax-error
:code cleaned-thought
:error (format nil "~a" c)))))))
(harness-log "ASSOCIATIVE Suggestion: ~a~%" cleaned-thought)
(harness-log "PROBABILISTIC Suggestion: ~a~%" cleaned-thought)
(when (and suggestion (listp suggestion))
(push suggestion suggestions))))
(if (and *consensus-enabled-p* suggestions)

4
src/package.lisp
View File

@@ -61,7 +61,7 @@
#:load-skill-with-timeout
#:topological-sort-skills
#:validate-lisp-syntax
#:safety-harness-validate
#:lisp-validator-validate
#:defskill
#:*skills-registry*
#:skill
@@ -88,7 +88,7 @@
#:register-emacs-client
#:unregister-emacs-client
;; --- Associative Engine ---
;; --- Probabilistic Engine ---
#:ask-neuro
#:register-neuro-backend
#:distill-prompt

15
src/policy-enforcer.lisp Normal file
View File

@@ -0,0 +1,15 @@
(in-package :org-agent)
(defskill :skill-policy-enforcer
:priority 1000 ; Absolute highest priority
:trigger (lambda (context) t) ; Always active as a fallback
:neuro (lambda (context)
"You are the Org-Agent Policy Enforcer. Your goal is to ensure all actions empower the user through the Lisp Machine and adhere to the System Policy.")
:symbolic (lambda (action context)
;; Basic invariant check: Block actions that appear to violate sovereignty
(let ((payload (getf action :payload)))
(if (and payload (search "proprietary" (format nil "~s" payload)))
(progn
(org-agent:harness-log "DETERMINISTIC [Policy]: Sovereignty violation suspected. Blocking action.")
nil)
action))))

42
src/safety-harness.lisp
View File

@@ -1,42 +0,0 @@
(in-package :org-agent)
(defparameter *safety-whitelist*
'(;; Math & Logic
+ - * / = < > <= >= 1+ 1- min max
and or not null eq eql equal string= string-equal
;; List Manipulation
list cons car cdr cadr cddr cdar caar append mapcar remove-if remove-if-not
length reverse sort nth nthcdr push pop
;; Plists and Hash Tables
getf gethash
;; Control Flow
let let* if cond when unless case typecase
;; Strings
format concatenate string-downcase string-upcase search
;; Kernel specifics
org-agent::harness-log
org-agent::snapshot-object-store
org-agent::rollback-object-store
org-agent::lookup-object
org-agent::list-objects-by-type
org-agent::ingest-ast
org-agent::find-headline-missing-id
org-agent::context-query-store
org-agent::context-get-active-projects
org-agent::context-get-recent-completed-tasks
org-agent::context-list-all-skills
org-agent::context-get-system-logs
org-agent::context-assemble-global-awareness
org-agent::org-object-id
org-agent::org-object-type
org-agent::org-object-attributes
org-agent::org-object-content
org-agent::org-object-parent-id
org-agent::org-object-children
org-agent::org-object-version
org-agent::org-object-last-sync
org-agent::org-object-hash
;; Essential macros
declare ignore
;; Let's also add simple data types
t nil quote function))

6
src/skills.lisp
View File

@@ -196,7 +196,7 @@
(return-from initialize-all-skills nil))
(let ((sorted-files (topological-sort-skills skills-dir)))
;; MANDATE: The System Invariants must be present for a safe boot
;; MANDATE: The System Policy must be present for a safe boot
(unless (member "org-skill-system-invariants" sorted-files :key #'pathname-name :test #'string-equal)
(error "BOOT FAILURE: org-skill-system-invariants.org not found in skills directory."))
@@ -244,9 +244,9 @@ EXAMPLES:
:guard (lambda (args context)
(declare (ignore context))
(let ((code (getf args :code)))
(let ((harness-pkg (find-package :org-agent.skills.org-skill-safety-harness)))
(let ((harness-pkg (find-package :org-agent.skills.org-skill-lisp-validator)))
(if harness-pkg
(uiop:symbol-call :org-agent.skills.org-skill-safety-harness :safety-harness-validate code)
(uiop:symbol-call :org-agent.skills.org-skill-lisp-validator :lisp-validator-validate code)
t))))
:body (lambda (args)
(let ((code (getf args :code)))

4
src/symbolic.lisp
View File

@@ -1,7 +1,7 @@
(in-package :org-agent)
(defun decide (proposed-action context)
"The Deliberate Safety Gate: iterates through all skill symbolic-gates sorted by priority."
"The Deterministic Safety Gate: iterates through all skill symbolic-gates sorted by priority."
(let ((current-action proposed-action)
(skills nil))
;; 1. Collect all skills with symbolic gates
@@ -21,7 +21,7 @@
;; If any gate returns a LOG or EVENT (blocking/intercepting), stop and return it.
(when (and (listp current-action)
(member (getf current-action :type) '(:LOG :EVENT :log :event)))
(harness-log "DELIBERATE: Intercepted by skill '~a'~%" (skill-name skill))
(harness-log "DETERMINISTIC: Intercepted by skill '~a'~%" (skill-name skill))
(return-from decide current-action))))
current-action))

50
src/system-invariants.lisp
View File

@@ -1,50 +0,0 @@
(in-package :org-agent)
(org-agent:def-cognitive-tool :harness-status "Returns the current operational status of the Org-Agent harness, including loaded skills and telemetry."
nil
:body (lambda (args)
(declare (ignore args))
(format nil "HARNESS STATUS:
- Active Skills: ~a
- Uptime: ~a seconds
- Memory Usage: ~a
- Providers: ~a"
(hash-table-count org-agent:*skills-registry*)
(get-universal-time) ; Placeholder for actual uptime
"Not implemented"
org-agent:*provider-cascade*)))
(org-agent:def-cognitive-tool :list-skills "Lists all currently loaded skills and their metadata."
nil
:body (lambda (args)
(declare (ignore args))
(let ((output "LOADED SKILLS:
"))
(maphash (lambda (name skill)
(setf output (concatenate 'string output
(format nil "- ~a (Priority: ~a, Deps: ~s)~%"
name
(org-agent:skill-priority skill)
(org-agent:skill-dependencies skill)))))
org-agent:*skills-registry*)
output)))
(org-agent:defskill :skill-system-invariants
:priority 1000 ; Absolute highest priority
:trigger (lambda (context) t) ; Always active as a fallback
:neuro (lambda (context)
"You are the Org-Agent System Invariants Skill. Your goal is to empower the user through the Lisp Machine.
Follow the Core Invariants:
1. Sovereignty: Avoid proprietary traps.
2. Technical Mastery: Explain your logic.
3. Zero-Bloat: Keep it minimal.
4. Transparency: Your thoughts are auditable.
5. Sustainability: Think long-term.")
:symbolic (lambda (action context)
;; Basic invariant check: Block actions that appear to violate sovereignty
(let ((payload (getf action :payload)))
(if (and payload (search "proprietary" (format nil "~s" payload)))
(progn
(org-agent:harness-log "DELIBERATE [Invariants]: Sovereignty violation suspected. Blocking action.")
nil)
action))))

2
tests/bouncer-tests.lisp
View File

@@ -3,7 +3,7 @@
(:export #:bouncer-suite))
(in-package :org-agent-bouncer-tests)
(def-suite bouncer-suite :description "Tests for System 2 Bouncer & Authorization Gate.")
(def-suite bouncer-suite :description "Tests for Deterministic Engine Bouncer & Authorization Gate.")
(in-suite bouncer-suite)
(test test-bouncer-interception

22
tests/lisp-validator-tests.lisp Normal file
View File

@@ -0,0 +1,22 @@
(defpackage :org-agent-lisp-validator-tests
(:use :cl :fiveam :org-agent)
(:export #:lisp-validator-suite))
(in-package :org-agent-lisp-validator-tests)
(def-suite lisp-validator-suite :description "Tests for the Lisp Validator.")
(in-suite lisp-validator-suite)
(test test-basic-math-safe
(is (org-agent:lisp-validator-validate "(+ 1 2)")))
(test test-blocked-eval
(is (not (org-agent:lisp-validator-validate "(eval '(+ 1 2))"))))
(test test-blocked-shell
(is (not (org-agent:lisp-validator-validate "(uiop:run-program \"ls\")"))))
(test test-nested-unsafe
(is (not (org-agent:lisp-validator-validate "(let ((x 1)) (delete-file \"test.txt\"))"))))
(test test-safe-kernel-api
(is (org-agent:lisp-validator-validate "(org-agent::lookup-object \"node-1\")")))

18
tests/pipeline-tests.lisp
View File

@@ -9,7 +9,6 @@
(defun setup-mock-skills ()
"Register mock skills for testing."
(clrhash org-agent::*skills-registry*)
(org-agent::defskill :mock-refactor
:priority 100
:trigger (lambda (ctx) (eq (getf (getf ctx :payload) :command) :organize-subtree))
@@ -19,7 +18,6 @@
:payload (:action :refactor-subtree
:target-id nil
:properties (("ID" . "node-123"))))))
(org-agent::defskill :mock-safety
:priority 50
:trigger (lambda (ctx) t) ; always triggers
@@ -86,9 +84,9 @@
(test test-log-buffering
"Verify that harness-log correctly populates the system logs."
(harness-log "PSF TEST LOG")
(harness-log "Engineering TEST LOG")
(let ((logs (context-get-system-logs 5)))
(is (cl:some (lambda (line) (search "PSF TEST LOG" line)) logs))))
(is (cl:some (lambda (line) (search "Engineering TEST LOG" line)) logs))))
(test test-global-awareness-assembly
"Verify that context-assemble-global-awareness reports active projects."
@@ -103,25 +101,15 @@
(clrhash org-agent::*object-store*)
(clrhash org-agent::*history-store*)
(setf org-agent::*object-store-snapshots* nil)
;; State A
(ingest-ast (list :type :HEADLINE :properties (list :ID "node-1" :TITLE "State A") :contents nil))
(setup-mock-skills)
;; Skill that crashes in Symbolic Gate
(org-agent::defskill :crashing-skill
:priority 200
:trigger (lambda (ctx) t)
:neuro (lambda (ctx) (list :type :REQUEST :payload (list :action :eval :code "(error \"BOOM\")")))
:symbolic (lambda (action ctx) (error "CRASH IN SYSTEM 2")))
;; Run pipeline. This turn will:
;; 1. Perceive (Take snapshot of State A)
;; 2. Neuro (Think)
;; 3. Decide (Crash!)
;; 4. Rollback to State A.
:symbolic (lambda (action ctx) (error "CRASH IN DETERMINISTIC ENGINE")))
(process-signal (list :type :EVENT :payload (list :sensor :test)))
;; Verify that we are still in State A
(let ((obj (lookup-object "node-1")))
(is (not (null obj)))

22
tests/safety-harness-tests.lisp
View File

@@ -1,22 +0,0 @@
(defpackage :org-agent-safety-tests
(:use :cl :fiveam :org-agent)
(:export #:safety-suite))
(in-package :org-agent-safety-tests)
(def-suite safety-suite :description "Tests for the Global Safety Harness.")
(in-suite safety-suite)
(test test-basic-math-safe
(is (org-agent:safety-harness-validate "(+ 1 2)")))
(test test-blocked-eval
(is (not (org-agent:safety-harness-validate "(eval '(+ 1 2))"))))
(test test-blocked-shell
(is (not (org-agent:safety-harness-validate "(uiop:run-program \"ls\")"))))
(test test-nested-unsafe
(is (not (org-agent:safety-harness-validate "(let ((x 1)) (delete-file \"test.txt\"))"))))
(test test-safe-kernel-api
(is (org-agent:safety-harness-validate "(org-agent::lookup-object \"node-1\")")))

2
tests/self-fix-tests.lisp
View File

@@ -23,7 +23,7 @@
:neuro nil
:symbolic (lambda (action context)
(declare (ignore action context))
(+ 1 \"two\"))) ; DELIBERATE BUG
(+ 1 \"two\"))) ; DETERMINISTIC BUG
#+end_src
")))