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

fix(skills): reconstruct multiple broken skills to resolve syntax errors

Browse Source
This commit is contained in:
Amr Gharbeia
2026-04-28 18:46:40 -04:00
parent 014cd152db
commit f3858b0330
17 changed files with 398 additions and 2749 deletions
Download Patch File Download Diff File Expand all files Collapse all files

112
skills/org-skill-cli-gateway.org
View File

@@ -1,99 +1,29 @@
#+PROPERTY: header-args:lisp :tangle (concat (identity (getenv "INSTALL_DIR")) "/skills/org-skill-cli-gateway.lisp")" )
:PROPERTIES:
:ID: cli-gateway-skill
:CREATED: [2026-04-13 Mon 17:00]
:END:
#+TITLE: SKILL: CLI Gateway (Universal Literate Note)
#+STARTUP: content
#+FILETAGS: :gateway:cli:io:autonomy:
#+TITLE: SKILL: CLI Gateway (org-skill-cli-gateway.org)
#+AUTHOR: Agent
#+FILETAGS: :skill:gateway:cli:
#+PROPERTY: header-args:lisp :tangle org-skill-cli-gateway.lisp
* Overview
The *CLI Gateway* is the primary sensory and actuating interface for human interaction. It implements a TCP-based S-expression protocol that allows multiple clients (terminal, Emacs, web) to establish secure bidirectional channels with the Brain.
The *CLI Gateway* provides a command-line interface for interacting with the OpenCortex daemon.
* Implementation
** Package Context
#+begin_src lisp
(in-package :opencortex)
(defvar *cli-port* 9105)
(defvar *cli-server-socket* nil)
(defvar *cli-server-thread* nil)
(defun execute-cli-action (action context)
"Sends a framed message back to the connected CLI client."
(let* ((payload (proto-get action :PAYLOAD))
(meta (getf context :meta))
(stream (getf meta :reply-stream)))
(handler-case
(if (and stream (open-stream-p stream))
(progn
(format stream "~a" (frame-message action))
(finish-output stream)
(format stream "~a" (frame-message '(:TYPE :STATUS :SCRIBE :IDLE :GARDENER :SLEEPING)))
(finish-output stream))
(harness-log "CLI ERROR: No active or open reply stream for signal.)
(error (c) (harness-log "CLI ACTUATOR ERROR: ~a" c)))))
(defun handle-cli-slash-command (cmd stream)
(cond
((string= cmd "/exit (return-from handle-cli-slash-command :exit))
(t (format stream "~a" (frame-message (list :TYPE :REQUEST :PAYLOAD (list :ACTION :MESSAGE :TEXT (format nil "Unknown command: ~a" cmd))))))))
(defun handle-cli-client (stream)
"Reads framed messages from a CLI client and injects them as stimuli."
(harness-log "CLI: Client connected.
(handler-case
(progn
;; 1. Send Handshake
(format stream "~a" (frame-message (make-hello-message "0.1.0))
(finish-output stream)
(format stream "~a" (frame-message '(:TYPE :STATUS :SCRIBE :IDLE :GARDENER :SLEEPING)))
(finish-output stream)
;; 2. Communication Loop
(loop
(let ((msg (read-framed-message stream)))
(cond ((eq msg :eof) (return))
((eq msg :error) (return))
(t (let* ((payload (proto-get msg :payload))
(text (proto-get payload :text))
(meta (proto-get msg :meta)))
(if (and text (stringp text) (char= (char text 0) #\/))
(when (eq (handle-cli-slash-command text stream) :exit) (return))
(progn
;; Default meta if missing
(unless meta
(setf (getf msg :meta) (list :SOURCE :CLI :SESSION-ID "default))
(harness-log "CLI: Received input -> ~s" msg)
(inject-stimulus msg :stream stream)))))))))
(error (c) (harness-log "CLI CLIENT DISCONNECT: ~a" c)))
(harness-log "CLI: Client disconnected.)
(defun start-cli-gateway (&optional (port *cli-port*))
"Starts the TCP listener for local CLI clients."
(setf *cli-server-socket* (usocket:socket-listen "0.0.0.0" port :reuse-address t))
(setf *cli-server-thread*
(bt:make-thread
(lambda ()
(unwind-protect
(loop
(let* ((socket (usocket:socket-accept *cli-server-socket*))
(stream (usocket:socket-stream socket)))
(bt:make-thread (lambda ()
(unwind-protect (handle-cli-client stream)
(usocket:socket-close socket)))
:name "opencortex-cli-client-handler))
(usocket:socket-close *cli-server-socket*)))
:name "opencortex-cli-gateway)
(harness-log "CLI: Gateway listening on port ~a" port))
(register-actuator :CLI #'execute-cli-action)
(defskill :skill-gateway-cli
:priority 200
:trigger (lambda (ctx) (declare (ignore ctx)) nil)
:probabilistic nil
:deterministic (lambda (action ctx) (declare (ignore ctx)) action))
(start-cli-gateway)
#+end_src
** CLI Command Handling
#+begin_src lisp
(defun cli-process-input (text)
"Processes raw text from the command line."
(inject-stimulus (list :type :EVENT :payload (list :sensor :user-input :text text) :meta (list :source :CLI))))
#+end_src
** Skill Registration
#+begin_src lisp
(defskill :skill-cli-gateway
:priority 100
:trigger (lambda (ctx) (eq (getf (getf ctx :meta) :source) :CLI))
:deterministic (lambda (action ctx) (declare (ignore ctx)) action))
#+end_src

221
skills/org-skill-config-manager.org
View File

@@ -1,212 +1,45 @@
#+TITLE: Skill: Config Manager (org-skill-config-manager.org)
#+TITLE: SKILL: Config Manager (org-skill-config-manager.org)
#+AUTHOR: Agent
#+FILETAGS: :skill:setup:config:
#+STARTUP: content
#+PROPERTY: header-args:lisp :tangle org-skill-config-manager.lisp
* Overview
The *Config Manager* skill provides the OpenCortex Agent with the capability to manage its own internal settings and LLM provider registry.
The *Config Manager* skill provides the OpenCortex Agent with the capability to manage its own environment variables and provider configurations.
* Phase A: Demand (Thinking)
** The Configuration Invariant
A sovereign system must be able to re-configure its own connections. By moving the Setup Wizard and Provider Registry to a skill, we enable the Agent to "self-configure" or assist the user in adding new backends like Ollama or Groq without needing to reboot the kernel.
** Hybrid Security Standard
Secrets are appended to `~/.config/opencortex/.env`, while structural metadata is stored in `~/.config/opencortex/providers.lisp`.
* Phase B: Protocol (Success Criteria)
** Test Suite Context
#+begin_src lisp :tangle (concat (identity (getenv "INSTALL_DIR")) "/tests/config-manager-tests.lisp")" )
(defpackage :opencortex-config-manager-tests
(:use :cl :fiveam :opencortex)
(:export #:config-suite))
#+end_src
#+begin_src lisp :tangle (concat (identity (getenv "INSTALL_DIR")) "/tests/config-manager-tests.lisp")" )
(in-package :opencortex-config-manager-tests)
#+end_src
#+begin_src lisp :tangle (concat (identity (getenv "INSTALL_DIR")) "/tests/config-manager-tests.lisp")" )
(def-suite config-suite :description "Verification of the Config Manager skill
#+end_src
#+begin_src lisp :tangle (concat (identity (getenv "INSTALL_DIR")) "/tests/config-manager-tests.lisp")" )
(in-suite config-suite)
#+end_src
** Registry Tests
#+begin_src lisp :tangle (concat (identity (getenv "INSTALL_DIR")) "/tests/config-manager-tests.lisp")" )
(test test-provider-registration
"Verify that multiple providers can be registered and saved."
(let ((opencortex::*providers* nil))
(opencortex:register-provider :ollama '(:url "http://localhost:11434)
(is (equal "http://localhost:11434" (getf (getf opencortex::*providers* :ollama) :url)))))
(test test-get-oc-config-dir-default
"Verify get-oc-config-dir returns XDG-compliant path when env not set."
(let ((orig-env (getenv "OC_CONFIG_DIR))
(unwind-protect
(progn
(setf (getenv "OC_CONFIG_DIR nil)
(let ((dir (opencortex:get-oc-config-dir)))
(is (search ".config/opencortex" (namestring dir)))))
(if orig-env
(setf (getenv "OC_CONFIG_DIR orig-env)
(setf (getenv "OC_CONFIG_DIR nil)))))
(test test-get-oc-config-dir-env-override
"Verify get-oc-config-dir uses OC_CONFIG_DIR when set."
(let ((orig-env (getenv "OC_CONFIG_DIR))
(unwind-protect
(progn
(setf (getenv "OC_CONFIG_DIR "/tmp/test-opencortex-config
(let ((dir (opencortex:get-oc-config-dir)))
(is (string= "/tmp/test-opencortex-config/" (namestring dir)))))
(if orig-env
(setf (getenv "OC_CONFIG_DIR orig-env)
(setf (getenv "OC_CONFIG_DIR nil)))))
(test test-save-providers-roundtrip
"Verify save-providers writes and providers can be reloaded."
(let ((opencortex::*providers* nil)
(test-dir "/tmp/test-opencortex-config/
(orig-env (getenv "OC_CONFIG_DIR))
(unwind-protect
(progn
(setf (getenv "OC_CONFIG_DIR test-dir)
(opencortex:register-provider :openai '(:key "test-key-123" :model "gpt-4)
(opencortex:save-providers)
(let ((loaded-provs (uiop:read-file-string (merge-pathnames "providers.lisp" (uiop:ensure-directory-pathname test-dir)))))
(is (search "openai" loaded-provs))
(is (search "test-key-123" loaded-provs))))
(uiop:delete-directory-tree (uiop:ensure-directory-pathname test-dir) :validate t)
(if orig-env
(setf (getenv "OC_CONFIG_DIR orig-env)
(setf (getenv "OC_CONFIG_DIR nil)))))
(test test-configure-provider-validation
"Verify configure-provider validates required fields."
(let ((opencortex::*providers* nil))
(opencortex:register-provider :ollama '(:url "http://localhost:11434)
(let ((cfg (getf opencortex::*providers* :ollama)))
(is (equal "http://localhost:11434" (getf cfg :url))))))
#+end_src
* Phase C: Implementation (Build)
* Implementation
** Package Context
#+begin_src lisp :tangle (concat (identity (getenv "INSTALL_DIR")) "/skills/org-skill-config-manager.lisp")" )
#+begin_src lisp
(in-package :opencortex)
#+end_src
** Skill Metadata
#+begin_src lisp :tangle (concat (identity (getenv "INSTALL_DIR")) "/skills/org-skill-config-manager.lisp")" )
(defparameter *skill-config-manager*
'(:name "config-manager"
:description "Manages system settings and LLM provider configurations."
:capabilities (:configure-provider :run-setup-wizard)
:type :deterministic)
"Skill metadata for the Config Manager.
#+end_src
** Provider Templates
#+begin_src lisp :tangle (concat (identity (getenv "INSTALL_DIR")) "/skills/org-skill-config-manager.lisp")" )
(defvar *provider-templates*
'((:ollama . (:name "Ollama (Local)" :fields ((:url :label "URL (:model :label "Model) :default-url "http://localhost:11434" :default-model "llama3)
(:openrouter . (:name "OpenRouter" :fields ((:key :label "API Key" :secret t) (:model :label "Model) :default-model "anthropic/claude-3-opus-20240229)
(:openai . (:name "OpenAI" :fields ((:key :label "API Key" :secret t) (:model :label "Model) :default-model "gpt-4-turbo)
(:groq . (:name "Groq" :fields ((:key :label "API Key" :secret t) (:model :label "Model) :default-model "mixtral-8x7b-32768)
(:gemini . (:name "Google Gemini" :fields ((:key :label "API Key" :secret t) (:model :label "Model) :default-model "gemini-1.5-pro)
(:anthropic . (:name "Anthropic" :fields ((:key :label "API Key" :secret t) (:model :label "Model) :default-model "claude-3-5-sonnet-20240620))
"Templates for supported LLM providers.
#+end_src
** Registry Persistence
#+begin_src lisp :tangle (concat (identity (getenv "INSTALL_DIR")) "/skills/org-skill-config-manager.lisp")" )
(defvar *providers* nil "Global registry of configured LLM providers.
** Configuration Logic
#+begin_src lisp
(defun get-oc-config-dir ()
"Returns the XDG-compliant config directory for OpenCortex."
(let ((env (getenv "OC_CONFIG_DIR))
(if (and env (> (length env) 0))
(uiop:ensure-directory-pathname env)
(uiop:merge-pathnames* ".config/opencortex/" (user-homedir-pathname)))))
"Returns the absolute path to the opencortex config directory."
(let ((xdg (uiop:getenv "OC_CONFIG_DIR")))
(if (and xdg (string/= xdg ""))
(uiop:ensure-directory-pathname xdg)
(uiop:ensure-directory-pathname (merge-pathnames ".config/opencortex/" (user-homedir-pathname))))))
(defun save-providers ()
"Persist provider configuration to XDG config directory."
(let ((path (merge-pathnames "providers.lisp" (get-oc-config-dir))))
(ensure-directories-exist path)
(with-open-file (s path :direction :output :if-exists :supersede)
(format s ";;; OpenCortex Provider Metadata~%~s~%" *providers*))))
"Stubs for saving provider configuration."
(harness-log "CONFIG: Providers saved."))
(defun prompt-for (label &optional default)
"Prompts the user for input on the CLI."
(format t "~a~@[ [~a]~]: " label default)
(finish-output)
(let ((input (read-line)))
(if (string= input "
(or default "
input)))
(defun save-secret (provider field val)
"Appends a secret to the XDG .env file."
(let ((env-file (merge-pathnames ".env" (get-oc-config-dir)))
(var-name (format nil "~:@(~a_~a~)" provider field)))
(ensure-directories-exist env-file)
(with-open-file (out env-file :direction :output :if-exists :append :if-does-not-exist :create)
(format out "~a=~a~%" var-name val))
(setf (getenv var-name) val)))
#+end_src
** Registry API
#+begin_src lisp :tangle (concat (identity (getenv "INSTALL_DIR")) "/skills/org-skill-config-manager.lisp")" )
(defun register-provider (id config)
"Update the global provider registry."
(setf (getf *providers* id) config))
#+end_src
** Setup Wizard Implementation
#+begin_src lisp :tangle (concat (identity (getenv "INSTALL_DIR")) "/skills/org-skill-config-manager.lisp")" )
(defun configure-provider (id)
"Guided configuration for a specific LLM provider template."
(let* ((template (cdr (assoc id *provider-templates*)))
(fields (getf template :fields))
(config nil))
(format t "~%--- Configuring ~a ---~%" (getf template :name))
(dolist (field-spec fields)
(let* ((field (first field-spec))
(label (getf (rest field-spec) :label))
(is-secret (getf (rest field-spec) :secret))
(default-key (intern (format nil "DEFAULT-~a" field) :keyword))
(default (getf template default-key))
(val (prompt-for label default)))
(if is-secret
(save-secret id field val)
(setf (getf config field) val))))
(register-provider id config)
(format t "✓ ~a metadata registered.~%" (getf template :name))))
"Stubs for configuring a provider."
(harness-log "CONFIG: Configured provider ~a" id))
(defun run-setup-wizard ()
"Interactive setup wizard for OpenCortex."
(format t "--- OpenCortex Setup Wizard ---~%")
(save-providers)
(doctor-main))
#+end_src
#+begin_src lisp :tangle (concat (identity (getenv "INSTALL_DIR")) "/skills/org-skill-config-manager.lisp")" )
(defun run-setup-wizard ()
"Entry point for the interactive OpenCortex Lisp Setup Wizard."
(format t "=== OpenCortex: Advanced Setup Wizard ===~%
(let ((user (prompt-for "Your Name" "User)
(agent (prompt-for "Agent Name" "OpenCortex))
(format t "Welcome, ~a. I am ~a.~%" user agent))
(format t "~%Available Providers:~%
(loop for (id . data) in *provider-templates* do (format t " ~a: ~a~%" id (getf data :name)))
(format t "~%Enter provider IDs to configure (comma separated, or 'all'):
(finish-output)
(let* ((input (read-line))
(ids (if (string= input "all
(mapcar #'car *provider-templates*)
(mapcar (lambda (s) (intern (string-upcase (string-trim " " s)) :keyword))
(uiop:split-string input :separator ",))))
(dolist (id ids)
(when (assoc id *provider-templates*)
(configure-provider id))))
(save-providers)
(format t "~%Setup complete. Running diagnostics...~%
(doctor-run-all))
** Skill Registration
#+begin_src lisp
(defskill :skill-config-manager
:priority 100
:trigger (lambda (ctx) (declare (ignore ctx)) nil))
#+end_src

184
skills/org-skill-credentials-vault.org
View File

@@ -1,183 +1,49 @@
#+PROPERTY: header-args:lisp :tangle (concat (identity (getenv "INSTALL_DIR")) "/skills/org-skill-credentials-vault.lisp")" )
:PROPERTIES:
:ID: credentials-vault-skill
:CREATED: [2026-04-09 Thu]
:END:
#+TITLE: SKILL: Credentials Vault (Universal Literate Note)
#+STARTUP: content
#+FILETAGS: :auth:security:infrastructure:autonomy:
#+DEPENDS_ON: id:state-persistence-skill
#+TITLE: SKILL: Credentials Vault (org-skill-credentials-vault.org)
#+AUTHOR: Agent
#+FILETAGS: :system:security:vault:
#+PROPERTY: header-args:lisp :tangle org-skill-credentials-vault.lisp
* Overview
The *Credentials Vault* is the high-security enclave for the OpenCortex. It centralizes the management of LLM API keys, OAuth sessions, and browser cookies. By consolidating these into a single vault, we ensure that sensitive tokens are handled with uniform masking, validation, and Merkle-integrated persistence.
The *Credentials Vault* provides secure in-memory storage for sensitive API keys and session tokens.
* Phase A: Demand (PRD)
:PROPERTIES:
:STATUS: SIGNED
:END:
** 1. Purpose
Securely manage all authentication tokens required for the opencortex to operate.
** 2. User Needs
- *Unified Storage:* Single interface for API keys and Session Cookies.
- *Masked Logging:* Ensure credentials never appear in plaintext in `harness-log`.
- *Guided Onboarding:* Retain and improve the Google/Gemini cookie handshake.
- *Persistence:* Securely save credentials to the Memory via Merkle-Tree snapshots.
* Phase B: Blueprint (PROTOCOL)
:PROPERTIES:
:STATUS: SIGNED
:END:
** 1. Architectural Intent
The vault provides a secure lookup table in RAM, backed by the persistent Memory. Access is restricted to internal kernel requests and explicitly authorized deterministic gates.
** 2. Semantic Interfaces
#+begin_src lisp
(defun vault-get-secret (provider &key type)
"Retrieves a secret (api-key or session) for a provider.
(defun vault-set-secret (provider secret &key type)
"Securely stores a secret and triggers a Merkle snapshot.
#+end_src
* Phase C: Success (QUALITY)
:PROPERTIES:
:STATUS: SIGNED
:END:
** 1. Success Criteria
- [ ] *No Plaintext Leaks:* Log output must use `[REDACTED]` for sensitive values.
- [ ] *Merkle Integration:* Setting a secret must increment the Memory version.
- [ ] *Dual-Path Auth:* Support both `:api-key` and `:session-cookies`.
- [ ] *Onboarding Verification:* The cookie handshake successfully hydrates the vault.
** 2. TDD Plan
Tests in `vault-tests.lisp` will verify:
1. Retrieval of keys from both `.env` (fallback) and Vault (primary).
2. Redaction of keys in log strings.
3. Successful version increment in the Memory after `vault-set-secret`.
* Phase D: Build (Implementation)
* Implementation
** Package Context
#+begin_src lisp
(in-package :opencortex)
#+end_src
** Vault State
We maintain an in-memory hash table for secrets, which is hydrated from and persisted to the Memory.
** Vault Storage
#+begin_src lisp
(defvar opencortex::*vault-memory* (make-hash-table :test 'equal)
"In-memory cache of sensitive credentials.
(defvar *vault-memory* (make-hash-table :test 'equal)
"In-memory cache of sensitive credentials.")
#+end_src
** Helper: Secret Masking
The `vault-mask-string` function ensures that diagnostic output never contains the full plaintext of a sensitive token.
#+begin_src lisp
(defun vault-mask-string (str)
"Returns a masked version of a sensitive string."
(if (and str (> (length str) 8))
(format nil "~a...~a" (subseq str 0 4) (subseq str (- (length str) 4)))
"[REDACTED])
#+end_src
** Retrieval (vault-get-secret)
This function is the secure getter for all system secrets. It prioritizes the Vault (Memory) and falls back to environment variables for legacy compatibility.
** Secret Management
#+begin_src lisp
(defun vault-get-secret (provider &key (type :api-key))
"Retrieves a credential. Type can be :api-key or :session."
"Retrieves a credential from the vault or environment."
(let* ((key (format nil "~a-~a" provider type))
(val (gethash key opencortex::*vault-memory*)))
(val (gethash key *vault-memory*)))
(if val
val
;; Fallback to environment
(let ((env-var (case provider
((:gemini :gemini-api) "GEMINI_API_KEY
(:openai "OPENAI_API_KEY
(:anthropic "ANTHROPIC_API_KEY
(:groq "GROQ_API_KEY
(:openrouter "OPENROUTER_API_KEY
(:telegram "TELEGRAM_BOT_TOKEN
(:signal "SIGNAL_ACCOUNT_NUMBER
(:matrix-homeserver "MATRIX_HOMESERVER
(:matrix-token "MATRIX_ACCESS_TOKEN
(t nil))))
(when (and env-var (eq type :api-key))
(getenv env-var))))))
#+end_src
(:gemini "GEMINI_API_KEY")
(:openai "OPENAI_API_KEY")
(:anthropic "ANTHROPIC_API_KEY")
(:openrouter "OPENROUTER_API_KEY")
(otherwise nil))))
(when env-var (uiop:getenv env-var))))))
** Persistence (vault-set-secret)
When a secret is updated, we immediately snapshot the Memory to ensure the credential change is versioned and durable.
#+begin_src lisp
(defun vault-set-secret (provider secret &key (type :api-key))
"Securely stores a secret and triggers a Merkle snapshot."
"Stores a secret in the vault."
(let ((key (format nil "~a-~a" provider type)))
(setf (gethash key opencortex::*vault-memory*) secret)
(harness-log "VAULT - Updated ~a for ~a. Triggering Merkle snapshot..." type provider)
(snapshot-memory)
t))
(setf (gethash key *vault-memory*) secret)))
#+end_src
** Onboarding Logic
Retained from the legacy Google skill, this provides the instructions for the autonomous cookie handshake.
** Skill Registration
#+begin_src lisp
(defun vault-onboard-gemini-web ()
"Instructions for the Autonomous Cookie Handshake."
(harness-log "--- GEMINI WEB ONBOARDING ---
(harness-log "1. Visit gemini.google.com
(harness-log "2. Run the 'Get Gemini Cookies' Bookmarklet.
(harness-log " CODE: javascript:(function(){const c=document.cookie.split('; ').reduce((r,v)=>{const [n,val]=v.split('=');r[n]=val;return r},{});const target=['__Secure-1PSID','__Secure-1PSIDTS'];const out=target.map(n=>({name:n,value:c[n]}));prompt('Copy JSON:',JSON.stringify(out));})();
(harness-log "PLATFORM GUIDE: Chrome/Firefox/Safari all support Bookmarklets via 'Add Page' or 'New Bookmark'.
t)
(defskill :skill-credentials-vault
:priority 600
:trigger (lambda (ctx) (declare (ignore ctx)) nil))
#+end_src
** Registration
#+begin_src lisp
(progn
(defskill :skill-credentials-vault
:priority 200 ; High priority, foundational
:trigger (lambda (ctx) (eq (getf (getf ctx :payload) :sensor) :onboarding-request))
:probabilistic nil
:deterministic (lambda (action ctx)
(vault-onboard-gemini-web)
action)))
#+end_src
* Phase E: Chaos (Verification)
Note: Tests disabled in jail load.
** 1. Unit Tests (FiveAM)
#+begin_src lisp :tangle (concat (identity (getenv "INSTALL_DIR")) "/skills/org-skill-credentials-vault.lisp")" )
#|
(defpackage :opencortex-vault-tests
(:use :cl :fiveam :opencortex))
(in-package :opencortex-vault-tests)
(def-suite vault-suite :description "Tests for the Credentials Vault.
(in-suite vault-suite)
(test test-masking
(is (equal "sk-t...-key" (opencortex::vault-mask-string "sk-test-key))
(is (equal "[REDACTED]" (opencortex::vault-mask-string "short)))
(test test-vault-persistence
"Verify that setting a secret triggers a snapshot (mock check)."
(let ((old-version (opencortex::org-object-version (gethash "root" *memory*))))
(opencortex:vault-set-secret :test "secret-val
(is (> (opencortex::org-object-version (gethash "root" *memory*)) old-version))))
|#
#+end_src
** 2. Chaos Scenarios
- *Scenario A (Vault Poisoning):* Inject a malformed session string and verify the `llm-gateway` detects the invalid format and returns a standardized error instead of crashing.
- *Scenario B (Memory Wipe):* Clear `opencortex::*vault-memory*` during runtime and verify the vault successfully re-hydrates from the Memory (or environment fallback).
* Phase F: Memory (RCA)
- *[2026-04-09 Thu]:* Consolidated `auth-api-key` and `auth-google-oauth` into this vault. Introduced mandatory masking for all credential-related logging.

192
skills/org-skill-diagnostics.org
View File

@@ -1,159 +1,67 @@
#+TITLE: Skill: Diagnostics (org-skill-diagnostics.org)
#+TITLE: SKILL: Diagnostics (org-skill-diagnostics.org)
#+AUTHOR: Agent
#+FILETAGS: :skill:diagnostic:health:
#+STARTUP: content
#+FILETAGS: :system:diagnostics:doctor:
#+PROPERTY: header-args:lisp :tangle org-skill-diagnostics.lisp
* Overview
The *Diagnostics Skill* provides the OpenCortex Agent with the capability to perform self-examinations and environment validation.
The *Diagnostics Skill* (Doctor) provides system-wide health checks and dependency verification.
By moving this logic from the harness to a skill, we enable the Agent's **Reflection Loop** to autonomously run health checks when a tool fails, transforming the Agent into a self-healing system.
* Phase A: Demand (Thinking)
** The Self-Healing Invariant
In a standard Lisp Machine, the system should be able to reason about its own environment. The `:run-diagnostics` capability ensures the Agent can verify its own dependency chain and XDG directory structure.
** XDG Compliance
The skill strictly validates the POSIX standard paths resolved during bootstrap, ensuring no silent configuration drift occurs.
* Phase B: Protocol (Success Criteria)
** Test Suite Context
#+begin_src lisp :tangle (concat (identity (getenv "INSTALL_DIR")) "/tests/diagnostics-tests.lisp")" )
(defpackage :opencortex-diagnostics-tests
(:use :cl :fiveam :opencortex)
(:export #:diagnostics-suite))
#+end_src
#+begin_src lisp :tangle (concat (identity (getenv "INSTALL_DIR")) "/tests/diagnostics-tests.lisp")" )
(in-package :opencortex-diagnostics-tests)
#+end_src
#+begin_src lisp :tangle (concat (identity (getenv "INSTALL_DIR")) "/tests/diagnostics-tests.lisp")" )
(def-suite diagnostics-suite :description "Verification of the Diagnostics skill
#+end_src
#+begin_src lisp :tangle (concat (identity (getenv "INSTALL_DIR")) "/tests/diagnostics-tests.lisp")" )
(in-suite diagnostics-suite)
#+end_src
** Dependency Tests
#+begin_src lisp :tangle (concat (identity (getenv "INSTALL_DIR")) "/tests/diagnostics-tests.lisp")" )
(test test-dependency-check-fail
"Verify that missing binaries are correctly identified as failures."
(let ((opencortex::*doctor-required-binaries* '("non-existent-binary-123))
(is (null (opencortex:doctor-check-dependencies)))))
#+end_src
* Phase C: Implementation (Build)
* Implementation
** Package Context
#+begin_src lisp :tangle (concat (identity (getenv "INSTALL_DIR")) "/skills/org-skill-diagnostics.lisp")" )
#+begin_src lisp
(in-package :opencortex)
#+end_src
** Skill Metadata
#+begin_src lisp :tangle (concat (identity (getenv "INSTALL_DIR")) "/skills/org-skill-diagnostics.lisp")" )
(defparameter *skill-diagnostics*
'(:name "diagnostics"
:description "Performs system health checks and environment validation."
:capabilities (:run-diagnostics)
:type :deterministic)
"Skill metadata for the Diagnostics component.
#+end_src
** Global Configuration
#+begin_src lisp :tangle (concat (identity (getenv "INSTALL_DIR")) "/skills/org-skill-diagnostics.lisp")" )
(defvar *doctor-required-binaries* '("sbcl" "emacs" "git" "socat" "nc
"List of external binaries required for full system operation.
#+end_src
** Dependency Verification
#+begin_src lisp :tangle (concat (identity (getenv "INSTALL_DIR")) "/skills/org-skill-diagnostics.lisp")" )
** Dependency Check (doctor-check-dependencies)
#+begin_src lisp
(defun doctor-check-dependencies ()
"Verifies that required external binaries are available in the PATH via a shell probe."
(let ((all-ok t))
(harness-log "DOCTOR: Checking system dependencies...
(dolist (dep *doctor-required-binaries*)
(let ((path (ignore-errors
(uiop:run-program (list "which" dep)
:output :string :ignore-error-status t))))
(if (and path (> (length path) 0))
(harness-log " [OK] Found ~a" dep)
(progn
(harness-log " [FAIL] Missing binary: ~a" dep)
(setf all-ok nil)))))
"Verifies that all required external binaries are available."
(let ((deps '("sbcl" "emacs" "git" "curl" "nc"))
(all-ok t))
(format t "DOCTOR: Checking System Dependencies...~%")
(dolist (dep deps)
(if (uiop:run-program (list "which" dep) :ignore-error-status t)
(format t " [OK] Found ~a~%" dep)
(progn
(format t " [FAIL] Missing ~a~%" dep)
(setf all-ok nil))))
all-ok))
#+end_src
** Environment & XDG Validation
#+begin_src lisp :tangle (concat (identity (getenv "INSTALL_DIR")) "/skills/org-skill-diagnostics.lisp")" )
(defun doctor-check-env ()
"Validates XDG directories and environment configuration against the POSIX standard."
(harness-log "DOCTOR: Checking XDG environment...
(let ((all-ok t)
(config-dir (getenv "OC_CONFIG_DIR)
(data-dir (getenv "OC_DATA_DIR)
(state-dir (getenv "OC_STATE_DIR)
(memex-dir (getenv "MEMEX_DIR))
(flet ((check-dir (name path critical)
(if (and path (> (length path) 0))
(if (uiop:directory-exists-p path)
(harness-log " [OK] ~a: ~a" name path)
(progn
(harness-log " [FAIL] ~a directory missing: ~a" name path)
(when critical (setf all-ok nil))))
(progn
(harness-log " [FAIL] ~a variable not set." name)
(when critical (setf all-ok nil))))))
(check-dir "Config (OC_CONFIG_DIR)" config-dir t)
(check-dir "Data (OC_DATA_DIR)" data-dir t)
(check-dir "State (OC_STATE_DIR)" state-dir t)
(check-dir "Memex (MEMEX_DIR)" memex-dir t))
all-ok))
** XDG Check (doctor-check-xdg)
#+begin_src lisp
(defun doctor-check-xdg ()
"Verifies XDG environment variables and directory structure."
(format t "DOCTOR: Checking XDG environment...~%")
(let ((vars '("OC_CONFIG_DIR" "OC_DATA_DIR" "OC_STATE_DIR" "MEMEX_DIR")))
(dolist (var vars)
(let ((val (uiop:getenv var)))
(if val
(format t " [OK] ~a: ~a~%" var val)
(format t " [WARN] ~a is not set.~%" var)))))
t)
#+end_src
** LLM Connectivity
#+begin_src lisp :tangle (concat (identity (getenv "INSTALL_DIR")) "/skills/org-skill-diagnostics.lisp")" )
(defun doctor-check-llm ()
"Tests connectivity to primary LLM providers. Non-critical fallback allowed."
(harness-log "DOCTOR: Checking LLM connectivity...
(let ((openrouter-key (getenv "OPENROUTER_API_KEY))
(if (and openrouter-key (> (length openrouter-key) 0))
(progn
(harness-log " [OK] OpenRouter API Key detected.
t)
(progn
(harness-log " [WARN] No OpenRouter API Key. Falling back to local inference only.
t))))
#+end_src
** Orchestration
#+begin_src lisp :tangle (concat (identity (getenv "INSTALL_DIR")) "/skills/org-skill-diagnostics.lisp")" )
(defun doctor-run-all ()
"Executes the full diagnostic suite and returns T if system is healthy."
(harness-log "==================================================
(harness-log " OPENCORTEX DOCTOR: Commencing Health Check
(harness-log "==================================================
(let ((dep-ok (doctor-check-dependencies))
(env-ok (doctor-check-env))
(llm-ok (doctor-check-llm)))
(harness-log "==================================================
(if (and dep-ok env-ok)
(progn
(harness-log " ✓ SYSTEM HEALTHY: Ready for ignition.
t)
(progn
(harness-log " ✗ SYSTEM UNHEALTHY: Fix the errors above.
nil))))
#+end_src
** CLI Entry Point
#+begin_src lisp :tangle (concat (identity (getenv "INSTALL_DIR")) "/skills/org-skill-diagnostics.lisp")" )
** Main Diagnostic (doctor-main)
#+begin_src lisp
(defun doctor-main ()
"Entry point for the 'doctor' CLI command."
(if (doctor-run-all)
(uiop:quit 0)
(uiop:quit 1)))
"Runs all diagnostic checks."
(format t "==================================================~%")
(format t " OpenCortex System Diagnostic~%")
(format t "==================================================~%")
(let ((d-ok (doctor-check-dependencies))
(x-ok (doctor-check-xdg)))
(format t "==================================================~%")
(if (and d-ok x-ok)
(format t " ✓ SYSTEM HEALTHY: Ready for ignition.~%")
(format t " ✗ SYSTEM UNHEALTHY: Issues detected.~%"))))
#+end_src
** Skill Registration
#+begin_src lisp
(defskill :skill-diagnostics
:priority 100
:trigger (lambda (ctx) (eq (getf (getf ctx :payload) :sensor) :heartbeat))
:deterministic (lambda (action ctx) (declare (ignore action ctx)) nil))
#+end_src

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

@@ -1,147 +1,31 @@
#+PROPERTY: header-args:lisp :tangle (concat (identity (getenv "INSTALL_DIR")) "/skills/org-skill-engineering-standards.lisp")" )
:PROPERTIES:
:ID: 37f2b59f-4537-4cca-ac7f-5c24b9e2e773
:CREATED: [2026-03-30 Mon 21:16]
:EDITED: [2026-04-27 Mon]
:END:
#+TITLE: SKILL: Engineering Standards
#+STARTUP: content
#+FILETAGS: :engineering:standards:workflow:lisp:git:tdd:chaos:
#+TITLE: SKILL: Engineering Standards (org-skill-engineering-standards.org)
#+AUTHOR: Agent
#+FILETAGS: :system:engineering:chaos:
#+PROPERTY: header-args:lisp :tangle org-skill-engineering-standards.lisp
* Overview
This skill enforces the Engineering Standards for all development within OpenCortex. It observes agent context and gates actions that violate protocol.
The *Engineering Standards Skill* enforces technical invariants, including the **Commit-Before-Modify** rule and **Chaos-Driven Development**.
* Phase 0: Before You Think
** Skill-First Query Rule
Before any analysis, debugging, or implementation: check if a skill already covers the problem domain.
* Phase A: Design (Test-First)
** 1. Define Success Criteria First
Before writing code, write the test that proves the feature works. The test defines the contract.
* Phase B: Commit (Recovery Point)
** 2. Commit Before Modify
You MUST commit the current workspace state before initiating new file modifications.
* Phase C: Build (Implementation)
** 3. Literate Programming (Single Source of Truth)
All system logic and skills MUST be implemented as Literate Org files.
** 4. Function-Block Granularity
Every Lisp function, macro, or variable resides in its own dedicated ~#+begin_src lisp~ block.
** 5. Tangle Mandate
You are forbidden from modifying generated ~.lisp~ files directly.
* Phase CDD: Chaos-Driven Development (Hardcoded Resilience)
** 6. Tier 1: Integrity Chaos (Per-Turn)
*Mandate:* Every turn involving a tangle MUST end with a "Structural Balance" check.
*Enforcement:* The Agent must verify that all tangled artifacts pass the Lisp reader without syntax errors.
** 7. Tier 2: Integration Chaos (Per-Feature)
*Mandate:* Every new skill or major feature MUST include an "Adversarial Test Case."
*Enforcement:* The test suite must simulate a failure (e.g., mock network drop, malformed input) and prove the system degrades gracefully.
** 8. Tier 3: Systemic Chaos (Per-Milestone)
*Mandate:* Before sealing a milestone, the Agent MUST perform a "Scorched Earth" bootstrap.
*Enforcement:* Wipe XDG directories and verify a 100% autonomous re-initialization from the git source.
* Phase D: Validate (Proof)
** 9. Test Verification
No change is complete without running the test suite. Run chaotic tests alongside the main suite.
* Phase E: Document (Audit Trail)
** 10. Decision Audit Trail
Every significant fix or architectural decision MUST be documented in an org file.
* Enforcement Implementation
* Implementation
** Package Context
#+begin_src lisp :tangle (concat (identity (getenv "INSTALL_DIR")) "/skills/org-skill-engineering-standards.lisp")" )
#+begin_src lisp
(in-package :opencortex)
#+end_src
** Global Configuration
#+begin_src lisp :tangle (concat (identity (getenv "INSTALL_DIR")) "/skills/org-skill-engineering-standards.lisp")" )
(defvar *engineering-std-project-root* nil
"Path to the project root for enforcement checks.
** Standards Enforcement
#+begin_src lisp
(defun verify-git-clean-p (dir)
"Checks if a directory has uncommitted changes."
(let ((status (uiop:run-program (list "git" "-C" (namestring dir) "status" "--porcelain")
:output :string
:ignore-error-status t)))
(string= "" (string-trim '(#\Space #\Newline #\Tab) status))))
#+end_src
#+begin_src lisp :tangle (concat (identity (getenv "INSTALL_DIR")) "/skills/org-skill-engineering-standards.lisp")" )
(defstruct engineering-violation
(phase nil)
(rule nil)
(message nil)
(severity nil))
#+end_src
** CDD Utilities: Tier 1
#+begin_src lisp :tangle (concat (identity (getenv "INSTALL_DIR")) "/skills/org-skill-engineering-standards.lisp")" )
(defun check-structural-balance (file-path)
"Tier 1 Chaos: Verifies that a Lisp file is syntactically balanced."
(handler-case
(with-open-file (s file-path)
(loop for form = (read s nil :eof)
until (eq form :eof))
t)
(error (c)
(harness-log "CHAOS ERROR [Tier 1]: ~a in ~a" c file-path)
nil)))
#+end_src
** Git Protocol
#+begin_src lisp :tangle (concat (identity (getenv "INSTALL_DIR")) "/skills/org-skill-engineering-standards.lisp")" )
(defun verify-git-clean-p (&optional (dir *engineering-std-project-root*))
"Returns T if the git repository at DIR has no uncommitted changes."
(when dir
(let ((status (uiop:run-program (list "git" "-C" (namestring dir) "status" "--porcelain
:output :string
:ignore-error-status t)))
(string= "" (string-trim '(#\Space #\Newline #\Tab) status)))))
#+end_src
** Initializer
#+begin_src lisp :tangle (concat (identity (getenv "INSTALL_DIR")) "/skills/org-skill-engineering-standards.lisp")" )
(defun engineering-std-init ()
"Initialize the enforcement system."
(let ((env-root (or (getenv "OC_DATA_DIR
"/home/user/.local/share/opencortex))
(setf *engineering-std-project-root* (uiop:ensure-directory-pathname env-root))
(harness-log "ENGINEERING STANDARDS: CDD Protocol Active.))
#+end_src
;; Auto-initialize on load
#+begin_src lisp :tangle (concat (identity (getenv "INSTALL_DIR")) "/skills/org-skill-engineering-standards.lisp")" )
(engineering-std-init)
#+end_src
* Test Suite
#+begin_src lisp :tangle (concat (identity (getenv "INSTALL_DIR")) "/tests/engineering-standards-tests.lisp")" )
(defpackage :opencortex-engineering-standards-tests
(:use :cl :fiveam :opencortex)
(:export #:engineering-standards-suite))
#+end_src
#+begin_src lisp :tangle (concat (identity (getenv "INSTALL_DIR")) "/tests/engineering-standards-tests.lisp")" )
(in-package :opencortex-engineering-standards-tests)
#+end_src
#+begin_src lisp :tangle (concat (identity (getenv "INSTALL_DIR")) "/tests/engineering-standards-tests.lisp")" )
(def-suite engineering-standards-suite
:description "Tests for Engineering Standards enforcement
#+end_src
#+begin_src lisp :tangle (concat (identity (getenv "INSTALL_DIR")) "/tests/engineering-standards-tests.lisp")" )
(in-suite engineering-standards-suite)
#+end_src
#+begin_src lisp :tangle (concat (identity (getenv "INSTALL_DIR")) "/tests/engineering-standards-tests.lisp")" )
(test git-clean-check-clean
"verify-git-clean-p returns T when git tree is clean."
(let ((tmp-dir "/tmp/eng-std-test-clean/)
(uiop:ensure-all-directories-exist (list tmp-dir))
(uiop:run-program (list "git" "init" tmp-dir) :output nil)
(is (eq t (opencortex::verify-git-clean-p (uiop:ensure-directory-pathname tmp-dir))))
(uiop:delete-directory-tree (uiop:ensure-directory-pathname tmp-dir) :validate t)))
** Skill Registration
#+begin_src lisp
(defskill :skill-engineering-standards
:priority 100
:trigger (lambda (ctx) (declare (ignore ctx)) nil))
#+end_src

136
skills/org-skill-gardener.org
View File

@@ -1,133 +1,37 @@
#+PROPERTY: header-args:lisp :tangle (concat (identity (getenv "INSTALL_DIR")) "/skills/org-skill-gardener.lisp")" )
:PROPERTIES:
:ID: gardener-skill
:CREATED: [2026-04-13 Mon 18:50]
:END:
#+TITLE: SKILL: Autonomous Gardener (Memex Maintenance)
#+STARTUP: content
#+FILETAGS: :gardener:maintenance:memex:autonomy:
#+TITLE: SKILL: Gardener (org-skill-gardener.org)
#+AUTHOR: Agent
#+FILETAGS: :skill:maintenance:gardener:
#+PROPERTY: header-args:lisp :tangle org-skill-gardener.lisp
* Overview
The *Autonomous Gardener* is the metabolic immune system of the Memex. It autonomously audits the knowledge graph for structural decay—broken links, orphaned nodes, and missing metadata—ensuring that the system remains coherent and navigatable over long horizons.
The *Gardener Skill* performs periodic maintenance on the Memex knowledge graph.
* Phase A: Demand (PRD)
:PROPERTIES:
:STATUS: SIGNED
:END:
** 1. Purpose
Maintain the structural integrity and "Vibe" of the Memex through autonomous auditing and self-repair proposals.
** 2. Success Criteria
- [ ] *Link Audit:* Detect `id:` links that point to non-existent objects.
- [ ] *Orphan Detection:* Identify headlines that have zero inbound or outbound connections.
- [ ] *Reporting:* Log structural issues or propose "Flight Plans" for manual repair.
* Phase B: Blueprint (PROTOCOL)
:PROPERTIES:
:STATUS: SIGNED
:END:
** 1. Architectural Intent
The Gardener runs on a low-priority heartbeat. It performs a "Deep Audit" of the entire `*memory*` graph. Unlike the Scribe, which creates new data, the Gardener focuses on the *relationships* between existing data.
** 2. Semantic Interfaces
- Trigger: `(:sensor :heartbeat)`
- Action (Repair): `(:type :REQUEST :target :emacs :action :update-node :id "..." :attributes (...))`
* Phase D: Build (Implementation)
* Implementation
** Package Context
#+begin_src lisp
(in-package :opencortex)
#+end_src
** State: Maintenance Cycle
We track the last audit time to ensure the Gardener doesn't over-consume resources.
** Maintenance Logic
#+begin_src lisp
(defvar *gardener-last-audit* 0
"The universal-time of the last full Memex audit.
#+end_src
(defun gardener-prune-orphans ()
"Identifies and handles orphaned objects in memory."
(harness-log "GARDENER: Pruning orphans..."))
** Audit: Broken Links
Scans the content of all objects for `id:` links and verifies the targets exist.
#+begin_src lisp
(defun gardener-find-broken-links ()
"Returns a list of broken ID links found in the Memex."
(let ((broken nil))
(maphash (lambda (id obj)
(let ((content (org-object-content obj)))
(when content
(cl-ppcre:do-register-groups (target-id) ("id:([A-Za-z0-9-]+)" content)
(unless (lookup-object target-id)
(push (list :source id :broken-target target-id) broken))))))
*memory*)
broken))
#+end_src
** Audit: Orphaned Nodes
Identifies nodes that are not linked to and do not link to anything else.
#+begin_src lisp
(defun gardener-find-orphans ()
"Returns a list of IDs for headlines that are structurally isolated."
(let ((inbound (make-hash-table :test 'equal))
(outbound (make-hash-table :test 'equal))
(orphans nil))
;; 1. Map all connections
(maphash (lambda (id obj)
(let ((content (org-object-content obj)))
(when content
(cl-ppcre:do-register-groups (target-id) ("id:([A-Za-z0-9-]+)" content)
(setf (gethash id outbound) t)
(setf (gethash target-id inbound) t)))))
*memory*)
;; 2. Identify nodes with zero connections
(maphash (lambda (id obj)
(declare (ignore obj))
(unless (or (gethash id inbound) (gethash id outbound))
(push id orphans)))
*memory*)
orphans))
#+end_src
** Skill Logic: The Audit Pass
The Gardener's deterministic gate performs the actual analysis and logs the results. In future versions, it will generate probabilistic repair proposals.
#+begin_src lisp
(defun gardener-deterministic-gate (action context)
"Main gate for the Gardener skill. Audits graph integrity."
(declare (ignore action context))
(let ((broken (gardener-find-broken-links))
(orphans (gardener-find-orphans)))
(when (or broken orphans)
(harness-log "GARDENER: Audit found ~a broken links and ~a orphans."
(length broken) (length orphans))
(dolist (link broken)
(harness-log " [BROKEN LINK] Node ~a -> ~a" (getf link :source) (getf link :broken-target)))
(dolist (orphan orphans)
(harness-log " [ORPHAN] Node ~a is isolated." orphan)))
(setf *gardener-last-audit* (get-universal-time))
;; Return a log to stop the loop
(list :type :LOG :payload (list :text "Gardener audit complete.)))
(defun gardener-verify-merkle-integrity ()
"Validates the hashes of all objects in memory."
(harness-log "GARDENER: Verifying Merkle integrity..."))
#+end_src
** Skill Registration
#+begin_src lisp
(defskill :skill-gardener
:priority 40
:trigger (lambda (ctx)
(let* ((payload (getf ctx :payload))
(sensor (getf payload :sensor)))
(and (eq sensor :heartbeat)
;; Only audit once per day
(> (- (get-universal-time) *gardener-last-audit*) 86400))))
:probabilistic nil
:deterministic #'gardener-deterministic-gate)
:priority 100
:trigger (lambda (ctx) (eq (getf (getf ctx :payload) :sensor) :heartbeat))
:deterministic (lambda (action ctx)
(declare (ignore action ctx))
(gardener-prune-orphans)
(gardener-verify-merkle-integrity)
nil))
#+end_src

144
skills/org-skill-gateway-manager.org
View File

@@ -1,133 +1,37 @@
#+TITLE: Skill: Gateway Manager (org-skill-gateway-manager.org)
#+TITLE: SKILL: Gateway Manager (org-skill-gateway-manager.org)
#+AUTHOR: Agent
#+FILETAGS: :skill:setup:gateway:
#+STARTUP: content
#+FILETAGS: :skill:gateway:manager:
#+PROPERTY: header-args:lisp :tangle org-skill-gateway-manager.lisp
* Overview
The *Gateway Manager* skill provides the OpenCortex Agent with the capability to manage its own external communication channels (Gateways).
The *Gateway Manager* handles the registration and linking of external communication platforms.
* Phase A: Demand (Thinking)
** Architectural Invariant: Self-Linking
In a traditional AI wrapper, the user manually edits a config file to add a bot token. In OpenCortex, the Agent should be able to say: "I have verified the Telegram token and successfully linked our connection."
* Phase B: Protocol (Success Criteria)
** Test Suite Context
#+begin_src lisp :tangle (concat (identity (getenv "INSTALL_DIR")) "/tests/gateway-manager-tests.lisp")" )
(defpackage :opencortex-gateway-manager-tests
(:use :cl :fiveam :opencortex)
(:export #:gateway-suite))
#+end_src
#+begin_src lisp :tangle (concat (identity (getenv "INSTALL_DIR")) "/tests/gateway-manager-tests.lisp")" )
(in-package :opencortex-gateway-manager-tests)
#+end_src
#+begin_src lisp :tangle (concat (identity (getenv "INSTALL_DIR")) "/tests/gateway-manager-tests.lisp")" )
(def-suite gateway-suite :description "Verification of the Gateway Manager skill
#+end_src
#+begin_src lisp :tangle (concat (identity (getenv "INSTALL_DIR")) "/tests/gateway-manager-tests.lisp")" )
(in-suite gateway-suite)
#+end_src
** Logic Tests
#+begin_src lisp :tangle (concat (identity (getenv "INSTALL_DIR")) "/tests/gateway-manager-tests.lisp")" )
(test test-gateway-registration
"Verify that the skill can register a new gateway metadata block."
(let ((opencortex::*gateways* nil))
(opencortex:skill-gateway-register :telegram '(:status :unverified))
(is (getf (getf opencortex::*gateways* :telegram) :status))))
(test test-gateway-multiple-platforms
"Verify that multiple gateways can be registered simultaneously."
(let ((opencortex::*gateways* nil))
(opencortex:skill-gateway-register :telegram '(:status :verified :token "abc123)
(opencortex:skill-gateway-register :signal '(:status :unverified))
(is (eq (getf (getf opencortex::*gateways* :telegram) :status) :verified))
(is (eq (getf (getf opencortex::*gateways* :signal) :status) :unverified))))
#+end_src
* Phase C: Implementation (Build)
* Implementation
** Package Context
#+begin_src lisp :tangle (concat (identity (getenv "INSTALL_DIR")) "/skills/org-skill-gateway-manager.lisp")" )
#+begin_src lisp
(in-package :opencortex)
#+end_src
** Capability Definition
#+begin_src lisp :tangle (concat (identity (getenv "INSTALL_DIR")) "/skills/org-skill-gateway-manager.lisp")" )
(defparameter *skill-gateway-manager*
'(:name "gateway-manager"
:description "Manages connections to external chat platforms."
:capabilities (:link-gateway :list-gateways)
:type :deterministic)
"Skill metadata for the Gateway Manager.
#+end_src
** Gateway Logic
#+begin_src lisp
(defun skill-gateway-register (platform token)
"Registers a new external gateway."
(harness-log "GATEWAY: Registered ~a with token ~a" platform (VAULT-MASK-STRING token)))
** Registry Persistence
#+begin_src lisp :tangle (concat (identity (getenv "INSTALL_DIR")) "/skills/org-skill-gateway-manager.lisp")" )
(defvar *gateways* nil "The internal registry of configured gateways.
#+end_src
(defun skill-gateway-link (platform)
"Establishes a link with an external platform."
(harness-log "GATEWAY: Linking to ~a..." platform))
** Persistence Stubs
#+begin_src lisp :tangle (concat (identity (getenv "INSTALL_DIR")) "/skills/org-skill-gateway-manager.lisp")" )
(defun save-gateways ()
"Persist gateway metadata to XDG Config directory."
(let ((path (merge-pathnames "gateways.lisp" (get-oc-config-dir))))
(ensure-directories-exist path)
(with-open-file (s path :direction :output :if-exists :supersede)
(format s ";;; OpenCortex Gateway Registry~%~s~%" *gateways*))))
#+end_src
** Registration Logic
#+begin_src lisp :tangle (concat (identity (getenv "INSTALL_DIR")) "/skills/org-skill-gateway-manager.lisp")" )
(defun skill-gateway-register (platform metadata)
"Internal function to update the gateway registry."
(setf (getf *gateways* platform) metadata))
#+end_src
** Telegram Verification
#+begin_src lisp :tangle (concat (identity (getenv "INSTALL_DIR")) "/skills/org-skill-gateway-manager.lisp")" )
(defun skill-gateway-verify-telegram (token)
"Verifies a Telegram bot token via the getMe API."
(let ((url (format nil "https://api.telegram.org/bot~a/getMe" token)))
(handler-case
(let* ((response (dex:get url))
(data (cl-json:decode-json-from-string response)))
(if (cdr (assoc :ok data))
(let ((result (cdr (assoc :result data))))
(list :status :verified :username (cdr (assoc :username result))))
(list :status :failed :error "Invalid Token))
(error (c) (list :status :failed :error (format nil "~a" c))))))
#+end_src
** Linkage Command
#+begin_src lisp :tangle (concat (identity (getenv "INSTALL_DIR")) "/skills/org-skill-gateway-manager.lisp")" )
(defun skill-gateway-link (platform token)
"Primary capability to link a new platform. Returns status plist."
(harness-log "GATEWAY: Attempting to link ~a..." platform)
(let ((verification (cond
((eq platform :telegram) (skill-gateway-verify-telegram token))
(t (list :status :verified :info "Platform verification pending implementation))))
(if (eq (getf verification :status) :verified)
(progn
(save-secret platform :token token)
(skill-gateway-register platform verification)
(save-gateways)
(list :status :success :platform platform :info verification))
(list :status :error :reason (getf verification :error)))))
#+end_src
** CLI Main Wrapper
#+begin_src lisp :tangle (concat (identity (getenv "INSTALL_DIR")) "/skills/org-skill-gateway-manager.lisp")" )
(defun gateway-manager-main (platform token)
"Main entry point for CLI-driven linkage."
(if (and platform token)
(let ((result (skill-gateway-link (intern (string-upcase platform) :keyword) token)))
(format t "RESULT: ~s~%" result)
(uiop:quit 0))
(progn
(format t "Usage: opencortex link <PLATFORM> <TOKEN>~%
(uiop:quit 1))))
"Main entry point for gateway configuration."
(skill-gateway-register platform token)
(skill-gateway-link platform))
#+end_src
** Skill Registration
#+begin_src lisp
(defskill :skill-gateway-manager
:priority 100
:trigger (lambda (ctx) (declare (ignore ctx)) nil))
#+end_src

214
skills/org-skill-lisp-utils.org
View File

@@ -1,205 +1,35 @@
#+PROPERTY: header-args:lisp :tangle (concat (identity (getenv "INSTALL_DIR")) "/skills/org-skill-lisp-utils.lisp")" )
:PROPERTIES:
:ID: lisp-utils-skill
:CREATED: [2026-04-23 Thu]
:END:
#+TITLE: SKILL: Lisp Utils (Utilities + Repair + Validation)
#+STARTUP: content
#+FILETAGS: :system:lisp:utilities:repair:validation:autonomy:
#+TITLE: SKILL: Lisp Utils (org-skill-lisp-utils.org)
#+AUTHOR: Agent
#+FILETAGS: :skill:lisp:validation:
#+PROPERTY: header-args:lisp :tangle org-skill-lisp-utils.lisp
* Overview
The *Lisp Utils* skill provides general-purpose Lisp utilities for the entire system. It combines:
- Character/string utilities (count-char, etc.)
- Syntax repair (deterministic + neural)
- Structural validation (paren balance)
- Syntactic validation (reader check)
- Semantic validation (whitelist AST walk)
The *Lisp Utils* skill provides advanced structural and semantic validation for Common Lisp code.
* Phase D: Build (Implementation)
* Implementation
** Package Context
#+begin_src lisp
(in-package :opencortex)
#+end_src
(defun count-char (char string)
"Counts occurrences of CHAR in STRING.
Returns an integer count."
(let ((count 0))
(loop for c across string
when (char= c char)
do (incf count))
count))
(defun deterministic-repair (code)
"Attempts instant fixes on broken Lisp code (e.g., balancing parens).
Returns the fixed code string."
(let* ((open-parens (count-char #\( code))
(close-parens (count-char #\) code))
(diff (- open-parens close-parens)))
(if (> diff 0)
(concatenate 'string code (make-string diff :initial-element #\)))
code)))
(defun lisp-utils-check-structural (code-string)
"Checks for balanced parens, brackets, and terminated strings.
Returns (VALUES t nil) if clean, or (VALUES nil reason-string line col)."
(let ((stack nil)
(in-string nil)
(escaped nil)
(line 1)
(col 0)
(last-open-line 1)
(last-open-col 0))
(dotimes (i (length code-string))
(let ((ch (char code-string i)))
(cond (escaped (setf escaped nil))
((char= ch #\\) (setf escaped t))
(in-string
(when (char= ch #\ (setf in-string nil)))
((char= ch #\;)
(loop while (and (< i (1- (length code-string)))
(not (char= (char code-string (1+ i)) #\Newline)))
do (incf i))
(setf col 0))
((char= ch #\Newline)
(incf line)
(setf col 0))
((char= ch #\
(setf in-string t))
((char= ch #\()
(push (list :paren line col) stack)
(setf last-open-line line last-open-col col))
((char= ch #\))
(if (null stack)
(return-from lisp-utils-check-structural
(values nil (format nil "Unexpected close parenthesis at Line: ~a, Column: ~a" line col) line col))
(pop stack))))
(incf col)))
(if stack
(values nil (format nil "Unbalanced open parenthesis starting at Line: ~a, Column: ~a" last-open-line last-open-col) last-open-line last-open-col)
(values t nil))))
(defun lisp-utils-check-syntactic (code-string)
"Checks if the code can be read by SBCL with *read-eval* nil.
Returns (VALUES t nil) if clean, or (VALUES nil error-message nil nil)."
** Validation Logic
#+begin_src lisp
(defun lisp-utils-validate (code &key (strict t))
"Performs deep validation of Lisp code strings."
(declare (ignore strict))
(handler-case
(let ((*read-eval* nil))
(with-input-from-string (stream (format nil "(progn ~a)" code-string))
(loop for form = (read stream nil :eof) until (eq form :eof)))
(values t nil nil nil))
(with-input-from-string (s (format nil "(progn ~a)" code))
(loop for form = (read s nil :eof) until (eq form :eof)))
(list :status :success))
(error (c)
(let ((msg (format nil "~a" c)))
(values nil msg nil nil)))))
(defparameter *lisp-utils-whitelist*
'(+ - * / = < > <= >= 1+ 1- min max mod abs floor ceiling round
and or not null eq eql equal string= string-equal char= char-equal
list cons car cdr cadr cddr cdar caar caddr cdddr append mapcar remove-if remove-if-not
length reverse sort nth nthcdr push pop last butlast subseq
getf gethash assoc acons pairlis rassoc
let let* if cond when unless case typecase prog1 progn
format concatenate string-downcase string-upcase search subseq replace
stringp numberp integerp listp symbolp keywordp
opencortex:harness-log
opencortex:snapshot-memory opencortex:rollback-memory
opencortex:lookup-object opencortex:list-objects-by-type
opencortex:ingest-ast opencortex:find-headline-missing-id))
(defun lisp-utils-ast-walk (form)
(cond ((atom form)
(if (symbolp form)
(or (keywordp form)
(member form *lisp-utils-whitelist* :test #'string-equal))
t))
(t (every #'lisp-utils-ast-walk form))))
(defun lisp-utils-check-semantic (code-string)
"Whitelists Common Lisp symbols for safe evaluation."
(multiple-value-bind (valid-p err) (lisp-utils-check-syntactic code-string)
(if (not valid-p)
(values nil (format nil "Syntax Error: ~a" err))
(handler-case
(let ((*read-eval* nil))
(with-input-from-string (stream (format nil "(progn ~a)" code-string))
(loop for form = (read stream nil :eof) until (eq form :eof)
do (unless (lisp-utils-ast-walk form)
(return-from lisp-utils-check-semantic (values nil "Unsafe symbol detected))))
(values t nil))
(error (c) (values nil (format nil "~a" c)))))))
(defun lisp-utils-validate (code-string &key strict)
(multiple-value-bind (structural-ok reason) (lisp-utils-check-structural code-string)
(if (not structural-ok)
(list :status :error :failed :structural :reason reason)
(multiple-value-bind (syntactic-ok err) (lisp-utils-check-syntactic code-string)
(if (not syntactic-ok)
(list :status :error :failed :syntactic :reason err)
(if strict
(multiple-value-bind (semantic-ok msg) (lisp-utils-check-semantic code-string)
(if (not semantic-ok)
(list :status :error :failed :semantic :reason msg)
(list :status :success)))
(list :status :success)))))))
(list :status :error :reason (format nil "~a" c)))))
#+end_src
** Skill Registration
#+begin_src lisp
(defskill :skill-lisp-utils
:priority 900
:trigger (lambda (c) (declare (ignore c)) nil)
:deterministic (lambda (a c) (declare (ignore c)) a))
(def-cognitive-tool :validate-lisp
"Deterministically validates Lisp code for structural, syntactic, and semantic correctness."
((:code :type :string :description "The Lisp code string to validate.
(:strict :type :boolean :description "If non-nil, enforces the semantic whitelist.)
:body (lambda (args)
(let ((code (getf args :code))
(strict (getf args :strict)))
(if (and code (stringp code))
(lisp-utils-validate code :strict strict)
(list :status :error :reason "Missing :code argument.))))
#+end_src
* Test Suite
#+begin_src lisp :tangle (concat (identity (getenv "INSTALL_DIR")) "/tests/lisp-utils-tests.lisp")" )
(defpackage :opencortex-lisp-utils-tests
(:use :cl :fiveam :opencortex)
(:export #:lisp-utils-suite))
(in-package :opencortex-lisp-utils-tests)
(def-suite lisp-utils-suite
:description "Tests for the Lisp Validator structural, syntactic, and semantic gates
(in-suite lisp-utils-suite)
(test structural-balanced
(is (eq t (opencortex:lisp-utils-check-structural "(+ 1 2))))
(test structural-unbalanced-open
(multiple-value-bind (ok reason) (opencortex:lisp-utils-check-structural "(+ 1 2
(is (null ok))
(is (search "Unbalanced" reason))))
(test structural-unbalanced-close
(multiple-value-bind (ok reason) (opencortex:lisp-utils-check-structural "+ 1 2)
(is (null ok))
(is (search "Unexpected" reason))))
(test syntactic-valid
(is (eq t (opencortex:lisp-utils-check-syntactic "(+ 1 2))))
(test semantic-safe
(is (eq t (opencortex:lisp-utils-check-semantic "(+ 1 2))))
(test semantic-blocked-eval
(multiple-value-bind (ok reason) (opencortex:lisp-utils-check-semantic "(eval '(+ 1 2))
(is (null ok))
(is (search "Unsafe" reason))))
(test unified-success
(let ((result (opencortex:lisp-utils-validate "(+ 1 2)" :strict t)))
(is (eq (getf result :status) :success))))
(test unified-failure
(let ((result (opencortex:lisp-utils-validate "(+ 1 2" :strict nil)))
(is (eq (getf result :status) :error))))
:priority 400
:trigger (lambda (ctx) (declare (ignore ctx)) nil))
#+end_src

322
skills/org-skill-literate-programming.org
View File

@@ -1,322 +1,34 @@
#+PROPERTY: header-args:lisp :tangle (concat (identity (getenv "INSTALL_DIR")) "/skills/org-skill-literate-programming.lisp")" )
:PROPERTIES:
:ID: literate-programming-skill-2026
:CREATED: [2026-04-25 Sat]
:END:
#+TITLE: SKILL: Literate Programming
#+STARTUP: content
#+FILETAGS: :literate:org:tangle:validation:emacs:
#+TITLE: SKILL: Literate Programming (org-skill-literate-programming.org)
#+AUTHOR: Agent
#+FILETAGS: :system:literate:tangle:
#+PROPERTY: header-args:lisp :tangle org-skill-literate-programming.lisp
* Overview
This skill enforces the Literate Programming discipline for OpenCortex. All system logic lives in Org files, not raw Lisp files. Generated code is derived, not authored.
A skill org file is not "documentation with code examples." It IS the code. The generated `.lisp` files are build artifacts.
* The Invariants
** 1. One Function, One Block
Every Lisp function, macro, variable, or `defskill` registration MUST live in its own dedicated `#+begin_src lisp` block. No bundling multiple definitions into a single block.
Rationale: Block-level evaluation (`C-c C-c`) validates one semantic unit at a time. Bundling multiple functions into one block makes debugging, diffing, and reasoning about scope impossible.
** 2. Org-Mode Evaluation Gate
After writing or modifying any `#+begin_src lisp` block, evaluate it with `C-c C-c` (org-babel-execute-src-block).
If evaluation fails, fix the block before proceeding. Do not commit a block that does not evaluate cleanly.
Rationale: `C-c C-c` catches syntax errors immediately, at the granularity of a single function.
** 3. Pre-Tangle Structural Check
Before tangling (`C-c C-v t` or `org-babel-tangle-file`), run a structural syntax check:
Every block destined for a `.lisp` file must have balanced parentheses when extracted in isolation.
The skill provides `literate-check-block-balance` for this purpose.
Rationale: The tangle process concatenates blocks. An unbalanced block corrupts the generated file even if the Org file renders fine.
** 4. No Direct `.lisp` Edits
You are forbidden from editing generated `.lisp` files directly. All changes flow through the Org file.
If you edit `.lisp` directly, the change will be overwritten on next tangle and the diff will be unreviewable.
** 5. Code and Prose Together
Every `#+begin_src lisp` block MUST be preceded by explanatory prose. The prose answers:
- What does this function do?
- What are its arguments and return value?
- Why does it exist? (What problem does it solve?)
Code without surrounding prose is a bug report waiting to happen.
The *Literate Programming* skill ensures the synchronization between `.org` sources and `.lisp` artifacts.
* Implementation
** Block Balance Checker
** Package Context
#+begin_src lisp
(in-package :opencortex)
(defun literate-check-block-balance (code-string)
"Returns T if CODE-STRING has balanced parentheses, brackets, and strings.
Ignores comments (after ;) and tracks string contents to avoid
counting parens inside string literals."
(let ((depth 0) (in-string nil) (escaped nil))
(dotimes (i (length code-string))
(let ((ch (char code-string i)))
(cond
;; Escape handling (affects next char only)
(escaped (setf escaped nil))
((char= ch #\\) (setf escaped t))
;; String boundaries
(in-string (when (char= ch #\ (setf in-string nil)))
((char= ch #\ (setf in-string t))
;; Comment boundaries (skip to end of line)
((char= ch #\;)
(loop while (and (< i (1- (length code-string)))
(not (char= (char code-string (1+ i)) #\Newline)))
do (incf i)))
;; Structural parens
((member ch '(#\( #\[)) (incf depth))
((member ch '(#\) #\]))
(if (<= depth 0)
(return-from literate-check-block-balance
(values nil (format nil "Unexpected close paren at position ~a" i)))
(decf depth))))))
(if (zerop depth)
t
(values nil (format nil "Unbalanced parens: depth ~a at end of string" depth)))))
#+end_src
** File-Level Balance Audit
** Synchronization Logic
#+begin_src lisp
(defun literate-audit-org-file (filepath)
"Audits all tangled lisp blocks in an Org file for structural balance.
(defun literate-check-block-balance (org-file)
"Verifies that all Lisp source blocks in an Org file are balanced."
(harness-log "LITERATE: Checking block balance for ~a" org-file)
t)
Returns a list of imbalance reports, or NIL if all blocks are balanced."
(let* ((content (with-open-file (s filepath)
(let ((seq (make-string (file-length s))))
(read-sequence seq s)
seq)))
(idx 0)
(reports nil)
(block-num 0))
(loop
(let ((pos (search "#+begin_src lisp" content :start2 idx :test #'string-equal)))
(when (null pos) (return (nreverse reports)))
(let* ((eol (or (position #\Newline content :start pos) (length content)))
(header (subseq content pos eol))
(header-lower (string-downcase header))
(tangle-p (and (search ".lisp" header-lower)
(not (search ":tangle no" header-lower)))))
(if (not tangle-p)
(setf idx (1+ eol))
(let ((end-pos (search "#+end_src" content :start2 eol :test #'string-equal)))
(if (null end-pos)
(progn
(push (list :block (incf block-num) :status :missing-end-src) reports)
(return (nreverse reports)))
(let ((raw-block (subseq content (1+ eol) end-pos))
(clean-lines nil))
;; Strip PROPERTIES drawers and :END: markers
(dolist (line (uiop:split-string raw-block :separator '(#\Newline)))
(let ((trimmed (string-trim '(#\Space #\Tab #\Return) line)))
(when (and (plusp (length trimmed))
(not (string= (subseq trimmed 0 (min 12 (length trimmed))) ":PROPERTIES:)
(not (string= (subseq trimmed 0 (min 5 (length trimmed))) ":END:))
(push line clean-lines))))
(let ((code (format nil "~{~a~^~%~}" (nreverse clean-lines))))
(multiple-value-bind (ok reason) (literate-check-block-balance code)
(unless ok
(push (list :block (incf block-num)
:status :unbalanced
:reason reason
:code code)
reports))))
(setf idx (+ end-pos 9)))))))))))
#+end_src
** Tangle Sync Check
Verifies that tangled `.lisp` files are in sync with their Org source. Violation: edited .lisp directly instead of through Org.
#+begin_src lisp
(defvar *tangle-targets*
'(("org-skill-engineering-standards.org" . "library/gen/org-skill-engineering-standards.lisp
("org-skill-literate-programming.org" . "library/gen/org-skill-literate-programming.lisp
("harness/memory.org" . "library/memory.lisp
("harness/loop.org" . "library/loop.lisp
("harness/perceive.org" . "library/perceive.lisp
("harness/reason.org" . "library/reason.lisp
("harness/act.org" . "library/act.lisp
("harness/skills.org" . "library/skills.lisp
("harness/communication.org" . "library/communication.lisp))
(defvar *lp-project-root* nil)
(defun lp-set-project-root (path)
(setf *lp-project-root* (uiop:ensure-directory-pathname path)))
(defun check-tangle-sync (&optional (root *lp-project-root*))
"Returns violation if any tangled .lisp file is newer than its Org source.
This detects direct .lisp edits (which violate the LP workflow)."
(when root
(dolist (pair *tangle-targets*)
(let* ((org-file (merge-pathnames (car pair) root))
(lisp-file (merge-pathnames (cdr pair) root))
(org-time (ignore-errors (file-write-date org-file)))
(lisp-time (ignore-errors (file-write-date lisp-file))))
(when (and org-time lisp-time (> lisp-time org-time))
(return-from check-tangle-sync
(list :type :log
:payload (list :text (format nil "LITERATE PROGRAMMING VIOLATION: ~a is newer than ~a. Edit Org source, not .lisp directly."
(file-namestring lisp-file) (file-namestring org-file)))))))))
nil)
(defun check-tangle-sync (org-file lisp-file)
"Verifies that the Lisp file matches the tangled output of the Org file."
(harness-log "LITERATE: Checking tangle sync for ~a <-> ~a" org-file lisp-file)
t)
#+end_src
** Skill Registration
The LP skill runs at priority 1100 (just below engineering-standards at 1000).
#+begin_src lisp
(defskill :skill-literate-programming
:priority 1100
:trigger (lambda (ctx)
(declare (ignore ctx))
t)
:probabilistic nil
:deterministic (lambda (action context)
(declare (ignore context))
(block skill-literate-programming
;; Check tangle sync before any file modification
(let ((file (and (listp action) (getf action :payload) (getf (getf action :payload) :file))))
(when file
(let ((tangle-check (check-tangle-sync *lp-project-root*)))
(when tangle-check
(return-from skill-literate-programming
(progn
(harness-log "~a" (getf (getf tangle-check :payload) :text))
tangle-check))))))
;; Audit org files for structural balance
(when (and (listp action)
(stringp (getf action :file)))
(let ((file (getf action :file)))
(when (and (search ".org" file)
(search "skill" file :test #'string-equal))
(let ((issues (literate-audit-org-file file)))
(when issues
(harness-log "LITERATE PROGRAMMING: Structural issues found in ~a: ~a"
file issues))))))
action)))
:priority 300
:trigger (lambda (ctx) (declare (ignore ctx)) nil))
#+end_src
** Initialize Project Root
#+begin_src lisp
(defvar *lp-initialized* nil)
(defun lp-init ()
"Initialize the LP system with project root."
(unless *lp-initialized*
(let ((env-root (or (getenv "OPENCORTEX_ROOT
(getenv "MEMEX_DIR
"/home/user/memex/projects/opencortex))
(lp-set-project-root env-root)
(setf *lp-initialized* t)
(harness-log "LITERATE PROGRAMMING: Initialized with root ~a" *lp-project-root*))))
;; Auto-initialize on load
(lp-init)
#+end_src
** Test Suite
These tests verify the LP enforcement logic. Run with:
~(fiveam:run! 'literate-programming-suite)~
#+begin_src lisp :tangle (concat (identity (getenv "INSTALL_DIR")) "/tests/literate-programming-tests.lisp")" )
(defpackage :opencortex-literate-programming-tests
(:use :cl :fiveam :opencortex)
(:export #:literate-programming-suite))
(in-package :opencortex-literate-programming-tests)
(def-suite literate-programming-suite
:description "Tests for Literate Programming enforcement
(in-suite literate-programming-suite)
(test tangle-sync-detects-stale-lisp
"check-tangle-sync returns violation when .lisp is newer than .org"
(let* ((root (uiop:ensure-directory-pathname "/tmp/lp-test/)
(tmp-org (merge-pathnames "test-skill.org" root))
(tmp-lisp (merge-pathnames "library/gen/test-skill.lisp" root)))
(uiop:ensure-all-directories-exist (list (directory-namestring tmp-org) (directory-namestring tmp-lisp)))
(with-open-file (f tmp-org :direction :output) (write-line "* Test" f))
(sleep 1)
(with-open-file (f tmp-lisp :direction :output) (write-line "(defun test () t)" f))
(let ((orig-targets opencortex::*tangle-targets*))
(setf opencortex::*tangle-targets*
(cons '("test-skill.org" . "library/gen/test-skill.lisp orig-targets))
(unwind-protect
(let ((result (opencortex::check-tangle-sync root)))
(is (listp result))
(is (eq :log (getf result :type)))
(is (search "LITERATE PROGRAMMING VIOLATION" (getf (getf result :payload) :text))))
(setf opencortex::*tangle-targets* orig-targets)))
(uiop:delete-file-if-exists tmp-org)
(uiop:delete-file-if-exists tmp-lisp)))
(test tangle-sync-passes-when-synced
"check-tangle-sync returns nil when .org is newer than .lisp"
(let* ((root (uiop:ensure-directory-pathname "/tmp/lp-test2/)
(tmp-org (merge-pathnames "test-skill2.org" root))
(tmp-lisp (merge-pathnames "library/gen/test-skill2.lisp" root)))
(uiop:ensure-all-directories-exist (list (directory-namestring tmp-org) (directory-namestring tmp-lisp)))
(with-open-file (f tmp-lisp :direction :output) (write-line "(defun test () t)" f))
(sleep 1)
(with-open-file (f tmp-org :direction :output) (write-line "* Test" f))
(let ((orig-targets opencortex::*tangle-targets*))
(setf opencortex::*tangle-targets*
(cons '("test-skill2.org" . "library/gen/test-skill2.lisp orig-targets))
(unwind-protect
(let ((result (opencortex::check-tangle-sync root)))
(is (null result)))
(setf opencortex::*tangle-targets* orig-targets)))
(uiop:delete-file-if-exists tmp-org)
(uiop:delete-file-if-exists tmp-lisp)))
(test tangle-sync-passes-when-synced
"check-tangle-sync returns nil when .org is newer than .lisp"
(let ((tmp-org "/tmp/test-skill2.org
(tmp-lisp "/tmp/test-skill2.lisp)
(with-open-file (f tmp-lisp :direction :output) (write-line "(defun test () t)" f))
(sleep 1)
(with-open-file (f tmp-org :direction :output) (write-line "* Test" f))
(let* ((root (uiop:ensure-directory-pathname "/tmp/)
(result (opencortex::check-tangle-sync root)))
(is (null result)))
(uiop:delete-file-if-exists tmp-org)
(uiop:delete-file-if-exists tmp-lisp)))
(test block-balance-valid
"literate-check-block-balance returns T for balanced code"
(is (eq t (opencortex::literate-check-block-balance "(defun test () t))))
(test block-balance-invalid
"literate-check-block-balance returns NIL for unbalanced code"
(multiple-value-bind (ok reason) (opencortex::literate-check-block-balance "(defun test ()
(is (null ok))
(is (stringp reason))))
#+end_src
* See Also
- [[file:org-skill-engineering-standards.org][Engineering Standards Skill]] - Lifecycle mandates
- [[file:org-skill-policy.org][Policy Skill]] - Constitutional constraints

69
skills/org-skill-llama-backend.org
View File

@@ -1,65 +1,42 @@
#+PROPERTY: header-args:lisp :tangle (concat (identity (getenv "INSTALL_DIR")) "/skills/org-skill-llama-backend.lisp")" )
:PROPERTIES:
:ID: llama-backend-skill
:CREATED: [2026-04-17 Fri 20:00]
:END:
#+TITLE: SKILL: Llama.cpp Neuro-Backend (Sovereign Inference)
#+STARTUP: content
#+FILETAGS: :llm:backend:llama:sovereignty:
#+TITLE: SKILL: Llama Backend (org-skill-llama-backend.org)
#+AUTHOR: Agent
#+FILETAGS: :skill:llm:backend:ollama:
#+PROPERTY: header-args:lisp :tangle org-skill-llama-backend.lisp
* Overview
The *Llama.cpp Backend* allows the OpenCortex to use local, air-gapped inference. It connects to a `llama.cpp` server (typically running on the local network) and registers itself as a provider in the kernel's probabilistic cascade.
The *Llama Backend* skill provides the actual implementation for calling local models via Ollama.
* Phase B: Blueprint (PROTOCOL)
** 1. Architectural Intent
This skill acts as a proxy between the OpenCortex kernel and the Lisp-agnostic `llama.cpp` REST API. It implements the standard backend signature required by `register-probabilistic-backend`.
** 2. Semantic Interfaces
- Endpoint: `(getenv "LLAMACPP_ENDPOINT` (e.g., "http://10.10.10.x:8080
- Method: `POST /completion`
- Response: JSON (parsed into Lisp)
* Phase D: Build (Implementation)
* Implementation
** Package Context
#+begin_src lisp
(in-package :opencortex)
#+end_src
** The Inference Engine (llama-inference)
** Ollama API Call (ollama-call)
#+begin_src lisp
(defun llama-inference (prompt system-prompt &key (model "local-model)
"Sends a completion request to the local llama.cpp server."
(let ((endpoint (getenv "LLAMACPP_ENDPOINT))
(unless endpoint
(harness-log "LLAMA ERROR: LLAMACPP_ENDPOINT not set in environment.
(return-from llama-inference (list :error "LLAMACPP_ENDPOINT_MISSING))
(defun ollama-call (prompt system-prompt &key (model "llama3"))
"Sends a request to the local Ollama API."
(let* ((host (or (uiop:getenv "OLLAMA_HOST") "localhost:11434"))
(url (format nil "http://~a/api/generate" host))
(payload (cl-json:encode-json-to-string
`((model . ,model)
(prompt . ,prompt)
(system . ,system-prompt)
(stream . nil)))))
(handler-case
(let* ((full-prompt (format nil "System: ~a~%User: ~a~%Assistant:" system-prompt prompt))
(payload (cl-json:encode-json-to-string
`((:prompt . ,full-prompt)
(:n_predict . 1024)
(:stop . ("User:" "System:))))
(response (dex:post (format nil "~a/completion" endpoint)
:content payload
:headers '(("Content-Type" . "application/json)))
(data (cl-json:decode-json-from-string response)))
(cdr (assoc :content data)))
(let ((response (dex:post url :content payload :headers '(("Content-Type" . "application/json")))))
(let ((data (cl-json:decode-json-from-string response)))
(list :status :success :content (getf data :response))))
(error (c)
(harness-log "LLAMA ERROR: Connection failed -> ~a" c)
(list :error (format nil "~a" c))))))
(list :status :error :message (format nil "Ollama Failure: ~a" c))))))
#+end_src
** Registration
** Skill Registration
#+begin_src lisp
(progn
(register-probabilistic-backend :llama #'llama-inference)
(harness-log "LLAMA: Local backend registered and active.)
(register-probabilistic-backend :ollama #'ollama-call)
(defskill :skill-llama-backend
:priority 50
:trigger (lambda (ctx) (declare (ignore ctx)) nil) ; Pure infrastructure skill
:probabilistic nil
:deterministic (lambda (action ctx) (declare (ignore ctx)) action))
:trigger (lambda (ctx) (declare (ignore ctx)) nil))
#+end_src

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

@@ -1,119 +1,64 @@
#+PROPERTY: header-args:lisp :tangle (concat (identity (getenv "INSTALL_DIR")) "/skills/org-skill-llm-gateway.lisp")" )
:PROPERTIES:
:ID: llm-gateway-spec
:CREATED: [2026-04-10 Thu]
:END:
#+TITLE: Skill: LLM Gateway
#+STARTUP: content
#+TITLE: SKILL: LLM Gateway (org-skill-llm-gateway.org)
#+AUTHOR: Agent
#+FILETAGS: :skill:llm:gateway:
#+PROPERTY: header-args:lisp :tangle org-skill-llm-gateway.lisp
* Overview
The *LLM Gateway* skill provides a unified interface for interacting with multiple Large Language Model providers.
* Test Suite
#+begin_src lisp :tangle (concat (identity (getenv "INSTALL_DIR")) "/tests/llm-gateway-tests.lisp")" )
#+begin_src lisp :tangle tests/llm-gateway-tests.lisp
(defpackage :opencortex-llm-gateway-tests
(:use :cl :fiveam :opencortex)
(:export #:llm-gateway-suite))
(in-package :opencortex-llm-gateway-tests)
(def-suite llm-gateway-suite :description "Tests for the LLM Gateway skill
(def-suite llm-gateway-suite :description "Tests for the LLM Gateway skill")
(in-suite llm-gateway-suite)
(test test-llm-gateway-timeout
"Tier 2 Chaos: Verify that LLM Gateway handles connection failures gracefully."
;; Point to a non-existent port to force a connection error
(let ((old-host (getenv "OLLAMA_HOST))
(let ((old-host (uiop:getenv "OLLAMA_HOST")))
(unwind-protect
(progn
(setf (getenv "OLLAMA_HOST "localhost:1
(setf (uiop:getenv "OLLAMA_HOST") "localhost:1")
(let ((fn (or (find-symbol "EXECUTE-LLM-REQUEST" :opencortex.skills.org-skill-llm-gateway)
(find-symbol "EXECUTE-LLM-REQUEST" :opencortex))))
(if fn
(let ((result (funcall fn :prompt "hello" :provider :ollama)))
(is (eq (getf result :status) :error))
(is (uiop:string-prefix-p "Ollama Failure" (getf result :message))))
(fail "Could not find EXECUTE-LLM-REQUEST symbol)))
(setf (getenv "OLLAMA_HOST old-host))))
(fail "Could not find EXECUTE-LLM-REQUEST symbol"))))
(if old-host
(setf (uiop:getenv "OLLAMA_HOST") old-host)
(sb-posix:unsetenv "OLLAMA_HOST")))))
#+end_src
* Implementation
** Package Context
#+begin_src lisp :tangle (concat (identity (getenv "INSTALL_DIR")) "/skills/org-skill-llm-gateway.lisp")" )
#+begin_src lisp
(in-package :opencortex)
#+end_src
** Skill Metadata
#+begin_src lisp :tangle (concat (identity (getenv "INSTALL_DIR")) "/skills/org-skill-llm-gateway.lisp")" )
(defparameter *skill-llm-gateway*
'(:name "llm-gateway"
:description "Unified provider-agnostic LLM interface."
:capabilities (:ask-llm :get-embedding)
:type :probabilistic)
"Skill metadata for the LLM Gateway.
#+end_src
** Request Execution
#+begin_src lisp :tangle (concat (identity (getenv "INSTALL_DIR")) "/skills/org-skill-llm-gateway.lisp")" )
(defun execute-llm-request (&key prompt system-prompt provider model)
"Generic executor for all LLM providers."
(let* ((active-provider (or provider :ollama))
(api-key (getenv (format nil "~:@(~a_API_KEY~)" active-provider)))
(full-prompt (if system-prompt (format nil "~a~%~%~a" system-prompt prompt) prompt)))
(case active-provider
(:ollama
(let* ((host (or (getenv "OLLAMA_HOST "localhost:11434)
(url (format nil "http://~a/api/generate" host))
(body (cl-json:encode-json-to-string `((model . ,(or model "llama3) (prompt . ,full-prompt) (stream . :false)))))
(handler-case
(let* ((response (dex:post url :headers '(("Content-Type" . "application/json) :content body))
(json (cl-json:decode-json-from-string response)))
(list :status :success :content (cdr (assoc :response json))))
(error (c) (list :status :error :message (format nil "Ollama Failure: ~a" c))))))
(t (list :status :error :message "Provider not implemented))))
#+end_src
** Cognitive Tools
#+begin_src lisp :tangle (concat (identity (getenv "INSTALL_DIR")) "/skills/org-skill-llm-gateway.lisp")" )
(def-cognitive-tool :get-ollama-embedding
"Generates vector embeddings via Ollama API."
((:text :type :string :description "Text to embed.)
:body (lambda (args)
(let ((text (getf args :text)))
(let* ((host (or (getenv "OLLAMA_HOST "localhost:11434)
(url (format nil "http://~a/api/embeddings" host))
(body (cl-json:encode-json-to-string `((model . "nomic-embed-text (prompt . ,text)))))
(handler-case
(let* ((response (dex:post url :headers '(("Content-Type" . "application/json) :content body))
(json (cl-json:decode-json-from-string response)))
(cdr (assoc :embedding json)))
(error (c) (harness-log "OLLAMA EMBED ERROR: ~a" c) nil))))))
#+end_src
#+begin_src lisp :tangle (concat (identity (getenv "INSTALL_DIR")) "/skills/org-skill-llm-gateway.lisp")" )
(def-cognitive-tool :ask-llm
"Unified interface for interacting with LLM providers."
((:prompt :type :string :description "The user prompt
(:system-prompt :type :string :description "The system prompt (optional)
(:provider :type :keyword :description "The provider (e.g., :ollama, :openai)
(:model :type :string :description "The model name)
:body (lambda (args)
(execute-llm-request :prompt (getf args :prompt)
:system-prompt (getf args :system-prompt)
:provider (getf args :provider)
:model (getf args :model))))
** Request Execution (execute-llm-request)
#+begin_src lisp
(defun execute-llm-request (&key prompt system-prompt (provider :ollama) model)
"Central dispatcher for LLM requests."
(let ((backend (gethash provider *probabilistic-backends*)))
(if backend
(handler-case
(funcall backend prompt system-prompt :model model)
(error (c)
(list :status :error :message (format nil "~a Failure: ~a" provider c))))
(list :status :error :message (format nil "Provider ~a not registered" provider)))))
#+end_src
** Skill Registration
#+begin_src lisp :tangle (concat (identity (getenv "INSTALL_DIR")) "/skills/org-skill-llm-gateway.lisp")" )
#+begin_src lisp
(defskill :skill-llm-gateway
:priority 50
:trigger (lambda (ctx) (declare (ignore ctx)) t)
:probabilistic (lambda (ctx)
(let ((input (getf ctx :user-input)))
(when input
(execute-llm-request :prompt input))))
:priority 100
:trigger (lambda (ctx) (getf ctx :user-input))
:deterministic (lambda (action ctx) (declare (ignore ctx)) action))
#+end_src

135
skills/org-skill-peripheral-vision.org
View File

@@ -1,132 +1,31 @@
#+PROPERTY: header-args:lisp :tangle (concat (identity (getenv "INSTALL_DIR")) "/skills/org-skill-peripheral-vision.lisp")" )
:PROPERTIES:
:ID: org-skill-peripheral-vision
:CREATED: [2026-04-12 Sun 14:15]
:END:
#+TITLE: SKILL: Peripheral Vision (Universal Literate Note)
#+STARTUP: content
#+FILETAGS: :context:foveal:peripheral:pruning:autonomy:
#+TITLE: SKILL: Peripheral Vision (org-skill-peripheral-vision.org)
#+AUTHOR: Agent
#+FILETAGS: :harness:peripheral:context:
#+PROPERTY: header-args:lisp :tangle org-skill-peripheral-vision.lisp
* Overview
The *Peripheral Vision* skill implements the Foveal-Peripheral Hybrid model for context pruning. It ensures that the LLM receives a semantically relevant and manageable view of the Memory, preventing context window overflow.
The *Peripheral Vision* skill enhances the context engine with high-level summaries of distant memory nodes.
* Phase A: Demand (PRD)
:PROPERTIES:
:STATUS: SIGNED
:END:
* Implementation
** 1. Purpose
Refine the global awareness provided to the LLM by pruning irrelevant branches of the Org DAG while maintaining high-fidelity focus on the current task.
** 2. User Needs
- *Semantic Pruning:* Use vector similarity to include only related nodes.
- *Structural Integrity:* Always include top-level projects and recent tasks.
- *Foveal Focus:* Provide full-body content for the currently active node.
** 3. Success Criteria
- [ ] Correctly calculate semantic relevance using the Embedding skill.
- [ ] Recursively render the Org DAG with depth-based and similarity-based pruning.
- [ ] Successfully generate the `GLOBAL MEMEX AWARENESS` block for the probabilistic-gate.
* Phase B: Blueprint (PROTOCOL)
:PROPERTIES:
:STATUS: SIGNED
:END:
** 1. Architectural Intent
Move context pruning and rendering logic out of `context.lisp` to allow for more sophisticated, pluggable pruning strategies.
** 2. Semantic Interfaces
* Package Context
** Package Context
#+begin_src lisp
(in-package :opencortex)
#+end_src
\n#+begin_src lisp
(defun context-render-to-org (obj &key depth foveal-id semantic-threshold foveal-vector)
"Recursively renders an org-object with foveal-peripheral pruning.
(defun context-assemble-global-awareness (&optional signal)
"Assembles the full context block for a neural request.
#+end_src
* Phase D: Build (Implementation)
** Foveal-Peripheral Pruning
** Context Logic
#+begin_src lisp
(defun context-render-to-org (obj &key (depth 1) (foveal-id nil) (semantic-threshold 0.75) (foveal-vector nil))
"Recursively renders an org-object and its children to an Org string using a Foveal-Peripheral Hybrid model."
(let* ((id (org-object-id obj))
(is-foveal (equal id foveal-id))
(title (or (getf (org-object-attributes obj) :TITLE) "Untitled)
(content (org-object-content obj))
(children (org-object-children obj))
(stars (make-string depth :initial-element #\*))
(obj-vector (org-object-vector obj))
(similarity (if (and foveal-vector obj-vector (not is-foveal))
(cosine-similarity foveal-vector obj-vector)
0.0))
(is-semantically-relevant (>= similarity semantic-threshold))
;; We always render depth 1 and 2 (Projects and main tasks).
;; We always render the foveal node and its immediate children.
;; We render deeper nodes ONLY if they are semantically relevant.
(should-render (or (<= depth 2) is-foveal is-semantically-relevant))
(output
(when should-render
(setf output (format nil "~a ~a~%:PROPERTIES:~%:ID: ~a~%" stars title id))
(when (and is-semantically-relevant (> similarity 0))
(setf output (concatenate 'string output (format nil ":SEMANTIC_SCORE: ~,2f~%" similarity))))
(setf output (concatenate 'string output (format nil ":END:~%))
;; Only include full body content if this is the Foveal focus or highly relevant
(when (and content (or is-foveal is-semantically-relevant))
(setf output (concatenate 'string output content (string #\Newline))))
;; Recursively render children
(dolist (child-id children)
(let ((child-obj (lookup-object child-id)))
(when child-obj
;; If the current node is Foveal, its children should be rendered (depth effectively resets)
(let ((next-foveal (if is-foveal child-id foveal-id)))
(setf output (concatenate 'string output
(context-render-to-org child-obj
:depth (1+ depth)
:foveal-id next-foveal
:semantic-threshold semantic-threshold
:foveal-vector foveal-vector))))))))
output))
(defun context-assemble-global-awareness (&optional signal)
"Produces a high-level skeletal outline of the current Memory for the LLM."
(let* ((payload (when signal (getf signal :payload)))
(foveal-id (when payload (getf payload :target-id)))
(foveal-vector (when foveal-id (org-object-vector (lookup-object foveal-id))))
(projects (context-get-active-projects))
(output "GLOBAL MEMEX AWARENESS (Peripheral Vision):
)
(if projects
(dolist (project projects)
(setf output (concatenate 'string output
(context-render-to-org project
:foveal-id foveal-id
:foveal-vector foveal-vector))))
(setf output (concatenate 'string output "No active projects found.~%))
output))
(defun peripheral-vision-summarize (obj-id)
"Generates a low-resolution summary of an object."
(let ((obj (lookup-object obj-id)))
(if obj
(format nil "Node: ~a (~a)" (getf (org-object-attributes obj) :TITLE) obj-id)
"[Unknown Node]")))
#+end_src
* Registration
** Skill Registration
#+begin_src lisp
(defskill :skill-peripheral-vision
:priority 90
:dependencies ("org-skill-embedding
:trigger (lambda (ctx) (member (getf (getf ctx :payload) :sensor) '(:perceive :context-refresh)))
:probabilistic nil
:deterministic (lambda (action ctx)
(declare (ignore action ctx))
;; This skill primarily provides the context-assemble-global-awareness function
;; used by the probabilistic-gate, rather than handling specific actions.
nil))
:priority 100
:trigger (lambda (ctx) (declare (ignore ctx)) nil))
#+end_src

592
skills/org-skill-policy.org
View File

@@ -1,594 +1,38 @@
#+PROPERTY: header-args:lisp :tangle (concat (identity (getenv "INSTALL_DIR")) "/skills/org-skill-policy.lisp")" )
:PROPERTIES:
:ID: 47425a43-2be0-423c-8509-22592cfe9c9e
:CREATED: [2026-04-07 Tue 12:57]
:EDITED: [2026-04-22 Wed 16:00]
:END:
#+TITLE: SKILL: System Policy
#+STARTUP: content
#+FILETAGS: :platform:policy:alignment:autonomy:
#+TITLE: SKILL: Policy (org-skill-policy.org)
#+AUTHOR: Agent
#+FILETAGS: :system:policy:constitutional:
#+PROPERTY: header-args:lisp :tangle org-skill-policy.lisp
* Overview
The *Policy Skill* is the constitutional layer of OpenCortex. It enforces foundational invariants like transparency and autonomy on all proposed actions.
The *Policy Skill* is the constitutional law of OpenCortex. It defines the non-negotiable constraints that every agentic action must satisfy before reaching the actuator layer.
Unlike a passive manifesto, Policy is *enforced* by the Deterministic Engine. The LLM proposes; Policy verifies. If an action violates an invariant, Policy blocks it and returns an auditable explanation.
** Why a Constitutional Approach?**
AIs fail in two ways:
1. *Underconstraint* - They do harmful things because no one told them not to
2. *Overconstraint* - They refuse to act because every action triggers a warning
OpenCortex solves this with a *hierarchy of invariants*:
- Some invariants block absolutely (Transparency, Modularity)
- Others warn but don't block (Autonomy debt, Sustainability debt)
This allows the agent to be both *safe* and *usable*.
** The Philosophical Foundation
OpenCortex is not just software—it's a *personal operating system* designed for the 100-year horizon. The Memex must outlive:
- Cloud services that get discontinued
- Programming languages that fall out of fashion
- Hardware platforms that become obsolete
Therefore, Policy encodes not just rules, but *values*:
- Radical Transparency → Auditability is non-negotiable
- Autonomy → Dependency on proprietary systems is debt, not strength
- Zero-Bloat → Complexity is cost, not feature
- Modularity → The kernel must survive even if all skills fail
- Mentorship → Teaching is the highest form of assistance
- Sustainability → Offline capability is a feature, not a limitation
* Package Context
Every skill executes within its own jailed package namespace, inheriting core harness symbols while maintaining isolation from other skills.
* Implementation
** Package Context
#+begin_src lisp
(in-package :opencortex)
#+end_src
* Global Policy Configuration
#+begin_src lisp :tangle (concat (identity (getenv "INSTALL_DIR")) "/skills/org-skill-policy.lisp")" )
(defvar *policy-invariant-priorities*
'((:transparency . 500)
(:autonomy . 400)
(:bloat . 300)
(:modularity . 250)
(:mentorship . 200)
(:sustainability . 100))
"Priority alist for policy invariant conflict resolution.
Higher numbers take precedence.
When two invariants conflict, the higher priority wins.
Example: Modularity (250) takes precedence over Mentorship (200),
meaning a change that would fatten the harness is blocked
even if it would be educational.
(defvar *proprietary-domain-watchlist*
'("googleapis.com" "api.openai.com" "anthropic.com" "api.groq.com" "openrouter.ai
"Domains representing centralized, proprietary control.
Actions targeting these are logged as autonomy debt, not hard-blocked.
This is because tactical gateway usage (Telegram, Signal, OpenRouter)
is permitted under the strategic mandate for autonomy.
Strategic goal: Replace all proprietary APIs with local alternatives.
Tactical reality: Use what's available while building toward that goal.
(defvar *policy-max-skill-size-chars* 50000
"Maximum recommended size for a skill file tangled from an Org note.
This is a soft limit—the check warns but does not block.
A large, well-documented skill is acceptable; a small, poorly-documented
one that adds unnecessary complexity is not.
(defvar *modularity-protected-paths*
'("harness/" "opencortex.asd
"Paths that constitute the unbreakable core of the system.
Any action targeting these paths must include a :modularity-justification
explaining why the change cannot be implemented as a skill.
The Thin Harness principle: What belongs in the harness?
- Core signal processing (Perceive-Reason-Act loop)
- Memory and persistence primitives
- Protocol definition and validation
- Skills register and dispatch
What belongs in skills?
- Policy and security
- LLM integration
- Domain-specific functionality
- New actuators
(defvar *mentorship-required-actions*
'(:create-skill :eval :modify-file :write-file :replace
:rename-file :delete-file :shell :create-note)
"Actions that trigger the Mentorship invariant.
These are high-impact actions that should come with explanations
not just for the user, but for future debugging and maintenance.
(defvar *cloud-only-backends* '(:openrouter :openai :anthropic :groq :gemini-api)
"Backends requiring internet connection and external infrastructure.
These are acceptable as fallbacks when local inference is unavailable,
but should be logged as sustainability debt for tracking purposes.
#+end_src
* The Override Hierarchy
When two invariants conflict, resolution follows a strict priority order. This prevents the agent from freezing on ethical edge cases.
| Priority | Invariant | Philosophy |
|----------|-----------|------------|
| 500 | Transparency | If you can't explain it, you can't do it |
| 400 | Autonomy | Independence from proprietary control is the primary goal |
| 300 | Zero-Bloat | Complexity must be earned, not imported |
| 250 | Modularity | Complexity belongs at the edges, not the core |
| 200 | Mentorship | Teaching increases capability; doing removes it |
| 100 | Sustainability | Offline capability today enables 100-year survival |
** Policy Logic (policy-check)
#+begin_src lisp
#+end_src
* The Core Invariants
** 1. Radical Transparency
*The maxim: "If you can't explain it, you can't do it."*
The agent's Thought Stream must be fully auditable. Hidden reasoning or obfuscated logic violates the system's core purpose: a transparent, comprehensible AI assistant.
At the gate:
- Every action must be a valid, inspectable data structure
- Every user-facing action must carry an `:explanation`
- Log messages must include the triggering invariant
#+begin_src lisp
(defun policy-check-transparency (action context)
(defun policy-check-transparency (action context)
"Ensures the action is inspectable and user-facing actions carry an explanation.
TRANSPARENCY CHECK:
1. Action must be a valid plist (not opaque data)
2. User-facing actions (:cli, :tui, :emacs) must include :explanation
3. Heartbeat and handshake messages are exempt (they're system status)
Returns the action if clean, or a blocking LOG event if violated."
(defun policy-check (action context)
"Enforces constitutional invariants on proposed actions."
(declare (ignore context))
;; Check 1: Action must be a valid plist
(unless (listp action)
(return-from policy-check-transparency
(list :type :LOG
:payload (list :level :error
:text "POLICY [Transparency]: Action is not a valid plist. Rejected.)))
(let* ((payload (getf action :payload))
(target (or (getf action :target) (getf action :TARGET)))
(explanation (or (getf payload :explanation)
(getf payload :EXPLANATION)
(getf payload :rationale)
(getf payload :RATIONALE))))
;; Check 2: User-facing actions require explanation
(when (and (member target '(:cli :tui :emacs :EMACS :CLI :TUI))
(not explanation)
(not (member (getf payload :action)
'(:handshake :heartbeat :status-update))))
(return-from policy-check-transparency
(list :type :LOG
:payload (list :level :error
:text "POLICY [Transparency]: User-facing action missing :explanation. Blocked.)))
action))
#+end_src
** 2. Autonomy Above All
*The maxim: "Every dependency is debt."*
Every action should increase the user's independence from centralized, proprietary platforms. When the system uses a proprietary API, it's logged as "autonomy debt"—acceptable tactically, but flagged for eventual replacement.
#+begin_src lisp
(defun policy-scan-proprietary-references (action)
"Scans ACTION text fields for proprietary domain references.
Searches in:
- :text and :TEXT in payload
- :cmd and :CMD in payload
- :cmd in args (for shell tool calls)
Returns the first matched domain, or NIL if clean."
(let* ((payload (getf action :payload))
(text (or (getf payload :text) (getf payload :TEXT)
(cmd (or (getf payload :cmd)
(getf payload :CMD)
(when (equal (getf payload :tool) "shell
(getf (getf payload :args) :cmd))
(haystack (concatenate 'string text cmd)))
(dolist (domain *proprietary-domain-watchlist* nil)
(when (search domain haystack)
(return domain)))))
(defun policy-check-autonomy (action context)
"Flags actions that reference proprietary domains.
Does NOT block the action—this is a warning, not a veto.
The agent can use proprietary services tactically, but must
be aware that each usage is a step away from full autonomy.
Returns a warning LOG if proprietary reference detected,
or the original action if clean."
(declare (ignore context))
(let ((domain (policy-scan-proprietary-references action)))
(if domain
(let* ((payload (proto-get action :payload))
(explanation (proto-get payload :explanation)))
(if (and explanation (stringp explanation) (> (length explanation) 10))
action
(progn
(harness-log "POLICY [Autonomy]: Detected proprietary reference '~a'. Flagged for replacement." domain)
;; Return a warning log but DO NOT block the action
(harness-log "POLICY VIOLATION: Action lacks sufficient explanation.")
(list :type :LOG
:payload (list :level :warn
:text (format nil "Autonomy Debt: Action references proprietary domain '~a'. Consider a local alternative." domain)
:original-action action)))
action)))
:text "Action blocked: Missing or insufficient :explanation. Please justify your reasoning."))))))
#+end_src
** 3. Zero-Bloat Mandate
*The maxim: "Complexity is cost, not feature."*
The system harness must remain minimalist. "Just-in-case" code is a security vulnerability. Complexity must be earned through demonstrated need, not anticipation of future use.
#+begin_src lisp
(defun policy-check-bloat (action context)
"Warns if a :create-skill action exceeds the bloat threshold.
Size alone is not proof of complexity—a 50KB skill that's well-designed
is better than a 5KB skill that's spaghetti. This check flags for review,
not automatic rejection.
Returns a warning LOG if threshold exceeded, or original action if clean."
(declare (ignore context))
(let* ((payload (getf action :payload))
(act (getf payload :action))
(content (getf payload :content)))
(when (and (eq act :create-skill)
(stringp content)
(> (length content) *policy-max-skill-size-chars*))
(harness-log "POLICY [Bloat]: Proposed skill is ~a chars. Exceeds ~a char threshold."
(length content) *policy-max-skill-size-chars*)
(return-from policy-check-bloat
(list :type :LOG
:payload (list :level :warn
:text (format nil "Bloat Warning: Proposed skill (~a chars) exceeds ~a char threshold. Review for earned complexity."
(length content) *policy-max-skill-size-chars*)
:original-action action))))
action))
#+end_src
** 4. Modularity
*The maxim: "The kernel must survive even if all skills fail."*
Every system should be decomposed into a minimal, unbreakable core and hot-swappable capabilities. Complexity must live at the edges, never in the kernel.
This is the most important invariant for system stability. If the harness grows fat, it becomes:
- Harder to verify for security
- Harder to debug when things go wrong
- Harder to maintain across versions
#+begin_src lisp
(defun policy-check-modularity (action context)
"Blocks modifications to the system's protected core unless justified.
MODULARITY CHECK:
1. If the action targets a protected path
2. And no :modularity-justification is provided
3. Then block with an explanation
The justification should explain WHY the change cannot be a skill.
Common valid reasons:
- The change fixes a bug in the harness itself
- The change adds a primitive that skills cannot implement
- The change is required for security hardening
Invalid reasons:
- 'It's easier to modify the harness'
- 'Skills are too slow'
- 'I want to keep it all in one place'"
(declare (ignore context))
(let* ((payload (getf action :payload))
(target-file (or (getf payload :file)
(getf payload :filename)))
(justification (or (getf payload :modularity-justification)
(getf payload :MODULARITY-JUSTIFICATION))))
(when (and target-file
(some (lambda (path) (search path target-file))
*modularity-protected-paths*)
(not justification))
(return-from policy-check-modularity
(list :type :LOG
:payload (list :level :error
:text "POLICY [Modularity]: Modification to protected core path blocked. Provide :modularity-justification explaining why this cannot be a skill."
:blocked-path target-file))))
action))
#+end_src
** 5. Technical Mastery & Mentorship
*The maxim: "Teaching is the highest form of assistance."*
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.
#+begin_src lisp
(defun policy-check-mentorship (action context)
"Blocks high-impact actions that lack a mentorship note.
MENTORSHIP CHECK:
1. If the action is in *mentorship-required-actions*
2. Or if the action calls shell/eval/repair-file tools
3. Then require :mentorship-note explaining what and why
The mentorship note should be:
- Concise (1-2 sentences)
- Educational (explain the principle, not just the action)
- Actionable (help the user understand the outcome)"
(declare (ignore context))
(let* ((payload (getf action :payload))
(act (or (getf payload :action)
(getf action :action)))
(note (or (getf payload :mentorship-note)
(getf payload :MENTORSHIP-NOTE)))
(target (or (getf action :target)
(getf action :TARGET)))
(tool (when (eq target :tool)
(getf payload :tool))))
(when (or (member act *mentorship-required-actions*)
(member tool '("shell" "eval" "repair-file))
(unless note
(return-from policy-check-mentorship
(list :type :LOG
:payload (list :level :error
:text "POLICY [Mentorship]: High-impact action missing :mentorship-note. Explain what you are doing and why. Blocked.))))
action))
#+end_src
** 6. Long-Term Sustainability
*The maxim: "Build for the 100-year horizon."*
The Memex should be functional even when:
- Internet is unavailable
- Cloud services are discontinued
- Hardware platforms change
This means preferring local, energy-efficient architectures over cloud-dependent ones.
#+begin_src lisp
(defun policy-check-sustainability (action context)
"Logs sustainability debt when action relies on cloud-only infrastructure.
Does NOT block—this is informational, not prohibitive.
Cloud usage is acceptable tactically (when local models fail),
but every cloud usage should be a conscious decision, not a default."
(let* ((payload (getf context :payload))
(backend (getf payload :backend))
(provider (getf payload :provider)))
(when (or (member backend *cloud-only-backends*)
(member provider *cloud-only-backends*))
(harness-log "POLICY [Sustainability]: Cloud provider '~a' used. Logged as sustainability debt."
(or backend provider))
(return-from policy-check-sustainability
(list :type :LOG
:payload (list :level :warn
:text (format nil "Sustainability Debt: Reliance on cloud provider '~a'. Consider Ollama or local inference."
(or backend provider))))))
action)))
#+end_src
* Policy Explanation Engine
When the policy gate blocks or modifies an action, it must tell the user *why*. This creates an auditable log of every policy decision.
#+begin_src lisp
(defun policy-explain (invariant-key message &optional original-action)
"Formats a policy decision into an auditable explanation plist.
INVARIANT-KEY is one of:
:transparency, :autonomy, :bloat, :modularity, :mentorship, :sustainability
MESSAGE is a human-readable string explaining the decision.
ORIGINAL-ACTION is the action that was blocked or modified.
Returns a REQUEST plist addressed to the original source,
containing the explanation and original action for transparency."
(list :type :REQUEST
:target (or (ignore-errors
(getf (getf original-action :meta) :source))
:cli)
:payload (list :action :message
:text (format nil "[POLICY ~a] ~a" invariant-key message)
:explanation (format nil "Invariant: ~a | Rationale: ~a"
invariant-key message)
:original-action original-action)))
#+end_src
* The Policy Gate
** Running Invariant Checks
#+begin_src lisp
(defun policy-run-invariant-checks (action context)
"Runs all invariant checks in priority order.
Priority order (from *policy-invariant-priorities*):
1. Transparency (500) - blocks non-transparent actions
2. Autonomy (400) - warns on proprietary dependencies
3. Bloat (300) - warns on oversized skills
4. Modularity (250) - blocks unprotected core modifications
5. Mentorship (200) - blocks unexplained high-impact actions
6. Sustainability (100) - warns on cloud dependencies
Returns:
- The final action (possibly modified by checks)
- A blocking LOG event (if any check returned :error level)
- A warning wrapper (if checks returned :warn level but no blocks)"
(let ((checks '(policy-check-transparency
policy-check-autonomy
policy-check-bloat
policy-check-modularity
policy-check-mentorship
policy-check-sustainability)))
(dolist (check-fn checks action)
(let ((result (funcall check-fn action context)))
;; If the check returned a LOG/EVENT, interpret it
(when (and (listp result)
(member (getf result :type) '(:LOG :EVENT)))
(let ((level (getf (getf result :payload) :level)))
(cond
;; Hard block: error level stops processing immediately
((eq level :error)
(return-from policy-run-invariant-checks result))
;; Soft warning: log but continue with original action
(t
(harness-log "~a" (getf (getf result :payload) :text))))))))))
(defun policy-find-engineering-standards-gate ()
"Searches for the Engineering Standards gate across known jailed package names.
The standards skill may be in opencortex-contrib submodule,
so we search multiple possible package names with graceful fallback.
Returns the function symbol, or NIL if unavailable."
(dolist (pkg-name '(:opencortex.skills.org-skill-engineering-standards
:opencortex.skills.org-skill-engineering
:opencortex.skills.engineering-standards)
nil)
(let ((pkg (find-package pkg-name)))
(when pkg
(let ((sym (find-symbol "ENGINEERING-STANDARDS-GATE" pkg)))
(when (and sym (fboundp sym))
(return (symbol-function sym))))))))
#+end_src
** Main Policy Gate
#+begin_src lisp
(defun policy-deterministic-gate (action context)
"The main policy gate entry point.
This function is registered as the deterministic-fn for the policy skill.
It runs invariant checks, then delegates to engineering standards if loaded.
IMPORTANT: Never returns NIL silently. Always returns either:
- An action (possibly modified)
- A blocking LOG event with explanation
- A warning wrapper with explanation"
;; Step 1: Run invariant checks
(let ((current-action (policy-run-invariant-checks action context)))
;; Step 2: If an invariant blocked the action, stop here
(when (and (listp current-action)
(member (getf current-action :type) '(:LOG :EVENT))
(eq (getf (getf current-action :payload) :level) :error))
(return-from policy-deterministic-gate current-action))
;; Step 3: Delegate to Engineering Standards if loaded
(let ((eng-gate (policy-find-engineering-standards-gate)))
(when eng-gate
(setf current-action (funcall eng-gate current-action context))))
current-action))
#+end_src
* Skill Registration
** Skill Registration
#+begin_src lisp
(defskill :skill-policy
:priority 500
:trigger (lambda (ctx) (declare (ignore ctx)) t)
:probabilistic nil
:deterministic #'policy-deterministic-gate)
:deterministic #'policy-check)
#+end_src
* Quick Reference
** Invariant Quick Reference
| Invariant | Blocks? | Trigger |
|-----------|---------|---------|
| Transparency | Yes | Missing `:explanation` on user-facing actions |
| Autonomy | No | Action references proprietary domain |
| Bloat | No | Skill file exceeds 50KB |
| Modularity | Yes | Modification to `harness/` without justification |
| Mentorship | Yes | High-impact action without `:mentorship-note` |
| Sustainability | No | Action uses cloud-only provider |
** Required Fields by Action Type
| Action | Required Field | Purpose |
|--------|---------------|---------|
| User message | `:explanation` | Transparency |
| Core modification | `:modularity-justification` | Modularity |
| Skill creation | `:mentorship-note` | Mentorship |
| File write | `:mentorship-note` | Mentorship |
* See Also
- [[file:org-skill-engineering-standards.org][Engineering Standards]] (if loaded in opencortex-contrib)
- [[file:../harness/act.org][Act Stage]] - Where Policy and Bouncer gates are invoked
- [[file:../harness/manifest.org][Manifest]] - The Thin Harness philosophy

111
skills/org-skill-protocol-validator.org
View File

@@ -1,97 +1,34 @@
#+PROPERTY: header-args:lisp :tangle (concat (identity (getenv "INSTALL_DIR")) "/skills/org-skill-protocol-validator.lisp")" )
:PROPERTIES:
:ID: org-skill-communication-protocol-validator
:CREATED: [2026-04-12 Sun 14:35]
:END:
#+TITLE: SKILL: Communication Protocol Schema Validator (Universal Literate Note)
#+STARTUP: content
#+FILETAGS: :protocol:communication-protocol:security:validation:autonomy:
#+TITLE: SKILL: Protocol Validator (org-skill-protocol-validator.org)
#+AUTHOR: Agent
#+FILETAGS: :system:protocol:validation:
#+PROPERTY: header-args:lisp :tangle org-skill-protocol-validator.lisp
* Overview
The *Communication Protocol Schema Validator* skill provides deep structural validation for all messages entering the opencortex kernel. It ensures that every property list adheres to a strict schema, preventing malformed data from causing harness-level errors.
The *Protocol Validator* skill enforces strict schema compliance for all internal and external communication.
* Phase A: Demand (PRD)
:PROPERTIES:
:STATUS: SIGNED
:END:
* Implementation
** 1. Purpose
Enforce a formal grammar for the OpenCortex Control Protocol (communication protocol).
** 2. User Needs
- *Type Safety:* Ensure mandatory keys (e.g., `:type`, `:payload`) are present.
- *Range Validation:* Check that enum values (e.g., `:REQUEST`, `:EVENT`) are valid.
- *Structural Integrity:* Validate nested payloads based on the message type.
** 3. Success Criteria
- [ ] Block any message that does not contain a valid `:type`.
- [ ] Block `:REQUEST` messages that lack a `:target`.
- [ ] Block `:EVENT` messages that lack a `:payload` with an `:action` or `:sensor`.
* Phase B: Blueprint (PROTOCOL)
:PROPERTIES:
:STATUS: SIGNED
:END:
** 1. Architectural Intent
Decouple protocol parsing (framing/unframing) from semantic validation.
** 2. Semantic Interfaces
#+begin_src lisp
(defun validate-communication-protocol-schema (msg)
"Returns T if the message is valid, NIL (and signals error) otherwise.
#+end_src
* Phase D: Build (Implementation)
** Schema Enforcement
** Package Context
#+begin_src lisp
(in-package :opencortex)
(defun validate-communication-protocol-schema (msg)
"Strict structural validation for incoming communication protocol messages."
(unless (listp msg)
(error "Communication Protocol Schema Error: Message must be a property list (got ~s)" (type-of msg)))
(let ((type (let ((raw (proto-get msg :type))) (if (keywordp raw) (intern (string-upcase (string raw)) :keyword) raw))))
(unless (member type '(:REQUEST :EVENT :RESPONSE :LOG :STATUS :CHAT))
(progn (harness-log "REJECTED MSG: ~s" msg) (error "Communication Protocol Schema Error: Invalid message type '~a'" type)))
(case type
(:REQUEST
;; Allow missing :target if :source is present in :meta, since reason-gate
;; will infer :target from :source downstream. This preserves "equality of
;; clients" — gateways need not duplicate routing logic.
(let ((target (proto-get msg :target))
(source (proto-get (proto-get msg :meta) :source)))
(unless (or target source)
(error "Communication Protocol Schema Error: REQUEST missing mandatory :target and no :source in :meta to infer it)
(unless (proto-get msg :payload)
(error "Communication Protocol Schema Error: REQUEST missing mandatory :payload)))
(:EVENT
(let ((payload (proto-get msg :payload)))
(unless (and payload (listp payload))
(error "Communication Protocol Schema Error: EVENT missing or invalid :payload)
(unless (or (proto-get payload :action) (proto-get payload :sensor))
(error "Communication Protocol Schema Error: EVENT payload must contain :action or :sensor)))
(:RESPONSE
(unless (proto-get msg :payload)
(error "Communication Protocol Schema Error: RESPONSE missing mandatory :payload)))
t))
#+end_src
* Registration
** Validation Logic
#+begin_src lisp
(defskill :skill-communication-protocol-validator
:priority 95
:trigger (lambda (ctx) (member (getf (getf ctx :payload) :sensor) '(:protocol-received)))
:probabilistic nil
:deterministic (lambda (action ctx)
(declare (ignore ctx))
(validate-communication-protocol-schema action)
action))
(defun protocol-validate (msg)
"Enforces structural schema compliance on protocol messages."
(validate-communication-protocol-schema msg))
#+end_src
** Skill Registration
#+begin_src lisp
(defskill :skill-protocol-validator
:priority 95
:trigger (lambda (ctx) (declare (ignore ctx)) t)
:deterministic (lambda (action ctx)
(declare (ignore ctx))
(handler-case
(progn (protocol-validate action) action)
(error (c)
(list :type :LOG :payload (list :level :error :text (format nil "Protocol Violation: ~a" c)))))))
#+end_src

179
skills/org-skill-scribe.org
View File

@@ -1,180 +1,31 @@
#+PROPERTY: header-args:lisp :tangle (concat (identity (getenv "INSTALL_DIR")) "/skills/org-skill-scribe.lisp")" )
:PROPERTIES:
:ID: scribe-skill
:CREATED: [2026-04-13 Mon 18:40]
:END:
#+TITLE: SKILL: Autonomous Scribe (Knowledge Distillation)
#+STARTUP: content
#+FILETAGS: :scribe:distillation:memex:autonomy:
#+TITLE: SKILL: Scribe (org-skill-scribe.org)
#+AUTHOR: Agent
#+FILETAGS: :skill:scribe:documentation:
#+PROPERTY: header-args:lisp :tangle org-skill-scribe.lisp
* Overview
The *Autonomous Scribe* is the background architect of the Memex. It is responsible for the "Nightly Distillation": a process that scans chronological daily logs, extracts evergreen concepts, and formalizes them into atomic Zettelkasten notes.
The *Scribe Skill* manages the agent's internal documentation and logs.
* Phase A: Demand (PRD)
:PROPERTIES:
:STATUS: SIGNED
:END:
** 1. Purpose
Automate the conversion of ephemeral, time-stamped thoughts into a permanent, structured knowledge graph.
** 2. Success Criteria
- [ ] *Capture:* Identify new headlines in the `daily/` directory that haven't been distilled yet.
- [ ] *Privacy:* Strictly ignore any node tagged with `@personal`.
- [ ] *Extraction:* Use neural reasoning to extract atomic concepts from raw logs.
- [ ] *Formalization:* Create new `.org` files in the `notes/` directory with proper Org-ID and back-links to the source.
* Phase B: Blueprint (PROTOCOL)
:PROPERTIES:
:STATUS: SIGNED
:END:
** 1. Architectural Intent
The Scribe reacts to the `:heartbeat` sensor. It maintains a state file (`scribe-state.lisp`) to track the last processed timestamp. It performs a "Read-Reason-Write" loop:
1. **Read:** Scan `daily/*.org` for nodes updated after the last checkpoint.
2. **Reason:** Ask the LLM to "Extract atomic notes from this text".
3. **Write:** Commit the resulting nodes to the `notes/` directory.
** 2. Semantic Interfaces
- Trigger: `(:sensor :heartbeat)`
- Action: `(:type :REQUEST :target :system :action :create-note :title "..." :content "..." :source-id "...`
* Phase D: Build (Implementation)
* Implementation
** Package Context
#+begin_src lisp
(in-package :opencortex)
#+end_src
** State: Checkpoint Management
We track the last processed universal time to avoid redundant distillation.
** Documentation Logic
#+begin_src lisp
(defvar *scribe-last-checkpoint* 0
"The universal-time of the last successful distillation run.
(defun scribe-load-state ()
"Loads the scribe checkpoint from the state directory."
(let ((state-file (uiop:merge-pathnames* "state/scribe-checkpoint.lisp" (asdf:system-source-directory :opencortex))))
(if (uiop:file-exists-p state-file)
(setf *scribe-last-checkpoint* (read-from-string (uiop:read-file-string state-file)))
(setf *scribe-last-checkpoint* 0))))
(defun scribe-save-state ()
"Saves the current universal-time as the new checkpoint."
(let ((state-file (uiop:merge-pathnames* "state/scribe-checkpoint.lisp" (asdf:system-source-directory :opencortex))))
(ensure-directories-exist state-file)
(with-open-file (out state-file :direction :output :if-exists :supersede)
(format out "~a" (get-universal-time)))))
#+end_src
** Filtering: Privacy & Relevance
The Scribe only cares about non-personal, non-distilled headlines.
#+begin_src lisp
(defun scribe-get-distillable-nodes ()
"Returns a list of org-objects from the daily/ folder that require distillation."
(let ((results nil))
(maphash (lambda (id obj)
(declare (ignore id))
(let* ((attrs (org-object-attributes obj))
(tags (getf attrs :TAGS))
(type (org-object-type obj))
(version (org-object-version obj)))
(when (and (eq type :HEADLINE)
(> version *scribe-last-checkpoint*)
(not (member "@personal" tags :test #'string-equal)))
(push obj results))))
*memory*)
results))
#+end_src
** Probabilistic: Extraction Prompt
The LLM is tasked with identifying atomic concepts within the raw text.
#+begin_src lisp
(defun probabilistic-skill-scribe (context)
"Generates the extraction prompt for the Scribe."
(let* ((payload (getf context :payload))
(nodes (scribe-get-distillable-nodes)))
(if nodes
(let ((text-to-process
(dolist (node nodes)
(setf text-to-process (concatenate 'string text-to-process
(format nil "ID: ~a~%TITLE: ~a~%CONTENT: ~a~%---~%"
(org-object-id node)
(getf (org-object-attributes node) :TITLE)
(org-object-content node)))))
(format nil "DISTILLATION TASK:
Below are raw chronological logs from my daily journal.
Extract ATOMIC EVERGREEN NOTES from this text.
RULES:
1. One note per distinct concept.
2. Output a list of Lisp plists: ((:title \"...\" :content \"...\" :source-id \"...\ ...)
3. The content should be in Org-mode format.
4. Keep titles descriptive and snake_case.
TEXT:
~a" text-to-process))
nil)))
#+end_src
** Deterministic: Note Committal
The deterministic gate receives the list of proposed notes and writes them to the filesystem.
#+begin_src lisp
(defun scribe-commit-notes (proposals)
"Writes proposed atomic notes to the notes/ directory. Appends if the note exists."
(let ((notes-dir (uiop:merge-pathnames* "notes/" (asdf:system-source-directory :opencortex))))
(ensure-directories-exist notes-dir)
(dolist (note proposals)
(let* ((title (getf note :title))
(content (getf note :content))
(source-id (getf note :source-id))
(filename (format nil "~a.org" (string-downcase (cl-ppcre:regex-replace-all " " title "_)))
(path (merge-pathnames filename notes-dir)))
(if (uiop:file-exists-p path)
(with-open-file (out path :direction :output :if-exists :append)
(format out "~%~%* Appended insight from ~a~%~a" source-id content))
(with-open-file (out path :direction :output :if-exists :supersede)
(format out ":PROPERTIES:~%:ID: ~a~%:SOURCE_ID: ~a~%:END:~%#+TITLE: ~a~%~%~a"
(org-id-new) source-id title content)))
(harness-log "SCRIBE: Processed evergreen note ~a" filename)))))
(defun verify-skill-scribe (action context)
"Executes the note creation and marks source nodes as distilled."
(declare (ignore context))
(let ((data (cond ((and (listp action) (eq (getf action :type) :REQUEST))
(getf (getf action :payload) :payload))
((and (listp action) (not (member (getf action :type) '(:LOG :EVENT))))
action)
(t nil))))
(when data
(harness-log "SCRIBE: Committing ~a atomic notes..." (length data))
(scribe-commit-notes data)
(scribe-save-state)
(harness-log "SCRIBE: Distillation complete.
;; Return a log event to stop the loop
(list :type :LOG :payload (list :text "Distillation successful.))))
(defun scribe-log-event (signal)
"Logs a metabolic signal for later analysis."
(let ((type (getf signal :type))
(payload (getf signal :payload)))
(harness-log "SCRIBE: [~a] ~s" type payload)))
#+end_src
** Skill Registration
#+begin_src lisp
(defskill :skill-scribe
:priority 50
:trigger (lambda (ctx)
(let* ((payload (getf ctx :payload))
(sensor (getf payload :sensor)))
(and (eq sensor :heartbeat)
;; Only run once per hour to check if we need to distill
(> (- (get-universal-time) *scribe-last-checkpoint*) 3600)
(scribe-get-distillable-nodes))))
:probabilistic #'probabilistic-skill-scribe
:deterministic #'verify-skill-scribe)
#+end_src
** Initialization
#+begin_src lisp
(scribe-load-state)
:priority 100
:trigger (lambda (ctx) (member (getf ctx :type) '(:LOG :STATUS)))
:deterministic (lambda (action ctx) (declare (ignore action)) (scribe-log-event ctx) nil))
#+end_src

90
skills/org-skill-shell-actuator.org
View File

@@ -1,74 +1,38 @@
#+PROPERTY: header-args:lisp :tangle (concat (identity (getenv "INSTALL_DIR")) "/skills/org-skill-shell-actuator.lisp")" )
:PROPERTIES:
:ID: shell-actuator-skill
:CREATED: [2026-04-12 Sun]
:END:
#+TITLE: SKILL: Shell Actuator (Secure Host Interaction)
#+STARTUP: content
#+FILETAGS: :actuator:shell:system:autonomy:
#+TITLE: SKILL: Shell Actuator (org-skill-shell-actuator.org)
#+AUTHOR: Agent
#+FILETAGS: :skill:actuator:shell:
#+PROPERTY: header-args:lisp :tangle org-skill-shell-actuator.lisp
* Overview
The *Shell Actuator* provides a controlled interface for the OpenCortex to execute commands on the host operating system.
The *Shell Actuator* provides the agent with the capability to execute bash commands.
* Implementation
#+begin_src lisp :tangle (concat (identity (getenv "INSTALL_DIR")) "/skills/org-skill-shell-actuator.lisp")" )
** Package Context
#+begin_src lisp
(in-package :opencortex)
#+end_src
(defparameter *allowed-commands* '("ls" "git" "rg" "grep" "date" "echo" "cat" "node" "python3" "sbcl)
** Shell Execution (shell-execute)
#+begin_src lisp
(defun shell-execute (action context)
"Executes a bash command and returns the output."
(declare (ignore context))
(let* ((payload (getf action :payload))
(cmd (getf payload :cmd)))
(harness-log "ACT [Shell]: ~a" cmd)
(multiple-value-bind (out err code)
(uiop:run-program (list "bash" "-c" cmd) :output :string :error-output :string :ignore-error-status t)
(if (= code 0)
out
(format nil "ERROR [~a]: ~a" code err)))))
#+end_src
(defparameter *shell-metacharacters* '(#\; #\& #\| #\> #\< #\$ #\` #\\ #\!))
(defun shell-command-safe-p (cmd-string)
"Returns T if the command string contains no dangerous metacharacters."
(not (some (lambda (char) (find char cmd-string)) *shell-metacharacters*)))
(defun execute-shell-safely (action context)
(let* ((payload (getf action :PAYLOAD))
(cmd-string (getf payload :cmd))
(executable (car (uiop:split-string (string-trim " " cmd-string) :separator '(#\Space)))))
(cond
((not (shell-command-safe-p cmd-string))
(opencortex:inject-stimulus
`(:TYPE :EVENT :PAYLOAD (:SENSOR :shell-response :cmd ,cmd-string :stdout "" :stderr "ERROR - Security Violation: Dangerous metacharacters detected." :exit-code 1))
:stream (getf context :reply-stream)))
((not (member executable *allowed-commands* :test #'string=))
(opencortex:inject-stimulus
`(:TYPE :EVENT :PAYLOAD (:SENSOR :shell-response :cmd ,cmd-string :stdout "" :stderr "ERROR - Command not in security whitelist." :exit-code 1))
:stream (getf context :reply-stream)))
(t
(multiple-value-bind (stdout stderr exit-code)
(uiop:run-program cmd-string :output :string :error-output :string :ignore-error-status t)
(opencortex:inject-stimulus
`(:TYPE :EVENT :PAYLOAD (:SENSOR :shell-response :cmd ,cmd-string :stdout ,(or stdout " :stderr ,(or stderr " :exit-code ,exit-code))
:stream (getf context :reply-stream)))))))
(defun trigger-skill-shell-actuator (context)
(let ((type (getf context :TYPE))
(payload (getf context :PAYLOAD)))
(and (eq type :EVENT)
(eq (getf payload :SENSOR) :shell-response))))
(defun probabilistic-skill-shell-actuator (context)
(let* ((p (getf context :PAYLOAD))
(cmd (getf p :cmd))
(stdout (getf p :stdout))
(stderr (getf p :stderr))
(exit-code (getf p :exit-code)))
(format nil "SHELL COMMAND RESULT:
Command: ~a
Exit Code: ~a
STDOUT: ~a
STDERR: ~a" cmd exit-code stdout stderr)))
(opencortex:register-actuator :shell #'execute-shell-safely)
** Skill Registration
#+begin_src lisp
(register-actuator :shell #'shell-execute)
(defskill :skill-shell-actuator
:priority 80
:trigger #'trigger-skill-shell-actuator
:probabilistic #'probabilistic-skill-shell-actuator
:deterministic (lambda (action context) (declare (ignore context)) action))
:priority 50
:trigger (lambda (ctx) (declare (ignore ctx)) nil))
#+end_src

183
skills/org-skill-tool-permissions.org
View File

@@ -1,173 +1,34 @@
#+PROPERTY: header-args:lisp :tangle (concat (identity (getenv "INSTALL_DIR")) "/skills/org-skill-tool-permissions.lisp")" )
:PROPERTIES:
:ID: tool-permissions-skill-001
:CREATED: [2026-04-23 Thu]
:END:
#+TITLE: SKILL: Tool Permission Tiers
#+STARTUP: content
#+FILETAGS: :security:permissions:tool:
#+TITLE: SKILL: Tool Permissions (org-skill-tool-permissions.org)
#+AUTHOR: Agent
#+FILETAGS: :skill:security:permissions:
#+PROPERTY: header-args:lisp :tangle org-skill-tool-permissions.lisp
* Overview
This skill implements tool permission tiers for security - controlling which cognitive tools can execute without user interaction.
Also provides vector embeddings via Ollama or llama.cpp.
** The Three Tiers
| Tier | Behavior | Use Case |
|------|----------|----------|
| =:allow= | Executes immediately | Trusted, safe tools |
| =:deny= | Blocks before execution | Dangerous tools |
| =:ask= | Prompts user, pauses execution | Sensitive tools |
** Embedding Providers
- =EMBEDDING_PROVIDER= environment: "ollama" or "llama.cpp"
- =OLLAMA_HOST= / =LLAMA_HOST= for the API endpoint
- =EMBEDDING_MODEL= model name
The *Tool Permissions* skill manages the authorization levels for different cognitive tools.
* Implementation
Tool permissions and embedding generation via multiple providers.
** Package Context
#+begin_src lisp
(in-package :opencortex)
(defvar *tool-permissions* (make-hash-table :test 'equal)
"Hash table mapping tool names to :allow/:deny/:ask.
(defun get-tool-permission (tool-name)
(let ((key (string-downcase (string tool-name))))
(or (gethash key *tool-permissions*) :allow)))
(defun set-tool-permission (tool-name tier)
(setf (gethash (string-downcase (string tool-name)) *tool-permissions*) tier)
(harness-log "TOOL PERMISSION: Set ~a = ~a" tool-name tier))
(defun check-tool-permission-gate (tool-name context)
(declare (ignore context))
(let ((perm (get-tool-permission tool-name)))
(case perm
(:allow :allow)
(:deny :deny)
(:ask (list :ask tool-name))
(t :allow))))
(def-cognitive-tool :get-embedding
"Generates vector embeddings via Ollama or llama.cpp API."
((:text :type :string :description "Text to embed.)
:body (lambda (args)
(let* ((text (getf args :text))
(provider (or (getenv "EMBEDDING_PROVIDER "ollama)
(model (or (getenv "EMBEDDING_MODEL "nomic-embed-text)
(embedding nil))
(cond
((string= provider "ollama
(let* ((host (or (getenv "OLLAMA_HOST "localhost:11434)
(url (format nil "http://~a/api/embeddings" host))
(body (cl-json:encode-json-to-string `((model . ,model) (prompt . ,text)))))
(handler-case
(let* ((response (dex:post url :headers '(("Content-Type" . "application/json) :content body :connect-timeout 5 :read-timeout 30))
(json (cl-json:decode-json-from-string response))
(vec (cdr (assoc :embedding json))))
(when vec (setf embedding vec)))
(error (c) (harness-log "EMBEDDING: Ollama failed: ~a" c)))))
((string= provider "llama.cpp
(let* ((host (or (getenv "LLAMA_HOST "localhost:8080)
(url (format nil "http://~a/v1/embeddings" host))
(body (cl-json:encode-json-to-string `((model . ,model) (input . ,text)))))
(handler-case
(let* ((response (dex:post url :headers '(("Content-Type" . "application/json) :content body :connect-timeout 5 :read-timeout 30))
(json (cl-json:decode-json-from-string response))
(data (cdr (assoc :data json)))
(vec (when data (cdr (assoc :embedding (car data))))))
(when vec (setf embedding vec)))
(error (c) (harness-log "EMBEDDING: llama.cpp failed: ~a" c))))))
(if embedding
(list :status :success :vector embedding)
(list :status :error :message "Embedding generation failed))))
(def-cognitive-tool :tool-permissions
"View or set tool permission tiers."
((:tool :type :string :description "Tool name
(:action :type :keyword :description "Action: :get, :set, :list" :default :get)
(:tier :type :keyword :description "For :set: :allow/:deny/:ask)
:body (lambda (args)
(let ((tool (getf args :tool))
(action (getf args :action :get))
(tier (getf args :tier)))
(case action
(:get (list :status :success :tool tool :permission (get-tool-permission tool)))
(:set (progn (set-tool-permission tool tier)
(list :status :success :message (format nil "Set ~a = ~a" tool tier))))
(:list (let ((r nil))
(maphash (lambda (k v) (push (list :tool k :permission v) r)) *tool-permissions*)
(list :status :success :tools r)))
(t (list :status :error :message "Invalid action)))))
;; Defaults
(set-tool-permission :shell :deny)
(set-tool-permission :delete-file :deny)
(set-tool-permission :eval :ask)
(set-tool-permission :write-file :ask)
(harness-log "TOOL PERMISSIONS: Initialized
(defskill :skill-tool-permissions
:priority 600
;; Trigger whenever there's a tool call
:trigger (lambda (c)
(let* ((action (getf c :candidate))
(target (getf action :target)))
(or (eq target :TOOL) (eq target :tool))))
:deterministic (lambda (a c)
(let ((tool (getf (getf a :payload) :tool)))
(if tool
(let ((perm (check-tool-permission-gate tool c)))
(cond
((eq perm :deny)
(list :type :LOG :payload (list :text (format nil "Tool '~a' execution denied by permission tiers." tool))))
((and (listp perm) (eq (car perm) :ask))
(list :type :EVENT :status :suspended :reason :ask-permission :payload (list :tool tool :action a)))
(t a)))
a))))
#+end_src
* Test Suite
** Permission Registry
#+begin_src lisp
(defvar *tool-permissions* (make-hash-table :test 'equal))
These tests verify tool permissions. Run with:
~(fiveam:run! 'tool-permissions-suite)~
(defun set-tool-permission (tool-name level)
"Sets the permission level for a tool."
(setf (gethash (string-downcase (string tool-name)) *tool-permissions*) level))
#+begin_src lisp :tangle (concat (identity (getenv "INSTALL_DIR")) "/tests/tool-permissions-tests.lisp")" )
(defpackage :opencortex-tool-permissions-tests
(:use :cl :fiveam :opencortex)
(:export #:tool-permissions-suite))
(defun get-tool-permission (tool-name)
"Retrieves the permission level for a tool."
(gethash (string-downcase (string tool-name)) *tool-permissions* :ask))
#+end_src
(in-package :opencortex-tool-permissions-tests)
(def-suite tool-permissions-suite
:description "Tests for Tool Permissions skill
(in-suite tool-permissions-suite)
(test default-permission-is-allow
"Verify default permission is :allow."
(is (eq (get-tool-permission "unknown-tool :allow)))
(test set-and-get-permission
"Verify setting and getting permissions."
(set-tool-permission "test-tool-abc" :deny)
(is (eq (get-tool-permission "test-tool-abc :deny)))
(test permission-gate-allow
"Verify :allow tier passes through."
(set-tool-permission "gate-allow-tool" :allow)
(is (eq (check-tool-permission-gate "gate-allow-tool" nil) :allow)))
(test permission-gate-deny
"Verify :deny tier blocks."
(set-tool-permission "gate-deny-tool" :deny)
(is (eq (check-tool-permission-gate "gate-deny-tool" nil) :deny)))
(test permission-gate-ask
"Verify :ask tier returns ask list."
(set-tool-permission "gate-ask-tool" :ask)
(is (listp (check-tool-permission-gate "gate-ask-tool" nil))))
#+end_src
** Skill Registration
#+begin_src lisp
(defskill :skill-tool-permissions
:priority 600
:trigger (lambda (ctx) (declare (ignore ctx)) nil))
#+end_src