docs: add literate prose to naming-drift aliases and HITL gateway changes
Some checks failed
Deploy (Gitea) / deploy (push) Failing after 3s

Adds prose sections before every code block to satisfy the
prose-before-code discipline. Each backward-compatibility alias
(process-signal, perceive-gate, reason-gate, act-gate, inject-stimulus)
now has its own subsection explaining why it exists and what new code
should use instead.

Also:
- Fixes double #+end_src in core-loop-perceive.org
- Renames inject-stimulus → stimulus-inject in heartbeat-start and
  client-handle-connection (both already had aliases)
- Adds HITL interception prose to gateway-manager.org telegram/signal
  sections
- Splits Pre-Reason Handler Registry into two code blocks (defvar + defun)
  for one-per-block compliance
This commit is contained in:
2026-05-03 13:58:08 -04:00
parent bbc5e4d8bf
commit 3f51a772d4
11 changed files with 109 additions and 47 deletions

View File

@@ -78,12 +78,12 @@ The function handles four failure modes:
- High-depth errors (depth > 2) → dropped (avoids cascading failures)
- **Unhandled error**: the handler-case catches everything, preventing any single bad signal from crashing the agent
*** loop-process
The main pipeline entry point.
;; REPL-VERIFIED: 2026-05-03T13:00:00
#+begin_src lisp
;; Alias: process-signal → loop-process (backward compatibility)
(defun process-signal (signal)
(loop-process signal))
(defun loop-process (signal)
"The entry point to the Metabolic Pipeline: Perceive -> Reason -> Act."
(let ((current-signal signal))
@@ -121,6 +121,18 @@ The function handles four failure modes:
:payload (list :sensor :loop-error :message (format nil "~a" c) :depth depth)))))))))))
#+end_src
*** process-signal (backward-compatibility alias)
The pipeline entry point was originally named ~process-signal~. Code
that still uses the old name can call this alias. New code should call
~loop-process~.
;; REPL-VERIFIED: 2026-05-03T13:00:00
#+begin_src lisp
(defun process-signal (signal)
(loop-process signal))
#+end_src
** Heartbeat Mechanism
The heartbeat is a background thread that fires every N seconds (configurable via ~HEARTBEAT_INTERVAL~ env var, default 60). On each tick, it:
@@ -159,8 +171,8 @@ The heartbeat signal is how background skills (Gardener, Scribe) get triggered w
(when (>= *heartbeat-save-counter* (/ *memory-auto-save-interval* interval))
(setf *heartbeat-save-counter* 0)
(save-memory-to-disk))
(inject-stimulus
(list :type :EVENT :payload (list :sensor :heartbeat :unix-time (get-universal-time))))))
(stimulus-inject
(list :type :EVENT :payload (list :sensor :heartbeat :unix-time (get-universal-time))))))
:name "passepartout-heartbeat"))))
#+end_src
#+end_src