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

docs: Rename cognitive architecture to Associative/Deliberate and Foreground/Background

Browse Source
This commit is contained in:
Amr Gharbeia
2026-04-12 14:09:47 -04:00
parent 04df131f63
commit c46c4d4fd7
11 changed files with 459 additions and 65 deletions
Download Patch File Download Diff File Expand all files Collapse all files

10
skills/org-skill-agent.org
View File

@@ -48,7 +48,7 @@ Define the core functional and security requirements for the neurosymbolic daemo
** 2. User Needs
- *Homoiconic Memory:* Use Org-mode AST as the primary data structure for both human and machine.
- *Deterministic Reasoning:* Common Lisp (SBCL) for high-performance, threaded symbolic logic.
- *Cognitive Loop:* A strict four-stage pipeline: Perceive -> Think (System 1) -> Decide (System 2) -> Act.
- *Cognitive Loop:* A strict four-stage pipeline: Perceive -> Think (Associative) -> Decide (Deliberate) -> Act.
- *Minimalist Core:* The kernel handles only the loop, object-store, and communication; all else is a skill.
- *Security by Default:* Reader safety (*read-eval* disabled) and package-based skill jailing.
@@ -56,7 +56,7 @@ Define the core functional and security requirements for the neurosymbolic daemo
*** TODO Core Lisp microkernel stability (Heartbeat consistency)
*** TODO OACP Swank/Socket communication reliability
*** TODO Org AST-to-Lisp conversion fidelity
*** TODO System 2 Safety Gating (The Harness) enforcement
*** TODO Deliberate Safety Gating (The Harness) enforcement
* Phase B: Blueprint (PROTOCOL)
:PROPERTIES:
@@ -72,10 +72,10 @@ The kernel is transport-agnostic and business-logic-agnostic. It communicates wi
"Injects an event into the global object store.")
(defun kernel-think (context)
"Queries System 1 (LLM) for an intuitive proposal.")
"Queries Associative (LLM) for an intuitive proposal.")
(defun kernel-decide (proposal context)
"Invokes System 2 (Symbolic Skills) to verify or overrule the proposal.")
"Invokes Deliberate (Symbolic Skills) to verify or overrule the proposal.")
(defun kernel-act (action)
"Dispatches verified commands to the registered actuators.")
@@ -139,7 +139,7 @@ Follow the Core Invariants:
(let ((payload (getf action :payload)))
(if (and payload (search "proprietary" (format nil "~s" payload)))
(progn
(org-agent:kernel-log "SYSTEM 2 [Agent]: Sovereignty violation suspected. Blocking action.")
(org-agent:kernel-log "DELIBERATE [Agent]: Sovereignty violation suspected. Blocking action.")
nil)
action))))
#+end_src

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

@@ -26,30 +26,55 @@ Verify the system's stability and error-handling capabilities under stress.
- *Recovery Verification:* Ensure the kernel can recover from a "skip-event" restart.
* Phase D: Build (Implementation)
:PROPERTIES:
:STATUS: SIGNED
:END:
** Chaos Injection Logic
#+begin_src lisp :tangle ../src/chaos-logic.lisp
(in-package :org-agent)
(defun chaos-inject-error (sensor-type)
"Injects a synthetic error into a specific sensor pipeline."
(org-agent:kernel-log "CHAOS - Injecting synthetic error into ~a sensor..." sensor-type)
(org-agent:inject-stimulus
(unless *chaos-enabled-p*
(kernel-log "CHAOS ERROR - Injection blocked. Production gate is ACTIVE.")
(return-from chaos-inject-error nil))
(kernel-log "CHAOS - Injecting synthetic error into ~a sensor..." sensor-type)
(inject-stimulus
`(:type :EVENT :payload (:sensor ,sensor-type :error "SYNTHETIC_CHAOS_ERROR"))))
(defun chaos-stress-test (action context)
"Executes a randomized stress test by injecting failures into the system."
(declare (ignore context))
(unless *chaos-enabled-p*
(kernel-log "CHAOS ERROR - Stress test blocked. Production gate is ACTIVE.")
(return-from chaos-stress-test "FAILURE - Production gate active."))
(let* ((payload (getf action :payload))
(mode (or (getf payload :mode) :random))
(intensity (or (getf payload :intensity) 3)))
(org-agent:kernel-log "CHAOS - Commencing stress test (Mode: ~a, Intensity: ~a)" mode intensity)
(kernel-log "CHAOS - Commencing stress test (Mode: ~a, Intensity: ~a)" mode intensity)
(snapshot-object-store)
(case mode
(:random (dotimes (i intensity)
(let ((failure-type (nth (random 3) '(:test-failure :shell-timeout :llm-error))))
(org-agent:inject-stimulus
(inject-stimulus
`(:type :EVENT :payload (:sensor :chaos-injection :type ,failure-type))))))
(:shell (org-agent:inject-stimulus
(:shell (inject-stimulus
`(:type :EVENT :payload (:sensor :shell-response :cmd "git push" :exit-code 128 :stderr "fatal: network unreachable")))))
(snapshot-object-store)
(format nil "SUCCESS - Chaos stress test initiated.")))
(defun chaos-enable ()
"Disables the production gate and allows chaos injection."
(setf *chaos-enabled-p* t)
(kernel-log "CHAOS - Production gate DISABLED. Chaos injection is now ALLOWED.")
t)
(defun chaos-disable ()
"Enables the production gate and blocks chaos injection."
(setf *chaos-enabled-p* nil)
(kernel-log "CHAOS - Production gate ENABLED. Chaos injection is now BLOCKED.")
t)
#+end_src
@@ -58,23 +83,26 @@ Verify the system's stability and error-handling capabilities under stress.
:STATUS: SIGNED
:END:
* Phase B: Blueprint (PROTOCOL)
:PROPERTIES:
:STATUS: IN_PROGRESS
:END:
** 1. Architectural Intent
The *Chaos Gauntlet* skill is designed to be non-invasive, running primarily in a background mode. It should not interfere with normal system operation unless explicitly triggered. It is protected by a **Production Gate** (`*chaos-enabled-p*`) to prevent accidental disruptions during real work.
** 1. Architectural Intent
The *Chaos Gauntlet* skill is designed to be non-invasive, running primarily in a background mode. It should not interfere with normal system operation unless explicitly triggered. The skill aims to provide a controlled environment for inducing and observing failures. Key intents:
- *Controlled Chaos:* Failures must be injected in a precise and controllable manner.
- *Merkle Integrity:* Every stress test triggers a Merkle snapshot before and after to allow for full-system rollback.
- *Observability:* The system's response to failures must be easily observable through logging.
- *Controlled Chaos:* Failures must be injected in a precise and controllable manner (specific sensor, specific error type).
- *Observability:* The system's response to failures must be easily observable through logging and system state.
- *Minimal Impact:* The skill should avoid causing permanent damage or corruption to the system or its data.
- *Testability*: Easy to run, configure, and verify success/failure. Reports failures through the regular error reporting mechanisms. Logs activity with 'CHAOS' tag.
- *Recoverability*: Emphasis on testing kernel's recovery from errors, by deliberately triggering skip-event type restarts.
** 2. Semantic Interfaces
** 2. Semantic Interfaces
*** A. Gate Control
*** A. Triggering Chaos
#+begin_src lisp
(defun chaos-enable ()
"Disables the production gate and allows chaos injection.")
(defun chaos-disable ()
"Enables the production gate and blocks chaos injection.")
#+end_src
*** B. Triggering Chaos
*`chaos-trigger` Sensor:*
Events of type `:EVENT` with a `:payload` containing `(:sensor :chaos-trigger)` trigger the skill. The payload can contain a `:mode` key to specify the type of chaos to inject (e.g., `:random`, `:shell`), and an `:intensity` to control the number of failures injected.

28
skills/org-skill-chat.org
View File

@@ -50,10 +50,29 @@ Interfaces for conversational event handling and UI integration. Source of truth
** Event Perception
#+begin_src lisp :tangle ../src/chat-logic.lisp
(in-package :org-agent)
(defun chat-archive-message (text &key (role :user) channel chat-id)
"Archives a chat message into the persistent Object Store and triggers a snapshot."
(let* ((msg-id (org-id-new))
(obj (make-org-object
:id msg-id
:type :CHAT-MESSAGE
:attributes `(:role ,role :channel ,channel :chat-id ,chat-id :timestamp ,(get-universal-time))
:content text
:version (get-universal-time))))
(setf (gethash msg-id *object-store*) obj)
(kernel-log "CHAT - Message archived: ~a (~a)" msg-id role)
(snapshot-object-store)
msg-id))
(defun trigger-skill-chat (context)
(let* ((payload (getf context :payload))
(sensor (getf payload :sensor)))
(eq sensor :chat-message)))
(when (eq sensor :chat-message)
;; Archive inbound message
(chat-archive-message (getf payload :text) :role :user :channel (getf payload :channel) :chat-id (getf payload :chat-id))
t)))
#+end_src
** Symbolic Verification
@@ -76,7 +95,12 @@ Interfaces for conversational event handling and UI integration. Source of truth
(or (getf payload :cmd) (getf proposed-action :cmd)))
(member target '(:tool :TOOL))))
(member (getf proposed-action :type) '(:response :RESPONSE :log :LOG))))
proposed-action
(progn
;; Archive outbound response
(when (and (member (getf proposed-action :type) '(:request :REQUEST))
(not (eq target :tool)))
(chat-archive-message (getf payload :text) :role :agent :channel target :chat-id (or (getf payload :chat-id) (getf payload :room-id))))
proposed-action)
(let ((err-text (format nil "\n\n*System Error:* Chat agent returned invalid action: ~s" proposed-action)))
`(:type :request :target :emacs :payload (:action :insert-at-end :buffer "*org-agent-chat*" :text ,err-text))))))
#+end_src

118
skills/org-skill-embedding.org Normal file
View File

@@ -0,0 +1,118 @@
:PROPERTIES:
:ID: org-skill-embedding
:CREATED: [2026-04-12 Sun 14:00]
:END:
#+TITLE: SKILL: Vector Embedding (Universal Literate Note)
#+STARTUP: content
#+FILETAGS: :embedding:vector-search:semantic:psf:
* Overview
The *Vector Embedding* skill provides semantic search and vectorization capabilities to the org-agent. It decouples the specific embedding algorithms and provider-specific API calls from the core kernel.
* Phase A: Demand (PRD)
:PROPERTIES:
:STATUS: SIGNED
:END:
** 1. Purpose
Provide a standardized interface for converting text into vector representations and performing similarity searches.
** 2. User Needs
- *Text Vectorization:* Convert Org-mode content into high-dimensional vectors.
- *Similarity Search:* Find semantically related nodes in the Object Store.
- *Provider Agnosticism:* Support multiple embedding models (Gemini, OpenAI, etc.).
** 3. Success Criteria
- [ ] Successfully retrieve embeddings from a configured provider.
- [ ] Perform cosine similarity calculations between vectors.
- [ ] Register as a hot-reloadable skill.
* Phase B: Blueprint (PROTOCOL)
:PROPERTIES:
:STATUS: SIGNED
:END:
** 1. Architectural Intent
Move heavy neural and mathematical logic out of `core.lisp` and `neuro.lisp` into a dedicated skill.
** 2. Semantic Interfaces
#+begin_src lisp
(defun get-embedding (text)
"Retrieves a vector representation of text via the configured neural provider.")
(defun cosine-similarity (v1 v2)
"Calculates the semantic distance between two vectors.")
(defun find-most-similar (query-vector top-k)
"Identifies the top-k most semantically related objects in the store.")
#+end_src
* Phase D: Build (Implementation)
** Vector Operations
#+begin_src lisp :tangle ../src/embedding-logic.lisp
(in-package :org-agent)
(defun get-embedding (text)
"Retrieves a vector representation of text via the configured neural provider."
(let* ((auth (get-provider-auth :gemini))
(api-key (getf auth :api-key))
(endpoint "https://generativelanguage.googleapis.com/v1beta/models/text-embedding-004:embedContent"))
(unless api-key
(kernel-log "EMBEDDING ERROR: No API key for :gemini")
(return-from get-embedding nil))
(let* ((url (format nil "~a?key=~a" endpoint api-key))
(headers `(("Content-Type" . "application/json")))
(body (cl-json:encode-json-to-string
`((model . "models/text-embedding-004")
(content . ((parts . ((text . ,text)))))))))
(handler-case
(let* ((response (dex:post url :headers headers :content body))
(json (cl-json:decode-json-from-string response))
(embedding (getf (getf json :embedding) :values)))
embedding)
(error (c)
(kernel-log "EMBEDDING FAILURE: ~a" c)
nil)))))
(defun dot-product (v1 v2)
"Calculates the dot product of two numerical vectors."
(reduce #'+ (mapcar #'* v1 v2)))
(defun magnitude (v)
"Calculates the Euclidean magnitude of a numerical vector."
(sqrt (reduce #'+ (mapcar (lambda (x) (* x x)) v))))
(defun cosine-similarity (v1 v2)
"Calculates the semantic distance between two vectors."
(let ((m1 (magnitude v1))
(m2 (magnitude v2)))
(if (or (zerop m1) (zerop m2)) 0 (/ (dot-product v1 v2) (* m1 m2)))))
(defun find-most-similar (query-vector top-k)
"Identifies the top-k most semantically related objects in the store."
(let ((similarities nil))
(maphash (lambda (id obj)
(declare (ignore id))
(let ((vec (org-object-vector obj)))
(when vec
(push (cons (cosine-similarity query-vector vec) obj) similarities))))
*object-store*)
(let ((sorted (sort similarities #'> :key #'car)))
(subseq sorted 0 (min top-k (length sorted))))))
#+end_src
* Registration
#+begin_src lisp :tangle ../src/embedding-logic.lisp
(defskill :skill-embedding
:priority 50
:trigger (lambda (ctx) (eq (getf (getf ctx :payload) :sensor) :embedding-request))
:neuro nil
:symbolic (lambda (action ctx)
(declare (ignore ctx))
(case (getf action :action)
(:get-embedding (get-embedding (getf action :text)))
(:similarity (cosine-similarity (getf action :v1) (getf action :v2)))
(t action))))
#+end_src

91
skills/org-skill-oacp-validator.org Normal file
View File

@@ -0,0 +1,91 @@
:PROPERTIES:
:ID: org-skill-oacp-validator
:CREATED: [2026-04-12 Sun 14:35]
:END:
#+TITLE: SKILL: OACP Schema Validator (Universal Literate Note)
#+STARTUP: content
#+FILETAGS: :protocol:oacp:security:validation:psf:
* Overview
The *OACP Schema Validator* skill provides deep structural validation for all messages entering the org-agent kernel. It ensures that every property list adheres to a strict schema, preventing malformed data from causing kernel-level errors.
* Phase A: Demand (PRD)
:PROPERTIES:
:STATUS: SIGNED
:END:
** 1. Purpose
Enforce a formal grammar for the Org-Agent Control Protocol (OACP).
** 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-oacp-schema (msg)
"Returns T if the message is valid, NIL (and signals error) otherwise.")
#+end_src
* Phase D: Build (Implementation)
** Schema Enforcement
#+begin_src lisp :tangle ../src/protocol-validator.lisp
(in-package :org-agent)
(defun validate-oacp-schema (msg)
"Strict structural validation for incoming OACP messages."
(unless (listp msg)
(error "OACP Schema Error: Message must be a property list (got ~s)" (type-of msg)))
(let ((type (getf msg :type)))
(unless (member type '(:REQUEST :EVENT :RESPONSE :LOG))
(error "OACP Schema Error: Invalid message type '~a'" type))
(case type
(:REQUEST
(unless (getf msg :target)
(error "OACP Schema Error: REQUEST missing mandatory :target"))
(unless (getf msg :payload)
(error "OACP Schema Error: REQUEST missing mandatory :payload")))
(:EVENT
(let ((payload (getf msg :payload)))
(unless (and payload (listp payload))
(error "OACP Schema Error: EVENT missing or invalid :payload"))
(unless (or (getf payload :action) (getf payload :sensor))
(error "OACP Schema Error: EVENT payload must contain :action or :sensor"))))
(:RESPONSE
(unless (getf msg :payload)
(error "OACP Schema Error: RESPONSE missing mandatory :payload"))))
t))
#+end_src
* Registration
#+begin_src lisp :tangle ../src/protocol-validator.lisp
(defskill :skill-oacp-validator
:priority 95
:trigger (lambda (ctx) (member (getf (getf ctx :payload) :sensor) '(:protocol-received)))
:neuro nil
:symbolic (lambda (action ctx)
(declare (ignore ctx))
(validate-oacp-schema action)
action))
#+end_src

127
skills/org-skill-peripheral-vision.org Normal file
View File

@@ -0,0 +1,127 @@
: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:psf:
* 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 Object Store, preventing context window overflow.
* Phase A: Demand (PRD)
:PROPERTIES:
:STATUS: SIGNED
:END:
** 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 neuro-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
#+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
#+begin_src lisp :tangle ../src/context-logic.lisp
(in-package :org-agent)
(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 Object Store 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))
#+end_src
* Registration
#+begin_src lisp :tangle ../src/context-logic.lisp
(defskill :skill-peripheral-vision
:priority 90
:dependencies ("org-skill-embedding")
:trigger (lambda (ctx) (member (getf (getf ctx :payload) :sensor) '(:perceive :context-refresh)))
:neuro nil
:symbolic (lambda (action ctx)
(declare (ignore action ctx))
;; This skill primarily provides the context-assemble-global-awareness function
;; used by the neuro-gate, rather than handling specific actions.
nil))
#+end_src