PSF: Mass-regeneration complete. 53/53 high-fidelity blueprints and TDD suites established. Zero-cost Pro bridge active.

notes/org-skill-hook-manager.org

@@ -18,42 +18,54 @@ Provide a hook-based event system.
 - *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
-Event-driven extension system.
+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
-#+begin_src lisp
-(defun register-hook (hook-name fn) "Register FN on HOOK-NAME.")
-(defun run-hooks (hook-name &rest args) "Run all functions on HOOK-NAME with ARGS.")
-#+end_src
 
-* Phase D: Build (Implementation)
+*** 2.1. `register-hook`
 
-#+begin_src lisp :tangle ../projects/org-skill-hook-manager/src/hook-manager.lisp
-(defvar *hooks* (make-hash-table :test 'equal))
+Registers a function to be executed when a specific hook is triggered.
 
-(defun register-hook (hook-name fn)
-  "Registers a function FN for the given HOOK-NAME."
-  (pushnew fn (gethash hook-name *hooks*))
-  (kernel-log "HOOK - Registered function for ~a" hook-name))
+    Signature: `(register-hook hook-name function)`
 
-(defun run-hooks (hook-name &rest args)
-  "Executes all registered functions for HOOK-NAME with ARGS."
-  (let ((fns (gethash hook-name *hooks*)))
-    (dolist (fn fns)
-      (apply fn args))))
-#+end_src
+    - `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).
 
-* Registration
-#+begin_src lisp
-(defskill :skill-hook-manager
-  :priority 100
-  :trigger (lambda (context) nil)
-  :neuro (lambda (context) nil)
-  :symbolic (lambda (action context) action))
-#+end_src
+    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)`