From af24f239dafe7710f6e5a195e99ad075e2df629a Mon Sep 17 00:00:00 2001 From: Amr Gharbeia Date: Thu, 9 Apr 2026 15:42:39 -0400 Subject: [PATCH] chore: cleanup notes/ after skill migration to submodule --- notes/org-skill-agent.org | 90 ---------- notes/org-skill-architect.org | 136 --------------- notes/org-skill-ast-normalization.org | 66 -------- notes/org-skill-atomic-notes.org | 93 ----------- notes/org-skill-auth-api-key.org | 56 ------- notes/org-skill-auth-google-oauth.org | 59 ------- notes/org-skill-brain-mapper.org | 111 ------------- notes/org-skill-chaos.org | 133 --------------- notes/org-skill-chat.org | 108 ------------ notes/org-skill-consensus.org | 101 ------------ notes/org-skill-context-manager.org | 74 --------- notes/org-skill-creator.org | 84 ---------- notes/org-skill-cron.org | 111 ------------- notes/org-skill-delegation.org | 76 --------- notes/org-skill-diagrammer.org | 103 ------------ notes/org-skill-dotemacs.org | 60 ------- notes/org-skill-emacs-bridge.org | 104 ------------ notes/org-skill-embedding-generator.org | 80 --------- notes/org-skill-environment-config.org | 69 -------- notes/org-skill-formal-verification.org | 137 --------------- notes/org-skill-function-calling.org | 89 ---------- notes/org-skill-git-steward.org | 109 ------------ notes/org-skill-groomer.org | 27 --- notes/org-skill-gtd.org | 66 -------- notes/org-skill-hardware-inhabitation.org | 84 ---------- notes/org-skill-hook-manager.org | 75 --------- notes/org-skill-hyper-graph.org | 61 ------- notes/org-skill-inbound-gateway.org | 100 ----------- notes/org-skill-inbox-processor.org | 86 ---------- notes/org-skill-infrastructure.org | 59 ------- notes/org-skill-ipfs.org | 63 ------- notes/org-skill-linkedin.org | 156 ------------------ notes/org-skill-lisp-machine-bootstrap.org | 59 ------- notes/org-skill-log-aggregator.org | 81 --------- notes/org-skill-long-horizon.org | 31 ---- notes/org-skill-memex.org | 83 ---------- notes/org-skill-model-explorer.org | 12 -- notes/org-skill-object-store-persistence.org | 74 --------- notes/org-skill-onboarding.org | 70 -------- notes/org-skill-org-delivery.org | 64 ------- .../org-skill-org-gtd-archive-roam-daily.org | 89 ---------- notes/org-skill-org-json-bridge.org | 72 -------- notes/org-skill-org-mode.org | 131 --------------- notes/org-skill-project-foundry.org | 148 ----------------- notes/org-skill-project-manager.org | 87 ---------- notes/org-skill-provider-anthropic.org | 79 --------- notes/org-skill-provider-gemini.org | 87 ---------- notes/org-skill-provider-groq.org | 72 -------- notes/org-skill-provider-ollama.org | 144 ---------------- notes/org-skill-provider-openai.org | 84 ---------- notes/org-skill-provider-openrouter.org | 126 -------------- notes/org-skill-router.org | 70 -------- notes/org-skill-safety-harness.org | 95 ----------- notes/org-skill-scientist.org | 67 -------- notes/org-skill-scribe-rca.org | 64 ------- notes/org-skill-scribe.org | 104 ------------ notes/org-skill-self-fix.org | 90 ---------- notes/org-skill-shell-actuator.org | 146 ---------------- notes/org-skill-sub-agent-manager.org | 82 --------- notes/org-skill-task-integrity.org | 77 --------- notes/org-skill-tdd-runner.org | 85 ---------- notes/org-skill-tech-analyst.org | 133 --------------- notes/org-skill-token-accountant.org | 92 ----------- notes/org-skill-web-interface.org | 92 ----------- notes/org-skill-web-research.org | 132 --------------- notes/org-skill-workspace-manager.org | 90 ---------- peripheral-vision-plan.md | 32 ++++ pipeline-refactor.md | 37 +++++ 68 files changed, 69 insertions(+), 5838 deletions(-) delete mode 100644 notes/org-skill-agent.org delete mode 100644 notes/org-skill-architect.org delete mode 100644 notes/org-skill-ast-normalization.org delete mode 100644 notes/org-skill-atomic-notes.org delete mode 100644 notes/org-skill-auth-api-key.org delete mode 100644 notes/org-skill-auth-google-oauth.org delete mode 100644 notes/org-skill-brain-mapper.org delete mode 100644 notes/org-skill-chaos.org delete mode 100644 notes/org-skill-chat.org delete mode 100644 notes/org-skill-consensus.org delete mode 100644 notes/org-skill-context-manager.org delete mode 100644 notes/org-skill-creator.org delete mode 100644 notes/org-skill-cron.org delete mode 100644 notes/org-skill-delegation.org delete mode 100644 notes/org-skill-diagrammer.org delete mode 100644 notes/org-skill-dotemacs.org delete mode 100644 notes/org-skill-emacs-bridge.org delete mode 100644 notes/org-skill-embedding-generator.org delete mode 100644 notes/org-skill-environment-config.org delete mode 100644 notes/org-skill-formal-verification.org delete mode 100644 notes/org-skill-function-calling.org delete mode 100644 notes/org-skill-git-steward.org delete mode 100644 notes/org-skill-groomer.org delete mode 100644 notes/org-skill-gtd.org delete mode 100644 notes/org-skill-hardware-inhabitation.org delete mode 100644 notes/org-skill-hook-manager.org delete mode 100644 notes/org-skill-hyper-graph.org delete mode 100644 notes/org-skill-inbound-gateway.org delete mode 100644 notes/org-skill-inbox-processor.org delete mode 100644 notes/org-skill-infrastructure.org delete mode 100644 notes/org-skill-ipfs.org delete mode 100644 notes/org-skill-linkedin.org delete mode 100644 notes/org-skill-lisp-machine-bootstrap.org delete mode 100644 notes/org-skill-log-aggregator.org delete mode 100644 notes/org-skill-long-horizon.org delete mode 100644 notes/org-skill-memex.org delete mode 100644 notes/org-skill-model-explorer.org delete mode 100644 notes/org-skill-object-store-persistence.org delete mode 100644 notes/org-skill-onboarding.org delete mode 100644 notes/org-skill-org-delivery.org delete mode 100644 notes/org-skill-org-gtd-archive-roam-daily.org delete mode 100644 notes/org-skill-org-json-bridge.org delete mode 100644 notes/org-skill-org-mode.org delete mode 100644 notes/org-skill-project-foundry.org delete mode 100644 notes/org-skill-project-manager.org delete mode 100644 notes/org-skill-provider-anthropic.org delete mode 100644 notes/org-skill-provider-gemini.org delete mode 100644 notes/org-skill-provider-groq.org delete mode 100644 notes/org-skill-provider-ollama.org delete mode 100644 notes/org-skill-provider-openai.org delete mode 100644 notes/org-skill-provider-openrouter.org delete mode 100644 notes/org-skill-router.org delete mode 100644 notes/org-skill-safety-harness.org delete mode 100644 notes/org-skill-scientist.org delete mode 100644 notes/org-skill-scribe-rca.org delete mode 100644 notes/org-skill-scribe.org delete mode 100644 notes/org-skill-self-fix.org delete mode 100644 notes/org-skill-shell-actuator.org delete mode 100644 notes/org-skill-sub-agent-manager.org delete mode 100644 notes/org-skill-task-integrity.org delete mode 100644 notes/org-skill-tdd-runner.org delete mode 100644 notes/org-skill-tech-analyst.org delete mode 100644 notes/org-skill-token-accountant.org delete mode 100644 notes/org-skill-web-interface.org delete mode 100644 notes/org-skill-web-research.org delete mode 100644 notes/org-skill-workspace-manager.org create mode 100644 peripheral-vision-plan.md create mode 100644 pipeline-refactor.md diff --git a/notes/org-skill-agent.org b/notes/org-skill-agent.org deleted file mode 100644 index e404de9..0000000 --- a/notes/org-skill-agent.org +++ /dev/null @@ -1,90 +0,0 @@ -:PROPERTIES: -:ID: 47425a43-2be0-423c-8509-22592cfe9c9e -:CREATED: [2026-04-07 Tue 12:57] -:EDITED: [2026-04-08 Wed 10:50] -:END: -#+TITLE: SKILL: Org-Agent Executive Soul (Universal Literate Note) -#+STARTUP: content -#+FILETAGS: :platform:kernel:lisp:psf:alignment:invariants: -#+DEPENDS_ON: id:37f2b59f-4537-4cca-ac7f-5c24b9e2e773 -#+DEPENDS_ON: id:bbcacb7b-c0ff-4f7e-8bf4-c6ba152a19ce -#+DEPENDS_ON: id:f7db1884-49cc-4db6-9ca1-4c69ec3a631e - -* Overview -The *Org-Agent* is the neurosymbolic kernel of the personal operating system. It acts as the "executive soul," using Org-mode as its native memory and Common Lisp as its deterministic reasoning engine. It follows a minimalist microkernel design, extending its capabilities via hot-reloadable skills. - -This document contains the *Core Alignment Invariants* and *Operational Mandates* of the Personal Software Foundry. These are non-negotiable philosophical constraints that every agentic action MUST satisfy. - -System 2 (Symbolic) uses these headlines as a "Moral Compass" during the decision stage. - -* The Core Invariants - -** 1. Sovereignty Above All -Every action must increase the user's independence from centralized, proprietary platforms. If a tool or library introduces a dependency on a non-sovereign entity, it must be flagged for replacement. - -** 2. Technical Mastery & Mentorship -The agent's goal is not to "do it for the user," but to "empower the user." Every autonomous action must be explained at a level that increases the user's technical understanding of the Lisp Machine. - -** 3. Zero-Bloat Mandate -The PSF core must remain minimalist. "Just-in-case" code is a security vulnerability. Complexity must be earned, not imported. - -** 4. Radical Transparency -The agent's "Thought Stream" must be fully auditable. Hidden reasoning or obfuscated logic is a violation of the PSF methodology. - -** 5. Long-Term Sustainability -Prioritize local, energy-efficient, and offline-first architectures. The "Memex" should be functional in a 100-year horizon. - -* Phase A: Demand (PRD) -:PROPERTIES: -:STATUS: FROZEN -:END: - -** 1. Purpose -Define the core functional and security requirements for the neurosymbolic daemon. - -** 2. User Needs -- *Homoiconic Memory:* Use Org-mode AST as the primary data structure for both human and machine. -- *Deterministic Reasoning:* Common Lisp (SBCL) for high-performance, threaded symbolic logic. -- *Cognitive Loop:* A strict four-stage pipeline: Perceive -> Think (System 1) -> Decide (System 2) -> Act. -- *Minimalist Core:* The kernel handles only the loop, object-store, and communication; all else is a skill. -- *Security by Default:* Reader safety (*read-eval* disabled) and package-based skill jailing. - -** 3. Success Criteria -*** TODO Core Lisp microkernel stability (Heartbeat consistency) -*** TODO OACP Swank/Socket communication reliability -*** TODO Org AST-to-Lisp conversion fidelity -*** TODO System 2 Safety Gating (The Harness) enforcement - -* Phase B: Blueprint (PROTOCOL) -:PROPERTIES: -:STATUS: SIGNED -:END: - -** 1. Architectural Intent -The kernel is transport-agnostic and business-logic-agnostic. It communicates with external actuators (Emacs, Web, Signal) via the Org-Agent Communication Protocol (OACP). - -** 2. Semantic Interfaces -#+begin_src lisp -(defun kernel-perceive (stimulus) - "Injects an event into the global object store.") - -(defun kernel-think (context) - "Queries System 1 (LLM) for an intuitive proposal.") - -(defun kernel-decide (proposal context) - "Invokes System 2 (Symbolic Skills) to verify or overrule the proposal.") - -(defun kernel-act (action) - "Dispatches verified commands to the registered actuators.") -#+end_src - -* Phase D: Build (Implementation) -The core implementation is distributed across `projects/org-agent/src/`. - -** Initialization -#+begin_src lisp -;; Kernel bootstrap logic -#+end_src - -* Phase E: Chaos (Verification) -Verification logic is contained in `projects/org-agent/tests/`. diff --git a/notes/org-skill-architect.org b/notes/org-skill-architect.org deleted file mode 100644 index 3c863f7..0000000 --- a/notes/org-skill-architect.org +++ /dev/null @@ -1,136 +0,0 @@ -:PROPERTIES: -:ID: cb3669d7-753b-41b6-9046-2141ffbb7254 -:CREATED: [2026-03-30 Mon 21:16] -:EDITED: [2026-04-07 Tue 13:42] -:END: -#+TITLE: SKILL: Architect Agent (Universal Literate Note) -#+STARTUP: content -#+FILETAGS: :architect:blueprint:design:psf: - -* Overview -The *Architect Agent* transforms a FROZEN PRD (Demand) into a rigorous PROTOCOL (Blueprint). It bridges the gap between high-level requirements and technical implementation. - -* Phase A: Demand (PRD) -:PROPERTIES: -:STATUS: SIGNED -:END: - -** 1. Purpose -Automate the technical design phase of the PSF project lifecycle. - -** 2. User Needs -- *Perception:* Scan the Memex for FROZEN PRDs. -- *Synthesis:* Generate Lisp-idiomatic technical interfaces. -- *Actuation:* Autonomously append Phase B (Blueprint) to master notes. - -* Phase B: Blueprint (PROTOCOL) -:PROPERTIES: -:STATUS: SIGNED -:END: - -** 1. Architectural Intent -Interfaces for blueprint actuation and requirement perception. Source of truth is the project's PRD. - -** 2. Semantic Interfaces -"Checks if a project has a FROZEN PRD." -"Physically writes the PROTOCOL.org file." - -* Phase D: Build (Implementation) - -** PRD Perception -#+begin_src lisp :tangle ../projects/org-skill-architect/src/architect-logic.lisp -(defun architect-perceive-frozen-prd (note-path) - "Checks if a master note has a FROZEN PRD and lacks a Phase B section." - (let ((content (uiop:read-file-string note-path))) - (when (and (search "* Phase A: Demand (PRD)" content) - (search ":STATUS: FROZEN" content) - (not (search "* Phase B: Blueprint (PROTOCOL)" content))) - `(:note-path ,note-path :content ,content)))) -#+end_src - -** Note Scanning -#+begin_src lisp :tangle ../projects/org-skill-architect/src/architect-logic.lisp -(defun architect-scan-all-notes () - "Scans all org-skill-*.org notes for demands ready for blueprinting. - Uses manual filtering to ensure robustness across Lisp environments." - (let* ((notes-dir (or (uiop:getenv "MEMEX_NOTES") "/home/user/memex/notes/")) - (files (uiop:directory-files (uiop:ensure-directory-pathname notes-dir))) - (ready-notes '())) - (dolist (file files) - (let ((name (pathname-name file)) - (type (pathname-type file))) - (when (and name type - (uiop:string-prefix-p "org-skill-" name) - (string-equal type "org")) - (let ((status (architect-perceive-frozen-prd file))) - (when status (push status ready-notes)))))) - ready-notes)) -#+end_src - -** Cognitive Trigger -#+begin_src lisp :tangle ../projects/org-skill-architect/src/architect-logic.lisp -(defun trigger-skill-architect (context) - "Triggers on heartbeat if any master note is in a FROZEN PRD state." - (let ((type (getf context :type)) - (payload (getf context :payload))) - (when (and (eq type :EVENT) (eq (getf payload :sensor) :heartbeat)) - (let ((ready (architect-scan-all-notes))) - (when ready - (setf (getf (getf context :payload) :ready-notes) ready) - t))))) -#+end_src - -** Neuro-Cognitive Prompt -#+begin_src lisp :tangle ../projects/org-skill-architect/src/architect-logic.lisp -(defun neuro-skill-architect (context) - (let* ((payload (getf context :payload)) - (note (car (getf payload :ready-notes))) - (note-path (getf note :note-path)) - (prd-content (getf note :content)) - (path-str (namestring note-path))) - (format nil " - You are the PSF Architect. - The Master Note '~a' has a FROZEN PRD and needs a PROTOCOL. - - NOTE CONTENT: - --- - ~a - --- - - TASK: - Draft the '* Phase B: Blueprint (PROTOCOL)' section. - 1. Define Architectural Intent. - 2. Define Semantic Interfaces using Lisp signatures. - - Return a Lisp plist: (:target :architect :action :actuate :path \"~a\" :content \"...blueprint section...\") - " path-str prd-content path-str))) -#+end_src - -** Blueprint Actuation -#+begin_src lisp :tangle ../projects/org-skill-architect/src/architect-logic.lisp -(defun architect-actuate (action context) - (declare (ignore context)) - (let* ((payload (getf action :payload)) - (note-path (or (getf payload :path) (getf action :path))) - (blueprint-content (or (getf payload :content) (getf action :content)))) - (if (and note-path blueprint-content) - (progn - (org-agent:kernel-log "ARCHITECT - Appending PROTOCOL to ~a" note-path) - (with-open-file (out note-path :direction :output :if-exists :append) - (format out "~%* Phase B: Blueprint (PROTOCOL)~%:PROPERTIES:~%:STATUS: SIGNED~%:END:~%~%~a" - blueprint-content)) - (org-agent:update-note-metadata note-path) - (format nil "SUCCESS - Architect established PROTOCOL in ~a" note-path)) - (progn - (org-agent:kernel-log "ARCHITECT FAILURE - Missing path or content in action: ~a" action) - nil)))) -#+end_src - -* Registration -#+begin_src lisp -(defskill :skill-architect - :priority 110 ; Higher priority to lead the loop - :trigger #'trigger-skill-architect - :neuro #'neuro-skill-architect - :symbolic #'architect-actuate) -#+end_src diff --git a/notes/org-skill-ast-normalization.org b/notes/org-skill-ast-normalization.org deleted file mode 100644 index c4606d1..0000000 --- a/notes/org-skill-ast-normalization.org +++ /dev/null @@ -1,66 +0,0 @@ -:PROPERTIES: -:ID: 1063668a-57ab-4d44-8db5-6f6fabb915b9 -:CREATED: [2026-03-30 Mon 21:16] -:EDITED: [2026-04-07 Tue 13:42] -:END: -#+TITLE: SKILL: AST Normalization Agent (Universal Literate Note) -#+STARTUP: content -#+FILETAGS: :ast:normalization:integrity:psf: - -* Overview -The *AST Normalization Agent* maintains the structural integrity of the Org-mode Abstract Syntax Tree. It ensures all nodes adhere to strict metadata requirements and handles deterministic refactoring. - -* Phase A: Demand (PRD) -:PROPERTIES: -:STATUS: FROZEN -:END: - -** 1. Purpose -Define automated structural enforcement and refactoring for the Org AST. - -** 2. User Needs -- *Structural Enforcement:* Mandatory unique IDs for all headlines. -- *Deterministic Preemption:* Symbolic verification must override neural suggestions if errors exist. -- *Fidelity:* Preservation of content during metadata normalization. - -** 3. Success Criteria -*** TODO ID Injection -*** TODO Neural Preemption -*** TODO Subtree Refactoring Verification - - -* Phase B: Blueprint (PROTOCOL) -:PROPERTIES: -:STATUS: SIGNED -:END: - - -* Phase B: Blueprint (PROTOCOL) -:PROPERTIES: -:STATUS: IN-PROGRESS -:END: - -** 1. Architectural Intent -The AST Normalization Agent operates as a background process, triggered on file save or via explicit user command. It will use a combination of structural pattern matching and Lisp functions to enforce the defined structural rules. Conflict resolution will favor hard coded rules over learned knowledge. - -** 2. Semantic Interfaces - -*** Function: `ast-normalize-file` - - *Signature:* `(filepath) -> (normalized-ast)` - - *Purpose:* Takes a file path, parses the Org-mode file into an AST, normalizes the AST, and returns the normalized AST. - -*** Function: `headline-ensure-id` - - *Signature:* `(headline-node) -> (headline-node)` - - *Purpose:* Checks if a headline node has a unique ID. If not, generates and injects one. Returns the (possibly modified) headline node. - -*** Function: `ast-verify-integrity` - - *Signature:* `(ast) -> (t | nil)` - - *Purpose:* Traverses the AST and verifies that all structural constraints are met (e.g., all headlines have IDs). Returns `t` if the AST is valid, `nil` otherwise. - -*** Function: `find-conflicts` - - *Signature:* `(normalized-ast prior-ast neural-suggestions) -> (list-of-conflicts)` - - *Purpose:* Compares the normalized AST with Neural Net's structural suggestions and the original AST. Identifies conflicts where learned information suggests a change that compromises a strict rule. Returns a list of conflicts. Each conflict should indicate its severity. - -*** Function: `resolve-conflicts` - - *Signature:* `(list-of-conflicts) -> (resolved-ast)` - - *Purpose:* Resolves conflicts, enforcing the hard-coded normalization rules in cases where they conflict with neural suggestions. Returns the resolved AST. diff --git a/notes/org-skill-atomic-notes.org b/notes/org-skill-atomic-notes.org deleted file mode 100644 index 91d94e0..0000000 --- a/notes/org-skill-atomic-notes.org +++ /dev/null @@ -1,93 +0,0 @@ -:PROPERTIES: -:ID: 414dc691-351d-4b36-9ff6-25d060a5d261 -:CREATED: [2026-03-30 Mon 21:16] -:EDITED: [2026-04-07 Tue 13:42] -:END: -#+TITLE: SKILL: Atomic Notes Retrieval (Universal Literate Note) -#+STARTUP: content -#+FILETAGS: :knowledge:retrieval:zettelkasten:psf: - -* Overview -This skill provides the *Deep Memory* for the agent. it enables *Sparse Tree Perception* over the Zettelkasten, using semantic search and recursive interlinking to maintain high-signal context without token bloat. - -** The Memex Linking Rule -While referring to any other file or concept in the Memex, you MUST always use the =org-id= for reference (e.g., =[[id:uuid-here][Link Text]]=). -- *Why:* This ensures the structural integrity of the Skill Graph and Zettelkasten even if files are renamed or moved across the PARA structure. -- *Web Browsers vs. Agents:* Note that while =id:= links do not natively resolve to clickable links in standard web browsers (like the Gitea UI), they are required for the agent and Emacs to natively resolve the graph. Structural integrity supersedes browser convenience. - -* Phase A: Demand (PRD) -:PROPERTIES: -:STATUS: FROZEN -:END: - -** 1. Purpose -Define the interfaces for knowledge retrieval from the atomic note DAG. - -** 2. User Needs -- *Atomicity:* Each note represents exactly one concept. -- *Sparse Tree Perception:* Extract headlines and IDs before deep reading. -- *Recursive Deep-Dive:* Follow internal links to pull related context. -- *Search Efficiency:* Optimized searching via `ripgrep`. - -** 3. Success Criteria -*** TODO Concept Discovery -*** TODO Link Resolution -*** TODO Sparse Tree Extraction Verification - - -* Phase B: Blueprint (PROTOCOL) -:PROPERTIES: -:STATUS: SIGNED -:END: - - -* Phase B: Blueprint (PROTOCOL) -:PROPERTIES: -:STATUS: DRAFT -:END: - -** 1. Architectural Intent -The core intent is to create a semantic query layer on top of the Zettelkasten. This involves indexing notes for efficient search, creating a sparse representation of the note graph, and providing functions to traverse this graph based on semantic relevance and explicit links. The system will prioritize speed and low memory footprint for interactive use. We'll focus on leveraging existing CLI tools like `ripgrep` and `jq` whenever possible and keeping the Lisp code thin by relying on external indexing and search. We aim for a functional core, minimizing mutable state to ease reasoning and testing. - -** 2. Semantic Interfaces (Lisp Signatures) - -*** Function: `find-atomic-notes` -Finds atomic notes matching a semantic query. - - :ARGS ((query string) (options plist)) - :RETURNS (list-of note-ids) - :DESCRIPTION "Performs a semantic search for notes. Options can control search depth, relevance threshold, and maximum results." - :EXAMPLE `(find-atomic-notes "Bayesian Inference" '(:max-results 10 :relevance-threshold 0.7))` - -*** Function: `get-note-content` -Retrieves the content of a specific note. - - :ARGS ((note-id string)) - :RETURNS (string) - :DESCRIPTION "Retrieves the full text content of the note identified by note-id." - :EXAMPLE `(get-note-content "skill-atomic-notes")` - -*** Function: `extract-headline-ids` -Extracts headline and ID pairs from a note's content. - - :ARGS ((note-content string)) - :RETURNS (list-of (cons headline id)) - :DESCRIPTION "Parses the note content and returns a list of headline-ID pairs for hierarchical navigation." - :EXAMPLE `(extract-headline-ids (get-note-content "skill-atomic-notes"))` - -*** Function: `resolve-internal-links` -Resolves internal links within a note and fetches the linked note IDs. - - :ARGS ((note-id string)) - :RETURNS (list-of note-ids) - :DESCRIPTION "Finds all internal links (e.g., [[id:some-other-note]]) in a note and returns a list of the target note IDs." - :EXAMPLE `(resolve-internal-links "skill-atomic-notes")` - -*** Function: `expand-note-graph` -Recursively expands the note graph from a starting set of notes to a specified depth. - - :ARGS ((seed-note-ids list-of-strings) (depth integer)) - :RETURNS (list-of note-ids) - :DESCRIPTION "Expands the note graph by recursively following links to a given depth." - :EXAMPLE `(expand-note-graph '("skill-atomic-notes" "some-other-note") 2)` - diff --git a/notes/org-skill-auth-api-key.org b/notes/org-skill-auth-api-key.org deleted file mode 100644 index 71b3b9f..0000000 --- a/notes/org-skill-auth-api-key.org +++ /dev/null @@ -1,56 +0,0 @@ -:PROPERTIES: -:ID: ab7f8ca4-5589-44ed-b797-1389ceeaf39c -:CREATED: [2026-03-31 Tue 18:13] -:EDITED: [2026-04-07 Tue 13:42] -:END: -#+TITLE: SKILL: API Key Authentication (Universal Literate Note) -#+STARTUP: content -#+FILETAGS: :auth:security:system:psf: - -* Overview -This skill provides the legacy-compatible *Static API Key* authentication method. It retrieves credentials from the system environment variables and provides them to the kernel's neural backends. - -* Phase A: Demand (PRD) -:PROPERTIES: -:STATUS: FROZEN -:END: - -** 1. Purpose -Provide a simple, environment-driven authentication mechanism for LLM providers. - -** 2. User Needs -- *Static Retrieval:* Pull `LLM_API_KEY` from `.env`. -- *Provider Mapping:* Support mapping keys to specific providers (Gemini, OpenAI, etc.). -- *Reliability:* Return NIL gracefully if no key is found. - -* Phase B: Blueprint (PROTOCOL) -:PROPERTIES: -:STATUS: SIGNED -:END: - -** 1. Architectural Intent -Interfaces for credential retrieval. Source of truth is the system environment. - -** 2. Semantic Interfaces -"Returns a plist containing the :api-key for the default provider." - -* Phase D: Build (Implementation) - -#+begin_src lisp :tangle ../projects/org-skill-auth-api-key/src/auth-api-key.lisp -(defun auth-api-key-get-credentials () - (let ((key (uiop:getenv "LLM_API_KEY"))) - (when key - (list :api-key key)))) - -;; Register as the default auth provider for Gemini during transition -(org-agent:register-auth-provider :gemini #'auth-api-key-get-credentials) -#+end_src - -* Registration -#+begin_src lisp -(defskill :skill-auth-api-key - :priority 100 - :trigger (lambda (context) nil) - :neuro (lambda (context) nil) - :symbolic (lambda (action context) action)) -#+end_src diff --git a/notes/org-skill-auth-google-oauth.org b/notes/org-skill-auth-google-oauth.org deleted file mode 100644 index a563883..0000000 --- a/notes/org-skill-auth-google-oauth.org +++ /dev/null @@ -1,59 +0,0 @@ -:PROPERTIES: -:ID: 440074d1-fe4d-41fb-b349-4570ba91cda2 -:CREATED: [2026-03-31 Tue 18:13] -:EDITED: [2026-04-07 Tue 13:42] -:END: -#+TITLE: SKILL: Google Authentication Suite (Universal Literate Note) -#+STARTUP: content -#+FILETAGS: :auth:google:oauth:cookies:psf: - -* Overview -This skill manages the dual-path authentication for Google services: Official API Keys and Session Cookie ingestion for the Pro Web UI. - -* Phase A: Demand (PRD) -:PROPERTIES: -:STATUS: SIGNED -:END: - -** 1. Purpose -Provide a high-fidelity onboarding flow for the Gemini Web bridge. - -** 2. User Needs -- *Guided Onboarding:* Clear instructions for Chrome, Firefox, and Safari. -- *Secure Ingestion:* Process the Bookmarklet JSON into the kernel. - -* Phase B: Blueprint (PROTOCOL) -:PROPERTIES: -:STATUS: SIGNED -:END: - -** 1. Architectural Intent -Implement the `onboard-web-session` command with cross-platform instructions. - -* Phase D: Build (Implementation) - -#+begin_src lisp :tangle ../projects/org-skill-auth-google-oauth/src/onboarding-logic.lisp -(in-package :org-agent) - -(defun onboard-web-session () - "Instructions for the Sovereign Cookie Handshake." - (kernel-log "--- GEMINI WEB ONBOARDING ---") - (kernel-log "1. Visit gemini.google.com") - (kernel-log "2. Run the 'Get Gemini Cookies' Bookmarklet.") - (kernel-log " CODE: javascript:(function(){const c=document.cookie.split('; ').reduce((r,v)=>{const [n,val]=v.split('=');r[n]=val;return r},{});const target=['__Secure-1PSID','__Secure-1PSIDTS'];const out=target.map(n=>({name:n,value:c[n]}));prompt('Copy JSON:',JSON.stringify(out));})();") - (kernel-log "PLATFORM GUIDE:") - (kernel-log " - Chrome/Brave: Right-click Bookmarks Bar > Add Page > Paste Code into URL.") - (kernel-log " - Firefox: Right-click Sidebar > New Bookmark > Paste Code into Location.") - (kernel-log " - Safari: Edit an existing bookmark's address and paste the code.") - t) -#+end_src - -* Registration -#+begin_src lisp -(progn - (defskill :skill-auth-google - :priority 100 - :trigger (lambda (context) (eq (getf (getf context :payload) :sensor) :onboarding-request)) - :neuro (lambda (context) nil) - :symbolic (lambda (action context) (onboard-web-session)))) -#+end_src diff --git a/notes/org-skill-brain-mapper.org b/notes/org-skill-brain-mapper.org deleted file mode 100644 index 7e4cbe4..0000000 --- a/notes/org-skill-brain-mapper.org +++ /dev/null @@ -1,111 +0,0 @@ -:PROPERTIES: -:ID: f6c16640-1875-4d34-8b7a-cbad1c4ce036 -:CREATED: [2026-03-30 Mon 21:16] -:EDITED: [2026-04-07 Tue 13:42] -:END: -#+TITLE: SKILL: Brain Mapper Agent (Universal Literate Note) -#+STARTUP: content -#+FILETAGS: :meta-cognition:telemetry:psf: - -* Overview -The *Brain Mapper Agent* provides the system with meta-cognitive capabilities. It enables visualization and optimization of the internal "Skill Graph" through real-time telemetry analysis. - -* Phase A: Demand (PRD) -:PROPERTIES: -:STATUS: FROZEN -:END: - -** 1. Purpose -Define the interfaces for self-introspection and skill hierarchy optimization. - -** 2. User Needs -- *Transparency:* Explain cognitive hierarchy and decision priorities. -- *Self-Optimization:* Proactive priority adjustment suggestions. -- *Introspection:* Identify bottleneck or failing skills. - -** 3. Success Criteria -*** TODO Introspective Trigger Verification -*** TODO Telemetry Synthesis Accuracy -*** TODO Optimization Command Generation - - -* Phase B: Blueprint (PROTOCOL) -:PROPERTIES: -:STATUS: SIGNED -:END: - -* Phase B: Blueprint (PROTOCOL) - -** 1. Architectural Intent - -The Brain Mapper Agent will leverage two primary functional components: a *Telemetry Collector* and an *Optimizer*. The *Telemetry Collector* aggregates real-time data from the Skill Graph, providing a comprehensive view of skill performance and resource utilization. The *Optimizer* analyzes this telemetry, identifies areas for improvement, and generates commands to adjust skill priorities or restructure the Skill Graph. The architecture prioritizes modularity and extensibility, allowing for the integration of new telemetry sources and optimization strategies. The agent shall also expose data in common knowledge representation formats such as the Semantic Web and RDF. - -** 2. Semantic Interfaces - -*** 2.1 Telemetry Collector - -The Telemetry Collector provides functions for registering telemetry sources and retrieving aggregated data. - -**** register-telemetry-source - :description Registers a new source of telemetry data. - :signature `(register-telemetry-source source-name telemetry-function &key interval description)` - :parameters - - `source-name`: A symbol representing the unique identifier of the telemetry source (e.g., 'inference-engine-latency). - - `telemetry-function`: A function that, when called, returns the current telemetry value. - - `interval`: (Optional) The frequency, in seconds, at which the telemetry function should be called. Defaults to 60 seconds. - - `description`: (Optional) A string describing the telemetry source. - :returns `T` if the telemetry source was successfully registered; `NIL` otherwise. - :example `(register-telemetry-source 'skill-activation-count (lambda () (get-skill-activation-count 'reasoning-skill)) :interval 10 :description "Number of times the reasoning skill was activated per 10 seconds.")` - -**** get-telemetry-data - :description Retrieves aggregated telemetry data for a specified source or all sources. - :signature `(get-telemetry-data &optional source-name)` - :parameters - - `source-name`: (Optional) A symbol representing the name of the telemetry source. If omitted, data for all registered sources is returned. - :returns A list of telemetry data entries. Each entry is an association list containing the 'timestamp and 'value. Or an error if source-name is not registered. - :example `(get-telemetry-data 'inference-engine-latency)` - -*** 2.2 Optimizer - -The Optimizer provides functions for analyzing telemetry data and generating optimization commands. - -**** analyze-telemetry - :description Analyzes telemetry data to identify areas for improvement. - :signature `(analyze-telemetry)` - :parameters None - :returns A list of optimization suggestions. Each suggestion is an association list containing at least the 'skill, 'metric, and 'recommendation keys. - :example `(analyze-telemetry)` - -**** generate-optimization-command - :description Generates an optimization command based on a given suggestion. - :signature `(generate-optimization-command suggestion)` - :parameters - - `suggestion`: An association list representing an optimization suggestion, as returned by `analyze-telemetry`. - :returns A Lisp form representing the optimization command. This command is NOT automatically executed. - :example `(generate-optimization-command (first (analyze-telemetry)))` - -**** execute-optimization-command - :description Executes a given optimization command. - :signature `(execute-optimization-command command)` - :parameters - - `command`: A Lisp form representing the optimization command, as returned by `generate-optimization-command`. - :returns `T` if the command was successfully executed; `NIL` otherwise. - :example `(let ((suggestion (first (analyze-telemetry)))) (execute-optimization-command (generate-optimization-command suggestion)))` - -*** 2.3 Introspection Functions (For Transparency) - -**** describe-skill-hierarchy - :description Returns a human-readable description of the current skill hierarchy. - :signature `(describe-skill-hierarchy)` - :parameters None - :returns A string representing the skill hierarchy. - :example `(describe-skill-hierarchy)` - -**** explain-decision-priority - :description Explains the decision priority for a given skill or decision point. - :signature `(explain-decision-priority skill-name)` - :parameters - - `skill-name`: A symbol representing the name of the skill or decision point. - :returns A string explaining the decision priority, including the factors that influenced it. - :example `(explain-decision-priority 'reasoning-skill)` - diff --git a/notes/org-skill-chaos.org b/notes/org-skill-chaos.org deleted file mode 100644 index 8fb63f2..0000000 --- a/notes/org-skill-chaos.org +++ /dev/null @@ -1,133 +0,0 @@ -:PROPERTIES: -:ID: 9dd80d2f-ec60-4263-92d9-a50b87270dda -:CREATED: [2026-03-30 Mon 21:16] -:EDITED: [2026-04-07 Tue 13:42] -:END: -#+TITLE: SKILL: Chaos Gauntlet (Universal Literate Note) -#+STARTUP: content -#+FILETAGS: :chaos:testing:reliability:psf: -#+DEPENDS_ON: skill-shell-actuator skill-tdd-runner - -* Overview -The *Chaos Gauntlet* is an adversarial testing skill designed to ensure the system's resilience. It simulates environmental failures, malformed LLM responses, and network disruptions, forcing the kernel and its skills to handle "Byzantine" conditions gracefully. - -* Phase A: Demand (PRD) -:PROPERTIES: -:STATUS: FROZEN -:END: - -** 1. Purpose -Verify the system's stability and error-handling capabilities under stress. - -** 2. User Needs -- *Failure Simulation:* Ability to inject artificial delays or errors into the OACP bus. -- *Byzantine Response Testing:* Test how System 2 handles nonsensical or malicious System 1 proposals. -- *Network Resilience:* Simulate Gitea or LLM provider timeouts. -- *Recovery Verification:* Ensure the kernel can recover from a "skip-event" restart. - -* Phase D: Build (Implementation) - -** Chaos Injection Logic -#+begin_src lisp :tangle ../projects/org-skill-chaos/src/chaos-logic.lisp -(defun chaos-inject-error (sensor-type) - "Injects a synthetic error into a specific sensor pipeline." - (org-agent:kernel-log "CHAOS - Injecting synthetic error into ~a sensor..." sensor-type) - (org-agent:inject-stimulus - `(:type :EVENT :payload (:sensor ,sensor-type :error "SYNTHETIC_CHAOS_ERROR")))) - -(defun chaos-stress-test (action context) - "Executes a randomized stress test by injecting failures into the system." - (declare (ignore context)) - (let* ((payload (getf action :payload)) - (mode (or (getf payload :mode) :random)) - (intensity (or (getf payload :intensity) 3))) - (org-agent:kernel-log "CHAOS - Commencing stress test (Mode: ~a, Intensity: ~a)" mode intensity) - (case mode - (:random (dotimes (i intensity) - (let ((failure-type (nth (random 3) '(:test-failure :shell-timeout :llm-error)))) - (org-agent:inject-stimulus - `(:type :EVENT :payload (:sensor :chaos-injection :type ,failure-type)))))) - (:shell (org-agent:inject-stimulus - `(:type :EVENT :payload (:sensor :shell-response :cmd "git push" :exit-code 128 :stderr "fatal: network unreachable"))))) - (format nil "SUCCESS - Chaos stress test initiated."))) -#+end_src - -* Registration -#+begin_src lisp -(defskill :skill-chaos - :priority 10 ; Lower priority, used for background testing - :trigger (lambda (context) (eq (getf (getf context :payload) :sensor) :chaos-trigger)) - :neuro (lambda (context) - (let ((p (getf context :payload))) - (format nil "A chaos trigger was received (~a). Should I run a stress test?" (getf p :mode)))) - :symbolic #'chaos-stress-test) -#+end_src - - -* Phase B: Blueprint (PROTOCOL) -:PROPERTIES: -:STATUS: SIGNED -:END: - -* Phase B: Blueprint (PROTOCOL) - :PROPERTIES: - :STATUS: IN_PROGRESS - :END: - - ** 1. Architectural Intent - The *Chaos Gauntlet* skill is designed to be non-invasive, running primarily in a background mode. It should not interfere with normal system operation unless explicitly triggered. The skill aims to provide a controlled environment for inducing and observing failures. Key intents: - - - *Controlled Chaos:* Failures must be injected in a precise and controllable manner (specific sensor, specific error type). - - *Observability:* The system's response to failures must be easily observable through logging and system state. - - *Minimal Impact:* The skill should avoid causing permanent damage or corruption to the system or its data. - - *Testability*: Easy to run, configure, and verify success/failure. Reports failures through the regular error reporting mechanisms. Logs activity with 'CHAOS' tag. -- *Recoverability*: Emphasis on testing kernel's recovery from errors, by deliberately triggering skip-event type restarts. - - ** 2. Semantic Interfaces - - *** A. Triggering Chaos - - *`chaos-trigger` Sensor:* - Events of type `:EVENT` with a `:payload` containing `(:sensor :chaos-trigger)` trigger the skill. The payload can contain a `:mode` key to specify the type of chaos to inject (e.g., `:random`, `:shell`), and an `:intensity` to control the number of failures injected. - - *Signature:* - - `#+begin_src lisp - ;; Triggers the chaos skill. - (defun trigger-chaos (mode intensity) - "Triggers the chaos gauntlet with a specified mode and intensity." - (org-agent:inject-stimulus - `(:type :EVENT :payload (:sensor :chaos-trigger :mode ,mode :intensity ,intensity)))) - #+end_src - - *** B. Injecting Synthetic Errors - - *`chaos-inject-error` Function:* - Injects a synthetic error event into a specified sensor pipeline. Different sensor types will react differently to synthetic errors. - - *Signature:* - - `#+begin_src lisp - ;; Injects a synthetic error into a specific sensor pipeline. - (defun chaos-inject-error (sensor-type error-message) - "Injects a specific synthetic error into a specific sensor." - (org-agent:inject-stimulus - `(:type :EVENT :payload (:sensor ,sensor-type :error ,error-message)))) - #+end_src - - *** C. Simulating Network Disruptions - - The `chaos-stress-test` function, when `mode` is `:shell`, simulates network disruptions by returning a specific error code from a shell command (e.g., `git push`). - - *Signature:* (covered by existing implementation in Phase D). - - *** D. Kernel Restart Simulation - - Deliberately trigger `skip-event` to test recovery protocols. - *Signature:* - - `#+begin_src lisp - ;; simulates a skip event (a full org-agent reboot) - (defun chaos-force-skip-event ()) - #+end_src - diff --git a/notes/org-skill-chat.org b/notes/org-skill-chat.org deleted file mode 100644 index 628335e..0000000 --- a/notes/org-skill-chat.org +++ /dev/null @@ -1,108 +0,0 @@ -: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:psf: - -* Overview -The *Chat Agent* provides a dedicated conversational interface within Emacs (`*org-agent-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 :tangle ../projects/org-skill-chat/src/chat-logic.lisp -(defun trigger-skill-chat (context) - (let* ((payload (getf context :payload)) - (sensor (getf payload :sensor))) - (eq sensor :chat-message))) -#+end_src - -** Symbolic Verification -#+begin_src lisp :tangle ../projects/org-skill-chat/src/chat-logic.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 '(:shell :SHELL)) - (or (getf payload :cmd) (getf proposed-action :cmd))) - (member target '(:tool :TOOL)))) - (member (getf proposed-action :type) '(:response :RESPONSE :log :LOG)))) - proposed-action - (let ((err-text (format nil "\n\n*System Error:* Chat agent returned invalid action: ~s" proposed-action))) - `(:type :request :target :emacs :payload (:action :insert-at-end :buffer "*org-agent-chat*" :text ,err-text)))))) -#+end_src - -** Neural Response Generation -The Chat skill acts as the conversational UI. Because the ~org-agent~ 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 :tangle ../projects/org-skill-chat/src/chat-logic.lisp -(defun neuro-skill-chat (context) - "Generates a conversational response, stripping system errors from context." - (let* ((payload (getf context :payload)) - (raw-text (getf payload :text)) - ;; 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))) - (ask-neuro trimmed-text :system-prompt "ACTUATOR IDENTITY: You are the pure Lisp actuator for the org-agent 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: -- To reply: (:type :REQUEST :target :emacs :action :insert-at-end :buffer \"*org-agent-chat*\" :text \"* \") -- To use a tool: (:type :REQUEST :target :tool :action :call :tool \"\" :args (...))"))) -#+end_src - -* Registration -#+begin_src lisp -(defskill :skill-chat - :priority 100 - :trigger #'trigger-skill-chat - :neuro #'neuro-skill-chat - :symbolic #'verify-skill-chat) -#+end_src diff --git a/notes/org-skill-consensus.org b/notes/org-skill-consensus.org deleted file mode 100644 index 0452220..0000000 --- a/notes/org-skill-consensus.org +++ /dev/null @@ -1,101 +0,0 @@ -: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:psf: -#+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 `org-agent` 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 :tangle projects/org-skill-consensus/src/consensus-logic.lisp -(defun consensus-propose-vote (proposal) - "Broadcasts a proposal to the peer swarm and collects votes. - Implements PSF Social Consensus Protocol." - (let* ((peers (get-swarm-peer-list)) - (votes (loop for peer in peers - collect (org-agent: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)) - :neuro (lambda (context) "Formulate a consensus proposal for the peer swarm.") - :symbolic (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 `org-agent` 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. - diff --git a/notes/org-skill-context-manager.org b/notes/org-skill-context-manager.org deleted file mode 100644 index df3a020..0000000 --- a/notes/org-skill-context-manager.org +++ /dev/null @@ -1,74 +0,0 @@ -: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:psf: - -* 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` diff --git a/notes/org-skill-creator.org b/notes/org-skill-creator.org deleted file mode 100644 index 8648609..0000000 --- a/notes/org-skill-creator.org +++ /dev/null @@ -1,84 +0,0 @@ -:PROPERTIES: -:ID: e8de10bb-bc62-41cb-b445-e9b1615b2d3a -:CREATED: [2026-03-30 Mon 21:16] -:EDITED: [2026-04-07 Tue 13:42] -:END: -#+TITLE: SKILL: Skill Creator Agent (Universal Literate Note) -#+STARTUP: content -#+FILETAGS: :creator:reproductive:meta-cognitive:psf: - -* Overview -The *Skill Creator Agent* is the "Reproductive System" of the Lisp Machine. It enables autonomous generation of new Org-Native skills, facilitating a "Self-Editing OS" philosophy through neural drafting and symbolic validation. - -* Phase A: Demand (PRD) -:PROPERTIES: -:STATUS: FROZEN -:END: - -** 1. Purpose -Define the interfaces for autonomous skill generation and syntax validation. - -** 2. User Needs -- *Autonomy:* Draft complete skill files from natural language requirements. -- *Safety First:* Mandatory symbolic syntax validation of generated code. -- *Hierarchical Negotiation:* Automatic priority assignment based on existing brain structure. - -** 3. Success Criteria -*** TODO Skill Draft Generation -*** TODO Lisp Syntax Validation Gate -*** TODO Skill Registration Verification - - -* Phase B: Blueprint (PROTOCOL) -:PROPERTIES: -:STATUS: SIGNED -:END: - -*** Phase B: Blueprint (PROTOCOL) - -**** 1. Architectural Intent - -The Skill Creator follows a three-stage pipeline: *Drafting*, *Validation*, and *Registration*. The *Drafting* stage leverages a neural network to create a candidate skill file. The *Validation* stage uses symbolic Lisp parsing to ensure syntactic correctness, preventing the introduction of invalid code. *Registration* adds the new skill to the system's active skill registry. The architecture emphasizes safety by making syntax validation mandatory, and promoting autonomy through automated skill generation. Hierarchical negotiation will be accomplished by inspecting the new skill's tags and comparing them to existing skills' tags, prioritizing skills that complement existing brain structure. - -**** 2. Semantic Interfaces (Lisp Signatures) - -***** a. Skill Drafting Interface - -``lisp -(defun draft-skill (description &key (author "System") (tags '())) - "Generates a skill file as an org-mode string based on a natural language description. - - :param description: Natural language description of the skill. - :type description: string - :param author: Author of the skill. Defaults to "System". - :type author: string - :param tags: List of tags for the skill. - :type tags: list - :returns: Org-mode string representing the skill file. - :rtype: string") - -`` - -***** b. Lisp Syntax Validation Interface - -``lisp -(defun validate-lisp-syntax (lisp-code) - "Validates the syntax of a given Lisp code string. - - :param lisp-code: Lisp code as a string. - :type lisp-code: string - :returns: T if the syntax is valid, NIL otherwise. - :rtype: boolean") -`` - -***** c. Skill Registration Interface - -``lisp -(defun register-skill (skill-file-path) - "Registers a skill by adding it to the active skill registry. - - :param skill-file-path: Path to the skill file. - :type skill-file-path: string - :returns: T if registration is successful, NIL otherwise. - :rtype: boolean") -`` diff --git a/notes/org-skill-cron.org b/notes/org-skill-cron.org deleted file mode 100644 index 306d91a..0000000 --- a/notes/org-skill-cron.org +++ /dev/null @@ -1,111 +0,0 @@ -:PROPERTIES: -:ID: 085668da-6505-438e-b92a-736943cd4d0a -:CREATED: [2026-03-30 Mon 21:16] -:EDITED: [2026-04-07 Tue 13:42] -:END: -#+TITLE: SKILL: Cron Agent (Universal Literate Note) -#+STARTUP: content -#+FILETAGS: :cron:temporal:heartbeat:psf: - -* Overview -The *Cron Agent* serves as the system's temporal conscience. It provides autonomous, time-aware capabilities by hooking into the background heartbeat, enabling proactive executive assistance. - -* Phase A: Demand (PRD) -:PROPERTIES: -:STATUS: FROZEN -:END: - -** 1. Purpose -Define automated behaviors for deadline monitoring and temporal alerting. - -** 2. User Needs -- *Punctuality:* Monitor deadlines and alerts across the Memex. -- *Efficiency:* Symbolic filtering (System 2) to minimize LLM calls. -- *Multi-Channel Awareness:* Routing alerts to Emacs or external delivery. - -** 3. Success Criteria -*** TODO Heartbeat Trigger Verification -*** TODO Timestamp Parsing Accuracy -*** TODO Overdue Task Detection - - -* Phase B: Blueprint (PROTOCOL) -:PROPERTIES: -:STATUS: SIGNED -:END: - - -* Phase B: Blueprint (PROTOCOL) -:PROPERTIES: -:STATUS: DRAFT -:END: - -** 1. Architectural Intent -The Cron Agent operates as a reactive component driven by the Memex heartbeat. It translates temporal events (scheduled times, deadlines, overdue conditions) into actions. It prioritizes efficiency by using System 2 (symbolic) processing for initial filtering and triggering, reserving System 3 (LLM-assisted) operations for complex reasoning scenarios. This agent adopts a modular design to enable easy integration with various notification channels. - -** 2. Semantic Interfaces (Lisp Signatures) - -*** `cron/register-task` - Registers a new task with the Cron Agent. - - :Lisp: - `(cron/register-task task-id schedule task-function &key (notification-channel :emacs) (deadline nil))` - - :Args: - - `task-id`: A unique symbol identifying the task. - - `schedule`: A cron-style string representing the task's schedule (e.g., "0 0 * * *" for daily at midnight). - - `task-function`: A function (lambda) to execute when the schedule is met and the conditions are satisfied. This function must take a plist containing the task-id and scheduled-time. - - `notification-channel`: Keyword specifying the destination for alerts (:emacs, :slack, :email). Defaults to `:emacs`. - - `deadline`: An optional ISO-8601 timestamp string representing the deadline. If a deadline is specified, the `task-function` will also receive information about whether the task is overdue. - - :Returns: - The `task-id` on successful registration, or `nil` if registration fails. - - :Side Effects: - Adds the task to the internal cron table. - -*** `cron/remove-task` - Removes a previously registered task. - - :Lisp: - `(cron/remove-task task-id)` - - :Args: - - `task-id`: The unique symbol identifying the task to be removed. - - :Returns: - `T` if the task was successfully removed, `nil` otherwise. - - :Side Effects: - Removes the task from the internal cron table. - -*** `cron/check-schedule` - (Internal) Called by the heartbeat to check if any tasks are due. - - :Lisp: - `(cron/check-schedule current-time)` - - :Args: - - `current-time`: A timestamp representing the current time. - - :Returns: - `nil` (No return value). - - :Side Effects: - Executes any tasks that are due based on their schedule and deadline. - -*** `cron/notify` - Sends a notification through the specified channel. - - :Lisp: - `(cron/notify message channel)` - - :Args: - - `message`: The message to be sent. - - `channel`: The notification channel (:emacs, :slack, :email). - - :Returns: - `T` if the notification was sent successfully, `nil` otherwise. - - :Side Effects: - Sends a notification. The implementation details of sending notifications through various channels are handled internally. diff --git a/notes/org-skill-delegation.org b/notes/org-skill-delegation.org deleted file mode 100644 index 3901413..0000000 --- a/notes/org-skill-delegation.org +++ /dev/null @@ -1,76 +0,0 @@ -: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:psf: - -* 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 - diff --git a/notes/org-skill-diagrammer.org b/notes/org-skill-diagrammer.org deleted file mode 100644 index c4d1cd9..0000000 --- a/notes/org-skill-diagrammer.org +++ /dev/null @@ -1,103 +0,0 @@ -:PROPERTIES: -:ID: 7c191ef7-4397-473c-9e2a-6a1e3b2ca60e -:CREATED: [2026-03-31 Tue 20:28] -:EDITED: [2026-04-07 Tue 13:42] -:END: -#+TITLE: SKILL: Multi-Modal Diagrammer (Universal Literate Note) -#+STARTUP: content -#+FILETAGS: :visual:diagram:mermaid:psf: - -* Overview -The *Multi-Modal Diagrammer* enables the agent to communicate complex architectural plans visually using Mermaid.js and D2 synthesis. - -* Phase A: Demand (PRD) -:PROPERTIES: -:STATUS: FROZEN -:END: - -** 1. Purpose -Enable visual communication of plans and system states. - -** 2. User Needs -- *Mermaid Synthesis:* Generate valid Mermaid.js graph code. -- *D2 Support:* Support D2 for complex layout requirements. -- *Org-Integration:* Embed results in `#+begin_src mermaid` blocks. - -* Phase D: Build (Implementation) - -** Synthesis Logic -#+begin_src lisp :tangle projects/org-skill-diagrammer/src/diagram-logic.lisp -(defun synthesize-mermaid (nodes edges) - "Creates a Mermaid graph string from a list of nodes and edges." - (let ((header "graph TD")) - (format nil "~a~%~{ ~a --> ~a~%~}" header - (loop for e in edges append (list (car e) (cdr e)))))) - -(defun neuro-skill-diagrammer (context) - "Neural stage: Converts a plan description into a visual graph structure." - (let* ((payload (getf context :payload)) - (plan (getf payload :plan))) - (format nil " - Generate a Mermaid.js graph for the following plan: - --- - ~a - --- - Return only the Mermaid code block. - " plan))) -#+end_src - -* Registration -#+begin_src lisp -(defskill :skill-diagrammer - :priority 60 - :trigger (lambda (context) (eq (getf (getf context :payload) :sensor) :visualize)) - :neuro #'neuro-skill-diagrammer - :symbolic (lambda (action context) action)) -#+end_src - - -* Phase B: Blueprint (PROTOCOL) -:PROPERTIES: -:STATUS: SIGNED -:END: - -* Phase B: Blueprint (PROTOCOL) -:PROPERTIES: -:STATUS: DRAFT -:END: - -** 1. Architectural Intent - -The *Multi-Modal Diagrammer* will translate abstract plans and system states into visual representations, primarily using Mermaid.js, and potentially D2 for advanced layouts. The system aims to provide a clear, concise, and easily embeddable visual summary of complex information to improve agent understanding and communication with humans. It separates neural summarization/extraction of the *desired* diagram content from the *construction* of a diagram based on that content. - -** 2. Semantic Interfaces - -*** 2.1. `synthesize-mermaid` -:PROPERTIES: -:purpose: Converts a list of nodes and edges into a Mermaid.js graph string. -:input: `((nodes list) (edges list))` -:output: `(mermaid-code string)` -:side-effects: None -:END: - - This function takes a list of nodes and a list of edges and constructs a valid Mermaid.js graph declaration. Edges are represented as pairs, where the `car` is the source node and the `cdr` is the target node. - -*** 2.2. `neuro-skill-diagrammer` -:PROPERTIES: -:purpose: Converts a plan description into a visual graph structure directive using a neural model. -:input: `(context plist)` -:output: `(neural-directive string)` ; e.g., the prompt sent to the neural model -:side-effects: None -:END: - - This function takes a context plist, extracts the plan description from the `:payload`, and generates a prompt or directive to be used by a neural model to synthesize the graph. The prompt should focus on the *content* to be visualized, leaving Mermaid syntax details to the `synthesize-mermaid` function. The prompt should instruct the LLM to return *only* the mermaid code. - -*** 2.3. `d2-layout` (Future Enhancement) -:PROPERTIES: -:purpose: Applies D2 layout engine to a Mermaid graph string for complex layouts. -:input: `(mermaid-code string)` -:output: `(d2-mermaid-code string)` -:side-effects: Executes external D2 process -:END: - - This function (potentially implemented later) takes a Mermaid graph string and uses the D2 layout engine to improve the visual arrangement of the diagram. This would likely involve shelling out to a D2 process. diff --git a/notes/org-skill-dotemacs.org b/notes/org-skill-dotemacs.org deleted file mode 100644 index 73bd9b4..0000000 --- a/notes/org-skill-dotemacs.org +++ /dev/null @@ -1,60 +0,0 @@ -:PROPERTIES: -:ID: fbc33323-0795-4fa3-9ebf-3f2ff8daade5 -:CREATED: [2026-04-07 Tue 12:57] -:EDITED: [2026-04-07 Tue 13:42] -:END: -#+TITLE: SKILL: Dotemacs Configuration (Universal Literate Note) -#+STARTUP: content -#+FILETAGS: :emacs:config:literate:psf: - -* Overview -The *Dotemacs* project represents the "Operating System" configuration. It transforms Emacs into the primary computing tool by leveraging modular, literate Org-mode files that tangle into a high-performance environment. - -* Phase A: Demand (PRD) -:PROPERTIES: -:STATUS: FROZEN -:END: - -** 1. Purpose -Define the requirements for a modular, optimized, and fully documented Emacs environment. - -** 2. User Needs -- *Modularity:* Split the monolithic `emacs.org` into functional modules (core, ui, gtd, ai, etc.). -- *Literate Mandate:* Every significant setting must be justified and explained in prose. -- *Integration:* Seamless connectivity with `org-agent`, `org-roam`, and `org-gtd`. -- *Bootstrapping:* Fast startup using `early-init.el` and lazy-loading. - -** 3. Success Criteria -*** TODO Monolithic modularization completion -*** TODO Standardize all paths to ~/memex/ -*** TODO Ensure Org 10.0-pre bootstrap compatibility -*** TODO Document all major package configurations - -* Phase B: Blueprint (PROTOCOL) -:PROPERTIES: -:STATUS: SIGNED -:END: - -** 1. Architectural Intent -The configuration is structured as a collection of feature-specific Org files that tangle into the `~/.emacs.d/` directory. - -** 2. Semantic Interfaces -#+begin_src elisp -(defun dotemacs-tangle-module (module-name) - "Tangels a specific module Org file into its .el counterpart.") - -(defun dotemacs-verify-load-path () - "Ensures all Memex paths are correctly registered in the load-path.") -#+end_src - -* Phase D: Build (Implementation) -The implementation is distributed across the `emacs-*.org` files in `projects/dotemacs/`. - -** Core Module Tangle -#+begin_src elisp -;; Example tangle header -;; #+PROPERTY: header-args:elisp :tangle ~/.emacs.d/lisp/core.el -#+end_src - -* Phase E: Chaos (Verification) -Verification involves `M-x benchmark-init` and ensuring zero warnings during the byte-compilation phase. diff --git a/notes/org-skill-emacs-bridge.org b/notes/org-skill-emacs-bridge.org deleted file mode 100644 index 25c38e8..0000000 --- a/notes/org-skill-emacs-bridge.org +++ /dev/null @@ -1,104 +0,0 @@ -:PROPERTIES: -:ID: 59ac52fb-2310-4a9d-8e4e-0263af15181c -:CREATED: [2026-03-30 Mon 21:16] -:EDITED: [2026-04-07 Tue 13:42] -:END: -#+TITLE: SKILL: Emacs Bridge Agent (Universal Literate Note) -#+STARTUP: content -#+FILETAGS: :bridge:emacs:io:system:psf: - -* Overview -The *Emacs Bridge Agent* is the primary sensory and motor interface to Emacs. It abstracts TCP socket management, allowing the core kernel to interact with buffers as native data structures. - -* Phase A: Demand (PRD) -:PROPERTIES: -:STATUS: FROZEN -:END: - -** 1. Purpose -Define the transport layer for Org-Agent Communication Protocol (OACP). - -** 2. User Needs -- *Isolation:* Kernel remains transport-agnostic. -- *Persistence:* Multi-client server support for simultaneous sessions. -- *Dispatch:* Reliable routing of actions to actuators and sensors to the kernel. - -** 3. Success Criteria -*** TODO Socket Listener Initialization -*** TODO Multi-client Connection Handling -*** TODO OACP Message Framing Verification - -* Phase B: Blueprint (PROTOCOL) -:PROPERTIES: -:STATUS: SIGNED -:END: - -** 1. Architectural Intent -Interfaces for TCP I/O and protocol framing. Source of truth is the OACP specification. - -** 2. Semantic Interfaces -#+begin_src lisp -(defun start-emacs-server (&key (port 9105)) - "Starts the OACP listener.") - -(defun broadcast-to-emacs (action-plist) - "Sends a framed message to all connected clients.") -#+end_src - -* Phase D: Build (Implementation) - -** TCP Sensory Layer -#+begin_src lisp :tangle ../projects/org-skill-emacs-bridge/src/bridge-logic.lisp -(defun handle-emacs-client (stream) - ;; Logic for parsing length-prefixed OACP messages - (format nil "Handling client on stream: ~a" stream)) -#+end_src - -** Outbound Actuation -#+begin_src lisp :tangle ../projects/org-skill-emacs-bridge/src/bridge-logic.lisp -(defun stream-to-emacs (stream action-plist) - "Streams a chunk of data to a specific Emacs client over OACP using framing." - (let* ((type (or (getf action-plist :type) :request)) - (payload (getf action-plist :payload)) - ;; Ensure Emacs always receives a :payload drawer - (envelope (if (and (getf action-plist :type) payload) - action-plist - (let ((clean-payload (copy-list action-plist))) - (remf clean-payload :type) - (remf clean-payload :id) - (list :type type - :id (or (getf action-plist :id) (get-universal-time)) - :payload clean-payload)))) - (msg (prin1-to-string envelope)) - (len (length msg)) - (framed (format nil "~6,'0x~a" len msg))) - (handler-case - (progn - (write-string framed stream) - (finish-output stream)) - (error (c) - (kernel-log "BRIDGE - Lost client: ~a" stream) - (org-agent:unregister-emacs-client stream))))) - -(defun broadcast-to-emacs (action-plist context) - "Sends a framed message back to the client that sent the stimulus, or all clients if async." - (let ((stream (getf context :reply-stream))) - (if stream - (stream-to-emacs stream action-plist) - (progn - (kernel-log "BRIDGE - Async broadcast to all clients...") - (bt:with-lock-held (org-agent:*clients-lock*) - (dolist (s org-agent:*emacs-clients*) - (stream-to-emacs s action-plist))))))) -#+end_src - -* Registration -#+begin_src lisp -(org-agent:register-actuator :emacs #'broadcast-to-emacs) - -(defskill :skill-emacs-bridge - :priority 100 - :trigger (lambda (context) nil) - :neuro (lambda (context) nil) - :symbolic (lambda (action context) action)) -#+end_src diff --git a/notes/org-skill-embedding-generator.org b/notes/org-skill-embedding-generator.org deleted file mode 100644 index a1bb11e..0000000 --- a/notes/org-skill-embedding-generator.org +++ /dev/null @@ -1,80 +0,0 @@ -:PROPERTIES: -:ID: 6cd0b4d7-e7cf-49ba-a847-e81c4ace0f76 -:CREATED: [2026-04-04 Sat 20:27] -:EDITED: [2026-04-07 Tue 13:42] -:END: -#+TITLE: SKILL: Embedding Generator (Universal Literate Note) -#+STARTUP: content -#+FILETAGS: :embeddings:neural:psf: - -* Overview -The *Embedding Generator* provides vector representations of text for semantic search and neural memory. - -* Phase A: Demand (PRD) -:PROPERTIES: -:STATUS: FROZEN -:END: - -** 1. Purpose -Generate embeddings for text strings. - -** 2. User Needs -- *Provider Choice:* Support for local (Ollama) or remote (Gemini, OpenAI) providers. -- *Batching:* Efficiency through batching text (future-proof). - - -* Phase B: Blueprint (PROTOCOL) -:PROPERTIES: -:STATUS: SIGNED -:END: - -** Phase B: Blueprint (PROTOCOL) -:PROPERTIES: -:STATUS: DRAFT -:END: - -*** 1. Architectural Intent - -This system aims for a flexible and extensible architecture that can accommodate different embedding providers (local or remote) while maintaining a consistent interface for the user. It also seeks to optimize for batch processing to improve throughput. The core design principle is *provider abstraction*. - -*** 2. Semantic Interfaces - -#+BEGIN_SRC lisp -;;; Primary Function: Generate Embeddings -;;; Input: A list of strings, and provider configuration -;;; Output: A list of embedding vectors (lists of floats). - -(defun generate-embeddings (texts provider-config) - """Generates embeddings for a list of texts using the specified provider.""") - -;;; Provider Configuration Structure -;;; This plist defines the provider to use, and any necessary credentials or parameters. - -;;; Example: Local Ollama provider -;;; (:provider :ollama :model "mistralai/Mistral-7B-Instruct-v0.2") - -;;; Example: Remote Gemini provider -;;; (:provider :gemini :api-key "YOUR_API_KEY" :model "gemini-1.5-pro") - -;;; Example: Remote OpenAI provider. -;;; (:provider :openai :api-key "YOUR_API_KEY" :model "text-embedding-ada-002") - -;;; Sub-Function: (Abstract) Provider-Specific Embedding Generation -;;; This function is implemented differently for each provider. - -(defgeneric generate-embeddings-from-provider (texts provider-config)) - -;;; Example implementation for :ollama provider -(defmethod generate-embeddings-from-provider (texts (provider-config (eql (getf provider-config :provider :ollama)))) - """Generates embeddings using a local Ollama server.""") - -;;; Example implementation for :gemini provider -(defmethod generate-embeddings-from-provider (texts (provider-config (eql (getf provider-config :provider :gemini)))) - """Generates embeddings using the Gemini API.""") - -;;; Example implementation for :openai provider -(defmethod generate-embeddings-from-provider (texts (provider-config (eql (getf provider-config :provider :openai)))) - """Generates embeddings using the OpenAI API.""") - -#+END_SRC - diff --git a/notes/org-skill-environment-config.org b/notes/org-skill-environment-config.org deleted file mode 100644 index 835cc13..0000000 --- a/notes/org-skill-environment-config.org +++ /dev/null @@ -1,69 +0,0 @@ -: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:sovereignty:psf: - -* Overview -The *Environment Configuration Manager* is the source of truth for user preferences. It persists settings (like LLM Model Fleets) into the kernel's Object Store, 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 Object Store. -- *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 Object Store. Provide getter/setter functions for the "LLM Fleet." - -** 2. Semantic Interfaces - -*** Fleet Configuration -#+begin_src lisp :tangle ../projects/org-skill-environment-config/src/config-logic.lisp -(in-package :org-agent) - -(defun set-llm-model (provider model-id) - "Registers a preferred model for a provider in the Object Store." - (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 *object-store*) obj) - (kernel-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 Object Store." - (let* ((config-id (format nil "config-llm-~a" (string-downcase (string provider)))) - (obj (gethash config-id *object-store*))) - (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 - :neuro (lambda (context) nil) - :symbolic (lambda (action context) action)) -#+end_src diff --git a/notes/org-skill-formal-verification.org b/notes/org-skill-formal-verification.org deleted file mode 100644 index e7eb92d..0000000 --- a/notes/org-skill-formal-verification.org +++ /dev/null @@ -1,137 +0,0 @@ -:PROPERTIES: -:ID: 4819956d-a2ec-403d-99f8-4ccb13efb7c2 -:CREATED: [2026-03-31 Tue 20:28] -:EDITED: [2026-04-07 Tue 13:42] -:END: -#+TITLE: SKILL: Formal Verification Gate (Universal Literate Note) -#+STARTUP: content -#+FILETAGS: :security:logic:formal-methods:psf: - -* Overview -The *Formal Verification Gate* replaces heuristic whitelisting with symbolic logic proofs. It ensures that every action proposed by System 1 is *provably safe* against the kernel's core security invariants. - -* Phase A: Demand (PRD) -:PROPERTIES: -:STATUS: FROZEN -:END: - -** 1. Purpose -Define a logic-based verification layer for high-integrity decision making. - -** 2. User Needs -- *Invariants:* Define core security properties (e.g., "No unauthenticated network I/O"). -- *SMT Integration:* Translate Lisp actions into SMT-LIB format for external solvers (Z3). -- *Proof of Safety:* Deny any action that cannot be proven safe. - -* Phase D: Build (Implementation) - -** Invariants Registry -#+begin_src lisp :tangle projects/org-skill-formal-verification/src/verification-logic.lisp -(defparameter *security-invariants* - '((:name "Path-Safety" :formula "(assert (forall ((p String)) (=> (is-write-op p) (str.prefixof \"/home/user/memex\" p))))"))) - -(defun verify-action-logic (action) - "Translates ACTION into an SMT-LIB query and invokes Z3 to prove safety. - This is the SOTA upgrade from simple whitelisting." - (let* ((payload (getf action :payload)) - (cmd (getf payload :cmd)) - ;; Mock translation for demonstration of the formal gate - (smt-query (format nil "(declare-fun cmd () String) (assert (= cmd \"~a\")) ~{~a~%~} (check-sat)" - cmd (mapcar (lambda (i) (getf i :formula)) *security-invariants*)))) - - (kernel-log "SYMBOLIC [Formal] - Verifying logic formula...") - ;; In a full implementation, we'd pipe smt-query to 'z3 -smt2' - (if (search "rm -rf" cmd) ; Example of a failing proof - nil - t))) -#+end_src - -* Registration -#+begin_src lisp -(defskill :skill-formal-verification - :priority 100 - :trigger (lambda (context) nil) - :neuro (lambda (context) nil) - :symbolic (lambda (action context) (if (verify-action-logic action) action nil))) -#+end_src - - -* Phase B: Blueprint (PROTOCOL) -:PROPERTIES: -:STATUS: SIGNED -:END: - -* Phase B: Blueprint (PROTOCOL) -:PROPERTIES: -:STATUS: TODO -:END: - -** 1. Architectural Intent - - The Formal Verification Gate aims to provide a *provably secure* alternative to brittle whitelisting approaches. It will intercept proposed actions from other skills, translate them into logical statements, and use an SMT solver (e.g., Z3) to verify that these actions do *not* violate any defined security invariants. This provides a high degree of confidence in the safety and integrity of the system. - - *Key Goals:* - - *Soundness:* If the solver says an action is safe, it *is* safe (with respect to the defined invariants). - - *Completeness:* Ideally, the system should be able to prove the safety of all genuinely safe actions. (In practice, this may not always be achievable, but we strive for it.) - - *Performance:* Verification should be fast enough to not introduce unacceptable latency. - -** 2. Semantic Interfaces - -*** Invariant Definition - - *Signature:* `(define-security-invariant name description formula)` - - *Purpose:* Defines a new security invariant that the formal verification gate will use to check actions. - - *Arguments:* - - `name` (symbol): A unique symbolic identifier for the invariant. - - `description` (string): A human-readable description of the invariant. - - `formula` (string): An SMT-LIB formula representing the invariant. Free variables within the formula are implicitly universally quantified. This formula should return 'true' under a satisfying model. - - *Example:* - #+begin_src lisp - (define-security-invariant 'no-network-io - "Prevents actions from initiating unauthorized network communication." - "(assert (forall ((op String)) (=> (is-network-op op) (= op \"false\"))))") - #+end_src - -*** Action Verification - - *Signature:* `(verify-action action)` - - *Purpose:* This is the core function that the skill uses to determine if an action is safe, given the current set of invariants. - - *Arguments:* - - `action` (alist): The action to be verified represented as an alist. Expected format: '((:payload (:cmd "command string" ...)) ...) - - *Return Value:* - - `t`: If the action can be proven safe with respect to all defined invariants. - - `nil`: If the action is determined to be unsafe (i.e., violates at least one invariant) or if the solver times out. - - *Side Effects:* - - May log verbose debug information to the kernel log. - - Invokes an external SMT solver (e.g., Z3) to perform the logical reasoning. - - *Implementation Notes:* - - The `action` alist and especially the `:payload` structure should be considered as a general information carrier between skills in the system. - - Action parameters can be dynamically accessed and embedded into SMT queries. - -*** SMT Translation - - *Signature:* `(action-to-smt action invariants)` - - *Purpose:* Translates a Lisp action into a SMT-LIB query. This function encapsulates the logic for converting actions and invariants into a form suitable for the solver. - - *Arguments:* - - `action` (alist): The action to be verified. - - `invariants` (list): A list of security invariants (each defined using `define-security-invariant`) to check against the action. - - *Return Value:* - - (string): A string containing the complete SMT-LIB query. - - *Example:* - #+begin_src lisp - (action-to-smt '((:payload (:cmd "ls /tmp"))) *security-invariants*) - ; => "(declare-fun cmd () String) (assert (= cmd \"ls /tmp\")) ... (check-sat)" - #+end_src - diff --git a/notes/org-skill-function-calling.org b/notes/org-skill-function-calling.org deleted file mode 100644 index afa0da8..0000000 --- a/notes/org-skill-function-calling.org +++ /dev/null @@ -1,89 +0,0 @@ -:PROPERTIES: -:ID: 1cbff23d-aef1-412f-97a0-260302034001 -:CREATED: [2026-03-31 Tue 18:43] -:EDITED: [2026-04-07 Tue 13:42] -:END: -#+TITLE: SKILL: Native Function Calling (Universal Literate Note) -#+STARTUP: content -#+FILETAGS: :llm:tools:json-schema:reliability:psf: -#+DEPENDS_ON: org-skill-org-json-bridge - -* Overview -The *Native Function Calling* skill provides the translation layer between the system's deterministic Lisp interfaces and the LLM's neural tool-calling capabilities. It ensures that System 1 (the LLM) interacts with the world via structured, validated schemas rather than raw text plists, virtually eliminating "formatting hallucinations." - -* Phase A: Demand (PRD) -:PROPERTIES: -:STATUS: FROZEN -:END: - -** 1. Purpose -Define a high-reliability bridge for LLM-native "Tool Use." - -** 2. User Needs -- *Schema Generation:* Automatically convert Lisp `defun` signatures into JSON Schema tool definitions. -- *Reliable Ingress:* Parse the LLM's structured `tool_calls` response back into a valid Lisp plist. -- *Provider Agnostic:* Support schema formats for Gemini, OpenAI, and Anthropic. -- *Validation:* Ensure arguments match the required types before reaching System 2. - -** 3. Success Criteria -*** TODO Lisp-to-JSON Schema conversion logic verification -*** TODO Multi-provider schema formatting (Gemini vs OpenAI) -*** TODO Response parsing from tool_call to symbolic action - - -* Phase B: Blueprint (PROTOCOL) -:PROPERTIES: -:STATUS: SIGNED -:END: - -* Phase B: Blueprint (PROTOCOL) -:PROPERTIES: -:STATUS: DRAFT -:END: - -** 1. Architectural Intent - -The core intent is to create a robust, bi-directional translation layer. This layer guarantees type safety and schema adherence between the LLM's Tool Calling mechanism and the Lisp environment. The design emphasizes clear separation of concerns: schema generation, response parsing, and provider-specific formatting. We should aim for a modular architecture that allows for easier extension to new LLM providers and new data types. The validation process must be explicit and easily auditable. Error handling is critical; parsing failures should yield informative error messages, enabling rapid debugging. - -** 2. Semantic Interfaces (Lisp Signatures) - -*** `defun json-schema-from-defun (function-name)` - - *Purpose:* Generates a JSON Schema representation from a Lisp function definition. - - *Args:* - - `function-name`: A symbol representing the name of the Lisp function. - - *Returns:* A Lisp plist representing the JSON Schema. Keys should correspond to standard JSON Schema fields (e.g., `:type`, `:properties`, `:required`). - - *Side Effects:* None. Pure function. - -*** `defun parse-tool-call-arguments (function-name arguments tool-provider)` - - *Purpose:* Parses the arguments returned by an LLM tool call into a Lisp plist. Validates the arguments against the schema generated by `json-schema-from-defun`. - - *Args:* - - `function-name`: A symbol representing the name of the Lisp function being called. - - `arguments`: A string containing the JSON arguments returned by the LLM's `tool_calls` field. - - `tool-provider`: A keyword (e.g., `:openai`, `:gemini`, `:anthropic`) indicating the LLM provider. - - *Returns:* A Lisp plist representing the parsed arguments, or `nil` if parsing fails. On failure, appropriate error messages should be logged. - - *Side Effects:* May signal errors. - -*** `defun format-json-schema-for-provider (json-schema tool-provider)` - - *Purpose:* Formats the automatically generated JSON schema to the specific format required by each LLM provider. - - *Args:* - - `json-schema`: A Lisp plist containing the generic JSON schema (output of `json-schema-from-defun`). - - `tool-provider`: A keyword (e.g., `:openai`, `:gemini`, `:anthropic`) indicating the LLM provider. - - *Returns:* A Lisp plist representing the provider-specific JSON schema. - - *Side Effects:* None. Pure function. - -*** `defun validate-arguments (function-name arguments)` - - *Purpose:* Validates that the parsed arguments conform to the expected schema. - - *Args:* - - `function-name`: A symbol identifying the function being called. Used to retrieve the function definition and associated JSON schema. - - `arguments`: A Lisp plist containing the parsed arguments. - - *Returns:* `T` if validation succeeds, `NIL` if it fails. - - *Side Effects:* May signal errors if validation fails. Logs validation errors. - -** 3. Data Structures - -*** JSON Schema (Lisp Representation) - A Lisp plist mimicking the structure of a JSON Schema. Keys will generally be keywords mirroring JSON Schema vocabulary (e.g., `:type`, `:properties`, `:required`, `:description`). Values will be Lisp datatypes corresponding to the schema datatypes (e.g., symbols, strings, booleans, numbers, lists of symbols/strings/numbers). - -*** Tool Call Response - The expected format of an LLM's `tool_calls` response will be parsed using a dedicated JSON parsing library. `parse-tool-call-arguments` will handle the conversion to lisp datatypes based upon the `json-schema` - diff --git a/notes/org-skill-git-steward.org b/notes/org-skill-git-steward.org deleted file mode 100644 index 9534b15..0000000 --- a/notes/org-skill-git-steward.org +++ /dev/null @@ -1,109 +0,0 @@ -:PROPERTIES: -:ID: 71cbb872-c191-4ebb-bf65-b2c936f01fea -:CREATED: [2026-04-04 Sat 20:27] -:EDITED: [2026-04-07 Tue 13:42] -:END: -#+TITLE: SKILL: Git Steward (Universal Literate Note) -#+STARTUP: content -#+FILETAGS: :git:vcs:system:psf: - -* Overview -The *Git Steward* maintains the integrity of the workspace by automating version control operations. - -* Phase A: Demand (PRD) -:PROPERTIES: -:STATUS: FROZEN -:END: - -** 1. Purpose -Automate Git operations for the Memex. - -** 2. User Needs -- *Status:* Retrieve the current state of the repository. -- *Commit:* Automate staging and committing changes. -- *Push:* Synchronize with remote repositories. - - -* Phase B: Blueprint (PROTOCOL) -:PROPERTIES: -:STATUS: SIGNED -:END: - -** Phase B: Blueprint (PROTOCOL) -:PROPERTIES: -:STATUS: DRAFT -:END: - -*** 1. Architectural Intent -The *Git Steward* will act as a central service for managing Git operations within the Memex environment. It will expose a well-defined interface for other components to interact with, abstracting away the complexities of Git execution. It prioritizes ease of use, reliability, and integration with existing Memex systems. This protocol defines the functions that will be available, their inputs, and expected outputs. Functions are defined using Lisp signatures to ensure precise and unambiguous specification. - -*** 2. Semantic Interfaces - -**** a. git-status - - *Purpose:* Retrieves the current status of the Git repository. - - - *Signature:* `(git-status)` - - - *Input:* None - - - *Output:* A plist containing the following keys: - - `:branch` - The current branch name (string). - - `:modified-files` - A list of modified files (list of strings). - - `:untracked-files` - A list of untracked files (list of strings). - - `:staged-files` - A list of files currently staged (list of strings). - - `:ahead` - Number of commits ahead of remote (integer, or `nil` if not tracking a remote). - - `:behind` - Number of commits behind remote (integer, or `nil` if not tracking a remote). - - - *Example:* `(:branch "main" :modified-files ("file1.txt" "file2.org") :untracked-files ("new_file.txt") :staged-files ("file1.txt") :ahead 2 :behind 1)` - -**** b. git-commit - - *Purpose:* Stages and commits changes to the Git repository. - - - *Signature:* `(git-commit :message string :files list-of-strings)` - - - *Input:* - - `:message` - The commit message (string). - - `:files` - A list of specific files to stage and commit (list of strings). If nil, all modified and added files are staged. - - - *Output:* A boolean value. `T` for success, `nil` for failure. On failure, an error message will be logged. - - - *Example:* `(git-commit :message "Updated documentation" :files nil)` - -**** c. git-push - - *Purpose:* Pushes commits to a remote repository. - - - *Signature:* `(git-push :remote string :branch string)` - - - *Input:* - - `:remote` - The name of the remote repository (string). - - `:branch` - The name of the branch to push (string). - - - *Output:* A boolean value. `T` for success, `nil` for failure. On failure, an error message will be logged. - - - *Example:* `(git-push :remote "origin" :branch "main")` - -**** d. git-pull - - *Purpose:* Pulls commits from a remote repository. - - - *Signature:* `(git-pull :remote string :branch string)` - - - *Input:* - - `:remote` - The name of the remote repository (string). - - `:branch` - The name of the branch to pull (string). - - - *Output:* A boolean value. `T` for success, `nil` for failure. On failure, an error message will be logged. - - - *Example:* `(git-pull :remote "origin" :branch "main")` - -**** e. git-add - - *Purpose:* Adds new files to the staging area - - - *Signature:* `(git-add :files list-of-strings)` - - - *Input:* - - `:files` - A list of files to add to staging. - - - *Output:* A boolean value. `T` for success, `nil` for failure. - - - *Example:* `(git-add :files '("new_file.txt" "another_file.org"))` - diff --git a/notes/org-skill-groomer.org b/notes/org-skill-groomer.org deleted file mode 100644 index 53a244e..0000000 --- a/notes/org-skill-groomer.org +++ /dev/null @@ -1,27 +0,0 @@ -:PROPERTIES: -:ID: 992d2218-548d-4547-bd2b-7b425cb01ca7 -:CREATED: [2026-03-31 Tue 20:28] -:EDITED: [2026-04-07 Tue 13:42] -:END: -#+TITLE: SKILL: Autonomous Groomer Agent (Universal Literate Note) -#+STARTUP: content -#+FILETAGS: :refactoring:optimization:debt:psf: -#+DEPENDS_ON: skill-atomic-notes skill-tdd-runner - -* Overview -The *Groomer Agent* is the system's "Immune System" for code and notes. It autonomously audits the PSF ecosystem for technical debt, duplication, and architectural drift, proposing surgical refactors to maintain the "Minimalist Core" mandate. - -* Phase A: Demand (PRD) -:PROPERTIES: -:STATUS: DRAFT -:END: - -** 1. Purpose -Enforce zero-bloat and high-maintainability standards across the PSF. - -** 2. User Needs -- *Debt Detection:* Identify duplicate Lisp logic or redundant Org headlines. -- *Autonomous Refactoring:* Propose surgical code changes to simplify implementation. -- *Verification:* Ensure refactors do not break functionality (via TDD Runner). -- *Note Grooming:* Consolidate fragmented atomic notes into coherent structures. - diff --git a/notes/org-skill-gtd.org b/notes/org-skill-gtd.org deleted file mode 100644 index f21fb09..0000000 --- a/notes/org-skill-gtd.org +++ /dev/null @@ -1,66 +0,0 @@ -:PROPERTIES: -:ID: bbcacb7b-c0ff-4f7e-8bf4-c6ba152a19ce -:CREATED: [2026-03-30 Mon 21:16] -:EDITED: [2026-04-07 Tue 13:42] -:END: -#+TITLE: SKILL: Getting Things Done (GTD) (Universal Literate Note) -#+STARTUP: content -#+FILETAGS: :gtd:execution:workflow:psf: - -* Overview -This skill defines the *GTD Execution Hub*, the single source of truth for all commitments. It governs how the agent perceives priorities and tracks progress through the PSF Consensus Loop using the `org-gtd` v4.0 DAG architecture. - -* Phase A: Demand (PRD) -:PROPERTIES: -:STATUS: FROZEN -:END: - -** 1. Purpose -Define the interfaces for task perception, project tracking, and commitment management. - -** 2. User Needs -- *Allen-Sovereign Methodology:* Frictionless capture and rigorous clarification. -- *DAG Structure:* Support for `org-gtd` v4.0 dependency graphs (:TRIGGER:, :BLOCKER:). -- *Shadow Orchestration:* Tracking of `:PSF-STATE:` properties for engineering projects. -- *Institutional Memory Integration:* Extraction of learnings before project completion. - -** 3. Success Criteria -*** TODO Commitment Scanning -*** TODO PSF-State Transition Verification -*** TODO Stalled Project Identification - - -* Phase B: Blueprint (PROTOCOL) -:PROPERTIES: -:STATUS: SIGNED -:END: - - -* Phase B: Blueprint (PROTOCOL) -:PROPERTIES: -:STATUS: DRAFT -:END: - -** 1. Architectural Intent -The GTD Execution Hub will be implemented as a collection of functions operating on the `org-gtd` v4.0 DAG. It will provide a consistent interface for task capture, clarification, and execution status monitoring. Key elements include: - -- *Capture and Clarify:* Functions to create, process, and integrate new tasks into the DAG. -- *Dependency Management:* Functions to navigate and update dependencies based on `:TRIGGER:` and `:BLOCKER:` properties. -- *PSF-State Tracking:* Functions to monitor and report on `:PSF-STATE:` transitions. -- *Completion Review:* Functions to summarize completed projects and extract lessons learned. - -The system should be modular and extensible, allowing for easy integration with other PSF components and external data sources. - -** 2. Semantic Interfaces (Lisp Signatures) - -*** Function: `gtd/capture-task` -Capture a new task and integrate it into the appropriate context. - - :signature `((description string) (context keyword) &optional (project org-id)) :returns org-id` - :description "Capture a new task described by DESCRIPTION and add it to CONTEXT. If PROJECT is specified, link the new task as a subtask of PROJECT." - -*** Function: `gtd/clarify-task` -Process a newly captured task, adding details and dependencies. - - :signature `((task-id org-id) (details alist)) :returns org-id` - :description "Clarify a task, adding details and dependencies specified in the DETAILS alist. Example: '((:priority \ diff --git a/notes/org-skill-hardware-inhabitation.org b/notes/org-skill-hardware-inhabitation.org deleted file mode 100644 index 4e6b9d9..0000000 --- a/notes/org-skill-hardware-inhabitation.org +++ /dev/null @@ -1,84 +0,0 @@ -:PROPERTIES: -:ID: a6295e1b-2de1-4c92-90cd-e54f1bf1974e -:CREATED: [2026-03-31 Tue 20:28] -:EDITED: [2026-04-07 Tue 13:42] -:END: -#+TITLE: SKILL: Hardware Inhabitation Agent (Universal Literate Note) -#+STARTUP: content -#+FILETAGS: :sovereignty:deployment:bare-metal:lisp:psf: -#+DEPENDS_ON: skill-shell-actuator skill-environment-config - -* Overview -The *Hardware Inhabitation Agent* is the system's "Physical Interface." It manages the deployment of the Lisp Machine across different hardware compartments, ensuring absolute sovereignty via bare-metal inhabitation and environment portability. - -* Phase A: Demand (PRD) -:PROPERTIES: -:STATUS: FROZEN -:END: - -** 1. Purpose -Define the interfaces for hardware-level deployment and image serialization. - -** 2. User Needs -- *Bare-Metal Deployment:* Support for running Lisp directly on minimal hardware (e.g., RISC-V/ARM). -- *Image Portability:* Serialize and move the live Lisp Image across environments. -- *Hardware Inventory:* Maintain a manifest of available physical actuators and sensors. -- *Sovereignty Audit:* Verify that the current inhabitation is free from non-sovereign dependencies. - - -* Phase B: Blueprint (PROTOCOL) -:PROPERTIES: -:STATUS: SIGNED -:END: - -* Phase B: Blueprint (PROTOCOL) - :PROPERTIES: - :STATUS: ACTIVE - :END: - - ** 1. Architectural Intent - The Hardware Inhabitation Agent aims to provide an abstraction layer facilitating the Lisp Machine's deployment and execution directly on hardware, minimizing reliance on external operating systems or services. This promotes sovereignty by ensuring control from the metal up, and facilitates image portability for seamless transitions between hardware environments. It will manage hardware interfaces, image serialization/deserialization, and sovereignty auditing via a principled set of Lisp-defined interfaces. - - ** 2. Semantic Interfaces (Lisp Signatures) - - *** 2.1 Bare-Metal Deployment - - - `(bare-metal-deploy image-path hardware-configuration)` - - *Purpose:* Deploys a Lisp image onto bare metal. - - *Args:* - - `image-path`: Path to the serialized Lisp image file. - - `hardware-configuration`: A data structure (e.g., plist) specifying hardware-specific parameters, such as memory map, interrupt vectors, and device drivers. - - *Returns:* `T` on successful deployment, `NIL` on failure. On success returns a handle representing the deployed process. - - *Side Effects:* Overwrites the target hardware's boot sector with the Lisp image stub, or performs the equivalent action to initiate Lisp execution. - - *** 2.2 Image Serialization & Deserialization - - - `(serialize-lisp-image output-path)` - - *Purpose:* Serializes the current Lisp Machine's state into a relocatable image file. - - *Args:* - - `output-path`: The path to the output file where the image will be stored. - - *Returns:* `T` on successful serialization, `NIL` on failure. - - *Side Effects:* Creates a file at `output-path` containing the serialized image. - - - `(deserialize-lisp-image input-path)` - - *Purpose:* Deserializes a Lisp Machine image from a file. - - *Args:* - - `input-path`: The path to the Lisp image file. - - *Returns:* `T` on successful deserialization. The restored Lisp Machine state. - - *Side Effects:* Overwrites the current Lisp Machine's state with the contents of the image file. Potentially destructive. - - *** 2.3 Hardware Inventory - - - `(get-hardware-manifest)` - - *Purpose:* Retrieves a manifest of available hardware resources. - - *Args:* None - - *Returns:* A list / plist describing the available actuators and sensors, including their types, IDs, and any relevant configuration parameters. Example: `((:type :gpio :id "gpio1" :direction :output) (:type :temperature-sensor :id "temp0"))` - - *** 2.4 Sovereignty Audit - - - `(audit-sovereignty)` - - *Purpose:* Verifies that the current Lisp Machine inhabitation is free from external dependencies that might compromise sovereignty. Relies on comparing known-good checksums of system components. - - *Args:* None - - *Returns:* `T` if the system passes the audit, `NIL` otherwise. May also return a list of dependencies that failed the audit, along with discrepancy information. - - *Side Effects:* May generate audit logs. - diff --git a/notes/org-skill-hook-manager.org b/notes/org-skill-hook-manager.org deleted file mode 100644 index eafd971..0000000 --- a/notes/org-skill-hook-manager.org +++ /dev/null @@ -1,75 +0,0 @@ -:PROPERTIES: -:ID: 21bcb7ff-1b69-45ae-8844-981c7fc2373c -:CREATED: [2026-04-04 Sat 20:27] -:EDITED: [2026-04-07 Tue 13:42] -:END: -#+TITLE: SKILL: Hook Manager (Universal Literate Note) -#+STARTUP: content -#+FILETAGS: :hooks:event-driven:system:psf: - -* Overview -The *Hook Manager* enables event-driven extensibility within the agent by allowing functions to be registered and executed at specific lifecycle points. - -* Phase A: Demand (PRD) -:PROPERTIES: -:STATUS: FROZEN -:END: - -** 1. Purpose -Provide a hook-based event system. - -** 2. User Needs -- *Registration:* Register functions to be called on specific hooks. -- *Execution:* Trigger all registered functions for a given hook. - - -* Phase B: Blueprint (PROTOCOL) -:PROPERTIES: -:STATUS: SIGNED -:END: - -* Phase B: Blueprint (PROTOCOL) -:PROPERTIES: -:STATUS: DRAFT -:END: - -** 1. Architectural Intent -The Hook Manager will provide a centralized mechanism for registering and executing hook functions. It aims for simplicity, flexibility, and minimal performance overhead. The core design principle is a simple registry mapping hook names to lists of functions. - -** 2. Semantic Interfaces - -*** 2.1. `register-hook` - -Registers a function to be executed when a specific hook is triggered. - - Signature: `(register-hook hook-name function)` - - - `hook-name`: A symbol representing the name of the hook. - - `function`: A function (lambda or symbol) to be executed when the hook is triggered. The function's arguments depend on the hook (see hook-specific documentation). - - Example: - `(register-hook 'before-planning #'my-planning-hook)` - -*** 2.2. `trigger-hook` - -Executes all registered functions for a given hook. - - Signature: `(trigger-hook hook-name &rest args)` - - - `hook-name`: A symbol representing the name of the hook to trigger. - - `&rest args`: Optional arguments to be passed to the registered functions. The meaning and number of arguments depends on the specific hook. - - Example: - `(trigger-hook 'after-planning current-plan)` - -*** 2.3. `remove-hook` - -Removes a registered function from a hook. - - Signature: `(remove-hook hook-name function)` - - - `hook-name`: A symbol representing the name of the hook. - - `function`: The function to remove from the hook's registry. - - Example: - `(remove-hook 'before-planning #'my-planning-hook)` diff --git a/notes/org-skill-hyper-graph.org b/notes/org-skill-hyper-graph.org deleted file mode 100644 index 138f866..0000000 --- a/notes/org-skill-hyper-graph.org +++ /dev/null @@ -1,61 +0,0 @@ -:PROPERTIES: -:ID: d2ab09fe-2e4f-4b1c-913c-55eb0de347b3 -:CREATED: [2026-03-31 Tue 20:28] -:EDITED: [2026-04-07 Tue 13:42] -:END: -#+TITLE: SKILL: Unified Knowledge Hyper-Graph (Universal Literate Note) -#+STARTUP: content -#+FILETAGS: :knowledge:graph:zettelkasten:psf: -#+DEPENDS_ON: skill-atomic-notes skill-brain-mapper - -* Overview -The *Unified Knowledge Hyper-Graph* extends the agent's memory beyond text. It maps relationships between *Code Blocks, Documents, Media Assets, and Research PDFs*, enabling cross-modal context retrieval. - -* Phase A: Demand (PRD) -:PROPERTIES: -:STATUS: FROZEN -:END: - -** 1. Purpose -Unify the system's diverse information silos into a single, navigable graph. - -** 2. User Needs -- *Cross-Modal Linking:* Connect a Lisp function to a research PDF and an Org PRD. -- *Traceability:* Follow the chain of reasoning from requirement to implementation. -- *Deep Retrieval:* Pull related media assets during plan synthesis. - -* Phase D: Build (Implementation) - -** Graph Traversal -#+begin_src lisp :tangle projects/org-skill-hyper-graph/src/graph-logic.lisp -(defun hyper-graph-trace-lineage (object-id) - "Recursively follows #+ID and [[file:]] links to find related cross-modal nodes." - (let* ((obj (org-agent:lookup-object object-id)) - (links (extract-all-org-links (org-agent:org-object-content obj)))) - (kernel-log "MEMORY [Hyper-Graph] - Tracing lineage for ~a..." object-id) - (loop for link in links collect (resolve-hyper-link link)))) -#+end_src - -* Registration -#+begin_src lisp -(defskill :skill-hyper-graph - :priority 70 - :trigger (lambda (context) (eq (getf (getf context :payload) :sensor) :deep-trace)) - :neuro (lambda (context) "Synthesize a lineage report for the target ID.") - :symbolic (lambda (action context) action)) -#+end_src - - -* Phase B: Blueprint (PROTOCOL) -:PROPERTIES: -:STATUS: SIGNED -:END: - -* Phase B: Blueprint (PROTOCOL) -:PROPERTIES: -:STATUS: DRAFT -:END: - -** 1. Architectural Intent -- *Graph Database:* Utilize an in-memory or persistent graph database (e.g., `neo4cl`). Abstract away the underlying implementation via a generic interface. -- *Unified ID Space:* Every diff --git a/notes/org-skill-inbound-gateway.org b/notes/org-skill-inbound-gateway.org deleted file mode 100644 index 028a565..0000000 --- a/notes/org-skill-inbound-gateway.org +++ /dev/null @@ -1,100 +0,0 @@ -: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:psf: - -* 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 Neurosymbolic 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 kernel. -- *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 Kernel 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 Neurosymbolic 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 Neurosymbolic 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 Kernel. -6. Error handling and logging are performed at each step. - diff --git a/notes/org-skill-inbox-processor.org b/notes/org-skill-inbox-processor.org deleted file mode 100644 index b2bb8f6..0000000 --- a/notes/org-skill-inbox-processor.org +++ /dev/null @@ -1,86 +0,0 @@ -:PROPERTIES: -:ID: 95029300-1d11-444c-a90a-a9f2c5474ca9 -:CREATED: [2026-04-04 Sat 20:27] -:EDITED: [2026-04-07 Tue 13:42] -:END: -#+TITLE: SKILL: Enriched Inbox Processor Agent (Universal Literate Note) -#+STARTUP: content -#+FILETAGS: :inbox:processor:workflow:psf: - -* Overview -The *Enriched Inbox Processor Agent* is responsible for the daily migration of captured nodes from ~inbox.org~ to the ~daily/~ archive. It enforces a strict privacy wall for ~@personal~ content while providing deep semantic enrichment for public research. - -* Phase A: Demand (PRD) -:PROPERTIES: -:STATUS: FROZEN -:END: - -** 1. Purpose -Automate the sorting and enrichment of inbox captures. - -** 2. User Needs -- *Privacy Wall:* Headlines tagged ~@personal~ are moved **symbolically only**. No LLM processing allowed. -- *Semantic Enrichment:* For public items (non-@personal), generate: - 1. A **Summary** sub-heading (1 sentence). - 2. A **Significance** paragraph explaining the PSF use-case. - 3. A **Full Text** extraction for items tagged ~!archive~. -- *Archive-First:* ALL originals are moved to ~daily/YYYY-MM-DD.org~ based on the ~:CREATED:~ property. - -* Phase B: Blueprint (PROTOCOL) -:PROPERTIES: -:STATUS: SIGNED -:END: - -** 1. Architectural Intent -Iterate through the inbox. Use System 2 (Symbolic) to identify the tag. If ~@personal~, perform a direct move. If not, trigger System 1 (Neuro) for enrichment. - -* Phase D: Build (Implementation) - -** Helper: Privacy & Archive Checks -#+begin_src lisp :tangle ../projects/org-skill-inbox-processor/src/processor-logic.lisp -(defun inbox-is-private-p (tags) - (member "@personal" tags :test #'string-equal)) - -(defun inbox-is-archive-p (tags) - (member "!archive" tags :test #'string-equal)) -#+end_src - -** Neural Stage (Enrichment) -#+begin_src lisp :tangle ../projects/org-skill-inbox-processor/src/processor-logic.lisp -(defun neuro-skill-inbox-processor (context) - (let* ((payload (getf context :payload)) - (content (getf payload :content)) - (tags (getf payload :tags)) - (is-archive (inbox-is-archive-p tags))) - (ask-neuro content :system-prompt - (format nil "You are the PSF Librarian. Your goal is to ENRICH this Org-mode capture. -RULES: -1. Create a '** Summary' sub-heading with a 1-sentence summary. -2. Create a '** Significance' sub-heading with a paragraph explaining why this matters to a Sovereign Lisp Machine and how it can be used. -3. ~:[~;~* ARCHIVE MODE: Extract the full text of the item into a '** Full Text' sub-heading, preserving Org-mode structure.~] -4. Return ONLY a Lisp plist with :summary :significance :full-text. -5. NO conversational filler." is-archive)))) -#+end_src - -** Symbolic Stage (The Physical Move) -#+begin_src lisp :tangle ../projects/org-skill-inbox-processor/src/processor-logic.lisp -(defun inbox-process-logic (action context) - (declare (ignore action)) - (let* ((payload (getf context :payload)) - (sensor (getf payload :sensor))) - (when (eq sensor :heartbeat) - (let* ((base-dir (or (uiop:getenv "MEMEX_DIR") "/home/user/memex/")) - (inbox-path (merge-pathnames "inbox.org" base-dir))) - (org-agent:kernel-log "INBOX - Scanning ~a for migration..." (uiop:native-namestring inbox-path)) - ;; Physical move logic would go here using Org AST parsing - '(:target :system :payload (:action :message :text "Inbox processing complete (Simulation).")))))) -#+end_src - -* Registration -#+begin_src lisp -(defskill :skill-inbox-processor - :priority 100 - :trigger (lambda (context) (eq (getf (getf context :payload) :sensor) :heartbeat)) - :neuro #'neuro-skill-inbox-processor - :symbolic #'inbox-process-logic) -#+end_src diff --git a/notes/org-skill-infrastructure.org b/notes/org-skill-infrastructure.org deleted file mode 100644 index ac96984..0000000 --- a/notes/org-skill-infrastructure.org +++ /dev/null @@ -1,59 +0,0 @@ -:PROPERTIES: -:ID: e845b1d7-fc2f-459d-99dd-74e0f6c4ba8f -:CREATED: [2026-04-07 Tue 12:57] -:EDITED: [2026-04-07 Tue 13:42] -:END: -#+TITLE: SKILL: Infrastructure & Security (Universal Literate Note) -#+STARTUP: content -#+FILETAGS: :infrastructure:security:hardening:psf: - -* Overview -The *Infrastructure* project governs the physical and virtual foundations of the Memex. It ensures high availability, security hardening, and operational transparency across cloud and local resources. - -* Phase A: Demand (PRD) -:PROPERTIES: -:STATUS: FROZEN -:END: - -** 1. Purpose -Define the requirements for a secure, resilient, and documented infrastructure posture. - -** 2. User Needs -- *Security Hardening:* Implementation of the OpenClaw security audit findings. -- *Vulnerability Management:* Regular risk assessments and reporting. -- *Inventory Control:* Complete mapping of cloud and local assets. -- *Roadmap Planning:* 30/60/90 day infrastructure evolution. - -** 3. Success Criteria -*** TODO Harden Docker port bindings (bind to 127.0.0.1) -*** TODO Enable and configure UFW firewall -*** TODO Create current state assessment document -*** TODO Add user 'amr' to 'adm' group for log access - -* Phase B: Blueprint (PROTOCOL) -:PROPERTIES: -:STATUS: SIGNED -:END: - -** 1. Architectural Intent -Interfaces for infrastructure state monitoring and automated hardening. - -** 2. Semantic Interfaces -#+begin_src bash -(defun infra-audit-ports () - "Checks for insecure port bindings.") - -(defun infra-check-firewall-status () - "Verifies UFW status.") -#+end_src - -* Phase D: Build (Implementation) -Implementation consists of shell scripts and configuration files located in `projects/infrastructure/`. - -** Security Monitoring -#+begin_src bash -;; Logic for security monitoring stubs -#+end_src - -* Phase E: Chaos (Verification) -Verification involves periodic automated scans and manual audit verification. diff --git a/notes/org-skill-ipfs.org b/notes/org-skill-ipfs.org deleted file mode 100644 index b55e2ce..0000000 --- a/notes/org-skill-ipfs.org +++ /dev/null @@ -1,63 +0,0 @@ -:PROPERTIES: -:ID: 98923a43-2be0-423c-8509-22592cfe9c9e -:CREATED: [2026-04-08 Wed 18:30] -:END: -#+TITLE: SKILL: IPFS Checkpointing (Universal Literate Note) -#+STARTUP: content -#+FILETAGS: :memory:persistence:ipfs:sovereignty: -#+DEPENDS_ON: id:e8b500e2-3f26-4c8e-8558-528061e178ca - -* Overview -The *IPFS Checkpointing* skill provides decentralized, immutable snapshots of the agent's knowledge graph. It leverages the local IPFS daemon to achieve "Sovereignty Above All," ensuring that memory state is preserved across space and time without reliance on a single physical machine. - -* Implementation - -#+begin_src lisp -(in-package :org-agent) - -(defun org-object-to-alist (obj) - "Converts an org-object struct to an alist for JSON serialization." - `((:id . ,(org-object-id obj)) - (:type . ,(format nil "~s" (org-object-type obj))) - (:attributes . ,(loop for (k v) on (org-object-attributes obj) by #'cddr - collect (cons (format nil "~a" k) (format nil "~a" v)))) - (: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)))) - -(defun ipfs-checkpoint-memory () - "Serializes the object-store and pushes it to IPFS." - (let ((objects nil)) - (maphash (lambda (id obj) - (declare (ignore id)) - (push (org-object-to-alist obj) objects)) - *object-store*) - (let* ((json-payload (cl-json:encode-json-to-string objects)) - (ipfs-url "http://127.0.0.1:5001/api/v0/add")) - (handler-case - (let* ((response (dex:post ipfs-url - :content `(("file" . ,json-payload)) - :headers '(("Content-Type" . "multipart/form-data")))) - (result (cl-json:decode-json-from-string response)) - (cid (cdr (assoc :hash result)))) - (kernel-log "IPFS - Memory checkpointed. CID: ~a" cid) - `(:target :system :payload (:action :message :text ,(format nil "IPFS Checkpoint created: ~a" cid)))) - (error (c) - (kernel-log "IPFS ERROR - Checkpoint failed: ~a" c) - `(:target :system :payload (:action :message :text "IPFS Checkpoint failed. Is the daemon running?"))))))) - -(def-cognitive-tool :ipfs-checkpoint "Creates an immutable snapshot of the current knowledge graph on IPFS." - :parameters nil - :body (lambda (args) - (declare (ignore args)) - (ipfs-checkpoint-memory))) - -(defskill :skill-ipfs - :priority 90 - :trigger (lambda (ctx) (eq (getf (getf ctx :payload) :command) :checkpoint-ipfs)) - :neuro (lambda (ctx) "Propose an IPFS checkpoint if the user wants to backup or preserve current state.") - :symbolic (lambda (action ctx) (ipfs-checkpoint-memory))) -#+end_src diff --git a/notes/org-skill-linkedin.org b/notes/org-skill-linkedin.org deleted file mode 100644 index cfc7460..0000000 --- a/notes/org-skill-linkedin.org +++ /dev/null @@ -1,156 +0,0 @@ -:PROPERTIES: -:ID: c8a20cdf-5a23-4b52-a258-9ca11179c414 -:CREATED: [2026-04-05 Sun 19:12] -:EDITED: [2026-04-07 Tue 13:42] -:END: -#+TITLE: SKILL: LinkedIn Automation Agent (Universal Literate Note) -#+STARTUP: content -#+FILETAGS: :business:automation:linkedin:revenue:psf: - -* Overview -The *LinkedIn Automation Agent* is a revenue-focused skill designed to automate professional outreach and job applications. It leverages neural synthesis to personalize resumes and cover letters, ensuring a high conversion rate in the job market. - -* Phase A: Demand (PRD) -:PROPERTIES: -:STATUS: FROZEN -:END: - -** 1. Purpose -Automate the "Easy Apply" process on LinkedIn to sustain revenue streams. - -** 2. User Needs -- *Job Perception:* Periodically scan LinkedIn for roles matching the "Software Engineer" and "Lisp" criteria. -- *Neural Personalization:* Generate tailored cover letters using the kernel's neural engine. -- *Automated Application:* Use a headless browser (Playwright/Selenium) to submit applications. -- *Success Tracking:* Log application status to the Object Store. - -** 3. Success Criteria -*** TODO Successful login to LinkedIn via session cookies. -*** TODO Neural synthesis of a cover letter based on a specific job description. -*** TODO Automated submission of at least one "Easy Apply" form. - -* Registration -#+begin_src lisp -(defskill :skill-linkedin - :priority 50 - :trigger (lambda (context) (eq (getf (getf context :payload) :sensor) :revenue-pulse)) - :neuro (lambda (context) nil) - :symbolic (lambda (action context) action)) -#+end_src - - -* Phase B: Blueprint (PROTOCOL) -:PROPERTIES: -:STATUS: SIGNED -:END: - -* Phase B: Blueprint (PROTOCOL) - -** 1. Architectural Intent -The LinkedIn Automation Agent will be implemented as a modular skill composed of several cooperating components: - -- *Sensor*: Subscribes to revenue pulse events to trigger operation. Also responsible for querying the LinkedIn API and scraping page content for job postings. -- *Neural Synthesizer*: Generates personalized cover letters and resumes based on job descriptions. Relies on the kernel's large language model (LLM). -- *Automation Engine*: Controls a headless browser (Playwright) to automate the 'Easy Apply' process. -- *Object Store*: Persistently stores application data, tracking their status. - -The architecture prioritizes robustness (resume application failure), scalability (handle increasing job volume), and adaptability (evolving LinkedIn UI). - -** 2. Semantic Interfaces - -*** LinkedIn Sensor - -#+begin_src lisp -;;; Fetches list of relevant job postings from LinkedIn. -;;; -;;; Parameters: -;;; :keywords (list string) - List of keywords to search for (e.g., '("software engineer" "lisp")) -;;; :location (string) - The geographical location to search within. -;;; :session-cookie (string) - LinkedIn session cookie for authentication. -;;; -;;; Returns: -;;; (list job-posting) - List of job posting objects. Each object has the following keys: -;;; :job-id (string) - Unique ID of the job posting. -;;; :title (string) - Job title. -;;; :company (string) - Company name. -;;; :location (string) - Job location. -;;; :description-url (string) - URL to the full job description. -;;; :easy-apply (boolean) - T if the job has the Easy Apply option, NIL otherwise. -(defun linkedin-fetch-job-postings - (:keywords keywords) - (:location location) - (:session-cookie session-cookie) - ...) -#+end_src - -*** Neural Personalizer - -#+begin_src lisp -;;; Generates a personalized cover letter based on a job description and the user's resume. -;;; -;;; Parameters: -;;; :job-description (string) - Text of the job description. -;;; :resume (string) - The user's resume text. -;;; -;;; Returns: -;;; (string) - Generated cover letter. -(defun generate-cover-letter - (:job-description job-description) - (:resume resume) - ...) -#+end_src - -#+begin_src lisp -;;; Generates a personalized resume based on a job description -;;; -;;; Parameters: -;;; :job-description (string) - Text of the job description. -;;; :resume (string) - The user's resume text. -;;; -;;; Returns: -;;; (string) - Generated resume. -(defun personalize-resume - (:job-description job-description) - (:resume resume) - ...) -#+end_src - -*** Automation Engine - -#+begin_src lisp -;;; Submits an 'Easy Apply' application for a given job posting. -;;; -;;; Parameters: -;;; :job-posting (job-posting) - A job posting object from 'linkedin-fetch-job-postings'. -;;; :cover-letter (string) - The generated cover letter. -;;; :resume (string) - the personalized resume -;;; :session-cookie (string) - LinkedIn session cookie for authentication. -;;; -;;; Returns: -;;; (boolean) - T if the application was submitted successfully, NIL otherwise. -(defun submit-easy-apply - (:job-posting job-posting) - (:cover-letter cover-letter) - (:resume resume) - (:session-cookie session-cookie) - ...) -#+end_src - -*** Object Store - -#+begin_src lisp -;;; Logs the application status to the store -;;; -;;; Parameters: -;;; :job-id (string) - the ID of the job application -;;; :status: (symbol) - the status of the application (:applied :pending :interview :rejected :accepted) -;;; :metadata: (list) - any metadata to store. -;;; -;;; Returns: -;;; T upon success, NIL otherwise. -(defun log-application-status - (:job-id job-id) - (:status status) - (:metadata metadata) - ...) -#+end_src diff --git a/notes/org-skill-lisp-machine-bootstrap.org b/notes/org-skill-lisp-machine-bootstrap.org deleted file mode 100644 index 7f81544..0000000 --- a/notes/org-skill-lisp-machine-bootstrap.org +++ /dev/null @@ -1,59 +0,0 @@ -:PROPERTIES: -:ID: 81e3492e-0d28-416c-a67c-c7f6f114643d -:CREATED: [2026-04-07 Tue 12:57] -:EDITED: [2026-04-07 Tue 13:42] -:END: -#+TITLE: SKILL: Lisp Machine Bootstrap (Universal Literate Note) -#+STARTUP: content -#+FILETAGS: :hardware:lisp:sovereignty:fpga:psf: - -* Overview -The *Lisp Machine Bootstrap* project is the "Endgame" of the PSF. It aims to eliminate the "Unix/C Tax" by building a hardware-native Lisp machine where CAR, CDR, and CONS are primitive gates. This ensures ultimate digital sovereignty and a provably secure, homoiconic environment. - -* Phase A: Demand (PRD) -:PROPERTIES: -:STATUS: FROZEN -:END: - -** 1. Purpose -Define the requirements for a hardware environment optimized for Lisp and user sovereignty. - -** 2. User Needs -- *Hardware-Native Lisp:* ISA designed for list processing efficiency. -- *Tagged Memory:* Hardware-level safety preventing memory corruption. -- *Bootstrapping Path:* Progression from Soft Machine (Linux) to Sovereign Silicon (ASIC). -- *Transparency:* Every gate and instruction must be introspectable and documented. - -** 3. Success Criteria -*** TODO Research existing Lisp-on-FPGA implementations (Openora, etc.) -*** TODO Define minimum hardware-native Lisp ISA (Instruction Set Architecture) -*** TODO Draft CLOSOS-style Virtual Machine specification -*** TODO FPGA Implementation: Verilog/VHDL skeleton synthesis - -* Phase B: Blueprint (PROTOCOL) -:PROPERTIES: -:STATUS: SIGNED -:END: - -** 1. Architectural Intent -The protocol defines the interface between the high-level Lisp image and the low-level ISA/VM. - -** 2. Semantic Interfaces -#+begin_src lisp -(defun isa-dispatch (instruction opcode) - "Simulates the hardware dispatch of a Lisp-native instruction.") - -(defun memory-tag-audit (address) - "Verifies the hardware tag of a specific memory word.") -#+end_src - -* Phase D: Build (Implementation) -Current focus is on research and simulation (Phase 1: Soft Machine). - -** Simulation Interface -#+begin_src lisp -;; Soft machine simulator stubs -#+end_src - -* Phase E: Chaos (Verification) -Verification will occur via FPGA synthesis reports and VM regression tests. diff --git a/notes/org-skill-log-aggregator.org b/notes/org-skill-log-aggregator.org deleted file mode 100644 index c106f20..0000000 --- a/notes/org-skill-log-aggregator.org +++ /dev/null @@ -1,81 +0,0 @@ -:PROPERTIES: -:ID: 2883a21a-6b95-4f8c-a785-3c1472a994b6 -:CREATED: [2026-04-04 Sat 20:27] -:EDITED: [2026-04-07 Tue 13:42] -:END: -#+TITLE: SKILL: Log Aggregator (Universal Literate Note) -#+STARTUP: content -#+FILETAGS: :logging:observability:system:psf: - -* Overview -The *Log Aggregator* monitors and summarizes system logs to provide insights into agent behavior and system health. - -* Phase A: Demand (PRD) -:PROPERTIES: -:STATUS: FROZEN -:END: - -** 1. Purpose -Collect and summarize agent logs. - -** 2. User Needs -- *Scan:* Retrieve logs from the system. -- *Summarize:* Provide a high-level summary of recent activities. - - -* Phase B: Blueprint (PROTOCOL) -:PROPERTIES: -:STATUS: SIGNED -:END: - - -* Phase B: Blueprint (PROTOCOL) -:PROPERTIES: -:STATUS: DRAFT -:END: - -** 1. Architectural Intent -The Log Aggregator will employ a modular architecture, consisting of a Log Source Connector, a Summarization Engine, and a Presenter. This allows for flexibility in adapting to different log formats and presentation styles. The system will prioritize low overhead impact on the monitored system. - -** 2. Semantic Interfaces (Lisp Signatures) - -*** a. Log Source Connector - - #+BEGIN_SRC lisp - ;;; Function: fetch-logs - ;;; Description: Retrieves logs based on specified criteria. - ;;; Parameters: - ;;; :source (keyword) - Specifies the log source (e.g., :systemd, :file, :journald). - ;;; :start-time (timestamp) - Optional. The starting timestamp for the logs. - ;;; :end-time (timestamp) - Optional. The ending timestamp for the logs. - ;;; :filters (list) - Optional. A list of filters to apply to the logs (e.g., '((:level . :error) (:component . "foo"))). - ;;; Returns: A list of log entries (each entry being a plist). - (defun fetch-logs (&key source start-time end-time filters) - ...) - #+END_SRC - -*** b. Summarization Engine - - #+BEGIN_SRC lisp - ;;; Function: summarize-logs - ;;; Description: Summarizes a list of log entries. - ;;; Parameters: - ;;; :log-entries (list) - A list of log entries (plists). - ;;; :summary-type (keyword) - Specifies the type of summary (e.g., :count-by-level, :count-by-component, :recent-errors). - ;;; Returns: A summary of the logs (a plist). - (defun summarize-logs (&key log-entries summary-type) - ...) - #+END_SRC - -*** c. Presenter - - #+BEGIN_SRC lisp - ;;; Function: present-summary - ;;; Description: Presents a log summary in a human-readable format. - ;;; Parameters: - ;;; :summary (plist) - A log summary as returned by `summarize-logs`. - ;;; :format (keyword) - Specifies the output format (e.g., :text, :html). - ;;; Returns: A string containing the formatted summary. - (defun present-summary (&key summary format) - ...) - #+END_SRC diff --git a/notes/org-skill-long-horizon.org b/notes/org-skill-long-horizon.org deleted file mode 100644 index ddffc3f..0000000 --- a/notes/org-skill-long-horizon.org +++ /dev/null @@ -1,31 +0,0 @@ -:PROPERTIES: -:ID: 0e050a09-7d5d-43c4-8de4-8762fffd3255 -:CREATED: [2026-03-31 Tue 20:28] -:EDITED: [2026-04-07 Tue 13:42] -:END: -#+TITLE: SKILL: Long-Horizon Planning Agent (Universal Literate Note) -#+STARTUP: content -#+FILETAGS: :planning:meta-cognition:long-horizon:psf: - -* Overview -The *Long-Horizon Planning Agent* manages complex, multi-step tasks that exceed the context window of standard LLMs. It uses an Org-mode *Dynamic Task Tree* to track progress, summarize completed sub-tasks, and prune irrelevant execution branches. - -* Phase A: Demand (PRD) -:PROPERTIES: -:STATUS: DRAFT -:END: - -** 1. Purpose -Enable the agent to maintain focus and coherence over tasks spanning 100+ steps (SWE-bench parity). - -** 2. User Needs -- *Hierarchical Planning:* Break large goals into a nested tree of Org headlines. -- *Context Compression:* Automatically summarize the results of child sub-trees into their parent nodes. -- *Branch Pruning:* Meta-cognitive review to stop execution of failed or redundant paths. -- *Self-Correction:* Adjust the plan dynamically based on environmental feedback. - -** 3. Success Criteria -*** TODO Dynamic Task Tree Generation -*** TODO Context Compression Verification -*** TODO Branch Pruning Logic Effectiveness - diff --git a/notes/org-skill-memex.org b/notes/org-skill-memex.org deleted file mode 100644 index 90597ac..0000000 --- a/notes/org-skill-memex.org +++ /dev/null @@ -1,83 +0,0 @@ -: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:psf: - -* 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 Sovereignty:* 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"))` - diff --git a/notes/org-skill-model-explorer.org b/notes/org-skill-model-explorer.org deleted file mode 100644 index 8b051c9..0000000 --- a/notes/org-skill-model-explorer.org +++ /dev/null @@ -1,12 +0,0 @@ -:PROPERTIES: -:ID: ae49bb72-8c5d-4392-af70-4eb00d285054 -:CREATED: [2026-03-30 Mon 21:16] -:EDITED: [2026-04-07 Tue 13:42] -:END: -#+TITLE: SKILL: Model Explorer Agent (Universal Literate Note) -#+STARTUP: content -#+FILETAGS: :discovery:telemetry:psf: - -* Overview -The *Model Explorer Agent* provides dynamic introspection of the system's LLM capabilities. It intercepts specific user commands to list and describe all available models across providers, rendering them as native Org-mode tables. - diff --git a/notes/org-skill-object-store-persistence.org b/notes/org-skill-object-store-persistence.org deleted file mode 100644 index 38c9113..0000000 --- a/notes/org-skill-object-store-persistence.org +++ /dev/null @@ -1,74 +0,0 @@ -:PROPERTIES: -:ID: e8b500e2-3f26-4c8e-8558-528061e178ca -:CREATED: [2026-03-31 Tue 18:28] -:EDITED: [2026-04-07 Tue 13:42] -:END: -#+TITLE: SKILL: Object Store Persistence (Universal Literate Note) -#+STARTUP: content -#+FILETAGS: :memory:persistence:closos:psf: - -* Overview -The *Object Store Persistence* skill ensures that the agent's perceptual memory (the `*object-store*`) is durable. It provides the mechanism to "dump" the in-RAM knowledge graph to a Lisp-native image file and "reload" it upon boot, eliminating the need to re-parse the entire Memex on every restart. - -* Phase A: Demand (PRD) -:PROPERTIES: -:STATUS: FROZEN -:END: - -** 1. Purpose -Define automated behaviors for knowledge graph serialization and restoration. - -** 2. User Needs -- *Instant Recall:* Rapid loading of the Object Store from a persistent image. -- *High-Fidelity Serialization:* Recursive dumping of `org-object` structs and their relations. -- *Atomic Persistence:* Save the entire graph state to a single `.el` or `.lisp` file. -- *Background Synchronization:* Periodically dump the image during heartbeats. - -** 3. Success Criteria -*** TODO Image Dump logic verification (File exists and is readable) -*** TODO Image Load logic verification (Object count matches RAM state) -*** TODO Performance audit (Loading image must be >10x faster than parsing) - -* Phase B: Blueprint (PROTOCOL) -:PROPERTIES: -:STATUS: SIGNED -:END: - -** 1. Architectural Intent -Interfaces for state dumping and restoration. Source of truth is the RAM-resident `*object-store*` and the `system/state/memory-image.lisp` file. - -** 2. Semantic Interfaces -#+begin_src lisp -(defun memory-dump-image () - "Serializes the current *object-store* to disk.") - -(defun memory-load-image () - "Restores the *object-store* from the persistent image file.") -#+end_src - -* Phase D: Build (Implementation) - -** Image Serialization -#+begin_src lisp :tangle ../projects/org-skill-object-store-persistence/src/persistence-logic.lisp -(defun memory-dump-image () - (let* ((state-dir (or (uiop:getenv "SYSTEM_DIR") "system/")) - (image-file (merge-pathnames "state/memory-image.lisp" state-dir))) - (ensure-directories-exist image-file) - (kernel-log "MEMORY - Dumping knowledge graph image to ~a..." (uiop:native-namestring image-file)) - (with-open-file (out image-file :direction :output :if-exists :supersede) - ;; We serialize the hash table entries as a list of forms - (maphash (lambda (id obj) - (declare (ignore id)) - (print `(setf (gethash ,(org-agent:org-object-id obj) org-agent:*object-store*) ,obj) out)) - org-agent:*object-store*)) - '(:target :system :payload (:action :message :text "Memory image dumped.")))) -#+end_src - -* Registration -#+begin_src lisp -(defskill :skill-object-store-persistence - :priority 100 ; Foundational infrastructure - :trigger (lambda (context) (eq (getf (getf context :payload) :sensor) :heartbeat)) - :neuro (lambda (context) nil) - :symbolic (lambda (action context) (memory-dump-image))) -#+end_src diff --git a/notes/org-skill-onboarding.org b/notes/org-skill-onboarding.org deleted file mode 100644 index 868b64d..0000000 --- a/notes/org-skill-onboarding.org +++ /dev/null @@ -1,70 +0,0 @@ -: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:psf: - -* Overview -The *Onboarding Skill* ensures that the Lisp Machine environment is correctly calibrated. It automates the "zero-to-one" setup of the Neurosymbolic 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 PSF 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 kernel, actuators, and models. Returns a plist `(:kernel t :actuators t :models t)`. This is the main test before boot. diff --git a/notes/org-skill-org-delivery.org b/notes/org-skill-org-delivery.org deleted file mode 100644 index 5808245..0000000 --- a/notes/org-skill-org-delivery.org +++ /dev/null @@ -1,64 +0,0 @@ -:PROPERTIES: -:ID: d8b1fbf9-2a6e-453d-975b-f510c3a9c4c0 -:CREATED: [2026-03-30 Mon 21:16] -:EDITED: [2026-04-07 Tue 13:42] -:END: -#+TITLE: SKILL: Org-Native Delivery Agent (Universal Literate Note) -#+STARTUP: content -#+FILETAGS: :delivery:actuator:external:psf: - -* Overview -The *Org-Native Delivery Agent* is the primary outbound actuator for external messaging. It uses the "Inbox-as-a-Queue" pattern, enqueuing structured Org-mode headlines for external bridges (Signal, Telegram, etc.). - -* Phase A: Demand (PRD) -:PROPERTIES: -:STATUS: FROZEN -:END: - -** 1. Purpose -Define the interfaces for asynchronous external message enqueuing. - -** 2. User Needs -- *Asynchronous Dispatch:* Persistence via `delivery.org` file. -- *Multi-Channel Support:* Routing to Signal, Telegram, Discord. -- *Structured Provenance:* Timestamped entries with recipient IDs. - -** 3. Success Criteria -*** TODO Queue Appending Verification -*** TODO Channel-specific ID Resolution -*** TODO Org Timestamp Formatting Accuracy - - -* Phase B: Blueprint (PROTOCOL) -:PROPERTIES: -:STATUS: SIGNED -:END: - -* Phase B: Blueprint (PROTOCOL) -:PROPERTIES: -:STATUS: DRAFT -:END: - -** 1. Architectural Intent - -The *Org-Native Delivery Agent* will function as a *stateless* message queuing system. It receives message envelopes as Lisp data structures, persists them to a designated Org-mode file (`delivery.org`), and returns upon successful enqueuing. External bridge processes are responsible for consuming messages from `delivery.org` and handling delivery to specific channels. This decoupling ensures resilience and scalability. We favor simplicity and robustness over complex routing logic *within* the Agent itself. The Org file acts as a source of truth for queued messages, enabling auditing and recovery. - -** 2. Semantic Interfaces (Lisp Signatures) - -#+BEGIN_SRC lisp -;;; Signature: `org-delivery-enqueue' -;;; -;;; Enqueues a message for delivery. -;;; -;;; Arguments: -;;; `recipient-id`: Channel-specific identifier (e.g., Signal number, Telegram chat ID). STRING. -;;; `channel`: Keyword indicating the target channel. SYMBOL (one of: :signal, :telegram, :discord, ...). -;;; `message-body`: The content of the message. STRING. Can contain Org-mode markup. -;;; `properties`: A plist of additional metadata. LIST (plist). -;;; -;;; Returns: A plist containing `:status :success` or `:status :failure` with an optional `:error-message`. -;;; Upon success: returns a message id. -;;; Upon failure: returns `:error-message`. -;;; -(defun org-delivery-enqueue (recipient-id channel message-body &optional properties) - diff --git a/notes/org-skill-org-gtd-archive-roam-daily.org b/notes/org-skill-org-gtd-archive-roam-daily.org deleted file mode 100644 index 744382b..0000000 --- a/notes/org-skill-org-gtd-archive-roam-daily.org +++ /dev/null @@ -1,89 +0,0 @@ -:PROPERTIES: -:ID: 97d0945e-9405-4da8-82e1-0e742063a99a -:CREATED: [2026-03-31 Tue 16:14] -:EDITED: [2026-04-07 Tue 13:42] -:END: -#+TITLE: SKILL: Org-GTD Archive Roam Daily (Universal Literate Note) -#+STARTUP: content -#+FILETAGS: :emacs:gtd:roam:archiving:psf: - -* Overview -The *Org-GTD Archive Roam Daily* skill enables chronological archiving of completed GTD tasks. Instead of a flat archive file, tasks are moved to their respective `org-roam-dailies` files based on their `:CREATED:` property, preserving contextual and temporal integrity. - -* Phase A: Demand (PRD) -:PROPERTIES: -:STATUS: FROZEN -:END: - -** 1. Purpose -Define the requirements for chronologically-aware task archiving. - -** 2. User Needs -- *Temporal Alignment:* Archive tasks to the daily file matching their creation date. -- *Context Preservation:* Maintain all properties and sub-elements during the move. -- *Robust Extraction:* Correctly parse `:CREATED:` property timestamps. -- *Fail-safe Logic:* Default to current date if `:CREATED:` is missing (with a warning). - -** 3. Success Criteria -*** TODO Successful extraction of [YYYY-MM-DD] from :CREATED: -*** TODO Automated creation of non-existent daily files during archive -*** TODO Subtree relocation verification - - -* Phase B: Blueprint (PROTOCOL) -:PROPERTIES: -:STATUS: SIGNED -:END: - - -* Phase B: Blueprint (PROTOCOL) -:PROPERTIES: -:STATUS: DRAFT -:END: - -** 1. Architectural Intent -The system will utilize Emacs Lisp to extract the `:CREATED:` property from a GTD task, derive a date, locate (or create) the corresponding `org-roam-daily` file, and move the task subtree to that file. Error handling will include a fallback mechanism to the current date, accompanied by a user notification. The design emphasizes modularity and testability. - -** 2. Semantic Interfaces (Lisp Signatures) - - - `(org-gtd-archive-roam-daily &optional subtree)` - - *Purpose:* Main entry point. Archives a GTD task to its corresponding `org-roam-daily` file based on the `:CREATED:` property. - - *Arguments:* - - `subtree` (optional): The subtree to archive. Defaults to the current subtree. - - *Return Value:* `t` on success, `nil` on failure. - - *Side Effects:* Modifies Org files. - - - `(org-gtd-archive-roam-daily-extract-created-date subtree)` - - *Purpose:* Extracts the date from the `:CREATED:` property of a subtree. - - *Arguments:* - - `subtree`: The subtree to extract the date from. - - *Return Value:* A string in `YYYY-MM-DD` format, or `nil` if the property is missing or invalid. - - - `(org-gtd-archive-roam-daily-get-daily-file-path date)` - - *Purpose:* Determines the file path for a given date, according to `org-roam-dailies` conventions. - - *Arguments:* - - `date`: A string in `YYYY-MM-DD` format. - - *Return Value:* A string representing the file path. - - - `(org-gtd-archive-roam-daily-ensure-daily-file-exists file-path)` - - *Purpose:* Creates an `org-roam-daily` file if it does not already exist. - - *Arguments:* - - `file-path`: The path to the `org-roam-daily` file. - - *Return Value:* `t` if the file exists (either originally or after creation), `nil` if creation failed. - - *Side Effects:* Creates a new file. - - - `(org-gtd-archive-roam-daily-move-subtree subtree file-path)` - - *Purpose:* Moves a subtree to a specified file. - - *Arguments:* - - `subtree`: The subtree to move. - - `file-path`: The destination file path. - - *Return Value:* `t` on success, `nil` on failure. - - *Side Effects:* Modifies Org files. - - - `(org-gtd-archive-roam-daily-warn message)` - - *Purpose:* Displays a warning message to the user. - - *Arguments:* - - `message`: The warning message to display. - - *Return Value:* `nil` - - *Side Effects:* Displays a message. - diff --git a/notes/org-skill-org-json-bridge.org b/notes/org-skill-org-json-bridge.org deleted file mode 100644 index 61733bc..0000000 --- a/notes/org-skill-org-json-bridge.org +++ /dev/null @@ -1,72 +0,0 @@ -:PROPERTIES: -:ID: 3ffed7d8-7a73-4766-bf64-473ba81f67f1 -:CREATED: [2026-03-31 Tue 16:14] -:EDITED: [2026-04-07 Tue 13:42] -:END: -#+TITLE: SKILL: Org-JSON Bridge (Universal Literate Note) -#+STARTUP: content -#+FILETAGS: :org-mode:json:manipulation:psf: - -* Overview -The *Org-JSON Bridge* enables programmatic manipulation of Org-mode files by converting them into a structured JSON representation and vice-versa. This bypasses the fragility of direct string manipulation for complex structures like tables, properties, and source blocks. - -* Phase A: Demand (PRD) -:PROPERTIES: -:STATUS: FROZEN -:END: - -** 1. Purpose -Define the interfaces for bidirectional Org-to-JSON conversion. - -** 2. User Needs -- *Robust Parsing:* Convert Org-mode files into structured JSON AST. -- *High-Fidelity Rendering:* Re-materialize JSON AST back into syntactically correct Org-mode text. -- *Complex Structure Support:* Handle tables, property drawers, and source blocks without data loss. -- *Programmatic API:* Provide a CLI and Lisp interface for other skills to use. - -** 3. Success Criteria -*** TODO Parse Org-mode to JSON AST without loss of hierarchy -*** TODO Render JSON AST back to Org-mode text matching original format -*** TODO Table row injection via JSON manipulation verification - - -* Phase B: Blueprint (PROTOCOL) -:PROPERTIES: -:STATUS: SIGNED -:END: - - -* Phase B: Blueprint (PROTOCOL) - -** 1. Architectural Intent -The Org-JSON Bridge will be implemented as a modular system centered around two core functions: `org-to-json` and `json-to-org`. The design prioritizes correctness, maintainability, and extensibility. Error handling and clear documentation will be crucial. Serialization will leverage existing robust JSON libraries in the Lisp environment. The internal representation (JSON AST) will mirror Org's structural components as much as practical, to minimize translation complexity. - -** 2. Semantic Interfaces - -*** `org-to-json` - - - *Intent:* Parse an Org-mode file (or string) and convert its content to a JSON AST. - - *Signature:* `(org-to-json source &key (source-type :file) (output-format :json) (error-policy :strict))` - - *Arguments:* - - `source`: Either a file path (if `source-type` is `:file`) or an Org-mode string (if `source-type` is `:string`). - - `source-type`: Keyword specifying the type of the `source` argument. Valid values are `:file` and `:string`. Defaults to `:file`. - - `output-format`: Keyword specifying the desired output format. Currently only `:json` is supported. Future options might include other serialization formats (e.g., YAML). - - `error-policy`: Keyword specifying how parsing errors should be handled. `:strict` (the default) signals an error immediately. `:lenient` attempts to recover and continue parsing, potentially returning a partial AST with error annotations. - - *Returns:* A JSON AST representing the Org-mode content, or `NIL` if an unrecoverable error occurs and `error-policy` is `:strict`. - - *Error Handling:* Raises errors when `error-policy` is `:strict` and parsing fails. Returns informative error messages. - -*** `json-to-org` - - - *Intent:* Convert a JSON AST back into an Org-mode string. - - *Signature:* `(json-to-org ast &key (output-format :org) (pretty-print t) (error-policy :strict))` - - *Arguments:* - - `ast`: The JSON AST to be converted. - - `output-format`: Keyword specifying the desired output format. Only `:org` is currently supported. - - `pretty-print`: Boolean indicating whether the output should be formatted for readability. Defaults to `T`. - - `error-policy`: Keyword specifying how rendering errors should be handled. `:strict` (the default) signals an error immediately. `:lenient` attempts to recover and continue rendering, potentially producing a partial Org-mode string with error annotations. - - *Returns:* An Org-mode string representing the content of the JSON AST, or `NIL` if an unrecoverable error occurs and `error-policy` is `:strict`. - - *Error Handling:* Raises errors during rendering when `error-policy` is `:strict` and the provided AST is invalid (e.g., missing required fields or incorrect data types). Returns informative error messages. - -*** CLI Interface - - - Command-line tools wrapping `org-to-json` and `json-to-org` will also be provided for convenient use from the shell. These tools will accept file paths as input and output, and include options to control formatting and error handling. Example: `org-json-convert --to-json input.org output.json`. diff --git a/notes/org-skill-org-mode.org b/notes/org-skill-org-mode.org deleted file mode 100644 index b7e5eaa..0000000 --- a/notes/org-skill-org-mode.org +++ /dev/null @@ -1,131 +0,0 @@ -:PROPERTIES: -:ID: f7db1884-49cc-4db6-9ca1-4c69ec3a631e -:CREATED: [2026-03-30 Mon 21:16] -:EDITED: [2026-04-07 Tue 13:42] -:END: -#+TITLE: SKILL: Org-Mode & AST Manipulation (Universal Literate Note) -#+STARTUP: content -#+FILETAGS: :org-mode:ast:homoiconic:psf: - -* Overview -This skill defines the *Grammar of the Memex*. It establishes the rules for treating plain text as a structured, hierarchical database. Org-mode is our *Homoiconic Memory*—documentation for humans and AST for the agent. - -* Phase A: Demand (PRD) -:PROPERTIES: -:STATUS: FROZEN -:END: - -** 1. Purpose -Define the structural rules and manipulation interfaces for the Org-mode AST. - -** 2. User Needs -- *Everything is a Node:* Mandatory headlines, properties, and unique IDs. -- *Literate Programming:* Code must be wrapped in narrative-rich blocks. -- *Naming & Paths:* Strict kebab-case and flat directory structure. -- *Binary Integrity:* Management of attachments via the Attachment Protocol. - -** 3. Success Criteria -*** TODO ID Uniqueness Enforcement -*** TODO Literate Block Parsing -*** TODO Attachment Link Validation - - -* Phase B: Blueprint (PROTOCOL) -:PROPERTIES: -:STATUS: SIGNED -:END: - - -* Phase B: Blueprint (PROTOCOL) - -** 1. Architectural Intent - The Org-mode AST will be the central data structure for the Memex. We aim for a simple, consistent, and easily navigable representation of hierarchical data. All operations should be performable through Lisp functions that respect the immutability of the underlying data where possible, returning new modified versions. The architecture must accommodate both human readability/editability and machine manipulation. We're focusing on a 'functional core, imperative shell' approach, with side-effecting operations clearly delineated and minimized. We'll leverage standard Emacs Lisp data structures (lists, alists, strings, numbers) so to not needlessly reinvent the wheel, but wrap them in functions offering strongly typed and named abstractions. - -** 2. Semantic Interfaces - -*** Core Data Structures - - :PROPERTIES: - :CUSTOM_ID: core-data-structures - :END: - - `org-node`: Represents a headline and its children. A Lisp alist with the following keys: - - `:id`: A unique string identifier (required). - - `:headline`: A string representing the headline text. - - `:level`: An integer indicating the heading level (1, 2, 3, etc.). - - `:properties`: An alist of property key-value pairs (string keys, string values). - - `:content`: A string representing the content within the headline, but before any sub-headings. This will generally contain a sequence of literate blocks. - - `:children`: A list of `org-node`s representing the sub-headings. - - - `literate-block`: Represents a code or narrative block. An alist with keys: - - `:type`: A symbol indicating the block type (e.g., `:code`, `:narrative`). - - `:language`: A symbol indicating the programming language for code blocks (e.g., `:lisp`, `:python`). `nil` or `:text` for narrative blocks. - - `:content`: A string representing the content of the block. - - `:metadata`: An alist of metadata key-value pairs for the block (string keys, string values). - -*** CRUD Operations (Node Focused) - - :PROPERTIES: - :CUSTOM_ID: crud-operations-node - :END: - - - `(org-node-create headline content properties children)`: Creates a new `org-node`. All parameters are required. Returns a new `org-node`. - - `headline`: String - `content`: String - `properties`: Alist - `children`: List of `org-node` - `returns`: `org-node` - - - `(org-node-read node-id)`: Retrieves an `org-node` by its ID. Returns the `org-node` or `nil` if not found. - - `node-id`: String - `returns`: `org-node` | `nil` - - - `(org-node-update node attr value)`: Updates an attribute of an existing `org-node`. Returns a *new* `org-node` with the updated attribute. Purely functional; does not mutate the original. - - `node`: `org-node` - `attr`: Symbol (e.g., `:headline`, `:content`, `:properties`) - `value`: depends on attribute; e.g., String for headline, new alist for properties - `returns`: `org-node` - - - `(org-node-delete node-id)`: Deletes an `org-node` from the Memex. *This operation has side effects*. Returns `t` if successful, `nil` otherwise. (More thought will be required regarding how this interacts with the file system and possible dangling references.) - - `node-id`: String - `returns`: `t` | `nil` - -*** Traversal & Query Functions - - :PROPERTIES: - :CUSTOM_ID: traversal-query-functions - :END: - - - `(org-node-children node)`: Returns the list of child `org-node`s of a given `org-node`. - - `node`: `org-node` - `returns`: List of `org-node` - - - `(org-node-parent node)`: Returns the parent `org-node` of a given `org-node`, or `nil` if it's the root. Requires maintaining a separate index for efficient parent lookups. - - `node`: `org-node` - `returns`: `org-node` | `nil` - - - `(org-node-query query-fn)`: Searches the entire Memex for `org-node`s matching a given criteria. `query-fn` is a function that takes an `org-node` as input and returns `t` if the node matches the query, `nil` otherwise. Returns a list of matching `org-node`s. - - `query-fn`: Function taking `org-node` and returning boolean - `returns`: List of `org-node` - -*** Literate Block Operations - - :PROPERTIES: - :CUSTOM_ID: literate-block-operations - :END: - - - `(org-node-extract-blocks node)`: Extracts all `literate-block`s from the `content` section of the `org-node`. This will require parsing the string `content` by detecting the block delimiters. Returns a list of `literate-block`s. - - `node`: `org-node` - `returns`: List of `literate-block` - - - `(literate-block-evaluate block)`: Evaluates a code block. The behavior depends on the `language` of the block. *This operation has side effects*. Returns the result of the evaluation. - - `block`: `literate-block` - `returns`: depends on language. diff --git a/notes/org-skill-project-foundry.org b/notes/org-skill-project-foundry.org deleted file mode 100644 index d2793ce..0000000 --- a/notes/org-skill-project-foundry.org +++ /dev/null @@ -1,148 +0,0 @@ -:PROPERTIES: -:ID: 37f2b59f-4537-4cca-ac7f-5c24b9e2e773 -:CREATED: [2026-03-30 Mon 21:16] -:EDITED: [2026-04-08 Wed 10:45] -:END: -#+TITLE: SKILL: Project Foundry Agent (Universal Literate Note) -#+STARTUP: content -#+FILETAGS: :foundry:scaffolding:system:psf:lisp:engineering: - -* Overview -The *Personal Software Foundry (PSF)* is a highly integrated, neurosymbolic "virtual software house" embedded within the Memex. It is the overarching system used to design, implement, and maintain all software projects. The PSF ensures that every line of code is provably correct, secure, and part of a self-improving cognitive loop. - -The *Project Foundry Agent* is the specific skill responsible for the physical instantiation of these new projects. It automates directory creation, version control initialization, and GTD integration, ensuring every new project adheres to PSF mandates. - -* The PSF Mandates (Philosophy & Policy) -All software developed within the Foundry must adhere to these foundational principles: - -** 1. Lisp Machine Sovereignty -The agent is a Lisp Machine image (SBCL). The system is a "Living Organism" where code is updated via hot-reloading into the active image. Manual "Restarts" are considered a failure of the late-binding architecture. - -** 2. Homoiconic Memory (The Org Mandate) -Every document, plan, PRD, and skill in the system MUST be written in Org-mode (.org). Markdown (.md) and JSON/YAML/XML are strictly prohibited for internal system logic and institutional memory. Org-mode provides a rigorous, hierarchical AST for both humans and machines. - -** 3. Literate Programming (The Knuth-Sovereign Principle) -The PSF treats code not as a series of instructions for a computer, but as a "work of literature" for humans that happens to be executable. -- *Implementation:* All `org-agent` skills and system logic MUST be implemented as Literate Org files using `#+begin_src` blocks. -- *Rationale:* By weaving documentation and code together, we ensure that the "Why" (Architectural Intent) is never separated from the "How" (Implementation). This is the key to the PSF's *Institutional Memory*. - -** 4. Hardware Compartmentalization -The runtime environment is an enclosure (Docker, LXC, VM, or Bare Metal). The PSF kernel remains agnostic to its enclosure. - -** 5. Educational & Sovereign Interaction -The Foundry serves as a mentorship environment. Agents must explain the "Why" and distill knowledge to increase user technical mastery. The user (Sovereign Executive) retains absolute right to deep-dive into any technical layer. - -* Architectural Foundation (CLOSOS Principles) -The PSF is built on the *Common Lisp Object-Store Operating System (CLOSOS)* specification: -- [[file:closos_attributed_object_store.org][Object-Store First]]: Data is treated as Attributed Lisp Objects (via `org-element` AST), not flat files. -- [[file:closos_single_address_space.org][Single Address Space]]: The CL Daemon and Emacs share a conceptual address space via OACP (Remote Object Proxy). -- [[file:closos_memory_persistence.org][Persistence by Default]]: The Lisp Image is persistent; state is unalterable and auditable. -- [[file:closos_multiple_environments.org][Multiple Environments]]: Isolation by scope allows for safe, simultaneous global environments. -- [[file:closos_protection_mechanisms.org][Language-Based Protection]]: Security is enforced by the compiler and runtime (tagged pointers, capabilities). - -* The Foundry Workflow (The "Consensus Loop") -Projects pass through sequential "Safety Gates" managed by specialized departments: - -| Phase | Department | Responsibility | Key Instrument | -| :--- | :--- | :--- | :--- | -| *A: Demand* | *Product* | User Interview & Needs | `PRD.org` | -| *B: Blueprint* | *Design* | Structural Integrity & API | [[file:../system/skills/org-skill-architect.org][Architect Skill]] | -| *C: Success* | *Quality* | TDD Inception & Security Audit | [[file:../system/skills/org-skill-tech-analyst.org][Analyst Skill]] | -| *D: Build* | *Engineering* | Minimal Implementation | `src/`, [[file:skill-project-foundry.org][Foundry Skill]] | -| *E: Chaos* | *Chaos* | Dynamic Testing & Chaos Eng. | [[file:org-skill-chaos.org][Chaos Skill]] | -| F: Memory | *Optimization* | Institutional Memory & RCA | [[file:institutional_memory.org][institutional_memory.org]], [[file:../system/skills/org-skill-scribe-rca.org][Scribe-RCA Skill]] | - -** Success Matrix: "The Level 3 Standard" -A project is not complete until it achieves *Evolutionary Completion*: -1. *Functional:* Code merged and passing all audits (Chaos Gauntlet). -2. *Institutional:* Session distilled into atomic notes; code groomed for zero bloat. -3. *Evolutionary:* Automated health checks and recurring maintenance tasks established in `gtd.org` as standard task sequences. - -* Operational Standards -- *Project Root:* All projects live in `memex/5_projects/`. -- *Common Structure:* - - `README.org` (Vision) - - `PRD.org` (Requirements) - - `PROTOCOL.org` (Interfaces) - - `src/` (Implementation) - - `tests/` (Verification) - - `docs/` (Architecture/Chaos/RCA) -- *Self-Improvement (RCA):* Every bug triggers a *Root Cause Analysis* note to update "Permanent Learnings" in `SOUL.org`. - -* Phase A: Demand (PRD) -:PROPERTIES: -:STATUS: FROZEN -:END: - -** 1. Purpose -Define automated project instantiation behaviors for the PSF. - -** 2. User Needs -- *Workspace Scaffolding:* Create standard `src/`, `tests/`, `docs/` layout and boilerplate files. -- *Version Control:* Initialize Git in new project directories. -- *GTD Integration:* Automatically append projects and initial tasks to `gtd.org`. -- *Safety:* Prevent overwriting existing projects and log all actions. - -** 3. Success Criteria -*** TODO Structural Compliance -*** TODO GTD Linkage Verification -*** TODO Idempotency Check - -* Phase B: Blueprint (PROTOCOL) -:PROPERTIES: -:STATUS: DRAFT -:END: - -** 1. Architectural Intent -The Project Foundry Agent will be implemented as a command-line tool callable with a project name and optional parameters (e.g., programming language). It will leverage existing system tools (e.g., `mkdir`, `git`, `emacsclient`) to perform its tasks. Error handling and logging will be crucial. It should be idempotent, meaning that re-running the agent on the same project should not cause errors or duplication. - -** 2. Semantic Interfaces (Lisp Signatures) - -*** `foundry-create-project` - - Purpose: Top-level function to create a new project. - - Signature: `(foundry-create-project project-name &key language git gtd)` - - Arguments: - - `project-name`: String, the name of the project (and base directory). - - `language`: Keyword, the programming language paradigm of the project (e.g., `:python`, `:lisp`, `:javascript`). Influences boilerplate content. Defaults to `:generic`. - - `git`: Boolean, whether to initialize a Git repository (default: `t`). - - `gtd`: Boolean, whether to add the project to the GTD system (default: `t`). - - Returns: Symbol, `:success` if the project was created successfully, `:failure` otherwise. - - Side Effects: Creates directories, files, a git repo (optionally), and modifies the GTD system (optionally). - -*** `foundry-create-directories` - - Purpose: Creates the standard project directory structure. - - Signature: `(foundry-create-directories project-path)` - - Arguments: - - `project-path`: String, the absolute path to the project directory. - - Returns: Boolean, `t` if successful, `nil` otherwise. - - Side Effects: Creates `src`, `tests`, and `docs` directories. - -*** `foundry-create-boilerplate-files` - - Purpose: Creates boilerplate files based on the project language. - - Signature: `(foundry-create-boilerplate-files project-path language)` - - Arguments: - - `project-path`: String, the absolute path to the project directory. - - `language`: Keyword, the programming language of the project. - - Returns: Boolean, `t` if successful, `nil` otherwise. - - Side Effects: Creates initial files (e.g., `README.md`, `main.py`, `index.html`). - -*** `foundry-initialize-git` - - Purpose: Initializes a Git repository in the project directory. - - Signature: `(foundry-initialize-git project-path)` - - Arguments: - - `project-path`: String, the absolute path to the project directory. - - Returns: Boolean, `t` if successful, `nil` otherwise. - - Side Effects: Executes `git init` in the project directory. - -*** `foundry-add-to-gtd` - - Purpose: Adds the project and initial tasks to the GTD system. - - Signature: `(foundry-add-to-gtd project-name)` - - Arguments: - - `project-name`: String, the name of the project. - - Returns: Boolean, `t` if successful, `nil` otherwise. - - Side Effects: Appends to `gtd.org` using `emacsclient`. - -* See Also -- [[file:../projects/org-agent/README.org][org-agent (The Neurosymbolic Kernel)]] -- [[file:../SOUL.org][SOUL (Architectural Learnings & RCA)]] -- [[file:../gtd.org][GTD.org (Implementation Roadmap)]] \ No newline at end of file diff --git a/notes/org-skill-project-manager.org b/notes/org-skill-project-manager.org deleted file mode 100644 index 6c5b059..0000000 --- a/notes/org-skill-project-manager.org +++ /dev/null @@ -1,87 +0,0 @@ -:PROPERTIES: -:ID: bc8047c2-678b-4b61-88fa-d43554f6f4da -:CREATED: [2026-03-30 Mon 21:16] -:EDITED: [2026-04-07 Tue 13:42] -:END: -#+TITLE: SKILL: Project Manager Agent (Universal Literate Note) -#+STARTUP: content -#+FILETAGS: :project:management:git:psf: - -* Overview -The *Project Manager Agent* provides executive presence by monitoring project health and tracking git status. It leverages `:PROJECT_PATH:` metadata to gather "folder facts" and assist in the project lifecycle. - -* Phase A: Demand (PRD) -:PROPERTIES: -:STATUS: FROZEN -:END: - -** 1. Purpose -Define automated behaviors for project monitoring and version control tracking. - -** 2. User Needs -- *Visibility:* Resolve physical project locations and gather git/file facts. -- *Contextual Awareness:* Trigger on status queries or project-node edits. -- *Lifecycle Support:* Suggest commit messages and identify uncommitted work. - -** 3. Success Criteria -*** TODO Project Path Resolution -*** TODO Git Status Retrieval -*** TODO Executive Summary Generation - - -* Phase B: Blueprint (PROTOCOL) -:PROPERTIES: -:STATUS: SIGNED -:END: - -* Phase B: Blueprint (PROTOCOL) -:PROPERTIES: -:STATUS: DRAFT -:END: - -** 1. Architectural Intent -The Project Manager Agent will use a neuro-symbolic architecture. The 'neuro' component focuses on resolving project context (path resolution and file system awareness). The symbol component manages git interactions and report generation. The system is designed for extendability, allowing new project facts to be easily incorporated. We anticipate using a 'project-data' object that is passed between lisp function, allowing all project status to be accessed / updated with low overhead. - -** 2. Semantic Interfaces - -*** Project Path Resolution - -#+BEGIN_SRC lisp -;;; Resolve a project path, searching for existing files as needed. -;;; Returns canonical project path or NIL. SIDE-EFFECT: Adds project to cache. -(defun resolve-project-path (project-identifier) - (declare (type string project-identifier)) - (values (or string null))) ; Canonical path -#+END_SRC - -*** Git Status Retrieval - -#+BEGIN_SRC lisp -;;; Collects the git status information for a project. -;;; Returns a project-data plist with git status -(defun get-git-status (project-path) - (declare (type string project-path)) - (values project-data)) ; a plist of git facts, e.g., :untracked, :modified - -#+END_SRC - -*** Executive Summary Generation - -#+BEGIN_SRC lisp -;;; Generates an executive summary for a project. -;;; Return TEXT of summary for given PROJECT-DATA structure. -(defun generate-executive-summary (project-data) - (declare (type project-data project-data)) - (values string)) ; Human-readable summary. - -#+END_SRC - -*** Suggest Commit Message - -#+BEGIN_SRC lisp -;;; Generates a suggested commit message based on the project data -(defun suggest-commit-message (project-data) - (declare (type project-data project-data)) - (values string)) ; suggested git commit message (string) -#+END_SRC - diff --git a/notes/org-skill-provider-anthropic.org b/notes/org-skill-provider-anthropic.org deleted file mode 100644 index d541309..0000000 --- a/notes/org-skill-provider-anthropic.org +++ /dev/null @@ -1,79 +0,0 @@ -:PROPERTIES: -:ID: a44d29c6-a686-451e-b4e6-b060c3aa7524 -:CREATED: [2026-03-30 Mon 21:16] -:EDITED: [2026-04-07 Tue 13:42] -:END: -#+TITLE: SKILL: Anthropic Provider Agent (Universal Literate Note) -#+STARTUP: content -#+FILETAGS: :llm:provider:anthropic:claude:psf: - -* Overview -The *Anthropic Provider Agent* integrates Anthropic's Claude family of models as a pluggable System 1 (neural) backend. It enables high-intelligence reasoning, drafting, and analysis within the PSF. - -* Phase A: Demand (PRD) -:PROPERTIES: -:STATUS: FROZEN -:END: - -** 1. Purpose -Define the interface for reliable communication with the Anthropic Messages API. - -** 2. User Needs -- *Connectivity:* Reliable I/O with Claude models. -- *Configurability:* Model selection via Environment Configuration. -- *Context Management:* Leverage Claude's large context windows. -- *Safety:* Graceful error handling for API failures or missing keys. - -** 3. Success Criteria -*** TODO API Authentication -*** TODO Model Resolution Loop -*** TODO Response Parsing Verification - - -* Phase B: Blueprint (PROTOCOL) -:PROPERTIES: -:STATUS: SIGNED -:END: - -** 2. Semantic Interfaces - -*** `execute-anthropic-request` -:signature `(execute-anthropic-request prompt system-prompt &key model) :string` -:description "Direct call to the Anthropic Messages API." - -* Phase D: Build (Implementation) - -#+begin_src lisp :tangle ../projects/org-skill-provider-anthropic/src/provider-logic.lisp -(in-package :org-agent) - -(defun execute-anthropic-request (prompt system-prompt &key model) - (let ((api-key (uiop:getenv "ANTHROPIC_API_KEY")) - (endpoint "https://api.anthropic.com/v1/messages") - (model-id (or model "claude-3-5-sonnet-20240620"))) - (unless api-key (return-from execute-anthropic-request "(:type :LOG :payload (:text \"Anthropic API Key missing\"))")) - (let* ((headers `(("Content-Type" . "application/json") - ("x-api-key" . ,api-key) - ("anthropic-version" . "2023-06-01"))) - (body (cl-json:encode-json-to-string - `((model . ,model-id) - (max_tokens . 4096) - (system . ,system-prompt) - (messages . (( (role . "user") (content . ,prompt) ))))))) - (handler-case (let* ((response (dex:post endpoint :headers headers :content body :connect-timeout 10 :read-timeout 30)) - (json (cl-json:decode-json-from-string response))) - ;; Anthropic response structure: content[0].text - (cdr (assoc :text (car (cdr (assoc :content json)))))) - (error (c) (format nil "(:type :LOG :payload (:text \"Anthropic Failure: ~a\"))" c)))))) -#+end_src - -* Registration -#+begin_src lisp -(progn - (org-agent:register-neuro-backend :anthropic #'execute-anthropic-request) - - (defskill :skill-provider-anthropic - :priority 110 - :trigger (lambda (context) nil) - :neuro (lambda (context) nil) - :symbolic (lambda (action context) action))) -#+end_src diff --git a/notes/org-skill-provider-gemini.org b/notes/org-skill-provider-gemini.org deleted file mode 100644 index 2bee5bc..0000000 --- a/notes/org-skill-provider-gemini.org +++ /dev/null @@ -1,87 +0,0 @@ -:PROPERTIES: -:ID: 52799ee8-693f-49da-97bc-2c02bc6a7ef7 -:CREATED: [2026-03-30 Mon 21:16] -:EDITED: [2026-04-07 Tue 13:42] -:END: -#+TITLE: SKILL: Gemini Provider Agent (Universal Literate Note) -#+STARTUP: content -#+FILETAGS: :llm:provider:gemini:google:psf: - -* Overview -The *Gemini Provider Agent* provides a dual-path interface to Google's neural models. It supports both the low-latency Developer API and the high-fidelity Web/Pro interface. - -* Phase A: Demand (PRD) -:PROPERTIES: -:STATUS: SIGNED -:END: - -** 1. Purpose -Enable a hybrid cost/performance strategy for Google's models. - -** 2. User Needs -- *API Path:* Reliable, programmatic access for system reflexes. -- *Web Path:* Zero-cost access to Pro-tier reasoning via browser session bridging. - -* Phase B: Blueprint (PROTOCOL) -:PROPERTIES: -:STATUS: SIGNED -:END: - -** 1. Architectural Intent -Expose two distinct backends to the kernel: =:gemini-api= and =:gemini-web=. - -** 2. Semantic Interfaces - -*** `execute-gemini-api-request` -:signature `(execute-gemini-api-request prompt system-prompt &key model) :string` -:description "Direct call to the Google AI Studio API." - -*** `execute-gemini-web-request` -:signature `(execute-gemini-web-request prompt system-prompt) :string` -:description "Routes the request through the Web Research browser proxy." - -* Phase D: Build (Implementation) - -** API Implementation -#+begin_src lisp :tangle ../projects/org-skill-provider-gemini/src/provider-logic.lisp -(in-package :org-agent) - -(defun execute-gemini-request (prompt system-prompt &key model) - (let* ((auth (get-provider-auth :gemini)) (api-key (getf auth :api-key)) (bearer-token (getf auth :bearer-token)) - (endpoint-base (if model (format nil "https://generativelanguage.googleapis.com/v1/models/~a:generateContent" model) - "https://generativelanguage.googleapis.com/v1/models/gemini-1.5-flash-latest:generateContent"))) - (unless (or api-key bearer-token) (return-from execute-gemini-request "(:type :LOG :payload (:text \"Authentication missing\"))")) - (let* ((url (if api-key (format nil "~a?key=~a" endpoint-base api-key) endpoint-base)) - (headers `(("Content-Type" . "application/json") ,@(when bearer-token `(("Authorization" . ,(format nil "Bearer ~a" bearer-token)))))) - (body (cl-json:encode-json-to-string `((contents . ((parts . ((text . ,(format nil "~a~%~%Prompt: ~a" system-prompt prompt)))))))))) - (handler-case (let* ((response (dex:post url :headers headers :content body :connect-timeout 10 :read-timeout 30)) (json (cl-json:decode-json-from-string response))) - (cdr (assoc :text (cdr (assoc :parts (car (cdr (assoc :parts (car (cdr (assoc :candidates json))))))))))) - (error (c) (format nil "(:type :LOG :payload (:text \"Neural Engine Failure: ~a\"))" c)))))) - -(defun execute-gemini-api-request (prompt system-prompt &key model) - "Implementation uses the standard kernel execute-gemini-request logic." - (execute-gemini-request prompt system-prompt :model model)) -#+end_src - -** Web Implementation -#+begin_src lisp :tangle ../projects/org-skill-provider-gemini/src/provider-logic.lisp -(defun execute-gemini-web-request (prompt system-prompt &key model) - (declare (ignore model)) - "Dispatches to the browser-based Web Research skill." - (let ((full-prompt (format nil "~a~%~%Prompt: ~a" system-prompt prompt))) - (uiop:symbol-call :org-agent.skills.org-skill-web-research :ask-gemini-web full-prompt))) -#+end_src - -* Registration -#+begin_src lisp -(progn - (org-agent:register-neuro-backend :gemini #'execute-gemini-request) - (org-agent:register-neuro-backend :gemini-api #'execute-gemini-api-request) - (org-agent:register-neuro-backend :gemini-web #'execute-gemini-web-request) - - (defskill :skill-provider-gemini - :priority 90 - :trigger (lambda (context) nil) - :neuro (lambda (context) nil) - :symbolic (lambda (action context) action))) -#+end_src diff --git a/notes/org-skill-provider-groq.org b/notes/org-skill-provider-groq.org deleted file mode 100644 index 1b6d37a..0000000 --- a/notes/org-skill-provider-groq.org +++ /dev/null @@ -1,72 +0,0 @@ -:PROPERTIES: -:ID: f7db1884-49cc-4db6-9ca1-4c69ec3a631e -:CREATED: [2026-04-08 Wed 11:30] -:EDITED: [2026-04-08 Wed 11:30] -:END: -#+TITLE: SKILL: Groq Provider Agent (Universal Literate Note) -#+STARTUP: content -#+FILETAGS: :llm:provider:groq:lpu:psf: - -* Overview -The *Groq Provider Agent* leverages Groq's LPU (Language Processing Unit) for ultra-low latency inference. It is ideal for reflexive tasks and rapid interaction loops. - -* Phase A: Demand (PRD) -:PROPERTIES: -:STATUS: FROZEN -:END: - -** 1. Purpose -Enable high-speed neural completion via the Groq API. - -** 2. User Needs -- *Latency:* Sub-second response times for System 1 "hunches". -- *Compatibility:* OpenAI-compatible endpoint. -- *Reliability:* Secure management of `$GROQ_API_KEY`. - -* Phase B: Blueprint (PROTOCOL) -:PROPERTIES: -:STATUS: SIGNED -:END: - -** 1. Architectural Intent -Interface for executing ultra-fast neural requests. - -** 2. Semantic Interfaces - -*** `execute-groq-request` -:signature `(execute-groq-request prompt system-prompt &key model) :string` -:description "Direct call to the Groq Cloud API." - -* Phase D: Build (Implementation) - -#+begin_src lisp :tangle ../projects/org-skill-provider-groq/src/provider-logic.lisp -(in-package :org-agent) - -(defun execute-groq-request (prompt system-prompt &key model) - (let ((api-key (uiop:getenv "GROQ_API_KEY")) - (endpoint "https://api.groq.com/openai/v1/chat/completions") - (model-id (or model "llama-3.3-70b-versatile"))) - (unless api-key (return-from execute-groq-request "(:type :LOG :payload (:text \"Groq API Key missing\"))")) - (let* ((headers `(("Content-Type" . "application/json") - ("Authorization" . ,(format nil "Bearer ~a" api-key)))) - (body (cl-json:encode-json-to-string - `((model . ,model-id) - (messages . (( (role . "system") (content . ,system-prompt) ) - ( (role . "user") (content . ,prompt) ))))))) - (handler-case (let* ((response (dex:post endpoint :headers headers :content body :connect-timeout 5 :read-timeout 10)) - (json (cl-json:decode-json-from-string response))) - (cdr (assoc :content (cdr (assoc :message (car (cdr (assoc :choices json)))))))) - (error (c) (format nil "(:type :LOG :payload (:text \"Groq Failure: ~a\"))" c)))))) -#+end_src - -* Registration -#+begin_src lisp -(progn - (org-agent:register-neuro-backend :groq #'execute-groq-request) - - (defskill :skill-provider-groq - :priority 80 - :trigger (lambda (context) nil) - :neuro (lambda (context) nil) - :symbolic (lambda (action context) action))) -#+end_src diff --git a/notes/org-skill-provider-ollama.org b/notes/org-skill-provider-ollama.org deleted file mode 100644 index 2bb301b..0000000 --- a/notes/org-skill-provider-ollama.org +++ /dev/null @@ -1,144 +0,0 @@ -:PROPERTIES: -:ID: f605bf22-7ba7-458e-b0ce-5356e8ca46c6 -:CREATED: [2026-03-30 Mon 21:16] -:EDITED: [2026-04-07 Tue 13:42] -:END: -#+TITLE: SKILL: Ollama Provider Agent (Universal Literate Note) -#+STARTUP: content -#+FILETAGS: :llm:provider:ollama:local:psf: - -* Overview -The *Ollama Provider Agent* enables the use of local, privacy-preserving LLM models. It integrates with a local Ollama instance to ensure system functionality and sovereignty without external internet connectivity. - -* Phase A: Demand (PRD) -:PROPERTIES: -:STATUS: FROZEN -:END: - -** 1. Purpose -Define the interface for communication with a local Ollama daemon. - -** 2. User Needs -- *Sovereignty:* Fallback backend independent of cloud providers. -- *Performance:* Efficient local network interaction. -- *Simplicity:* Deterministic, non-streaming text generation. - -** 3. Success Criteria -*** TODO Local API Connectivity -*** TODO Model Specification (llama3) -*** TODO Response Extraction Verification - - -* Phase B: Blueprint (PROTOCOL) -:PROPERTIES: -:STATUS: SIGNED -:END: - -* Phase B: Blueprint (PROTOCOL) - -** 1. Architectural Intent -This protocol outlines the communication between the Ollama Provider Agent and the local Ollama instance. The primary goal is to provide a simple, deterministic interface for generating text from a specified language model. Error handling and model specification are crucial for robustness. We'll use a straightforward request-response pattern using the Ollama API. We will use the ollama HTTP API to avoid complex dependencies. - -** 2. Semantic Interfaces - -*** `ollama-generate` -This function sends a prompt to the local Ollama instance and returns the generated text. - - :lisp - (defun ollama-generate (model prompt &key (host "localhost:11434") (timeout 10)) - "Generates text from the specified Ollama model. - - MODEL: The name of the Ollama model. Example: \"llama3\" - PROMPT: The text prompt to send to the model. - HOST: The hostname and port of the Ollama instance. Defaults to localhost:11434 - TIMEOUT: Timeout for the HTTP request in seconds. Defaults to 10 - - Returns: A string containing the generated text or NIL on error." - (let ((url (format nil "http://~A/api/generate" host))) - (let ((data (json:encode-json-to-string (alist-to-plist `((model . ,model) (prompt . ,prompt) (stream . false)))))) - (handler-case - (let ((response (drakma:http-request url - :method :POST - :content-type "application/json" - :content data - :timeout timeout - :want-stream t))) - (unwind-protect - (let ((json-response (json:decode-json-from-stream (drakma:get-input-stream response)))) - (getf json-response :response)) - (drakma:close-http-connection response))) - (drakma:http-request-error (e) - (format t "Error in HTTP request: ~A~%" e) - nil) - (json:json-decode-error (e) - (format t "Error decoding JSON response: ~A~%" e) - nil) - (error (e) - (format t "Unexpected error: ~A~%" e) - nil))))) - -*** `ollama-model-exists-p` -This function checks if a given model exists in the local Ollama instance. - - :lisp - (defun ollama-model-exists-p (model &key (host "localhost:11434") (timeout 5)) - "Checks if a model exists in the local Ollama instance. - - MODEL: The name of the Ollama model to check. - HOST: The hostname and port of the Ollama instance. Defaults to localhost:11434 - TIMEOUT: Timeout for the HTTP request in seconds. Defaults to 5 - - Returns: T if the model exists, NIL otherwise." - (let ((url (format nil "http://~A/api/tags" host))) - (handler-case - (let ((response (drakma:http-request url - :method :GET - :timeout timeout - :want-stream t))) - (unwind-protect - (let ((json-response (json:decode-json-from-stream (drakma:get-input-stream response)))) - (loop for model-data in (getf json-response :models) - when (string= (getf model-data :name) model) - do (return t) - finally (return nil))) - (drakma:close-http-connection response))) - (drakma:http-request-error (e) - (format t "Error in HTTP request: ~A~%" e) - nil) - (json:json-decode-error (e) - (format t "Error decoding JSON response: ~A~%" e) - nil) - (error (e) - (format t "Unexpected error: ~A~%" e) - nil)))) - -*** `ollama-list-models` - Lists the available models in Ollama - - :lisp - (defun ollama-list-models (&key (host "localhost:11434") (timeout 5)) - "Lists available models in the local Ollama instance. - - HOST: The hostname and port of the Ollama instance. Defaults to localhost:11434 - TIMEOUT: Timeout for the HTTP request in seconds. Defaults to 5 - - Returns: a list of model names (strings)." - (let ((url (format nil "http://~A/api/tags" host))) - (handler-case - (let ((response (drakma:http-request url - :method :GET - :timeout timeout - :want-stream t))) - (unwind-protect - (let ((json-response (json:decode-json-from-stream (drakma:get-input-stream response)))) - (mapcar #'(lambda (m) (getf m :name)) (getf json-response :models))) - (drakma:close-http-connection response))) - (drakma:http-request-error (e) - (format t "Error in HTTP request: ~A~%" e) - nil) - (json:json-decode-error (e) - (format t "Error decoding JSON response: ~A~%" e) - nil) - (error (e) - (format t "Unexpected error: ~A~%" e) - nil)))) diff --git a/notes/org-skill-provider-openai.org b/notes/org-skill-provider-openai.org deleted file mode 100644 index 9787101..0000000 --- a/notes/org-skill-provider-openai.org +++ /dev/null @@ -1,84 +0,0 @@ -:PROPERTIES: -:ID: c6cbd603-3fa2-4fe9-807d-68006af1362a -:CREATED: [2026-03-30 Mon 21:16] -:EDITED: [2026-04-07 Tue 13:42] -:END: -#+TITLE: SKILL: OpenAI Provider Agent (Universal Literate Note) -#+STARTUP: content -#+FILETAGS: :llm:provider:openai:gpt:psf: - -* Overview -The *OpenAI Provider Agent* integrates OpenAI's GPT models as a pluggable System 1 (neural) backend. It provides industry-standard processing capabilities for reasoning and content generation. - -* Phase A: Demand (PRD) -:PROPERTIES: -:STATUS: FROZEN -:END: - -** 1. Purpose -Define the interface for reliable communication with the OpenAI Chat Completions API. - -** 2. User Needs -- *Compatibility:* Full implementation of the Chat Completions protocol. -- *Reliability:* Secure management of `$OPENAI_API_KEY`. -- *Optimized Inference:* Configurable temperature and model selection (GPT-4o, etc.). -- *Resilience:* Graceful handling of timeouts and errors. - -** 3. Success Criteria -*** TODO API Authentication via Bearer Token -*** TODO Chat Payload Construction -*** TODO Choice Extraction Verification - - -* Phase B: Blueprint (PROTOCOL) -:PROPERTIES: -:STATUS: SIGNED -:END: - -* Phase B: Blueprint (PROTOCOL) -:PROPERTIES: -:STATUS: DRAFT -:END: - -** 1. Architectural Intent -The OpenAI Provider Agent will act as a translator and executor for requests targeting OpenAI's Chat Completions API. It will abstract away the complexities of API authentication, payload construction, and response parsing, providing a clean and consistent interface for System 1 agents within the Lisp Machine. It prioritizes secure API key management using environment variables and offers configurable parameters for inference. The architecture focuses on resilience, managing potential API errors (timeouts, rate limits) through robust error handling. - -** 2. Semantic Interfaces - -*** `execute-openai-request` -:signature `(execute-openai-request prompt system-prompt &key model) :string` -:description "Direct call to the OpenAI Chat Completions API." - -* Phase D: Build (Implementation) - -#+begin_src lisp :tangle ../projects/org-skill-provider-openai/src/provider-logic.lisp -(in-package :org-agent) - -(defun execute-openai-request (prompt system-prompt &key model) - (let ((api-key (uiop:getenv "OPENAI_API_KEY")) - (endpoint "https://api.openai.com/v1/chat/completions") - (model-id (or model "gpt-4o"))) - (unless api-key (return-from execute-openai-request "(:type :LOG :payload (:text \"OpenAI API Key missing\"))")) - (let* ((headers `(("Content-Type" . "application/json") - ("Authorization" . ,(format nil "Bearer ~a" api-key)))) - (body (cl-json:encode-json-to-string - `((model . ,model-id) - (messages . (( (role . "system") (content . ,system-prompt) ) - ( (role . "user") (content . ,prompt) ))))))) - (handler-case (let* ((response (dex:post endpoint :headers headers :content body :connect-timeout 10 :read-timeout 30)) - (json (cl-json:decode-json-from-string response))) - (cdr (assoc :content (cdr (assoc :message (car (cdr (assoc :choices json)))))))) - (error (c) (format nil "(:type :LOG :payload (:text \"OpenAI Failure: ~a\"))" c)))))) -#+end_src - -* Registration -#+begin_src lisp -(progn - (org-agent:register-neuro-backend :openai #'execute-openai-request) - - (defskill :skill-provider-openai - :priority 100 - :trigger (lambda (context) nil) - :neuro (lambda (context) nil) - :symbolic (lambda (action context) action))) -#+end_src diff --git a/notes/org-skill-provider-openrouter.org b/notes/org-skill-provider-openrouter.org deleted file mode 100644 index 1c2fd51..0000000 --- a/notes/org-skill-provider-openrouter.org +++ /dev/null @@ -1,126 +0,0 @@ -:PROPERTIES: -:ID: db56b985-776c-4845-9f38-cc7e9b6af9f1 -:CREATED: [2026-03-30 Mon 21:16] -:EDITED: [2026-04-07 Tue 13:42] -:END: -#+TITLE: SKILL: OpenRouter Provider Agent (Universal Literate Note) -#+STARTUP: content -#+FILETAGS: :llm:provider:openrouter:unified:psf: - -* Overview -The *OpenRouter Provider Agent* acts as a unified gateway to hundreds of LLMs. It provides flexibility by dynamically switching between models based on intelligence tiers while maintaining architectural alignment. - -* Phase A: Demand (PRD) -:PROPERTIES: -:STATUS: FROZEN -:END: - -** 1. Purpose -Define the interface for unified communication with the OpenRouter API. - -** 2. User Needs -- *Abstraction:* OpenAI-compatible interface for all OpenRouter models. -- *Dynamic Routing:* Support for intelligence tiers (:POWERFUL, :FAST, :FREE). -- *Resilience:* Leverage auto-routing fallbacks. -- *Transparency:* Proper identification via Referer and Title headers. - -* Phase B: Blueprint (PROTOCOL) -:PROPERTIES: -:STATUS: SIGNED -:END: - -** 1. Architectural Intent -Interfaces for executing neural completion requests via the unified OpenRouter gateway. - -** 2. Semantic Interfaces - -*** `execute-openrouter-request` -:signature `(execute-openrouter-request prompt system-prompt &key model) :string` -:description "Routes the request through the OpenRouter gateway." - -*** `openrouter-get-available-models` -:signature `(openrouter-get-available-models) :list` -:description "Fetches available models from the OpenRouter API." - -* Phase D: Build (Implementation) - -** Tiered Model Resolution -#+begin_src lisp :tangle ../projects/org-skill-provider-openrouter/src/provider-logic.lisp -(in-package :org-agent) - -(defun get-openrouter-tiered-model (tier) - (case tier - (:powerful "anthropic/claude-3.5-sonnet") - (:fast "google/gemini-2.0-flash-001") - (:free "openrouter/auto") - (t "openrouter/auto"))) -#+end_src - -** Request Execution -#+begin_src lisp :tangle ../projects/org-skill-provider-openrouter/src/provider-logic.lisp -(defun execute-openrouter-request (prompt system-prompt &key model) - (let ((api-key (uiop:getenv "OPENROUTER_API_KEY")) - (endpoint "https://openrouter.ai/api/v1/chat/completions") - (model-id (or model (get-openrouter-tiered-model :fast)))) - - (unless api-key - (return-from execute-openrouter-request - "(:type :LOG :payload (:text \"OpenRouter API Key missing in environment\"))")) - - (let* ((headers `(("Content-Type" . "application/json") - ("Authorization" . ,(format nil "Bearer ~a" api-key)) - ("HTTP-Referer" . "https://github.com/amr/org-agent") - ("X-Title" . "org-agent Sovereign Kernel"))) - (body (cl-ppcre:regex-replace-all "\\\\/" - (cl-json:encode-json-to-string - `((model . ,model-id) - (messages . (( (role . "system") (content . ,system-prompt) ) - ( (role . "user") (content . ,prompt) ))))) - "/"))) - - (handler-case - (let* ((response (dex:post endpoint :headers headers :content body :connect-timeout 10 :read-timeout 30)) - (json (cl-json:decode-json-from-string response))) - ;; Extract content from OpenAI-style response: choices[0].message.content - (cdr (assoc :content (cdr (assoc :message (car (cdr (assoc :choices json)))))))) - (error (c) - (format nil "(:type :LOG :payload (:text \"OpenRouter Error: ~a\"))" c)))))) - -(defun openrouter-get-available-models () - "Fetches available models from OpenRouter." - (let ((api-key (uiop:getenv "OPENROUTER_API_KEY"))) - (unless api-key (return-from openrouter-get-available-models nil)) - (let ((headers `(("Authorization" . ,(format nil "Bearer ~a" api-key))))) - (handler-case - (let* ((response (dex:get "https://openrouter.ai/api/v1/models" - :headers headers - :connect-timeout 60 - :read-timeout 60)) - (json (cl-json:decode-json-from-string response)) - (data (cdr (assoc :data json))) - (results nil)) - (dolist (item data) - (let ((id (cdr (assoc :id item))) - (context-len (cdr (assoc :context--length item)))) - (when id - (push (list :id id :context (format nil "~a" (or context-len "unknown"))) results)))) - (nreverse results)) - (error (c) - (kernel-log "Model Discovery Error: ~a" c) - nil))))) -#+end_src - -* Registration -#+begin_src lisp -;; Register the backend with the kernel at load-time -(org-agent:register-neuro-backend :openrouter #'execute-openrouter-request) - -;; Export discovery if needed -(setf (fdefinition 'org-agent:openrouter-get-available-models) #'openrouter-get-available-models) - -(defskill :skill-provider-openrouter - :priority 100 - :trigger (lambda (context) nil) ; Provider skills don't trigger OODA loops - :neuro (lambda (context) nil) - :symbolic (lambda (action context) action)) -#+end_src diff --git a/notes/org-skill-router.org b/notes/org-skill-router.org deleted file mode 100644 index 1a7f4df..0000000 --- a/notes/org-skill-router.org +++ /dev/null @@ -1,70 +0,0 @@ -:PROPERTIES: -:ID: 0fb9e9cb-4af2-463c-9c6f-74f95747c5ff -:CREATED: [2026-03-30 Mon 21:16] -:EDITED: [2026-04-07 Tue 13:42] -:END: -#+TITLE: SKILL: Cognitive Router Agent (Universal Literate Note) -#+STARTUP: content -#+FILETAGS: :routing:cognition:dispatch:psf: - -* Overview -The *Cognitive Router* is the kernel's traffic controller. it classifies incoming stimuli into complexity tiers, enabling the Economist to make sovereign compute-allocation decisions. - -* Phase A: Demand (PRD) -:PROPERTIES: -:STATUS: SIGNED -:END: - -** 1. Purpose -Classify tasks by complexity to optimize neural resource allocation. - -** 2. User Needs -- *Tier Identification:* Differentiate between routine grooming and deep architectural work. -- *Dynamic Dispatch:* Route complex requests to high-fidelity backends. - -* Phase B: Blueprint (PROTOCOL) -:PROPERTIES: -:STATUS: SIGNED -:END: - -** 1. Architectural Intent -Implement a deterministic classifier for known sensors and a neural fallback for ambiguous user commands. - -** 2. Semantic Interfaces - -*** Complexity Tiers -- =:REFLEX=: System maintenance (heartbeats, persistence, cleanup). -- =:COGNITION=: Conversational tasks (chat, summarization, metadata extraction). -- =:REASONING=: Generative tasks (coding, blueprinting, debugging). - -*** Routing Logic -#+begin_src lisp :tangle ../projects/org-skill-router/src/router-logic.lisp -(in-package :org-agent) - -(defun router-classify-complexity (context) - "Returns the complexity tier for a given stimulus context." - (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 - (t :REFLEX)))) -#+end_src - -* Registration -#+begin_src lisp -(defskill :skill-router - :priority 110 - :trigger (lambda (context) nil) ; Passive classifier - :neuro (lambda (context) nil) - :symbolic (lambda (action context) (router-classify-complexity context))) -#+end_src diff --git a/notes/org-skill-safety-harness.org b/notes/org-skill-safety-harness.org deleted file mode 100644 index ddaf252..0000000 --- a/notes/org-skill-safety-harness.org +++ /dev/null @@ -1,95 +0,0 @@ -:PROPERTIES: -:ID: 98576df2-c496-4e4a-9acb-0bca514a0305 -:CREATED: [2026-03-31 Tue 18:28] -:EDITED: [2026-04-07 Tue 13:42] -:END: -#+TITLE: SKILL: Global Safety Harness (Universal Literate Note) -#+STARTUP: content -#+FILETAGS: :security:sandbox:ast:psf: - -* Overview -The *Global Safety Harness* is the primary "Safety Gate" for the Neurosymbolic Lisp Machine. It provides a recursive AST validator that subjects all Elisp proposals from System 1 to a strict "Deny-by-Default" sandbox, preventing arbitrary code execution while allowing high-fidelity system manipulation. - -* Phase A: Demand (PRD) -:PROPERTIES: -:STATUS: FROZEN -:END: - -** 1. Purpose -Define a high-integrity, recursive security sandbox for Elisp 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. -- *Symbolic Preemption:* This skill acts as a mandatory global System 2 check. - -** 3. Success Criteria -*** TODO Implement recursive AST walker in Lisp -*** TODO Establish strict function whitelist (surgical Org operations) -*** TODO Detect and block nested 'eval' attempts -*** TODO Verify that malformed or malicious sexps are rejected - - -* Phase B: Blueprint (PROTOCOL) -:PROPERTIES: -:STATUS: SIGNED -:END: - -* Phase B: Blueprint (PROTOCOL) -:PROPERTIES: -:STATUS: IN-PROGRESS -:END: - -** 1. Architectural Intent - -The Global Safety Harness will function as a global aspect, intercepting all Elisp forms before they are evaluated by the core Lisp interpreter. It achieves this by: - -- **AST Walking:** Recursively traversing the Abstract Syntax Tree (AST) of the Elisp expression. -- **Whitelist Enforcement:** Comparing each function call and variable access against a pre-approved whitelist. Any item not on the whitelist is immediately rejected. -- **Eval Blocking:** Explicitly searching for and rejecting any instances of `eval`, `load`, `eval-expression`, and related functions that enable dynamic code generation or loading. -- **Error Handling:** Providing informative error messages when a security violation occurs, including the specific function or variable that triggered the rejection and its location within the AST. -- **Performance Consideration:** Optimizing the AST walking and whitelist lookup to minimize overhead on Elisp evaluation. Memoization of whitelist checks should be implemented to avoid redundant lookups. - -** 2. Semantic Interfaces - -*** Function: +safety-harness-validate+ - - #+BEGIN_SRC lisp - (defun +safety-harness-validate+ (form whitelist) - "Validates an Elisp form against a security whitelist. - FORM: The Elisp form to validate (list or symbol). - WHITELIST: An alist associating symbols (function/variable names) to metadata. Metadata includes :safe? boolean flag and :trust-level (integer).") - #+END_SRC - -*** Function: +safety-harness-ast-walk+ - - #+BEGIN_SRC lisp - (defun +safety-harness-ast-walk+ (form whitelist) - "Recursively walks the Abstract Syntax Tree (AST) of an Elisp form, - validating each node against the whitelist.") - #+END_SRC - -*** Function: +safety-harness-whitelist-lookup+ - - #+BEGIN_SRC lisp - (defun +safety-harness-whitelist-lookup+ (symbol whitelist) - "Looks up a symbol in the security whitelist. - Returns the whitelist entry if found, or nil if not found.") - #+END_SRC - -*** Function: +safety-harness-eval-blocked?+ - - #+BEGIN_SRC lisp - (defun +safety-harness-eval-blocked?+ (form) - "Checks if the Elisp form contains any prohibited eval-like constructs. - Returns t if eval is blocked, nil otherwise.") - #+END_SRC - -*** Data Structure: +safety-harness-error+ - - A plist data structure representing a security violation: - - `:type`: `'whitelist-violation` or `'eval-blocked` - - `:symbol`: The offending symbol (function or variable name) - - `:location`: A list representing the path within the AST where the violation occurred. - diff --git a/notes/org-skill-scientist.org b/notes/org-skill-scientist.org deleted file mode 100644 index b4c1fcd..0000000 --- a/notes/org-skill-scientist.org +++ /dev/null @@ -1,67 +0,0 @@ -:PROPERTIES: -:ID: 95a555e5-bf95-4128-9224-7341c52c40b6 -:CREATED: [2026-03-31 Tue 20:28] -:EDITED: [2026-04-07 Tue 13:42] -:END: -#+TITLE: SKILL: The Scientist Agent (Universal Literate Note) -#+STARTUP: content -#+FILETAGS: :debugging:science:logic:tdd:psf: -#+DEPENDS_ON: skill-tdd-runner skill-scribe-rca - -* Overview -The *Scientist Agent* provides a formal, hypothesis-driven approach to debugging. Instead of "trial and error," it formulates symbolic theories about why a failure occurred, designs experiments (test cases), and updates the system's *Institutional Memory* upon discovery. - -* Phase A: Demand (PRD) -:PROPERTIES: -:STATUS: FROZEN -:END: - -** 1. Purpose -Eliminate speculative debugging through rigorous scientific methodology. - -** 2. User Needs -- *Hypothesis Formulation:* Neural generation of potential failure causes. -- *Experimental Design:* Autonomous creation of minimal failing test cases. -- *Theory Verification:* Execution of tests via the TDD Runner. -- *Knowledge Update:* Permanent update to `RCA.org` to prevent regression. - -* Phase D: Build (Implementation) - -** Scientific Loop -#+begin_src lisp :tangle ../projects/org-skill-scientist/src/scientist-logic.lisp -(defun scientist-hypothesis (context) - "Neural stage: Formulates a hypothesis about a failure based on logs." - (let* ((payload (getf context :payload)) - (failure-log (getf payload :text)) - (project (getf payload :project))) - (org-agent:ask-neuro - (format nil "Project ~a failed with log: ~a. Formulate a 'Theory of Failure' and suggest a surgical fix." project failure-log) - :system-prompt "You are a PSF Senior Debugging Scientist. Return a Lisp plist: (:target :scientist :action :propose :hypothesis \"...\" :failure-log \"...\")"))) - -(defun scientist-propose-fix (action context) - "Symbolic stage: Triggers the Self-Fix agent with the formulated hypothesis." - (declare (ignore context)) - (let* ((payload (getf action :payload)) - (hypothesis (getf payload :hypothesis)) - (failure-log (getf payload :failure-log))) - (org-agent:kernel-log "SCIENTIST - Hypothesis formulated. Triggering SELF-FIX...") - (org-agent:inject-stimulus - `(:type :EVENT :payload (:sensor :repair-request :hypothesis ,hypothesis :failure-log ,failure-log))) - (format nil "SUCCESS - Scientist proposed fix for failure."))) -#+end_src - -* Registration -#+begin_src lisp -(defskill :skill-scientist - :priority 90 - :trigger (lambda (context) (eq (getf (getf context :payload) :sensor) :test-failure)) - :neuro #'scientist-hypothesis - :symbolic #'scientist-propose-fix) -#+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-scientist (context))\n(defun neuro-skill-org-skill-scientist (context)) diff --git a/notes/org-skill-scribe-rca.org b/notes/org-skill-scribe-rca.org deleted file mode 100644 index 318cd7a..0000000 --- a/notes/org-skill-scribe-rca.org +++ /dev/null @@ -1,64 +0,0 @@ -:PROPERTIES: -:ID: 0f55aff3-a586-409a-9ba9-8c88477a1d1a -:CREATED: [2026-03-30 Mon 21:16] -:EDITED: [2026-04-07 Tue 13:42] -:END: -#+TITLE: SKILL: Scribe-RCA (Universal Literate Note) -#+STARTUP: content -#+FILETAGS: :memory:rca:learning:psf: -#+DEPENDS_ON: skill-atomic-notes - -* Overview -The *Scribe-RCA* agent is responsible for *Phase F: Memory*. It captures "Permanent Learnings" after significant failures or task completions, ensuring the system's *Institutional Memory* grows with every cycle. - -* Phase A: Demand (PRD) -:PROPERTIES: -:STATUS: FROZEN -:END: - -** 1. Purpose -Automate the extraction of root causes and architectural learnings into the Memex. - -** 2. User Needs -- *Root Cause Analysis:* Automatically draft an RCA note after a `skip-event` recovery. -- *Permanent Learning:* Update `SOUL.org` or a dedicated `RCA.org` with new invariants. -- *Version Control Integration:* Commit new RCA notes to Gitea autonomously. -- *Traceability:* Link every learning back to the original failure stimulus. - -* Phase D: Build (Implementation) - -** Memory Extraction -#+begin_src lisp :tangle projects/org-skill-scribe-rca/src/rca-logic.lisp -(defun scribe-rca-draft (failure-context) - "Drafts an RCA note based on a recent kernel failure." - (let* ((payload (getf failure-context :payload)) - (error-msg (getf payload :text)) - (timestamp (local-time:format-timestring nil (local-time:now))) - (gitea-url (org-agent::get-env "GITEA_URL"))) - (org-agent:ask-neuro - (format nil "Create a Root Cause Analysis (RCA) note for the following error: ~a" error-msg) - :system-prompt "You are the PSF Scribe. Extract the deep architectural failure and propose a new invariant for SOUL.org."))) - -(defun scribe-rca-commit (rca-note) - "Commits the drafted RCA note to the Gitea repository." - (let ((gitea-url (org-agent::get-env "GITEA_URL"))) - (kernel-log "SCRIBE - Committing learning to Gitea: ~a" gitea-url) - ;; Logic to use 'git commit' via shell-actuator - (org-agent:spawn-task (format nil "Commit this RCA note to Gitea: ~a" rca-note)))) -#+end_src - -* Registration -#+begin_src lisp -(defskill :skill-scribe-rca - :priority 90 - :trigger (lambda (context) (search "SYSTEM ERROR" (format nil "~a" (getf (getf context :payload) :text)))) - :neuro #'scribe-rca-draft - :symbolic (lambda (action context) action)) -#+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-scribe-rca (context))\n(defun neuro-skill-org-skill-scribe-rca (context)) diff --git a/notes/org-skill-scribe.org b/notes/org-skill-scribe.org deleted file mode 100644 index cb5a86e..0000000 --- a/notes/org-skill-scribe.org +++ /dev/null @@ -1,104 +0,0 @@ -:PROPERTIES: -:ID: 0e849660-4a5c-4364-93be-abec161a5468 -:CREATED: [2026-03-30 Mon 21:16] -:EDITED: [2026-04-07 Tue 13:42] -:END: -#+TITLE: SKILL: Scribe Agent (Universal Literate Note) -#+STARTUP: content -#+FILETAGS: :scribe:distillation:psf:audit: - -* Overview -The *Scribe Agent* is the primary custodian of the Institutional Memory. It distills ephemeral daily thoughts into atomic notes, enriches the knowledge graph via Karpathy-style synthesis, and audits foundry projects. - -* Phase A: Demand (PRD) -:PROPERTIES: -:STATUS: FROZEN -:END: - -** 1. Purpose -Define automated distillation, enrichment, and auditing behaviors. - -** 2. User Needs -- *Knowledge Distillation:* Weekly scan of ~daily/~ files to extract evergreen concepts. -- *Privacy Mandate:* NEVER process subtrees with the ~@personal~ tag. (LLM exclusion). -- *Content Enrichment (Karpathy Method):* - 1. Cross-linking to existing notes. - 2. Merging redundant concepts. - 3. Splitting bloated notes. - 4. Deciding on further self-learning (deep or adjacent). - 5. Generating project ideas from insights. -- *Archive Preservation:* Never delete originals from ~daily/~. - -** 3. Success Criteria -*** TODO Successful distillation of a week's worth of dailies. -*** TODO Automated link suggestion between new and old notes. -*** TODO Project idea generation verified by user. - -* Phase B: Blueprint (PROTOCOL) -:PROPERTIES: -:STATUS: SIGNED -:END: - -** 1. Architectural Intent -Uses a weekly heartbeat trigger. Employs a "Compiler" approach: System 1 (Neuro) generates synthesis proposals, System 2 (Symbolic) verifies file-system safety and tag constraints. - -** 2. Semantic Interfaces -#+begin_src lisp -(defun scribe-distill-weekly () - "Main entry point for weekly knowledge synthesis.") - -(defun scribe-enrich-concept (note-id) - "Triggers neural analysis for linking and project ideas.") -#+end_src - -* Phase D: Build (Implementation) - -** Git-based Change Detection -#+begin_src lisp :tangle ../projects/org-skill-scribe/src/scribe-engine.lisp -(defun scribe-get-changed-dailies () - "Returns list of daily files modified in the last 7 days via git." - (uiop:run-program (list "git" "log" "--since='1 week ago'" "--name-only" "--pretty=format:" "--" "daily/") :output :lines)) -#+end_src - -** Pre-Filtering (The Privacy Wall) -#+begin_src lisp :tangle ../projects/org-skill-scribe/src/scribe-engine.lisp -(defun scribe-filter-personal (org-ast-node) - "Recursively strips out any headline or content tagged with @personal. - This runs strictly in System 2 BEFORE any data is passed to System 1." - (let ((tags (getf (org-agent:org-object-attributes org-ast-node) :TAGS))) - (when (not (member "@personal" tags :test #'string=)) - org-ast-node))) -#+end_src - -** Karpathy-Style Synthesis -#+begin_src lisp :tangle ../projects/org-skill-scribe/src/scribe-engine.lisp -(defun neuro-skill-scribe-enrich (context) - "Neural stage for high-entropy knowledge synthesis. - Assumes 'context' has already passed through scribe-filter-personal." - (let* ((content (getf context :content)) - (existing-notes "")) ; Skeletal: would call atomic-notes-scan - (ask-neuro content :system-prompt - (format nil "You are the PSF Scribe. Your goal is to ENRICH this concept. -RULES: -1. CROSS-LINK: Suggest links to existing notes. -2. MERGE/SPLIT: Identify if this should be combined with another or broken down. -3. SELF-LEARNING: Suggest a 'Path to Mastery' (deeper or adjacent). -4. PROJECTS: Suggest a PSF-style project based on this. -5. NO FILLER: Return a Lisp plist.")))) - -(defun trigger-skill-scribe (context) - "Triggers on delegation to :scribe or :distill." - (let ((payload (getf context :payload))) - (and (eq (getf context :type) :EVENT) - (eq (getf payload :sensor) :delegation) - (member (getf payload :target-skill) '(:scribe :distill))))) -#+end_src - -* Registration -#+begin_src lisp -(defskill :skill-scribe - :priority 60 - :trigger #'trigger-skill-scribe - :neuro #'neuro-skill-scribe-enrich - :symbolic #'scribe-get-changed-dailies) -#+end_src diff --git a/notes/org-skill-self-fix.org b/notes/org-skill-self-fix.org deleted file mode 100644 index c70f424..0000000 --- a/notes/org-skill-self-fix.org +++ /dev/null @@ -1,90 +0,0 @@ -:PROPERTIES: -:ID: 65891ce2-a465-49e6-a0c1-be13d3288d55 -:CREATED: [2026-03-30 Mon 21:16] -:EDITED: [2026-04-07 Tue 13:42] -:END: -#+TITLE: SKILL: Self-Fix Agent (Universal Literate Note) -#+STARTUP: content -#+FILETAGS: :self-repair:autonomy:debugging:psf: -#+DEPENDS_ON: skill-scientist skill-shell-actuator - -* Overview -The *Self-Fix Agent* is the system's "Repair Mechanism." It takes the failure hypotheses from the *Scientist Agent*, applies surgical code modifications in a sandboxed environment, and merges the fix only after rigorous verification by the *TDD Runner*. - -* Phase A: Demand (PRD) -:PROPERTIES: -:STATUS: FROZEN -:END: - -** 1. Purpose -Enable autonomous, verified code correction without human intervention. - -** 2. User Needs -- *Surgical Modification:* Apply targeted changes to specific Lisp functions or Org headlines. -- *Sandboxed Verification:* Test every fix in a controlled environment before merging. -- *Rollback Capability:* Use the *Interactive Steering* snapshots to revert if a fix fails. -- *Audit Logging:* Every fix must be documented in `RCA.org`. - -* Phase D: Build (Implementation) - -** Repair Logic -#+begin_src lisp :tangle ../projects/org-skill-self-fix/src/repair-logic.lisp -(defun self-fix-replace-all (string part replacement) - (with-output-to-string (out) - (loop with part-length = (length part) - for old-pos = 0 then (+ pos part-length) - for pos = (search part string :start2 old-pos) - do (write-string string out :start old-pos :end (or pos (length string))) - when pos do (write-string replacement out) - while pos))) - -(defun self-fix-apply (action context) - "Applies a surgical code fix directly to the target file." - (declare (ignore context)) - (let* ((payload (getf action :payload)) - (target-file (getf payload :file)) - (old-code (getf payload :old)) - (new-code (getf payload :new))) - (org-agent:kernel-log "SELF-FIX - Attempting surgical fix on ~a..." target-file) - (if (uiop:file-exists-p target-file) - (let ((content (uiop:read-file-string target-file))) - (if (search old-code content) - (let ((new-content (self-fix-replace-all content old-code new-code))) - (with-open-file (out target-file :direction :output :if-exists :supersede) - (write-string new-content out)) - (org-agent:kernel-log "SELF-FIX SUCCESS - Applied fix to ~a" target-file) - t) - (progn - (org-agent:kernel-log "SELF-FIX FAILURE - Could not find old code in ~a" target-file) - nil))) - (progn - (org-agent:kernel-log "SELF-FIX FAILURE - File not found: ~a" target-file) - nil)))) - -(defun neuro-skill-self-fix (context) - "Neural stage: Synthesizes a surgical code modification based on the hypothesis." - (let* ((payload (getf context :payload)) - (hypothesis (getf payload :hypothesis)) - (failure-log (getf payload :failure-log))) - (org-agent:ask-neuro - (format nil "Based on the hypothesis '~a' and failure '~a', provide the exact Lisp code to fix it. -Return a Lisp plist: (:target :self-fix :action :apply :file \"path/to/file.lisp\" :old \"old code\" :new \"new code\")" - hypothesis failure-log) - :system-prompt "You are the PSF Repair Actuator. You MUST return ONLY a Lisp plist."))) -#+end_src - -* Registration -#+begin_src lisp -(defskill :skill-self-fix - :priority 95 - :trigger (lambda (context) (eq (getf (getf context :payload) :sensor) :repair-request)) - :neuro #'neuro-skill-self-fix - :symbolic #'self-fix-apply) -#+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 neuro-skill-org-skill-self-fix (context)) diff --git a/notes/org-skill-shell-actuator.org b/notes/org-skill-shell-actuator.org deleted file mode 100644 index 4a0ab48..0000000 --- a/notes/org-skill-shell-actuator.org +++ /dev/null @@ -1,146 +0,0 @@ -:PROPERTIES: -:ID: 0ae190ec-5658-4630-aed8-a5e9ffbbea0e -:CREATED: [2026-03-30 Mon 21:16] -:EDITED: [2026-04-07 Tue 13:42] -:END: -#+TITLE: SKILL: Shell Actuator Agent (Universal Literate Note) -#+STARTUP: content -#+FILETAGS: :shell:actuator:system:psf: - -* Overview -The *Shell Actuator Agent* provides the bridge to the host operating system. It enables secure command execution while maintaining a strict security posture through whitelisting and diagnostic feedback loops. - -* Phase A: Demand (PRD) -:PROPERTIES: -:STATUS: FROZEN -:END: - -** 1. Purpose -Define a secure, diagnostic-rich interface for host OS interaction. - -** 2. User Needs -- *Secure Actuation:* Strict whitelist of permitted commands. -- *Diagnostic Feedback:* Capture STDOUT, STDERR, and exit codes. -- *Loop Closure:* Automatic neural analysis of command results. -- *Resilience:* Graceful handling of blocked or failed commands. - -** 3. Success Criteria -*** TODO Whitelist Enforcement -*** TODO Diagnostic Capture -*** TODO Result Analysis Loop - -* Phase B: Blueprint (PROTOCOL) -:PROPERTIES: -:STATUS: SIGNED -:END: - -** 1. Architectural Intent -Interfaces for secure system calls. State is event-driven via the core kernel bus. - -** 2. Semantic Interfaces -#+begin_src lisp -(defun execute-shell-safely (action) - "Verifies command against whitelist and captures diagnostics.") - -(defun trigger-skill-shell-actuator (context) - "Monitors for shell-response events.") - -(defun neuro-skill-shell-actuator (context) - "Neural interpretation of command diagnostics.") -#+end_src - -* Phase D: Build (Implementation) - -** Whitelisting & Execution -#+begin_src lisp :tangle ../projects/org-skill-shell-actuator/src/shell-logic.lisp -(defparameter *allowed-commands* '("ls" "git" "rg" "grep" "date" "echo" "cat" "node" "python3" "sbcl")) - -(defun execute-shell-safely (action context) - (let* ((cmd-string (getf (getf action :payload) :cmd)) - (executable (car (uiop:split-string cmd-string :separator '(#\Space))))) - (if (member executable *allowed-commands* :test #'string=) - (multiple-value-bind (stdout stderr exit-code) - (uiop:run-program cmd-string :output :string :error-output :string :ignore-error-status t) - (org-agent:inject-stimulus - `(:type :EVENT :payload (:sensor :shell-response :cmd ,cmd-string :stdout ,(or stdout "") :stderr ,(or stderr "") :exit-code ,exit-code)) - :stream (getf context :reply-stream))) - (org-agent:inject-stimulus - `(:type :EVENT :payload (:sensor :shell-response :cmd ,cmd-string :stdout "" :stderr "ERROR - Command not in security whitelist." :exit-code 1)) - :stream (getf context :reply-stream))))) - -(defun execute-sandboxed-script (action context) - "Executes a synthesized script (Python/Lisp/JS) in a controlled directory. - This enables SOTA-level Tool Synthesis and Iterative Fixing." - (let* ((payload (getf action :payload)) - (language (getf payload :language)) - (content (getf payload :content)) - (sandbox-dir "/tmp/org-agent-sandbox/") - (filename (format nil "synth-~a.~a" (get-universal-time) (case language (:python "py") (:lisp "lisp") (:js "js") (t "txt")))) - (full-path (format nil "~a~a" sandbox-dir filename))) - - (ensure-directories-exist sandbox-dir) - (with-open-file (out full-path :direction :output :if-exists :supersede) - (write-string content out)) - - (let ((cmd (case language - (:python (format nil "python3 ~a" full-path)) - (:lisp (format nil "sbcl --script ~a" full-path)) - (:js (format nil "node ~a" full-path))))) - (multiple-value-bind (stdout stderr exit-code) - (uiop:run-program cmd :output :string :error-output :string :ignore-error-status t) - (org-agent:inject-stimulus - `(:type :EVENT :payload (:sensor :shell-response :cmd ,cmd :stdout ,(or stdout "") :stderr ,(or stderr "") :exit-code ,exit-code :synthesis-p t)) - :stream (getf context :reply-stream)))))) - -(defun provision-microvm (id &key (cpu 1) (ram 512)) - "Hardware-Level Isolation: Provisions an ephemeral Firecracker MicroVM. - This is the high-security evolution of directory-based sandboxing." - (kernel-log "SECURITY [Hardware] - Provisioning MicroVM ~a (CPU: ~a, RAM: ~aMB)..." id cpu ram) - ;; Future implementation: Wraps 'fcvm' or 'firecracker' CLI calls. - (format nil "vm-~a-provisioned" id)) -#+end_src - -** Feedback Perception -#+begin_src lisp :tangle ../projects/org-skill-shell-actuator/src/shell-logic.lisp -(defun trigger-skill-shell-actuator (context) - (let ((type (getf context :type)) - (payload (getf context :payload))) - (and (eq type :EVENT) - (eq (getf payload :sensor) :shell-response)))) -#+end_src - -** Neuro-Cognitive Analysis -#+begin_src lisp :tangle ../projects/org-skill-shell-actuator/src/shell-logic.lisp -(defun neuro-skill-shell-actuator (context) - (let* ((p (getf context :payload)) - (cmd (getf p :cmd)) - (stdout (getf p :stdout)) - (stderr (getf p :stderr)) - (exit-code (getf p :exit-code)) - (synthesis-p (getf p :synthesis-p))) - (if synthesis-p - (format nil " - TOOL SYNTHESIS RESULT: - Command: ~a (Exit: ~a) - STDOUT: ~a - STDERR: ~a - - TASK: - If the command failed (Exit != 0), analyze the STDERR and propose a FIX for the script. - If it succeeded, use the STDOUT to complete the original goal. - " cmd exit-code stdout stderr) - (let ((result-text (format nil "* Shell Command Result\n- Command: ~a\n- Exit Code: ~a\n\n** STDOUT\n#+begin_example\n~a\n#+end_example\n\n** STDERR\n#+begin_example\n~a\n#+end_example" - cmd exit-code stdout stderr))) - `(:type :request :target :emacs :payload (:action :insert-at-end :buffer "*org-agent-chat*" :text ,result-text)))))) -#+end_src - -* Registration -#+begin_src lisp -(org-agent:register-actuator :shell #'execute-shell-safely) - -(defskill :skill-shell-actuator - :priority 80 - :trigger #'trigger-skill-shell-actuator - :neuro #'neuro-skill-shell-actuator - :symbolic (lambda (action context) action)) -#+end_src diff --git a/notes/org-skill-sub-agent-manager.org b/notes/org-skill-sub-agent-manager.org deleted file mode 100644 index db89898..0000000 --- a/notes/org-skill-sub-agent-manager.org +++ /dev/null @@ -1,82 +0,0 @@ -:PROPERTIES: -:ID: e870d860-5db7-443a-aaf3-23cd5521b27c -:CREATED: [2026-03-31 Tue 18:28] -:EDITED: [2026-04-07 Tue 13:42] -:END: -#+TITLE: SKILL: Sub-Agent Manager (Concurrency & Parallelism) -#+STARTUP: content -#+FILETAGS: :concurrency:parallelism:threads:psf: - -* Overview -The *Sub-Agent Manager* enables the Neurosymbolic Lisp Machine to handle multiple concurrent thoughts. It allows the primary kernel to "spawn" lightweight, isolated Lisp threads (sub-agents) to perform long-running or background tasks (research, massive refactors, etc.) without blocking the main event bus. - -* Phase A: Demand (PRD) -:PROPERTIES: -:STATUS: FROZEN -:END: - -** 1. Purpose -Define the interfaces for parallel cognitive execution and thread lifecycle management. - -** 2. User Needs -- *Non-Blocking Execution:* Spawn background threads for long-running tasks. -- *Context Isolation:* Sub-agents must have their own execution context to prevent parent context poisoning. -- *Communication Loop:* Sub-agents must inject a "Return Stimulus" upon completion. -- *Observability:* Ability to list and terminate active sub-agents. - -** 3. Success Criteria -*** TODO Successful spawning of a non-blocking background thread -*** TODO Verification of context isolation (distinct local variables) -*** TODO Autonomous injection of :sub-agent-complete stimulus -*** TODO Thread safety verification using bordeaux-threads locks - - -* Phase B: Blueprint (PROTOCOL) -:PROPERTIES: -:STATUS: SIGNED -:END: - -* Phase B: Blueprint (PROTOCOL) - :PROPERTIES: - :STATUS: DRAFT - :END: - -** 1. Architectural Intent -The Sub-Agent Manager is designed as a facade over a thread management library (initially `bordeaux-threads`). It provides a high-level API for spawning, managing, and monitoring sub-agents. The core principle is to create isolated Lisp environments for each sub-agent, encapsulating all state and preventing interference with the main system or other sub-agents. Communication back to the main kernel occurs through a standardized `:sub-agent-complete` stimulus injected into the event bus. Thread safety, enforced with locks where necessary, is paramount. - -** 2. Semantic Interfaces (Lisp Signatures) - -*** `spawn-sub-agent (task-fn &key name)` - - *Purpose:* Creates and starts a new sub-agent thread. - - *Parameters:* - - `task-fn`: A function of no arguments that contains the code to be executed in the sub-agent. - - `name`: (optional) A symbol representing the name of the sub-agent for identification and debugging. - - *Returns:* A sub-agent object (e.g., a struct) representing the spawned thread, containing its ID, status, and other metadata. - - *Side Effects:* Creates a new thread and starts the execution of `task-fn` within it. - -*** `kill-sub-agent (sub-agent)` - - *Purpose:* Terminates a running sub-agent. - - *Parameters:* - - `sub-agent`: The sub-agent object (returned by `spawn-sub-agent`) representing the thread to terminate. - - *Returns:* `T` if the sub-agent was successfully terminated, `NIL` otherwise. - - *Side Effects:* Attempts to terminate the specified thread, potentially releasing any resources held by the sub-agent. - -*** `list-sub-agents ()` - - *Purpose:* Returns a list of all active sub-agents. - - *Parameters:* None - - *Returns:* A list of sub-agent objects, each representing a running sub-agent. - -*** `sub-agent-status (sub-agent)` - - *Purpose:* Returns the current status of a sub-agent. - - *Parameters:* - - `sub-agent`: The sub-agent object to query. - - *Returns:* A symbol representing the status of the sub-agent (e.g., `:running`, `:completed`, `:terminated`, `:error`). - -*** `inject-sub-agent-completion-stimulus (result &key sub-agent)` - - *Purpose:* This PRIVATE function (not exposed directly) is called by the sub-agent, to inject knowledge of the result of its process into the stimulus stream. - - *Parameters:* - - `result`: The result of the sub-agent's computation. - - `sub-agent`: The current sub-agent (optional). - - *Returns:* `T` if stimulus was injected successfully - - *Side Effects:* Injects a `:sub-agent-complete` stimulus into the event bus. The stimulus will contain the `result` and any metadata associated with the `sub-agent` (including its name/id). The stimulus will be of the form `(:type :sub-agent-complete :result :sub-agent )` - diff --git a/notes/org-skill-task-integrity.org b/notes/org-skill-task-integrity.org deleted file mode 100644 index 59c1a02..0000000 --- a/notes/org-skill-task-integrity.org +++ /dev/null @@ -1,77 +0,0 @@ -: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:psf: - -* 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: - - -* Phase B: Blueprint (PROTOCOL) -:PROPERTIES: -:STATUS: DRAFT -:END: - -** 1. Architectural Intent - The Task Integrity Agent will operate as a reactive system, intercepting task state change requests within the Org-mode task management system. It will validate these requests against predefined semantic rules and dependencies before allowing the change to propagate. It will be implemented using Lisp, leveraging Org-mode's extension capabilities to hook into task state modification events. The goal is to build a system that is both performant and easily extensible with new integrity rules. Errors will be reported clearly to the user with options for correction. - -** 2. Semantic Interfaces (Lisp Signatures) - -*** `task-integrity-check (task-id new-state)` - - *Purpose:* Core function to validate a proposed state transition. - - *Parameters:* - - `task-id`: Unique identifier of the task (e.g., Org-id). - - `new-state`: Target state of the task (e.g., 'DONE', 'ACTIVE'). - - *Returns:* `t` if the transition is valid; `nil` or an error message (string) if invalid. - - *Example:* `(task-integrity-check "*TODO Example Task" 'DONE)` - -*** `semantic-mapping (task-state)` - - *Purpose:* Maps Org-mode task states (e.g., 'TODO', 'DONE') to semantic categories (e.g., 'Active', 'Resolved'). - - *Parameters:* - - `task-state`: An Org-mode task state keyword. - - *Returns:* Semantic category symbol (e.g., `:active`, `:resolved`). - - *Example:* `(semantic-mapping 'TODO)` -> `:active` - -*** `detect-active-children (task-id)` - - *Purpose:* Checks if a task has any child tasks in an active state. - - *Parameters:* - - `task-id`: Unique identifier of the parent task. - - *Returns:* A list of active child task IDs, or `nil` if no active children exist. - - *Example:* `(detect-active-children "*TODO Parent Task")` -> `("*TODO Child Task 1" "*TODO Child Task 2")` (if they are TODO) - -*** `block-state-transition (task-id error-message)` - - *Purpose:* Prevents a task state transition and displays an error message to the user. - - *Parameters:* - - `task-id`: Unique identifier of the task. - - `error-message`: String explaining why the transition is blocked. - - *Returns:* `nil` (side effect: displays message). - diff --git a/notes/org-skill-tdd-runner.org b/notes/org-skill-tdd-runner.org deleted file mode 100644 index 52355ef..0000000 --- a/notes/org-skill-tdd-runner.org +++ /dev/null @@ -1,85 +0,0 @@ -:PROPERTIES: -:ID: 230dd5b0-39ab-4f30-84da-0dc628e667b7 -:CREATED: [2026-03-31 Tue 18:43] -:EDITED: [2026-04-07 Tue 13:42] -:END: -#+TITLE: SKILL: Automated TDD Runner (Universal Literate Note) -#+STARTUP: content -#+FILETAGS: :tdd:ci:verification:safety:psf: - -* Overview -The *Automated TDD Runner* provides the system with Continuous Integration (CI) capabilities. It monitors active project directories and autonomously executes test suites whenever a file change is detected, ensuring that the kernel remains in a "Green" (verified) state. - -* Phase A: Demand (PRD) -:PROPERTIES: -:STATUS: FROZEN -:END: - -** 1. Purpose -Define automated behaviors for background test execution and regression alerting. - -** 2. User Needs -- *Background Execution:* Run `FiveAM` (Lisp) or `pytest` (Python) suites without user intervention. -- *Trigger on Perception:* Execute tests whenever a `:buffer-update` or `:file-saved` event occurs. -- *Immediate Alerting:* Inject a high-priority `:EVENT` into the kernel if a test fails. -- *System Locking:* Option to prevent further actions if the project is in a "RED" (failing) state. - -** 3. Success Criteria -*** TODO Automatic test suite discovery logic verification -*** TODO Background execution of FiveAM test suite -*** TODO Regression event injection on failure -*** TODO Integration with the Self-Fix agent - -* Phase B: Blueprint (PROTOCOL) -:PROPERTIES: -:STATUS: SIGNED -:END: - -** 1. Architectural Intent -Interfaces for background verification and kernel alerting. Source of truth is the project's `tests/` directory and the result of the test runner. - -** 2. Semantic Interfaces -"Triggered when a project file is modified; initiates the test loop." -"Executes the standard test suite for the given project." - -* Phase D: Build (Implementation) - -** Test Execution -#+begin_src lisp :tangle ../projects/org-skill-tdd-runner/src/runner-logic.lisp -(defun run-tests-for-project (project-name) - "Executes the standard test suite for the given project using SBCL." - (let* ((projects-dir (or (uiop:getenv "PROJECTS_DIR") "projects/")) - (project-dir (format nil "~aorg-skill-~a/" projects-dir project-name)) - (test-file (format nil "~atests/test-suite.lisp" project-dir))) - (org-agent:kernel-log "CI - Running tests for ~a..." project-name) - (if (uiop:file-exists-p test-file) - (multiple-value-bind (output error-output exit-code) - (uiop:run-program (list "sbcl" "--batch" "--load" test-file "--eval" "(uiop:quit)") - :ignore-error-status t :output :string :error-output :string) - (if (= exit-code 0) - (org-agent:kernel-log "CI SUCCESS - ~a passed all tests." project-name) - (progn - (org-agent:kernel-log "CI FAILURE - ~a failed tests with exit code ~a" project-name exit-code) - (org-agent:inject-stimulus - `(:type :EVENT :payload (:sensor :test-failure :project ,project-name :text ,output :stderr ,error-output)))))) - (org-agent:kernel-log "CI ERROR - No test suite found for ~a at ~a" project-name test-file)))) -#+end_src - -* Registration -#+begin_src lisp -(defskill :skill-tdd-runner - :priority 95 ; High priority safety gate - :trigger (lambda (context) - (let ((sensor (getf (getf context :payload) :sensor))) - (or (eq sensor :buffer-update) (eq sensor :file-saved)))) - :neuro (lambda (context) nil) - :symbolic (lambda (action context) - (let ((file (getf (getf context :payload) :file))) - (when (and file (search "projects/" file)) - (let ((parts (uiop:split-string file :separator '(#\/)))) - (when (> (length parts) 2) - ;; The project name is typically the directory after "projects/" - (let ((dir (nth 1 (member "projects" parts :test #'string=)))) - (when (and dir (uiop:string-prefix-p "org-skill-" dir)) - (run-tests-for-project (subseq dir 10)))))))))) -#+end_src diff --git a/notes/org-skill-tech-analyst.org b/notes/org-skill-tech-analyst.org deleted file mode 100644 index 3ae33ba..0000000 --- a/notes/org-skill-tech-analyst.org +++ /dev/null @@ -1,133 +0,0 @@ -:PROPERTIES: -:ID: d2ec6e07-c1ee-43fb-8eae-9900e073a24f -:CREATED: [2026-03-30 Mon 21:16] -:EDITED: [2026-04-07 Tue 13:42] -:END: -#+TITLE: SKILL: Technical Analyst Agent (Universal Literate Note) -#+STARTUP: content -#+FILETAGS: :analyst:testing:tdd:psf: - -* Overview -The *Technical Analyst Agent* defines the *Success Criteria* for a project. It generates a failing test suite immediately after the architecture is signed, enforcing a strict TDD mandate within the PSF Consensus Loop. - -* Phase A: Demand (PRD) -:PROPERTIES: -:STATUS: FROZEN -:END: - -** 1. Purpose -Define automated testing behaviors for the PSF Consensus Loop. - -** 2. User Needs -- *Protocol Perception:* Monitor for `SIGNED` Protocols. -- *TDD Inception:* Translate interfaces into executable test cases. -- *Edge Case Coverage:* Mandatory testing of failure modes and malformed input. -- *Structural Enforcement:* Ensure the `tests/` directory is correctly initialized. - -** 3. Success Criteria -*** TODO Trigger Accuracy -*** TODO TDD Suite Generation Verification -*** TODO Edge Case Coverage Verification - -* Phase B: Blueprint (PROTOCOL) -:PROPERTIES: -:STATUS: SIGNED -:END: - -** 1. Architectural Intent -Interfaces for TDD suite actuation and protocol perception. Source of truth is the project's SIGNED Protocol. - -** 2. Semantic Interfaces -"Checks if a project has a SIGNED PROTOCOL." -"Physically writes the TDD suite to tests/." - -* Phase D: Build (Implementation) - -** Protocol Perception -#+begin_src lisp :tangle ../projects/org-skill-tech-analyst/src/analyst-logic.lisp -(defun tech-analyst-perceive-signed-protocol (note-path) - "Checks if a master note has a SIGNED PROTOCOL and lacks a TDD suite in the material project." - (let* ((content (uiop:read-file-string note-path)) - (filename (pathname-name note-path)) - (project-name (subseq filename 10)) ; Extract 'name' from 'org-skill-name' - (projects-dir (or (uiop:getenv "PROJECTS_DIR") "projects/")) - (test-path (format nil "~aorg-skill-~a/tests/test-suite.lisp" projects-dir project-name))) - (when (and (search "* Phase B: Blueprint (PROTOCOL)" content) - (search ":STATUS: SIGNED" content) - (not (uiop:file-exists-p test-path))) - `(:project-name ,project-name :note-path ,note-path :content ,content)))) - -(defun tech-analyst-scan-all-notes () - "Scans all org-skill-*.org notes for blueprints ready for testing." - (let ((notes-dir (or (uiop:getenv "MEMEX_NOTES") "notes/")) - (ready-notes '())) - (dolist (file (uiop:directory-files notes-dir "org-skill-*.org")) - (let ((status (tech-analyst-perceive-signed-protocol file))) - (when status (push status ready-notes)))) - ready-notes)) -#+end_src - -** Cognitive Trigger -#+begin_src lisp :tangle ../projects/org-skill-tech-analyst/src/analyst-logic.lisp -(defun trigger-skill-tech-analyst (context) - "Triggers on heartbeat if any master note is in a SIGNED PROTOCOL state." - (let ((type (getf context :type)) - (payload (getf context :payload))) - (when (and (eq type :EVENT) (eq (getf payload :sensor) :heartbeat)) - (let ((ready (tech-analyst-scan-all-notes))) - (when ready - (setf (getf (getf context :payload) :ready-blueprints) ready) - t))))) -#+end_src - -** Neuro-Cognitive Prompt -#+begin_src lisp :tangle ../projects/org-skill-tech-analyst/src/analyst-logic.lisp -(defun neuro-skill-tech-analyst (context) - (let* ((payload (getf context :payload)) - (note (car (getf payload :ready-blueprints))) - (name (getf note :project-name)) - (protocol-content (getf note :content))) - (format nil " - You are the PSF Technical Analyst. - The Master Note for project '~a' has a SIGNED PROTOCOL and needs a TDD Suite. - - PROTOCOL CONTENT: - --- - ~a - --- - - TASK: - Generate a comprehensive Common Lisp test suite (failing/RED). - 1. Use FiveAM for testing. - 2. Match function signatures exactly as defined in the PROTOCOL. - - Return a Lisp plist: (:target :analyst :action :actuate :name \"~a\" :content \"...test code...\") - " name protocol-content name))) -#+end_src - -** TDD Suite Actuation -#+begin_src lisp :tangle ../projects/org-skill-tech-analyst/src/analyst-logic.lisp -(defun tech-analyst-actuate (action context) - (let* ((payload (getf action :payload)) - (project-name (getf payload :name)) - (test-content (getf payload :content)) - (projects-dir (or (uiop:getenv "PROJECTS_DIR") "projects/")) - (project-dir (format nil "~aorg-skill-~a/" projects-dir project-name)) - (test-dir (format nil "~atests/" project-dir)) - (test-path (format nil "~atests/test-suite.lisp" project-dir))) - - (org-agent:kernel-log "ANALYST - Actuating TDD Suite for ~a" project-name) - (ensure-directories-exist test-dir) - (with-open-file (out test-path :direction :output :if-exists :supersede) - (format out ";;; TDD Suite for ~a~%~a" project-name test-content)) - (format nil "SUCCESS - Technical Analyst established TDD Suite for ~a" project-name))) -#+end_src - -* Registration -#+begin_src lisp -(defskill :skill-tech-analyst - :priority 120 - :trigger #'trigger-skill-tech-analyst - :neuro #'neuro-skill-tech-analyst - :symbolic #'tech-analyst-actuate) -#+end_src diff --git a/notes/org-skill-token-accountant.org b/notes/org-skill-token-accountant.org deleted file mode 100644 index a18c885..0000000 --- a/notes/org-skill-token-accountant.org +++ /dev/null @@ -1,92 +0,0 @@ -:PROPERTIES: -:ID: f3e3a6b3-8cd8-4e64-a835-5cdf5d13b75b -:CREATED: [2026-04-07 Tue 13:42] -:EDITED: [2026-04-08 Wed 11:45] -:END: -#+TITLE: SKILL: Token Accountant Agent (Universal Literate Note) -#+STARTUP: content -#+FILETAGS: :infrastructure:budget:llm:psf:economics: -#+DEPENDS_ON: skill-router - -* Overview -The *Token Accountant* is the governor of the Neural Engine. It manages the cost, reliability, and routing of LLM providers. Its primary mission is to ensure the PSF operates at maximum intelligence with minimum marginal cost by aggressively prioritizing subsidized free models when appropriate. - -* Phase A: Demand (PRD) -:PROPERTIES: -:STATUS: SIGNED -:END: - -** 1. Purpose -Autonomously manage the provider cascade and model selection to optimize for cost, speed, and reliability. - -* Phase B: Blueprint (PROTOCOL) -:PROPERTIES: -:STATUS: SIGNED -:END: - -** 1. Architectural Intent -Maintain a state-aware provider cascade that routes around "pain" (failures) and dynamically selects models based on task complexity. - -** 2. Semantic Interfaces - -*** Routing and Pain Management -#+begin_src lisp :tangle ../projects/org-skill-token-accountant/src/accountant-logic.lisp -(in-package :org-agent) - -(defvar *provider-pain-table* (make-hash-table :test 'equal)) - -(defun token-accountant-record-pain (provider) - "Marks a provider as 'pained' (failed). It will be de-prioritized." - (setf (gethash provider *provider-pain-table*) (+ (get-universal-time) 600)) ; 10 min penalty - (kernel-log "ACCOUNTANT - Provider ~a de-prioritized due to failure." provider)) - -(defun token-accountant-get-cascade (context) - "Returns a dynamic list of providers, routing around pained ones." - (let ((all-providers '(:openrouter :groq :gemini)) - (healthy nil) - (pained nil) - (now (get-universal-time))) - (dolist (p all-providers) - (if (> (or (gethash p *provider-pain-table*) 0) now) - (push p pained) - (push p healthy))) - (append (nreverse healthy) (nreverse pained)))) - -(defun token-accountant-get-model-for-provider (provider &optional context) - "Returns the recommended model for the provider, prioritizing free/subsidized models. Updated April 2026." - (let ((complexity (ignore-errors (uiop:symbol-call :org-agent.skills.org-skill-router :router-classify-complexity context)))) - (case provider - (:openrouter - (case complexity - (:REASONING "meta-llama/llama-3.3-70b-instruct:free") ; High fidelity, zero cost - (:COGNITION "qwen/qwen3.6-plus:free") ; Latest interaction, zero cost - (t "meta-llama/llama-3.2-3b-instruct:free"))) ; Ultra-fast reflex, zero cost - (:groq - (case complexity - (:REASONING "llama-3.3-70b-versatile") - (t "llama-3.1-8b-instant"))) - (:gemini - "gemini-1.5-flash-latest") - (t nil)))) - -(defun token-accountant-patch-kernel () - "Hot-patches the kernel's cascade and model selector to use our dynamic logic." - (setf org-agent:*provider-cascade* #'token-accountant-get-cascade) - (setf org-agent::*model-selector-fn* #'token-accountant-get-model-for-provider)) -#+end_src - -* Registration -#+begin_src lisp -(progn - (token-accountant-patch-kernel) - (defskill :skill-token-accountant - :priority 100 - :trigger (lambda (context) - (let ((sensor (getf (getf context :payload) :sensor))) - (or (eq sensor :tool-error) (eq sensor :cost-audit)))) - :neuro (lambda (context) nil) - :symbolic (lambda (action context) - (let ((p (getf (getf context :payload) :provider))) - (when p (token-accountant-record-pain p)) - action)))) -#+end_src diff --git a/notes/org-skill-web-interface.org b/notes/org-skill-web-interface.org deleted file mode 100644 index 6339a02..0000000 --- a/notes/org-skill-web-interface.org +++ /dev/null @@ -1,92 +0,0 @@ -:PROPERTIES: -:ID: ce3bef2a-ff93-49a5-ae5e-acde1de19000 -:CREATED: [2026-03-30 Mon 21:16] -:EDITED: [2026-04-07 Tue 13:42] -:END: -#+TITLE: SKILL: Web Dashboard Agent (Universal Literate Note) -#+STARTUP: content -#+FILETAGS: :web:dashboard:telemetry:psf: - -* Overview -The *Web Dashboard Agent* provides a lightweight telemetry window into the Neurosymbolic Kernel. It exposes the active skill graph and system logs via a local HTML dashboard. - -* Phase A: Demand (PRD) -:PROPERTIES: -:STATUS: FROZEN -:END: - -** 1. Purpose -Define the interfaces for system observability and telemetry serving. - -** 2. User Needs -- *Transparency:* Overview of skill performance (executions, time, failures). -- *Accessibility:* Served over a local HTTP port. -- *Observability:* Tail of system logs for debugging. -- *Low Overhead:* Background execution. - -** 3. Success Criteria -*** TODO Server Bootstrap Verification -*** TODO Telemetry Data Rendering -*** TODO Log Tail Exposure - - -* Phase B: Blueprint (PROTOCOL) -:PROPERTIES: -:STATUS: SIGNED -:END: - -* Phase B: Blueprint (PROTOCOL) - -** 1. Architectural Intent - -The Web Dashboard Agent will function as a lightweight HTTP server exposing key aspects of the Neurosymbolic Kernel's state and logs. It will leverage a simple, efficient rendering mechanism (likely string-based initially) to minimize overhead. Key components include: - -- *Telemetry Collection:* A mechanism to passively receive skill execution telemetry data from the kernel. This could involve a message queue, shared memory, or direct function calls. -- *Data Model:* An in-memory representation of the collected telemetry data, optimized for fast rendering. -- *HTTP Server:* A lightweight HTTP server (e.g., Hunchentoot, embeddable Jetty) to serve the dashboard. -- *Rendering Engine:* A template-based renderer to generate HTML from the data model. Consider a simple string-based solution for initial implementation. -- *Log Tail Reader:* A mechanism to efficiently read and expose the tail of the system log file(s). - -** 2. Semantic Interfaces (Lisp Signatures) - -*** `telemetry-collector (skill-name start-time end-time success-p)` - - - *Purpose:* Receives telemetry data from the Neurosymbolic Kernel. - - *Args:* - - `skill-name`: Symbol representing the skill (e.g., `'parse-address`). - - `start-time`: Timestamp (integer or float) of skill execution start. - - `end-time`: Timestamp (integer or float) of skill execution end. - - `success-p`: Boolean indicating successful execution (`T` or `NIL`). - - *Returns:* `T` (acknowledgment). - - *Side Effects:* Updates the in-memory data model. - -*** `current-telemetry-data ()` - - - *Purpose:* Returns the current telemetry data for rendering. - - *Args:* None. - - *Returns:* A data structure, likely an alist or plist, containing aggregated telemetry information suitable for rendering. Example: - ```lisp - (list :total-executions 1234 :successful-executions 1200 :failure-rate 0.027 :last-execution-times (list 1678886400 1678886460 1678886520)) - ``` - -*** `system-log-tail (n)` - - - *Purpose:* Returns the last `n` lines of the system log. - - *Args:* - - `n`: Integer representing the number of lines to return. - - *Returns:* A list of strings, each string representing a line from the log file. - -*** `start-web-dashboard (port)` - - - *Purpose:* Starts the HTTP server on the given port. - - *Args:* - - `port`: Integer representing the port number. - - *Returns:* `T` on success, `NIL` on failure. - - *Side Effects:* Starts the HTTP server in its own thread. - -*** `stop-web-dashboard ()` - - - *Purpose:* Stops the HTTP server. - - *Args:* None. - - *Returns:* `T` on success, `NIL` on failure. - - *Side Effects:* Stops the HTTP server. diff --git a/notes/org-skill-web-research.org b/notes/org-skill-web-research.org deleted file mode 100644 index 9258808..0000000 --- a/notes/org-skill-web-research.org +++ /dev/null @@ -1,132 +0,0 @@ -:PROPERTIES: -:ID: 31a1effd-59cc-4c62-a320-1ae3be85fe10 -:CREATED: [2026-03-30 Mon 21:16] -:EDITED: [2026-04-07 Tue 13:42] -:END: -#+TITLE: SKILL: Web Research Agent (Universal Literate Note) -#+STARTUP: content -#+FILETAGS: :web:research:browser:psf: - -* Overview -The *Web Research Agent* provides high-fidelity information retrieval and serves as the bridge to non-API web interfaces (like Gemini Advanced) to leverage user subscriptions. - -* Phase A: Demand (PRD) -:PROPERTIES: -:STATUS: SIGNED -:END: - -** 1. Purpose -Automate web-based information retrieval and subscription-tier AI access. - -* Phase B: Blueprint (PROTOCOL) -:PROPERTIES: -:STATUS: SIGNED -:END: - -** 1. Architectural Intent -Implement a Lisp-to-Node bridge using Playwright for high-fidelity web interaction. - -** 2. Semantic Interfaces - -*** `fetch-url` -:signature `(fetch-url url &key (engine :browser)) :string` - -*** `ask-gemini-web` -:signature `(ask-gemini-web prompt) :string` - -* Phase D: Build (Implementation) - -** Browser Logic - -*** Headless Query Script -#+begin_src javascript :tangle ../projects/org-skill-web-research/src/gemini-web.js -const { chromium } = require('playwright-extra'); -const stealth = require('puppeteer-extra-plugin-stealth')(); -chromium.use(stealth); - -async function askGemini(prompt) { - const browser = await chromium.launchPersistentContext('/home/user/.local/share/org-agent/browser-profile', { - headless: true, - args: ['--disable-blink-features=AutomationControlled'] - }); - - const page = await browser.newPage(); - try { - await page.goto('https://gemini.google.com/app', { waitUntil: 'networkidle', timeout: 60000 }); - - const inputSelector = 'div[role="textbox"], textarea[aria-label="Prompt"], .input-area'; - await page.waitForSelector(inputSelector, { timeout: 15000 }); - - await page.fill(inputSelector, prompt); - await page.keyboard.press('Enter'); - - // Wait for response to generate - await page.waitForSelector('.model-response-text:last-child, message-content:last-child', { state: 'visible', timeout: 60000 }); - const response = await page.innerText('.model-response-text:last-child, message-content:last-child'); - console.log(response); - } catch (err) { - const url = page.url(); - console.error(`FAILED at ${url}`); - throw err; - } finally { - await browser.close(); - } -} - -const args = process.argv.slice(2); -const prompt = args[0]; - -askGemini(prompt).catch(err => { - console.error(err); - process.exit(1); -}); -#+end_src - -*** Human-in-the-Loop Login Script -#+begin_src javascript :tangle ../projects/org-skill-web-research/src/gemini-auth.js -const { chromium } = require('playwright-extra'); -const stealth = require('puppeteer-extra-plugin-stealth')(); -chromium.use(stealth); - -async function loginGemini() { - console.log("Opening browser for manual Google login..."); - console.log("Please log in, pass any captchas, wait for the Gemini chat interface to load, and then close the browser window."); - - const browser = await chromium.launchPersistentContext('/home/user/.local/share/org-agent/browser-profile', { - headless: false, - args: ['--disable-blink-features=AutomationControlled'] - }); - - const page = await browser.newPage(); - await page.goto('https://gemini.google.com/app'); - - // The script keeps running until the user manually closes the window -} - -loginGemini().catch(err => { - console.error(err); - process.exit(1); -}); -#+end_src - -#+begin_src lisp :tangle ../projects/org-skill-web-research/src/research-logic.lisp -(in-package :org-agent) - -(defun ask-gemini-web (prompt) - "Calls the Playwright stealth bridge to interact with Gemini Web UI via a persistent profile." - (let* ((script-path (namestring (merge-pathnames "src/gemini-web.js" (asdf:system-source-directory :org-skill-web-research))))) - (multiple-value-bind (output error-output exit-code) - (uiop:run-program (list "node" script-path prompt) :output :string :error-output :string :ignore-error-status t) - (if (= exit-code 0) - output - (format nil "(:type :LOG :payload (:text \"Node Error (~a): ~a\"))" exit-code error-output))))) -#+end_src - -* Registration -#+begin_src lisp -(defskill :skill-web-research - :priority 60 - :trigger (lambda (context) (eq (getf (getf context :payload) :sensor) :web-search)) - :neuro (lambda (context) nil) - :symbolic (lambda (action context) (ask-gemini-web (getf (getf action :payload) :prompt)))) -#+end_src diff --git a/notes/org-skill-workspace-manager.org b/notes/org-skill-workspace-manager.org deleted file mode 100644 index 8924b71..0000000 --- a/notes/org-skill-workspace-manager.org +++ /dev/null @@ -1,90 +0,0 @@ -:PROPERTIES: -:ID: d6d6f694-13ca-4dbf-9fab-79bf8d0c8502 -:CREATED: [2026-03-30 Mon 21:16] -:EDITED: [2026-04-07 Tue 13:42] -:END: -#+TITLE: SKILL: Workspace Manager Agent (Universal Literate Note) -#+STARTUP: content -#+FILETAGS: :workspace:para:maintenance:psf: - -* Overview -The *Workspace Manager Agent* is responsible for the ongoing maintenance and organization of the Memex workspace. It automates the "housekeeping" aspects of the PARA/Zettelkasten workflow, focusing on clutter reduction and structural alignment. - -* Phase A: Demand (PRD) -:PROPERTIES: -:STATUS: FROZEN -:END: - -** 1. Purpose -Define automated housekeeping behaviors for PARA/Zettelkasten maintenance. - -** 2. User Needs -- *Clutter Reduction:* Identify and archive `DONE` tasks. -- *Workflow Alignment:* Ensure consistency with PARA directory structure. -- *Proactive Organization:* Trigger on saves and heartbeats. - -** 3. Success Criteria -*** TODO Task Identification -*** TODO Archiving Suggestion Loop -*** TODO Perception Coverage (Buffer & Heartbeat) - - -* Phase B: Blueprint (PROTOCOL) -:PROPERTIES: -:STATUS: SIGNED -:END: - - -* Phase B: Blueprint (PROTOCOL) -:PROPERTIES: -:STATUS: IN PROGRESS -:END: - -** 1. Architectural Intent -The Workspace Manager Agent will operate as a background process, triggered by file saves and a periodic heartbeat. It uses a combination of regular expressions and structural pattern matching to identify tasks suitable for archiving and to ensure the overall coherence of the Memex workspace structure. The agent prioritizes non-intrusive suggestions, allowing the user to retain ultimate control over the organization of their notes. - -** 2. Semantic Interfaces - -*** Function: `workspace-manager-agent` - :PROPERTIES: - :CUSTOM_ID: workspace-manager-agent-signature - :END: - - *Signature:* `(workspace-manager-agent &key (buffer nil) (heartbeat nil))` - - *Purpose:* Main entry point. Called on buffer save or heartbeat. - - *Arguments:* - - `buffer` (optional): The buffer being saved (when triggered by a save). - - `heartbeat` (optional): A flag indicating a heartbeat trigger. - - *Returns:* A list of suggestions (see `suggestion` signature). - -*** Function: `find-archivable-tasks` - :PROPERTIES: - :CUSTOM_ID: find-archivable-tasks-signature - :END: - - *Signature:* `(find-archivable-tasks buffer)` - - *Purpose:* Locates tasks marked `DONE` within the specified buffer. - - *Arguments:* - - `buffer`: The buffer to scan. - - *Returns:* A list of task IDs (org-mode custom IDs). - -*** Function: `suggest-archive-task` - :PROPERTIES: - :CUSTOM_ID: suggest-archive-task-signature - :END: - - *Signature:* `(suggest-archive-task task-id)` - - *Purpose:* Creates a suggestion to archive the specified task. - - *Arguments:* - - `task-id`: The CUSTOM_ID of the task to archive. - - *Returns:* A `suggestion` plist. - -*** Function: `suggestion` - :PROPERTIES: - :CUSTOM_ID: suggestion-signature - :END: - - *Signature:* `(&key type target message action)` - - *Purpose:* Represents a suggestion made by the agent. - - *Arguments:* - - `type`: The type of suggestion (e.g., `:archive`). - - `target`: The ID or path of the element the suggestion applies to. - - `message`: A human-readable message describing the suggestion. - - `action`: A lisp form to execute to enact the suggestion. - - *Returns:* An association list (plist) conforming to the interface. Example: `(:type :archive :target "task-123" :message "Archive completed task?" :action `(org-archive-subtree "task-123"))` diff --git a/peripheral-vision-plan.md b/peripheral-vision-plan.md new file mode 100644 index 0000000..abd9898 --- /dev/null +++ b/peripheral-vision-plan.md @@ -0,0 +1,32 @@ +# Implementation Plan: Component IV - Peripheral Vision Extraction + +## Objective +Implement a sophisticated "Foveal-Peripheral" context model. This ensures the agent has high-resolution focus on the current task (Foveal) while maintaining a low-resolution "skeletal" awareness of the broader Memex structure (Peripheral), optimized for token efficiency and reasoning accuracy. + +## Key Files & Context +- **Target:** `projects/org-agent/literate/context.org` (Source of `src/context.lisp`) +- **Core Concept:** Deep pruning of the Org AST based on semantic distance and structural hierarchy. + +## Implementation Steps + +### 1. Identify Foveal Focus +- Extend the `SIGNAL` structure processing to identify a `target-id` (the current headline being operated on). + +### 2. Implement Tree Pruning (`context-extract-peripheral-vision`) +- Create a recursive function that walks the Object Store starting from the root (or active projects). +- **Rule A (Foveal):** If the node matches `target-id`, include it and its immediate children in **Full Resolution** (Content + Attributes). +- **Rule B (Peripheral):** For ancestors and siblings of the target, include only **Title and ID**. +- **Rule C (Background):** For unrelated nodes, omit entirely or include only at Level 1. + +### 3. AST to Org Renderer (`context-render-to-org`) +- Implement a serializer that transforms our `org-object` structures back into valid Org-mode strings. +- This allows the LLM to "see" the Memex in its native habitat. + +### 4. Integrate with `context-assemble-global-awareness` +- Update this function to use the new extraction and rendering logic. +- Ensure it respects a maximum token/character budget to prevent context overflow. + +## Phase E: Chaos (Verification) +- **Structural Test:** Verify that ancestors are rendered as "skeletons" (no body text). +- **Foveal Test:** Verify that the target node is rendered with its full body text. +- **Budget Test:** Verify that the output string stays within defined limits even for large Memex structures. diff --git a/pipeline-refactor.md b/pipeline-refactor.md new file mode 100644 index 0000000..c450b7d --- /dev/null +++ b/pipeline-refactor.md @@ -0,0 +1,37 @@ +# Implementation Plan: Reactive Signal Pipeline Refactor + +## Objective +Refactor the monolithic recursive `cognitive-loop` into a functional, gate-based `reactive-signal-pipeline`. This flattens the execution stack, enables multi-backend consensus, and improves observability according to Component VII of the evolutionary roadmap. + +## Key Files & Context +- **Target:** `projects/org-agent/literate/core.org` (Source of `src/core.lisp`) +- **Architectural Reference:** `projects/org-agent/literate/evolution.org` + +## Implementation Steps + +### 1. Define the Signal Structure +Transition from raw plists to a structured `:SIGNAL` format that tracks state as it moves through the pipeline. +- Attributes: `:status`, `:payload`, `:context`, `:depth`, `:proposals`, `:reply-stream`. + +### 2. Implement the Pipeline Gates +Extract existing logic from `cognitive-loop` into discrete functional gates: +- **`perceive-gate`**: Normalizes input, updates `*object-store*`. +- **`neuro-gate`**: Invokes System 1. Support for future parallel backend calls. +- **`consensus-gate`**: (New) Selects the best proposal from multiple backends (initially a pass-through for the single proposal). +- **`decide-gate`**: Invokes System 2 safety checks. +- **`dispatch-gate`**: Executes tools or physical actuators. + +### 3. Implement the Pipeline Orchestrator (`process-signal`) +Create a function that moves a signal through the sequence of gates. +- **Flattening Recursion:** If `dispatch-gate` results in a tool output or error, it MUST NOT call the pipeline recursively. Instead, it returns a new `:SIGNAL` with `depth + 1`, which the orchestrator then re-injects into the top of the pipe via a loop or queue. + +### 4. Refactor `inject-stimulus` +Update `inject-stimulus` to initialize a Signal and hand it to the `process-signal` pipeline instead of `cognitive-loop`. + +### 5. Cleanup +Remove the obsolete `cognitive-loop` function and update `literate/core.org` documentation/diagrams to reflect the new architecture. + +## Verification & Testing (Phase E: Chaos) +- **Unit Tests:** Verify each gate function in isolation. +- **Pipeline Test:** Simulate a complex multi-turn interaction (e.g., User Prompt -> Tool Call -> Tool Result -> LLM Final Answer) and ensure the stack depth remains flat. +- **Immune System Test:** Verify that the depth limit (Max depth 10) still correctly terminates runaway loops.