DOCS: Systematic overhaul of Literate source (Granularity & Technical Reasoning)

literate/act.org

@@ -4,18 +4,37 @@
 #+STARTUP: content
 
 * Stage 3: Act (act.lisp)
+
 ** Architectural Intent: Actuation
-The Act stage performs the final side-effects of the reasoning engine. It routes approved actions to their registered physical actuators (CLI, Shell, Emacs, etc.) and handles the execution of internal system tools.
+The Act stage performs the final physical side-effects of the metabolic pipeline. It takes an approved **Action** (the result of the Reasoning stage) and routes it to the correct physical **Actuator**.
 
-** Actuator Configuration
-The core harness can be configured via environment variables to operate silently or target different default outputs.
+Actuators are the "hands" of the OpenCortex. They can be local (printing to a terminal), virtual (executing a shell command), or remote (sending a Matrix message). Crucially, the core microharness does not know *how* to talk to these services; it only knows how to *dispatch* to the registered actuator functions.
 
+** Pipeline Initialization
 #+begin_src lisp :tangle ../src/act.lisp
 (in-package :opencortex)
+#+end_src
 
-(defvar *default-actuator* :cli)
-(defvar *silent-actuators* '(:cli :system-message :emacs))
+* Actuator Configuration
 
+** Default Actuator
+#+begin_src lisp :tangle ../src/act.lisp
+(defvar *default-actuator* :cli
+  "The fallback actuator used if a signal has no source or target metadata.")
+#+end_src
+
+** Silent Actuators
+To prevent infinite feedback loops, certain actuators are flagged as "silent." Results from these actuators are logged but do not trigger a fresh metabolic cycle.
+
+#+begin_src lisp :tangle ../src/act.lisp
+(defvar *silent-actuators* '(:cli :system-message :emacs)
+  "List of actuators whose feedback should not re-enter the Reasoning stage.")
+#+end_src
+
+** Initialization Logic (initialize-actuators)
+This function hydrates the actuator configuration from the environment and registers the core built-in actuators.
+
+#+begin_src lisp :tangle ../src/act.lisp
 (defun initialize-actuators ()
   "Loads actuator routing defaults from environment variables and registers core harness actuators."
   (let ((def (uiop:getenv "DEFAULT_ACTUATOR"))
@@ -38,15 +57,19 @@ The core harness can be configured via environment variables to operate silently
                                 (finish-output stream))))))
 #+end_src
 
-** Dispatching Actions
-The `dispatch-action` function is the primary router. It identifies the target actuator and executes the requested side-effects.
+* Primary Routing
+
+** Dispatching Logic (dispatch-action)
+The primary router. It identifies the target actuator based on the Signal's `:META` source or the Action's `:TARGET`.
 
 #+begin_src lisp :tangle ../src/act.lisp
 (defun dispatch-action (action context)
+  "Routes an approved action to its registered physical actuator."
   (let ((payload (proto-get action :payload)))
+    ;; Optimization: Heartbeats are system events, not actions.
     (when (eq (proto-get payload :sensor) :heartbeat)
       (return-from dispatch-action nil)))
-  "Routes an approved action to its registered physical actuator."
+
   (when (and action (listp action))
     (let* ((meta (proto-get context :meta))
            (source (proto-get meta :source))
@@ -56,7 +79,7 @@ The `dispatch-action` function is the primary router. It identifies the target a
                            *default-actuator*))
            (target (intern (string-upcase (string raw-target)) :keyword))
            (actuator-fn (gethash target *actuator-registry*)))
-      ;; Ensure outbound action has meta if context had it
+      ;; Propagation: Ensure outbound action inherits metadata
       (when (and meta (null (getf action :meta)))
         (setf (getf action :meta) meta))
       (if actuator-fn 
@@ -64,8 +87,10 @@ The `dispatch-action` function is the primary router. It identifies the target a
           (harness-log "ACT ERROR: No actuator for ~s (from ~s)" target raw-target)))))
 #+end_src
 
-** Internal System Actions
-The `:system` actuator handles internal harness commands like code evaluation and dynamic skill loading.
+* Built-in Actuators
+
+** System Actuator (execute-system-action)
+Handles meta-operations like hot-loading skills or evaluating raw Lisp within the image.
 
 #+begin_src lisp :tangle ../src/act.lisp
 (defun execute-system-action (action context)
@@ -85,8 +110,8 @@ The `:system` actuator handles internal harness commands like code evaluation an
       (t (harness-log "ACT ERROR [System]: Unknown command ~s" cmd)))))
 #+end_src
 
-** Cognitive Tool Actuation
-The `:tool` actuator handles the execution of registered cognitive tools.
+** Tool Result Formatting (format-tool-result)
+A UI helper that distills technical LLM responses into human-readable text.
 
 #+begin_src lisp :tangle ../src/act.lisp
 (defun format-tool-result (tool-name result)
@@ -99,9 +124,14 @@ The `:tool` actuator handles the execution of registered cognitive tools.
               ((and (eq status :error) msg) (format nil "ERROR [~a]: ~a" tool-name msg))
               (t (format nil "TOOL [~a] RESULT: ~s" tool-name result))))
       (format nil "TOOL [~a] RESULT: ~a" tool-name result)))
+#+end_src
 
+** Tool Actuator (execute-tool-action)
+The engine for physical interaction. It executes a cognitive tool and generates feedback signals for the user.
+
+#+begin_src lisp :tangle ../src/act.lisp
 (defun execute-tool-action (action context)
-  "Executes a registered cognitive tool. (ACTUATOR)"
+  "Executes a registered cognitive tool and generates feedback signals. (ACTUATOR)"
   (let* ((payload (getf action :payload))
          (tool-name (getf payload :tool))
          (tool-args (getf payload :args))
@@ -115,7 +145,7 @@ The `:tool` actuator handles the execution of registered cognitive tools.
                    (result (funcall (cognitive-tool-body tool) clean-args)))
               (let ((feedback (list :TYPE :EVENT :DEPTH (1+ depth) :META meta
                                     :PAYLOAD (list :SENSOR :tool-output :RESULT result :TOOL tool-name))))
-                ;; If we have a source, send a status message with the result, formatted for humans
+                ;; UI Propagation: Send distilled text result back to the source client
                 (when source
                    (dispatch-action (list :TYPE :REQUEST :TARGET source 
                                           :PAYLOAD (list :ACTION :MESSAGE :TEXT (format-tool-result tool-name result))) 
@@ -128,8 +158,10 @@ The `:tool` actuator handles the execution of registered cognitive tools.
               :PAYLOAD (list :SENSOR :tool-error :message "Tool not found")))))
 #+end_src
 
-** The Act Gate
-The final stage of the metabolic loop. It performs a "last-mile" safety check before dispatching the action to the registered actuator.
+* The Final Pipeline Stage
+
+** Act Gate (act-gate)
+The exit point of the metabolic pipeline. It applies a last-mile safety check via the Deterministic Engine and dispatches the signal to the physical world.
 
 #+begin_src lisp :tangle ../src/act.lisp
 (defun act-gate (signal)
@@ -166,14 +198,12 @@ The final stage of the metabolic loop. It performs a "last-mile" safety check be
        (if approved
            (let* ((target (getf approved :target))
                   (result (dispatch-action approved context)))
-             ;; If the actuator returns a signal (like :tool-output), it becomes the feedback.
-             ;; Otherwise, generate tool-output feedback for non-silent actuators.
              (cond ((and (listp result) (member (getf result :type) '(:EVENT :LOG)))
                     (setf feedback result))
                    ((and result (not (member target *silent-actuators*)))
                     (setf feedback (list :type :EVENT :depth (1+ (getf signal :depth 0)) :meta meta
                                          :payload (list :sensor :tool-output :result result :tool approved))))))
-           ;; If no approved action but we have a source, this might be a raw event/log stimulus.
+           ;; Fallback: route generic stimuli back to their origin
            (when source
              (dispatch-action signal context)))))