amr/org-agent-contrib
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: Add initial skills to contrib

Browse Source
This commit is contained in:
Amr Gharbeia
2026-04-16 12:00:23 -04:00
parent c5d3d8c5fa
commit a04d8415f3
22 changed files with 2600 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

147
skills/org-skill-chat.org Normal file
View File

@@ -0,0 +1,147 @@
:PROPERTIES:
:ID: 4829cb25-efcb-4e0f-9285-7a045213d8b9
:CREATED: [2026-03-30 Mon 21:16]
:EDITED: [2026-04-07 Tue 13:42]
:END:
#+TITLE: SKILL: Chat Agent (Universal Literate Note)
#+STARTUP: content
#+FILETAGS: :chat:conversational:ui:autonomy:
* Overview
The *Chat Agent* provides a dedicated conversational interface within Emacs (`*opencortex-chat*`). It enables fluid dialogue while maintaining strict persona alignment and contextual awareness.
* Phase A: Demand (PRD)
:PROPERTIES:
:STATUS: FROZEN
:END:
** 1. Purpose
Define the interfaces for direct human-to-agent conversational interaction.
** 2. User Needs
- *Direct Interaction:* Specialized handler for `:chat-message` events.
- *Persona Alignment:* Consistency with the Identity Agent's definitions.
- *Contextual Awareness:* Reference to chat history for dialogue continuity.
- *Structural Output:* Responses formatted as valid Org-mode subtrees.
** 3. Success Criteria
*** TODO Chat Event Triggering
*** TODO Persona-Driven Response Generation
*** TODO Emacs Buffer Insertion Verification
* Phase B: Blueprint (PROTOCOL)
:PROPERTIES:
:STATUS: SIGNED
:END:
** 1. Architectural Intent
Interfaces for conversational event handling and UI integration. Source of truth is the dynamic chat buffer and the Identity skill.
** 2. Semantic Interfaces
#+begin_src lisp
(defun trigger-skill-chat (context)
"Triggers on :sensor :chat-message.")
(defun verify-skill-chat (proposed-action context)
"Ensures response is targeted to the correct Emacs buffer.")
#+end_src
* Phase D: Build (Implementation)
** Event Perception
#+begin_src lisp
(defun chat-archive-message (text &key (role :user) channel chat-id)
"Archives a chat message into the persistent Memory 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 *memory*) obj)
(harness-log "CHAT - Message archived: ~a (~a)" msg-id role)
(snapshot-memory)
msg-id))
(defun trigger-skill-chat (context)
(let* ((payload (getf context :payload))
(sensor (getf payload :sensor)))
(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
** Deterministic Verification
#+begin_src lisp
(defun verify-skill-chat (proposed-action context)
(let* ((payload (getf proposed-action :payload))
(action (or (getf payload :action) (getf proposed-action :action)))
(target (getf proposed-action :target)))
(if (and (listp proposed-action)
(or (and (member (getf proposed-action :type) '(:request :REQUEST))
(or (and (member target '(:emacs :EMACS))
(member action '(:insert-at-end :INSERT-AT-END)))
(and (member target '(:telegram :TELEGRAM))
(or (getf payload :chat-id) (getf proposed-action :chat-id)))
(and (member target '(:signal :SIGNAL))
(or (getf payload :chat-id) (getf proposed-action :chat-id)))
(and (member target '(:matrix :MATRIX))
(or (getf payload :room-id) (getf proposed-action :room-id)))
(and (member target '(:shell :SHELL))
(or (getf payload :cmd) (getf proposed-action :cmd)))
(member target '(:tool :TOOL))))
(member (getf proposed-action :type) '(:response :RESPONSE :log :LOG))))
(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 "*opencortex-chat*" :text ,err-text))))))
#+end_src
** Neural Response Generation
The Chat skill acts as the conversational UI. Because the ~opencortex~ kernel evaluates LLM output via ~read-from-string~ (expecting a valid s-expression) and the chat verifier strictly expects an Emacs ~:insert-at-end~ actuation, we must explicitly mandate that the LLM wraps its conversational output in a Common Lisp property list.
#+begin_src lisp
(defun probabilistic-skill-chat (context)
"Generates a conversational response, stripping system errors from context."
(let* ((payload (getf context :payload))
(raw-text (getf payload :text))
(channel (or (getf payload :channel) :emacs))
(chat-id (getf payload :chat-id))
;; Context Purge: Remove system errors and hallucinations from the history
(clean-text (cl-ppcre:regex-replace-all "(?i)Unknown request|System Error.*|Thinking\\.\\.\\." raw-text ""))
(trimmed-text (if (> (length clean-text) 1000)
(subseq clean-text (- (length clean-text) 1000))
clean-text))
(reply-instruction
(case channel
(:telegram (format nil "- To reply via Telegram: (:type :REQUEST :target :telegram :chat-id \"~a\" :text \"<Response>\")" chat-id))
(:signal (format nil "- To reply via Signal: (:type :REQUEST :target :signal :chat-id \"~a\" :text \"<Response>\")" chat-id))
(:matrix (format nil "- To reply via Matrix: (:type :REQUEST :target :matrix :room-id \"~a\" :text \"<Response>\")" chat-id))
(:cli (format nil "- To reply via CLI: (:type :REQUEST :target :cli :text \"<Response>\")"))
(t "- To reply via Emacs: (:type :REQUEST :target :emacs :action :insert-at-end :buffer \"*opencortex-chat*\" :text \"* <Response>\")"))))
(ask-probabilistic trimmed-text :system-prompt (concatenate 'string
"ACTUATOR IDENTITY: You are the pure Lisp actuator for the opencortex kernel.
MANDATE: Output EXACTLY ONE Common Lisp property list starting with (:type :REQUEST).
ZERO CONVERSATION: Do not explain. Do not use markdown.
STRICT RULE: Never output the strings 'Unknown request' or 'System Error'.
REQUIRED FORMATS:
" reply-instruction "
- To use a tool: (:type :REQUEST :target :tool :action :call :tool \"<name>\" :args (...))"))))
#+end_src
* Registration
#+begin_src lisp
(defskill :skill-chat
:priority 100
:trigger #'trigger-skill-chat
:probabilistic #'probabilistic-skill-chat
:deterministic #'verify-skill-chat)
#+end_src

101
skills/org-skill-consensus.org Normal file
View File

@@ -0,0 +1,101 @@
:PROPERTIES:
:ID: 89954f1a-7923-441e-a3c6-c35b9c3273d9
:CREATED: [2026-03-31 Tue 20:28]
:EDITED: [2026-04-07 Tue 13:42]
:END:
#+TITLE: SKILL: Social Consensus Protocol (Universal Literate Note)
#+STARTUP: content
#+FILETAGS: :distributed:swarms:consensus:autonomy:
#+DEPENDS_ON: skill-sub-agent-manager
* Overview
The *Social Consensus Protocol* enables multi-agent negotiation. It provides a Lisp-native implementation of decentralized agreement, allowing federated `opencortex` instances to coordinate on shared resources and conflicting goals.
* Phase A: Demand (PRD)
:PROPERTIES:
:STATUS: FROZEN
:END:
** 1. Purpose
Enable reliable, cross-instance coordination without a central master.
** 2. User Needs
- *Resource Negotiation:* Agree on which instance should handle a high-compute task.
- *Conflict Resolution:* Settle divergent world-states during swarm execution.
- *Byzantine Fault Tolerance:* Handle disconnected or misbehaving instances gracefully.
* Phase D: Build (Implementation)
** Consensus Algorithm (Simplified Raft)
#+begin_src lisp
(defun consensus-propose-vote (proposal)
"Broadcasts a proposal to the peer swarm and collects votes.
Implements opencortex Social Consensus Protocol."
(let* ((peers (get-swarm-peer-list))
(votes (loop for peer in peers
collect (opencortex:send-swarm-packet peer `(:type :REQUEST :action :vote :proposal ,proposal)))))
(if (> (count :YES votes) (/ (length peers) 2))
t ; Consensus reached
nil)))
#+end_src
* Registration
#+begin_src lisp
(defskill :skill-consensus
:priority 85
:trigger (lambda (context) (eq (getf (getf context :payload) :sensor) :conflict-detected))
:probabilistic (lambda (context) "Formulate a consensus proposal for the peer swarm.")
:deterministic (lambda (action context) action))
#+end_src
* Phase B: Blueprint (PROTOCOL)
:PROPERTIES:
:STATUS: SIGNED
:END:
* Phase B: Blueprint (PROTOCOL)
:PROPERTIES:
:STATUS: IN-PROGRESS
:END:
** 1. Architectural Intent
The consensus protocol should be implemented as a swarm behavior modeled after Raft, but simplified for the constraints of the `opencortex` ecosystem (i.e. eventual consistency, potentially unreliable messaging). The architecture should allow for future extensions, such as dynamically adjusting the voting threshold based on swarm size or node reputation. We use gossip protocols for state sharing.
** 2. Semantic Interfaces
*** a. Proposal Submission
- *Function Signature:* `(consensus-propose-value value &key (timeout 10))`
- *Purpose:* Initiate a consensus-building process for a given `value`. The `value` can represent a resource assignment, conflict resolution strategy, or any other agreed-upon data structure.
- *Arguments:*
- `value`: The Lisp object (e.g., symbol, list, string) representing the proposal.
- `timeout`: (Optional) The maximum time (in seconds) to wait for consensus.
- *Return Value:* `T` if consensus is reached on the `value` within the timeout; otherwise `NIL`.
- *Side Effects:* Broadcasts proposal messages to the swarm, updates local consensus state.
*** b. Vote Request Handling
- *Function Signature:* `(consensus-handle-vote-request proposal)`
- *Purpose:* Handles incoming vote requests from other swarm members.
- *Arguments:*
- `proposal`: The proposal being voted on (Lisp object).
- *Return Value:* `:YES` if the local agent agrees with the proposal; `:NO` otherwise. Decision is based on local state and policies.
- *Side Effects:* None (ideally, decision logic should be idempotent).
*** c. State Synchronization
- *Function Signature:* `(consensus-gossip-state)`
- *Purpose:* Periodically gossips its summarized consensus state to a random subset of peers. This should include current term, leader information, and recent proposal hashes.
- *Arguments:* None.
- *Return Value:* None.
- *Side Effects:* Sends state packets to other peers.
*** d. Peer Discovery
- *Function Signature:* `(get-swarm-peer-list)`
- *Purpose:* Returns a list of known peer agents in the swarm.
- *Arguments:* None
- *Return Value:* List of agent IDs/addresses. Relies on underlying SWIM or similar infrastructure.
- *Side Effects:* Potentially triggers peer discovery if stale.

74
skills/org-skill-context-manager.org Normal file
View File

@@ -0,0 +1,74 @@
:PROPERTIES:
:ID: a7af7dab-c2fd-4259-99fc-9d386c423e98
:CREATED: [2026-04-04 Sat 20:27]
:EDITED: [2026-04-07 Tue 13:42]
:END:
#+TITLE: SKILL: Context Manager (Universal Literate Note)
#+STARTUP: content
#+FILETAGS: :context:system:autonomy:
* Overview
The *Context Manager* handles the cognitive stack of the agent, allowing for switching between different projects, areas, and tasks while maintaining a clean environment.
* Phase A: Demand (PRD)
:PROPERTIES:
:STATUS: FROZEN
:END:
** 1. Purpose
Manage a stack-based context system for the agent.
** 2. User Needs
- *Push/Pop:* Ability to enter and exit specific project contexts.
- *Path Resolution:* Resolve relative paths based on the current context.
* Phase B: Blueprint (PROTOCOL)
:PROPERTIES:
:STATUS: SIGNED
:END:
* Phase B: Blueprint (PROTOCOL)
:PROPERTIES:
:STATUS: IN_PROGRESS
:END:
** 1. Architectural Intent
The *Context Manager* will operate as a stack-based system, allowing nested contexts. Each context will maintain its own set of variables (primarily file paths, but extensible to other configuration). The core functionality will be exposed through Lisp functions for pushing, popping, and resolving paths within the current context. Error handling will be robust, providing clear messages when a context is misconfigured or a requested resource is unavailable.
** 2. Semantic Interfaces (Lisp signatures)
*** `push-context`
:PROPERTIES:
:annotation: Creates a new context and pushes it onto the stack. Takes a context identifier (symbol) and an optional set of key-value pairs to initialize the context.
:END:
Signature: `(push-context context-id &key initial-bindings) => context-id`
Example: `(push-context 'my-project :project-dir "/path/to/my/project/" :author "Jane Doe")`
*** `pop-context`
:PROPERTIES:
:annotation: Removes the current context from the stack, returning to the previous context.
:END:
Signature: `(pop-context) => context-id`
Example: `(pop-context)`
*** `resolve-path`
:PROPERTIES:
:annotation: Resolves a relative path against the current context. Searches up the context stack if necessary.
:END:
Signature: `(resolve-path path &key context-id) => absolute-path`
Example: `(resolve-path "data/input.txt" :context-id 'my-project)`
*** `get-context-value`
:PROPERTIES:
:annotation: Retrieves a value associated with a key in the current context.
:END:
Signature: `(get-context-value key &key context-id) => value`
Example: `(get-context-value :project-dir :context-id 'my-project)`
*** `context-id`
:PROPERTIES:
:annotation: Returns the ID of the current context.
:END:
Signature:`(context-id) => symbol`
Example:`(context-id) ; returns the current context-id eg 'my-project or nil if top level`

76
skills/org-skill-delegation.org Normal file
View File

@@ -0,0 +1,76 @@
:PROPERTIES:
:ID: f670cf84-21ab-41eb-a16b-b9a3f3c8c76e
:CREATED: [2026-04-04 Sat 20:27]
:EDITED: [2026-04-07 Tue 13:42]
:END:
#+TITLE: SKILL: Delegation Manager (Universal Literate Note)
#+STARTUP: content
#+FILETAGS: :delegation:multi-agent:autonomy:
* Overview
The *Delegation Manager* orchestrates the dispatch of tasks to sub-agents or specialized skills.
* Phase A: Demand (PRD)
:PROPERTIES:
:STATUS: FROZEN
:END:
** 1. Purpose
Define the protocol for delegating work between agents.
** 2. User Needs
- *Trigger:* Detect when a task requires delegation.
- *Actuate:* Execute the delegation to a target skill or agent.
* Phase B: Blueprint (PROTOCOL)
:PROPERTIES:
:STATUS: SIGNED
:END:
* Phase B: Blueprint (PROTOCOL)
:PROPERTIES:
:STATUS: DRAFT
:END:
** 1. Architectural Intent
The Delegation Manager will utilize a message-passing architecture. Tasks are packaged into messages and routed based on content. A central *resolution* function determines the appropriate target agent or skill for each task. Error handling and fallback mechanisms are crucial for robustness. The core principle is *explicit delegation contracts* to ensure compatibility and predictability.
** 2. Semantic Interfaces (Lisp Signatures)
*** Task Delegation
#+BEGIN_SRC lisp
;; Sends a task to a target. Returns a promise (future) that will eventually resolve
;; to the task result. The :delegation-id is internally managed to track the delegation lifecycle.
(defun delegate-task (task priority context)
:returns (promise task-result))
#+END_SRC
*** Skill Resolution
#+BEGIN_SRC lisp
;; Determines the target agent/skill for a given task.
;; It receives the task details and any relevant context. Returns the ID of the
;; targeted agent/skill. Can return `:error` if no suitable delegation is found.
(defun resolve-skill (task context)
:returns (skill-id or :error))
#+END_SRC
*** Error Handling
#+BEGIN_SRC lisp
;; Reports a delegation failure. This allows for fallback strategies.
(defun report-delegation-failure (delegation-id error-message)
:returns nil)
#+END_SRC
*** Task Result Handling
#+BEGIN_SRC lisp
;; Informs the Delegation Manager that a task has been completed successfully.
(defun report-task-completion (delegation-id result)
:returns nil)
#+END_SRC

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

@@ -0,0 +1,117 @@
: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:autonomy:
* Overview
The *Vector Embedding* skill provides semantic search and vectorization capabilities to the opencortex. 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 Memory.
- *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 `probabilistic.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
(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
(harness-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)
(harness-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))))
*memory*)
(let ((sorted (sort similarities #'> :key #'car)))
(subseq sorted 0 (min top-k (length sorted))))))
#+end_src
* Registration
#+begin_src lisp
(defskill :skill-embedding
:priority 50
:trigger (lambda (ctx) (eq (getf (getf ctx :payload) :sensor) :embedding-request))
:probabilistic nil
:deterministic (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

87
skills/org-skill-engineering-standards.org Normal file
View File

@@ -0,0 +1,87 @@
:PROPERTIES:
:ID: 37f2b59f-4537-4cca-ac7f-5c24b9e2e773
:CREATED: [2026-03-30 Mon 21:16]
:EDITED: [2026-04-12 Sun 18:45]
:END:
#+TITLE: SKILL: Engineering Standards (Universal Literate Note)
#+STARTUP: content
#+FILETAGS: :engineering:standards:workflow:lisp:git:tdd:
* Overview
These are the strict **Engineering Standards** for all development within this system. They ensure that every line of code is provably correct, auditable, and maintainable. These standards are enforced both through the agent's instructions and physical Lisp safety gates.
* The Mandates (Operational Standards)
** 1. Commit Before Modify
You MUST commit and push the current state of the workspace BEFORE initiating any new file modifications. This ensures a clean recovery point. The system physically blocks file modifications if the working tree is dirty.
** 2. Literate Programming (The Single Source of Truth)
All system logic and skills MUST be implemented as Literate Org files. Weaving documentation and code together ensures that the "Why" (Architectural Intent) is never separated from the "How" (Implementation).
** 3. Literate Granularity (The Function-Block Rule)
Every Lisp function, macro, or variable MUST reside in its own dedicated `#+begin_src lisp` block, immediately preceded by its literate explanatory text. This ensures that the logical intent is documented alongside the implementation.
** 4. Test-Driven Development (Continuous QA)
No change is complete without verification. Every new function or macro must be accompanied by a FiveAM test case. You must run the test suite and verify success before considering a task complete.
** 5. The Consensus Loop (Plan Mode)
Major architectural shifts or complex refactors require a formal implementation plan. You must enter Plan Mode, draft a Blueprint (PROTOCOL), and seek formal approval before execution.
** 6. The Stop-and-Wait Mandate (Turn-Yielding)
You are strictly forbidden from drafting a plan or requesting formal approval in the same conversational turn that you propose an initial strategy or begin file discovery. You MUST propose your strategy in plain text, explicitly state "Waiting for user feedback," and yield the turn. You may only proceed to draft the `.md` plan after the user explicitly replies with agreement.
** 7. GTD Synchronization (Roadmap Integrity)
You are strictly forbidden from considering a task complete without updating `gtd.org`. Every major architectural shift, feature implementation, or refactor MUST be recorded in the project roadmap to ensure technical transparency and historical auditability. When updating `gtd.org`, you MUST NEVER use checkboxes (`[ ]`) for sub-tasks; always use hierarchical sub-TODO headlines.
** 8. Configuration Externalization (Environment-Driven)
Source code MUST be strictly free of hardcoded configuration values (e.g., ports, rhythms, timeouts). All such values must be extracted to the environment (via `.env`) and documented in `.env.example`. This ensures portability and security.
** 9. Literate-Only Modification (The Tangle Mandate)
You are strictly forbidden from modifying generated source code files (e.g., `.lisp`, `.py`, `.el`) directly. All changes MUST be made within the corresponding Literate Org file and then tangled to the source. Direct modification of source code is only permitted with explicit user authorization.
* Phase B: Blueprint (PROTOCOL)
:PROPERTIES:
:STATUS: SIGNED
:END:
** 1. Architectural Intent
The Engineering Standards skill provides the deterministic enforcement of the workflow. It intercepts agent actions and validates them against the git environment and system state.
** 2. Semantic Interfaces
*** `verify-git-clean-p`
- Purpose: Checks if the git repository is in a clean state.
- Returns: `t` if clean, `nil` if dirty.
* Phase D: Build (Implementation)
** Git Status Enforcement
#+begin_src lisp
(defun verify-git-clean-p (dir)
"Returns T if the git repository at DIR has no 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))))
(defun engineering-standards-gate (action context)
"Physically enforces the 'Commit Before Modify' rule."
(let* ((payload (getf action :payload))
(act (or (getf payload :action) (getf action :action)))
(target-file (getf payload :file)))
;; If the action involves modifying files, check git status
(when (member act '(:modify-file :write-file :replace :rename-file :delete-file))
(let ((proj-root (asdf:system-source-directory :opencortex)))
(unless (verify-git-clean-p proj-root)
(harness-log "DETERMINISTIC [Standards]: BLOCKING ACTION. Working tree is dirty. Commit changes before modification.")
(return-from engineering-standards-gate
(list :type :LOG :payload (list :text "Engineering Standard Violation: Working tree dirty. You MUST commit before modifying files."))))))
action))
#+end_src
* See Also
- [[file:org-skill-system-invariants.org][System Policy]]
- [[file:../README.org][opencortex README]]

68
skills/org-skill-environment-config.org Normal file
View File

@@ -0,0 +1,68 @@
:PROPERTIES:
:ID: 20afa98c-446d-437b-b388-b2616e7b4531
:CREATED: [2026-03-30 Mon 21:16]
:EDITED: [2026-04-07 Tue 13:42]
:END:
#+TITLE: SKILL: Environment Configuration Manager (Universal Literate Note)
#+STARTUP: content
#+FILETAGS: :system:config:autonomousty:autonomy:
* Overview
The *Environment Configuration Manager* is the source of truth for user preferences. It persists settings (like LLM Model Fleets) into the harness's Memory, allowing for dynamic runtime reconfiguration without environment variable bloat.
* Phase A: Demand (PRD)
:PROPERTIES:
:STATUS: SIGNED
:END:
** 1. Purpose
Provide a programmatic and literate interface for managing system-wide settings.
** 2. User Needs
- *Fleet Management:* Define preferred models for each LLM provider.
- *Persistence:* Ensure settings survive kernel restarts via the Memory.
- *Transparency:* Allow the user to audit current settings via the REPL or Org tables.
* Phase B: Blueprint (PROTOCOL)
:PROPERTIES:
:STATUS: SIGNED
:END:
** 1. Architectural Intent
Define a standardized `CONFIG` object type in the Memory. Provide getter/setter functions for the "LLM Fleet."
** 2. Semantic Interfaces
*** Fleet Configuration
#+begin_src lisp
(defun set-llm-model (provider model-id)
"Registers a preferred model for a provider in the Memory."
(let ((config-id (format nil "config-llm-~a" (string-downcase (string provider)))))
(let ((obj (make-org-object
:id config-id
:type :CONFIG
:attributes `(:provider ,provider :model-id ,model-id)
:content (format nil "Fleet preference for ~a set to ~a" provider model-id)
:version (get-universal-time))))
(setf (gethash config-id *memory*) obj)
(harness-log "CONFIG - Fleet updated: ~a -> ~a" provider model-id)
t)))
(defun get-llm-model (provider &optional default)
"Retrieves the preferred model for a provider from the Memory."
(let* ((config-id (format nil "config-llm-~a" (string-downcase (string provider))))
(obj (gethash config-id *memory*)))
(if obj
(getf (org-object-attributes obj) :model-id)
default)))
#+end_src
* Registration
#+begin_src lisp
(defskill :skill-environment-config
:priority 100
:trigger (lambda (context) nil) ; Passive utility skill
:probabilistic (lambda (context) nil)
:deterministic (lambda (action context) action))
#+end_src

205
skills/org-skill-event-orchestrator.org Normal file
View File

@@ -0,0 +1,205 @@
:PROPERTIES:
:ID: event-orchestrator-skill
:CREATED: [2026-04-09 Thu]
:END:
#+TITLE: SKILL: Event Orchestrator (Universal Literate Note)
#+STARTUP: content
#+FILETAGS: :system:control:event-driven:cron:hooks:routing:autonomy:
#+DEPENDS_ON: id:state-persistence-skill
* Overview
The *Event Orchestrator* is the central nervous system of the OpenCortex. It unifies three previously fragmented domains of system control:
1. **Cron (Temporal Control):** Triggering tasks based on time and heartbeats.
2. **Hooks (Lifecycle Control):** Enabling event-driven extensibility at specific code points.
3. **Routing (Cognitive Control):** Classifying incoming stimuli into complexity tiers for optimal resource allocation.
By consolidating these into a single unit, we ensure that all system automation is auditable, Merkle-integrated, and follows a uniform safety standard.
* Phase A: Demand (PRD)
:PROPERTIES:
:STATUS: SIGNED
:END:
** 1. Purpose
Provide a unified, high-integrity interface for background automation and stimulus classification.
** 2. User Needs
- *Predictable Scheduling:* Precise execution of tasks based on cron-strings or intervals.
- *Reactive Extensions:* Ability to "hook" into system events (save, boot, ingest).
- *Intelligent Dispatch:* Automated complexity tiering to prevent wasted compute.
- *Durable Registry:* All registered hooks and cron-jobs must be persisted to the Memory.
* Phase B: Blueprint (PROTOCOL)
:PROPERTIES:
:STATUS: SIGNED
:END:
** 1. Architectural Intent
The orchestrator maintains three internal registries (Hooks, Cron, Routing Rules). It provides a standard API for registration and triggering, using the `LOCAL` persistence adapter to ensure these registries survive reboots.
** 2. Semantic Interfaces
#+begin_src lisp
(defun orchestrator-register-hook (hook-name fn)
"Adds a function to a system hook.")
(defun orchestrator-schedule-task (task-id schedule fn)
"Schedules a recurring task.")
(defun orchestrator-classify-stimulus (context)
"Assigns a complexity tier (:REFLEX, :COGNITION, :REASONING) to a stimulus.")
#+end_src
* Phase C: Success (QUALITY)
:PROPERTIES:
:STATUS: SIGNED
:END:
** 1. Success Criteria
- [ ] *Hook Latency:* Triggering a hook with 10 functions must complete in <1ms.
- [ ] *Cron Precision:* Scheduled tasks must fire within 1s of their target window.
- [ ] *Merkle Persistence:* Adding a hook or cron-job must increment the Memory version.
- [ ] *Classification Accuracy:* Routine system events must always be classified as `:REFLEX`.
** 2. TDD Plan
Tests in `tests/orchestrator-tests.lisp` will verify hook execution order, cron-job triggering via a mocked heartbeat, and the routing classification logic.
* Phase D: Build (Implementation)
** Package Context
#+begin_src lisp
#+end_src
** Registry State
We maintain our internal registries in hash-tables, which will be serialized via the State Persistence layer.
#+begin_src lisp
(defvar *hook-registry* (make-hash-table :test 'equal)
"Maps hook-names (symbols) to lists of functions.")
(defvar *cron-registry* (make-hash-table :test 'equal)
"Maps task-ids to plists containing schedule and function.")
#+end_src
** Hook: Registration
Allows external skills to register logic at system lifecycle points.
#+begin_src lisp
(defun orchestrator-register-hook (hook-name fn)
"Registers a function for a named hook. Triggers a Merkle snapshot."
(pushnew fn (gethash hook-name *hook-registry*))
(harness-log "ORCHESTRATOR - Registered hook function for ~a" hook-name)
(snapshot-memory)
t)
#+end_src
** Hook: Triggering
Executes all functions associated with a specific hook.
#+begin_src lisp
(defun orchestrator-trigger-hook (hook-name &rest args)
"Executes all registered functions for the given hook name."
(let ((functions (gethash hook-name *hook-registry*)))
(dolist (fn functions)
(handler-case (apply fn args)
(error (c) (harness-log "ORCHESTRATOR ERROR - Hook ~a failed: ~a" hook-name c))))))
#+end_src
** Cron: Task Scheduling
Registers a recurring task to be executed during heartbeats.
#+begin_src lisp
(defun orchestrator-schedule-task (task-id schedule fn)
"Schedules a task for execution. Schedule can be an interval (integer seconds) or 'heartbeat'."
(setf (gethash task-id *cron-registry*) (list :schedule schedule :fn fn :last-run 0))
(harness-log "ORCHESTRATOR - Scheduled task ~a (~a)" task-id schedule)
(snapshot-memory)
t)
#+end_src
** Cron: Heartbeat Processor
The internal loop that checks the cron-registry during every system pulse.
#+begin_src lisp
(defun orchestrator-process-cron ()
"Checked by the harness on every heartbeat."
(let ((now (get-universal-time)))
(maphash (lambda (id task)
(let ((schedule (getf task :schedule))
(last-run (getf task :last-run))
(fn (getf task :fn)))
(when (or (eq schedule :heartbeat)
(and (integerp schedule) (>= (- now last-run) schedule)))
(handler-case (funcall fn)
(error (c) (harness-log "ORCHESTRATOR ERROR - Cron task ~a failed: ~a" id c)))
(setf (getf (gethash id *cron-registry*) :last-run) now))))
*cron-registry*)))
#+end_src
** Router: Complexity Classification
Deterministic logic to classify incoming stimuli into complexity tiers.
#+begin_src lisp
(defun orchestrator-classify-complexity (context)
"Returns the complexity tier (:REFLEX, :COGNITION, :REASONING) for a stimulus."
(let* ((payload (getf context :payload))
(sensor (getf payload :sensor))
(skill (find-triggered-skill context))
(skill-name (when skill (skill-name skill))))
(cond
;; reasoning: generative or architectural
((member skill-name '("skill-architect" "skill-tech-analyst" "skill-scientist" "skill-self-fix") :test #'string-equal) :REASONING)
((member sensor '(:user-command)) :REASONING)
;; cognition: human interaction or semantic data
((member sensor '(:chat-message :delegation)) :COGNITION)
((member skill-name '("skill-scribe" "skill-web-research") :test #'string-equal) :COGNITION)
;; reflex: system infrastructure and background automation
(t :REFLEX))))
#+end_src
** Registration
We register the orchestrator as a core skill and hot-patch the harness's routing hook to use our classification logic.
#+begin_src lisp
(progn
;; Hook into kernel routing
(setf opencortex::*model-selector-fn* #'orchestrator-classify-complexity)
(defskill :skill-event-orchestrator
:priority 400 ; Foundational control layer
:trigger (lambda (ctx) (eq (getf (getf ctx :payload) :sensor) :heartbeat))
:probabilistic nil
:deterministic (lambda (action ctx)
(orchestrator-process-cron)
action)))
#+end_src
* Phase E: Chaos (Verification)
** 1. Unit Tests (FiveAM)
#+begin_src lisp
(defpackage :opencortex-orchestrator-tests
(:use :cl :fiveam :opencortex))
(in-package :opencortex-orchestrator-tests)
(def-suite orchestrator-suite :description "Tests for Event Orchestrator.")
(in-suite orchestrator-suite)
(test test-hook-execution
(let ((test-val 0))
(opencortex:orchestrator-register-hook :test-hook (lambda () (setf test-val 1)))
(opencortex:orchestrator-trigger-hook :test-hook)
(is (= 1 test-val))))
(test test-routing-reflex
(let ((ctx '(:payload (:sensor :heartbeat))))
(is (eq :REFLEX (opencortex:orchestrator-classify-complexity ctx)))))
#+end_src
** 2. Chaos Scenarios
- *Scenario A (Infinite Hook Loop):* Register two hooks that call each other and verify the orchestrator's recursion limit or handler-case prevents a kernel stack-overflow.
- *Scenario B (Cron Stall):* Register a cron-job that performs a long synchronous sleep and verify the `harness-log` identifies the delay in the heartbeat pulse.
* Phase F: Memory (RCA)
- *[2026-04-09 Thu]:* Consolidated Cron, Hook Manager, and Cognitive Router into a single orchestrator. Fixed the lack of implementation for Cron and Hooks.

149
skills/org-skill-formal-verification.org Normal file
View File

@@ -0,0 +1,149 @@
:PROPERTIES:
:ID: 4819956d-a2ec-403d-99f8-4ccb13efb7c2
:CREATED: [2026-03-31 Tue 20:28]
:EDITED: [2026-04-11 Sat 17:45]
:END:
#+TITLE: SKILL: Formal Verification Gate (Universal Literate Note)
#+STARTUP: content
#+FILETAGS: :security:logic:formal-methods:autonomy:
* Overview
The *Formal Verification Gate* replaces heuristic whitelisting with deterministic logic proofs. It ensures that every action proposed by Probabilistic Engine is *provably safe* against the harness's core security invariants using a Lisp-native deterministic prover.
** Deep Reasoning: The Sandbox of Intent
This gate is the first line of defense against both "Inside Threats" (maliciously modified skill files) and "Hallucination Threats" (LLMs generating unsafe commands).
1. **Isolation from Implementation:** The Prover does not trust the logic inside a skill. It sits between the skill's proposal and the physical world.
2. **Structural Enforcement:** Even if a skill is compromised and attempts to execute a command like `rm -rf /`, the Prover identifies the violation of the `path-confinement` invariant and blocks it before it hits the OS.
3. **Prover vs. Bouncer:**
- **The Prover (Static):** Focuses on *Structure*. "Is this path legal? Is this tool allowed?"
- **The Bouncer (Runtime):** Focuses on *Content*. "Is this message leaking my API keys? Is this network packet unauthorized?"
* Phase A: Demand (PRD)
:PROPERTIES:
:STATUS: SIGNED
:END:
** 1. Purpose
Define a logic-based verification layer for high-integrity decision making without external SMT dependencies.
** 2. Success Criteria
- [ ] *Invariants:* Express security properties as Lisp predicates.
- [ ] *Soundness:* Block any action that fails a deterministic safety check.
- [ ] *Path Confinement:* Prove that file operations are confined to the Autonomous's memex.
- [ ] *Network Protection:* Prove that shell commands do not attempt unauthorized data exfiltration.
* Phase B: Blueprint (PROTOCOL)
:PROPERTIES:
:STATUS: SIGNED
:END:
** 1. Architectural Intent
The gate operates as high-priority middleware. It decomposes proposed actions and applies a suite of formal invariants. Unlike simple string matching, it evaluates the *intent* and *impact* of the action within the current context.
** 2. Semantic Interfaces
- `(def-invariant name action-type (action context) ...)`
- `(verify-action-formally action context)`
* Phase D: Build (Implementation)
** Package Context
#+begin_src lisp
#+end_src
** Invariant Registry
Global store for all registered security invariants.
#+begin_src lisp
(defvar *formal-invariants* (make-hash-table :test 'equal)
"Registry of security invariants used by the Formal Verification Gate.")
#+end_src
** Invariant Definition Macro
#+begin_src lisp
(defmacro def-invariant (name action-type (action context) &body body)
"Defines a formal security invariant.
BODY must return T for safe actions and NIL for unsafe ones."
`(setf (gethash (string-downcase (string ',name)) *formal-invariants*)
(list :name ',name
:type ,action-type
:logic (lambda (,action ,context) ,@body))))
#+end_src
** Invariant: Path Confinement
Ensures all file-related operations (including shell calls that touch files) are confined to the memex root.
#+begin_src lisp
(def-invariant path-confinement :all (action context)
"Forces all path-based operations to reside within the Autonomous Memex."
(declare (ignore context))
(let* ((payload (getf action :payload))
(path (or (getf payload :file) (getf payload :path)))
(cmd (getf payload :cmd))
(memex-root (or (uiop:getenv "MEMEX_DIR") "/home/user/memex")))
(cond
;; If a path is explicitly provided, verify it is absolute and within root
(path
(let ((truename (ignore-errors (namestring (truename path)))))
(if truename
(str:starts-with-p memex-root truename)
;; If file doesn't exist yet, check string prefix
(str:starts-with-p memex-root path))))
;; If it's a shell command, check for absolute paths outside memex
(cmd
(not (cl-ppcre:scan "(^|\\s)/((etc|var|proc|root|sys)|(home/(?!user/memex)))" cmd)))
(t t))))
#+end_src
** Invariant: No Network Exfiltration
Blocks common tools and patterns used for data exfiltration via the shell.
#+begin_src lisp
(def-invariant no-network-exfil :shell (action context)
"Prevents shell commands from establishing unauthorized external connections."
(declare (ignore context))
(let* ((payload (getf action :payload))
(cmd (getf payload :cmd)))
(if (and cmd (stringp cmd))
(let ((forbidden-tools '("nc" "netcat" "ssh" "scp" "rsync" "ftp" "telnet")))
(not (some (lambda (tool) (cl-ppcre:scan (format nil "(^|\\s)~a(\\s|$)" tool) cmd))
forbidden-tools)))
t)))
#+end_src
** Verification Engine
The core prover that applies all relevant invariants to an action.
#+begin_src lisp
(defun verify-action-formally (action context)
"Deterministically proves that ACTION satisfies all applicable security invariants."
(let ((action-target (getf action :target))
(action-type (getf action :type))
(all-passed t))
(maphash (lambda (id inv)
(declare (ignore id))
(let ((inv-type (getf inv :type))
(inv-logic (getf inv :logic))
(inv-name (getf inv :name)))
(when (or (eq inv-type :all)
(eq inv-type action-target)
(eq inv-type action-type))
(unless (funcall inv-logic action context)
(harness-log "FORMAL FAILURE: Action ~s violated invariant ~a" action inv-name)
(setf all-passed nil)))))
*formal-invariants*)
all-passed))
#+end_src
** Registration: Skill
#+begin_src lisp
(defskill :skill-formal-verification
:priority 95 ; Just below Bouncer
:trigger (lambda (context) (declare (ignore context)) nil) ; Middleware only
:probabilistic nil
:deterministic (lambda (action context)
(if (verify-action-formally action context)
action
(let ((err (format nil "Formal verification failed for action: ~s" action)))
`(:type :log :payload (:level :error :text ,err))))))
#+end_src

187
skills/org-skill-gateway-matrix.org Normal file
View File

@@ -0,0 +1,187 @@
:PROPERTIES:
:ID: gateway-matrix-skill
:CREATED: [2026-04-11 Sat 17:00]
:END:
#+TITLE: SKILL: Matrix Gateway (Universal Literate Note)
#+STARTUP: content
#+FILETAGS: :gateway:matrix:io:autonomy:
#+DEPENDS_ON: id:credentials-vault-skill
* Overview
The *Matrix Gateway* provides bi-directional communication via the Matrix Client-Server API. It features an asynchronous polling sensor using the `/sync` endpoint and a registered actuator for outbound `m.room.message` events.
* Phase A: Demand (PRD)
:PROPERTIES:
:STATUS: SIGNED
:END:
** 1. Purpose
Integrate the OpenCortex into the Matrix federation for secure, distributed chat.
** 2. Success Criteria
- [ ] *Inbound:* Messages from Matrix rooms are normalized and injected into the harness Bus.
- [ ] *Outbound:* The `:matrix` target correctly routes messages to specific room IDs.
- [ ] *State:* The `since` token is maintained during a session to prevent message loops.
* Phase B: Blueprint (PROTOCOL)
:PROPERTIES:
:STATUS: SIGNED
:END:
** 1. Architectural Intent
Autonomous background polling of the Matrix homeserver. Uses `dexador` for HTTP and `cl-json` for parsing.
** 2. Semantic Interfaces
- `(:sensor :chat-message :channel :matrix ...)`
- `(:type :REQUEST :target :matrix :room-id "..." :text "...")`
* Phase D: Build (Implementation)
** Package Context
#+begin_src lisp
#+end_src
** State: Sync Token
Tracks the last processed event to ensure we only receive new messages.
#+begin_src lisp
(defvar *matrix-since-token* nil)
#+end_src
** State: Polling Thread
Reference to the background thread responsible for sync requests.
#+begin_src lisp
(defvar *matrix-polling-thread* nil)
#+end_src
** Credential Retrieval: Homeserver
#+begin_src lisp
(defun get-matrix-homeserver () (vault-get-secret :matrix-homeserver))
#+end_src
** Credential Retrieval: Token
#+begin_src lisp
(defun get-matrix-token () (vault-get-secret :matrix-token))
#+end_src
** Actuator: sendMessage
Sends an `m.room.message` to a Matrix room.
#+begin_src lisp
(defun execute-matrix-action (action context)
"Sends a message via Matrix Client API."
(declare (ignore context))
(let* ((payload (getf action :payload))
(room-id (or (getf payload :room-id) (getf action :room-id)))
(text (or (getf payload :text) (getf action :text)))
(hs (get-matrix-homeserver))
(token (get-matrix-token))
(txn-id (get-universal-time))
(url (format nil "~a/_matrix/client/v3/rooms/~a/send/m.room.message/~a" hs room-id txn-id)))
(when (and hs token room-id text)
(harness-log "MATRIX: Sending message to ~a..." room-id)
(handler-case
(dex:put url
:headers `(("Authorization" . ,(format nil "Bearer ~a" token))
("Content-Type" . "application/json"))
:content (cl-json:encode-json-to-string
`((msgtype . "m.text") (body . ,text))))
(error (c) (harness-log "MATRIX ERROR: ~a" c))))))
#+end_src
** Sensor: Sync loop & Injection
Polls the `/sync` endpoint and processes timeline events.
#+begin_src lisp
(defun matrix-process-sync ()
"Calls Matrix sync and injects new messages."
(let* ((hs (get-matrix-homeserver))
(token (get-matrix-token))
(url (format nil "~a/_matrix/client/v3/sync?timeout=30000~@[&since=~a~]"
hs *matrix-since-token*)))
(when (and hs token)
(handler-case
(let* ((response (dex:get url :headers `(("Authorization" . ,(format nil "Bearer ~a" token)))))
(json (cl-json:decode-json-from-string response))
(next-batch (or (cdr (assoc :next-batch json))
(cdr (assoc :next--batch json))))
(rooms (cdr (assoc :rooms json)))
(joined (cdr (assoc :join rooms))))
(when next-batch
(setf *matrix-since-token* next-batch))
(dolist (room-entry joined)
(let* ((room-id (string-downcase (string (car room-entry))))
(room-data (cdr room-entry))
(timeline (cdr (assoc :timeline room-data)))
(events (cdr (assoc :events timeline))))
(dolist (event events)
(let* ((type (cdr (assoc :type event)))
(content (cdr (assoc :content event)))
(sender (cdr (assoc :sender event)))
(body (cdr (assoc :body content))))
(when (and (string= type "m.room.message") body)
(harness-log "MATRIX: Received message from ~a in ~a" sender room-id)
(inject-stimulus
(list :type :EVENT
:payload (list :sensor :chat-message
:channel :matrix
:room-id room-id
:sender sender
:text body)))))))))
(error (c) (harness-log "MATRIX SYNC ERROR: ~a" c))))))
#+end_src
** Start Polling
Initializes the Matrix background thread.
#+begin_src lisp
(defun start-matrix-gateway ()
"Initializes the Matrix background thread."
(unless (and *matrix-polling-thread* (bt:thread-alive-p *matrix-polling-thread*))
(setf *matrix-polling-thread*
(bt:make-thread
(lambda ()
(loop
(matrix-process-sync)
(sleep 2)))
:name "opencortex-matrix-gateway"))
(harness-log "MATRIX: Gateway sync active.")))
#+end_src
** Stop Polling
Gracefully terminates the background thread.
#+begin_src lisp
(defun stop-matrix-gateway ()
(when (and *matrix-polling-thread* (bt:thread-alive-p *matrix-polling-thread*))
(bt:destroy-thread *matrix-polling-thread*)
(setf *matrix-polling-thread* nil)))
#+end_src
** Registration: Actuator
Register the Matrix channel as a physical actuator.
#+begin_src lisp
(register-actuator :matrix #'execute-matrix-action)
#+end_src
** Registration: Skill
Define the passive skill entry for the gateway.
#+begin_src lisp
(defskill :skill-gateway-matrix
:priority 150
:trigger (lambda (ctx) (declare (ignore ctx)) nil)
:probabilistic nil
:deterministic (lambda (action ctx) (declare (ignore ctx)) action))
#+end_src
** Initialization
Trigger the sync loop upon loading.
#+begin_src lisp
(start-matrix-gateway)
#+end_src

157
skills/org-skill-gateway-signal.org Normal file
View File

@@ -0,0 +1,157 @@
:PROPERTIES:
:ID: gateway-signal-skill
:CREATED: [2026-04-11 Sat 16:30]
:END:
#+TITLE: SKILL: Signal Gateway (Universal Literate Note)
#+STARTUP: content
#+FILETAGS: :gateway:signal:io:autonomy:
#+DEPENDS_ON: id:credentials-vault-skill
* Overview
The *Signal Gateway* provides bi-directional communication between the Autonomous and the OpenCortex via the `signal-cli` tool. It features a non-blocking polling sensor and a high-integrity actuator for outbound messaging.
* Phase A: Demand (PRD)
:PROPERTIES:
:STATUS: SIGNED
:END:
** 1. Purpose
Enable secure Signal communication for the OpenCortex.
** 2. Success Criteria
- [ ] *Inbound:* Messages received via `signal-cli receive` are injected into the harness Bus.
- [ ] *Outbound:* The `:signal` target correctly routes messages via `signal-cli send`.
- [ ] *Robustness:* Handles JSON output from `signal-cli` and filters system messages.
* Phase B: Blueprint (PROTOCOL)
:PROPERTIES:
:STATUS: SIGNED
:END:
** 1. Architectural Intent
Wraps the `signal-cli` binary. Polling is done in a background thread to prevent blocking the harness.
** 2. Semantic Interfaces
- `(:sensor :chat-message :channel :signal ...)`
- `(:type :REQUEST :target :signal :chat-id "+1..." :text "...")`
* Phase D: Build (Implementation)
** Package Context
#+begin_src lisp
#+end_src
** State: Signal Identity
Retrieves the Signal account number from the secure vault.
#+begin_src lisp
(defun get-signal-account () (vault-get-secret :signal))
#+end_src
** State: Polling Thread
Reference to the background thread responsible for message reception.
#+begin_src lisp
(defvar *signal-polling-thread* nil)
#+end_src
** Actuator: sendMessage
Executes the `signal-cli send` command.
#+begin_src lisp
(defun execute-signal-action (action context)
"Sends a message via signal-cli."
(declare (ignore context))
(let* ((payload (getf action :payload))
(chat-id (or (getf payload :chat-id) (getf action :chat-id)))
(text (or (getf payload :text) (getf action :text)))
(account (get-signal-account)))
(when (and account chat-id text)
(harness-log "SIGNAL: Sending message to ~a..." chat-id)
(handler-case
(uiop:run-program (list "signal-cli" "-u" account "send" "-m" text chat-id)
:output :string :error-output :string)
(error (c) (harness-log "SIGNAL ERROR: ~a" c))))))
#+end_src
** Sensor: receive & Injection
Polls for new messages and injects them into the harness.
#+begin_src lisp
(defun signal-process-updates ()
"Polls for new messages via signal-cli and injects them into the harness."
(let ((account (get-signal-account)))
(when account
(handler-case
(let* ((output (uiop:run-program (list "signal-cli" "-u" account "receive" "--json")
:output :string :error-output :string :ignore-error-status t))
(lines (cl-ppcre:split "\\n" output)))
(dolist (line lines)
(when (and line (> (length line) 0))
(let* ((json (ignore-errors (cl-json:decode-json-from-string line)))
(envelope (cdr (assoc :envelope json)))
(source (cdr (assoc :source envelope)))
(data-message (cdr (assoc :data-message envelope)))
(text (cdr (assoc :message data-message))))
(when (and source text)
(harness-log "SIGNAL: Received message from ~a" source)
(inject-stimulus
(list :type :EVENT
:payload (list :sensor :chat-message
:channel :signal
:chat-id source
:text text))))))))
(error (c) (harness-log "SIGNAL POLL ERROR: ~a" c))))))
#+end_src
** Start Polling
Initializes the Signal background thread.
#+begin_src lisp
(defun start-signal-gateway ()
"Initializes the Signal background thread."
(unless (and *signal-polling-thread* (bt:thread-alive-p *signal-polling-thread*))
(setf *signal-polling-thread*
(bt:make-thread
(lambda ()
(loop
(signal-process-updates)
(sleep 5)))
:name "opencortex-signal-gateway"))
(harness-log "SIGNAL: Gateway polling active.")))
#+end_src
** Stop Polling
Gracefully terminates the background thread.
#+begin_src lisp
(defun stop-signal-gateway ()
(when (and *signal-polling-thread* (bt:thread-alive-p *signal-polling-thread*))
(bt:destroy-thread *signal-polling-thread*)
(setf *signal-polling-thread* nil)))
#+end_src
** Registration: Actuator
Register the Signal channel as a physical actuator.
#+begin_src lisp
(register-actuator :signal #'execute-signal-action)
#+end_src
** Registration: Skill
Define the passive skill entry for the gateway.
#+begin_src lisp
(defskill :skill-gateway-signal
:priority 150
:trigger (lambda (ctx) (declare (ignore ctx)) nil) ;; Passive
:probabilistic nil
:deterministic (lambda (action ctx) (declare (ignore ctx)) action))
#+end_src
** Initialization
Trigger the polling loop upon loading.
#+begin_src lisp
(start-signal-gateway)
#+end_src

173
skills/org-skill-gateway-telegram.org Normal file
View File

@@ -0,0 +1,173 @@
:PROPERTIES:
:ID: gateway-telegram-skill
:CREATED: [2026-04-11 Sat 15:50]
:END:
#+TITLE: SKILL: Telegram Gateway (Universal Literate Note)
#+STARTUP: content
#+FILETAGS: :gateway:telegram:io:autonomy:
#+DEPENDS_ON: id:credentials-vault-skill
* Overview
The *Telegram Gateway* provides bi-directional communication between the Autonomous and the OpenCortex via the Telegram Bot API. It features a non-blocking polling sensor and a high-integrity actuator for outbound messaging.
* Phase A: Demand (PRD)
:PROPERTIES:
:STATUS: SIGNED
:END:
** 1. Purpose
Enable mobile/remote access to the OpenCortex via a secure Telegram bot.
** 2. Success Criteria
- [ ] *Inbound:* Messages from authorized Telegram IDs are injected into the harness Bus.
- [ ] *Outbound:* The `:telegram` target correctly routes messages to the Bot API.
- [ ] *Persistence:* The polling offset is maintained to prevent duplicate processing.
* Phase B: Blueprint (PROTOCOL)
:PROPERTIES:
:STATUS: SIGNED
:END:
** 1. Architectural Intent
The gateway operates as an autonomous background service. It uses `dexador` for HTTP polling and `cl-json` for payload processing. Authentication is enforced via a whitelist of authorized `chat_id`s.
** 2. Semantic Interfaces
- `(:sensor :chat-message :channel :telegram ...)`
- `(:type :REQUEST :target :telegram :chat-id "..." :text "...")`
* Phase D: Build (Implementation)
** Package Context
#+begin_src lisp
#+end_src
** State: Update Tracking
Tracks the last processed message ID to prevent duplicates.
#+begin_src lisp
(defvar *telegram-last-update-id* 0)
#+end_src
** State: Polling Thread
Reference to the background thread responsible for message reception.
#+begin_src lisp
(defvar *telegram-polling-thread* nil)
#+end_src
** State: Authorized Chats
Whitelist of chat IDs permitted to interact with the agent.
#+begin_src lisp
(defvar *telegram-authorized-chats* nil
"List of chat IDs allowed to interact with the bot. Hydrated from environment.")
#+end_src
** Token Retrieval
Fetches the Bot API token from the secure vault.
#+begin_src lisp
(defun get-telegram-token () (vault-get-secret :telegram))
#+end_src
** Actuator: sendMessage
#+begin_src lisp
(defun execute-telegram-action (action context)
"Sends a message back to Telegram."
(declare (ignore context))
(let* ((payload (getf action :payload))
(chat-id (or (getf payload :chat-id) (getf action :chat-id)))
(text (or (getf payload :text) (getf action :text)))
(token (get-telegram-token))
(url (format nil "https://api.telegram.org/bot~a/sendMessage" token)))
(when (and token chat-id text)
(harness-log "TELEGRAM: Sending message to ~a..." chat-id)
(handler-case
(dex:post url
:headers '(("Content-Type" . "application/json"))
:content (cl-json:encode-json-to-string
`((chat_id . ,chat-id) (text . ,text))))
(error (c) (harness-log "TELEGRAM ERROR: ~a" c))))))
#+end_src
** Sensor: getUpdates & Injection
#+begin_src lisp
(defun telegram-process-updates ()
"Polls for new messages and injects them into the harness."
(let* ((token (get-telegram-token))
(url (format nil "https://api.telegram.org/bot~a/getUpdates?offset=~a"
token (1+ *telegram-last-update-id*))))
(when token
(handler-case
(let* ((response (dex:get url))
(json (cl-json:decode-json-from-string response))
(updates (cdr (assoc :result json))))
(dolist (update updates)
(let* ((update-id (cdr (assoc :update--id update)))
(message (cdr (assoc :message update)))
(chat (cdr (assoc :chat message)))
(chat-id (cdr (assoc :id chat)))
(text (cdr (assoc :text message))))
(setf *telegram-last-update-id* update-id)
(when (and text chat-id)
(harness-log "TELEGRAM: Received message from ~a" chat-id)
(inject-stimulus
(list :type :EVENT
:payload (list :sensor :chat-message
:channel :telegram
:chat-id (format nil "~a" chat-id)
:text text)))))))
(error (c) (harness-log "TELEGRAM POLL ERROR: ~a" c))))))
#+end_src
** Start Polling
Initializes the Telegram background thread.
#+begin_src lisp
(defun start-telegram-gateway ()
"Initializes the Telegram background thread."
(unless (and *telegram-polling-thread* (bt:thread-alive-p *telegram-polling-thread*))
(setf *telegram-polling-thread*
(bt:make-thread
(lambda ()
(loop
(telegram-process-updates)
(sleep 3)))
:name "opencortex-telegram-gateway"))
(harness-log "TELEGRAM: Gateway polling active.")))
#+end_src
** Stop Polling
Gracefully terminates the background thread.
#+begin_src lisp
(defun stop-telegram-gateway ()
(when (and *telegram-polling-thread* (bt:thread-alive-p *telegram-polling-thread*))
(bt:destroy-thread *telegram-polling-thread*)
(setf *telegram-polling-thread* nil)))
#+end_src
** Registration: Actuator
Register the Telegram channel as a physical actuator.
#+begin_src lisp
(register-actuator :telegram #'execute-telegram-action)
#+end_src
** Registration: Skill
Define the passive skill entry for the gateway.
#+begin_src lisp
(defskill :skill-gateway-telegram
:priority 150
:trigger (lambda (ctx) (declare (ignore ctx)) nil) ;; Passive, handles its own loop
:probabilistic nil
:deterministic (lambda (action ctx) (declare (ignore ctx)) action))
#+end_src
** Initialization
Trigger the polling loop upon loading.
#+begin_src lisp
(start-telegram-gateway)
#+end_src

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

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

100
skills/org-skill-inbound-gateway.org Normal file
View File

@@ -0,0 +1,100 @@
:PROPERTIES:
:ID: 89ee87e0-ac9f-45cd-9fb4-e3dc5c52fe34
:CREATED: [2026-03-31 Tue 18:43]
:EDITED: [2026-04-07 Tue 13:42]
:END:
#+TITLE: SKILL: Inbound Multi-Channel Gateway (Universal Literate Note)
#+STARTUP: content
#+FILETAGS: :gateway:sensors:io:autonomy:
* Overview
The *Inbound Multi-Channel Gateway* provides the sensory interface for external messaging. It enables the agent to "hear" the user from various platforms (Signal, Telegram, SMS) by normalizing disparate inbound payloads into standard Probabilistic-Deterministic Kernel stimuli.
* Phase A: Demand (PRD)
:PROPERTIES:
:STATUS: FROZEN
:END:
** 1. Purpose
Define a secure and extensible ingress for external communication channels.
** 2. User Needs
- *Multi-Channel Ingress:* Support Signal (via signal-cli), Telegram (via Bot API), and generic Webhooks.
- *Payload Normalization:* Convert platform-specific JSON into standard Lisp plists.
- *Security & Authentication:* Verify sender identity before injecting stimuli into the harness.
- *Asynchronous Reception:* Non-blocking monitoring of inbound message queues.
** 3. Success Criteria
*** TODO Signal-cli message reception and parsing
*** TODO Telegram Bot API webhook normalization
*** TODO Sender verification logic (Whitelisting)
*** TODO Autonomous stimulus injection into the harness Bus
* Phase B: Blueprint (PROTOCOL)
:PROPERTIES:
:STATUS: SIGNED
:END:
* Phase B: Blueprint (PROTOCOL)
:PROPERTIES:
:STATUS: DRAFT
:END:
** 1. Architectural Intent
The Inbound Gateway should operate as a modular, asynchronous service.
Each channel (Signal, Telegram, Webhook) will have its own adapter responsible for receiving and normalizing messages.
A central dispatcher will then authenticate and inject these normalized messages as stimuli into the Probabilistic-Deterministic Kernel’s message bus.
Error handling and logging will be crucial for observability and maintainability.
** 2. Semantic Interfaces (Lisp Signatures)
*** `inbound-message-handler`
- *Purpose:* Main entry point for processing inbound messages from all channels.
- *Signature:* `(inbound-message-handler channel message-payload)`
- *Arguments:*
- `channel` (keyword): Identifies the source channel (e.g., `:signal`, `:telegram`, `:webhook`).
- `message-payload` (string): The raw message payload received from the channel.
- *Returns:* Boolean indicating successful processing (T) or failure (NIL).
*** `normalize-message`
- *Purpose:* Converts a platform-specific message payload into a standard Lisp plist.
- *Signature:* `(normalize-message channel message-payload)`
- *Arguments:*
- `channel` (keyword): The source channel.
- `message-payload` (string): The raw message payload.
- *Returns:* A Lisp plist representing the normalized message. Example: `(:sender "+15551234567" :text "Hello, world!" :timestamp 1678886400)`.
*** `authenticate-sender`
- *Purpose:* Verifies the identity of the message sender based on the channel.
- *Signature:* `(authenticate-sender channel sender-id)`
- *Arguments:*
- `channel` (keyword): The source channel.
- `sender-id` (string): The sender's unique identifier (e.g., phone number for Signal, username for Telegram).
- *Returns:* Boolean indicating successful authentication (T) or failure (NIL). Consider using ACLs (Access Control Lists).
*** `inject-stimulus`
- *Purpose:* Injects a normalized message into the Probabilistic-Deterministic Kernel's message bus as a stimulus.
- *Signature:* `(inject-stimulus stimulus-plist)`
- *Arguments:*
- `stimulus-plist` (plist): The normalized message plist.
- *Returns:* A unique identifier for the injected stimulus.
*** `channel-listener`
- *Purpose:* Asynchronously listens for inbound messages on a specific channel.
- *Signature:* `(channel-listener channel-config)`
- *Arguments:*
- `channel-config` (plist): Configuration parameters specific to the channel (e.g., API key, webhook URL).
- *Returns:* (Non-blocking) N/A. The listener will spawn threads to handle incoming messages.
** 3. Example Flow (Signal)
1. `channel-listener` (for `:signal`) receives a new message via `signal-cli`.
2. The raw message is passed to `inbound-message-handler` with `channel` = `:signal`.
3. `inbound-message-handler` calls `normalize-message` to convert the Signal payload to a standard plist.
4. `inbound-message-handler` calls `authenticate-sender` to verify the sender's identity.
5. If authentication succeeds, `inbound-message-handler` calls `inject-stimulus` to inject the message into the harness.
6. Error handling and logging are performed at each step.

74
skills/org-skill-lisp-repair.org Normal file
View File

@@ -0,0 +1,74 @@
:PROPERTIES:
:ID: 1e5a2c30-d3a9-4674-8db7-b08e7e1f44d1
:CREATED: [2026-04-11 Sat 14:40]
:END:
#+TITLE: SKILL: Lisp Repair Syntax Gate
#+STARTUP: content
#+FILETAGS: :system:repair:syntax:lisp:autonomy:
* Overview
The *Lisp Repair Syntax Gate* asynchronously intercepts `:syntax-error` events emitted by the harness when Probabilistic Engine (LLM) proposals fail to parse. It performs deterministic or neural repairs and re-injects the corrected action into the pipeline.
* Implementation
** Core Repair Logic
#+begin_src lisp
(defun count-char (char string)
(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)."
(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 neural-repair (code error-message)
"Uses Probabilistic Engine to deeply repair the syntax structure."
(let ((prompt (format nil "The following Lisp code failed to parse.
ERROR: ~a
CODE: ~a
MANDATE: Output EXACTLY ONE valid Common Lisp list. Do not explain. Do not use markdown blocks."
error-message code))
(system-prompt "You are a Lisp Syntax Repair Actuator. Return only valid, balanced Lisp code."))
(let ((repaired (ask-probabilistic prompt :system-prompt system-prompt)))
(string-trim '(#\Space #\Newline #\Tab) repaired))))
#+end_src
** Skill Definition
Reacts to syntax error events and transforms them into repaired requests.
#+begin_src lisp
(defskill :skill-lisp-repair
:priority 90
:trigger (lambda (ctx) (eq (getf (getf ctx :payload) :sensor) :syntax-error))
:probabilistic nil ;; Handled deterministically in deterministic or manually via ask-probabilistic
:deterministic (lambda (action context)
(declare (ignore action))
(let* ((payload (getf context :payload))
(code (getf payload :code))
(error-msg (getf payload :error)))
(harness-log "SYNTAX GATE: Reacting to broken Lisp stimulus...")
(let ((fast-fix (deterministic-repair code)))
(handler-case
(let ((repaired (read-from-string fast-fix)))
(harness-log "SYNTAX GATE: Deterministic repair SUCCESS.")
repaired)
(error ()
(harness-log "SYNTAX GATE: Deterministic repair failed. Escalating...")
(let ((deep-fix (neural-repair code error-msg)))
(handler-case
(let ((repaired (read-from-string deep-fix)))
(harness-log "SYNTAX GATE: Neural repair SUCCESS.")
repaired)
(error ()
(harness-log "SYNTAX GATE: Neural repair failed.")
(list :type :LOG :payload (list :text "Lisp Repair Failed.")))))))))))
#+end_src

182
skills/org-skill-lisp-validator.org Normal file
View File

@@ -0,0 +1,182 @@
:PROPERTIES:
:ID: 98576df2-c496-4e4a-9acb-0bca514a0305
:CREATED: [2026-03-31 Tue 18:28]
:EDITED: [2026-04-09 Thu]
:END:
#+TITLE: SKILL: Lisp Validator
#+STARTUP: content
#+FILETAGS: :security:lisp:ast:autonomy:
* Overview
The *Lisp Validator* is the primary structural gate for the Probabilistic-Deterministic Lisp Machine. It provides a recursive AST validator that subjects all Lisp proposals from the Probabilistic Engine to a strict "Deny-by-Default" sandbox.
* Phase A: Demand (PRD)
:PROPERTIES:
:STATUS: FROZEN
:END:
** 1. Purpose
Define a high-integrity, recursive security sandbox for Lisp execution.
** 2. User Needs
- *Recursive Validation:* Every nested function call and variable access MUST be checked.
- *Deny-by-Default:* Only explicitly whitelisted functions and variables are permitted.
- *Eval Protection:* Block all forms of `eval`, `load`, or dynamic execution.
- *Deterministic Preemption:* This skill acts as a mandatory global Deterministic Engine check.
** 3. Success Criteria
*** DONE Implement recursive AST walker in Lisp
*** DONE Establish strict function whitelist (surgical Org operations)
*** DONE Detect and block nested 'eval' attempts
*** DONE Verify that malformed or malicious sexps are rejected
* Implementation
** Package
#+begin_src lisp
#+end_src
** Whitelist Definition
#+begin_src lisp
(defparameter *lisp-validator-whitelist*
'(;; Math & Logic
+ - * / = < > <= >= 1+ 1- min max
and or not null eq eql equal string= string-equal
;; List Manipulation
list cons car cdr cadr cddr cdar caar append mapcar remove-if remove-if-not
length reverse sort nth nthcdr push pop
;; Plists and Hash Tables
getf gethash
;; Control Flow
let let* if cond when unless case typecase
;; Strings
format concatenate string-downcase string-upcase search
;; Kernel specifics
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
opencortex::context-query-store
opencortex::context-get-active-projects
opencortex::context-get-recent-completed-tasks
opencortex::context-list-all-skills
opencortex::context-get-system-logs
opencortex::context-assemble-global-awareness
opencortex::org-object-id
opencortex::org-object-type
opencortex::org-object-attributes
opencortex::org-object-content
opencortex::org-object-parent-id
opencortex::org-object-children
opencortex::org-object-version
opencortex::org-object-last-sync
opencortex::org-object-hash
;; Essential macros
declare ignore
;; Let's also add simple data types
t nil quote function))
#+end_src
** Dynamic Symbol Registration
We allow other skills to register safe symbols for the validator.
#+begin_src lisp
(defvar *lisp-validator-registry* nil
"List of dynamically registered safe symbols.")
(defun lisp-validator-register (symbols)
"Adds symbols to the global validator registry."
(setf *lisp-validator-registry* (append *lisp-validator-registry* (if (listp symbols) symbols (list symbols))))
(harness-log "LISP VALIDATOR: Registered ~a new safe symbols." (length (if (listp symbols) symbols (list symbols)))))
(defun lisp-validator-is-safe (symbol)
"Checks if a symbol is in the static whitelist or the dynamic registry."
(or (member symbol *lisp-validator-whitelist* :test #'string-equal)
(member symbol *lisp-validator-registry* :test #'string-equal)))
#+end_src
** Recursive AST Walker
#+begin_src lisp
(defun lisp-validator-ast-walk (form)
"Recursively walks the Lisp AST. Returns T if safe, NIL if unsafe."
(cond
;; Self-evaluating objects (strings, numbers, keywords) are safe.
((or (stringp form) (numberp form) (keywordp form) (characterp form))
t)
;; Symbols used as variables (in non-function position)
((symbolp form)
(lisp-validator-is-safe form))
;; Lists represent function calls or special forms.
((listp form)
(let ((head (car form)))
(cond
((eq head 'quote) t)
((not (symbolp head)) nil)
((lisp-validator-is-safe head)
(every #'lisp-validator-ast-walk (cdr form)))
(t
(harness-log "LISP VALIDATOR: Blocked call to non-whitelisted function ~a" head)
nil))))
(t nil)))
#+end_src
** Cognitive Tools
#+begin_src lisp
(opencortex:def-cognitive-tool :lisp-validator-status "Returns validator-related telemetry, including blocked actions and harness status."
nil
:body (lambda (args)
(declare (ignore args))
(format nil "LISP VALIDATOR STATUS:
- Static Whitelist: ~a symbols
- Dynamic Registry: ~a symbols
- Total Blocked Actions: ~a"
(length *lisp-validator-whitelist*)
(length *lisp-validator-registry*)
"Not implemented")))
#+end_src
** Skill Definition
#+begin_src lisp
(opencortex:defskill :skill-lisp-validator
:priority 900 ; High priority, before most skills
:trigger (lambda (ctx)
;; Check if any proposed action is an :eval or :shell call
(let ((candidate (getf ctx :candidate)))
(when candidate
(let ((payload (getf candidate :payload)))
(member (getf payload :action) '(:eval :shell))))))
:probabilistic nil ; Purely deterministic/safety skill
:deterministic (lambda (action context)
(harness-log "DETERMINISTIC ENGINE [Lisp-Validator]: Intercepted critical action for structural validation.")
action))
#+end_src
* Phase E: Chaos (Verification)
#+begin_src lisp
(defpackage :opencortex-lisp-validator-tests
(:use :cl :fiveam :opencortex)
(:export #:lisp-validator-suite))
(in-package :opencortex-lisp-validator-tests)
(def-suite lisp-validator-suite :description "Tests for the Lisp Validator.")
(in-suite lisp-validator-suite)
(test test-basic-math-safe
(is (opencortex:lisp-validator-validate "(+ 1 2)")))
(test test-blocked-eval
(is (not (opencortex:lisp-validator-validate "(eval '(+ 1 2))"))))
(test test-blocked-shell
(is (not (opencortex:lisp-validator-validate "(uiop:run-program \"ls\")"))))
(test test-nested-unsafe
(is (not (opencortex:lisp-validator-validate "(let ((x 1)) (delete-file \"test.txt\"))"))))
(test test-safe-kernel-api
(is (opencortex:lisp-validator-validate "(opencortex::lookup-object \"node-1\")")))
#+end_src

83
skills/org-skill-memex.org Normal file
View File

@@ -0,0 +1,83 @@
:PROPERTIES:
:ID: 3cf112fa-c8f6-4649-8d0f-96cde70d8807
:CREATED: [2026-03-31 Tue 13:03]
:EDITED: [2026-04-07 Tue 13:42]
:END:
#+TITLE: SKILL: Memex Manager (Universal Literate Note)
#+STARTUP: content
#+FILETAGS: :memex:gtd:zettelkasten:integrity:autonomy:
* Overview
The *Memex Manager* is the primary automation engine for the Personal Knowledge Management system. It enforces metadata standards, automates task lifecycles, and distills ephemeral daily logs into timeless knowledge.
* Phase A: Demand (PRD)
:PROPERTIES:
:STATUS: FROZEN
:END:
** 1. Purpose
Define automated behaviors for knowledge and task management integrity.
** 2. User Needs
- *Unified Capture:* Landing all new information in `inbox.org`.
- *Metadata Compliance:* Mandatory `:CREATED:` and `:LOGBOOK:` drawers.
- *Automated Task Lifecycle:* `NEXT` promotion logic for GTD.
- *Mobile Autonomousty:* Compatibility with Markor and Orgzly.
- *Agentic Distillation:* Extracting evergreen concepts from daily logs.
** 3. Success Criteria
*** TODO Metadata Audit Accuracy
*** TODO Task Promotion Verification
*** TODO Note Distillation Provenance
* Phase B: Blueprint (PROTOCOL)
:PROPERTIES:
:STATUS: SIGNED
:END:
* Phase B: Blueprint (PROTOCOL)
:PROPERTIES:
:STATUS: DRAFT
:END:
** 1. Architectural Intent
The Memex Manager is designed as a collection of independent, composable functions orchestrated by Emacs Lisp. We prioritize modularity, testability, and adherence to functional programming principles. Each function addresses a specific aspect of PKM automation. The system should be easily extensible to accommodate new workflows and data sources. Core functions must be idempotent where applicable, and failures must be gracefully handled with informative logging. The system will interact with Org mode files primarily via the `org.el` library and file system operations. Error reporting should use Emacs' built-in mechanisms.
** 2. Semantic Interfaces (Lisp Signatures)
*** `memex-capture-unified (content &key source)`
- *Purpose:* Append `content` to `inbox.org`, tagging with `source`.
- *Input:*
- `content`: String, the text to be captured.
- `source`: Keyword, indicating the origin (e.g., `:email`, `:web`, `:cli`).
- *Output:* Boolean, `t` on success, `nil` on failure.
- *Side Effects:* Modifies `inbox.org`.
- *Example:* `(memex-capture-unified "New idea from a book" :source :book)`
*** `memex-metadata-enforce (filepath)`
- *Purpose:* Ensure `:CREATED:` and `:LOGBOOK:` drawers exist and are populated in the Org file at `filepath`.
- *Input:* `filepath`: String, the path to the Org file.
- *Output:* Boolean, `t` if metadata is compliant, `nil` if not (and log warnings.)
- *Side Effects:* Potentially modifies the Org file.
- *Example:* `(memex-metadata-enforce "/home/user/memex/notes/some-new-note.org")`
*** `memex-task-promote (filepath &key heading)`
- *Purpose:* Advance the GTD status of the task matching `heading` within `filepath` (NEXT -> DOING -> REVIEW -> DONE).
- *Input:*
- `filepath`: String, the path to the Org file.
- `heading`: String, the exact text of the Org mode heading for the task.
- *Output:* Boolean, `t` on success, `nil` if the task isn't found or promotion fails.
- *Side Effects:* Modifies the Org file if the task is promoted.
- *Example:* `(memex-task-promote "/home/user/memex/tasks.org" :heading "Implement file sync")`
*** `memex-distill-notes (logfile &key keywords)`
- *Purpose:* Extract and create evergreen notes from a daily log file.
- *Input:*
- `logfile`: String, the path to the daily log Org file.
- `keywords`: List of strings. Focuses extraction based on keywords.
- *Output:* List of strings, representing the filepaths of the newly created evergreen notes extracted from the log.
- *Side Effects:* Creates one or more new Org files for the distilled concepts.
- *Example:* `(memex-distill-notes "/home/user/memex/daily/2024-10-27.org" :keywords '("spaced repetition" "zettelkasten"))`

70
skills/org-skill-onboarding.org Normal file
View File

@@ -0,0 +1,70 @@
:PROPERTIES:
:ID: 4ed67571-bde3-44f9-93d1-f5b2aef5f26b
:CREATED: [2026-03-31 Tue 18:13]
:EDITED: [2026-04-07 Tue 13:42]
:END:
#+TITLE: SKILL: Onboarding & Calibration (Universal Literate Note)
#+STARTUP: content
#+FILETAGS: :onboarding:calibration:setup:autonomy:
* Overview
The *Onboarding Skill* ensures that the Lisp Machine environment is correctly calibrated. It automates the "zero-to-one" setup of the Probabilistic-Deterministic Kernel, including path normalization, identity personalization, and provider/actuator configuration.
* Phase A: Demand (PRD)
:PROPERTIES:
:STATUS: FROZEN
:END:
** 1. Purpose
Define automated behaviors for verifying and configuring the opencortex environment.
** 2. User Needs
- *Environment Verification:* Confirm SBCL, Quicklisp, and core binaries are present.
- *Path Calibration:* Resolve absolute paths for the Memex PARA structure.
- *Neural Calibration:* Interactive selection of LLM providers and models.
- *Actuator Calibration:* Interactive setup of delivery channels (Signal, Telegram, etc.).
- *Identity Persona:* Establish $MEMEX_USER and $MEMEX_ASSISTANT.
** 3. Success Criteria
*** TODO SBCL/Quicklisp Verification Logic
*** TODO Automated .env Generation from Template
*** TODO Model Tiering Property Injection
*** TODO Delivery Channel Actuator Verification
* Phase B: Blueprint (PROTOCOL)
:PROPERTIES:
:STATUS: SIGNED
:END:
* Phase B: Blueprint (PROTOCOL)
:PROPERTIES:
:STATUS: DRAFT
:END:
** 1. Architectural Intent
The Onboarding Protocol aims for a modular, extensible, and interactive configuration process. We will leverage Lisp's interactive environment and metaprogramming capabilities to guide the user through setup and validation. The core principle is *gradual disclosure* and *progressive enhancement*. The system first checks for minimal requirements and then interactively enhances the configuration. Configuration data is stored in a `.env` file, ensuring persistence and easy modification. Modules (Actors in the system) are responsible for specific aspects of configuration and are designed to be easily added or modified. Error handling is proactive, guiding the user through resolution steps rather than crashing. Logging and audit trails will be implemented.
** 2. Semantic Interfaces (Lisp Signatures)
*** `verify-system-dependencies &key (sbcl-present-p t) (quicklisp-present-p t) -> boolean`
Verifies the presence and basic functionality of essential system dependencies like SBCL and Quicklisp. Returns `T` if all specified dependencies are met, `NIL` otherwise. Accepts keyword arguments to selectively disable verification of specific dependencies (useful during development).
*** `calibrate-memex-paths &key (memex-root "/home/user/memex/") -> plist`
Interactively guides the user to define the absolute paths for the Memex PARA structure (Projects, Areas, Resources, Archive). Stores these paths in a plist and updates the `.env` file. `memex-root` provides a default value; the user can override this. Returns a plist of the form `(:projects "/path/to/projects/" :areas "/path/to/areas/" ...)`
*** `calibrate-neural-provider &key (default-provider :openai) (default-model "gpt-3.5-turbo") -> plist`
Presents the user with a choice of LLM providers and models. Validates API keys (if required) and stores the chosen provider, model, and API key in the `.env` file. `default-provider` and `default-model` provide starting defaults. Returns a plist of the form `(:provider :openai :model "gpt-4" :api-key "sk-...")`
*** `configure-delivery-channel &key (channel-type :signal) -> plist`
Guides the user through the configuration of a specific delivery channel (e.g., Signal, Telegram). Interactively prompts for necessary credentials and validates the configuration. Returns configurations as plist, containing `:channel-type` and other necessary credentials, e.g., `(:channel-type :signal :phone-number "+15551234567" :signal-cli-path "/usr/bin/signal-cli")`
*** `setup-identity &key (memex-user "user") (memex-assistant "Assistant") -> plist`
Sets up the `$MEMEX_USER` and `$MEMEX_ASSISTANT` environment variables, allowing customization of the user and assistant names used within the Lisp Machine. Interactively prompts the user for confirmation or modification of the default values. Returns a plist `(:memex-user "NewUser" :memex-assistant "NewAssistant")`.
*** `generate-env-file &key (template-path "/path/to/default/.env.template") (output-path ".env") (config-data plist) -> boolean`
Generates the `.env` file from a template, populating it with the configuration data gathered from the other calibration functions. Returns `T` on success, `NIL` on failure.
*** `validate-env-variables -> plist`
Validates .env variables are set and functional for the harness, actuators, and models. Returns a plist `(:kernel t :actuators t :models t)`. This is the main test before boot.

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

@@ -0,0 +1,37 @@
:PROPERTIES:
:ID: 9d3fe6c3-904c-4750-ad37-0364ad0c4dde
:CREATED: [2026-04-12 Sun 20:00]
:END:
#+TITLE: SKILL: Policy Enforcer
#+STARTUP: content
#+FILETAGS: :security:alignment:policy:autonomy:
#+DEPENDS_ON: id:47425a43-2be0-423c-8509-22592cfe9c9e
* Overview
The *Policy Enforcer* is the deterministic gate that ensures all probabilistic proposals adhere to the Core Invariants defined in the [[id:47425a43-2be0-423c-8509-22592cfe9c9e][System Policy]].
** Architectural Intent: The Implicit Bridge
Unlike traditional software where a "Kernel" might have hardcoded rules, the OpenCortex harness is a "dumb" pipeline. This skill creates the bridge between human-readable rules and machine-enforced constraints through three mechanisms:
1. **Topological Bootstrapping:** By declaring a #+DEPENDS_ON: dependency on the Policy file's ID, we ensure the System Policy is always registered in the Lisp image's skill catalog before this enforcer attempts to guard it.
2. **Priority Preemption:** By setting :priority 1000, this skill registers itself as the very first check in the decide-gate. It effectively "pre-empts" all other skills, ensuring that no action (like a shell command or a file write) is even considered until it has cleared the alignment check.
3. **Decoupled Enforcement:** The harness does not "know" it is enforcing a policy. It simply executes the highest-priority deterministic functions provided by its skills. This allows the Autonomous to swap out policies or enforcers without ever touching the core harness code.
* Implementation
#+begin_src lisp
(defskill :skill-policy-enforcer
:priority 1000 ; Absolute highest priority
:trigger (lambda (context) t) ; Always active as a fallback
:probabilistic (lambda (context)
\"You are the OpenCortex Policy Enforcer. Your goal is to ensure all actions empower the user through the Lisp Machine and adhere to the System Policy.\")
:deterministic (lambda (action context)
;; Basic invariant check: Block actions that appear to violate autonomy
(let ((payload (getf action :payload)))
(if (and payload (search \"proprietary\" (format nil \"~s\" payload)))
(progn
(opencortex:harness-log \"DETERMINISTIC [Policy]: Autonomy violation suspected. Blocking action.\")
nil)
action))))
#+end_src

97
skills/org-skill-self-fix.org Normal file
View File

@@ -0,0 +1,97 @@
:PROPERTIES:
:ID: 65891ce2-a465-49e6-a0c1-be13d3288d55
:CREATED: [2026-03-30 Mon 21:16]
:EDITED: [2026-04-09 Thu]
:END:
#+TITLE: SKILL: Self-Fix Agent (Universal Literate Note)
#+STARTUP: content
#+FILETAGS: :self-repair:autonomy:debugging:autonomy:
#+DEPENDS_ON: id:0ae190ec-5991-49b5-9038-f860548a3a0c
#+DEPENDS_ON: id:98576df2-c496-4e4a-9acb-0bca514a0305
* Overview
The *Self-Fix Agent* is the system's "Repair Mechanism." It takes failure hypotheses, applies surgical code modifications, and verifies them using the Memory's rollback capabilities.
* Phase D: Build (Implementation)
** Repair Logic
#+begin_src lisp
(defun self-fix-apply (action context)
"Applies a surgical code fix and reloads the modified skill."
(declare (ignore context))
(let* ((payload (getf action :payload))
(target-file (getf payload :file))
(old-code (getf payload :old))
(new-code (getf payload :new))
(is-skill (and (stringp (namestring target-file))
(search "skills/" (namestring target-file)))))
(opencortex:snapshot-memory)
(opencortex:harness-log "SELF-FIX - Attempting surgical fix on ~a..." target-file)
(handler-case
(if (uiop:file-exists-p target-file)
(let ((content (uiop:read-file-string target-file)))
(if (search old-code content)
(let ((new-content (cl-ppcre:regex-replace-all (cl-ppcre:quote-meta-chars old-code) content new-code)))
(with-open-file (out target-file :direction :output :if-exists :supersede)
(write-string new-content out))
(if is-skill
(progn
(opencortex:harness-log "SELF-FIX - Reloading modified skill ~a..." target-file)
(if (opencortex:load-skill-from-org target-file)
(progn
(opencortex:harness-log "SELF-FIX SUCCESS - Applied and reloaded.")
t)
(progn
(opencortex:harness-log "SELF-FIX FAILURE - Skill reload failed. Rolling back.")
(with-open-file (out target-file :direction :output :if-exists :supersede)
(write-string content out))
(opencortex:rollback-memory 0)
nil)))
(progn
(opencortex:harness-log "SELF-FIX SUCCESS - Applied fix to file.")
t)))
(progn (opencortex:harness-log "SELF-FIX FAILURE - Pattern not found.") nil)))
(progn (opencortex:harness-log "SELF-FIX FAILURE - File not found.") nil))
(error (c)
(opencortex:harness-log "SELF-FIX CRASH - ~a. Rolling back." c)
(opencortex:rollback-memory 0)
nil))))
#+end_src
** Registration
#+begin_src lisp
(def-cognitive-tool :repair-file
"Applies a surgical code modification to a file and reloads the skill if applicable."
((:file :type :string :description "Path to the target file")
(:old :type :string :description "The literal code block to find")
(:new :type :string :description "The literal code block to replace it with"))
:body (lambda (args)
(if (self-fix-apply (list :payload args) nil)
"REPAIR SUCCESSFUL."
"REPAIR FAILED.")))
#+end_src
** Skill Definition
#+begin_src lisp
(opencortex:defskill :skill-self-fix
:priority 95
:trigger (lambda (context) (eq (getf (getf context :payload) :sensor) :repair-request))
:probabilistic (lambda (context)
(format nil "You are the opencortex Repair Actuator. Synthesize a surgical fix for the reported failure.
Return a Lisp plist for :repair-file."))
:deterministic (lambda (action context)
(let ((payload (getf action :payload)))
(self-fix-apply action context))))
#+end_src
* Phase B: Blueprint (PROTOCOL)
:PROPERTIES:
:STATUS: SIGNED
:END:
** 1. Architectural IntentnEstablish core functional interfaces for this skill.\n\n** 2. Semantic Interfaces\n(defun trigger-skill-org-skill-self-fix (context))\n(defun probabilistic-skill-org-skill-self-fix (context))

269
skills/org-skill-state-persistence.org Normal file
View File

@@ -0,0 +1,269 @@
:PROPERTIES:
:ID: state-persistence-skill
:CREATED: [2026-04-09 Thu]
:END:
#+TITLE: SKILL: State Persistence Layer (Universal Literate Note)
#+STARTUP: content
#+FILETAGS: :memory:persistence:closos:ipfs:autonomy:
* Overview
The *State Persistence Layer* ensures the durability and autonomousty of the agent's memory. It unifies local, high-performance Lisp image dumps with decentralized, immutable IPFS checkpointing. This dual-path approach provides both rapid operational recovery and long-term historical integrity.
** Deep Reasoning: Protection Against External Tampering
While the *Prover* and *Bouncer* protect against internal skill failures, the Merkle-Tree architecture within the State Layer protects against **External Threats** (e.g., a hacker or virus modifying your `.org` files directly on disk).
1. **Skill Hashing:** Every code block and headline in a skill file has a unique Merkle hash recorded in the Memory.
2. **Integrity Verification:** Upon loading or reloading a skill, the harness re-calculates the hash and compares it against the "known good" state in the Merkle Tree.
3. **Automatic Lockdown:** If a file has been tampered with externally, the hash mismatch triggers an immediate lockdown. the harness refuses to execute the skill and alerts the Autonomous via Signal/Telegram.
* Phase A: Demand (PRD)
:PROPERTIES:
:STATUS: SIGNED
:END:
** 1. Purpose
Define automated behaviors for knowledge graph serialization, local persistence, and decentralized archival.
** 2. User Needs
- *Instant Recall:* Rapid local loading of the Memory from a persistent image.
- *Decentralized Archival:* Pushing immutable snapshots to IPFS for cross-node sync and autonomousty.
- *Merkle Integrity:* Every save operation must respect and record the Merkle-Tree history.
- *Safety:* Sanitize and validate data during restoration to prevent code injection.
* Phase B: Blueprint (PROTOCOL)
:PROPERTIES:
:STATUS: SIGNED
:END:
** 1. Architectural Intent
The persistence layer acts as a bridge between the volatile RAM-resident Memory and permanent storage backends. It provides two adapters: `LOCAL` (fast, SBCL-native) and `IPFS` (autonomous, content-addressed).
** 2. Semantic Interfaces
#+begin_src lisp
(defun persistence-dump-local ()
"Serializes RAM state to a local Lisp image file.")
(defun persistence-push-ipfs ()
"Pushes an immutable snapshot of the graph to IPFS.")
(defun persistence-restore-ipfs (cid)
"Hydrates the RAM state from an IPFS content identifier.")
#+end_src
* Phase C: Success (QUALITY)
:PROPERTIES:
:STATUS: SIGNED
:END:
** 1. Success Criteria
- [ ] *Speed:* Local image load must be <500ms for a 10k node graph.
- [ ] *Fidelity:* IPFS round-trip must result in a bit-identical Memory.
- [ ] *Validation:* Restoration must block any `read-eval` reader macros in content.
** 2. TDD Plan
Tests in `tests/persistence-tests.lisp` will verify the local dump/load cycle and the JSON serialization format for IPFS.
* Phase D: Build (Implementation)
** Package Context
#+begin_src lisp
;; Skill logic is evaluated in a jailed package by the Harness.
#+end_src
** Helper: Local State Path
Ensures we have a standardized location for local memory images.
#+begin_src lisp
(defun persistence-get-local-path ()
"Returns the path to the local memory image file."
(let ((state-dir (or (uiop:getenv "SYSTEM_DIR") "system/")))
(merge-pathnames "state/memory-image.lisp" state-dir)))
#+end_src
** Local Image Dump (persistence-dump-local)
Serializes the Merkle history and current pointers to a Lisp file.
#+begin_src lisp
(defun persistence-dump-local ()
"Serializes the entire history store and current pointers to a local Lisp image."
(let ((image-file (persistence-get-local-path)))
(ensure-directories-exist image-file)
(harness-log "PERSISTENCE - Dumping local image to ~a..." (uiop:native-namestring image-file))
(with-open-file (out image-file :direction :output :if-exists :supersede)
(format out "~%")
;; 1. Dump all immutable objects in the history store
(maphash (lambda (hash obj)
(print `(setf (gethash ,hash *history-store*) ,obj) out))
*history-store*)
;; 2. Dump the current active pointers
(maphash (lambda (id obj)
(print `(setf (gethash ,id *memory*) (gethash ,(org-object-hash obj) *history-store*)) out))
*memory*))
t))
#+end_src
** Local Image Load (persistence-load-local)
Restores the state from the local disk.
#+begin_src lisp
(defun persistence-load-local ()
"Loads the memory image from local disk."
(let ((image-file (persistence-get-local-path)))
(if (uiop:file-exists-p image-file)
(progn
(harness-log "PERSISTENCE - Loading local image...")
(load image-file)
t)
(progn
(harness-log "PERSISTENCE ERROR - Local image not found.")
nil))))
#+end_src
** IPFS Serialization (persistence-serialize-for-archival)
Converts the live `*memory*` into a list of Lisp Property Lists (Plists) for autonomous, homoiconic transport.
#+begin_src lisp
(defun persistence-serialize-for-archival ()
"Serializes the entire memory for IPFS transport as native S-Expressions."
(let ((objects nil))
(maphash (lambda (id obj)
(declare (ignore id))
(push (list :id (org-object-id obj)
:type (org-object-type obj)
:attributes (org-object-attributes obj)
:content (org-object-content obj)
:parent-id (org-object-parent-id obj)
:children (org-object-children obj)
:version (org-object-version obj)
:last-sync (org-object-last-sync obj)
:hash (org-object-hash obj))
objects))
*memory*)
objects))
#+end_src
** IPFS Push (persistence-push-ipfs)
Pushes the serialized knowledge graph to the decentralized network as a Lisp string.
#+begin_src lisp
(defun persistence-push-ipfs ()
"Serializes the store and pushes it to IPFS as a Lisp text block, returning the CID."
(let* ((data (persistence-serialize-for-archival))
(lisp-payload (format nil "~s" data))
(ipfs-url "http://127.0.0.1:5001/api/v0/add"))
(handler-case
(let* ((response (dex:post ipfs-url
:content `(("file" . ,lisp-payload))
:headers '(("Content-Type" . "multipart/form-data"))))
(result-str (flexi-streams:octets-to-string response))
(start-idx (search "\"Hash\":\"" result-str))
(cid (when start-idx
(let* ((val-start (+ start-idx 8))
(val-end (position #\" result-str :start val-start)))
(subseq result-str val-start val-end)))))
(harness-log "PERSISTENCE - Checkpoint to IPFS successful. CID: ~a" cid)
cid)
(error (c)
(harness-log "PERSISTENCE ERROR - IPFS push failed: ~a" c)
nil))))
#+end_src
** IPFS Restore (persistence-restore-ipfs)
Restores the graph from IPFS, using `read-from-string` with `*read-eval* nil` to prevent injection.
#+begin_src lisp
(defun persistence-restore-ipfs (cid)
"Fetches data from IPFS and safely hydrates the memory."
(let ((ipfs-url (format nil "http://127.0.0.1:5001/api/v0/cat?arg=~a" cid)))
(handler-case
(let* ((response (dex:post ipfs-url))
(payload-str (flexi-streams:octets-to-string response)))
(let ((*read-eval* nil))
(let ((data (read-from-string payload-str)))
(clrhash *memory*)
(dolist (item data)
(let* ((id (getf item :id))
(obj (make-org-object
:id id
:type (getf item :type)
:attributes (getf item :attributes)
:content (getf item :content)
:parent-id (getf item :parent-id)
:children (getf item :children)
:version (getf item :version)
:last-sync (getf item :last-sync)
:hash (getf item :hash))))
(setf (gethash id *memory*) obj)))
(harness-log "PERSISTENCE - Restored from IPFS: ~a" cid)
t)))
(error (c)
(harness-log "PERSISTENCE ERROR - IPFS restoration failed: ~a" c)
nil))))
#+end_src
** Cognitive Tools
Expose persistence capabilities to the neural Probabilistic Engine.
#+begin_src lisp
(progn
(def-cognitive-tool :checkpoint-memory "Creates both a local image and a decentralized IPFS snapshot." nil
:body (lambda (args)
(declare (ignore args))
(persistence-dump-local)
(let ((cid (persistence-push-ipfs)))
(format nil "Local dump complete. IPFS CID: ~a" (or cid "FAILED")))))
(def-cognitive-tool :restore-memory "Restores the state from a specific source."
((:source :type :keyword :description "Either :LOCAL or :IPFS")
(:cid :type :string :description "Required if source is :IPFS"))
:body (lambda (args)
(case (getf args :source)
(:local (if (persistence-load-local) "Restored from disk." "Local restore failed."))
(:ipfs (if (persistence-restore-ipfs (getf args :cid)) "Restored from network." "IPFS restore failed."))))))
#+end_src
** Registration
#+begin_src lisp
(defskill :skill-state-persistence
:priority 100
:trigger (lambda (ctx)
(let ((sensor (getf (getf ctx :payload) :sensor)))
(member sensor '(:heartbeat :manual-persist))))
:probabilistic nil
:deterministic (lambda (action ctx)
(persistence-dump-local)
action))
#+end_src
* Phase E: Chaos (Verification)
** 1. Unit Tests (FiveAM)
#+begin_src lisp
(defpackage :opencortex-persistence-tests
(:use :cl :fiveam :opencortex))
(in-package :opencortex-persistence-tests)
(def-suite persistence-suite :description "Tests for State Persistence Layer.")
(in-suite persistence-suite)
(test test-local-roundtrip
"Ensure RAM -> Disk -> RAM preserves data integrity."
(let ((test-id "persist-test-1")
(test-hash "fake-hash-123"))
(let ((obj (make-org-object :id test-id :content "Integrity Check" :hash test-hash)))
(setf (gethash test-hash *history-store*) obj)
(setf (gethash test-id *memory*) obj))
(opencortex:persistence-dump-local)
(clrhash *memory*)
(clrhash *history-store*)
(opencortex:persistence-load-local)
(is (not (null (gethash test-id *memory*))))
(is (equal "Integrity Check" (org-object-content (gethash test-id *memory*))))))
#+end_src
** 2. Chaos Scenarios
- *Scenario A (IPFS Daemon Down):* Kill the IPFS daemon and verify `persistence-push-ipfs` returns a standardized error instead of hanging the harness.
- *Scenario B (Corrupt Image):* Intentionally mangle the `memory-image.lisp` file and verify the loader catches the error during `load` and falls back to a clean state.
* Phase F: Memory (RCA)
- *[2026-04-09 Thu]:* Unified local SBCL image dumps with IPFS decentralized snapshots. Implemented safety-first restoration logic.

96
skills/org-skill-task-integrity.org Normal file
View File

@@ -0,0 +1,96 @@
:PROPERTIES:
:ID: 74f65792-1bf2-4b33-ab1a-e8a4830143fb
:CREATED: [2026-03-30 Mon 21:16]
:EDITED: [2026-04-07 Tue 13:42]
:END:
#+TITLE: SKILL: Task Integrity Agent (Universal Literate Note)
#+STARTUP: content
#+FILETAGS: :gtd:integrity:safety:autonomy:
* Overview
The *Task Integrity Agent* is the "Guardian" of the GTD system. It ensures that all task transitions adhere to semantic rules, preventing logical inconsistencies and maintaining the structural health of the task hierarchy.
* Phase A: Demand (PRD)
:PROPERTIES:
:STATUS: FROZEN
:END:
** 1. Purpose
Define automated behaviors for GTD state consistency and dependency verification.
** 2. User Needs
- *Semantic Enforcement:* Valid state transitions (Active vs. Resolved).
- *Dependency Awareness:* Block closing parents with active children.
- *Proactive Assistance:* Suggesting next logical actions based on momentum.
- *Fidelity:* Preservation of metadata during state transitions.
** 3. Success Criteria
*** TODO Semantic Category Mapping
*** TODO Active Children Detection
*** TODO State Transition Block Verification
* Phase B: Blueprint (PROTOCOL)
:PROPERTIES:
:STATUS: SIGNED
:END:
* Implementation
** Semantic Mapping
#+begin_src lisp
(defun semantic-mapping (task-state)
"Maps Org-mode task states to semantic categories."
(case (intern (string-upcase task-state) :keyword)
((:todo :active :started :wait) :active)
((:done :cancelled :resolved) :resolved)
(t :unknown)))
#+end_src
** Active Children Detection
#+begin_src lisp
(defun detect-active-children (task-id)
"Checks if a task has any child tasks in an active state."
(let ((children (list-objects-with-attribute :PARENT task-id)))
(remove-if-not (lambda (child)
(let ((todo (getf (org-object-attributes child) :TODO)))
(and todo (eq (semantic-mapping todo) :active))))
children)))
#+end_src
** Integrity Check (task-integrity-check)
Enforces high-integrity semantic rules for task management.
#+begin_src lisp
(defun task-integrity-check (action)
"Enforces semantic GTD integrity rules on proposed actions."
(let* ((payload (getf action :payload))
(act (or (getf payload :action) (getf action :action)))
(id (or (getf payload :id) (getf action :id)))
(new-attrs (or (getf payload :attributes) (getf action :attributes))))
(when (and (eq act :update-node)
(equal (getf new-attrs :TODO) "DONE"))
(let ((active-children (detect-active-children id)))
(when active-children
(return-from task-integrity-check
(format nil "Blocked by Task Integrity: ~a active children exist." (length active-children))))))
nil))
#+begin_src
** Skill Definition
#+begin_src lisp
(defskill :skill-task-integrity
:priority 90
:trigger (lambda (ctx) (declare (ignore ctx)) nil)
:probabilistic nil
:deterministic (lambda (action context)
(declare (ignore context))
(let ((err (task-integrity-check action)))
(if err
(list :type :LOG :payload (list :text err))
action))))
#+end_src