feat(psf): complete high-integrity loop for advanced features

notes/org-skill-sub-agent-manager.org

@@ -0,0 +1,80 @@
+#+TITLE: SKILL: Sub-Agent Manager (Concurrency & Parallelism)
+#+ID: skill-sub-agent-manager
+#+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:
+
+** 1. Architectural Intent
+Interfaces for parallel cognitive loops. Source of truth is the OS thread registry and the kernel event bus.
+
+** 2. Semantic Interfaces
+#+begin_src lisp
+(defun sub-agent-spawn (goal context)
+  "Creates a new thread and starts a localized cognitive loop.")
+
+(defun sub-agent-list-active ()
+  "Returns a list of currently running sub-agent threads.")
+#+end_src
+
+* Phase D: Build (Implementation)
+
+** Parallel Spawning
+#+begin_src lisp :tangle projects/org-skill-sub-agent-manager/src/concurrency-logic.lisp
+(defvar *active-sub-agents* '() "Registry of active sub-agent thread objects.")
+
+(defun sub-agent-spawn (goal parent-context)
+  (let ((thread-name (format nil "sub-agent-~a" (get-universal-time))))
+    (kernel-log "CONCURRENCY - Spawning sub-agent for goal: ~a" goal)
+    (let ((new-thread 
+           (bt:make-thread 
+            (lambda ()
+              (handler-case
+                  (let* ((context `(:type :SUB-GOAL :payload (:goal ,goal :parent ,parent-context)))
+                         (result (org-agent:think context))) ; Execute sub-goal thinking
+                    ;; Inject the result back into the main kernel bus
+                    (org-agent:inject-stimulus 
+                     `(:type :EVENT :payload (:sensor :sub-agent-complete :result ,result :goal ,goal))))
+                (error (c)
+                  (kernel-log "SUB-AGENT ERROR (~a): ~a" thread-name c))))
+            :name thread-name)))
+      (push new-thread *active-sub-agents*)
+      (format nil "SUCCESS - Sub-agent '~a' is now thinking in the background." thread-name))))
+#+end_src
+
+* Registration
+#+begin_src lisp
+(defskill :skill-sub-agent-manager
+  :priority 90
+  :trigger (lambda (context) (eq (getf (getf context :payload) :action) :spawn))
+  :neuro (lambda (context) nil)
+  :symbolic (lambda (action context) 
+              (let ((goal (getf (getf action :payload) :goal)))
+                (sub-agent-spawn goal context))))
+#+end_src